@specific.dev/spectest 0.39.0 → 0.43.0

package/src/components/replayFake.ts

@@ -0,0 +1,1015 @@
+// 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 env eval` against 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.
+//
+// AWS SigV4 (`sign: { type: "awsSigv4", ... }`): static header injection
+// can't broker AWS auth — the `Authorization` value is a keyed HMAC over the
+// entire request, not a static token. So the forward instead RE-SIGNS: the
+// app signs with throwaway dummy creds (any AWS SDK refuses to build a request
+// with none), we strip that signature and re-sign the exact outbound request
+// with the real credentials (also direct secret refs, same eval-scoped push +
+// redaction). Region/service are inferred from the request. See
+// `../aws-sigv4.ts`.
+
+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";
+import {
+  inferSigV4Scope,
+  signAwsV4Request,
+  type SigV4Credentials,
+} from "../aws-sigv4.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>;
+}
+
+/** SigV4 request-signing broker. Unlike `inject` (which SETs a static header
+ *  value), this RE-SIGNS the outbound request: the app signs with throwaway
+ *  dummy credentials, we strip that signature and re-sign the exact outbound
+ *  request with the real credentials — the only way to broker AWS auth, whose
+ *  signature is a keyed HMAC over the whole request, not a static token.
+ *
+ *  The three fields are **secret refs, resolved directly** from the project's
+ *  Secrets store (NOT `{{secret:}}` templates) — same eval-scoped push and
+ *  fail-closed redaction as `inject`. Region + service are inferred from the
+ *  incoming request (its credential scope, else the host); the app never
+ *  configures them. */
+export interface AwsSigV4Sign {
+  type: "awsSigv4";
+  /** Secret ref for the AWS access key id. */
+  accessKeyId: string;
+  /** Secret ref for the AWS secret access key. */
+  secretAccessKey: string;
+  /** Optional secret ref for a session token (temporary credentials). */
+  sessionToken?: string;
+}
+
+export type SignConfig = AwsSigV4Sign;
+
+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[];
+  /** SigV4 request signing (AWS). When set, the record-mode forward strips the
+   *  app's dummy signature and re-signs the outbound request with the brokered
+   *  credentials. Point your AWS SDK at the real host with any dummy static
+   *  creds (e.g. `AWS_ACCESS_KEY_ID=test`) — the dummies are stripped and the
+   *  real ones live only on the outbound wire (redacted from the cassette). */
+  sign?: SignConfig;
+  /** 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;
+  /** Request body (omitted when empty): decoded + redacted UTF-8 text, or
+   *  base64 for binary payloads (S3 object PUTs, protobuf, …). */
+  body?: string;
+  /** Encoding of `body`. Absent = `"utf8"` (back-compat with old cassettes). */
+  bodyEncoding?: "utf8" | "base64";
+}
+
+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,
+  };
+}
+
+/** SigV4 puts per-request signing params (`X-Amz-Signature`, `X-Amz-Date`, …)
+ *  in the query for presigned URLs — they change every call and would poison
+ *  query matching, so they're dropped from both the match key and the forward
+ *  when signing is active. */
+function isAmzParam(key: string): boolean {
+  return key.toLowerCase().startsWith("x-amz-");
+}
+
+function stripAmzParams(search: URLSearchParams): URLSearchParams {
+  const out = new URLSearchParams();
+  for (const [k, v] of search) if (!isAmzParam(k)) out.append(k, v);
+  return out;
+}
+
+function normalizeQuery(search: URLSearchParams, stripAmz: boolean): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const key of [...search.keys()].sort()) {
+    if (stripAmz && isAmzParam(key)) continue;
+    out[key] = search.getAll(key).slice().sort();
+  }
+  return out;
+}
+
+function sha256Bytes(bytes: Uint8Array): string {
+  return "sha256:" + createHash("sha256").update(Buffer.from(bytes)).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 plus the
+ *  SigV4 signing credentials (direct refs, not templates). */
+function collectSecretRefs(rules: InjectRule[], sign: SignConfig | undefined): 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]);
+    }
+  }
+  if (sign?.type === "awsSigv4") {
+    refs.add(sign.accessKeyId);
+    refs.add(sign.secretAccessKey);
+    if (sign.sessionToken) refs.add(sign.sessionToken);
+  }
+  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: Uint8Array;
+}): 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(Buffer.from(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, opts.sign);
+
+  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,
+    bodyBytes: Uint8Array,
+    state: CassetteState,
+  ): Promise<Response> {
+    // Credential brokering (static header inject): first matching rule wins.
+    // Resolve its `{{secret:REF}}` tokens from the eval-scoped store.
+    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: [] };
+
+    // SigV4 signing: resolve the credential secret refs (direct refs, not
+    // `{{secret:}}` templates). Missing required refs fail loud alongside any
+    // missing inject refs.
+    let signCreds: SigV4Credentials | undefined;
+    const signMissing: string[] = [];
+    if (opts.sign?.type === "awsSigv4") {
+      const s = opts.sign;
+      const accessKeyId = getRecordSecret(s.accessKeyId);
+      const secretAccessKey = getRecordSecret(s.secretAccessKey);
+      const sessionToken = s.sessionToken ? getRecordSecret(s.sessionToken) : undefined;
+      if (accessKeyId === undefined) signMissing.push(s.accessKeyId);
+      if (secretAccessKey === undefined) signMissing.push(s.secretAccessKey);
+      if (s.sessionToken && sessionToken === undefined) signMissing.push(s.sessionToken);
+      if (accessKeyId !== undefined && secretAccessKey !== undefined) {
+        signCreds = { accessKeyId, secretAccessKey, sessionToken };
+      }
+    }
+
+    const missing = [...brokered.missing, ...signMissing];
+    if (missing.length > 0) {
+      const refs = [...new Set(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 env 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;
+
+    // SigV4 re-signing: strip the app's dummy signature and re-sign the exact
+    // outbound request (method/path/query/signed-headers/body-hash) with the
+    // brokered credentials, so `authorization`/`x-amz-date`/`x-amz-content-sha256`
+    // are internally consistent.
+    const signSecrets: ResolvedSecret[] = [];
+    let wireQuery = url.searchParams.toString();
+    if (opts.sign?.type === "awsSigv4" && signCreds) {
+      const scope = inferSigV4Scope({
+        authorization: req.headers.get("authorization"),
+        credentialParam: url.searchParams.get("X-Amz-Credential"),
+        host,
+      });
+      if (!scope) {
+        return new Response(
+          `replayFake(${opts.name}): could not infer the AWS region/service to sign ` +
+            `${reqLike.method} ${reqLike.path} (no SigV4 Credential on the request, and host ` +
+            `${JSON.stringify(host)} is not a <service>.<region>.amazonaws.com name).\n`,
+          { status: 599, headers: { "content-type": "text/plain" } },
+        );
+      }
+      // Drop the app's own (dummy-signed) signing headers before re-signing.
+      for (const h of ["authorization", "x-amz-date", "x-amz-content-sha256", "x-amz-security-token"]) {
+        delete fwdHeaders[h];
+      }
+      // Fold the app's remaining `x-amz-*`/content-type headers (e.g.
+      // `x-amz-target`) into the signature; they stay on the outbound wire.
+      const additionalHeaders: Record<string, string> = {};
+      for (const [k, v] of Object.entries(fwdHeaders)) {
+        if (
+          k === "content-type" ||
+          (k.startsWith("x-amz-") &&
+            k !== "x-amz-date" &&
+            k !== "x-amz-content-sha256" &&
+            k !== "x-amz-security-token")
+        ) {
+          additionalHeaders[k] = v;
+        }
+      }
+      const forwardParams = stripAmzParams(url.searchParams);
+      const signed = signAwsV4Request({
+        method: reqLike.method,
+        path: reqLike.path,
+        query: forwardParams,
+        host,
+        body: bodyBytes,
+        credentials: signCreds,
+        scope,
+        additionalHeaders,
+      });
+      for (const [k, v] of Object.entries(signed.headers)) fwdHeaders[k] = v;
+      // Send the canonical query we signed (URLSearchParams' `+`-for-space
+      // encoding would diverge from the signed `%20`).
+      wireQuery = signed.canonicalQuery;
+      signSecrets.push(
+        { ref: opts.sign.accessKeyId, value: signCreds.accessKeyId },
+        { ref: opts.sign.secretAccessKey, value: signCreds.secretAccessKey },
+      );
+      if (signCreds.sessionToken && opts.sign.sessionToken) {
+        signSecrets.push({ ref: opts.sign.sessionToken, value: signCreds.sessionToken });
+      }
+    }
+
+    const pathWithQuery = reqLike.path + (wireQuery ? `?${wireQuery}` : "");
+
+    let upstream: UpstreamResponse;
+    try {
+      upstream = await forwardToRealUpstream({
+        ip: ips[0],
+        host,
+        method: reqLike.method,
+        pathWithQuery,
+        headers: fwdHeaders,
+        body: bodyBytes,
+      });
+    } 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 redactSecrets = [...brokered.secrets, ...signSecrets];
+    const redact = makeRedactor(redactSecrets, 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,
+        ...(reqLike.body !== undefined
+          ? {
+              bodyHash: reqLike.bodyHash,
+              // Redact text bodies; leave base64 (binary) bodies verbatim — a
+              // secret is vanishingly unlikely to survive base64, and the
+              // fail-closed check below still catches it if it does.
+              body: reqLike.bodyEncoding === "base64" ? reqLike.body : redact(reqLike.body),
+              bodyEncoding: reqLike.bodyEncoding,
+            }
+          : {}),
+      },
+      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 redactSecrets) {
+      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 bodyBytes =
+      req.method === "GET" || req.method === "HEAD"
+        ? new Uint8Array(0)
+        : new Uint8Array(await req.arrayBuffer());
+    const decodedBody = bodyBytes.length > 0 ? decodeBody(bodyBytes) : undefined;
+    const reqLike: CassetteRequest = {
+      method: req.method.toUpperCase(),
+      path: url.pathname,
+      // Strip SigV4 `x-amz-*` query params from the match key when signing —
+      // presigned URLs carry a per-request signature there.
+      query: normalizeQuery(url.searchParams, opts.sign !== undefined),
+      headers: recordable(req.headers, ["content-type", ...(match.headers ?? [])]),
+      ...(decodedBody
+        ? {
+            bodyHash: sha256Bytes(bodyBytes),
+            body: decodedBody.body,
+            bodyEncoding: decodedBody.bodyEncoding,
+          }
+        : {}),
+    };
+
+    if (resolveMode() === "replay") return replay(reqLike, state);
+    return record(req, url, reqLike, bodyBytes, 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;
+}