@apifuse/provider-sdk 2.2.0-beta.2 → 2.2.0-beta.21

package/src/runtime/stealth.ts

@@ -1,26 +1,32 @@
 import { createHash } from "node:crypto";
 import type { Browser, ImpitOptions, ImpitResponse, RequestInit } from "impit";
 import { Impit } from "impit";
+import { Cookie, CookieJar as ToughCookieJar } from "tough-cookie";
 
-import type { ProxyResolutionOptions } from "../config/loader";
+import type { ProxyResolutionOptions, ProxyVendorName } from "../config/loader.js";
 import {
 	DEFAULT_SMARTPROXY_POOL_SIZE,
 	invalidateProxyResolutionCacheAsync,
 	ProxyResolutionError,
+	policyResolvesRegistryVendorChain,
+	resolvePolicyProxyPoolSpan,
+	resolvePolicyTransportAttemptCap,
 	resolveProxyConfigAsync,
-	SMARTPROXY_MAX_POOL_SIZE,
-} from "../config/loader";
-import { SDKError, TransportError } from "../errors";
-import { getStealthProfile } from "../stealth/profiles";
+	vendorFromResolvedSource,
+} from "../config/loader.js";
+import { SDKError, StealthCookieStoreVersionError, TransportError } from "../errors.js";
+import { getStealthProfile } from "../stealth/profiles.js";
 import type {
 	CookieJar,
 	HttpMethod,
 	StealthClient,
+	StealthCookieStore,
+	StealthCookieStoreV1,
 	StealthFetchOptions,
 	StealthRedirectHop,
 	StealthResponse,
 	StealthSession,
-} from "../types";
+} from "../types.js";
 import {
 	createProxyAuthIpDeniedError,
 	createProxyEdgeAuthRejectedError,
@@ -35,7 +41,7 @@ import {
 	isProxyPoolStaleStatus,
 	PROXY_EDGE_AUTH_REJECTED_CODE,
 	PROXY_POOL_STALE_CODE,
-} from "./proxy-errors";
+} from "./proxy-errors.js";
 import {
 	computeProxyAttemptIndex,
 	computeProxyTransportRetryDelayMs,
@@ -43,15 +49,27 @@ import {
 	normalizeProxyTransportRetryOptions,
 	shouldRetryProxyTransportAttempt,
 	validateUnsafeProxyTransportRetryMethods,
-} from "./proxy-retry-policy";
-import { appendQueryParams } from "./request-options";
+} from "./proxy-retry-policy.js";
+import {
+	evaluateRedirectHop,
+	isRedirectStatus,
+	resolveRedirectUrl,
+} from "./redirects.js";
+import {
+	isSensitiveKey,
+	redactSensitiveError,
+	redactSensitiveRequestError,
+	redactSensitiveText,
+	redactUrlQueryParams,
+	normalizeSensitiveParams,
+	serializeRequestUrl,
+} from "./request-options.js";
 
 const DEFAULT_PROFILE = "chrome-146";
 
 const MISSING_PROXY_WARNING =
 	"[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
 
-const MAX_POLICY_PROXY_RETRY_ATTEMPTS = SMARTPROXY_MAX_POOL_SIZE;
 const MAX_POLICY_PROXY_POOL_REFRESHES = 1;
 const PROXY_CONNECT_FAILURE_CODE = "proxy_connect_failed";
 const PROXY_CONNECT_FAILURE_BODY_PATTERN =
@@ -60,6 +78,14 @@ 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;
 
