@spinabot/brigade 0.1.2 → 1.0.1

package/dist/infra/net/dns-pinning.js

@@ -0,0 +1,128 @@
+/**
+ * DNS-pinned dispatcher for SSRF-guarded fetch.
+ *
+ * The basic SSRF guard resolves a hostname's IP, checks it against the
+ * refuse list, and then hands the request off to `fetch`. There's a
+ * window between those two events: a hostile DNS server can return a
+ * public IP to the guard, then a private IP to the socket. This is the
+ * classic DNS-rebinding TOCTOU attack.
+ *
+ * To close it, we pre-resolve the hostname ourselves, pick the answers
+ * that PASS the SSRF check, and force the actual TCP connect to use one
+ * of THOSE EXACT IPs via undici's `Agent.connect.lookup` hook. The Host
+ * header still reads as the original hostname so TLS SNI + cert
+ * validation keep working.
+ *
+ * The `lookup` callback must match `dns.lookup`'s contract — when
+ * `opts.all === true`, we return an array of `{address, family}`
+ * objects; otherwise we return a single triple. Earlier revisions
+ * returned only the single-triple shape; undici 7+ calls with
+ * `opts.all: true` and that mismatch surfaces as
+ * `Invalid IP address: undefined`.
+ */
+import { promises as dnsPromises } from "node:dns";
+let undiciP = null;
+async function loadUndici() {
+    if (!undiciP) {
+        undiciP = import("undici").catch((err) => {
+            undiciP = null;
+            throw err;
+        });
+    }
+    return undiciP;
+}
+/**
+ * Resolve the hostname → list of A/AAAA records. Throws on resolution failure.
+ */
+export async function resolveAll(hostname) {
+    return await dnsPromises.lookup(hostname, { all: true });
+}
+/**
+ * Build a per-call undici Agent that locks the TCP connect to one of the
+ * pre-resolved + SSRF-vetted IPs, regardless of what the system resolver
+ * says at connect time.
+ */
+export async function createPinnedDispatcher(args) {
+    const { Agent } = await loadUndici();
+    const normalizedHost = args.hostname.toLowerCase();
+    let rrIndex = 0;
+    return new Agent({
+        connect: {
+            lookup: ((host, options, callback) => {
+                // Re-resolve any host that isn't our pinned one via the
+                // system resolver. This covers redirects to other hosts —
+                // the outer guard will re-pin per hop, but undici's
+                // internal connection-pool reuse can ask `lookup` for the
+                // proxy host too. Falling back to the system resolver
+                // keeps those cases working.
+                const target = (host ?? "").toLowerCase();
+                if (target && target !== normalizedHost) {
+                    import("node:dns").then(({ lookup }) => {
+                        // Mirror the same shape the caller asked for.
+                        if (options?.all) {
+                            lookup(host, { all: true }, (err, addrs) => callback(err, addrs));
+                        }
+                        else {
+                            const family = options?.family;
+                            lookup(host, family ? { family } : {}, (err, address, fam) => callback(err, address, fam));
+                        }
+                    });
+                    return;
+                }
+                // Filter by requested family if the caller specified one.
+                const wantedFamily = options?.family;
+                const candidates = wantedFamily
+                    ? args.pinned.filter((p) => p.family === wantedFamily)
+                    : args.pinned;
+                if (candidates.length === 0) {
+                    callback(Object.assign(new Error("no usable pinned address"), { code: "ENOTFOUND" }));
+                    return;
+                }
+                if (options?.all) {
+                    callback(null, candidates.map((p) => ({ address: p.address, family: p.family })));
+                    return;
+                }
+                // Round-robin if multiple are present, mirroring system DNS.
+                const chosen = candidates[rrIndex % candidates.length];
+                rrIndex += 1;
+                callback(null, chosen.address, chosen.family);
+            }),
+        },
+    });
+}
+/**
+ * One-shot helper: resolve, classify, keep every record that passes the
+ * SSRF check, and return a pinned dispatcher. Returns `null` when no
+ * resolved address passes (caller refuses the fetch).
+ */
+export async function buildPinnedDispatcherForHostname(args) {
+    const records = await resolveAll(args.hostname);
+    const safe = [];
+    for (const r of records) {
+        const family = r.family === 6 ? 6 : 4;
+        const reason = args.classifyAddress(r.address, family);
+        if (reason)
+            continue;
+        safe.push({ address: r.address, family });
+    }
+    if (safe.length === 0)
+        return null;
+    const dispatcher = await createPinnedDispatcher({
+        hostname: args.hostname,
+        pinned: safe,
+    });
+    return { dispatcher, addresses: safe };
+}
+/**
+ * Lazy-load undici's `fetch` — kept separate from the dispatcher so
+ * callers can do `fetch(url, { dispatcher })` using the SAME undici
+ * version the dispatcher was built from. Mixing Node's bundled
+ * `globalThis.fetch` with an externally-imported undici Agent
+ * triggers "invalid onRequestStart method" because the interceptor
+ * protocol drifts across versions.
+ */
+export async function undiciFetch(input, init) {
+    const undici = await loadUndici();
+    return (await undici.fetch(input, init));
+}
+//# sourceMappingURL=dns-pinning.js.map

