@apifuse/provider-sdk 2.2.0-beta.57 → 2.2.0-beta.59

package/dist/error-resolution.js

@@ -8,6 +8,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
     "BROWSER_CDP_POOL_REQUIRED",
     "BROWSER_RUNTIME_UNSUPPORTED",
     "STEALTH_RUNTIME_UNSUPPORTED",
+    "STEALTH_HEADER_OVERRIDE_UNSUPPORTED",
     "SSE_EVENT_UNDECLARED",
     "STREAM_EVENT_TOO_LARGE",
     "STREAM_CHUNK_TOO_LARGE",
@@ -49,6 +50,13 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
     "http_redirect_missing_location",
     "http_redirect_loop",
     "transport_invalid_url",
+    "EGRESS_LEASE_INVALID",
+    "EGRESS_LEASE_BINDING_INVALID",
+    "EGRESS_LEASE_KEY_MISSING",
+    "EGRESS_LEASE_KEY_WEAK",
+    "STEALTH_BODY_UNSUPPORTED",
+    "REPLAY_SESSION_MISMATCH",
+    "REPLAY_ALREADY_ATTEMPTED",
     "retry_exhausted",
     "auth_abort_unsafe_data",
     "credentials_auth_missing_credential_keys",
@@ -112,6 +120,11 @@ export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES = new Map([
     // contract): the upstream evaluated the request and said no under its
     // own rules — a conflict with upstream state, never a 5xx.
     ["UPSTREAM_REJECTED", 409],
+    // Only an unverifiable or foreign handle is the caller's: key and binding
+    // faults stay unmapped (500) because the engine host, not the caller, owns them.
+    ["EGRESS_LEASE_INVALID", 409],
+    ["REPLAY_SESSION_MISMATCH", 409],
+    ["REPLAY_ALREADY_ATTEMPTED", 409],
     ["UPSTREAM_ERROR", 502],
     ["BLOCKED", 502],
     ["OCR_UNAVAILABLE", 503],

package/dist/index.d.ts

@@ -34,20 +34,22 @@ export type { PrevalidateResult } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
 export type { ProxyTelemetryHeaderPayload, ProxyHash, ProxyTelemetryLogPayload, ProxyTelemetryResolvedPayload, ProxyTelemetryUnresolvedPayload, } from "./runtime/proxy-telemetry.js";
 export { RequestTelemetry, closedEnum, type ClosedEnum, type GatewayIngestible, type RequestTelemetryLogPayload, type SpanIndex, type TelemetryContributor, type TelemetryKey, type TenantNeutral, } from "./runtime/request-telemetry.js";
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./runtime/resolver-config.js";
+export { APIFUSE__ENGINE__CEREMONY_LEASE_KEY } from "./runtime/egress-lease.js";
+export { ResolverTelemetryCollector, type ResolverCacheReadTelemetryEvent, type ResolverCacheWriteTelemetryEvent, type ResolverFailoverTelemetryEvent, type ResolverIdentityTelemetryEvent, type ResolverOutcomeTelemetryEvent, type ResolverTelemetryAttemptOutcome, type ResolverAttemptSample, type ResolverTelemetryCacheStatus, type ResolverTelemetryCacheWriteReason, type ResolverTelemetryErrorClass, type ResolverTelemetryHeaderPayload, type ResolverTelemetryIdentitySource, type ResolverTelemetryLogPayload, type ResolverTelemetryOutcome, type ResolverTelemetryPhase, type ResolverTelemetrySink, type ResolverVendorAttemptTelemetryEvent, } from "./runtime/resolver-telemetry.js";
+export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./runtime/resolver-config.js";
 export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export type { ResolverRuntimeOptions } from "./runtime/resolver.js";
-export type { ResolverVendorTransport } from "./runtime/resolver-vendors/types.js";
+export type { ResolverPaidUsageContext, ResolverVendorTransport, ResolverVendorUnavailableReason, } from "./runtime/resolver-vendors/types.js";
 export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";
 export { createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
 export { APIFUSE__OCR__API_KEY_ENV, APIFUSE__OCR__BACKEND_ENV, APIFUSE__OCR__BASE_URL_ENV, APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__OCR__MODEL_ENV, CLOUDFLARE_ACCOUNT_ID_ENV, CLOUDFLARE_WORKERS_AI_OCR_BACKEND, createCloudflareWorkersAiOcrClient, createOcrClientFromEnv, createOpenAiCompatibleOcrClient, createUnsupportedOcrClient, DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL, extractCaptchaCandidates, OPENAI_COMPATIBLE_OCR_BACKEND, } from "./runtime/ocr.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
 export { type CreateTraceContextOptions, createTraceContext, type Span, type TraceContext, } from "./runtime/trace.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 { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, 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, untrustedContent, z, } from "./schema.js";
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ProviderErrorCauseFrame, type ServeOptions, serve, } from "./server/serve.js";
 export { DEFAULT_STEALTH_BROWSER, DEFAULT_STEALTH_OS, getStealthProfile, listStealthProfiles, } from "./stealth/profiles.js";
 export * from "./stream.js";
-export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserCookie, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ChallengeSolution, 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, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OcrCaptchaCandidate, OcrCaptchaOptions, OcrCaptchaResult, OcrContext, OcrImageInput, OcrRecognizeRequest, OcrResult, OcrWarning, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceConsumeMode, ProviderChoiceConsumeResult, ProviderChoiceContext, ProviderChoiceExplicitParseResult, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderChallenge, ProviderChallengeKind, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderOcrConfig, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderResolverConfig, ProviderResolverVendor, ProviderRuntimeTarget, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, ResolverContext, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthClient, StealthBrowser, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthProfileDescriptor, StealthProfileSelection, StealthOS, 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, BrowserCookie, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ChallengeSolution, 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, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OcrCaptchaCandidate, OcrCaptchaOptions, OcrCaptchaResult, OcrContext, OcrImageInput, OcrRecognizeRequest, OcrResult, OcrWarning, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceConsumeMode, ProviderChoiceConsumeResult, ProviderChoiceContext, ProviderChoiceExplicitParseResult, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderChallenge, ProviderChallengeKind, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderOcrConfig, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderResolverConfig, ProviderResolverVendor, ProviderRuntimeTarget, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStealthConfig, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, ResolverContext, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthClient, StealthBrowser, StealthChallengeClassification, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthProfileDescriptor, StealthProfileSelection, StealthOS, 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/index.js

@@ -27,14 +27,16 @@ export { generateInsights } from "./runtime/insights.js";
 export { wrapWithInstrumentation, } from "./runtime/instrumentation.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
 export { RequestTelemetry, closedEnum, } from "./runtime/request-telemetry.js";
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./runtime/resolver-config.js";
+export { APIFUSE__ENGINE__CEREMONY_LEASE_KEY } from "./runtime/egress-lease.js";
+export { ResolverTelemetryCollector, } from "./runtime/resolver-telemetry.js";
+export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./runtime/resolver-config.js";
 export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";
 export { createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
 export { APIFUSE__OCR__API_KEY_ENV, APIFUSE__OCR__BACKEND_ENV, APIFUSE__OCR__BASE_URL_ENV, APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__OCR__MODEL_ENV, CLOUDFLARE_ACCOUNT_ID_ENV, CLOUDFLARE_WORKERS_AI_OCR_BACKEND, createCloudflareWorkersAiOcrClient, createOcrClientFromEnv, createOpenAiCompatibleOcrClient, createUnsupportedOcrClient, DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL, extractCaptchaCandidates, OPENAI_COMPATIBLE_OCR_BACKEND, } from "./runtime/ocr.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
 export { createTraceContext, } from "./runtime/trace.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, sensitive, z, } from "./schema.js";
+export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, sensitive, untrustedContent, z, } from "./schema.js";
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, serve, } from "./server/serve.js";
 export { DEFAULT_STEALTH_BROWSER, DEFAULT_STEALTH_OS, getStealthProfile, listStealthProfiles, } from "./stealth/profiles.js";
 export * from "./stream.js";

package/dist/lint.js

@@ -246,7 +246,7 @@ function lintAuthModel(provider) {
             rule: "platform-managed-no-credential-keys",
             level: "error",
             field: "credential.keys",
-            message: `${providerLabel} must not declare credential.keys for platform-managed auth mode.`,
+            message: `${providerLabel} must not declare credential.keys because platform-managed auth mode already implies the unfiltered credential capability.`,
         });
     }
     const authFlowSource = getAuthFlowSource(provider);
