@kyaki/witness 0.1.0

package/src/pollination.ts

@@ -0,0 +1,229 @@
+/**
+ * pollination.ts — relying-party STH pollination (Phase 6).
+ *
+ * The one sound defense against a TARGETED split-view — an operator that shows a victim a
+ * root B@n it never shows any honest witness. The monitor cannot see B (it never enters the
+ * witnessed world), and quorum verification over the operator's OWN co-signature bundle can
+ * be cherry-picked by the operator. Pollination closes it by having the VICTIM pull each
+ * trusted witness's co-signature DIRECTLY (operator-independent, SSRF-safe) and run the
+ * audited `verifyWitnessedTreeHead`, FAIL-CLOSED: unless >= quorum distinct trusted witnesses
+ * co-signed the EXACT served root, the victim refuses.
+ *
+ * Why it is sound: a witness co-signature is WITNESS-signed over (logId, treeSize, rootHash),
+ * so neither a MITM nor the operator can forge "W endorsed B". The victim asks the witnesses
+ * themselves, so the operator cannot turn suppression into a false ACCEPT — if it withholds the
+ * witness responses the victim simply FAILS CLOSED (detection of the contradiction requires the
+ * victim to actually reach >= quorum honest witnesses directly). It does NOT defeat COLLUSION
+ * (>= quorum witnesses lying together — quorum >= 2 under disjoint control remains the only
+ * in-band lever). And SPENDS NEVER DEPEND ON WITNESS LIVENESS: pollination is an ADDITIONAL
+ * relying-party fail-closed check layered on quorum, not the kernel's safety gate; an
+ * unreachable witness is reported and simply does not count toward the quorum.
+ *
+ * DISPLAY ↔ VERDICT (load-bearing, do not weaken): `confirmed` is taken SOLELY from the audited
+ * `verifyWitnessedTreeHead` — never a hand-ported quorum rule. The display fields
+ * (matched/revoked/unreachable) are a MIRROR of that verdict's own accounting, gated on the
+ * SAME pre-count refusals the verifier applies (the policy.logId pin, the quorum-validity bound,
+ * and STH authenticity). So `matched` can never be reported under a basis the verdict already
+ * rejected — `matched >= quorum` if and only if `confirmed` (see the gate below). The two were
+ * once allowed to diverge on a malformed policy (a §4 over-claim caught by the Phase-6 review);
+ * that is now closed by computing the display under the verifier's exact gates.
+ */
+import {
+  verifyWitnessedTreeHead, verifyWitnessCosignature, verifySignedTreeHead,
+  type SignedTreeHead, type WitnessCosignature, type WitnessedTreeHead, type WitnessPolicy,
+} from '@kyaki/core';
+import { boundedFanOut } from './fan-out.js';
+import { safeFetchJson, type SsrfPolicy } from './ssrf.js';
+
+/** A trusted witness a relying party pulls a co-signature from. Satisfied in-process by
+ *  `DurableWitness` (it has `id` + `endorsement`) and over the wire by `HttpPollinationSource`.
+ *  `id` SHOULD be set (both built-in implementations set it): a source may only contribute the
+ *  endorsement of the witness it claims to be — see the identity binding in `pollinate`. */
+export interface PollinationSource {
+  /** The witness DID — must be in the relying party's `trustedWitnesses` to count, and must
+   *  match the `witnessId` of the co-signature this source returns. */
+  readonly id?: string;
+  /** This witness's endorsement (its endorsed STH + its own co-signature) at `treeSize`.
+   *  MUST be self-bounding (its own timeout) for a hard liveness guarantee; `pollinate` also
+   *  applies a backstop per-source timeout so a hung source can never wedge the whole call. */
+  endorsement(treeSize?: number): Promise<{ sth: SignedTreeHead; cosignature: WitnessCosignature } | undefined>;
+}
+
+export interface PollinationResult {
+  /** Fail-closed verdict: did >= quorum DISTINCT trusted, non-revoked witnesses co-sign the
+   *  EXACT (logId, treeSize, rootHash) served? Driven SOLELY by `verifyWitnessedTreeHead`.
+   *
+   *  What `confirmed=true` MEANS — and does NOT: a quorum of the relying party's OWN trusted set
+   *  co-signed the exact served root. It is NOT proof of honesty: COLLUSION of >= quorum trusted
+   *  witnesses is out of scope (raise the bar only with quorum >= 2 under disjoint control, or
+   *  threshold signatures). `confirmed=false` with witnesses `unreachable` is INCONCLUSIVE
+   *  (a liveness gap), not proof of a fork — distinguish it from `confirmed=false` with all
+   *  witnesses reached (corroboration genuinely refused). */
+  confirmed: boolean;
+  /** Distinct trusted, NON-REVOKED witnesses whose co-signature authentically binds the served head.
+   *  Counted exactly as the verdict counts — a revoked witness is never included, and on any input
+   *  the verdict rejects pre-count (wrong operator / invalid quorum / non-authentic STH) `matched`
+   *  is 0, so it can never contradict `confirmed` (e.g. show matched >= quorum while confirmed=false). */
+  matched: number;
+  /** Size of the trusted-witness set (the ORIGINAL allowlist; `revoked` is reported separately so the
+   *  UI can render "N of T, R revoked" transparently rather than silently shrinking the denominator). */
+  total: number;
+  /** Distinct trusted witnesses whose co-signature bound the head but were NOT counted because they
+   *  are revoked (Phase 7 v1b) — a transparency signal, never part of the quorum. */
+  revoked: number;
+  /** Distinct TRUSTED witnesses that could not be reached and did not end up matched or revoked —
+   *  a LIVENESS signal (they never count toward the quorum). Keyed to the trusted set and excludes
+   *  any witness already counted, so matched + revoked + unreachable <= total (a coherent partition);
+   *  a non-trusted source that failed is not surfaced here (it could never have counted anyway). */
+  unreachable: string[];
+}
+
+/** Optional knobs for `pollinate`. */
+export interface PollinateOptions {
+  /** Backstop timeout (ms) applied to EACH source pull, so a hung source (e.g. an in-process
+   *  durable witness blocked on a store lock) can never wedge the whole call — the "worst-case
+   *  one timeout" liveness guarantee is a property of `pollinate`, not delegated to the source
+   *  type. Set above an HTTP source's own SSRF timeout so it only bites a genuinely hung source.
+   *  Default 10000. */
+  sourceTimeoutMs?: number;
+}
+
+const DEFAULT_SOURCE_TIMEOUT_MS = 10_000;
+
+/** Resolve `p`, or reject with POLLINATION_SOURCE_TIMEOUT after `ms`. The underlying work may
+ *  continue (an in-process op is not cancellable) but its result is ignored — what is bounded is
+ *  how long the caller WAITS, which is the liveness property that matters. ms<=0 disables the bound. */
+function withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
+  if (!Number.isFinite(ms) || ms <= 0) return p;
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('POLLINATION_SOURCE_TIMEOUT')), ms);
+    p.then(
+      (v) => { clearTimeout(timer); resolve(v); },
+      (e) => { clearTimeout(timer); reject(e); },
+    );
+  });
+}
+
+/**
+ * Pollinate: pull each trusted witness's co-signature at the served head's size and confirm,
+ * fail-closed, that >= quorum distinct trusted witnesses co-signed the EXACT (logId, treeSize,
+ * rootHash) the relying party was served. The verdict is the audited `verifyWitnessedTreeHead`
+ * (never a hand-ported quorum rule). An unreachable witness is reported and never makes the
+ * check pass. Liveness-independent: the fan-out is concurrency-bounded and per-source
+ * timeout-bounded, so neither a large pinned witness set nor a hung source can DoS the victim,
+ * and a pollination failure never blocks a spend (it is an additional relying-party check).
+ */
+export async function pollinate(
+  servedSth: SignedTreeHead,
+  sources: readonly PollinationSource[],
+  policy: WitnessPolicy,
+  opts?: PollinateOptions,
+): Promise<PollinationResult> {
+  const trusted = new Set(policy.trustedWitnesses ?? []);
+  const revoked = new Set(policy.revokedWitnesses ?? []);   // Phase 7 v1b — proven equivocators
+  const timeoutMs = opts?.sourceTimeoutMs ?? DEFAULT_SOURCE_TIMEOUT_MS;
+
+  // Guard the served size at the boundary: a non-integer/negative treeSize can only come from a
+  // malformed STH (which `verifyWitnessedTreeHead` rejects anyway) and would build a junk
+  // `?size=NaN` query. Skip the fetch entirely in that case — but STILL derive `confirmed` from
+  // the audited verifier below (never hand-decide it).
+  const validSize = Number.isInteger(servedSth.treeSize) && servedSth.treeSize >= 0;
+
+  const cosignatures: WitnessCosignature[] = [];
+  const downLabels: string[] = [];
+  if (validSize) {
+    // Pull every source with a BOUNDED in-flight cap (a large pinned set can't exhaust sockets/heap)
+    // and a per-source backstop timeout. Each branch catches its OWN failure — including a null/
+    // malformed source entry (the label is computed defensively) — so a dead source lands in
+    // `unreachable` and never rejects the whole call. Worst-case wall-clock is one timeout per batch.
+    const settled = await boundedFanOut(
+      sources,
+      async (src, i): Promise<{ cosig: WitnessCosignature } | { down: string }> => {
+        const label = src?.id ?? `witness#${i}`;
+        try {
+          const e = await withTimeout(src.endorsement(servedSth.treeSize), timeoutMs);
+          const cosig = e?.cosignature;
+          if (!cosig) return { down: label };                                   // no endorsement ⇒ cannot corroborate
+          // Bind the source's claimed identity to the co-signature it returns: a source may only
+          // ever contribute its OWN endorsement, so a single (possibly operator-controlled) endpoint
+          // cannot stand in for the quorum by replaying several witnesses' public co-signatures — the
+          // operator-INDEPENDENCE the mechanism rests on. A mismatch ⇒ this source did not return its
+          // own endorsement ⇒ treat it as no corroboration (it never counts toward quorum).
+          if (src?.id !== undefined && cosig.witnessId !== src.id) return { down: label };
+          return { cosig };
+        } catch {
+          return { down: label };                                               // transport failure / timeout ⇒ liveness
+        }
+      },
+    );
+    for (const r of settled) {
+      if (r.status !== 'fulfilled') continue;   // boundedFanOut settles per item and never throws; defensive
+      if ('cosig' in r.value) cosignatures.push(r.value.cosig);
+      else downLabels.push(r.value.down);
+    }
+  }
+
+  const wth: WitnessedTreeHead = { sth: servedSth, cosignatures };
+  const confirmed = verifyWitnessedTreeHead(wth, policy);   // the AUTHORITATIVE fail-closed verdict
+
+  // DISPLAY-NEVER-CONTRADICTS-VERDICT. The display fields must mirror EXACTLY what the verdict
+  // counts. `verifyWitnessedTreeHead` refuses BEFORE counting any endorser when the served head is
+  // not the pinned operator's authentic STH (its logId != policy.logId, or the operator signature is
+  // invalid), the trusted set is empty, or the quorum is structurally invalid. On ANY of those the
+  // honest display is "0 corroborated" — never a parallel count under a basis the verdict already
+  // rejected. Mirror those exact pre-count gates (transparency.ts verifyWitnessedTreeHead) here.
+  const quorum = policy.quorum ?? trusted.size;
+  const quorumValid = Number.isInteger(quorum) && quorum >= 1 && quorum <= trusted.size;
+  const structurallyValid =
+    validSize
+    && trusted.size > 0
+    && quorumValid
+    && servedSth.logId === policy.logId        // the policy.logId PIN — NOT the served head's own logId
+    && verifySignedTreeHead(servedSth);        // authentic operator STH (catches a forged sig over a real root)
+  if (!structurallyValid) {
+    return { confirmed, matched: 0, total: trusted.size, revoked: 0, unreachable: trustedDistinct(downLabels, trusted) };
+  }
+
+  // On the structurally-valid path these per-cosig filters are byte-identical to
+  // `verifyWitnessedTreeHead`'s (self-witness exclusion, trusted membership, exact tuple, authentic
+  // cosig, revocation skip, distinct-by-witnessId), so `endorsers.size === the verifier's count` and
+  // `matched >= quorum  <=>  confirmed`. This is a DISPLAY mirror of the verdict, never a substitute.
+  const endorsers = new Set<string>();
+  const revokedSeen = new Set<string>();        // DISTINCT revoked witnesses that bound the head (never counted)
+  for (const c of cosignatures) {
+    if (!c || c.witnessId === policy.logId) continue;   // no operator self-witness (policy.logId == servedSth.logId here)
+    if (!trusted.has(c.witnessId)) continue;
+    if (c.logId !== policy.logId || c.treeSize !== servedSth.treeSize || c.rootHash !== servedSth.rootHash) continue;
+    if (!verifyWitnessCosignature(c)) continue;
+    if (revoked.has(c.witnessId)) { revokedSeen.add(c.witnessId); continue; }   // bound the head, but NOT counted (v1b)
+    endorsers.add(c.witnessId);
+  }
+  // `unreachable`: distinct TRUSTED witnesses whose source(s) failed, EXCLUDING any that ended up
+  // matched or revoked (a witness reachable on one endpoint and down on another is NOT "unreachable").
+  // Keyed to the trusted set so matched + revoked + unreachable <= total — a coherent partition.
+  const unreachable = [...new Set(downLabels)].filter(
+    (id) => trusted.has(id) && !endorsers.has(id) && !revokedSeen.has(id),
+  );
+  return { confirmed, matched: endorsers.size, total: trusted.size, revoked: revokedSeen.size, unreachable };
+}
+
+/** Distinct TRUSTED labels from a down-source list — the `unreachable` field on a structurally
+ *  refused head (no witness can have counted, so there is nothing to exclude). */
+function trustedDistinct(labels: readonly string[], trusted: ReadonlySet<string>): string[] {
+  return [...new Set(labels)].filter((id) => trusted.has(id));
+}
+
+/** Pulls a witness's endorsement over the wire via `GET /cosig?size`, SSRF-guarded.
+ *  The load-bearing object is the returned `cosignature` (witness-signed over the exact tuple);
+ *  the returned `sth` is informational and not re-trusted by `pollinate`. */
+export class HttpPollinationSource implements PollinationSource {
+  constructor(private readonly baseUrl: string, readonly id: string, private readonly ssrf: SsrfPolicy) {}
+
+  async endorsement(treeSize?: number): Promise<{ sth: SignedTreeHead; cosignature: WitnessCosignature } | undefined> {
+    const url = treeSize === undefined ? `${this.baseUrl}/cosig` : `${this.baseUrl}/cosig?size=${treeSize}`;
+    const body = (await safeFetchJson(url, { method: 'GET' }, this.ssrf)) as
+      { sth?: SignedTreeHead | null; cosignature?: WitnessCosignature | null } | undefined;
+    if (!body?.sth || !body.cosignature) return undefined;
+    return { sth: body.sth, cosignature: body.cosignature };
+  }
+}

