@specific.dev/spectest 0.115.1 → 0.116.0

package/dist/fake-upstream.d.ts

@@ -0,0 +1,114 @@
+/** 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 supplied for the environment lifetime. Values
+ *  never enter project files, the warm-cache hash, or a cassette (redaction
+ *  fails closed). */
+export interface InjectRule {
+    match?: InjectMatch;
+    headers: Record<string, string>;
+}
+/** SigV4 request-signing broker. Unlike `inject` (which SETs a static header
+ *  value), this RE-SIGNS the outbound request: the app signs with throwaway
+ *  dummy credentials, we strip that signature and re-sign the exact outbound
+ *  request with the real credentials — the only way to broker AWS auth, whose
+ *  signature is a keyed HMAC over the whole request, not a static token.
+ *
+ *  The three fields are **secret refs, resolved directly** from the project's
+ *  Secrets store (NOT `{{secret:}}` templates), with the same lifetime and
+ *  fail-closed redaction as `inject`. Region + service are inferred from the
+ *  incoming request (its credential scope, else the host); the app never
+ *  configures them. */
+export interface AwsSigV4Sign {
+    type: "awsSigv4";
+    /** Secret ref for the AWS access key id. */
+    accessKeyId: string;
+    /** Secret ref for the AWS secret access key. */
+    secretAccessKey: string;
+    /** Optional secret ref for a session token (temporary credentials). */
+    sessionToken?: string;
+}
+export type SignConfig = AwsSigV4Sign;
+/** One resolved secret value and the ref it came from (for the redaction
+ *  placeholder). */
+export interface ResolvedSecret {
+    ref: string;
+    value: string;
+}
+/** Hop-by-hop + body-framing headers never forwarded / never replayed
+ *  (we decompress on the way through, so the encoding/length no longer
+ *  describe the bytes the app receives). */
+export declare const STRIP_FORWARD_HEADERS: Set<string>;
+/** 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
+ *  when signing is active. */
+export declare function isAmzParam(key: string): boolean;
+/** Every secret ref referenced by any inject rule's header templates plus the
+ *  SigV4 signing credentials (direct refs, not templates). */
+export declare function collectSecretRefs(rules: InjectRule[], sign: SignConfig | undefined): string[];
+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. */
+export declare function ruleMatches(match: InjectMatch | undefined, req: IncomingRequest): boolean;
+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 environment credential. Collects resolved secrets (for redaction)
+ *  and any refs the control plane didn't supply (fail loud). */
+export declare function brokerHeaders(rule: InjectRule): BrokeredHeaders;
+/** 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. */
+export declare function resolveExternalA(host: string): Promise<string[]>;
+interface UpstreamResponse {
+    status: number;
+    headers: Record<string, string>;
+    /** Keep cookie boundaries when returning an unrecorded response. */
+    cookies?: string[];
+    /** Decompressed body bytes. */
+    bytes: Uint8Array;
+}
+/** Forward without capturing. Callers may separately record the result. */
+export declare function forwardHttp(req: Request, host: string, opts: {
+    inject?: InjectRule[];
+    sign?: SignConfig;
+}, bodyBytes: Uint8Array, label: string): Promise<Response | {
+    upstream: UpstreamResponse;
+    secrets: ResolvedSecret[];
+}>;
+export {};

package/dist/fake-upstream.js

