haechi 1.3.0 → 1.3.2

package/packages/proxy/index.mjs

@@ -4,6 +4,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { isUtf8 } from "node:buffer";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { once } from "node:events";
 import { inspectResponseStream } from "../stream-filter/index.mjs";
 
 export const DEFAULT_PROXY_PORT = 11016;
@@ -107,6 +108,19 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
   const metrics = runtime.metrics ?? noopMetrics();
   const logger = createLogger(config.logging?.format ?? "text");
 
+  // P0-CR-001 — the upstream header forward policy, derived ONCE from config.
+  // gatewayConsumedAuthorization is true whenever the gateway authenticates the
+  // CLIENT (auth.provider !== "none"): the request's Authorization is then the
+  // gateway credential Haechi consumed and must NOT be forwarded to the model
+  // upstream. With auth.provider "none" the client's Authorization is the
+  // upstream provider key and IS forwarded. extraHeaders is the operator's
+  // additive target.forwardHeaders allowlist (validated lowercase in
+  // normalizeConfig); it can only widen, never override the always-drop set.
+  const forwardPolicy = {
+    gatewayConsumedAuthorization: (config.auth?.provider ?? "none") !== "none",
+    extraHeaders: new Set(config.target?.forwardHeaders ?? [])
+  };
+
   // WS4-B backpressure: a configurable global max-in-flight ceiling. 0 (default)
   // disables it, preserving 1.1 behavior. When > 0 and the live count is at the
   // ceiling, a NEW non-exempt request is rejected 503 + Retry-After BEFORE auth
@@ -213,7 +227,8 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
       const authContext = { identity, profile, policyEngine, correlationId };
 
       const body = await readBody(request, {
-        maxBytes: config.limits.maxRequestBytes
+        maxBytes: config.limits.maxRequestBytes,
+        response
       });
       const json = parseJsonBody(body);
 
@@ -237,7 +252,7 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
 
       if (isStreamingRequest(json, routeContext)) {
         if (config.streaming.requestMode === "inspect") {
-          await handleInspectedStream({ runtime, request, response, routeContext, json, authContext, metrics });
+          await handleInspectedStream({ runtime, request, response, routeContext, json, authContext, metrics, forwardPolicy });
           return;
         }
 
@@ -254,16 +269,36 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
             blocked: false
           });
           countDecision(metrics, { routeContext, mode, decision: "forwarded" });
+          // CR2-001 — a per-request AbortController whose signal is threaded into
+          // the upstream fetch; aborting it (on a downstream client disconnect)
+          // tears down the upstream request + body so neither leaks.
+          const streamAbort = new AbortController();
           const upstreamResponse = await forward({
             upstream: config.target.upstream,
             request,
             body,
             timeoutMs: config.limits.upstreamTimeoutMs,
-            metrics
+            metrics,
+            forwardPolicy,
+            abortController: streamAbort
+          });
+          // P1-CR-003 — sanitize response headers (strip the upstream's
+          // content-encoding/content-length/transfer/hop-by-hop) on this path
+          // too: Node fetch() auto-decompressed the body, so the original
+          // compressed headers would now be wrong. P1-CR-004 — TRUE bounded
+          // streaming pass-through: pipe the upstream body to the client with a
+          // running byte cap instead of buffering the whole response.
+          response.writeHead(upstreamResponse.status, sanitizeResponseHeaders(upstreamResponse));
+          await pipeUpstreamBodyBounded({
+            upstreamResponse,
+            response,
+            request,
+            maxBytes: streamingPassThroughMaxBytes(config),
+            abortController: streamAbort,
+            logger,
+            metrics,
+            correlationId
           });
-          const { body: rawBody } = await readUpstreamBody(upstreamResponse);
-          response.writeHead(upstreamResponse.status, Object.fromEntries(upstreamResponse.headers.entries()));
-          response.end(rawBody);
           return;
         }
 
@@ -301,7 +336,8 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
         request,
         body: JSON.stringify(result.payload),
         timeoutMs: config.limits.upstreamTimeoutMs,
