@apifuse/provider-sdk 2.2.0-beta.4 → 2.2.0-beta.40

package/dist/runtime/stealth.js

@@ -1,20 +1,38 @@
 import { createHash } from "node:crypto";
-import { Impit } from "impit";
-import { DEFAULT_SMARTPROXY_POOL_SIZE, invalidateProxyResolutionCacheAsync, ProxyResolutionError, resolveProxyConfigAsync, SMARTPROXY_MAX_POOL_SIZE, } from "../config/loader.js";
+import { DEFAULT_SMARTPROXY_POOL_SIZE, invalidateProxyResolutionCacheAsync, ProxyResolutionError, policyResolvesRegistryVendorChain, resolvePolicyProxyPoolSpan, resolvePolicyTransportAttemptCap, resolveProxyConfigAsync, vendorFromResolvedSource, } from "../config/loader.js";
 import { SDKError, TransportError } from "../errors.js";
 import { getStealthProfile } from "../stealth/profiles.js";
+import { StealthCookieJar } from "./stealth-cookies.js";
 import { createProxyAuthIpDeniedError, createProxyEdgeAuthRejectedError, createProxyEdgeTlsRejectedError, createProxyPoolExhaustedError, createProxyPoolStaleError, isProxyAuthIpDeniedMessage, isProxyEdgeAuthRejectedMessage, isProxyEdgeTlsRejectedResponse, isProxyPoolRefreshableError, isProxyPoolStaleMessage, isProxyPoolStaleStatus, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_STALE_CODE, } from "./proxy-errors.js";
 import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, normalizeProxyTransportRetryOptions, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy.js";
-import { appendQueryParams } from "./request-options.js";
-const DEFAULT_PROFILE = "chrome-146";
+import { evaluateRedirectHop, isRedirectStatus, nextRedirectMethod, resolveRedirectUrl, } from "./redirects.js";
+import { isSensitiveKey, normalizeSensitiveParams, redactSensitiveError, redactSensitiveRequestError, redactSensitiveText, redactUrlQueryParams, serializeRequestUrl, } from "./request-options.js";
+export const DEFAULT_PROFILE = "chrome-146";
 const MISSING_PROXY_WARNING = "[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
-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 = /\bproxy\b.*\b(non[\s-]?200|connect|tunnel)|\bconnect\b.*\bproxy\b|\btunnel\b/i;
 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];
