@specific.dev/spectest 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.6.0",
+  "version": "0.8.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

@@ -24,7 +24,15 @@ import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard } from "./index.js";
+import {
+  assert,
+  expect,
+  expectRaw,
+  lowerIngress,
+  dnsName as makeDnsDecl,
+  isWildcard,
+  proxy as makeProxyDecl,
+} from "./index.js";
 import type { DnsTarget, LoweredIngress } from "./index.js";
 import { openBrowser } from "./browser.js";
 import { openMobile, isMobileApp } from "./mobile.js";
@@ -1222,6 +1230,24 @@ const INGRESS_HTTP_SERVERS = new Map<number, any>();
 /** Running HTTPS servers per port (currently always {INGRESS_HTTPS_PORT}). */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const INGRESS_HTTPS_SERVERS = new Map<number, any>();
+/**
+ * Live per-port route tables, keyed by listen port (80 / 443 / fake ports).
+ * Each listener's `fetch` closure captures *this* Map object, so adding an
+ * entry takes effect immediately with no rebind — that's what lets a runtime
+ * `tls` (a `ctx.startService({ tls })`) bind a new ingress route after boot.
+ * Held at module scope so it's part of the live daemon process and forks
+ * with the snapshot, exactly like fake state / the names REGISTRY. Rebuilt on
+ * /load (cleared by {@link stopIngressServers}).
+ */
+const INGRESS_ROUTES_BY_PORT = new Map<number, Map<string, Route>>();
+/**
+ * The :443 SNI cert table: serverName → leaf. Unlike the route table, Bun's
+ * TLS config is fixed at `Bun.serve` time (reload won't add an SNI entry), so
+ * minting a cert for a *new* hostname requires rebinding the :443 listener
+ * (cheap, ~1ms — see {@link rebindHttpsListener}). A hostname already covered
+ * by an existing exact or wildcard cert needs no rebind, just a route entry.
+ */
+const HTTPS_CERT_BY_HOST = new Map<string, { cert: string; key: string }>();
 
 /**
  * Tear down listener servers between /load calls so the new project's
@@ -1246,6 +1272,8 @@ function stopIngressServers(): void {
     }
   }
   INGRESS_HTTPS_SERVERS.clear();
+  INGRESS_ROUTES_BY_PORT.clear();
+  HTTPS_CERT_BY_HOST.clear();
 }
 
 function buildIngress(project: Project): void {
@@ -1441,12 +1469,11 @@ async function startIngress(): Promise<void> {
   // before binding so the HTTPS listener has certs ready and a startup
   // failure aborts /bootstrap cleanly.
   const caPresent = existsSync(CA_PATH) && existsSync(CA_KEY_PATH);
-  const certByHost = new Map<string, { cert: string; key: string }>();
   if (caPresent) {
     for (const group of LOWERED.certificates) {
       if (group.hostnames.length === 0) continue;
       const leaf = await generateHostCert(group.hostnames[0], group.hostnames);
-      for (const h of group.hostnames) certByHost.set(h, leaf);
+      for (const h of group.hostnames) HTTPS_CERT_BY_HOST.set(h, leaf);
     }
   } else if (LOWERED.certificates.length > 0) {
     // eslint-disable-next-line no-console
@@ -1455,73 +1482,49 @@ async function startIngress(): Promise<void> {
     );
   }
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const Bun = (globalThis as any).Bun;
-  if (!Bun?.serve) {
-    throw new Error(
-      "ingress requires Bun.serve; the daemon must run under Bun (it does in-VM)",
-    );
-  }
-
-  // Resolve every ingress hostname to its handler. Fakes run an in-daemon
-  // handler; proxies reverse-proxy to a service:port. This single table
-  // drives both the HTTP and HTTPS listeners.
-  const routeByHost = new Map<string, Route>();
-  for (const fake of FAKES.values()) {
-    for (const h of fake.hostnames) routeByHost.set(h, { kind: "fake", fake });
-  }
-  for (const p of LOWERED.proxies) {
-    routeByHost.set(p.hostname, { kind: "proxy", service: p.service, port: p.port });
-  }
+  const Bun = requireBun();
 
-  // ── HTTP listeners: group routes by port, dispatch per-request by Host.
-  //    Proxies bind :80 (HTTPS, if any, is on :443); fakes use their
-  //    declared port. Skip :443 in the HTTP map — HTTPS wins.
-  const httpRoutesByPort = new Map<number, Map<string, Route>>();
+  // Resolve every ingress hostname to its handler into the live per-port
+  // route tables (module scope, so runtime `tls` can extend them later).
+  // Fakes run an in-daemon handler on their declared port; proxies
+  // reverse-proxy to a service:port and bind :80 (HTTPS, if any, is :443).
   const ensurePort = (port: number): Map<string, Route> => {
-    const m = httpRoutesByPort.get(port) ?? new Map<string, Route>();
-    httpRoutesByPort.set(port, m);
+    const m = INGRESS_ROUTES_BY_PORT.get(port) ?? new Map<string, Route>();
+    INGRESS_ROUTES_BY_PORT.set(port, m);
     return m;
   };
   for (const fake of FAKES.values()) {
     if (fake.port === INGRESS_HTTPS_PORT) continue;
     const routes = ensurePort(fake.port);
-    for (const h of fake.hostnames) routes.set(h, routeByHost.get(h)!);
+    for (const h of fake.hostnames) routes.set(h, { kind: "fake", fake });
   }
   if (LOWERED.proxies.length > 0) {
     const routes = ensurePort(INGRESS_HTTP_PORT);
-    for (const p of LOWERED.proxies) routes.set(p.hostname, routeByHost.get(p.hostname)!);
+    for (const p of LOWERED.proxies) {
+      routes.set(p.hostname, { kind: "proxy", service: p.service, port: p.port });
+    }
   }
-  for (const [port, byHost] of httpRoutesByPort) {
-    const label = `port ${port}`;
-    INGRESS_HTTP_SERVERS.set(port, bindIngressServer(Bun, port, byHost, label));
-    const hosts = [...byHost.keys()].join(", ");
-    // eslint-disable-next-line no-console
-    console.log(`[ingress] http :${port} for ${hosts}`);
+  // The :443 route table mirrors every certificated hostname's handler.
+  if (HTTPS_CERT_BY_HOST.size > 0) {
+    const httpsRoutes = ensurePort(INGRESS_HTTPS_PORT);
+    for (const h of HTTPS_CERT_BY_HOST.keys()) {
+      for (const fake of FAKES.values()) {
+        if (fake.hostnames.includes(h)) httpsRoutes.set(h, { kind: "fake", fake });
+      }
+      const proxy = LOWERED.proxies.find((p) => p.hostname === h);
+      if (proxy) httpsRoutes.set(h, { kind: "proxy", service: proxy.service, port: proxy.port });
+    }
   }
 
-  // ── HTTPS listener on INGRESS_HTTPS_PORT: SNI per certificated hostname.
-  if (certByHost.size > 0) {
-    const tlsEntries: Array<{ cert: string; key: string; serverName: string }> = [];
-    const byHostHttps = new Map<string, Route>();
-    for (const [h, leaf] of certByHost) {
-      tlsEntries.push({ cert: leaf.cert, key: leaf.key, serverName: h });
-      const route = routeByHost.get(h);
-      if (route) byHostHttps.set(h, route);
-    }
-    const label = `https :${INGRESS_HTTPS_PORT}`;
-    const server = bindIngressServer(
-      Bun,
-      INGRESS_HTTPS_PORT,
-      byHostHttps,
-      label,
-      tlsEntries,
-    );
-    INGRESS_HTTPS_SERVERS.set(INGRESS_HTTPS_PORT, server);
-    const hosts = [...byHostHttps.keys()].join(", ");
+  // ── HTTP listeners (one per non-443 port).
+  for (const [port, byHost] of INGRESS_ROUTES_BY_PORT) {
+    if (port === INGRESS_HTTPS_PORT) continue;
+    INGRESS_HTTP_SERVERS.set(port, bindIngressServer(Bun, port, byHost, `port ${port}`));
     // eslint-disable-next-line no-console
-    console.log(`[ingress] https :${INGRESS_HTTPS_PORT} for ${hosts}`);
+    console.log(`[ingress] http :${port} for ${[...byHost.keys()].join(", ")}`);
   }
+  // ── HTTPS listener on INGRESS_HTTPS_PORT: SNI per certificated hostname.
+  if (HTTPS_CERT_BY_HOST.size > 0) rebindHttpsListener(Bun);
 
   // Seed the resolver's names registry: ingress hostnames (fakes, TLS
   // proxies, dnsName(→ingress)) → bridge gateway, plus ingress-targeted
@@ -1530,6 +1533,148 @@ async function startIngress(): Promise<void> {
   await seedNamesRegistry({ servicesUp: false });
 }
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function requireBun(): any {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const Bun = (globalThis as any).Bun;
+  if (!Bun?.serve) {
+    throw new Error(
+      "ingress requires Bun.serve; the daemon must run under Bun (it does in-VM)",
+    );
+  }
+  return Bun;
+}
+
+/** Flatten {@link HTTPS_CERT_BY_HOST} into Bun's TLS-entry SNI array. */
+function tlsEntriesFromCerts(): Array<{ cert: string; key: string; serverName: string }> {
+  return [...HTTPS_CERT_BY_HOST].map(([serverName, leaf]) => ({
+    cert: leaf.cert,
+    key: leaf.key,
+    serverName,
+  }));
+}
+
+/**
+ * (Re)bind the :443 listener from the current cert table + route map. Bun's
+ * TLS config is immutable per `Bun.serve`, so adding an SNI cert means
+ * stopping the old listener and serving a fresh one — cheap (~1ms) and the
+ * window is sub-millisecond. The route Map is the persistent module object,
+ * so the new listener closes over the same table (later route additions need
+ * no rebind). No-ops to a plain rebind when only routes changed.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function rebindHttpsListener(Bun: any): void {
+  const routes = INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTPS_PORT) ?? new Map<string, Route>();
+  INGRESS_ROUTES_BY_PORT.set(INGRESS_HTTPS_PORT, routes);
+  const old = INGRESS_HTTPS_SERVERS.get(INGRESS_HTTPS_PORT);
+  if (old) {
+    try {
+      old.stop(true);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn("[ingress] failed to stop https listener for rebind:", err);
+    }
+  }
+  const server = bindIngressServer(
+    Bun,
+    INGRESS_HTTPS_PORT,
+    routes,
+    `https :${INGRESS_HTTPS_PORT}`,
+    tlsEntriesFromCerts(),
+  );
+  INGRESS_HTTPS_SERVERS.set(INGRESS_HTTPS_PORT, server);
+  // eslint-disable-next-line no-console
+  console.log(`[ingress] https :${INGRESS_HTTPS_PORT} for ${[...routes.keys()].join(", ")}`);
+}
+
+/** True if an exact or wildcard cert already covers `hostname` for SNI. */
+function certCovers(hostname: string): boolean {
+  if (HTTPS_CERT_BY_HOST.has(hostname)) return true;
+  for (const serverName of HTTPS_CERT_BY_HOST.keys()) {
+    if (isWildcard(serverName) && hostname.endsWith(wildcardSuffix(serverName))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Bind a runtime ingress route for one `tls: [{ hostname, port }]` entry on a
+ * {@link RuntimeServiceSpec} — the runtime twin of a boot service's `tls`.
+ * Mints a leaf cert (unless one already covers the hostname), stands up a
+ * TLS-terminating reverse proxy at `https://<hostname>/` → `service:port`,
+ * also serves plain `http://<hostname>/`, and points the hostname at the
+ * daemon gateway in the resolver registry. Idempotent per hostname.
+ *
+ * Everything it mutates (the live route tables, the :443 cert table, the
+ * names REGISTRY) is daemon-process state, so the binding forks with the
+ * per-test snapshot exactly like fake state — a `dependsOn` child inherits
+ * it, siblings forked from an earlier snapshot never see it.
+ */
+async function bindRuntimeTls(hostname: string, service: string, port: number): Promise<void> {
+  // Reuse the boot primitives for validation + lowercasing; throws on a
+  // malformed hostname / upstream just like a boot `tls` would at load.
+  const decl = makeProxyDecl(hostname, { service, port });
+  const host = decl.hostname;
+  if (!existsSync(CA_PATH) || !existsSync(CA_KEY_PATH)) {
+    throw new Error(
+      `runtime tls for ${JSON.stringify(host)} requires the in-VM root CA at ${CA_PATH}`,
+    );
+  }
+  const Bun = requireBun();
+  const route: Route = { kind: "proxy", service, port };
+
+  // Plain HTTP on :80 (parity with boot `tls`, which serves both schemes).
+  let httpRoutes = INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTP_PORT);
+  if (!httpRoutes) {
+    httpRoutes = new Map<string, Route>();
+    INGRESS_ROUTES_BY_PORT.set(INGRESS_HTTP_PORT, httpRoutes);
+  }
+  httpRoutes.set(host, route);
+  if (!INGRESS_HTTP_SERVERS.has(INGRESS_HTTP_PORT)) {
+    INGRESS_HTTP_SERVERS.set(
+      INGRESS_HTTP_PORT,
+      bindIngressServer(Bun, INGRESS_HTTP_PORT, httpRoutes, `port ${INGRESS_HTTP_PORT}`),
+    );
+  }
+
+  // HTTPS on :443. A new cert forces a listener rebind; an already-covered
+  // hostname (exact dup or a boot wildcard) just needs the route entry.
+  const needCert = !certCovers(host);
+  if (needCert) {
+    HTTPS_CERT_BY_HOST.set(host, await generateHostCert(host, [host]));
+  }
+  const httpsRoutes = INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTPS_PORT) ?? new Map<string, Route>();
+  INGRESS_ROUTES_BY_PORT.set(INGRESS_HTTPS_PORT, httpsRoutes);
+  httpsRoutes.set(host, route);
+  if (needCert || !INGRESS_HTTPS_SERVERS.has(INGRESS_HTTPS_PORT)) {
+    rebindHttpsListener(Bun);
+  }
+
+  // Resolve the hostname to the daemon gateway (where :443/:80 listen).
+  const gw = await bridgeGatewayIp();
+  REGISTRY.hosts[host] = gw;
+  await writeRegistry();
+  // eslint-disable-next-line no-console
+  console.log(`[ingress] runtime https ${host} -> ${service}:${port}`);
+}
+
+/**
+ * Undo {@link bindRuntimeTls} for one hostname when its runtime service is
+ * stopped: drop the route (so it 404s) and the registry entry. The cert is
+ * left in the SNI table — harmless without a route, and removing it would
+ * mean an avoidable :443 rebind.
+ */
+async function unbindRuntimeTls(hostname: string): Promise<void> {
+  const host = hostname.toLowerCase();
+  INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTP_PORT)?.delete(host);
+  INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTPS_PORT)?.delete(host);
+  if (host in REGISTRY.hosts) {
+    delete REGISTRY.hosts[host];
+    await writeRegistry();
+  }
+}
+
 /**
  * Spin up one Bun.serve listener bound to (port, optional TLS) that
  * dispatches every request to the matching Route by Host header.
@@ -2020,6 +2165,11 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
     await runContainer(svc, tag, flags, aliases);
     await waitForReady(svc);
     const ip = (await serviceContainerIp(svc.name)) ?? "";
+    // `tls` is the runtime twin of a boot service's: stand up a
+    // TLS-terminating reverse proxy at https://<hostname>/ → this container.
+    for (const entry of svc.tls ?? []) {
+      await bindRuntimeTls(entry.hostname, svc.name, entry.port);
+    }
     RUNTIME_SERVICES.set(svc.name, svc);
     recordEnv({
       op: "startService",
@@ -2046,8 +2196,10 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
 async function stopRuntimeService(name: string): Promise<void> {
   const t0 = Date.now();
   const resv = reserveEvent();
+  const svc = RUNTIME_SERVICES.get(name);
   await docker(["rm", "-f", name], 30_000);
   RUNTIME_SERVICES.delete(name);
+  for (const entry of svc?.tls ?? []) await unbindRuntimeTls(entry.hostname);
   recordEnv({ op: "stopService", service: name, durationMs: Date.now() - t0 }, resv);
 }
 

package/src/index.ts

@@ -348,22 +348,28 @@ export type ReadyCheck =
 /**
  * Spec for a service started at runtime via {@link TestContext.startService}
  * (or the `ctx` handed to a fake). It's a normal {@link ServiceConfig} plus a
- * required `name`, minus the two fields that only make sense at boot:
- *
- *  - `tls` — runtime services are reached *directly* by their own IP on
- *    `spectest-net` (like a real machine on a network), not through the
- *    daemon's HTTP ingress, so there's no proxy/cert to configure. Map a
- *    friendly DNS name onto one with {@link TestContext.dnsName}.
- *  - `dependsOn` — there is no boot DAG at runtime; the caller orders
- *    `startService` calls itself with `await`.
+ * required `name`, minus only `dependsOn` (there is no boot DAG at runtime;
+ * the caller orders `startService` calls itself with `await`).
  *
  * The container joins `spectest-net` with its own IP and is resolvable by
  * `name` (single-label, via the resolver / docker embedded DNS) and by any
  * `hostnames` (extra `--network-alias`es). Like everything else in the VM it
  * is captured by the per-test post-state snapshot, so a `dependsOn` child
  * inherits the live container while siblings never see it.
+ *
+ * `tls: [{ hostname, port }]` works exactly as it does for a boot service:
+ * the daemon mints a leaf cert from the in-VM root CA and stands up a
+ * TLS-terminating reverse proxy at `https://<hostname>/` (and plain
+ * `http://<hostname>/`) → the container's `port`, binding it onto the live
+ * `:443`/`:80` ingress listeners the moment the container is ready. The
+ * hostname resolves to the daemon gateway for tests, `ctx.browser()`, and
+ * peer containers. Because the route lives in daemon memory (and the
+ * resolver registry file), it forks with the per-test snapshot like fake
+ * state, and is torn down when the service is stopped. This lets a runtime
+ * provider mint a CA-trusted HTTPS endpoint on demand — e.g. a per-DB proxy
+ * the Neon serverless driver reaches at its *default* `https://<host>/sql`.
  */
-export interface RuntimeServiceSpec extends Omit<ServiceConfig, "tls" | "dependsOn"> {
+export interface RuntimeServiceSpec extends Omit<ServiceConfig, "dependsOn"> {
   /**
    * Container name and primary DNS name on `spectest-net`. Must be unique
    * within the current fork — generate a fresh one per provisioned instance