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

package/dist/runtime/stealth.js

@@ -1,12 +1,15 @@
 import { createHash } from "node:crypto";
+import { Cookie } from "tough-cookie";
 import { DEFAULT_SMARTPROXY_POOL_SIZE, invalidateProxyResolutionCacheAsync, ProxyResolutionError, policyResolvesRegistryVendorChain, resolvePolicyProxyPoolSpan, resolvePolicyTransportAttemptCap, resolveProxyConfigAsync, vendorFromResolvedSource, } from "../config/loader.js";
 import { SDKError, TransportError } from "../errors.js";
-import { DEFAULT_STEALTH_BROWSER, DEFAULT_STEALTH_OS, getStealthProfile, resolveStealthProfileSelection, } from "../stealth/profiles.js";
+import { DEFAULT_STEALTH_BROWSER, DEFAULT_STEALTH_OS, getStealthProfile, resolverClientProfileFamily, resolveStealthProfileSelection, } from "../stealth/profiles.js";
 import { chrome149HeaderOrder } from "./chrome149-header-order.js";
+import { ENGINE_CEREMONY_EGRESS_LEASE, } from "./egress-lease.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 { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, isProxyTransportRetryMethod, normalizeProxyTransportRetryOptions, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy.js";
 import { evaluateRedirectHop, isRedirectStatus, nextRedirectMethod, resolveRedirectUrl, } from "./redirects.js";
 import { isSensitiveKey, normalizeSensitiveParams, redactSensitiveError, redactSensitiveRequestError, redactSensitiveText, redactUrlQueryParams, serializeRequestUrl, } from "./request-options.js";
