@poolzin/pool-bot 2026.2.25 → 2026.2.26

package/dist/infra/exec-safe-bin-policy.js

@@ -31,8 +31,8 @@ function compileSafeBinProfile(fixture) {
     return {
         minPositional: fixture.minPositional,
         maxPositional: fixture.maxPositional,
-        valueFlags: toFlagSet(fixture.valueFlags),
-        blockedFlags: toFlagSet(fixture.blockedFlags),
+        allowedValueFlags: toFlagSet(fixture.allowedValueFlags),
+        deniedFlags: toFlagSet(fixture.deniedFlags),
     };
 }
 function compileSafeBinProfiles(fixtures) {
@@ -42,19 +42,8 @@ export const SAFE_BIN_GENERIC_PROFILE_FIXTURE = {};
 export const SAFE_BIN_PROFILE_FIXTURES = {
     jq: {
         maxPositional: 1,
-        valueFlags: [
-            "--arg",
-            "--argjson",
-            "--argstr",
-            "--argfile",
-            "--rawfile",
-            "--slurpfile",
-            "--from-file",
-            "--library-path",
-            "-L",
-            "-f",
-        ],
-        blockedFlags: [
+        allowedValueFlags: ["--arg", "--argjson", "--argstr"],
+        deniedFlags: [
             "--argfile",
             "--rawfile",
             "--slurpfile",
@@ -65,31 +54,29 @@ export const SAFE_BIN_PROFILE_FIXTURES = {
         ],
     },
     grep: {
-        maxPositional: 1,
-        valueFlags: [
+        // Keep grep stdin-only: pattern must come from -e/--regexp.
+        // Allowing one positional is ambiguous because -e consumes the pattern and
+        // frees the positional slot for a filename.
+        maxPositional: 0,
+        allowedValueFlags: [
             "--regexp",
-            "--file",
             "--max-count",
             "--after-context",
             "--before-context",
             "--context",
             "--devices",
-            "--directories",
             "--binary-files",
             "--exclude",
-            "--exclude-from",
             "--include",
             "--label",
             "-e",
-            "-f",
             "-m",
             "-A",
             "-B",
             "-C",
             "-D",
-            "-d",
         ],
-        blockedFlags: [
+        deniedFlags: [
             "--file",
             "--exclude-from",
             "--dereference-recursive",
@@ -103,7 +90,7 @@ export const SAFE_BIN_PROFILE_FIXTURES = {
     },
     cut: {
         maxPositional: 0,
-        valueFlags: [
+        allowedValueFlags: [
             "--bytes",
             "--characters",
             "--fields",
@@ -117,36 +104,41 @@ export const SAFE_BIN_PROFILE_FIXTURES = {
     },
     sort: {
         maxPositional: 0,
-        valueFlags: [
+        allowedValueFlags: [
             "--key",
             "--field-separator",
             "--buffer-size",
             "--temporary-directory",
-            "--compress-program",
             "--parallel",
             "--batch-size",
             "--random-source",
-            "--files0-from",
-            "--output",
             "-k",
             "-t",
             "-S",
             "-T",
-            "-o",
         ],
-        blockedFlags: ["--files0-from", "--output", "-o"],
+        // --compress-program can invoke an external executable and breaks stdin-only guarantees.
+        deniedFlags: ["--compress-program", "--files0-from", "--output", "-o"],
     },
     uniq: {
         maxPositional: 0,
-        valueFlags: ["--skip-fields", "--skip-chars", "--check-chars", "--group", "-f", "-s", "-w"],
+        allowedValueFlags: [
+            "--skip-fields",
+            "--skip-chars",
+            "--check-chars",
+            "--group",
+            "-f",
+            "-s",
+            "-w",
+        ],
     },
     head: {
         maxPositional: 0,
-        valueFlags: ["--lines", "--bytes", "-n", "-c"],
+        allowedValueFlags: ["--lines", "--bytes", "-n", "-c"],
     },
     tail: {
         maxPositional: 0,
-        valueFlags: [
+        allowedValueFlags: [
             "--lines",
             "--bytes",
             "--sleep-interval",
@@ -162,12 +154,28 @@ export const SAFE_BIN_PROFILE_FIXTURES = {
     },
     wc: {
         maxPositional: 0,
-        valueFlags: ["--files0-from"],
-        blockedFlags: ["--files0-from"],
+        deniedFlags: ["--files0-from"],
     },
 };
 export const SAFE_BIN_GENERIC_PROFILE = compileSafeBinProfile(SAFE_BIN_GENERIC_PROFILE_FIXTURE);
 export const SAFE_BIN_PROFILES = compileSafeBinProfiles(SAFE_BIN_PROFILE_FIXTURES);
+export function resolveSafeBinDeniedFlags(fixtures = SAFE_BIN_PROFILE_FIXTURES) {
+    const out = {};
+    for (const [name, fixture] of Object.entries(fixtures)) {
+        const denied = Array.from(new Set(fixture.deniedFlags ?? [])).toSorted();
+        if (denied.length > 0) {
+            out[name] = denied;
+        }
+    }
+    return out;
+}
+export function renderSafeBinDeniedFlagsDocBullets(fixtures = SAFE_BIN_PROFILE_FIXTURES) {
+    const deniedByBin = resolveSafeBinDeniedFlags(fixtures);
+    const bins = Object.keys(deniedByBin).toSorted();
+    return bins
+        .map((bin) => `- \`${bin}\`: ${deniedByBin[bin].map((flag) => `\`${flag}\``).join(", ")}`)
+        .join("\n");
+}
 function isSafeLiteralToken(value) {
     if (!value || value === "-") {
         return true;
@@ -177,25 +185,25 @@ function isSafeLiteralToken(value) {
 function isInvalidValueToken(value) {
     return !value || !isSafeLiteralToken(value);
 }
-function consumeLongOptionToken(args, index, flag, inlineValue, valueFlags, blockedFlags) {
-    if (blockedFlags.has(flag)) {
+function consumeLongOptionToken(args, index, flag, inlineValue, allowedValueFlags, deniedFlags) {
+    if (deniedFlags.has(flag)) {
         return -1;
     }
     if (inlineValue !== undefined) {
         return isSafeLiteralToken(inlineValue) ? index + 1 : -1;
     }
-    if (!valueFlags.has(flag)) {
+    if (!allowedValueFlags.has(flag)) {
         return index + 1;
     }
     return isInvalidValueToken(args[index + 1]) ? -1 : index + 2;
 }
-function consumeShortOptionClusterToken(args, index, raw, cluster, flags, valueFlags, blockedFlags) {
+function consumeShortOptionClusterToken(args, index, raw, cluster, flags, allowedValueFlags, deniedFlags) {
     for (let j = 0; j < flags.length; j += 1) {
         const flag = flags[j];
-        if (blockedFlags.has(flag)) {
+        if (deniedFlags.has(flag)) {
             return -1;
         }
-        if (!valueFlags.has(flag)) {
+        if (!allowedValueFlags.has(flag)) {
             continue;
         }
         const inlineValue = cluster.slice(j + 1);
@@ -221,8 +229,8 @@ function validatePositionalCount(positional, profile) {
     return typeof profile.maxPositional !== "number" || positional.length <= profile.maxPositional;
 }
 export function validateSafeBinArgv(args, profile) {
-    const valueFlags = profile.valueFlags ?? NO_FLAGS;
-    const blockedFlags = profile.blockedFlags ?? NO_FLAGS;
+    const allowedValueFlags = profile.allowedValueFlags ?? NO_FLAGS;
+    const deniedFlags = profile.deniedFlags ?? NO_FLAGS;
     const positional = [];
     let i = 0;
     while (i < args.length) {
@@ -252,14 +260,14 @@ export function validateSafeBinArgv(args, profile) {
             continue;
         }
         if (token.style === "long") {
-            const nextIndex = consumeLongOptionToken(args, i, token.flag, token.inlineValue, valueFlags, blockedFlags);
+            const nextIndex = consumeLongOptionToken(args, i, token.flag, token.inlineValue, allowedValueFlags, deniedFlags);
             if (nextIndex < 0) {
                 return false;
             }
             i = nextIndex;
             continue;
         }
-        const nextIndex = consumeShortOptionClusterToken(args, i, token.raw, token.cluster, token.flags, valueFlags, blockedFlags);
+        const nextIndex = consumeShortOptionClusterToken(args, i, token.raw, token.cluster, token.flags, allowedValueFlags, deniedFlags);
         if (nextIndex < 0) {
             return false;
         }

package/dist/infra/fs-safe.js

@@ -1,76 +1,108 @@
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { isNotFoundPathError, isPathInside, isSymlinkOpenError } from "./path-guards.js";
 export class SafeOpenError extends Error {
     code;
-    constructor(code, message) {
-        super(message);
+    constructor(code, message, options) {
+        super(message, options);
         this.code = code;
         this.name = "SafeOpenError";
     }
 }
-const NOT_FOUND_CODES = new Set(["ENOENT", "ENOTDIR"]);
+const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
+const OPEN_READ_FLAGS = fsConstants.O_RDONLY | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
 const ensureTrailingSep = (value) => (value.endsWith(path.sep) ? value : value + path.sep);
-const isNodeError = (err) => Boolean(err && typeof err === "object" && "code" in err);
-const isNotFoundError = (err) => isNodeError(err) && typeof err.code === "string" && NOT_FOUND_CODES.has(err.code);
-const isSymlinkOpenError = (err) => isNodeError(err) && (err.code === "ELOOP" || err.code === "EINVAL" || err.code === "ENOTSUP");
-export async function openFileWithinRoot(params) {
-    let rootReal;
-    try {
-        rootReal = await fs.realpath(params.rootDir);
-    }
-    catch (err) {
-        if (isNotFoundError(err)) {
-            throw new SafeOpenError("not-found", "root dir not found");
-        }
-        throw err;
-    }
-    const rootWithSep = ensureTrailingSep(rootReal);
-    const resolved = path.resolve(rootWithSep, params.relativePath);
-    if (!resolved.startsWith(rootWithSep)) {
-        throw new SafeOpenError("invalid-path", "path escapes root");
-    }
-    const supportsNoFollow = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
-    const flags = fsConstants.O_RDONLY | (supportsNoFollow ? fsConstants.O_NOFOLLOW : 0);
+async function openVerifiedLocalFile(filePath) {
     let handle;
     try {
-        handle = await fs.open(resolved, flags);
+        handle = await fs.open(filePath, OPEN_READ_FLAGS);
     }
     catch (err) {
-        if (isNotFoundError(err)) {
+        if (isNotFoundPathError(err)) {
             throw new SafeOpenError("not-found", "file not found");
         }
         if (isSymlinkOpenError(err)) {
-            throw new SafeOpenError("invalid-path", "symlink open blocked");
+            throw new SafeOpenError("symlink", "symlink open blocked", { cause: err });
         }
         throw err;
     }
     try {
-        const lstat = await fs.lstat(resolved).catch(() => null);
-        if (lstat?.isSymbolicLink()) {
-            throw new SafeOpenError("invalid-path", "symlink not allowed");
-        }
-        const realPath = await fs.realpath(resolved);
-        if (!realPath.startsWith(rootWithSep)) {
-            throw new SafeOpenError("invalid-path", "path escapes root");
+        const [stat, lstat] = await Promise.all([handle.stat(), fs.lstat(filePath)]);
+        if (lstat.isSymbolicLink()) {
+            throw new SafeOpenError("symlink", "symlink not allowed");
         }
-        const stat = await handle.stat();
         if (!stat.isFile()) {
-            throw new SafeOpenError("invalid-path", "not a file");
+            throw new SafeOpenError("not-file", "not a file");
         }
+        if (stat.ino !== lstat.ino || stat.dev !== lstat.dev) {
+            throw new SafeOpenError("path-mismatch", "path changed during read");
+        }
+        const realPath = await fs.realpath(filePath);
         const realStat = await fs.stat(realPath);
         if (stat.ino !== realStat.ino || stat.dev !== realStat.dev) {
-            throw new SafeOpenError("invalid-path", "path mismatch");
+            throw new SafeOpenError("path-mismatch", "path mismatch");
         }
         return { handle, realPath, stat };
     }
     catch (err) {
         await handle.close().catch(() => { });
-        if (err instanceof SafeOpenError)
+        if (err instanceof SafeOpenError) {
             throw err;
-        if (isNotFoundError(err)) {
+        }
+        if (isNotFoundPathError(err)) {
             throw new SafeOpenError("not-found", "file not found");
         }
         throw err;
     }
 }
+export async function openFileWithinRoot(params) {
+    let rootReal;
+    try {
+        rootReal = await fs.realpath(params.rootDir);
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            throw new SafeOpenError("not-found", "root dir not found");
+        }
+        throw err;
+    }
+    const rootWithSep = ensureTrailingSep(rootReal);
+    const resolved = path.resolve(rootWithSep, params.relativePath);
+    if (!isPathInside(rootWithSep, resolved)) {
+        throw new SafeOpenError("invalid-path", "path escapes root");
+    }
+    let opened;
+    try {
+        opened = await openVerifiedLocalFile(resolved);
+    }
+    catch (err) {
+        if (err instanceof SafeOpenError) {
+            if (err.code === "not-found") {
+                throw err;
+            }
+            throw new SafeOpenError("invalid-path", "path is not a regular file under root", {
+                cause: err,
+            });
+        }
+        throw err;
+    }
+    if (!isPathInside(rootWithSep, opened.realPath)) {
+        await opened.handle.close().catch(() => { });
+        throw new SafeOpenError("invalid-path", "path escapes root");
+    }
+    return opened;
+}
+export async function readLocalFileSafely(params) {
+    const opened = await openVerifiedLocalFile(params.filePath);
+    try {
+        if (params.maxBytes !== undefined && opened.stat.size > params.maxBytes) {
+            throw new SafeOpenError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${opened.stat.size})`);
+        }
+        const buffer = await opened.handle.readFile();
+        return { buffer, realPath: opened.realPath, stat: opened.stat };
+    }
+    finally {
+        await opened.handle.close().catch(() => { });
+    }
+}

package/dist/infra/gateway-lock.js

@@ -118,7 +118,7 @@ async function readLockPayload(lockPath) {
 function resolveGatewayLockPath(env) {
     const stateDir = resolveStateDir(env);
     const configPath = resolveConfigPath(env, stateDir);
-    const hash = createHash("sha1").update(configPath).digest("hex").slice(0, 8);
+    const hash = createHash("sha256").update(configPath).digest("hex").slice(0, 8);
     const lockDir = resolveGatewayLockDir();
     const lockPath = path.join(lockDir, `gateway.${hash}.lock`);
     return { lockPath, configPath };
@@ -186,7 +186,11 @@ export async function acquireGatewayLock(opts = {}) {
                         stale = Date.now() - st.mtimeMs > staleMs;
                     }
                     catch {
-                        stale = true;
+                        // On Windows or locked filesystems we may be unable to stat the
+                        // lock file even though the existing gateway is still healthy.
+                        // Treat the lock as non-stale so we keep waiting instead of
+                        // forcefully removing another gateway's lock.
+                        stale = false;
                     }
                 }
                 if (stale) {

package/dist/infra/heartbeat-wake.js

@@ -1,3 +1,4 @@
+import { isHeartbeatActionWakeReason, normalizeHeartbeatWakeReason, resolveHeartbeatReasonKind, } from "./heartbeat-reason.js";
 let handler = null;
 let handlerGeneration = 0;
 const pendingWakes = new Map();
@@ -8,34 +9,27 @@ let timerDueAt = null;
 let timerKind = null;
 const DEFAULT_COALESCE_MS = 250;
 const DEFAULT_RETRY_MS = 1_000;
-const HOOK_REASON_PREFIX = "hook:";
 const REASON_PRIORITY = {
     RETRY: 0,
     INTERVAL: 1,
     DEFAULT: 2,
     ACTION: 3,
 };
-function isActionWakeReason(reason) {
-    return reason === "manual" || reason === "exec-event" || reason.startsWith(HOOK_REASON_PREFIX);
-}
 function resolveReasonPriority(reason) {
-    if (reason === "retry") {
+    const kind = resolveHeartbeatReasonKind(reason);
+    if (kind === "retry") {
         return REASON_PRIORITY.RETRY;
     }
-    if (reason === "interval") {
+    if (kind === "interval") {
         return REASON_PRIORITY.INTERVAL;
     }
-    if (isActionWakeReason(reason)) {
+    if (isHeartbeatActionWakeReason(reason)) {
         return REASON_PRIORITY.ACTION;
     }
     return REASON_PRIORITY.DEFAULT;
 }
 function normalizeWakeReason(reason) {
-    if (typeof reason !== "string") {
-        return "requested";
-    }
-    const trimmed = reason.trim();
-    return trimmed.length > 0 ? trimmed : "requested";
+    return normalizeHeartbeatWakeReason(reason);
 }
 function normalizeWakeTarget(value) {
     const trimmed = typeof value === "string" ? value.trim() : "";

package/dist/infra/host-env-security-policy.json

@@ -0,0 +1,19 @@
+{
+    "blockedKeys": [
+        "NODE_OPTIONS",
+        "NODE_PATH",
+        "PYTHONHOME",
+        "PYTHONPATH",
+        "PERL5LIB",
+        "PERL5OPT",
+        "RUBYLIB",
+        "RUBYOPT",
+        "BASH_ENV",
+        "ENV",
+        "SHELL",
+        "GCONV_PATH",
+        "IFS",
+        "SSLKEYLOGFILE"
+    ],
+    "blockedPrefixes": ["DYLD_", "LD_", "BASH_FUNC_"]
+}

package/dist/infra/host-env-security.js

@@ -0,0 +1,66 @@
+import HOST_ENV_SECURITY_POLICY_JSON from "./host-env-security-policy.json" with { type: "json" };
+const PORTABLE_ENV_VAR_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const HOST_ENV_SECURITY_POLICY = HOST_ENV_SECURITY_POLICY_JSON;
+export const HOST_DANGEROUS_ENV_KEY_VALUES = Object.freeze(HOST_ENV_SECURITY_POLICY.blockedKeys.map((key) => key.toUpperCase()));
+export const HOST_DANGEROUS_ENV_PREFIXES = Object.freeze(HOST_ENV_SECURITY_POLICY.blockedPrefixes.map((prefix) => prefix.toUpperCase()));
+export const HOST_DANGEROUS_ENV_KEYS = new Set(HOST_DANGEROUS_ENV_KEY_VALUES);
+export function normalizeEnvVarKey(rawKey, options) {
+    const key = rawKey.trim();
+    if (!key) {
+        return null;
+    }
+    if (options?.portable && !PORTABLE_ENV_VAR_KEY.test(key)) {
+        return null;
+    }
+    return key;
+}
+export function isDangerousHostEnvVarName(rawKey) {
+    const key = normalizeEnvVarKey(rawKey);
+    if (!key) {
+        return false;
+    }
+    const upper = key.toUpperCase();
+    if (HOST_DANGEROUS_ENV_KEYS.has(upper)) {
+        return true;
+    }
+    return HOST_DANGEROUS_ENV_PREFIXES.some((prefix) => upper.startsWith(prefix));
+}
+export function sanitizeHostExecEnv(params) {
+    const baseEnv = params?.baseEnv ?? process.env;
+    const overrides = params?.overrides ?? undefined;
+    const blockPathOverrides = params?.blockPathOverrides ?? true;
+    const merged = {};
+    for (const [rawKey, value] of Object.entries(baseEnv)) {
+        if (typeof value !== "string") {
+            continue;
+        }
+        const key = normalizeEnvVarKey(rawKey, { portable: true });
+        if (!key || isDangerousHostEnvVarName(key)) {
+            continue;
+        }
+        merged[key] = value;
+    }
+    if (!overrides) {
+        return merged;
+    }
+    for (const [rawKey, value] of Object.entries(overrides)) {
+        if (typeof value !== "string") {
+            continue;
+        }
+        const key = normalizeEnvVarKey(rawKey, { portable: true });
+        if (!key) {
+            continue;
+        }
+        const upper = key.toUpperCase();
+        // PATH is part of the security boundary (command resolution + safe-bin checks). Never allow
+        // request-scoped PATH overrides from agents/gateways.
+        if (blockPathOverrides && upper === "PATH") {
+            continue;
+        }
+        if (isDangerousHostEnvVarName(upper)) {
+            continue;
+        }
+        merged[key] = value;
+    }
+    return merged;
+}