@apifuse/provider-sdk 2.2.0-beta.32 → 2.2.0-beta.35

package/dist/runtime/resolver-vendors/twocaptcha.js

@@ -235,17 +235,23 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
             if (!resolverVendorSupports(TWOCAPTCHA_VENDOR_ID, challenge.kind)) {
                 throw new TypeError(`2captcha resolver does not support ${challenge.kind}`);
             }
-            if (challenge.kind !== "recaptcha_v2" && challenge.kind !== "aws_waf") {
-                throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "not_implemented", {
-                    phase: "create_task",
-                });
+            if (challenge.kind === "aws_waf") {
+                const missingFields = [
+                    ...(challenge.siteKey?.trim() ? [] : ["siteKey"]),
+                    ...(challenge.captchaScript?.trim() ? [] : ["captchaScript"]),
+                    ...(challenge.context?.trim() ? [] : ["context"]),
+                    ...(challenge.iv?.trim() ? [] : ["iv"]),
+                ];
+                if (missingFields.length > 0) {
+                    throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "missing_challenge_input", {
+                        missingFields,
+                        phase: "create_task",
+                    });
+                }
             }
-            if (challenge.kind === "aws_waf" &&
-                (!challenge.siteKey?.trim() ||
-                    !challenge.captchaScript?.trim() ||
-                    !challenge.context?.trim() ||
-                    !challenge.iv?.trim())) {
-                throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "not_implemented", {
+            if (challenge.kind === "recaptcha_v3" && challenge.minScore === undefined) {
+                throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "missing_challenge_input", {
+                    missingFields: ["minScore"],
                     phase: "create_task",
                 });
             }
@@ -278,14 +284,47 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
                             ...(identity ? { userAgent: identity.userAgent } : {}),
                             ...(proxy ?? {}),
                         }
