@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/bin/apifuse-record.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-// @ts-nocheck
+import { readDiagnosticEnv } from "../src/runtime/diagnostic-env.js";
 
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
@@ -8,20 +8,72 @@ import { pathToFileURL } from "node:url";
 
 import {
 	createBypassProviderCache,
+	createCredentialContext,
 	createHttpClient,
-	createProviderChoiceContext,
-	createStealthClient,
+	createInProcessProviderEngine,
+	createOcrClientFromEnv,
+	createHandleContext,
+	createProviderEnvironment,
 	createSttClientFromEnv,
 	executeOperation,
 	type HttpClient,
+	type HttpResponse,
+	type HttpStreamResponse,
 	type ProviderContext,
 	type ProviderDefinition,
+	type ProviderEngineBindingCandidates,
 	ProviderError,
+	type RequestOptions,
 	type StealthClient,
 	TransportError,
 	ValidationError,
 } from "../src/index.js";
+import {
+	type LocalConnection,
+	LOCAL_CONNECTION_ID,
+	LOCAL_CONNECTION_SECRETS_ENV,
+	providerRequiresConnection,
+	resolveLocalConnection,
+} from "../src/cli/local-connection.js";
+import { createCliResolverRuntime } from "../src/cli/resolver-runtime.js";
+import { isAbsoluteUrl } from "../src/runtime/http.js";
+import { getProviderBaseUrl, getProviderStealthBaseUrl } from "../src/runtime/provider.js";
+import { assertProcessEngineModeSupported } from "../src/runtime/engine-mode.js";
+import type { JsonValue } from "../src/contract-json.js";
+import {
+	isSensitiveFixtureKey,
+	requestPathForFixture,
+	sanitizeDiagnosticText,
+	sanitizeFixtureString,
+} from "../src/fixture-sanitization.js";
+import {
+	isSensitiveKey,
+	normalizeSensitiveParams,
+	parseHttpRequestInvocation,
+	REDACTED_QUERY_VALUE,
+	redactSensitiveError,
+	redactSensitiveText,
+	redactUrlQueryParams,
+	replaceRequestOptionsInHttpInvocation,
+	requestOptionsFromHttpInvocation,
+	serializeRequestUrl,
+} from "../src/runtime/request-options.js";
+import type { ResolverTelemetryCollector } from "../src/runtime/resolver-telemetry.js";
 import { createMemoryProviderRuntimeState } from "../src/runtime/state.js";
