@specific.dev/spectest 0.99.0 → 0.100.0

package/dist/components/index.d.ts

@@ -13,6 +13,6 @@ export { github, type GithubOptions } from "./github.js";
 export { apple, type AppleOptions } from "./apple.js";
 export { microsoft, type MicrosoftOptions } from "./microsoft.js";
 export { okta, type OktaOptions } from "./okta.js";
-export { replayFake, type ReplayFakeOptions, type ReplayMatch, type InjectRule, type InjectMatch, type StringMatch, type SignConfig, type AwsSigV4Sign, type ReplayHelpers, type ReplaySummary, type Cassette, type CassetteInteraction, type CassetteRequest, type CassetteResponse, type CassetteState, } from "./replayFake.js";
+export { replayFake, type ReplayFakeOptions, type ReplayKey, type ReplayRequest, type MatchKey, type JsonValue, type InjectRule, type InjectMatch, type StringMatch, type SignConfig, type AwsSigV4Sign, type ReplayHelpers, type ReplaySummary, type Cassette, type CassetteInteraction, type CassetteRequest, type CassetteResponse, type CassetteState, } from "./replayFake.js";
 export { electron, type ElectronOptions } from "./electron.js";
 export { android, type AndroidOptions } from "./android.js";

package/dist/components/replay-key.d.ts

@@ -0,0 +1,27 @@
+import type { CassetteRequest } from "./replayFake.js";
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/** Identity content. Objects compare independently of property order; arrays
+ *  preserve order. Bytes are distinct from strings, arrays, and objects. */
+export type MatchKey = null | boolean | number | string | Uint8Array | readonly MatchKey[] | {
+    readonly [key: string]: MatchKey;
+};
+/** A buffered request view shared by incoming and recorded requests.
+ *  Headers are lowercase and exclude credentials. Recorded values may be
+ *  redacted; choose identity fields that survive recording. */
+export interface ReplayRequest {
+    readonly method: string;
+    readonly path: string;
+    readonly query: Readonly<Record<string, readonly string[]>>;
+    readonly headers: Readonly<Record<string, string>>;
+    /** Decode UTF-8, throwing on invalid text. */
+    text(): string;
+    /** Parse JSON. The type parameter is not runtime validation. */
+    json<T = JsonValue>(): T;
+    /** Return an independent copy of the body bytes. */
+    bytes(): Uint8Array;
+}
+export type ReplayKey = (request: ReplayRequest) => MatchKey;
+/** Internal only; the SDK exports the request/key types, not this function. */
+export declare function replaySignature(request: CassetteRequest, key?: ReplayKey): string;

package/dist/components/replay-key.js

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+/** Stream a typed, length-delimited canonical representation into the hash.
+ *  Never call toJSON: unsupported values must fail rather than silently lose
+ *  identity fields. In particular, an async callback must not become `{}`. */
+function hashKey(key) {
+    const hash = createHash("sha256");
+    const ancestors = new Set();
+    const visit = (value) => {
+        if (value === null || typeof value === "boolean" || typeof value === "string") {
+            hash.update(JSON.stringify(value));
+            return;
+        }
+        if (typeof value === "number" && Number.isFinite(value)) {
+            hash.update(JSON.stringify(value));
+            return;
+        }
+        if (value instanceof Uint8Array) {
+            hash.update(`bytes:${value.byteLength}:`);
+            hash.update(value);
+            return;
+        }
+        if (value instanceof Promise) {
+            // Report the invalid callback synchronously without leaving a rejected
+            // async callback to become an unrelated unhandled-rejection failure.
+            void value.catch(() => { });
+            throw new Error("key callbacks must be synchronous, not return promises");
+        }
+        if (typeof value !== "object" || value === null) {
+            throw new Error("key must contain only JSON values or Uint8Array bytes (no undefined, functions, or non-finite numbers)");
+        }
+        if (ancestors.has(value))
+            throw new Error("key must not contain cycles");
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            throw new Error("key must not contain symbol properties");
+        }
+        ancestors.add(value);
+        if (Array.isArray(value)) {
+            if (Object.keys(value).length !== value.length) {
+                throw new Error("key arrays must be dense and have no extra properties");
+            }
+            hash.update("[");
+            for (let i = 0; i < value.length; i++) {
+                if (!Object.hasOwn(value, i))
+                    throw new Error("key arrays must be dense");
+                visit(value[i]);
+                hash.update(",");
+            }
+            hash.update("]");
+        }
+        else {
+            const proto = Object.getPrototypeOf(value);
+            if (proto !== Object.prototype && proto !== null) {
+                throw new Error("key must use plain objects, not promises, dates, maps, or class instances; callbacks must be synchronous");
+            }
+            hash.update("{");
+            for (const name of Object.keys(value).sort()) {
+                hash.update(JSON.stringify(name));
+                hash.update(":");
+                visit(value[name]);
+                hash.update(",");
+            }
+            hash.update("}");
+        }
+        ancestors.delete(value);
+    };
+    visit(key);
+    return hash.digest("hex");
+}
+function bodyBytes(request) {
+    return Buffer.from(request.body ?? "", request.bodyEncoding === "base64" ? "base64" : "utf8");
+}
+function requestView(request) {
+    let bytes;
+    let text;
+    const readBytes = () => bytes ??= bodyBytes(request);
+    const readText = () => text ??= new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(readBytes());
+    const query = Object.fromEntries(Object.entries(request.query).map(([k, v]) => [k, Object.freeze([...v])]));
+    return Object.freeze({
+        method: request.method.toUpperCase(),
+        path: request.path,
+        query: Object.freeze(query),
+        headers: Object.freeze({ ...request.headers }),
+        text: readText,
+        json: () => JSON.parse(readText()),
+        bytes: () => Uint8Array.from(readBytes()),
+    });
+}
+/** Internal only; the SDK exports the request/key types, not this function. */
+export function replaySignature(request, key) {
+    if (key)
+        return hashKey(key(requestView(request)));
+    // Existing cassettes retain the original byte hash even when their stored
+    // text was redacted. Older/hand-written cassettes may only have the body.
+    const body = request.bodyHash ?? `sha256:${createHash("sha256").update(bodyBytes(request)).digest("hex")}`;
+    return hashKey({ method: request.method.toUpperCase(), path: request.path, query: request.query, body });
+}