+function sensitiveQueryParamNames(url: string): string[] {
+	const queryStart = url.indexOf("?");
+	if (queryStart === -1) return [];
+	const fragmentStart = url.indexOf("#", queryStart);
+	const query = url.slice(queryStart + 1, fragmentStart === -1 ? undefined : fragmentStart);
+	return [...new URLSearchParams(query).keys()].filter(isSensitiveKey);
+}
+
 export type StealthClientOptions = ProxyResolutionOptions & {
 	warn?: (message: string) => void;
 	/**
@@ -112,6 +138,8 @@ type StealthTransportResponse = Pick<
 	ImpitResponse,
 	"arrayBuffer" | "headers" | "json" | "ok" | "status" | "text"
 > & {
+	body?: ReadableStream<Uint8Array>;
+	abort?: () => void;
 	url?: string;
 	redirected?: boolean;
 };
@@ -125,81 +153,145 @@ function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
 	return typeof value === "object" && value !== null;
 }
 
+const LEGACY_COOKIE_ORIGIN = "https://legacy-cookie.invalid/";
+
 class CookieJarImpl implements CookieJar {
-	private readonly cookies: Record<string, string>;
+	private cookies: ToughCookieJar;
+	private readonly defaultUrl: string;
 
-	constructor(cookieStrings: string[]) {
-		this.cookies = {};
+	constructor(cookieStrings: readonly string[], defaultUrl = LEGACY_COOKIE_ORIGIN) {
+		this.cookies = new ToughCookieJar(undefined, {
+			allowSecureOnLocal: false,
+			rejectPublicSuffixes: true,
+		});
+		this.defaultUrl = this.normalizeUrl(defaultUrl) ?? LEGACY_COOKIE_ORIGIN;
 		this.setFromCookieStrings(cookieStrings);
 	}
 
-	setFromCookieStrings(cookieStrings: readonly string[]): void {
-		for (const cookieString of cookieStrings) {
-			const [nameValue] = cookieString.split(";");
-			if (!nameValue) {
-				continue;
-			}
-
-			const separatorIndex = nameValue.indexOf("=");
-			if (separatorIndex === -1) {
-				continue;
-			}
+	/**
+	 * URL-less legacy operations are scoped to this jar's default URL. Session
+	 * jars use the client's base URL and response jars use the response URL. A
+	 * flat restore has no attributes to recover, so it creates host-only Path=/
+	 * cookies for that default URL instead of making them visible to every host.
+	 */
+	setFromCookieStrings(cookieStrings: readonly string[], url = this.defaultUrl): void {
+		const cookieUrl = this.normalizeUrl(url);
+		if (!cookieUrl) return;
 
-			const name = nameValue.slice(0, separatorIndex).trim();
-			const value = nameValue.slice(separatorIndex + 1).trim();
-			if (name) this.cookies[name] = value;
+		for (const cookieString of cookieStrings) {
+			this.cookies.setCookieSync(cookieString, cookieUrl, { ignoreError: true });
 		}
 	}
 
-	get(name: string): string | undefined {
-		return this.cookies[name];
+	get(name: string, url?: string): string | undefined {
+		return this.getAll(url)[name];
 	}
 
-	getAll(): Record<string, string> {
-		return { ...this.cookies };
+	getAll(url?: string): Record<string, string> {
+		return Object.fromEntries(
+			this.getUniqueCookies(url ?? this.defaultUrl).map((cookie) => [cookie.key, cookie.value]),
+		);
 	}
 
-	has(name: string): boolean {
-		return Object.hasOwn(this.cookies, name);
+	has(name: string, url?: string): boolean {
+		return Object.hasOwn(this.getAll(url), name);
 	}
 
-	toString(): string {
-		return Object.entries(this.cookies)
-			.map(([name, value]) => `${name}=${value}`)
+	toString(url?: string): string {
+		return this.getUniqueCookies(url ?? this.defaultUrl)
+			.map((cookie) => cookie.cookieString())
 			.join("; ");
 	}
 
-	toHeader(): string {
-		return this.toString();
+	toHeader(url?: string): string {
+		return this.toString(url);
 	}
 
 	snapshot(): Record<string, string> {
-		return this.getAll();
+		// This compatibility view deliberately enumerates the serialized store,
+		// not getAll(defaultUrl): persistence must include sibling hosts and paths.
+		// Duplicate names still collapse because a flat map cannot represent them.
+		const entries: [string, string][] = [];
+		for (const cookie of this.serialize().jar.cookies) {
+			if (typeof cookie.key === "string" && typeof cookie.value === "string" && cookie.key) {
+				entries.push([cookie.key, cookie.value]);
+			}
+		}
+		return Object.fromEntries(entries);
 	}
 
 	restore(cookies: Record<string, string>): void {
 		this.clear();
 		for (const [name, value] of Object.entries(cookies)) {
-			if (name) this.cookies[name] = value;
+			if (!name) continue;
+			this.cookies.setCookieSync(new Cookie({ key: name, path: "/", value }), this.defaultUrl, {
+				ignoreError: true,
+			});
 		}
 	}
 
-	clear(): void {
-		for (const name of Object.keys(this.cookies)) {
-			delete this.cookies[name];
+	serialize(): StealthCookieStoreV1 {
+		const jar = this.cookies.serializeSync();
+		if (!jar) {
+			throw new SDKError("Stealth cookie store could not be serialized", {
+				code: "stealth_cookie_store_serialize_failed",
+			});
+		}
+		return { version: 1, jar };
+	}
+
+	deserialize(state: StealthCookieStore): void {
+		const version = isRecord(state) ? state.version : undefined;
+		if (version !== 1) {
+			throw new StealthCookieStoreVersionError(version);
 		}
+
+		// Deserialize into a new jar first so invalid state cannot partially clear
+		// or replace a live session. tough-cookie restores the cookie attributes and
+		// matching semantics represented in its own serialized format.
+		const restored = ToughCookieJar.deserializeSync(state.jar);
+		// tough-cookie 6 does not include this option in serializeSync(). Preserve
+		// the SDK's stricter setting across restoration.
+		Reflect.set(restored, "allowSecureOnLocal", false);
+		this.cookies = restored;
+	}
+
+	clear(): void {
+		this.cookies.removeAllCookiesSync();
 	}
 
-	find(predicate: (cookie: string) => boolean): string | undefined {
-		for (const [name, value] of Object.entries(this.cookies)) {
-			const cookie = `${name}=${value}`;
-			if (predicate(cookie)) {
-				return cookie;
+	find(predicate: (cookie: string) => boolean, url?: string): string | undefined {
+		for (const cookie of this.getUniqueCookies(url ?? this.defaultUrl)) {
+			const cookieString = cookie.cookieString();
+			if (predicate(cookieString)) {
+				return cookieString;
 			}
 		}
 
 		return undefined;
 	}
+
+	private normalizeUrl(url: string): string | undefined {
+		try {
+			return new URL(url).toString();
+		} catch {
+			return undefined;
+		}
+	}
+
+	private getUniqueCookies(url: string): Cookie[] {
+		const cookieUrl = this.normalizeUrl(url);
+		if (!cookieUrl) return [];
+
+		// tough-cookie returns longer (more-specific) paths first. Keeping the
+		// first cookie for each name prevents ambiguous duplicate-name headers.
+		const names = new Set<string>();
+		return this.cookies.getCookiesSync(cookieUrl).filter((cookie) => {
+			if (names.has(cookie.key)) return false;
+			names.add(cookie.key);
+			return true;
+		});
+	}
 }
 
 function closestImpitBrowser(
@@ -280,12 +372,12 @@ function hasOwn(object: object, key: string): boolean {
 }
 function toImpitCookieJar(cookieJar: CookieJarImpl): NonNullable<ImpitOptions["cookieJar"]> {
 	return {
-		setCookie(cookie: string, _url: string, cb?: (error?: unknown) => void) {
-			cookieJar.setFromCookieStrings([cookie]);
+		setCookie(cookie: string, url: string, cb?: (error?: unknown) => void) {
+			cookieJar.setFromCookieStrings([cookie], url);
 			if (typeof cb === "function") cb();
 		},
-		getCookieString(_url: string) {
-			return cookieJar.toString();
+		getCookieString(url: string) {
+			return cookieJar.toHeader(url);
 		},
 	};
 }
@@ -337,10 +429,17 @@ function splitCombinedSetCookieHeader(headerValue: string): string[] {
 export async function normalizeResponse(
 	response: StealthTransportResponse,
 	requestUrl?: string,
+	maxBodyBytes?: number,
 ): Promise<StealthResponse> {
 	const headers = Object.fromEntries(response.headers.entries());
-	const cookies = new CookieJarImpl(setCookieHeadersFromResponse(response.headers));
-	const bodyBytes = await response.arrayBuffer();
+	const cookies = new CookieJarImpl(
+		setCookieHeadersFromResponse(response.headers),
+		response.url ?? requestUrl,
+	);
+	const bodyBytes =
+		maxBodyBytes === undefined
+			? await response.arrayBuffer()
+			: await readResponseBodyWithLimit(response, maxBodyBytes);
 	const body = new TextDecoder().decode(bodyBytes);
 
 	return {
@@ -368,6 +467,83 @@ export async function normalizeResponse(
 	};
 }
 
+function responseTooLargeError(maxBodyBytes: number, observedBytes: number): TransportError {
+	return new TransportError(
+		`Response body exceeded maxBodyBytes limit of ${maxBodyBytes} bytes (observed ${observedBytes} bytes)`,
+		{
+			code: "response_too_large",
+			category: "upstream_http",
+			retryable: false,
+			status: 0,
+		},
+	);
+}
+
+function declaredContentLength(headers: Headers): number | undefined {
+	const contentLength = headers.get("content-length")?.trim();
+	if (!contentLength || !/^\d+$/.test(contentLength)) return undefined;
+	const parsed = Number(contentLength);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function abortTransportResponse(response: StealthTransportResponse): boolean {
+	if (!response.abort) return false;
+	try {
+		response.abort();
+	} catch {
+		// The size error remains the primary failure if impit has already closed the response.
+	}
+	return true;
+}
+
+async function readResponseBodyWithLimit(
+	response: StealthTransportResponse,
+	maxBodyBytes: number,
+): Promise<ArrayBuffer> {
+	const contentLength = declaredContentLength(response.headers);
+	if (contentLength !== undefined && contentLength > maxBodyBytes) {
+		if (!abortTransportResponse(response)) {
+			await response.body?.cancel().catch(() => undefined);
+		}
+		throw responseTooLargeError(maxBodyBytes, contentLength);
+	}
+
+	if (!response.body) {
+		throw new TransportError("Response body stream is unavailable", {
+			code: "transport_stream_unavailable",
+			category: "upstream_http",
+			status: 0,
+		});
+	}
+
+	const reader = response.body.getReader();
+	const chunks: Uint8Array[] = [];
+	let receivedBytes = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			receivedBytes += value.byteLength;
+			if (receivedBytes > maxBodyBytes) {
+				await reader.cancel().catch(() => undefined);
+				abortTransportResponse(response);
+				throw responseTooLargeError(maxBodyBytes, receivedBytes);
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+
+	const bodyBytes = new Uint8Array(receivedBytes);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bodyBytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return bodyBytes.buffer;
+}
+
 function normalizeBody(body: StealthFetchOptions["body"]): string {
 	if (body === undefined) {
 		return "";
@@ -426,6 +602,7 @@ type ResolvedAttemptProxy = {
 	url?: string;
 	poolIndex?: number;
 	proxyHash?: string;
+	vendor?: ProxyVendorName;
 };
 
 function proxyPoolIndexFromDiagnostics(
@@ -559,16 +736,6 @@ function normalizeMethod(method: HttpMethod | string): StealthMethod {
 	}
 }
 
-function isRedirectStatus(status: number): boolean {
-	return [301, 302, 303, 307, 308].includes(status);
-}
-
-function nextRedirectMethod(status: number, method: StealthMethod): StealthMethod {
-	if (status === 303 && method !== "HEAD") return "GET";
-	if ((status === 301 || status === 302) && method === "POST") return "GET";
-	return method;
-}
-
 function locationHeader(headers: Record<string, string>): string | undefined {
 	for (const [name, value] of Object.entries(headers)) {
 		if (name.toLowerCase() === "location") return value;
@@ -585,7 +752,7 @@ function createSessionFetcher(
 	let closed = false;
 	let hasWarnedMissingProxy = false;
 	const warn = clientOptions.warn ?? console.warn;
-	const cookieJar = new CookieJarImpl([]);
+	const cookieJar = new CookieJarImpl([], baseUrl);
 	const impitCookieJar = toImpitCookieJar(cookieJar);
 
 	function getClient(
@@ -615,6 +782,7 @@ function createSessionFetcher(
 	async function resolveRequestProxy(
 		options?: StealthFetchOptions,
 		proxyAttempt?: number,
+		refreshEpoch?: number,
 	): Promise<ResolvedAttemptProxy> {
 		const resolvedProxy = await resolveProxyConfigAsync({
 			proxy: options?.proxy ?? clientOptions.proxy,
@@ -626,6 +794,10 @@ function createSessionFetcher(
 				proxyAttemptOffset: options?.proxyAttemptOffset,
 				retryAttemptOffset: proxyAttempt,
 			}),
+			// The impit stealth transport tunnels both HTTP CONNECT and SOCKS5,
+			// preserving the client TLS fingerprint end-to-end.
+			transportProtocols: ["http", "socks5"],
+			...(refreshEpoch === undefined ? {} : { proxyRefreshEpoch: refreshEpoch }),
 			telemetry: clientOptions.telemetry,
 		});
 
@@ -638,42 +810,65 @@ function createSessionFetcher(
 			url: resolvedProxy.url,
 			poolIndex: proxyPoolIndexFromDiagnostics(resolvedProxy.diagnostics),
 			proxyHash: proxyEndpointHash(resolvedProxy.url),
+			vendor: vendorFromResolvedSource(resolvedProxy.source),
 		};
 	}
 
 	const session: StealthSession = {
 		async fetch(url, options: StealthFetchOptions = {}) {
-			const method = normalizeMethod(options.method ?? "GET");
-			const hasExplicitRetryPolicy = options.retry !== undefined;
-			const stealthRetryOptions =
-				normalizeProxyTransportRetryOptions(options.retry, {
-					extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
-					label: "Stealth",
-				}) ??
-				(hasExplicitRetryPolicy
-					? undefined
-					: createDefaultProxyTransportRetryOptions({
+			const { hasExplicitRetryPolicy, method, stealthRetryOptions } = (() => {
+				try {
+					const method = normalizeMethod(options.method ?? "GET");
+					const hasExplicitRetryPolicy = options.retry !== undefined;
+					const stealthRetryOptions =
+						normalizeProxyTransportRetryOptions(options.retry, {
 							extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
 							label: "Stealth",
-						}));
-			if (stealthRetryOptions) {
-				validateUnsafeProxyTransportRetryMethods(stealthRetryOptions, "Stealth");
-			}
+						}) ??
+						(hasExplicitRetryPolicy
+							? undefined
+							: createDefaultProxyTransportRetryOptions({
+									extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
+									label: "Stealth",
+								}));
+					if (stealthRetryOptions) {
+						validateUnsafeProxyTransportRetryMethods(stealthRetryOptions, "Stealth");
+					}
+					return { hasExplicitRetryPolicy, method, stealthRetryOptions };
+				} catch (error) {
+					throw redactSensitiveRequestError(error, url, options.sensitiveParams);
+				}
+			})();
 			const hasPolicyProxy = isPolicyManagedProxy(clientOptions);
 			const usesPolicyAllocator = hasPolicyProxy && !options.proxy && !clientOptions.proxy;
 			const retryAttemptCap = Math.max(1, stealthRetryOptions?.attempts ?? 1);
+			// Span the whole vendor chain: successive attempts rotate one vendor's
+			// pool, then fail over to the next vendor via the flat attempt index.
+			const policyProxy =
+				clientOptions.proxyPolicy ??
+				(typeof clientOptions.upstream?.proxy === "object"
+					? clientOptions.upstream.proxy
+					: undefined);
+			// The pool span is already bounded by each vendor's max pool size
+			// (smartproxy ≤20, nodemaven ≤50), so the configured span never exceeds
+			// the chain's true maximum — a large NodeMaven pool stays fully
+			// reachable rather than being truncated at an arbitrary ceiling.
 			const policyProxyAttemptCap = Math.max(
 				1,
-				Math.min(
-					MAX_POLICY_PROXY_RETRY_ATTEMPTS,
-					clientOptions.proxyPolicy?.session?.poolSize ??
-						(typeof clientOptions.upstream?.proxy === "object"
-							? clientOptions.upstream.proxy.session?.poolSize
-							: undefined) ??
-						DEFAULT_SMARTPROXY_POOL_SIZE,
-				),
+				policyProxy ? resolvePolicyProxyPoolSpan(policyProxy) : DEFAULT_SMARTPROXY_POOL_SIZE,
 			);
-			const maxAttempts = usesPolicyAllocator ? policyProxyAttemptCap : retryAttemptCap;
+			// A registry vendor chain (smartproxy/nodemaven) is the only policy whose
+			// successive attempts resolve a *different* endpoint, so it is the only one
+			// that may widen the attempt cap to the pool span, de-duplicate endpoints,
+			// and drive allocator stale-pool refresh. A static custom/decodo policy
+			// resolves the same URL every attempt: widening/refreshing it would resend
+			// the request dozens of times (up to maxAttempts × refreshes) and bypass
+			// retry:false and unsafe-method controls. Static policies therefore follow
+			// the ordinary transport-retry budget instead.
+			const rotatesRegistryChain =
+				usesPolicyAllocator && policyResolvesRegistryVendorChain(policyProxy);
+			const maxAttempts = rotatesRegistryChain ? policyProxyAttemptCap : retryAttemptCap;
+			const dedupeAllocatorEndpoints = rotatesRegistryChain;
 			let lastError: unknown;
 
 			for (
@@ -688,6 +883,11 @@ function createSessionFetcher(
 				for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
 					let proxy: string | undefined;
 					let attemptProxy: ResolvedAttemptProxy | undefined;
+					// Reuse the exact serialization used by this outbound attempt in its catch path.
+					let serializedUrl: ReturnType<typeof serializeRequestUrl> | undefined;
+					let fallbackSensitiveValues: readonly string[] = [];
+					let fallbackRequestUrl: string | undefined;
+					let fallbackRedactedUrl: string | undefined;
 					const attemptStartedAt = Date.now();
 					let attemptRecorded = false;
 					const recordProxyAttempt = (
@@ -698,7 +898,7 @@ function createSessionFetcher(
 						if (attemptRecorded || !proxy) return;
 						attemptRecorded = true;
 						clientOptions.telemetry?.recordProxyAttempt?.({
-							provider: "smartproxy",
+							provider: attemptProxy?.vendor ?? "smartproxy",
 							attempt: attempt + 1,
 							...(attemptProxy?.poolIndex === undefined
 								? {}
@@ -711,12 +911,27 @@ function createSessionFetcher(
 						});
 					};
 					try {
+						const sensitiveParams = normalizeSensitiveParams(options.sensitiveParams);
+						const structural = redactUrlQueryParams(url, Object.keys(sensitiveParams ?? {}));
+						fallbackSensitiveValues = [
+							...new Set([
+								...Object.values(sensitiveParams ?? {}).map(String),
+								...structural.sensitiveValues,
+							]),
+						].filter((value) => value !== "");
+						fallbackRequestUrl = url;
+						fallbackRedactedUrl = structural.redactedUrl;
 						assertNoUnsupportedFingerprintOverrides(options);
-						attemptProxy = await resolveRequestProxy(options, attempt);
+						attemptProxy = await resolveRequestProxy(options, attempt, refreshAttempt);
 						proxy = attemptProxy.url;
-						if (proxy && usesPolicyAllocator) {
+						if (proxy && dedupeAllocatorEndpoints) {
+							// An under-filled allocation repeats endpoints (via the modulo
+							// pool mapping) before the flat offset crosses into the next
+							// vendor. Skip an already-tried endpoint and advance the offset
+							// rather than breaking — breaking here would strand the request on
+							// the primary vendor and never reach the fallback leg.
 							if (attemptedProxies.has(proxy)) {
-								break;
+								continue;
 							}
 							attemptedProxies.add(proxy);
 						}
@@ -725,10 +940,15 @@ function createSessionFetcher(
 								(!hasPolicyProxy && proxy && clientOptions.proxyStealth?.insecureSkipVerify),
 						);
 						const profileName = options.profile ?? defaultProfile;
-						const requestUrl = appendQueryParams(resolveUrl(baseUrl, url), options.params);
+						serializedUrl = serializeRequestUrl(
+							resolveUrl(baseUrl, url),
+							options.params,
+							sensitiveParams,
+						);
+						const { requestUrl } = serializedUrl;
 						const headers = { ...(options.headers ?? {}) };
 						if (!hasHeader(headers, "Cookie")) {
-							const cookieHeader = cookieJar.toString();
+							const cookieHeader = cookieJar.toHeader(requestUrl);
 							if (cookieHeader) headers.Cookie = cookieHeader;
 						}
 						const requestInit: StealthRequestInit = {
@@ -744,8 +964,11 @@ function createSessionFetcher(
 							requestUrl,
 							requestInit,
 						);
-						const normalized = await normalizeResponse(response, requestUrl);
-						cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers));
+						const normalized = await normalizeResponse(response, requestUrl, options.maxBodyBytes);
+						cookieJar.setFromCookieStrings(
+							setCookieHeadersFromResponse(response.headers),
+							response.url ?? requestUrl,
+						);
 
 						if (proxy && isProxyConnectFailureResponse(response, normalized.body)) {
 							throw createProxyConnectFailureError(normalized.body);
@@ -789,16 +1012,36 @@ function createSessionFetcher(
 						recordProxyAttempt("ok", undefined, response.status);
 						return normalized;
 					} catch (error) {
-						const normalizedError = normalizeStealthTransportError(error);
+						const sensitiveValues = serializedUrl?.sensitiveValues ?? fallbackSensitiveValues;
+						let normalizedError: TransportError;
+						try {
+							normalizedError = normalizeStealthTransportError(error);
+						} catch (normalizationError) {
+							throw redactSensitiveError(
+								normalizationError,
+								sensitiveValues,
+								serializedUrl?.requestUrl ?? fallbackRequestUrl,
+								serializedUrl?.redactedUrl ?? fallbackRedactedUrl,
+							);
+						}
+						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;
-						if (proxy && usesPolicyAllocator && isProxyPoolRefreshableError(normalizedError)) {
+						if (proxy && rotatesRegistryChain && refreshableProxyError) {
 							stalePoolError = normalizedError;
-							if (shouldRunProxyAuthDiagnostic(normalizedError)) {
+							if (runProxyAuthDiagnostic) {
 								stalePoolDiagnosticProxy = proxy;
 							}
 							if (attempt + 1 < maxAttempts) {
@@ -806,13 +1049,30 @@ function createSessionFetcher(
 							}
 							break;
 						}
+						// 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
+						// failure is a signal to advance to the next endpoint — potentially
+						// crossing into the fallback vendor — not to retry the same endpoint.
+						// Truncating that rotation at the per-endpoint retry budget would
+						// strand the request on the primary vendor and never reach the
+						// fallback, since the crossover only happens once the flat attempt
+						// index exceeds the primary vendor's pool size (~10-20).
+						// resolvePolicyTransportAttemptCap widens to the full chain span only
+						// for implicit, safe-method allocator requests; explicit retry
+						// policies (their documented `attempts` ceiling), unsafe methods, and
+						// static/non-registry vendors keep the per-endpoint retry budget.
+						const transportRetryCap = resolvePolicyTransportAttemptCap({
+							policy: policyProxy,
+							usesPolicyAllocator,
+							retryAttempts: stealthRetryOptions?.attempts ?? 1,
+							explicitRetry: hasExplicitRetryPolicy,
+							method,
+						});
 						if (
-							attempt + 1 <
-								(stealthRetryOptions
-									? Math.min(maxAttempts, stealthRetryOptions.attempts)
-									: maxAttempts) &&
+							attempt + 1 < transportRetryCap &&
 							shouldRetryProxyTransportAttempt({
-								error: normalizedError,
+								error: { code: retryErrorCode },
 								explicitRetry: hasExplicitRetryPolicy,
 								method,
 								options: stealthRetryOptions,
@@ -829,7 +1089,7 @@ function createSessionFetcher(
 				}
 
 				if (
-					usesPolicyAllocator &&
+					rotatesRegistryChain &&
 					stalePoolError &&
 					refreshAttempt < MAX_POLICY_PROXY_POOL_REFRESHES
 				) {
@@ -882,25 +1142,99 @@ function createSessionFetcher(
 					options.maxHops === undefined || !Number.isFinite(options.maxHops)
 						? 10
 						: Math.max(0, Math.floor(options.maxHops));
+				const {
+					url: _url,
+					maxHops: _maxHops,
+					stopWhen,
+					params,
+					sensitiveParams,
+					...fetchOptions
+				} = options;
 				const hops: StealthRedirectHop[] = [];
-				let currentUrl = resolveUrl(baseUrl, options.url);
 				let method = normalizeMethod(options.method ?? "GET");
 				let body = options.body;
 				let response: StealthResponse | undefined;
 				const visitedRequests = new Set<string>();
-
-				const { url: _url, maxHops: _maxHops, stopWhen, params, ...fetchOptions } = options;
+				const initialParams = params
+					? Object.fromEntries(
+							Object.entries(params).map(([key, value]) => [
+								key,
+								Array.isArray(value) ? [...value] : value,
+							]),
+						)
+					: undefined;
+				const normalizedSensitiveParams = normalizeSensitiveParams(sensitiveParams);
+				const initialSensitiveParams = normalizedSensitiveParams
+					? { ...normalizedSensitiveParams }
+					: undefined;
+				const sensitiveParamNames = initialSensitiveParams
+					? Object.keys(initialSensitiveParams)
+					: [];
+				const callerStructural = redactUrlQueryParams(options.url, sensitiveParamNames);
+				const sensitiveValues = new Set(
+					[
+						...Object.values(initialSensitiveParams ?? {}),
+						...callerStructural.sensitiveValues,
+					].filter((value) => value !== ""),
+				);
+				const redactRedirectUrl = (value: string): string => {
+					const structural = redactUrlQueryParams(value, [
+						...new Set([...sensitiveParamNames, ...sensitiveQueryParamNames(value)]),
+					]);
+					for (const sensitiveValue of structural.sensitiveValues) {
+						sensitiveValues.add(sensitiveValue);
+					}
+					return redactSensitiveText(structural.redactedUrl, [...sensitiveValues]);
+				};
+				let currentUrl: string;
+				let initialUrl: ReturnType<typeof serializeRequestUrl>;
+				try {
+					currentUrl = resolveUrl(baseUrl, options.url);
+					redactRedirectUrl(currentUrl);
+					initialUrl = serializeRequestUrl(currentUrl, initialParams, initialSensitiveParams);
+					for (const value of initialUrl.sensitiveValues) {
+						if (value !== "") sensitiveValues.add(value);
+					}
+				} catch (error) {
+					throw redactSensitiveError(
+						error,
+						[...sensitiveValues],
+						options.url,
+						redactRedirectUrl(options.url),
+					);
+				}
 
 				for (let hopIndex = 0; hopIndex <= maxHops; hopIndex += 1) {
-					visitedRequests.add(`${method} ${currentUrl}`);
-					response = await session.fetch(currentUrl, {
-						...fetchOptions,
-						body,
-						method,
-						...(hopIndex === 0 && params ? { params } : {}),
-						redirect: "manual",
-						throwOnHttpError: false,
-					});
+					const outboundUrl =
+						hopIndex === 0 ? initialUrl.requestUrl : serializeRequestUrl(currentUrl).requestUrl;
+					// Preserve params-only loop bookkeeping from before sensitiveParams:
+					// the first visited key is the caller's resolved URL, not its expanded query.
+					const visitedUrl = hopIndex === 0 && !initialSensitiveParams ? currentUrl : outboundUrl;
+					visitedRequests.add(`${method} ${visitedUrl}`);
+					try {
+						response = await session.fetch(currentUrl, {
+							...fetchOptions,
+							body,
+							method,
+							...(hopIndex === 0 && initialParams ? { params: initialParams } : {}),
+							...(hopIndex === 0 && initialSensitiveParams
+								? { sensitiveParams: initialSensitiveParams }
+								: {}),
+							redirect: "manual",
+							throwOnHttpError: false,
+						});
+					} catch (error) {
+						throw redactSensitiveError(
+							error,
+							[...sensitiveValues],
+							outboundUrl,
+							redactRedirectUrl(outboundUrl),
+						);
+					}
+					// StealthResponse.url is programmatic metadata and remains raw. Only the
+					// redirect hop emitted below is a diagnostic surface.
+					const responseUrl =
+						response.url ?? (hopIndex === 0 && initialSensitiveParams ? outboundUrl : currentUrl);
 
 					if (!isRedirectStatus(response.status)) {
 						return {
@@ -908,63 +1242,79 @@ function createSessionFetcher(
 							hops,
 							reason: "completed",
 							cookies: cookieJar.snapshot(),
+							cookieStore: cookieJar.serialize(),
 						};
 					}
 
 					const location = locationHeader(response.headers);
-					const nextUrl = location
-						? new URL(location, response.url ?? currentUrl).toString()
-						: undefined;
-					const hop: StealthRedirectHop = {
-						url: response.url ?? currentUrl,
+					const redactedResponseUrl = redactRedirectUrl(responseUrl);
+					const redactedLocation = location ? redactRedirectUrl(location) : undefined;
+					let nextUrl: string | undefined;
+					try {
+						nextUrl = resolveRedirectUrl(location, responseUrl);
+					} catch (error) {
+						throw redactSensitiveError(error, [...sensitiveValues], location, redactedLocation);
+					}
+					const realHop: StealthRedirectHop = {
+						url: responseUrl,
 						status: response.status,
 						method,
 						...(location ? { location } : {}),
 						...(nextUrl ? { nextUrl } : {}),
 					};
+					const hop: StealthRedirectHop = {
+						...realHop,
+						url: redactedResponseUrl,
+						...(redactedLocation ? { location: redactedLocation } : {}),
+						...(nextUrl ? { nextUrl: redactRedirectUrl(nextUrl) } : {}),
+					};
 					hops.push(hop);
 
-					if (stopWhen && (await stopWhen(hop))) {
-						return {
-							final: response,
-							hops,
-							reason: "stopped",
-							cookies: cookieJar.snapshot(),
-						};
-					}
-
-					if (!nextUrl) {
-						return {
-							final: response,
-							hops,
-							reason: "missing_location",
-							cookies: cookieJar.snapshot(),
-						};
+					let shouldStop = false;
+					if (stopWhen) {
+						try {
+							shouldStop = await stopWhen(realHop);
+						} catch (error) {
+							let sanitizedError: unknown = error;
+							for (const [rawUrl, safeUrl] of [
+								[responseUrl, redactedResponseUrl],
+								[location, redactedLocation],
+								[nextUrl, nextUrl ? redactRedirectUrl(nextUrl) : undefined],
+							] as const) {
+								if (!rawUrl || !safeUrl) continue;
+								sanitizedError = redactSensitiveError(
+									sanitizedError,
+									[...sensitiveValues],
+									rawUrl,
+									safeUrl,
+								);
+							}
+							throw sanitizedError;
+						}
 					}
-
-					if (hops.length > maxHops) {
+					const decision = evaluateRedirectHop({
+						status: response.status,
+						method,
+						nextUrl,
+						shouldStop,
+						redirectCount: hops.length,
+						maxHops,
+						visitedRequests,
+					});
+					if (decision.kind === "stop") {
 						return {
 							final: response,
 							hops,
-							reason: "max_hops",
+							reason: decision.reason,
 							cookies: cookieJar.snapshot(),
+							cookieStore: cookieJar.serialize(),
 						};
 					}
-
-					const nextMethod = nextRedirectMethod(response.status, method);
-					if (nextMethod !== method) {
+					if (decision.nextMethod !== method) {
 						body = undefined;
 					}
-					if (visitedRequests.has(`${nextMethod} ${nextUrl}`)) {
-						return {
-							final: response,
-							hops,
-							reason: "loop",
-							cookies: cookieJar.snapshot(),
-						};
-					}
-					method = nextMethod;
-					currentUrl = nextUrl;
+					method = decision.nextMethod;
+					currentUrl = decision.nextUrl;
 				}
 
 				if (!response) {
@@ -982,6 +1332,7 @@ function createSessionFetcher(
 					hops,
 					reason: "max_hops",
 					cookies: cookieJar.snapshot(),
+					cookieStore: cookieJar.serialize(),
 				};
 			},
 		},