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

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

@@ -1,8 +1,10 @@
 import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
+import type { TraceRecorder } from "../trace.js";
 import { assertResolverHostAllowed } from "./hosts.js";
 import {
 	type ResolverIdentity,
 	type ResolverVendorAdapter,
+	ResolverChallengeVerdictError,
 	ResolverVendorUnavailableError,
 	resolverVendorSupports,
 } from "./types.js";
@@ -34,6 +36,7 @@ export interface TwoCaptchaResolverVendorAdapter extends ResolverVendorAdapter {
 		challenge: ProviderChallenge,
 		identity: ResolverIdentity | undefined,
 		signal: AbortSignal,
+		traceRecorder?: TraceRecorder,
 	): Promise<Extract<ChallengeSolution, { readonly form: "token" }>>;
 }
 
@@ -62,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));
 
@@ -89,7 +135,7 @@ function raceWithAbort<T>(
 				}
 				reject(
 					new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
-						cause: error,
+						...safeCauseOptions(error, sensitiveValues),
 						phase,
 					}),
 				);
@@ -156,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",
@@ -173,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(
 		() =>
@@ -185,6 +239,7 @@ async function postJson(
 			}),
 		signal,
 		phase,
+		sensitiveValues,
 	);
 
 	let responseText: string;
@@ -220,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;
 }
@@ -231,6 +289,28 @@ function endpoint(baseUrl: string, path: string): string {
 	return `${baseUrl.replace(/\/+$/u, "")}/${path}`;
 }
 
+function spanErrorAttributes(
+	error: unknown,
+	phase: TwoCaptchaOperationPhase,
+): Record<string, unknown> | undefined {
+	if (error instanceof ResolverVendorUnavailableError) {
+		return {
+			unavailability_reason: error.reason,
+			transport_phase: error.phase,
+		};
+	}
+	// The solve budget raises TwoCaptchaSolveTimeoutError inside the spanned closure and
+	// the outer catch converts it only after the span has been finalized, so the span has
+	// to recognize it here or slow solves lose exactly the attribution these spans add.
+	if (error instanceof TwoCaptchaSolveTimeoutError) {
+		return {
+			unavailability_reason: "timeout",
+			transport_phase: phase,
+		};
+	}
+	return undefined;
+}
+
 export function createTwoCaptchaResolverVendorAdapter(
 	options: TwoCaptchaResolverVendorOptions,
 ): TwoCaptchaResolverVendorAdapter {
@@ -248,7 +328,7 @@ export function createTwoCaptchaResolverVendorAdapter(
 			return resolverVendorSupports(TWOCAPTCHA_VENDOR_ID, kind);
 		},
 
-		async solve(challenge, identity, callerSignal) {
+		async solve(challenge, identity, callerSignal, traceRecorder) {
 			const apiKey = options.apiKey?.trim();
 			if (!apiKey) {
 				throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "missing_credentials", {
@@ -258,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",
 				});
@@ -285,62 +375,101 @@ export function createTwoCaptchaResolverVendorAdapter(
 			let phase: TwoCaptchaOperationPhase = "create_task";
 
 			try {
-				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 ?? {}),
-						},
-					},
-					solveController.signal,
-					phase,
-				);
-				const taskId = taskIdFrom(createResult.payload);
-				if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
-					throw unavailableForPayload(createResult.payload, phase);
-				}
-
-				phase = "poll_result";
-				while (true) {
-					callerSignal.throwIfAborted();
-					const remainingMs = timeoutMs - (now() - startedAt);
-					if (remainingMs <= 0) throw new TwoCaptchaSolveTimeoutError();
-					await delay(Math.min(pollIntervalMs, remainingMs), solveController.signal);
-					callerSignal.throwIfAborted();
-					if (now() - startedAt >= timeoutMs) throw new TwoCaptchaSolveTimeoutError();
-
-					const pollResult = await postJson(
+				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, "getTaskResult"),
-						{ clientKey: apiKey, taskId },
+						endpoint(baseUrl, "createTask"),
+						{ clientKey: apiKey, task },
 						solveController.signal,
 						phase,
+						[apiKey],
 					);
-					if (!pollResult.ok || pollResult.payload.errorId !== 0) {
-						throw unavailableForPayload(pollResult.payload, phase);
-					}
-					if (pollResult.payload.status === "processing") continue;
-					if (pollResult.payload.status !== "ready") {
-						throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
-							phase,
-						});
+					const taskId = taskIdFrom(createResult.payload);
+					if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
+						throw unavailableForPayload(createResult.payload, phase);
 					}