@@ -757,9 +757,9 @@ function browserVersionLiteralMessage(finding) {
         case "profile":
             return `Hardcoded stealth profile "${finding.literal}" pins a browser version and will rot. Select the browser and OS structurally, for example stealth: { browser: "chrome", os: "macos" }.`;
         case "user-agent":
-            return `Hardcoded User-Agent browser version "${finding.literal}" can disagree with the stealth TLS fingerprint. Remove the literal and derive it from the structured profile, for example getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.`;
+            return `Hardcoded User-Agent browser version "${finding.literal}" can disagree with the stealth TLS fingerprint. Remove the literal. ctx.stealth owns User-Agent and rejects a caller value with STEALTH_HEADER_OVERRIDE_UNSUPPORTED, so omit the header there and select the profile with stealth: { browser: "chrome", os: "macos" }. For ctx.http only, derive it from getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.`;
         case "sec-ch-ua":
-            return 'Hardcoded sec-ch-ua versions can disagree with the stealth TLS fingerprint. Remove the literal and let ctx.stealth generate client hints from stealth: { browser: "chrome", os: "macos" }; derive any explicit User-Agent with getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.';
+            return 'Hardcoded sec-ch-ua versions can disagree with the stealth TLS fingerprint. Remove the literal and let ctx.stealth generate client hints from stealth: { browser: "chrome", os: "macos" }. ctx.stealth also owns User-Agent, so omit that header there as well; for ctx.http only, derive it from getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.';
     }
 }
 function lintBrowserVersionLiterals(provider) {

package/dist/provider.d.ts

@@ -8,12 +8,12 @@ export type { JsonPrimitive, JsonValue } from "./contract-json.js";
 export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, HealthScenarioSchema, HealthStepSchema, ExtractStepSchema, FindFirstSchema, GuardStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, RelativeDateNodeSchema, ValueTypeSchema, } from "./health-scenario.js";
 export type { AssertionExpression, AssertionPredicate, AttemptReference, AssertResult, AssertStep, BoundedJsonPath, CandidateBlock, CandidatePolicy, CandidateReference, CredentialReference, CredentialRefDeclaration, EstablishedConnectionReference, ExtractStep, FindFirst, GuardAttribution, GuardReasonCode, GuardResult, GuardStep, HealthScenario, HealthStep, JsonTemplate, JournalPolicy, ManualTriggerPolicy, NonEmpty, OperationResult, OperationStep, Operand, Quantifier, ReferenceNode, Reference, RelativeDateNode, RetryPolicy, SafeRegex, ScopedAssertionExpression, ScopedAssertionPredicate, ScopedItemReference, ScopedOperand, StepBase, StepReference, ExtractResult, ValueType, } from "./health-scenario.js";
 export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, type ProviderErrorObservability, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
