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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.22
+
+- Release candidate for main commit b8bf920b5ca053d1bf43018167fd4eedff01700d.
+
+## Unreleased
+
+- Added the `thrown-error-code-undeclared` authoring lint (warning level): `apifuse check` now statically flags literal `ProviderError`/`ValidationError` codes that are neither SDK-registered nor declared in any operation's `docs.errorCodes`, surfacing the runtime `unregistered_provider_error_code` signal at check time. The canonical SDK code→status mapping moved to `SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES` in `error-resolution.ts`, shared by the runtime status resolver and the lint.
+
+## 2.2.0-beta.21
+
+- Release candidate for main commit 00f61024fb18db39711dc5076c4621508baa49f5.
+
 ## 2.2.0-beta.20
 
 - Release candidate for main commit 8043d2ef0047e431aace750d8abca2e1149ec1d6.
@@ -110,6 +122,7 @@
 
 ## Unreleased
 
+- Upstream the platform monorepo's beta.16 dist patch: OAuth2-proxied auth ceremony (`createOAuth2ProxiedStart`, `OAUTH2_PROXIED_PKCE_VERIFIER_KEY`, `APIFUSE__AUTH_PROXY__URL` origin key, proxied redirect/callback turns) and the provider runtime state upgrades it depends on (in-memory compareAndSet with quota-aware write policy, Redis CAS/set Lua scripts with entry quotas and legacy index migration). The monorepo drops `patchedDependencies` once it pins this release.
 - **honest-provider-error-contract (phase 2):** `UPSTREAM_REJECTED` is a registered code family serving HTTP 409 with `retryable: false` — deterministic upstream business refusals are no longer 502s. Operation-declared `docs.errorCodes` may now use 409/410/422. Public error envelopes carry a `source` field (`client` | `upstream_rule` | `upstream_failure` | `apifuse`) derived from the observability category. Taxonomy version bumps to `2026-08-07` with the `upstream_rejected`, `dependency_unavailable`, `unsupported_transport`, and `client_cancelled` categories (409/410/422 map to `upstream_rejected`), matching the platform monorepo SoT. The `unregistered_provider_error_code` signal now carries a `signalFix` pointing at `docs.errorCodes` declaration.
 - **Breaking for custom native gateway adapters:** `NativeGatewayProxySynthesisInput` now includes an injected `credentials` resolver and selected `protocol`; synthesizers may return promises and structured skip reasons, and `resolveNativeGatewayProxy` is async. Default callers retain env-backed behavior. Native transport now supports both HTTP CONNECT and SOCKS5, defaults per vendor with an explicit runtime override, registers smartproxy allocation ahead of nodemaven when declared in that order, and reports every exhausted vendor reason without exposing proxy credentials.
 - Honor operation `docs.errorCodes` at runtime: declared provider-owned statuses and retryability now drive the HTTP envelope, observability header, and structured log; invalid statuses fail `defineProvider`, declared codes no longer emit the unregistered-code signal, and `TransportError` status-preservation workarounds are obsolete.

package/dist/ceremonies/index.d.ts

@@ -1,5 +1,7 @@
 import type { AuthFlowDefinition, AuthTurn } from "../types.js";
 type JsonObject = Record<string, unknown>;
