@apifuse/provider-sdk 2.2.0-beta.20 → 2.2.0-beta.22

package/src/ceremonies/index.ts

@@ -26,6 +26,15 @@ const validateAuthTurn = ajv.compile(AUTH_TURN_SCHEMA);
 
 const OAUTH2_STATE_KEY = "__oauth2_state";
 const OAUTH2_PKCE_VERIFIER_KEY = "__oauth2_pkce_verifier";
+export const OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY = "APIFUSE__AUTH_PROXY__URL";
+export const OAUTH2_PROXIED_PKCE_VERIFIER_KEY = "__oauth2_proxied_pkce_verifier";
+const OAUTH2_PROXIED_RESERVED_AUTHORIZE_PARAMS = new Set([
+	"client_id",
+	"response_type",
+	"state",
+	"code_challenge",
+	"code_challenge_method",
+]);
 const DEVICE_FLOW_KEY = "__device_flow";
 const MAGIC_LINK_KEY = "__magic_link";
 const COMBINED_STAGE_KEY = "__combined_stage";
@@ -248,6 +257,76 @@ export function createOAuth2Ceremony(options: {
 	};
 }
 
+/**
+ * Builds the start handler for a custom-scheme OAuth provider. The shared
+ * auth-proxy owns state minting and callback capture, while the provider owns
+ * token exchange and any following authentication turns.
+ */
+export function createOAuth2ProxiedStart(
+	options: import("../types.js").ProxiedOAuthConfig,
+): import("../types.js").AuthFlowStartHandler {
+	const pkce = options.pkce ?? "S256";
+
+	return (ctx) =>
+		runCeremonyHandler(
+			async () => {
+				for (const key of Object.keys(options.authorizeParams ?? {})) {
+					if (OAUTH2_PROXIED_RESERVED_AUTHORIZE_PARAMS.has(key.toLowerCase())) {
+						throw new ValidationError(
+							`OAuth2 proxied authorizeParams cannot override reserved parameter "${key}".`,
+						);
+					}
+				}
+				const proxyOrigin = ctx.env.get(OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY);
+				if (!proxyOrigin) {
+					throw new ProviderSecretError(
+						`Missing required platform environment: ${OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY}`,
+					);
+				}
+				const clientId = getRequiredEnv(ctx, options.clientIdEnvKey);
+				if (!ctx.flowId) {
+					throw new ValidationError(
+						"OAuth2 proxied start requires the gateway flow id.",
+					);
+				}
+
+				const authorizePath = new URL(options.authorizeUrl).pathname;
+				const url = new URL(
+					`/p/${encodeURIComponent(ctx.providerId)}/f/${encodeURIComponent(ctx.flowId)}${authorizePath}`,
+					proxyOrigin,
+				);
+				url.searchParams.set("client_id", clientId);
+				url.searchParams.set("response_type", "code");
+
+				if (pkce === "S256") {
+					const verifier = createCodeVerifier();
+					ctx.context.set(OAUTH2_PROXIED_PKCE_VERIFIER_KEY, verifier);
+					url.searchParams.set("code_challenge", createCodeChallenge(verifier));
+					url.searchParams.set("code_challenge_method", "S256");
+				}
+
+				for (const [key, value] of Object.entries(options.authorizeParams ?? {})) {
+					url.searchParams.set(key, value);
+				}
+
+				return createTurn("redirect", {
+					data: { url: url.toString() },
+					hint: "Open the provider authorization page to continue.",
+					expectedInput: {
+						type: "object",
+						required: ["code", "state"],
+						properties: {
+							code: { type: "string" },
+							state: { type: "string" },
+						},
+					},
+				});
+			},
+			"OAuth2 proxied start failed",
+			ctx,
+		);
+}
+
 export function createDeviceFlowCeremony(options: {
 	deviceCodeUrl: string;
 	tokenUrl: string;

package/src/define.ts

@@ -84,7 +84,36 @@ interface ProviderImplementationProfile {
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
 const OPERATION_ID_REGEX = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
 const VALID_RUNTIMES = ["standard", "shared", "browser"] as const;
-const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"] as const;
+const VALID_AUTH_MODES = [
+	"none",
+	"platform-managed",
+	"credentials",
+	"oauth2",
+	"oauth2_proxied",
+] as const;
+const PROXIED_OAUTH_REQUIRED_FIELDS = [
+	"authorizeUrl",
+	"tokenUrl",
+	"customScheme",
+	"rewriteProfile",
+	"clientIdEnvKey",
+] as const;
+const PROXIED_OAUTH_ALLOWED_FIELDS = new Set([
+	...PROXIED_OAUTH_REQUIRED_FIELDS,
+	"pkce",
+	"authorizeParams",
+	"tokenParams",
+]);
+const PROXIED_OAUTH_RESERVED_AUTHORIZE_PARAMS = new Set([
+	"client_id",
+	"response_type",
+	"state",
+	"code_challenge",
+	"code_challenge_method",
+]);
+const PROXIED_OAUTH_PROFILE_REGEX = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const PROXIED_OAUTH_ENV_KEY_REGEX = /^[A-Z][A-Z0-9_]*__[A-Z0-9_]+$/;
+const CUSTOM_SCHEME_REGEX = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/\S+$/;
 const VALID_PROVIDER_ACCESS_VISIBILITIES = ["public", "early_access"] as const;
 const VALID_PROVIDER_PROXY_MODES = ["disabled", "optional", "required"] as const;
 const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "nodemaven", "decodo", "custom"] as const;
@@ -303,6 +332,111 @@ function assertLiteralField<TValue extends string>(
 		);
 	}
 }