+const MAX_STEALTH_REDIRECT_HOPS = 10;
+const REDIRECT_BODY_HEADERS = new Set([
+    "content-encoding",
+    "content-language",
+    "content-location",
+    "content-type",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function sensitiveQueryParamNames(url) {
+    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);
+}
 const REMOVED_CHROME_PROFILE_NAMES = new Set([
     "chrome-120",
     "chrome-124",
@@ -28,133 +46,93 @@ const REMOVED_CHROME_PROFILE_NAMES = new Set([
     "chrome-130-psk",
     "edge-131",
 ]);
-const CHROME_IMPIT_BY_MAJOR = {
-    100: "chrome100",
-    101: "chrome101",
-    104: "chrome104",
-    107: "chrome107",
-    110: "chrome110",
-    116: "chrome116",
-    124: "chrome124",
-    125: "chrome125",
-    131: "chrome131",
-    136: "chrome136",
-    142: "chrome142",
-};
-const FIREFOX_IMPIT_BY_MAJOR = {
-    128: "firefox128",
-    133: "firefox133",
-    135: "firefox135",
-    144: "firefox144",
-};
-function isRecord(value) {
-    return typeof value === "object" && value !== null;
-}
-class CookieJarImpl {
-    cookies;
-    constructor(cookieStrings) {
-        this.cookies = {};
-        this.setFromCookieStrings(cookieStrings);
-    }
-    setFromCookieStrings(cookieStrings) {
-        for (const cookieString of cookieStrings) {
-            const [nameValue] = cookieString.split(";");
-            if (!nameValue) {
-                continue;
-            }
-            const separatorIndex = nameValue.indexOf("=");
-            if (separatorIndex === -1) {
-                continue;
-            }
-            const name = nameValue.slice(0, separatorIndex).trim();
-            const value = nameValue.slice(separatorIndex + 1).trim();
-            if (name)
-                this.cookies[name] = value;
-        }
-    }
-    get(name) {
-        return this.cookies[name];
-    }
-    getAll() {
-        return { ...this.cookies };
-    }
-    has(name) {
-        return Object.hasOwn(this.cookies, name);
-    }
-    toString() {
-        return Object.entries(this.cookies)
-            .map(([name, value]) => `${name}=${value}`)
-            .join("; ");
-    }
-    toHeader() {
-        return this.toString();
+let wreqModulePromise;
+function getWreqModule() {
+    if (!wreqModulePromise) {
+        wreqModulePromise = import("wreq-js").catch((error) => {
+            throw new SDKError(`Stealth transport is unavailable on ${process.platform}-${process.arch}: the wreq-js native binary could not be loaded.`, {
+                code: "stealth_transport_unavailable",
+                cause: error instanceof Error ? error : undefined,
+            });
+        });
     }
-    snapshot() {
-        return this.getAll();
+    return wreqModulePromise;
+}
+function parseProfileIdentifier(identifier) {
+    const match = /^(safari_ios|safari_ipad|firefox_android|firefox_private|chrome|edge|firefox|opera|safari|okhttp)_(\d+(?:[._]\d+)*)$/.exec(identifier.toLowerCase());
+    if (!match?.[1] || !match[2])
+        return null;
+    return {
+        family: match[1],
+        version: match[2].split(/[._]/).map(Number),
+    };
+}
+function compareVersionDistance(target, left, right) {
+    const width = Math.max(target.length, left.length, right.length);
+    for (let index = 0; index < width; index += 1) {
+        const targetPart = target[index] ?? 0;
+        const leftDistance = Math.abs((left[index] ?? 0) - targetPart);
+        const rightDistance = Math.abs((right[index] ?? 0) - targetPart);
+        if (leftDistance !== rightDistance)
+            return leftDistance - rightDistance;
     }
-    restore(cookies) {
-        this.clear();
-        for (const [name, value] of Object.entries(cookies)) {
-            if (name)
-                this.cookies[name] = value;
+    return 0;
+}
+function closestWreqProfile(identifier, wreqProfiles) {
+    const requested = parseProfileIdentifier(identifier);
+    if (!requested)
+        return undefined;
+    let closest;
+    for (const candidateName of wreqProfiles) {
+        const candidate = parseProfileIdentifier(candidateName);
+        if (!candidate || candidate.family !== requested.family)
+            continue;
+        if (!closest ||
+            compareVersionDistance(requested.version, candidate.version, closest.version) < 0) {
+            closest = { name: candidateName, version: candidate.version };
         }
     }
-    clear() {
-        for (const name of Object.keys(this.cookies)) {
-            delete this.cookies[name];
-        }
+    return closest?.name;
+}
+function resolveDefaultWreqProfileMapping() {
+    let profile;
+    try {
+        profile = getStealthProfile(DEFAULT_PROFILE);
     }
-    find(predicate) {
-        for (const [name, value] of Object.entries(this.cookies)) {
-            const cookie = `${name}=${value}`;
-            if (predicate(cookie)) {
-                return cookie;
-            }
-        }
-        return undefined;
+    catch (error) {
+        throw new SDKError(`Default stealth profile "${DEFAULT_PROFILE}" cannot be mapped to a wreq-js browser profile.`, { cause: error instanceof Error ? error : undefined });
     }
-}
-function closestImpitBrowser(major, candidates) {
-    let closestMajor;
-    let closestBrowser;
-    for (const [candidateMajorText, browser] of Object.entries(candidates)) {
-        const candidateMajor = Number(candidateMajorText);
-        if (closestMajor === undefined ||
-            Math.abs(candidateMajor - major) < Math.abs(closestMajor - major)) {
-            closestMajor = candidateMajor;
-            closestBrowser = browser;
-        }
+    const identifier = profile.tlsClientIdentifier?.toLowerCase() ?? "";
+    if (!parseProfileIdentifier(identifier)) {
+        throw new SDKError(`Default stealth profile "${DEFAULT_PROFILE}" cannot be mapped to a wreq-js browser profile.`);
     }
-    return closestBrowser ?? "chrome142";
+    return { identifier, os: profile.platform };
 }
-function resolveImpitBrowser(profileName) {
+const DEFAULT_WREQ_PROFILE_MAPPING = resolveDefaultWreqProfileMapping();
+export function resolveWreqProfile(profileName, wreqProfiles) {
     if (REMOVED_CHROME_PROFILE_NAMES.has(profileName)) {
         throw new SDKError(`Unknown stealth profile: ${profileName}`);
     }
-    let profile;
+    let identifier;
+    let os;
     try {
-        profile = getStealthProfile(profileName);
+        const profile = getStealthProfile(profileName);
+        identifier = profile.tlsClientIdentifier?.toLowerCase() ?? "";
+        os = profile.platform;
     }
     catch {
         // Preserve the previous ctx.stealth.fetch() compatibility behavior: unknown
         // profile strings still run with the transport default instead of failing
         // before the request starts. Removed built-in profile aliases above remain
         // explicit errors so callers do not accidentally pin retired fingerprints.
-        return "chrome142";
+        identifier = DEFAULT_WREQ_PROFILE_MAPPING.identifier;
+        os = DEFAULT_WREQ_PROFILE_MAPPING.os;
     }
-    const identifier = profile.tlsClientIdentifier?.toLowerCase() ?? "";
-    const chromeMatch = /^(?:chrome|edge)_(\d+)/.exec(identifier);
-    if (chromeMatch?.[1]) {
-        return closestImpitBrowser(Number(chromeMatch[1]), CHROME_IMPIT_BY_MAJOR);
+    const browser = closestWreqProfile(identifier, wreqProfiles);
+    if (!browser) {
+        throw new SDKError(`Stealth profile "${profileName}" cannot be mapped to a wreq-js browser profile.`);
     }
-    const firefoxMatch = /^firefox_(\d+)/.exec(identifier);
-    if (firefoxMatch?.[1]) {
-        return closestImpitBrowser(Number(firefoxMatch[1]), FIREFOX_IMPIT_BY_MAJOR);
-    }
-    if (identifier.startsWith("safari_")) {
-        throw new SDKError(`Stealth profile "${profileName}" uses a Safari stealth fingerprint, but TypeScript ctx.stealth uses impit which currently supports Chrome, Firefox, and OkHttp profiles only. Use a Chrome/Firefox stealth profile for ctx.stealth or ctx.browser for Safari-specific behavior.`);
-    }
-    throw new SDKError(`Stealth profile "${profileName}" cannot be mapped to an impit browser profile.`);
+    return { browser, os };
 }
 function resolveUrl(baseUrl, url) {
     return new URL(url, baseUrl).toString();
@@ -174,18 +152,6 @@ function normalizeHeaders(headers) {
 function hasOwn(object, key) {
     return Object.hasOwn(object, key);
 }
-function toImpitCookieJar(cookieJar) {
-    return {
-        setCookie(cookie, _url, cb) {
-            cookieJar.setFromCookieStrings([cookie]);
-            if (typeof cb === "function")
-                cb();
-        },
-        getCookieString(_url) {
-            return cookieJar.toString();
-        },
-    };
-}
 function assertNoUnsupportedFingerprintOverrides(options) {
     if (!isRecord(options))
         return;
@@ -199,7 +165,7 @@ function assertNoUnsupportedFingerprintOverrides(options) {
         unsupported.push("stealth.h2");
     if (unsupported.length === 0)
         return;
-    throw new SDKError(`ctx.stealth.fetch uses impit-managed browser fingerprints and no longer accepts low-level stealth overrides: ${unsupported.join(", ")}. Use the profile option instead.`);
+    throw new SDKError(`ctx.stealth.fetch uses transport-managed browser fingerprints and no longer accepts low-level stealth overrides: ${unsupported.join(", ")}. Use the profile option instead.`);
 }
 function responseHeadersToRecord(headers) {
     const record = {};
@@ -234,10 +200,12 @@ function splitCombinedSetCookieHeader(headerValue) {
         cookieStrings.push(finalCookie);
     return cookieStrings;
 }
-export async function normalizeResponse(response, requestUrl) {
+export async function normalizeResponse(response, requestUrl, maxBodyBytes) {
     const headers = Object.fromEntries(response.headers.entries());
-    const cookies = new CookieJarImpl(setCookieHeadersFromResponse(response.headers));
-    const bodyBytes = await response.arrayBuffer();
+    const cookies = new StealthCookieJar(setCookieHeadersFromResponse(response.headers), response.url ?? requestUrl);
+    const bodyBytes = maxBodyBytes === undefined
+        ? await response.arrayBuffer()
+        : await readResponseBodyWithLimit(response, maxBodyBytes);
     const body = new TextDecoder().decode(bodyBytes);
     return {
         status: response.status,
@@ -263,6 +231,63 @@ export async function normalizeResponse(response, requestUrl) {
         },
     };
 }
+function responseTooLargeError(maxBodyBytes, observedBytes) {
+    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) {
+    const contentLength = headers.get("content-length")?.trim();
+    if (!contentLength || !/^\d+$/.test(contentLength))
+        return undefined;
+    const parsed = Number(contentLength);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+async function readResponseBodyWithLimit(response, maxBodyBytes) {
+    const contentLength = declaredContentLength(response.headers);
+    if (contentLength !== undefined && contentLength > maxBodyBytes) {
+        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 = [];
+    let receivedBytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            receivedBytes += value.byteLength;
+            if (receivedBytes > maxBodyBytes) {
+                await reader.cancel().catch(() => undefined);
+                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) {
     if (body === undefined) {
         return "";
@@ -420,16 +445,6 @@ function normalizeMethod(method) {
             throw new SDKError(`Unsupported stealth method: ${method}`);
     }
 }
-function isRedirectStatus(status) {
-    return [301, 302, 303, 307, 308].includes(status);
-}
-function nextRedirectMethod(status, method) {
-    if (status === 303 && method !== "HEAD")
-        return "GET";
-    if ((status === 301 || status === 302) && method === "POST")
-        return "GET";
-    return method;
-}
 function locationHeader(headers) {
     for (const [name, value] of Object.entries(headers)) {
         if (name.toLowerCase() === "location")
@@ -437,43 +452,153 @@ function locationHeader(headers) {
     }
     return undefined;
 }
+function withoutRedirectBodyHeaders(headers) {
+    return Object.fromEntries(Object.entries(headers).filter(([name]) => !REDIRECT_BODY_HEADERS.has(name.toLowerCase())));
+}
+function assertStealthRedirectUrl(url) {
+    const protocol = new URL(url).protocol;
+    if (protocol !== "http:" && protocol !== "https:") {
+        throw new TransportError(`Stealth redirect target scheme "${protocol}" is not allowed`, {
+            code: "transport_invalid_url",
+            status: 0,
+        });
+    }
+}
+function discardStealthRedirectBody(response) {
+    try {
+        const cancellation = response.body?.cancel();
+        if (cancellation)
+            void cancellation.catch(() => undefined);
+    }
+    catch {
+        // Redirect handling is decided from status and headers. A cancellation
+        // failure must not replace or delay that decision.
+    }
+}
+async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, method, options) {
+    let currentUrl = requestUrl;
+    let currentMethod = method;
+    let currentBody = options.body === undefined ? undefined : normalizeBody(options.body);
+    let currentHeaders = { ...(options.headers ?? {}) };
+    let followedHops = 0;
+    let response;
+    const deadline = options.timeout ? performance.now() + options.timeout : undefined;
+    while (true) {
+        const headers = { ...currentHeaders };
+        if (!hasHeader(headers, "Cookie")) {
+            const cookieHeader = cookieJar.toHeader(currentUrl);
+            if (cookieHeader)
+                headers.Cookie = cookieHeader;
+        }
+        const requestInit = {
+            headers: normalizeHeaders(headers),
+            method: currentMethod,
+            redirect: "manual",
+        };
+        if (currentBody !== undefined)
+            requestInit.body = currentBody;
+        await transport.clearCookies();
+        const remainingTimeout = deadline === undefined ? undefined : Math.ceil(deadline - performance.now());
+        if (remainingTimeout !== undefined && remainingTimeout <= 0) {
+            throw new TransportError("Request timed out", {
+                code: "transport_timeout",
+                status: 0,
+            });
+        }
+        if (remainingTimeout !== undefined)
+            requestInit.timeout = remainingTimeout;
+        response = await transport.fetch(currentUrl, requestInit);
+        cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers), response.url ?? currentUrl);
+        if (!isRedirectStatus(response.status) || options.redirect === "manual")
+            break;
+        if (options.redirect === "error") {
+            discardStealthRedirectBody(response);
+            throw new TransportError("Stealth request encountered a redirect", {
+                code: "transport_network_error",
+                status: 0,
+            });
+        }
+        const nextUrl = resolveRedirectUrl(response.headers.get("location") ?? undefined, response.url ?? currentUrl);
+        if (!nextUrl)
+            break;
+        if (followedHops >= MAX_STEALTH_REDIRECT_HOPS) {
+            discardStealthRedirectBody(response);
+            throw new TransportError(`Stealth request exceeded the ${MAX_STEALTH_REDIRECT_HOPS}-redirect limit`, { code: "transport_network_error", status: 0 });
+        }
+        assertStealthRedirectUrl(nextUrl);
+        discardStealthRedirectBody(response);
+        const nextMethod = nextRedirectMethod(response.status, currentMethod);
+        if (nextMethod !== currentMethod) {
+            currentBody = undefined;
+            currentHeaders = withoutRedirectBodyHeaders(currentHeaders);
+        }
+        currentMethod = nextMethod;
+        currentUrl = nextUrl;
+        followedHops += 1;
+    }
+    const normalized = await normalizeResponse(response, currentUrl, options.maxBodyBytes);
+    if (followedHops > 0)
+        normalized.redirected = true;
+    return { normalized, response };
+}
 function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
     const clients = new Map();
     let closed = false;
     let hasWarnedMissingProxy = false;
     const warn = clientOptions.warn ?? console.warn;
-    const cookieJar = new CookieJarImpl([]);
-    const impitCookieJar = toImpitCookieJar(cookieJar);
-    function getClient(profileName, proxyUrl, ignoreTlsErrors) {
+    const cookieJar = new StealthCookieJar([], baseUrl);
+    async function getClientEntry(profileName, proxyUrl, ignoreTlsErrors) {
         if (closed) {
             throw new TransportError("Stealth session is closed", { status: 0 });
         }
-        const browser = resolveImpitBrowser(profileName);
+        const wreq = await getWreqModule();
+        const { browser, os } = resolveWreqProfile(profileName, wreq.getProfiles());
         const cacheKey = JSON.stringify({ browser, proxyUrl, ignoreTlsErrors });
-        let client = clients.get(cacheKey);
-        if (!client) {
-            client = new Impit({
-                browser,
-                cookieJar: impitCookieJar,
-                ...(proxyUrl ? { proxyUrl } : {}),
-                ...(ignoreTlsErrors ? { ignoreTlsErrors: true } : {}),
-                timeout: 30_000,
-            });
-            clients.set(cacheKey, client);
+        let entry = clients.get(cacheKey);
+        if (!entry) {
+            entry = {
+                session: wreq.createSession({
+                    browser,
+                    os,
+                    ...(proxyUrl ? { proxy: proxyUrl } : {}),
+                    ...(ignoreTlsErrors ? { insecure: true } : {}),
+                    timeout: 30_000,
+                }),
+                tail: Promise.resolve(),
+            };
+            clients.set(cacheKey, entry);
+        }
+        return entry;
+    }
+    async function withClient(profileName, proxyUrl, ignoreTlsErrors, operation) {
+        const entry = await getClientEntry(profileName, proxyUrl, ignoreTlsErrors);
+        const previous = entry.tail;
+        let release;
+        entry.tail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            return await operation(await entry.session);
+        }
+        finally {
+            release();
         }
-        return client;
     }
-    async function resolveRequestProxy(options, proxyAttempt) {
+    async function resolveRequestProxy(options, proxyAttempt, refreshEpoch) {
         const resolvedProxy = await resolveProxyConfigAsync({
             proxy: options?.proxy ?? clientOptions.proxy,
             upstream: clientOptions.upstream,
-            apifuseConfig: clientOptions.apifuseConfig,
             affinityKey: clientOptions.affinityKey,
             proxyAttempt: computeProxyAttemptIndex({
                 baseProxyAttempt: clientOptions.proxyAttempt,
                 proxyAttemptOffset: options?.proxyAttemptOffset,
                 retryAttemptOffset: proxyAttempt,
             }),
+            // The 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,
         });
         if (resolvedProxy.shouldWarn && !hasWarnedMissingProxy) {
@@ -484,34 +609,57 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
             url: resolvedProxy.url,
             poolIndex: proxyPoolIndexFromDiagnostics(resolvedProxy.diagnostics),
             proxyHash: proxyEndpointHash(resolvedProxy.url),
+            vendor: vendorFromResolvedSource(resolvedProxy.source),
         };
     }
     const session = {
         async fetch(url, options = {}) {
-            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);
-            const policyProxyAttemptCap = Math.max(1, Math.min(MAX_POLICY_PROXY_RETRY_ATTEMPTS, clientOptions.proxyPolicy?.session?.poolSize ??
+            // 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.session?.poolSize
-                    : undefined) ??
-                DEFAULT_SMARTPROXY_POOL_SIZE));
-            const maxAttempts = usesPolicyAllocator ? policyProxyAttemptCap : retryAttemptCap;
+                    ? 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, policyProxy ? resolvePolicyProxyPoolSpan(policyProxy) : DEFAULT_SMARTPROXY_POOL_SIZE);
+            // 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. Deprecated custom/decodo policies
+            // have no managed endpoint to rotate or refresh, so they follow the ordinary
+            // transport-retry budget instead.
+            const rotatesRegistryChain = usesPolicyAllocator && policyResolvesRegistryVendorChain(policyProxy);
+            const maxAttempts = rotatesRegistryChain ? policyProxyAttemptCap : retryAttemptCap;
+            const dedupeAllocatorEndpoints = rotatesRegistryChain;
             let lastError;
             for (let refreshAttempt = 0; refreshAttempt <= MAX_POLICY_PROXY_POOL_REFRESHES; refreshAttempt += 1) {
                 let stalePoolError;
@@ -520,6 +668,11 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                 for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
                     let proxy;
                     let attemptProxy;
+                    // Reuse the exact serialization used by this outbound attempt in its catch path.
+                    let serializedUrl;
+                    let fallbackSensitiveValues = [];
+                    let fallbackRequestUrl;
+                    let fallbackRedactedUrl;
                     const attemptStartedAt = Date.now();
                     let attemptRecorded = false;
                     const recordProxyAttempt = (outcome, errorCode, status) => {
@@ -527,7 +680,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             return;
                         attemptRecorded = true;
                         clientOptions.telemetry?.recordProxyAttempt?.({
-                            provider: "smartproxy",
+                            provider: attemptProxy?.vendor ?? "smartproxy",
                             attempt: attempt + 1,
                             ...(attemptProxy?.poolIndex === undefined
                                 ? {}
@@ -540,37 +693,36 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         });
                     };
                     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);
                         }
                         const ignoreTlsErrors = Boolean(options.stealth?.insecureSkipVerify ??
                             (!hasPolicyProxy && proxy && clientOptions.proxyStealth?.insecureSkipVerify));
                         const profileName = options.profile ?? defaultProfile;
-                        const requestUrl = appendQueryParams(resolveUrl(baseUrl, url), options.params);
-                        const headers = { ...(options.headers ?? {}) };
-                        if (!hasHeader(headers, "Cookie")) {
-                            const cookieHeader = cookieJar.toString();
-                            if (cookieHeader)
-                                headers.Cookie = cookieHeader;
-                        }
-                        const requestInit = {
-                            headers: normalizeHeaders(headers),
-                            method,
-                            ...(options.redirect ? { redirect: options.redirect } : {}),
-                            ...(options.timeout ? { timeout: options.timeout } : {}),
-                        };
-                        if (options.body !== undefined) {
-                            requestInit.body = normalizeBody(options.body);
-                        }
-                        const response = await getClient(profileName, proxy, ignoreTlsErrors).fetch(requestUrl, requestInit);
-                        const normalized = await normalizeResponse(response, requestUrl);
-                        cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers));
+                        serializedUrl = serializeRequestUrl(resolveUrl(baseUrl, url), options.params, sensitiveParams);
+                        const { requestUrl } = serializedUrl;
+                        const { normalized, response } = await withClient(profileName, proxy, ignoreTlsErrors, (transport) => fetchStealthRedirectChain(transport, cookieJar, requestUrl, method, options));
                         if (proxy && isProxyConnectFailureResponse(response, normalized.body)) {
                             throw createProxyConnectFailureError(normalized.body);
                         }
@@ -602,12 +754,23 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         return normalized;
                     }
                     catch (error) {
-                        const normalizedError = normalizeStealthTransportError(error);
+                        const sensitiveValues = serializedUrl?.sensitiveValues ?? fallbackSensitiveValues;
+                        let normalizedError;
+                        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) {
@@ -615,12 +778,29 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             }
                             break;
                         }
-                        if (attempt + 1 <
-                            (stealthRetryOptions
-                                ? Math.min(maxAttempts, stealthRetryOptions.attempts)
-                                : maxAttempts) &&
+                        // 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 < transportRetryCap &&
                             shouldRetryProxyTransportAttempt({
-                                error: normalizedError,
+                                error: { code: retryErrorCode },
                                 explicitRetry: hasExplicitRetryPolicy,
                                 method,
                                 options: stealthRetryOptions,
@@ -634,7 +814,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         throw normalizedError;
                     }
                 }
-                if (usesPolicyAllocator &&
+                if (rotatesRegistryChain &&
                     stalePoolError &&
                     refreshAttempt < MAX_POLICY_PROXY_POOL_REFRESHES) {
                     await invalidateProxyResolutionCacheAsync({
@@ -670,81 +850,153 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                 const maxHops = 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 = [];
-                let currentUrl = resolveUrl(baseUrl, options.url);
                 let method = normalizeMethod(options.method ?? "GET");
                 let body = options.body;
                 let response;
                 const visitedRequests = new Set();
-                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) => {
+                    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;
+                let initialUrl;
+                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 {
                             final: response,
                             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 = {
-                        url: response.url ?? currentUrl,
+                    const redactedResponseUrl = redactRedirectUrl(responseUrl);
+                    const redactedLocation = location ? redactRedirectUrl(location) : undefined;
+                    let nextUrl;
+                    try {
+                        nextUrl = resolveRedirectUrl(location, responseUrl);
+                    }
+                    catch (error) {
+                        throw redactSensitiveError(error, [...sensitiveValues], location, redactedLocation);
+                    }
+                    const realHop = {
+                        url: responseUrl,
                         status: response.status,
                         method,
                         ...(location ? { location } : {}),
                         ...(nextUrl ? { nextUrl } : {}),
                     };
+                    const hop = {
+                        ...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 = error;
+                            for (const [rawUrl, safeUrl] of [
+                                [responseUrl, redactedResponseUrl],
+                                [location, redactedLocation],
+                                [nextUrl, nextUrl ? redactRedirectUrl(nextUrl) : undefined],
+                            ]) {
+                                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) {
                     response = await session.fetch(currentUrl, {
@@ -761,23 +1013,35 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                     hops,
                     reason: "max_hops",
                     cookies: cookieJar.snapshot(),
+                    cookieStore: cookieJar.serialize(),
                 };
             },
         },
         close() {
             closed = true;
+            for (const client of clients.values()) {
+                void client.session
+                    .then((session) => session.close())
+                    .catch((error) => {
+                    const message = error instanceof Error ? error.message : String(error);
+                    warn(`[provider-sdk] Failed to close stealth transport session: ${message}`);
+                });
+            }
             clients.clear();
         },
     };
     return session;
     async function classifyProxyAuthDiagnostic(profileName, proxy) {
         try {
-            const response = await getClient(profileName, proxy, false).fetch(PROXY_AUTH_DIAGNOSTIC_URL, {
-                method: "GET",
-                timeout: PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS,
+            return await withClient(profileName, proxy, false, async (client) => {
+                await client.clearCookies();
+                const response = await client.fetch(PROXY_AUTH_DIAGNOSTIC_URL, {
+                    method: "GET",
+                    timeout: PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS,
+                });
+                const normalized = await normalizeResponse(response);
+                return classifyProxyAuthDiagnosticMessage(normalized.body);
             });
-            const normalized = await normalizeResponse(response);
-            return classifyProxyAuthDiagnosticMessage(normalized.body);
         }
         catch (error) {
             const message = error instanceof Error