+					return taskId;
+				};
+				const taskId = traceRecorder
+					? await traceRecorder.runSpan("resolver.vendor.create_task", createTask, {
+							attributes: {
+								vendor: TWOCAPTCHA_VENDOR_ID,
+								challenge_kind: challenge.kind,
+							},
+							onError: (error) => spanErrorAttributes(error, "create_task"),
+						})
+					: await createTask();
 
-					const token = tokenFrom(pollResult.payload);
-					if (!token?.trim()) {
-						throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
+				phase = "poll_result";
+				const pollResult = async () => {
+					while (true) {
+						callerSignal.throwIfAborted();
+						const remainingMs = timeoutMs - (now() - startedAt);
+						if (remainingMs <= 0) throw new TwoCaptchaSolveTimeoutError();
+						await delay(Math.min(pollIntervalMs, remainingMs), solveController.signal);
+						callerSignal.throwIfAborted();
+						if (now() - startedAt >= timeoutMs) throw new TwoCaptchaSolveTimeoutError();
+
+						const pollResult = await postJson(
+							fetchImpl,
+							endpoint(baseUrl, "getTaskResult"),
+							{ clientKey: apiKey, taskId },
+							solveController.signal,
 							phase,
-						});
+							[apiKey],
+						);
+						if (!pollResult.ok || pollResult.payload.errorId !== 0) {
+							throw unavailableForPayload(pollResult.payload, phase);
+						}
+						if (pollResult.payload.status === "processing") continue;
+						if (pollResult.payload.status !== "ready") {
+							throw new ResolverVendorUnavailableError(
+								TWOCAPTCHA_VENDOR_ID,
+								"transport_failure",
+								{ phase },
+							);
+						}
+
+						const token = tokenFrom(pollResult.payload, challenge);
+						if (!token?.trim()) {
+							throw new ResolverVendorUnavailableError(
+								TWOCAPTCHA_VENDOR_ID,
+								"transport_failure",
+								{ phase },
+							);
+						}
+						return { form: "token" as const, token };
 					}