-export { createProviderEnvironment, createInProcessProviderEngine, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_TELEMETRY_ENV_NAMES, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedTelemetryEnvName, PROVIDER_CAPABILITY_KEYS, PROVIDER_ENGINE_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
+export { createProviderEnvironment, createInProcessProviderEngine, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RUNTIME_ENV_NAMES, ENGINE_OWNED_TELEMETRY_ENV_NAMES, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedResolverCredentialName, isEngineOwnedRuntimeEnvName, isEngineOwnedTelemetryEnvName, PROVIDER_CAPABILITY_KEYS, PROVIDER_ENGINE_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
 export type { ProviderCapabilityKey, ProviderEngine, ProviderEngineAttachmentInput, ProviderEngineBindingCandidates, ProviderEngineCapabilitySurface, ProviderEngineRequest, ProviderEngineResidentSurface, ProviderEngineSession, ProviderEngineTransport, } from "./engine.js";
 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, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceConsumeMode, ProviderChoiceConsumeResult, ProviderChoiceContext, ProviderChoiceExplicitParseResult, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeTarget, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, } from "./types.js";
+export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, 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, untrustedContent, 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, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceConsumeMode, ProviderChoiceConsumeResult, ProviderChoiceContext, ProviderChoiceExplicitParseResult, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeTarget, ProviderRuntimeState, ProviderStealthConfig, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthChallengeClassification, } from "./types.js";
 export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
 export type { NativeGatewayProxy, NativeGatewayProxyResolutionInput, NativeGatewayProxySkipReason, NativeGatewayProxySynthesizer, NativeGatewayProxySynthesisResult, NativeGatewayProxySynthesisInput, NativeNetworkClientOptions, NativeNetworkErrorCode, VendorCredentialLookup, VendorCredentialResolver, } from "./runtime/native-network.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/provider.js

