@poolzin/pool-bot 2026.3.4 → 2026.3.6

package/dist/infra/net/ssrf.js

@@ -1,6 +1,7 @@
 import { lookup as dnsLookupCb } from "node:dns";
 import { lookup as dnsLookup } from "node:dns/promises";
 import { Agent } from "undici";
+import { extractEmbeddedIpv4FromIpv6, isBlockedSpecialUseIpv4Address, isBlockedSpecialUseIpv6Address, isCanonicalDottedDecimalIPv4, isIpv4Address, isLegacyIpv4Literal, parseCanonicalIpAddress, parseLooseIpAddress, } from "../../shared/net/ip.js";
 import { normalizeHostname } from "./hostname.js";
 export class SsrFBlockedError extends Error {
     constructor(message) {
@@ -27,6 +28,14 @@ function normalizeHostnameAllowlist(values) {
         .map((value) => normalizeHostname(value))
         .filter((value) => value !== "*" && value !== "*." && value.length > 0)));
 }
+export function isPrivateNetworkAllowedByPolicy(policy) {
+    return policy?.dangerouslyAllowPrivateNetwork === true || policy?.allowPrivateNetwork === true;
+}
+function resolveIpv4SpecialUseBlockOptions(policy) {
+    return {
+        allowRfc2544BenchmarkRange: policy?.allowRfc2544BenchmarkRange === true,
+    };
+}
 function isHostnameAllowedByPattern(hostname, pattern) {
     if (pattern.startsWith("*.")) {
         const suffix = pattern.slice(2);
@@ -43,45 +52,7 @@ function matchesHostnameAllowlist(hostname, allowlist) {
     }
     return allowlist.some((pattern) => isHostnameAllowedByPattern(hostname, pattern));
 }
-function parseStrictIpv4Octet(part) {
-    if (!/^[0-9]+$/.test(part)) {
-        return null;
-    }
-    const value = Number.parseInt(part, 10);
-    if (Number.isNaN(value) || value < 0 || value > 255) {
-        return null;
-    }
-    // Accept only canonical decimal octets (no leading zeros, no alternate radices).
-    if (part !== String(value)) {
-        return null;
-    }
-    return value;
-}
-function parseIpv4(address) {
-    const parts = address.split(".");
-    if (parts.length !== 4) {
-        return null;
-    }
-    for (const part of parts) {
-        if (parseStrictIpv4Octet(part) === null) {
-            return null;
-        }
-    }
-    return parts.map((part) => Number.parseInt(part, 10));
-}
-function classifyIpv4Part(part) {
-    if (/^0x[0-9a-f]+$/i.test(part)) {
-        return "hex";
-    }
-    if (/^0x/i.test(part)) {
-        return "invalid-hex";
-    }
-    if (/^[0-9]+$/.test(part)) {
-        return "decimal";
-    }
-    return "non-numeric";
-}
-function isUnsupportedLegacyIpv4Literal(address) {
+function looksLikeUnsupportedIpv4Literal(address) {
     const parts = address.split(".");
     if (parts.length === 0 || parts.length > 4) {
         return false;
@@ -89,186 +60,12 @@ function isUnsupportedLegacyIpv4Literal(address) {
     if (parts.some((part) => part.length === 0)) {
         return true;
     }
-    const partKinds = parts.map(classifyIpv4Part);
-    if (partKinds.some((kind) => kind === "non-numeric")) {
-        return false;
-    }
-    if (partKinds.some((kind) => kind === "invalid-hex")) {
-        return true;
-    }
-    if (parts.length !== 4) {
-        return true;
-    }
-    for (const part of parts) {
-        if (/^0x/i.test(part)) {
-            return true;
-        }
-        const value = Number.parseInt(part, 10);
-        if (Number.isNaN(value) || value > 255 || part !== String(value)) {
-            return true;
-        }
-    }
-    return false;
-}
-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;
-    }
-    // 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;
-        }
-        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;
-    }
-    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 fullParts = doubleColonParts.length === 1
-        ? input.split(":")
-        : [...headParts, ...Array.from({ length: missingParts }, () => "0"), ...tailParts];
-    if (fullParts.length !== 8) {
-        return null;
-    }
-    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],
-    },
-    {
-        // ISATAP IID format: 000000ug00000000:5efe:w.x.y.z (RFC 5214 section 6.1).
-        // Match only the IID marker bits to avoid over-broad :5efe: detection.
-        matches: (hextets) => (hextets[4] & 0xfcff) === 0 && hextets[5] === 0x5efe,
-        extract: (hextets) => [hextets[6], hextets[7]],
-    },
-];
-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 ipv4ToUint(parts) {
-    const [a, b, c, d] = parts;
-    return (((a << 24) >>> 0) | (b << 16) | (c << 8) | d) >>> 0;
-}
-function ipv4RangeFromCidr(cidr) {
-    const base = ipv4ToUint(cidr.base);
-    const hostBits = 32 - cidr.prefixLength;
-    const mask = cidr.prefixLength === 0 ? 0 : (0xffffffff << hostBits) >>> 0;
-    const start = (base & mask) >>> 0;
-    const end = (start | (~mask >>> 0)) >>> 0;
-    return [start, end];
-}
-const BLOCKED_IPV4_SPECIAL_USE_CIDRS = [
-    { base: [0, 0, 0, 0], prefixLength: 8 },
-    { base: [10, 0, 0, 0], prefixLength: 8 },
-    { base: [100, 64, 0, 0], prefixLength: 10 },
-    { base: [127, 0, 0, 0], prefixLength: 8 },
-    { base: [169, 254, 0, 0], prefixLength: 16 },
-    { base: [172, 16, 0, 0], prefixLength: 12 },
-    { base: [192, 0, 0, 0], prefixLength: 24 },
-    { base: [192, 0, 2, 0], prefixLength: 24 },
-    { base: [192, 88, 99, 0], prefixLength: 24 },
-    { base: [192, 168, 0, 0], prefixLength: 16 },
-    { base: [198, 18, 0, 0], prefixLength: 15 },
-    { base: [198, 51, 100, 0], prefixLength: 24 },
-    { base: [203, 0, 113, 0], prefixLength: 24 },
-    { base: [224, 0, 0, 0], prefixLength: 4 },
-    { base: [240, 0, 0, 0], prefixLength: 4 },
-];
-const BLOCKED_IPV4_SPECIAL_USE_RANGES = BLOCKED_IPV4_SPECIAL_USE_CIDRS.map(ipv4RangeFromCidr);
-function isBlockedIpv4SpecialUse(parts) {
-    if (parts.length !== 4) {
-        return false;
-    }
-    const value = ipv4ToUint(parts);
-    for (const [start, end] of BLOCKED_IPV4_SPECIAL_USE_RANGES) {
-        if (value >= start && value <= end) {
-            return true;
-        }
-    }
-    return false;
+    // Tighten only "ipv4-ish" literals (numbers + optional 0x prefix). Hostnames like
+    // "example.com" must stay in hostname policy handling and not be treated as malformed IPs.
+    return parts.every((part) => /^[0-9]+$/.test(part) || /^0x/i.test(part));
 }
 // Returns true for private/internal and special-use non-global addresses.
