@specific.dev/spectest 0.24.0 → 0.27.0

package/dist/components/replayFake.js

@@ -0,0 +1,738 @@
+// 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.
+//
+// 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 { isRecording } from "../recorder.js";
+import { getRecordSecret } from "../record-secrets.js";
+import { inferSigV4Scope, signAwsV4Request, } from "../aws-sigv4.js";
+// ────────────────────────────────────────────────────────────────────────
+// 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) {
+    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) {
+    return key.toLowerCase().startsWith("x-amz-");
+}
+function stripAmzParams(search) {
+    const out = new URLSearchParams();
+    for (const [k, v] of search)
+        if (!isAmzParam(k))
+            out.append(k, v);
+    return out;
+}
+function normalizeQuery(search, stripAmz) {
+    const out = {};
+    for (const key of [...search.keys()].sort()) {
+        if (stripAmz && isAmzParam(key))
+            continue;
+        out[key] = search.getAll(key).slice().sort();
+    }
+    return out;
+}
+function sha256Bytes(bytes) {
+    return "sha256:" + createHash("sha256").update(Buffer.from(bytes)).digest("hex");
+}
+function recordable(headers, want) {
+    const out = {};
+    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, match) {
+    const sig = {};
+    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 = {};
+        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() {
+    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, host) {
+    return { version: 1, fake: name, host, interactions: [] };
+}
+/** Validate + normalize a parsed cassette (from a file or passed inline). */
+function coerceCassette(parsed, name, host) {
+    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, file, host) {
+    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;
+    try {
+        parsed = JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`replayFake(${name}): failed to read cassette ${p}: ${err.message}`);
+    }
+    return coerceCassette(parsed, name, host);
+}
+/** Decode response bytes to a string, falling back to base64 for binary. */
+function decodeBody(bytes) {
+    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" };
+    }
+}
+function makeRedactor(secrets, patterns) {
+    return (s) => {
+        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, sign) {
+    const refs = new Set();
+    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, value) {
+    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;
+}
+/** True if every dimension the matcher specifies is satisfied (AND across
+ *  dimensions). No `match` → always true. */
+function ruleMatches(match, req) {
+    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;
+}
+/** 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) {
+    const headers = {};
+    const secrets = [];
+    const missing = [];
+    const seen = new Set();
+    for (const [name, template] of Object.entries(rule.headers)) {
+        headers[name.toLowerCase()] = template.replace(SECRET_TOKEN, (_full, ref) => {
+            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) {
+    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) => {
+            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);
+    });
+}
+/** 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) {
+    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 = [];
+            res.on("data", (c) => chunks.push(c));
+            res.on("end", () => {
+                let bytes = 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 = {};
+                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) {
+    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 = () => {
+        if (opts.mode === "record")
+            return "record";
+        if (opts.mode === "replay")
+            return "replay";
+        return isRecording() ? "replay" : "record";
+    };
+    // ── REPLAY ──────────────────────────────────────────────────────────
+    function replay(reqLike, state) {
+        const sig = signature(reqLike, match);
+        const matches = [];
+        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, url, reqLike, bodyBytes, state) {
+        // 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;
+        const signMissing = [];
+        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_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 = {};
+        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 = [];
+        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 = {};
+            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;
+        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.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 = {};
+        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 = {};
+        for (const [k, vs] of Object.entries(reqLike.query)) {
+            redactedQuery[k] = vs.map(redact);
+        }
+        const interaction = {
+            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, {
+            status: upstream.status,
+            headers: new Headers(respHeaders),
+        });
+    }
+    // ── handler ─────────────────────────────────────────────────────────
+    const handler = async (req, state, _ctx) => {
+        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 = {
+            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 = {
+        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: () => ({
+            cassette: emptyCassette(opts.name, host),
+            cursor: new Map(),
+            recorded: [],
+            dirty: false,
+        }),
+        handler,
+        helpers: ({ state }) => ({
+            replay(file) {
+                let loaded;
+                let label;
+                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() {
+                return {
+                    version: 1,
+                    fake: opts.name,
+                    host,
+                    interactions: [...state.cassette.interactions, ...state.recorded],
+                };
+            },
+            recorded() {
+                return state.recorded.slice();
+            },
+            count() {
+                return state.recorded.length;
+            },
+        }),
+    };
+    return def;
+}