@@ -0,0 +1,348 @@
+// Shared upstream transport and credential brokering. No cassette state lives here.
+import { createSocket } from "node:dgram";
+import { request as httpsRequest } from "node:https";
+import { brotliDecompressSync, gunzipSync, inflateSync } from "node:zlib";
+import * as dnsPacket from "dns-packet";
+import { getRecordSecret } from "./record-secrets.js";
+import { inferSigV4Scope, signAwsV4Request } from "./aws-sigv4.js";
+/** Hop-by-hop + body-framing headers never forwarded / never replayed
+ *  (we decompress on the way through, so the encoding/length no longer
+ *  describe the bytes the app receives). */
+export const STRIP_FORWARD_HEADERS = new Set([
+    "host",
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailers",
+    "transfer-encoding",
+    "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");
+/** 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
+ *  when signing is active. */
+export function isAmzParam(key) {
+    return key.toLowerCase().startsWith("x-amz-");
+}
+function stripAmzParams(search) {
+    const out = new URLSearchParams();
+    for (const [k, v] of search)
+        if (!isAmzParam(k))
+            out.append(k, v);
+    return out;
+}
+/** `{{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 plus the
+ *  SigV4 signing credentials (direct refs, not templates). */
+export function collectSecretRefs(rules, sign) {
+    const refs = new Set();
+    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]);
+        }
+    }
+    if (sign?.type === "awsSigv4") {
+        refs.add(sign.accessKeyId);
+        refs.add(sign.secretAccessKey);
+        if (sign.sessionToken)
+            refs.add(sign.sessionToken);
+    }
+    return [...refs];
+}
+function matchString(m, value) {
+    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;
+}
+/** True if every dimension the matcher specifies is satisfied (AND across
+ *  dimensions). No `match` → always true. */
+export function ruleMatches(match, req) {
+    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;
+}
+/** Resolve a rule's header templates, substituting every `{{secret:REF}}`
+ *  with the environment credential. Collects resolved secrets (for redaction)
+ *  and any refs the control plane didn't supply (fail loud). */
+export function brokerHeaders(rule) {
+    const headers = {};
+    const secrets = [];
+    const missing = [];
+    const seen = new Set();
+    for (const [name, template] of Object.entries(rule.headers)) {
+        headers[name.toLowerCase()] = template.replace(SECRET_TOKEN, (_full, ref) => {
+            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 };
+}
+/** 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. */
+export function resolveExternalA(host) {
+    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) => {
+            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 ?? []).flatMap((a) => a.type === "A" && typeof a.data === "string" && a.data.length > 0 ? [a.data] : []);
+                finish(ips);
+            }
+            catch {
+                finish([]);
+            }
+        });
+        sock.on("error", () => finish([]));
+        sock.send(query, EXTERNAL_DNS_PORT, EXTERNAL_DNS, (err) => {
+            if (err)
+                finish([]);
+        });
+        setTimeout(() => finish([]), 3_000);
+    });
+}
+/** 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) {
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            host: args.ip,
+            port: 443,
+            method: args.method,
+            signal: args.signal,
+            path: args.pathWithQuery,
+            servername: args.host,
+            headers: { ...args.headers, host: args.host, "accept-encoding": "identity" },
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (c) => chunks.push(c));
+            res.on("end", () => {
+                let bytes = 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 = {};
+                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, cookies: res.headers["set-cookie"] });
+            });
+            res.on("error", reject);
+        });
+        req.on("error", reject);
+        if (args.body.length > 0)
+            req.write(Buffer.from(args.body));
+        req.end();
+    });
+}
+/** Forward without capturing. Callers may separately record the result. */
+export async function forwardHttp(req, host, opts, bodyBytes, label) {
+    const url = new URL(req.url);
+    const reqLike = { method: req.method.toUpperCase(), path: url.pathname };
+    // Credential brokering (static header inject): first matching rule wins.
+    // Resolve its `{{secret:REF}}` tokens from the environment secret store.
+    const rule = (opts.inject ?? []).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: [] };
+    // SigV4 signing: resolve the credential secret refs (direct refs, not
+    // `{{secret:}}` templates). Missing required refs fail loud alongside any
+    // missing inject refs.
+    let signCreds;
+    const signMissing = [];
+    if (opts.sign?.type === "awsSigv4") {
+        const s = opts.sign;
+        const accessKeyId = getRecordSecret(s.accessKeyId);
+        const secretAccessKey = getRecordSecret(s.secretAccessKey);
+        const sessionToken = s.sessionToken ? getRecordSecret(s.sessionToken) : undefined;
+        if (accessKeyId === undefined)
+            signMissing.push(s.accessKeyId);
+        if (secretAccessKey === undefined)
+            signMissing.push(s.secretAccessKey);
+        if (s.sessionToken && sessionToken === undefined)
+            signMissing.push(s.sessionToken);
+        if (accessKeyId !== undefined && secretAccessKey !== undefined) {
+            signCreds = { accessKeyId, secretAccessKey, sessionToken };
+        }
+    }
+    const missing = [...brokered.missing, ...signMissing];
+    if (missing.length > 0) {
+        const refs = [...new Set(missing)];
+        return new Response(`${label}: secret(s) ${JSON.stringify(refs)} were not supplied ` +
+            `(configure them on the project's Secrets page, then start a new environment or fork).\n`, { status: 599, headers: { "content-type": "text/plain" } });
+    }
+    // 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(`${label}: 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/framing, 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 = {};
+    req.headers.forEach((v, k) => {
+        if (k.toLowerCase() === "content-encoding" || !STRIP_FORWARD_HEADERS.has(k.toLowerCase()))
+            fwdHeaders[k.toLowerCase()] = v;
+    });
+    for (const [k, v] of Object.entries(brokered.headers))
+        fwdHeaders[k] = v;
+    // SigV4 re-signing: strip the app's dummy signature and re-sign the exact
+    // outbound request (method/path/query/signed-headers/body-hash) with the
+    // brokered credentials, so `authorization`/`x-amz-date`/`x-amz-content-sha256`
+    // are internally consistent.
+    const signSecrets = [];
+    let wireQuery = url.search.slice(1);
+    if (opts.sign?.type === "awsSigv4" && signCreds) {
+        const scope = inferSigV4Scope({
+            authorization: req.headers.get("authorization"),
+            credentialParam: url.searchParams.get("X-Amz-Credential"),
+            host,
+        });
+        if (!scope) {
+            return new Response(`${label}: could not infer the AWS region/service to sign ` +
+                `${reqLike.method} ${reqLike.path} (no SigV4 Credential on the request, and host ` +
+                `${JSON.stringify(host)} is not a <service>.<region>.amazonaws.com name).\n`, { status: 599, headers: { "content-type": "text/plain" } });
+        }
+        // Drop the app's own (dummy-signed) signing headers before re-signing.
+        for (const h of ["authorization", "x-amz-date", "x-amz-content-sha256", "x-amz-security-token"]) {
+            delete fwdHeaders[h];
+        }
+        // Fold the app's remaining `x-amz-*`/content-type headers (e.g.
+        // `x-amz-target`) into the signature; they stay on the outbound wire.
+        const additionalHeaders = {};
+        for (const [k, v] of Object.entries(fwdHeaders)) {
+            if (k === "content-type" ||
+                (k.startsWith("x-amz-") &&
+                    k !== "x-amz-date" &&
+                    k !== "x-amz-content-sha256" &&
+                    k !== "x-amz-security-token")) {
+                additionalHeaders[k] = v;
+            }
+        }
+        const forwardParams = stripAmzParams(url.searchParams);
+        const signed = signAwsV4Request({
+            method: reqLike.method,
+            path: reqLike.path,
+            query: forwardParams,
+            host,
+            body: bodyBytes,
+            credentials: signCreds,
+            scope,
+            additionalHeaders,
+        });
+        for (const [k, v] of Object.entries(signed.headers))
+            fwdHeaders[k] = v;
+        // Send the canonical query we signed (URLSearchParams' `+`-for-space
+        // encoding would diverge from the signed `%20`).
+        wireQuery = signed.canonicalQuery;
+        signSecrets.push({ ref: opts.sign.accessKeyId, value: signCreds.accessKeyId }, { ref: opts.sign.secretAccessKey, value: signCreds.secretAccessKey });
+        if (signCreds.sessionToken && opts.sign.sessionToken) {
+            signSecrets.push({ ref: opts.sign.sessionToken, value: signCreds.sessionToken });
+        }
+    }
+    const pathWithQuery = reqLike.path + (wireQuery ? `?${wireQuery}` : "");
+    let upstream;
+    try {
+        upstream = await forwardToRealUpstream({
+            ip: ips[0],
+            host,
+            method: reqLike.method,
+            pathWithQuery,
+            headers: fwdHeaders,
+            body: bodyBytes,
+            signal: req.signal,
+        });
+    }
+    catch (err) {
+        return new Response(`${label}: forward to real ${host} (${ips[0]}) failed: ${err.message}\n`, { status: 599, headers: { "content-type": "text/plain" } });
+    }
+    return { upstream, secrets: [...brokered.secrets, ...signSecrets] };
+}