package/src/ssrf.ts

@@ -0,0 +1,190 @@
+/**
+ * ssrf.ts — an SSRF-safe outbound fetch for the WitnessMonitor (RULES §5.3).
+ *
+ * The monitor PULLS operator-signed STHs from witness URLs. Left unguarded, a witness
+ * base URL of `http://169.254.169.254/` (cloud metadata) or `http://localhost:5432`
+ * (an internal service) turns the monitor into a server-side request forgery primitive.
+ * §0 ranks security above correctness, so this is a build-blocking control, not a
+ * deployment afterthought. The layered defense:
+ *   1. HOST ALLOWLIST — the monitor may only connect to the hostnames of its
+ *      CONFIG-PINNED witness set; a request to any other host is refused. (The witness
+ *      set is operator-INDEPENDENT and not attacker-registerable — that is the whole
+ *      basis of the cross-party guarantee, so pinning it here is free.)
+ *   2. SCHEME — https only, unless `allowHttp` is set for loopback dev/tests.
+ *   3. NO INTERNAL TARGETS — reject IP-literal hosts in loopback/RFC1918/link-local/ULA
+ *      ranges, AND resolve hostnames and reject any answer in those ranges
+ *      (resolve-then-check defeats a DNS-rebinding allowlisted name pointing inward).
+ *   4. NO REDIRECTS — `redirect: 'error'` so a 3xx to an internal target cannot smuggle
+ *      past the checks; BODY CAP + TIMEOUT so a hostile/slow endpoint cannot exhaust
+ *      heap or wedge a polling round.
+ *
+ * Residual (documented): a TOCTOU between resolve-check and connect remains (the OS may
+ * re-resolve to a different IP). The host allowlist is the primary control; full IP
+ * pinning of the connection is the further hardening if the monitor is ever pointed at
+ * untrusted-DNS hosts. For a pinned, operator-independent witness set this is sufficient.
+ */
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+
+export interface SsrfPolicy {
+  /** Exact hostnames (lowercased) the monitor may connect to — the pinned witness set.
+   *  REQUIRED and non-empty: an empty allowlist refuses everything (fail-closed). */
+  allowHosts: string[];
+  /** Permit plain http and loopback/private targets — loopback dev & tests ONLY.
+   *  Default false ⇒ https required and every internal range is refused. */
+  allowHttp?: boolean;
+  /** Max response body bytes. Default 64 KiB (an STH/proof is well under 1 KiB). */
+  maxBytes?: number;
+  /** Per-request timeout in ms. Default 5000. */
+  timeoutMs?: number;
+}
+
+const DEFAULT_MAX_BYTES = 64 * 1024;
+const DEFAULT_TIMEOUT_MS = 5000;
+
+/** Map a pair of 16-bit hex groups (the low 32 bits of a v6 address) to dotted v4. */
+function hexPairToV4(hiHex: string, loHex: string): string {
+  const hi = parseInt(hiHex, 16), lo = parseInt(loHex, 16);
+  return `${(hi >> 8) & 255}.${hi & 255}.${(lo >> 8) & 255}.${lo & 255}`;
+}
+
+/** Is `ip` (a valid v4/v6 literal) in a loopback/private/link-local/ULA/CGNAT/NAT64 range? */
+export function isPrivateIp(ip: string): boolean {
+  const v = isIP(ip);
+  if (v === 4) {
+    const p = ip.split('.').map(Number);
+    if (p.length !== 4 || p.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true; // malformed ⇒ unsafe
+    const [a, b] = p as [number, number, number, number];
+    if (a === 10) return true;                         // 10.0.0.0/8
+    if (a === 127) return true;                        // loopback
+    if (a === 0) return true;                          // 0.0.0.0/8 unspecified
+    if (a === 169 && b === 254) return true;           // link-local
+    if (a === 172 && b >= 16 && b <= 31) return true;  // 172.16.0.0/12
+    if (a === 192 && b === 168) return true;           // 192.168.0.0/16
+    if (a === 100 && b >= 64 && b <= 127) return true; // 100.64.0.0/10 carrier-grade NAT (RFC 6598)
+    if (a === 198 && (b === 18 || b === 19)) return true; // 198.18.0.0/15 benchmarking
+    if (a >= 224) return true;                         // multicast / reserved
+    return false;
+  }
+  if (v === 6) {
+    const ip6 = ip.toLowerCase().replace(/^\[|\]$/g, '');
+    if (ip6 === '::1' || ip6 === '::') return true;                       // loopback / unspecified
+    if (ip6.startsWith('fe80')) return true;                             // link-local
+    if (ip6.startsWith('fc') || ip6.startsWith('fd')) return true;       // ULA fc00::/7
+    // IPv4-mapped (::ffff:a.b.c.d AND its hex-quad form ::ffff:7f00:1) — re-check the v4.
+    const mapped = ip6.match(/::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped) return isPrivateIp(mapped[1]!);
+    const hexMapped = ip6.match(/::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (hexMapped) return isPrivateIp(hexPairToV4(hexMapped[1]!, hexMapped[2]!));
+    // NAT64 well-known prefix (64:ff9b::/96) embeds an arbitrary v4 destination — a gateway
+    // forwards 64:ff9b::7f00:1 to 127.0.0.1, so the embedded v4 must be re-checked too.
+    const nat64Dotted = ip6.match(/^64:ff9b::(\d+\.\d+\.\d+\.\d+)$/);
+    if (nat64Dotted) return isPrivateIp(nat64Dotted[1]!);
+    const nat64Hex = ip6.match(/^64:ff9b::([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (nat64Hex) return isPrivateIp(hexPairToV4(nat64Hex[1]!, nat64Hex[2]!));
+    if (ip6 === '64:ff9b::') return true;                                // the bare NAT64 prefix
+    return false;
+  }
+  return true; // not a recognizable IP ⇒ treat as unsafe
+}
+
+/** Validate a URL against the policy; throws a named `SSRF_*` error on any violation. */
+export async function assertSafeUrl(rawUrl: string, policy: SsrfPolicy): Promise<void> {
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new Error('SSRF_INVALID_URL');
+  }
+  const allowHttp = policy.allowHttp === true;
+  if (url.protocol !== 'https:' && !(allowHttp && url.protocol === 'http:')) {
+    throw new Error(`SSRF_SCHEME_FORBIDDEN: ${url.protocol}`);
+  }
+  const host = url.hostname.toLowerCase();
+  const allow = new Set((policy.allowHosts ?? []).map((h) => h.toLowerCase()));
+  if (allow.size === 0 || !allow.has(host)) {
+    throw new Error(`SSRF_HOST_NOT_ALLOWED: ${host}`);
+  }
+  // An IP-literal host: check the literal directly.
+  if (isIP(host)) {
+    if (isPrivateIp(host) && !allowHttp) throw new Error(`SSRF_PRIVATE_IP: ${host}`);
+    return;
+  }
+  // A hostname: resolve and reject any answer in an internal range (DNS-rebinding guard).
+  if (!allowHttp) {
+    let addrs: { address: string }[];
+    try {
+      addrs = await lookup(host, { all: true });
+    } catch {
+      throw new Error(`SSRF_DNS_FAILED: ${host}`);
+    }
+    if (addrs.length === 0) throw new Error(`SSRF_DNS_EMPTY: ${host}`);
+    for (const { address } of addrs) {
+      if (isPrivateIp(address)) throw new Error(`SSRF_RESOLVES_PRIVATE: ${host} -> ${address}`);
+    }
+  }
+}
+
+/**
+ * Read a response body, aborting the moment the running byte total exceeds `maxBytes`.
+ * NEVER trusts Content-Length (a hostile/chunked endpoint omits it): the cap is enforced
+ * while STREAMING, so heap is bounded to maxBytes + one chunk regardless of the header or
+ * transfer encoding. `res.text()` would buffer the whole body BEFORE any size check — the
+ * exact DoS this avoids.
+ */
+async function readCappedText(res: Response, maxBytes: number, controller: AbortController): Promise<string> {
+  const reader = res.body?.getReader();
+  if (!reader) {                              // no stream available — still cap, never unbounded
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.length > maxBytes) throw new Error(`SSRF_BODY_TOO_LARGE: > ${maxBytes}`);
+    return buf.toString('utf8');
+  }
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        controller.abort();                   // stop the transfer immediately
+        throw new Error(`SSRF_BODY_TOO_LARGE: > ${maxBytes}`);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    try { reader.releaseLock(); } catch { /* already released on abort */ }
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+/** A fetch that enforces the SSRF policy, blocks redirects, and caps body + time.
+ *  Returns the parsed JSON body (or throws on a non-2xx / oversize / timeout). */
+export async function safeFetchJson(rawUrl: string, init: RequestInit, policy: SsrfPolicy): Promise<unknown> {
+  const maxBytes = policy.maxBytes ?? DEFAULT_MAX_BYTES;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), policy.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  try {
+    // The DNS resolve inside assertSafeUrl is NOT abortable (node:dns/promises.lookup ignores
+    // AbortSignal), so race it against the SAME timeout — otherwise a slow-resolving (but
+    // allowlisted) host blows past the per-request ceiling before fetch even starts.
+    const aborted = new Promise<never>((_, reject) => {
+      controller.signal.addEventListener('abort', () => reject(new Error('SSRF_TIMEOUT')), { once: true });
+    });
+    await Promise.race([assertSafeUrl(rawUrl, policy), aborted]);
+    const res = await fetch(rawUrl, { ...init, redirect: 'error', signal: controller.signal });
+    if (res.status === 204) return undefined;
+    if (!res.ok) throw new Error(`HTTP_${res.status}`);
+    // A declared oversized Content-Length is a cheap fast-fail; but a MISSING/zero header is
+    // "unknown size", NOT "safe" — the streaming reader enforces the real cap either way.
+    const declared = Number(res.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+      throw new Error(`SSRF_BODY_TOO_LARGE: ${declared} > ${maxBytes}`);
+    }
+    const text = await readCappedText(res, maxBytes, controller);
+    return text ? JSON.parse(text) : undefined;
+  } finally {
+    clearTimeout(timer);
+  }
+}