@poolzin/pool-bot 2026.2.23 → 2026.2.25

package/dist/gateway/hooks.js

@@ -1,14 +1,16 @@
 import { randomUUID } from "node:crypto";
 import { listAgentIds, resolveDefaultAgentId } from "../agents/agent-scope.js";
 import { listChannelPlugins } from "../channels/plugins/index.js";
+import { readJsonBodyWithLimit, requestBodyErrorToText } from "../infra/http-body.js";
 import { normalizeAgentId } from "../routing/session-key.js";
 import { normalizeMessageChannel } from "../utils/message-channel.js";
 import { resolveHookMappings } from "./hooks-mapping.js";
 const DEFAULT_HOOKS_PATH = "/hooks";
 const DEFAULT_HOOKS_MAX_BODY_BYTES = 256 * 1024;
 export function resolveHooksConfig(cfg) {
-    if (cfg.hooks?.enabled !== true)
+    if (cfg.hooks?.enabled !== true) {
         return null;
+    }
     const token = cfg.hooks?.token?.trim();
     if (!token) {
         throw new Error("hooks.enabled requires hooks.token");
@@ -26,6 +28,18 @@ export function resolveHooksConfig(cfg) {
     const defaultAgentId = resolveDefaultAgentId(cfg);
     const knownAgentIds = resolveKnownAgentIds(cfg, defaultAgentId);
     const allowedAgentIds = resolveAllowedAgentIds(cfg.hooks?.allowedAgentIds);
+    const defaultSessionKey = resolveSessionKey(cfg.hooks?.defaultSessionKey);
+    const allowedSessionKeyPrefixes = resolveAllowedSessionKeyPrefixes(cfg.hooks?.allowedSessionKeyPrefixes);
+    if (defaultSessionKey &&
+        allowedSessionKeyPrefixes &&
+        !isSessionKeyAllowedByPrefix(defaultSessionKey, allowedSessionKeyPrefixes)) {
+        throw new Error("hooks.defaultSessionKey must match hooks.allowedSessionKeyPrefixes");
+    }
+    if (!defaultSessionKey &&
+        allowedSessionKeyPrefixes &&
+        !isSessionKeyAllowedByPrefix("hook:example", allowedSessionKeyPrefixes)) {
+        throw new Error("hooks.allowedSessionKeyPrefixes must include 'hook:' when hooks.defaultSessionKey is unset");
+    }
     return {
         basePath: trimmed,
         token,
@@ -36,6 +50,11 @@ export function resolveHooksConfig(cfg) {
             knownAgentIds,
             allowedAgentIds,
         },
+        sessionPolicy: {
+            defaultSessionKey,
+            allowRequestSessionKey: cfg.hooks?.allowRequestSessionKey === true,
+            allowedSessionKeyPrefixes,
+        },
     };
 }
 function resolveKnownAgentIds(cfg, defaultAgentId) {
@@ -65,62 +84,68 @@ function resolveAllowedAgentIds(raw) {
     }
     return allowed;
 }
+function resolveSessionKey(raw) {
+    const value = raw?.trim();
+    return value ? value : undefined;
+}
+function normalizeSessionKeyPrefix(raw) {
+    const value = raw.trim().toLowerCase();
+    return value ? value : undefined;
+}
+function resolveAllowedSessionKeyPrefixes(raw) {
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    const set = new Set();
+    for (const prefix of raw) {
+        const normalized = normalizeSessionKeyPrefix(prefix);
+        if (!normalized) {
+            continue;
+        }
+        set.add(normalized);
+    }
+    return set.size > 0 ? Array.from(set) : undefined;
+}
+function isSessionKeyAllowedByPrefix(sessionKey, prefixes) {
+    const normalized = sessionKey.trim().toLowerCase();
+    if (!normalized) {
+        return false;
+    }
+    return prefixes.some((prefix) => normalized.startsWith(prefix));
+}
 export function extractHookToken(req, url) {
     const auth = typeof req.headers.authorization === "string" ? req.headers.authorization.trim() : "";
     if (auth.toLowerCase().startsWith("bearer ")) {
         const token = auth.slice(7).trim();
-        if (token)
+        if (token) {
             return { token, fromQuery: false };
+        }
     }
     const headerToken = typeof req.headers["x-poolbot-token"] === "string" ? req.headers["x-poolbot-token"].trim() : "";
-    if (headerToken)
+    if (headerToken) {
         return { token: headerToken, fromQuery: false };
-    const queryToken = url.searchParams.get("token");
-    if (queryToken)
-        return { token: queryToken.trim(), fromQuery: true };
+    }
+    const queryToken = url?.searchParams.get("token")?.trim();
+    if (queryToken) {
+        return { token: queryToken, fromQuery: true };
+    }
     return { token: undefined, fromQuery: false };
 }
 export async function readJsonBody(req, maxBytes) {
-    return await new Promise((resolve) => {
-        let done = false;
-        let total = 0;
-        const chunks = [];
-        req.on("data", (chunk) => {
-            if (done)
-                return;
-            total += chunk.length;
-            if (total > maxBytes) {
-                done = true;
-                resolve({ ok: false, error: "payload too large" });
-                req.destroy();
-                return;
-            }
-            chunks.push(chunk);
-        });
-        req.on("end", () => {
-            if (done)
-                return;
-            done = true;
-            const raw = Buffer.concat(chunks).toString("utf-8").trim();
-            if (!raw) {
-                resolve({ ok: true, value: {} });
-                return;
-            }
-            try {
-                const parsed = JSON.parse(raw);
-                resolve({ ok: true, value: parsed });
-            }
-            catch (err) {
-                resolve({ ok: false, error: String(err) });
-            }
-        });
-        req.on("error", (err) => {
-            if (done)
-                return;
-            done = true;
-            resolve({ ok: false, error: String(err) });
-        });
-    });
+    const result = await readJsonBodyWithLimit(req, { maxBytes, emptyObjectOnEmpty: true });
+    if (result.ok) {
+        return result;
+    }
+    if (result.code === "PAYLOAD_TOO_LARGE") {
+        return { ok: false, error: "payload too large" };
+    }
+    if (result.code === "REQUEST_BODY_TIMEOUT") {
+        return { ok: false, error: "request body timeout" };
+    }
+    if (result.code === "CONNECTION_CLOSED") {
+        return { ok: false, error: requestBodyErrorToText("CONNECTION_CLOSED") };
+    }
+    return { ok: false, error: result.error };
 }
 export function normalizeHookHeaders(req) {
     const headers = {};
@@ -136,8 +161,9 @@ export function normalizeHookHeaders(req) {
 }
 export function normalizeWakePayload(payload) {
     const text = typeof payload.text === "string" ? payload.text.trim() : "";
-    if (!text)
+    if (!text) {
         return { ok: false, error: "text required" };
+    }
     const mode = payload.mode === "next-heartbeat" ? "next-heartbeat" : "now";
     return { ok: true, value: { text, mode } };
 }
@@ -145,13 +171,16 @@ const listHookChannelValues = () => ["last", ...listChannelPlugins().map((plugin
 const getHookChannelSet = () => new Set(listHookChannelValues());
 export const getHookChannelError = () => `channel must be ${listHookChannelValues().join("|")}`;
 export function resolveHookChannel(raw) {
-    if (raw === undefined)
+    if (raw === undefined) {
         return "last";
-    if (typeof raw !== "string")
+    }
+    if (typeof raw !== "string") {
         return null;
+    }
     const normalized = normalizeMessageChannel(raw);
-    if (!normalized || !getHookChannelSet().has(normalized))
+    if (!normalized || !getHookChannelSet().has(normalized)) {
         return null;
+    }
     return normalized;
 }
 export function resolveHookDeliver(raw) {
@@ -182,23 +211,49 @@ export function isHookAgentAllowed(hooksConfig, agentId) {
     return resolved ? allowed.has(resolved) : false;
 }
 export const getHookAgentPolicyError = () => "agentId is not allowed by hooks.allowedAgentIds";
+export const getHookSessionKeyRequestPolicyError = () => "sessionKey is disabled for external /hooks/agent payloads; set hooks.allowRequestSessionKey=true to enable";
+export const getHookSessionKeyPrefixError = (prefixes) => `sessionKey must start with one of: ${prefixes.join(", ")}`;
+export function resolveHookSessionKey(params) {
+    const requested = resolveSessionKey(params.sessionKey);
+    if (requested) {
+        if (params.source === "request" && !params.hooksConfig.sessionPolicy.allowRequestSessionKey) {
+            return { ok: false, error: getHookSessionKeyRequestPolicyError() };
+        }
+        const allowedPrefixes = params.hooksConfig.sessionPolicy.allowedSessionKeyPrefixes;
+        if (allowedPrefixes && !isSessionKeyAllowedByPrefix(requested, allowedPrefixes)) {
+            return { ok: false, error: getHookSessionKeyPrefixError(allowedPrefixes) };
+        }
+        return { ok: true, value: requested };
+    }
+    const defaultSessionKey = params.hooksConfig.sessionPolicy.defaultSessionKey;
+    if (defaultSessionKey) {
+        return { ok: true, value: defaultSessionKey };
+    }
+    const generated = `hook:${(params.idFactory ?? randomUUID)()}`;
+    const allowedPrefixes = params.hooksConfig.sessionPolicy.allowedSessionKeyPrefixes;
+    if (allowedPrefixes && !isSessionKeyAllowedByPrefix(generated, allowedPrefixes)) {
+        return { ok: false, error: getHookSessionKeyPrefixError(allowedPrefixes) };
+    }
+    return { ok: true, value: generated };
+}
 export function normalizeAgentPayload(payload, opts) {
     const message = typeof payload.message === "string" ? payload.message.trim() : "";
-    if (!message)
+    if (!message) {
         return { ok: false, error: "message required" };
+    }
     const nameRaw = payload.name;
     const name = typeof nameRaw === "string" && nameRaw.trim() ? nameRaw.trim() : "Hook";
     const agentIdRaw = payload.agentId;
     const agentId = typeof agentIdRaw === "string" && agentIdRaw.trim() ? agentIdRaw.trim() : undefined;
     const wakeMode = payload.wakeMode === "next-heartbeat" ? "next-heartbeat" : "now";
     const sessionKeyRaw = payload.sessionKey;
-    const idFactory = opts?.idFactory ?? randomUUID;
     const sessionKey = typeof sessionKeyRaw === "string" && sessionKeyRaw.trim()
         ? sessionKeyRaw.trim()
-        : `hook:${idFactory()}`;
+        : `hook:${(opts?.idFactory ?? randomUUID)()}`;
     const channel = resolveHookChannel(payload.channel);
-    if (!channel)
+    if (!channel) {
         return { ok: false, error: getHookChannelError() };
+    }
     const toRaw = payload.to;
     const to = typeof toRaw === "string" && toRaw.trim() ? toRaw.trim() : undefined;
     const modelRaw = payload.model;

package/dist/gateway/http-common.js

@@ -1,4 +1,14 @@
 import { readJsonBody } from "./hooks.js";
+/**
+ * Apply baseline security headers that are safe for all response types (API JSON,
+ * HTML pages, static assets, SSE streams). Headers that restrict framing or set a
+ * Content-Security-Policy are intentionally omitted here because some handlers
+ * (canvas host, A2UI) serve content that may be loaded inside frames.
+ */
+export function setDefaultSecurityHeaders(res) {
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("Referrer-Policy", "no-referrer");
+}
 export function sendJson(res, status, body) {
     res.statusCode = status;
     res.setHeader("Content-Type", "application/json; charset=utf-8");
@@ -44,6 +54,18 @@ export function sendInvalidRequest(res, message) {
 export async function readJsonBodyOrError(req, res, maxBytes) {
     const body = await readJsonBody(req, maxBytes);
     if (!body.ok) {
+        if (body.error === "payload too large") {
+            sendJson(res, 413, {
+                error: { message: "Payload too large", type: "invalid_request_error" },
+            });
+            return undefined;
+        }
+        if (body.error === "request body timeout") {
+            sendJson(res, 408, {
+                error: { message: "Request body timeout", type: "invalid_request_error" },
+            });
+            return undefined;
+        }
         sendInvalidRequest(res, body.error);
         return undefined;
     }

package/dist/gateway/method-scopes.js

@@ -0,0 +1,169 @@
+export const ADMIN_SCOPE = "operator.admin";
+export const READ_SCOPE = "operator.read";
+export const WRITE_SCOPE = "operator.write";
+export const APPROVALS_SCOPE = "operator.approvals";
+export const PAIRING_SCOPE = "operator.pairing";
+export const CLI_DEFAULT_OPERATOR_SCOPES = [
+    ADMIN_SCOPE,
+    APPROVALS_SCOPE,
+    PAIRING_SCOPE,
+];
+const NODE_ROLE_METHODS = new Set(["node.invoke.result", "node.event", "skills.bins"]);
+const METHOD_SCOPE_GROUPS = {
+    [APPROVALS_SCOPE]: [
+        "exec.approval.request",
+        "exec.approval.waitDecision",
+        "exec.approval.resolve",
+    ],
+    [PAIRING_SCOPE]: [
+        "node.pair.request",
+        "node.pair.list",
+        "node.pair.approve",
+        "node.pair.reject",
+        "node.pair.verify",
+        "device.pair.list",
+        "device.pair.approve",
+        "device.pair.reject",
+        "device.pair.remove",
+        "device.token.rotate",
+        "device.token.revoke",
+        "node.rename",
+    ],
+    [READ_SCOPE]: [
+        "health",
+        "logs.tail",
+        "channels.status",
+        "status",
+        "usage.status",
+        "usage.cost",
+        "tts.status",
+        "tts.providers",
+        "models.list",
+        "agents.list",
+        "agent.identity.get",
+        "skills.status",
+        "voicewake.get",
+        "sessions.list",
+        "sessions.preview",
+        "sessions.resolve",
+        "sessions.usage",
+        "sessions.usage.timeseries",
+        "sessions.usage.logs",
+        "cron.list",
+        "cron.status",
+        "cron.runs",
+        "system-presence",
+        "last-heartbeat",
+        "node.list",
+        "node.describe",
+        "chat.history",
+        "config.get",
+        "talk.config",
+        "agents.files.list",
+        "agents.files.get",
+    ],
+    [WRITE_SCOPE]: [
+        "send",
+        "poll",
+        "agent",
+        "agent.wait",
+        "wake",
+        "talk.mode",
+        "tts.enable",
+        "tts.disable",
+        "tts.convert",
+        "tts.setProvider",
+        "voicewake.set",
+        "node.invoke",
+        "chat.send",
+        "chat.abort",
+        "browser.request",
+        "push.test",
+    ],
+    [ADMIN_SCOPE]: [
+        "channels.logout",
+        "agents.create",
+        "agents.update",
+        "agents.delete",
+        "skills.install",
+        "skills.update",
+        "cron.add",
+        "cron.update",
+        "cron.remove",
+        "cron.run",
+        "sessions.patch",
+        "sessions.reset",
+        "sessions.delete",
+        "sessions.compact",
+        "connect",
+        "chat.inject",
+        "web.login.start",
+        "web.login.wait",
+        "set-heartbeats",
+        "system-event",
+        "agents.files.set",
+    ],
+};
+const ADMIN_METHOD_PREFIXES = ["exec.approvals.", "config.", "wizard.", "update."];
+const METHOD_SCOPE_BY_NAME = new Map(Object.entries(METHOD_SCOPE_GROUPS).flatMap(([scope, methods]) => methods.map((method) => [method, scope])));
+function resolveScopedMethod(method) {
+    const explicitScope = METHOD_SCOPE_BY_NAME.get(method);
+    if (explicitScope) {
+        return explicitScope;
+    }
+    if (ADMIN_METHOD_PREFIXES.some((prefix) => method.startsWith(prefix))) {
+        return ADMIN_SCOPE;
+    }
+    return undefined;
+}
+export function isApprovalMethod(method) {
+    return resolveScopedMethod(method) === APPROVALS_SCOPE;
+}
+export function isPairingMethod(method) {
+    return resolveScopedMethod(method) === PAIRING_SCOPE;
+}
+export function isReadMethod(method) {
+    return resolveScopedMethod(method) === READ_SCOPE;
+}
+export function isWriteMethod(method) {
+    return resolveScopedMethod(method) === WRITE_SCOPE;
+}
+export function isNodeRoleMethod(method) {
+    return NODE_ROLE_METHODS.has(method);
+}
+export function isAdminOnlyMethod(method) {
+    return resolveScopedMethod(method) === ADMIN_SCOPE;
+}
+export function resolveRequiredOperatorScopeForMethod(method) {
+    return resolveScopedMethod(method);
+}
+export function resolveLeastPrivilegeOperatorScopesForMethod(method) {
+    const requiredScope = resolveRequiredOperatorScopeForMethod(method);
+    if (requiredScope) {
+        return [requiredScope];
+    }
+    // Default-deny for unclassified methods.
+    return [];
+}
+export function authorizeOperatorScopesForMethod(method, scopes) {
+    if (scopes.includes(ADMIN_SCOPE)) {
+        return { allowed: true };
+    }
+    const requiredScope = resolveRequiredOperatorScopeForMethod(method) ?? ADMIN_SCOPE;
+    if (requiredScope === READ_SCOPE) {
+        if (scopes.includes(READ_SCOPE) || scopes.includes(WRITE_SCOPE)) {
+            return { allowed: true };
+        }
+        return { allowed: false, missingScope: READ_SCOPE };
+    }
+    if (scopes.includes(requiredScope)) {
+        return { allowed: true };
+    }
+    return { allowed: false, missingScope: requiredScope };
+}
+export function isGatewayMethodClassified(method) {
+    if (isNodeRoleMethod(method)) {
+        return true;
+    }
+    return resolveRequiredOperatorScopeForMethod(method) !== undefined;
+}

package/dist/gateway/net.js

@@ -347,3 +347,26 @@ export function isLoopbackHost(host) {
     const unbracket = h.startsWith("[") && h.endsWith("]") ? h.slice(1, -1) : h;
     return isLoopbackAddress(unbracket);
 }
+/**
+ * Returns true if the URL uses wss:// (encrypted) OR ws:// to a loopback address.
+ * Plaintext ws:// to non-loopback addresses is insecure (CWE-319, CVSS 9.8):
+ * both credentials (gateway token/password) and chat/conversation data
+ * AND chat/conversation data would be exposed to network interception.
+ */
+export function isSecureWebSocketUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol === "wss:") {
+        return true;
+    }
+    if (parsed.protocol !== "ws:") {
+        return false;
+    }
+    // ws:// is only secure for loopback addresses
+    return isLoopbackHost(parsed.hostname);
+}