@poolzin/pool-bot 2026.2.20 → 2026.2.22

package/dist/infra/heartbeat-wake.js

@@ -1,61 +1,222 @@
 let handler = null;
-let pendingReason = null;
+let handlerGeneration = 0;
+const pendingWakes = new Map();
 let scheduled = false;
 let running = false;
 let timer = null;
+let timerDueAt = null;
+let timerKind = null;
 const DEFAULT_COALESCE_MS = 250;
 const DEFAULT_RETRY_MS = 1_000;
-function schedule(coalesceMs) {
-    if (timer)
+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") {
+        return REASON_PRIORITY.RETRY;
+    }
+    if (reason === "interval") {
+        return REASON_PRIORITY.INTERVAL;
+    }
+    if (isActionWakeReason(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";
+}
+function normalizeWakeTarget(value) {
+    const trimmed = typeof value === "string" ? value.trim() : "";
+    return trimmed || undefined;
+}
+function getWakeTargetKey(params) {
+    const agentId = normalizeWakeTarget(params.agentId);
+    const sessionKey = normalizeWakeTarget(params.sessionKey);
+    return `${agentId ?? ""}::${sessionKey ?? ""}`;
+}
+function queuePendingWakeReason(params) {
+    const requestedAt = params?.requestedAt ?? Date.now();
+    const normalizedReason = normalizeWakeReason(params?.reason);
+    const normalizedAgentId = normalizeWakeTarget(params?.agentId);
+    const normalizedSessionKey = normalizeWakeTarget(params?.sessionKey);
+    const wakeTargetKey = getWakeTargetKey({
+        agentId: normalizedAgentId,
+        sessionKey: normalizedSessionKey,
+    });
+    const next = {
+        reason: normalizedReason,
+        priority: resolveReasonPriority(normalizedReason),
+        requestedAt,
+        agentId: normalizedAgentId,
+        sessionKey: normalizedSessionKey,
+    };
+    const previous = pendingWakes.get(wakeTargetKey);
+    if (!previous) {
+        pendingWakes.set(wakeTargetKey, next);
         return;
+    }
+    if (next.priority > previous.priority) {
+        pendingWakes.set(wakeTargetKey, next);
+        return;
+    }
+    if (next.priority === previous.priority && next.requestedAt >= previous.requestedAt) {
+        pendingWakes.set(wakeTargetKey, next);
+    }
+}
+function schedule(coalesceMs, kind = "normal") {
+    const delay = Number.isFinite(coalesceMs) ? Math.max(0, coalesceMs) : DEFAULT_COALESCE_MS;
+    const dueAt = Date.now() + delay;
+    if (timer) {
+        // Keep retry cooldown as a hard minimum delay. This prevents the
+        // finally-path reschedule (often delay=0) from collapsing backoff.
+        if (timerKind === "retry") {
+            return;
+        }
+        // If existing timer fires sooner or at the same time, keep it.
+        if (typeof timerDueAt === "number" && timerDueAt <= dueAt) {
+            return;
+        }
+        // New request needs to fire sooner — preempt the existing timer.
+        clearTimeout(timer);
+        timer = null;
+        timerDueAt = null;
+        timerKind = null;
+    }
+    timerDueAt = dueAt;
+    timerKind = kind;
     timer = setTimeout(async () => {
         timer = null;
+        timerDueAt = null;
+        timerKind = null;
         scheduled = false;
         const active = handler;
-        if (!active)
+        if (!active) {
             return;
+        }
         if (running) {
             scheduled = true;
-            schedule(coalesceMs);
+            schedule(delay, kind);
             return;
         }
-        const reason = pendingReason;
-        pendingReason = null;
+        const pendingBatch = Array.from(pendingWakes.values());
+        pendingWakes.clear();
         running = true;
         try {
-            const res = await active({ reason: reason ?? undefined });
-            if (res.status === "skipped" && res.reason === "requests-in-flight") {
-                // The main lane is busy; retry soon.
-                pendingReason = reason ?? "retry";
-                schedule(DEFAULT_RETRY_MS);
+            for (const pendingWake of pendingBatch) {
+                const wakeOpts = {
+                    reason: pendingWake.reason ?? undefined,
+                    ...(pendingWake.agentId ? { agentId: pendingWake.agentId } : {}),
+                    ...(pendingWake.sessionKey ? { sessionKey: pendingWake.sessionKey } : {}),
+                };
+                const res = await active(wakeOpts);
+                if (res.status === "skipped" && res.reason === "requests-in-flight") {
+                    // The main lane is busy; retry this wake target soon.
+                    queuePendingWakeReason({
+                        reason: pendingWake.reason ?? "retry",
+                        agentId: pendingWake.agentId,
+                        sessionKey: pendingWake.sessionKey,
+                    });
+                    schedule(DEFAULT_RETRY_MS, "retry");
+                }
             }
         }
         catch {
             // Error is already logged by the heartbeat runner; schedule a retry.
-            pendingReason = reason ?? "retry";
-            schedule(DEFAULT_RETRY_MS);
+            for (const pendingWake of pendingBatch) {
+                queuePendingWakeReason({
+                    reason: pendingWake.reason ?? "retry",
+                    agentId: pendingWake.agentId,
+                    sessionKey: pendingWake.sessionKey,
+                });
+            }
+            schedule(DEFAULT_RETRY_MS, "retry");
         }
         finally {
             running = false;
-            if (pendingReason || scheduled)
-                schedule(coalesceMs);
+            if (pendingWakes.size > 0 || scheduled) {
+                schedule(delay, "normal");
+            }
         }
-    }, coalesceMs);
+    }, delay);
     timer.unref?.();
 }