+import { createStealthClient } from "../src/runtime/stealth.js";
+import { parseSchema } from "../src/schema.js";
+import {
+	captureStreamEvidence,
+	createStreamCaptureEnvelope,
+	findStreamCaptureGroup,
+	findStreamEvidenceRecords,
+	hasStreamEvidenceMarker,
+	parseStreamEvidenceRecord,
+	STREAM_PREVIEW_BYTES,
+	type StreamCaptureGroupItem,
+	type StreamEvidenceCapture,
+	type StreamEvidenceRequest,
+} from "../src/stream-evidence.js";
 
 type CliArgs = {
 	append: boolean;
@@ -29,6 +81,10 @@ type CliArgs = {
 	operation?: string;
 	params: string;
 	sanitize: boolean;
+	/** Repeated `--credential key=value`, in order. */
+	credentials: string[];
+	/** `--no-credential`: run without a connection even when auth declares one. */
+	noCredential: boolean;
 };
 
 type ProviderRuntime = ProviderDefinition;
@@ -39,60 +95,163 @@ const HELP_TEXT = `Usage: apifuse record [path] --operation <operation> --params
 
 Calls a real upstream-backed operation through ctx.http or ctx.stealth and writes __fixtures__/raw.json.
 
+Absolute request URLs need no declaration. A relative URL resolves the way serve resolves it: against
+the operation's upstream.baseUrl, else the provider's first declared one (ctx.stealth then falls back
+to https://<allowedHosts[0]>). A relative ctx.http URL with no base anywhere is refused and names
+the upstream.baseUrl to declare.
+
+Streaming responses are recorded as evidence (status, selected headers, full-body SHA-256 and byte
+count, plus a ${STREAM_PREVIEW_BYTES}-byte base64 preview). Test replay is evidence-only: ctx.http.stream exposes the
+preview as its body and the original body_sha256/body_bytes as response metadata.
+When an operation opens multiple streams, all evidence records are saved in stream call order.
+Mixed JSON/stream operations save a tagged call-ordered envelope so snapshot replay can route each response.
+ctx.http.sse() recording is unsupported and fails explicitly.
+
 Options:
   --operation, -o <name>   operation to call
   --params, -p <json>      JSON input passed to the operation (default: {})
-  --append                 append to an existing array fixture
+  --append                 preserve the existing fixture and append this capture
   --sanitize               redact common token/header fields (default)
-  --no-sanitize            write the captured upstream payload as-is
+  --no-sanitize            disable common-field redaction (sensitiveParams are always redacted)
+  --credential <k>=<v>     credential the gateway would inject (repeatable)
+  --no-credential          record without a credential even when auth declares one
   --help, -h               show this help
 
+Credentials:
+  A provider whose auth.mode is not "none" reads a credential the gateway
+  resolves and injects at invocation time -- for "platform-managed" that is the
+  platform-owned key, which is not a provider secret and is not in the
+  checkout. Supply it with --credential, or with
+  ${LOCAL_CONNECTION_SECRETS_ENV}='{"<key>":"<value>"}'. The keys are the ones
+  the provider passes to ctx.credential.get(...).
+
 Example:
   apifuse record providers/korea-air-quality --operation realtime --params '{"stationName":"jongno"}'`;
 
 export async function main() {
+	let capture: ReturnType<typeof createCaptureContext> | undefined;
 	try {
 		const args = parseArgs(normalizeArgs(process.argv.slice(2)));
 		const location = resolveProviderLocation(args.providerPath);
 		const provider = await loadProvider(location.rootDir);
+		// The capture context attaches in-process; refuse an explicit remote request instead of ignoring it.
+		assertProcessEngineModeSupported();
 		const operationName = resolveOperationName(provider, args.operation);
 		const operation = provider.operations[operationName];
-		const parsedParams = parseParams(operation, args.params);
+		const parsedParams = await parseParams(operation, args.params);
+
+		const connection = resolveRecordConnection(provider, args);
 
-		const capture = createCaptureContext(
+		capture = createCaptureContext(
 			provider,
-			resolveOperationBaseUrl(provider, operationName),
+			resolveRecordBaseUrls(provider, operationName),
+			args.sanitize,
+			connection,
 		);
 
 		console.log(`[apifuse record] Calling ${operationName} on ${provider.id}...`);
 
-		const result = await executeOperation(provider, operationName, capture.ctx, parsedParams);
-		const captured = capture.getCapturedRaw();
+		let result: unknown;
+		try {
+			result = await executeOperation(provider, operationName, capture.ctx, parsedParams);
+		} catch (operationError) {
+			capture.throwIfRefused();
+			let partial: unknown;
+			try {
+				partial = await capture.getCapturedRaw();
+			} catch (finalizationError) {
+				throw new StreamRecorderError("Operation and stream finalization both failed.", [
+					operationError,
+					finalizationError,
+				]);
+			}
+			const streamCount = findStreamEvidenceRecords(partial).length;
+			if (streamCount > 0) {
+				throw new StreamRecorderError(
+					`Operation failed after finalizing ${streamCount} stream capture${streamCount === 1 ? "" : "s"}.`,
+					[operationError],
+				);
+			}
+			throw operationError;
+		} finally {
+			const telemetryLine = formatResolverTelemetry(
+				capture.resolverTelemetry,
+				capture.getCapturedSensitiveParams().values,
+			);
+			if (telemetryLine) console.log(telemetryLine);
+		}
+		// Checked on success too: an operation that caught the refusal and carried
+		// on would otherwise save a fixture missing the request it never made.
+		capture.throwIfRefused();
+		const captured = await capture.getCapturedRaw();
 
 		if (captured === undefined) {
 			throw new Error(`No upstream response was captured for ${provider.id}.${operationName}.`);
 		}
 
-		const rawPayload = args.sanitize ? sanitizeFixture(captured) : captured;
+		const sensitiveParams = capture.getCapturedSensitiveParams();
+		const rawPayload = jsonFixtureValue(captured);
 		const fixturePath = resolve(location.rootDir, "__fixtures__", "raw.json");
-		const nextPayload = await prepareFixturePayload(fixturePath, rawPayload, args.append);
+		const redactedCapture = redactFixture(rawPayload, sensitiveParams, args.sanitize);
+		const mergedPayload = await prepareFixturePayload(fixturePath, redactedCapture, args.append);
+		// Mandatory query-secret redaction applies to the merged history, including
+		// values discovered in older declared-key URL positions. Optional common-
+		// field sanitization applies only to this run's new capture so --append does
+		// not rewrite deliberately preserved historical fields.
+		const historicalSensitiveParams = discoverSensitiveQueryValues(mergedPayload, sensitiveParams);
+		const nextPayload = redactFixture(mergedPayload, historicalSensitiveParams, false);
 
 		await mkdir(dirname(fixturePath), { recursive: true });
 		await writeFile(fixturePath, `${JSON.stringify(nextPayload, null, 2)}\n`);
 
 		console.log(
 			`[apifuse record] Captured response (${formatBytes(
-				Buffer.byteLength(JSON.stringify(rawPayload)),
+				Buffer.byteLength(JSON.stringify(redactedCapture)),
 			)})`,
 		);
 		console.log(`[apifuse record] Saved to ${relative(process.cwd(), fixturePath)}`);
 
 		void result;
 	} catch (error) {
-		handleCliError(error);
+		handleCliError(error, capture?.getCapturedSensitiveParams().values);
 	}
 }
 
+/**
+ * The connection this run attaches, or a hard failure when the provider needs
+ * one and none is configured.
+ *
+ * Failing here rather than at the handler is the whole point. Before this, a
+ * platform-managed provider recorded with `credential: { mode: "none" }`, so
+ * `ctx.credential.get(...)` returned `undefined` and the run died on the
+ * provider's own `MISSING_SECRET` — indistinguishable, to the author, from an
+ * upstream outage or a bad key. It reported as a capability the recorder
+ * lacked only if you already knew to look.
+ */
+function resolveRecordConnection(
+	provider: ProviderRuntime,
+	args: CliArgs,
+): LocalConnection | undefined {
+	if (args.noCredential) {
+		if (providerRequiresConnection(provider)) {
+			console.warn(
+				`[apifuse record] --no-credential: recording ${provider.id} without the credential its auth.mode "${provider.auth?.mode}" declares.`,
+			);
+		}
+		return undefined;
+	}
+
+	const resolution = resolveLocalConnection(provider, {
+		overrides: args.credentials,
+	});
+	if (!resolution.ok)
+		throw new ProviderError(resolution.reason, {
+			code: "CREDENTIAL_UNAVAILABLE",
+			fix: "Supply the credential with --credential or the environment variable named above.",
+		});
+	return resolution.connection;
+}
+
 function normalizeArgs(argv: string[]): string[] {
 	return argv[0] === "record" ? argv.slice(1) : argv;
 }
@@ -103,6 +262,8 @@ function parseArgs(argv: string[]): CliArgs {
 	let params = "{}";
 	let sanitize = true;
 	let append = false;
+	const credentials: string[] = [];
+	let noCredential = false;
 
 	for (let index = 0; index < argv.length; index += 1) {
 		const arg = argv[index];
@@ -159,6 +320,26 @@ function parseArgs(argv: string[]): CliArgs {
 			continue;
 		}
 
+		if (arg === "--credential") {
+			const value = argv[index + 1];
+			if (!value) {
+				throw new Error("Missing value for --credential.");
+			}
+			credentials.push(value);
+			index += 1;
+			continue;
+		}
+
+		if (arg.startsWith("--credential=")) {
+			credentials.push(arg.slice("--credential=".length));
+			continue;
+		}
+
+		if (arg === "--no-credential") {
+			noCredential = true;
+			continue;
+		}
+
 		if (arg.startsWith("-")) {
 			throw new Error(`Unknown option: ${arg}`);
 		}
@@ -171,16 +352,59 @@ function parseArgs(argv: string[]): CliArgs {
 		throw new Error(`Unexpected argument: ${arg}`);
 	}
 
-	return { append, providerPath, operation, params, sanitize };
+	return {
+		append,
+		providerPath,
+		operation,
+		params,
+		sanitize,
+		credentials,
+		noCredential,
+	};
+}
+
+/**
+ * The `resolver` sibling of the server request log, printed once per recorded invocation. The
+ * collector redacts at record time with the values registered so far; the mandatory query-secret
+ * pass over the final line also covers values captured after a solve and short low-entropy values
+ * the diagnostic redactor does not match, the same way handleCliError treats CLI errors.
+ */
+export function formatResolverTelemetry(
+	collector: ResolverTelemetryCollector,
+	sensitiveValues: readonly string[] = [],
+): string | undefined {
+	const resolver = collector.toLogPayload();
+	return resolver
+		? `[apifuse record] Resolver telemetry ${redactSensitiveText(
+				JSON.stringify({ resolver }),
+				sensitiveValues,
+			)}`
+		: undefined;
 }
 
-function handleCliError(error: unknown): never {
-	const message = formatCliError(error);
+function handleCliError(error: unknown, sensitiveValues: readonly string[] = []): never {
+	const message = redactSensitiveText(formatCliError(error), sensitiveValues);
 	console.error(`[apifuse record] ${message}`);
 	process.exit(1);
 }
 
-function formatCliError(error: unknown): string {
+class StreamRecorderError extends Error {
+	readonly diagnosticCauses: readonly unknown[];
+
+	constructor(message: string, diagnosticCauses: readonly unknown[]) {
+		super(message, { cause: diagnosticCauses[0] });
+		this.name = "StreamRecorderError";
+		this.diagnosticCauses = diagnosticCauses;
+	}
+}
+
+export function formatCliError(error: unknown): string {
+	if (error instanceof StreamRecorderError) {
+		return [
+			sanitizeDiagnosticText(error.message),
+			...error.diagnosticCauses.map((cause) => `cause=${formatDiagnosticCause(cause)}`),
+		].join(" ");
+	}
 	if (error instanceof TransportError) {
 		return [
 			error.message,
@@ -201,12 +425,32 @@ function formatCliError(error: unknown): string {
 	}
 
 	if (error instanceof Error) {
+		if (/^Stream capture\b/.test(error.message) && error.cause !== undefined) {
+			return `${sanitizeDiagnosticText(error.message)} cause=${formatDiagnosticCause(error.cause)}`;
+		}
 		return error.message;
 	}
 
 	return String(error);
 }
 
+function formatDiagnosticCause(cause: unknown): string {
+	if (cause instanceof StreamRecorderError) {
+		return [
+			sanitizeDiagnosticText(cause.message),
+			...cause.diagnosticCauses.map((nested) => `cause=${formatDiagnosticCause(nested)}`),
+		].join(" ");
+	}
+	if (!(cause instanceof Error)) return sanitizeDiagnosticText(String(cause));
+	const code =
+		"code" in cause && typeof cause.code === "string"
+			? ` code=${sanitizeDiagnosticText(cause.code)}`
+			: "";
+	const nestedCause =
+		cause.cause === undefined ? "" : ` cause=${formatDiagnosticCause(cause.cause)}`;
+	return `${sanitizeDiagnosticText(cause.message)}${code}${nestedCause}`;
+}
+
 function resolveProviderLocation(inputPath?: string) {
 	const originalInput = inputPath ?? process.cwd();
 	const resolvedInput = resolve(process.cwd(), originalInput);
@@ -284,7 +528,10 @@ function resolveOperationName(provider: ProviderRuntime, operationName?: string)
 	return firstOperation;
 }
 
-function parseParams(operation: ProviderRuntime["operations"][string], value: string): unknown {
+async function parseParams(
+	operation: ProviderRuntime["operations"][string],
+	value: string,
+): Promise<unknown> {
 	let parsed: unknown;
 
 	try {
@@ -295,47 +542,195 @@ function parseParams(operation: ProviderRuntime["operations"][string], value: st
 		);
 	}
 
-	return operation.input ? operation.input.parse(parsed) : parsed;
+	return operation.input ? parseSchema(operation.input, parsed, "record.params") : parsed;
 }
 
-function resolveOperationBaseUrl(provider: ProviderRuntime, operationName: string): string {
-	const baseUrl = provider.operations[operationName]?.upstream?.baseUrl;
-	if (!baseUrl) {
-		throw new Error(
-			`Operation "${operationName}" for provider "${provider.id}" must define upstream.baseUrl.`,
-		);
-	}
+/**
+ * The bases the recorder's `ctx.http` and `ctx.stealth` resolve relative
+ * request URLs against. An absent base means only absolute URLs resolve.
+ */
+export type RecordBaseUrls = {
+	readonly http?: string;
+	readonly stealth?: string;
+};
 
-	return baseUrl;
+/**
+ * `upstream.baseUrl` only resolves relative request URLs (and seeds the stealth
+ * cookie jar's default origin); the recorder uses it for nothing else, so an
+ * operation that requests absolute URLs records without one. The operation's
+ * own base wins; otherwise the recorder binds the bases `serve` binds, so a
+ * relative URL resolves in a recording exactly as it does in production.
+ */
+export function resolveRecordBaseUrls(
+	provider: ProviderRuntime,
+	operationName: string,
+): RecordBaseUrls {
+	const declared = provider.operations[operationName]?.upstream?.baseUrl;
+	const own = typeof declared === "string" && declared.length > 0 ? declared : undefined;
+	const http = own ?? getProviderBaseUrl(provider);
+	const stealth = own ?? getProviderStealthBaseUrl(provider);
+	return { ...(http ? { http } : {}), ...(stealth ? { stealth } : {}) };
 }
 
-function createCaptureContext(provider: ProviderRuntime, baseUrl: string) {
-	let capturedRaw: unknown;
+/** A request the recorder cannot resolve without a declaration; fails the run even if the operation catches it. */
+class RecordRefusalError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "RecordRefusalError";
+	}
+}
 
-	const http = proxyHttpClient(createHttpClient(baseUrl), (response) => {
-		capturedRaw = response.data;
-	});
-	const stealth = proxyStealthClient(createStealthClient(baseUrl), (response) => {
-		capturedRaw = normalizeCapturedStealthResponse(response);
+export function createCaptureContext(
+	provider: ProviderRuntime,
+	baseUrls: RecordBaseUrls,
+	sanitize: boolean,
+	connection?: LocalConnection,
+) {
+	let refusal: RecordRefusalError | undefined;
+	const refuse = (message: string): never => {
+		refusal ??= new RecordRefusalError(message);
+		throw refusal;
+	};
+	const assertResolvableHttpUrl = (url: string) => {
+		if (baseUrls.http || isAbsoluteUrl(url)) return;
+		refuse(
+			`ctx.http cannot resolve the relative URL "${requestPathForFixture(url)}": no operation of provider "${provider.id}" declares upstream.baseUrl. Declare upstream.baseUrl on the recorded operation, or request an absolute URL.`,
+		);
+	};
+	let nextCaptureOrder = 0;
+	let nextStreamOrdinal = 0;
+	let capturedRaw: JsonValue | undefined;
+	const rawCaptures: Array<{ order: number; value: JsonValue }> = [];
+	const streamCaptures: Array<{
+		order: number;
+		request: StreamEvidenceRequest;
+		capture: StreamEvidenceCapture;
+	}> = [];
+	let capturedSse: { order: number; method: string; path: string } | undefined;
+	const sensitiveParamNames = new Set<string>();
+	const sensitiveParamValues = new Set<string>();
+	const cache = createBypassProviderCache({ providerId: provider.id });
+	const { resolver, resolverTelemetry, registerSensitiveValues } = createCliResolverRuntime(
+		provider,
+		cache,
+	);
+	// The injected credential is the most sensitive value in the run, and the
+	// recorder prints provider errors and writes fixtures. Seed its VALUES into
+	// the redaction set before anything can execute, so an upstream error that
+	// echoes the key, and any fixture that captured it, are redacted by the same
+	// machinery that already covers declared query secrets.
+	//
+	// Values only, never the key names: `sensitiveParamNames` means "declared
+	// query-key position", and `redactFixture` deliberately skips common-field
+	// sanitization for a key that appears in it. Seeding `access_token` there
+	// would therefore write a *newly issued* upstream `access_token` — which
+	// does not equal the injected value — to raw.json in plaintext. A credential
+	// key that really is a query parameter is added to the name set by
+	// `captureSensitiveRequestValues` when the provider sends it, which is the
+	// only place that claim is true.
+	for (const value of Object.values(connection?.secrets ?? {})) {
+		if (value.length > 0) sensitiveParamValues.add(value);
+	}
+	registerSensitiveValues([...sensitiveParamValues]);
+
+	const captureSensitiveParams = (url: string, options?: SensitiveRequestOptions) => {
+		try {
+			captureSensitiveRequestValues(url, options, sensitiveParamNames, sensitiveParamValues);
+		} finally {
+			// Resolver telemetry redacts at record time, so the vendor diagnostics of a later solve
+			// must not echo a query secret captured here (same guarantee as handleCliError).
+			registerSensitiveValues([...sensitiveParamValues]);
+		}
+	};
+	const getCapturedSensitiveParams = (): CapturedSensitiveParams => ({
+		names: [...sensitiveParamNames],
+		values: [...sensitiveParamValues],
 	});
-
-	const env = {
-		get: (key: string) => process.env[key],
+	const reserveCaptureOrder = () => {
+		nextCaptureOrder += 1;
+		return nextCaptureOrder;
 	};
-	const credential = {
-		mode: "none" as const,
-		get: () => undefined,
-		getAll: () => ({}),
-		getAccessToken: () => undefined,
-		getScopes: () => [],
+	const retainRawCapture = (order: number, value: unknown) => {
+		const json = jsonFixtureValue(value);
+		capturedRaw = json;
+		rawCaptures.push({ order, value: json });
 	};
+
+	const http = captureHttpClient(createHttpClient(baseUrls.http), {
+		assertResolvableUrl: assertResolvableHttpUrl,
+		reserveOrder: reserveCaptureOrder,
+		reserveStreamOrdinal: () => {
+			nextStreamOrdinal += 1;
+			return nextStreamOrdinal;
+		},
+		onSensitiveParams: captureSensitiveParams,
+		onResponse: (order, response) => retainRawCapture(order, response.data),
+		onStreamResponse: (order, ordinal, requestUrl, method, response) => {
+			const resolvedRequestUrl = new URL(requestUrl, baseUrls.http).toString();
+			const request = {
+				ordinal,
+				method,
+				path: requestPathForFixture(resolvedRequestUrl),
+			};
+			const capture = captureStreamEvidence(response, {
+				requestUrl: resolvedRequestUrl,
+				request,
+				...(sanitize
+					? {
+							sanitizeFixture: (value: JsonValue) =>
+								jsonFixtureValue(sanitizeStreamFixture(value, getCapturedSensitiveParams())),
+						}
+					: {}),
+			});
+			streamCaptures.push({ order, request, capture });
+			return capture.response;
+		},
+		onSseResponse: (order, requestUrl, method) => {
+			capturedSse = {
+				order,
+				method,
+				path: requestPathForFixture(new URL(requestUrl, baseUrls.http).toString()),
+			};
+		},
+	});
+	// Without a base `serve` binds no stealth transport either, so every call is refused.
+	const refuseStealth = (): never =>
+		refuse(
+			`ctx.stealth has no base URL: provider "${provider.id}" declares neither upstream.baseUrl nor allowedHosts. Declare allowedHosts on the provider (serve binds ctx.stealth to https://<allowedHosts[0]>) or upstream.baseUrl on the recorded operation.`,
+		);
+	const stealth: StealthClient = baseUrls.stealth
+		? proxyStealthClient(
+				createStealthClient(baseUrls.stealth, {
+					...(provider.stealth ? { stealth: provider.stealth } : {}),
+				}),
+				captureSensitiveParams,
+				(order, response) => retainRawCapture(order, normalizeCapturedStealthResponse(response)),
+				reserveCaptureOrder,
+			)
+		: { fetch: async () => refuseStealth(), createSession: refuseStealth };
+
+	const providerEnvironment = createProviderEnvironment(
+		process.env,
+		provider.secrets?.map((secret) => secret.name) ?? [],
+	);
+	const env = { get: (key: string) => readDiagnosticEnv(key, providerEnvironment) };
+	// Built exactly the way `serve` builds it from a gateway-supplied
+	// `request.connection`, so the provider takes its production branch rather
+	// than the always-undefined one a stub credential forces.
+	const credential = createCredentialContext({
+		...(provider.credential?.keys ? { allowedKeys: provider.credential.keys } : {}),
+		...(connection ? { mode: connection.mode, values: connection.secrets } : {}),
+	});
 	const state = createMemoryProviderRuntimeState();
-	const ctx: ProviderContext = {
+	const candidates: ProviderEngineBindingCandidates = {
 		env,
 		credential,
-		request: { headers: {} },
+		request: {
+			headers: {},
+			connectionId: connection ? LOCAL_CONNECTION_ID : "local-record",
+		},
 		http,
-		cache: createBypassProviderCache({ providerId: provider.id }),
+		cache,
 		state,
 		stealth,
 		browser: {
@@ -362,70 +757,292 @@ function createCaptureContext(provider: ProviderRuntime, baseUrl: string) {
 				throw new Error("Auth prompts are not available in apifuse record.");
 			},
 		},
+		ocr: createOcrClientFromEnv(provider.ocr),
 		stt: createSttClientFromEnv(provider.stt),
-		choice: createProviderChoiceContext({
+		resolver,
+		handle: createHandleContext({
 			providerId: provider.id,
-			env,
-			request: { headers: {} },
-			credential,
+			request: {
+				headers: {},
+				connectionId: connection ? LOCAL_CONNECTION_ID : "local-record",
+			},
 			state,
 		}),
 	};
+	const ctx = createInProcessProviderEngine().attach({
+		provider,
+		bindings: candidates,
+	}) as ProviderContext;
 
 	return {
 		ctx,
-		getCapturedRaw: () => capturedRaw,
+		resolverTelemetry,
+		throwIfRefused: () => {
+			if (refusal) throw refusal;
+		},
+		getCapturedRaw: async () => {
+			if (streamCaptures.length === 0) {
+				if (capturedSse) throw unsupportedSseCaptureError(capturedSse);
+				return capturedRaw;
+			}
+
+			const settled = await Promise.allSettled(
+				streamCaptures.map(async ({ order, request, capture }) => ({
+					order,
+					request,
+					value: redactStreamEvidence(await capture.getEvidence(), getCapturedSensitiveParams()),
+				})),
+			);
+			const failures = settled.flatMap((result, index) =>
+				result.status === "rejected"
+					? [
+							new StreamRecorderError(
+								`Stream finalization failed: method=${streamCaptures[index]!.request.method} path=${streamCaptures[index]!.request.path} ordinal=${streamCaptures[index]!.request.ordinal}.`,
+								[result.reason],
+							),
+						]
+					: [],
+			);
+			if (failures.length > 0) {
+				throw new StreamRecorderError(
+					`${failures.length} stream capture${failures.length === 1 ? "" : "s"} failed to finalize.`,
+					failures,
+				);
+			}
+			const evidence = settled.flatMap((result) =>
+				result.status === "fulfilled" ? [result.value] : [],
+			);
+			if (capturedSse) throw unsupportedSseCaptureError(capturedSse);
+			const timeline: StreamCaptureGroupItem[] = [...rawCaptures, ...evidence]
+				.sort((left, right) => left.order - right.order)
+				.map((item) =>
+					"request" in item
+						? { kind: "stream" as const, evidence: item.value }
+						: { kind: "response" as const, value: item.value },
+				);
+			return createStreamCaptureEnvelope(timeline);
+		},
+		getCapturedSensitiveParams,
 	};
 }
 
-function proxyHttpClient(
-	client: HttpClient,
-	onResponse: (response: Awaited<ReturnType<HttpClient["get"]>>) => void,
-): HttpClient {
-	return new Proxy(client, {
-		get(target, prop, receiver) {
-			const value = Reflect.get(target, prop, receiver);
+type CapturedSensitiveParams = {
+	names: readonly string[];
+	values: readonly string[];
+};
 
-			if (typeof value !== "function") {
-				return value;
-			}
+type SensitiveRequestOptions = Pick<RequestOptions, "params" | "sensitiveParams">;
+
+function captureSensitiveRequestValues(
+	url: string,
+	options: SensitiveRequestOptions | undefined,
+	names: Set<string>,
+	values: Set<string>,
+): void {
+	const sensitiveParams = normalizeSensitiveParams(options?.sensitiveParams);
+	if (sensitiveParams === undefined) return;
+	if (!sensitiveParams || typeof sensitiveParams !== "object" || Array.isArray(sensitiveParams)) {
+		throw new TypeError("sensitiveParams must be an object whose values are strings.");
+	}
 
-			return async (...args: unknown[]) => {
-				const response = await value.apply(target, args);
-				onResponse(response);
-				return response;
-			};
+	const entries = Object.entries(sensitiveParams);
+	for (const [key, value] of entries) {
+		if (typeof value !== "string") {
+			throw new TypeError(`sensitiveParams.${key} must be a string.`);
+		}
+		names.add(key);
+		if (value !== "") values.add(value);
+	}
+
+	let serializedUrl: ReturnType<typeof serializeRequestUrl>;
+	try {
+		const absoluteUrl = new URL(String(url), "http://apifuse.invalid").toString();
+		serializedUrl = serializeRequestUrl(absoluteUrl, options?.params, sensitiveParams);
+	} catch (error) {
+		const structural = redactUrlQueryParams(String(url), [...names]);
+		const safeUrl = redactSensitiveText(structural.redactedUrl, [
+			...values,
+			...structural.sensitiveValues,
+		]);
+		const causeKind = error instanceof Error ? error.name : typeof error;
+		throw new TypeError(`Cannot securely record sensitiveParams for "${safeUrl}" (${causeKind}).`, {
+			cause: redactSensitiveError(
+				error,
+				[...values, ...structural.sensitiveValues],
+				String(url),
+				structural.redactedUrl,
+			),
+		});
+	}
+
+	for (const value of serializedUrl.sensitiveValues) {
+		if (value !== "") values.add(value);
+	}
+}
+
+function snapshotRequestOptions<T extends SensitiveRequestOptions>(options: T): T {
+	return {
+		...options,
+		...(options.params
+			? {
+					params: Object.fromEntries(
+						Object.entries(options.params).map(([key, value]) => [
+							key,
+							Array.isArray(value) ? [...value] : value,
+						]),
+					),
+				}
+			: {}),
+		...(normalizeSensitiveParams(options.sensitiveParams)
+			? { sensitiveParams: { ...options.sensitiveParams } }
+			: {}),
+	};
+}
+
+type HttpCaptureCallbacks = {
+	/** Throws before the request when the recorder cannot resolve `url`. */
+	assertResolvableUrl(url: string): void;
+	reserveOrder(): number;
+	reserveStreamOrdinal(): number;
+	onSensitiveParams(url: string, options?: RequestOptions): void;
+	onResponse(order: number, response: HttpResponse): void;
+	onStreamResponse(
+		order: number,
+		ordinal: number,
+		requestUrl: string,
+		method: string,
+		response: HttpStreamResponse,
+	): HttpStreamResponse;
+	onSseResponse(order: number, requestUrl: string, method: string): void;
+};
+
+function captureHttpClient(client: HttpClient, callbacks: HttpCaptureCallbacks): HttpClient {
+	const captureResponse = async (
+		order: number,
+		responsePromise: Promise<HttpResponse>,
+	): Promise<HttpResponse> => {
+		const response = await responsePromise;
+		callbacks.onResponse(order, response);
+		return response;
+	};
+	const captureRequestOptions = (method: PropertyKey, args: unknown[]) => {
+		callbacks.assertResolvableUrl(String(args[0]));
+		const invocation = parseHttpRequestInvocation(method, args);
+		const options = invocation ? requestOptionsFromHttpInvocation(invocation) : undefined;
+		if (!invocation || !options) return;
+		const snapshot = snapshotRequestOptions(options);
+		callbacks.onSensitiveParams(String(args[0]), snapshot);
+		replaceRequestOptionsInHttpInvocation(invocation, snapshot);
+	};
+
+	return {
+		request: (...args: Parameters<HttpClient["request"]>) => {
+			captureRequestOptions("request", args);
+			return captureResponse(callbacks.reserveOrder(), client.request(...args));
+		},
+		get: (...args: Parameters<HttpClient["get"]>) => {
+			captureRequestOptions("get", args);
+			return captureResponse(callbacks.reserveOrder(), client.get(...args));
+		},
+		post: (...args: Parameters<HttpClient["post"]>) => {
+			captureRequestOptions("post", args);
+			return captureResponse(callbacks.reserveOrder(), client.post(...args));
+		},
+		put: (...args: Parameters<HttpClient["put"]>) => {
+			captureRequestOptions("put", args);
+			return captureResponse(callbacks.reserveOrder(), client.put(...args));
+		},
+		delete: (...args: Parameters<HttpClient["delete"]>) => {
+			captureRequestOptions("delete", args);
+			return captureResponse(callbacks.reserveOrder(), client.delete(...args));
+		},
+		stream: async (...args: Parameters<HttpClient["stream"]>) => {
+			captureRequestOptions("stream", args);
+			const order = callbacks.reserveOrder();
+			const ordinal = callbacks.reserveStreamOrdinal();
+			const method = (args[1]?.method ?? "GET").toUpperCase();
+			const response = await client.stream(...args);
+			return callbacks.onStreamResponse(order, ordinal, args[0], method, response);
 		},
-	}) as HttpClient;
+		sse: async (...args: Parameters<HttpClient["sse"]>) => {
+			captureRequestOptions("sse", args);
+			const order = callbacks.reserveOrder();
+			const response = await client.sse(...args);
+			callbacks.onSseResponse(order, args[0], (args[1]?.method ?? "GET").toUpperCase());
+			return response;
+		},
+	};
 }
 
 type StealthSession = ReturnType<StealthClient["createSession"]>;
 
 function proxyStealthClient(
 	client: StealthClient,
-	onResponse: (response: Awaited<ReturnType<StealthClient["fetch"]>>) => void,
+	onSensitiveParams: (url: string, options?: SensitiveRequestOptions) => void,
+	onResponse: (order: number, response: Awaited<ReturnType<StealthClient["fetch"]>>) => void,
+	reserveOrder: () => number,
 ): StealthClient {
 	return {
 		fetch: async (...args: Parameters<StealthClient["fetch"]>) => {
+			const order = reserveOrder();
+			if (args[1]) args[1] = snapshotRequestOptions(args[1]);
+			onSensitiveParams(args[0], args[1]);
 			const response = await client.fetch(...args);
-			onResponse(response);
+			if (response.url) onSensitiveParams(response.url, args[1]);
+			onResponse(order, response);
 			return response;
 		},
 		createSession: (...args: Parameters<StealthClient["createSession"]>) =>
-			proxyStealthSession(client.createSession(...args), onResponse),
+			proxyStealthSession(
+				client.createSession(...args),
+				onSensitiveParams,
+				onResponse,
+				reserveOrder,
+			),
 	};
 }
 
 function proxyStealthSession(
 	session: StealthSession,
-	onResponse: (response: Awaited<ReturnType<StealthClient["fetch"]>>) => void,
+	onSensitiveParams: (url: string, options?: SensitiveRequestOptions) => void,
+	onResponse: (order: number, response: Awaited<ReturnType<StealthClient["fetch"]>>) => void,
+	reserveOrder: () => number,
 ): StealthSession {
 	return {
 		fetch: async (...args: Parameters<StealthSession["fetch"]>) => {
+			const order = reserveOrder();
+			if (args[1]) args[1] = snapshotRequestOptions(args[1]);
+			onSensitiveParams(args[0], args[1]);
 			const response = await session.fetch(...args);
-			onResponse(response);
+			if (response.url) onSensitiveParams(response.url, args[1]);
+			onResponse(order, response);
+			return response;
+		},
+		replayChallenged: async (...args: Parameters<StealthSession["replayChallenged"]>) => {
+			const order = reserveOrder();
+			const response = await session.replayChallenged(...args);
+			onResponse(order, response);
 			return response;
 		},
+		cookies: session.cookies,
+		redirects: {
+			run: async (...args: Parameters<StealthSession["redirects"]["run"]>) => {
+				const order = reserveOrder();
+				args[0] = snapshotRequestOptions(args[0]);
+				onSensitiveParams(args[0].url, args[0]);
+				const callerStopWhen = args[0].stopWhen;
+				args[0].stopWhen = async (hop) => {
+					for (const url of [hop.url, hop.location, hop.nextUrl]) {
+						if (url) onSensitiveParams(url, args[0]);
+					}
+					return callerStopWhen ? await callerStopWhen(hop) : false;
+				};
+				const result = await session.redirects.run(...args);
+				if (result.final.url) onSensitiveParams(result.final.url, args[0]);
+				onResponse(order, result.final);
+				return result;
+			},
+		},
 		close: () => session.close(),
 	};
 }
@@ -438,31 +1055,193 @@ function normalizeCapturedStealthResponse(response: Awaited<ReturnType<StealthCl
 	}
 }
 
-function sanitizeFixture(value: unknown): unknown {
+function redactStreamEvidence(
+	evidence: Awaited<ReturnType<StreamEvidenceCapture["getEvidence"]>>,
+	sensitiveParams: CapturedSensitiveParams,
+): Awaited<ReturnType<StreamEvidenceCapture["getEvidence"]>> {
+	return parseStreamEvidenceRecord(redactFixture(evidence, sensitiveParams, false));
+}
+
+function sanitizeStreamFixture(value: unknown, sensitiveParams: CapturedSensitiveParams): unknown {
+	if (typeof value === "string") {
+		if (value !== "" && sensitiveParams.values.includes(value)) return REDACTED_QUERY_VALUE;
+		return sanitizeFixtureString(redactFixtureText(value, sensitiveParams));
+	}
 	if (Array.isArray(value)) {
-		return value.map((item) => sanitizeFixture(item));
+		return value.map((item) => sanitizeStreamFixture(item, sensitiveParams));
 	}
-
 	if (!value || typeof value !== "object") {
-		return value;
+		return redactFixture(value, sensitiveParams, false);
 	}
 
-	const entries = Object.entries(value as MutableRecord).map(([key, entryValue]) => {
-		if (isSensitiveKey(key)) {
-			return [key, "[REDACTED]"] as const;
-		}
+	const result: MutableRecord = Object.create(null) as MutableRecord;
+	for (const [key, entryValue] of Object.entries(value as MutableRecord)) {
+		const redactedKey = sensitiveParams.values.includes(key)
+			? REDACTED_QUERY_VALUE
+			: redactFixtureText(key, sensitiveParams);
+		const uniqueKey = collisionSafeKey(result, redactedKey);
+		result[uniqueKey] =
+			isSensitiveFixtureKey(key) && !sensitiveParams.names.includes(key)
+				? REDACTED_QUERY_VALUE
+				: sanitizeStreamFixture(entryValue, sensitiveParams);
+	}
+	return result;
+}
 
-		return [key, sanitizeFixture(entryValue)] as const;
-	});
+function redactStreamPreview(
+	bodyPreviewBase64: string,
+	sensitiveParams: CapturedSensitiveParams,
+): { bodyPreviewBase64: string; changed: boolean } {
+	const preview = Buffer.from(bodyPreviewBase64, "base64");
+	if (preview.byteLength === 0) return { bodyPreviewBase64, changed: false };
+
+	const text = new TextDecoder().decode(preview);
+	let redactedText = redactFixtureText(text, sensitiveParams);
+	const trimmed = text.trimEnd();
+	try {
+		const parsed = JSON.parse(trimmed) as unknown;
+		const structurallyRedacted = JSON.stringify(redactFixture(parsed, sensitiveParams, false));
+		if (structurallyRedacted !== JSON.stringify(parsed)) redactedText = structurallyRedacted;
+	} catch {
+		// Non-JSON previews still use the shared free-text sensitive-value policy.
+	}
+	if (redactedText === text) return { bodyPreviewBase64, changed: false };
 
-	return Object.fromEntries(entries);
+	const fitted = Buffer.alloc(preview.byteLength, 0x20);
+	let redactedBytes = Buffer.from(redactedText);
+	if (redactedBytes.byteLength > fitted.byteLength) {
+		redactedBytes = Buffer.from(REDACTED_QUERY_VALUE);
+	}
+	redactedBytes.copy(fitted, 0, 0, Math.min(redactedBytes.byteLength, fitted.byteLength));
+	return { bodyPreviewBase64: fitted.toString("base64"), changed: true };
 }
 
-function isSensitiveKey(key: string): boolean {
-	return /authorization|token|api[-_]?key/i.test(key);
+function redactFixture(
+	value: unknown,
+	sensitiveParams: CapturedSensitiveParams,
+	sanitizeCommonFields: boolean,
+): unknown {
+	if (typeof value === "string") {
+		if (value !== "" && sensitiveParams.values.includes(value)) return REDACTED_QUERY_VALUE;
+		return redactFixtureText(value, sensitiveParams);
+	}
+
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+		return sensitiveParams.values.includes(String(value)) ? REDACTED_QUERY_VALUE : value;
+	}
+
+	if (Array.isArray(value)) {
+		return value.map((item) => redactFixture(item, sensitiveParams, sanitizeCommonFields));
+	}
+
+	if (!value || typeof value !== "object") return value;
+
+	const result: MutableRecord = Object.create(null) as MutableRecord;
+	for (const [key, entryValue] of Object.entries(value as MutableRecord)) {
+		const redactedKey = sensitiveParams.values.includes(key)
+			? REDACTED_QUERY_VALUE
+			: redactFixtureText(key, sensitiveParams);
+		const uniqueKey = collisionSafeKey(result, redactedKey);
+		result[uniqueKey] =
+			sanitizeCommonFields &&
+			(isSensitiveKey(key) || isSensitiveFixtureKey(key)) &&
+			!sensitiveParams.names.includes(key)
+				? REDACTED_QUERY_VALUE
+				: redactFixture(entryValue, sensitiveParams, sanitizeCommonFields);
+	}
+	const record = value as MutableRecord;
+	if (record.__apifuse_stream__ === true && typeof record.body_preview_base64 === "string") {
+		const preview = redactStreamPreview(record.body_preview_base64, sensitiveParams);
+		result.body_preview_base64 = preview.bodyPreviewBase64;
+		if (preview.changed) result.preview_sanitized = true;
+	}
+	return result;
+}
+
+function redactFixtureText(text: string, sensitiveParams: CapturedSensitiveParams): string {
+	// Shared free-text policy: long values are unconditional substrings; values
+	// shorter than four characters require token boundaries. Exact scalar echoes
+	// and declared query-key positions are structurally redacted for every length.
+	let redacted = redactSensitiveText(text, sensitiveParams.values);
+	for (const name of sensitiveParams.names) {
+		let componentEncodedName = name;
+		try {
+			componentEncodedName = encodeURIComponent(name);
+		} catch {
+			// Lone surrogates remain covered by the raw and form-encoded variants.
+		}
+		const keyVariants = new Set([
+			name,
+			componentEncodedName,
+			new URLSearchParams({ [name]: "" }).toString().slice(0, -1),
+		]);
+		for (const key of keyVariants) {
+			const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+			const queryValue = new RegExp(`(^|[?&])(${escapedKey}=)[^&#\\s"]*`, "g");
+			redacted = redacted.replace(queryValue, (_match, prefix, assignment) => {
+				return `${prefix}${assignment}${REDACTED_QUERY_VALUE}`;
+			});
+		}
+	}
+	return redacted;
+}
+
+function discoverSensitiveQueryValues(
+	value: unknown,
+	sensitiveParams: CapturedSensitiveParams,
+): CapturedSensitiveParams {
+	const values = new Set(sensitiveParams.values);
+	const absoluteUrl = /\b[A-Za-z][A-Za-z\d+.-]*:\/\/[^\s<>"']+/g;
+	const discoverFromUrl = (url: string) => {
+		for (const discovered of redactUrlQueryParams(url, sensitiveParams.names).sensitiveValues) {
+			if (discovered !== "" && discovered !== REDACTED_QUERY_VALUE) values.add(discovered);
+		}
+	};
+	const visitText = (text: string) => {
+		if (!/\s/.test(text)) {
+			try {
+				new URL(text, "http://apifuse.invalid");
+				discoverFromUrl(text);
+				return;
+			} catch {
+				// Fall through to extracting absolute URL spans from prose.
+			}
+		}
+		for (const match of text.matchAll(absoluteUrl)) {
+			try {
+				new URL(match[0]);
+				discoverFromUrl(match[0]);
+			} catch {
+				// Ignore URI-like prose that is not a parseable URL.
+			}
+		}
+	};
+	const visit = (current: unknown): void => {
+		if (typeof current === "string") {
+			visitText(current);
+			return;
+		}
+		if (Array.isArray(current)) {
+			for (const item of current) visit(item);
+			return;
+		}
+		if (!current || typeof current !== "object") return;
+		for (const [key, entryValue] of Object.entries(current as MutableRecord)) {
+			visitText(key);
+			visit(entryValue);
+		}
+	};
+	visit(value);
+	return { names: sensitiveParams.names, values: [...values] };
 }
 
-async function prepareFixturePayload(
+function collisionSafeKey(record: MutableRecord, preferredKey: string): string {
+	if (!(preferredKey in record)) return preferredKey;
+	let suffix = 2;
+	while (`${preferredKey}#${suffix}` in record) suffix += 1;
+	return `${preferredKey}#${suffix}`;
+}
+export async function prepareFixturePayload(
 	fixturePath: string,
 	payload: unknown,
 	append: boolean,
@@ -471,15 +1250,45 @@ async function prepareFixturePayload(
 		return payload;
 	}
 
+	let fixtureSource: string;
 	try {
-		const existing = JSON.parse(readFileSync(fixturePath, "utf8")) as unknown;
-		if (Array.isArray(existing)) {
-			return [...existing, payload];
-		}
-	} catch {
-		// Fall through to overwrite with the new payload.
+		fixtureSource = readFileSync(fixturePath, "utf8");
+	} catch (error) {
+		throw new Error(
+			`Cannot append to existing fixture "${fixturePath}" because it could not be read: ${
+				error instanceof Error ? error.message : String(error)
+			}. Fix its permissions or delete it, then run apifuse record --append again.`,
+		);
 	}
 
+	let existing: unknown;
+	try {
+		existing = JSON.parse(fixtureSource) as unknown;
+	} catch (error) {
+		throw new Error(
+			`Cannot append to corrupt fixture "${fixturePath}" because it is not valid JSON: ${
+				error instanceof Error ? error.message : String(error)
+			}. Fix or delete the fixture, then run apifuse record --append again.`,
+		);
+	}
+
+	if (hasStreamEvidenceMarker(existing)) {
+		const evidence = parseStreamEvidenceRecord(existing);
+		return [createStreamCaptureEnvelope([{ kind: "stream", evidence }]), payload];
+	}
+	if (Array.isArray(existing)) {
+		if (existing.some((item) => hasStreamEvidenceMarker(item))) {
+			const legacyGroup = findStreamCaptureGroup(existing);
+			if (legacyGroup) {
+				const prefix = existing.slice(0, -legacyGroup.items.length);
+				return [...prefix, createStreamCaptureEnvelope(legacyGroup.items), payload];
+			}
+		}
+		return [...existing, payload];
+	}
+	if (existing !== null) {
+		return [existing, payload];
+	}
 	return payload;
 }
 
@@ -491,4 +1300,24 @@ function formatBytes(bytes: number): string {
 	return `${(bytes / 1024).toFixed(1)} KB`;
 }
 
-await main();
+function jsonFixtureValue(value: unknown): JsonValue {
+	const serialized = JSON.stringify(value);
+	if (serialized === undefined) {
+		throw new Error("Captured upstream response is not JSON-serializable.");
+	}
+	return JSON.parse(serialized) as JsonValue;
+}
+
+function unsupportedSseCaptureError(request: {
+	order: number;
+	method: string;
+	path: string;
+}): Error {
+	return new Error(
+		`apifuse record does not support ctx.http.sse(): method=${request.method} path=${request.path} call=${request.order}.`,
+	);
+}
+
+if (import.meta.main) {
+	await main();
+}