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

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.21
+
+- Release candidate for main commit 00f61024fb18db39711dc5076c4621508baa49f5.
+
 ## 2.2.0-beta.20
 
 - Release candidate for main commit 8043d2ef0047e431aace750d8abca2e1149ec1d6.
@@ -110,6 +114,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/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?: {

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,

package/dist/runtime/state.js

@@ -3,6 +3,90 @@ import { ProviderError } from "../errors.js";
 import { createProviderRedisClient, ensureRedisReady, withRedisTimeout, } from "./redis.js";
 const DEFAULT_REDIS_TIMEOUT_MS = 250;
 const REDIS_STATE_PREFIX = "apifuse:provider-state:v1";
+const LEGACY_INDEX_SCAN_COUNT = 256;
+const LEGACY_INDEX_SCAN_MAX_PAGES = 8;
+const SET_WITH_QUOTA_SCRIPT = `
+local now = tonumber(ARGV[1])
+local max_entries = tonumber(ARGV[2])
+local expires_at = tonumber(ARGV[3])
+local index_ttl = tonumber(ARGV[4])
+local envelope = ARGV[5]
+
+redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", now)
+local exists = redis.call("EXISTS", KEYS[1])
+local indexed = redis.call("ZSCORE", KEYS[2], KEYS[1])
+if exists == 0 and not indexed and redis.call("ZCARD", KEYS[2]) >= max_entries then
+	return {0, false}
+end
+
+redis.call("SET", KEYS[1], envelope, "PXAT", expires_at)
+redis.call("ZADD", KEYS[2], expires_at, KEYS[1])
+redis.call("PEXPIRE", KEYS[2], index_ttl)
+return {1, envelope}
+`;
+const COMPARE_AND_SET_WITH_QUOTA_SCRIPT = `
+local current = redis.call("GET", KEYS[1])
+local current_version = 0
+if current then
+	local ok, decoded = pcall(cjson.decode, current)
+	if not ok or type(decoded) ~= "table" or type(decoded.version) ~= "number" then
+		return {-2, current}
+	end
+	current_version = decoded.version
+end
+if current_version ~= tonumber(ARGV[1]) then
+	return {-1, current or false}
+end
+
+local now = tonumber(ARGV[2])
+local max_entries = tonumber(ARGV[3])
+local expires_at = tonumber(ARGV[4])
+local index_ttl = tonumber(ARGV[5])
+local envelope = ARGV[6]
+redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", now)
+local exists = current and 1 or 0
+local indexed = redis.call("ZSCORE", KEYS[2], KEYS[1])
+if exists == 0 and not indexed and redis.call("ZCARD", KEYS[2]) >= max_entries then
+	return {0, false}
+end
+
+redis.call("SET", KEYS[1], envelope, "PXAT", expires_at)
+redis.call("ZADD", KEYS[2], expires_at, KEYS[1])
+redis.call("PEXPIRE", KEYS[2], index_ttl)
+return {1, envelope}
+`;
+const DELETE_WITH_INDEX_SCRIPT = `
+redis.call("DEL", KEYS[1])
+redis.call("ZREM", KEYS[2], KEYS[1])
+return 1
+`;
+// Older SDKs wrote only the value key. Every operation that depends on the
+// namespace index advances a bounded SCAN cursor and lazily imports active
+// legacy envelopes into the new ZSET. The cursor is
+// deliberately cyclic rather than permanently "complete": an old pod may
+// still write an unindexed key during a rolling deploy. Each list/write call
+// does a fixed amount of migration work; Redis KEYS and unbounded scans remain
+// forbidden.
+const BACKFILL_LEGACY_INDEX_SCRIPT = `
+local now = tonumber(ARGV[1])
+local index_ttl = tonumber(ARGV[2])
+local next_cursor = ARGV[3]
+
+redis.call("ZREMRANGEBYSCORE", KEYS[1], "-inf", now)
+for i = 4, #ARGV, 3 do
+	local key = ARGV[i]
+	local expected = ARGV[i + 1]
+	local expires_at = tonumber(ARGV[i + 2])
+	if redis.call("GET", key) == expected then
+		redis.call("ZADD", KEYS[1], "NX", expires_at, key)
+	end
+end
+if redis.call("EXISTS", KEYS[1]) == 1 then
+	redis.call("PEXPIRE", KEYS[1], index_ttl)
+end
+redis.call("SET", KEYS[2], next_cursor, "PX", index_ttl)
+return redis.call("ZCARD", KEYS[1])
+`;
 const redisBackends = new Map();
 function getRedisBackend(redisUrl) {
     const existing = redisBackends.get(redisUrl);
@@ -46,6 +130,9 @@ function publicStateKey(providerId, namespace, redisKey) {
     const prefix = `${providerStatePrefix(providerId, namespace)}:`;
     return redisKey.startsWith(prefix) ? redisKey.slice(prefix.length) : redisKey;
 }
+function redisGlobLiteral(value) {
+    return value.replace(/[\\*?\[\]]/g, "\\$&");
+}
 function parseStateDurationMs(ttl) {
     const match = /^(\d+)(ms|s|m|h|d)$/.exec(ttl ?? "1h");
     if (!match)
@@ -119,12 +206,55 @@ class RedisProviderStateNamespace {
     redisKey(key) {
         return providerStateKey(this.providerId, this.namespaceName, key);
     }
-    prefix() {
+    indexKey() {
+        // Keep bookkeeping outside the caller-owned keyspace. A provider may use
+        // any state key (including "__index"), so a suffix inside the namespace
+        // could turn the ZSET into a string and break every subsequent write.
+        const namespaceIdentity = Buffer.from(providerStatePrefix(this.providerId, this.namespaceName), "utf8").toString("base64url");
+        return `${REDIS_STATE_PREFIX}:index:${namespaceIdentity}`;
+    }
+    legacyScanCursorKey() {
+        return `${this.indexKey()}:legacy-scan-cursor`;
+    }
+    legacyPrefix() {
         return `${providerStatePrefix(this.providerId, this.namespaceName)}:`;
     }
-    async activeKeys() {
+    async backfillLegacyIndex() {
         await requireRedisReady(this.backend.redis);
-        return await withRequiredRedis(() => this.backend.redis.keys(`${this.prefix()}*`));
+        const cursorKey = this.legacyScanCursorKey();
+        let cursor = (await withRequiredRedis(() => this.backend.redis.get(cursorKey))) ?? "0";
+        const pattern = `${redisGlobLiteral(this.legacyPrefix())}*`;
+        const indexTtlMs = parseStateDurationMs(this.options.maxTtl);
+        for (let page = 0; page < LEGACY_INDEX_SCAN_MAX_PAGES; page += 1) {
+            const [nextCursor, keys] = await withRequiredRedis(() => this.backend.redis.scan(cursor, "MATCH", pattern, "COUNT", LEGACY_INDEX_SCAN_COUNT));
+            const rawValues = keys.length > 0
+                ? await withRequiredRedis(() => this.backend.redis.mget(keys))
+                : [];
+            const now = Date.now();
+            const activeLegacyArgs = [];
+            for (const [index, raw] of rawValues.entries()) {
+                const key = keys[index];
+                if (!key || !raw)
+                    continue;
+                const envelope = envelopeFromJson(publicStateKey(this.providerId, this.namespaceName, key), raw);
+                const expiresAtMs = envelope ? Date.parse(envelope.expiresAt) : Number.NaN;
+                if (!Number.isFinite(expiresAtMs) || expiresAtMs <= now)
+                    continue;
+                activeLegacyArgs.push(key, raw, String(expiresAtMs));
+            }
+            await withRequiredRedis(() => this.backend.redis.eval(BACKFILL_LEGACY_INDEX_SCRIPT, 2, this.indexKey(), cursorKey, String(now), String(indexTtlMs), nextCursor, ...activeLegacyArgs));
+            cursor = nextCursor;
+            if (cursor === "0")
+                break;
+        }
+    }
+    async indexedKeys(limit) {
+        await requireRedisReady(this.backend.redis);
+        const now = Date.now();
+        return await withRequiredRedis(async () => {
+            await this.backend.redis.zremrangebyscore(this.indexKey(), "-inf", now);
+            return await this.backend.redis.zrangebyscore(this.indexKey(), now + 1, "+inf", "LIMIT", 0, limit);
+        });
     }
     enforceValueSize(value) {
         const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
@@ -132,20 +262,32 @@ class RedisProviderStateNamespace {
             throw new UnsupportedProviderStateError(`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`);
         }
     }
-    async enforceMaxEntries(key) {
-        const keys = await this.activeKeys();
-        const redisKey = this.redisKey(key);
-        const otherKeys = keys.filter((candidate) => candidate !== redisKey);
-        if (otherKeys.length >= this.options.maxEntries) {
-            throw new UnsupportedProviderStateError(`Provider runtime state namespace quota exceeded (${otherKeys.length + 1} > ${this.options.maxEntries})`);
+    quotaExceeded() {
+        return new UnsupportedProviderStateError(`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`);
+    }
+    writeTiming(ttl) {
+        const ttlMs = parseStateDurationMs(ttl ?? this.options.defaultTtl);
+        const maxTtlMs = parseStateDurationMs(this.options.maxTtl);
+        if (ttlMs > maxTtlMs) {
+            throw new UnsupportedProviderStateError(`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`);
         }
+        const expiresAtMs = Date.now() + ttlMs;
+        return {
+            expiresAt: new Date(expiresAtMs).toISOString(),
+            expiresAtMs,
+            indexTtlMs: maxTtlMs,
+        };
     }
     async list(options) {
-        const keys = (await this.activeKeys()).filter((key) => {
+        const requestedLimit = Math.max(0, options?.limit ?? this.options.maxEntries);
+        if (requestedLimit === 0)
+            return [];
+        await this.backfillLegacyIndex();
+        const keys = (await this.indexedKeys(this.options.maxEntries)).filter((key) => {
             const publicKey = publicStateKey(this.providerId, this.namespaceName, key);
             return options?.prefix ? publicKey.startsWith(options.prefix) : true;
         });
-        const limited = keys.slice(0, Math.max(0, options?.limit ?? keys.length));
+        const limited = keys.slice(0, requestedLimit);
         if (limited.length === 0)
             return [];
         const values = await withRequiredRedis(() => this.backend.redis.mget(limited));
@@ -164,20 +306,22 @@ class RedisProviderStateNamespace {
     }
     async set(key, value, options) {
         this.enforceValueSize(value);
-        await this.enforceMaxEntries(key);
+        await this.backfillLegacyIndex();
         const current = await this.get(key);
         const createdAt = current?.createdAt ?? new Date().toISOString();
         const version = (current?.version ?? 0) + 1;
-        const ttl = options?.ttl ?? this.options.defaultTtl;
-        const ttlMs = parseStateDurationMs(ttl);
-        const expiresAt = resolveExpiresAt(ttl);
-        const envelope = redisEnvelope(value, version, createdAt, expiresAt);
-        await withRequiredRedis(() => this.backend.redis.set(this.redisKey(key), JSON.stringify(envelope), "PX", ttlMs));
+        const timing = this.writeTiming(options?.ttl);
+        const envelope = redisEnvelope(value, version, createdAt, timing.expiresAt);
+        await requireRedisReady(this.backend.redis);
+        const result = await withRequiredRedis(() => this.backend.redis.eval(SET_WITH_QUOTA_SCRIPT, 2, this.redisKey(key), this.indexKey(), String(Date.now()), String(this.options.maxEntries), String(timing.expiresAtMs), String(timing.indexTtlMs), JSON.stringify(envelope)));
+        if (!Array.isArray(result) || Number(result[0]) !== 1) {
+            throw this.quotaExceeded();
+        }
         return {
             key,
             value,
             version,
-            expiresAt,
+            expiresAt: timing.expiresAt,
             createdAt,
             updatedAt: envelope.updatedAt,
         };
@@ -190,15 +334,38 @@ class RedisProviderStateNamespace {
     }
     async compareAndSet(key, expectedVersion, value, options) {
         this.enforceValueSize(value);
+        await this.backfillLegacyIndex();
         const current = await this.get(key);
         if ((current?.version ?? 0) !== expectedVersion) {
             return { ok: false, current };
         }
-        return { ok: true, value: await this.set(key, value, options) };
+        const createdAt = current?.createdAt ?? new Date().toISOString();
+        const timing = this.writeTiming(options?.ttl);
+        const envelope = redisEnvelope(value, expectedVersion + 1, createdAt, timing.expiresAt);
+        await requireRedisReady(this.backend.redis);
+        const result = await withRequiredRedis(() => this.backend.redis.eval(COMPARE_AND_SET_WITH_QUOTA_SCRIPT, 2, this.redisKey(key), this.indexKey(), String(expectedVersion), String(Date.now()), String(this.options.maxEntries), String(timing.expiresAtMs), String(timing.indexTtlMs), JSON.stringify(envelope)));
+        if (Array.isArray(result) && Number(result[0]) === 0) {
+            throw this.quotaExceeded();
+        }
+        if (!Array.isArray(result) || Number(result[0]) !== 1) {
+            const rawCurrent = Array.isArray(result) && typeof result[1] === "string" ? result[1] : null;
+            return { ok: false, current: envelopeFromJson(key, rawCurrent) };
+        }
+        return {
+            ok: true,
+            value: {
+                key,
+                value,
+                version: envelope.version,
+                expiresAt: timing.expiresAt,
+                createdAt,
+                updatedAt: envelope.updatedAt,
+            },
+        };
     }
     async delete(key) {
         await requireRedisReady(this.backend.redis);
-        await withRequiredRedis(() => this.backend.redis.del(this.redisKey(key)));
+        await withRequiredRedis(() => this.backend.redis.eval(DELETE_WITH_INDEX_SCRIPT, 2, this.redisKey(key), this.indexKey()));
     }
     async increment(key, field, delta = 1, options) {
         const current = (await this.get(key))?.value ?? {};
@@ -258,6 +425,23 @@ class MemoryProviderStateNamespace {
     constructor(options) {
         this.options = options;
     }
+    enforceValueSize(value) {
+        const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
+        if (bytes > this.options.maxValueBytes) {
+            throw new UnsupportedProviderStateError(`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`);
+        }
+    }
+    enforceWritePolicy(key, value, ttl) {
+        this.enforceValueSize(value);
+        const ttlMs = parseStateDurationMs(ttl ?? this.options.defaultTtl);
+        const maxTtlMs = parseStateDurationMs(this.options.maxTtl);
+        if (ttlMs > maxTtlMs) {
+            throw new UnsupportedProviderStateError(`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`);
+        }
+        if (!this.values.has(key) && this.values.size >= this.options.maxEntries) {
+            throw new UnsupportedProviderStateError(`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`);
+        }
+    }
     pruneExpired(nowMs = Date.now()) {
         for (const [key, row] of this.values.entries()) {
             if (row.expiresAt && Date.parse(row.expiresAt) <= nowMs) {
@@ -276,6 +460,7 @@ class MemoryProviderStateNamespace {
     }
     async set(key, value, options) {
         this.pruneExpired();
+        this.enforceWritePolicy(key, value, options?.ttl);
         const now = new Date().toISOString();
         const current = this.values.get(key);
         const expiresAt = resolveMemoryStateExpiresAt(options?.ttl ?? this.options.defaultTtl);
@@ -293,8 +478,24 @@ class MemoryProviderStateNamespace {
     async patch(_key, _partial, _options) {
         throw new UnsupportedProviderStateError("In-memory provider runtime state does not support patch");
     }
-    async compareAndSet(_key, _expectedVersion, _value, _options) {
-        throw new UnsupportedProviderStateError("In-memory provider runtime state does not support compareAndSet");
+    async compareAndSet(key, expectedVersion, value, options) {
+        this.pruneExpired();
+        const current = this.values.get(key);
+        if ((current?.version ?? 0) !== expectedVersion) {
+            return { ok: false, current: current ?? null };
+        }
+        this.enforceWritePolicy(key, value, options?.ttl);
+        const now = new Date().toISOString();
+        const stored = {
+            key,
+            value,
+            version: expectedVersion + 1,
+            expiresAt: resolveMemoryStateExpiresAt(options?.ttl ?? this.options.defaultTtl),
+            createdAt: current?.createdAt ?? now,
+            updatedAt: now,
+        };
+        this.values.set(key, stored);
+        return { ok: true, value: stored };
     }
     async delete(key) {
         this.values.delete(key);