@apifuse/provider-sdk 2.2.0-beta.33 → 2.2.0-beta.36

package/src/runtime/choice.ts

@@ -263,10 +263,9 @@ export function createProviderChoiceContext(
 			);
 		}
 
-		// Legacy encrypted-envelope compatibility fallback. Removal is gated on
-		// the last legacy mint plus the maximum issued TTL; see ADR 0006.
-		// A structurally valid word token returns above, so lookup, expiry,
-		// consumption, and binding failures can never enter this branch.
+		// Inline choices continue to use the encrypted envelope. A structurally
+		// valid word token returns above, so lookup, expiry, consumption, and
+		// binding failures can never enter this branch.
 		try {
 			const [actualPrefix, tokenKid, encodedIv, encryptedPayload, authTag, signature] =
 				parseManagedChoiceTokenParts(parseOptions.token);
@@ -321,17 +320,14 @@ export function createProviderChoiceContext(
 					required: true,
 				}),
 			});
-			const payload = isServerChoiceHandlePayload(envelope.payload)
-				? parseLegacyServerStoredChoice({
-						handle: envelope.payload,
-						storage: parseOptions.storage,
-						contextState: options.state,
-					})
-				: envelope.payload;
+			if (isServerChoiceHandlePayload(envelope.payload)) {
+				throw wordChoiceNotFoundError();
+			}
+			const payload = envelope.payload;
 			const parsed =
 				consumeMode === "explicit"
 					? Promise.resolve(payload).then((resolvedPayload) =>
-							createLegacyExplicitParseResult({
+							createInlineExplicitParseResult({
 								payload: resolvedPayload,
 								replayKey: digestChoiceReplayKey(parseOptions.token),
 								onConsume: () =>
@@ -471,7 +467,7 @@ function emitChoiceTelemetry(
 	}
 }
 
-function createLegacyExplicitParseResult(options: {
+function createInlineExplicitParseResult(options: {
 	readonly payload: ProviderChoiceTokenPayload;
 	readonly replayKey: string;
 	readonly onConsume: () => void;
@@ -656,14 +652,6 @@ async function parseWordServerStoredChoice(options: {
 		) {
 			throw wordChoiceNotFoundError();
 		}
-		assertFreshProviderChoiceIssuedAt(record.issued_at_ms, {
-			ttlMs:
-				options.parseOptions.ttlMs != null
-					? Math.min(options.parseOptions.ttlMs, record.ttl_ms)
-					: record.ttl_ms,
-			nowMs: options.parseOptions.nowMs,
-			futureToleranceMs: options.parseOptions.futureToleranceMs,
-		});
 		assertPayloadDigestMatches({
 			actual: digestChoicePayload(serializeChoicePayload(record.payload)),
 			expected: record.payload_digest,
@@ -685,6 +673,31 @@ async function parseWordServerStoredChoice(options: {
 		}
 		throw error;
 	}
+	// Freshness is classified last, reachable only after every identity,
+	// integrity, and binding check above has passed (ADR 0006, amended
+	// 2026-08-20): a caller that proved the record's binding may observe the
+	// canonical stale error, while an unbound record keeps the collapsed
+	// not-found error so expiry never becomes an existence signal for
+	// guessable tokens.
+	try {
+		assertFreshProviderChoiceIssuedAt(record.issued_at_ms, {
+			ttlMs:
+				options.parseOptions.ttlMs != null
+					? Math.min(options.parseOptions.ttlMs, record.ttl_ms)
+					: record.ttl_ms,
+			nowMs: options.parseOptions.nowMs,
+			futureToleranceMs: options.parseOptions.futureToleranceMs,
+		});
+	} catch (error) {
+		const recordIsBound = Boolean(
+			record.binding?.connection_hash || record.binding?.credential_hash,
+		);
+		if (recordIsBound && error instanceof ProviderChoiceTokenError && error.reason === "stale") {
+			throw error;
+		}
+		if (error instanceof ProviderChoiceTokenError) throw wordChoiceNotFoundError();
+		throw error;
+	}
 
 	const consumeMode = options.parseOptions.consume ?? "never";
 	if (record.status === "consumed") {
@@ -759,53 +772,6 @@ async function consumeWordServerStoredChoice(options: {
 	}
 }
 
-async function parseLegacyServerStoredChoice(options: {
-	readonly handle: ServerChoiceHandlePayload;
-	readonly storage?: ProviderChoiceStorageOptions;
-	readonly contextState?: ProviderRuntimeState;
-}): Promise<ProviderChoiceTokenPayload> {
-	const storage = resolveParseStorage(options.storage);
-	const namespace = resolveChoiceStateNamespace({
-		storage,
-		contextState: options.contextState,
-	});
-	// Reading a server-stored choice back deserializes a persisted value. A
-	// corrupt/undecodable value would otherwise surface as a raw JSON.parse
-	// SyntaxError (or another unexpected throwable) that escapes the choice error
-	// taxonomy, gets masked as internal_error 500, and is treated as retryable by
-	// the hub -> reservation restart loop (2026-07-22 catchtable RCA, candidate A).
-	// Convert any non-branded throwable into a branded invalid_payload so it maps
-	// to a clean, non-retryable 400. Branded ProviderChoiceTokenError and genuine
-	// ProviderError (e.g. Redis-unavailable / state-unavailable) pass through so
-	// their category/retryable semantics are preserved.
-	let record: StateValue<ProviderChoiceTokenPayload> | null;
-	try {
-		record = await namespace.get<ProviderChoiceTokenPayload>(
-			optionsStateKey(options.handle.state_id),
-		);
-	} catch (error) {
-		if (error instanceof ProviderChoiceTokenError || isProviderError(error)) {
-			throw error;
-		}
-		throw new ProviderChoiceTokenError(
-			"invalid_payload",
-			"Provider choice token state payload could not be decoded.",
-		);
-	}
-	if (!record) {
-		throw new ProviderChoiceTokenError(
-			"invalid_payload",
-			"Provider choice token state payload is missing.",
-		);
-	}
-	const serializedPayload = serializeChoicePayload(record.value);
-	assertPayloadDigestMatches({
-		actual: digestChoicePayload(serializedPayload),
-		expected: options.handle.payload_digest,
-	});
-	return record.value;
-}
-
 function generateChoiceWordSequence(wordCount: number): string {
 	return Array.from({ length: wordCount }, () =>
 		choiceWordAt(randomInt(CHOICE_WORDLIST_SIZE)),

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

@@ -242,7 +242,7 @@ async function solveInPage(
 		},
 		async () => {
 			const userAgent = await raceWithAbort(
-				() => page.evaluate<string>("navigator.userAgent"),
+				() => page.userAgent(),
 				signal,
 			);
 			await raceWithAbort(() => page.goto(pageUrl), signal);

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 === "aws_waf" &&
-				(!challenge.siteKey?.trim() ||
-					!challenge.captchaScript?.trim() ||
-					!challenge.context?.trim() ||
-					!challenge.iv?.trim())
-			) {
-				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 === "recaptcha_v3" && challenge.minScore === undefined) {
-				throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
+				throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "missing_challenge_input", {
+					missingFields: ["minScore"],
 					phase: "create_task",
 				});
 			}

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

@@ -117,6 +117,7 @@ export type ResolverVendorUnavailableReason =
 	| "missing_credentials"
 	| "missing_proxy_identity"
 	| "missing_client_profile"
+	| "missing_challenge_input"
 	| "missing_transport"
 	| "allocation_exhausted"
 	| "transport_failure"
@@ -128,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. */
@@ -137,6 +140,7 @@ type ResolverErrorOptions = {
 };
 
 export class ResolverVendorUnavailableError extends Error {
+	readonly missingFields?: readonly string[];
 	readonly upstreamHost?: string;
 	readonly phase?: string;
 	readonly round?: number;
@@ -146,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

@@ -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;
@@ -347,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,
 	});
 }
@@ -473,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 } : {}),
@@ -484,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,
@@ -917,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));
 				}
 			}

package/src/server/serve-implementation.ts

@@ -571,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 {
@@ -776,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;
@@ -796,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,
@@ -836,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,
@@ -844,6 +866,7 @@ function createAuthFlowContext(
 				...proxyClientOptions,
 				...(signal ? { signal } : {}),
 			}),
+			state: state.forConnection(resolveOperationConnectionId(request)),
 			stealth: stealthBaseUrl
 				? capabilityModules.stealth
 					? stealthProfile
@@ -2005,6 +2028,7 @@ async function handleAuthFlow(
 	request: AuthFlowRequest,
 	route: AuthRoute,
 	options: ProviderServerRuntimeOptions,
+	state: ProviderRuntimeState,
 	signal?: AbortSignal,
 ): Promise<Response | AuthFlowResponse> {
 	const flow = provider.auth?.flow;
@@ -2019,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);
@@ -2540,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,
@@ -2580,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,
@@ -2620,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,
@@ -2660,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,
@@ -2700,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

@@ -1807,6 +1807,8 @@ export type BrowserResourcePolicy = {
 
 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.
@@ -1914,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>;
 	  }
 	| {
@@ -1970,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;
 }
 
@@ -2124,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;