+import { akamaiSbsdChallengeKey, detectAkamaiSbsdChallenge, } from "./stealth-akamai-sbsd.js";
 import { StealthCookieJar } from "./stealth-cookies.js";
 export const DEFAULT_STEALTH_PROFILE = Object.freeze({
     browser: DEFAULT_STEALTH_BROWSER,
@@ -19,6 +22,18 @@ const PROXY_CONNECT_FAILURE_BODY_PATTERN = /\bproxy\b.*\b(non[\s-]?200|connect|t
 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];
+// 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 = new Set([
+    PROXY_CONNECT_FAILURE_CODE,
+    "transport_network_error",
+    "transport_timeout",
+]);
+function isBoundEgressTransportFailure(error) {
+    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",
@@ -37,6 +52,14 @@ function sensitiveQueryParamNames(url) {
     const query = url.slice(queryStart + 1, fragmentStart === -1 ? undefined : fragmentStart);
     return [...new URLSearchParams(query).keys()].filter(isSensitiveKey);
 }
+function assertAkamaiSbsdClientProfile(declared, session) {
+    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).",
+    });
+}
 let wreqModulePromise;
 function getWreqModule() {
     if (!wreqModulePromise) {
@@ -98,6 +121,25 @@ export function resolveWreqProfile(selection, wreqProfiles) {
 function resolveUrl(baseUrl, url) {
     return new URL(url, baseUrl).toString();
 }
+function resolveRequestUrl(baseUrl, url) {
+    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) {
     return Array.from(headers.entries());
 }
@@ -365,7 +407,8 @@ 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);
@@ -430,6 +473,29 @@ function setCookieHeadersFromResponse(headers) {
     const setCookie = headers.get("set-cookie");
     return setCookie ? splitCombinedSetCookieHeader(setCookie) : [];
 }
+function resolverCookiesFromResponse(response, requestUrl) {
+    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) {
     const cookieNamePattern = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+=/;
     const cookieStrings = [];
@@ -605,15 +671,20 @@ function readResponseBodyChunk(reader, signal) {
 }
 function normalizeBody(body) {
     if (body === undefined) {
-        return "";
+        return undefined;
     }
     if (typeof body === "string") {
         return body;
     }
     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) {
     const policy = options.proxyPolicy ?? options.upstream?.proxy;
@@ -655,6 +726,10 @@ function proxyPoolIndexFromDiagnostics(diagnostics) {
     }
     return Math.floor(value);
 }
+function positiveDiagnosticNumber(diagnostics, name) {
+    const value = diagnostics?.[name];
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
 function proxyEndpointHash(proxyUrl) {
     if (!proxyUrl)
         return undefined;
@@ -902,6 +977,65 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
     let hasWarnedMissingProxy = false;
     const warn = clientOptions.warn ?? console.warn;
     const cookieJar = new StealthCookieJar([], baseUrl);
+    const akamaiSbsdState = { transactions: new Map() };
+    const challengedReplays = new WeakMap();
+    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() {
+        akamaiSbsdState.rememberedScript = undefined;
+        akamaiSbsdState.transactions.clear();
+        akamaiSbsdState.completedSuccessKey = undefined;
+    }
+    function currentEgressGeneration() {
+        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() {
+        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() {
+        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, error) {
+        const bound = ceremonyEgressLease?.binding;
+        if (!ceremonyEgressLease ||
+            !bound ||
+            !attemptProxyUrl ||
+            attemptProxyUrl !== bound.proxyUrl ||
+            !isBoundEgressTransportFailure(error)) {
+            return false;
+        }
+        ceremonyEgressLease.dropBinding();
+        syncCeremonyEgress();
+        return true;
+    }
     async function getClientEntry(profile, proxyUrl, ignoreTlsErrors, defaultHeaders) {
         if (closed) {
             throw new TransportError("Stealth session is closed", { status: 0 });
@@ -984,6 +1118,23 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
         });
     }
     async function resolveRequestProxy(options, proxyAttempt, refreshEpoch) {
+        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,
@@ -998,6 +1149,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
             transportProtocols: ["http", "socks5"],
             ...(refreshEpoch === undefined ? {} : { proxyRefreshEpoch: refreshEpoch }),
             telemetry: clientOptions.telemetry,
+            engineCredentials: clientOptions.engineCredentials,
         });
         if (resolvedProxy.shouldWarn && !hasWarnedMissingProxy) {
             hasWarnedMissingProxy = true;
@@ -1008,11 +1160,72 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
             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) {
+        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 = {
+            vendor: attemptProxy.vendor,
+            proxyUrl: attemptProxy.url,
+            poolIndex: attemptProxy.poolIndex,
+            affinityKey: clientOptions.affinityKey,
+            refreshEpoch: attemptProxy.refreshEpoch ?? 0,
+            lifetimeMinutes: attemptProxy.lifetimeMinutes,
         };
+        lease.bind(binding);
     }
     const session = {
-        async fetch(url, options = {}) {
+        async fetch(url, callerOptions = {}) {
+            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 = {
+                ...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;
             const { hasExplicitRetryPolicy, method, stealthRetryOptions } = (() => {
                 try {
                     const method = normalizeMethod(options.method ?? "GET");
@@ -1059,7 +1272,10 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
             // 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 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;
             for (let refreshAttempt = 0; refreshAttempt <= MAX_POLICY_PROXY_POOL_REFRESHES; refreshAttempt += 1) {
@@ -1075,8 +1291,9 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                     let fallbackSensitiveValues = [];
                     let fallbackRequestUrl;
                     let fallbackRedactedUrl;
-                    const attemptStartedAt = Date.now();
+                    let attemptStartedAt = Date.now();
                     let attemptRecorded = false;
+                    const attemptEgressGeneration = currentEgressGeneration();
                     const recordProxyAttempt = (outcome, errorCode, status) => {
                         if (attemptRecorded || !proxy)
                             return;
@@ -1094,6 +1311,45 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             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, attemptNormalized) => {
+                        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 = (error) => 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) => {
+                        let normalizedError;
+                        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) => {
+                        const redactedError = redactAttemptError(normalizedError);
+                        recordProxyAttempt("error", proxyAttemptErrorCode(redactedError), proxyAttemptStatus(redactedError));
+                        return redactedError;
+                    };
                     try {
                         throwIfAmbientAborted(clientOptions.signal);
                         const sensitiveParams = normalizeSensitiveParams(options.sensitiveParams);
@@ -1123,12 +1379,13 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         }
                         const ignoreTlsErrors = Boolean(options.stealth?.insecureSkipVerify ??
                             (!hasPolicyProxy && proxy && clientOptions.proxyStealth?.insecureSkipVerify));
-                        serializedUrl = serializeRequestUrl(resolveUrl(baseUrl, url), options.params, sensitiveParams);
+                        serializedUrl = serializeRequestUrl(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)]);
                         const chromeEmulationHeaders = mapping.browser.startsWith("chrome_")
-                            ? Array.from(wreq.getEmulationHeaders(mapping.browser, mapping.os), ([name, value]) => [String(name), String(value)])
+                            ? emulationHeaders
                             : undefined;
                         const buildOrderedHeaders = chromeEmulationHeaders
                             ? (currentUrl, currentMethod, currentBody, currentHeaders) => buildChromeHeaderTuples({
@@ -1139,6 +1396,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                                 requestUrl: currentUrl,
                                 acceptLanguage: clientOptions.stealth?.acceptLanguage,
                                 requestClass: options.stealth?.requestClass,
+                                userActivation: options.stealth?.userActivation,
                             })
                             : undefined;
                         const initialHeaders = normalizeHeaders({ ...(options.headers ?? {}) });
@@ -1147,61 +1405,261 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             if (cookieHeader)
                                 initialHeaders.cookie = cookieHeader;
                         }
-                        const defaultHeaders = buildOrderedHeaders?.(requestUrl, method, options.body === undefined ? undefined : normalizeBody(options.body), 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) {
-                            if (proxy &&
-                                usesPolicyAllocator &&
-                                isProxyEdgeTlsRejectedResponse(response.status, [JSON.stringify(responseHeadersToRecord(response.headers)), normalized.body].join("\n"))) {
-                                throw createProxyEdgeTlsRejectedError(response.status);
+                        const defaultHeaders = buildOrderedHeaders?.(requestUrl, method, requestBody, initialHeaders);
+                        const fetchOnBoundSession = (fetchUrl, fetchMethod, fetchOptions, fetchSignal, orderedHeaders = buildOrderedHeaders, sessionDefaultHeaders = defaultHeaders) => withClient(requestProfile, proxy, ignoreTlsErrors, (transport) => fetchStealthRedirectChain(transport, cookieJar, fetchUrl, fetchMethod, fetchOptions, fetchSignal, orderedHeaders), fetchSignal, sessionDefaultHeaders);
+                        const throwProxyTransportFault = (faultResponse, faultBody) => {
+                            if (!proxy)
+                                return;
+                            if (isProxyConnectFailureResponse(faultResponse, faultBody)) {
+                                throw createProxyConnectFailureError(faultBody);
+                            }
+                            if (faultResponse.status < 400)
+                                return;
+                            if (usesPolicyAllocator &&
+                                isProxyEdgeTlsRejectedResponse(faultResponse.status, [JSON.stringify(responseHeadersToRecord(faultResponse.headers)), faultBody].join("\n"))) {
+                                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)) {
-                                throw createProxyPoolStaleError(response.status);
+                            if (isProxyPoolStaleStatus(faultResponse.status) &&
+                                isProxyPoolStaleMessage(faultBody)) {
+                                throw createProxyPoolStaleError(faultResponse.status);
                             }
-                        }
-                        if (response.status >= 400 && options.throwOnHttpError !== false) {
-                            throw new TransportError(`Upstream request failed with status ${response.status}`, {
-                                code: "upstream_http_error",
-                                status: response.status,
+                        };
+                        let { normalized, response } = await fetchOnBoundSession(requestUrl, method, options, clientOptions.signal);
+                        throwProxyTransportFault(response, normalized.body);
+                        // 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);
+                        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 (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]));
+                            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, currentMethod, currentBody, currentHeaders) => buildChromeHeaderTuples({
+                                    emulationHeaders: chromeEmulationHeaders,
+                                    method: currentMethod,
+                                    body: currentBody,
+                                    headers: currentHeaders,
+                                    requestUrl: currentUrl,
+                                    acceptLanguage: clientOptions.stealth?.acceptLanguage,
+                                })
+                                : undefined;
+                            const resolverTransport = {
+                                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 = {
+                                ...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) => {
+                                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 }), (error) => ({ solved: false, error }))
+                                                .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);
+                                        }
+                                    },
+                                });
+                                return finalizeAttempt(response, normalized);
+                            }
+                            ({ normalized, response } = await solveAndReplay(false));
                         }
-                        recordProxyAttempt("ok", undefined, response.status);
-                        return normalized;
+                        return finalizeAttempt(response, normalized);
                     }
                     catch (error) {
-                        const sensitiveValues = serializedUrl?.sensitiveValues ?? fallbackSensitiveValues;
-                        let normalizedError;
-                        try {
-                            throwIfAmbientAborted(clientOptions.signal);
-                            normalizedError = normalizeStealthTransportError(error);
-                        }
-                        catch (normalizationError) {
-                            const redactedNormalizationError = redactSensitiveError(normalizationError, sensitiveValues, serializedUrl?.requestUrl ?? fallbackRequestUrl, serializedUrl?.redactedUrl ?? fallbackRedactedUrl);
-                            if (normalizationError instanceof TransportError &&
-                                normalizationError.code === "transport_cancelled") {
-                                recordProxyAttempt("error", proxyAttemptErrorCode(normalizationError), proxyAttemptStatus(normalizationError));
-                            }
-                            throw redactedNormalizationError;
-                        }
+                        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;
                             }
@@ -1210,6 +1668,15 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             }
                             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
@@ -1244,7 +1711,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             throwIfAmbientAborted(clientOptions.signal);
                             continue;
                         }
-                        throw normalizedError;
+                        throw redactedError;
                     }
                 }
                 if (rotatesRegistryChain &&
@@ -1280,6 +1747,32 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
             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) {
@@ -1455,6 +1948,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
         },
         close() {
             closed = true;
+            clearAkamaiSbsdState();
             for (const client of clients.values()) {
                 void client.session
                     .then((session) => session.close())