@specific.dev/spectest 0.98.0 → 0.100.0

package/README.md

@@ -128,3 +128,35 @@ routes each stream by `:authority`, and preserves streaming bodies, metadata,
 trailers, and cancellation. HTTP/1.1 requests still use the existing HTTP proxy.
 Runtime services support the same option. HTTP/2 streams currently bypass
 `ctx.intercept` and HTTP request recording.
+
+### CORS at ingress
+
+Fake and service ingress default to `cors: "passthrough"`: OPTIONS requests
+reach the handler or upstream through `ctx.intercept`, and response CORS headers
+are preserved, including their absence on rejections or responses with no CORS
+policy. Allowed credentialed requests depend on the application's own headers.
+
+Automatic CORS is opt-in per fake or service hostname:
+
+```ts
+defineFake({ name: "api", hostnames: ["api.test"], cors: "permissive", handler });
+// On a boot or runtime service:
+tls: [{ hostname: "api.test", port: 3000, cors: "permissive" }]
+// On a Supabase gateway (including responses from interceptors):
+supabase({ hostname: "supabase.example.com", cors: "permissive" });
+// On a low-level component proxy:
+proxy("api.test", { service: "api", port: 3000, cors: "permissive" });
+```
+
+Permissive HTTP/1 ingress answers CORS preflights before interceptors and adds
+reflected allow-origin plus allow-credentials to responses without allow-origin,
+including errors. Ordinary OPTIONS still reaches the handler. Use passthrough
+when testing application CORS policies. HTTP/2 streams always pass CORS through.
+
+Prefer the application's production hostnames for the frontend and API inside
+the environment: Spectest resolves declared names to its test services and
+provides certificates trusted inside the environment. This preserves existing
+origin allowlists and cookie relationships. Different subdomains are still
+different origins; a synthetic response must still supply the intended CORS
+headers. Permissive mode is a convenience override and should not be used to
+verify application CORS restrictions.

package/dist/components/index.d.ts

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

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

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

package/dist/components/replay-key.js

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

package/dist/components/replayFake.d.ts

@@ -1,18 +1,6 @@
 import type { FakeDefinition } from "../index.js";
