@apifuse/provider-sdk 2.2.0-beta.58 → 2.2.0-beta.59

package/src/runtime/stealth.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { Cookie } from "tough-cookie";
 import type {
 	BrowserProfile,
 	EmulationOS,
@@ -22,6 +23,7 @@ import {
 	DEFAULT_STEALTH_BROWSER,
 	DEFAULT_STEALTH_OS,
 	getStealthProfile,
+	resolverClientProfileFamily,
 	resolveStealthProfileSelection,
 } from "../stealth/profiles.js";
 import type {
@@ -35,6 +37,11 @@ import type {
 	StealthSession,
 } from "../types.js";
 import { chrome149HeaderOrder } from "./chrome149-header-order.js";
+import {
+	ENGINE_CEREMONY_EGRESS_LEASE,
+	type CeremonyEgressBinding,
+	type CeremonyEgressLeaseRuntime,
+} from "./egress-lease.js";
 import {
 	createProxyAuthIpDeniedError,
 	createProxyEdgeAuthRejectedError,
@@ -54,6 +61,7 @@ import {
 	computeProxyAttemptIndex,
 	computeProxyTransportRetryDelayMs,
 	createDefaultProxyTransportRetryOptions,
+	isProxyTransportRetryMethod,
 	normalizeProxyTransportRetryOptions,
 	shouldRetryProxyTransportAttempt,
 	validateUnsafeProxyTransportRetryMethods,
@@ -73,6 +81,13 @@ import {
 	redactUrlQueryParams,
 	serializeRequestUrl,
 } from "./request-options.js";
+import type { ResolverVendorTransport } from "./resolver-vendors/types.js";
+import {
+	type AkamaiSbsdSessionState,
+	akamaiSbsdChallengeKey,
+	detectAkamaiSbsdChallenge,
+	type StealthChallengeRuntime,
+} from "./stealth-akamai-sbsd.js";
 import { StealthCookieJar } from "./stealth-cookies.js";
 
 export const DEFAULT_STEALTH_PROFILE: StealthProfileDescriptor = Object.freeze({
@@ -90,6 +105,21 @@ const PROXY_CONNECT_FAILURE_BODY_PATTERN =
 const PROXY_AUTH_DIAGNOSTIC_URL = "http://example.com/";
 const PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS = 5_000;
 const STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES = [PROXY_CONNECT_FAILURE_CODE] as const;
+// Failures that mean the bound ceremony endpoint did not carry the request to the origin.
+// Proxy-level refusals are covered by isProxyPoolRefreshableError; PROXY_AUTH_IP_DENIED is
+// deliberately absent because another endpoint of the same vendor is denied just the same.
+const BOUND_EGRESS_TRANSPORT_FAILURE_CODES: ReadonlySet<string> = new Set([
+	PROXY_CONNECT_FAILURE_CODE,
+	"transport_network_error",
+	"transport_timeout",
+]);
+
+function isBoundEgressTransportFailure(error: TransportError): boolean {
+	return (
+		isProxyPoolRefreshableError(error) ||
+		(error.code !== undefined && BOUND_EGRESS_TRANSPORT_FAILURE_CODES.has(error.code))
+	);
+}
 const MAX_STEALTH_REDIRECT_HOPS = 10;
 const REDIRECT_BODY_HEADERS = new Set([
 	"content-encoding",
@@ -131,6 +161,35 @@ export type StealthClientOptions = ProxyResolutionOptions & {
 	proxyStealth?: { insecureSkipVerify?: boolean };
 };
 
+/** Server-attached challenge wiring and engine lease; kept off the public StealthClientOptions type. */
+type StealthSessionClientOptions = StealthClientOptions & {
+	stealth?: StealthClientOptions["stealth"] & {
+		readonly challengeRuntime?: StealthChallengeRuntime;
+	};
+	readonly [ENGINE_CEREMONY_EGRESS_LEASE]?: CeremonyEgressLeaseRuntime;
+};
+
+type ChallengedReplayRecord = {
+	consumed: boolean;
+	/** Ceremony egress generation the challenged request ran on; a rebind retires the record. */
+	readonly generation: number;
+	replay(): Promise<StealthResponse>;
+};
+
+function assertAkamaiSbsdClientProfile(
+	declared: string | undefined,
+	session: StealthProfileDescriptor,
+): void {
+	if (declared === undefined || resolverClientProfileFamily(declared) === session.browser) return;
+	throw new SDKError(
+		`Resolver client profile "${declared}" does not match the initiating stealth session browser "${session.browser}"`,
+		{
+			code: "RESOLVER_CLIENT_PROFILE_MISMATCH",
+			fix: "Make resolver.clientProfile name the provider stealth browser family (chrome, firefox, or safari).",
+		},
+	);
+}
+
 type StealthTransportHeaders = {
 	entries(): IterableIterator<[string, string]>;
 	get(name: string): string | null;
@@ -256,6 +315,25 @@ function resolveUrl(baseUrl: string, url: string): string {
 	return new URL(url, baseUrl).toString();
 }
 
+function resolveRequestUrl(baseUrl: string, url: string): string {
+	try {
+		return resolveUrl(baseUrl, url);
+	} catch (error) {
+		// Both inputs are caller-owned, so an unparsable URL is a programming error, never a
+		// transport condition: not retryable, not the upstream's fault. Classify it here rather
+		// than in normalizeStealthTransportError, which also sees ERR_INVALID_URL from malformed
+		// upstream redirect targets. The fixed message keeps the URL (and any inline query
+		// values) out of the diagnostic surface; the runtime TypeError stays in `cause`.
+		throw new TransportError("Invalid request URL", {
+			code: "transport_invalid_url",
+			status: 0,
+			category: "provider_error",
+			retryable: false,
+			...(error instanceof Error ? { cause: error } : {}),
+		});
+	}
+}
+
 function headerEntriesFromHeaders(headers: StealthTransportHeaders): [string, string][] {
 	return Array.from(headers.entries());
 }
@@ -517,11 +595,12 @@ function requiredEmulationHeader(headers: ReadonlyMap<string, string>, name: str
 function buildChromeHeaderTuples(options: {
 	emulationHeaders: Iterable<[string, string]>;
 	method: StealthMethod;
-	body?: string;
+	body?: string | Buffer;
 	headers: Record<string, string>;
 	requestUrl: string;
 	acceptLanguage?: string;
 	requestClass?: ChromeRequestClass;
+	userActivation?: boolean;
 }): HeaderTuple[] {
 	const callerEntries = normalizedCallerHeaderEntriesFromRecord(options.headers);
 	const caller = new Map(callerEntries);
@@ -558,7 +637,7 @@ function buildChromeHeaderTuples(options: {
 	]);
 	if (isNavigation) {
 		values.set("upgrade-insecure-requests", "1");
-		values.set("sec-fetch-user", "?1");
+		if (options.userActivation !== false) values.set("sec-fetch-user", "?1");
 	}
 	for (const [name, value] of callerEntries) values.set(name, value);
 	for (const name of ["content-type", "origin", "referer"] as const) {
@@ -626,6 +705,33 @@ function setCookieHeadersFromResponse(headers: StealthTransportHeaders): string[
 	return setCookie ? splitCombinedSetCookieHeader(setCookie) : [];
 }
 
+function resolverCookiesFromResponse(
+	response: StealthTransportResponse,
+	requestUrl: string,
+): Awaited<ReturnType<ResolverVendorTransport["fetch"]>>["cookies"] {
+	const responseUrl = response.url ?? requestUrl;
+	return setCookieHeadersFromResponse(response.headers).flatMap((cookieString) => {
+		const cookie = Cookie.parse(cookieString);
+		if (!cookie?.key) return [];
+		const expires =
+			cookie.expires instanceof Date && Number.isFinite(cookie.expires.getTime())
+				? cookie.expires.getTime() / 1_000
+				: undefined;
+		return [
+			{
+				name: cookie.key,
+				value: cookie.value,
+				...(expires === undefined ? {} : { expires }),
+				httpOnly: cookie.httpOnly,
+				secure: cookie.secure,
+				...(cookie.domain ? { domain: cookie.domain } : { domain: new URL(responseUrl).hostname }),
+				...(cookie.path ? { path: cookie.path } : {}),
+				...(cookie.sameSite ? { sameSite: cookie.sameSite } : {}),
+			},
+		];
+	});
+}
+
 function splitCombinedSetCookieHeader(headerValue: string): string[] {
 	const cookieNamePattern = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+=/;
 	const cookieStrings: string[] = [];
@@ -831,9 +937,9 @@ function readResponseBodyChunk(
 	});
 }
 
-function normalizeBody(body: StealthFetchOptions["body"]): string {
+function normalizeBody(body: unknown): string | Buffer | undefined {
 	if (body === undefined) {
-		return "";
+		return undefined;
 	}
 
 	if (typeof body === "string") {
@@ -841,10 +947,15 @@ function normalizeBody(body: StealthFetchOptions["body"]): string {
 	}
 
 	if (Buffer.isBuffer(body)) {
-		return body.toString();
+		return Buffer.from(body);
 	}
 
-	return String(body);
+	// `StealthFetchOptions.body` is `string | Buffer`; anything else is a provider fault,
+	// caught before the first request so a later replay can send the same bytes.
+	throw new SDKError("Stealth request bodies must be a string or Buffer", {
+		code: "STEALTH_BODY_UNSUPPORTED",
+		fix: "Supply a string or Buffer body; streams and typed arrays are not snapshotted.",
+	});
 }
 
 function isPolicyManagedProxy(options: StealthClientOptions): boolean {
@@ -890,6 +1001,8 @@ type ResolvedAttemptProxy = {
 	poolIndex?: number;
 	proxyHash?: string;
 	vendor?: ProxyVendorName;
+	refreshEpoch?: number;
+	lifetimeMinutes?: number;
 };
 
 function proxyPoolIndexFromDiagnostics(
@@ -902,6 +1015,14 @@ function proxyPoolIndexFromDiagnostics(
 	return Math.floor(value);
 }
 
+function positiveDiagnosticNumber(
+	diagnostics: Record<string, string | number | boolean> | undefined,
+	name: string,
+): number | undefined {
+	const value = diagnostics?.[name];
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
 function proxyEndpointHash(proxyUrl: string | undefined): string | undefined {
 	if (!proxyUrl) return undefined;
 	try {
@@ -1099,7 +1220,7 @@ async function fetchStealthRedirectChain(
 	buildHeaders?: (
 		url: string,
 		method: StealthMethod,
-		body: string | undefined,
+		body: string | Buffer | undefined,
 		headers: Record<string, string>,
 	) => HeaderTuple[],
 ): Promise<{ normalized: StealthResponse; response: StealthTransportResponse }> {
@@ -1196,13 +1317,81 @@ async function fetchStealthRedirectChain(
 function createSessionFetcher(
 	baseUrl: string,
 	defaultProfile: StealthProfileDescriptor,
-	clientOptions: StealthClientOptions,
+	clientOptions: StealthSessionClientOptions,
 ): StealthSession {
 	const clients = new Map<string, WreqSessionCacheEntry>();
 	let closed = false;
 	let hasWarnedMissingProxy = false;
 	const warn = clientOptions.warn ?? console.warn;
 	const cookieJar = new StealthCookieJar([], baseUrl);
+	const akamaiSbsdState: AkamaiSbsdSessionState = { transactions: new Map() };
+	const challengedReplays = new WeakMap<StealthResponse, ChallengedReplayRecord>();
+	const ceremonyEgressLease = clientOptions[ENGINE_CEREMONY_EGRESS_LEASE];
+	// The lease is shared by every session of this client; this is the lease generation this
+	// session's challenge state and replay records were built against.
+	let observedEgressGeneration = ceremonyEgressLease?.generation ?? 0;
+	const automaticChallengeRefetchPolicy = {
+		...createDefaultProxyTransportRetryOptions({ label: "Stealth" }),
+		methods: ["GET"],
+	};
+
+	function clearAkamaiSbsdState(): void {
+		akamaiSbsdState.rememberedScript = undefined;
+		akamaiSbsdState.transactions.clear();
+		akamaiSbsdState.completedSuccessKey = undefined;
+	}
+
+	function currentEgressGeneration(): number {
+		return ceremonyEgressLease?.generation ?? 0;
+	}
+
+	/**
+	 * Whoever dropped the binding (this session by expiry or release, or another session of
+	 * the same client), the challenge state that was only valid on the retired endpoint goes
+	 * with it, and replay records made against the old generation stop matching.
+	 */
+	function syncCeremonyEgress(): void {
+		const generation = currentEgressGeneration();
+		if (generation === observedEgressGeneration) return;
+		observedEgressGeneration = generation;
+		clearAkamaiSbsdState();
+	}
+
+	/**
+	 * A binding past its vendor session lifetime is dropped, together with the challenge
+	 * state that was only valid on that endpoint, so this request selects and binds afresh.
+	 */
+	function expireCeremonyEgressLease(): void {
+		ceremonyEgressLease?.dropExpiredBinding();
+		syncCeremonyEgress();
+	}
+
+	/**
+	 * The lease is best effort (ADR-0010: a raw Smartproxy endpoint is not a vendor-guaranteed
+	 * lease). When the attempt that ran on the bound endpoint fails at the transport (the
+	 * proxy refused it, the tunnel never opened, the socket died or timed out) the binding is
+	 * released so the ceremony can leave a dead endpoint before its lifetime elapses. Origin
+	 * responses, however bad, keep the binding: the endpoint is alive. Returns true when a
+	 * binding was released.
+	 */
+	function releaseFailedCeremonyEgress(
+		attemptProxyUrl: string | undefined,
+		error: TransportError,
+	): boolean {
+		const bound = ceremonyEgressLease?.binding;
+		if (
+			!ceremonyEgressLease ||
+			!bound ||
+			!attemptProxyUrl ||
+			attemptProxyUrl !== bound.proxyUrl ||
+			!isBoundEgressTransportFailure(error)
+		) {
+			return false;
+		}
+		ceremonyEgressLease.dropBinding();
+		syncCeremonyEgress();
+		return true;
+	}
 
 	async function getClientEntry(
 		profile: StealthProfileDescriptor,
@@ -1304,6 +1493,26 @@ function createSessionFetcher(
 		proxyAttempt?: number,
 		refreshEpoch?: number,
 	): Promise<ResolvedAttemptProxy> {
+		const bound = ceremonyEgressLease?.binding;
+		if (bound) {
+			if (options?.proxy !== undefined || options?.proxyAttemptOffset !== undefined) {
+				throw new SDKError(
+					"A ceremony-bound egress cannot be overridden by provider request options",
+					{
+						code: "EGRESS_LEASE_BINDING_INVALID",
+						fix: "Remove `proxy` and `proxyAttemptOffset` from stealth requests made inside an auth ceremony.",
+					},
+				);
+			}
+			return {
+				url: bound.proxyUrl,
+				poolIndex: bound.poolIndex,
+				proxyHash: proxyEndpointHash(bound.proxyUrl),
+				vendor: bound.vendor,
+				refreshEpoch: bound.refreshEpoch,
+				lifetimeMinutes: bound.lifetimeMinutes,
+			};
+		}
 		const resolvedProxy = await resolveProxyConfigAsync({
 			proxy: options?.proxy ?? clientOptions.proxy,
 			upstream: clientOptions.upstream,
@@ -1318,6 +1527,7 @@ function createSessionFetcher(
 			transportProtocols: ["http", "socks5"],
 			...(refreshEpoch === undefined ? {} : { proxyRefreshEpoch: refreshEpoch }),
 			telemetry: clientOptions.telemetry,
+			engineCredentials: clientOptions.engineCredentials,
 		});
 
 		if (resolvedProxy.shouldWarn && !hasWarnedMissingProxy) {
@@ -1330,12 +1540,77 @@ function createSessionFetcher(
 			poolIndex: proxyPoolIndexFromDiagnostics(resolvedProxy.diagnostics),
 			proxyHash: proxyEndpointHash(resolvedProxy.url),
 			vendor: vendorFromResolvedSource(resolvedProxy.source),
+			refreshEpoch: refreshEpoch ?? 0,
+			...(positiveDiagnosticNumber(resolvedProxy.diagnostics, "lifetimeMinutes") === undefined
+				? {}
+				: {
+						lifetimeMinutes: positiveDiagnosticNumber(resolvedProxy.diagnostics, "lifetimeMinutes"),
+					}),
+		};
+	}
+
+	function bindCeremonyEgress(attemptProxy: ResolvedAttemptProxy | undefined): void {
+		const lease = ceremonyEgressLease;
+		if (!lease || !attemptProxy?.url || !attemptProxy.vendor) return;
+		if (lease.binding) {
+			// A concurrent request on this session may have bound the ceremony while this one
+			// was in flight on an endpoint it selected before the binding existed (pool
+			// rotation after a transport failure). Its response reached the origin from an
+			// egress the handle does not name; accepting it would split the ceremony identity.
+			if (attemptProxy.url !== lease.binding.proxyUrl) {
+				throw new SDKError("The response arrived on an egress other than the ceremony's bound endpoint", {
+					code: "EGRESS_LEASE_BINDING_INVALID",
+				});
+			}
+			return;
+		}
+		if (
+			attemptProxy.poolIndex === undefined ||
+			attemptProxy.lifetimeMinutes === undefined ||
+			!clientOptions.affinityKey
+		) {
+			// Registry vendors always report pool index and session lifetime; missing either
+			// is an SDK fault, not something the caller can correct.
+			throw new SDKError("The selected egress cannot be represented by a ceremony lease", {
+				code: "EGRESS_LEASE_BINDING_INVALID",
+			});
+		}
+		const binding: CeremonyEgressBinding = {
+			vendor: attemptProxy.vendor,
+			proxyUrl: attemptProxy.url,
+			poolIndex: attemptProxy.poolIndex,
+			affinityKey: clientOptions.affinityKey,
+			refreshEpoch: attemptProxy.refreshEpoch ?? 0,
+			lifetimeMinutes: attemptProxy.lifetimeMinutes,
 		};
+		lease.bind(binding);
 	}
 
 	const session: StealthSession = {
-		async fetch(url, options: StealthFetchOptions = {}) {
+		async fetch(url, callerOptions: StealthFetchOptions = {}) {
+			expireCeremonyEgressLease();
+			const requestBody = normalizeBody(callerOptions.body);
+			// Snapshot the caller's headers with the body before the first send: the first
+			// request and an explicit replay both use this copy, so a caller mutating its own
+			// objects afterwards cannot make the two sends differ.
+			const options: StealthFetchOptions = {
+				...callerOptions,
+				...(callerOptions.headers
+					? {
+							headers: Object.fromEntries(
+								Object.entries(callerOptions.headers).map(([name, value]) => [
+									name,
+									Array.isArray(value) ? [...value] : value,
+								]),
+							),
+						}
+					: {}),
+				...(requestBody === undefined ? {} : { body: requestBody }),
+			};
 			const requestProfile = resolveStealthProfileSelection(options.stealth, defaultProfile);
+			let challengeSolveAttempted = false;
+			let challengeRefetchAttempted = false;
+			let challengeSolveFailure: { readonly error: unknown } | undefined;
 			const { hasExplicitRetryPolicy, method, stealthRetryOptions } = (() => {
 				try {
 					const method = normalizeMethod(options.method ?? "GET");
@@ -1387,7 +1662,10 @@ function createSessionFetcher(
 			// transport-retry budget instead.
 			const rotatesRegistryChain =
 				usesPolicyAllocator && policyResolvesRegistryVendorChain(policyProxy);
-			const maxAttempts = rotatesRegistryChain ? policyProxyAttemptCap : retryAttemptCap;
+			const unboundMaxAttempts = rotatesRegistryChain ? policyProxyAttemptCap : retryAttemptCap;
+			// A bound ceremony has exactly one endpoint to try; releasing the binding after a
+			// transport failure widens the budget back to the ordinary rotation span.
+			let maxAttempts = ceremonyEgressLease?.binding ? 1 : unboundMaxAttempts;
 			const dedupeAllocatorEndpoints = rotatesRegistryChain;
 			let lastError: unknown;
 
@@ -1409,8 +1687,9 @@ function createSessionFetcher(
 					let fallbackSensitiveValues: readonly string[] = [];
 					let fallbackRequestUrl: string | undefined;
 					let fallbackRedactedUrl: string | undefined;
-					const attemptStartedAt = Date.now();
+					let attemptStartedAt = Date.now();
 					let attemptRecorded = false;
+					const attemptEgressGeneration = currentEgressGeneration();
 					const recordProxyAttempt = (
 						outcome: "ok" | "error",
 						errorCode?: string,
@@ -1431,6 +1710,68 @@ function createSessionFetcher(
 							durationMs: Date.now() - attemptStartedAt,
 						});
 					};
+					// Shared tail of the first fetch, the automatic refetch, and an explicit replay: a
+					// classified challenge is returned whatever `throwOnHttpError` says (documented on
+					// StealthFetchOptions), any other non-2xx honours it, and the proxy attempt is
+					// recorded once per delivered response.
+					const finalizeAttempt = (
+						attemptResponse: StealthTransportResponse,
+						attemptNormalized: StealthResponse,
+					): StealthResponse => {
+						if (
+							!attemptNormalized.challenge &&
+							attemptResponse.status >= 400 &&
+							options.throwOnHttpError !== false
+						) {
+							throw new TransportError(
+								`Upstream request failed with status ${attemptResponse.status}`,
+								{ code: "upstream_http_error", status: attemptResponse.status },
+							);
+						}
+						recordProxyAttempt("ok", undefined, attemptResponse.status);
+						return attemptNormalized;
+					};
+					const redactAttemptError = <T>(error: T): T =>
+						redactSensitiveError(
+							error,
+							serializedUrl?.sensitiveValues ?? fallbackSensitiveValues,
+							serializedUrl?.requestUrl ?? fallbackRequestUrl,
+							serializedUrl?.redactedUrl ?? fallbackRedactedUrl,
+						);
+					// Cancellation and resolver failures leave the transport path here, redacted; any
+					// other failure becomes the TransportError the retry decision reasons about.
+					const normalizeAttemptError = (error: unknown): TransportError => {
+						let normalizedError: TransportError;
+						try {
+							throwIfAmbientAborted(clientOptions.signal);
+							normalizedError = normalizeStealthTransportError(error);
+						} catch (normalizationError) {
+							if (
+								normalizationError instanceof TransportError &&
+								normalizationError.code === "transport_cancelled"
+							) {
+								recordProxyAttempt(
+									"error",
+									proxyAttemptErrorCode(normalizationError),
+									proxyAttemptStatus(normalizationError),
+								);
+							}
+							throw redactAttemptError(normalizationError);
+						}
+						if (challengeSolveFailure && error === challengeSolveFailure) {
+							throw redactAttemptError(challengeSolveFailure.error);
+						}
+						return normalizedError;
+					};
+					const recordAttemptFailure = (normalizedError: TransportError): TransportError => {
+						const redactedError = redactAttemptError(normalizedError);
+						recordProxyAttempt(
+							"error",
+							proxyAttemptErrorCode(redactedError),
+							proxyAttemptStatus(redactedError),
+						);
+						return redactedError;
+					};
 					try {
 						throwIfAmbientAborted(clientOptions.signal);
 						const sensitiveParams = normalizeSensitiveParams(options.sensitiveParams);
@@ -1463,24 +1804,25 @@ function createSessionFetcher(
 								(!hasPolicyProxy && proxy && clientOptions.proxyStealth?.insecureSkipVerify),
 						);
 						serializedUrl = serializeRequestUrl(
-							resolveUrl(baseUrl, url),
+							resolveRequestUrl(baseUrl, url),
 							options.params,
 							sensitiveParams,
 						);
 						const { requestUrl } = serializedUrl;
 						const wreq = await getWreqModule();
 						const mapping = resolveWreqProfile(requestProfile, wreq.getProfiles());
+						const emulationHeaders = Array.from(
+							wreq.getEmulationHeaders(mapping.browser, mapping.os),
+							([name, value]) => [String(name), String(value)] as HeaderTuple,
+						);
 						const chromeEmulationHeaders = mapping.browser.startsWith("chrome_")
-							? Array.from(
-									wreq.getEmulationHeaders(mapping.browser, mapping.os),
-									([name, value]) => [String(name), String(value)] as HeaderTuple,
-								)
+							? emulationHeaders
 							: undefined;
 						const buildOrderedHeaders = chromeEmulationHeaders
 							? (
 									currentUrl: string,
 									currentMethod: StealthMethod,
-									currentBody: string | undefined,
+									currentBody: string | Buffer | undefined,
 									currentHeaders: Record<string, string>,
 								) =>
 									buildChromeHeaderTuples({
@@ -1491,6 +1833,7 @@ function createSessionFetcher(
 										requestUrl: currentUrl,
 										acceptLanguage: clientOptions.stealth?.acceptLanguage,
 										requestClass: options.stealth?.requestClass,
+										userActivation: options.stealth?.userActivation,
 									})
 							: undefined;
 						const initialHeaders = normalizeHeaders({ ...(options.headers ?? {}) });
@@ -1501,110 +1844,358 @@ function createSessionFetcher(
 						const defaultHeaders = buildOrderedHeaders?.(
 							requestUrl,
 							method,
-							options.body === undefined ? undefined : normalizeBody(options.body),
+							requestBody,
 							initialHeaders,
 						);
-						const { normalized, response } = await withClient(
-							requestProfile,
-							proxy,
-							ignoreTlsErrors,
-							(transport) =>
-								fetchStealthRedirectChain(
-									transport,
-									cookieJar,
-									requestUrl,
-									method,
-									options,
-									clientOptions.signal,
-									buildOrderedHeaders,
-								),
-							clientOptions.signal,
-							defaultHeaders,
-						);
-
-						if (proxy && isProxyConnectFailureResponse(response, normalized.body)) {
-							throw createProxyConnectFailureError(normalized.body);
-						}
-
-						if (response.status >= 400) {
+						const fetchOnBoundSession = (
+							fetchUrl: string,
+							fetchMethod: StealthMethod,
+							fetchOptions: StealthFetchOptions,
+							fetchSignal: AbortSignal | undefined,
+							orderedHeaders = buildOrderedHeaders,
+							sessionDefaultHeaders = defaultHeaders,
+						) =>
+							withClient(
+								requestProfile,
+								proxy,
+								ignoreTlsErrors,
+								(transport) =>
+									fetchStealthRedirectChain(
+										transport,
+										cookieJar,
+										fetchUrl,
+										fetchMethod,
+										fetchOptions,
+										fetchSignal,
+										orderedHeaders,
+									),
+								fetchSignal,
+								sessionDefaultHeaders,
+							);
+						const throwProxyTransportFault = (
+							faultResponse: StealthTransportResponse,
+							faultBody: string,
+						) => {
+							if (!proxy) return;
+							if (isProxyConnectFailureResponse(faultResponse, faultBody)) {
+								throw createProxyConnectFailureError(faultBody);
+							}
+							if (faultResponse.status < 400) return;
 							if (
-								proxy &&
 								usesPolicyAllocator &&
 								isProxyEdgeTlsRejectedResponse(
-									response.status,
-									[JSON.stringify(responseHeadersToRecord(response.headers)), normalized.body].join(
+									faultResponse.status,
+									[JSON.stringify(responseHeadersToRecord(faultResponse.headers)), faultBody].join(
 										"\n",
 									),
 								)
 							) {
-								throw createProxyEdgeTlsRejectedError(response.status);
+								throw createProxyEdgeTlsRejectedError(faultResponse.status);
 							}
-							if (proxy && isProxyAuthIpDeniedMessage(normalized.body)) {
+							if (isProxyAuthIpDeniedMessage(faultBody)) {
 								throw createProxyAuthIpDeniedError();
 							}
-							if (proxy && isProxyEdgeAuthRejectedMessage(normalized.body)) {
+							if (isProxyEdgeAuthRejectedMessage(faultBody)) {
 								throw createProxyEdgeAuthRejectedError();
 							}
 							if (
-								proxy &&
-								isProxyPoolStaleStatus(response.status) &&
-								isProxyPoolStaleMessage(normalized.body)
+								isProxyPoolStaleStatus(faultResponse.status) &&
+								isProxyPoolStaleMessage(faultBody)
 							) {
-								throw createProxyPoolStaleError(response.status);
+								throw createProxyPoolStaleError(faultResponse.status);
 							}
-						}
+						};
+						let { normalized, response } = await fetchOnBoundSession(
+							requestUrl,
+							method,
+							options,
+							clientOptions.signal,
+						);
+						throwProxyTransportFault(response, normalized.body);
 
-						if (response.status >= 400 && options.throwOnHttpError !== false) {
-							throw new TransportError(`Upstream request failed with status ${response.status}`, {
-								code: "upstream_http_error",
-								status: response.status,
-							});
-						}
+						// Commit only after the selected endpoint reached the origin. A failed
+						// proxy attempt may rotate pool index; the successful exact endpoint is
+						// the one sealed into the ceremony handle.
+						bindCeremonyEgress(attemptProxy);
 
-						recordProxyAttempt("ok", undefined, response.status);
-						return normalized;
-					} catch (error) {
-						const sensitiveValues = serializedUrl?.sensitiveValues ?? fallbackSensitiveValues;
-						let normalizedError: TransportError;
-						try {
-							throwIfAmbientAborted(clientOptions.signal);
-							normalizedError = normalizeStealthTransportError(error);
-						} catch (normalizationError) {
-							const redactedNormalizationError = redactSensitiveError(
-								normalizationError,
-								sensitiveValues,
-								serializedUrl?.requestUrl ?? fallbackRequestUrl,
-								serializedUrl?.redactedUrl ?? fallbackRedactedUrl,
+						const akamaiSbsd = clientOptions.stealth?.challengeRuntime?.akamaiSbsd;
+						const detected = akamaiSbsd
+							? detectAkamaiSbsdChallenge(
+									normalized,
+									requestUrl,
+									cookieJar,
+									akamaiSbsd.allowedHosts,
+									akamaiSbsdState,
+								)
+							: undefined;
+						if (detected && akamaiSbsd) {
+							if (challengeSolveAttempted || challengeRefetchAttempted) {
+								normalized.challenge = {
+									challenge: detected,
+									outcome: "challenge_persisted",
+								};
+								return finalizeAttempt(response, normalized);
+							}
+							const automaticReplayEligible = isProxyTransportRetryMethod(
+								method,
+								automaticChallengeRefetchPolicy,
+								{ body: requestBody, headers: options.headers },
 							);
-							if (
-								normalizationError instanceof TransportError &&
-								normalizationError.code === "transport_cancelled"
-							) {
-								recordProxyAttempt(
-									"error",
-									proxyAttemptErrorCode(normalizationError),
-									proxyAttemptStatus(normalizationError),
+							if (automaticReplayEligible && !akamaiSbsd.solve) {
+								normalized.challenge = {
+									challenge: detected,
+									outcome: "resolver_unavailable",
+								};
+								return finalizeAttempt(response, normalized);
+							}
+
+							const emulationHeaderMap = new Map(
+								emulationHeaders.map(([name, value]) => [name.toLowerCase(), value] as const),
+							);
+							const initiatingHeaders = normalizeHeaders({ ...(options.headers ?? {}) });
+							// Mirror what the protected request actually sent: `stealth.acceptLanguage` is
+							// applied by the Chrome header builder only; Safari/Firefox sessions send the
+							// emulation default.
+							const sessionHeaders = {
+								"User-Agent": requiredEmulationHeader(emulationHeaderMap, "user-agent"),
+								"Accept-Language":
+									initiatingHeaders["accept-language"] ??
+									(chromeEmulationHeaders ? clientOptions.stealth?.acceptLanguage : undefined) ??
+									requiredEmulationHeader(emulationHeaderMap, "accept-language"),
+							};
+							const resolverBuildHeaders = chromeEmulationHeaders
+								? (
+										currentUrl: string,
+										currentMethod: StealthMethod,
+										currentBody: string | Buffer | undefined,
+										currentHeaders: Record<string, string>,
+									) =>
+										buildChromeHeaderTuples({
+											emulationHeaders: chromeEmulationHeaders,
+											method: currentMethod,
+											body: currentBody,
+											headers: currentHeaders,
+											requestUrl: currentUrl,
+											acceptLanguage: clientOptions.stealth?.acceptLanguage,
+										})
+								: undefined;
+							const resolverTransport: ResolverVendorTransport = {
+								sessionHeaders,
+								getCookie(name, cookieUrl) {
+									return cookieJar.get(name, cookieUrl);
+								},
+								async fetch(transportUrl, init) {
+									const boundSignal = clientOptions.signal
+										? AbortSignal.any([clientOptions.signal, init.signal])
+										: init.signal;
+									const transportHeaders = { ...(init.headers ?? {}) };
+									if (resolverBuildHeaders) {
+										for (const name of Object.keys(transportHeaders)) {
+											if (name.toLowerCase() === "user-agent") {
+												delete transportHeaders[name];
+											}
+										}
+									}
+									// Session defaults come from this request's own shape, never from the
+									// initiating request: its defaults carry the upstream Cookie header,
+									// which wreq would otherwise merge into the Hyper /ip call.
+									const result = await fetchOnBoundSession(
+										transportUrl,
+										init.method,
+										{
+											method: init.method,
+											headers: transportHeaders,
+											...(init.body === undefined ? {} : { body: init.body }),
+											redirect: "manual",
+											throwOnHttpError: false,
+											...(init.maxBodyBytes === undefined
+												? {}
+												: { maxBodyBytes: init.maxBodyBytes }),
+										},
+										boundSignal,
+										resolverBuildHeaders,
+										resolverBuildHeaders?.(
+											transportUrl,
+											init.method,
+											init.body,
+											normalizeHeaders(transportHeaders),
+										),
+									);
+									return {
+										status: result.normalized.status,
+										headers: result.normalized.headers,
+										body: result.normalized.body,
+										cookies: resolverCookiesFromResponse(result.response, transportUrl),
+									};
+								},
+							};
+							// `options` is already the fetch-start snapshot; the replay gets its own copy
+							// of the body bytes so the transport cannot alias the first send's buffer.
+							const replayOptions: StealthFetchOptions = {
+								...options,
+								...(Buffer.isBuffer(requestBody) ? { body: Buffer.from(requestBody) } : {}),
+							};
+							const transactionKey = akamaiSbsdChallengeKey(detected, {
+								wreqBrowser: mapping.browser,
+								wreqOs: mapping.os,
+								proxyUrl: proxy,
+							});
+							const challenged = { normalized, response };
+							const solveAndReplay = async (
+								explicitReplay: boolean,
+							): Promise<{ normalized: StealthResponse; response: StealthTransportResponse }> => {
+								if (!akamaiSbsd.solve) {
+									throw new SDKError("No resolver is available for the challenged request", {
+										code: "RESOLVER_UNAVAILABLE",
+									});
+								}
+								// Only a solve that will actually run on this session needs the profile match.
+								assertAkamaiSbsdClientProfile(akamaiSbsd.clientProfile, requestProfile);
+								// A safe request that already solved this exact challenge on this identity
+								// left the session cookies valid: the explicit replay reuses them once
+								// instead of paying for a second solve.
+								const reuseCompletedSuccess =
+									explicitReplay && akamaiSbsdState.completedSuccessKey === transactionKey;
+								if (reuseCompletedSuccess) akamaiSbsdState.completedSuccessKey = undefined;
+							let ownsTransaction = false;
+								if (!reuseCompletedSuccess) {
+									let transaction = akamaiSbsdState.transactions.get(transactionKey);
+							if (!transaction) {
+										akamaiSbsdState.completedSuccessKey = undefined;
+								challengeSolveAttempted = true;
+								ownsTransaction = true;
+								// The solve spans several round trips, so it runs under the client's ambient
+								// signal and the resolver's own timeouts, not this fetch's per-request `timeout`.
+								transaction = {
+									result: akamaiSbsd
+										.solve(
+											detected,
+											resolverTransport,
+											clientOptions.signal ?? new AbortController().signal,
+										)
+										.then(
+											() => ({ solved: true }) as const,
+											(error: unknown) => ({ solved: false, error }) as const,
+										)
+										.finally(() => {
+											akamaiSbsdState.transactions.delete(transactionKey);
+										}),
+								};
+								akamaiSbsdState.transactions.set(transactionKey, transaction);
+							}
+							const transactionResult = await transaction.result;
+							if (!transactionResult.solved) {
+								if (ownsTransaction) {
+									// The proxy delivered the challenged response; the resolver failed.
+									// Surface that failure as-is: it is not a transport fault to normalize
+									// or retry.
+											if (!explicitReplay) {
+												recordProxyAttempt("ok", undefined, challenged.response.status);
+											}
+									challengeSolveFailure = { error: transactionResult.error };
+									throw challengeSolveFailure;
+								}
+										return {
+											normalized: {
+												...challenged.normalized,
+												challenge: { challenge: detected, outcome: "solve_failed" },
+											},
+											response: challenged.response,
+								};
+									}
+							}
+							challengeRefetchAttempted = true;
+								// An explicit replay is a new transport exchange on the bound endpoint and
+								// gets its own proxy-attempt record timed from here, not from the initiating
+								// fetch (the caller's think time in between is not transport duration); the
+								// automatic refetch stays within the initiating attempt's record.
+								if (explicitReplay) {
+									// The solve above may have taken seconds; if another session of this client
+									// moved the ceremony meanwhile, the mutation must not go out on the retired
+									// endpoint.
+									if (currentEgressGeneration() !== attemptEgressGeneration) {
+										throw new SDKError(
+											"The ceremony's egress binding changed while the replay was being solved",
+											{ code: "REPLAY_SESSION_MISMATCH" },
+										);
+									}
+									attemptRecorded = false;
+									attemptStartedAt = Date.now();
+								}
+								const replayed = await fetchOnBoundSession(
+								requestUrl,
+								method,
+									replayOptions,
+								clientOptions.signal,
 								);
+								throwProxyTransportFault(replayed.response, replayed.normalized.body);
+							const persisted = detectAkamaiSbsdChallenge(
+									replayed.normalized,
+								requestUrl,
+								cookieJar,
+								akamaiSbsd.allowedHosts,
+								akamaiSbsdState,
+							);
+							if (persisted) {
+									replayed.normalized.challenge = {
+									challenge: persisted,
+									outcome: "challenge_persisted",
+								};
+								} else if (ownsTransaction && !explicitReplay) {
+									akamaiSbsdState.completedSuccessKey = transactionKey;
+						}
+								return replayed;
+							};
+
+							if (!automaticReplayEligible) {
+								normalized.challenge = {
+									challenge: detected,
+									outcome: "replay_required",
+								};
+								challengedReplays.set(normalized, {
+									consumed: false,
+									generation: attemptEgressGeneration,
+									async replay() {
+						try {
+											const replayed = await solveAndReplay(true);
+											return finalizeAttempt(replayed.response, replayed.normalized);
+										} catch (error) {
+											const normalizedError = normalizeAttemptError(error);
+											releaseFailedCeremonyEgress(proxy, normalizedError);
+											throw recordAttemptFailure(normalizedError);
 							}
-							throw redactedNormalizationError;
+									},
+								});
+								return finalizeAttempt(response, normalized);
+						}
+							({ normalized, response } = await solveAndReplay(false));
 						}
+
+						return finalizeAttempt(response, normalized);
+					} catch (error) {
+						const normalizedError = normalizeAttemptError(error);
 						const retryErrorCode = proxyAttemptErrorCode(normalizedError);
 						const refreshableProxyError = isProxyPoolRefreshableError(normalizedError);
 						const runProxyAuthDiagnostic = shouldRunProxyAuthDiagnostic(normalizedError);
-						normalizedError = redactSensitiveError(
-							normalizedError,
-							sensitiveValues,
-							serializedUrl?.requestUrl ?? fallbackRequestUrl,
-							serializedUrl?.redactedUrl ?? fallbackRedactedUrl,
-						);
-						recordProxyAttempt(
-							"error",
-							proxyAttemptErrorCode(normalizedError),
-							proxyAttemptStatus(normalizedError),
-						);
-						lastError = normalizedError;
+						const redactedError = recordAttemptFailure(normalizedError);
+						lastError = redactedError;
+						const releasedBoundEgress = releaseFailedCeremonyEgress(proxy, normalizedError);
+						if (releasedBoundEgress) {
+							// The request now proceeds as an unbound one with the full rotation budget;
+							// the attempt spent on the dead endpoint does not count against it.
+							maxAttempts = attempt + 1 + unboundMaxAttempts;
+						}
+						if (challengeSolveAttempted || challengeRefetchAttempted) {
+							// The single refetch is spent (owner or waiter of a shared solve): another
+							// transport attempt would replay the original request and may rotate the
+							// proxy the solved jar is bound to.
+							throw redactedError;
+						}
 						if (proxy && rotatesRegistryChain && refreshableProxyError) {
-							stalePoolError = normalizedError;
+							// Also the path a released bound endpoint takes after a proxy-level refusal:
+							// the stale-pool bookkeeping here is what drives allocator invalidation and the
+							// refresh pass when the fresh selection lands on the same endpoint again.
+							stalePoolError = redactedError;
 							if (runProxyAuthDiagnostic) {
 								stalePoolDiagnosticProxy = proxy;
 							}
@@ -1613,6 +2204,17 @@ function createSessionFetcher(
 							}
 							break;
 						}
+						if (
+							releasedBoundEgress &&
+							attempt + 1 < maxAttempts &&
+							retryErrorCode === PROXY_CONNECT_FAILURE_CODE
+						) {
+							// The tunnel to the released endpoint never opened, so the origin never saw the
+							// request: selecting and binding a fresh endpoint in this request is safe for
+							// any method. Ambiguous failures (reset, timeout) fall through to the ordinary
+							// method-aware retry decision below with the binding already released.
+							continue;
+						}
 						// Cap the number of transport retries. For a policy-allocator chain,
 						// every attempt resolves a *different* endpoint/vendor (poolIndex
 						// rotates across the concatenated vendor pool spans), so a transport
@@ -1652,7 +2254,7 @@ function createSessionFetcher(
 							throwIfAmbientAborted(clientOptions.signal);
 							continue;
 						}
-						throw normalizedError;
+						throw redactedError;
 					}
 				}
 
@@ -1703,6 +2305,35 @@ function createSessionFetcher(
 			throwIfAmbientAborted(clientOptions.signal);
 			throw normalizeStealthTransportError(lastError);
 		},
+		async replayChallenged(challengedResponse) {
+			// Lease expiry is evaluated when a fetch starts, not here: the replay belongs to the
+			// exchange that was challenged on the bound endpoint (Akamai state is IP-bound), so a
+			// lifetime boundary crossed during the solve does not move it elsewhere. The next
+			// fetch drops the expired binding and rebinds.
+			const replay = challengedReplays.get(challengedResponse);
+			if (!replay || challengedResponse.challenge?.outcome !== "replay_required") {
+				throw new SDKError("The challenged response does not belong to this stealth session", {
+					code: "REPLAY_SESSION_MISMATCH",
+				});
+			}
+			syncCeremonyEgress();
+			if (replay.generation !== currentEgressGeneration()) {
+				// The ceremony rebound to another egress after this request ran (in this session or
+				// another of the same client); solving and replaying on the retired endpoint would
+				// split the identity the handle names.
+				throw new SDKError(
+					"The challenged response predates the ceremony's current egress binding",
+					{ code: "REPLAY_SESSION_MISMATCH" },
+				);
+			}
+			if (replay.consumed) {
+				throw new SDKError("The challenged request has already used its one replay budget", {
+					code: "REPLAY_ALREADY_ATTEMPTED",
+				});
+			}
+			replay.consumed = true;
+			return replay.replay();
+		},
 		cookies: cookieJar,
 		redirects: {
 			async run(options) {
@@ -1906,6 +2537,7 @@ function createSessionFetcher(
 		},
 		close() {
 			closed = true;
+			clearAkamaiSbsdState();
 			for (const client of clients.values()) {
 				void client.session
 					.then((session) => session.close())