@apifuse/provider-sdk 2.2.0-beta.28 → 2.2.0-beta.29

package/src/runtime/browser.ts

@@ -290,7 +290,13 @@ function formatExpression<T>(fn: string | (() => T)): string {
 
 function toLaunchOptions(options: BrowserClientOptions): LaunchOptions {
 	return {
-		args: options.extraArgs,
+		// `extraArgs` is optional, but playwright-extra's stealth evasions mutate
+		// `options.args` unguarded (navigator.webdriver does
+		// `options.args.findIndex(...)` in beforeLaunch). Forwarding `undefined`
+		// therefore crashes every stealth launch that omits extraArgs with
+		// "TypeError: undefined is not an object (evaluating 'options.args.findIndex')".
+		// Always hand the launcher a concrete array.
+		args: options.extraArgs ?? [],
 		executablePath: options.executablePath,
 		headless: options.headless ?? true,
 		proxy: options.proxy ? { server: options.proxy } : undefined,
@@ -975,6 +981,20 @@ function getCdpExecutionContext(params: unknown): {
 	};
 }
 
+function getCdpDestroyedExecutionContextId(params: unknown): number | undefined {
+	if (!isRecord(params)) {
+		return undefined;
+	}
+
+	return typeof params.executionContextId === "number"
+		? params.executionContextId
+		: undefined;
+}
+
+function isMissingExecutionContextError(error: unknown): boolean {
+	return error instanceof Error && /\b(?:cannot|failed to) find context\b/i.test(error.message);
+}
+
 class CdpBrowserLocator implements BrowserLocator {
 	constructor(
 		private readonly frame: {
@@ -1120,7 +1140,20 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 	async evaluateInFrame<T>(frameId: string, fn: string | (() => T)): Promise<T> {
 		await this.initialize();
 		const contextId = await this.getFrameExecutionContextId(frameId);
-		return await this.evaluateWithContext<T>(fn, contextId);
+		try {
+			return await this.evaluateWithContext<T>(fn, contextId);
+		} catch (error) {
+			if (!isMissingExecutionContextError(error)) {
+				throw error;
+			}
+
+			if (this.frameExecutionContexts.get(frameId) === contextId) {
+				this.frameExecutionContexts.delete(frameId);
+			}
+
+			const refreshedContextId = await this.getFrameExecutionContextId(frameId);
+			return await this.evaluateWithContext<T>(fn, refreshedContextId);
+		}
 	}
 
 	async waitForSelectorInFrame(
@@ -1384,6 +1417,21 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 				this.frameExecutionContexts.set(context.frameId, context.id);
 			}
 		});
+		this.pageClient.on("Runtime.executionContextDestroyed", (params) => {
+			const destroyedContextId = getCdpDestroyedExecutionContextId(params);
+			if (destroyedContextId === undefined) {
+				return;
+			}
+
+			for (const [frameId, contextId] of this.frameExecutionContexts) {
+				if (contextId === destroyedContextId) {
+					this.frameExecutionContexts.delete(frameId);
+				}
+			}
+		});
+		this.pageClient.on("Runtime.executionContextsCleared", () => {
+			this.frameExecutionContexts.clear();
+		});
 		await this.pageClient.send("Page.enable");
 		await this.pageClient.send("Runtime.enable");
 		this.initialized = true;

package/src/runtime/proxy-telemetry.ts

@@ -4,6 +4,7 @@ import type {
 	ProxyProtocol,
 	ProxyResolutionTelemetryEvent,
 	ProxyTelemetrySink,
+	ProxyUserAgentSource,
 	ProxyVendorFailoverTelemetryEvent,
 	ProxyVendorName,
 	SmartproxyAllocatorBodyClass,
@@ -15,6 +16,7 @@ type ProviderTelemetryHeader = {
 	v: 1;
 	proxy?: {
 		provider: ProxyVendorName;
+		userAgentSource?: ProxyUserAgentSource;
 		protocol?: ProxyProtocol;
 		cacheStatus: ProxyCacheStatus;
 		cacheHit: boolean;
@@ -98,6 +100,7 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 	recordProxyResolution(event: ProxyResolutionTelemetryEvent): void {
 		this.#events.push({
 			provider: event.provider,
+			...(event.userAgentSource ? { userAgentSource: event.userAgentSource } : {}),
 			...(event.protocol ? { protocol: event.protocol } : {}),
 			cacheStatus: event.cacheStatus,
 			cacheHit: event.cacheHit,
@@ -175,6 +178,7 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 		const aggregate = rest.reduce<ProxyResolutionTelemetryEvent>(
 			(acc, event) => ({
 				provider: event.provider,
+				userAgentSource: event.userAgentSource ?? acc.userAgentSource,
 				cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
 				cacheHit: acc.cacheHit && event.cacheHit,
 				resolutionMs: acc.resolutionMs + event.resolutionMs,
@@ -196,6 +200,7 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 			v: 1,
 			proxy: {
 				provider: serving.provider,
+				...(aggregate.userAgentSource ? { userAgentSource: aggregate.userAgentSource } : {}),
 				...(serving.protocol ? { protocol: serving.protocol } : {}),
 				cacheStatus: aggregate.cacheStatus,
 				cacheHit: aggregate.cacheHit,

package/src/runtime/resolver-public.ts

@@ -0,0 +1,18 @@
+export {
+	APIFUSE__CDP_POOL__URL,
+	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
+	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
+	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+	APIFUSE__RESOLVER__TIMEOUT_MS,
+	bindResolverSignal,
+	createResolverClient,
+	createResolverClientFromEnv,
+	createUnsupportedResolverClient,
+	DEFAULT_RESOLVER_TIMEOUT_MS,
+	invalidateResolverSolution,
+	RESOLVER_ADAPTER_REGISTRY,
+	RESOLVER_INSTRUMENTATION_METADATA,
+	type ResolverAdapterFactory,
+	type ResolverInstrumentationMetadata,
+	type ResolverRuntimeOptions,
+} from "./resolver.js";

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

@@ -316,8 +316,9 @@ export function createBrowserResolverVendorAdapter(
 		},
 
 		async solve(challenge, identity, callerSignal, traceRecorder) {
-			void identity;
-			if (!options.cdpUrl?.trim()) {
+			const cdpUrl = options.cdpUrl?.trim();
+			const proxyUrl = identity?.proxyUrl;
+			if (!cdpUrl && proxyUrl === undefined) {
 				throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "missing_credentials");
 			}
 			if (!isSupportedKind(challenge.kind)) {
@@ -326,6 +327,14 @@ export function createBrowserResolverVendorAdapter(
 			assertResolverHostAllowed(challenge.pageUrl, options.allowedHosts);
 			const challengeKind = challenge.kind;
 			callerSignal.throwIfAborted();
+			if (proxyUrl !== undefined && proxyUrl.length === 0) {
+				throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "missing_proxy_identity");
+			}
+			if (cdpUrl && proxyUrl !== undefined) {
+				// The current pool acquire protocol cannot bind a proxy to its browser context.
+				// Refuse so the chain can choose a vendor that can honor the resolved identity.
+				throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "not_implemented");
+			}
 
 			const solveController = new AbortController();
 			const onCallerAbort = () => solveController.abort(abortReason(callerSignal));
@@ -340,8 +349,9 @@ export function createBrowserResolverVendorAdapter(
 			try {
 				client = createClient({
 					allowedHosts: [...options.allowedHosts],
-					cdpUrl: options.cdpUrl.trim(),
-					requireCdpPool: true,
+					cdpUrl: cdpUrl ?? "",
+					...(proxyUrl === undefined ? {} : { proxy: proxyUrl }),
+					requireCdpPool: cdpUrl !== undefined,
 				});
 				const contextOperation = client.withIsolatedContext(async (page) => {
 					handlerEntered = true;

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

@@ -4,6 +4,7 @@ import { assertResolverHostAllowed } from "./hosts.js";
 import {
 	type ResolverIdentity,
 	type ResolverVendorAdapter,
+	ResolverChallengeVerdictError,
 	ResolverVendorUnavailableError,
 	resolverVendorSupports,
 } from "./types.js";
@@ -64,10 +65,53 @@ function abortReason(signal: AbortSignal): unknown {
 	return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
 }
 
+function containsSensitiveValue(value: unknown, sensitiveValues: readonly string[]): boolean {
+	const secrets = sensitiveValues.filter((secret) => secret.length > 0);
+	if (secrets.length === 0) return false;
+	const seen = new Set<object>();
+
+	const inspect = (candidate: unknown): boolean => {
+		if (typeof candidate === "string") {
+			return secrets.some((secret) => candidate.includes(secret));
+		}
+		if (
+			candidate === null ||
+			(typeof candidate !== "object" && typeof candidate !== "function")
+		) {
+			return false;
+		}
+		if (seen.has(candidate)) return false;
+		seen.add(candidate);
+
+		try {
+			for (const property of Reflect.ownKeys(candidate)) {
+				if (typeof property === "string" && inspect(property)) return true;
+				const descriptor = Object.getOwnPropertyDescriptor(candidate, property);
+				if (!descriptor) return true;
+				if ("value" in descriptor && inspect(descriptor.value)) return true;
+				if (descriptor.get !== undefined || descriptor.set !== undefined) return true;
+			}
+		} catch {
+			return true;
+		}
+		return false;
+	};
+
+	return inspect(value);
+}
+
+function safeCauseOptions(
+	error: unknown,
+	sensitiveValues: readonly string[],
+): { readonly cause?: unknown } {
+	return containsSensitiveValue(error, sensitiveValues) ? {} : { cause: error };
+}
+
 function raceWithAbort<T>(
 	operation: () => Promise<T>,
 	signal: AbortSignal,
 	phase?: TwoCaptchaOperationPhase,
+	sensitiveValues: readonly string[] = [],
 ): Promise<T> {
 	if (signal.aborted) return Promise.reject(abortReason(signal));
 
@@ -91,7 +135,7 @@ function raceWithAbort<T>(
 				}
 				reject(
 					new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
-						cause: error,
+						...safeCauseOptions(error, sensitiveValues),
 						phase,
 					}),
 				);
@@ -158,10 +202,17 @@ function isAllocationExhausted(payload: JsonRecord): boolean {
 	);
 }
 
+function isNegativeVerdict(payload: JsonRecord): boolean {
+	return errorText(payload, "errorCode").toLowerCase() === "error_captcha_unsolvable";
+}
+
 function unavailableForPayload(
 	payload: JsonRecord,
 	phase: TwoCaptchaOperationPhase,
-): ResolverVendorUnavailableError {
+): ResolverVendorUnavailableError | ResolverChallengeVerdictError {
+	if (isNegativeVerdict(payload)) {
+		return new ResolverChallengeVerdictError(TWOCAPTCHA_VENDOR_ID, "solve_failed");
+	}
 	return new ResolverVendorUnavailableError(
 		TWOCAPTCHA_VENDOR_ID,
 		isAllocationExhausted(payload) ? "allocation_exhausted" : "transport_failure",
@@ -175,6 +226,7 @@ async function postJson(
 	body: JsonRecord,
 	signal: AbortSignal,
 	phase: TwoCaptchaOperationPhase,
+	sensitiveValues: readonly string[],
 ): Promise<{ readonly ok: boolean; readonly payload: JsonRecord }> {
 	const response = await raceWithAbort(
 		() =>
@@ -187,6 +239,7 @@ async function postJson(
 			}),
 		signal,
 		phase,
+		sensitiveValues,
 	);
 
 	let responseText: string;
@@ -222,9 +275,12 @@ function taskIdFrom(payload: JsonRecord): string | number | undefined {
 	return typeof taskId === "string" || typeof taskId === "number" ? taskId : undefined;
 }
 
-function tokenFrom(payload: JsonRecord): string | undefined {
+function tokenFrom(payload: JsonRecord, challenge: ProviderChallenge): string | undefined {
 	const solution = payload.solution;
 	if (!isJsonRecord(solution)) return undefined;
+	if (challenge.kind === "aws_waf") {
+		return typeof solution.existing_token === "string" ? solution.existing_token : undefined;
+	}
 	if (typeof solution.gRecaptchaResponse === "string") return solution.gRecaptchaResponse;
 	return typeof solution.token === "string" ? solution.token : undefined;
 }
@@ -282,8 +338,18 @@ 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") {
-				// AWS WAF remains deferred because its challenge variant has no required site key.
+			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" &&
+				(!challenge.siteKey?.trim() ||
+					!challenge.captchaScript?.trim() ||
+					!challenge.context?.trim() ||
+					!challenge.iv?.trim())
+			) {
 				throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "not_implemented", {
 					phase: "create_task",
 				});
@@ -310,22 +376,33 @@ export function createTwoCaptchaResolverVendorAdapter(
 
 			try {
 				const createTask = async () => {
+					const task =
+						challenge.kind === "aws_waf"
+							? {
+									type: proxy ? "AmazonTask" : "AmazonTaskProxyless",
+									websiteURL: challenge.pageUrl,
+									websiteKey: challenge.siteKey,
+									captchaScript: challenge.captchaScript,
+									context: challenge.context,
+									iv: challenge.iv,
+									...(identity ? { userAgent: identity.userAgent } : {}),
+									...(proxy ?? {}),
+								}
+							: {
+									type: proxy ? "RecaptchaV2Task" : "RecaptchaV2TaskProxyless",
+									websiteURL: challenge.pageUrl,
+									websiteKey: challenge.siteKey,
+									isInvisible: false,
+									...(identity ? { userAgent: identity.userAgent } : {}),
+									...(proxy ?? {}),
+								};
 					const createResult = await postJson(
 						fetchImpl,
 						endpoint(baseUrl, "createTask"),
-						{
-							clientKey: apiKey,
-							task: {
-								type: proxy ? "RecaptchaV2Task" : "RecaptchaV2TaskProxyless",
-								websiteURL: challenge.pageUrl,
-								websiteKey: challenge.siteKey,
-								isInvisible: false,
-								...(identity ? { userAgent: identity.userAgent } : {}),
-								...(proxy ?? {}),
-							},
-						},
+						{ clientKey: apiKey, task },
 						solveController.signal,
 						phase,
+						[apiKey],
 					);
 					const taskId = taskIdFrom(createResult.payload);
 					if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
@@ -359,6 +436,7 @@ export function createTwoCaptchaResolverVendorAdapter(
 							{ clientKey: apiKey, taskId },
 							solveController.signal,
 							phase,
+							[apiKey],
 						);
 						if (!pollResult.ok || pollResult.payload.errorId !== 0) {
 							throw unavailableForPayload(pollResult.payload, phase);
@@ -372,7 +450,7 @@ export function createTwoCaptchaResolverVendorAdapter(
 							);
 						}
 
-						const token = tokenFrom(pollResult.payload);
+						const token = tokenFrom(pollResult.payload, challenge);
 						if (!token?.trim()) {
 							throw new ResolverVendorUnavailableError(
 								TWOCAPTCHA_VENDOR_ID,
@@ -403,9 +481,14 @@ export function createTwoCaptchaResolverVendorAdapter(
 						phase,
 					});
 				}
-				if (error instanceof ResolverVendorUnavailableError) throw error;
+				if (
+					error instanceof ResolverVendorUnavailableError ||
+					error instanceof ResolverChallengeVerdictError
+				) {
+					throw error;
+				}
 				throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
-					cause: error,
+					...safeCauseOptions(error, [apiKey]),
 					phase,
 				});
 			} finally {

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

@@ -113,13 +113,14 @@ export interface ResolverVendorAdapter {
 export type ResolverVendorUnavailableReason =
 	| "missing_credentials"
 	| "missing_proxy_identity"
+	| "missing_client_profile"
 	| "missing_transport"
 	| "allocation_exhausted"
 	| "transport_failure"
 	| "timeout"
 	| "not_implemented";
 
-export type ResolverChallengeVerdictReason = "human_puzzle";
+export type ResolverChallengeVerdictReason = "human_puzzle" | "solve_failed";
 
 type ResolverErrorOptions = {
 	/** Raw cause; adapters must not place bodies, cookies, headers, credentials, or proxy URLs here. */
@@ -159,7 +160,11 @@ export class ResolverChallengeVerdictError extends Error {
 		readonly reason: ResolverChallengeVerdictReason,
 		options: ResolverErrorOptions = {},
 	) {
-		super(`Resolver vendor ${vendor} returned a challenge verdict: ${reason}`);
+		super(
+			reason === "solve_failed"
+				? `Resolver vendor ${vendor} attempted the challenge but did not solve it`
+				: `Resolver vendor ${vendor} returned a challenge verdict: ${reason}`,
+		);
 		this.name = "ResolverChallengeVerdictError";
 		if (options.cause !== undefined) {
 			this.cause = options.cause;

package/src/runtime/resolver.ts

@@ -1,6 +1,12 @@
 import { createHash } from "node:crypto";
 
+import {
+	resolveProxyConfigAsync,
+	type ProxyResolutionOptions,
+	type ProxyUserAgentSource,
+} from "../config/loader.js";
 import { ProviderError } from "../errors.js";
+import { getStealthProfile } from "../stealth/profiles.js";
 import type {
 	ChallengeSolution,
 	ProviderCache,
@@ -42,6 +48,7 @@ import {
 	APIFUSE__RESOLVER__TIMEOUT_MS,
 	DEFAULT_RESOLVER_TIMEOUT_MS,
 } from "./resolver-config.js";
+import { DEFAULT_PROFILE } from "./stealth.js";
 import type { TraceRecorder } from "./trace.js";
 
 export {
@@ -94,8 +101,14 @@ type ResolverChainClient = ResolverContext & {
 export interface ResolverRuntimeOptions {
 	readonly allowedHosts?: readonly string[];
 	readonly cache?: ProviderCache;
-	/** Provider-declared proxy intent. The SDK never accepts a caller-built identity. */
-	readonly proxyMode?: ProviderProxyMode;
+	/** Inputs for SDK-owned lazy proxy resolution. The SDK never accepts a caller-built identity. */
+	readonly proxyIntent?: {
+		readonly mode: ProviderProxyMode;
+		readonly upstream: NonNullable<ProxyResolutionOptions["upstream"]>;
+		readonly affinityKey?: ProxyResolutionOptions["affinityKey"];
+		readonly telemetry?: ProxyResolutionOptions["telemetry"];
+		readonly userAgent?: string;
+	};
 	/** Server-owned context/proxy scope used only for identity-bound cache entries. */
 	readonly identityScope?: string;
 	/** SDK-owned transport already bound to the resolved proxy lease and client profile. */
@@ -212,6 +225,24 @@ export function swapResolverAdapterFactoryForTests(
 	};
 }
 
+let resolveDefaultResolverUserAgent: () => string | undefined = () =>
+	getStealthProfile(DEFAULT_PROFILE).userAgent;
+
+/** Internal test seam; deliberately not re-exported from the package root. */
+export function swapResolverDefaultUserAgentForTests(
+	resolver: (() => string | undefined) | undefined,
+): () => void {
+	const original = resolveDefaultResolverUserAgent;
+	resolveDefaultResolverUserAgent =
+		resolver ?? (() => getStealthProfile(DEFAULT_PROFILE).userAgent);
+	let restored = false;
+	return () => {
+		if (restored) return;
+		restored = true;
+		resolveDefaultResolverUserAgent = original;
+	};
+}
+
 // This is the sole allowlist for declared vendors whose registry entry may be absent.
 // Remove a vendor here when its adapter is registered.
 const KNOWN_UNIMPLEMENTED_RESOLVER_VENDORS: ReadonlySet<ProviderResolverVendor> = new Set([
@@ -340,6 +371,7 @@ function adapterRequiresTransport(
 function sanitizeDiagnosticUrl(rawUrl: string): string {
 	try {
 		const parsed = new URL(rawUrl);
+		if (parsed.username || parsed.password) return "[REDACTED_PROXY_URL]";
 		return `${parsed.protocol}//${parsed.host}`;
 	} catch {
 		return "[REDACTED_URL]";
@@ -355,7 +387,12 @@ function sanitizeCauseMessage(message: string): string {
 		.split(/\s+/)
 		.filter(Boolean)
 		.map((token) => {
-			if (token === "[REDACTED]" || /^[a-z][a-z\d+.-]*:\/\/[^\s]+$/i.test(token)) return token;
+			if (
+				token === "[REDACTED]" ||
+				token === "[REDACTED_PROXY_URL]" ||
+				/^[a-z][a-z\d+.-]*:\/\/[^\s]+$/i.test(token)
+			)
+				return token;
 			const word = token.replace(/^[^a-z\d]+|[^a-z\d]+$/gi, "");
 			return word.length > 0 &&
 				word.length <= 32 &&
@@ -704,13 +741,58 @@ export async function invalidateResolverSolution(
 	});
 }
 
+async function resolveResolverIdentity(
+	proxyIntent: NonNullable<ResolverRuntimeOptions["proxyIntent"]>,
+): Promise<{
+	readonly identity?: ResolverIdentity;
+	readonly unavailableReason?: ResolverVendorUnavailableReason;
+	readonly userAgentSource?: ProxyUserAgentSource;
+}> {
+	const userAgentSource: ProxyUserAgentSource = proxyIntent.userAgent ? "declared" : "defaulted";
+	let proxyUrl: string | undefined;
+	try {
+		const resolved = await resolveProxyConfigAsync({
+			upstream: proxyIntent.upstream,
+			affinityKey: proxyIntent.affinityKey,
+			telemetry: proxyIntent.telemetry
+				? {
+						...proxyIntent.telemetry,
+						recordProxyResolution(event) {
+							proxyIntent.telemetry?.recordProxyResolution({
+								...event,
+								userAgentSource,
+							});
+						},
+					}
+				: undefined,
+		});
+		proxyUrl = resolved.url;
+		if (!proxyUrl) return { unavailableReason: "missing_proxy_identity", userAgentSource };
+	} catch {
+		// Lease failures contain infrastructure detail that must not cross the resolver
+		// boundary. A required policy is classified by the existing fail-closed guard.
+		return { unavailableReason: "missing_proxy_identity", userAgentSource };
+	}
+
+	try {
+		const userAgent = proxyIntent.userAgent || resolveDefaultResolverUserAgent();
+		if (!userAgent) return { unavailableReason: "missing_client_profile", userAgentSource };
+		return {
+			identity: { proxyUrl, userAgent },
+			userAgentSource,
+		};
+	} catch {
+		return { unavailableReason: "missing_client_profile", userAgentSource };
+	}
+}
+
 function createResolverChainClient(options: {
 	readonly kinds: readonly ProviderChallengeKind[];
 	readonly entries: readonly ResolverChainEntry[];
 	readonly unavailableReason?: string;
 	readonly cache?: ProviderCache;
 	readonly identity?: ResolverIdentity;
-	readonly proxyMode?: ProviderProxyMode;
+	readonly proxyIntent?: ResolverRuntimeOptions["proxyIntent"];
 	readonly identityScope?: string;
 	readonly transport?: ResolverVendorTransport;
 	readonly createTransport?: ResolverRuntimeOptions["createTransport"];
@@ -735,16 +817,21 @@ function createResolverChainClient(options: {
 			const supportingEntries = options.entries.filter((entry) => entry.supports(challenge.kind));
 			if (supportingEntries.length === 0) throwUnsupportedKind(challenge.kind);
 			signal.throwIfAborted();
-			// A required proxy policy is checked before the cache. Solutions minted under a
-			// previous release are shared and long-lived, so consulting the cache first would
-			// keep reporting success without a proxy identity until every old entry expired.
+			const identityResolution = options.proxyIntent
+				? await resolveResolverIdentity(options.proxyIntent)
+				: { identity: options.identity };
+			const identity = identityResolution.identity;
+			signal.throwIfAborted();
+			// Resolve a required proxy lease before consulting the cache. Solutions minted
+			// under a previous release are shared and long-lived, but a portable cached token
+			// must not bypass the upstream admission policy when no lease can be resolved.
 			const requiredProxyIdentityMissing =
-				options.proxyMode === "required" && options.identity === undefined;
+				options.proxyIntent?.mode === "required" && identity === undefined;
 			if (requiredProxyIdentityMissing) {
 				throwExhausted(
 					supportingEntries.map((entry) => ({
 						vendor: entry.id,
-						reason: "missing_proxy_identity" as const,
+						reason: identityResolution.unavailableReason ?? "missing_proxy_identity",
 					})),
 				);
 			}
@@ -752,12 +839,11 @@ function createResolverChainClient(options: {
 				const cached = await findCachedSolution(
 					options.cache,
 					challenge,
-					options.identity,
+					identity,
 					options.identityScope,
 				);
 				if (cached) return cached;
 			}
-
 			const attempts: ResolverChainAttempt[] = [];
 			for (const entry of supportingEntries) {
 				const adapter = entry.createAdapter();
@@ -778,7 +864,7 @@ function createResolverChainClient(options: {
 						const transport = unrestrictedTransport
 							? restrictResolverTransport(unrestrictedTransport, options.allowedHosts ?? [])
 							: undefined;
-						return adapter.solve(challenge, options.identity, signal, traceRecorder, transport);
+						return adapter.solve(challenge, identity, signal, traceRecorder, transport);
 					};
 					const solution = traceRecorder
 						? await traceRecorder.runSpan("resolver.vendor.attempt", solveAttempt, {
@@ -786,6 +872,7 @@ function createResolverChainClient(options: {
 									vendor: adapter.id,
 									challenge_kind: challenge.kind,
 									client_profile: options.clientProfile,
+									resolver_identity_source: identityResolution.userAgentSource,
 								},
 								onError(error) {
 									return error instanceof ResolverVendorUnavailableError
@@ -801,9 +888,9 @@ function createResolverChainClient(options: {
 						solutionExpiryMs(solution) !== undefined
 					) {
 						const issuingIdentity =
-							adapter.getIssuingIdentity?.(solution, options.identity, challenge) ??
+							adapter.getIssuingIdentity?.(solution, identity, challenge) ??
 							resolverChallengeIssuingIdentity(challenge, {
-								...(options.identity ? { proxyUrl: options.identity.proxyUrl } : {}),
+								...(identity ? { proxyUrl: identity.proxyUrl } : {}),
 								userAgent: solution.userAgent,
 							});
 						if (issuingIdentity) {
@@ -837,7 +924,7 @@ export function createResolverClient(options: {
 	readonly unavailableReason?: string;
 	readonly cache?: ProviderCache;
 	readonly identity?: ResolverIdentity;
-	readonly proxyMode?: ProviderProxyMode;
+	readonly proxyIntent?: ResolverRuntimeOptions["proxyIntent"];
 	readonly transport?: ResolverVendorTransport;
 	readonly createTransport?: ResolverRuntimeOptions["createTransport"];
 	readonly clientProfile?: string;
@@ -853,7 +940,7 @@ export function createResolverClient(options: {
 		unavailableReason: options.unavailableReason,
 		cache: options.cache,
 		identity: options.identity,
-		proxyMode: options.proxyMode,
+		proxyIntent: options.proxyIntent,
 		transport: options.transport,
 		createTransport: options.createTransport,
 		clientProfile: options.clientProfile,
@@ -945,7 +1032,7 @@ function createResolverClientFromEnvInternal(
 			};
 		}),
 		cache: options.cache,
-		proxyMode: options.proxyMode,
+		proxyIntent: options.proxyIntent,
 		identityScope: options.identityScope,
 		transport: options.transport,
 		createTransport: options.createTransport,

package/src/runtime/stealth.ts

@@ -67,7 +67,7 @@ import {
 	serializeRequestUrl,
 } from "./request-options.js";
 
-const DEFAULT_PROFILE = "chrome-146";
+export const DEFAULT_PROFILE = "chrome-146";
 
 const MISSING_PROXY_WARNING =
 	"[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";