From 961b4adc1cae08a8ff1c1ad7aa649ea21755bc33 Mon Sep 17 00:00:00 2001
From: Yuri Chukhlib <yuri.v.chu@gmail.com>
Date: Mon, 26 Jan 2026 15:51:25 +0100
Subject: [PATCH] feat(gateway): deprecate query param hook token auth for
 security (#2200)

* feat(gateway): deprecate query param hook token auth for security

Query parameter tokens appear in:
- Server access logs
- Browser history
- Referrer headers
- Network monitoring tools

This change adds a deprecation warning when tokens are provided via
query parameter, encouraging migration to header-based authentication
(Authorization: Bearer <token> or X-Clawdbot-Token header).

Changes:
- Modified extractHookToken to return { token, fromQuery } object
- Added deprecation warning in server-http.ts when fromQuery is true
- Updated tests to verify the new return type and fromQuery flag

Fixes #2148

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: deprecate hook query token auth (#2200) (thanks @YuriNachos)

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 CHANGELOG.md               |  1 +
 docs/automation/webhook.md |  8 ++++----
 src/gateway/hooks.test.ts  | 12 +++++++++---
 src/gateway/hooks.ts       | 15 ++++++++++-----
 src/gateway/server-http.ts |  9 ++++++++-
 5 files changed, 32 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a1057175a..629f46908 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@ Docs: https://docs.clawd.bot
 Status: unreleased.
 
 ### Changes
+- Gateway: warn on hook tokens via query params; document header auth preference. (#2200) Thanks @YuriNachos.
 - Doctor: warn on gateway exposure without auth. (#2016) Thanks @Alex-Alaniz.
 - Docs: add Vercel AI Gateway to providers sidebar. (#1901) Thanks @jerilynzheng.
 - Agents: expand cron tool description with full schema docs. (#1988) Thanks @tomascupr.
diff --git a/docs/automation/webhook.md b/docs/automation/webhook.md
index 4fbf6bf50..12fc6b92a 100644
--- a/docs/automation/webhook.md
+++ b/docs/automation/webhook.md
@@ -27,10 +27,10 @@ Notes:
 
 ## Auth
 
-Every request must include the hook token:
-- `Authorization: Bearer <token>`
-- or `x-clawdbot-token: <token>`
-- or `?token=<token>`
+Every request must include the hook token. Prefer headers:
+- `Authorization: Bearer <token>` (recommended)
+- `x-clawdbot-token: <token>`
+- `?token=<token>` (deprecated; logs a warning and will be removed in a future major release)
 
 ## Endpoints
 
diff --git a/src/gateway/hooks.test.ts b/src/gateway/hooks.test.ts
index 5a3c5e79e..447e91bdb 100644
--- a/src/gateway/hooks.test.ts
+++ b/src/gateway/hooks.test.ts
@@ -47,15 +47,21 @@ describe("gateway hooks helpers", () => {
       },
     } as unknown as IncomingMessage;
     const url = new URL("http://localhost/hooks/wake?token=query");
-    expect(extractHookToken(req, url)).toBe("top");
+    const result1 = extractHookToken(req, url);
+    expect(result1.token).toBe("top");
+    expect(result1.fromQuery).toBe(false);
 
     const req2 = {
       headers: { "x-clawdbot-token": "header" },
     } as unknown as IncomingMessage;
-    expect(extractHookToken(req2, url)).toBe("header");
+    const result2 = extractHookToken(req2, url);
+    expect(result2.token).toBe("header");
+    expect(result2.fromQuery).toBe(false);
 
     const req3 = { headers: {} } as unknown as IncomingMessage;
-    expect(extractHookToken(req3, url)).toBe("query");
+    const result3 = extractHookToken(req3, url);
+    expect(result3.token).toBe("query");
+    expect(result3.fromQuery).toBe(true);
   });
 
   test("normalizeWakePayload trims + validates", () => {
diff --git a/src/gateway/hooks.ts b/src/gateway/hooks.ts
index 6065d121d..31265c341 100644
--- a/src/gateway/hooks.ts
+++ b/src/gateway/hooks.ts
@@ -41,21 +41,26 @@ export function resolveHooksConfig(cfg: ClawdbotConfig): HooksConfigResolved | n
   };
 }
 
-export function extractHookToken(req: IncomingMessage, url: URL): string | undefined {
+export type HookTokenResult = {
+  token: string | undefined;
+  fromQuery: boolean;
+};
+
+export function extractHookToken(req: IncomingMessage, url: URL): HookTokenResult {
   const auth =
     typeof req.headers.authorization === "string" ? req.headers.authorization.trim() : "";
   if (auth.toLowerCase().startsWith("bearer ")) {
     const token = auth.slice(7).trim();
-    if (token) return token;
+    if (token) return { token, fromQuery: false };
   }
   const headerToken =
     typeof req.headers["x-clawdbot-token"] === "string"
       ? req.headers["x-clawdbot-token"].trim()
       : "";
-  if (headerToken) return headerToken;
+  if (headerToken) return { token: headerToken, fromQuery: false };
   const queryToken = url.searchParams.get("token");
-  if (queryToken) return queryToken.trim();
-  return undefined;
+  if (queryToken) return { token: queryToken.trim(), fromQuery: true };
+  return { token: undefined, fromQuery: false };
 }
 
 export async function readJsonBody(
diff --git a/src/gateway/server-http.ts b/src/gateway/server-http.ts
index 136ec6229..08415f346 100644
--- a/src/gateway/server-http.ts
+++ b/src/gateway/server-http.ts
@@ -76,13 +76,20 @@ export function createHooksRequestHandler(
       return false;
     }
 
-    const token = extractHookToken(req, url);
+    const { token, fromQuery } = extractHookToken(req, url);
     if (!token || token !== hooksConfig.token) {
       res.statusCode = 401;
       res.setHeader("Content-Type", "text/plain; charset=utf-8");
       res.end("Unauthorized");
       return true;
     }
+    if (fromQuery) {
+      logHooks.warn(
+        "Hook token provided via query parameter is deprecated for security reasons. " +
+          "Tokens in URLs appear in logs, browser history, and referrer headers. " +
+          "Use Authorization: Bearer <token> or X-Clawdbot-Token header instead.",
+      );
+    }
 
     if (req.method !== "POST") {
       res.statusCode = 405;