@specific.dev/spectest 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/components/index.ts

@@ -27,8 +27,11 @@ export {
   replayFake,
   type ReplayFakeOptions,
   type ReplayMatch,
-  type ReplaySecretInjection,
+  type InjectRule,
+  type InjectMatch,
+  type StringMatch,
   type ReplayHelpers,
+  type ReplaySummary,
   type Cassette,
   type CassetteInteraction,
   type CassetteRequest,

package/src/components/replayFake.ts

@@ -6,42 +6,58 @@
 // and registers the hostname, dispatch routes by `Host` header to the
 // generated `handler`, and `state` forks per test like any fake.
 //
-// The only new behaviour lives inside the generated `handler`/`state`:
+// 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 a committed
-//     cassette and the recorded response is returned. No network. This is
-//     what runs under `spectest test`.
-//   - RECORD: the request is forwarded to the real upstream, the
+//   - 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.
 //
-// Secrets are injected at the egress boundary (the forwarder): the app
-// only ever holds a placeholder; the real value — pushed eval-scoped from
-// the control plane via {@link getRecordSecret} — is swapped in on the
-// forward to upstream and never persists into a cassette (redacted,
-// fail-closed) or any snapshot a hermetic run could fork.
-
+// Credential brokering (per-fake): `inject` rules set
+// headers on the egress forward — overwriting whatever the app sent — so
+// app code never holds the credential. Header values embed `{{secret:REF}}`
+// tokens; each REF is resolved server-side from the platform Secrets store
+// and pushed eval-scoped from the control plane (via {@link getRecordSecret}).
+// The real value lives only on the outbound wire to the real upstream and
+// is redacted from the cassette (fail-closed) — it never enters project
+// code, the tarball, the warm-cache hash, or any snapshot a hermetic run
+// could fork.
+
+import { createSocket } from "node:dgram";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
+import { request as httpsRequest } from "node:https";
 import path from "node:path";
+import { brotliDecompressSync, gunzipSync, inflateSync } from "node:zlib";
+import * as dnsPacket from "dns-packet";
 
 import type { FakeContext, FakeDefinition } from "../index.js";
 import { isRecording } from "../recorder.js";
 import { getRecordSecret } from "../record-secrets.js";
 
-// Pristine `fetch`, captured at module load (project import time, before
-// any per-test / per-eval fetch wrapper monkey-patches `globalThis.fetch`).
-// The forwarder uses this so its outbound call isn't intercepted by the
-// recorder — same reason the daemon's reverse-proxy keeps its own
-// `NATIVE_FETCH`.
-const NATIVE_FETCH: typeof fetch = globalThis.fetch.bind(globalThis);
-
 // ────────────────────────────────────────────────────────────────────────
 // Options + cassette format
 // ────────────────────────────────────────────────────────────────────────
@@ -61,39 +77,59 @@ export interface ReplayMatch {
   headers?: string[];
 }
 
-export interface ReplaySecretInjection {
-  /** Platform secret reference, e.g. `"STRIPE_API_KEY"`. The control plane
-   *  resolves it (default: `SPECTEST_SECRET_STRIPE_API_KEY` in the server
-   *  env) and pushes the value on the eval path only. */
-  ref: string;
-  /** Build the headers to set on the forward to upstream from the real
-   *  secret value, *replacing* whatever placeholder the app sent. Default:
-   *  `{ authorization: "Bearer <value>" }`. */
-  inject?: (req: Request, value: string) => Record<string, string>;
-  /** Extra substrings/patterns to scrub from stored request/response
-   *  bodies and queries (the secret value itself is always scrubbed). */
-  redactPatterns?: (string | RegExp)[];
+/** Match one request dimension. A bare string is an exact match; the
+ *  object forms cover prefix and regex matching. */
+export type StringMatch =
+  | string
+  | { exact: string }
+  | { startsWith: string }
+  | { regex: string };
+
+/** Request matchers for a credential-injection rule. A rule applies only
+ *  when EVERY specified dimension matches; omit `match` to always apply. */
+export interface InjectMatch {
+  /** Match the request path (no query). */
+  path?: StringMatch;
+  /** HTTP method(s) — any one matching satisfies it. */
+  method?: string | string[];
+  /** Query-param matchers (ANDed); each key's value(s) must match. */
+  query?: Record<string, StringMatch>;
+  /** Header matchers (ANDed; header names case-insensitive). */
+  headers?: Record<string, StringMatch>;
+}
+
+/** One credential-brokering rule. When it matches a request, these headers
+ *  are SET on the egress forward — overwriting whatever the app sent (so app
+ *  code can't smuggle a different value past the broker). Header VALUES may
+ *  embed `{{secret:REF}}` tokens; each `REF` is resolved server-side from the
+ *  project's Secrets store and pushed eval-scoped — the real value never
+ *  enters project code, the
+ *  tarball, the warm-cache hash, or a cassette (it's redacted, fail-closed). */
+export interface InjectRule {
+  match?: InjectMatch;
+  headers: Record<string, string>;
 }
 
 export interface ReplayFakeOptions {
   /** Stable name — the `ctx.fakes` key. */
   name: string;
-  /** Hostnames the fake answers to (e.g. `["api.stripe.test"]`). Keep
-   *  these distinct from the real `upstream` host so the record-mode
-   *  forward doesn't resolve back into the daemon (see the loopback
-   *  guard). */
-  hostnames: string[];
-  /** Real upstream base URL to forward to in record mode (e.g.
-   *  `"https://api.stripe.com"`). */
-  upstream: string;
-  /** TCP port the fake listens on. Default `80`. */
-  port?: number;
-  /** Cassette filename under `spectest/recordings/`. Default `<name>.json`. */
-  cassette?: 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;
-  /** Record-time secret injection at the egress boundary. */
-  secret?: ReplaySecretInjection;
+  /** Per-fake credential brokering. Rules are evaluated in
+   *  order; the first whose `match` matches wins (a rule without `match`
+   *  matches everything and shadows later rules). Applied at the
+   *  record-mode egress forward; resolved secret values are redacted from
+   *  the cassette (fail-closed). */
+  inject?: InjectRule[];
+  /** Extra substrings/patterns to scrub from stored request/response
+   *  bodies and queries (every injected secret value is always scrubbed). */
+  redactPatterns?: (string | RegExp)[];
   /** `"auto"` (default) records under eval and replays under test;
    *  `"record"` / `"replay"` force a mode. */
   mode?: "auto" | "record" | "replay";
@@ -127,7 +163,8 @@ export interface CassetteInteraction {
 export interface Cassette {
   version: 1;
   fake: string;
-  upstream: string;
+  /** The real host this cassette mirrors (e.g. `api.stripe.com`). */
+  host: string;
   interactions: CassetteInteraction[];
 }
 
@@ -141,8 +178,28 @@ export interface CassetteState {
   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> {
-  /** Full cassette JSON (committed interactions + newly recorded, redacted)
+  /** 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;
@@ -166,8 +223,8 @@ const SENSITIVE_HEADERS = new Set([
 ]);
 
 /** Hop-by-hop + body-framing headers never forwarded / never replayed
- *  (Bun's fetch already decompresses, so the encoding/length no longer
- *  describe the bytes). */
+ *  (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",
@@ -180,8 +237,16 @@ const STRIP_FORWARD_HEADERS = new Set([
   "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 {
@@ -237,41 +302,64 @@ function signature(req: CassetteRequest, match: ReturnType<typeof defaultMatch>)
   return JSON.stringify(sig);
 }
 
-function recordingsDir(): string {
-  const dir =
+/** 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(dir, "recordings");
+  return path.join(spectestDir, "tests");
 }
 
-function emptyCassette(name: string, upstream: string): Cassette {
-  return { version: 1, fake: name, upstream, interactions: [] };
+function emptyCassette(name: string, host: string): Cassette {
+  return { version: 1, fake: name, host, interactions: [] };
 }
 
-function loadCassette(name: string, file: string, upstream: string): Cassette {
-  const p = path.join(recordingsDir(), file);
-  if (!existsSync(p)) return emptyCassette(name, upstream);
+/** 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 {
-    const parsed = JSON.parse(readFileSync(p, "utf8")) as Cassette;
-    if (!Array.isArray(parsed.interactions)) {
-      throw new Error("cassette has no `interactions` array");
-    }
-    return {
-      version: 1,
-      fake: parsed.fake ?? name,
-      upstream: parsed.upstream ?? upstream,
-      interactions: parsed.interactions,
-    };
+    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(buf: ArrayBuffer): { body: string; bodyEncoding: "utf8" | "base64" } {
-  const bytes = new Uint8Array(buf);
+function decodeBody(bytes: Uint8Array): { body: string; bodyEncoding: "utf8" | "base64" } {
   try {
     const text = new TextDecoder("utf8", { fatal: true }).decode(bytes);
     return { body: text, bodyEncoding: "utf8" };
@@ -280,15 +368,21 @@ function decodeBody(buf: ArrayBuffer): { body: string; bodyEncoding: "utf8" | "b
   }
 }
 
+/** One resolved secret value and the ref it came from (for the redaction
+ *  placeholder). */
+interface ResolvedSecret {
+  ref: string;
+  value: string;
+}
+
 function makeRedactor(
-  secretValue: string | undefined,
+  secrets: ResolvedSecret[],
   patterns: (string | RegExp)[] | undefined,
-  ref: string | undefined,
 ): (s: string) => string {
   return (s: string): string => {
     let out = s;
-    if (secretValue && secretValue.length > 0) {
-      out = out.split(secretValue).join(`<REDACTED:${ref ?? "SECRET"}>`);
+    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") {
@@ -302,6 +396,204 @@ function makeRedactor(
   };
 }
 
+// ────────────────────────────────────────────────────────────────────────
+// Credential brokering: matchers + secret-token resolution
+// ────────────────────────────────────────────────────────────────────────
+
+/** `{{secret:REF}}` template token embedded in an injected header value. */
+const SECRET_TOKEN = /\{\{secret:([A-Za-z0-9_]+)\}\}/g;
+
+/** Every secret ref referenced by any inject rule's header templates. */
+function collectSecretRefs(rules: InjectRule[]): string[] {
+  const refs = new Set<string>();
+  for (const rule of rules) {
+    for (const value of Object.values(rule.headers)) {
+      for (const m of value.matchAll(SECRET_TOKEN)) refs.add(m[1]);
+    }
+  }
+  return [...refs];
+}
+
+function matchString(m: StringMatch, value: string): boolean {
+  if (typeof m === "string") return value === m;
+  if ("exact" in m) return value === m.exact;
+  if ("startsWith" in m) return value.startsWith(m.startsWith);
+  if ("regex" in m) return new RegExp(m.regex).test(value);
+  return false;
+}
+
+interface IncomingRequest {
+  method: string;
+  path: string;
+  query: URLSearchParams;
+  headers: Headers;
+}
+
+/** True if every dimension the matcher specifies is satisfied (AND across
+ *  dimensions). No `match` → always true. */
+function ruleMatches(match: InjectMatch | undefined, req: IncomingRequest): boolean {
+  if (!match) return true;
+  if (match.path !== undefined && !matchString(match.path, req.path)) return false;
+  if (match.method !== undefined) {
+    const methods = (Array.isArray(match.method) ? match.method : [match.method]).map((s) =>
+      s.toUpperCase(),
+    );
+    if (!methods.includes(req.method.toUpperCase())) return false;
+  }
+  if (match.query) {
+    for (const [k, m] of Object.entries(match.query)) {
+      if (!req.query.getAll(k).some((v) => matchString(m, v))) return false;
+    }
+  }
+  if (match.headers) {
+    for (const [k, m] of Object.entries(match.headers)) {
+      const v = req.headers.get(k.toLowerCase());
+      if (v === null || !matchString(m, v)) return false;
+    }
+  }
+  return true;
+}
+
+interface BrokeredHeaders {
+  /** Lowercased header → resolved value, to SET on the forward. */
+  headers: Record<string, string>;
+  /** Resolved secrets (for redaction). */
+  secrets: ResolvedSecret[];
+  /** Refs referenced but not supplied by the control plane. */
+  missing: string[];
+}
+
+/** Resolve a rule's header templates, substituting every `{{secret:REF}}`
+ *  with the eval-scoped value. Collects resolved secrets (for redaction)
+ *  and any refs the control plane didn't supply (fail loud). */
+function brokerHeaders(rule: InjectRule): BrokeredHeaders {
+  const headers: Record<string, string> = {};
+  const secrets: ResolvedSecret[] = [];
+  const missing: string[] = [];
+  const seen = new Set<string>();
+  for (const [name, template] of Object.entries(rule.headers)) {
+    headers[name.toLowerCase()] = template.replace(SECRET_TOKEN, (_full, ref: string) => {
+      const value = getRecordSecret(ref);
+      if (value === undefined) {
+        missing.push(ref);
+        return "";
+      }
+      if (!seen.has(ref)) {
+        seen.add(ref);
+        secrets.push({ ref, value });
+      }
+      return value;
+    });
+  }
+  return { headers, secrets, missing };
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Record-mode egress: resolve the real host externally, then MITM-forward
+// ────────────────────────────────────────────────────────────────────────
+
+/** Resolve a host's A records against an EXTERNAL DNS server, bypassing the
+ *  in-VM resolver (which would answer with the daemon's own gateway for a
+ *  faked host). Mirrors spectest-resolver's own upstream-forward transport
+ *  (dns-packet over UDP) so it works identically in-VM. */
+function resolveExternalA(host: string): Promise<string[]> {
+  const query = dnsPacket.encode({
+    type: "query",
+    id: 1,
+    flags: dnsPacket.RECURSION_DESIRED,
+    questions: [{ type: "A", name: host }],
+  });
+  return new Promise((resolve) => {
+    const sock = createSocket("udp4");
+    let done = false;
+    const finish = (ips: string[]): void => {
+      if (done) return;
+      done = true;
+      try {
+        sock.close();
+      } catch {
+        // ignore
+      }
+      resolve(ips);
+    };
+    sock.on("message", (msg) => {
+      try {
+        const res = dnsPacket.decode(msg);
+        const ips = (res.answers ?? [])
+          .filter((a) => a.type === "A")
+          .map((a) => a.data as string)
+          .filter((d) => typeof d === "string" && d.length > 0);
+        finish(ips);
+      } catch {
+        finish([]);
+      }
+    });
+    sock.on("error", () => finish([]));
+    sock.send(query, EXTERNAL_DNS_PORT, EXTERNAL_DNS, (err) => {
+      if (err) finish([]);
+    });
+    setTimeout(() => finish([]), 3_000);
+  });
+}
+
+interface UpstreamResponse {
+  status: number;
+  headers: Record<string, string>;
+  /** Decompressed body bytes. */
+  bytes: Uint8Array;
+}
+
+/** Open a real HTTPS connection to `ip` but with SNI + `Host` = `host`, so
+ *  the public certificate validates against the real hostname (the in-VM CA
+ *  is not involved on this leg). Decompresses the response so the stored and
+ *  returned bytes are the plain payload. */
+function forwardToRealUpstream(args: {
+  ip: string;
+  host: string;
+  method: string;
+  pathWithQuery: string;
+  headers: Record<string, string>;
+  body: string;
+}): Promise<UpstreamResponse> {
+  return new Promise((resolve, reject) => {
+    const req = httpsRequest(
+      {
+        host: args.ip,
+        port: 443,
+        method: args.method,
+        path: args.pathWithQuery,
+        servername: args.host,
+        headers: { ...args.headers, host: args.host, "accept-encoding": "identity" },
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (c: Buffer) => chunks.push(c));
+        res.on("end", () => {
+          let bytes: Uint8Array = Buffer.concat(chunks);
+          const enc = String(res.headers["content-encoding"] ?? "").toLowerCase();
+          try {
+            if (enc.includes("br")) bytes = brotliDecompressSync(bytes);
+            else if (enc.includes("gzip")) bytes = gunzipSync(bytes);
+            else if (enc.includes("deflate")) bytes = inflateSync(bytes);
+          } catch {
+            // Leave the bytes as-is if decompression fails.
+          }
+          const headers: Record<string, string> = {};
+          for (const [k, v] of Object.entries(res.headers)) {
+            if (typeof v === "string") headers[k.toLowerCase()] = v;
+            else if (Array.isArray(v)) headers[k.toLowerCase()] = v.join(", ");
+          }
+          resolve({ status: res.statusCode ?? 0, headers, bytes });
+        });
+        res.on("error", reject);
+      },
+    );
+    req.on("error", reject);
+    if (args.body.length > 0) req.write(args.body);
+    req.end();
+  });
+}
+
 // ────────────────────────────────────────────────────────────────────────
 // replayFake
 // ────────────────────────────────────────────────────────────────────────
@@ -310,21 +602,16 @@ export function replayFake(
   opts: ReplayFakeOptions,
 ): FakeDefinition<CassetteState, ReplayHelpers> {
   if (!opts.name) throw new Error("replayFake: `name` is required");
-  if (!Array.isArray(opts.hostnames) || opts.hostnames.length === 0) {
-    throw new Error(`replayFake(${opts.name}): at least one hostname is required`);
-  }
-  if (!opts.upstream) {
-    throw new Error(`replayFake(${opts.name}): "upstream" is required`);
+  if (!opts.host || typeof opts.host !== "string") {
+    throw new Error(`replayFake(${opts.name}): "host" (the real hostname) is required`);
   }
-  const cassetteFile = opts.cassette ?? `${opts.name}.json`;
-  const upstream = opts.upstream.replace(/\/+$/, "");
+  const host = opts.host.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
   const match = defaultMatch(opts.match);
-  const fakeHosts = new Set(opts.hostnames.map((h) => h.toLowerCase()));
-  const inject =
-    opts.secret?.inject ??
-    ((_req: Request, value: string): Record<string, string> => ({
-      authorization: `Bearer ${value}`,
-    }));
+  const injectRules = opts.inject ?? [];
+  // Refs every header template references — the control plane resolves these
+  // server-side and pushes them eval-scoped (see the daemon's
+  // /record-secret-refs endpoint, which reads `def.secretRefs`).
+  const secretRefs = collectSecretRefs(injectRules);
 
   const resolveMode = (): "record" | "replay" => {
     if (opts.mode === "record") return "record";
@@ -360,67 +647,86 @@ export function replayFake(
     return new Response(payload, { status: hit.response.status, headers });
   }
 
-  // ── RECORD ──────────────────────────────────────────────────────────
+  // ── RECORD (MITM) ───────────────────────────────────────────────────
   async function record(
     req: Request,
+    url: URL,
     reqLike: CassetteRequest,
     rawBody: string,
     state: CassetteState,
   ): Promise<Response> {
-    const secretValue = opts.secret ? getRecordSecret(opts.secret.ref) : undefined;
-    if (opts.secret && secretValue === undefined) {
+    // Credential brokering: first matching inject rule wins. Resolve its
+    // `{{secret:REF}}` tokens from the eval-scoped store; a
+    // referenced-but-unsupplied ref fails loud.
+    const rule = injectRules.find((r) =>
+      ruleMatches(r.match, {
+        method: reqLike.method,
+        path: reqLike.path,
+        query: url.searchParams,
+        headers: req.headers,
+      }),
+    );
+    const brokered = rule ? brokerHeaders(rule) : { headers: {}, secrets: [], missing: [] };
+    if (brokered.missing.length > 0) {
+      const refs = [...new Set(brokered.missing)];
       return new Response(
-        `replayFake(${opts.name}): secret ${JSON.stringify(opts.secret.ref)} was not supplied ` +
-          `(set SPECTEST_SECRET_${opts.secret.ref} in the server env and record via spectest_eval).\n`,
+        `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" } },
       );
     }
 
-    // Build the upstream URL and guard against forwarding back into the
-    // daemon (which would happen if the upstream host is itself one of
-    // this fake's hostnames — the in-VM resolver points those at us).
-    const target = new URL(reqLike.path, upstream + "/");
-    const incomingUrl = new URL(req.url);
-    incomingUrl.searchParams.forEach((v, k) => target.searchParams.append(k, v));
-    if (fakeHosts.has(target.hostname.toLowerCase())) {
-      throw new Error(
-        `replayFake(${opts.name}): upstream host ${target.hostname} is also a fake hostname — ` +
-          `forwarding would loop back into the daemon. Use a distinct fake hostname ` +
-          `(e.g. "api.${opts.name}.test") pointed at upstream ${upstream}.`,
+    // 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, then apply secret injection
-    // (replacing whatever placeholder the app sent — the real key only
-    // ever appears on this outbound wire).
-    const fwdHeaders = new Headers();
+    // 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.set(k, v);
+      if (!STRIP_FORWARD_HEADERS.has(k.toLowerCase())) fwdHeaders[k.toLowerCase()] = v;
     });
-    if (opts.secret && secretValue !== undefined) {
-      for (const [k, v] of Object.entries(inject(req, secretValue))) {
-        fwdHeaders.set(k, v);
-      }
-    }
+    for (const [k, v] of Object.entries(brokered.headers)) fwdHeaders[k] = v;
 
-    const upstreamRes = await NATIVE_FETCH(target.toString(), {
-      method: reqLike.method,
-      headers: fwdHeaders,
-      body: rawBody.length > 0 ? rawBody : undefined,
-      redirect: "manual",
-    });
-    const resBuf = await upstreamRes.arrayBuffer();
+    const search = url.searchParams.toString();
+    const pathWithQuery = reqLike.path + (search ? `?${search}` : "");
+
+    let upstream: UpstreamResponse;
+    try {
+      upstream = await forwardToRealUpstream({
+        ip: ips[0],
+        host,
+        method: reqLike.method,
+        pathWithQuery,
+        headers: fwdHeaders,
+        body: rawBody,
+      });
+    } catch (err) {
+      return new Response(
+        `replayFake(${opts.name}): forward to real ${host} (${ips[0]}) failed: ${(err as Error).message}\n`,
+        { status: 599, headers: { "content-type": "text/plain" } },
+      );
+    }
 
     // Decode + redact for storage; return the real (un-redacted) bytes to
     // the app so the manual session behaves like production.
-    const redact = makeRedactor(secretValue, opts.secret?.redactPatterns, opts.secret?.ref);
-    const decoded = decodeBody(resBuf);
+    const redact = makeRedactor(brokered.secrets, opts.redactPatterns);
+    const decoded = decodeBody(upstream.bytes);
     const respHeaders: Record<string, string> = {};
-    upstreamRes.headers.forEach((v, k) => {
-      const lower = k.toLowerCase();
-      if (SENSITIVE_HEADERS.has(lower) || STRIP_FORWARD_HEADERS.has(lower)) return;
-      respHeaders[lower] = v;
-    });
+    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)) {
@@ -437,20 +743,22 @@ export function replayFake(
           : {}),
       },
       response: {
-        status: upstreamRes.status,
+        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 the raw
-    // secret (a missed redaction is a leak, not a warning).
-    if (secretValue && secretValue.length > 0) {
-      if (JSON.stringify(interaction).includes(secretValue)) {
+    // Fail-closed: never persist a cassette that still carries any raw
+    // secret value (a missed redaction is a leak, not a warning).
+    const serialized = JSON.stringify(interaction);
+    for (const { ref, value } of brokered.secrets) {
+      if (value.length > 0 && serialized.includes(value)) {
         throw new Error(
-          `replayFake(${opts.name}): refusing to record — the secret value survived redaction ` +
-            `into the interaction for ${reqLike.method} ${reqLike.path}. Add a redactPatterns entry.`,
+          `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.`,
         );
       }
     }
@@ -458,8 +766,10 @@ export function replayFake(
     state.recorded.push(interaction);
     state.dirty = true;
 
-    const outHeaders = new Headers(respHeaders);
-    return new Response(resBuf, { status: upstreamRes.status, headers: outHeaders });
+    return new Response(upstream.bytes, {
+      status: upstream.status,
+      headers: new Headers(respHeaders),
+    });
   }
 
   // ── handler ─────────────────────────────────────────────────────────
@@ -479,27 +789,51 @@ export function replayFake(
     };
 
     if (resolveMode() === "replay") return replay(reqLike, state);
-    return record(req, reqLike, rawBody, state);
+    return record(req, url, reqLike, rawBody, state);
   };
 
   const def: FakeDefinition<CassetteState, ReplayHelpers> = {
     name: opts.name,
-    hostnames: opts.hostnames,
-    port: opts.port,
-    secretRefs: opts.secret ? [opts.secret.ref] : [],
+    // 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: loadCassette(opts.name, cassetteFile, upstream),
+      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,
-          upstream,
+          host,
           interactions: [...state.cassette.interactions, ...state.recorded],
         };
       },

package/src/daemon.ts

@@ -3016,11 +3016,27 @@ function installFetchWrapper(): () => void {
   };
 }
 
-function execInService(service: string, command: string): Promise<ExecResult> {
+/** Build the `docker exec` argv for a service command. An optional `cwd`
+ *  becomes `-w <cwd>` (the working-directory option of `ctx.exec`), so the
+ *  command runs from that directory without it being baked into the command
+ *  string. Used by both the buffered and streaming variants so they stay in
+ *  lockstep. */
+function dockerExecArgs(service: string, command: string, cwd?: string): string[] {
+  const args = ["exec"];
+  if (cwd) args.push("-w", cwd);
+  args.push(service, "sh", "-lc", command);
+  return args;
+}
+
+function execInService(
+  service: string,
+  command: string,
+  cwd?: string,
+): Promise<ExecResult> {
   return new Promise((resolve) => {
     execFile(
       "docker",
-      ["exec", service, "sh", "-lc", command],
+      dockerExecArgs(service, command, cwd),
       { maxBuffer: 16 * 1024 * 1024 },
       (err, stdout, stderr) => {
         const exitCode =
@@ -3046,8 +3062,9 @@ function execInService(service: string, command: string): Promise<ExecResult> {
 async function execInServiceWrapped(
   service: string,
   command: string,
+  opts?: { cwd?: string },
 ): Promise<Wrapped<ExecResult>> {
-  const res = await execInService(service, command);
+  const res = await execInService(service, command, opts?.cwd);
   return wrap(res, undefined) as unknown as Wrapped<ExecResult>;
 }
 
@@ -3074,9 +3091,10 @@ function execInServiceStreaming(
   service: string,
   command: string,
   onChunk: (stream: "stdout" | "stderr", data: string) => void,
+  cwd?: string,
 ): Promise<ExecResult> {
   return new Promise((resolve) => {
-    const child = spawn("docker", ["exec", service, "sh", "-lc", command], {
+    const child = spawn("docker", dockerExecArgs(service, command, cwd), {
       stdio: ["ignore", "pipe", "pipe"],
     });
     const acc = { stdout: "", stderr: "" };
@@ -3267,8 +3285,13 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   // or animated output replays with real timing in the web UI. The
   // frames are presentation-only; the ExecResult (and any assertions on
   // it) still sees the plain separated stdout/stderr.
-  const recordedExec = async (service: string, command: string): Promise<ExecResult> => {
+  const recordedExec = async (
+    service: string,
+    command: string,
+    opts?: { cwd?: string },
+  ): Promise<ExecResult> => {
     const t = Date.now();
+    const cwd = opts?.cwd;
     const resv = reserveEvent();
     const session = newTerminalSession(
       start,
@@ -3280,8 +3303,11 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     );
     terminalSessions.push(session.record);
     // Synthetic prompt frame so the replay is self-describing — the
-    // program's own output starts on the next line, like a real shell.
-    session.pushFrame(0, `\x1b[32m${service} $\x1b[0m \x1b[1m${command}\x1b[0m\r\n`);
+    // program's own output starts on the next line, like a real shell. A
+    // working directory rides in the prompt sigil (`svc:/dir $`) the way a
+    // real shell prompt shows it, so the recording stays self-describing.
+    const sigil = cwd ? `${service}:${cwd}` : service;
+    session.pushFrame(0, `\x1b[32m${sigil} $\x1b[0m \x1b[1m${command}\x1b[0m\r\n`);
     let frameBytes = 0;
     let frameCapped = false;
     const res = await execInServiceStreaming(service, command, (_stream, data) => {
@@ -3302,13 +3328,14 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
       // `\r\n` too keeps a CR|LF split across chunk boundaries
       // harmless (`\r\r\n` renders identically).
       session.pushFrame((Date.now() - t) / 1000, data.replace(/\r?\n/g, "\r\n"));
-    });
+    }, cwd);
     session.markClosed();
     const stdout = truncateUtf8(res.stdout);
     const stderr = truncateUtf8(res.stderr);
     const seq = recordExec({
       service,
       command,
+      cwd,
       exitCode: res.exitCode,
       stdout: stdout.value,
       stdoutTruncated: stdout.truncated,

package/src/index.ts

@@ -572,8 +572,17 @@ export interface TestContext<
    *  program sees plain pipes (`isatty` false), so stdout/stderr stay
    *  byte-identical to what `exec` always returned and TTY-gated
    *  spinners/colour won't be emitted — reach for `terminal` when the
-   *  CLI needs to believe it's on a TTY. */
-  exec(service: string, command: string): Promise<Wrapped<ExecResult>>;
+   *  CLI needs to believe it's on a TTY.
+   *
+   *  Pass `{ cwd }` to run the command from a working directory instead of
+   *  prefixing it with `cd <dir> && ` — the cwd is kept off the command
+   *  string, so the timeline sidebar shows just the command and the
+   *  directory surfaces in the detail view. */
+  exec(
+    service: string,
+    command: string,
+    opts?: ExecOpts,
+  ): Promise<Wrapped<ExecResult>>;
   /**
    * Run a command inside a service container under a PTY and record the
    * full terminal session as an asciicast for replay in the web UI.
@@ -756,6 +765,20 @@ export interface ExecResult {
   exitCode: number;
 }
 
+/** Options for {@link TestContext.exec}. */
+export interface ExecOpts {
+  /**
+   * Working directory inside the container to run the command from.
+   * Equivalent to prefixing the command with `cd <cwd> && `, but the
+   * directory is kept off the command string: the recorded step's
+   * sidebar summary shows just the command, while the working directory
+   * is surfaced in the detail view (the prompt line of the captured
+   * terminal and the step's panel header). Implemented as `docker exec
+   * -w <cwd>`, so a relative path resolves against the image's WORKDIR.
+   */
+  cwd?: string;
+}
+
 export interface TestSuite<
   S extends ServicesMap = ServicesMap,
   F extends FakesMap = FakesMap,
@@ -997,7 +1020,11 @@ export interface ProjectSetupContext<
   F extends FakesMap = FakesMap,
 > {
   fetch: SpectestFetch;
-  exec(service: string, command: string): Promise<Wrapped<ExecResult>>;
+  exec(
+    service: string,
+    command: string,
+    opts?: ExecOpts,
+  ): Promise<Wrapped<ExecResult>>;
   readonly svc: ServiceHandlesFor<S>;
   /** Same surface tests see — fakes are already up by setup time. Typed
    * against the declared fakes map (see {@link TestContext.fakes}). */
@@ -1341,6 +1368,15 @@ interface Transforms {
   /** URL-decode the value, mirroring `decodeURIComponent(x)`. Chains after
    *  `base64Decoded()` for base64-then-URL-encoded values. */
   urlDecoded(): Expectation;
+  /** Parse the value as JSON (`JSON.parse(x)`) and assert on the result with the
+   *  full matcher vocabulary — `toEqual` against the decoded object/array,
+   *  `toContain`/`toHaveLength` against a decoded array. Throws-as-failed-assertion
+   *  if the value isn't a string or isn't valid JSON. Chains after other
+   *  transforms (e.g. `base64Decoded().jsonDecoded()` for a base64-wrapped JSON
+   *  payload). The optional type parameter `T` annotates the decoded shape at the
+   *  call site (`jsonDecoded<User>()`) — it casts the parsed value, but, like the
+   *  matchers, is not enforced at runtime. */
+  jsonDecoded<T = unknown>(): Expectation;
   /**
    * Generic escape hatch: apply an arbitrary `fn` to the raw value and assert on
    * the result, keeping provenance. `label` is a plain word (`"json"`,

package/src/recorder.ts

@@ -47,6 +47,12 @@ export interface ExecEvent extends BaseEvent {
   kind: "exec";
   service: string;
   command: string;
+  /**
+   * Working directory the command ran from (`ctx.exec(svc, cmd, { cwd })`),
+   * if any. Kept off `command` so the sidebar shows just the command; the
+   * detail view surfaces it. Absent when the call used no `cwd`.
+   */
+  cwd?: string;
   exitCode: number;
   /** stdout truncated to OUTPUT_SNIPPET_BYTES. */
   stdout: string;