-                        : {
-                            type: proxy ? "RecaptchaV2Task" : "RecaptchaV2TaskProxyless",
-                            websiteURL: challenge.pageUrl,
-                            websiteKey: challenge.siteKey,
-                            isInvisible: false,
-                            ...(identity ? { userAgent: identity.userAgent } : {}),
-                            ...(proxy ?? {}),
-                        };
+                        : challenge.kind === "recaptcha_v2"
+                            ? {
+                                type: proxy ? "RecaptchaV2Task" : "RecaptchaV2TaskProxyless",
+                                websiteURL: challenge.pageUrl,
+                                websiteKey: challenge.siteKey,
+                                isInvisible: false,
+                                ...(identity ? { userAgent: identity.userAgent } : {}),
+                                ...(proxy ?? {}),
+                            }
+                            : challenge.kind === "recaptcha_v3"
+                                ? {
+                                    type: "RecaptchaV3TaskProxyless",
+                                    websiteURL: challenge.pageUrl,
+                                    websiteKey: challenge.siteKey,
+                                    minScore: challenge.minScore,
+                                    pageAction: challenge.action,
+                                    ...(identity ? { userAgent: identity.userAgent } : {}),
+                                }
+                                : challenge.kind === "hcaptcha"
+                                    ? {
+                                        type: proxy ? "HCaptchaTask" : "HCaptchaTaskProxyless",
+                                        websiteURL: challenge.pageUrl,
+                                        websiteKey: challenge.siteKey,
+                                        ...(identity ? { userAgent: identity.userAgent } : {}),
+                                        ...(proxy ?? {}),
+                                    }
+                                    : challenge.kind === "turnstile"
+                                        ? {
+                                            type: proxy ? "TurnstileTask" : "TurnstileTaskProxyless",
+                                            websiteURL: challenge.pageUrl,
+                                            websiteKey: challenge.siteKey,
+                                            ...(challenge.action !== undefined ? { action: challenge.action } : {}),
+                                            ...(challenge.cdata !== undefined ? { data: challenge.cdata } : {}),
+                                            ...(identity ? { userAgent: identity.userAgent } : {}),
+                                            ...(proxy ?? {}),
+                                        }
+                                        : // `resolverVendorSupports` above already rejected every kind this
+                                            // adapter does not build a task for, so this branch is unreachable.
+                                            (() => {
+                                                throw new TypeError(`2captcha resolver does not support ${challenge.kind}`);
+                                            })();
                     const createResult = await postJson(fetchImpl, endpoint(baseUrl, "createTask"), { clientKey: apiKey, task }, solveController.signal, phase, [apiKey]);
                     const taskId = taskIdFrom(createResult.payload);
                     if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {

package/dist/runtime/resolver-vendors/types.d.ts

@@ -2,7 +2,7 @@ import type { ChallengeSolution, ProviderChallenge, ProviderChallengeKind, Provi
 import type { TraceRecorder } from "../trace.js";
 export declare const RESOLVER_VENDOR_CAPABILITIES: {
     readonly browser: readonly ["aws_waf", "cloudflare_interstitial"];
-    readonly "2captcha": readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf", "akamai_sec_cpt", "akamai_sensor"];
+    readonly "2captcha": readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "aws_waf"];
     readonly capsolver: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf"];
     readonly capmonster: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha"];
     readonly custom: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf", "akamai_sec_cpt", "akamai_sensor"];
@@ -55,11 +55,13 @@ export interface ResolverVendorAdapter {
     getIssuingIdentity?(solution: ChallengeSolution, requestedIdentity: ResolverIdentity | undefined, challenge: ProviderChallenge): ResolverIssuingIdentity | undefined;
     solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder, transport?: ResolverVendorTransport): Promise<ChallengeSolution>;
 }
-export type ResolverVendorUnavailableReason = "missing_credentials" | "missing_proxy_identity" | "missing_client_profile" | "missing_transport" | "allocation_exhausted" | "transport_failure" | "timeout" | "not_implemented";
+export type ResolverVendorUnavailableReason = "missing_credentials" | "missing_proxy_identity" | "missing_client_profile" | "missing_challenge_input" | "missing_transport" | "allocation_exhausted" | "transport_failure" | "timeout" | "not_implemented";
 export type ResolverChallengeVerdictReason = "human_puzzle" | "solve_failed";
 type ResolverErrorOptions = {
     /** Raw cause; adapters must not place bodies, cookies, headers, credentials, or proxy URLs here. */
     readonly cause?: unknown;
+    /** Names of challenge fields required by this adapter but absent from this call's input. */
+    readonly missingFields?: readonly string[];
     /** Upstream hostname only; never a URL. */
     readonly upstreamHost?: string;
     /** Adapter-defined sensor-loop phase, such as fetch_script or post_sensor. */
@@ -70,6 +72,7 @@ type ResolverErrorOptions = {
 export declare class ResolverVendorUnavailableError extends Error {
     readonly vendor: ProviderResolverVendor;
     readonly reason: ResolverVendorUnavailableReason;
+    readonly missingFields?: readonly string[];
     readonly upstreamHost?: string;
     readonly phase?: string;
     readonly round?: number;

package/dist/runtime/resolver-vendors/types.js

@@ -1,14 +1,17 @@
 export const RESOLVER_VENDOR_CAPABILITIES = {
     browser: ["aws_waf", "cloudflare_interstitial"],
+    // Every kind listed per vendor is implemented by that vendor's adapter; the
+    // per-adapter "agrees with every declared capability" tests iterate this
+    // table, so adding a kind here without an implementation fails the suite.
+    // 2captcha omits `cloudflare_interstitial`, `akamai_sec_cpt`, and
+    // `akamai_sensor`: their API offers no task type for them, so declaring them
+    // would route challenges to a vendor that can only refuse.
     "2captcha": [
         "turnstile",
         "recaptcha_v2",
         "recaptcha_v3",
         "hcaptcha",
-        "cloudflare_interstitial",
         "aws_waf",
-        "akamai_sec_cpt",
-        "akamai_sensor",
     ],
     capsolver: [
         "turnstile",
@@ -36,14 +39,23 @@ export function resolverVendorSupports(vendor, kind) {
 export class ResolverVendorUnavailableError extends Error {
     vendor;
     reason;
+    missingFields;
     upstreamHost;
     phase;
     round;
     constructor(vendor, reason, options = {}) {
-        super(`Resolver vendor ${vendor} is unavailable: ${reason}`);
+        const missingFields = reason === "missing_challenge_input"
+            ? options.missingFields?.filter((field) => /^[A-Za-z][A-Za-z0-9_]*$/u.test(field))
+            : undefined;
+        super(reason === "missing_challenge_input" && missingFields !== undefined && missingFields.length > 0
+            ? `Resolver vendor ${vendor} cannot use incomplete challenge input; missing fields: ${missingFields.join(", ")}`
+            : `Resolver vendor ${vendor} is unavailable: ${reason}`);
         this.vendor = vendor;
         this.reason = reason;
         this.name = "ResolverVendorUnavailableError";
+        if (missingFields !== undefined && missingFields.length > 0) {
+            this.missingFields = Object.freeze([...missingFields]);
+        }
         if (options.cause !== undefined) {
             this.cause = options.cause;
         }

package/dist/runtime/resolver.d.ts

@@ -34,7 +34,7 @@ export type ResolverInstrumentationMetadata = {
     readonly target: ResolverContext;
     readonly traceRecorder: TraceRecorder;
 };
-export type ResolverAdapterFactory = (configuration: string, timeoutMs: number, allowedHosts: readonly string[]) => ResolverVendorAdapter;
+export type ResolverAdapterFactory = (configuration: string | undefined, timeoutMs: number, allowedHosts: readonly string[]) => ResolverVendorAdapter;
 export declare const RESOLVER_ADAPTER_REGISTRY: Partial<Readonly<Record<ProviderResolverVendor, ResolverAdapterFactory>>>;
 export declare function swapResolverAdapterFactoryForTests(vendor: ProviderResolverVendor, factory: ResolverAdapterFactory | undefined): () => void;
 /** Internal test seam; deliberately not re-exported from the package root. */

package/dist/runtime/resolver.js

@@ -56,6 +56,9 @@ const SAFE_CAUSE_MESSAGE_WORDS = new Set([
 ]);
 const resolverAdapterRegistry = {
     "2captcha"(configuration, timeoutMs, allowedHosts) {
+        if (configuration === undefined) {
+            throw new Error("2captcha resolver adapter factory requires an API key");
+        }
         return createTwoCaptchaResolverVendorAdapter({
             allowedHosts,
             apiKey: configuration,
@@ -173,10 +176,17 @@ function throwUnsupportedKind(kind) {
     });
 }
 function throwExhausted(attempts) {
-    const summary = attempts.map(({ vendor, reason }) => `${vendor}: ${reason}`).join(", ");
+    const hasMissingChallengeInput = attempts.some((attempt) => attempt.reason === "missing_challenge_input");
+    const summary = attempts
+        .map(({ vendor, reason, missingFields }) => missingFields === undefined || missingFields.length === 0
+        ? `${vendor}: ${reason}`
+        : `${vendor}: ${reason} (missing fields: ${missingFields.join(", ")})`)
+        .join(", ");
     throw new ProviderError(`Resolver vendor chain exhausted: ${summary}`, {
         code: "RESOLVER_CHAIN_EXHAUSTED",
-        fix: "Configure another supporting resolver vendor or restore an unavailable vendor.",
+        fix: hasMissingChallengeInput
+            ? "Capture the named challenge fields or configure another supporting resolver vendor."
+            : "Configure another supporting resolver vendor or restore an unavailable vendor.",
         details: attempts,
     });
 }
@@ -280,6 +290,7 @@ function unavailableAttempt(error) {
     return {
         vendor: error.vendor,
         reason: error.reason,
+        ...(error.missingFields ? { missingFields: [...error.missingFields] } : {}),
         ...(cause ? { cause } : {}),
         ...(upstreamHost ? { upstreamHost } : {}),
         ...(phase ? { phase } : {}),
@@ -290,6 +301,7 @@ function unavailableSpanAttributes(error) {
     const attempt = unavailableAttempt(error);
     return {
         unavailability_reason: error.reason,
+        missing_fields: error.missingFields,
         cause_name: attempt.cause?.name,
         cause_message: attempt.cause?.message,
         upstream_host: attempt.upstreamHost,
@@ -608,6 +620,8 @@ function createResolverChainClient(options) {
                     signal.throwIfAborted();
                     if (!(error instanceof ResolverVendorUnavailableError))
                         throw error;
+                    // Every vendor-unavailable result, including missing_challenge_input, falls
+                    // through so another adapter can solve with a different input contract.
                     attempts.push(unavailableAttempt(error));
                 }
             }
@@ -643,13 +657,18 @@ function resolveVendorAvailability(vendor, env) {
             reason: "missing_transport",
         };
     }
+    if (vendor === "browser") {
+        return {
+            vendor,
+            available: true,
+            configuration: normalizedEnvValue(env, APIFUSE__CDP_POOL__URL),
+        };
+    }
     const envKey = vendor === "2captcha"
         ? APIFUSE__RESOLVER__2CAPTCHA__API_KEY
         : vendor === "capsolver"
             ? APIFUSE__RESOLVER__CAPSOLVER__API_KEY
-            : vendor === "capmonster"
-                ? APIFUSE__RESOLVER__CAPMONSTER__API_KEY
-                : APIFUSE__CDP_POOL__URL;
+            : APIFUSE__RESOLVER__CAPMONSTER__API_KEY;
     const configuration = normalizedEnvValue(env, envKey);
     return configuration
         ? { vendor, available: true, configuration }

package/dist/server/serve-implementation.d.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { type ProviderErrorCategory } from "../observability.js";
 import type { OcrContext, ProviderContext, ProviderDefinition, ProviderRuntimeState, ResolverContext, SttContext } from "../types.js";
 import type { SelfTestCancellationLogEvent } from "./self-test.js";
-import { type OperationRequest } from "./types.js";
+import { type AuthFlowRequest, type OperationRequest } from "./types.js";
 /** Compact SDK-owned error classification emitted separately from the public response body. */
 export declare const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
 export type ErrorObservabilityDetails = {
@@ -63,6 +63,7 @@ export type ProviderServerOperationExecutorInput = {
 export type ProviderServerOperationExecutor = (input: ProviderServerOperationExecutorInput) => Promise<unknown>;
 export declare function resolveProviderProxyAffinityKey(provider: ProviderDefinition, request: OperationRequest, operationId: string): string;
 export declare function resolveProviderResolverIdentityScope(provider: ProviderDefinition, affinityKey: string, contextId: string): string;
+export declare function resolveAuthFlowProxyAffinityKey(provider: ProviderDefinition, request: Pick<AuthFlowRequest, "connection" | "connectionId" | "externalRef" | "tenantId" | "providerId">): string;
 type ProviderRequestCost = {
     durationMs: number;
     cpuUserMicros: number;

package/dist/server/serve-implementation.js

@@ -11,7 +11,7 @@ import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.j
 import { categoryForStatus, sourceForCategory, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability.js";
 import { createScratchpad } from "../runtime/auth-flow.js";
 import { createProviderCache } from "../runtime/cache.js";
-import { createProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV, } from "../runtime/choice.js";
+import { createProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "../runtime/choice.js";
 import { createCredentialContext } from "../runtime/credential.js";
 import { createEnvContext } from "../runtime/env.js";
 import { executeOperation } from "../runtime/executor.js";
@@ -343,7 +343,14 @@ export function resolveProviderResolverIdentityScope(provider, affinityKey, cont
     });
 }
 function resolveOperationConnectionId(request) {
-    return request.connection?.id ?? request.connectionId;
+    // An empty string is a malformed identifier, not an identity: treat it as
+    // absent so it can never override a valid id or key a real scope. Requests
+    // without any usable id fall back to the documented missing-connection
+    // sentinel scope instead of scoping context/affinity/state under "".
+    return normalizeConnectionId(request.connection?.id) ?? normalizeConnectionId(request.connectionId);
+}
+function normalizeConnectionId(id) {
+    return id === "" ? undefined : id;
 }
 function resolveNativeProxyPolicy(provider) {
     if (typeof provider.proxy === "object")
@@ -376,7 +383,6 @@ function createProviderContext(provider, request, operationId, options, state =
     const env = createEnvContext([
         ...(provider.secrets?.map((secret) => secret.name) ?? []),
         PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
-        PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV,
     ]);
     const credential = createCredentialContext({
         allowedKeys: provider.credential?.keys,
@@ -498,7 +504,14 @@ function createFlowContextStore(allowedKeys, initialContext = {}) {
         },
     };
 }
-function createAuthFlowContext(provider, request, options, signal) {
+export function resolveAuthFlowProxyAffinityKey(provider, request) {
+    return (resolveOperationConnectionId(request) ??
+        request.externalRef ??
+        request.tenantId ??
+        request.providerId ??
+        provider.id);
+}
+function createAuthFlowContext(provider, request, options, state, signal) {
     const baseUrl = getProviderBaseUrl(provider);
     const stealthBaseUrl = getProviderStealthBaseUrl(provider);
     const stealthProfile = getProviderStealthProfile(provider);
@@ -507,11 +520,7 @@ function createAuthFlowContext(provider, request, options, signal) {
     const flowContextStore = createFlowContextStore(provider.context?.keys ?? Object.keys(contextData), contextData);
     const proxyClientOptions = {
         upstream: { proxy: provider.proxy },
-        affinityKey: request.connectionId ??
-            request.externalRef ??
-            request.tenantId ??
-            request.providerId ??
-            provider.id,
+        affinityKey: resolveAuthFlowProxyAffinityKey(provider, request),
     };
     const resolverIdentityScope = resolveProviderResolverIdentityScope(provider, proxyClientOptions.affinityKey, request.requestId);
     const stealthClientOptions = {
@@ -532,7 +541,7 @@ function createAuthFlowContext(provider, request, options, signal) {
     return {
         context: {
             flowId: request.flowId,
-            connectionId: request.connectionId,
+            connectionId: resolveOperationConnectionId(request),
             externalRef: request.externalRef,
             tenantId: request.tenantId ?? "",
             providerId: request.providerId ?? provider.id,
@@ -540,6 +549,7 @@ function createAuthFlowContext(provider, request, options, signal) {
                 ...proxyClientOptions,
                 ...(signal ? { signal } : {}),
             }),
+            state: state.forConnection(resolveOperationConnectionId(request)),
             stealth: stealthBaseUrl
                 ? capabilityModules.stealth
                     ? stealthProfile
@@ -1360,7 +1370,7 @@ function responseWithProviderTelemetry(response, proxyTelemetry) {
         statusText: response.statusText,
     });
 }
-async function handleAuthFlow(provider, request, route, options, signal) {
+async function handleAuthFlow(provider, request, route, options, state, signal) {
     const flow = provider.auth?.flow;
     if (!flow) {
         throw new ProviderError("Auth flow is not configured", {
@@ -1372,7 +1382,7 @@ async function handleAuthFlow(provider, request, route, options, signal) {
     // any flow code runs instead of at whatever point the ceremony first reads
     // the env. `abort` stays exempt: a user must always be able to cancel a
     // stranded flow even when provisioning is broken.
-    const { context, getPatch } = createAuthFlowContext(provider, request, options, signal);
+    const { context, getPatch } = createAuthFlowContext(provider, request, options, state, signal);
     try {
         if (route !== "abort") {
             assertRequiredSecretsPresent(provider, context.env);
@@ -1746,7 +1756,7 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "start", options, c.req.raw.signal);
+            const response = await handleAuthFlow(provider, body, "start", options, state, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "start", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }
@@ -1766,7 +1776,7 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "continue", options, c.req.raw.signal);
+            const response = await handleAuthFlow(provider, body, "continue", options, state, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "continue", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }
@@ -1786,7 +1796,7 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "poll", options, c.req.raw.signal);
+            const response = await handleAuthFlow(provider, body, "poll", options, state, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "poll", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }
@@ -1806,7 +1816,7 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "refresh", options, c.req.raw.signal);
+            const response = await handleAuthFlow(provider, body, "refresh", options, state, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "refresh", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }
@@ -1826,7 +1836,7 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "abort", options, c.req.raw.signal);
+            const response = await handleAuthFlow(provider, body, "abort", options, state, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "disconnect", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }

package/dist/testing/run.js

@@ -230,6 +230,7 @@ function createUpstreamContext(provider, operationName, upstreamStub) {
             id: `standard-test-${operationName}`,
             url: async () => currentUrl,
             title: async () => currentResponse?.text.match(/<title[^>]*>([^<]*)<\/title>/i)?.[1] ?? "",
+            userAgent: async () => String((await browserAction("userAgent")).data),
             content: async () => currentResponse?.text ?? "",
             evaluate: async (fn) => (await browserAction("evaluate", typeof fn === "string" ? fn : String(fn))).data,
             locator: (selector) => ({

package/dist/types.d.ts

@@ -1451,7 +1451,7 @@ export interface BrowserCookie {
     readonly secure: boolean;
     readonly sameSite?: "Strict" | "Lax" | "None";
 }
-export type BrowserResourceMethod = "GET" | "HEAD";
+export type BrowserResourceMethod = "GET" | "HEAD" | "POST";
 export type BrowserResourceRequest = {
     readonly url: string;
     readonly method: BrowserResourceMethod;
@@ -1460,6 +1460,8 @@ export type BrowserResourceRequest = {
 };
 export type BrowserResourceBody = Buffer | Uint8Array | ArrayBuffer | string;
 export type BrowserResourceDecision = {
+    readonly action: "continue";
+} | {
     readonly action: "fulfill";
     readonly status?: number;
     readonly headers?: Readonly<Record<string, string>>;
@@ -1475,10 +1477,18 @@ export type BrowserResourceRoute = {
 export type BrowserResourcePolicy = {
     readonly defaultAction?: "block";
     readonly allowedMethods?: readonly BrowserResourceMethod[];
+    /**
+     * Appends an enforcing CSP header to every renderable document response
+     * while the policy is active. Existing CSP headers are retained, so this
+     * can only further restrict the document.
+     */
+    readonly documentContentSecurityPolicy?: string;
     readonly routes: readonly BrowserResourceRoute[];
 };
 export interface BrowserPage extends BrowserFrame {
     close(): Promise<void>;
+    /** Returns the user agent used by this page's browser context. */
+    userAgent(): Promise<string>;
     /**
      * Reads the browser context's cookie jar, including httpOnly cookies.
      * Cookie expiry values are Unix seconds and are absent for session cookies.
@@ -1571,7 +1581,7 @@ export type ProviderChoiceExplicitParseResult = {
     readonly payload: Record<string, unknown>;
     /** Stable, opaque key for provider-owned idempotency records. */
     readonly replayKey: string;
-    /** Atomically claims a word token. Legacy managed tokens report unsupported. */
+    /** Atomically claims a word token. Inline tokens report unsupported. */
     consume(): Promise<ProviderChoiceConsumeResult>;
 } | {
     readonly status: "consumed";
@@ -1618,7 +1628,7 @@ export interface ProviderChoiceParseOptions {
     futureToleranceMs?: number;
     bind?: ProviderChoiceBindingOptions;
     storage?: ProviderChoiceStorageOptions;
-    /** Defaults to never, matching legacy managed-token parse semantics. */
+    /** Defaults to never, preserving reusable choice-token parse semantics. */
     consume?: ProviderChoiceConsumeMode;
 }
 export interface ProviderChoiceContext {
@@ -1739,6 +1749,18 @@ export interface FlowContext {
     tenantId: string;
     providerId: string;
     http: HttpClient;
+    /** Durable connection-scoped runtime state. Present when the host runtime
+     * supplies one; auth ceremonies must fail closed when absent rather than
+     * fall back to bypassable in-process storage.
+     *
+     * Scoped via `ProviderRuntimeState.forConnection`: requests that resolve no
+     * connection id (pre-connection ceremonies such as first-time logins) share
+     * the documented isolated missing-connection scope. That sharing is the
+     * intended semantic — it lets counters keyed by caller identity (e.g. a
+     * login email) persist across separate ceremonies for the same caller.
+     * Flows storing entries in that scope MUST key them by caller identity;
+     * un-keyed entries would be shared across all connectionless ceremonies. */
+    readonly state?: ProviderRuntimeState;
     /** Present when the selected runtime supplies native network capabilities. */
     readonly native?: NativeProviderContext;
     stealth: StealthClient;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.32",
+	"version": "2.2.0-beta.35",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -106,10 +106,11 @@
 		"lint": "biome lint .",
 		"lint:fix": "biome lint --write",
 		"lint:deprecated": "bun run scripts/lint-deprecated-usage.ts",
+		"lint:test-typesafety": "bun scripts/check-test-typesafety.ts",
 		"format": "biome format --write",
 		"type-check": "tsc --noEmit",
 		"test": "bun test",
-		"check": "bun run lint && bun run type-check && bun run lint:deprecated && bun run build",
+		"check": "bun run lint && bun run type-check && bun run lint:deprecated && bun run lint:test-typesafety && bun run build",
 		"pack:check": "bun run build && bun bin/apifuse-pack-check.ts",
 		"pack:smoke": "bun run build && bun bin/apifuse-pack-smoke.ts",
 		"pack:types": "bun run build && bun bin/apifuse-pack-types.ts",

package/src/error-resolution.ts

@@ -20,7 +20,6 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
 	"RUNTIME_UNSUPPORTED",
 	"PROVIDER_STATE_UNSUPPORTED",
 	"CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
-	"CHOICE_WORD_ISSUANCE_INVALID",
 	"CHOICE_STATE_PAYLOAD_TOO_LARGE",
 	"CHOICE_STATE_UNAVAILABLE",
 	"CHOICE_CONTEXT_REQUIRED",

package/src/index.ts

@@ -61,7 +61,6 @@ export {
 	createProviderChoiceContext,
 	createTestProviderChoiceContext,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
-	PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV,
 } from "./runtime/choice.js";
 export {
 	type CreateCredentialContextOptions,

package/src/provider.ts

@@ -56,7 +56,6 @@ export {
 	createProviderChoiceContext,
 	createTestProviderChoiceContext,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
-	PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV,
 } from "./runtime/choice.js";
 export {
 	APIFUSE_DESCRIPTION_KEY_META_KEY,

package/src/runtime/auth-flow.ts

@@ -6,6 +6,7 @@ import type {
 	FlowContext,
 	HttpClient,
 	OcrContext,
+	ProviderRuntimeState,
 	StealthClient,
 	SttContext,
 } from "../types.js";
@@ -59,6 +60,8 @@ export function createFlowContext(options: {
 	providerId: string;
 	connectionId?: string;
 	externalRef?: string;
+	/** Host-agnostic: callers pass an already-scoped runtime state, which this helper forwards verbatim. */
+	state?: ProviderRuntimeState;
 	allowedKeys: string[];
 	initialContext?: Record<string, unknown>;
 	ocr?: OcrContext;
@@ -71,6 +74,7 @@ export function createFlowContext(options: {
 		tenantId: options.tenantId,
 		providerId: options.providerId,
 		http: options.http,
+		state: options.state,
 		stealth: options.stealth,
 		env: options.env,
 		context: createScratchpad(options.allowedKeys, options.initialContext),