@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/infra/heartbeat-runner.js

@@ -17,10 +17,11 @@ import { getQueueSize } from "../process/command-queue.js";
 import { normalizeAgentId, toAgentStoreSessionKey } from "../routing/session-key.js";
 import { defaultRuntime } from "../runtime.js";
 import { escapeRegExp } from "../utils.js";
-import { formatErrorMessage } from "./errors.js";
+import { formatErrorMessage, hasErrnoCode } from "./errors.js";
 import { isWithinActiveHours } from "./heartbeat-active-hours.js";
 import { buildCronEventPrompt, isCronSystemEvent, isExecCompletionEvent, } from "./heartbeat-events-filter.js";
 import { emitHeartbeatEvent, resolveIndicatorType } from "./heartbeat-events.js";
+import { resolveHeartbeatReasonKind } from "./heartbeat-reason.js";
 import { resolveHeartbeatVisibility } from "./heartbeat-visibility.js";
 import { requestHeartbeatNow, setHeartbeatWakeHandler, } from "./heartbeat-wake.js";
 import { deliverOutboundPayloads } from "./outbound/deliver.js";
@@ -322,6 +323,56 @@ function normalizeHeartbeatReply(payload, responsePrefix, ackMaxChars) {
     }
     return { shouldSkip: false, text: finalText, hasMedia };
 }