-export function isPrivateIpAddress(address) {
+export function isPrivateIpAddress(address, policy) {
     let normalized = address.trim().toLowerCase();
     if (normalized.startsWith("[") && normalized.endsWith("]")) {
         normalized = normalized.slice(1, -1);
@@ -276,57 +73,29 @@ export function isPrivateIpAddress(address) {
     if (!normalized) {
         return false;
     }
-    if (normalized.includes(":")) {
-        const hextets = parseIpv6Hextets(normalized);
-        if (!hextets) {
-            // Security-critical parse failures should fail closed.
-            return true;
+    const blockOptions = resolveIpv4SpecialUseBlockOptions(policy);
+    const strictIp = parseCanonicalIpAddress(normalized);
+    if (strictIp) {
+        if (isIpv4Address(strictIp)) {
+            return isBlockedSpecialUseIpv4Address(strictIp, blockOptions);
         }
-        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) {
+        if (isBlockedSpecialUseIpv6Address(strictIp)) {
             return true;
         }
-        const embeddedIpv4 = extractIpv4FromEmbeddedIpv6(hextets);
+        const embeddedIpv4 = extractEmbeddedIpv4FromIpv6(strictIp);
         if (embeddedIpv4) {
-            return isBlockedIpv4SpecialUse(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 isBlockedSpecialUseIpv4Address(embeddedIpv4, blockOptions);
         }
         return false;
     }
-    const ipv4 = parseIpv4(normalized);
-    if (ipv4) {
-        return isBlockedIpv4SpecialUse(ipv4);
+    // Security-critical parse failures should fail closed for any malformed IPv6 literal.
+    if (normalized.includes(":") && !parseLooseIpAddress(normalized)) {
+        return true;
+    }
+    if (!isCanonicalDottedDecimalIPv4(normalized) && isLegacyIpv4Literal(normalized)) {
+        return true;
     }
-    // Reject non-canonical IPv4 literal forms (octal/hex/short/packed) by default.
-    if (isUnsupportedLegacyIpv4Literal(normalized)) {
+    if (looksLikeUnsupportedIpv4Literal(normalized)) {
         return true;
     }
     return false;
@@ -346,12 +115,27 @@ function isBlockedHostnameNormalized(normalized) {
         normalized.endsWith(".local") ||
         normalized.endsWith(".internal"));
 }
-export function isBlockedHostnameOrIp(hostname) {
+export function isBlockedHostnameOrIp(hostname, policy) {
     const normalized = normalizeHostname(hostname);
     if (!normalized) {
         return false;
     }
-    return isBlockedHostnameNormalized(normalized) || isPrivateIpAddress(normalized);
+    return isBlockedHostnameNormalized(normalized) || isPrivateIpAddress(normalized, policy);
+}
+const BLOCKED_HOST_OR_IP_MESSAGE = "Blocked hostname or private/internal/special-use IP address";
+const BLOCKED_RESOLVED_IP_MESSAGE = "Blocked: resolves to private/internal/special-use IP address";
+function assertAllowedHostOrIpOrThrow(hostnameOrIp, policy) {
+    if (isBlockedHostnameOrIp(hostnameOrIp, policy)) {
+        throw new SsrFBlockedError(BLOCKED_HOST_OR_IP_MESSAGE);
+    }
+}
+function assertAllowedResolvedAddressesOrThrow(results, policy) {
+    for (const entry of results) {
+        // Reuse the exact same host/IP classifier as the pre-DNS check to avoid drift.
+        if (isBlockedHostnameOrIp(entry.address, policy)) {
+            throw new SsrFBlockedError(BLOCKED_RESOLVED_IP_MESSAGE);
+        }
+    }
 }
 export function createPinnedLookup(params) {
     const normalizedHost = normalizeHostname(params.hostname);
@@ -392,34 +176,52 @@ export function createPinnedLookup(params) {
         cb(null, chosen.address, chosen.family);
     });
 }
+function dedupeAndPreferIpv4(results) {
+    const seen = new Set();
+    const ipv4 = [];
+    const otherFamilies = [];
+    for (const entry of results) {
+        if (seen.has(entry.address)) {
+            continue;
+        }
+        seen.add(entry.address);
+        if (entry.family === 4) {
+            ipv4.push(entry.address);
+            continue;
+        }
+        otherFamilies.push(entry.address);
+    }
+    return [...ipv4, ...otherFamilies];
+}
 export async function resolvePinnedHostnameWithPolicy(hostname, params = {}) {
     const normalized = normalizeHostname(hostname);
     if (!normalized) {
         throw new Error("Invalid hostname");
     }
-    const allowPrivateNetwork = Boolean(params.policy?.allowPrivateNetwork);
+    const allowPrivateNetwork = isPrivateNetworkAllowedByPolicy(params.policy);
     const allowedHostnames = normalizeHostnameSet(params.policy?.allowedHostnames);
     const hostnameAllowlist = normalizeHostnameAllowlist(params.policy?.hostnameAllowlist);
     const isExplicitAllowed = allowedHostnames.has(normalized);
+    const skipPrivateNetworkChecks = allowPrivateNetwork || isExplicitAllowed;
     if (!matchesHostnameAllowlist(normalized, hostnameAllowlist)) {
         throw new SsrFBlockedError(`Blocked hostname (not in allowlist): ${hostname}`);
     }
-    if (!allowPrivateNetwork && !isExplicitAllowed && isBlockedHostnameOrIp(normalized)) {
-        throw new SsrFBlockedError("Blocked hostname or private/internal/special-use IP address");
+    if (!skipPrivateNetworkChecks) {
+        // Phase 1: fail fast for literal hosts/IPs before any DNS lookup side-effects.
+        assertAllowedHostOrIpOrThrow(normalized, params.policy);
     }
     const lookupFn = params.lookupFn ?? dnsLookup;
     const results = await lookupFn(normalized, { all: true });
     if (results.length === 0) {
         throw new Error(`Unable to resolve hostname: ${hostname}`);
     }
-    if (!allowPrivateNetwork && !isExplicitAllowed) {
-        for (const entry of results) {
-            if (isPrivateIpAddress(entry.address)) {
-                throw new SsrFBlockedError("Blocked: resolves to private/internal/special-use IP address");
-            }
-        }
+    if (!skipPrivateNetworkChecks) {
+        // Phase 2: re-check DNS answers so public hostnames cannot pivot to private targets.
+        assertAllowedResolvedAddressesOrThrow(results, params.policy);
     }
-    const addresses = Array.from(new Set(results.map((entry) => entry.address)));
+    // Prefer addresses returned as IPv4 by DNS family metadata before other
+    // families so Happy Eyeballs and pinned round-robin both attempt IPv4 first.
+    const addresses = dedupeAndPreferIpv4(results);
     if (addresses.length === 0) {
         throw new Error(`Unable to resolve hostname: ${hostname}`);
     }

package/dist/infra/path-alias-guards.js

@@ -0,0 +1,21 @@
+import { BOUNDARY_PATH_ALIAS_POLICIES, resolveBoundaryPath, } from "./boundary-path.js";
+import { assertNoHardlinkedFinalPath } from "./hardlink-guards.js";
+export const PATH_ALIAS_POLICIES = BOUNDARY_PATH_ALIAS_POLICIES;
+export async function assertNoPathAliasEscape(params) {
+    const resolved = await resolveBoundaryPath({
+        absolutePath: params.absolutePath,
+        rootPath: params.rootPath,
+        boundaryLabel: params.boundaryLabel,
+        policy: params.policy,
+    });
+    const allowFinalSymlink = params.policy?.allowFinalSymlinkForUnlink === true;
+    if (allowFinalSymlink && resolved.kind === "symlink") {
+        return;
+    }
+    await assertNoHardlinkedFinalPath({
+        filePath: resolved.absolutePath,
+        root: resolved.rootPath,
+        boundaryLabel: params.boundaryLabel,
+        allowFinalHardlinkForUnlink: params.policy?.allowFinalHardlinkForUnlink,
+    });
+}

package/dist/infra/path-guards.js

@@ -1,6 +1,16 @@
 import path from "node:path";
 const NOT_FOUND_CODES = new Set(["ENOENT", "ENOTDIR"]);
 const SYMLINK_OPEN_CODES = new Set(["ELOOP", "EINVAL", "ENOTSUP"]);
+export function normalizeWindowsPathForComparison(input) {
+    let normalized = path.win32.normalize(input);
+    if (normalized.startsWith("\\\\?\\")) {
+        normalized = normalized.slice(4);
+        if (normalized.toUpperCase().startsWith("UNC\\")) {
+            normalized = `\\\\${normalized.slice(4)}`;
+        }
+    }
+    return normalized.replaceAll("/", "\\").toLowerCase();
+}
 export function isNodeError(value) {
     return Boolean(value && typeof value === "object" && "code" in value);
 }
@@ -17,7 +27,9 @@ export function isPathInside(root, target) {
     const resolvedRoot = path.resolve(root);
     const resolvedTarget = path.resolve(target);
     if (process.platform === "win32") {
-        const relative = path.win32.relative(resolvedRoot.toLowerCase(), resolvedTarget.toLowerCase());
+        const rootForCompare = normalizeWindowsPathForComparison(resolvedRoot);
+        const targetForCompare = normalizeWindowsPathForComparison(resolvedTarget);
+        const relative = path.win32.relative(rootForCompare, targetForCompare);
         return relative === "" || (!relative.startsWith("..") && !path.win32.isAbsolute(relative));
     }
     const relative = path.relative(resolvedRoot, resolvedTarget);

package/dist/infra/ports-probe.js

@@ -0,0 +1,19 @@
+import net from "node:net";
+export async function tryListenOnPort(params) {
+    const listenOptions = { port: params.port };
+    if (params.host) {
+        listenOptions.host = params.host;
+    }
+    if (typeof params.exclusive === "boolean") {
+        listenOptions.exclusive = params.exclusive;
+    }
+    await new Promise((resolve, reject) => {
+        const tester = net
+            .createServer()
+            .once("error", (err) => reject(err))
+            .once("listening", () => {
+            tester.close(() => resolve());
+        })
+            .listen(listenOptions);
+    });
+}

package/dist/infra/prototype-keys.js

@@ -0,0 +1,4 @@
+const BLOCKED_OBJECT_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+export function isBlockedObjectKey(key) {
+    return BLOCKED_OBJECT_KEYS.has(key);
+}