@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/gateway/server-http.js

@@ -1,19 +1,24 @@
 import { createServer as createHttpServer, } from "node:http";
 import { createServer as createHttpsServer } from "node:https";
+import { resolveAgentAvatar } from "../agents/identity-avatar.js";
 import { A2UI_PATH, CANVAS_HOST_PATH, CANVAS_WS_PATH, handleA2uiHttpRequest, } from "../canvas-host/a2ui.js";
 import { loadConfig } from "../config/config.js";
-import { resolveAgentAvatar } from "../agents/identity-avatar.js";
+import { safeEqualSecret } from "../security/secret-equal.js";
 import { handleSlackHttpRequest } from "../slack/http/index.js";
-import { authorizeGatewayConnect, isLocalDirectRequest } from "./auth.js";
+import { authorizeHttpGatewayConnect, isLocalDirectRequest, } from "./auth.js";
+import { CANVAS_CAPABILITY_TTL_MS, normalizeCanvasScopedUrl } from "./canvas-capability.js";
 import { handleControlUiAvatarRequest, handleControlUiHttpRequest, } from "./control-ui.js";
-import { extractHookToken, getHookAgentPolicyError, getHookChannelError, isHookAgentAllowed, normalizeAgentPayload, normalizeHookHeaders, normalizeWakePayload, readJsonBody, resolveHookTargetAgentId, resolveHookChannel, resolveHookDeliver, } from "./hooks.js";
 import { applyHookMappings } from "./hooks-mapping.js";
-import { sendUnauthorized } from "./http-common.js";
-import { getBearerToken, getHeader } from "./http-utils.js";
-import { resolveGatewayClientIp } from "./net.js";
+import { extractHookToken, getHookAgentPolicyError, getHookChannelError, isHookAgentAllowed, normalizeAgentPayload, normalizeHookHeaders, normalizeWakePayload, readJsonBody, resolveHookSessionKey, resolveHookTargetAgentId, resolveHookChannel, resolveHookDeliver, } from "./hooks.js";
+import { sendGatewayAuthFailure, setDefaultSecurityHeaders } from "./http-common.js";
+import { getBearerToken } from "./http-utils.js";
 import { handleOpenAiHttpRequest } from "./openai-http.js";
 import { handleOpenResponsesHttpRequest } from "./openresponses-http.js";
+import { GATEWAY_CLIENT_MODES, normalizeGatewayClientMode } from "./protocol/client-info.js";
 import { handleToolsInvokeHttpRequest } from "./tools-invoke-http.js";
+const HOOK_AUTH_FAILURE_LIMIT = 20;
+const HOOK_AUTH_FAILURE_WINDOW_MS = 60_000;
+const HOOK_AUTH_FAILURE_TRACK_MAX = 2048;
 function sendJson(res, status, body) {
     res.statusCode = status;
     res.setHeader("Content-Type", "application/json; charset=utf-8");
@@ -26,67 +31,167 @@ function isCanvasPath(pathname) {
         pathname.startsWith(`${CANVAS_HOST_PATH}/`) ||
         pathname === CANVAS_WS_PATH);
 }