@@ -4,9 +4,9 @@ export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderC
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define.js";
 export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, HealthScenarioSchema, HealthStepSchema, ExtractStepSchema, FindFirstSchema, GuardStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, RelativeDateNodeSchema, ValueTypeSchema, } from "./health-scenario.js";
 export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
-export { createProviderEnvironment, createInProcessProviderEngine, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_TELEMETRY_ENV_NAMES, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedTelemetryEnvName, PROVIDER_CAPABILITY_KEYS, PROVIDER_ENGINE_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
+export { createProviderEnvironment, createInProcessProviderEngine, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RUNTIME_ENV_NAMES, ENGINE_OWNED_TELEMETRY_ENV_NAMES, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedResolverCredentialName, isEngineOwnedRuntimeEnvName, isEngineOwnedTelemetryEnvName, PROVIDER_CAPABILITY_KEYS, PROVIDER_ENGINE_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export { 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, sensitive, z, } from "./schema.js";
+export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, sensitive, untrustedContent, z, } from "./schema.js";
 export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/runtime/bounded-expiring-map.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Map whose entries carry an expiry and whose size is capped.
+ *
+ * Expired entries are dropped when read and swept on every insert, so a
+ * process that keeps minting new keys does not retain dead values. When the
+ * cap is still exceeded after the sweep, the least recently used entry is
+ * evicted and counted in `capacityEvictions` so callers can tell the two
+ * kinds of removal apart. Callers pass `now` explicitly so a single timestamp
+ * is used across a lookup-then-store sequence.
+ */
+export declare class BoundedExpiringMap<K, V> {
+    #private;
+    constructor(maxEntries: number, expiresAt: (value: V) => number);
+    get size(): number;
+    /** Entries removed to satisfy `maxEntries`; expiry removals are not counted. */
+    get capacityEvictions(): number;
+    get(key: K, now: number): V | undefined;
+    set(key: K, value: V, now: number): void;
+    delete(key: K): boolean;
+    clear(): void;
+}

package/dist/runtime/bounded-expiring-map.js

@@ -0,0 +1,64 @@
+/**
+ * Map whose entries carry an expiry and whose size is capped.
+ *
+ * Expired entries are dropped when read and swept on every insert, so a
+ * process that keeps minting new keys does not retain dead values. When the
+ * cap is still exceeded after the sweep, the least recently used entry is
+ * evicted and counted in `capacityEvictions` so callers can tell the two
+ * kinds of removal apart. Callers pass `now` explicitly so a single timestamp
+ * is used across a lookup-then-store sequence.
+ */
+export class BoundedExpiringMap {
+    #entries = new Map();
+    #maxEntries;
+    #expiresAt;
+    #capacityEvictions = 0;
+    constructor(maxEntries, expiresAt) {
+        if (!Number.isInteger(maxEntries) || maxEntries <= 0) {
+            throw new RangeError("maxEntries must be a positive integer");
+        }
+        this.#maxEntries = maxEntries;
+        this.#expiresAt = expiresAt;
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    /** Entries removed to satisfy `maxEntries`; expiry removals are not counted. */
+    get capacityEvictions() {
+        return this.#capacityEvictions;
+    }
+    get(key, now) {
+        if (!this.#entries.has(key))
+            return undefined;
+        const value = this.#entries.get(key);
+        this.#entries.delete(key);
+        if (this.#expiresAt(value) <= now)
+            return undefined;
+        // Re-insert so Map iteration order doubles as the LRU order.
+        this.#entries.set(key, value);
+        return value;
+    }
+    set(key, value, now) {
+        for (const [existingKey, existing] of this.#entries) {
+            if (this.#expiresAt(existing) <= now)
+                this.#entries.delete(existingKey);
+        }
+        this.#entries.delete(key);
+        if (this.#expiresAt(value) <= now)
+            return;
+        this.#entries.set(key, value);
+        if (this.#entries.size > this.#maxEntries) {
+            const oldest = this.#entries.keys().next();
+            if (!oldest.done) {
+                this.#entries.delete(oldest.value);
+                this.#capacityEvictions += 1;
+            }
+        }
+    }
+    delete(key) {
+        return this.#entries.delete(key);
+    }
+    clear() {
+        this.#entries.clear();
+    }
+}

package/dist/runtime/cache.d.ts

@@ -7,5 +7,7 @@ export type ProviderCacheOptions = {
 };
 export declare const APIFUSE__CACHE__KEY_PEPPER_ENV = "APIFUSE__CACHE__KEY_PEPPER";
 export declare function createProviderCache(options: ProviderCacheOptions): ProviderCache;
+/** Internal cache capability, separate from hit/miss metadata. */
+export declare function isProviderCacheBypassed(cache: ProviderCache): boolean;
 export declare function createBypassProviderCache(options: Pick<ProviderCacheOptions, "providerId">): ProviderCache;
 export declare function resetProviderCacheForTests(): void;

package/dist/runtime/cache.js

@@ -465,12 +465,17 @@ export function createProviderCache(options) {
         },
     };
 }
+const bypassCaches = new WeakSet();
+/** Internal cache capability, separate from hit/miss metadata. */
+export function isProviderCacheBypassed(cache) {
+    return bypassCaches.has(cache);
+}
 export function createBypassProviderCache(options) {
     const configuredPepper = process.env[APIFUSE__CACHE__KEY_PEPPER_ENV];
     const pepper = configuredPepper && configuredPepper.length > 0 ? configuredPepper : undefined;
     const events = [];
     const secretScopedKeys = new Set();
-    return {
+    const cache = {
         key(namespace, parts, keyOptions) {
             const extra = new Set((keyOptions?.redactFields ?? []).map((field) => field.toLowerCase()));
             const normalized = normalizeKeyPart(parts, extra, pepper);
@@ -510,6 +515,8 @@ export function createBypassProviderCache(options) {
             };
         },
     };
+    bypassCaches.add(cache);
+    return cache;
 }
 export function resetProviderCacheForTests() {
     for (const backend of sharedBackends.values()) {

package/dist/runtime/egress-lease.d.ts

@@ -0,0 +1,63 @@
+import type { ProxyVendorName } from "../config/loader.js";
+/**
+ * AES-256-GCM key for the engine ceremony egress lease handle (ADR-0010 v1.1).
+ * Engine host only: the `APIFUSE__ENGINE__` family is rejected from provider
+ * secrets and filtered from provider env projections. Supply at least 32 random
+ * bytes (for example `openssl rand -base64 32`). Rotating the key fails
+ * verification of every outstanding handle (`EGRESS_LEASE_INVALID`, 409): the
+ * affected ceremonies restart; they do not expire.
+ */
+export declare const APIFUSE__ENGINE__CEREMONY_LEASE_KEY = "APIFUSE__ENGINE__CEREMONY_LEASE_KEY";
+/** Internal option key shared only by the server assembler and stealth runtime. */
+export declare const ENGINE_CEREMONY_EGRESS_LEASE: unique symbol;
+export type CeremonyEgressBinding = {
+    readonly vendor: ProxyVendorName;
+    readonly proxyUrl: string;
+    readonly poolIndex: number;
+    readonly affinityKey: string;
+    readonly refreshEpoch: number;
+    /**
+     * Vendor session lifetime the endpoint was allocated for (`proxy.session.lifetimeMinutes`,
+     * Smartproxy `life`, NodeMaven SID window). It is the upper bound of the lease, counted
+     * from the mint (the first successful attempt), so a Smartproxy lease can outlive the
+     * vendor session by the extraction-cache reuse window; expiry then drops and rebinds.
+     * The bound is not a vendor guarantee (ADR-0010: a raw Smartproxy endpoint is not a hard
+     * lease): the stealth runtime releases the binding as soon as the endpoint fails at the
+     * transport, so a dead endpoint is left before the lifetime elapses.
+     */
+    readonly lifetimeMinutes: number;
+};
+export type CeremonyEgressLeaseRuntime = {
+    /** Exact egress bound to this ceremony; undefined until the first successful attempt binds one. */
+    readonly binding: CeremonyEgressBinding | undefined;
+    /**
+     * Drops the binding once its vendor session lifetime has elapsed so the next attempt
+     * selects and binds a fresh endpoint. Returns true when a binding was dropped: the
+     * caller must also discard challenge state that was only valid for that endpoint.
+     */
+    dropExpiredBinding(): boolean;
+    /**
+     * Drops the binding unconditionally; the stealth runtime calls this when the bound
+     * endpoint fails at the transport. Same return and caller obligation as
+     * `dropExpiredBinding`.
+     */
+    dropBinding(): boolean;
+    /**
+     * Number of bindings dropped so far (expiry or release). Every stealth session created
+     * from one client shares the lease; a session compares this to what it last observed to
+     * retire endpoint-bound challenge state and replay records after another session moved
+     * the ceremony.
+     */
+    readonly generation: number;
+    bind(binding: CeremonyEgressBinding): void;
+    handle(): string | undefined;
+};
+export declare function createCeremonyEgressLeaseRuntime(options: {
+    readonly tenantId?: string;
+    readonly providerId: string;
+    readonly flowId: string;
+    readonly affinityKey: string;
+    readonly handle?: string;
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    readonly now?: () => number;
+}): CeremonyEgressLeaseRuntime;

package/dist/runtime/egress-lease.js

@@ -0,0 +1,233 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { SDKError } from "../errors.js";
+/**
+ * AES-256-GCM key for the engine ceremony egress lease handle (ADR-0010 v1.1).
+ * Engine host only: the `APIFUSE__ENGINE__` family is rejected from provider
+ * secrets and filtered from provider env projections. Supply at least 32 random
+ * bytes (for example `openssl rand -base64 32`). Rotating the key fails
+ * verification of every outstanding handle (`EGRESS_LEASE_INVALID`, 409): the
+ * affected ceremonies restart; they do not expire.
+ */
+export const APIFUSE__ENGINE__CEREMONY_LEASE_KEY = "APIFUSE__ENGINE__CEREMONY_LEASE_KEY";
+/** Internal option key shared only by the server assembler and stealth runtime. */
+export const ENGINE_CEREMONY_EGRESS_LEASE = Symbol.for("@apifuse/provider-sdk/engine-ceremony-egress-lease");
+const HANDLE_VERSION = 1;
+const HANDLE_MAX_BYTES = 16_384;
+const AEAD_NONCE_BYTES = 12;
+const AEAD_TAG_BYTES = 16;
+const AEAD_ALGORITHM = "aes-256-gcm";
+const AEAD_KEY_DOMAIN = "apifuse:ceremony-egress-lease:v1\0";
+const LEASE_KEY_MIN_BYTES = 32;
+/** The caller presented a handle this engine cannot verify for this ceremony (409). */
+function invalidLease() {
+    throw new SDKError("The engine ceremony egress lease is invalid", {
+        code: "EGRESS_LEASE_INVALID",
+        fix: "Restart the authentication ceremony to obtain a new engine-owned egress lease.",
+    });
+}
+/** The engine violated its own binding invariant (500); never attributable to the caller. */
+function bindingFault(message) {
+    throw new SDKError(message, {
+        code: "EGRESS_LEASE_BINDING_INVALID",
+        fix: "This is an SDK or provider-runtime fault; the ceremony lease cannot bind the selected egress.",
+    });
+}
+function encryptionKey(key) {
+    return createHash("sha256").update(AEAD_KEY_DOMAIN, "utf8").update(key, "utf8").digest();
+}
+/** Fixed field order and JSON.stringify's compact form are the canonical AAD encoding. */
+function scopeAad(scope) {
+    return Buffer.from(JSON.stringify({
+        version: HANDLE_VERSION,
+        tenantId: scope.tenantId,
+        providerId: scope.providerId,
+        flowId: scope.flowId,
+        affinityKey: scope.affinityKey,
+    }), "utf8");
+}
+function encodeHandle(payload, key, scope) {
+    const nonce = randomBytes(AEAD_NONCE_BYTES);
+    const cipher = createCipheriv(AEAD_ALGORITHM, encryptionKey(key), nonce, {
+        authTagLength: AEAD_TAG_BYTES,
+    });
+    cipher.setAAD(scopeAad(scope));
+    const ciphertext = Buffer.concat([
+        cipher.update(JSON.stringify(payload), "utf8"),
+        cipher.final(),
+    ]);
+    return [
+        `v${HANDLE_VERSION}`,
+        nonce.toString("base64url"),
+        ciphertext.toString("base64url"),
+        cipher.getAuthTag().toString("base64url"),
+    ].join(".");
+}
+function isFiniteInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isPositiveFinite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function decodeHandle(handle, key, scope) {
+    if (Buffer.byteLength(handle, "utf8") > HANDLE_MAX_BYTES)
+        return invalidLease();
+    const parts = handle.split(".");
+    if (parts.length !== 4 ||
+        parts[0] !== `v${HANDLE_VERSION}` ||
+        parts.slice(1).some((part) => !/^[A-Za-z0-9_-]+$/u.test(part))) {
+        return invalidLease();
+    }
+    let parsed;
+    try {
+        const nonce = Buffer.from(parts[1], "base64url");
+        const ciphertext = Buffer.from(parts[2], "base64url");
+        const tag = Buffer.from(parts[3], "base64url");
+        if (nonce.byteLength !== AEAD_NONCE_BYTES ||
+            tag.byteLength !== AEAD_TAG_BYTES ||
+            ciphertext.byteLength === 0) {
+            return invalidLease();
+        }
+        const decipher = createDecipheriv(AEAD_ALGORITHM, encryptionKey(key), nonce, {
+            authTagLength: AEAD_TAG_BYTES,
+        });
+        decipher.setAAD(scopeAad(scope));
+        decipher.setAuthTag(tag);
+        const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        parsed = JSON.parse(plaintext.toString("utf8"));
+    }
+    catch {
+        return invalidLease();
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return invalidLease();
+    const candidate = parsed;
+    if (candidate.version !== HANDLE_VERSION ||
+        (candidate.vendor !== "smartproxy" && candidate.vendor !== "nodemaven") ||
+        typeof candidate.proxyUrl !== "string" ||
+        !candidate.proxyUrl ||
+        !isFiniteInteger(candidate.poolIndex) ||
+        typeof candidate.affinityKey !== "string" ||
+        !candidate.affinityKey ||
+        !isFiniteInteger(candidate.refreshEpoch) ||
+        typeof candidate.tenantId !== "string" ||
+        !candidate.tenantId ||
+        typeof candidate.providerId !== "string" ||
+        !candidate.providerId ||
+        typeof candidate.flowId !== "string" ||
+        !candidate.flowId ||
+        !isFiniteInteger(candidate.mintedAtMs) ||
+        !isFiniteInteger(candidate.expiresAtMs) ||
+        candidate.expiresAtMs <= candidate.mintedAtMs ||
+        !isPositiveFinite(candidate.lifetimeMinutes)) {
+        return invalidLease();
+    }
+    try {
+        const proxy = new URL(candidate.proxyUrl);
+        if (proxy.protocol !== "http:" && proxy.protocol !== "socks5:")
+            return invalidLease();
+    }
+    catch {
+        return invalidLease();
+    }
+    return candidate;
+}
+function bindingOf(payload) {
+    return {
+        vendor: payload.vendor,
+        proxyUrl: payload.proxyUrl,
+        poolIndex: payload.poolIndex,
+        affinityKey: payload.affinityKey,
+        refreshEpoch: payload.refreshEpoch,
+        lifetimeMinutes: payload.lifetimeMinutes,
+    };
+}
+export function createCeremonyEgressLeaseRuntime(options) {
+    const environment = options.environment ?? process.env;
+    const now = options.now ?? Date.now;
+    if (typeof options.tenantId !== "string" || !options.tenantId.trim()) {
+        throw new SDKError("A tenant is required for an engine ceremony egress lease", {
+            code: "EGRESS_LEASE_INVALID",
+            fix: "Restart the authentication ceremony with its tenant identity.",
+        });
+    }
+    const scope = {
+        tenantId: options.tenantId,
+        providerId: options.providerId,
+        flowId: options.flowId,
+        affinityKey: options.affinityKey,
+    };
+    const key = environment[APIFUSE__ENGINE__CEREMONY_LEASE_KEY]?.trim();
+    if (!key) {
+        throw new SDKError("The engine ceremony egress lease key is not configured", {
+            code: "EGRESS_LEASE_KEY_MISSING",
+            fix: `Configure ${APIFUSE__ENGINE__CEREMONY_LEASE_KEY} in the engine host.`,
+        });
+    }
+    // The key is the whole authenticity boundary of a handle (a verified handle's proxyUrl
+    // becomes the ceremony egress), so the documented minimum is enforced, not advisory.
+    if (Buffer.byteLength(key, "utf8") < LEASE_KEY_MIN_BYTES) {
+        throw new SDKError(`The engine ceremony egress lease key is shorter than ${LEASE_KEY_MIN_BYTES} bytes`, {
+            code: "EGRESS_LEASE_KEY_WEAK",
+            fix: `Set ${APIFUSE__ENGINE__CEREMONY_LEASE_KEY} to at least ${LEASE_KEY_MIN_BYTES} random bytes (for example \`openssl rand -base64 32\`).`,
+        });
+    }
+    let payload;
+    let currentHandle;
+    let generation = 0;
+    const dropBinding = () => {
+        if (!payload)
+            return false;
+        payload = undefined;
+        currentHandle = undefined;
+        generation += 1;
+        return true;
+    };
+    const dropExpiredBinding = () => payload !== undefined && now() >= payload.expiresAtMs ? dropBinding() : false;
+    if (options.handle !== undefined) {
+        // Scope mismatch fails GCM authentication because scope is AAD; there is
+        // deliberately no post-decrypt scope comparison fallback.
+        payload = decodeHandle(options.handle, key, scope);
+        currentHandle = options.handle;
+        // An expired but authentic handle is not a fault: the ceremony continues on a
+        // freshly selected endpoint and the next turn receives the new handle.
+        dropExpiredBinding();
+    }
+    return {
+        get binding() {
+            return payload ? bindingOf(payload) : undefined;
+        },
+        dropExpiredBinding,
+        dropBinding,
+        get generation() {
+            return generation;
+        },
+        bind(binding) {
+            if (payload) {
+                // The stealth runtime reuses the bound endpoint while a binding exists and
+                // never rebinds it; a second bind is an engine invariant break.
+                return bindingFault("The ceremony egress lease is already bound");
+            }
+            if (binding.affinityKey !== options.affinityKey ||
+                !binding.proxyUrl ||
+                (binding.vendor !== "smartproxy" && binding.vendor !== "nodemaven") ||
+                !isFiniteInteger(binding.poolIndex) ||
+                !isPositiveFinite(binding.lifetimeMinutes)) {
+                return bindingFault("The selected egress cannot be bound to the ceremony lease");
+            }
+            const mintedAtMs = now();
+            payload = {
+                version: HANDLE_VERSION,
+                tenantId: scope.tenantId,
+                providerId: options.providerId,
+                flowId: options.flowId,
+                ...binding,
+                mintedAtMs,
+                expiresAtMs: mintedAtMs + binding.lifetimeMinutes * 60_000,
+            };
+            currentHandle = encodeHandle(payload, key, scope);
+        },
+        handle() {
+            return currentHandle;
+        },
+    };
+}

package/dist/runtime/http.js

@@ -498,6 +498,7 @@ async function resolveNativeProxy(options, clientOptions, warn, proxyAttemptOffs
         // supported here, so a socks5 policy fails loudly rather than downgrading.
         transportProtocols: ["http"],
         telemetry: clientOptions.telemetry,
+        engineCredentials: clientOptions.engineCredentials,
     });
     if (resolvedProxy.shouldWarn) {
         warn("[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.");

package/dist/runtime/proxy-retry-policy.d.ts

@@ -21,7 +21,10 @@ export declare function normalizeProxyTransportRetryOptions(retry: RequestOption
     label?: RetryPolicyLabel;
 }): NormalizedProxyTransportRetryOptions | undefined;
 export declare function validateUnsafeProxyTransportRetryMethods(options: NormalizedProxyTransportRetryOptions, label?: RetryPolicyLabel): void;
-export declare function isProxyTransportRetryMethod(method: HttpMethod | string, options: NormalizedProxyTransportRetryOptions): boolean;
+export declare function isProxyTransportRetryMethod(method: HttpMethod | string, options: NormalizedProxyTransportRetryOptions, request?: {
+    readonly body?: unknown;
+    readonly headers?: Readonly<Record<string, string | readonly string[] | undefined>>;
+}): boolean;
 export declare function shouldRetryProxyTransportError(error: unknown, options: NormalizedProxyTransportRetryOptions): boolean;
 export declare function shouldRetryProxyTransportAttempt(input: {
     error: unknown;