package/dist/harness/fake-websocket.js

@@ -1,12 +1,15 @@
+import { isInteractiveEnvironment } from "../replay-mode.js";
+import { liveFakeHandlers } from "./live-fake.js";
 import { runUninstrumented } from "./instrumentation-scope.js";
 import { bindWebSocketLifetime, getWebSocketLifetime } from "./fake-websocket-lifetime.js";
 import { reportBackgroundFailure } from "./background-failures.js";
 import { parseSubprotocols } from "./ws-bridge.js";
 /** HTTP and WebSocket dispatch share fake state, helpers, and execution scope. */
 export async function dispatchFake(req, server, def, state, ctx) {
-    if (req.headers.get("upgrade")?.toLowerCase() !== "websocket" || !def.websocket) {
+    const implementation = def.live && isInteractiveEnvironment() ? liveFakeHandlers(def) : def;
+    if (req.headers.get("upgrade")?.toLowerCase() !== "websocket" || !implementation.websocket) {
         try {
-            return await runUninstrumented(() => def.handler(req, state, ctx));
+            return await runUninstrumented(() => implementation.handler(req, state, ctx));
         }
         catch (err) {
             return fakeError(def.name, err);
@@ -14,7 +17,7 @@ export async function dispatchFake(req, server, def, state, ctx) {
     }
     const lifetime = getWebSocketLifetime(req);
     try {
-        const accepted = await runUninstrumented(() => def.websocket(req, state, ctx));
+        const accepted = await runUninstrumented(() => implementation.websocket(req, state, ctx));
         if (accepted instanceof Response) {
             lifetime.end({ kind: "aborted" });
             return accepted;

package/dist/harness/live-fake.d.ts

@@ -0,0 +1,3 @@
+import type { FakeDefinition } from "../index.js";
+/** Select at request time, after the baseline has become interactive. */
+export declare function liveFakeHandlers(def: FakeDefinition): Pick<FakeDefinition, "handler" | "websocket">;

package/dist/harness/live-fake.js

@@ -0,0 +1,66 @@
+import { brokerHeaders, forwardHttp, resolveExternalA, ruleMatches, STRIP_FORWARD_HEADERS, } from "../fake-upstream.js";
+import { forwardWebSocket } from "../fake-upstream-websocket.js";
+import { getWebSocketLifetime } from "./fake-websocket-lifetime.js";
+import { reportBackgroundFailure } from "./background-failures.js";
+import { isInteractiveEnvironment } from "../replay-mode.js";
+/** Select at request time, after the baseline has become interactive. */
+export function liveFakeHandlers(def) {
+    function target(req) {
+        if (!isInteractiveEnvironment())
+            throw new Error("live forwarding requires an interactive environment");
+        const url = new URL(req.url);
+        if (!def.hostnames.some(host => host.toLowerCase() === url.hostname.toLowerCase())) {
+            throw new Error(`fake ${def.name}: upstream hostname is not declared on this fake`);
+        }
+        return url.hostname;
+    }
+    return {
+        async handler(req) {
+            const host = target(req);
+            const bytes = new Uint8Array(await req.arrayBuffer());
+            const result = await forwardHttp(req, host, def.live, bytes, `fake(${def.name})`);
+            if (result instanceof Response)
+                return result;
+            const { upstream } = result;
+            const headers = new Headers();
+            for (const [key, value] of Object.entries(upstream.headers)) {
+                if (key !== "set-cookie" && !STRIP_FORWARD_HEADERS.has(key))
+                    headers.set(key, value);
+            }
+            for (const cookie of upstream.cookies ?? [])
+                headers.append("set-cookie", cookie);
+            return new Response(req.method === "HEAD" || [204, 205, 304].includes(upstream.status)
+                ? null : upstream.bytes, { status: upstream.status, headers });
+        },
+        async websocket(req) {
+            const host = target(req);
+            const opts = def.live;
+            if (opts.sign)
+                throw new Error(`fake(${def.name}): SigV4 WebSocket signing is not supported`);
+            const url = new URL(req.url);
+            const rule = opts.inject?.find(rule => ruleMatches(rule.match, {
+                method: req.method, path: url.pathname, query: url.searchParams, headers: req.headers,
+            }));
+            const brokered = rule ? brokerHeaders(rule) : { headers: {}, missing: [] };
+            if (brokered.missing.length)
+                throw new Error(`fake(${def.name}): missing WebSocket secrets ${brokered.missing.join(", ")}`);
+            const ips = await resolveExternalA(host);
+            if (!ips.length)
+                throw new Error(`fake(${def.name}): could not resolve real upstream ${host}`);
+            const headers = {};
+            req.headers.forEach((value, key) => {
+                if (!STRIP_FORWARD_HEADERS.has(key) && !key.startsWith("sec-websocket-"))
+                    headers[key] = value;
+            });
+            Object.assign(headers, brokered.headers);
+            const { handlers } = await forwardWebSocket({
+                url: `wss://${host}${url.pathname}${url.search}`, ip: ips[0], host, headers,
+                protocols: (req.headers.get("sec-websocket-protocol") ?? "").split(",").map(p => p.trim()).filter(Boolean),
+                label: `fake(${def.name}) WebSocket`, lifetime: getWebSocketLifetime(req),
+                finished(_session, error) { if (error)
+                    reportBackgroundFailure(error); },
+            });
+            return handlers;
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import type { InjectRule, SignConfig } from "./fake-upstream.js";
+export type { InjectRule, InjectMatch, StringMatch, SignConfig, AwsSigV4Sign } from "./fake-upstream.js";
 export type { Phone, PhoneOptions, CallOptions, SpeechOptions } from "./phone.js";
 import type { Phone, PhoneOptions } from "./phone.js";
 import type { Android, AndroidApp } from "./android.js";
@@ -1456,6 +1458,14 @@ export interface ExecOpts {
 export interface TestSuite<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
     tests: TestCase<unknown, S, F>[];
 }
+/** Forward the entire fake to real HTTPS/WSS upstreams in interactive environments.
+ * Tests and shared baselines always use the scripted handlers. No traffic is recorded. */
+export interface FakeLiveOptions {
+    /** Same header injection rules as replayFake, applied to HTTP and WebSocket handshakes. */
+    inject?: InjectRule[];
+    /** Re-sign HTTP requests using brokered AWS credentials. Not supported for WebSockets. */
+    sign?: SignConfig;
+}
 /**
  * A fake server hosted in the harness. Use this to stand in for
  * external HTTP APIs (auth providers, payment gateways, …) that you can't
@@ -1489,6 +1499,10 @@ export interface FakeDefinition<S = any, H extends Record<string, unknown> = Rec
      * other fakes.
      */
     hostnames: readonly string[];
+    /** Opt in to forwarding all HTTP/WebSocket traffic to the declared real hosts
+     * over HTTPS/WSS (port 443) in interactive environments. Errors never fall back
+     * to scripted handlers. Omit to keep the fake scripted in every environment. */
+    live?: FakeLiveOptions;
     /** TCP port the fake listens on. Default `80`. */
     port?: number;
     /** Preserve handler/interceptor CORS policy by default. "permissive"
@@ -1546,7 +1560,7 @@ export interface FakeDefinition<S = any, H extends Record<string, unknown> = Rec
         ctx: FakeContext;
     }) => H | Promise<H>;
     /**
-     * Internal. Platform secret references this fake needs at *record* time
+     * Internal. Platform secret references this fake needs for upstream access
      * (set by {@link replayFake}). The daemon reports the union of these to
      * the control plane, which resolves each via its `SecretResolver` and
      * supplies them for the environment lifetime, including snapshots. Values

package/dist/index.js

@@ -407,6 +407,9 @@ export function defineFake(opts) {
             throw new Error(`defineFake(${opts.name}): hostname ${JSON.stringify(h)} ends in reserved ".internal" TLD`);
         }
     }
+    if (opts.live !== undefined && (!opts.live || typeof opts.live !== "object" || Array.isArray(opts.live))) {
+        throw new Error(`defineFake(${opts.name}): \`live\` must be an options object`);
+    }
     validateCorsMode(opts.cors);
     if (typeof opts.handler !== "function") {
         throw new Error(`defineFake(${opts.name}): \`handler\` is required`);

package/dist/record-secrets.d.ts

@@ -1,4 +1,4 @@
 /** Replace the complete environment secret set, including removing stale refs. */
 export declare function setRecordSecrets(secrets: Record<string, string>): void;
-/** Resolve a declared project secret for an outbound recording request. */
+/** Resolve a declared project secret for an outbound live or recording request. */
 export declare function getRecordSecret(ref: string): string | undefined;

package/dist/record-secrets.js

@@ -1,9 +1,9 @@
-// Environment-lifetime credentials for record-mode fakes. The control plane
+// Environment-lifetime credentials for live and record-mode fakes. The control plane
 // resolves declared references from the owning project's Secrets store before
 // service startup and refreshes them on warm starts and interactive forks.
 // They persist across evals, background requests and memory snapshots, just
 // like other environment state. Test forks inherit their parent's credentials;
-// replay mode still uses cassettes and never forwards upstream.
+// test mode still uses scripted handlers or cassettes and never forwards upstream.
 // Values stay out of project files, config hashes and recorded cassettes.
 const SECRETS = new Map();
 /** Replace the complete environment secret set, including removing stale refs. */
@@ -12,7 +12,7 @@ export function setRecordSecrets(secrets) {
     for (const [ref, value] of Object.entries(secrets))
         SECRETS.set(ref, value);
 }
-/** Resolve a declared project secret for an outbound recording request. */
+/** Resolve a declared project secret for an outbound live or recording request. */
 export function getRecordSecret(ref) {
     return SECRETS.get(ref);
 }

package/dist/replay-mode.d.ts

@@ -1,2 +1,4 @@
 export declare function setReplayEnvironmentMode(value: "test" | "interactive"): void;
 export declare function resolveReplayMode(requested?: "auto" | "record" | "replay"): "record" | "replay";
+/** Shared gate for live and replay fakes. Credentials never enable upstream access. */
+export declare function isInteractiveEnvironment(): boolean;

package/dist/replay-mode.js

@@ -1,6 +1,6 @@
 // Environment state: travels with memory snapshots, independently of the
-// per-case event recorder. Shared/warm baselines must never record upstream.
-// The control plane enables recording only on an interactive environment,
+// per-case event recorder. Shared/warm baselines must never forward upstream.
+// The control plane enables upstream access only on an interactive environment,
 // after capturing/restoring the shared baseline and before interactive setup.
 let mode = "test";
 export function setReplayEnvironmentMode(value) {
@@ -10,3 +10,7 @@ export function resolveReplayMode(requested = "auto") {
     // Even an explicit record option cannot send test traffic to real providers.
     return mode === "test" || requested === "replay" ? "replay" : "record";
 }
+/** Shared gate for live and replay fakes. Credentials never enable upstream access. */
+export function isInteractiveEnvironment() {
+    return mode === "interactive";
+}