+
+function validateProxiedOAuthParams(
+	value: unknown,
+	field: "authorizeParams" | "tokenParams",
+	providerId: string,
+): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.${field} must be an object of string values.`,
+		);
+	}
+	for (const [key, paramValue] of Object.entries(value)) {
+		if (!key.trim() || typeof paramValue !== "string") {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied.${field} must contain non-empty keys and string values.`,
+			);
+		}
+		if (
+			field === "authorizeParams" &&
+			PROXIED_OAUTH_RESERVED_AUTHORIZE_PARAMS.has(key.toLowerCase())
+		) {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied.authorizeParams cannot override reserved parameter "${key}".`,
+			);
+		}
+	}
+}
+
+function validateProxiedOAuthAuth(auth: Record<string, unknown>, providerId: string): void {
+	const proxied = auth.proxied;
+	if (auth.mode !== "oauth2_proxied") {
+		if (proxied !== undefined) {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied is only valid when auth.mode is "oauth2_proxied".`,
+			);
+		}
+		return;
+	}
+	if (!proxied || typeof proxied !== "object" || Array.isArray(proxied)) {
+		throw new ValidationError(
+			`Provider "${providerId}" with auth.mode "oauth2_proxied" must declare auth.proxied.`,
+		);
+	}
+	const config = Object.fromEntries(Object.entries(proxied));
+	for (const key of Object.keys(config)) {
+		if (!PROXIED_OAUTH_ALLOWED_FIELDS.has(key)) {
+			throw new ValidationError(
+				`Provider "${providerId}" has unknown auth.proxied field "${key}".`,
+			);
+		}
+	}
+	for (const field of PROXIED_OAUTH_REQUIRED_FIELDS) {
+		if (typeof config[field] !== "string" || !config[field].trim()) {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied.${field} must be a non-empty string.`,
+			);
+		}
+	}
+	for (const field of ["authorizeUrl", "tokenUrl"] as const) {
+		try {
+			const endpoint = new URL(String(config[field]));
+			if (
+				endpoint.protocol !== "https:" ||
+				endpoint.username ||
+				endpoint.password ||
+				endpoint.hash
+			) {
+				throw new Error("invalid endpoint");
+			}
+		} catch {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied.${field} must be an absolute HTTPS URL without credentials or a fragment.`,
+			);
+		}
+	}
+	const customScheme = String(config.customScheme);
+	if (
+		!CUSTOM_SCHEME_REGEX.test(customScheme) ||
+		customScheme.toLowerCase().startsWith("http://") ||
+		customScheme.toLowerCase().startsWith("https://")
+	) {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.customScheme must be a non-HTTP custom-scheme URL prefix.`,
+		);
+	}
+	if (!PROXIED_OAUTH_PROFILE_REGEX.test(String(config.rewriteProfile))) {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.rewriteProfile must be a kebab-case profile name.`,
+		);
+	}
+	if (!PROXIED_OAUTH_ENV_KEY_REGEX.test(String(config.clientIdEnvKey))) {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.clientIdEnvKey must be an APIFuse-style uppercase environment key.`,
+		);
+	}
+	if (config.pkce !== undefined && config.pkce !== "S256" && config.pkce !== "none") {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.pkce must be "S256" or "none".`,
+		);
+	}
+	validateProxiedOAuthParams(config.authorizeParams, "authorizeParams", providerId);
+	validateProxiedOAuthParams(config.tokenParams, "tokenParams", providerId);
+}
+
 function validateProviderShape(config: unknown): void {
 	assertObjectConfig(config);
 	assertRequiredField(config, "id");
@@ -315,6 +449,9 @@ function validateProviderShape(config: unknown): void {
 	const auth = config.auth;
 	if (auth && typeof auth === "object" && "mode" in auth && typeof auth.mode === "string")
 		assertLiteralField(auth.mode, "auth.mode", VALID_AUTH_MODES, String(config.id));
+	if (auth && typeof auth === "object" && !Array.isArray(auth)) {
+		validateProxiedOAuthAuth(Object.fromEntries(Object.entries(auth)), String(config.id));
+	}
 	if (auth && typeof auth === "object" && "exchange" in auth) {
 		throw new ProviderError(
 			`Provider "${String(config.id)}" auth.exchange is not part of the Provider SDK auth contract`,

package/src/error-resolution.ts

@@ -1,3 +1,5 @@
+import type { ProviderErrorStatus } from "./types.js";
+
 // This set suppresses the unregistered-provider-error-code signal for codes
 // intentionally emitted by SDK paths. It is not the complete authority for
 // runtime error resolution: branded errors and additional canonical SDK codes
@@ -89,3 +91,32 @@ export const SDK_RUNTIME_OWNED_ERROR_CODES = new Set([
 	"NOT_FOUND",
 	"not_found",
 ]);
+
+// Canonical SDK status mapping for recognized provider-thrown error codes.
+// serve.ts toStatusCode consults this map (after operation-declared overrides
+// for non-SDK-owned codes), and the authoring lint treats these codes as
+// SDK-registered. Add new codes here instead of duplicating literals in
+// either consumer.
+export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, ProviderErrorStatus> =
+	new Map<string, ProviderErrorStatus>([
+		["AUTH_REQUIRED", 401],
+		["reauth_required", 401],
+		// Unprovisioned declared secret: a deployment/config defect, never an
+		// upstream failure — explicit 400.
+		["MISSING_SECRET", 400],
+		["NOT_FOUND", 404],
+		["not_found", 404],
+		["NO_DATA", 404],
+		["RATE_LIMITED", 429],
+		["UPSTREAM_RATE_LIMIT", 429],
+		["LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR", 429],
+		// Deterministic upstream business refusal (honest-provider-error-
+		// contract): the upstream evaluated the request and said no under its
+		// own rules — a conflict with upstream state, never a 5xx.
+		["UPSTREAM_REJECTED", 409],
+		["UPSTREAM_ERROR", 502],
+		["BLOCKED", 502],
+		["STT_UNAVAILABLE", 503],
+		["UNSUPPORTED_STT_BACKEND", 503],
+		["STATEFUL_FORWARDING_REPLAY_CACHE_FULL", 503],
+	]);

package/src/index.ts

@@ -277,6 +277,7 @@ export type {
 	ProviderProxyConfig,
 	ProviderProxyMode,
 	ProviderProxyPolicy,
+	ProxiedOAuthConfig,
 	ProviderProxyProvider,
 	ProviderProxySessionAffinity,
 	ProviderPublicConnectionMode,

package/src/lint.ts

@@ -1,9 +1,19 @@
 import type { ZodType } from "zod";
 
+import {
+	SDK_RUNTIME_OWNED_ERROR_CODES,
+	SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES,
+} from "./error-resolution.js";
 import { lintPublicSchemaFieldNames } from "./public-schema-field-lint.js";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_SENSITIVE_META_KEY } from "./schema.js";
 
-type AuthModeLike = "none" | "platform-managed" | "credentials" | "oauth2" | "api-key";
+type AuthModeLike =
+	| "none"
+	| "platform-managed"
+	| "credentials"
+	| "oauth2"
+	| "oauth2_proxied"
+	| "api-key";
 
 type ProviderAuthLike = {
 	mode?: AuthModeLike;
@@ -793,6 +803,303 @@ function lintSelfHostedBrowserPatterns(
 	return diagnostics;
 }
 
+const THROWN_ERROR_CONSTRUCTION_PATTERN = /new\s+(?:ProviderError|ValidationError)\s*\(/g;
+
+const TEST_SOURCE_FILE_PATTERN = /(?:^|\/)(?:__tests__|__mocks__)\/|\.(?:test|spec)\.[cm]?[jt]sx?$/;
+
+/**
+ * Skips a string literal starting at `startIndex` (which must point at the
+ * opening quote). Returns the index of the closing quote, or -1 when the
+ * literal is unterminated. Template literals handle nested `${...}`
+ * expressions, including strings inside them.
+ */
+function skipStringLiteral(source: string, startIndex: number): number {
+	const quote = source[startIndex];
+	for (let index = startIndex + 1; index < source.length; index++) {
+		const char = source[index];
+		if (char === "\\") {
+			index++;
+			continue;
+		}
+		if (quote === "`" && char === "$" && source[index + 1] === "{") {
+			index = skipTemplateExpression(source, index + 2);
+			if (index < 0) {
+				return -1;
+			}
+			continue;
+		}
+		if (char === quote) {
+			return index;
+		}
+		if (quote !== "`" && char === "\n") {
+			return -1;
+		}
+	}
+	return -1;
+}
+
+function skipTemplateExpression(source: string, startIndex: number): number {
+	let depth = 1;
+	for (let index = startIndex; index < source.length; index++) {
+		const char = source[index];
+		if (char === '"' || char === "'" || char === "`") {
+			index = skipStringLiteral(source, index);
+			if (index < 0) {
+				return -1;
+			}
+			continue;
+		}
+		if (char === "{") {
+			depth++;
+		} else if (char === "}") {
+			depth--;
+			if (depth === 0) {
+				return index;
+			}
+		}
+	}
+	return -1;
+}
+
+/**
+ * Extracts the argument text of a call whose opening paren has already been
+ * consumed (`startIndex` points just past it). Returns undefined when the
+ * call never closes in this source, which the caller treats as "skip
+ * silently" — this scanner is conservative by design.
+ */
+function extractBalancedCallArguments(source: string, startIndex: number): string | undefined {
+	let depth = 1;
+	for (let index = startIndex; index < source.length; index++) {
+		const char = source[index];
+		if (char === '"' || char === "'" || char === "`") {
+			index = skipStringLiteral(source, index);
+			if (index < 0) {
+				return undefined;
+			}
+			continue;
+		}
+		if (char === "/" && source[index + 1] === "/") {
+			const newline = source.indexOf("\n", index);
+			if (newline === -1) {
+				return undefined;
+			}
+			index = newline;
+			continue;
+		}
+		if (char === "/" && source[index + 1] === "*") {
+			const end = source.indexOf("*/", index + 2);
+			if (end === -1) {
+				return undefined;
+			}
+			index = end + 1;
+			continue;
+		}
+		if (char === "(") {
+			depth++;
+		} else if (char === ")") {
+			depth--;
+			if (depth === 0) {
+				return source.slice(startIndex, index);
+			}
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Collects literal string values of top-level `code:` properties inside a
+ * ProviderError/ValidationError options object. Only plain `"..."` / `'...'`
+ * literals at options-object depth count; computed codes (identifiers,
+ * ternaries, template substitutions, concatenations, escapes) are skipped
+ * silently so the rule never guesses.
+ */
+function collectLiteralErrorCodeValues(args: string): string[] {
+	const codes: string[] = [];
+	let braceDepth = 0;
+	let parenDepth = 0;
+	let bracketDepth = 0;
+	let previousSignificantChar = "";
+	for (let index = 0; index < args.length; index++) {
+		const char = args[index] ?? "";
+		if (char === '"' || char === "'" || char === "`") {
+			const end = skipStringLiteral(args, index);
+			if (end < 0) {
+				return codes;
+			}
+			index = end;
+			previousSignificantChar = char;
+			continue;
+		}
+		if (char === "/" && args[index + 1] === "/") {
+			const newline = args.indexOf("\n", index);
+			if (newline === -1) {
+				return codes;
+			}
+			index = newline;
+			continue;
+		}
+		if (char === "/" && args[index + 1] === "*") {
+			const end = args.indexOf("*/", index + 2);
+			if (end === -1) {
+				return codes;
+			}
+			index = end + 1;
+			continue;
+		}
+		if (/\s/.test(char)) {
+			continue;
+		}
+		if (char === "{") {
+			braceDepth++;
+		} else if (char === "}") {
+			braceDepth--;
+		} else if (char === "(") {
+			parenDepth++;
+		} else if (char === ")") {
+			parenDepth--;
+		} else if (char === "[") {
+			bracketDepth++;
+		} else if (char === "]") {
+			bracketDepth--;
+		} else if (
+			braceDepth === 1 &&
+			parenDepth === 0 &&
+			bracketDepth === 0 &&
+			(previousSignificantChar === "{" || previousSignificantChar === ",") &&
+			args.startsWith("code", index)
+		) {
+			let cursor = index + "code".length;
+			while (cursor < args.length && /\s/.test(args[cursor] ?? "")) {
+				cursor++;
+			}
+			if (args[cursor] === ":") {
+				cursor++;
+				while (cursor < args.length && /\s/.test(args[cursor] ?? "")) {
+					cursor++;
+				}
+				const quote = args[cursor];
+				if (quote === '"' || quote === "'") {
+					const end = skipStringLiteral(args, cursor);
+					if (end > cursor) {
+						const value = args.slice(cursor + 1, end);
+						let after = end + 1;
+						while (after < args.length && /\s/.test(args[after] ?? "")) {
+							after++;
+						}
+						const nextChar = after < args.length ? (args[after] ?? "") : "";
+						if (!value.includes("\\") && (nextChar === "," || nextChar === "}" || nextChar === "")) {
+							codes.push(value);
+						}
+						index = end;
+						previousSignificantChar = quote;
+						continue;
+					}
+					return codes;
+				}
+			}
+		}
+		previousSignificantChar = char;
+	}
+	return codes;
+}
+
+function collectLiteralThrownErrorCodes(source: string): string[] {
+	const codes: string[] = [];
+	THROWN_ERROR_CONSTRUCTION_PATTERN.lastIndex = 0;
+	for (
+		let match = THROWN_ERROR_CONSTRUCTION_PATTERN.exec(source);
+		match;
+		match = THROWN_ERROR_CONSTRUCTION_PATTERN.exec(source)
+	) {
+		const argsStart = match.index + match[0].length;
+		const args = extractBalancedCallArguments(source, argsStart);
+		if (args !== undefined) {
+			codes.push(...collectLiteralErrorCodeValues(args));
+		}
+		THROWN_ERROR_CONSTRUCTION_PATTERN.lastIndex = argsStart;
+	}
+	return codes;
+}
+
+/**
+ * Static counterpart of the runtime `unregistered_provider_error_code`
+ * signal (honest-provider-error-contract Phase 3.5.5): flags
+ * `new ProviderError(...)` / `new ValidationError(...)` constructions whose
+ * literal `code` is neither SDK-registered (SDK_RUNTIME_OWNED_ERROR_CODES
+ * plus the canonical status-mapped codes shared with serve.ts toStatusCode)
+ * nor declared in any operation's docs.errorCodes. At runtime such a code
+ * serves HTTP 500 and emits the signal; this rule surfaces it at check time.
+ *
+ * A throw site cannot be attributed to a specific operation statically —
+ * providers routinely throw from helpers shared across operations — so this
+ * rule matches against the provider-level union of declared codes. That is
+ * the honest scope: it will not catch a code declared only on the "wrong"
+ * operation, and it never claims per-operation attribution it cannot prove.
+ * Only literal string codes are checked; computed/dynamic codes and test
+ * sources are skipped silently. Warning level: the long tail of existing
+ * providers converges gradually, so this must not fail `apifuse check`.
+ */
+function lintUndeclaredThrownErrorCodes(provider: {
+	authFlowSource?: string;
+	providerSourceFiles?: Record<string, string>;
+	operations?: Record<
+		string,
+		{
+			handler?: unknown;
+			source?: string;
+			docs?: { errorCodes?: ReadonlyArray<{ code: string }> };
+		}
+	>;
+}): LintDiagnostic[] {
+	const knownCodes = new Set<string>([
+		...SDK_RUNTIME_OWNED_ERROR_CODES,
+		...SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.keys(),
+	]);
+	for (const operation of Object.values(provider.operations ?? {})) {
+		for (const entry of operation.docs?.errorCodes ?? []) {
+			if (typeof entry?.code === "string") {
+				knownCodes.add(entry.code);
+			}
+		}
+	}
+
+	const sources: Array<{ field: string; source: string }> = [];
+	const sourceFiles = Object.entries(provider.providerSourceFiles ?? {}).filter(
+		([filePath]) => !TEST_SOURCE_FILE_PATTERN.test(filePath),
+	);
+	if (sourceFiles.length > 0) {
+		for (const [filePath, source] of sourceFiles) {
+			sources.push({ field: `sourceFiles.${filePath}`, source });
+		}
+	} else {
+		if (provider.authFlowSource) {
+			sources.push({ field: "auth.flow", source: provider.authFlowSource });
+		}
+		for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
+			const source = getOperationSource(operation);
+			if (source) {
+				sources.push({ field: `operations.${operationKey}.handler`, source });
+			}
+		}
+	}
+
+	const diagnostics: LintDiagnostic[] = [];
+	for (const { field, source } of sources) {
+		const undeclaredCodes = new Set(
+			collectLiteralThrownErrorCodes(source).filter((code) => !knownCodes.has(code)),
+		);
+		for (const code of undeclaredCodes) {
+			diagnostics.push({
+				rule: "thrown-error-code-undeclared",
+				level: "warn",
+				field,
+				message: `Thrown error code "${code}" (${field}) is neither SDK-registered nor declared in any operation's docs.errorCodes; at runtime it serves HTTP 500 and emits the unregistered_provider_error_code signal. Declare it in the owning operation's docs.errorCodes with status and retryable.`,
+			});
+		}
+	}
+	return diagnostics;
+}
+
 export function lintOperation(op: {
 	description?: string;
 	descriptionKey?: string;
@@ -935,6 +1242,7 @@ export function lintProvider(
 				derivations?: Record<string, string>;
 				handler?: unknown;
 				source?: string;
+				docs?: { errorCodes?: ReadonlyArray<{ code: string }> };
 			}
 		>;
 		meta?: {
@@ -952,6 +1260,7 @@ export function lintProvider(
 		...lintCredentialWriteUsage(provider),
 		...lintPlaywrightDirectImports(provider),
 		...lintSelfHostedBrowserPatterns(provider, options),
+		...lintUndeclaredThrownErrorCodes(provider),
 	];
 
 	if (provider.operations) {

package/src/provider.ts

@@ -148,6 +148,7 @@ export type {
 	ProviderLocaleKeyInput,
 	ProviderLogoProfile,
 	ProviderProxyPolicy,
+	ProxiedOAuthConfig,
 	ProviderPublicConnectionMode,
 	ProviderPublicProfile,
 	ProviderResolvedFile,

package/src/runtime/auth-flow.ts

@@ -48,6 +48,7 @@ export function createScratchpad(
 }
 
 export function createFlowContext(options: {
+	flowId?: string;
 	http: HttpClient;
 	stealth: StealthClient;
 	env: EnvContext;
@@ -60,6 +61,7 @@ export function createFlowContext(options: {
 	stt?: SttContext;
 }): FlowContext {
 	return {
+		flowId: options.flowId,
 		connectionId: options.connectionId,
 		externalRef: options.externalRef,
 		tenantId: options.tenantId,