@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/browser/config.js

@@ -16,6 +16,30 @@ function normalizeTimeoutMs(raw, fallback) {
     const value = typeof raw === "number" && Number.isFinite(raw) ? Math.floor(raw) : fallback;
     return value < 0 ? fallback : value;
 }
+function normalizeStringList(raw) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return undefined;
+    }
+    const values = raw
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0);
+    return values.length > 0 ? values : undefined;
+}
+function resolveBrowserSsrFPolicy(cfg) {
+    const allowPrivateNetwork = cfg?.ssrfPolicy?.allowPrivateNetwork;
+    const allowedHostnames = normalizeStringList(cfg?.ssrfPolicy?.allowedHostnames);
+    const hostnameAllowlist = normalizeStringList(cfg?.ssrfPolicy?.hostnameAllowlist);
+    if (allowPrivateNetwork === undefined &&
+        allowedHostnames === undefined &&
+        hostnameAllowlist === undefined) {
+        return undefined;
+    }
+    return {
+        ...(allowPrivateNetwork === true ? { allowPrivateNetwork: true } : {}),
+        ...(allowedHostnames ? { allowedHostnames } : {}),
+        ...(hostnameAllowlist ? { hostnameAllowlist } : {}),
+    };
+}
 export function parseHttpUrl(raw, label) {
     const trimmed = raw.trim();
     const parsed = new URL(trimmed);
@@ -113,6 +137,10 @@ export function resolveBrowserConfig(cfg, rootConfig) {
         (profiles[DEFAULT_BROWSER_DEFAULT_PROFILE_NAME]
             ? DEFAULT_BROWSER_DEFAULT_PROFILE_NAME
             : DEFAULT_CLAWD_BROWSER_PROFILE_NAME);
+    const ssrfPolicy = resolveBrowserSsrFPolicy(cfg);
+    const extraArgs = Array.isArray(cfg?.extraArgs)
+        ? cfg.extraArgs.filter((a) => typeof a === "string" && a.trim().length > 0)
+        : [];
     return {
         enabled,
         evaluateEnabled,
@@ -129,6 +157,8 @@ export function resolveBrowserConfig(cfg, rootConfig) {
         attachOnly,
         defaultProfile,
         profiles,
+        ssrfPolicy,
+        extraArgs,
     };
 }
 /**

package/dist/browser/extension-relay-auth.js

@@ -0,0 +1,55 @@
+import { createHmac } from "node:crypto";
+import { loadConfig } from "../config/config.js";
+const RELAY_TOKEN_CONTEXT = "poolbot-extension-relay-v1";
+const DEFAULT_RELAY_PROBE_TIMEOUT_MS = 500;
+const POOLBOT_RELAY_BROWSER = "PoolBot/extension-relay";
+function resolveGatewayAuthToken() {
+    const envToken = process.env.POOLBOT_GATEWAY_TOKEN?.trim() ?? process.env.CLAWDBOT_GATEWAY_TOKEN?.trim();
+    if (envToken) {
+        return envToken;
+    }
+    try {
+        const cfg = loadConfig();
+        const configToken = cfg.gateway?.auth?.token?.trim();
+        if (configToken) {
+            return configToken;
+        }
+    }
+    catch {
+        // ignore config read failures; caller can fallback to per-process random token
+    }
+    return null;
+}
+function deriveRelayAuthToken(gatewayToken, port) {
+    return createHmac("sha256", gatewayToken).update(`${RELAY_TOKEN_CONTEXT}:${port}`).digest("hex");
+}
+export function resolveRelayAuthTokenForPort(port) {
+    const gatewayToken = resolveGatewayAuthToken();
+    if (gatewayToken) {
+        return deriveRelayAuthToken(gatewayToken, port);
+    }
+    throw new Error("extension relay requires gateway auth token (set gateway.auth.token or POOLBOT_GATEWAY_TOKEN)");
+}
+export async function probeAuthenticatedPoolBotRelay(params) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), params.timeoutMs ?? DEFAULT_RELAY_PROBE_TIMEOUT_MS);
+    try {
+        const versionUrl = new URL("/json/version", `${params.baseUrl}/`).toString();
+        const res = await fetch(versionUrl, {
+            signal: ctrl.signal,
+            headers: { [params.relayAuthHeader]: params.relayAuthToken },
+        });
+        if (!res.ok) {
+            return false;
+        }
+        const body = (await res.json());
+        const browserName = typeof body?.Browser === "string" ? body.Browser.trim() : "";
+        return browserName === POOLBOT_RELAY_BROWSER;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/browser/extension-relay.js

@@ -1,8 +1,8 @@
-import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import WebSocket, { WebSocketServer } from "ws";
 import { isLoopbackAddress, isLoopbackHost } from "../gateway/net.js";
 import { rawDataToString } from "../infra/ws.js";
+import { probeAuthenticatedPoolBotRelay, resolveRelayAuthTokenForPort, } from "./extension-relay-auth.js";
 const RELAY_AUTH_HEADER = "x-poolbot-relay-token";
 function headerValue(value) {
     if (!value) {
@@ -16,14 +16,32 @@ function headerValue(value) {
 function getHeader(req, name) {
     return headerValue(req.headers[name.toLowerCase()]);
 }
+function getRelayAuthTokenFromRequest(req, url) {
+    const headerToken = getHeader(req, RELAY_AUTH_HEADER)?.trim();
+    if (headerToken) {
+        return headerToken;
+    }
+    const queryToken = url?.searchParams.get("token")?.trim();
+    if (queryToken) {
+        return queryToken;
+    }
+    return undefined;
+}
+function parseUrlPort(parsed) {
+    const port = parsed.port?.trim() !== "" ? Number(parsed.port) : parsed.protocol === "https:" ? 443 : 80;
+    if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+        return null;
+    }
+    return port;
+}
 function parseBaseUrl(raw) {
     const parsed = new URL(raw.trim().replace(/\/$/, ""));
     if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
         throw new Error(`extension relay cdpUrl must be http(s), got ${parsed.protocol}`);
     }
     const host = parsed.hostname;
-    const port = parsed.port?.trim() !== "" ? Number(parsed.port) : parsed.protocol === "https:" ? 443 : 80;
-    if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+    const port = parseUrlPort(parsed);
+    if (!port) {
         throw new Error(`extension relay cdpUrl has invalid port: ${parsed.port || "(empty)"}`);
     }
     return { host, port, baseUrl: parsed.toString().replace(/\/$/, "") };
@@ -47,23 +65,24 @@ function rejectUpgrade(socket, status, bodyText) {
         // ignore
     }
 }
-const serversByPort = new Map();
-const relayAuthByPort = new Map();
+const relayRuntimeByPort = new Map();
+function isAddrInUseError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        err.code === "EADDRINUSE");
+}
 function relayAuthTokenForUrl(url) {
     try {
         const parsed = new URL(url);
         if (!isLoopbackHost(parsed.hostname)) {
             return null;
         }
-        const port = parsed.port?.trim() !== ""
-            ? Number(parsed.port)
-            : parsed.protocol === "https:" || parsed.protocol === "wss:"
-                ? 443
-                : 80;
-        if (!Number.isFinite(port)) {
+        const port = parseUrlPort(parsed);
+        if (!port) {
             return null;
         }
-        return relayAuthByPort.get(port) ?? null;
+        return relayRuntimeByPort.get(port)?.relayAuthToken ?? null;
     }
     catch {
         return null;
@@ -81,10 +100,11 @@ export async function ensureChromeExtensionRelayServer(opts) {
     if (!isLoopbackHost(info.host)) {
         throw new Error(`extension relay requires loopback cdpUrl host (got ${info.host})`);
     }
-    const existing = serversByPort.get(info.port);
+    const existing = relayRuntimeByPort.get(info.port);
     if (existing) {
-        return existing;
+        return existing.server;
     }
+    const relayAuthToken = resolveRelayAuthTokenForPort(info.port);
     let extensionWs = null;
     const cdpClients = new Set();
     const connectedTargets = new Map();
@@ -144,9 +164,9 @@ export async function ensureChromeExtensionRelayServer(opts) {
             case "Browser.getVersion":
                 return {
                     protocolVersion: "1.3",
-                    product: "Chrome/PoolBot-Extension-Relay",
+                    product: "Chrome/Pool Bot-Extension-Relay",
                     revision: "0",
-                    userAgent: "PoolBot-Extension-Relay",
+                    userAgent: "Pool Bot-Extension-Relay",
                     jsVersion: "V8",
                 };
             case "Browser.setDownloadBehavior":
@@ -207,7 +227,6 @@ export async function ensureChromeExtensionRelayServer(opts) {
             }
         }
     };
-    const relayAuthToken = randomBytes(32).toString("base64url");
     const server = createServer((req, res) => {
         const url = new URL(req.url ?? "/", info.baseUrl);
         const path = url.pathname;
@@ -333,6 +352,11 @@ export async function ensureChromeExtensionRelayServer(opts) {
             return;
         }
         if (pathname === "/extension") {
+            const token = getRelayAuthTokenFromRequest(req, url);
+            if (!token || token !== relayAuthToken) {
+                rejectUpgrade(socket, 401, "Unauthorized");
+                return;
+            }
             if (extensionWs) {
                 rejectUpgrade(socket, 409, "Extension already connected");
                 return;
@@ -343,7 +367,7 @@ export async function ensureChromeExtensionRelayServer(opts) {
             return;
         }
         if (pathname === "/cdp") {
-            const token = getHeader(req, RELAY_AUTH_HEADER);
+            const token = getRelayAuthTokenFromRequest(req, url);
             if (!token || token !== relayAuthToken) {
                 rejectUpgrade(socket, 401, "Unauthorized");
                 return;
@@ -548,10 +572,34 @@ export async function ensureChromeExtensionRelayServer(opts) {
             cdpClients.delete(ws);
         });
     });
-    await new Promise((resolve, reject) => {
-        server.listen(info.port, info.host, () => resolve());
-        server.once("error", reject);
-    });
+    try {
+        await new Promise((resolve, reject) => {
+            server.listen(info.port, info.host, () => resolve());
+            server.once("error", reject);
+        });
+    }
+    catch (err) {
+        if (isAddrInUseError(err) &&
+            (await probeAuthenticatedPoolBotRelay({
+                baseUrl: info.baseUrl,
+                relayAuthHeader: RELAY_AUTH_HEADER,
+                relayAuthToken,
+            }))) {
+            const existingRelay = {
+                host: info.host,
+                port: info.port,
+                baseUrl: info.baseUrl,
+                cdpWsUrl: `ws://${info.host}:${info.port}/cdp`,
+                extensionConnected: () => false,
+                stop: async () => {
+                    relayRuntimeByPort.delete(info.port);
+                },
+            };
+            relayRuntimeByPort.set(info.port, { server: existingRelay, relayAuthToken });
+            return existingRelay;
+        }
+        throw err;
+    }
     const addr = server.address();
     const port = addr?.port ?? info.port;
     const host = info.host;
@@ -563,8 +611,7 @@ export async function ensureChromeExtensionRelayServer(opts) {
         cdpWsUrl: `ws://${host}:${port}/cdp`,
         extensionConnected: () => Boolean(extensionWs),
         stop: async () => {
-            serversByPort.delete(port);
-            relayAuthByPort.delete(port);
+            relayRuntimeByPort.delete(port);
             try {
                 extensionWs?.close(1001, "server stopping");
             }
@@ -586,17 +633,15 @@ export async function ensureChromeExtensionRelayServer(opts) {
             wssCdp.close();
         },
     };
-    relayAuthByPort.set(port, relayAuthToken);
-    serversByPort.set(port, relay);
+    relayRuntimeByPort.set(port, { server: relay, relayAuthToken });
     return relay;
 }
 export async function stopChromeExtensionRelayServer(opts) {
     const info = parseBaseUrl(opts.cdpUrl);
-    const existing = serversByPort.get(info.port);
+    const existing = relayRuntimeByPort.get(info.port);
     if (!existing) {
         return false;
     }
-    await existing.stop();
-    relayAuthByPort.delete(info.port);
+    await existing.server.stop();
     return true;
 }

package/dist/browser/navigation-guard.js

@@ -0,0 +1,39 @@
+import { resolvePinnedHostnameWithPolicy, } from "../infra/net/ssrf.js";
+const NETWORK_NAVIGATION_PROTOCOLS = new Set(["http:", "https:"]);
+const SAFE_NON_NETWORK_URLS = new Set(["about:blank"]);
+function isAllowedNonNetworkNavigationUrl(parsed) {
+    // Keep non-network navigation explicit; about:blank is the only allowed bootstrap URL.
+    return SAFE_NON_NETWORK_URLS.has(parsed.href);
+}
+export class InvalidBrowserNavigationUrlError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidBrowserNavigationUrlError";
+    }
+}
+export function withBrowserNavigationPolicy(ssrfPolicy) {
+    return ssrfPolicy ? { ssrfPolicy } : {};
+}
+export async function assertBrowserNavigationAllowed(opts) {
+    const rawUrl = String(opts.url ?? "").trim();
+    if (!rawUrl) {
+        throw new InvalidBrowserNavigationUrlError("url is required");
+    }
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new InvalidBrowserNavigationUrlError(`Invalid URL: ${rawUrl}`);
+    }
+    if (!NETWORK_NAVIGATION_PROTOCOLS.has(parsed.protocol)) {
+        if (isAllowedNonNetworkNavigationUrl(parsed)) {
+            return;
+        }
+        throw new InvalidBrowserNavigationUrlError(`Navigation blocked: unsupported protocol "${parsed.protocol}"`);
+    }
+    await resolvePinnedHostnameWithPolicy(parsed.hostname, {
+        lookupFn: opts.lookupFn,
+        policy: opts.ssrfPolicy,
+    });
+}

package/dist/browser/paths.js

@@ -1,4 +1,6 @@
+import fs from "node:fs/promises";
 import path from "node:path";
+import { SafeOpenError, openFileWithinRoot } from "../infra/fs-safe.js";
 import { resolvePreferredPoolbotTmpDir } from "../infra/tmp-poolbot-dir.js";
 export const DEFAULT_BROWSER_TMP_DIR = resolvePreferredPoolbotTmpDir();
 export const DEFAULT_TRACE_DIR = DEFAULT_BROWSER_TMP_DIR;
@@ -35,3 +37,78 @@ export function resolvePathsWithinRoot(params) {
     }
     return { ok: true, paths: resolvedPaths };
 }
+export async function resolveExistingPathsWithinRoot(params) {
+    const rootDir = path.resolve(params.rootDir);
+    let rootRealPath;
+    try {
+        rootRealPath = await fs.realpath(rootDir);
+    }
+    catch {
+        // Keep historical behavior for missing roots and rely on openFileWithinRoot for final checks.
+        rootRealPath = undefined;
+    }
+    const isInRoot = (relativePath) => Boolean(relativePath) && !relativePath.startsWith("..") && !path.isAbsolute(relativePath);
+    const resolveExistingRelativePath = async (requestedPath) => {
+        const raw = requestedPath.trim();
+        const lexicalPathResult = resolvePathWithinRoot({
+            rootDir,
+            requestedPath,
+            scopeLabel: params.scopeLabel,
+        });
+        if (lexicalPathResult.ok) {
+            return {
+                ok: true,
+                relativePath: path.relative(rootDir, lexicalPathResult.path),
+                fallbackPath: lexicalPathResult.path,
+            };
+        }
+        if (!rootRealPath || !raw || !path.isAbsolute(raw)) {
+            return lexicalPathResult;
+        }
+        try {
+            const resolvedExistingPath = await fs.realpath(raw);
+            const relativePath = path.relative(rootRealPath, resolvedExistingPath);
+            if (!isInRoot(relativePath)) {
+                return lexicalPathResult;
+            }
+            return {
+                ok: true,
+                relativePath,
+                fallbackPath: resolvedExistingPath,
+            };
+        }
+        catch {
+            return lexicalPathResult;
+        }
+    };
+    const resolvedPaths = [];
+    for (const raw of params.requestedPaths) {
+        const pathResult = await resolveExistingRelativePath(raw);
+        if (!pathResult.ok) {
+            return { ok: false, error: pathResult.error };
+        }
+        let opened;
+        try {
+            opened = await openFileWithinRoot({
+                rootDir,
+                relativePath: pathResult.relativePath,
+            });
+            resolvedPaths.push(opened.realPath);
+        }
+        catch (err) {
+            if (err instanceof SafeOpenError && err.code === "not-found") {
+                // Preserve historical behavior for paths that do not exist yet.
+                resolvedPaths.push(pathResult.fallbackPath);
+                continue;
+            }
+            return {
+                ok: false,
+                error: `Invalid path: must stay within ${params.scopeLabel} and be a regular non-symlink file`,
+            };
+        }
+        finally {
+            await opened?.handle.close().catch(() => { });
+        }
+    }
+    return { ok: true, paths: resolvedPaths };
+}

package/dist/browser/profiles.js

@@ -15,8 +15,9 @@ export const CDP_PORT_RANGE_START = 18800;
 export const CDP_PORT_RANGE_END = 18899;
 export const PROFILE_NAME_REGEX = /^[a-z0-9][a-z0-9-]*$/;
 export function isValidProfileName(name) {
-    if (!name || name.length > 64)
+    if (!name || name.length > 64) {
         return false;
+    }
     return PROFILE_NAME_REGEX.test(name);
 }
 export function allocateCdpPort(usedPorts, range) {
@@ -25,17 +26,20 @@ export function allocateCdpPort(usedPorts, range) {
     if (!Number.isFinite(start) || !Number.isFinite(end) || start <= 0 || end <= 0) {
         return null;
     }
-    if (start > end)
+    if (start > end) {
         return null;
+    }
     for (let port = start; port <= end; port++) {
-        if (!usedPorts.has(port))
+        if (!usedPorts.has(port)) {
             return port;
+        }
     }
     return null;
 }
 export function getUsedPorts(profiles) {
-    if (!profiles)
+    if (!profiles) {
         return new Set();
+    }
     const used = new Set();
     for (const profile of Object.values(profiles)) {
         if (typeof profile.cdpPort === "number") {
@@ -43,8 +47,9 @@ export function getUsedPorts(profiles) {
             continue;
         }
         const rawUrl = profile.cdpUrl?.trim();
-        if (!rawUrl)
+        if (!rawUrl) {
             continue;
+        }
         try {
             const parsed = new URL(rawUrl);
             const port = parsed.port && Number.parseInt(parsed.port, 10) > 0
@@ -63,7 +68,7 @@ export function getUsedPorts(profiles) {
     return used;
 }
 export const PROFILE_COLORS = [
-    "#A855F7", // Purple (poolbot default)
+    "#FF4500", // Orange-red (poolbot default)
     "#0066CC", // Blue
     "#00AA00", // Green
     "#9933FF", // Purple
@@ -83,11 +88,11 @@ export function allocateColor(usedColors) {
     }
     // All colors used, cycle based on count
     const index = usedColors.size % PROFILE_COLORS.length;
-    // biome-ignore lint/style/noNonNullAssertion: Array is non-empty constant
     return PROFILE_COLORS[index] ?? PROFILE_COLORS[0];
 }
 export function getUsedColors(profiles) {
-    if (!profiles)
+    if (!profiles) {
         return new Set();
+    }
     return new Set(Object.values(profiles).map((p) => p.color.toUpperCase()));
 }

package/dist/browser/pw-ai-module.js

@@ -3,8 +3,9 @@ let pwAiModuleSoft = null;
 let pwAiModuleStrict = null;
 function isModuleNotFoundError(err) {
     const code = extractErrorCode(err);
-    if (code === "ERR_MODULE_NOT_FOUND")
+    if (code === "ERR_MODULE_NOT_FOUND") {
         return true;
+    }
     const msg = formatErrorMessage(err);
     return (msg.includes("Cannot find module") ||
         msg.includes("Cannot find package") ||
@@ -17,21 +18,25 @@ async function loadPwAiModule(mode) {
         return await import("./pw-ai.js");
     }
     catch (err) {
-        if (mode === "soft")
+        if (mode === "soft") {
             return null;
-        if (isModuleNotFoundError(err))
+        }
+        if (isModuleNotFoundError(err)) {
             return null;
+        }
         throw err;
     }
 }
 export async function getPwAiModule(opts) {
     const mode = opts?.mode ?? "soft";
     if (mode === "soft") {
-        if (!pwAiModuleSoft)
+        if (!pwAiModuleSoft) {
             pwAiModuleSoft = loadPwAiModule("soft");
+        }
         return await pwAiModuleSoft;
     }
-    if (!pwAiModuleStrict)
+    if (!pwAiModuleStrict) {
         pwAiModuleStrict = loadPwAiModule("strict");
+    }
     return await pwAiModuleStrict;
 }