package/dist/components/replayFake.d.ts

@@ -1,18 +1,6 @@
 import type { FakeDefinition } from "../index.js";
-/** 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[];
-}
+import { type ReplayKey } from "./replay-key.js";
+export type { JsonValue, MatchKey, ReplayRequest, ReplayKey } from "./replay-key.js";
 /** Match one request dimension. A bare string is an exact match; the
  *  object forms cover prefix and regex matching. */
 export type StringMatch = string | {
@@ -75,8 +63,12 @@ export interface ReplayFakeOptions {
      *  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;
+    /** Complete request identity. Default: method, path, normalized query,
+     *  and exact body bytes. The same synchronous, deterministic callback runs
+     *  on recorded and incoming requests. Return JSON values and/or Uint8Array
+     *  bytes; objects compare independently of property order. No implicit
+     *  matching dimensions or fallback apply when a key is supplied. */
+    key?: ReplayKey;
     /** 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
@@ -101,7 +93,8 @@ export interface CassetteRequest {
     path: string;
     /** Normalized: keys + repeated values sorted, so matching is order-free. */
     query: Record<string, string[]>;
-    /** Matched/readable header subset only — never `authorization`/`cookie`. */
+    /** Captured non-sensitive headers — never `authorization`/`cookie`.
+     *  Older cassettes may contain only content-type and selected headers. */
     headers: Record<string, string>;
     bodyHash?: string;
     /** Request body (omitted when empty): decoded + redacted UTF-8 text, or
@@ -131,6 +124,8 @@ export interface Cassette {
 /** Forked-per-test state for one replay fake. */
 export interface CassetteState {
     cassette: Cassette;
+    /** Complete signature → cassette interaction indexes, in cassette order. */
+    index: Map<string, number[]>;
     /** Per-match-signature replay cursor (call-order sequencing). */
     cursor: Map<string, number>;
     /** Interactions captured this record session. */

package/dist/components/replayFake.js

@@ -62,6 +62,7 @@ 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 { replaySignature } from "./replay-key.js";
 import { inferSigV4Scope, signAwsV4Request, } from "../aws-sigv4.js";
 // ────────────────────────────────────────────────────────────────────────
 // Helpers
@@ -71,7 +72,9 @@ const SENSITIVE_HEADERS = new Set([
     "cookie",
     "set-cookie",
     "proxy-authorization",
+    "api-key",
     "x-api-key",
+    "x-goog-api-key",
     "x-amz-security-token",
 ]);
 /** Hop-by-hop + body-framing headers never forwarded / never replayed
@@ -97,15 +100,6 @@ const STRIP_FORWARD_HEADERS = new Set([
  *  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
@@ -144,31 +138,6 @@ function recordable(headers, want) {
     }
     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
@@ -190,7 +159,7 @@ function coerceCassette(parsed, name, host) {
         version: 1,
         fake: parsed.fake ?? name,
         host: parsed.host ?? host,
-        interactions: parsed.interactions,
+        interactions: structuredClone(parsed.interactions),
     };
 }
 /** Read a cassette by its path relative to `spectest/tests/` (e.g.
@@ -218,7 +187,7 @@ function readCassetteFile(name, file, 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);
+        const text = new TextDecoder("utf8", { fatal: true, ignoreBOM: true }).decode(bytes);
         return { body: text, bodyEncoding: "utf8" };
     }
     catch {
@@ -434,7 +403,12 @@ export function replayFake(opts) {
         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);
+    if ("match" in opts) {
+        throw new Error(`replayFake(${opts.name}): \`match\` has been replaced by \`key(request)\`, which defines the complete request identity`);
+    }
+    if (opts.key !== undefined && typeof opts.key !== "function") {
+        throw new Error(`replayFake(${opts.name}): \`key\` must be a synchronous function`);
+    }
     const injectRules = opts.inject ?? [];
     // Refs every header template references — the control plane resolves these
     // server-side and pushes them for the environment lifetime (see the daemon's
@@ -448,19 +422,33 @@ export function replayFake(opts) {
         return isRecording() ? "replay" : "record";
     };
     // ── REPLAY ──────────────────────────────────────────────────────────
+    function signature(request, location) {
+        try {
+            return replaySignature(request, opts.key);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`replayFake(${opts.name}): invalid replay key for ${location}: ${message}`);
+        }
+    }
     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);
+        let sig;
+        try {
+            sig = signature(reqLike, "incoming request");
+        }
+        catch (error) {
+            return new Response(error.message + "\n", {
+                status: 599, headers: { "content-type": "text/plain" },
+            });
         }
+        const matches = state.index.get(sig) ?? [];
         const idx = state.cursor.get(sig) ?? 0;
-        const hit = matches[idx];
+        const interactionIndex = matches[idx];
+        const hit = interactionIndex === undefined ? undefined : state.cassette.interactions[interactionIndex];
         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`;
+                `${reqLike.method} ${reqLike.path} (${matches.length === 0 ? "unknown key" : "exhausted key"}; matched ${matches.length}, wanted #${idx + 1}). ` +
+                `Check \`key\` or re-record the cassette.\n`;
             return new Response(body, {
                 status: 599,
                 headers: { "content-type": "text/plain" },
@@ -618,7 +606,7 @@ export function replayFake(opts) {
                 method: reqLike.method,
                 path: reqLike.path,
                 query: redactedQuery,
-                headers: reqLike.headers,
+                headers: Object.fromEntries(Object.entries(reqLike.headers).map(([k, v]) => [k, redact(v)])),
                 ...(reqLike.body !== undefined
                     ? {
                         bodyHash: reqLike.bodyHash,
@@ -667,7 +655,7 @@ export function replayFake(opts) {
             // 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 ?? [])]),
+            headers: recordable(req.headers, [...req.headers.keys()]),
             ...(decodedBody
                 ? {
                     bodyHash: sha256Bytes(bodyBytes),
@@ -690,6 +678,7 @@ export function replayFake(opts) {
         // `replay(...)` to populate it.
         state: () => ({
             cassette: emptyCassette(opts.name, host),
+            index: new Map(),
             cursor: new Map(),
             recorded: [],
             dirty: false,
@@ -711,22 +700,34 @@ export function replayFake(opts) {
                     throw new Error(`replayFake(${opts.name}): replay(...) needs a cassette path under spectest/tests/ ` +
                         `(e.g. "recordings/${opts.name}.json").`);
                 }
+                // Build/validate before replacing live state: a bad key/cassette
+                // must leave the previous cassette and consumption cursors intact.
+                const index = new Map();
+                for (const [i, interaction] of loaded.interactions.entries()) {
+                    const sig = signature(interaction.request, `${JSON.stringify(label)} interaction #${i + 1}`);
+                    const queue = index.get(sig);
+                    if (queue)
+                        queue.push(i);
+                    else
+                        index.set(sig, [i]);
+                }
                 // Mutate the live state object (the handler reads the same
                 // reference); reset the cursor so replay starts from the top.
                 state.cassette = loaded;
+                state.index = index;
                 state.cursor = new Map();
                 return { cassette: label, host: loaded.host, interactions: loaded.interactions.length };
             },
             dump() {
-                return {
+                return structuredClone({
                     version: 1,
                     fake: opts.name,
                     host,
                     interactions: [...state.cassette.interactions, ...state.recorded],
-                };
+                });
             },
             recorded() {
-                return state.recorded.slice();
+                return structuredClone(state.recorded);
             },
             count() {
                 return state.recorded.length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.99.0",
+  "version": "0.100.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/index.ts

@@ -85,7 +85,10 @@ export { okta, type OktaOptions } from "./okta.js";
 export {
   replayFake,
   type ReplayFakeOptions,
-  type ReplayMatch,
+  type ReplayKey,
+  type ReplayRequest,
+  type MatchKey,
+  type JsonValue,
   type InjectRule,
   type InjectMatch,
   type StringMatch,

package/src/components/replay-key.ts

@@ -0,0 +1,127 @@
+import { createHash } from "node:crypto";
+import type { CassetteRequest } from "./replayFake.js";
+
+export type JsonValue =
+  | null | boolean | number | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+/** Identity content. Objects compare independently of property order; arrays
+ *  preserve order. Bytes are distinct from strings, arrays, and objects. */
+export type MatchKey =
+  | null | boolean | number | string | Uint8Array
+  | readonly MatchKey[]
+  | { readonly [key: string]: MatchKey };
+
+/** A buffered request view shared by incoming and recorded requests.
+ *  Headers are lowercase and exclude credentials. Recorded values may be
+ *  redacted; choose identity fields that survive recording. */
+export interface ReplayRequest {
+  readonly method: string;
+  readonly path: string;
+  readonly query: Readonly<Record<string, readonly string[]>>;
+  readonly headers: Readonly<Record<string, string>>;
+  /** Decode UTF-8, throwing on invalid text. */
+  text(): string;
+  /** Parse JSON. The type parameter is not runtime validation. */
+  json<T = JsonValue>(): T;
+  /** Return an independent copy of the body bytes. */
+  bytes(): Uint8Array;
+}
+
+export type ReplayKey = (request: ReplayRequest) => MatchKey;
+
+/** Stream a typed, length-delimited canonical representation into the hash.
+ *  Never call toJSON: unsupported values must fail rather than silently lose
+ *  identity fields. In particular, an async callback must not become `{}`. */
+function hashKey(key: MatchKey): string {
+  const hash = createHash("sha256");
+  const ancestors = new Set<object>();
+  const visit = (value: unknown): void => {
+    if (value === null || typeof value === "boolean" || typeof value === "string") {
+      hash.update(JSON.stringify(value));
+      return;
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+      hash.update(JSON.stringify(value));
+      return;
+    }
+    if (value instanceof Uint8Array) {
+      hash.update(`bytes:${value.byteLength}:`);
+      hash.update(value);
+      return;
+    }
+    if (value instanceof Promise) {
+      // Report the invalid callback synchronously without leaving a rejected
+      // async callback to become an unrelated unhandled-rejection failure.
+      void value.catch(() => {});
+      throw new Error("key callbacks must be synchronous, not return promises");
+    }
+    if (typeof value !== "object" || value === null) {
+      throw new Error("key must contain only JSON values or Uint8Array bytes (no undefined, functions, or non-finite numbers)");
+    }
+    if (ancestors.has(value)) throw new Error("key must not contain cycles");
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+      throw new Error("key must not contain symbol properties");
+    }
+    ancestors.add(value);
+    if (Array.isArray(value)) {
+      if (Object.keys(value).length !== value.length) {
+        throw new Error("key arrays must be dense and have no extra properties");
+      }
+      hash.update("[");
+      for (let i = 0; i < value.length; i++) {
+        if (!Object.hasOwn(value, i)) throw new Error("key arrays must be dense");
+        visit(value[i]);
+        hash.update(",");
+      }
+      hash.update("]");
+    } else {
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) {
+        throw new Error("key must use plain objects, not promises, dates, maps, or class instances; callbacks must be synchronous");
+      }
+      hash.update("{");
+      for (const name of Object.keys(value).sort()) {
+        hash.update(JSON.stringify(name));
+        hash.update(":");
+        visit((value as Record<string, unknown>)[name]);
+        hash.update(",");
+      }
+      hash.update("}");
+    }
+    ancestors.delete(value);
+  };
+  visit(key);
+  return hash.digest("hex");
+}
+
+function bodyBytes(request: CassetteRequest): Uint8Array {
+  return Buffer.from(request.body ?? "", request.bodyEncoding === "base64" ? "base64" : "utf8");
+}
+
+function requestView(request: CassetteRequest): ReplayRequest {
+  let bytes: Uint8Array | undefined;
+  let text: string | undefined;
+  const readBytes = () => bytes ??= bodyBytes(request);
+  const readText = () => text ??= new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(readBytes());
+  const query = Object.fromEntries(Object.entries(request.query).map(([k, v]) => [k, Object.freeze([...v])]));
+  return Object.freeze({
+    method: request.method.toUpperCase(),
+    path: request.path,
+    query: Object.freeze(query),
+    headers: Object.freeze({ ...request.headers }),
+    text: readText,
+    json: <T = JsonValue>(): T => JSON.parse(readText()) as T,
+    bytes: () => Uint8Array.from(readBytes()),
+  });
+}
+
+/** Internal only; the SDK exports the request/key types, not this function. */
+export function replaySignature(request: CassetteRequest, key?: ReplayKey): string {
+  if (key) return hashKey(key(requestView(request)));
+  // Existing cassettes retain the original byte hash even when their stored
+  // text was redacted. Older/hand-written cassettes may only have the body.
+  const body = request.bodyHash ?? `sha256:${createHash("sha256").update(bodyBytes(request)).digest("hex")}`;
+  return hashKey({ method: request.method.toUpperCase(), path: request.path, query: request.query, body });
+}

package/src/components/replayFake-record.test.ts

@@ -0,0 +1,114 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Isolate module mocks from other tests. Drive the actual record handler,
+// replacing only DNS/HTTPS transport; no credentials or external egress.
+test("recorded headers, redaction, and exact body bytes survive record → replay", async () => {
+  const moduleUrl = (file: string) => JSON.stringify(new URL(file, import.meta.url).href);
+  const script = `
+    import { strict as assert } from "node:assert";
+    import { EventEmitter } from "node:events";
+    import { mock, test } from "bun:test";
+    import * as dnsPacket from ${JSON.stringify(import.meta.resolve("dns-packet"))};
+
+    test("record round trip", async () => {
+    mock.module("node:dgram", () => ({ createSocket() {
+      const socket = new EventEmitter();
+      socket.close = () => {};
+      socket.send = (_query, _port, _host, done) => {
+        done();
+        queueMicrotask(() => socket.emit("message", dnsPacket.encode({
+          type: "response", id: 1,
+          answers: [{ type: "A", name: "api.example.test", ttl: 60, data: "127.0.0.1" }],
+        })));
+      };
+      return socket;
+    } }));
+
+    const upstreamHeaders = [];
+    mock.module("node:https", () => ({ request(options, callback) {
+      upstreamHeaders.push(options.headers);
+      const req = new EventEmitter();
+      req.write = () => {};
+      req.end = () => queueMicrotask(() => {
+        const res = new EventEmitter();
+        res.statusCode = 200;
+        res.headers = { "content-type": "text/plain" };
+        callback(res);
+        res.emit("data", Buffer.from("response"));
+        res.emit("end");
+      });
+      return req;
+    } }));
+
+    const { replayFake } = await import(${moduleUrl("./replayFake.ts")});
+    const { setRecordSecrets } = await import(${moduleUrl("../record-secrets.ts")});
+    setRecordSecrets({ API_KEY: "recording-secret" });
+    const options = {
+      name: "test", host: "api.example.test",
+      inject: [{ headers: { authorization: "Bearer {{secret:API_KEY}}" } }],
+      redactPatterns: ["private-field"],
+    };
+    const record = replayFake({ ...options, mode: "record" });
+    const state = record.state();
+    const helpers = record.helpers({ name: "test", state, ctx: {} });
+    const bodies = ["\\ufeffhello", new Uint8Array([0, 128, 255]), "recording-secret private-field"];
+    for (const [i, body] of bodies.entries()) {
+      const res = await record.handler(new Request("https://api.example.test/messages", {
+        method: "POST", body,
+        headers: {
+          "X-Task": "task-" + i,
+          authorization: "Bearer dummy", cookie: "dummy-cookie",
+          "api-key": "dummy-api-key", "x-goog-api-key": "dummy-google-key",
+          "x-extra": "recording-secret private-field",
+        },
+      }), state, {});
+      assert.equal(res.status, 200, await res.text());
+    }
+    assert.equal(helpers.count(), 3);
+    assert.equal(upstreamHeaders[0].authorization, "Bearer recording-secret");
+    const cassette = JSON.parse(JSON.stringify(helpers.dump()));
+    assert.equal(cassette.interactions[0].request.body, "\\ufeffhello");
+    assert.equal(cassette.interactions[1].request.bodyEncoding, "base64");
+    assert.equal(cassette.interactions[2].request.body, "<REDACTED:API_KEY> <REDACTED>");
+    for (const [i, it] of cassette.interactions.entries()) {
+      assert.equal(it.request.headers["x-task"], "task-" + i);
+      assert.equal(it.request.headers["x-extra"], "<REDACTED:API_KEY> <REDACTED>");
+      for (const name of ["authorization", "cookie", "api-key", "x-goog-api-key"]) {
+        assert.equal(it.request.headers[name], undefined);
+      }
+    }
+    assert.equal(JSON.stringify(cassette).includes("recording-secret"), false);
+
+    for (const key of [undefined, r => r.headers["x-task"]]) {
+      const replay = replayFake({ ...options, mode: "replay", key });
+      const replayState = replay.state();
+      replay.helpers({ name: "test", state: replayState, ctx: {} }).replay(cassette);
+      for (const i of [2, 0, 1]) {
+        const res = await replay.handler(new Request("https://api.example.test/messages", {
+          method: "POST", body: bodies[i], headers: { "X-Task": "task-" + i },
+        }), replayState, {});
+        assert.equal(res.status, 200);
+        assert.equal(await res.text(), "response");
+      }
+    }
+    assert.equal(upstreamHeaders.length, 3); // Replay never forwards.
+    });
+  `;
+  const dir = await mkdtemp(join(tmpdir(), "spectest-replay-record-"));
+  try {
+    const file = join(dir, "record.test.ts");
+    await writeFile(file, script);
+    const child = Bun.spawn([process.execPath, "test", file], {
+      stdout: "pipe", stderr: "pipe",
+    });
+    const [exit, stdout, stderr] = await Promise.all([
+      child.exited, new Response(child.stdout).text(), new Response(child.stderr).text(),
+    ]);
+    expect(exit, stdout + stderr).toBe(0);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}, 10_000);

package/src/components/replayFake.test.ts

@@ -0,0 +1,254 @@
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import type { FakeContext } from "../index.js";
+import { replayFake, type Cassette, type CassetteInteraction, type ReplayFakeOptions, type ReplayRequest, type ReplayKey, type MatchKey } from "./index.js";
+
+const context = {} as FakeContext;
+const host = "api.example.test";
+const sha = (body: string | Uint8Array) => `sha256:${createHash("sha256").update(body).digest("hex")}`;
+
+function interaction(body: string | Uint8Array, answer: string, path = "/messages"): CassetteInteraction {
+  return {
+    request: {
+      method: "POST", path, query: {}, headers: { "content-type": "application/json" },
+      body: typeof body === "string" ? body : Buffer.from(body).toString("base64"),
+      bodyEncoding: typeof body === "string" ? "utf8" : "base64",
+      bodyHash: sha(body),
+    },
+    response: { status: 200, headers: {}, body: answer, bodyEncoding: "utf8" },
+  };
+}
+
+function cassette(interactions: CassetteInteraction[]): Cassette {
+  return { version: 1, fake: "test", host, interactions };
+}
+
+async function harness(options: Partial<ReplayFakeOptions> = {}) {
+  const fake = replayFake({ name: "test", host, mode: "replay", ...options });
+  const state = await fake.state!();
+  const helpers = await fake.helpers!({ name: "test", state, ctx: context });
+  return {
+    state, helpers,
+    async send(body: string | Uint8Array = "", path = "/messages", init: RequestInit = {}) {
+      return await fake.handler(new Request(`https://${host}${path}`, {
+        method: "POST", body: body as BodyInit, ...init,
+      }), state, context);
+    },
+  };
+}
+
+describe("replay request identity", () => {
+  test("default matches 654 concurrent requests by body, independently of arrival order", async () => {
+    const h = await harness();
+    const calls = Array.from({ length: 654 }, (_, id) => interaction(JSON.stringify({ id }), `answer-${id}`));
+    h.helpers.replay(cassette(calls));
+    // A permutation visits every identity once in a different order.
+    const results = await Promise.all(calls.map(async (_, i) => {
+      const id = (i * 37) % calls.length;
+      const response = await h.send(JSON.stringify({ id }));
+      expect(response.status).toBe(200);
+      expect(await response.text()).toBe(`answer-${id}`);
+    }));
+    expect(results).toHaveLength(654);
+    expect(h.state.cursor.size).toBe(654);
+  });
+
+  test("default uses method/path/normalized query/exact bytes, including old cassettes without hashes", async () => {
+    const h = await harness();
+    const it = interaction('{"a":1}', "ok");
+    delete it.request.bodyHash;
+    delete it.request.bodyEncoding;
+    it.request.query = { b: ["1", "2"], a: ["x"] };
+    h.helpers.replay(cassette([it]));
+    for (const [body, path, init] of [
+      ['{ "a":1}', "/messages?a=x&b=2&b=1", {}],
+      ['{"a":1}', "/other?a=x&b=2&b=1", {}],
+      ['{"a":1}', "/messages?a=x&b=2&b=1", { method: "PUT" }],
+      ['{"a":1}', "/messages?a=y&b=2&b=1", {}],
+    ] as const) expect((await h.send(body, path, init)).status).toBe(599);
+    expect(await (await h.send('{"a":1}', "/messages?b=2&a=x&b=1")).text()).toBe("ok");
+  });
+
+  test("the existing committed HTTP cassette still replays with the new default", async () => {
+    const h = await harness();
+    const existing = await Bun.file(new URL("../../../examples/replay-fake/spectest/tests/recordings/httpbin.json", import.meta.url)).json() as Cassette;
+    h.helpers.replay(existing);
+    const response = await h.send("", "/get?hello=world", { method: "GET", body: null });
+    expect(response.status).toBe(200);
+    expect((await response.json()).args).toEqual({ hello: ["world"] });
+  });
+
+  test("SigV4 query credentials stay outside default and custom identity", async () => {
+    for (const key of [undefined, (r: ReplayRequest) => ({ path: r.path, query: r.query })]) {
+      const h = await harness({ key, sign: { type: "awsSigv4", accessKeyId: "ACCESS", secretAccessKey: "SECRET" } });
+      h.helpers.replay(cassette([interaction("body", "ok")]));
+      expect(await (await h.send("body", "/messages?X-Amz-Signature=changing&X-Amz-Date=20261001")).text()).toBe("ok");
+    }
+  });
+
+  test("Dentio keys separate model/tasks while ignoring a changing date", async () => {
+    let evaluations = 0;
+    const h = await harness({ key(request) {
+      evaluations++;
+      const body = request.json<{ system: { text: string }[] }>();
+      return { model: request.path, task: body.system[0].text.slice(0, 200) };
+    } });
+    const calls = Array.from({ length: 8 }, (_, i) => ({
+      task: `task-${i}`.padEnd(200, "."),
+      path: `/model/${i < 4 ? "haiku" : "sonnet"}/converse`,
+    }));
+    const body = (task: string, date: string) => JSON.stringify({ system: [{ text: `${task} Today: ${date}` }] });
+    h.helpers.replay(cassette(calls.map((call, i) => interaction(body(call.task, "2026-10-01"), i === 4 ? "Karies 16o" : `task-${i}`, call.path))));
+    expect(evaluations).toBe(8);
+    for (const i of [7, 2, 4, 0, 6, 1, 5, 3]) {
+      expect(await (await h.send(body(calls[i].task, "2026-10-02"), calls[i].path)).text()).toBe(i === 4 ? "Karies 16o" : `task-${i}`);
+    }
+    expect(evaluations).toBe(16); // No rescanning/recomputing cassette keys.
+  });
+
+  test("custom key is the entire identity, with no implicit HTTP dimensions", async () => {
+    const h = await harness({ key: request => request.json<{ task: string }>().task });
+    h.helpers.replay(cassette([interaction('{"task":"same","date":"yesterday"}', "ok", "/old")]));
+    expect(await (await h.send('{"task":"same","date":"today"}', "/new?nonce=123", { method: "PUT" })).text()).toBe("ok");
+  });
+
+  test("JSON objects compare structurally but arrays preserve order", async () => {
+    const h = await harness({ key: request => request.json() });
+    h.helpers.replay(cassette([interaction('{"b":2,"a":{"x":[1,2]}}', "ok")]));
+    expect((await h.send('{"a":{"x":[2,1]},"b":2}')).status).toBe(599);
+    expect(await (await h.send('{ "a": {"x":[1,2]}, "b": 2 }')).text()).toBe("ok");
+  });
+
+  test("binary keys are lossless and distinct from JSON lookalikes", async () => {
+    const h = await harness({ key: request => ({ body: request.bytes() }) });
+    const bytes = new Uint8Array([0, 255, 128]);
+    h.helpers.replay(cassette([interaction(bytes, "binary")]));
+    expect((await h.send("[0,255,128]")).status).toBe(599);
+    expect(await (await h.send(bytes)).text()).toBe("binary");
+
+    const mixed = await harness({ key: r => r.path === "/binary" ? new Uint8Array([1, 2]) : r.json() });
+    mixed.helpers.replay(cassette([interaction("", "bytes", "/binary"), interaction("[1,2]", "array"), interaction('{"0":1,"1":2}', "object")]));
+    expect(await (await mixed.send("[1,2]")).text()).toBe("array");
+    expect(await (await mixed.send('{"0":1,"1":2}')).text()).toBe("object");
+    expect(await (await mixed.send("", "/binary")).text()).toBe("bytes");
+  });
+
+  test("empty and BOM-prefixed bodies preserve their bytes", async () => {
+    for (const key of [undefined, (r: ReplayRequest) => r.bytes()]) {
+      const h = await harness({ key });
+      h.helpers.replay(cassette([interaction("", "empty"), interaction("\ufeffhello", "bom")]));
+      expect(await (await h.send("")).text()).toBe("empty");
+      expect((await h.send("hello")).status).toBe(599);
+      expect(await (await h.send("\ufeffhello")).text()).toBe("bom");
+    }
+  });
+
+  test("same-key queues consume once, fail on exhaustion, and reset on reload", async () => {
+    const h = await harness();
+    const c = cassette([interaction("same", "first"), interaction("other", "other"), interaction("same", "second")]);
+    h.helpers.replay(c);
+    expect(await Promise.all([h.send("same"), h.send("same")].map(async p => (await p).text()))).toEqual(["first", "second"]);
+    const exhausted = await h.send("same");
+    expect(exhausted.status).toBe(599);
+    expect(await exhausted.text()).toContain("exhausted key");
+    expect(await (await h.send("missing")).text()).toContain("unknown key");
+    expect(await (await h.send("other")).text()).toBe("other");
+    h.helpers.replay(c);
+    expect(await (await h.send("same")).text()).toBe("first");
+  });
+
+  test("cassette keys and cursors are isolated between fake states", async () => {
+    const a = await harness(), b = await harness();
+    const c = cassette([interaction("same", "ok")]);
+    a.helpers.replay(c); b.helpers.replay(c);
+    expect(await (await a.send("same")).text()).toBe("ok");
+    expect((await a.send("same")).status).toBe(599);
+    expect(await (await b.send("same")).text()).toBe("ok");
+    // Inline input cannot mutate a loaded/indexed cassette.
+    c.interactions[0].response.body = "mutated";
+    expect(a.helpers.dump().interactions[0].response.body).toBe("ok");
+    a.helpers.dump().interactions[0].response.body = "mutated dump";
+    expect(a.helpers.dump().interactions[0].response.body).toBe("ok");
+  });
+
+  test("request accessors are synchronous, reusable, and omit internal hashes/credentials", async () => {
+    const h = await harness({ key(r) {
+      expect("bodyHash" in r).toBe(false);
+      expect(r.headers.authorization).toBeUndefined();
+      expect(r.headers.cookie).toBeUndefined();
+      expect(Object.isFrozen(r)).toBe(true);
+      expect(Object.isFrozen(r.query)).toBe(true);
+      const bytes = r.bytes(); bytes.fill(0);
+      expect(r.text()).toBe('{"a":1}');
+      expect(r.json<{ a: number }>()).toEqual({ a: 1 });
+      return r.headers["x-task"]!;
+    } });
+    const it = interaction('{"a":1}', "ok");
+    it.request.headers["x-task"] = "journal";
+    h.helpers.replay(cassette([it]));
+    expect(await (await h.send('{"a":1}', "/messages", { headers: { "X-Task": "journal", authorization: "secret", cookie: "secret" } })).text()).toBe("ok");
+  });
+
+  test("bad incoming JSON fails without consuming a response; bad loads preserve live state", async () => {
+    const h = await harness({ key: r => r.json() });
+    h.helpers.replay(cassette([interaction("{}", "ok")]));
+    expect(() => h.helpers.replay(cassette([interaction("invalid", "bad")]))).toThrow("interaction #1");
+    const bad = await h.send("invalid");
+    expect(bad.status).toBe(599);
+    expect(await bad.text()).toContain("invalid replay key");
+    expect(await (await h.send("{}")).text()).toBe("ok");
+  });
+
+  test.each([
+    undefined, NaN, Infinity, BigInt(1), new Date(), new Map(), Promise.resolve("x"),
+    { missing: undefined }, [undefined], Array(1), () => "x",
+  ])("rejects unsupported keys instead of silently collapsing identities: %p", async value => {
+    const h = await harness({ key: () => value as MatchKey });
+    expect(() => h.helpers.replay(cassette([interaction("", "bad")]))).toThrow("invalid replay key");
+  });
+
+  test("rejects cyclic keys but permits shared subobjects", async () => {
+    const value: Record<string, MatchKey> = {};
+    value.self = value;
+    const bad = await harness({ key: () => value });
+    expect(() => bad.helpers.replay(cassette([interaction("", "bad")]))).toThrow("cycles");
+    const shared = { a: 1 };
+    const good = await harness({ key: () => [shared, shared] });
+    good.helpers.replay(cassette([interaction("", "ok")]));
+    expect(await (await good.send()).text()).toBe("ok");
+  });
+
+  test("rejects an async callback that throws without leaking an unhandled rejection", async () => {
+    const h = await harness({ key: (async () => { throw new Error("async failure"); }) as unknown as ReplayFakeOptions["key"] });
+    expect(() => h.helpers.replay(cassette([interaction("", "bad")]))).toThrow("synchronous");
+    await Promise.resolve();
+  });
+
+  test("old match options fail with migration guidance", () => {
+    expect(() => replayFake({ name: "test", host, match: { body: "hash" } } as unknown as ReplayFakeOptions)).toThrow("has been replaced by `key(request)`");
+  });
+});
+
+// Compile-time API checks, verified by the targeted TypeScript check as well
+// as the SDK build. Never invoked: invalid callbacks must not run.
+function publicTypes(request: ReplayRequest): void {
+  const json: ReplayKey = r => r.json();
+  const bytes: ReplayKey = r => ({ body: r.bytes(), query: r.query });
+  void [json, bytes];
+  // @ts-expect-error bodyHash is internal, not part of the callback view.
+  request.bodyHash;
+  // @ts-expect-error Request metadata is read-only.
+  request.method = "POST";
+  // @ts-expect-error Query values are read-only.
+  request.query.id.push("another");
+  // @ts-expect-error Callbacks must be synchronous.
+  const asyncKey: ReplayKey = async r => r.text();
+  // @ts-expect-error Undefined is not an identity.
+  const absentKey: ReplayKey = () => undefined;
+  void [asyncKey, absentKey];
+  replayFake({ name: "test", host,
+    // @ts-expect-error Per-dimension matching switches have been removed.
+    match: { body: "hash" },
+  });
+}
+void publicTypes;

package/src/components/replayFake.ts

@@ -65,6 +65,8 @@ 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 { replaySignature, type ReplayKey } from "./replay-key.js";
+export type { JsonValue, MatchKey, ReplayRequest, ReplayKey } from "./replay-key.js";
 import {
   inferSigV4Scope,
   signAwsV4Request,
@@ -75,21 +77,6 @@ import {
 // 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 =
@@ -155,8 +142,12 @@ export interface ReplayFakeOptions {
    *  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;
+  /** Complete request identity. Default: method, path, normalized query,
+   *  and exact body bytes. The same synchronous, deterministic callback runs
+   *  on recorded and incoming requests. Return JSON values and/or Uint8Array
+   *  bytes; objects compare independently of property order. No implicit
+   *  matching dimensions or fallback apply when a key is supplied. */
+  key?: ReplayKey;
   /** 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
@@ -182,7 +173,8 @@ export interface CassetteRequest {
   path: string;
   /** Normalized: keys + repeated values sorted, so matching is order-free. */
   query: Record<string, string[]>;
-  /** Matched/readable header subset only — never `authorization`/`cookie`. */
+  /** Captured non-sensitive headers — never `authorization`/`cookie`.
+   *  Older cassettes may contain only content-type and selected headers. */
   headers: Record<string, string>;
   bodyHash?: string;
   /** Request body (omitted when empty): decoded + redacted UTF-8 text, or
@@ -216,6 +208,8 @@ export interface Cassette {
 /** Forked-per-test state for one replay fake. */
 export interface CassetteState {
   cassette: Cassette;
+  /** Complete signature → cassette interaction indexes, in cassette order. */
+  index: Map<string, number[]>;
   /** Per-match-signature replay cursor (call-order sequencing). */
   cursor: Map<string, number>;
   /** Interactions captured this record session. */
@@ -263,7 +257,9 @@ const SENSITIVE_HEADERS = new Set([
   "cookie",
   "set-cookie",
   "proxy-authorization",
+  "api-key",
   "x-api-key",
+  "x-goog-api-key",
   "x-amz-security-token",
 ]);
 
@@ -292,17 +288,6 @@ const STRIP_FORWARD_HEADERS = new Set([
 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
@@ -341,27 +326,6 @@ function recordable(headers: Headers, want: string[]): Record<string, string> {
   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
@@ -386,7 +350,7 @@ function coerceCassette(parsed: Cassette, name: string, host: string): Cassette
     version: 1,
     fake: parsed.fake ?? name,
     host: parsed.host ?? host,
-    interactions: parsed.interactions,
+    interactions: structuredClone(parsed.interactions),
   };
 }
 
@@ -421,7 +385,7 @@ function readCassetteFile(name: string, file: string, host: string): Cassette {
 /** 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);
+    const text = new TextDecoder("utf8", { fatal: true, ignoreBOM: true }).decode(bytes);
     return { body: text, bodyEncoding: "utf8" };
   } catch {
     return { body: Buffer.from(bytes).toString("base64"), bodyEncoding: "base64" };
@@ -671,7 +635,12 @@ export function replayFake(
     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);
+  if ("match" in opts) {
+    throw new Error(`replayFake(${opts.name}): \`match\` has been replaced by \`key(request)\`, which defines the complete request identity`);
+  }
+  if (opts.key !== undefined && typeof opts.key !== "function") {
+    throw new Error(`replayFake(${opts.name}): \`key\` must be a synchronous function`);
+  }
   const injectRules = opts.inject ?? [];
   // Refs every header template references — the control plane resolves these
   // server-side and pushes them for the environment lifetime (see the daemon's
@@ -685,19 +654,33 @@ export function replayFake(
   };
 
   // ── REPLAY ──────────────────────────────────────────────────────────
+  function signature(request: CassetteRequest, location: string): string {
+    try {
+      return replaySignature(request, opts.key);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`replayFake(${opts.name}): invalid replay key for ${location}: ${message}`);
+    }
+  }
+
   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);
+    let sig: string;
+    try {
+      sig = signature(reqLike, "incoming request");
+    } catch (error) {
+      return new Response((error as Error).message + "\n", {
+        status: 599, headers: { "content-type": "text/plain" },
+      });
     }
+    const matches = state.index.get(sig) ?? [];
     const idx = state.cursor.get(sig) ?? 0;
-    const hit = matches[idx];
+    const interactionIndex = matches[idx];
+    const hit = interactionIndex === undefined ? undefined : state.cassette.interactions[interactionIndex];
     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`;
+        `${reqLike.method} ${reqLike.path} (${matches.length === 0 ? "unknown key" : "exhausted key"}; matched ${matches.length}, wanted #${idx + 1}). ` +
+        `Check \`key\` or re-record the cassette.\n`;
       return new Response(body, {
         status: 599,
         headers: { "content-type": "text/plain" },
@@ -883,7 +866,7 @@ export function replayFake(
         method: reqLike.method,
         path: reqLike.path,
         query: redactedQuery,
-        headers: reqLike.headers,
+        headers: Object.fromEntries(Object.entries(reqLike.headers).map(([k, v]) => [k, redact(v)])),
         ...(reqLike.body !== undefined
           ? {
               bodyHash: reqLike.bodyHash,
@@ -943,7 +926,7 @@ export function replayFake(
       // 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 ?? [])]),
+      headers: recordable(req.headers, [...req.headers.keys()]),
       ...(decodedBody
         ? {
             bodyHash: sha256Bytes(bodyBytes),
@@ -967,6 +950,7 @@ export function replayFake(
     // `replay(...)` to populate it.
     state: (): CassetteState => ({
       cassette: emptyCassette(opts.name, host),
+      index: new Map(),
       cursor: new Map(),
       recorded: [],
       dirty: false,
@@ -988,22 +972,32 @@ export function replayFake(
               `(e.g. "recordings/${opts.name}.json").`,
           );
         }
+        // Build/validate before replacing live state: a bad key/cassette
+        // must leave the previous cassette and consumption cursors intact.
+        const index = new Map<string, number[]>();
+        for (const [i, interaction] of loaded.interactions.entries()) {
+          const sig = signature(interaction.request, `${JSON.stringify(label)} interaction #${i + 1}`);
+          const queue = index.get(sig);
+          if (queue) queue.push(i);
+          else index.set(sig, [i]);
+        }
         // Mutate the live state object (the handler reads the same
         // reference); reset the cursor so replay starts from the top.
         state.cassette = loaded;
+        state.index = index;
         state.cursor = new Map();
         return { cassette: label, host: loaded.host, interactions: loaded.interactions.length };
       },
       dump(): Cassette {
-        return {
+        return structuredClone({
           version: 1,
           fake: opts.name,
           host,
           interactions: [...state.cassette.interactions, ...state.recorded],
-        };
+        });
       },
       recorded(): CassetteInteraction[] {
-        return state.recorded.slice();
+        return structuredClone(state.recorded);
       },
       count(): number {
         return state.recorded.length;