+export declare const OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY = "APIFUSE__AUTH_PROXY__URL";
+export declare const OAUTH2_PROXIED_PKCE_VERIFIER_KEY = "__oauth2_proxied_pkce_verifier";
 export declare function validateCeremonyOutput(turn: unknown): AuthTurn;
 export declare function createOAuth2Ceremony(options: {
     authorizeUrl: string;
@@ -9,6 +11,12 @@ export declare function createOAuth2Ceremony(options: {
     scopes: string[];
     usePKCE?: boolean;
 }): AuthFlowDefinition;
+/**
+ * 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 declare function createOAuth2ProxiedStart(options: import("../types.js").ProxiedOAuthConfig): import("../types.js").AuthFlowStartHandler;
 export declare function createDeviceFlowCeremony(options: {
     deviceCodeUrl: string;
     tokenUrl: string;

package/dist/ceremonies/index.js

@@ -9,6 +9,15 @@ const ajv = new Ajv2020({ allErrors: true, strict: true, strictSchema: true });
 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";
@@ -173,6 +182,54 @@ export function createOAuth2Ceremony(options) {
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "OAuth flow aborted." })),
     };
 }
+/**
+ * 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) {
+    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) {
     return {
         start: (ctx) => runCeremonyHandler(async () => {

package/dist/define.js

@@ -8,7 +8,36 @@ import { HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX, HEALTH_CHECK_DEGRADED_THRESHOLD
 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"];
-const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"];
+const VALID_AUTH_MODES = [
+    "none",
+    "platform-managed",
+    "credentials",
+    "oauth2",
+    "oauth2_proxied",
+];
+const PROXIED_OAUTH_REQUIRED_FIELDS = [
+    "authorizeUrl",
+    "tokenUrl",
+    "customScheme",
+    "rewriteProfile",
+    "clientIdEnvKey",
+];
+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"];
 const VALID_PROVIDER_PROXY_MODES = ["disabled", "optional", "required"];
 const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "nodemaven", "decodo", "custom"];
@@ -89,6 +118,76 @@ function assertLiteralField(value, field, validValues, providerId) {
         });
     }
 }
+function validateProxiedOAuthParams(value, field, providerId) {
+    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, providerId) {
+    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"]) {
+        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) {
     assertObjectConfig(config);
     assertRequiredField(config, "id");
@@ -101,6 +200,9 @@ function validateProviderShape(config) {
     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`, {
             fix: "Use the single canonical auth interface: auth.flow. Gateway calls auth.flow.start/continue/poll/abort/refresh only and persists complete turn data.credential as-is, so put login/token/session exchange inside auth.flow.continue.",

package/dist/error-resolution.d.ts

@@ -1,2 +1,4 @@
+import type { ProviderErrorStatus } from "./types.js";
 export declare const SDK_OWNED_PROVIDER_ERROR_CODES: Set<string>;
 export declare const SDK_RUNTIME_OWNED_ERROR_CODES: Set<string>;
+export declare const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, ProviderErrorStatus>;

package/dist/error-resolution.js

@@ -88,3 +88,30 @@ 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 = new Map([
+    ["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/dist/index.d.ts

@@ -38,7 +38,7 @@ export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SEN
 export { createServerApp, ERROR_OBSERVABILITY_HEADER, type ServeOptions, serve, } from "./server/index.js";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
 export * from "./stream.js";
-export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
+export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
 export { DEFAULT_OPERATION_TRANSPORT, HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, PROBE_INTERVALS, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
 export * from "./utils/date.js";
 export * from "./utils/parse.js";

package/dist/lint.d.ts

@@ -1,4 +1,4 @@
-type AuthModeLike = "none" | "platform-managed" | "credentials" | "oauth2" | "api-key";
+type AuthModeLike = "none" | "platform-managed" | "credentials" | "oauth2" | "oauth2_proxied" | "api-key";
 type ProviderAuthLike = {
     mode?: AuthModeLike;
     flow?: {
@@ -65,6 +65,11 @@ export declare function lintProvider(provider: {
         derivations?: Record<string, string>;
         handler?: unknown;
         source?: string;
+        docs?: {
+            errorCodes?: ReadonlyArray<{
+                code: string;
+            }>;
+        };
     }>;
     meta?: {
         contract?: ProviderContractMetaLike;

package/dist/lint.js

@@ -1,3 +1,4 @@
+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";
 const AUTH_OPERATION_ID_PATTERN = /^(?:auth[-_])?(?:login|exchange|continue|refresh|callback)(?:[-_]|$)/i;
@@ -587,6 +588,281 @@ function lintSelfHostedBrowserPatterns(provider, options) {
     }
     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, startIndex) {
+    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, startIndex) {
+    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, startIndex) {
+    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) {
+    const codes = [];
+    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) {
+    const codes = [];
+    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) {
+    const knownCodes = new Set([
+        ...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 = [];
+    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 = [];
+    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) {
     const diagnostics = [];
     const description = op.description ?? "";
@@ -677,6 +953,7 @@ export function lintProvider(provider, options = {}) {
         ...lintCredentialWriteUsage(provider),
         ...lintPlaywrightDirectImports(provider),
         ...lintSelfHostedBrowserPatterns(provider, options),
+        ...lintUndeclaredThrownErrorCodes(provider),
     ];
     if (provider.operations) {
         const authMode = provider.auth?.mode;

package/dist/provider.d.ts

@@ -7,6 +7,6 @@ export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, i
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, z, } from "./schema.js";
-export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, } from "./types.js";
+export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, } from "./types.js";
 export { createNativeNetworkClient, createEnvVendorCredentialResolver, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, type NativeGatewayProxy, type NativeGatewayProxyResolutionInput, type NativeGatewayProxySkipReason, type NativeGatewayProxySynthesizer, type NativeGatewayProxySynthesisResult, type NativeGatewayProxySynthesisInput, type NativeNetworkClientOptions, type NativeNetworkErrorCode, type VendorCredentialLookup, type VendorCredentialResolver, } from "./runtime/native-network.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/runtime/auth-flow.d.ts

@@ -1,6 +1,7 @@
 import type { ContextScratchpad, EnvContext, FlowContext, HttpClient, StealthClient, SttContext } from "../types.js";
 export declare function createScratchpad(allowedKeys: string[], initial?: Record<string, unknown>): ContextScratchpad;
 export declare function createFlowContext(options: {
+    flowId?: string;
     http: HttpClient;
     stealth: StealthClient;
     env: EnvContext;

package/dist/runtime/auth-flow.js

@@ -32,6 +32,7 @@ export function createScratchpad(allowedKeys, initial = {}) {
 }
 export function createFlowContext(options) {
     return {
+        flowId: options.flowId,
         connectionId: options.connectionId,
         externalRef: options.externalRef,
         tenantId: options.tenantId,