+function resolveHeartbeatReasonFlags(reason) {
+    const reasonKind = resolveHeartbeatReasonKind(reason);
+    return {
+        isExecEventReason: reasonKind === "exec-event",
+        isCronEventReason: reasonKind === "cron",
+        isWakeReason: reasonKind === "wake" || reasonKind === "hook",
+    };
+}
+async function resolveHeartbeatPreflight(params) {
+    const reasonFlags = resolveHeartbeatReasonFlags(params.reason);
+    const session = resolveHeartbeatSession(params.cfg, params.agentId, params.heartbeat, params.forcedSessionKey);
+    const pendingEventEntries = peekSystemEventEntries(session.sessionKey);
+    const hasTaggedCronEvents = pendingEventEntries.some((event) => event.contextKey?.startsWith("cron:"));
+    const shouldInspectPendingEvents = reasonFlags.isExecEventReason || reasonFlags.isCronEventReason || hasTaggedCronEvents;
+    const shouldBypassFileGates = reasonFlags.isExecEventReason ||
+        reasonFlags.isCronEventReason ||
+        reasonFlags.isWakeReason ||
+        hasTaggedCronEvents;
+    const basePreflight = {
+        ...reasonFlags,
+        session,
+        pendingEventEntries,
+        hasTaggedCronEvents,
+        shouldInspectPendingEvents,
+    };
+    if (shouldBypassFileGates) {
+        return basePreflight;
+    }
+    const workspaceDir = resolveAgentWorkspaceDir(params.cfg, params.agentId);
+    const heartbeatFilePath = path.join(workspaceDir, DEFAULT_HEARTBEAT_FILENAME);
+    try {
+        const heartbeatFileContent = await fs.readFile(heartbeatFilePath, "utf-8");
+        if (isHeartbeatContentEffectivelyEmpty(heartbeatFileContent)) {
+            return {
+                ...basePreflight,
+                skipReason: "empty-heartbeat-file",
+            };
+        }
+    }
+    catch (err) {
+        if (hasErrnoCode(err, "ENOENT")) {
+            // Missing HEARTBEAT.md is intentional in some setups (for example, when
+            // heartbeat instructions live outside the file), so keep the run active.
+            // The heartbeat prompt already says "if it exists".
+            return basePreflight;
+        }
+        // For other read errors, proceed with heartbeat as before.
+    }
+    return basePreflight;
+}
 export async function runHeartbeatOnce(opts) {
     const cfg = opts.cfg ?? loadConfig();
     const agentId = normalizeAgentId(opts.agentId ?? resolveDefaultAgentId(cfg));
@@ -343,34 +394,24 @@ export async function runHeartbeatOnce(opts) {
     if (queueSize > 0) {
         return { status: "skipped", reason: "requests-in-flight" };
     }
-    // Skip heartbeat if HEARTBEAT.md exists but has no actionable content.
-    // This saves API calls/costs when the file is effectively empty (only comments/headers).
-    // EXCEPTION: Don't skip for exec events, cron events, or explicit wake requests -
-    // they have pending system events to process regardless of HEARTBEAT.md content.
-    const isExecEventReason = opts.reason === "exec-event";
-    const isCronEventReason = Boolean(opts.reason?.startsWith("cron:"));
-    const isWakeReason = opts.reason === "wake" || Boolean(opts.reason?.startsWith("hook:"));
-    const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);
-    const heartbeatFilePath = path.join(workspaceDir, DEFAULT_HEARTBEAT_FILENAME);
-    try {
-        const heartbeatFileContent = await fs.readFile(heartbeatFilePath, "utf-8");
-        if (isHeartbeatContentEffectivelyEmpty(heartbeatFileContent) &&
-            !isExecEventReason &&
-            !isCronEventReason &&
-            !isWakeReason) {
-            emitHeartbeatEvent({
-                status: "skipped",
-                reason: "empty-heartbeat-file",
-                durationMs: Date.now() - startedAt,
-            });
-            return { status: "skipped", reason: "empty-heartbeat-file" };
-        }
-    }
-    catch {
-        // File doesn't exist or can't be read - proceed with heartbeat.
-        // The LLM prompt says "if it exists" so this is expected behavior.
+    // Preflight centralizes trigger classification, event inspection, and HEARTBEAT.md gating.
+    const preflight = await resolveHeartbeatPreflight({
+        cfg,
+        agentId,
+        heartbeat,
+        forcedSessionKey: opts.sessionKey,
+        reason: opts.reason,
+    });
+    if (preflight.skipReason) {
+        emitHeartbeatEvent({
+            status: "skipped",
+            reason: preflight.skipReason,
+            durationMs: Date.now() - startedAt,
+        });
+        return { status: "skipped", reason: preflight.skipReason };
     }
-    const { entry, sessionKey, storePath } = resolveHeartbeatSession(cfg, agentId, heartbeat, opts.sessionKey);
+    const { entry, sessionKey, storePath } = preflight.session;
+    const { isCronEventReason, pendingEventEntries } = preflight;
     const previousUpdatedAt = entry?.updatedAt;
     const delivery = resolveHeartbeatDeliveryTarget({ cfg, entry, heartbeat });
     const heartbeatAccountId = heartbeat?.accountId?.trim();
@@ -402,10 +443,7 @@ export async function runHeartbeatOnce(opts) {
     // Check if this is an exec event or cron event with pending system events.
     // If so, use a specialized prompt that instructs the model to relay the result
     // instead of the standard heartbeat prompt with "reply HEARTBEAT_OK".
-    const isExecEvent = opts.reason === "exec-event";
-    const pendingEventEntries = peekSystemEventEntries(sessionKey);
-    const hasTaggedCronEvents = pendingEventEntries.some((event) => event.contextKey?.startsWith("cron:"));
-    const shouldInspectPendingEvents = isExecEvent || isCronEventReason || hasTaggedCronEvents;
+    const shouldInspectPendingEvents = preflight.shouldInspectPendingEvents;
     const pendingEvents = shouldInspectPendingEvents
         ? pendingEventEntries.map((event) => event.text)
         : [];
@@ -459,6 +497,7 @@ export async function runHeartbeatOnce(opts) {
             channel: delivery.channel,
             to: delivery.to,
             accountId: delivery.accountId,
+            threadId: delivery.threadId,
             payloads: [{ text: heartbeatOkText }],
             agentId,
             deps: opts.deps,
@@ -635,6 +674,7 @@ export async function runHeartbeatOnce(opts) {
             to: delivery.to,
             accountId: deliveryAccountId,
             agentId,
+            threadId: delivery.threadId,
             payloads: [
                 ...reasoningPayloads,
                 ...(shouldSkipMain

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;
+}

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

@@ -23,8 +23,86 @@ export async function resolveArchiveSourcePath(archivePath) {
     }
     return { ok: true, path: resolved };
 }
+function toOptionalString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function parseResolvedSpecFromId(id) {
+    const at = id.lastIndexOf("@");
+    if (at <= 0 || at >= id.length - 1) {
+        return undefined;
+    }
+    const name = id.slice(0, at).trim();
+    const version = id.slice(at + 1).trim();
+    if (!name || !version) {
+        return undefined;
+    }
+    return `${name}@${version}`;
+}
+function normalizeNpmPackEntry(entry) {
+    if (!entry || typeof entry !== "object") {
+        return null;
+    }
+    const rec = entry;
+    const name = toOptionalString(rec.name);
+    const version = toOptionalString(rec.version);
+    const id = toOptionalString(rec.id);
+    const resolvedSpec = (name && version ? `${name}@${version}` : undefined) ??
+        (id ? parseResolvedSpecFromId(id) : undefined);
+    return {
+        filename: toOptionalString(rec.filename),
+        metadata: {
+            name,
+            version,
+            resolvedSpec,
+            integrity: toOptionalString(rec.integrity),
+            shasum: toOptionalString(rec.shasum),
+        },
+    };
+}
+function parseNpmPackJsonOutput(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const candidates = [trimmed];
+    const arrayStart = trimmed.indexOf("[");
+    if (arrayStart > 0) {
+        candidates.push(trimmed.slice(arrayStart));
+    }
+    for (const candidate of candidates) {
+        let parsed;
+        try {
+            parsed = JSON.parse(candidate);
+        }
+        catch {
+            continue;
+        }
+        const entries = Array.isArray(parsed) ? parsed : [parsed];
+        let fallback = null;
+        for (let i = entries.length - 1; i >= 0; i -= 1) {
+            const normalized = normalizeNpmPackEntry(entries[i]);
+            if (!normalized) {
+                continue;
+            }
+            if (!fallback) {
+                fallback = normalized;
+            }
+            if (normalized.filename) {
+                return normalized;
+            }
+        }
+        if (fallback) {
+            return fallback;
+        }
+    }
+    return null;
+}
 export async function packNpmSpecToArchive(params) {
-    const res = await runCommandWithTimeout(["npm", "pack", params.spec, "--ignore-scripts"], {
+    const res = await runCommandWithTimeout(["npm", "pack", params.spec, "--ignore-scripts", "--json"], {
         timeoutMs: Math.max(params.timeoutMs, 300_000),
         cwd: params.cwd,
         env: {
@@ -35,13 +113,19 @@ export async function packNpmSpecToArchive(params) {
     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();
+    const parsedJson = parseNpmPackJsonOutput(res.stdout || "");
+    const packed = parsedJson?.filename ??
+        (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) };
+    return {
+        ok: true,
+        archivePath: path.join(params.cwd, packed),
+        metadata: parsedJson?.metadata ?? {},
+    };
 }

package/dist/infra/net/ssrf.js

@@ -8,7 +8,11 @@ export class SsrFBlockedError extends Error {
         this.name = "SsrFBlockedError";
     }
 }
-const BLOCKED_HOSTNAMES = new Set(["localhost", "metadata.google.internal"]);
+const BLOCKED_HOSTNAMES = new Set([
+    "localhost",
+    "localhost.localdomain",
+    "metadata.google.internal",
+]);
 function normalizeHostnameSet(values) {
     if (!values || values.length === 0) {
         return new Set();
@@ -39,16 +43,72 @@ 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;
     }
-    const numbers = parts.map((part) => Number.parseInt(part, 10));
-    if (numbers.some((value) => Number.isNaN(value) || value < 0 || value > 255)) {
-        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) {
+    const parts = address.split(".");
+    if (parts.length === 0 || parts.length > 4) {
+        return false;
+    }
+    if (parts.some((part) => part.length === 0)) {
+        return true;
+    }
+    const partKinds = parts.map(classifyIpv4Part);
+    if (partKinds.some((kind) => kind === "non-numeric")) {
+        return false;
     }
-    return numbers;
+    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("%");
@@ -148,6 +208,12 @@ const EMBEDDED_IPV4_RULES = [
         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) {
@@ -159,31 +225,49 @@ function extractIpv4FromEmbeddedIpv6(hextets) {
     }
     return null;
 }
-function isPrivateIpv4(parts) {
-    const [octet1, octet2] = parts;
-    if (octet1 === 0) {
-        return true;
-    }
-    if (octet1 === 10) {
-        return true;
-    }
-    if (octet1 === 127) {
-        return true;
-    }
-    if (octet1 === 169 && octet2 === 254) {
-        return true;
-    }
-    if (octet1 === 172 && octet2 >= 16 && octet2 <= 31) {
-        return true;
-    }
-    if (octet1 === 192 && octet2 === 168) {
-        return true;
+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;
     }
-    if (octet1 === 100 && octet2 >= 64 && octet2 <= 127) {
-        return true;
+    const value = ipv4ToUint(parts);
+    for (const [start, end] of BLOCKED_IPV4_SPECIAL_USE_RANGES) {
+        if (value >= start && value <= end) {
+            return true;
+        }
     }
     return false;
 }
+// Returns true for private/internal and special-use non-global addresses.
 export function isPrivateIpAddress(address) {
     let normalized = address.trim().toLowerCase();
     if (normalized.startsWith("[") && normalized.endsWith("]")) {
@@ -219,7 +303,7 @@ export function isPrivateIpAddress(address) {
         }
         const embeddedIpv4 = extractIpv4FromEmbeddedIpv6(hextets);
         if (embeddedIpv4) {
-            return isPrivateIpv4(embeddedIpv4);
+            return isBlockedIpv4SpecialUse(embeddedIpv4);
         }
         // IPv6 private/internal ranges
         // - link-local: fe80::/10
@@ -238,16 +322,23 @@ export function isPrivateIpAddress(address) {
         return false;
     }
     const ipv4 = parseIpv4(normalized);
-    if (!ipv4) {
-        return false;
+    if (ipv4) {
+        return isBlockedIpv4SpecialUse(ipv4);
     }
-    return isPrivateIpv4(ipv4);
+    // Reject non-canonical IPv4 literal forms (octal/hex/short/packed) by default.
+    if (isUnsupportedLegacyIpv4Literal(normalized)) {
+        return true;
+    }
+    return false;
 }
 export function isBlockedHostname(hostname) {
     const normalized = normalizeHostname(hostname);
     if (!normalized) {
         return false;
     }
+    return isBlockedHostnameNormalized(normalized);
+}
+function isBlockedHostnameNormalized(normalized) {
     if (BLOCKED_HOSTNAMES.has(normalized)) {
         return true;
     }
@@ -255,6 +346,13 @@ export function isBlockedHostname(hostname) {
         normalized.endsWith(".local") ||
         normalized.endsWith(".internal"));
 }
+export function isBlockedHostnameOrIp(hostname) {
+    const normalized = normalizeHostname(hostname);
+    if (!normalized) {
+        return false;
+    }
+    return isBlockedHostnameNormalized(normalized) || isPrivateIpAddress(normalized);
+}
 export function createPinnedLookup(params) {
     const normalizedHost = normalizeHostname(params.hostname);
     const fallback = params.fallback ?? dnsLookupCb;
@@ -306,13 +404,8 @@ export async function resolvePinnedHostnameWithPolicy(hostname, params = {}) {
     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}`);
-        }
-        if (isPrivateIpAddress(normalized)) {
-            throw new SsrFBlockedError("Blocked: private/internal IP address");
-        }
+    if (!allowPrivateNetwork && !isExplicitAllowed && isBlockedHostnameOrIp(normalized)) {
+        throw new SsrFBlockedError("Blocked hostname or private/internal/special-use IP address");
     }
     const lookupFn = params.lookupFn ?? dnsLookup;
     const results = await lookupFn(normalized, { all: true });
@@ -322,7 +415,7 @@ export async function resolvePinnedHostnameWithPolicy(hostname, params = {}) {
     if (!allowPrivateNetwork && !isExplicitAllowed) {
         for (const entry of results) {
             if (isPrivateIpAddress(entry.address)) {
-                throw new SsrFBlockedError("Blocked: resolves to private/internal IP address");
+                throw new SsrFBlockedError("Blocked: resolves to private/internal/special-use IP address");
             }
         }
     }