+/**
+ * Register (or clear) the heartbeat wake handler.
+ * Returns a disposer function that clears this specific registration.
+ * Stale disposers (from previous registrations) are no-ops, preventing
+ * a race where an old runner's cleanup clears a newer runner's handler.
+ */
 export function setHeartbeatWakeHandler(next) {
+    handlerGeneration += 1;
+    const generation = handlerGeneration;
     handler = next;
-    if (handler && pendingReason) {
-        schedule(DEFAULT_COALESCE_MS);
+    if (next) {
+        // New lifecycle starting (e.g. after SIGUSR1 in-process restart).
+        // Clear any timer metadata from the previous lifecycle so stale retry
+        // cooldowns do not delay a fresh handler.
+        if (timer) {
+            clearTimeout(timer);
+        }
+        timer = null;
+        timerDueAt = null;
+        timerKind = null;
+        // Reset module-level execution state that may be stale from interrupted
+        // runs in the previous lifecycle. Without this, `running === true` from
+        // an interrupted heartbeat blocks all future schedule() attempts, and
+        // `scheduled === true` can cause spurious immediate re-runs.
+        running = false;
+        scheduled = false;
+    }
+    if (handler && pendingWakes.size > 0) {
+        schedule(DEFAULT_COALESCE_MS, "normal");
     }
+    return () => {
+        if (handlerGeneration !== generation) {
+            return;
+        }
+        if (handler !== next) {
+            return;
+        }
+        handlerGeneration += 1;
+        handler = null;
+    };
 }
 export function requestHeartbeatNow(opts) {
-    pendingReason = opts?.reason ?? pendingReason ?? "requested";
-    schedule(opts?.coalesceMs ?? DEFAULT_COALESCE_MS);
+    queuePendingWakeReason({
+        reason: opts?.reason,
+        agentId: opts?.agentId,
+        sessionKey: opts?.sessionKey,
+    });
+    schedule(opts?.coalesceMs ?? DEFAULT_COALESCE_MS, "normal");
 }
 export function hasHeartbeatWakeHandler() {
     return handler !== null;
 }
 export function hasPendingHeartbeatWake() {
-    return pendingReason !== null || Boolean(timer) || scheduled;
+    return pendingWakes.size > 0 || Boolean(timer) || scheduled;
+}
+export function resetHeartbeatWakeStateForTests() {
+    if (timer) {
+        clearTimeout(timer);
+    }
+    timer = null;
+    timerDueAt = null;
+    timerKind = null;
+    pendingWakes.clear();
+    scheduled = false;
+    running = false;
+    handlerGeneration += 1;
+    handler = null;
 }

package/dist/infra/install-source-utils.js

@@ -0,0 +1,47 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { runCommandWithTimeout } from "../process/exec.js";
+import { resolveUserPath } from "../utils.js";
+import { fileExists, resolveArchiveKind } from "./archive.js";
+export async function withTempDir(prefix, fn) {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+    try {
+        return await fn(tmpDir);
+    }
+    finally {
+        await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+export async function resolveArchiveSourcePath(archivePath) {
+    const resolved = resolveUserPath(archivePath);
+    if (!(await fileExists(resolved))) {
+        return { ok: false, error: `archive not found: ${resolved}` };
+    }
+    if (!resolveArchiveKind(resolved)) {
+        return { ok: false, error: `unsupported archive: ${resolved}` };
+    }
+    return { ok: true, path: resolved };
+}
+export async function packNpmSpecToArchive(params) {
+    const res = await runCommandWithTimeout(["npm", "pack", params.spec, "--ignore-scripts"], {
+        timeoutMs: Math.max(params.timeoutMs, 300_000),
+        cwd: params.cwd,
+        env: {
+            COREPACK_ENABLE_DOWNLOAD_PROMPT: "0",
+            NPM_CONFIG_IGNORE_SCRIPTS: "true",
+        },
+    });
+    if (res.code !== 0) {
+        return { ok: false, error: `npm pack failed: ${res.stderr.trim() || res.stdout.trim()}` };
+    }
+    const packed = (res.stdout || "")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .pop();
+    if (!packed) {
+        return { ok: false, error: "npm pack produced no archive" };
+    }
+    return { ok: true, archivePath: path.join(params.cwd, packed) };
+}

package/dist/infra/net/ssrf.js

@@ -1,27 +1,44 @@
 import { lookup as dnsLookupCb } from "node:dns";
 import { lookup as dnsLookup } from "node:dns/promises";
 import { Agent } from "undici";
+import { normalizeHostname } from "./hostname.js";
 export class SsrFBlockedError extends Error {
     constructor(message) {
         super(message);
         this.name = "SsrFBlockedError";
     }
 }
-const PRIVATE_IPV6_PREFIXES = ["fe80:", "fec0:", "fc", "fd"];
 const BLOCKED_HOSTNAMES = new Set(["localhost", "metadata.google.internal"]);
-function normalizeHostname(hostname) {
-    const normalized = hostname.trim().toLowerCase().replace(/\.$/, "");
-    if (normalized.startsWith("[") && normalized.endsWith("]")) {
-        return normalized.slice(1, -1);
-    }
-    return normalized;
-}
 function normalizeHostnameSet(values) {
     if (!values || values.length === 0) {
         return new Set();
     }
     return new Set(values.map((value) => normalizeHostname(value)).filter(Boolean));
 }
+function normalizeHostnameAllowlist(values) {
+    if (!values || values.length === 0) {
+        return [];
+    }
+    return Array.from(new Set(values
+        .map((value) => normalizeHostname(value))
+        .filter((value) => value !== "*" && value !== "*." && value.length > 0)));
+}
+function isHostnameAllowedByPattern(hostname, pattern) {
+    if (pattern.startsWith("*.")) {
+        const suffix = pattern.slice(2);
+        if (!suffix || hostname === suffix) {
+            return false;
+        }
+        return hostname.endsWith(`.${suffix}`);
+    }
+    return hostname === pattern;
+}
+function matchesHostnameAllowlist(hostname, allowlist) {
+    if (allowlist.length === 0) {
+        return true;
+    }
+    return allowlist.some((pattern) => isHostnameAllowedByPattern(hostname, pattern));
+}
 function parseIpv4(address) {
     const parts = address.split(".");
     if (parts.length !== 4) {
@@ -33,33 +50,114 @@ function parseIpv4(address) {
     }
     return numbers;
 }
-function parseIpv4FromMappedIpv6(mapped) {
-    if (mapped.includes(".")) {
-        return parseIpv4(mapped);
+function stripIpv6ZoneId(address) {
+    const index = address.indexOf("%");
+    return index >= 0 ? address.slice(0, index) : address;
+}
+function parseIpv6Hextets(address) {
+    let input = stripIpv6ZoneId(address.trim().toLowerCase());
+    if (!input) {
+        return null;
     }
-    const parts = mapped.split(":").filter(Boolean);
-    if (parts.length === 1) {
-        const value = Number.parseInt(parts[0], 16);
-        if (Number.isNaN(value) || value < 0 || value > 0xffff_ffff) {
+    // Handle IPv4-embedded IPv6 like ::ffff:127.0.0.1 by converting the tail to 2 hextets.
+    if (input.includes(".")) {
+        const lastColon = input.lastIndexOf(":");
+        if (lastColon < 0) {
+            return null;
+        }
+        const ipv4 = parseIpv4(input.slice(lastColon + 1));
+        if (!ipv4) {
             return null;
         }
-        return [(value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff];
+        const high = (ipv4[0] << 8) + ipv4[1];
+        const low = (ipv4[2] << 8) + ipv4[3];
+        input = `${input.slice(0, lastColon)}:${high.toString(16)}:${low.toString(16)}`;
+    }
+    const doubleColonParts = input.split("::");
+    if (doubleColonParts.length > 2) {
+        return null;
     }
-    if (parts.length !== 2) {
+    const headParts = doubleColonParts[0]?.length > 0 ? doubleColonParts[0].split(":").filter(Boolean) : [];
+    const tailParts = doubleColonParts.length === 2 && doubleColonParts[1]?.length > 0
+        ? doubleColonParts[1].split(":").filter(Boolean)
+        : [];
+    const missingParts = 8 - headParts.length - tailParts.length;
+    if (missingParts < 0) {
         return null;
     }
-    const high = Number.parseInt(parts[0], 16);
-    const low = Number.parseInt(parts[1], 16);
-    if (Number.isNaN(high) ||
-        Number.isNaN(low) ||
-        high < 0 ||
-        low < 0 ||
-        high > 0xffff ||
-        low > 0xffff) {
+    const fullParts = doubleColonParts.length === 1
+        ? input.split(":")
+        : [...headParts, ...Array.from({ length: missingParts }, () => "0"), ...tailParts];
+    if (fullParts.length !== 8) {
         return null;
     }
-    const value = (high << 16) + low;
-    return [(value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff];
+    const hextets = [];
+    for (const part of fullParts) {
+        if (!part) {
+            return null;
+        }
+        const value = Number.parseInt(part, 16);
+        if (Number.isNaN(value) || value < 0 || value > 0xffff) {
+            return null;
+        }
+        hextets.push(value);
+    }
+    return hextets;
+}
+function decodeIpv4FromHextets(high, low) {
+    return [(high >>> 8) & 0xff, high & 0xff, (low >>> 8) & 0xff, low & 0xff];
+}
+const EMBEDDED_IPV4_RULES = [
+    {
+        // IPv4-mapped: ::ffff:a.b.c.d and IPv4-compatible ::a.b.c.d.
+        matches: (hextets) => hextets[0] === 0 &&
+            hextets[1] === 0 &&
+            hextets[2] === 0 &&
+            hextets[3] === 0 &&
+            hextets[4] === 0 &&
+            (hextets[5] === 0xffff || hextets[5] === 0),
+        extract: (hextets) => [hextets[6], hextets[7]],
+    },
+    {
+        // NAT64 well-known prefix: 64:ff9b::/96.
+        matches: (hextets) => hextets[0] === 0x0064 &&
+            hextets[1] === 0xff9b &&
+            hextets[2] === 0 &&
+            hextets[3] === 0 &&
+            hextets[4] === 0 &&
+            hextets[5] === 0,
+        extract: (hextets) => [hextets[6], hextets[7]],
+    },
+    {
+        // NAT64 local-use prefix: 64:ff9b:1::/48.
+        matches: (hextets) => hextets[0] === 0x0064 &&
+            hextets[1] === 0xff9b &&
+            hextets[2] === 0x0001 &&
+            hextets[3] === 0 &&
+            hextets[4] === 0 &&
+            hextets[5] === 0,
+        extract: (hextets) => [hextets[6], hextets[7]],
+    },
+    {
+        // 6to4 prefix: 2002::/16 where hextets[1..2] carry IPv4.
+        matches: (hextets) => hextets[0] === 0x2002,
+        extract: (hextets) => [hextets[1], hextets[2]],
+    },
+    {
+        // Teredo prefix: 2001:0000::/32 with client IPv4 obfuscated via XOR 0xffff.
+        matches: (hextets) => hextets[0] === 0x2001 && hextets[1] === 0x0000,
+        extract: (hextets) => [hextets[6] ^ 0xffff, hextets[7] ^ 0xffff],
+    },
+];
+function extractIpv4FromEmbeddedIpv6(hextets) {
+    for (const rule of EMBEDDED_IPV4_RULES) {
+        if (!rule.matches(hextets)) {
+            continue;
+        }
+        const [high, low] = rule.extract(hextets);
+        return decodeIpv4FromHextets(high, low);
+    }
+    return null;
 }
 function isPrivateIpv4(parts) {
     const [octet1, octet2] = parts;
@@ -94,18 +192,50 @@ export function isPrivateIpAddress(address) {
     if (!normalized) {
         return false;
     }
-    if (normalized.startsWith("::ffff:")) {
-        const mapped = normalized.slice("::ffff:".length);
-        const ipv4 = parseIpv4FromMappedIpv6(mapped);
-        if (ipv4) {
-            return isPrivateIpv4(ipv4);
-        }
-    }
     if (normalized.includes(":")) {
-        if (normalized === "::" || normalized === "::1") {
+        const hextets = parseIpv6Hextets(normalized);
+        if (!hextets) {
+            // Security-critical parse failures should fail closed.
+            return true;
+        }
+        const isUnspecified = hextets[0] === 0 &&
+            hextets[1] === 0 &&
+            hextets[2] === 0 &&
+            hextets[3] === 0 &&
+            hextets[4] === 0 &&
+            hextets[5] === 0 &&
+            hextets[6] === 0 &&
+            hextets[7] === 0;
+        const isLoopback = hextets[0] === 0 &&
+            hextets[1] === 0 &&
+            hextets[2] === 0 &&
+            hextets[3] === 0 &&
+            hextets[4] === 0 &&
+            hextets[5] === 0 &&
+            hextets[6] === 0 &&
+            hextets[7] === 1;
+        if (isUnspecified || isLoopback) {
+            return true;
+        }
+        const embeddedIpv4 = extractIpv4FromEmbeddedIpv6(hextets);
+        if (embeddedIpv4) {
+            return isPrivateIpv4(embeddedIpv4);
+        }
+        // IPv6 private/internal ranges
+        // - link-local: fe80::/10
+        // - site-local (deprecated, but internal): fec0::/10
+        // - unique local: fc00::/7
+        const first = hextets[0];
+        if ((first & 0xffc0) === 0xfe80) {
+            return true;
+        }
+        if ((first & 0xffc0) === 0xfec0) {
+            return true;
+        }
+        if ((first & 0xfe00) === 0xfc00) {
             return true;
         }
-        return PRIVATE_IPV6_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+        return false;
     }
     const ipv4 = parseIpv4(normalized);
     if (!ipv4) {
@@ -171,7 +301,11 @@ export async function resolvePinnedHostnameWithPolicy(hostname, params = {}) {
     }
     const allowPrivateNetwork = Boolean(params.policy?.allowPrivateNetwork);
     const allowedHostnames = normalizeHostnameSet(params.policy?.allowedHostnames);
+    const hostnameAllowlist = normalizeHostnameAllowlist(params.policy?.hostnameAllowlist);
     const isExplicitAllowed = allowedHostnames.has(normalized);
+    if (!matchesHostnameAllowlist(normalized, hostnameAllowlist)) {
+        throw new SsrFBlockedError(`Blocked hostname (not in allowlist): ${hostname}`);
+    }
     if (!allowPrivateNetwork && !isExplicitAllowed) {
         if (isBlockedHostname(normalized)) {
             throw new SsrFBlockedError(`Blocked hostname: ${hostname}`);