@runuai/host 0.9.148 → 0.9.149

package/lib/secrets-proxy/engine.ts

@@ -0,0 +1,1633 @@
+/**
+ * Secrets proxy engine (ADR-153 §3 "The boundary proxy").
+ *
+ * The gateway listener has already established which task a connection
+ * belongs to (the forwarder's HMAC handshake, or a sidecar's single task) and
+ * hands over the raw socket. Its next bytes are a TLS ClientHello for a
+ * domain that task's /etc/hosts pins to the proxy. Per connection:
+ *
+ *   TLS server — a leaf minted for the SNI name, only if the task declares it
+ *     → HTTP/1.1 through Node's strict parser (a non-listening http.Server)
+ *     → the task's placeholders swapped for real values in eligible headers
+ *     → vetted upstream: runner-side DNS, public addresses only, TLS verified
+ *       against public roots for the declared domain
+ *     → the response scrubbed back to placeholders whenever anything was
+ *       injected into its request.
+ *
+ * The invariant: a real value leaves this process only toward its key's bound
+ * domain, over verified TLS, and never flows back to the task. A step that
+ * cannot uphold it refuses instead ("withhold means never send"), and every
+ * refusal and skip is audited — never with a value, placeholder, path or
+ * query in the entry.
+ */
+
+import {
+  STATUS_CODES,
+  createServer as createHttpServer,
+  type IncomingMessage,
+  type ServerResponse,
+} from "node:http";
+import { request as httpsRequest, type RequestOptions as HttpsRequestOptions } from "node:https";
+import { isIP, type LookupFunction, type Socket } from "node:net";
+import { Transform, Writable, pipeline, type Duplex } from "node:stream";
+import {
+  connect as tlsConnect,
+  createSecureContext,
+  createServer as createTlsServer,
+  rootCertificates,
+  type ConnectionOptions,
+  type SecureContext,
+  type TLSSocket,
+} from "node:tls";
+import * as zlib from "node:zlib";
+
+import type { TaskEnvHead } from "../project-env-task-policy";
+import { isPublicAddress } from "./address";
+import type { LeafCertificate, LeafCertificateCache } from "./ca";
+import { authorityMatches, canonicalHostname, isProxiableDomain } from "./hostname";
+import { PreparedRules, ScrubError, createScrubStream, scrubHeaderText, scrubRules, type ScrubRule } from "./scrub";
+
+export interface ProxyKeyRef {
+  projectId: string;
+  key: string;
+  domains: readonly string[];
+  /** The head the key's value must have, carried to the value read. */
+  head?: TaskEnvHead;
+}
+
+export interface ProxyTaskState {
+  /** Canonical domains this task may intercept. */
+  domains(): ReadonlySet<string>;
+  /** This task's placeholder → key it stands for, or null. */
+  lookup(placeholder: string): ProxyKeyRef | null;
+  /** All of this task's placeholders (to find them in headers). */
+  placeholders(): readonly string[];
+  /** The CURRENT real value, read per request (so rotation applies to the next request). Null = withhold. */
+  realValue(ref: ProxyKeyRef): string | null;
+}
+
+export interface SecretsProxyLimits {
+  /** TLS handshake, from hand-over to the end of the handshake (absolute). */
+  handshakeMs: number;
+  /** A request head, from its first byte to its last (absolute). */
+  headersMs: number;
+  /** A connection with no request in flight and no bytes of the next one. */
+  idleMs: number;
+  maxHeaderBytes: number;
+  maxConnectionsPerTask: number;
+  /** Responses up to this Content-Length are buffered, scrubbed, verified
+   *  and sent with an exact length; larger or unsized ones are streamed. */
+  maxBufferedBody: number;
+  /** Runner-side resolution, and separately the upstream dial plus TLS
+   *  handshake. Never a bound on the response: an SSE stream may stay quiet
+   *  for as long as the client keeps it open. */
+  upstreamConnectMs: number;
+}
+
+export interface SecretsProxyDeps {
+  getTaskState(taskId: string): ProxyTaskState | null;
+  /** The runner CA's leaf cache: a leaf per declared domain, minted on demand. */
+  ca: LeafCertificateCache;
+  /** A + AAAA, resolved runner-side, never through the task's pins. */
+  resolveHost(hostname: string): Promise<string[]>;
+  /** Default: the strict check in ./address (tests inject a loopback allowance). */
+  isPublicAddress?(ip: string): boolean;
+  /** Default: Node's bundled Mozilla roots — never the system store, never
+   *  NODE_EXTRA_CA_CERTS, so it can never include Uai's own CA. */
+  upstreamCa?: string | Buffer | Array<string | Buffer>;
+  /** One entry per injection, refusal or skip. Never a value, placeholder,
+   *  path or query. */
+  audit(entry: Record<string, unknown>): void;
+  now?(): number;
+  limits?: Partial<SecretsProxyLimits>;
+  /** Test seam: production always dials 443, the only port a pin redirects. */
+  upstreamPort?: number;
+}
+
+export interface SecretsProxy {
+  /** Take over a socket whose task the caller has already authenticated; its
+   *  next bytes must be a TLS ClientHello. `isCurrent` is the gateway's
+   *  generation check, required so no caller can forget it: once it says
+   *  false — the task stopped or was restarted — the connection is served
+   *  nothing more. Never throws. */
+  handleConnection(connection: { taskId: string; socket: Socket; isCurrent: () => boolean }): void;
+  /** Tear down every open connection of one task, in-flight upstream requests
+   *  and tunnels included. Revocation (stop, teardown, a new generation)
+   *  drops the task's state first, which refuses NEW requests; this ends the
+   *  streams already under way, so nothing opened under the old generation
+   *  outlives it. */
+  closeTask(taskId: string): void;
+  /** Refuse new connections and tear down every open one. */
+  close(): Promise<void>;
+}
+
+export const DEFAULT_SECRETS_PROXY_LIMITS: Readonly<SecretsProxyLimits> = Object.freeze({
+  handshakeMs: 10_000,
+  headersMs: 30_000,
+  idleMs: 60_000,
+  maxHeaderBytes: 32 * 1024,
+  maxConnectionsPerTask: 64,
+  maxBufferedBody: 2 * 1024 * 1024,
+  upstreamConnectMs: 30_000,
+});
+
+/** A compressed body chosen for buffering is decoded at most this far: a
+ *  2 MB gzip can inflate a thousandfold. */
+const MAX_DECODED_BUFFERED_BYTES = 64 * 1024 * 1024;
+/** Pipelined requests one connection may have in flight; each is an upstream
+ *  request, and the per-task cap counts connections, not requests. */
+const MAX_IN_FLIGHT_PER_CONNECTION = 16;
+const PLACEHOLDER_SHAPE = "uai_proxied_";
+const MAX_PROXIED_VALUE_CHARS = 4_096;
+
+const HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-connection",
+  "proxy-authorization",
+  "proxy-authenticate",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+]);
+/** Never swapped into (ADR-153 §3 rule 4): they are echoed back, logged, or
+ *  describe the client rather than authenticate it. */
+const NEVER_SWAPPED = new Set(["cookie", "host", "forwarded", "via", "referer", "origin", "user-agent"]);
+/** Set by the proxy itself: Host is the declared domain, framing follows
+ *  Node's parse (never the client's header list), identity encoding keeps
+ *  responses scannable, and `expect` was already answered by Node. */
+const PROXY_SET = new Set(["host", "content-length", "expect", "accept-encoding"]);
+/** Dropped from an injected request: a byte range of a response could hold a
+ *  fragment of a value that no scan can recognise. */
+const RANGE_HEADERS = new Set(["range", "if-range"]);
+/** Dropped from a scrubbed response: they describe bytes the task no longer
+ *  receives. */
+const VALIDATOR_HEADERS = new Set(["content-md5", "digest", "content-digest", "repr-digest", "etag", "last-modified"]);
+/** Visible ASCII and space: anything else is ambiguous in a header (latin1 vs
+ *  UTF-8) or a header-injection vector (CR/LF). */
+const HEADER_SAFE_VALUE = /^[\x20-\x7e]*$/;
+
+type Phase = "handshake" | "idle" | "head" | "active" | "tunnel";
+
+interface Connection {
+  readonly taskId: string;
+  readonly raw: Socket;
+  /** False once the generation that opened the connection is revoked. */
+  readonly isCurrent: () => boolean;
+  tls: TLSSocket | null;
+  /** The canonical SNI name, fixed during the handshake. */
+  domain: string | null;
+  phase: Phase;
+  inFlight: number;
+  timer: NodeJS.Timeout | null;
+  onData: (() => void) | null;
+  /** Upstream requests and tunnels to tear down with the connection. */
+  readonly children: Set<{ destroy(): unknown }>;
+  closed: boolean;
+}
+
+interface Injected {
+  readonly ref: ProxyKeyRef;
+  readonly value: string;
+  readonly placeholder: string;
+}
+
+interface VettedAddress {
+  readonly address: string;
+  readonly family: 4 | 6;
+}
+
+interface Codec {
+  decode(): Transform;
+  encode(streaming: boolean): Transform;
+}
+
+type ZstdZlib = {
+  createZstdDecompress?: () => Transform;
+  createZstdCompress?: (options?: Record<string, unknown>) => Transform;
+  constants: { ZSTD_e_flush?: number };
+};
+
+function codecFor(coding: string): Codec | null {
+  switch (coding) {
+    case "gzip":
+    case "x-gzip":
+      return {
+        decode: () => zlib.createGunzip(),
+        // A sync flush per write keeps a streamed (SSE) body flowing.
+        encode: (streaming) => zlib.createGzip(streaming ? { flush: zlib.constants.Z_SYNC_FLUSH } : {}),
+      };
+    case "deflate":
+      // The zlib-wrapped form RFC 9110 defines; a server sending raw deflate
+      // fails to decode, and the response fails closed.
+      return {
+        decode: () => zlib.createInflate(),
+        encode: (streaming) => zlib.createDeflate(streaming ? { flush: zlib.constants.Z_SYNC_FLUSH } : {}),
+      };
+    case "br":
+      return {
+        decode: () => zlib.createBrotliDecompress(),
+        encode: (streaming) =>
+          zlib.createBrotliCompress({
+            ...(streaming ? { flush: zlib.constants.BROTLI_OPERATION_FLUSH } : {}),
+            params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 5 },
+          }),
+      };
+    case "zstd": {
+      // Only where the runtime has it (Node 22.15+/23.8+); otherwise a 502.
+      const zstd = zlib as unknown as ZstdZlib;
+      const decompress = zstd.createZstdDecompress;
+      const compress = zstd.createZstdCompress;
+      if (typeof decompress !== "function" || typeof compress !== "function") return null;
+      const flush = zstd.constants.ZSTD_e_flush;
+      return {
+        decode: () => decompress(),
+        encode: (streaming) => compress(streaming && flush !== undefined ? { flush } : {}),
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+/** "identity" when the body is unencoded, the single coding's name, or null
+ *  for stacked codings, which are refused rather than unwound. */
+function contentCoding(header: string | undefined): string | null {
+  if (header === undefined) return "identity";
+  const codings = header
+    .split(",")
+    .map((coding) => coding.trim().toLowerCase())
+    .filter((coding) => coding !== "" && coding !== "identity");
+  if (codings.length === 0) return "identity";
+  return codings.length === 1 ? (codings[0] ?? null) : null;
+}
+
+function* headerPairs(raw: readonly string[]): Generator<[string, string]> {
+  for (let index = 0; index + 1 < raw.length; index += 2) {
+    yield [raw[index] ?? "", raw[index + 1] ?? ""];
+  }
+}
+
+function headerValues(raw: readonly string[], name: string): string[] {
+  const values: string[] = [];
+  for (const [key, value] of headerPairs(raw)) {
+    if (key.toLowerCase() === name) values.push(value);
+  }
+  return values;
+}
+
+function connectionTokens(raw: readonly string[]): Set<string> {
+  const tokens = new Set<string>();
+  for (const value of headerValues(raw, "connection")) {
+    for (const token of value.split(",")) {
+      const name = token.trim().toLowerCase();
+      if (name !== "") tokens.add(name);
+    }
+  }
+  return tokens;
+}
+
+/** Response headers minus hop-by-hop ones and whatever `Connection` lists. */
+function endToEndHeaders(raw: readonly string[]): string[] {
+  const listed = connectionTokens(raw);
+  const headers: string[] = [];
+  for (const [name, value] of headerPairs(raw)) {
+    const lower = name.toLowerCase();
+    if (!HOP_BY_HOP.has(lower) && !listed.has(lower)) headers.push(name, value);
+  }
+  return headers;
+}
+
+function declaredLength(raw: readonly string[]): number | null {
+  const lengths = headerValues(raw, "content-length");
+  if (lengths.length !== 1 || !/^[0-9]{1,15}$/.test(lengths[0] ?? "")) return null;
+  return Number(lengths[0]);
+}
+
+/** False only for no Transfer-Encoding, or exactly one field naming exactly
+ *  `chunked` — the single framing Node removes. Anything else leaves coded
+ *  bytes in the body: `gzip, chunked` arrives still compressed, and a
+ *  repeated `chunked, chunked` leaves an inner chunk stream whose framing
+ *  can split a value into pieces no scan sees whole. */
+function hasForeignTransferCoding(raw: readonly string[]): boolean {
+  const fields = headerValues(raw, "transfer-encoding");
+  if (fields.length === 0) return false;
+  if (fields.length > 1) return true;
+  const codings = (fields[0] ?? "").split(",").map((coding) => coding.trim().toLowerCase());
+  return !(codings.length === 1 && codings[0] === "chunked");
+}
+
+/** Passes a request body through unchanged, calling `onFound` once when one
+ *  of `needles` appears in it, across chunk boundaries too. */
+function observePlaceholders(needles: readonly string[], onFound: () => void): Transform {
+  const buffers = needles.filter((needle) => needle.length > 0).map((needle) => Buffer.from(needle, "latin1"));
+  const keep = Math.max(0, ...buffers.map((needle) => needle.length - 1));
+  let tail = Buffer.alloc(0);
+  let found = buffers.length === 0;
+  return new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      if (!found) {
+        const window = tail.length === 0 ? chunk : Buffer.concat([tail, chunk]);
+        if (buffers.some((needle) => window.includes(needle))) {
+          found = true;
+          onFound();
+        } else {
+          tail = Buffer.from(window.subarray(Math.max(0, window.length - keep)));
+        }
+      }
+      callback(null, chunk);
+    },
+  });
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** The credential of an `Authorization: Basic` value, decoded, or null when
+ *  the value is not Basic. One grammar for swapping and for the upgrade
+ *  refusal, so neither can accept a form the other misses. */
+function decodeBasic(value: string): { scheme: string; token: string; decoded: string } | null {
+  const basic = /^(basic[ \t]+)([A-Za-z0-9+/_-]+={0,2})$/i.exec(value);
+  if (basic === null) return null;
+  const [, scheme = "", token = ""] = basic;
+  return { scheme, token, decoded: Buffer.from(token, "base64").toString("latin1") };
+}
+
+type HeadCheck =
+  | { ok: true; path: string }
+  | { ok: false; status: number; reason: string; message: string };
+
+/** ADR-153 §3 rule 3, beyond what Node's strict parser already refuses. */
+function checkRequestHead(req: IncomingMessage, domain: string): HeadCheck {
+  const hosts = headerValues(req.rawHeaders, "host");
+  if (hosts.length !== 1) {
+    // RFC 9112 §3.2 makes a missing or repeated Host a 400, not a 421.
+    return {
+      ok: false,
+      status: 400,
+      reason: "host_missing_or_duplicate",
+      message: "exactly one Host header is required",
+    };
+  }
+  if (!authorityMatches(hosts[0] ?? "", domain)) {
+    return { ok: false, status: 421, reason: "host_mismatch", message: "Host does not match the TLS server name" };
+  }
+  // llhttp already rejects Content-Length with Transfer-Encoding and repeated
+  // lengths, but it emits `request` before failing on some codings (a bare
+  // `Transfer-Encoding: gzip`), so framing is checked again here.
+  const lengths = headerValues(req.rawHeaders, "content-length");
+  const codings = headerValues(req.rawHeaders, "transfer-encoding");
+  if (
+    lengths.length > 1 ||
+    codings.length > 1 ||
+    (lengths.length > 0 && codings.length > 0) ||
+    (codings.length === 1 && codings[0]?.trim().toLowerCase() !== "chunked")
+  ) {
+    return { ok: false, status: 400, reason: "ambiguous_framing", message: "ambiguous request framing" };
+  }
+  const target = req.url ?? "";
+  if (target.startsWith("/")) return { ok: true, path: target };
+  if (target === "*" && req.method === "OPTIONS") return { ok: true, path: target };
+  const absolute = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/([^/?#]*)([^#]*)$/.exec(target);
+  if (absolute === null) {
+    return { ok: false, status: 400, reason: "request_target", message: "unsupported request target" };
+  }
+  const [, scheme = "", authority = "", rest = ""] = absolute;
+  if (scheme.toLowerCase() !== "https" || !authorityMatches(authority, domain)) {
+    return {
+      ok: false,
+      status: 400,
+      reason: "absolute_form_authority",
+      message: "the request URL names another authority",
+    };
+  }
+  // The client's own path bytes: a WHATWG URL round trip would collapse
+  // `/a/../b` and re-escape characters the upstream may care about.
+  return { ok: true, path: rest === "" ? "/" : rest.startsWith("/") ? rest : `/${rest}` };
+}
+
+/**
+ * Finds this task's placeholders in text and decides, per occurrence, whether
+ * it is swapped (ADR-153 §3 rule 4). One instance per request: the real
+ * value of each key is read once, so a rotation mid-request cannot put two
+ * different values into one request, and the scrub set matches what was sent.
+ */
+class Swapper {
+  readonly injected = new Map<string, Injected>();
+  /** Re-encoded Basic credentials → the task's original token. */
+  readonly echoes: Array<{ from: string; to: string }> = [];
+  readonly skipped = new Set<string>();
+  refusal: "withheld" | "unencodable_value" | "value_too_long" | null = null;
+  /** This task's placeholders, longest first. */
+  readonly all: readonly string[];
+  private readonly matcher: RegExp | null;
+  private readonly values = new Map<string, string | null>();
+
+  constructor(
+    private readonly state: ProxyTaskState,
+    private readonly domain: string,
+  ) {
+    let placeholders: readonly string[] = [];
+    try {
+      placeholders = state.placeholders();
+    } catch {
+      // Unenumerable placeholders are never swapped: they go upstream as-is.
+    }
+    const usable = [...new Set(placeholders.filter((entry) => typeof entry === "string" && entry.length > 0))]
+      // Longest first, so a placeholder that contains another wins.
+      .sort((left, right) => right.length - left.length);
+    this.all = usable;
+    this.matcher = usable.length > 0 ? new RegExp(usable.map(escapeRegExp).join("|"), "g") : null;
+  }
+
+  /** A header value with eligible placeholders swapped. */
+  text(value: string): string {
+    return this.walk(value, (placeholder) => this.resolve(placeholder));
+  }
+
+  /** `Authorization: Basic` is swapped inside the decoded `user:pass`
+   *  (Stripe and Twilio authenticate this way); anything else as text. */
+  authorization(value: string): string {
+    const basic = decodeBasic(value);
+    if (basic !== null) {
+      const swapped = this.text(basic.decoded);
+      if (swapped !== basic.decoded) {
+        const encoded = Buffer.from(swapped, "latin1").toString("base64");
+        // An upstream that echoes the header echoes the base64 form, which
+        // no scan for the raw value would recognise.
+        this.echoes.push({ from: encoded, to: basic.token });
+        return `${basic.scheme}${encoded}`;
+      }
+    }
+    return this.text(value);
+  }
+
+  /** Records placeholders where they are never swapped (an excluded header,
+   *  the URL), leaving the text as it is. */
+  observe(value: string, reason: string): void {
+    this.walk(value, (placeholder) => {
+      this.skipped.add(reason);
+      return placeholder;
+    });
+  }
+
+  /** Whether one of this task's placeholders occurs at all, bound to this
+   *  domain or not — the test for refusing an upgrade. */
+  contains(value: string): boolean {
+    let found = false;
+    this.walk(value, (placeholder) => {
+      found = true;
+      return placeholder;
+    });
+    return found;
+  }
+
+  private walk(value: string, onPlaceholder: (placeholder: string) => string): string {
+    if (this.matcher === null) {
+      this.noteForeign(value);
+      return value;
+    }
+    let output = "";
+    let last = 0;
+    for (const match of value.matchAll(this.matcher)) {
+      const at = match.index ?? 0;
+      const between = value.slice(last, at);
+      this.noteForeign(between);
+      output += between + onPlaceholder(match[0]);
+      last = at + match[0].length;
+    }
+    const rest = value.slice(last);
+    this.noteForeign(rest);
+    return last === 0 ? value : output + rest;
+  }
+
+  /** Another task's placeholder (or a stale one) is forwarded unchanged. */
+  private noteForeign(text: string): void {
+    if (text.includes(PLACEHOLDER_SHAPE)) this.skipped.add("foreign_placeholder");
+  }
+
+  private resolve(placeholder: string): string {
+    let ref: ProxyKeyRef | null = null;
+    try {
+      ref = this.state.lookup(placeholder);
+    } catch {
+      ref = null;
+    }
+    if (ref === null) {
+      this.skipped.add("unknown_placeholder");
+      return placeholder;
+    }
+    const domains = Array.isArray(ref.domains) ? ref.domains : [];
+    if (!domains.some((domain) => canonicalHostname(domain) === this.domain)) {
+      this.skipped.add("other_domain");
+      return placeholder;
+    }
+    const id = `${ref.projectId}\u0000${ref.key}`;
+    let value: string | null;
+    if (this.values.has(id)) {
+      value = this.values.get(id) ?? null;
+    } else {
+      try {
+        const current = this.state.realValue(ref);
+        value = typeof current === "string" ? current : null;
+      } catch {
+        value = null;
+      }
+      this.values.set(id, value);
+    }
+    if (value === null) {
+      this.refusal ??= "withheld";
+      return placeholder;
+    }
+    if (!HEADER_SAFE_VALUE.test(value)) {
+      this.refusal ??= "unencodable_value";
+      return placeholder;
+    }
+    // A header credential beyond this is not one; it would also make every
+    // scan of its responses proportionally costlier.
+    if (value.length > MAX_PROXIED_VALUE_CHARS) {
+      this.refusal ??= "value_too_long";
+      return placeholder;
+    }
+    this.injected.set(id, { ref, value, placeholder });
+    return value;
+  }
+}
+
+function sendError(res: ServerResponse, status: number, message: string): void {
+  if (res.headersSent || res.destroyed) {
+    res.destroy();
+    return;
+  }
+  const body = JSON.stringify({ error: `uai secrets proxy: ${message}` });
+  res.writeHead(status, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(body),
+    // A refused exchange ends the connection: the rest of its request body
+    // may still be arriving, and nothing after it is worth parsing.
+    connection: "close",
+  });
+  res.end(body);
+}
+
+/** A refusal on a socket the HTTP server has let go of (upgrade, CONNECT,
+ *  a parse error). */
+function writeRawRefusal(socket: Duplex, status: number, message: string): void {
+  if (socket.destroyed || !socket.writable) {
+    socket.destroy();
+    return;
+  }
+  const body = JSON.stringify({ error: `uai secrets proxy: ${message}` });
+  socket.end(
+    `HTTP/1.1 ${status} ${STATUS_CODES[status] ?? "Error"}\r\n` +
+      `content-type: application/json\r\ncontent-length: ${Buffer.byteLength(body)}\r\n` +
+      `connection: close\r\n\r\n${body}`,
+    () => socket.destroy(),
+  );
+}
+
+/** writeHead validates names and values and throws synchronously; inside an
+ *  event handler that would be an uncaught exception in the runner. */
+function writeHead(res: ServerResponse, status: number, message: string | undefined, headers: string[]): boolean {
+  try {
+    res.writeHead(status, message, headers);
+    return true;
+  } catch {
+    res.destroy();
+    return false;
+  }
+}
+
+/** The request head as parsed — names, values, order and duplicates as the
+ *  client sent them (header strings are latin1, as Node decoded them). */
+function serializeHead(req: IncomingMessage): Buffer {
+  let head = `${req.method ?? "GET"} ${req.url ?? "/"} HTTP/${req.httpVersion}\r\n`;
+  for (const [name, value] of headerPairs(req.rawHeaders)) head += `${name}: ${value}\r\n`;
+  return Buffer.from(`${head}\r\n`, "latin1");
+}
+
+function positive(value: number | undefined, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+
+export function createSecretsProxy(deps: SecretsProxyDeps): SecretsProxy {
+  const limits: SecretsProxyLimits = {
+    handshakeMs: positive(deps.limits?.handshakeMs, DEFAULT_SECRETS_PROXY_LIMITS.handshakeMs),
+    headersMs: positive(deps.limits?.headersMs, DEFAULT_SECRETS_PROXY_LIMITS.headersMs),
+    idleMs: positive(deps.limits?.idleMs, DEFAULT_SECRETS_PROXY_LIMITS.idleMs),
+    maxHeaderBytes: positive(deps.limits?.maxHeaderBytes, DEFAULT_SECRETS_PROXY_LIMITS.maxHeaderBytes),
+    maxConnectionsPerTask: positive(
+      deps.limits?.maxConnectionsPerTask,
+      DEFAULT_SECRETS_PROXY_LIMITS.maxConnectionsPerTask,
+    ),
+    maxBufferedBody: positive(deps.limits?.maxBufferedBody, DEFAULT_SECRETS_PROXY_LIMITS.maxBufferedBody),
+    upstreamConnectMs: positive(deps.limits?.upstreamConnectMs, DEFAULT_SECRETS_PROXY_LIMITS.upstreamConnectMs),
+  };
+  const now = deps.now ?? Date.now;
+  const publicAddress = deps.isPublicAddress ?? isPublicAddress;
+  const upstreamPort = deps.upstreamPort ?? 443;
+  // Built once: https.request would otherwise parse ~150 root PEMs per call.
+  // An explicit context also means NODE_EXTRA_CA_CERTS can never widen it.
+  const upstreamContext = createSecureContext({
+    ca: deps.upstreamCa ?? [...rootCertificates],
+    minVersion: "TLSv1.2",
+  });
+  const connections = new Set<Connection>();
+  const openPerTask = new Map<string, number>();
+  const bySocket = new WeakMap<Socket, Connection>();
+  const contexts = new WeakMap<LeafCertificate, SecureContext>();
+  let closing = false;
+
+  const audit = (entry: Record<string, unknown>): void => {
+    try {
+      deps.audit({ ts: now(), ...entry });
+    } catch {
+      // Audit is best-effort, as for mcp-audit; it never breaks a connection.
+    }
+  };
+  const refuse = (taskId: string, domain: string | null, reason: string): void => {
+    audit({ taskId, domain, event: "refused", reason });
+  };
+  const skip = (taskId: string, domain: string, reason: string): void => {
+    audit({ taskId, domain, event: "skipped", reason });
+  };
+
+  const taskState = (taskId: string): ProxyTaskState | null => {
+    try {
+      return deps.getTaskState(taskId);
+    } catch {
+      return null;
+    }
+  };
+  const current = (conn: Pick<Connection, "isCurrent">): boolean => {
+    try {
+      return conn.isCurrent() === true;
+    } catch {
+      return false;
+    }
+  };
+  /** A connection's task state: none once its generation is revoked, even
+   *  if the task (a later generation of it) is still served. */
+  const stateOf = (conn: Connection): ProxyTaskState | null => (current(conn) ? taskState(conn.taskId) : null);
+  const declares = (state: ProxyTaskState, domain: string): boolean => {
+    try {
+      return state.domains().has(domain);
+    } catch {
+      return false;
+    }
+  };
+  const vetted = (address: string): boolean => {
+    try {
+      return isIP(address) !== 0 && publicAddress(address) === true;
+    } catch {
+      return false;
+    }
+  };
+
+  const clearTimer = (conn: Connection): void => {
+    if (conn.timer !== null) {
+      clearTimeout(conn.timer);
+      conn.timer = null;
+    }
+  };
+  const arm = (conn: Connection, ms: number, onExpire: () => void): void => {
+    clearTimer(conn);
+    conn.timer = setTimeout(onExpire, ms);
+    conn.timer.unref();
+  };
+
+  const closeConnection = (conn: Connection): void => {
+    if (conn.closed) return;
+    conn.closed = true;
+    clearTimer(conn);
+    for (const child of conn.children) child.destroy();
+    conn.children.clear();
+    conn.tls?.destroy();
+    conn.raw.destroy();
+    connections.delete(conn);
+    const open = (openPerTask.get(conn.taskId) ?? 1) - 1;
+    if (open > 0) openPerTask.set(conn.taskId, open);
+    else openPerTask.delete(conn.taskId);
+  };
+
+  /** The generation fence, first in every HTTP event and every failure
+   *  path: a connection whose generation was revoked is answered nothing —
+   *  no 100, 417, 400 or 502 — and the audit says why, whatever else was
+   *  wrong with the exchange. True when the connection is (now) closed. */
+  const fenced = (conn: Connection, domain: string | null): boolean => {
+    if (conn.closed) return true;
+    if (current(conn)) return false;
+    refuse(conn.taskId, domain, "task_revoked");
+    closeConnection(conn);
+    return true;
+  };
+
+  const idle = (conn: Connection): void => {
+    conn.phase = "idle";
+    arm(conn, limits.idleMs, () => closeConnection(conn));
+  };
+  const beginHead = (conn: Connection): void => {
+    conn.phase = "head";
+    arm(conn, limits.headersMs, () => {
+      refuse(conn.taskId, conn.domain, "headers_timeout");
+      closeConnection(conn);
+    });
+  };
+  const detach = (conn: Connection, socket: Duplex): void => {
+    conn.phase = "tunnel";
+    clearTimer(conn);
+    if (conn.onData !== null) {
+      socket.removeListener("data", conn.onData);
+      conn.onData = null;
+    }
+  };
+
+  const secureContextFor = (leaf: LeafCertificate): SecureContext => {
+    let context = contexts.get(leaf);
+    if (context === undefined) {
+      context = createSecureContext({ key: leaf.privateKeyPem, cert: leaf.certificatePem });
+      contexts.set(leaf, context);
+    }
+    return context;
+  };
+
+  const vetUpstream = async (domain: string): Promise<VettedAddress | { refusal: string }> => {
+    let answer: unknown;
+    let timer: NodeJS.Timeout | undefined;
+    try {
+      // A resolver that never answers must not pin the connection.
+      answer = await Promise.race([
+        deps.resolveHost(domain),
+        new Promise<never>((_resolve, reject) => {
+          timer = setTimeout(() => reject(new Error("resolve timed out")), limits.upstreamConnectMs);
+          timer.unref();
+        }),
+      ]);
+    } catch {
+      return { refusal: "resolve_failed" };
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!Array.isArray(answer) || answer.length === 0) return { refusal: "resolve_failed" };
+    // One non-public address rejects the whole answer: a rebinding record
+    // cannot win by hiding a private address among public ones.
+    for (const address of answer) {
+      if (typeof address !== "string" || !vetted(address)) return { refusal: "non_public_address" };
+    }
+    const address = answer[0] as string;
+    return { address, family: isIP(address) === 6 ? 6 : 4 };
+  };
+
+  /** Pins Node's connect to the vetted address while `host`/`servername`
+   *  stay the domain, so hostname verification still checks the domain. */
+  const lookupFor = (target: VettedAddress): LookupFunction =>
+    (_hostname, options, callback) => {
+      if (options.all === true) callback(null, [{ address: target.address, family: target.family }]);
+      else callback(null, target.address, target.family);
+    };
+
+  /** Whether every injected value is still exactly what the task may send to
+   *  `domain` now: the generation and the domain grant still stand, each
+   *  placeholder still maps to its key, the key still reaches the domain, and
+   *  its current value (null once withheld, as when the task is no longer
+   *  ready) is the one about to be sent. The refusal reason, or null. */
+  const stillAdmitted = (conn: Connection, domain: string, injected: readonly Injected[]): string | null => {
+    const state = stateOf(conn);
+    if (state === null) return "task_revoked";
+    if (!declares(state, domain)) return "domain_revoked";
+    for (const { ref, value, placeholder } of injected) {
+      let current: ProxyKeyRef | null;
+      try {
+        current = state.lookup(placeholder);
+      } catch {
+        current = null;
+      }
+      if (current === null || current.projectId !== ref.projectId || current.key !== ref.key) return "withdrawn";
+      const domains = Array.isArray(current.domains) ? current.domains : [];
+      if (!domains.some((candidate) => canonicalHostname(candidate) === domain)) return "withdrawn";
+      let valueNow: string | null;
+      try {
+        const read = state.realValue(current);
+        valueNow = typeof read === "string" ? read : null;
+      } catch {
+        valueNow = null;
+      }
+      if (valueNow !== value) return "withdrawn";
+    }
+    return null;
+  };
+
+  /** One record per injected key, written BEFORE the value leaves. The audit
+   *  is part of the invariant (ADR-153 §1): when the record cannot be
+   *  written, the request is refused and nothing is sent. */
+  const recordInjections = (conn: Connection, domain: string, method: string, injected: Iterable<Injected>): boolean => {
+    try {
+      for (const { ref } of injected) {
+        deps.audit({ ts: now(), taskId: conn.taskId, event: "injected", key: ref.key, projectId: ref.projectId, domain, method });
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  /** How the upstream answered an injected request; best-effort, since the
+   *  value has already gone by now. */
+  const recordResponses = (
+    conn: Connection,
+    domain: string,
+    method: string,
+    injected: Iterable<Injected>,
+    status: number | null,
+  ): void => {
+    for (const { ref } of injected) {
+      audit({ taskId: conn.taskId, event: "response", key: ref.key, projectId: ref.projectId, domain, method, status });
+    }
+  };
+
+  const http = createHttpServer({
+    maxHeaderSize: limits.maxHeaderBytes,
+    insecureHTTPParser: false,
+    // Our handler answers (and audits) a missing Host; Node's built-in 400
+    // would skip the audit.
+    requireHostHeader: false,
+    // Header and idle timers are ours: Node only runs its headersTimeout and
+    // requestTimeout checks once a server has emitted 'listening', and this
+    // one never listens.
+    keepAliveTimeout: 0,
+    headersTimeout: 0,
+    requestTimeout: 0,
+  });
+
+  const passThrough = (res: ServerResponse, upstreamRes: IncomingMessage): void => {
+    const headers = endToEndHeaders(upstreamRes.rawHeaders);
+    if (!writeHead(res, upstreamRes.statusCode ?? 502, upstreamRes.statusMessage, headers)) {
+      upstreamRes.destroy();
+      return;
+    }
+    pipeline(upstreamRes, res, (error) => {
+      if (error) {
+        upstreamRes.destroy();
+        res.destroy();
+      }
+    });
+  };
+
+  const respondScrubbed = (
+    conn: Connection,
+    domain: string,
+    req: IncomingMessage,
+    res: ServerResponse,
+    upstreamRes: IncomingMessage,
+    rules: readonly ScrubRule[],
+  ): void => {
+    const fail = (reason: string): void => {
+      refuse(conn.taskId, domain, reason);
+      upstreamRes.destroy();
+      sendError(res, 502, "the upstream response could not be scrubbed");
+    };
+    const status = upstreamRes.statusCode ?? 502;
+    // Without Range (dropped when injecting) a 206 is unexpected, and a
+    // fragment could hold part of a value no scan can see.
+    if (status === 206) return fail("partial_content");
+    // Sorted once for the status line and every header of this response.
+    const prepared = new PreparedRules(rules);
+    const statusMessage = scrubHeaderText(upstreamRes.statusMessage ?? "", prepared);
+    if (statusMessage === null) return fail("scrub_failed");
+    const headers: string[] = [];
+    for (const [name, value] of headerPairs(endToEndHeaders(upstreamRes.rawHeaders))) {
+      const lower = name.toLowerCase();
+      if (VALIDATOR_HEADERS.has(lower) || lower === "content-length") continue;
+      const scrubbedName = scrubHeaderText(name, prepared);
+      const scrubbedValue = scrubHeaderText(value, prepared);
+      if (scrubbedName === null || scrubbedValue === null) return fail("scrub_failed");
+      headers.push(scrubbedName, scrubbedValue);
+    }
+    if (req.method === "HEAD" || status === 204 || status === 304 || status < 200) {
+      // No body follows, so the upstream's length still describes the
+      // entity (a HEAD size probe); only a body we rewrite loses it.
+      const length = declaredLength(upstreamRes.rawHeaders);
+      const bodyless = length !== null && status !== 204 && status >= 200 ? [...headers, "Content-Length", String(length)] : headers;
+      if (writeHead(res, status, statusMessage, bodyless)) res.end();
+      upstreamRes.resume();
+      return;
+    }
+    const coding = contentCoding(upstreamRes.headers["content-encoding"]);
+    const codec = coding === null || coding === "identity" ? null : codecFor(coding);
+    // Nothing unscannable passes after an injection.
+    if (coding === null || (coding !== "identity" && codec === null)) return fail("unsupported_encoding");
+    const length = declaredLength(upstreamRes.rawHeaders);
+    const buffered = length !== null && length <= limits.maxBufferedBody;
+    let failure = "upstream_failed";
+    const stages: Transform[] = [];
+    if (codec !== null) {
+      const decoder = codec.decode();
+      decoder.once("error", () => {
+        failure = "decode_failed";
+      });
+      stages.push(decoder);
+    }
+    const scrubber = createScrubStream(prepared, buffered ? { maxInputBytes: MAX_DECODED_BUFFERED_BYTES } : {});
+    scrubber.once("error", (error) => {
+      failure = error instanceof ScrubError && error.code === "too_large" ? "body_too_large" : "scrub_failed";
+    });
+    stages.push(scrubber);
+    if (codec !== null) stages.push(codec.encode(!buffered));
+
+    if (buffered) {
+      const chunks: Buffer[] = [];
+      const sink = new Writable({
+        write(chunk: Buffer, _encoding, callback) {
+          chunks.push(chunk);
+          callback();
+        },
+      });
+      pipeline([upstreamRes, ...stages, sink], (error) => {
+        if (error) {
+          if (failure !== "upstream_failed") refuse(conn.taskId, domain, failure);
+          sendError(res, 502, "the upstream response could not be scrubbed");
+          return;
+        }
+        if (res.destroyed) return;
+        const body = Buffer.concat(chunks);
+        if (writeHead(res, status, statusMessage, [...headers, "Content-Length", String(body.length)])) res.end(body);
+      });
+      return;
+    }
+    // Unsized or large: chunked, scrubbed as it streams.
+    if (!writeHead(res, status, statusMessage, headers)) {
+      upstreamRes.destroy();
+      return;
+    }
+    res.flushHeaders();
+    pipeline([upstreamRes, ...stages, res], (error) => {
+      if (error) {
+        if (failure !== "upstream_failed") refuse(conn.taskId, domain, failure);
+        res.destroy();
+      }
+    });
+  };
+
+  const forward = (
+    conn: Connection,
+    req: IncomingMessage,
+    res: ServerResponse,
+    domain: string,
+    path: string,
+    headers: string[],
+    swapper: Swapper,
+    target: VettedAddress,
+  ): void => {
+    const method = req.method ?? "GET";
+    const injected = [...swapper.injected.values()];
+    let tcpConnected = false;
+    let secured = false;
+    let answered = false;
+    let responseRecorded = injected.length === 0;
+    const recordOnce = (status: number | null): void => {
+      if (responseRecorded) return;
+      responseRecorded = true;
+      recordResponses(conn, domain, method, injected, status);
+    };
+
+    // `secureContext` and `ALPNProtocols` are not in https.RequestOptions'
+    // type, but the agent hands every option to tls.connect, which honours
+    // them.
+    const options: HttpsRequestOptions & Pick<ConnectionOptions, "secureContext" | "ALPNProtocols"> = {
+      host: domain,
+      port: upstreamPort,
+      servername: domain,
+      lookup: lookupFor(target),
+      method,
+      path,
+      headers,
+      setHost: false,
+      // Never pooled (ADR-153 Limits): some upstreams bind authentication
+      // to the CONNECTION (NTLM/Negotiate), and every way of sharing one —
+      // across tasks, across a rotation, across Basic wrappers around the same
+      // value — let an identity the current request does not carry, and its
+      // scrub rules do not know, answer through it. A connection per request
+      // makes that impossible; the price is one handshake per proxied call.
+      agent: false,
+      secureContext: upstreamContext,
+      rejectUnauthorized: true,
+      ALPNProtocols: ["http/1.1"],
+    };
+    const upstreamReq = httpsRequest(options);
+    conn.children.add(upstreamReq);
+    const send = (): void => {
+      const hasBody = req.headers["transfer-encoding"] !== undefined || req.headers["content-length"] !== undefined;
+      if (!hasBody) {
+        upstreamReq.end();
+        return;
+      }
+      // .pipe rather than pipeline(): an upstream failure must not destroy
+      // the client socket before our 502 has gone out on it. Bodies are never
+      // swapped into, but a placeholder there is recorded as a skip.
+      req
+        // The generic shape too, so another task's (or a stale) placeholder
+        // is recorded like it is in a header.
+        .pipe(observePlaceholders([...swapper.all, PLACEHOLDER_SHAPE], () => skip(conn.taskId, domain, "in_body")))
+        .pipe(upstreamReq);
+    };
+    const connectTimer = setTimeout(() => {
+      upstreamReq.destroy(Object.assign(new Error("upstream connect timed out"), { code: "UAI_UPSTREAM_TIMEOUT" }));
+    }, limits.upstreamConnectMs);
+    connectTimer.unref();
+    upstreamReq.on("socket", (socket) => {
+      socket.once("connect", () => {
+        tcpConnected = true;
+      });
+      // Nothing is written to the request before this point, so nothing —
+      // least of all a value — leaves before verification passed and the
+      // generation is re-checked, the last moment before it would.
+      socket.once("secureConnect", () => {
+        secured = true;
+        clearTimeout(connectTimer);
+        if (fenced(conn, domain)) {
+          answered = true;
+          return;
+        }
+        if (injected.length > 0) {
+          // The last moment before a byte leaves. The lookup and the upstream
+          // handshake took time: the policy may have narrowed, the task's
+          // readiness failed, or the value rotated. Every value must still be
+          // exactly what may be sent here now, and its injection is recorded
+          // here, where it is admitted.
+          const withdrawn = stillAdmitted(conn, domain, injected);
+          const refusal =
+            withdrawn ?? (recordInjections(conn, domain, method, injected) ? null : "audit_failed");
+          if (refusal !== null) {
+            answered = true;
+            // Nothing was recorded as injected, so no response is either.
+            responseRecorded = true;
+            refuse(conn.taskId, domain, refusal);
+            upstreamReq.destroy();
+            sendError(
+              res,
+              502,
+              refusal === "audit_failed"
+                ? "the injection could not be audited, so it was not sent"
+                : "a proxied secret was withdrawn while the request was under way, so it was not sent",
+            );
+            return;
+          }
+        }
+        send();
+      });
+    });
+    upstreamReq.on("error", (error: NodeJS.ErrnoException) => {
+      clearTimeout(connectTimer);
+      conn.children.delete(upstreamReq);
+      recordOnce(null);
+      // Once a response is under way its pipeline owns teardown: an EPIPE on
+      // the request side (an upstream that answered early and stopped
+      // reading) must not cut a healthy response short. A connection already
+      // closed (the client left, or the task was revoked) was not failed by
+      // the upstream, and is not audited as if it had been.
+      if (answered || conn.closed) return;
+      answered = true;
+      if (fenced(conn, domain)) return;
+      const reason =
+        error.code === "UAI_UPSTREAM_TIMEOUT"
+          ? "upstream_timeout"
+          : secured
+            ? "upstream_failed"
+            : tcpConnected
+              ? "upstream_tls"
+              : "upstream_unreachable";
+      refuse(conn.taskId, domain, reason);
+      sendError(res, 502, "the upstream request failed");
+    });
+    upstreamReq.on("response", (upstreamRes) => {
+      clearTimeout(connectTimer);
+      // Teardown belongs to the pipelines below (a buffered response can
+      // still answer 502); this only keeps a late error from going unhandled.
+      upstreamRes.on("error", () => undefined);
+      upstreamRes.once("close", () => conn.children.delete(upstreamReq));
+      recordOnce(upstreamRes.statusCode ?? null);
+      if (answered || res.destroyed) {
+        upstreamRes.destroy();
+        return;
+      }
+      answered = true;
+      if (fenced(conn, domain)) {
+        upstreamRes.destroy();
+        return;
+      }
+      // Node decodes chunked framing and nothing else: under
+      // `Transfer-Encoding: gzip, chunked` the body arrives still gzipped,
+      // with no Content-Encoding to say so — unscannable, and unrelayable as
+      // it stands once the hop-by-hop header is gone.
+      if (hasForeignTransferCoding(upstreamRes.rawHeaders)) {
+        refuse(conn.taskId, domain, "unsupported_transfer_coding");
+        upstreamRes.destroy();
+        sendError(res, 502, "the upstream response used a transfer coding the proxy cannot relay");
+        return;
+      }
+      if (injected.length === 0) passThrough(res, upstreamRes);
+      else respondScrubbed(conn, domain, req, res, upstreamRes, scrubRules(injected, swapper.echoes));
+    });
+    // A client that leaves mid-exchange takes the upstream request with it.
+    res.once("close", () => {
+      if (!res.writableFinished) upstreamReq.destroy();
+    });
+
+    req.on("error", () => upstreamReq.destroy());
+  };
+
+  const handleRequest = async (conn: Connection, req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    const domain = conn.domain ?? "";
+    const refuseRequest = (status: number, reason: string, message: string): void => {
+      refuse(conn.taskId, domain, reason);
+      sendError(res, status, message);
+    };
+    const state = stateOf(conn);
+    if (state === null) {
+      // The task's generation was revoked: nothing of it is served any more.
+      refuse(conn.taskId, domain, "task_revoked");
+      closeConnection(conn);
+      return;
+    }
+    if (!declares(state, domain)) {
+      refuseRequest(421, "domain_revoked", "this domain is no longer proxied for the task");
+      return;
+    }
+    const head = checkRequestHead(req, domain);
+    if (!head.ok) {
+      refuseRequest(head.status, head.reason, head.message);
+      return;
+    }
+
+    const swapper = new Swapper(state, domain);
+    const listed = connectionTokens(req.rawHeaders);
+    const forwarded: string[] = [];
+    for (const [name, value] of headerPairs(req.rawHeaders)) {
+      const lower = name.toLowerCase();
+      if (HOP_BY_HOP.has(lower) || PROXY_SET.has(lower) || listed.has(lower)) continue;
+      swapper.observe(name, "header_name");
+      if (NEVER_SWAPPED.has(lower) || lower.startsWith("x-forwarded-")) {
+        swapper.observe(value, "excluded_header");
+        forwarded.push(name, value);
+        continue;
+      }
+      forwarded.push(name, lower === "authorization" ? swapper.authorization(value) : swapper.text(value));
+    }
+    // Query and path are never swapped (varlock's default since 1.14): a URL
+    // lets an agent write the secret into a resource it can read back.
+    swapper.observe(head.path, "in_url");
+    try {
+      swapper.observe(decodeURIComponent(head.path), "in_url");
+    } catch {
+      // Malformed escapes: the raw form was already checked.
+    }
+    for (const reason of swapper.skipped) skip(conn.taskId, domain, reason);
+    if (swapper.refusal === "withheld") {
+      refuseRequest(502, "withheld", "a proxied secret is withheld for this task");
+      return;
+    }
+    if (swapper.refusal === "unencodable_value") {
+      refuseRequest(502, "unencodable_value", "a proxied secret cannot be carried in a header");
+      return;
+    }
+    if (swapper.refusal === "value_too_long") {
+      refuseRequest(502, "value_too_long", "a proxied secret is too long to carry");
+      return;
+    }
+
+    const injecting = swapper.injected.size > 0;
+    const headers = ["Host", domain];
+    for (const [name, value] of headerPairs(forwarded)) {
+      if (injecting && RANGE_HEADERS.has(name.toLowerCase())) continue;
+      headers.push(name, value);
+    }
+    headers.push("Accept-Encoding", "identity");
+    // Framing from Node's parse, re-emitted explicitly: with no length and no
+    // chunking, Node would write a GET's body raw — a smuggled request.
+    if (req.headers["transfer-encoding"] !== undefined) headers.push("Transfer-Encoding", "chunked");
+    else if (req.headers["content-length"] !== undefined) headers.push("Content-Length", req.headers["content-length"]);
+
+    const target = await vetUpstream(domain);
+    if (conn.closed || res.destroyed) return;
+    // The lookup awaited: the generation may have been revoked meanwhile, and
+    // the gateway's contract is to re-check right before using the task's
+    // authority — before a failed lookup is answered, too.
+    if (fenced(conn, domain)) return;
+    if ("refusal" in target) {
+      refuseRequest(502, target.refusal, "the upstream address was refused");
+      return;
+    }
+    // The injection is admitted, and recorded, at the upstream's handshake.
+    forward(conn, req, res, domain, head.path, headers, swapper, target);
+  };
+
+  const tunnel = (
+    conn: Connection,
+    req: IncomingMessage,
+    client: TLSSocket,
+    head: Buffer,
+    domain: string,
+    target: VettedAddress,
+  ): void => {
+    let tcpConnected = false;
+    let secured = false;
+    const upstream = tlsConnect({
+      host: domain,
+      port: upstreamPort,
+      servername: domain,
+      lookup: lookupFor(target),
+      secureContext: upstreamContext,
+      rejectUnauthorized: true,
+      ALPNProtocols: ["http/1.1"],
+    });
+    conn.children.add(upstream);
+    const connectTimer = setTimeout(() => {
+      upstream.destroy(Object.assign(new Error("upstream connect timed out"), { code: "UAI_UPSTREAM_TIMEOUT" }));
+    }, limits.upstreamConnectMs);
+    connectTimer.unref();
+    upstream.once("connect", () => {
+      tcpConnected = true;
+    });
+    upstream.on("error", (error: NodeJS.ErrnoException) => {
+      clearTimeout(connectTimer);
+      if (secured) {
+        closeConnection(conn);
+        return;
+      }
+      if (fenced(conn, domain)) return;
+      const reason =
+        error.code === "UAI_UPSTREAM_TIMEOUT"
+          ? "upstream_timeout"
+          : tcpConnected
+            ? "upstream_tls"
+            : "upstream_unreachable";
+      refuse(conn.taskId, domain, reason);
+      writeRawRefusal(client, 502, "the upstream connection failed");
+    });
+    upstream.once("secureConnect", () => {
+      clearTimeout(connectTimer);
+      secured = true;
+      // Nothing of the client's has been sent yet: a generation revoked
+      // during the connect gets no tunnel.
+      if (fenced(conn, domain)) return;
+      // Two pipelines plus the TLS and HTTP plumbing already on the task-side
+      // socket pass Node's default ceiling of ten 'close' listeners. That is
+      // a fixed count per tunnel, not growth, so it gets a fixed allowance
+      // rather than a warning on every upgrade.
+      client.setMaxListeners(Math.max(client.getMaxListeners(), 20));
+      // Byte for byte from here: the head, anything the parser had already
+      // read past it, then both directions. pipeline() propagates a FIN
+      // (`end`) as well as errors, so neither side is left streaming into a
+      // peer that has gone.
+      upstream.write(serializeHead(req));
+      if (head.length > 0) upstream.write(head);
+      pipeline(client, upstream, (error) => {
+        if (error) closeConnection(conn);
+      });
+      pipeline(upstream, client, (error) => {
+        if (error) closeConnection(conn);
+      });
+    });
+  };
+
+  const handleUpgrade = async (
+    conn: Connection,
+    req: IncomingMessage,
+    client: TLSSocket,
+    head: Buffer,
+  ): Promise<void> => {
+    const domain = conn.domain ?? "";
+    const refuseUpgrade = (status: number, reason: string, message: string): void => {
+      refuse(conn.taskId, domain, reason);
+      writeRawRefusal(client, status, message);
+    };
+    const state = stateOf(conn);
+    if (state === null) {
+      refuse(conn.taskId, domain, "task_revoked");
+      closeConnection(conn);
+      return;
+    }
+    if (!declares(state, domain)) {
+      refuseUpgrade(421, "domain_revoked", "this domain is no longer proxied for the task");
+      return;
+    }
+    const checked = checkRequestHead(req, domain);
+    if (!checked.ok) {
+      refuseUpgrade(checked.status, checked.reason, checked.message);
+      return;
+    }
+    // Upgrades are never injected (ADR-153 §3 rule 5). One that carries this
+    // task's placeholder anywhere — request line, any header, a Basic
+    // credential — is refused; one without passes byte for byte.
+    const swapper = new Swapper(state, domain);
+    const texts = [req.url ?? ""];
+    for (const [name, value] of headerPairs(req.rawHeaders)) {
+      texts.push(name, value);
+      const basic = name.toLowerCase() === "authorization" ? decodeBasic(value) : null;
+      if (basic !== null) texts.push(basic.decoded);
+    }
+    const carries = texts.map((text) => swapper.contains(text)).some(Boolean);
+    for (const reason of swapper.skipped) skip(conn.taskId, domain, reason);
+    if (carries) {
+      refuseUpgrade(403, "upgrade_with_placeholder", "upgrades are never injected; remove the proxied secret");
+      return;
+    }
+    const target = await vetUpstream(domain);
+    // As for a request: the lookup awaited, and the generation may have been
+    // revoked meanwhile.
+    if (fenced(conn, domain)) return;
+    if ("refusal" in target) {
+      refuseUpgrade(502, target.refusal, "the upstream address was refused");
+      return;
+    }
+    tunnel(conn, req, client, head, domain, target);
+  };
+
+  /** The connection an HTTP event belongs to, or null (the socket is gone, or
+   *  the generation fence closed it). */
+  const connectionFor = (socket: Duplex): Connection | null => {
+    const conn = bySocket.get(socket as Socket);
+    if (conn === undefined || conn.closed) {
+      socket.destroy();
+      return null;
+    }
+    return fenced(conn, conn.domain) ? null : conn;
+  };
+
+  const onRequest = (conn: Connection, req: IncomingMessage, res: ServerResponse): void => {
+    if (conn.inFlight >= MAX_IN_FLIGHT_PER_CONNECTION) {
+      refuse(conn.taskId, conn.domain, "pipeline_limit");
+      closeConnection(conn);
+      return;
+    }
+    conn.inFlight += 1;
+    conn.phase = "active";
+    clearTimer(conn);
+    res.once("close", () => {
+      conn.inFlight -= 1;
+      if (conn.closed) return;
+      // Answered before its body finished arriving (an early 401 to an
+      // upload): the rest of that body is not a next request head, so the
+      // connection ends here rather than timing it out as one later.
+      if (!req.complete) {
+        closeConnection(conn);
+        return;
+      }
+      if (conn.inFlight === 0 && conn.phase === "active") idle(conn);
+    });
+    handleRequest(conn, req, res).catch(() => {
+      refuse(conn.taskId, conn.domain, "internal_error");
+      sendError(res, 502, "internal error");
+    });
+  };
+
+  http.on("request", (req: IncomingMessage, res: ServerResponse) => {
+    req.on("error", () => undefined);
+    res.on("error", () => undefined);
+    const conn = connectionFor(req.socket);
+    if (conn !== null) onRequest(conn, req, res);
+  });
+
+  // `Expect: 100-continue`. Node would write the 100 itself, before any
+  // check of ours; it goes out only to a generation still current.
+  http.on("checkContinue", (req: IncomingMessage, res: ServerResponse) => {
+    req.on("error", () => undefined);
+    res.on("error", () => undefined);
+    const conn = connectionFor(req.socket);
+    if (conn === null) return;
+    res.writeContinue();
+    onRequest(conn, req, res);
+  });
+
+  // Any other expectation. Node would answer 417 itself, unaudited.
+  http.on("checkExpectation", (req: IncomingMessage, res: ServerResponse) => {
+    req.on("error", () => undefined);
+    res.on("error", () => undefined);
+    const conn = connectionFor(req.socket);
+    if (conn === null) return;
+    refuse(conn.taskId, conn.domain, "unsupported_expectation");
+    sendError(res, 417, "only Expect: 100-continue is supported");
+  });
+
+  http.on("upgrade", (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+    const conn = connectionFor(socket);
+    if (conn === null) return;
+    if (conn.inFlight > 0) {
+      // An upgrade pipelined behind a request still being answered: tunnel
+      // bytes and that response would interleave on one socket, and no
+      // refusal could be written without the same interleaving.
+      refuse(conn.taskId, conn.domain, "pipelined_upgrade");
+      closeConnection(conn);
+      return;
+    }
+    detach(conn, socket);
+    handleUpgrade(conn, req, socket as TLSSocket, head).catch(() => closeConnection(conn));
+  });
+
+  http.on("connect", (_req: IncomingMessage, socket: Duplex) => {
+    const conn = connectionFor(socket);
+    if (conn === null) return;
+    detach(conn, socket);
+    refuse(conn.taskId, conn.domain, "connect_method");
+    writeRawRefusal(socket, 400, "CONNECT is not supported");
+  });
+
+  http.on("clientError", (error: NodeJS.ErrnoException, socket: Duplex) => {
+    const conn = bySocket.get(socket as Socket);
+    if (conn === undefined) {
+      socket.destroy();
+      return;
+    }
+    const code = error.code ?? "";
+    if (!code.startsWith("HPE_")) {
+      closeConnection(conn);
+      return;
+    }
+    if (fenced(conn, conn.domain)) return;
+    detach(conn, socket);
+    if (conn.inFlight > 0) {
+      // Node emits `request` before failing on some heads (a bare
+      // `Transfer-Encoding: gzip`), so the exchange in flight owns the
+      // response and its audit: let what it wrote flush, then close.
+      socket.end(() => closeConnection(conn));
+      return;
+    }
+    const tooLarge = code === "HPE_HEADER_OVERFLOW";
+    refuse(conn.taskId, conn.domain, tooLarge ? "headers_too_large" : "malformed_request");
+    writeRawRefusal(socket, tooLarge ? 431 : 400, tooLarge ? "request headers too large" : "malformed request");
+  });
+
+  const onSecure = (conn: Connection, tlsSocket: TLSSocket): void => {
+    tlsSocket.on("error", () => closeConnection(conn));
+    tlsSocket.once("close", () => closeConnection(conn));
+    if (conn.closed) {
+      tlsSocket.destroy();
+      return;
+    }
+    conn.tls = tlsSocket;
+    clearTimer(conn);
+    const servername = typeof tlsSocket.servername === "string" ? canonicalHostname(tlsSocket.servername) : null;
+    // Node skips SNICallback on a resumed session, so a ticket minted for one
+    // domain could otherwise open another (checked live on Node 22.11 with a
+    // shared tls.Server). Every connection gets its own tls.Server — fresh
+    // ticket keys, nothing to resume — and a session that resumes anyway, or
+    // whose name drifted from the one checked, is refused.
+    const alpn = tlsSocket.alpnProtocol;
+    if (
+      conn.domain === null ||
+      servername !== conn.domain ||
+      tlsSocket.isSessionReused() ||
+      (typeof alpn === "string" && alpn !== "http/1.1")
+    ) {
+      refuse(conn.taskId, conn.domain, "tls_state_mismatch");
+      closeConnection(conn);
+      return;
+    }
+    bySocket.set(tlsSocket, conn);
+    http.emit("connection", tlsSocket);
+    // Attached AFTER the parser took the socket, so it only observes (Node
+    // then feeds its parser from 'data' events rather than natively). It
+    // marks the first byte of a request head, where the header clock starts.
+    const onData = (): void => {
+      if (conn.inFlight === 0 && conn.phase === "idle") beginHead(conn);
+    };
+    conn.onData = onData;
+    tlsSocket.on("data", onData);
+    idle(conn);
+  };
+
+  const startTls = (conn: Connection): void => {
+    arm(conn, limits.handshakeMs, () => {
+      refuse(conn.taskId, conn.domain, "handshake_timeout");
+      closeConnection(conn);
+    });
+    const tlsServer = createTlsServer({
+      ALPNProtocols: ["http/1.1"],
+      minVersion: "TLSv1.2",
+      // Only a backstop: Node's handshakeTimeout emits tlsClientError but
+      // never closes the socket, and it cannot be switched off (0 means the
+      // 120 s default). The absolute timer above is the real bound.
+      handshakeTimeout: limits.handshakeMs * 2,
+      SNICallback: (servername, callback) => {
+        const domain = canonicalHostname(servername);
+        const state = stateOf(conn);
+        if (state === null) {
+          refuse(conn.taskId, null, "task_revoked");
+          callback(new Error("the task is no longer served"));
+          return;
+        }
+        if (domain === null || !declares(state, domain)) {
+          // The undeclared name is task-chosen text: never audited.
+          refuse(conn.taskId, null, "sni_not_declared");
+          callback(new Error("server name is not proxied for this task"));
+          return;
+        }
+        // Defence in depth: the declaration parser already withholds keys
+        // for these, so a state that still lists one is refused here too.
+        if (!isProxiableDomain(domain)) {
+          refuse(conn.taskId, domain, "domain_not_proxiable");
+          callback(new Error("this server name is never proxied"));
+          return;
+        }
+        let context: SecureContext;
+        try {
+          context = secureContextFor(deps.ca.leafFor(domain));
+        } catch {
+          refuse(conn.taskId, domain, "certificate_unavailable");
+          callback(new Error("no certificate for this server name"));
+          return;
+        }
+        conn.domain = domain;
+        callback(null, context);
+      },
+    });
+    tlsServer.on("tlsClientError", () => closeConnection(conn));
+    tlsServer.on("secureConnection", (tlsSocket: TLSSocket) => onSecure(conn, tlsSocket));
+    tlsServer.emit("connection", conn.raw);
+  };
+
+  const handleConnection = ({
+    taskId,
+    socket,
+    isCurrent,
+  }: {
+    taskId: string;
+    socket: Socket;
+    isCurrent: () => boolean;
+  }): void => {
+    try {
+      // First, before anything can fail: an 'error' with no listener would
+      // take the whole runner down.
+      socket.on("error", () => socket.destroy());
+      if (closing || socket.destroyed) {
+        socket.destroy();
+        return;
+      }
+      if (!current({ isCurrent })) {
+        refuse(taskId, null, "task_revoked");
+        socket.destroy();
+        return;
+      }
+      if (taskState(taskId) === null) {
+        refuse(taskId, null, "unknown_task");
+        socket.destroy();
+        return;
+      }
+      const open = openPerTask.get(taskId) ?? 0;
+      if (open >= limits.maxConnectionsPerTask) {
+        refuse(taskId, null, "connection_limit");
+        socket.destroy();
+        return;
+      }
+      openPerTask.set(taskId, open + 1);
+      const conn: Connection = {
+        taskId,
+        raw: socket,
+        isCurrent,
+        tls: null,
+        domain: null,
+        phase: "handshake",
+        inFlight: 0,
+        timer: null,
+        onData: null,
+        children: new Set(),
+        closed: false,
+      };
+      connections.add(conn);
+      socket.once("close", () => closeConnection(conn));
+      if (typeof socket.setNoDelay === "function") socket.setNoDelay(true);
+      startTls(conn);
+    } catch {
+      socket.destroy();
+    }
+  };
+
+  const closeTask = (taskId: string): void => {
+    for (const conn of [...connections]) {
+      if (conn.taskId !== taskId) continue;
+      // Work under way (a request awaiting DNS or its upstream, a tunnel)
+      // ends because the task was revoked, and the audit says so, rather
+      // than reading as a transport failure or as nothing at all.
+      if (conn.phase === "active" || conn.phase === "tunnel") refuse(conn.taskId, conn.domain, "task_revoked");
+      closeConnection(conn);
+    }
+  };
+
+  const close = async (): Promise<void> => {
+    closing = true;
+    const open = [...connections];
+    const closed = open.map(
+      (conn) =>
+        new Promise<void>((resolve) => {
+          if (conn.raw.destroyed) resolve();
+          else conn.raw.once("close", () => resolve());
+        }),
+    );
+    for (const conn of open) closeConnection(conn);
+
+    await Promise.all(closed);
+  };
+
+  return { handleConnection, closeTask, close };
+}