@specific.dev/spectest 0.98.0 → 0.100.0

package/src/components/replayFake.ts

@@ -65,6 +65,8 @@ import * as dnsPacket from "dns-packet";
 import type { FakeContext, FakeDefinition } from "../index.js";
 import { isRecording } from "../recorder.js";
 import { getRecordSecret } from "../record-secrets.js";
+import { replaySignature, type ReplayKey } from "./replay-key.js";
+export type { JsonValue, MatchKey, ReplayRequest, ReplayKey } from "./replay-key.js";
 import {
   inferSigV4Scope,
   signAwsV4Request,
@@ -75,21 +77,6 @@ import {
 // Options + cassette format
 // ────────────────────────────────────────────────────────────────────────
 
-/** Which parts of a request define a match against the cassette. */
-export interface ReplayMatch {
-  /** Match on HTTP method. Default `true`. */
-  method?: boolean;
-  /** Match on path (no query). Default `true`. */
-  path?: boolean;
-  /** Match on normalized query string. Default `true`. */
-  query?: boolean;
-  /** Match on body: `true` = exact decoded body, `"hash"` = sha256 only.
-   *  Default off. */
-  body?: boolean | "hash";
-  /** Header names (lowercase) to include in the match. Default none. */
-  headers?: string[];
-}
-
 /** Match one request dimension. A bare string is an exact match; the
  *  object forms cover prefix and regex matching. */
 export type StringMatch =
@@ -155,8 +142,12 @@ export interface ReplayFakeOptions {
    *  resolved via an external DNS server — see the module header). Your
    *  app points at this real host directly; no separate stand-in. */
   host: string;
-  /** What defines a request match. Default `{ method, path, query }`. */
-  match?: ReplayMatch;
+  /** Complete request identity. Default: method, path, normalized query,
+   *  and exact body bytes. The same synchronous, deterministic callback runs
+   *  on recorded and incoming requests. Return JSON values and/or Uint8Array
+   *  bytes; objects compare independently of property order. No implicit
+   *  matching dimensions or fallback apply when a key is supplied. */
+  key?: ReplayKey;
   /** Per-fake credential brokering. Rules are evaluated in
    *  order; the first whose `match` matches wins (a rule without `match`
    *  matches everything and shadows later rules). Applied at the
@@ -182,7 +173,8 @@ export interface CassetteRequest {
   path: string;
   /** Normalized: keys + repeated values sorted, so matching is order-free. */
   query: Record<string, string[]>;
-  /** Matched/readable header subset only — never `authorization`/`cookie`. */
+  /** Captured non-sensitive headers — never `authorization`/`cookie`.
+   *  Older cassettes may contain only content-type and selected headers. */
   headers: Record<string, string>;
   bodyHash?: string;
   /** Request body (omitted when empty): decoded + redacted UTF-8 text, or
@@ -216,6 +208,8 @@ export interface Cassette {
 /** Forked-per-test state for one replay fake. */
 export interface CassetteState {
   cassette: Cassette;
+  /** Complete signature → cassette interaction indexes, in cassette order. */
+  index: Map<string, number[]>;
   /** Per-match-signature replay cursor (call-order sequencing). */
   cursor: Map<string, number>;
   /** Interactions captured this record session. */
@@ -263,7 +257,9 @@ const SENSITIVE_HEADERS = new Set([
   "cookie",
   "set-cookie",
   "proxy-authorization",
+  "api-key",
   "x-api-key",
+  "x-goog-api-key",
   "x-amz-security-token",
 ]);
 
@@ -292,17 +288,6 @@ const STRIP_FORWARD_HEADERS = new Set([
 const EXTERNAL_DNS = process.env.SPECTEST_UPSTREAM_DNS ?? "1.1.1.1";
 const EXTERNAL_DNS_PORT = Number(process.env.SPECTEST_UPSTREAM_PORT ?? "53");
 
-function defaultMatch(m: ReplayMatch | undefined): Required<Omit<ReplayMatch, "body" | "headers">> &
-  Pick<ReplayMatch, "body" | "headers"> {
-  return {
-    method: m?.method ?? true,
-    path: m?.path ?? true,
-    query: m?.query ?? true,
-    body: m?.body,
-    headers: m?.headers,
-  };
-}
-
 /** SigV4 puts per-request signing params (`X-Amz-Signature`, `X-Amz-Date`, …)
  *  in the query for presigned URLs — they change every call and would poison
  *  query matching, so they're dropped from both the match key and the forward
@@ -341,27 +326,6 @@ function recordable(headers: Headers, want: string[]): Record<string, string> {
   return out;
 }
 
-/** Canonical match signature for an interaction's request, used as both
- *  the replay-cursor key and the equality basis (two requests match iff
- *  their signatures are equal). Computed identically for an incoming
- *  request and a stored `CassetteRequest`. */
-function signature(req: CassetteRequest, match: ReturnType<typeof defaultMatch>): string {
-  const sig: Record<string, unknown> = {};
-  if (match.method) sig.method = req.method.toUpperCase();
-  if (match.path) sig.path = req.path;
-  if (match.query) sig.query = req.query;
-  if (match.body === true) sig.body = req.body ?? "";
-  else if (match.body === "hash") sig.bodyHash = req.bodyHash ?? "";
-  if (match.headers && match.headers.length > 0) {
-    const h: Record<string, string> = {};
-    for (const name of match.headers.map((n) => n.toLowerCase()).sort()) {
-      h[name] = req.headers[name] ?? "";
-    }
-    sig.headers = h;
-  }
-  return JSON.stringify(sig);
-}
-
 /** The project's `spectest/tests/` dir — cassettes live alongside the
  *  tests, and a `replay(path)` argument is a path relative to here. Keeping
  *  them under `tests/` means re-recording is picked up on the next run with
@@ -386,7 +350,7 @@ function coerceCassette(parsed: Cassette, name: string, host: string): Cassette
     version: 1,
     fake: parsed.fake ?? name,
     host: parsed.host ?? host,
-    interactions: parsed.interactions,
+    interactions: structuredClone(parsed.interactions),
   };
 }
 
@@ -421,7 +385,7 @@ function readCassetteFile(name: string, file: string, host: string): Cassette {
 /** Decode response bytes to a string, falling back to base64 for binary. */
 function decodeBody(bytes: Uint8Array): { body: string; bodyEncoding: "utf8" | "base64" } {
   try {
-    const text = new TextDecoder("utf8", { fatal: true }).decode(bytes);
+    const text = new TextDecoder("utf8", { fatal: true, ignoreBOM: true }).decode(bytes);
     return { body: text, bodyEncoding: "utf8" };
   } catch {
     return { body: Buffer.from(bytes).toString("base64"), bodyEncoding: "base64" };
@@ -671,7 +635,12 @@ export function replayFake(
     throw new Error(`replayFake(${opts.name}): "host" (the real hostname) is required`);
   }
   const host = opts.host.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
-  const match = defaultMatch(opts.match);
+  if ("match" in opts) {
+    throw new Error(`replayFake(${opts.name}): \`match\` has been replaced by \`key(request)\`, which defines the complete request identity`);
+  }
+  if (opts.key !== undefined && typeof opts.key !== "function") {
+    throw new Error(`replayFake(${opts.name}): \`key\` must be a synchronous function`);
+  }
   const injectRules = opts.inject ?? [];
   // Refs every header template references — the control plane resolves these
   // server-side and pushes them for the environment lifetime (see the daemon's
@@ -685,19 +654,33 @@ export function replayFake(
   };
 
   // ── REPLAY ──────────────────────────────────────────────────────────
+  function signature(request: CassetteRequest, location: string): string {
+    try {
+      return replaySignature(request, opts.key);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`replayFake(${opts.name}): invalid replay key for ${location}: ${message}`);
+    }
+  }
+
   function replay(reqLike: CassetteRequest, state: CassetteState): Response {
-    const sig = signature(reqLike, match);
-    const matches: CassetteInteraction[] = [];
-    for (const it of state.cassette.interactions) {
-      if (signature(it.request, match) === sig) matches.push(it);
+    let sig: string;
+    try {
+      sig = signature(reqLike, "incoming request");
+    } catch (error) {
+      return new Response((error as Error).message + "\n", {
+        status: 599, headers: { "content-type": "text/plain" },
+      });
     }
+    const matches = state.index.get(sig) ?? [];
     const idx = state.cursor.get(sig) ?? 0;
-    const hit = matches[idx];
+    const interactionIndex = matches[idx];
+    const hit = interactionIndex === undefined ? undefined : state.cassette.interactions[interactionIndex];
     if (!hit) {
       const body =
         `replayFake(${opts.name}): no cassette interaction for ` +
-        `${reqLike.method} ${reqLike.path} (matched ${matches.length}, wanted #${idx + 1}). ` +
-        `Re-record the cassette, or relax \`match\`.\n`;
+        `${reqLike.method} ${reqLike.path} (${matches.length === 0 ? "unknown key" : "exhausted key"}; matched ${matches.length}, wanted #${idx + 1}). ` +
+        `Check \`key\` or re-record the cassette.\n`;
       return new Response(body, {
         status: 599,
         headers: { "content-type": "text/plain" },
@@ -883,7 +866,7 @@ export function replayFake(
         method: reqLike.method,
         path: reqLike.path,
         query: redactedQuery,
-        headers: reqLike.headers,
+        headers: Object.fromEntries(Object.entries(reqLike.headers).map(([k, v]) => [k, redact(v)])),
         ...(reqLike.body !== undefined
           ? {
               bodyHash: reqLike.bodyHash,
@@ -943,7 +926,7 @@ export function replayFake(
       // Strip SigV4 `x-amz-*` query params from the match key when signing —
       // presigned URLs carry a per-request signature there.
       query: normalizeQuery(url.searchParams, opts.sign !== undefined),
-      headers: recordable(req.headers, ["content-type", ...(match.headers ?? [])]),
+      headers: recordable(req.headers, [...req.headers.keys()]),
       ...(decodedBody
         ? {
             bodyHash: sha256Bytes(bodyBytes),
@@ -967,6 +950,7 @@ export function replayFake(
     // `replay(...)` to populate it.
     state: (): CassetteState => ({
       cassette: emptyCassette(opts.name, host),
+      index: new Map(),
       cursor: new Map(),
       recorded: [],
       dirty: false,
@@ -988,22 +972,32 @@ export function replayFake(
               `(e.g. "recordings/${opts.name}.json").`,
           );
         }
+        // Build/validate before replacing live state: a bad key/cassette
+        // must leave the previous cassette and consumption cursors intact.
+        const index = new Map<string, number[]>();
+        for (const [i, interaction] of loaded.interactions.entries()) {
+          const sig = signature(interaction.request, `${JSON.stringify(label)} interaction #${i + 1}`);
+          const queue = index.get(sig);
+          if (queue) queue.push(i);
+          else index.set(sig, [i]);
+        }
         // Mutate the live state object (the handler reads the same
         // reference); reset the cursor so replay starts from the top.
         state.cassette = loaded;
+        state.index = index;
         state.cursor = new Map();
         return { cassette: label, host: loaded.host, interactions: loaded.interactions.length };
       },
       dump(): Cassette {
-        return {
+        return structuredClone({
           version: 1,
           fake: opts.name,
           host,
           interactions: [...state.cassette.interactions, ...state.recorded],
-        };
+        });
       },
       recorded(): CassetteInteraction[] {
-        return state.recorded.slice();
+        return structuredClone(state.recorded);
       },
       count(): number {
         return state.recorded.length;

package/src/components/supabase.ts

@@ -58,11 +58,13 @@ import { dirname, join } from "node:path";
 
 import {
   serviceGroup,
+  type CorsMode,
   type ServiceDefinition,
   type ServiceGroup,
   type ServiceSetupContext,
   type ServicesMap,
 } from "../index.js";
+import { validateCorsMode } from "../ingress.js";
 import { SQL, type SqlClient } from "../sql.js";
 import { apple } from "./apple.js";
 import type { OAuthClient } from "./emulate/service.js";
@@ -280,6 +282,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,
@@ -1640,6 +1646,7 @@ async function applyMigrations(
  * for hitting the REST/auth/storage APIs through the gateway.
  */
 export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
+  validateCorsMode(opts.cors);
   const name = opts.name ?? "supabase";
   const dbPassword = opts.dbPassword ?? "postgres";
   const jwtSecret = opts.jwtSecret ?? DEFAULT_JWT_SECRET;
@@ -2366,7 +2373,7 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
           },
         ],
         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 },
       };
 

package/src/daemon.ts

@@ -41,7 +41,7 @@ import {
   normalizeServiceImage,
   proxy as makeProxyDecl,
 } from "./index.js";
-import type { DnsTarget, LoweredIngress } from "./index.js";
+import type { CorsMode, DnsTarget, LoweredIngress } from "./index.js";
 import {
   COVERAGE_CONTAINER_DIR,
   coverageBundleRef,
@@ -127,9 +127,7 @@ import {
 } from "./harness/intercept.js";
 import {
   HOP_BY_HOP_HEADERS,
-  augmentCorsResponse,
-  corsPreflightResponse,
-  isCorsPreflight,
+  withIngressCors,
   upstreamRequestHeaders,
 } from "./harness/http-proxy.js";
 import {
@@ -2146,7 +2144,7 @@ async function startIngress(): Promise<void> {
   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
@@ -2162,7 +2160,7 @@ async function startIngress(): Promise<void> {
     }
     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 } : {}) });
       }
     }
   }
@@ -2319,10 +2317,10 @@ function certCovers(hostname: string): boolean {
  * 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, http2?: boolean): Promise<void> {
+async function bindRuntimeTls(hostname: string, service: string, port: number, http2?: boolean, cors?: CorsMode): 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, http2 });
+  const decl = makeProxyDecl(hostname, { service, port, http2, cors });
   const host = decl.hostname;
   if (!existsSync(CA_PATH) || !existsSync(CA_KEY_PATH)) {
     throw new Error(
@@ -2330,7 +2328,7 @@ async function bindRuntimeTls(hostname: string, service: string, port: number, h
     );
   }
   const Bun = requireBun();
-  const route: Route = { kind: "proxy", service, port, http2 };
+  const route: 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.
@@ -2500,11 +2498,6 @@ async function dispatchIngress(
       { 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: Request): Promise<Response> => {
     if (route.kind === "fake") {
@@ -2522,16 +2515,15 @@ async function dispatchIngress(
     }
     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);
+  });
 }
 
 /**
@@ -3152,7 +3144,7 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
     // `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/src/harness/http-proxy.test.ts

@@ -176,11 +176,12 @@ describe("preflight response", () => {
   });
 
   /** Without Vary, a cache can serve one origin's preflight to another. */
-  test("varies on origin and requested headers", () => {
+  test("varies on origin, requested method and headers", () => {
     const res = preflight({ origin: "http://a.test", "access-control-request-method": "GET" });
     const vary = res.headers.get("vary") ?? "";
     expect(vary.toLowerCase()).toContain("origin");
     expect(vary.toLowerCase()).toContain("access-control-request-headers");
+    expect(vary.toLowerCase()).toContain("access-control-request-method");
   });
 });
 

package/src/harness/http-proxy.ts

@@ -1,3 +1,5 @@
+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.
@@ -75,9 +77,8 @@ export function isCorsPreflight(req: {
 }
 
 /**
- * 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
@@ -104,16 +105,14 @@ 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: { headers: { get(n: string): string | null } },
@@ -133,3 +132,15 @@ export function augmentCorsResponse(
   }
   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: Request,
+  cors: CorsMode | undefined,
+  handle: (req: Request) => Response | Promise<Response>,
+): Promise<Response> {
+  if (cors === "permissive" && isCorsPreflight(req)) return corsPreflightResponse(req);
+  const res = await handle(req);
+  return cors === "permissive" ? augmentCorsResponse(req, res) : res;
+}

package/src/harness/ingress-cors.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, test } from "bun:test";
+import { defineEnvironment, defineFake, lowerIngress, provides, proxy, type CorsMode } from "../index.js";
+import { supabase } from "../components/supabase.js";
+import { withIngressCors, upstreamRequestHeaders } from "./http-proxy.js";
+import { InterceptRegistry, runChain } from "./intercept.js";
+
+const allowed = "https://app.tangent.test";
+const denied = "https://untrusted.test";
+const preflight = (origin: string, method = "PUT"): RequestInit => ({
+  method: "OPTIONS",
+  headers: { origin, "access-control-request-method": method, "access-control-request-headers": "authorization" },
+});
+
+for (const kind of ["fake", "service"] as const) {
+  for (const cors of [undefined, "passthrough"] as const) {
+    describe(`${kind} ingress, cors=${cors ?? "default"}`, () => {
+      test("preserves application CORS, rejections, range reads, OPTIONS and interceptor responses", async () => {
+        const seen: string[] = [];
+        const handler = async (req: Request): Promise<Response> => {
+          const path = new URL(req.url).pathname;
+          seen.push(`${req.method} ${path}`);
+          if (path === "/no-policy") return new Response("private", { headers: { vary: "Accept-Encoding" } });
+          if (req.method === "OPTIONS" && !req.headers.has("access-control-request-method")) {
+            return new Response("options", { status: 200, headers: { allow: "GET, PUT" } });
+          }
+          if (req.headers.get("origin") !== allowed) return new Response("origin denied", { status: 403 });
+          if (req.method === "OPTIONS" && req.headers.get("access-control-request-method") !== "PUT") {
+            return new Response("method denied", { status: 405, headers: { allow: "PUT" } });
+          }
+          const headers = {
+            "access-control-allow-origin": allowed,
+            "access-control-allow-credentials": "true",
+            "access-control-allow-methods": "PUT",
+            "access-control-allow-headers": "authorization",
+            "access-control-expose-headers": "Content-Range",
+            vary: "Origin, Accept-Encoding",
+          };
+          if (req.method === "OPTIONS") return new Response(null, { status: 204, headers });
+          if (req.headers.get("range")) return new Response("par", {
+            status: 206, headers: { ...headers, "content-range": "bytes 0-2/7" },
+          });
+          return new Response(req.headers.get("cookie"), { headers });
+        };
+        const upstream = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: handler });
+        const interceptors = new InterceptRegistry();
+        const pass = interceptors.register("bucket.test", undefined, (_req, next) => next());
+        const blocked = interceptors.register("bucket.test", "/intercepted", () =>
+          new Response("intercepted", { status: 418, headers: { vary: "Accept" } }));
+        const fake = defineFake({ name: "bucket", hostnames: ["bucket.test"], cors, handler });
+        const serviceRoute = lowerIngress(defineEnvironment({ name: "cors", services: {
+          web: { image: "nginx", tls: [{ hostname: "bucket.test", port: upstream.port!, cors }] },
+        } }).project([])).proxies[0];
+        const mode = kind === "fake" ? fake.cors : serviceRoute.cors;
+        const forward = kind === "fake" ? handler : async (req: Request) => fetch(
+          new URL(new URL(req.url).pathname, upstream.url), {
+            method: req.method, headers: upstreamRequestHeaders(req.headers, { proto: "https" }),
+            body: req.body, redirect: "manual",
+          });
+        const ingress = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: req =>
+          withIngressCors(req, mode, current => runChain(
+            interceptors.chainFor("bucket.test", new URL(current.url).pathname), current, forward)),
+        });
+        try {
+          const send = (path: string, init: RequestInit) => fetch(new URL(path, ingress.url), init);
+          const ok = await send("/probe", preflight(allowed));
+          expect(ok.status).toBe(204);
+          expect(ok.headers.get("access-control-allow-origin")).toBe(allowed);
+          expect(ok.headers.get("access-control-allow-credentials")).toBe("true");
+          expect(ok.headers.get("access-control-allow-methods")).toBe("PUT");
+          expect(ok.headers.get("access-control-allow-headers")).toBe("authorization");
+          expect(ok.headers.get("vary")).toBe("Origin, Accept-Encoding");
+          for (const [init, status, body] of [
+            [preflight(denied), 403, "origin denied"],
+            [preflight(allowed, "DELETE"), 405, "method denied"],
+            [{ headers: { origin: denied } }, 403, "origin denied"],
+          ] as const) {
+            const res = await send("/probe", init);
+            expect(res.status).toBe(status);
+            expect(await res.text()).toBe(body);
+            expect(res.headers.get("access-control-allow-origin")).toBeNull();
+            expect(res.headers.get("access-control-allow-credentials")).toBeNull();
+          }
+          const credentialed = await send("/probe", { method: "PUT", headers: { origin: allowed, cookie: "session=test" } });
+          expect(await credentialed.text()).toBe("session=test");
+          expect(credentialed.headers.get("access-control-allow-origin")).toBe(allowed);
+          expect(credentialed.headers.get("access-control-allow-credentials")).toBe("true");
+          const range = await send("/probe", { headers: { origin: allowed, range: "bytes=0-2" } });
+          expect(range.status).toBe(206);
+          expect(range.headers.get("content-range")).toBe("bytes 0-2/7");
+          expect(range.headers.get("access-control-expose-headers")).toBe("Content-Range");
+          expect(await range.text()).toBe("par");
+          const noPolicy = await send("/no-policy", { headers: { origin: allowed } });
+          expect(await noPolicy.text()).toBe("private");
+          expect(noPolicy.headers.get("access-control-allow-origin")).toBeNull();
+          expect(noPolicy.headers.get("access-control-allow-credentials")).toBeNull();
+          expect(noPolicy.headers.get("vary")).toBe("Accept-Encoding");
+          const options = await send("/probe", { method: "OPTIONS", headers: { origin: allowed } });
+          expect(options.status).toBe(200);
+          expect(options.headers.get("allow")).toBe("GET, PUT");
+          expect(options.headers.get("access-control-allow-origin")).toBeNull();
+          expect(await options.text()).toBe("options");
+          for (const init of [preflight(denied), { headers: { origin: denied } }]) {
+            const res = await send("/intercepted", init);
+            expect(res.status).toBe(418);
+            expect(await res.text()).toBe("intercepted");
+            expect(res.headers.get("access-control-allow-origin")).toBeNull();
+            expect(res.headers.get("vary")).toBe("Accept");
+          }
+          expect(pass.requests).toHaveLength(10);
+          expect(blocked.requests.map(r => r.method)).toEqual(["OPTIONS", "GET"]);
+          expect(seen.filter(s => s === "OPTIONS /probe")).toHaveLength(4);
+          expect(seen.some(s => s.endsWith("/intercepted"))).toBe(false);
+        } finally {
+          ingress.stop(true);
+          upstream.stop(true);
+        }
+      });
+    });
+  }
+}
+
+test("passthrough preserves the exact response, including interceptor CORS and repeated cookies", async () => {
+  const res = new Response("error", { status: 500, headers: {
+    "access-control-allow-origin": allowed, "access-control-allow-credentials": "false", vary: "Accept",
+  } });
+  res.headers.append("set-cookie", "a=1");
+  res.headers.append("set-cookie", "b=2");
+  const headers = [...res.headers];
+  expect(await withIngressCors(new Request("http://bucket.test", preflight(denied)), undefined, () => res)).toBe(res);
+  expect([...res.headers]).toEqual(headers);
+});
+
+test("permissive is opt-in for preflight interception and response augmentation", async () => {
+  let calls = 0;
+  const handle = () => { calls++; return new Response("denied", { status: 403 }); };
+  const pre = await withIngressCors(new Request("http://bucket.test", preflight(denied)), "permissive", handle);
+  expect(pre.status).toBe(204);
+  expect(pre.headers.get("access-control-allow-origin")).toBe(denied);
+  expect(pre.headers.get("access-control-allow-credentials")).toBe("true");
+  expect(calls).toBe(0);
+  const ordinary = await withIngressCors(new Request("http://bucket.test", { method: "OPTIONS" }), "permissive", handle);
+  expect(ordinary.status).toBe(403);
+  expect(calls).toBe(1);
+  const res = await withIngressCors(new Request("http://bucket.test", { headers: { origin: denied } }), "permissive", handle);
+  expect(res.status).toBe(403);
+  expect(res.headers.get("access-control-allow-origin")).toBe(denied);
+  expect(res.headers.get("access-control-allow-credentials")).toBe("true");
+  expect(calls).toBe(2);
+});
+
+test.each(["passthrough", "permissive"] as CorsMode[])("public config retains %s for fakes, TLS and component proxies", cors => {
+  const fake = defineFake({ name: "fake", hostnames: ["fake.test"], cors, handler: () => new Response() });
+  const env = defineEnvironment({ name: "cors", fakes: { fake }, services: {
+    web: provides({ image: "nginx", tls: [{ hostname: "web.test", port: 81, cors }] }, [
+      proxy("*.proxy.test", { service: "web", port: 81, cors }),
+    ]),
+  } });
+  const project = env.project([]);
+  expect(project.fakes?.fake.cors).toBe(cors);
+  expect(lowerIngress(project).proxies.map(p => p.cors)).toEqual([cors, cors]);
+});
+
+test("invalid CORS modes fail at configuration time", () => {
+  const cors = "typo" as CorsMode;
+  expect(() => defineFake({ name: "fake", hostnames: ["fake.test"], cors, handler: () => new Response() })).toThrow("cors must be");
+  expect(() => proxy("proxy.test", { service: "web", port: 81, cors })).toThrow("cors must be");
+  expect(() => defineEnvironment({ name: "cors", services: {
+    web: { image: "nginx", tls: [{ hostname: "web.test", port: 81, cors }] },
+  } })).toThrow("cors must be");
+});
+
+for (const cors of [undefined, "passthrough", "permissive"] as const) {
+  test(`Supabase gateway carries ${cors ?? "default"} CORS through group expansion`, () => {
+    const sb = supabase({ hostname: "supabase.test", cors });
+    const project = defineEnvironment({ name: "cors", services: { supabase: sb.group } }).project([]);
+    const gateway = lowerIngress(project).proxies.find(p => p.hostname === "supabase.test");
+    expect(gateway).toBeDefined();
+    expect(gateway?.cors).toBe(cors);
+  });
+}
+
+test("Supabase rejects an invalid CORS mode", () => {
+  expect(() => supabase({ hostname: "supabase.test", cors: "typo" as CorsMode })).toThrow("cors must be");
+});