@specific.dev/spectest 0.26.0 → 0.27.0

package/src/components/replayFake.ts

@@ -1,848 +0,0 @@
-// Record/replay fake — a VCR-style cassette fake.
-//
-// `replayFake({...})` returns a plain `FakeDefinition`, so it drops
-// straight into `fakes: { stripe: replayFake({...}) }` and inherits all
-// the existing fakes machinery: ingress lowering mints the TLS leaf cert
-// and registers the hostname, dispatch routes by `Host` header to the
-// generated `handler`, and `state` forks per test like any fake.
-//
-// You fake the REAL host directly — `host: "api.stripe.com"`, not a
-// stand-in. The fake answers for that name on both `http://` (:80) and
-// `https://` (:443, in-VM-CA leaf cert), and the SAME name is what gets
-// forwarded to the real upstream in record mode. The two modes:
-//
-//   - REPLAY (hermetic): the request is matched against the cassette the
-//     test EXPLICITLY loaded (`ctx.fakes.<name>.replay(file)`) and the
-//     recorded response is returned. No network. Nothing is auto-loaded:
-//     a test that loads no cassette gets a fail-loud 599 on every request.
-//     This is what runs under `spectest test`.
-//   - RECORD (MITM): the request is forwarded to the REAL host and the
-//     request/response pair is captured (decoded, redacted), and the real
-//     response is returned to the app so a manual session behaves like
-//     production. This runs under `spectest_eval` / a manual env.
-//
-// Because the fake's hostname IS the real host, the in-VM resolver points
-// that name at the daemon — so a naive `fetch("https://api.stripe.com")`
-// from the record-mode forwarder would loop straight back into us. The
-// forwarder therefore resolves the real IP itself against an EXTERNAL DNS
-// server (default 1.1.1.1, `SPECTEST_UPSTREAM_DNS`), then opens a real TLS
-// connection to that IP with the correct SNI/`Host` (validating the real
-// public cert). This is a transparent MITM: the app's leg is terminated
-// with our in-VM-CA leaf; the upstream leg is a genuine public-cert TLS
-// handshake to the real host.
-//
-// Mode is chosen by `isRecording()`: it is true only inside an active
-// recorder (a `spectest test` case), false in eval/manual. So `auto`
-// (the default) replays under test and records under eval — no new
-// control-plane mode flag. `mode: "record" | "replay"` overrides it.
-//
-// Credential brokering (per-fake): `inject` rules set
-// headers on the egress forward — overwriting whatever the app sent — so
-// app code never holds the credential. Header values embed `{{secret:REF}}`
-// tokens; each REF is resolved server-side from the platform Secrets store
-// and pushed eval-scoped from the control plane (via {@link getRecordSecret}).
-// The real value lives only on the outbound wire to the real upstream and
-// is redacted from the cassette (fail-closed) — it never enters project
-// code, the tarball, the warm-cache hash, or any snapshot a hermetic run
-// could fork.
-
-import { createSocket } from "node:dgram";
-import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
-import { request as httpsRequest } from "node:https";
-import path from "node:path";
-import { brotliDecompressSync, gunzipSync, inflateSync } from "node:zlib";
-import * as dnsPacket from "dns-packet";
-
-import type { FakeContext, FakeDefinition } from "../index.js";
-import { isRecording } from "../recorder.js";
-import { getRecordSecret } from "../record-secrets.js";
-
-// ────────────────────────────────────────────────────────────────────────
-// Options + cassette format
-// ────────────────────────────────────────────────────────────────────────
-
-/** Which parts of a request define a match against the cassette. */
-export interface ReplayMatch {
-  /** Match on HTTP method. Default `true`. */
-  method?: boolean;
-  /** Match on path (no query). Default `true`. */
-  path?: boolean;
-  /** Match on normalized query string. Default `true`. */
-  query?: boolean;
-  /** Match on body: `true` = exact decoded body, `"hash"` = sha256 only.
-   *  Default off. */
-  body?: boolean | "hash";
-  /** Header names (lowercase) to include in the match. Default none. */
-  headers?: string[];
-}
-
-/** Match one request dimension. A bare string is an exact match; the
- *  object forms cover prefix and regex matching. */
-export type StringMatch =
-  | string
-  | { exact: string }
-  | { startsWith: string }
-  | { regex: string };
-
-/** Request matchers for a credential-injection rule. A rule applies only
- *  when EVERY specified dimension matches; omit `match` to always apply. */
-export interface InjectMatch {
-  /** Match the request path (no query). */
-  path?: StringMatch;
-  /** HTTP method(s) — any one matching satisfies it. */
-  method?: string | string[];
-  /** Query-param matchers (ANDed); each key's value(s) must match. */
-  query?: Record<string, StringMatch>;
-  /** Header matchers (ANDed; header names case-insensitive). */
-  headers?: Record<string, StringMatch>;
-}
-
-/** One credential-brokering rule. When it matches a request, these headers
- *  are SET on the egress forward — overwriting whatever the app sent (so app
- *  code can't smuggle a different value past the broker). Header VALUES may
- *  embed `{{secret:REF}}` tokens; each `REF` is resolved server-side from the
- *  project's Secrets store and pushed eval-scoped — the real value never
- *  enters project code, the
- *  tarball, the warm-cache hash, or a cassette (it's redacted, fail-closed). */
-export interface InjectRule {
-  match?: InjectMatch;
-  headers: Record<string, string>;
-}
-
-export interface ReplayFakeOptions {
-  /** Stable name — the `ctx.fakes` key. */
-  name: string;
-  /** The REAL host to fake, e.g. `"api.stripe.com"`. The fake answers for
-   *  this name on both `http://` (:80) and `https://` (:443), and the same
-   *  name is forwarded to the real upstream in record mode (over HTTPS,
-   *  resolved via an external DNS server — see the module header). Your
-   *  app points at this real host directly; no separate stand-in. */
-  host: string;
-  /** What defines a request match. Default `{ method, path, query }`. */
-  match?: ReplayMatch;
-  /** Per-fake credential brokering. Rules are evaluated in
-   *  order; the first whose `match` matches wins (a rule without `match`
-   *  matches everything and shadows later rules). Applied at the
-   *  record-mode egress forward; resolved secret values are redacted from
-   *  the cassette (fail-closed). */
-  inject?: InjectRule[];
-  /** Extra substrings/patterns to scrub from stored request/response
-   *  bodies and queries (every injected secret value is always scrubbed). */
-  redactPatterns?: (string | RegExp)[];
-  /** `"auto"` (default) records under eval and replays under test;
-   *  `"record"` / `"replay"` force a mode. */
-  mode?: "auto" | "record" | "replay";
-}
-
-export interface CassetteRequest {
-  method: string;
-  path: string;
-  /** Normalized: keys + repeated values sorted, so matching is order-free. */
-  query: Record<string, string[]>;
-  /** Matched/readable header subset only — never `authorization`/`cookie`. */
-  headers: Record<string, string>;
-  bodyHash?: string;
-  /** Decoded + redacted request body (omitted when empty). */
-  body?: string;
-}
-
-export interface CassetteResponse {
-  status: number;
-  headers: Record<string, string>;
-  /** Decoded + redacted response body. */
-  body: string;
-  bodyEncoding: "utf8" | "base64";
-}
-
-export interface CassetteInteraction {
-  request: CassetteRequest;
-  response: CassetteResponse;
-}
-
-export interface Cassette {
-  version: 1;
-  fake: string;
-  /** The real host this cassette mirrors (e.g. `api.stripe.com`). */
-  host: string;
-  interactions: CassetteInteraction[];
-}
-
-/** Forked-per-test state for one replay fake. */
-export interface CassetteState {
-  cassette: Cassette;
-  /** Per-match-signature replay cursor (call-order sequencing). */
-  cursor: Map<string, number>;
-  /** Interactions captured this record session. */
-  recorded: CassetteInteraction[];
-  dirty: boolean;
-}
-
-/** What `replay(...)` returns — a small summary that surfaces in the test
- *  timeline (recorded as a `fake` event) so the run shows exactly which
- *  cassette a test loaded and how many interactions it carried. */
-export interface ReplaySummary {
-  /** Filename loaded (under `spectest/recordings/`) or `"(inline)"`. */
-  cassette: string;
-  /** The real host the cassette mirrors. */
-  host: string;
-  /** Number of interactions now available for replay. */
-  interactions: number;
-}
-
-export interface ReplayHelpers extends Record<string, unknown> {
-  /** Load a cassette into THIS fork's replay set and replay from it,
-   *  replacing whatever was loaded before and resetting the replay cursor.
-   *  Cassettes are NOT auto-loaded — call this at the top of a test. Pass a
-   *  path relative to `spectest/tests/` (e.g. `"recordings/stripe.json"`; it
-   *  must stay under `spectest/tests/`) or a cassette object; a missing file
-   *  throws. The returned summary is recorded as a step, so the UI timeline
-   *  shows what was loaded. */
-  replay(file: string | Cassette): ReplaySummary;
-  /** Full cassette JSON (loaded interactions + newly recorded, redacted)
-   *  — the MVP delivery channel: `export default ctx.fakes.<name>.dump()`,
-   *  then write the result to `spectest/recordings/<name>.json`. */
-  dump(): Cassette;
-  /** Interactions captured this record session. */
-  recorded(): CassetteInteraction[];
-  /** Count of interactions captured this record session. */
-  count(): number;
-}
-
-// ────────────────────────────────────────────────────────────────────────
-// Helpers
-// ────────────────────────────────────────────────────────────────────────
-
-const SENSITIVE_HEADERS = new Set([
-  "authorization",
-  "cookie",
-  "set-cookie",
-  "proxy-authorization",
-  "x-api-key",
-  "x-amz-security-token",
-]);
-
-/** Hop-by-hop + body-framing headers never forwarded / never replayed
- *  (we decompress on the way through, so the encoding/length no longer
- *  describe the bytes the app receives). */
-const STRIP_FORWARD_HEADERS = new Set([
-  "host",
-  "connection",
-  "keep-alive",
-  "proxy-authenticate",
-  "proxy-authorization",
-  "te",
-  "trailers",
-  "transfer-encoding",
-  "upgrade",
-  "content-length",
-  "content-encoding",
-  // We force `accept-encoding: identity` on the forward and decompress any
-  // residual encoding, so the app never sees a stale accept-encoding.
-  "accept-encoding",
-]);
-
-/** External resolver used to find the REAL upstream IP, bypassing the in-VM
- *  resolver (which points the faked host back at the daemon). */
-const EXTERNAL_DNS = process.env.SPECTEST_UPSTREAM_DNS ?? "1.1.1.1";
-const EXTERNAL_DNS_PORT = Number(process.env.SPECTEST_UPSTREAM_PORT ?? "53");
-
-function defaultMatch(m: ReplayMatch | undefined): Required<Omit<ReplayMatch, "body" | "headers">> &
-  Pick<ReplayMatch, "body" | "headers"> {
-  return {
-    method: m?.method ?? true,
-    path: m?.path ?? true,
-    query: m?.query ?? true,
-    body: m?.body,
-    headers: m?.headers,
-  };
-}
-
-function normalizeQuery(search: URLSearchParams): Record<string, string[]> {
-  const out: Record<string, string[]> = {};
-  for (const key of [...search.keys()].sort()) {
-    out[key] = search.getAll(key).slice().sort();
-  }
-  return out;
-}
-
-function sha256(s: string): string {
-  return "sha256:" + createHash("sha256").update(s).digest("hex");
-}
-
-function recordable(headers: Headers, want: string[]): Record<string, string> {
-  const out: Record<string, string> = {};
-  for (const name of want) {
-    const lower = name.toLowerCase();
-    if (SENSITIVE_HEADERS.has(lower)) continue;
-    const v = headers.get(lower);
-    if (v !== null) out[lower] = v;
-  }
-  return out;
-}
-
-/** Canonical match signature for an interaction's request, used as both
- *  the replay-cursor key and the equality basis (two requests match iff
- *  their signatures are equal). Computed identically for an incoming
- *  request and a stored `CassetteRequest`. */
-function signature(req: CassetteRequest, match: ReturnType<typeof defaultMatch>): string {
-  const sig: Record<string, unknown> = {};
-  if (match.method) sig.method = req.method.toUpperCase();
-  if (match.path) sig.path = req.path;
-  if (match.query) sig.query = req.query;
-  if (match.body === true) sig.body = req.body ?? "";
-  else if (match.body === "hash") sig.bodyHash = req.bodyHash ?? "";
-  if (match.headers && match.headers.length > 0) {
-    const h: Record<string, string> = {};
-    for (const name of match.headers.map((n) => n.toLowerCase()).sort()) {
-      h[name] = req.headers[name] ?? "";
-    }
-    sig.headers = h;
-  }
-  return JSON.stringify(sig);
-}
-
-/** The project's `spectest/tests/` dir — cassettes live alongside the
- *  tests, and a `replay(path)` argument is a path relative to here. Keeping
- *  them under `tests/` means re-recording is picked up on the next run with
- *  no environment rebuild (that subtree is re-imported with the tests). */
-function cassetteRoot(): string {
-  const spectestDir =
-    process.env.SPECTEST_PROJECT_DIR ??
-    path.join(process.env.SPECTEST_APP_DIR ?? "/opt/spectest/app", "spectest");
-  return path.join(spectestDir, "tests");
-}
-
-function emptyCassette(name: string, host: string): Cassette {
-  return { version: 1, fake: name, host, interactions: [] };
-}
-
-/** Validate + normalize a parsed cassette (from a file or passed inline). */
-function coerceCassette(parsed: Cassette, name: string, host: string): Cassette {
-  if (!parsed || !Array.isArray(parsed.interactions)) {
-    throw new Error(`replayFake(${name}): cassette has no \`interactions\` array`);
-  }
-  return {
-    version: 1,
-    fake: parsed.fake ?? name,
-    host: parsed.host ?? host,
-    interactions: parsed.interactions,
-  };
-}
-
-/** Read a cassette by its path relative to `spectest/tests/` (e.g.
- *  `"recordings/stripe.json"`). The path must stay under `spectest/tests/`,
- *  and explicit loads must point at a real file — a missing one throws (fail
- *  loud) rather than silently replaying nothing. */
-function readCassetteFile(name: string, file: string, host: string): Cassette {
-  const base = cassetteRoot();
-  const p = path.resolve(base, file);
-  if (p !== base && !p.startsWith(base + path.sep)) {
-    throw new Error(
-      `replayFake(${name}): cassette path ${JSON.stringify(file)} must be under spectest/tests/`,
-    );
-  }
-  if (!existsSync(p)) {
-    throw new Error(
-      `replayFake(${name}): cassette not found at ${p} — record one first, or pass a cassette object.`,
-    );
-  }
-  let parsed: Cassette;
-  try {
-    parsed = JSON.parse(readFileSync(p, "utf8")) as Cassette;
-  } catch (err) {
-    throw new Error(
-      `replayFake(${name}): failed to read cassette ${p}: ${(err as Error).message}`,
-    );
-  }
-  return coerceCassette(parsed, name, host);
-}
-
-/** Decode response bytes to a string, falling back to base64 for binary. */
-function decodeBody(bytes: Uint8Array): { body: string; bodyEncoding: "utf8" | "base64" } {
-  try {
-    const text = new TextDecoder("utf8", { fatal: true }).decode(bytes);
-    return { body: text, bodyEncoding: "utf8" };
-  } catch {
-    return { body: Buffer.from(bytes).toString("base64"), bodyEncoding: "base64" };
-  }
-}
-
-/** One resolved secret value and the ref it came from (for the redaction
- *  placeholder). */
-interface ResolvedSecret {
-  ref: string;
-  value: string;
-}
-
-function makeRedactor(
-  secrets: ResolvedSecret[],
-  patterns: (string | RegExp)[] | undefined,
-): (s: string) => string {
-  return (s: string): string => {
-    let out = s;
-    for (const { ref, value } of secrets) {
-      if (value.length > 0) out = out.split(value).join(`<REDACTED:${ref}>`);
-    }
-    for (const p of patterns ?? []) {
-      if (typeof p === "string") {
-        if (p.length > 0) out = out.split(p).join("<REDACTED>");
-      } else {
-        const g = p.flags.includes("g") ? p : new RegExp(p.source, p.flags + "g");
-        out = out.replace(g, "<REDACTED>");
-      }
-    }
-    return out;
-  };
-}
-
-// ────────────────────────────────────────────────────────────────────────
-// Credential brokering: matchers + secret-token resolution
-// ────────────────────────────────────────────────────────────────────────
-
-/** `{{secret:REF}}` template token embedded in an injected header value. */
-const SECRET_TOKEN = /\{\{secret:([A-Za-z0-9_]+)\}\}/g;
-
-/** Every secret ref referenced by any inject rule's header templates. */
-function collectSecretRefs(rules: InjectRule[]): string[] {
-  const refs = new Set<string>();
-  for (const rule of rules) {
-    for (const value of Object.values(rule.headers)) {
-      for (const m of value.matchAll(SECRET_TOKEN)) refs.add(m[1]);
-    }
-  }
-  return [...refs];
-}
-
-function matchString(m: StringMatch, value: string): boolean {
-  if (typeof m === "string") return value === m;
-  if ("exact" in m) return value === m.exact;
-  if ("startsWith" in m) return value.startsWith(m.startsWith);
-  if ("regex" in m) return new RegExp(m.regex).test(value);
-  return false;
-}
-
-interface IncomingRequest {
-  method: string;
-  path: string;
-  query: URLSearchParams;
-  headers: Headers;
-}
-
-/** True if every dimension the matcher specifies is satisfied (AND across
- *  dimensions). No `match` → always true. */
-function ruleMatches(match: InjectMatch | undefined, req: IncomingRequest): boolean {
-  if (!match) return true;
-  if (match.path !== undefined && !matchString(match.path, req.path)) return false;
-  if (match.method !== undefined) {
-    const methods = (Array.isArray(match.method) ? match.method : [match.method]).map((s) =>
-      s.toUpperCase(),
-    );
-    if (!methods.includes(req.method.toUpperCase())) return false;
-  }
-  if (match.query) {
-    for (const [k, m] of Object.entries(match.query)) {
-      if (!req.query.getAll(k).some((v) => matchString(m, v))) return false;
-    }
-  }
-  if (match.headers) {
-    for (const [k, m] of Object.entries(match.headers)) {
-      const v = req.headers.get(k.toLowerCase());
-      if (v === null || !matchString(m, v)) return false;
-    }
-  }
-  return true;
-}
-
-interface BrokeredHeaders {
-  /** Lowercased header → resolved value, to SET on the forward. */
-  headers: Record<string, string>;
-  /** Resolved secrets (for redaction). */
-  secrets: ResolvedSecret[];
-  /** Refs referenced but not supplied by the control plane. */
-  missing: string[];
-}
-
-/** Resolve a rule's header templates, substituting every `{{secret:REF}}`
- *  with the eval-scoped value. Collects resolved secrets (for redaction)
- *  and any refs the control plane didn't supply (fail loud). */
-function brokerHeaders(rule: InjectRule): BrokeredHeaders {
-  const headers: Record<string, string> = {};
-  const secrets: ResolvedSecret[] = [];
-  const missing: string[] = [];
-  const seen = new Set<string>();
-  for (const [name, template] of Object.entries(rule.headers)) {
-    headers[name.toLowerCase()] = template.replace(SECRET_TOKEN, (_full, ref: string) => {
-      const value = getRecordSecret(ref);
-      if (value === undefined) {
-        missing.push(ref);
-        return "";
-      }
-      if (!seen.has(ref)) {
-        seen.add(ref);
-        secrets.push({ ref, value });
-      }
-      return value;
-    });
-  }
-  return { headers, secrets, missing };
-}
-
-// ────────────────────────────────────────────────────────────────────────
-// Record-mode egress: resolve the real host externally, then MITM-forward
-// ────────────────────────────────────────────────────────────────────────
-
-/** Resolve a host's A records against an EXTERNAL DNS server, bypassing the
- *  in-VM resolver (which would answer with the daemon's own gateway for a
- *  faked host). Mirrors spectest-resolver's own upstream-forward transport
- *  (dns-packet over UDP) so it works identically in-VM. */
-function resolveExternalA(host: string): Promise<string[]> {
-  const query = dnsPacket.encode({
-    type: "query",
-    id: 1,
-    flags: dnsPacket.RECURSION_DESIRED,
-    questions: [{ type: "A", name: host }],
-  });
-  return new Promise((resolve) => {
-    const sock = createSocket("udp4");
-    let done = false;
-    const finish = (ips: string[]): void => {
-      if (done) return;
-      done = true;
-      try {
-        sock.close();
-      } catch {
-        // ignore
-      }
-      resolve(ips);
-    };
-    sock.on("message", (msg) => {
-      try {
-        const res = dnsPacket.decode(msg);
-        const ips = (res.answers ?? []).flatMap((a) =>
-          a.type === "A" && typeof a.data === "string" && a.data.length > 0 ? [a.data] : [],
-        );
-        finish(ips);
-      } catch {
-        finish([]);
-      }
-    });
-    sock.on("error", () => finish([]));
-    sock.send(query, EXTERNAL_DNS_PORT, EXTERNAL_DNS, (err) => {
-      if (err) finish([]);
-    });
-    setTimeout(() => finish([]), 3_000);
-  });
-}
-
-interface UpstreamResponse {
-  status: number;
-  headers: Record<string, string>;
-  /** Decompressed body bytes. */
-  bytes: Uint8Array;
-}
-
-/** Open a real HTTPS connection to `ip` but with SNI + `Host` = `host`, so
- *  the public certificate validates against the real hostname (the in-VM CA
- *  is not involved on this leg). Decompresses the response so the stored and
- *  returned bytes are the plain payload. */
-function forwardToRealUpstream(args: {
-  ip: string;
-  host: string;
-  method: string;
-  pathWithQuery: string;
-  headers: Record<string, string>;
-  body: string;
-}): Promise<UpstreamResponse> {
-  return new Promise((resolve, reject) => {
-    const req = httpsRequest(
-      {
-        host: args.ip,
-        port: 443,
-        method: args.method,
-        path: args.pathWithQuery,
-        servername: args.host,
-        headers: { ...args.headers, host: args.host, "accept-encoding": "identity" },
-      },
-      (res) => {
-        const chunks: Buffer[] = [];
-        res.on("data", (c: Buffer) => chunks.push(c));
-        res.on("end", () => {
-          let bytes: Uint8Array = Buffer.concat(chunks);
-          const enc = String(res.headers["content-encoding"] ?? "").toLowerCase();
-          try {
-            if (enc.includes("br")) bytes = brotliDecompressSync(bytes);
-            else if (enc.includes("gzip")) bytes = gunzipSync(bytes);
-            else if (enc.includes("deflate")) bytes = inflateSync(bytes);
-          } catch {
-            // Leave the bytes as-is if decompression fails.
-          }
-          const headers: Record<string, string> = {};
-          for (const [k, v] of Object.entries(res.headers)) {
-            if (typeof v === "string") headers[k.toLowerCase()] = v;
-            else if (Array.isArray(v)) headers[k.toLowerCase()] = v.join(", ");
-          }
-          resolve({ status: res.statusCode ?? 0, headers, bytes });
-        });
-        res.on("error", reject);
-      },
-    );
-    req.on("error", reject);
-    if (args.body.length > 0) req.write(args.body);
-    req.end();
-  });
-}
-
-// ────────────────────────────────────────────────────────────────────────
-// replayFake
-// ────────────────────────────────────────────────────────────────────────
-
-export function replayFake(
-  opts: ReplayFakeOptions,
-): FakeDefinition<CassetteState, ReplayHelpers> {
-  if (!opts.name) throw new Error("replayFake: `name` is required");
-  if (!opts.host || typeof opts.host !== "string") {
-    throw new Error(`replayFake(${opts.name}): "host" (the real hostname) is required`);
-  }
-  const host = opts.host.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
-  const match = defaultMatch(opts.match);
-  const injectRules = opts.inject ?? [];
-  // Refs every header template references — the control plane resolves these
-  // server-side and pushes them eval-scoped (see the daemon's
-  // /record-secret-refs endpoint, which reads `def.secretRefs`).
-  const secretRefs = collectSecretRefs(injectRules);
-
-  const resolveMode = (): "record" | "replay" => {
-    if (opts.mode === "record") return "record";
-    if (opts.mode === "replay") return "replay";
-    return isRecording() ? "replay" : "record";
-  };
-
-  // ── REPLAY ──────────────────────────────────────────────────────────
-  function replay(reqLike: CassetteRequest, state: CassetteState): Response {
-    const sig = signature(reqLike, match);
-    const matches: CassetteInteraction[] = [];
-    for (const it of state.cassette.interactions) {
-      if (signature(it.request, match) === sig) matches.push(it);
-    }
-    const idx = state.cursor.get(sig) ?? 0;
-    const hit = matches[idx];
-    if (!hit) {
-      const body =
-        `replayFake(${opts.name}): no cassette interaction for ` +
-        `${reqLike.method} ${reqLike.path} (matched ${matches.length}, wanted #${idx + 1}). ` +
-        `Re-record the cassette, or relax \`match\`.\n`;
-      return new Response(body, {
-        status: 599,
-        headers: { "content-type": "text/plain" },
-      });
-    }
-    state.cursor.set(sig, idx + 1);
-    const headers = new Headers(hit.response.headers);
-    const payload =
-      hit.response.bodyEncoding === "base64"
-        ? Buffer.from(hit.response.body, "base64")
-        : hit.response.body;
-    return new Response(payload, { status: hit.response.status, headers });
-  }
-
-  // ── RECORD (MITM) ───────────────────────────────────────────────────
-  async function record(
-    req: Request,
-    url: URL,
-    reqLike: CassetteRequest,
-    rawBody: string,
-    state: CassetteState,
-  ): Promise<Response> {
-    // Credential brokering: first matching inject rule wins. Resolve its
-    // `{{secret:REF}}` tokens from the eval-scoped store; a
-    // referenced-but-unsupplied ref fails loud.
-    const rule = injectRules.find((r) =>
-      ruleMatches(r.match, {
-        method: reqLike.method,
-        path: reqLike.path,
-        query: url.searchParams,
-        headers: req.headers,
-      }),
-    );
-    const brokered = rule ? brokerHeaders(rule) : { headers: {}, secrets: [], missing: [] };
-    if (brokered.missing.length > 0) {
-      const refs = [...new Set(brokered.missing)];
-      return new Response(
-        `replayFake(${opts.name}): secret(s) ${JSON.stringify(refs)} were not supplied ` +
-          `(configure them on the project's Secrets page, and record via spectest_eval).\n`,
-        { status: 599, headers: { "content-type": "text/plain" } },
-      );
-    }
-
-    // Resolve the REAL host's IP via an external resolver so we don't loop
-    // back into the daemon (the in-VM resolver answers our own gateway for
-    // this faked name). See the module header.
-    const ips = await resolveExternalA(host);
-    if (ips.length === 0) {
-      return new Response(
-        `replayFake(${opts.name}): could not resolve real upstream ${JSON.stringify(host)} ` +
-          `via external DNS ${EXTERNAL_DNS} (is the VM online?).\n`,
-        { status: 599, headers: { "content-type": "text/plain" } },
-      );
-    }
-
-    // Forward headers: drop hop-by-hop/encoding, then SET the brokered
-    // headers — overwriting whatever the app sent (so the credential can't
-    // be smuggled or spoofed by app code). The real values only ever appear
-    // on this outbound wire.
-    const fwdHeaders: Record<string, string> = {};
-    req.headers.forEach((v, k) => {
-      if (!STRIP_FORWARD_HEADERS.has(k.toLowerCase())) fwdHeaders[k.toLowerCase()] = v;
-    });
-    for (const [k, v] of Object.entries(brokered.headers)) fwdHeaders[k] = v;
-
-    const search = url.searchParams.toString();
-    const pathWithQuery = reqLike.path + (search ? `?${search}` : "");
-
-    let upstream: UpstreamResponse;
-    try {
-      upstream = await forwardToRealUpstream({
-        ip: ips[0],
-        host,
-        method: reqLike.method,
-        pathWithQuery,
-        headers: fwdHeaders,
-        body: rawBody,
-      });
-    } catch (err) {
-      return new Response(
-        `replayFake(${opts.name}): forward to real ${host} (${ips[0]}) failed: ${(err as Error).message}\n`,
-        { status: 599, headers: { "content-type": "text/plain" } },
-      );
-    }
-
-    // Decode + redact for storage; return the real (un-redacted) bytes to
-    // the app so the manual session behaves like production.
-    const redact = makeRedactor(brokered.secrets, opts.redactPatterns);
-    const decoded = decodeBody(upstream.bytes);
-    const respHeaders: Record<string, string> = {};
-    for (const [k, v] of Object.entries(upstream.headers)) {
-      if (SENSITIVE_HEADERS.has(k) || STRIP_FORWARD_HEADERS.has(k)) continue;
-      respHeaders[k] = v;
-    }
-
-    const redactedQuery: Record<string, string[]> = {};
-    for (const [k, vs] of Object.entries(reqLike.query)) {
-      redactedQuery[k] = vs.map(redact);
-    }
-    const interaction: CassetteInteraction = {
-      request: {
-        method: reqLike.method,
-        path: reqLike.path,
-        query: redactedQuery,
-        headers: reqLike.headers,
-        ...(rawBody.length > 0
-          ? { bodyHash: reqLike.bodyHash, body: redact(rawBody) }
-          : {}),
-      },
-      response: {
-        status: upstream.status,
-        headers: respHeaders,
-        body: decoded.bodyEncoding === "utf8" ? redact(decoded.body) : decoded.body,
-        bodyEncoding: decoded.bodyEncoding,
-      },
-    };
-
-    // Fail-closed: never persist a cassette that still carries any raw
-    // secret value (a missed redaction is a leak, not a warning).
-    const serialized = JSON.stringify(interaction);
-    for (const { ref, value } of brokered.secrets) {
-      if (value.length > 0 && serialized.includes(value)) {
-        throw new Error(
-          `replayFake(${opts.name}): refusing to record — the value for secret ${JSON.stringify(ref)} ` +
-            `survived redaction into the interaction for ${reqLike.method} ${reqLike.path}. ` +
-            `Add a redactPatterns entry.`,
-        );
-      }
-    }
-
-    state.recorded.push(interaction);
-    state.dirty = true;
-
-    return new Response(upstream.bytes as unknown as BodyInit, {
-      status: upstream.status,
-      headers: new Headers(respHeaders),
-    });
-  }
-
-  // ── handler ─────────────────────────────────────────────────────────
-  const handler = async (
-    req: Request,
-    state: CassetteState,
-    _ctx: FakeContext,
-  ): Promise<Response> => {
-    const url = new URL(req.url);
-    const rawBody = req.method === "GET" || req.method === "HEAD" ? "" : await req.text();
-    const reqLike: CassetteRequest = {
-      method: req.method.toUpperCase(),
-      path: url.pathname,
-      query: normalizeQuery(url.searchParams),
-      headers: recordable(req.headers, ["content-type", ...(match.headers ?? [])]),
-      ...(rawBody.length > 0 ? { bodyHash: sha256(rawBody) } : {}),
-    };
-
-    if (resolveMode() === "replay") return replay(reqLike, state);
-    return record(req, url, reqLike, rawBody, state);
-  };
-
-  const def: FakeDefinition<CassetteState, ReplayHelpers> = {
-    name: opts.name,
-    // Fake = real: we answer for the real host on :80 and :443.
-    hostnames: [host],
-    secretRefs,
-    // Cassettes are NOT auto-loaded — a fork starts with an empty replay
-    // set, so a test that loads nothing fails loud (599). Tests call
-    // `replay(...)` to populate it.
-    state: (): CassetteState => ({
-      cassette: emptyCassette(opts.name, host),
-      cursor: new Map(),
-      recorded: [],
-      dirty: false,
-    }),
-    handler,
-    helpers: ({ state }): ReplayHelpers => ({
-      replay(file: string | Cassette): ReplaySummary {
-        let loaded: Cassette;
-        let label: string;
-        if (file && typeof file === "object") {
-          loaded = coerceCassette(file, opts.name, host);
-          label = file.fake || "(inline)";
-        } else if (typeof file === "string" && file.length > 0) {
-          label = file;
-          loaded = readCassetteFile(opts.name, file, host);
-        } else {
-          throw new Error(
-            `replayFake(${opts.name}): replay(...) needs a cassette path under spectest/tests/ ` +
-              `(e.g. "recordings/${opts.name}.json").`,
-          );
-        }
-        // Mutate the live state object (the handler reads the same
-        // reference); reset the cursor so replay starts from the top.
-        state.cassette = loaded;
-        state.cursor = new Map();
-        return { cassette: label, host: loaded.host, interactions: loaded.interactions.length };
-      },
-      dump(): Cassette {
-        return {
-          version: 1,
-          fake: opts.name,
-          host,
-          interactions: [...state.cassette.interactions, ...state.recorded],
-        };
-      },
-      recorded(): CassetteInteraction[] {
-        return state.recorded.slice();
-      },
-      count(): number {
-        return state.recorded.length;
-      },
-    }),
-  };
-  return def;
-}