package/dist/infra/net/dns-pinning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dns-pinning.js","sourceRoot":"","sources":["../../../src/infra/net/dns-pinning.ts"],"names":[],"mappings":"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"}

package/dist/infra/net/fetch-guard.d.ts

@@ -0,0 +1,85 @@
+/**
+ * SSRF guard + manual redirect loop for outbound web fetches.
+ *
+ * Why this exists: Brigade runs LLM-controllable URLs through `fetch`.
+ * Without a guard, a model can be tricked into hitting `http://169.254.169.254/`
+ * (cloud metadata) or `http://localhost:1234/` (developer service) and
+ * leaking credentials. The guard:
+ *
+ *   1. Parses the URL — rejects non-http(s), malformed
+ *   2. Classifies the hostname/IP — rejects loopback, RFC1918, link-local,
+ *      `.local`, `.internal`, cloud-metadata, IPv6 ULA/link-local, etc.
+ *   3. Drives the request with `redirect: "manual"` and re-checks every hop
+ *      so a 301 → `http://10.0.0.1/` can't bypass the initial check
+ *   4. Strips `Authorization` + `Cookie` on cross-origin redirects so a
+ *      redirect to attacker.com can't exfiltrate creds
+ *
+ * Lifted in shape from the upstream reference. Brigade ships this in v1 —
+ * SSRF is one of the cheapest-to-write, highest-impact security gates.
+ */
+/** Default redirect cap — matches the upstream reference. */
+export declare const DEFAULT_MAX_REDIRECTS = 3;
+/** Custom error thrown when an SSRF gate rejects a URL or resolved IP. */
+export declare class SsrfBlockedError extends Error {
+    readonly url: string;
+    readonly reason: string;
+    constructor(url: string, reason: string);
+}
+/** Custom error thrown when a redirect loop / cycle / cap-exceed is hit. */
+export declare class RedirectError extends Error {
+    readonly url: string;
+    constructor(url: string, reason: string);
+}
+/**
+ * Refuse-fast hostname check — runs BEFORE DNS resolution. Catches the
+ * obvious cases (literal `localhost`, IP-in-hostname, forbidden suffix)
+ * so we don't even spend a DNS round-trip.
+ */
+export declare function classifyHostnameSync(hostname: string): string | null;
+/**
+ * Full SSRF check — sync hostname classify + DNS resolution + re-classify
+ * every resolved A/AAAA record. A hostname like `attacker.com` passing
+ * the sync check can still resolve to a private IP (`10.0.0.1`) and the
+ * DNS-rebinding variant needs to be caught after resolution.
+ *
+ * Both happy-paths and rejections are explicit: returns `null` when the
+ * URL is safe, returns an `SsrfBlockedError`-shaped reason string when
+ * not. Caller throws.
+ */
+export declare function classifyUrlForSsrf(rawUrl: string): Promise<string | null>;
+export interface GuardedFetchOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: RequestInit["body"];
+    maxRedirects?: number;
+    timeoutMs?: number;
+    /** Signal from the caller (e.g. agent turn cancel). Combined with the timeout signal. */
+    signal?: AbortSignal;
+    /** When set, retry transient failures (429 / 5xx / network) with exp-backoff. */
+    retry?: {
+        maxAttempts?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        onRetry?: (info: {
+            attempt: number;
+            delayMs: number;
+            reason: string;
+        }) => void;
+    };
+}
+/**
+ * Run an HTTP request with the SSRF guard active and a manual redirect
+ * loop. Every hop is SSRF-checked; `Authorization`/`Cookie` headers are
+ * stripped when the redirect crosses origins; the timeout signal is
+ * combined with the caller's signal so either side can cancel.
+ *
+ * Returns the final `Response` (status 2xx/3xx/4xx/5xx — caller handles
+ * status). Throws `SsrfBlockedError` on guard rejection, `RedirectError`
+ * on cycle/cap-exceed, or whatever `fetch` throws on network error.
+ */
+export declare function guardedFetch(rawUrl: string, opts?: GuardedFetchOptions): Promise<{
+    response: Response;
+    finalUrl: string;
+    redirectChain: string[];
+}>;
+//# sourceMappingURL=fetch-guard.d.ts.map

