@apifuse/provider-sdk 2.2.0-beta.1 → 2.2.0-beta.10

package/src/server/serve.ts

@@ -3,62 +3,65 @@ import { join } from "node:path";
 
 import { Hono } from "hono";
 import { z } from "zod";
-import { AuthAbortError, createAuthFlowHelpers } from "../auth";
+import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
 import {
 	AuthError,
+	isProviderError,
+	isSessionExpiredError,
+	isTransportError,
 	ProviderError,
-	SessionExpiredError,
-	TransportError,
-} from "../errors";
+} from "../errors.js";
 import {
 	loadProviderLocaleCatalogs,
 	localizeAuthTurn,
 	type ProviderLocaleCatalogMap,
-} from "../i18n/catalog";
-import type { ProviderLocale } from "../i18n/keys";
+} from "../i18n/catalog.js";
+import type { ProviderLocale } from "../i18n/keys.js";
 import {
 	categoryForStatus,
 	isRetryableCategory,
 	PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
 	type ProviderErrorCategory,
-} from "../observability";
-import { createScratchpad } from "../runtime/auth-flow";
-import { createBrowserClient } from "../runtime/browser";
-import { createProviderCache } from "../runtime/cache";
+} from "../observability.js";
+import { createScratchpad } from "../runtime/auth-flow.js";
+import { createBrowserClient } from "../runtime/browser.js";
+import { createProviderCache } from "../runtime/cache.js";
 import {
 	createProviderChoiceContext,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
-} from "../runtime/choice";
-import { createCredentialContext } from "../runtime/credential";
-import { createEnvContext } from "../runtime/env";
-import { executeOperation } from "../runtime/executor";
-import { createHttpClient } from "../runtime/http";
-import { wrapWithInstrumentation } from "../runtime/instrumentation";
-import { getProviderBaseUrl } from "../runtime/provider";
+} from "../runtime/choice.js";
+import { createCredentialContext } from "../runtime/credential.js";
+import { createEnvContext } from "../runtime/env.js";
+import { executeOperation } from "../runtime/executor.js";
+import { createHttpClient } from "../runtime/http.js";
+import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
+import { getProviderBaseUrl } from "../runtime/provider.js";
 import {
 	PROXY_AUTH_IP_DENIED_CODE,
 	PROXY_EDGE_AUTH_REJECTED_CODE,
 	PROXY_POOL_EXHAUSTED_CODE,
-} from "../runtime/proxy-errors";
+} from "../runtime/proxy-errors.js";
+import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector } from "../runtime/proxy-telemetry.js";
 import {
-	PROVIDER_TELEMETRY_HEADER,
-	ProxyTelemetryCollector,
-} from "../runtime/proxy-telemetry";
+	assertRequiredSecretsPresent,
+	listMissingRequiredSecrets,
+	MISSING_SECRET_CODE,
+} from "../runtime/secrets.js";
 import {
 	createProviderRuntimeStateFromEnv,
 	createUnsupportedProviderRuntimeState,
-} from "../runtime/state";
-import { createStealthClient } from "../runtime/stealth";
-import { createSttClientFromEnv } from "../runtime/stt";
-import { createTraceContext } from "../runtime/trace";
-import { parseSchema } from "../schema";
-import { getStealthProfile } from "../stealth/profiles";
+} from "../runtime/state.js";
+import { createStealthClient } from "../runtime/stealth.js";
+import { createSttClientFromEnv } from "../runtime/stt.js";
+import { createTraceContext } from "../runtime/trace.js";
+import { parseSchema } from "../schema.js";
+import { getStealthProfile } from "../stealth/profiles.js";
 import {
 	APIFUSE_STREAM_DONE_EVENT,
 	APIFUSE_STREAM_ERROR_EVENT,
 	encodeSseEvent,
 	error as streamError,
-} from "../stream";
+} from "../stream.js";
 import type {
 	AuthContext,
 	AuthTurn,
@@ -75,13 +78,14 @@ import type {
 	ProviderStreamEvent,
 	StealthClient,
 	SttContext,
-} from "../types";
+} from "../types.js";
 import {
 	createSelfTestApp,
+	createSelfTestAuthFlowInvoke,
 	createSelfTestInvoke,
 	resolveSelfTestPort,
-} from "./self-test";
-import { resolveSelfTestMasterSecrets } from "./self-test-token";
+} from "./self-test.js";
+import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
 import {
 	type AuthFlowRequest,
 	AuthFlowRequestSchema,
@@ -92,7 +96,7 @@ import {
 	OperationRequestSchema,
 	type OperationResponse,
 	type OperationSuccessResponse,
-} from "./types";
+} from "./types.js";
 
 const DEFAULT_HOST = "0.0.0.0";
 const DEFAULT_PORT = 3000;
