@poolzin/pool-bot 2026.2.23 → 2026.2.25

package/dist/gateway/auth.js

@@ -104,28 +104,60 @@ async function resolveVerifiedTailscaleUser(params) {
     };
 }
 export function resolveGatewayAuth(params) {
-    const authConfig = params.authConfig ?? {};
+    const baseAuthConfig = params.authConfig ?? {};
+    const authOverride = params.authOverride ?? undefined;
+    const authConfig = { ...baseAuthConfig };
+    if (authOverride) {
+        if (authOverride.mode !== undefined) {
+            authConfig.mode = authOverride.mode;
+        }
+        if (authOverride.token !== undefined) {
+            authConfig.token = authOverride.token;
+        }
+        if (authOverride.password !== undefined) {
+            authConfig.password = authOverride.password;
+        }
+        if (authOverride.allowTailscale !== undefined) {
+            authConfig.allowTailscale = authOverride.allowTailscale;
+        }
+        if (authOverride.rateLimit !== undefined) {
+            authConfig.rateLimit = authOverride.rateLimit;
+        }
+        if (authOverride.trustedProxy !== undefined) {
+            authConfig.trustedProxy = authOverride.trustedProxy;
+        }
+    }
     const env = params.env ?? process.env;
     const token = authConfig.token ?? env.POOLBOT_GATEWAY_TOKEN ?? undefined;
     const password = authConfig.password ?? env.POOLBOT_GATEWAY_PASSWORD ?? undefined;
     const trustedProxy = authConfig.trustedProxy;
     let mode;
-    if (authConfig.mode) {
+    let modeSource;
+    if (authOverride?.mode !== undefined) {
+        mode = authOverride.mode;
+        modeSource = "override";
+    }
+    else if (authConfig.mode) {
         mode = authConfig.mode;
+        modeSource = "config";
     }
     else if (password) {
         mode = "password";
+        modeSource = "password";
     }
     else if (token) {
         mode = "token";
+        modeSource = "token";
     }
     else {
-        mode = "none";
+        mode = "token";
+        modeSource = "default";
     }
     const allowTailscale = authConfig.allowTailscale ??
         (params.tailscaleMode === "serve" && mode !== "password" && mode !== "trusted-proxy");
     return {
         mode,
+        modeSource,
         token,
         password,
         allowTailscale,
@@ -203,6 +235,9 @@ export async function authorizeGatewayConnect(params) {
         }
         return { ok: false, reason: result.reason };
     }
+    if (auth.mode === "none") {
+        return { ok: true, method: "none" };
+    }
     const limiter = params.rateLimiter;
     const ip = params.clientIp ?? resolveRequestClientIp(req, trustedProxies) ?? req?.socket?.remoteAddress;
     const rateLimitScope = params.rateLimitScope ?? AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET;

package/dist/gateway/call.js

@@ -5,7 +5,8 @@ import { pickPrimaryTailnetIPv4 } from "../infra/tailnet.js";
 import { loadGatewayTlsRuntime } from "../infra/tls/gateway.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES, } from "../utils/message-channel.js";
 import { GatewayClient } from "./client.js";
-import { pickPrimaryLanIPv4 } from "./net.js";
+import { CLI_DEFAULT_OPERATOR_SCOPES, resolveLeastPrivilegeOperatorScopesForMethod, } from "./method-scopes.js";
+import { isSecureWebSocketUrl, pickPrimaryLanIPv4 } from "./net.js";
 import { PROTOCOL_VERSION } from "./protocol/index.js";
 export function resolveExplicitGatewayAuth(opts) {
     const token = typeof opts?.token === "string" && opts.token.trim().length > 0 ? opts.token.trim() : undefined;
@@ -69,6 +70,18 @@ export function buildGatewayConnectionDetails(options = {}) {
         ? "Warn: gateway.mode=remote but gateway.remote.url is missing; set gateway.remote.url or switch gateway.mode=local."
         : undefined;
     const bindDetail = !urlOverride && !remoteUrl ? `Bind: ${bindMode}` : undefined;
+    // Security check: block ALL insecure ws:// to non-loopback addresses (CWE-319, CVSS 9.8)
+    // This applies to the FINAL resolved URL, regardless of source (config, CLI override, etc).
+    // Both credentials and chat/conversation data must not be transmitted over plaintext to remote hosts.
+    if (!isSecureWebSocketUrl(url)) {
+        throw new Error([
+            `SECURITY ERROR: Gateway URL "${url}" uses plaintext ws:// to a non-loopback address.`,
+            "Both credentials and chat data would be exposed to network interception.",
+            `Source: ${urlSource}`,
+            `Config: ${configPath}`,
+            "Fix: Use wss:// for the gateway URL, or connect via SSH tunnel to localhost.",
+        ].join("\n"));
+    }
     const message = [
         `Gateway target: ${url}`,
         `Source: ${urlSource}`,
@@ -86,77 +99,89 @@ export function buildGatewayConnectionDetails(options = {}) {
         message,
     };
 }
-export async function callGateway(opts) {
-    const timeoutMs = typeof opts.timeoutMs === "number" && Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 10_000;
+function trimToUndefined(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function resolveGatewayCallTimeout(timeoutValue) {
+    const timeoutMs = typeof timeoutValue === "number" && Number.isFinite(timeoutValue) ? timeoutValue : 10_000;
     const safeTimerTimeoutMs = Math.max(1, Math.min(Math.floor(timeoutMs), 2_147_483_647));
+    return { timeoutMs, safeTimerTimeoutMs };
+}
+function resolveGatewayCallContext(opts) {
     const config = opts.config ?? loadConfig();
+    const configPath = opts.configPath ?? resolveConfigPath(process.env, resolveStateDir(process.env));
     const isRemoteMode = config.gateway?.mode === "remote";
-    const remote = isRemoteMode ? config.gateway?.remote : undefined;
-    const urlOverride = typeof opts.url === "string" && opts.url.trim().length > 0 ? opts.url.trim() : undefined;
+    const remote = isRemoteMode
+        ? config.gateway?.remote
+        : undefined;
+    const urlOverride = trimToUndefined(opts.url);
+    const remoteUrl = trimToUndefined(remote?.url);
     const explicitAuth = resolveExplicitGatewayAuth({ token: opts.token, password: opts.password });
-    ensureExplicitGatewayAuth({
-        urlOverride,
-        auth: explicitAuth,
-        errorHint: "Fix: pass --token or --password (or gatewayToken in tools).",
-        configPath: opts.configPath ?? resolveConfigPath(process.env, resolveStateDir(process.env)),
-    });
-    const remoteUrl = typeof remote?.url === "string" && remote.url.trim().length > 0 ? remote.url.trim() : undefined;
-    if (isRemoteMode && !urlOverride && !remoteUrl) {
-        const configPath = opts.configPath ?? resolveConfigPath(process.env, resolveStateDir(process.env));
-        throw new Error([
-            "gateway remote mode misconfigured: gateway.remote.url missing",
-            `Config: ${configPath}`,
-            "Fix: set gateway.remote.url, or set gateway.mode=local.",
-        ].join("\n"));
+    return { config, configPath, isRemoteMode, remote, urlOverride, remoteUrl, explicitAuth };
+}
+function ensureRemoteModeUrlConfigured(context) {
+    if (!context.isRemoteMode || context.urlOverride || context.remoteUrl) {
+        return;
     }
-    const authToken = config.gateway?.auth?.token;
-    const authPassword = config.gateway?.auth?.password;
-    const connectionDetails = buildGatewayConnectionDetails({
-        config,
-        url: urlOverride,
-        ...(opts.configPath ? { configPath: opts.configPath } : {}),
-    });
-    const url = connectionDetails.url;
-    const useLocalTls = config.gateway?.tls?.enabled === true && !urlOverride && !remoteUrl && url.startsWith("wss://");
-    const tlsRuntime = useLocalTls ? await loadGatewayTlsRuntime(config.gateway?.tls) : undefined;
-    const remoteTlsFingerprint = isRemoteMode && !urlOverride && remoteUrl && typeof remote?.tlsFingerprint === "string"
-        ? remote.tlsFingerprint.trim()
-        : undefined;
-    const overrideTlsFingerprint = typeof opts.tlsFingerprint === "string" ? opts.tlsFingerprint.trim() : undefined;
-    const tlsFingerprint = overrideTlsFingerprint ||
-        remoteTlsFingerprint ||
-        (tlsRuntime?.enabled ? tlsRuntime.fingerprintSha256 : undefined);
-    const token = explicitAuth.token ||
-        (!urlOverride
-            ? isRemoteMode
-                ? typeof remote?.token === "string" && remote.token.trim().length > 0
-                    ? remote.token.trim()
-                    : undefined
-                : process.env.POOLBOT_GATEWAY_TOKEN?.trim() ||
-                    process.env.CLAWDBOT_GATEWAY_TOKEN?.trim() ||
-                    (typeof authToken === "string" && authToken.trim().length > 0
-                        ? authToken.trim()
-                        : undefined)
+    throw new Error([
+        "gateway remote mode misconfigured: gateway.remote.url missing",
+        `Config: ${context.configPath}`,
+        "Fix: set gateway.remote.url, or set gateway.mode=local.",
+    ].join("\n"));
+}
+function resolveGatewayCredentials(context) {
+    const authToken = context.config.gateway?.auth?.token;
+    const authPassword = context.config.gateway?.auth?.password;
+    const token = context.explicitAuth.token ||
+        (!context.urlOverride
+            ? context.isRemoteMode
+                ? trimToUndefined(context.remote?.token)
+                : trimToUndefined(process.env.POOLBOT_GATEWAY_TOKEN) ||
+                    trimToUndefined(process.env.CLAWDBOT_GATEWAY_TOKEN) ||
+                    trimToUndefined(authToken)
             : undefined);
-    const password = explicitAuth.password ||
-        (!urlOverride
-            ? process.env.POOLBOT_GATEWAY_PASSWORD?.trim() ||
-                process.env.CLAWDBOT_GATEWAY_PASSWORD?.trim() ||
-                (isRemoteMode
-                    ? typeof remote?.password === "string" && remote.password.trim().length > 0
-                        ? remote.password.trim()
-                        : undefined
-                    : typeof authPassword === "string" && authPassword.trim().length > 0
-                        ? authPassword.trim()
-                        : undefined)
+    const password = context.explicitAuth.password ||
+        (!context.urlOverride
+            ? trimToUndefined(process.env.POOLBOT_GATEWAY_PASSWORD) ||
+                trimToUndefined(process.env.CLAWDBOT_GATEWAY_PASSWORD) ||
+                (context.isRemoteMode
+                    ? trimToUndefined(context.remote?.password)
+                    : trimToUndefined(authPassword))
             : undefined);
-    const formatCloseError = (code, reason) => {
-        const reasonText = reason?.trim() || "no close reason";
-        const hint = code === 1006 ? "abnormal closure (no close frame)" : code === 1000 ? "normal closure" : "";
-        const suffix = hint ? ` ${hint}` : "";
-        return `gateway closed (${code}${suffix}): ${reasonText}\n${connectionDetails.message}`;
-    };
-    const formatTimeoutError = () => `gateway timeout after ${timeoutMs}ms\n${connectionDetails.message}`;
+    return { token, password };
+}
+async function resolveGatewayTlsFingerprint(params) {
+    const { opts, context, url } = params;
+    const useLocalTls = context.config.gateway?.tls?.enabled === true &&
+        !context.urlOverride &&
+        !context.remoteUrl &&
+        url.startsWith("wss://");
+    const tlsRuntime = useLocalTls
+        ? await loadGatewayTlsRuntime(context.config.gateway?.tls)
+        : undefined;
+    const overrideTlsFingerprint = trimToUndefined(opts.tlsFingerprint);
+    const remoteTlsFingerprint = context.isRemoteMode && !context.urlOverride && context.remoteUrl
+        ? trimToUndefined(context.remote?.tlsFingerprint)
+        : undefined;
+    return (overrideTlsFingerprint ||
+        remoteTlsFingerprint ||
+        (tlsRuntime?.enabled ? tlsRuntime.fingerprintSha256 : undefined));
+}
+function formatGatewayCloseError(code, reason, connectionDetails) {
+    const reasonText = reason?.trim() || "no close reason";
+    const hint = code === 1006 ? "abnormal closure (no close frame)" : code === 1000 ? "normal closure" : "";
+    const suffix = hint ? ` ${hint}` : "";
+    return `gateway closed (${code}${suffix}): ${reasonText}\n${connectionDetails.message}`;
+}
+function formatGatewayTimeoutError(timeoutMs, connectionDetails) {
+    return `gateway timeout after ${timeoutMs}ms\n${connectionDetails.message}`;
+}
+async function executeGatewayRequestWithScopes(params) {
+    const { opts, scopes, url, token, password, tlsFingerprint, timeoutMs, safeTimerTimeoutMs } = params;
     return await new Promise((resolve, reject) => {
         let settled = false;
         let ignoreClose = false;
@@ -185,7 +210,7 @@ export async function callGateway(opts) {
             platform: opts.platform,
             mode: opts.mode ?? GATEWAY_CLIENT_MODES.CLI,
             role: "operator",
-            scopes: ["operator.admin", "operator.approvals", "operator.pairing"],
+            scopes,
             deviceIdentity: loadOrCreateDeviceIdentity(),
             minProtocol: opts.minProtocol ?? PROTOCOL_VERSION,
             maxProtocol: opts.maxProtocol ?? PROTOCOL_VERSION,
@@ -210,17 +235,73 @@ export async function callGateway(opts) {
                 }
                 ignoreClose = true;
                 client.stop();
-                stop(new Error(formatCloseError(code, reason)));
+                stop(new Error(formatGatewayCloseError(code, reason, params.connectionDetails)));
             },
         });
         const timer = setTimeout(() => {
             ignoreClose = true;
             client.stop();
-            stop(new Error(formatTimeoutError()));
+            stop(new Error(formatGatewayTimeoutError(timeoutMs, params.connectionDetails)));
         }, safeTimerTimeoutMs);
         client.start();
     });
 }
+async function callGatewayWithScopes(opts, scopes) {
+    const { timeoutMs, safeTimerTimeoutMs } = resolveGatewayCallTimeout(opts.timeoutMs);
+    const context = resolveGatewayCallContext(opts);
+    ensureExplicitGatewayAuth({
+        urlOverride: context.urlOverride,
+        auth: context.explicitAuth,
+        errorHint: "Fix: pass --token or --password (or gatewayToken in tools).",
+        configPath: context.configPath,
+    });
+    ensureRemoteModeUrlConfigured(context);
+    const connectionDetails = buildGatewayConnectionDetails({
+        config: context.config,
+        url: context.urlOverride,
+        ...(opts.configPath ? { configPath: opts.configPath } : {}),
+    });
+    const url = connectionDetails.url;
+    const tlsFingerprint = await resolveGatewayTlsFingerprint({ opts, context, url });
+    const { token, password } = resolveGatewayCredentials(context);
+    return await executeGatewayRequestWithScopes({
+        opts,
+        scopes,
+        url,
+        token,
+        password,
+        tlsFingerprint,
+        timeoutMs,
+        safeTimerTimeoutMs,
+        connectionDetails,
+    });
+}
+export async function callGatewayScoped(opts) {
+    return await callGatewayWithScopes(opts, opts.scopes);
+}
+export async function callGatewayCli(opts) {
+    const scopes = Array.isArray(opts.scopes) ? opts.scopes : CLI_DEFAULT_OPERATOR_SCOPES;
+    return await callGatewayWithScopes(opts, scopes);
+}
+export async function callGatewayLeastPrivilege(opts) {
+    const scopes = resolveLeastPrivilegeOperatorScopesForMethod(opts.method);
+    return await callGatewayWithScopes(opts, scopes);
+}
+export async function callGateway(opts) {
+    if (Array.isArray(opts.scopes)) {
+        return await callGatewayWithScopes(opts, opts.scopes);
+    }
+    const callerMode = opts.mode ?? GATEWAY_CLIENT_MODES.BACKEND;
+    const callerName = opts.clientName ?? GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT;
+    if (callerMode === GATEWAY_CLIENT_MODES.CLI || callerName === GATEWAY_CLIENT_NAMES.CLI) {
+        return await callGatewayCli(opts);
+    }
+    return await callGatewayLeastPrivilege({
+        ...opts,
+        mode: callerMode,
+        clientName: callerName,
+    });
+}
 export function randomIdempotencyKey() {
     return randomUUID();
 }

package/dist/gateway/canvas-capability.js

@@ -0,0 +1,75 @@
+import { randomBytes } from "node:crypto";
+export const CANVAS_CAPABILITY_PATH_PREFIX = "/__poolbot__/cap";
+export const CANVAS_CAPABILITY_QUERY_PARAM = "oc_cap";
+export const CANVAS_CAPABILITY_TTL_MS = 10 * 60_000;
+function normalizeCapability(raw) {
+    const trimmed = raw?.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function mintCanvasCapabilityToken() {
+    return randomBytes(18).toString("base64url");
+}
+export function buildCanvasScopedHostUrl(baseUrl, capability) {
+    const normalizedCapability = normalizeCapability(capability);
+    if (!normalizedCapability) {
+        return undefined;
+    }
+    try {
+        const url = new URL(baseUrl);
+        const trimmedPath = url.pathname.replace(/\/+$/, "");
+        const prefix = `${CANVAS_CAPABILITY_PATH_PREFIX}/${encodeURIComponent(normalizedCapability)}`;
+        url.pathname = `${trimmedPath}${prefix}`;
+        url.search = "";
+        url.hash = "";
+        return url.toString().replace(/\/$/, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function normalizeCanvasScopedUrl(rawUrl) {
+    const url = new URL(rawUrl, "http://localhost");
+    const prefix = `${CANVAS_CAPABILITY_PATH_PREFIX}/`;
+    let scopedPath = false;
+    let malformedScopedPath = false;
+    let capabilityFromPath;
+    let rewrittenUrl;
+    if (url.pathname.startsWith(prefix)) {
+        scopedPath = true;
+        const remainder = url.pathname.slice(prefix.length);
+        const slashIndex = remainder.indexOf("/");
+        if (slashIndex <= 0) {
+            malformedScopedPath = true;
+        }
+        else {
+            const encodedCapability = remainder.slice(0, slashIndex);
+            const canonicalPath = remainder.slice(slashIndex) || "/";
+            let decoded;
+            try {
+                decoded = decodeURIComponent(encodedCapability);
+            }
+            catch {
+                malformedScopedPath = true;
+            }
+            capabilityFromPath = normalizeCapability(decoded);
+            if (!capabilityFromPath || !canonicalPath.startsWith("/")) {
+                malformedScopedPath = true;
+            }
+            else {
+                url.pathname = canonicalPath;
+                if (!url.searchParams.has(CANVAS_CAPABILITY_QUERY_PARAM)) {
+                    url.searchParams.set(CANVAS_CAPABILITY_QUERY_PARAM, capabilityFromPath);
+                }
+                rewrittenUrl = `${url.pathname}${url.search}`;
+            }
+        }
+    }
+    const capability = capabilityFromPath ?? normalizeCapability(url.searchParams.get(CANVAS_CAPABILITY_QUERY_PARAM));
+    return {
+        pathname: url.pathname,
+        capability,
+        rewrittenUrl,
+        scopedPath,
+        malformedScopedPath,
+    };
+}

package/dist/gateway/control-plane-audit.js

@@ -0,0 +1,28 @@
+function normalizePart(value, fallback) {
+    if (typeof value !== "string") {
+        return fallback;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : fallback;
+}
+export function resolveControlPlaneActor(client) {
+    return {
+        actor: normalizePart(client?.connect?.client?.id, "unknown-actor"),
+        deviceId: normalizePart(client?.connect?.device?.id, "unknown-device"),
+        clientIp: normalizePart(client?.clientIp, "unknown-ip"),
+        connId: normalizePart(client?.connId, "unknown-conn"),
+    };
+}
+export function formatControlPlaneActor(actor) {
+    return `actor=${actor.actor} device=${actor.deviceId} ip=${actor.clientIp} conn=${actor.connId}`;
+}
+export function summarizeChangedPaths(paths, maxPaths = 8) {
+    if (paths.length === 0) {
+        return "<none>";
+    }
+    if (paths.length <= maxPaths) {
+        return paths.join(",");
+    }
+    const head = paths.slice(0, maxPaths).join(",");
+    return `${head},+${paths.length - maxPaths} more`;
+}

package/dist/gateway/control-plane-rate-limit.js

@@ -0,0 +1,53 @@
+const CONTROL_PLANE_RATE_LIMIT_MAX_REQUESTS = 3;
+const CONTROL_PLANE_RATE_LIMIT_WINDOW_MS = 60_000;
+const controlPlaneBuckets = new Map();
+function normalizePart(value, fallback) {
+    if (typeof value !== "string") {
+        return fallback;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : fallback;
+}
+export function resolveControlPlaneRateLimitKey(client) {
+    const deviceId = normalizePart(client?.connect?.device?.id, "unknown-device");
+    const clientIp = normalizePart(client?.clientIp, "unknown-ip");
+    return `${deviceId}|${clientIp}`;
+}
+export function consumeControlPlaneWriteBudget(params) {
+    const nowMs = params.nowMs ?? Date.now();
+    const key = resolveControlPlaneRateLimitKey(params.client);
+    const bucket = controlPlaneBuckets.get(key);
+    if (!bucket || nowMs - bucket.windowStartMs >= CONTROL_PLANE_RATE_LIMIT_WINDOW_MS) {
+        controlPlaneBuckets.set(key, {
+            count: 1,
+            windowStartMs: nowMs,
+        });
+        return {
+            allowed: true,
+            retryAfterMs: 0,
+            remaining: CONTROL_PLANE_RATE_LIMIT_MAX_REQUESTS - 1,
+            key,
+        };
+    }
+    if (bucket.count >= CONTROL_PLANE_RATE_LIMIT_MAX_REQUESTS) {
+        const retryAfterMs = Math.max(0, bucket.windowStartMs + CONTROL_PLANE_RATE_LIMIT_WINDOW_MS - nowMs);
+        return {
+            allowed: false,
+            retryAfterMs,
+            remaining: 0,
+            key,
+        };
+    }
+    bucket.count += 1;
+    return {
+        allowed: true,
+        retryAfterMs: 0,
+        remaining: Math.max(0, CONTROL_PLANE_RATE_LIMIT_MAX_REQUESTS - bucket.count),
+        key,
+    };
+}
+export const __testing = {
+    resetControlPlaneRateLimitState() {
+        controlPlaneBuckets.clear();
+    },
+};

package/dist/gateway/events.js

@@ -0,0 +1 @@
+export const GATEWAY_EVENT_UPDATE_AVAILABLE = "update.available";