package/dist/infra/net/fetch-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-guard.d.ts","sourceRoot":"","sources":["../../../src/infra/net/fetch-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,6DAA6D;AAC7D,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,0EAA0E;AAC1E,qBAAa,gBAAiB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAMvC;AAED,4EAA4E;AAC5E,qBAAa,aAAc,SAAQ,KAAK;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBACT,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAKvC;AA8GD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmBpE;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA+B/E;AAED,MAAM,WAAW,mBAAmB;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,iFAAiF;IACjF,KAAK,CAAC,EAAE;QACP,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,KAAK,IAAI,CAAC;KAC/E,CAAC;CACF;AAKD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CACjC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,mBAAwB,GAC5B,OAAO,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA8J5E"}

package/dist/infra/net/fetch-guard.js

@@ -0,0 +1,439 @@
+/**
+ * SSRF guard + manual redirect loop for outbound web fetches.
+ *
+ * Why this exists: Brigade runs LLM-controllable URLs through `fetch`.
+ * Without a guard, a model can be tricked into hitting `http://169.254.169.254/`
+ * (cloud metadata) or `http://localhost:1234/` (developer service) and
+ * leaking credentials. The guard:
+ *
+ *   1. Parses the URL — rejects non-http(s), malformed
+ *   2. Classifies the hostname/IP — rejects loopback, RFC1918, link-local,
+ *      `.local`, `.internal`, cloud-metadata, IPv6 ULA/link-local, etc.
+ *   3. Drives the request with `redirect: "manual"` and re-checks every hop
+ *      so a 301 → `http://10.0.0.1/` can't bypass the initial check
+ *   4. Strips `Authorization` + `Cookie` on cross-origin redirects so a
+ *      redirect to attacker.com can't exfiltrate creds
+ *
+ * Lifted in shape from the upstream reference. Brigade ships this in v1 —
+ * SSRF is one of the cheapest-to-write, highest-impact security gates.
+ */
+import { isIP, isIPv4, isIPv6 } from "node:net";
+import { promises as dnsPromises } from "node:dns";
+import { DEFAULT_TIMEOUT_SECONDS } from "../../agents/tools/web-shared.js";
+import { fetchWithRetry } from "../../agents/tools/web-retry.js";
+import { buildPinnedDispatcherForHostname, undiciFetch } from "./dns-pinning.js";
+/** Default redirect cap — matches the upstream reference. */
+export const DEFAULT_MAX_REDIRECTS = 3;
+/** Custom error thrown when an SSRF gate rejects a URL or resolved IP. */
+export class SsrfBlockedError extends Error {
+    url;
+    reason;
+    constructor(url, reason) {
+        super(`SSRF guard: refused to fetch ${url} (${reason})`);
+        this.name = "SsrfBlockedError";
+        this.url = url;
+        this.reason = reason;
+    }
+}
+/** Custom error thrown when a redirect loop / cycle / cap-exceed is hit. */
+export class RedirectError extends Error {
+    url;
+    constructor(url, reason) {
+        super(`Redirect loop: ${reason} (${url})`);
+        this.name = "RedirectError";
+        this.url = url;
+    }
+}
+/**
+ * Hostnames that are flat-out refused — cloud metadata services + the
+ * literal "localhost" variants + reserved TLDs that shouldn't escape an
+ * internal network.
+ */
+const FORBIDDEN_HOSTNAMES = new Set([
+    "localhost",
+    "localhost.localdomain",
+    "ip6-localhost",
+    "ip6-loopback",
+    "metadata.google.internal",
+    "metadata.aws.amazon.com",
+    "metadata.azure.com",
+    "169.254.169.254",
+    "fd00:ec2::254",
+]);
+/** Hostname suffixes that flag a host as private/internal. */
+const FORBIDDEN_HOSTNAME_SUFFIXES = [".local", ".internal", ".localhost"];
+/**
+ * Detect non-canonical IPv4 literals — `0177.0.0.1` (octal), `0x7f.0.0.1`
+ * (hex), `2130706433` (decimal-int), `127.1` (short). All of these resolve
+ * to `127.0.0.1` in `inet_aton` parsers but slip past a plain dotted-quad
+ * regex. We refuse them outright — a fetch URL has no business carrying a
+ * legacy form, and accepting them is a known SSRF bypass.
+ */
+function isLegacyIpv4Literal(host) {
+    // Single decimal integer that fits a 32-bit IPv4 address.
+    if (/^\d+$/.test(host) && Number(host) <= 0xFFFFFFFF && Number(host) >= 256)
+        return true;
+    const parts = host.split(".");
+    // Short forms (1-, 2-, 3-part dotted) — not canonical, refuse.
+    if (parts.length > 0 && parts.length < 4 && parts.every((p) => /^\d+$/.test(p)))
+        return true;
+    // Octal prefix (`0` + digits, length > 1) or hex prefix (`0x`).
+    for (const p of parts) {
+        if (/^0\d+$/.test(p))
+            return true;
+        if (/^0[xX][0-9a-fA-F]+$/.test(p))
+            return true;
+    }
+    return false;
+}
+/**
+ * Classify an IPv4 address. Returns a reason string when the IP is in a
+ * forbidden range, or `null` when it's safe to fetch.
+ */
+function classifyIPv4(ip) {
+    const parts = ip.split(".").map((p) => Number.parseInt(p, 10));
+    if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) {
+        return "invalid IPv4";
+    }
+    const [a, b] = parts;
+    // 0.0.0.0/8 — "this network"
+    if (a === 0)
+        return "0.0.0.0/8 unspecified";
+    // 10.0.0.0/8 — RFC1918 private
+    if (a === 10)
+        return "RFC1918 private (10/8)";
+    // 100.64.0.0/10 — CGNAT
+    if (a === 100 && b >= 64 && b <= 127)
+        return "CGNAT (100.64/10)";
+    // 127.0.0.0/8 — loopback
+    if (a === 127)
+        return "loopback (127/8)";
+    // 169.254.0.0/16 — link-local + cloud metadata
+    if (a === 169 && b === 254)
+        return "link-local / cloud-metadata (169.254/16)";
+    // 172.16.0.0/12 — RFC1918 private
+    if (a === 172 && b >= 16 && b <= 31)
+        return "RFC1918 private (172.16/12)";
+    // 192.168.0.0/16 — RFC1918 private
+    if (a === 192 && b === 168)
+        return "RFC1918 private (192.168/16)";
+    // 192.0.0.0/24 — IANA reserved
+    if (a === 192 && b === 0)
+        return "IANA reserved (192.0.0/24)";
+    // 224.0.0.0/4 — multicast
+    if (a >= 224 && a <= 239)
+        return "multicast (224.0.0.0/4)";
+    // 240.0.0.0/4 — reserved
+    if (a >= 240)
+        return "reserved (240.0.0.0/4)";
+    return null;
+}
+/**
+ * Classify an IPv6 address. Returns a reason string when the IP is in a
+ * forbidden range, or `null` when it's safe. Conservative — when in doubt
+ * we refuse.
+ */
+function classifyIPv6(ip) {
+    // Strip zone identifier (`fe80::1%eth0`) before classifying — the
+    // address itself is what we judge; zone routes locally only.
+    const noZone = ip.split("%", 1)[0] ?? ip;
+    const lower = noZone.toLowerCase();
+    // ::1 — loopback
+    if (lower === "::1" || lower === "::ffff:127.0.0.1")
+        return "IPv6 loopback";
+    // :: — unspecified
+    if (lower === "::")
+        return "IPv6 unspecified";
+    // fc00::/7 — Unique-Local (ULA)
+    if (lower.startsWith("fc") || lower.startsWith("fd"))
+        return "IPv6 ULA (fc00::/7)";
+    // fe80::/10 — link-local
+    if (lower.startsWith("fe8") || lower.startsWith("fe9") || lower.startsWith("fea") || lower.startsWith("feb")) {
+        return "IPv6 link-local (fe80::/10)";
+    }
+    // fec0::/10 — deprecated site-local. Some networks still use it
+    // internally; treat as private and refuse.
+    if (lower.startsWith("fec") || lower.startsWith("fed") || lower.startsWith("fee") || lower.startsWith("fef")) {
+        return "IPv6 site-local (fec0::/10, deprecated)";
+    }
+    // ::ffff:0:0/96 — IPv4-mapped — re-classify the embedded v4
+    const mapped = lower.match(/^::ffff:([0-9.]+)$/);
+    if (mapped) {
+        const inner = classifyIPv4(mapped[1] ?? "");
+        if (inner)
+            return `IPv4-mapped IPv6 → ${inner}`;
+    }
+    return null;
+}
+/**
+ * Refuse-fast hostname check — runs BEFORE DNS resolution. Catches the
+ * obvious cases (literal `localhost`, IP-in-hostname, forbidden suffix)
+ * so we don't even spend a DNS round-trip.
+ */
+export function classifyHostnameSync(hostname) {
+    const host = hostname.toLowerCase();
+    if (!host)
+        return "empty hostname";
+    if (FORBIDDEN_HOSTNAMES.has(host))
+        return `forbidden hostname (${host})`;
+    for (const suffix of FORBIDDEN_HOSTNAME_SUFFIXES) {
+        if (host.endsWith(suffix))
+            return `forbidden hostname suffix (${suffix})`;
+    }
+    // Strip brackets from IPv6 literals before classifying.
+    const stripped = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+    // Refuse non-canonical IPv4 (octal/hex/decimal-int/short forms) outright —
+    // these resolve to the same IP via legacy inet_aton parsers but bypass a
+    // dotted-quad sanity check.
+    if (isLegacyIpv4Literal(stripped))
+        return "legacy IPv4 literal (non-canonical form)";
+    if (isIPv4(stripped))
+        return classifyIPv4(stripped);
+    // Drop zone identifier before IPv6 classification.
+    const noZone = stripped.split("%", 1)[0] ?? stripped;
+    if (isIPv6(noZone))
+        return classifyIPv6(noZone);
+    if (isIP(stripped) === 0 && /^[\d.]+$/.test(stripped))
+        return "invalid IPv4 literal";
+    return null;
+}
+/**
+ * Full SSRF check — sync hostname classify + DNS resolution + re-classify
+ * every resolved A/AAAA record. A hostname like `attacker.com` passing
+ * the sync check can still resolve to a private IP (`10.0.0.1`) and the
+ * DNS-rebinding variant needs to be caught after resolution.
+ *
+ * Both happy-paths and rejections are explicit: returns `null` when the
+ * URL is safe, returns an `SsrfBlockedError`-shaped reason string when
+ * not. Caller throws.
+ */
+export async function classifyUrlForSsrf(rawUrl) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        return "invalid URL";
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return `forbidden protocol (${parsed.protocol})`;
+    }
+    const hostReason = classifyHostnameSync(parsed.hostname);
+    if (hostReason)
+        return hostReason;
+    // If hostname is already an IP, the sync check has already classified
+    // it — skip DNS.
+    if (isIP(parsed.hostname) !== 0)
+        return null;
+    // Resolve A + AAAA in parallel. `lookup` returns the active resolver's
+    // answer (system DNS or whatever); we treat any record in a forbidden
+    // range as a refusal. Network failure → DNS error: surface as a
+    // non-SSRF error so the caller's HTTP retry kicks in normally.
+    try {
+        const addresses = await dnsPromises.lookup(parsed.hostname, { all: true });
+        for (const a of addresses) {
+            const reason = a.family === 6 ? classifyIPv6(a.address) : classifyIPv4(a.address);
+            if (reason)
+                return `${parsed.hostname} resolves to ${a.address}: ${reason}`;
+        }
+    }
+    catch {
+        // DNS failure isn't an SSRF block — let the fetch attempt fail
+        // naturally so the model sees "could not resolve" instead of "SSRF".
+        return null;
+    }
+    return null;
+}
+/** Headers stripped on cross-origin redirects to prevent credential leakage. */
+const SENSITIVE_HEADERS = ["authorization", "cookie", "proxy-authorization"];
+/**
+ * Run an HTTP request with the SSRF guard active and a manual redirect
+ * loop. Every hop is SSRF-checked; `Authorization`/`Cookie` headers are
+ * stripped when the redirect crosses origins; the timeout signal is
+ * combined with the caller's signal so either side can cancel.
+ *
+ * Returns the final `Response` (status 2xx/3xx/4xx/5xx — caller handles
+ * status). Throws `SsrfBlockedError` on guard rejection, `RedirectError`
+ * on cycle/cap-exceed, or whatever `fetch` throws on network error.
+ */
+export async function guardedFetch(rawUrl, opts = {}) {
+    const maxRedirects = opts.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_SECONDS * 1_000;
+    const timeoutController = new AbortController();
+    const timeoutTimer = setTimeout(() => timeoutController.abort(new Error("timeout")), timeoutMs);
+    timeoutTimer.unref?.();
+    const signal = mergeSignals([opts.signal, timeoutController.signal]);
+    const visited = new Set();
+    const chain = [];
+    let currentUrl = rawUrl;
+    let currentMethod = (opts.method ?? "GET").toUpperCase();
+    let currentBody = opts.body;
+    let currentHeaders = { ...(opts.headers ?? {}) };
+    try {
+        for (let hop = 0; hop <= maxRedirects; hop += 1) {
+            if (visited.has(currentUrl)) {
+                throw new RedirectError(currentUrl, "cycle detected");
+            }
+            visited.add(currentUrl);
+            chain.push(currentUrl);
+            const ssrfReason = await classifyUrlForSsrf(currentUrl);
+            if (ssrfReason)
+                throw new SsrfBlockedError(currentUrl, ssrfReason);
+            // DNS pinning: pre-resolve + classify every A/AAAA record;
+            // build a per-hop undici Agent whose `connect.lookup` only
+            // returns the addresses that passed. This closes the TOCTOU
+            // window where a hostile DNS server flips records between
+            // our `classifyUrlForSsrf` check and the socket connect.
+            //
+            // Skip when the URL already names an IP literal (nothing to
+            // rebind). On DNS failure that's NOT an SSRF rejection, fall
+            // through to plain fetch so the model sees the natural
+            // "could not resolve" error.
+            let pinnedDispatcher;
+            const parsedNow = new URL(currentUrl);
+            if (isIP(parsedNow.hostname) === 0) {
+                try {
+                    const pinned = await buildPinnedDispatcherForHostname({
+                        hostname: parsedNow.hostname,
+                        classifyAddress: (addr, family) => family === 6 ? classifyIPv6(addr) : classifyIPv4(addr),
+                    });
+                    if (!pinned) {
+                        throw new SsrfBlockedError(currentUrl, "all resolved IPs failed SSRF check");
+                    }
+                    pinnedDispatcher = pinned.dispatcher;
+                }
+                catch (err) {
+                    if (err instanceof SsrfBlockedError)
+                        throw err;
+                    pinnedDispatcher = undefined;
+                }
+            }
+            // When the caller opts in, retry transient 429/5xx with exp-backoff.
+            // We retry the SAME hop (no re-classify of redirect chain) — the
+            // SSRF check already passed at this URL.
+            //
+            // Dispatcher path: must use undici's OWN `fetch` (not Node's
+            // bundled `globalThis.fetch`), because the interceptor protocol
+            // drifts between bundled-undici and externally-imported undici
+            // — that mismatch surfaces as "invalid onRequestStart method"
+            // when an external Agent is passed to the global fetch.
+            const doFetch = () => {
+                const init = {
+                    method: currentMethod,
+                    headers: currentHeaders,
+                    body: currentBody ?? undefined,
+                    redirect: "manual",
+                    signal,
+                };
+                if (pinnedDispatcher) {
+                    // Cast through `unknown` then a permissive `RequestInit` —
+                    // Node-bundled `undici-types` and the externally-imported
+                    // `undici` ship near-identical but not-quite-compatible
+                    // `Dispatcher` types (FormData / Readable variance). We
+                    // treat dispatcher opaquely at the type level; the runtime
+                    // contract is exercised by tests.
+                    return undiciFetch(currentUrl, {
+                        ...init,
+                        dispatcher: pinnedDispatcher,
+                    });
+                }
+                return fetch(currentUrl, init);
+            };
+            const response = opts.retry
+                ? await fetchWithRetry(doFetch, { ...opts.retry, signal })
+                : await doFetch();
+            // Non-redirect: we're done. Caller handles the status.
+            if (response.status < 300 || response.status >= 400 || response.status === 304) {
+                return { response, finalUrl: currentUrl, redirectChain: chain };
+            }
+            const location = response.headers.get("location");
+            if (!location) {
+                // Per RFC, a 3xx without Location is malformed. Treating it as
+                // success would silently send the model an empty body, hiding
+                // the upstream's broken redirect. Fail loudly.
+                throw new RedirectError(currentUrl, `3xx ${response.status} without Location header`);
+            }
+            // Resolve the redirect target relative to the current URL.
+            const nextUrl = (() => {
+                try {
+                    return new URL(location, currentUrl).toString();
+                }
+                catch {
+                    return null;
+                }
+            })();
+            if (!nextUrl)
+                throw new RedirectError(currentUrl, `malformed Location: ${location}`);
+            if (hop === maxRedirects) {
+                throw new RedirectError(nextUrl, `exceeded ${maxRedirects} redirects`);
+            }
+            const prevOrigin = new URL(currentUrl).origin;
+            const nextOrigin = new URL(nextUrl).origin;
+            const crossOrigin = prevOrigin !== nextOrigin;
+            // 303 forces GET; 301/302 historically convert POST→GET; 307/308
+            // preserve the method. Bodies are dropped on any method change.
+            // Additionally, on a cross-origin 307/308 we drop the body even
+            // though method is preserved — the source body may carry secrets
+            // (auth tokens, session blobs) that shouldn't be sent to the new
+            // origin.
+            let nextMethod = currentMethod;
+            let nextBody = currentBody;
+            if (response.status === 303) {
+                nextMethod = "GET";
+                nextBody = null;
+            }
+            else if ((response.status === 301 || response.status === 302) && currentMethod !== "GET" && currentMethod !== "HEAD") {
+                nextMethod = "GET";
+                nextBody = null;
+            }
+            else if ((response.status === 307 || response.status === 308) && crossOrigin) {
+                nextBody = null;
+            }
+            // Cross-origin redirects strip sensitive headers so a redirect
+            // to attacker.com can't see the original Authorization header.
+            let nextHeaders = currentHeaders;
+            if (crossOrigin) {
+                nextHeaders = {};
+                for (const [k, v] of Object.entries(currentHeaders)) {
+                    if (!SENSITIVE_HEADERS.includes(k.toLowerCase()))
+                        nextHeaders[k] = v;
+                }
+            }
+            currentUrl = nextUrl;
+            currentMethod = nextMethod;
+            currentBody = nextBody;
+            currentHeaders = nextHeaders;
+        }
+        // Loop body always returns or throws; unreachable.
+        throw new RedirectError(currentUrl, "redirect loop did not terminate");
+    }
+    finally {
+        clearTimeout(timeoutTimer);
+    }
+}
+/**
+ * Merge multiple `AbortSignal`s into one that aborts when ANY input aborts.
+ * Returns `undefined` when all inputs are undefined (no signal).
+ */
+function mergeSignals(signals) {
+    const real = signals.filter((s) => s !== undefined);
+    if (real.length === 0)
+        return undefined;
+    if (real.length === 1)
+        return real[0];
+    // Node 22 has AbortSignal.any; older falls back to manual wiring.
+    const anyFn = AbortSignal.any;
+    if (typeof anyFn === "function")
+        return anyFn.call(AbortSignal, real);
+    const ctl = new AbortController();
+    const handler = (e) => ctl.abort(e);
+    for (const s of real) {
+        if (s.aborted) {
+            ctl.abort(s.reason);
+            break;
+        }
+        s.addEventListener("abort", () => handler(s.reason), { once: true });
+    }
+    return ctl.signal;
+}
+//# sourceMappingURL=fetch-guard.js.map