@@ -156,9 +160,7 @@ function createStealthStub(): StealthClient {
 	};
 }
 
-function getProviderStealthBaseUrl(
-	provider: ProviderDefinition,
-): string | undefined {
+function getProviderStealthBaseUrl(provider: ProviderDefinition): string | undefined {
 	const baseUrl = getProviderBaseUrl(provider);
 	if (baseUrl) {
 		return baseUrl;
@@ -168,15 +170,10 @@ function getProviderStealthBaseUrl(
 }
 
 function getProviderStealthProfile(provider: ProviderDefinition) {
-	return provider.stealth?.profile
-		? getStealthProfile(provider.stealth.profile)
-		: undefined;
+	return provider.stealth?.profile ? getStealthProfile(provider.stealth.profile) : undefined;
 }
 
-function isProductionProviderBrowserMode(
-	provider: ProviderDefinition,
-	env = process.env,
-): boolean {
+function isProductionProviderBrowserMode(provider: ProviderDefinition, env = process.env): boolean {
 	if (provider.runtime !== "browser") {
 		return false;
 	}
@@ -185,9 +182,7 @@ function isProductionProviderBrowserMode(
 		return true;
 	}
 
-	return (
-		env.NODE_ENV === "production" && env.APIFUSE__PROVIDER__ID === provider.id
-	);
+	return env.NODE_ENV === "production" && env.APIFUSE__PROVIDER__ID === provider.id;
 }
 
 export function resolveProviderProxyAffinityKey(
@@ -195,18 +190,19 @@ export function resolveProviderProxyAffinityKey(
 	request: OperationRequest,
 	operationId: string,
 ): string {
-	const connectionKey =
-		request.connection?.id ?? request.connection?.externalRef;
+	const connectionKey = resolveOperationConnectionId(request) ?? request.connection?.externalRef;
 	const affinity =
-		typeof provider.proxy === "object"
-			? provider.proxy.session?.affinity
-			: undefined;
+		typeof provider.proxy === "object" ? provider.proxy.session?.affinity : undefined;
 	if (affinity === "operation") {
 		return `${provider.id}/${operationId}`;
 	}
 	return connectionKey ?? provider.id;
 }
 
+function resolveOperationConnectionId(request: OperationRequest): string | undefined {
+	return request.connection?.id ?? request.connectionId;
+}
+
 function createProviderContext(
 	provider: ProviderDefinition,
 	request: OperationRequest,
@@ -220,11 +216,7 @@ function createProviderContext(
 	const stealthProfile = getProviderStealthProfile(provider);
 	const proxyClientOptions = {
 		upstream: { proxy: provider.proxy },
-		affinityKey: resolveProviderProxyAffinityKey(
-			provider,
-			request,
-			operationId,
-		),
+		affinityKey: resolveProviderProxyAffinityKey(provider, request, operationId),
 		telemetry: proxyTelemetry,
 	};
 	let wrappedContext: ProviderContext | undefined;
@@ -245,7 +237,7 @@ function createProviderContext(
 		values: request.connection?.secrets,
 	});
 	const requestContext = {
-		connectionId: request.connection?.id,
+		connectionId: resolveOperationConnectionId(request),
 		headers: request.headers ?? {},
 	};
 	const context = wrapWithInstrumentation({
@@ -263,11 +255,7 @@ function createProviderContext(
 		state,
 		stealth: stealthBaseUrl
 			? stealthProfile
-				? createStealthClient(
-						stealthBaseUrl,
-						stealthProfile.name,
-						stealthClientOptions,
-					)
+				? createStealthClient(stealthBaseUrl, stealthProfile.name, stealthClientOptions)
 				: createStealthClient(stealthBaseUrl, stealthClientOptions)
 			: createStealthStub(),
 		browser:
@@ -380,11 +368,7 @@ function createAuthFlowContext(
 			http: createHttpClient(baseUrl, proxyClientOptions),
 			stealth: stealthBaseUrl
 				? stealthProfile
-					? createStealthClient(
-							stealthBaseUrl,
-							stealthProfile.name,
-							stealthClientOptions,
-						)
+					? createStealthClient(stealthBaseUrl, stealthProfile.name, stealthClientOptions)
 					: createStealthClient(stealthBaseUrl, stealthClientOptions)
 				: createStealthStub(),
 			env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
@@ -429,6 +413,12 @@ export type ProviderServerLogEvent =
 			retryable?: boolean;
 			issues?: Array<{ path: string; code: string; message: string }>;
 	  })
+	| {
+			level: "warn";
+			event: "provider_secrets_missing";
+			providerId: string;
+			missingSecrets: string[];
+	  }
 	| {
 			level: "warn";
 			event: "provider_cleanup_failed";
@@ -497,11 +487,8 @@ function zodDetails(error: z.ZodError): Array<{
 	}));
 }
 
-function toErrorResponse(
-	error: unknown,
-	requestId?: string,
-): OperationErrorResponse {
-	if (error instanceof ProviderError) {
+function toErrorResponse(error: unknown, requestId?: string): OperationErrorResponse {
+	if (isProviderError(error)) {
 		const details = publicProviderErrorDetails(error);
 		return {
 			error: {
@@ -525,11 +512,22 @@ function toErrorResponse(
 		};
 	}
 
+	// A masked internal error MUST NOT be advertised as retryable: without an
+	// explicit retryable:false the hub (bori provider-backed engine) defaults 5xx
+	// to retryable:true, which turns a deterministic pre-upstream crash into an
+	// infinite START->CONTINUE->restart loop (2026-07-22 catchtable reserve RCA).
+	// We still refuse to leak message/stack — only the error class name (or the
+	// primitive type for non-Error throwables) is surfaced for ops triage.
 	return {
 		error: {
 			code: "internal_error",
 			message: "Internal error",
 			...(requestId ? { requestId } : {}),
+			details: {
+				retryable: false,
+				category: "internal_error",
+				errorClass: error instanceof Error ? error.name : typeof error,
+			},
 		},
 	};
 }
@@ -557,7 +555,12 @@ function isPlainRecord(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-function providerObservabilityDetails(error: ProviderError):
+// Accepts `unknown` so the branded guards narrow cleanly from the top: the
+// subtype error classes are structurally compatible with ProviderError, so
+// narrowing from a ProviderError-typed value would collapse the negative branch
+// to `never`. Narrowing from unknown avoids that while still recognizing errors
+// from a duplicate SDK module instance.
+function providerObservabilityDetails(error: unknown):
 	| {
 			category: ProviderErrorCategory;
 			taxonomyVersion: string;
@@ -570,14 +573,26 @@ function providerObservabilityDetails(error: ProviderError):
 	// operation (see design.md §4.3 D3). Without this branch the auth error would
 	// serialize as a bare 401 with no retryable/category, losing the refresh
 	// signal for exactly the retryOnAuthRefresh operations it is meant to enable.
-	if (error instanceof SessionExpiredError) {
+	if (isSessionExpiredError(error)) {
 		return {
 			category: error.options?.category ?? "credential_expired",
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
 			retryable: error.options?.retryable ?? false,
 		};
 	}
-	if (!(error instanceof TransportError)) {
+	// Missing-secret errors carry the canonical credential_unavailable category
+	// so Gateway/observability can attribute the failure to provisioning, not
+	// the upstream. Matched by code (not constructor) so both the SDK-owned
+	// runtime gate and any not-yet-migrated provider-thrown MISSING_SECRET
+	// serialize identically, including across duplicate SDK module instances.
+	if (isProviderError(error) && error.code === MISSING_SECRET_CODE) {
+		return {
+			category: error.options?.category ?? "credential_unavailable",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: error.options?.retryable ?? false,
+		};
+	}
+	if (!isTransportError(error)) {
 		return undefined;
 	}
 	const isProxyPoolCode =
@@ -610,7 +625,7 @@ function providerObservabilityDetails(error: ProviderError):
 }
 
 function publicProviderErrorMessage(error: ProviderError): string {
-	if (error instanceof TransportError) {
+	if (isTransportError(error)) {
 		if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
 			return error.message;
 		}
@@ -633,22 +648,24 @@ function publicProviderErrorMessage(error: ProviderError): string {
 	return error.message;
 }
 
-function toStatusCode(
-	error: unknown,
-): 400 | 401 | 404 | 429 | 500 | 502 | 503 | 504 {
+function toStatusCode(error: unknown): 400 | 401 | 404 | 429 | 500 | 502 | 503 | 504 {
 	if (error instanceof z.ZodError) {
 		return 400;
 	}
 
-	if (error instanceof TransportError) {
+	if (isTransportError(error)) {
 		return error.code === "transport_timeout" ? 504 : 502;
 	}
 
-	if (error instanceof ProviderError) {
+	if (isProviderError(error)) {
 		switch (error.code) {
 			case "AUTH_REQUIRED":
 			case "reauth_required":
 				return 401;
+			// Unprovisioned declared secret: a deployment/config defect, never an
+			// upstream failure — explicit 400 (was only reached via fallthrough).
+			case MISSING_SECRET_CODE:
+				return 400;
 			case "NOT_FOUND":
 			case "not_found":
 			case "NO_DATA":
@@ -690,20 +707,15 @@ function logProviderError(
 	status: number,
 	cost: ProviderRequestCost,
 ): void {
-	const code =
-		error instanceof ProviderError
-			? (error.code ?? "provider_error")
-			: error instanceof z.ZodError
-				? "invalid_request"
-				: "internal_error";
+	const code = isProviderError(error)
+		? (error.code ?? "provider_error")
+		: error instanceof z.ZodError
+			? "invalid_request"
+			: "internal_error";
 	const errorClass = error instanceof Error ? error.name : typeof error;
 	const message = error instanceof Error ? error.message : String(error);
-	const details =
-		error instanceof ProviderError
-			? providerObservabilityDetails(error)
-			: undefined;
-	const emit =
-		typeof logger === "function" ? logger : defaultProviderServerLogger;
+	const details = isProviderError(error) ? providerObservabilityDetails(error) : undefined;
+	const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
 	emit({
 		level: status >= 500 ? "error" : "warn",
 		event: "provider_request_failed",
@@ -716,7 +728,7 @@ function logProviderError(
 		code,
 		errorClass,
 		message,
-		...(error instanceof TransportError && error.upstreamStatus
+		...(isTransportError(error) && error.upstreamStatus
 			? { upstreamStatus: error.upstreamStatus }
 			: {}),
 		...(details
@@ -738,8 +750,7 @@ function logProviderCleanupError(
 	resource: "browser" | "stealth",
 	error: unknown,
 ): void {
-	const emit =
-		typeof logger === "function" ? logger : defaultProviderServerLogger;
+	const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
 	const errorClass = error instanceof Error ? error.name : typeof error;
 	const message = error instanceof Error ? error.message : String(error);
 	emit({
@@ -764,8 +775,7 @@ function logProviderSuccess(
 	status: number,
 	cost: ProviderRequestCost,
 ): void {
-	const emit =
-		typeof logger === "function" ? logger : defaultProviderServerLogger;
+	const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
 	emit({
 		level: "info",
 		event: "provider_request_completed",
@@ -811,18 +821,13 @@ function toJsonSuccessResponse(
 	};
 }
 
-function isAsyncIterable<T = unknown>(
-	value: unknown,
-): value is AsyncIterable<T> {
+function isAsyncIterable<T = unknown>(value: unknown): value is AsyncIterable<T> {
 	if (!value || typeof value !== "object") return false;
 	const iterator = Reflect.get(value, Symbol.asyncIterator);
 	return typeof iterator === "function";
 }
 
-function responseWithCleanup(
-	response: Response,
-	cleanup: RequestCleanup,
-): Response {
+function responseWithCleanup(response: Response, cleanup: RequestCleanup): Response {
 	if (!response.body) {
 		void cleanup();
 		return response;
@@ -871,10 +876,7 @@ async function validateSseEvent(
 	const transport = getSseTransport(operation);
 	const schema = transport?.events?.[event.event];
 	if (!schema) {
-		if (
-			event.event === APIFUSE_STREAM_ERROR_EVENT ||
-			event.event === APIFUSE_STREAM_DONE_EVENT
-		) {
+		if (event.event === APIFUSE_STREAM_ERROR_EVENT || event.event === APIFUSE_STREAM_DONE_EVENT) {
 			return event;
 		}
 		throw new ProviderError(
@@ -887,11 +889,7 @@ async function validateSseEvent(
 			},
 		);
 	}
-	const data = await parseSchema(
-		schema,
-		event.data,
-		`transport.events.${event.event}`,
-	);
+	const data = await parseSchema(schema, event.data, `transport.events.${event.event}`);
 	return { ...event, data };
 }
 
@@ -911,8 +909,7 @@ function assertStreamPayloadWithinLimit(
 	throw new ProviderError(
 		`Stream ${kind} exceeded declared byte limit (${actualBytes} > ${maxBytes}).`,
 		{
-			code:
-				kind === "event" ? "STREAM_EVENT_TOO_LARGE" : "STREAM_CHUNK_TOO_LARGE",
+			code: kind === "event" ? "STREAM_EVENT_TOO_LARGE" : "STREAM_CHUNK_TOO_LARGE",
 			retryable: false,
 			category: "input_validation",
 			fix:
@@ -957,15 +954,10 @@ function toSseResponse(
 				const validated = await validateSseEvent(operation, next.value);
 				const encodedEvent = encodeSseEvent(validated);
 				const encodedBytes = encoder.encode(encodedEvent);
-				assertStreamPayloadWithinLimit(
-					encodedBytes.byteLength,
-					transport?.maxEventBytes,
-					"event",
-				);
+				assertStreamPayloadWithinLimit(encodedBytes.byteLength, transport?.maxEventBytes, "event");
 				controller.enqueue(encodedBytes);
 			} catch (error) {
-				const message =
-					error instanceof Error ? error.message : "Stream failed";
+				const message = error instanceof Error ? error.message : "Stream failed";
 				controller.enqueue(
 					encoder.encode(
 						encodeSseEvent(
@@ -1012,11 +1004,7 @@ function enforceStreamChunkLimit(
 					return;
 				}
 				if (value) {
-					assertStreamPayloadWithinLimit(
-						byteLength(value),
-						maxChunkBytes,
-						"chunk",
-					);
+					assertStreamPayloadWithinLimit(byteLength(value), maxChunkBytes, "chunk");
 					controller.enqueue(value);
 				}
 			} catch (error) {
@@ -1036,10 +1024,7 @@ function toStreamingResponse(
 	requestId?: string,
 ): Response {
 	const transport = operation.transport?.kind ?? "json";
-	if (
-		transport === "sse" &&
-		(result instanceof Response || result instanceof ReadableStream)
-	) {
+	if (transport === "sse" && (result instanceof Response || result instanceof ReadableStream)) {
 		void cleanup();
 		throw new ProviderError(
 			"SSE operations must return an AsyncIterable of typed stream.event(...) values.",
@@ -1053,20 +1038,13 @@ function toStreamingResponse(
 	}
 	if (result instanceof Response) {
 		const httpTransport = getHttpStreamTransport(operation);
-		if (
-			httpTransport &&
-			result.body &&
-			httpTransport?.maxChunkBytes !== undefined
-		) {
+		if (httpTransport && result.body && httpTransport?.maxChunkBytes !== undefined) {
 			return responseWithCleanup(
-				new Response(
-					enforceStreamChunkLimit(result.body, httpTransport.maxChunkBytes),
-					{
-						headers: result.headers,
-						status: result.status,
-						statusText: result.statusText,
-					},
-				),
+				new Response(enforceStreamChunkLimit(result.body, httpTransport.maxChunkBytes), {
+					headers: result.headers,
+					status: result.status,
+					statusText: result.statusText,
+				}),
 				cleanup,
 			);
 		}
@@ -1086,8 +1064,7 @@ function toStreamingResponse(
 						: {
 								"Content-Type":
 									operation.transport?.kind === "http-stream"
-										? (operation.transport.contentType ??
-											"application/octet-stream")
+										? (operation.transport.contentType ?? "application/octet-stream")
 										: "application/octet-stream",
 							},
 			}),
@@ -1107,18 +1084,14 @@ function toStreamingResponse(
 	);
 }
 
-function getSseTransport(
-	operation: OperationDefinition,
-): OperationSseTransport | undefined {
+function getSseTransport(operation: OperationDefinition): OperationSseTransport | undefined {
 	return operation.transport?.kind === "sse" ? operation.transport : undefined;
 }
 
 function getHttpStreamTransport(
 	operation: OperationDefinition,
 ): OperationHttpStreamTransport | undefined {
-	return operation.transport?.kind === "http-stream"
-		? operation.transport
-		: undefined;
+	return operation.transport?.kind === "http-stream" ? operation.transport : undefined;
 }
 
 function toAuthFlowResponse(
@@ -1139,9 +1112,7 @@ function toAuthFlowResponse(
 	};
 }
 
-function authFlowLocaleFromHeaders(
-	headers?: Record<string, string>,
-): ProviderLocale {
+function authFlowLocaleFromHeaders(headers?: Record<string, string>): ProviderLocale {
 	const header = Object.entries(headers ?? {}).find(
 		([key]) => key.toLowerCase() === "accept-language",
 	)?.[1];
@@ -1159,9 +1130,7 @@ function isAuthFlowLocale(value: string | undefined): value is ProviderLocale {
 }
 
 function isAuthTurn(value: unknown): value is AuthTurn {
-	return (
-		!!value && typeof value === "object" && "kind" in value && "turnId" in value
-	);
+	return !!value && typeof value === "object" && "kind" in value && "turnId" in value;
 }
 
 function loadAuthFlowLocaleCatalogs(
@@ -1198,10 +1167,7 @@ function materializeAuthFlowTurn(
 	});
 }
 
-function withAuthRequestHeaders(
-	request: AuthFlowRequest,
-	headers: Headers,
-): AuthFlowRequest {
+function withAuthRequestHeaders(request: AuthFlowRequest, headers: Headers): AuthFlowRequest {
 	return {
 		...request,
 		headers: {
@@ -1219,17 +1185,9 @@ async function handleOperation(
 	state: ProviderRuntimeState = createUnsupportedProviderRuntimeState(),
 	proxyTelemetry?: ProxyTelemetryCollector,
 ): Promise<Response | OperationResponse> {
-	const ctx = createProviderContext(
-		provider,
-		request,
-		operationId,
-		options,
-		state,
-		proxyTelemetry,
-	);
+	const ctx = createProviderContext(provider, request, operationId, options, state, proxyTelemetry);
 	const operation = provider.operations[operationId];
-	const streaming =
-		operation?.transport?.kind && operation.transport.kind !== "json";
+	const streaming = operation?.transport?.kind && operation.transport.kind !== "json";
 	let cleanupCalled = false;
 	const cleanup = async () => {
 		if (cleanupCalled) return;
@@ -1260,12 +1218,7 @@ async function handleOperation(
 		}
 	};
 	try {
-		const result = await executeOperation(
-			provider,
-			operationId,
-			ctx,
-			request.input,
-		);
+		const result = await executeOperation(provider, operationId, ctx, request.input);
 		if (streaming && operation) {
 			return toStreamingResponse(operation, result, cleanup, request.requestId);
 		}
@@ -1309,13 +1262,16 @@ async function handleAuthFlow(
 		});
 	}
 
-	const { context, getPatch } = createAuthFlowContext(
-		provider,
-		request,
-		options,
-		signal,
-	);
+	// Same SDK-owned gate as executeOperation: OAuth/credentials ceremonies
+	// depend on declared secrets (client ids/secrets), so fail structured before
+	// any flow code runs instead of at whatever point the ceremony first reads
+	// the env. `abort` stays exempt: a user must always be able to cancel a
+	// stranded flow even when provisioning is broken.
+	const { context, getPatch } = createAuthFlowContext(provider, request, options, signal);
 	try {
+		if (route !== "abort") {
+			assertRequiredSecretsPresent(provider, context.env);
+		}
 		const result =
 			route === "start"
 				? await flow.start(context)
@@ -1370,6 +1326,24 @@ export function createServerApp(
 			allowMemoryFallback: options.allowMemoryStateFallback === true,
 		});
 
+	// Boot-time visibility for unprovisioned declared secrets: emit a structured
+	// warn so deploy tooling/alerting sees the gap the moment the pod boots,
+	// instead of discovering it request-by-request. Deliberately log-only — a
+	// boot crash would trade a structured MISSING_SECRET signal for
+	// CrashLoopBackOff. Requests still fail closed via the executeOperation gate.
+	const missingSecretsAtBoot = listMissingRequiredSecrets(
+		provider,
+		createEnvContext(provider.secrets?.map((secret) => secret.name)),
+	);
+	if (missingSecretsAtBoot.length > 0) {
+		logger({
+			level: "warn",
+			event: "provider_secrets_missing",
+			providerId: provider.id,
+			missingSecrets: missingSecretsAtBoot,
+		});
+	}
+
 	app.notFound((c) =>
 		c.json(
 			{
@@ -1462,17 +1436,8 @@ export function createServerApp(
 				.clone()
 				.json()
 				.catch(() => undefined);
-			const body = withAuthRequestHeaders(
-				AuthFlowRequestSchema.parse(rawBody),
-				c.req.raw.headers,
-			);
-			const response = await handleAuthFlow(
-				provider,
-				body,
-				"start",
-				options,
-				c.req.raw.signal,
-			);
+			const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
+			const response = await handleAuthFlow(provider, body, "start", options, c.req.raw.signal);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1508,17 +1473,8 @@ export function createServerApp(
 				.clone()
 				.json()
 				.catch(() => undefined);
-			const body = withAuthRequestHeaders(
-				AuthFlowRequestSchema.parse(rawBody),
-				c.req.raw.headers,
-			);
-			const response = await handleAuthFlow(
-				provider,
-				body,
-				"continue",
-				options,
-				c.req.raw.signal,
-			);
+			const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
+			const response = await handleAuthFlow(provider, body, "continue", options, c.req.raw.signal);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1554,17 +1510,8 @@ export function createServerApp(
 				.clone()
 				.json()
 				.catch(() => undefined);
-			const body = withAuthRequestHeaders(
-				AuthFlowRequestSchema.parse(rawBody),
-				c.req.raw.headers,
-			);
-			const response = await handleAuthFlow(
-				provider,
-				body,
-				"poll",
-				options,
-				c.req.raw.signal,
-			);
+			const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
+			const response = await handleAuthFlow(provider, body, "poll", options, c.req.raw.signal);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1600,17 +1547,8 @@ export function createServerApp(
 				.clone()
 				.json()
 				.catch(() => undefined);
-			const body = withAuthRequestHeaders(
-				AuthFlowRequestSchema.parse(rawBody),
-				c.req.raw.headers,
-			);
-			const response = await handleAuthFlow(
-				provider,
-				body,
-				"refresh",
-				options,
-				c.req.raw.signal,
-			);
+			const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
+			const response = await handleAuthFlow(provider, body, "refresh", options, c.req.raw.signal);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1646,17 +1584,8 @@ export function createServerApp(
 				.clone()
 				.json()
 				.catch(() => undefined);
-			const body = withAuthRequestHeaders(
-				AuthFlowRequestSchema.parse(rawBody),
-				c.req.raw.headers,
-			);
-			const response = await handleAuthFlow(
-				provider,
-				body,
-				"abort",
-				options,
-				c.req.raw.signal,
-			);
+			const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
+			const response = await handleAuthFlow(provider, body, "abort", options, c.req.raw.signal);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1731,12 +1660,9 @@ export async function serve(
 	const bunRuntime = getBunServeRuntime();
 
 	if (bunRuntime === undefined) {
-		throw new ProviderError(
-			"Bun runtime is required to start the provider server",
-			{
-				code: "RUNTIME_UNSUPPORTED",
-			},
-		);
+		throw new ProviderError("Bun runtime is required to start the provider server", {
+			code: "RUNTIME_UNSUPPORTED",
+		});
 	}
 
 	const app = createServerApp(provider, {
@@ -1758,6 +1684,7 @@ export async function serve(
 		const selfTestApp = createSelfTestApp(provider, {
 			secrets: selfTestSecrets,
 			invoke: createSelfTestInvoke(app),
+			authFlow: createSelfTestAuthFlowInvoke(app),
 		});
 		bunRuntime.serve({
 			port: options.selfTestPort ?? resolveSelfTestPort(),