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

package/src/runtime/resolver-vendors/twocaptcha.ts

@@ -338,19 +338,23 @@ export function createTwoCaptchaResolverVendorAdapter(
 			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",
 				});
 			}
@@ -388,14 +392,49 @@ export function createTwoCaptchaResolverVendorAdapter(
 									...(identity ? { userAgent: identity.userAgent } : {}),
 									...(proxy ?? {}),
 								}
-							: {
-									type: proxy ? "RecaptchaV2Task" : "RecaptchaV2TaskProxyless",
+						: 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"),

package/src/runtime/resolver-vendors/types.ts

@@ -8,15 +8,18 @@ import type { TraceRecorder } from "../trace.js";
 
 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",
@@ -114,6 +117,7 @@ export type ResolverVendorUnavailableReason =
 	| "missing_credentials"
 	| "missing_proxy_identity"
 	| "missing_client_profile"
+	| "missing_challenge_input"
 	| "missing_transport"
 	| "allocation_exhausted"
 	| "transport_failure"
@@ -125,6 +129,8 @@ 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. */
@@ -134,6 +140,7 @@ type ResolverErrorOptions = {
 };
 
 export class ResolverVendorUnavailableError extends Error {
+	readonly missingFields?: readonly string[];
 	readonly upstreamHost?: string;
 	readonly phase?: string;
 	readonly round?: number;
@@ -143,8 +150,19 @@ export class ResolverVendorUnavailableError extends Error {
 		readonly reason: ResolverVendorUnavailableReason,
 		options: ResolverErrorOptions = {},
 	) {
-		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.name = "ResolverVendorUnavailableError";
+		if (missingFields !== undefined && missingFields.length > 0) {
+			this.missingFields = Object.freeze([...missingFields]);
+		}
 		if (options.cause !== undefined) {
 			this.cause = options.cause;
 		}

package/src/runtime/resolver.ts

@@ -71,7 +71,7 @@ type ResolvedResolverVendor =
 	| {
 			readonly vendor: Exclude<ProviderResolverVendor, "custom">;
 			readonly available: true;
-			readonly configuration: string;
+			readonly configuration: string | undefined;
 	  }
 	| {
 			readonly vendor: ProviderResolverVendor;
@@ -82,6 +82,7 @@ type ResolvedResolverVendor =
 type ResolverChainAttempt = {
 	readonly vendor: ProviderResolverVendor;
 	readonly reason: ResolverVendorUnavailableReason;
+	readonly missingFields?: readonly string[];
 	readonly cause?: {
 		readonly name: string;
 		readonly message: string;
@@ -184,13 +185,16 @@ export type ResolverInstrumentationMetadata = {
 };
 
 export type ResolverAdapterFactory = (
-	configuration: string,
+	configuration: string | undefined,
 	timeoutMs: number,
 	allowedHosts: readonly string[],
 ) => ResolverVendorAdapter;
 
 const resolverAdapterRegistry: Partial<Record<ProviderResolverVendor, ResolverAdapterFactory>> = {
 	"2captcha"(configuration, timeoutMs, allowedHosts) {
+		if (configuration === undefined) {
+			throw new Error("2captcha resolver adapter factory requires an API key");
+		}
 		return createTwoCaptchaResolverVendorAdapter({
 			allowedHosts,
 			apiKey: configuration,
@@ -344,10 +348,21 @@ function throwUnsupportedKind(kind: ProviderChallengeKind): never {
 }
 
 function throwExhausted(attempts: readonly ResolverChainAttempt[]): never {
-	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,
 	});
 }
@@ -470,6 +485,7 @@ function unavailableAttempt(error: ResolverVendorUnavailableError): ResolverChai
 	return {
 		vendor: error.vendor,
 		reason: error.reason,
+		...(error.missingFields ? { missingFields: [...error.missingFields] } : {}),
 		...(cause ? { cause } : {}),
 		...(upstreamHost ? { upstreamHost } : {}),
 		...(phase ? { phase } : {}),
@@ -481,6 +497,7 @@ function unavailableSpanAttributes(error: ResolverVendorUnavailableError): Recor
 	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,
@@ -914,6 +931,8 @@ function createResolverChainClient(options: {
 				} catch (error) {
 					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));
 				}
 			}
@@ -966,15 +985,20 @@ function resolveVendorAvailability(
 			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

package/src/server/serve-implementation.ts

@@ -39,7 +39,6 @@ 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 { createCredentialContext } from "../runtime/credential.js";
 import { createEnvContext } from "../runtime/env.js";
@@ -572,8 +571,18 @@ export function resolveProviderResolverIdentityScope(
 	});
 }
 
-function resolveOperationConnectionId(request: OperationRequest): string | undefined {
-	return request.connection?.id ?? request.connectionId;
+function resolveOperationConnectionId(
+	request: Pick<OperationRequest, "connection" | "connectionId">,
+): string | undefined {
+	// 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: string | undefined): string | undefined {
+	return id === "" ? undefined : id;
 }
 
 function resolveNativeProxyPolicy(provider: ProviderDefinition): ProviderProxyPolicy | undefined {
@@ -627,7 +636,6 @@ function createProviderContext(
 	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,
@@ -778,10 +786,27 @@ function createFlowContextStore(
 	};
 }
 
+export function resolveAuthFlowProxyAffinityKey(
+	provider: ProviderDefinition,
+	request: Pick<
+		AuthFlowRequest,
+		"connection" | "connectionId" | "externalRef" | "tenantId" | "providerId"
+	>,
+): string {
+	return (
+		resolveOperationConnectionId(request) ??
+		request.externalRef ??
+		request.tenantId ??
+		request.providerId ??
+		provider.id
+	);
+}
+
 function createAuthFlowContext(
 	provider: ProviderDefinition,
 	request: AuthFlowRequest,
 	options: ProviderServerRuntimeOptions,
+	state: ProviderRuntimeState,
 	signal?: AbortSignal,
 ): {
 	context: FlowContext;
@@ -798,12 +823,7 @@ function createAuthFlowContext(
 	);
 	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,
@@ -838,7 +858,7 @@ function createAuthFlowContext(
 	return {
 		context: {
 			flowId: request.flowId,
-			connectionId: request.connectionId,
+			connectionId: resolveOperationConnectionId(request),
 			externalRef: request.externalRef,
 			tenantId: request.tenantId ?? "",
 			providerId: request.providerId ?? provider.id,
@@ -846,6 +866,7 @@ function createAuthFlowContext(
 				...proxyClientOptions,
 				...(signal ? { signal } : {}),
 			}),
+			state: state.forConnection(resolveOperationConnectionId(request)),
 			stealth: stealthBaseUrl
 				? capabilityModules.stealth
 					? stealthProfile
@@ -2007,6 +2028,7 @@ async function handleAuthFlow(
 	request: AuthFlowRequest,
 	route: AuthRoute,
 	options: ProviderServerRuntimeOptions,
+	state: ProviderRuntimeState,
 	signal?: AbortSignal,
 ): Promise<Response | AuthFlowResponse> {
 	const flow = provider.auth?.flow;
@@ -2021,7 +2043,7 @@ async function handleAuthFlow(
 	// 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);
@@ -2542,7 +2564,14 @@ function createServerAppWithCapabilityModules(
 				.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,
@@ -2582,7 +2611,14 @@ function createServerAppWithCapabilityModules(
 				.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,
@@ -2622,7 +2658,14 @@ function createServerAppWithCapabilityModules(
 				.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,
@@ -2662,7 +2705,14 @@ function createServerAppWithCapabilityModules(
 				.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,
@@ -2702,7 +2752,14 @@ function createServerAppWithCapabilityModules(
 				.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,

package/src/testing/run.ts

@@ -377,6 +377,7 @@ function createUpstreamContext(
 			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 <T>(fn: string | (() => T)) =>
 				(await browserAction("evaluate", typeof fn === "string" ? fn : String(fn))).data as T,

package/src/types.ts

@@ -1757,7 +1757,7 @@ export interface BrowserCookie {
 	readonly sameSite?: "Strict" | "Lax" | "None";
 }
 
-export type BrowserResourceMethod = "GET" | "HEAD";
+export type BrowserResourceMethod = "GET" | "HEAD" | "POST";
 
 export type BrowserResourceRequest = {
 	readonly url: string;
@@ -1769,6 +1769,9 @@ export type BrowserResourceRequest = {
 export type BrowserResourceBody = Buffer | Uint8Array | ArrayBuffer | string;
 
 export type BrowserResourceDecision =
+	| {
+			readonly action: "continue";
+		}
 	| {
 			readonly action: "fulfill";
 			readonly status?: number;
@@ -1793,11 +1796,19 @@ 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.
@@ -1905,7 +1916,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>;
 	  }
 	| {
@@ -1961,7 +1972,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;
 }
 
@@ -2115,6 +2126,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;