-function hasAuthorizedWsClientForIp(clients, clientIp) {
+function isNodeWsClient(client) {
+    if (client.connect.role === "node") {
+        return true;
+    }
+    return normalizeGatewayClientMode(client.connect.client.mode) === GATEWAY_CLIENT_MODES.NODE;
+}
+function hasAuthorizedNodeWsClientForCanvasCapability(clients, capability) {
+    const nowMs = Date.now();
     for (const client of clients) {
-        if (client.clientIp && client.clientIp === clientIp) {
+        if (!isNodeWsClient(client)) {
+            continue;
+        }
+        if (!client.canvasCapability || !client.canvasCapabilityExpiresAtMs) {
+            continue;
+        }
+        if (client.canvasCapabilityExpiresAtMs <= nowMs) {
+            continue;
+        }
+        if (safeEqualSecret(client.canvasCapability, capability)) {
+            // Sliding expiration while the connected node keeps using canvas.
+            client.canvasCapabilityExpiresAtMs = nowMs + CANVAS_CAPABILITY_TTL_MS;
             return true;
         }
     }
     return false;
 }
 async function authorizeCanvasRequest(params) {
-    const { req, auth, trustedProxies, clients } = params;
-    if (isLocalDirectRequest(req, trustedProxies)) {
-        return true;
+    const { req, auth, trustedProxies, allowRealIpFallback, clients, canvasCapability, malformedScopedPath, rateLimiter, } = params;
+    if (malformedScopedPath) {
+        return { ok: false, reason: "unauthorized" };
     }
+    if (isLocalDirectRequest(req, trustedProxies, allowRealIpFallback)) {
+        return { ok: true };
+    }
+    let lastAuthFailure = null;
     const token = getBearerToken(req);
     if (token) {
-        const authResult = await authorizeGatewayConnect({
+        const authResult = await authorizeHttpGatewayConnect({
             auth: { ...auth, allowTailscale: false },
             connectAuth: { token, password: token },
             req,
             trustedProxies,
+            allowRealIpFallback,
+            rateLimiter,
         });
         if (authResult.ok) {
-            return true;
+            return authResult;
         }
+        lastAuthFailure = authResult;
     }
-    const clientIp = resolveGatewayClientIp({
-        remoteAddr: req.socket?.remoteAddress ?? "",
-        forwardedFor: getHeader(req, "x-forwarded-for"),
-        realIp: getHeader(req, "x-real-ip"),
-        trustedProxies,
-    });
-    if (!clientIp) {
-        return false;
+    if (canvasCapability && hasAuthorizedNodeWsClientForCanvasCapability(clients, canvasCapability)) {
+        return { ok: true };
+    }
+    return lastAuthFailure ?? { ok: false, reason: "unauthorized" };
+}
+function writeUpgradeAuthFailure(socket, auth) {
+    if (auth.rateLimited) {
+        const retryAfterSeconds = auth.retryAfterMs && auth.retryAfterMs > 0 ? Math.ceil(auth.retryAfterMs / 1000) : undefined;
+        socket.write([
+            "HTTP/1.1 429 Too Many Requests",
+            retryAfterSeconds ? `Retry-After: ${retryAfterSeconds}` : undefined,
+            "Content-Type: application/json; charset=utf-8",
+            "Connection: close",
+            "",
+            JSON.stringify({
+                error: {
+                    message: "Too many failed authentication attempts. Please try again later.",
+                    type: "rate_limited",
+                },
+            }),
+        ]
+            .filter(Boolean)
+            .join("\r\n"));
+        return;
     }
-    return hasAuthorizedWsClientForIp(clients, clientIp);
+    socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
 }
 export function createHooksRequestHandler(opts) {
     const { getHooksConfig, bindHost, port, logHooks, dispatchAgentHook, dispatchWakeHook } = opts;
+    const hookAuthFailures = new Map();
+    const resolveHookClientKey = (req) => {
+        return req.socket?.remoteAddress?.trim() || "unknown";
+    };
+    const recordHookAuthFailure = (clientKey, nowMs) => {
+        if (!hookAuthFailures.has(clientKey) && hookAuthFailures.size >= HOOK_AUTH_FAILURE_TRACK_MAX) {
+            // Prune expired entries instead of clearing all state.
+            for (const [key, entry] of hookAuthFailures) {
+                if (nowMs - entry.windowStartedAtMs >= HOOK_AUTH_FAILURE_WINDOW_MS) {
+                    hookAuthFailures.delete(key);
+                }
+            }
+            // If still at capacity after pruning, drop the oldest half.
+            if (hookAuthFailures.size >= HOOK_AUTH_FAILURE_TRACK_MAX) {
+                let toRemove = Math.floor(hookAuthFailures.size / 2);
+                for (const key of hookAuthFailures.keys()) {
+                    if (toRemove <= 0) {
+                        break;
+                    }
+                    hookAuthFailures.delete(key);
+                    toRemove--;
+                }
+            }
+        }
+        const current = hookAuthFailures.get(clientKey);
+        const expired = !current || nowMs - current.windowStartedAtMs >= HOOK_AUTH_FAILURE_WINDOW_MS;
+        const next = expired
+            ? { count: 1, windowStartedAtMs: nowMs }
+            : { count: current.count + 1, windowStartedAtMs: current.windowStartedAtMs };
+        // Delete-before-set refreshes Map insertion order so recently-active
+        // clients are not evicted before dormant ones during oldest-half eviction.
+        if (hookAuthFailures.has(clientKey)) {
+            hookAuthFailures.delete(clientKey);
+        }
+        hookAuthFailures.set(clientKey, next);
+        if (next.count <= HOOK_AUTH_FAILURE_LIMIT) {
+            return { throttled: false };
+        }
+        const retryAfterMs = Math.max(1, next.windowStartedAtMs + HOOK_AUTH_FAILURE_WINDOW_MS - nowMs);
+        return {
+            throttled: true,
+            retryAfterSeconds: Math.ceil(retryAfterMs / 1000),
+        };
+    };
+    const clearHookAuthFailure = (clientKey) => {
+        hookAuthFailures.delete(clientKey);
+    };
     return async (req, res) => {
         const hooksConfig = getHooksConfig();
-        if (!hooksConfig)
+        if (!hooksConfig) {
             return false;
+        }
         const url = new URL(req.url ?? "/", `http://${bindHost}:${port}`);
         const basePath = hooksConfig.basePath;
         if (url.pathname !== basePath && !url.pathname.startsWith(`${basePath}/`)) {
             return false;
         }
-        // pool-bot keeps the deprecation-warning approach for query-param tokens
-        // (upstream hard-rejects; we warn and allow for now)
-        const { token, fromQuery } = extractHookToken(req, url);
-        if (!token || token !== hooksConfig.token) {
+        if (url.searchParams.has("token")) {
+            res.statusCode = 400;
+            res.setHeader("Content-Type", "text/plain; charset=utf-8");
+            res.end("Hook token must be provided via Authorization: Bearer <token> or X-Pool Bot-Token header (query parameters are not allowed).");
+            return true;
+        }
+        const { token } = extractHookToken(req);
+        const clientKey = resolveHookClientKey(req);
+        if (!safeEqualSecret(token, hooksConfig.token)) {
+            const throttle = recordHookAuthFailure(clientKey, Date.now());
+            if (throttle.throttled) {
+                const retryAfter = throttle.retryAfterSeconds ?? 1;
+                res.statusCode = 429;
+                res.setHeader("Retry-After", String(retryAfter));
+                res.setHeader("Content-Type", "text/plain; charset=utf-8");
+                res.end("Too Many Requests");
+                logHooks.warn(`hook auth throttled for ${clientKey}; retry-after=${retryAfter}s`);
+                return true;
+            }
             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-Poolbot-Token header instead.");
-        }
+        clearHookAuthFailure(clientKey);
         if (req.method !== "POST") {
             res.statusCode = 405;
             res.setHeader("Allow", "POST");
@@ -103,7 +208,11 @@ export function createHooksRequestHandler(opts) {
         }
         const body = await readJsonBody(req, hooksConfig.maxBodyBytes);
         if (!body.ok) {
-            const status = body.error === "payload too large" ? 413 : 400;
+            const status = body.error === "payload too large"
+                ? 413
+                : body.error === "request body timeout"
+                    ? 408
+                    : 400;
             sendJson(res, status, { ok: false, error: body.error });
             return true;
         }
@@ -129,8 +238,18 @@ export function createHooksRequestHandler(opts) {
                 sendJson(res, 400, { ok: false, error: getHookAgentPolicyError() });
                 return true;
             }
+            const sessionKey = resolveHookSessionKey({
+                hooksConfig,
+                source: "request",
+                sessionKey: normalized.value.sessionKey,
+            });
+            if (!sessionKey.ok) {
+                sendJson(res, 400, { ok: false, error: sessionKey.error });
+                return true;
+            }
             const runId = dispatchAgentHook({
                 ...normalized.value,
+                sessionKey: sessionKey.value,
                 agentId: resolveHookTargetAgentId(hooksConfig, normalized.value.agentId),
             });
             sendJson(res, 202, { ok: true, runId });
@@ -171,12 +290,21 @@ export function createHooksRequestHandler(opts) {
                         sendJson(res, 400, { ok: false, error: getHookAgentPolicyError() });
                         return true;
                     }
+                    const sessionKey = resolveHookSessionKey({
+                        hooksConfig,
+                        source: "mapping",
+                        sessionKey: mapped.action.sessionKey,
+                    });
+                    if (!sessionKey.ok) {
+                        sendJson(res, 400, { ok: false, error: sessionKey.error });
+                        return true;
+                    }
                     const runId = dispatchAgentHook({
                         message: mapped.action.message,
                         name: mapped.action.name ?? "Hook",
                         agentId: resolveHookTargetAgentId(hooksConfig, mapped.action.agentId),
                         wakeMode: mapped.action.wakeMode,
-                        sessionKey: mapped.action.sessionKey ?? "",
+                        sessionKey: sessionKey.value,
                         deliver: resolveHookDeliver(mapped.action.deliver),
                         channel,
                         to: mapped.action.to,
@@ -202,7 +330,7 @@ export function createHooksRequestHandler(opts) {
     };
 }
 export function createGatewayHttpServer(opts) {
-    const { canvasHost, clients, controlUiEnabled, controlUiBasePath, controlUiRoot, openAiChatCompletionsEnabled, openResponsesEnabled, openResponsesConfig, handleHooksRequest, handlePluginRequest, resolvedAuth, } = opts;
+    const { canvasHost, clients, controlUiEnabled, controlUiBasePath, controlUiRoot, openAiChatCompletionsEnabled, openResponsesEnabled, openResponsesConfig, handleHooksRequest, handlePluginRequest, resolvedAuth, rateLimiter, } = opts;
     const httpServer = opts.tlsOptions
         ? createHttpsServer(opts.tlsOptions, (req, res) => {
             void handleRequest(req, res);
@@ -211,69 +339,120 @@ export function createGatewayHttpServer(opts) {
             void handleRequest(req, res);
         });
     async function handleRequest(req, res) {
+        setDefaultSecurityHeaders(res);
         // Don't interfere with WebSocket upgrades; ws handles the 'upgrade' event.
-        if (String(req.headers.upgrade ?? "").toLowerCase() === "websocket")
+        if (String(req.headers.upgrade ?? "").toLowerCase() === "websocket") {
             return;
+        }
         try {
             const configSnapshot = loadConfig();
             const trustedProxies = configSnapshot.gateway?.trustedProxies ?? [];
-            if (await handleHooksRequest(req, res))
+            const allowRealIpFallback = configSnapshot.gateway?.allowRealIpFallback === true;
+            const scopedCanvas = normalizeCanvasScopedUrl(req.url ?? "/");
+            if (scopedCanvas.malformedScopedPath) {
+                sendGatewayAuthFailure(res, { ok: false, reason: "unauthorized" });
+                return;
+            }
+            if (scopedCanvas.rewrittenUrl) {
+                req.url = scopedCanvas.rewrittenUrl;
+            }
+            const requestPath = new URL(req.url ?? "/", "http://localhost").pathname;
+            if (await handleHooksRequest(req, res)) {
                 return;
+            }
             if (await handleToolsInvokeHttpRequest(req, res, {
                 auth: resolvedAuth,
                 trustedProxies,
-            }))
-                return;
-            if (await handleSlackHttpRequest(req, res))
+                allowRealIpFallback,
+                rateLimiter,
+            })) {
                 return;
-            if (handlePluginRequest && (await handlePluginRequest(req, res)))
+            }
+            if (await handleSlackHttpRequest(req, res)) {
                 return;
+            }
+            if (handlePluginRequest) {
+                // Channel HTTP endpoints are gateway-auth protected by default.
+                // Non-channel plugin routes remain plugin-owned and must enforce
+                // their own auth when exposing sensitive functionality.
+                if (requestPath.startsWith("/api/channels/")) {
+                    const token = getBearerToken(req);
+                    const authResult = await authorizeHttpGatewayConnect({
+                        auth: resolvedAuth,
+                        connectAuth: token ? { token, password: token } : null,
+                        req,
+                        trustedProxies,
+                        allowRealIpFallback,
+                        rateLimiter,
+                    });
+                    if (!authResult.ok) {
+                        sendGatewayAuthFailure(res, authResult);
+                        return;
+                    }
+                }
+                if (await handlePluginRequest(req, res)) {
+                    return;
+                }
+            }
             if (openResponsesEnabled) {
                 if (await handleOpenResponsesHttpRequest(req, res, {
                     auth: resolvedAuth,
                     config: openResponsesConfig,
                     trustedProxies,
-                }))
+                    allowRealIpFallback,
+                    rateLimiter,
+                })) {
                     return;
+                }
             }
             if (openAiChatCompletionsEnabled) {
                 if (await handleOpenAiHttpRequest(req, res, {
                     auth: resolvedAuth,
                     trustedProxies,
-                }))
+                    allowRealIpFallback,
+                    rateLimiter,
+                })) {
                     return;
+                }
             }
             if (canvasHost) {
-                const url = new URL(req.url ?? "/", "http://localhost");
-                if (isCanvasPath(url.pathname)) {
+                if (isCanvasPath(requestPath)) {
                     const ok = await authorizeCanvasRequest({
                         req,
                         auth: resolvedAuth,
                         trustedProxies,
+                        allowRealIpFallback,
                         clients,
+                        canvasCapability: scopedCanvas.capability,
+                        malformedScopedPath: scopedCanvas.malformedScopedPath,
+                        rateLimiter,
                     });
-                    if (!ok) {
-                        sendUnauthorized(res);
+                    if (!ok.ok) {
+                        sendGatewayAuthFailure(res, ok);
                         return;
                     }
                 }
-                if (await handleA2uiHttpRequest(req, res))
+                if (await handleA2uiHttpRequest(req, res)) {
                     return;
-                if (await canvasHost.handleHttpRequest(req, res))
+                }
+                if (await canvasHost.handleHttpRequest(req, res)) {
                     return;
+                }
             }
             if (controlUiEnabled) {
                 if (handleControlUiAvatarRequest(req, res, {
                     basePath: controlUiBasePath,
                     resolveAvatar: (agentId) => resolveAgentAvatar(configSnapshot, agentId),
-                }))
+                })) {
                     return;
+                }
                 if (handleControlUiHttpRequest(req, res, {
                     basePath: controlUiBasePath,
                     config: configSnapshot,
                     root: controlUiRoot,
-                }))
+                })) {
                     return;
+                }
             }
             res.statusCode = 404;
             res.setHeader("Content-Type", "text/plain; charset=utf-8");
@@ -288,22 +467,36 @@ export function createGatewayHttpServer(opts) {
     return httpServer;
 }
 export function attachGatewayUpgradeHandler(opts) {
-    const { httpServer, wss, canvasHost, clients, resolvedAuth } = opts;
+    const { httpServer, wss, canvasHost, clients, resolvedAuth, rateLimiter } = opts;
     httpServer.on("upgrade", (req, socket, head) => {
         void (async () => {
+            const scopedCanvas = normalizeCanvasScopedUrl(req.url ?? "/");
+            if (scopedCanvas.malformedScopedPath) {
+                writeUpgradeAuthFailure(socket, { ok: false, reason: "unauthorized" });
+                socket.destroy();
+                return;
+            }
+            if (scopedCanvas.rewrittenUrl) {
+                req.url = scopedCanvas.rewrittenUrl;
+            }
             if (canvasHost) {
                 const url = new URL(req.url ?? "/", "http://localhost");
                 if (url.pathname === CANVAS_WS_PATH) {
                     const configSnapshot = loadConfig();
                     const trustedProxies = configSnapshot.gateway?.trustedProxies ?? [];
+                    const allowRealIpFallback = configSnapshot.gateway?.allowRealIpFallback === true;
                     const ok = await authorizeCanvasRequest({
                         req,
                         auth: resolvedAuth,
                         trustedProxies,
+                        allowRealIpFallback,
                         clients,
+                        canvasCapability: scopedCanvas.capability,
+                        malformedScopedPath: scopedCanvas.malformedScopedPath,
+                        rateLimiter,
                     });
-                    if (!ok) {
-                        socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+                    if (!ok.ok) {
+                        writeUpgradeAuthFailure(socket, ok);
                         socket.destroy();
                         return;
                     }

package/dist/gateway/server-maintenance.js

@@ -1,7 +1,7 @@
 import { abortChatRunById } from "./chat-abort.js";
-import { setBroadcastHealthUpdate } from "./server/health-state.js";
 import { DEDUPE_MAX, DEDUPE_TTL_MS, HEALTH_REFRESH_INTERVAL_MS, TICK_INTERVAL_MS, } from "./server-constants.js";
 import { formatError } from "./server-utils.js";
+import { setBroadcastHealthUpdate } from "./server/health-state.js";
 export function startGatewayMaintenanceTimers(params) {
     setBroadcastHealthUpdate((snap) => {
         params.broadcast("health", snap, {
@@ -30,20 +30,34 @@ export function startGatewayMaintenanceTimers(params) {
         .catch((err) => params.logHealth.error(`initial refresh failed: ${formatError(err)}`));
     // dedupe cache cleanup
     const dedupeCleanup = setInterval(() => {
+        const AGENT_RUN_SEQ_MAX = 10_000;
         const now = Date.now();
         for (const [k, v] of params.dedupe) {
-            if (now - v.ts > DEDUPE_TTL_MS)
+            if (now - v.ts > DEDUPE_TTL_MS) {
                 params.dedupe.delete(k);
+            }
         }
         if (params.dedupe.size > DEDUPE_MAX) {
-            const entries = [...params.dedupe.entries()].sort((a, b) => a[1].ts - b[1].ts);
+            const entries = [...params.dedupe.entries()].toSorted((a, b) => a[1].ts - b[1].ts);
             for (let i = 0; i < params.dedupe.size - DEDUPE_MAX; i++) {
                 params.dedupe.delete(entries[i][0]);
             }
         }
+        if (params.agentRunSeq.size > AGENT_RUN_SEQ_MAX) {
+            const excess = params.agentRunSeq.size - AGENT_RUN_SEQ_MAX;
+            let removed = 0;
+            for (const runId of params.agentRunSeq.keys()) {
+                params.agentRunSeq.delete(runId);
+                removed += 1;
+                if (removed >= excess) {
+                    break;
+                }
+            }
+        }
         for (const [runId, entry] of params.chatAbortControllers) {
-            if (now <= entry.expiresAtMs)
+            if (now <= entry.expiresAtMs) {
                 continue;
+            }
             abortChatRunById({
                 chatAbortControllers: params.chatAbortControllers,
                 chatRunBuffers: params.chatRunBuffers,
@@ -57,8 +71,9 @@ export function startGatewayMaintenanceTimers(params) {
         }
         const ABORTED_RUN_TTL_MS = 60 * 60_000;
         for (const [runId, abortedAt] of params.chatRunState.abortedRuns) {
-            if (now - abortedAt <= ABORTED_RUN_TTL_MS)
+            if (now - abortedAt <= ABORTED_RUN_TTL_MS) {
                 continue;
+            }
             params.chatRunState.abortedRuns.delete(runId);
             params.chatRunBuffers.delete(runId);
             params.chatDeltaSentAt.delete(runId);