-					return { form: "token", token };
-				}
+				};
+				return traceRecorder
+					? await traceRecorder.runSpan("resolver.vendor.poll_result", pollResult, {
+							attributes: {
+								vendor: TWOCAPTCHA_VENDOR_ID,
+								challenge_kind: challenge.kind,
+							},
+							onError: (error) => spanErrorAttributes(error, "poll_result"),
+						})
+					: await pollResult();
 			} catch (error) {
 				if (callerSignal.aborted) throw abortReason(callerSignal);
 				if (
@@ -352,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

@@ -112,13 +112,15 @@ 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. */
@@ -158,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,11 +1,18 @@
 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,
 	ProviderChallenge,
 	ProviderChallengeKind,
+	ProviderProxyMode,
 	ProviderResolverConfig,
 	ProviderResolverVendor,
 	ResolverContext,
@@ -29,14 +36,33 @@ import {
 	type ResolverVendorUnavailableReason,
 	resolverVendorSupports,
 } from "./resolver-vendors/types.js";
+import {
+	createUnsupportedResolverClient,
+	RESOLVER_INSTRUMENTATION_METADATA,
+} from "./resolver-shared.js";
+import {
+	APIFUSE__CDP_POOL__URL,
+	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
+	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
+	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+	APIFUSE__RESOLVER__TIMEOUT_MS,
+	DEFAULT_RESOLVER_TIMEOUT_MS,
+} from "./resolver-config.js";
+import { DEFAULT_PROFILE } from "./stealth.js";
 import type { TraceRecorder } from "./trace.js";
 
-export const APIFUSE__RESOLVER__2CAPTCHA__API_KEY = "APIFUSE__RESOLVER__2CAPTCHA__API_KEY";
-export const APIFUSE__RESOLVER__CAPSOLVER__API_KEY = "APIFUSE__RESOLVER__CAPSOLVER__API_KEY";
-export const APIFUSE__RESOLVER__CAPMONSTER__API_KEY = "APIFUSE__RESOLVER__CAPMONSTER__API_KEY";
-export const APIFUSE__RESOLVER__TIMEOUT_MS = "APIFUSE__RESOLVER__TIMEOUT_MS";
-export const APIFUSE__CDP_POOL__URL = "APIFUSE__CDP_POOL__URL";
-export const DEFAULT_RESOLVER_TIMEOUT_MS = 180_000;
+export {
+	createUnsupportedResolverClient,
+	RESOLVER_INSTRUMENTATION_METADATA,
+} from "./resolver-shared.js";
+export {
+	APIFUSE__CDP_POOL__URL,
+	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
+	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
+	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+	APIFUSE__RESOLVER__TIMEOUT_MS,
+	DEFAULT_RESOLVER_TIMEOUT_MS,
+} from "./resolver-config.js";
 
 type EnvLike = Record<string, string | undefined>;
 
@@ -75,6 +101,14 @@ type ResolverChainClient = ResolverContext & {
 export interface ResolverRuntimeOptions {
 	readonly allowedHosts?: readonly string[];
 	readonly cache?: ProviderCache;
+	/** 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. */
@@ -143,10 +177,6 @@ const SAFE_CAUSE_MESSAGE_WORDS: ReadonlySet<string> = new Set([
 	"writing",
 ]);
 
-export const RESOLVER_INSTRUMENTATION_METADATA = Symbol.for(
-	"@apifuse/provider-sdk/runtime/resolver-instrumentation-metadata",
-);
-
 export type ResolverInstrumentationMetadata = {
 	readonly target: ResolverContext;
 	readonly traceRecorder: TraceRecorder;
@@ -195,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([
@@ -323,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]";
@@ -338,9 +387,16 @@ 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 && SAFE_CAUSE_MESSAGE_WORDS.has(word.toLowerCase())
+			return word.length > 0 &&
+				word.length <= 32 &&
+				SAFE_CAUSE_MESSAGE_WORDS.has(word.toLowerCase())
 				? token
 				: "[REDACTED]";
 		});
@@ -685,12 +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 proxyIntent?: ResolverRuntimeOptions["proxyIntent"];
 	readonly identityScope?: string;
 	readonly transport?: ResolverVendorTransport;
 	readonly createTransport?: ResolverRuntimeOptions["createTransport"];
@@ -715,16 +817,33 @@ function createResolverChainClient(options: {
 			const supportingEntries = options.entries.filter((entry) => entry.supports(challenge.kind));
 			if (supportingEntries.length === 0) throwUnsupportedKind(challenge.kind);
 			signal.throwIfAborted();
+			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.proxyIntent?.mode === "required" && identity === undefined;
+			if (requiredProxyIdentityMissing) {
+				throwExhausted(
+					supportingEntries.map((entry) => ({
+						vendor: entry.id,
+						reason: identityResolution.unavailableReason ?? "missing_proxy_identity",
+					})),
+				);
+			}
 			if (options.cache && resolverChallengeIsCacheable(challenge)) {
 				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();
@@ -745,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, {
@@ -753,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
@@ -768,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) {
@@ -804,6 +924,7 @@ export function createResolverClient(options: {
 	readonly unavailableReason?: string;
 	readonly cache?: ProviderCache;
 	readonly identity?: ResolverIdentity;
+	readonly proxyIntent?: ResolverRuntimeOptions["proxyIntent"];
 	readonly transport?: ResolverVendorTransport;
 	readonly createTransport?: ResolverRuntimeOptions["createTransport"];
 	readonly clientProfile?: string;
@@ -819,6 +940,7 @@ export function createResolverClient(options: {
 		unavailableReason: options.unavailableReason,
 		cache: options.cache,
 		identity: options.identity,
+		proxyIntent: options.proxyIntent,
 		transport: options.transport,
 		createTransport: options.createTransport,
 		clientProfile: options.clientProfile,
@@ -853,17 +975,6 @@ function resolveVendorAvailability(
 		: { vendor, available: false, reason: "missing_credentials" };
 }
 
-export function createUnsupportedResolverClient(reason?: string): ResolverContext {
-	return {
-		async solve() {
-			throw new ProviderError(reason ?? "Resolver runtime is not configured", {
-				code: "RESOLVER_UNAVAILABLE",
-				fix: "Declare resolver on the provider definition and configure vendor credentials.",
-			});
-		},
-	};
-}
-
 export function bindResolverSignal(
 	resolver: ResolverContext,
 	defaultSignal: AbortSignal | undefined,
@@ -921,6 +1032,7 @@ function createResolverClientFromEnvInternal(
 			};
 		}),
 		cache: options.cache,
+		proxyIntent: options.proxyIntent,
 		identityScope: options.identityScope,
 		transport: options.transport,
 		createTransport: options.createTransport,