-        metrics
+        metrics,
+        forwardPolicy
       });
 
       const forwarded = await maybeProtectResponse({
@@ -332,10 +368,16 @@ export function createHaechiProxy({ runtime, port = DEFAULT_PROXY_PORT, host = "
         });
         metrics.increment("haechi_internal_error_total");
       }
+      // CR2-005 — an over-limit request body teardown carries `Connection: close`
+      // so the socket releases once the 413 is delivered (readBody destroys the
+      // request on response finish/close).
+      const extraHeaders = error?.errorCode === "haechi_request_body_too_large"
+        ? { connection: "close" }
+        : null;
       writeJson(response, error.statusCode ?? 500, {
         error: error.errorCode ?? "haechi_proxy_error",
         message: expected ? error.message : "Internal proxy error"
-      });
+      }, extraHeaders);
     } finally {
       const elapsedSeconds = Number(process.hrtime.bigint() - startedAt) / 1e9;
       // route label is a bounded route id (or "unknown") — never an identity/value.
@@ -633,7 +675,7 @@ async function recordAuthDenied({ runtime, routeContext, reason, correlationId =
   });
 }
 
-async function handleInspectedStream({ runtime, request, response, routeContext, json, authContext = {}, metrics = null }) {
+async function handleInspectedStream({ runtime, request, response, routeContext, json, authContext = {}, metrics = null, forwardPolicy = {} }) {
   const { haechi, config } = runtime;
   const requestMode = config.policy.mode ?? config.mode;
 
@@ -674,7 +716,8 @@ async function handleInspectedStream({ runtime, request, response, routeContext,
     request,
     body: JSON.stringify(requestResult.payload),
     timeoutMs: config.limits.upstreamTimeoutMs,
-    metrics
+    metrics,
+    forwardPolicy
   });
 
   const streamMode = config.streaming.responseMode ?? config.responseProtection.mode ?? config.policy.mode ?? config.mode;
@@ -687,7 +730,7 @@ async function handleInspectedStream({ runtime, request, response, routeContext,
     maxMatchBytes: config.streaming.maxMatchBytes
   });
 
-  response.writeHead(upstreamResponse.status, streamingResponseHeaders(upstreamResponse));
+  response.writeHead(upstreamResponse.status, sanitizeResponseHeaders(upstreamResponse));
 
   const { blocked, summary } = await inspectResponseStream({
     source: upstreamResponse.body ?? emptyAsyncIterable(),
@@ -708,13 +751,151 @@ async function handleInspectedStream({ runtime, request, response, routeContext,
   response.end();
 }
 
-function streamingResponseHeaders(upstreamResponse) {
+// P1-CR-003 — the SINGLE centralized response-header sanitizer used on EVERY
+// response path (pass-through, forwarded/unprotected, protected, streaming).
+// Node fetch() auto-decompresses gzip/br/deflate, so the upstream's original
+// content-encoding/content-length now describe the WIRE bytes Haechi no longer
+// emits — forwarding them makes a downstream client see "content-encoding: gzip"
+// on plain bytes and fail with "incorrect header check". transfer-encoding and
+// the hop-by-hop control headers (RFC 7230 §6.1) likewise describe the upstream
+// hop, not Haechi's connection to the client, so they are stripped too. A
+// correct content-length is re-set ONLY by a caller that emits a fully-buffered
+// body (transformedJsonHeaders / the buffered-body helper below); a streamed or
+// raw-piped body intentionally carries no content-length.
+const RESPONSE_HOP_BY_HOP_HEADERS = [
+  "content-encoding",
+  "content-length",
+  "transfer-encoding",
+  "connection",
+  "keep-alive",
+  "te",
+  "trailer",
+  "upgrade",
+  "proxy-authenticate"
+];
+
+function sanitizeResponseHeaders(upstreamResponse) {
   const headers = Object.fromEntries(upstreamResponse.headers.entries());
-  delete headers["content-length"];
-  delete headers["content-encoding"];
+  for (const name of RESPONSE_HOP_BY_HOP_HEADERS) {
+    delete headers[name];
+  }
   return headers;
 }
 
+// P1-CR-004 — the byte cap for the streaming pass-through path. Reuse
+// responseProtection.maxBytes (the existing hard response-size cap) so a single
+// dial governs all raw upstream-body reads; falls back to a 1 MiB default for a
+// hand-built config without responseProtection.
+function streamingPassThroughMaxBytes(config) {
+  const cap = config.responseProtection?.maxBytes;
+  return typeof cap === "number" && cap > 0 ? cap : 1048576;
+}
+
+// P1-CR-004 — TRUE bounded streaming pass-through. Pipe the upstream body to the
+// client response as it arrives (real streaming) while counting bytes; if the
+// running total exceeds maxBytes, abort: cancel the upstream reader and destroy
+// the client response so a long-lived or malicious stream cannot hold memory or
+// the connection open unbounded. Bytes already written cannot be retracted, so
+// this caps total memory/throughput, not the already-flushed prefix.
+async function pipeUpstreamBodyBounded({ upstreamResponse, response, request = null, maxBytes, abortController = null, logger = null, metrics = null, correlationId = null }) {
+  if (!upstreamResponse.body) {
+    response.end();
+    return;
+  }
+
+  const reader = upstreamResponse.body.getReader();
+  let received = 0;
+
+  // CR2-001 — a ONE-SHOT teardown on a downstream client disconnect. Without it,
+  // a parked `await once(response, "drain")` (backpressure) or a parked
+  // `await reader.read()` (no backpressure, upstream idle) never unparks after the
+  // client socket dies — neither `drain` nor `error` fires — so the async task and
+  // the upstream connection leak. On `close`/`aborted` we cancel the upstream
+  // reader (interrupts a parked read) AND abort the upstream fetch (tears down the
+  // connection); the listeners are removed on normal completion so the happy path
+  // does not leak a handle.
+  let disconnected = false;
+  // A SINGLE promise resolved by the one-shot tearDown below, so the backpressure
+  // wait can race against the disconnect WITHOUT registering a fresh `close`
+  // listener every drain cycle (which would accumulate on a sustained
+  // backpressured stream and trip MaxListenersExceededWarning).
+  let signalDisconnected;
+  const disconnectedPromise = new Promise((resolve) => {
+    signalDisconnected = resolve;
+  });
+  const tearDown = () => {
+    if (disconnected) {
+      return;
+    }
+    disconnected = true;
+    signalDisconnected();
+    void cancelReader(reader);
+    abortController?.abort();
+  };
+  const disconnectSources = [response, request].filter(Boolean);
+  for (const source of disconnectSources) {
+    source.once("close", tearDown);
+    source.once("aborted", tearDown);
+  }
+  const cleanupListeners = () => {
+    for (const source of disconnectSources) {
+      source.removeListener("close", tearDown);
+      source.removeListener("aborted", tearDown);
+    }
+  };
+
+  try {
+    while (true) {
+      if (disconnected) {
+        return;
+      }
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      received += value.byteLength;
+      if (maxBytes && received > maxBytes) {
+        // Over the cap: stop reading upstream and tear down the client write so
+        // the oversize stream is bounded (fail-closed on size).
+        void cancelReader(reader);
+        abortController?.abort();
+        metrics?.increment("haechi_response_stream_truncated_total");
+        logger?.error("proxy_stream_pass_through_too_large", {
+          correlationId,
+          maxBytes
+        });
+        if (!response.writableEnded) {
+          response.destroy();
+        }
+        return;
+      }
+      // Respect downstream backpressure: stop pulling upstream until the client
+      // socket has drained. CR2-001 — race the drain wait against `close` so a
+      // client disconnect mid-backpressure unparks the wait instead of hanging
+      // until the request timeout.
+      const ok = response.write(Buffer.from(value));
+      if (!ok && !disconnected) {
+        await Promise.race([
+          once(response, "drain"),
+          disconnectedPromise
+        ]);
+        if (disconnected || response.writableEnded || response.destroyed) {
+          return;
+        }
+      }
+    }
+    response.end();
+  } catch (error) {
+    void cancelReader(reader);
+    abortController?.abort();
+    if (!response.writableEnded) {
+      response.destroy();
+    }
+  } finally {
+    cleanupListeners();
+  }
+}
+
 function nodeResponseSink(response) {
   return {
     write(text) {
@@ -751,20 +932,42 @@ async function recordStreamDecision({ runtime, routeContext, blocked, summary, m
 }
 
 async function maybeProtectResponse({ upstreamResponse, routeContext, runtime, authContext = {}, issuedTokens = [], metrics = null }) {
-  const headers = Object.fromEntries(upstreamResponse.headers.entries());
+  // P1-CR-003 — content-encoding is read off the RAW upstream headers (before
+  // sanitation) for the compressed-response gate; the headers RETURNED to the
+  // client are always the sanitized set (no stale compression/length metadata).
+  const rawHeaders = Object.fromEntries(upstreamResponse.headers.entries());
+  const headers = sanitizeResponseHeaders(upstreamResponse);
 
   if (!runtime.config.responseProtection.enabled || !routeContext.protectResponse) {
-    const { body: rawBody } = await readUpstreamBody(upstreamResponse);
+    // P1-CR-004 — apply the same byte cap to this raw upstream-body read so an
+    // unprotected/forwarded response cannot be buffered unbounded. Fail closed
+    // (502) when the upstream body exceeds the cap.
+    const passThroughMax = streamingPassThroughMaxBytes(runtime.config);
+    const { body: rawBody, tooLarge } = await readUpstreamBody(upstreamResponse, { maxBytes: passThroughMax });
+    if (tooLarge) {
+      metrics?.increment("haechi_response_stream_truncated_total");
+      return {
+        decision: "response_unprotected_blocked",
+        status: 502,
+        headers: { "content-type": "application/json" },
+        body: Buffer.from(`${JSON.stringify({
+          error: "haechi_response_too_large",
+          reason: "response_body_too_large",
+          message: `Response body exceeds responseProtection.maxBytes (${passThroughMax})`
+        }, null, 2)}\n`)
+      };
+    }
     return {
       status: upstreamResponse.status,
-      headers,
+      // Re-set a correct content-length: this is a fully-buffered body.
+      headers: { ...headers, "content-length": String(rawBody.byteLength) },
       body: rawBody,
       decision: "forwarded"
     };
   }
 
   const responsePolicy = runtime.config.responseProtection;
-  const contentEncoding = headers["content-encoding"] ?? "";
+  const contentEncoding = rawHeaders["content-encoding"] ?? "";
   const bodyRead = await readUpstreamBody(upstreamResponse, { maxBytes: responsePolicy.maxBytes });
 
   if (bodyRead.tooLarge) {
@@ -916,14 +1119,24 @@ function restoreTokens(value, tokenValues) {
   return value;
 }
 
-async function forward({ upstream, request, body, timeoutMs = null, metrics = null }) {
+async function forward({ upstream, request, body, timeoutMs = null, metrics = null, forwardPolicy = {}, abortController = null }) {
   const target = buildUpstreamUrl({ upstream, requestUrl: request.url });
+  // CR2-001 — combine the upstream timeout with a per-request AbortController so a
+  // downstream client disconnect (which aborts `abortController`) tears down the
+  // in-flight upstream fetch + its body, instead of leaking the connection.
+  const timeoutSignal = timeoutMs ? AbortSignal.timeout(timeoutMs) : null;
+  let signal;
+  if (abortController && timeoutSignal) {
+    signal = AbortSignal.any([abortController.signal, timeoutSignal]);
+  } else {
+    signal = abortController ? abortController.signal : timeoutSignal ?? undefined;
+  }
   try {
     return await fetch(target, {
       method: request.method,
-      headers: filteredHeaders(request.headers),
+      headers: filteredHeaders(request.headers, forwardPolicy),
       body: request.method === "GET" || request.method === "HEAD" ? undefined : body,
-      signal: timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined
+      signal
     });
   } catch (error) {
     if (error?.name === "TimeoutError" || error?.name === "AbortError") {
@@ -949,25 +1162,118 @@ function buildUpstreamUrl({ upstream, requestUrl }) {
   return new URL(`${parsed.pathname}${parsed.search}`, upstream.endsWith("/") ? upstream : `${upstream}/`);
 }
 
-function filteredHeaders(headers) {
+// P0-CR-001 — DEFAULT-DROP upstream header allowlist. The client's request
+// headers cross from the local gateway trust boundary into the MODEL PROVIDER
+// boundary, so the policy is: forward ONLY a known-safe set; everything else
+// (including ambient client credentials — Cookie, Proxy-Authorization, and the
+// client's gateway Authorization) is dropped. The conditional `authorization`
+// rule is handled in filteredHeaders against the forward policy. An operator can
+// additively widen the set with `target.forwardHeaders` for an unusual upstream.
+//
+// The forwarded set is exactly the headers the OpenAI-compatible / Anthropic /
+// Gemini adapters need: the provider key headers (x-api-key, x-goog-api-key,
+// openai-organization, openai-beta), provider version/feature pins
+// (anthropic-version, anthropic-beta), and benign request metadata (accept,
+// content-type — always rewritten to application/json, user-agent,
+// accept-language). content-type is set unconditionally below so it is NOT in
+// this set.
+const FORWARD_HEADER_ALLOWLIST = new Set([
+  "x-api-key",
+  "anthropic-version",
+  "anthropic-beta",
+  "x-goog-api-key",
+  "openai-organization",
+  "openai-beta",
+  "accept",
+  "user-agent",
+  "accept-language"
+]);
+
+// ALWAYS-DROP: ambient client credentials + hop-by-hop control headers. These
+// must NEVER reach the upstream regardless of the allowlist or the operator's
+// target.forwardHeaders extension (a fail-closed denylist that wins over both).
+//   - host / content-length: rewritten/recomputed by fetch for the new request.
+//   - cookie / set-cookie / proxy-authorization: ambient client credentials.
+//   - connection / keep-alive / te / trailer / transfer-encoding / upgrade:
+//     hop-by-hop headers (RFC 7230 §6.1) that must not be tunneled end-to-end.
+const FORWARD_HEADER_DENYLIST = new Set([
+  "host",
+  "content-length",
+  "cookie",
+  "set-cookie",
+  "proxy-authorization",
+  "connection",
+  "keep-alive",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade"
+]);
+
+// `forwardPolicy` is built by createHaechiProxy from the runtime: it carries
+//   - gatewayConsumedAuthorization: true when auth.provider !== "none", i.e. the
+//     gateway authenticated the CLIENT with the request's Authorization. That
+//     header is the GATEWAY credential Haechi already consumed; forwarding it
+//     would leak a gateway secret into the model provider, so it is DROPPED.
+//     When false (auth.provider "none"), the client's Authorization is the
+//     UPSTREAM provider key (the OpenAI-compatible pass-through pattern), so it
+//     is FORWARDED.
+//   - extraHeaders: the operator's additive target.forwardHeaders allowlist
+//     (lowercase names) — never able to override the always-drop denylist.
+function filteredHeaders(headers, forwardPolicy = {}) {
+  const gatewayConsumedAuthorization = Boolean(forwardPolicy.gatewayConsumedAuthorization);
+  const extraHeaders = forwardPolicy.extraHeaders instanceof Set
+    ? forwardPolicy.extraHeaders
+    : new Set(Array.isArray(forwardPolicy.extraHeaders) ? forwardPolicy.extraHeaders : []);
+
   const next = new Headers();
   for (const [key, value] of Object.entries(headers)) {
-    if (!value || ["host", "content-length"].includes(key.toLowerCase())) {
+    if (!value) {
       continue;
     }
-    if (Array.isArray(value)) {
-      for (const item of value) {
-        next.append(key, item);
+    const name = key.toLowerCase();
+
+    // Always-drop wins over everything (credentials + hop-by-hop).
+    if (FORWARD_HEADER_DENYLIST.has(name)) {
+      continue;
+    }
+
+    // Conditional gateway-vs-upstream Authorization separation.
+    if (name === "authorization") {
+      if (gatewayConsumedAuthorization) {
+        // Gateway token Haechi already consumed — must not leak upstream.
+        continue;
       }
-    } else {
-      next.set(key, value);
+      // auth.provider "none": the client put the UPSTREAM provider key here.
+      appendHeader(next, key, value);
+      continue;
     }
+
+    // content-type is rewritten unconditionally below; skip the client's value.
+    if (name === "content-type") {
+      continue;
+    }
+
+    if (FORWARD_HEADER_ALLOWLIST.has(name) || extraHeaders.has(name)) {
+      appendHeader(next, key, value);
+    }
+    // Everything else is default-dropped (fail-closed).
   }
   next.set("content-type", "application/json");
   return next;
 }
 
-function readBody(request, { maxBytes }) {
+function appendHeader(target, key, value) {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      target.append(key, item);
+    }
+  } else {
+    target.set(key, value);
+  }
+}
+
+function readBody(request, { maxBytes, response = null }) {
   return new Promise((resolve, reject) => {
     const chunks = [];
     let received = 0;
@@ -980,6 +1286,26 @@ function readBody(request, { maxBytes }) {
       received += chunk.byteLength;
       if (received > maxBytes) {
         rejected = true;
+        // CR2-005 — stop reading and release the socket PROMPTLY instead of
+        // reading-and-discarding the rest of the upload until Node's finite
+        // requestTimeout. pause() halts the flowing read immediately (no further
+        // data is consumed); the connection is then torn down — but only AFTER the
+        // 413 has been written, so the client still receives it. The 413 carries
+        // `Connection: close` and the socket is destroyed once the response
+        // finishes/closes (destroying before the response is sent would reset the
+        // socket and the client would get a transport error instead of the 413).
+        request.pause();
+        if (response) {
+          const destroyRequest = () => {
+            if (!request.destroyed) {
+              request.destroy();
+            }
+          };
+          response.once("finish", destroyRequest);
+          response.once("close", destroyRequest);
+        } else {
+          request.destroy();
+        }
         reject(proxyError({
           statusCode: 413,
           errorCode: "haechi_request_body_too_large",
@@ -1032,8 +1358,8 @@ function parseJsonBody(body) {
   }
 }
 
-function writeJson(response, status, body) {
-  response.writeHead(status, { "content-type": "application/json" });
+function writeJson(response, status, body, extraHeaders = null) {
+  response.writeHead(status, { "content-type": "application/json", ...(extraHeaders ?? {}) });
   response.end(`${JSON.stringify(body, null, 2)}\n`);
 }
 
@@ -1041,10 +1367,32 @@ function isJson(contentType = "") {
   return contentType.toLowerCase().includes("application/json");
 }
 
+// CR2-004 — body-coupled validator headers that describe the UPSTREAM body. On a
+// transformed (protected/redacted/re-serialized) response the body changed, so
+// these become stale and must be dropped (a client/proxy honoring the upstream's
+// etag/last-modified could otherwise serve or revalidate against the wrong body).
+const BODY_COUPLED_VALIDATOR_HEADERS = [
+  "etag",
+  "content-md5",
+  "digest",
+  "last-modified"
+];
+
 function transformedJsonHeaders(headers) {
+  // P1-CR-003 — defensively strip the full hop-by-hop/compression set (the
+  // caller already passes the sanitized headers, but the transformed JSON body
+  // is freshly serialized, so any stale length/encoding metadata must not leak).
   const next = { ...headers, "content-type": "application/json" };
-  delete next["content-length"];
-  delete next["content-encoding"];
+  for (const name of RESPONSE_HOP_BY_HOP_HEADERS) {
+    delete next[name];
+  }
+  // CR2-004 — the body was MUTATED, so drop validators coupled to the upstream
+  // body and forbid caching the rewritten response. This path only (the raw
+  // pass-through path keeps its etag — its body is byte-unchanged so still valid).
+  for (const name of BODY_COUPLED_VALIDATOR_HEADERS) {
+    delete next[name];
+  }
+  next["cache-control"] = "no-store";
   return next;
 }
 
@@ -1077,10 +1425,13 @@ async function unprotectedResponseDecision({
   metrics?.increment("haechi_response_unprotected_total");
 
   if (allowed) {
+    // P1-CR-003 — `headers` is already the sanitized set (no stale
+    // compression/length metadata). Re-set a correct content-length for this
+    // fully-buffered body.
     return {
       decision,
       status: upstreamResponse.status,
-      headers,
+      headers: { ...headers, "content-length": String(rawBody.byteLength) },
       body: rawBody
     };
   }

package/packages/ssrf/index.mjs

@@ -18,6 +18,61 @@ import { lookup as dnsLookup } from "node:dns/promises";
 const DEFAULT_FETCH_TIMEOUT_MS = 5_000;
 const DEFAULT_MAX_BYTES = 1024 * 1024; // 1 MiB
 
+// Parse an IPv6 literal into its 16 octets (or null when it is not a valid IPv6
+// text form). This is the SOUND way to recognise an IPv4-mapped IPv6 address in
+// EVERY textual form: dotted (::ffff:127.0.0.1), HEX (::ffff:7f00:1), bracketed
+// ([::ffff:7f00:1], stripped by the caller), leading-zero (::ffff:7f00:0001),
+// mixed `::` compression, and case-insensitive ffff. We classify the last 32
+// bits as the embedded IPv4 ONLY when bytes 0..9 are zero and bytes 10..11 are
+// 0xffff (the ::ffff:0:0/96 IPv4-mapped prefix), so a genuinely public mapped
+// address (::ffff:8.8.8.8 == ::ffff:808:808) stays allowed and a non-mapped v6
+// (::ffff:0:7f00:1, NAT64 64:ff9b::…) is NOT mistaken for an embedded IPv4.
+function ipv6ToBytes(str) {
+  let s = str;
+  // A trailing dotted IPv4 quad (::ffff:127.0.0.1) — peel it off into the final
+  // two hextets so the remaining text is pure hex groups.
+  let tailV4 = null;
+  if (s.includes(".")) {
+    const idx = s.lastIndexOf(":");
+    if (idx === -1) return null;
+    const quad = s.slice(idx + 1).split(".");
+    if (quad.length !== 4) return null;
+    const oct = quad.map(Number);
+    if (oct.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return null;
+    tailV4 = oct;
+    s = `${s.slice(0, idx + 1)}0:0`; // placeholder hextets; overwritten below
+  }
+  const halves = s.split("::");
+  if (halves.length > 2) return null; // at most one "::"
+  const toGroups = (g) => (g === "" ? [] : g.split(":").map((h) => (/^[0-9a-fA-F]{1,4}$/.test(h) ? parseInt(h, 16) : NaN)));
+  const head = toGroups(halves[0]);
+  const tail = halves.length === 2 ? toGroups(halves[1]) : null;
+  if (head.some(Number.isNaN) || (tail && tail.some(Number.isNaN))) return null;
+  let groups;
+  if (tail === null) {
+    if (head.length !== 8) return null;
+    groups = head;
+  } else {
+    const missing = 8 - head.length - tail.length;
+    if (missing < 0) return null;
+    groups = [...head, ...Array(missing).fill(0), ...tail];
+  }
+  if (groups.length !== 8) return null;
+  const bytes = [];
+  for (const g of groups) bytes.push((g >> 8) & 0xff, g & 0xff);
+  if (tailV4) { bytes[12] = tailV4[0]; bytes[13] = tailV4[1]; bytes[14] = tailV4[2]; bytes[15] = tailV4[3]; }
+  return bytes;
+}
+
+// Return the embedded IPv4 dotted quad of an IPv4-mapped IPv6 address, or null.
+function mappedIpv4(bare) {
+  const b = ipv6ToBytes(bare);
+  if (!b) return null;
+  for (let i = 0; i < 10; i += 1) if (b[i] !== 0) return null; // bytes 0..9 must be zero
+  if (b[10] !== 0xff || b[11] !== 0xff) return null;           // bytes 10..11 must be 0xffff
+  return `${b[12]}.${b[13]}.${b[14]}.${b[15]}`;
+}
+
 // Block literal addresses in private/loopback/link-local ranges + cloud metadata.
 // Applied to both a literal host in the URL and every DNS-resolved address. This
 // is the canonical copy; the satellite copies must agree (parity-tested).
@@ -39,10 +94,11 @@ export function isBlockedAddress(host) {
   if (v === 6) {
     const h = bare.toLowerCase();
     if (h === "::1" || h === "::") return true;             // loopback / unspecified
-    if (h.startsWith("::ffff:")) {                          // IPv4-mapped
-      const mapped = h.slice("::ffff:".length);
-      if (isIP(mapped) === 4) return isBlockedAddress(mapped);
-    }
+    // IPv4-mapped IPv6 — normalise to the embedded IPv4 (handles dotted AND hex
+    // forms, e.g. ::ffff:127.0.0.1 and ::ffff:7f00:1) and run the v4 check, so a
+    // private/loopback/metadata target can't slip past as hex (P1-CR-002).
+    const mapped = mappedIpv4(bare);
+    if (mapped !== null) return isBlockedAddress(mapped);
     // Range-check the first hextet: fe80::/10 link-local, fc00::/7 ULA, ff00::/8 multicast.
     const firstHextet = parseInt(h.split(":")[0] || "", 16);
     if (Number.isFinite(firstHextet)) {