-/** Which parts of a request define a match against the cassette. */
-export interface ReplayMatch {
-    /** Match on HTTP method. Default `true`. */
-    method?: boolean;
-    /** Match on path (no query). Default `true`. */
-    path?: boolean;
-    /** Match on normalized query string. Default `true`. */
-    query?: boolean;
-    /** Match on body: `true` = exact decoded body, `"hash"` = sha256 only.
-     *  Default off. */
-    body?: boolean | "hash";
-    /** Header names (lowercase) to include in the match. Default none. */
-    headers?: string[];
-}
+import { type ReplayKey } from "./replay-key.js";
+export type { JsonValue, MatchKey, ReplayRequest, ReplayKey } from "./replay-key.js";
 /** Match one request dimension. A bare string is an exact match; the
  *  object forms cover prefix and regex matching. */
 export type StringMatch = string | {
@@ -75,8 +63,12 @@ export interface ReplayFakeOptions {
      *  resolved via an external DNS server — see the module header). Your
      *  app points at this real host directly; no separate stand-in. */
     host: string;
-    /** What defines a request match. Default `{ method, path, query }`. */
-    match?: ReplayMatch;
+    /** Complete request identity. Default: method, path, normalized query,
+     *  and exact body bytes. The same synchronous, deterministic callback runs
+     *  on recorded and incoming requests. Return JSON values and/or Uint8Array
+     *  bytes; objects compare independently of property order. No implicit
+     *  matching dimensions or fallback apply when a key is supplied. */
+    key?: ReplayKey;
     /** Per-fake credential brokering. Rules are evaluated in
      *  order; the first whose `match` matches wins (a rule without `match`
      *  matches everything and shadows later rules). Applied at the
@@ -101,7 +93,8 @@ export interface CassetteRequest {
     path: string;
     /** Normalized: keys + repeated values sorted, so matching is order-free. */
     query: Record<string, string[]>;
-    /** Matched/readable header subset only — never `authorization`/`cookie`. */
+    /** Captured non-sensitive headers — never `authorization`/`cookie`.
+     *  Older cassettes may contain only content-type and selected headers. */
     headers: Record<string, string>;
     bodyHash?: string;
     /** Request body (omitted when empty): decoded + redacted UTF-8 text, or
@@ -131,6 +124,8 @@ export interface Cassette {
 /** Forked-per-test state for one replay fake. */
 export interface CassetteState {
     cassette: Cassette;
+    /** Complete signature → cassette interaction indexes, in cassette order. */
+    index: Map<string, number[]>;
     /** Per-match-signature replay cursor (call-order sequencing). */
     cursor: Map<string, number>;
     /** Interactions captured this record session. */

package/dist/components/replayFake.js

@@ -62,6 +62,7 @@ import { brotliDecompressSync, gunzipSync, inflateSync } from "node:zlib";
 import * as dnsPacket from "dns-packet";
 import { isRecording } from "../recorder.js";
 import { getRecordSecret } from "../record-secrets.js";
+import { replaySignature } from "./replay-key.js";
 import { inferSigV4Scope, signAwsV4Request, } from "../aws-sigv4.js";
 // ────────────────────────────────────────────────────────────────────────
 // Helpers
@@ -71,7 +72,9 @@ const SENSITIVE_HEADERS = new Set([
     "cookie",
     "set-cookie",
     "proxy-authorization",
+    "api-key",
     "x-api-key",
+    "x-goog-api-key",
     "x-amz-security-token",
 ]);
 /** Hop-by-hop + body-framing headers never forwarded / never replayed
@@ -97,15 +100,6 @@ const STRIP_FORWARD_HEADERS = new Set([
  *  resolver (which points the faked host back at the daemon). */
 const EXTERNAL_DNS = process.env.SPECTEST_UPSTREAM_DNS ?? "1.1.1.1";
 const EXTERNAL_DNS_PORT = Number(process.env.SPECTEST_UPSTREAM_PORT ?? "53");
-function defaultMatch(m) {
-    return {
-        method: m?.method ?? true,
-        path: m?.path ?? true,
-        query: m?.query ?? true,
-        body: m?.body,
-        headers: m?.headers,
-    };
-}
 /** SigV4 puts per-request signing params (`X-Amz-Signature`, `X-Amz-Date`, …)
  *  in the query for presigned URLs — they change every call and would poison
  *  query matching, so they're dropped from both the match key and the forward
@@ -144,31 +138,6 @@ function recordable(headers, want) {
     }
     return out;
 }
-/** Canonical match signature for an interaction's request, used as both
- *  the replay-cursor key and the equality basis (two requests match iff
- *  their signatures are equal). Computed identically for an incoming
- *  request and a stored `CassetteRequest`. */
-function signature(req, match) {
-    const sig = {};
-    if (match.method)
-        sig.method = req.method.toUpperCase();
-    if (match.path)
-        sig.path = req.path;
-    if (match.query)
-        sig.query = req.query;
-    if (match.body === true)
-        sig.body = req.body ?? "";
-    else if (match.body === "hash")
-        sig.bodyHash = req.bodyHash ?? "";
-    if (match.headers && match.headers.length > 0) {
-        const h = {};
-        for (const name of match.headers.map((n) => n.toLowerCase()).sort()) {
-            h[name] = req.headers[name] ?? "";
-        }
-        sig.headers = h;
-    }
-    return JSON.stringify(sig);
-}
 /** The project's `spectest/tests/` dir — cassettes live alongside the
  *  tests, and a `replay(path)` argument is a path relative to here. Keeping
  *  them under `tests/` means re-recording is picked up on the next run with
@@ -190,7 +159,7 @@ function coerceCassette(parsed, name, host) {
         version: 1,
         fake: parsed.fake ?? name,
         host: parsed.host ?? host,
-        interactions: parsed.interactions,
+        interactions: structuredClone(parsed.interactions),
     };
 }
 /** Read a cassette by its path relative to `spectest/tests/` (e.g.
@@ -218,7 +187,7 @@ function readCassetteFile(name, file, host) {
 /** Decode response bytes to a string, falling back to base64 for binary. */
 function decodeBody(bytes) {
     try {
-        const text = new TextDecoder("utf8", { fatal: true }).decode(bytes);
+        const text = new TextDecoder("utf8", { fatal: true, ignoreBOM: true }).decode(bytes);
         return { body: text, bodyEncoding: "utf8" };
     }
     catch {
@@ -434,7 +403,12 @@ export function replayFake(opts) {
         throw new Error(`replayFake(${opts.name}): "host" (the real hostname) is required`);
     }
     const host = opts.host.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
-    const match = defaultMatch(opts.match);
+    if ("match" in opts) {
+        throw new Error(`replayFake(${opts.name}): \`match\` has been replaced by \`key(request)\`, which defines the complete request identity`);
+    }
+    if (opts.key !== undefined && typeof opts.key !== "function") {
+        throw new Error(`replayFake(${opts.name}): \`key\` must be a synchronous function`);
+    }
     const injectRules = opts.inject ?? [];
     // Refs every header template references — the control plane resolves these
     // server-side and pushes them for the environment lifetime (see the daemon's
@@ -448,19 +422,33 @@ export function replayFake(opts) {
         return isRecording() ? "replay" : "record";
     };
     // ── REPLAY ──────────────────────────────────────────────────────────
+    function signature(request, location) {
+        try {
+            return replaySignature(request, opts.key);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`replayFake(${opts.name}): invalid replay key for ${location}: ${message}`);
+        }
+    }
     function replay(reqLike, state) {
-        const sig = signature(reqLike, match);
-        const matches = [];
-        for (const it of state.cassette.interactions) {
-            if (signature(it.request, match) === sig)
-                matches.push(it);
+        let sig;
+        try {
+            sig = signature(reqLike, "incoming request");
+        }
+        catch (error) {
+            return new Response(error.message + "\n", {
+                status: 599, headers: { "content-type": "text/plain" },
+            });
         }
+        const matches = state.index.get(sig) ?? [];
         const idx = state.cursor.get(sig) ?? 0;
-        const hit = matches[idx];
+        const interactionIndex = matches[idx];
+        const hit = interactionIndex === undefined ? undefined : state.cassette.interactions[interactionIndex];
         if (!hit) {
             const body = `replayFake(${opts.name}): no cassette interaction for ` +
-                `${reqLike.method} ${reqLike.path} (matched ${matches.length}, wanted #${idx + 1}). ` +
-                `Re-record the cassette, or relax \`match\`.\n`;
+                `${reqLike.method} ${reqLike.path} (${matches.length === 0 ? "unknown key" : "exhausted key"}; matched ${matches.length}, wanted #${idx + 1}). ` +
+                `Check \`key\` or re-record the cassette.\n`;
             return new Response(body, {
                 status: 599,
                 headers: { "content-type": "text/plain" },
@@ -618,7 +606,7 @@ export function replayFake(opts) {
                 method: reqLike.method,
                 path: reqLike.path,
                 query: redactedQuery,
-                headers: reqLike.headers,
+                headers: Object.fromEntries(Object.entries(reqLike.headers).map(([k, v]) => [k, redact(v)])),
                 ...(reqLike.body !== undefined
                     ? {
                         bodyHash: reqLike.bodyHash,
@@ -667,7 +655,7 @@ export function replayFake(opts) {
             // Strip SigV4 `x-amz-*` query params from the match key when signing —
             // presigned URLs carry a per-request signature there.
             query: normalizeQuery(url.searchParams, opts.sign !== undefined),
-            headers: recordable(req.headers, ["content-type", ...(match.headers ?? [])]),
+            headers: recordable(req.headers, [...req.headers.keys()]),
             ...(decodedBody
                 ? {
                     bodyHash: sha256Bytes(bodyBytes),
@@ -690,6 +678,7 @@ export function replayFake(opts) {
         // `replay(...)` to populate it.
         state: () => ({
             cassette: emptyCassette(opts.name, host),
+            index: new Map(),
             cursor: new Map(),
             recorded: [],
             dirty: false,
@@ -711,22 +700,34 @@ export function replayFake(opts) {
                     throw new Error(`replayFake(${opts.name}): replay(...) needs a cassette path under spectest/tests/ ` +
                         `(e.g. "recordings/${opts.name}.json").`);
                 }
+                // Build/validate before replacing live state: a bad key/cassette
+                // must leave the previous cassette and consumption cursors intact.
+                const index = new Map();
+                for (const [i, interaction] of loaded.interactions.entries()) {
+                    const sig = signature(interaction.request, `${JSON.stringify(label)} interaction #${i + 1}`);
+                    const queue = index.get(sig);
+                    if (queue)
+                        queue.push(i);
+                    else
+                        index.set(sig, [i]);
+                }
                 // Mutate the live state object (the handler reads the same
                 // reference); reset the cursor so replay starts from the top.
                 state.cassette = loaded;
+                state.index = index;
                 state.cursor = new Map();
                 return { cassette: label, host: loaded.host, interactions: loaded.interactions.length };
             },
             dump() {
-                return {
+                return structuredClone({
                     version: 1,
                     fake: opts.name,
                     host,
                     interactions: [...state.cassette.interactions, ...state.recorded],
-                };
+                });
             },
             recorded() {
-                return state.recorded.slice();
+                return structuredClone(state.recorded);
             },
             count() {
                 return state.recorded.length;

package/dist/components/supabase.d.ts

@@ -1,4 +1,4 @@
-import { type ServiceDefinition, type ServiceGroup, type ServicesMap } from "../index.js";
+import { type CorsMode, type ServiceDefinition, type ServiceGroup, type ServicesMap } from "../index.js";
 import { type SqlClient } from "../sql.js";
 import { type EmailHelpers } from "./email.js";
 export type { MailTemplateId, MailTemplateSpec } from "./supabase-config.js";
@@ -63,6 +63,10 @@ export interface SupabaseOptions {
      * test hardcodes a Supabase URL it cannot be told to override.
      */
     hostname?: string;
+    /** CORS handling at the daemon ingress for `hostname`. Defaults to
+     * "passthrough", preserving gateway/interceptor policy. "permissive"
+     * restores automatic preflight replies and credentialed CORS headers. */
+    cors?: CorsMode;
     /**
      * Capture GoTrue's outgoing mail (signup confirmations, magic links, OTPs,
      * password recovery, invites) with the standard `email()` component. **On

package/dist/components/supabase.js

@@ -55,6 +55,7 @@ import { excludeAllBut, functionsReach } from "./supabase-functions-reach.js";
 import { readdir, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { serviceGroup, } from "../index.js";
+import { validateCorsMode } from "../ingress.js";
 import { SQL } from "../sql.js";
 import { apple } from "./apple.js";
 import { email, emailHelpers } from "./email.js";
@@ -1211,6 +1212,7 @@ db) {
  * for hitting the REST/auth/storage APIs through the gateway.
  */
 export function supabase(opts = {}) {
+    validateCorsMode(opts.cors);
     const name = opts.name ?? "supabase";
     const dbPassword = opts.dbPassword ?? "postgres";
     const jwtSecret = opts.jwtSecret ?? DEFAULT_JWT_SECRET;
@@ -1866,7 +1868,7 @@ export function supabase(opts = {}) {
                     },
                 ],
                 ports: [8000, 8443],
-                ...(opts.hostname ? { tls: [{ hostname: opts.hostname, port: 8000 }] } : {}),
+                ...(opts.hostname ? { tls: [{ hostname: opts.hostname, port: 8000, ...(opts.cors ? { cors: opts.cors } : {}) }] } : {}),
                 readyCheck: { type: "exec", command: "kong health", timeoutSecs: 90 },
             };
             return parts;

package/dist/daemon.js

@@ -56,7 +56,7 @@ import { installFetchWrapper, isTransportError } from "./harness/fetch.js";
 import { bindInstrumentationScope, createInstrumentationScope, runInstrumented, runUninstrumented, } from "./harness/instrumentation-scope.js";
 import { encodeRegistry } from "./harness/names-registry.js";
 import { InterceptRegistry, parseTarget, runChain, } from "./harness/intercept.js";
-import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, upstreamRequestHeaders, } from "./harness/http-proxy.js";
+import { HOP_BY_HOP_HEADERS, withIngressCors, upstreamRequestHeaders, } from "./harness/http-proxy.js";
 import { WS_BRIDGE_HANDLERS, openUpstreamWebSocket, parseSubprotocols, upstreamHandshakeHeaders, } from "./harness/ws-bridge.js";
 import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, selectCertName, wildcardSuffix, } from "./harness/hostmatch.js";
 import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
@@ -1707,7 +1707,7 @@ async function startIngress() {
     if (LOWERED.proxies.length > 0) {
         const routes = ensurePort(INGRESS_HTTP_PORT);
         for (const p of LOWERED.proxies) {
-            routes.set(p.hostname, { kind: "proxy", service: p.service, port: p.port, ...(p.http2 ? { http2: true } : {}) });
+            routes.set(p.hostname, { kind: "proxy", service: p.service, port: p.port, ...(p.http2 ? { http2: true } : {}), ...(p.cors ? { cors: p.cors } : {}) });
         }
     }
     // The :443 route table mirrors every handler whose hostname a cert
@@ -1724,7 +1724,7 @@ async function startIngress() {
         }
         for (const p of LOWERED.proxies) {
             if (certCovers(p.hostname)) {
-                httpsRoutes.set(p.hostname, { kind: "proxy", service: p.service, port: p.port, ...(p.http2 ? { http2: true } : {}) });
+                httpsRoutes.set(p.hostname, { kind: "proxy", service: p.service, port: p.port, ...(p.http2 ? { http2: true } : {}), ...(p.cors ? { cors: p.cors } : {}) });
             }
         }
     }
@@ -1876,16 +1876,16 @@ function certCovers(hostname) {
  * 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, service, port, http2) {
+async function bindRuntimeTls(hostname, service, port, http2, cors) {
     // 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, http2 });
+    const decl = makeProxyDecl(hostname, { service, port, http2, cors });
     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 = { kind: "proxy", service, port, http2 };
+    const route = { kind: "proxy", service, port, http2, cors };
     // Decide the cost before mutating anything: an already-covered hostname
     // (an exact duplicate, or one under a boot wildcard) needs only a route.
     const plan = planBind(INGRESS, host, {
@@ -2030,12 +2030,6 @@ server, byHost, listenerLabel, proto) {
     if (!route) {
         return new Response(`spectest-daemon: no ingress route bound to Host=${JSON.stringify(host)} on ${listenerLabel}\n`, { status: 404, headers: { "content-type": "text/plain" } });
     }
-    // Answer CORS preflights at the ingress (see corsPreflightResponse) so a
-    // cross-origin browser request carrying any header — Authorization,
-    // Cache-Control, Pragma, … — isn't rejected by whatever the upstream happens
-    // to list in Access-Control-Allow-Headers.
-    if (isCorsPreflight(req))
-        return corsPreflightResponse(req);
     // The real answer — a fake handled in-process, or the proxied container.
     const upstream = async (current) => {
         if (route.kind === "fake") {
@@ -2049,15 +2043,15 @@ server, byHost, listenerLabel, proto) {
         }
         return proxyToService(current, server, route.service, route.port, listenerLabel, proto);
     };
-    // `ctx.intercept` middleware runs first, in registration order, and reaches
-    // the upstream through `next()`. The CORS headers go on *after* the chain,
-    // so a forced 500 reaches the browser as a 500 and not as a CORS error —
-    // the trap `page.route`-style interception falls into.
-    const chain = INTERCEPTORS.chainFor(host, new URL(req.url).pathname);
-    const res = chain.length === 0
-        ? await upstream(req)
-        : await runChain(chain, req, upstream, recordInterceptedRequest);
-    return augmentCorsResponse(req, res);
+    // Passthrough (the default) lets middleware and the upstream handle every
+    // request and preserves their CORS policy, including absent headers.
+    const cors = route.kind === "fake" ? route.fake.def.cors : route.cors;
+    return withIngressCors(req, cors, async (current) => {
+        const chain = INTERCEPTORS.chainFor(host, new URL(current.url).pathname);
+        return chain.length === 0
+            ? upstream(current)
+            : runChain(chain, current, upstream, recordInterceptedRequest);
+    });
 }
 /**
  * The address to report as the client's in `X-Forwarded-For`.
@@ -2619,7 +2613,7 @@ async function startRuntimeService(spec) {
         // `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, entry.http2);
+            await bindRuntimeTls(entry.hostname, svc.name, entry.port, entry.http2, entry.cors);
         }
         RUNTIME_SERVICES.set(svc.name, svc);
         recordEnv({

package/dist/harness/http-proxy.d.ts

@@ -1,3 +1,4 @@
+import type { CorsMode } from "../ingress.js";
 /**
  * HTTP semantics the ingress proxy has to get right: which headers must
  * not be forwarded, and how CORS is answered.
@@ -37,9 +38,8 @@ export declare function isCorsPreflight(req: {
     };
 }): boolean;
 /**
- * Answer a preflight permissively — the environment is hermetic, so
- * there is nothing here to protect from itself, and a test failing on
- * CORS teaches nothing about the app.
+ * Answer a preflight for explicitly permissive ingress only. Passthrough
+ * must let the application or interceptor decide, including rejecting it.
  *
  * The one rule that is not a matter of taste: the **specific** origin is
  * echoed rather than `*`. `Allow-Origin: *` together with
@@ -53,15 +53,15 @@ export declare function corsPreflightResponse(req: {
     };
 }): Response;
 /**
- * Add CORS headers to a proxied response, without overriding the
- * upstream's own.
- *
- * An app that already sets `Access-Control-Allow-Origin` has an opinion —
- * possibly a deliberately restrictive one that a test is checking — and
- * replacing it would make the environment lie about the app's behaviour.
+ * Add CORS headers only when permissive ingress was explicitly requested.
+ * An absent allow-origin can be a deliberate rejection; callers must never
+ * use this augmentation in passthrough mode. Existing allow-origin is kept.
  */
 export declare function augmentCorsResponse(req: {
     headers: {
         get(n: string): string | null;
     };
 }, res: Response): Response;
+/** Apply the same policy around the entire fake/proxy + interceptor chain.
+ * Passthrough forwards even preflights and preserves the response unchanged. */
+export declare function withIngressCors(req: Request, cors: CorsMode | undefined, handle: (req: Request) => Response | Promise<Response>): Promise<Response>;

package/dist/harness/http-proxy.js

@@ -64,9 +64,8 @@ export function isCorsPreflight(req) {
         req.headers.has("access-control-request-method"));
 }
 /**
- * Answer a preflight permissively — the environment is hermetic, so
- * there is nothing here to protect from itself, and a test failing on
- * CORS teaches nothing about the app.
+ * Answer a preflight for explicitly permissive ingress only. Passthrough
+ * must let the application or interceptor decide, including rejecting it.
  *
  * The one rule that is not a matter of taste: the **specific** origin is
  * echoed rather than `*`. `Allow-Origin: *` together with
@@ -88,15 +87,13 @@ export function corsPreflightResponse(req) {
     // one origin's preflight to another.
     headers.append("vary", "Origin");
     headers.append("vary", "Access-Control-Request-Headers");
+    headers.append("vary", "Access-Control-Request-Method");
     return new Response(null, { status: 204, headers });
 }
 /**
- * Add CORS headers to a proxied response, without overriding the
- * upstream's own.
- *
- * An app that already sets `Access-Control-Allow-Origin` has an opinion —
- * possibly a deliberately restrictive one that a test is checking — and
- * replacing it would make the environment lie about the app's behaviour.
+ * Add CORS headers only when permissive ingress was explicitly requested.
+ * An absent allow-origin can be a deliberate rejection; callers must never
+ * use this augmentation in passthrough mode. Existing allow-origin is kept.
  */
 export function augmentCorsResponse(req, res) {
     const origin = req.headers.get("origin");
@@ -116,3 +113,11 @@ export function augmentCorsResponse(req, res) {
     }
     return res;
 }
+/** Apply the same policy around the entire fake/proxy + interceptor chain.
+ * Passthrough forwards even preflights and preserves the response unchanged. */
+export async function withIngressCors(req, cors, handle) {
+    if (cors === "permissive" && isCorsPreflight(req))
+        return corsPreflightResponse(req);
+    const res = await handle(req);
+    return cors === "permissive" ? augmentCorsResponse(req, res) : res;
+}