@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.2

package/dist/runtime/stealth.js

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
 import { Impit } from "impit";
 import { DEFAULT_SMARTPROXY_POOL_SIZE, invalidateProxyResolutionCacheAsync, ProxyResolutionError, resolveProxyConfigAsync, SMARTPROXY_MAX_POOL_SIZE, } from "../config/loader";
-import { ProviderError, SDKError, TransportError } from "../errors";
+import { SDKError, TransportError } from "../errors";
 import { getStealthProfile } from "../stealth/profiles";
-import { HttpRetryPreset, HttpRetryUnsafeMethodPolicy } from "../types";
-import { createProxyAuthIpDeniedError, createProxyEdgeAuthRejectedError, createProxyEdgeTlsRejectedError, createProxyPoolExhaustedError, createProxyPoolStaleError, isProxyAuthIpDeniedMessage, isProxyEdgeAuthRejectedMessage, isProxyEdgeTlsRejectedResponse, isProxyPoolRefreshableError, isProxyPoolStaleMessage, isProxyPoolStaleStatus, PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_STALE_CODE, } from "./proxy-errors";
+import { createProxyAuthIpDeniedError, createProxyEdgeAuthRejectedError, createProxyEdgeTlsRejectedError, createProxyPoolExhaustedError, createProxyPoolStaleError, isProxyAuthIpDeniedMessage, isProxyEdgeAuthRejectedMessage, isProxyEdgeTlsRejectedResponse, isProxyPoolRefreshableError, isProxyPoolStaleMessage, isProxyPoolStaleStatus, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_STALE_CODE, } from "./proxy-errors";
+import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, normalizeProxyTransportRetryOptions, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy";
 import { appendQueryParams } from "./request-options";
 const DEFAULT_PROFILE = "chrome-146";
 const MISSING_PROXY_WARNING = "[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
@@ -14,31 +14,7 @@ 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 DEFAULT_STEALTH_RETRY_METHODS = ["GET", "HEAD", "OPTIONS"];
-const DEFAULT_STEALTH_RETRY_ERROR_CODES = [
-    PROXY_CONNECT_FAILURE_CODE,
-    "transport_network_error",
-    "transport_timeout",
-];
-const RATE_LIMIT_STEALTH_RETRY_ERROR_CODES = ["transport_timeout"];
-const KNOWN_STEALTH_RETRY_METHODS = new Set([
-    "GET",
-    "HEAD",
-    "POST",
-    "PUT",
-    "DELETE",
-    "OPTIONS",
-    "TRACE",
-    "PATCH",
-]);
-const UNSAFE_STEALTH_RETRY_METHODS = new Set([
-    "POST",
-    "PUT",
-    "PATCH",
-    "DELETE",
-    "TRACE",
-]);
-const MAX_STEALTH_RETRY_ATTEMPTS = 8;
+const STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES = [PROXY_CONNECT_FAILURE_CODE];
 const REMOVED_CHROME_PROFILE_NAMES = new Set([
     "chrome-120",
     "chrome-124",
@@ -102,11 +78,32 @@ class CookieJarImpl {
     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();
+    }
+    snapshot() {
+        return this.getAll();
+    }
+    restore(cookies) {
+        this.clear();
+        for (const [name, value] of Object.entries(cookies)) {
+            if (name)
+                this.cookies[name] = value;
+        }
+    }
+    clear() {
+        for (const name of Object.keys(this.cookies)) {
+            delete this.cookies[name];
+        }
+    }
     find(predicate) {
         for (const [name, value] of Object.entries(this.cookies)) {
             const cookie = `${name}=${value}`;
@@ -237,7 +234,7 @@ function splitCombinedSetCookieHeader(headerValue) {
         cookieStrings.push(finalCookie);
     return cookieStrings;
 }
-export async function normalizeResponse(response) {
+export async function normalizeResponse(response, requestUrl) {
     const headers = Object.fromEntries(response.headers.entries());
     const cookies = new CookieJarImpl(setCookieHeadersFromResponse(response.headers));
     const bodyBytes = await response.arrayBuffer();
@@ -245,6 +242,12 @@ export async function normalizeResponse(response) {
     return {
         status: response.status,
         ok: response.status >= 200 && response.status < 300,
+        ...(response.url ? { url: response.url } : {}),
+        ...(response.redirected !== undefined
+            ? { redirected: response.redirected }
+            : requestUrl && response.url
+                ? { redirected: response.url !== requestUrl }
+                : {}),
         headers,
         rawHeaders: headerEntriesFromHeaders(response.headers),
         body,
@@ -276,130 +279,8 @@ function isPolicyManagedProxy(options) {
     const policy = options.proxyPolicy ?? options.upstream?.proxy;
     return Boolean(policy && typeof policy === "object");
 }
-function isRetrySafeStealthMethod(method) {
-    return method === "GET" || method === "HEAD" || method === "OPTIONS";
-}
-function createStealthRetryOptions(preset) {
-    switch (preset) {
-        case HttpRetryPreset.Off:
-            return {
-                attempts: 1,
-                methods: DEFAULT_STEALTH_RETRY_METHODS,
-                errorCodes: DEFAULT_STEALTH_RETRY_ERROR_CODES,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.AggressiveRead:
-            return {
-                attempts: 4,
-                methods: DEFAULT_STEALTH_RETRY_METHODS,
-                errorCodes: DEFAULT_STEALTH_RETRY_ERROR_CODES,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.RateLimitAware:
-            return {
-                attempts: 3,
-                methods: DEFAULT_STEALTH_RETRY_METHODS,
-                errorCodes: RATE_LIMIT_STEALTH_RETRY_ERROR_CODES,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.SafeRead:
-        case HttpRetryPreset.TransportTransient:
-            return {
-                attempts: 3,
-                methods: DEFAULT_STEALTH_RETRY_METHODS,
-                errorCodes: DEFAULT_STEALTH_RETRY_ERROR_CODES,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-    }
-    throw new ProviderError(`Unknown stealth retry preset: ${preset}`, {
-        code: "retry_invalid_policy",
-    });
-}
-function normalizeStealthRetryOptions(retry) {
-    if (retry === undefined)
-        return undefined;
-    if (retry === false)
-        return createStealthRetryOptions(HttpRetryPreset.Off);
-    if (retry === true)
-        return createStealthRetryOptions(HttpRetryPreset.TransportTransient);
-    if (typeof retry === "string") {
-        if (!Object.values(HttpRetryPreset).includes(retry)) {
-            throw new ProviderError(`Unknown stealth retry preset: ${retry}`, {
-                code: "retry_invalid_policy",
-            });
-        }
-        return createStealthRetryOptions(retry);
-    }
-    if (typeof retry !== "object" || retry === null || Array.isArray(retry)) {
-        throw new ProviderError("Stealth retry policy must be a plain object", {
-            code: "retry_invalid_policy",
-        });
-    }
-    if (retry.unsafeMethodPolicy !== undefined &&
-        !Object.values(HttpRetryUnsafeMethodPolicy).includes(retry.unsafeMethodPolicy)) {
-        throw new ProviderError(`Unknown stealth retry unsafe method policy: ${String(retry.unsafeMethodPolicy)}`, { code: "retry_invalid_policy" });
-    }
-    if (retry.methods !== undefined) {
-        if (!Array.isArray(retry.methods)) {
-            throw new ProviderError("Stealth retry methods must be an array", {
-                code: "retry_invalid_policy",
-            });
-        }
-        const unknownMethods = retry.methods
-            .map((method) => (typeof method === "string" ? method.toUpperCase() : ""))
-            .filter((method) => !KNOWN_STEALTH_RETRY_METHODS.has(method));
-        if (unknownMethods.length > 0) {
-            throw new ProviderError(`Unknown stealth retry method(s): ${unknownMethods.join(", ")}`, { code: "retry_invalid_policy" });
-        }
-    }
-    if (retry.errorCodes !== undefined) {
-        if (!Array.isArray(retry.errorCodes) ||
-            retry.errorCodes.some((errorCode) => typeof errorCode !== "string")) {
-            throw new ProviderError("Stealth retry errorCodes must contain only strings", { code: "retry_invalid_policy" });
-        }
-    }
-    const base = createStealthRetryOptions(retry.preset ?? HttpRetryPreset.TransportTransient);
-    const attempts = retry.attempts === undefined || !Number.isFinite(retry.attempts)
-        ? base.attempts
-        : Math.max(1, Math.min(MAX_STEALTH_RETRY_ATTEMPTS, Math.floor(retry.attempts)));
-    const normalized = {
-        attempts,
-        methods: retry.methods?.map((method) => method.toUpperCase()) ?? base.methods,
-        errorCodes: retry.errorCodes ?? base.errorCodes,
-        unsafeMethodPolicy: retry.unsafeMethodPolicy ?? base.unsafeMethodPolicy,
-    };
-    if (normalized.unsafeMethodPolicy !==
-        HttpRetryUnsafeMethodPolicy.AllowExplicitUnsafe) {
-        const unsafeMethods = normalized.methods.filter((method) => UNSAFE_STEALTH_RETRY_METHODS.has(method.toUpperCase()));
-        if (unsafeMethods.length > 0) {
-            throw new ProviderError(`Stealth retry methods include unsafe method(s): ${unsafeMethods.join(", ")}`, { code: "retry_unsafe_method" });
-        }
-    }
-    return normalized;
-}
-function isExplicitStealthRetryAllowed(method, error, retryOptions) {
-    if (!retryOptions || retryOptions.attempts <= 1)
-        return false;
-    return (retryOptions.methods.includes(method.toUpperCase()) &&
-        retryOptions.errorCodes.includes(proxyAttemptErrorCode(error)));
-}
-function isRetryableProxyTransportError(error) {
-    if (error instanceof TransportError) {
-        if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
-            return false;
-        }
-        return (error.code === PROXY_CONNECT_FAILURE_CODE ||
-            error.code === "transport_network_error" ||
-            error.code === "transport_timeout");
-    }
-    if (error instanceof SDKError) {
-        return false;
-    }
-    const message = error instanceof Error ? error.message : String(error);
-    return /\bproxy\b|\bnon[\s-]?200\b|\bconnect\b|\btunnel\b/i.test(message);
-}
 function isProxyConnectFailureResponse(response, body) {
-    return (response.status === 0 && PROXY_CONNECT_FAILURE_BODY_PATTERN.test(body ?? ""));
+    return response.status === 0 && PROXY_CONNECT_FAILURE_BODY_PATTERN.test(body ?? "");
 }
 function createProxyConnectFailureError(body, cause) {
     const bodyExcerpt = (body ?? "").trim().slice(0, 1_000);
@@ -502,8 +383,7 @@ function normalizeStealthTransportError(error) {
         return createProxyEdgeAuthRejectedError(error instanceof Error ? error : undefined);
     }
     const proxyTunnelStatus = getProxyTunnelStatus(error);
-    if (proxyTunnelStatus !== undefined &&
-        isProxyPoolStaleStatus(proxyTunnelStatus)) {
+    if (proxyTunnelStatus !== undefined && isProxyPoolStaleStatus(proxyTunnelStatus)) {
         return createProxyPoolStaleError(proxyTunnelStatus, error instanceof Error ? error : undefined);
     }
     if (PROXY_CONNECT_FAILURE_BODY_PATTERN.test(message)) {
@@ -515,6 +395,9 @@ function normalizeStealthTransportError(error) {
         cause: error instanceof Error ? error : undefined,
     });
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function normalizeMethod(method) {
     switch (method.toUpperCase()) {
         case "HEAD":
@@ -537,6 +420,23 @@ 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")
+            return value;
+    }
+    return undefined;
+}
 function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
     const clients = new Map();
     let closed = false;
@@ -564,18 +464,16 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
         return client;
     }
     async function resolveRequestProxy(options, proxyAttempt) {
-        const rawProxyAttemptOffset = options?.proxyAttemptOffset ?? 0;
-        const proxyAttemptOffset = Number.isFinite(rawProxyAttemptOffset)
-            ? Math.max(0, Math.floor(rawProxyAttemptOffset))
-            : 0;
         const resolvedProxy = await resolveProxyConfigAsync({
             proxy: options?.proxy ?? clientOptions.proxy,
             upstream: clientOptions.upstream,
             apifuseConfig: clientOptions.apifuseConfig,
             affinityKey: clientOptions.affinityKey,
-            proxyAttempt: proxyAttempt === undefined
-                ? proxyAttemptOffset
-                : proxyAttemptOffset + proxyAttempt,
+            proxyAttempt: computeProxyAttemptIndex({
+                baseProxyAttempt: clientOptions.proxyAttempt,
+                proxyAttemptOffset: options?.proxyAttemptOffset,
+                retryAttemptOffset: proxyAttempt,
+            }),
             telemetry: clientOptions.telemetry,
         });
         if (resolvedProxy.shouldWarn && !hasWarnedMissingProxy) {
@@ -588,20 +486,32 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
             proxyHash: proxyEndpointHash(resolvedProxy.url),
         };
     }
-    return {
+    const session = {
         async fetch(url, options = {}) {
             const method = normalizeMethod(options.method ?? "GET");
             const hasExplicitRetryPolicy = options.retry !== undefined;
-            const stealthRetryOptions = normalizeStealthRetryOptions(options.retry);
+            const stealthRetryOptions = normalizeProxyTransportRetryOptions(options.retry, {
+                extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
+                label: "Stealth",
+            }) ??
+                (hasExplicitRetryPolicy
+                    ? undefined
+                    : createDefaultProxyTransportRetryOptions({
+                        extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
+                        label: "Stealth",
+                    }));
+            if (stealthRetryOptions) {
+                validateUnsafeProxyTransportRetryMethods(stealthRetryOptions, "Stealth");
+            }
             const hasPolicyProxy = isPolicyManagedProxy(clientOptions);
             const usesPolicyAllocator = hasPolicyProxy && !options.proxy && !clientOptions.proxy;
-            const maxAttempts = usesPolicyAllocator
-                ? Math.max(1, Math.min(MAX_POLICY_PROXY_RETRY_ATTEMPTS, clientOptions.proxyPolicy?.session?.poolSize ??
-                    (typeof clientOptions.upstream?.proxy === "object"
-                        ? clientOptions.upstream.proxy.session?.poolSize
-                        : undefined) ??
-                    DEFAULT_SMARTPROXY_POOL_SIZE))
-                : 1;
+            const retryAttemptCap = Math.max(1, stealthRetryOptions?.attempts ?? 1);
+            const policyProxyAttemptCap = Math.max(1, Math.min(MAX_POLICY_PROXY_RETRY_ATTEMPTS, clientOptions.proxyPolicy?.session?.poolSize ??
+                (typeof clientOptions.upstream?.proxy === "object"
+                    ? clientOptions.upstream.proxy.session?.poolSize
+                    : undefined) ??
+                DEFAULT_SMARTPROXY_POOL_SIZE));
+            const maxAttempts = usesPolicyAllocator ? policyProxyAttemptCap : retryAttemptCap;
             let lastError;
             for (let refreshAttempt = 0; refreshAttempt <= MAX_POLICY_PROXY_POOL_REFRESHES; refreshAttempt += 1) {
                 let stalePoolError;
@@ -622,9 +532,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             ...(attemptProxy?.poolIndex === undefined
                                 ? {}
                                 : { poolIndex: attemptProxy.poolIndex }),
-                            ...(attemptProxy?.proxyHash
-                                ? { proxyHash: attemptProxy.proxyHash }
-                                : {}),
+                            ...(attemptProxy?.proxyHash ? { proxyHash: attemptProxy.proxyHash } : {}),
                             outcome,
                             ...(errorCode ? { errorCode } : {}),
                             ...(status === undefined ? {} : { status }),
@@ -635,16 +543,14 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         assertNoUnsupportedFingerprintOverrides(options);
                         attemptProxy = await resolveRequestProxy(options, attempt);
                         proxy = attemptProxy.url;
-                        if (proxy) {
+                        if (proxy && usesPolicyAllocator) {
                             if (attemptedProxies.has(proxy)) {
                                 break;
                             }
                             attemptedProxies.add(proxy);
                         }
                         const ignoreTlsErrors = Boolean(options.stealth?.insecureSkipVerify ??
-                            (!hasPolicyProxy &&
-                                proxy &&
-                                clientOptions.proxyStealth?.insecureSkipVerify));
+                            (!hasPolicyProxy && proxy && clientOptions.proxyStealth?.insecureSkipVerify));
                         const profileName = options.profile ?? defaultProfile;
                         const requestUrl = appendQueryParams(resolveUrl(baseUrl, url), options.params);
                         const headers = { ...(options.headers ?? {}) };
@@ -656,25 +562,22 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         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);
+                        const normalized = await normalizeResponse(response, requestUrl);
                         cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers));
-                        if (proxy &&
-                            isProxyConnectFailureResponse(response, normalized.body)) {
+                        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"))) {
+                                isProxyEdgeTlsRejectedResponse(response.status, [JSON.stringify(responseHeadersToRecord(response.headers)), normalized.body].join("\n"))) {
                                 throw createProxyEdgeTlsRejectedError(response.status);
                             }
                             if (proxy && isProxyAuthIpDeniedMessage(normalized.body)) {
@@ -702,9 +605,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const normalizedError = normalizeStealthTransportError(error);
                         recordProxyAttempt("error", proxyAttemptErrorCode(normalizedError), proxyAttemptStatus(normalizedError));
                         lastError = normalizedError;
-                        if (proxy &&
-                            usesPolicyAllocator &&
-                            isProxyPoolRefreshableError(normalizedError)) {
+                        if (proxy && usesPolicyAllocator && isProxyPoolRefreshableError(normalizedError)) {
                             stalePoolError = normalizedError;
                             if (shouldRunProxyAuthDiagnostic(normalizedError)) {
                                 stalePoolDiagnosticProxy = proxy;
@@ -714,15 +615,20 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             }
                             break;
                         }
-                        if (proxy &&
-                            attempt + 1 <
-                                (stealthRetryOptions
-                                    ? Math.min(maxAttempts, stealthRetryOptions.attempts)
-                                    : maxAttempts) &&
-                            (!hasExplicitRetryPolicy
-                                ? isRetrySafeStealthMethod(method)
-                                : isExplicitStealthRetryAllowed(method, normalizedError, stealthRetryOptions)) &&
-                            isRetryableProxyTransportError(normalizedError)) {
+                        if (attempt + 1 <
+                            (stealthRetryOptions
+                                ? Math.min(maxAttempts, stealthRetryOptions.attempts)
+                                : maxAttempts) &&
+                            shouldRetryProxyTransportAttempt({
+                                error: normalizedError,
+                                explicitRetry: hasExplicitRetryPolicy,
+                                method,
+                                options: stealthRetryOptions,
+                                proxyUsed: Boolean(proxy),
+                            })) {
+                            if (stealthRetryOptions) {
+                                await sleep(computeProxyTransportRetryDelayMs(stealthRetryOptions, attempt + 1));
+                            }
                             continue;
                         }
                         throw normalizedError;
@@ -758,11 +664,112 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
             }
             throw normalizeStealthTransportError(lastError);
         },
+        cookies: cookieJar,
+        redirects: {
+            async run(options) {
+                const maxHops = options.maxHops === undefined || !Number.isFinite(options.maxHops)
+                    ? 10
+                    : Math.max(0, Math.floor(options.maxHops));
+                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;
+                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,
+                    });
+                    if (!isRedirectStatus(response.status)) {
+                        return {
+                            final: response,
+                            hops,
+                            reason: "completed",
+                            cookies: cookieJar.snapshot(),
+                        };
+                    }
+                    const location = locationHeader(response.headers);
+                    const nextUrl = location
+                        ? new URL(location, response.url ?? currentUrl).toString()
+                        : undefined;
+                    const hop = {
+                        url: response.url ?? currentUrl,
+                        status: response.status,
+                        method,
+                        ...(location ? { location } : {}),
+                        ...(nextUrl ? { 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(),
+                        };
+                    }
+                    if (hops.length > maxHops) {
+                        return {
+                            final: response,
+                            hops,
+                            reason: "max_hops",
+                            cookies: cookieJar.snapshot(),
+                        };
+                    }
+                    const nextMethod = nextRedirectMethod(response.status, method);
+                    if (nextMethod !== method) {
+                        body = undefined;
+                    }
+                    if (visitedRequests.has(`${nextMethod} ${nextUrl}`)) {
+                        return {
+                            final: response,
+                            hops,
+                            reason: "loop",
+                            cookies: cookieJar.snapshot(),
+                        };
+                    }
+                    method = nextMethod;
+                    currentUrl = nextUrl;
+                }
+                if (!response) {
+                    response = await session.fetch(currentUrl, {
+                        ...fetchOptions,
+                        body,
+                        method,
+                        ...(params ? { params } : {}),
+                        redirect: "manual",
+                        throwOnHttpError: false,
+                    });
+                }
+                return {
+                    final: response,
+                    hops,
+                    reason: "max_hops",
+                    cookies: cookieJar.snapshot(),
+                };
+            },
+        },
         close() {
             closed = true;
             clients.clear();
         },
     };
+    return session;
     async function classifyProxyAuthDiagnostic(profileName, proxy) {
         try {
             const response = await getClient(profileName, proxy, false).fetch(PROXY_AUTH_DIAGNOSTIC_URL, {
@@ -774,10 +781,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
         }
         catch (error) {
             const message = error instanceof Error
-                ? [
-                    error.message,
-                    error.cause instanceof Error ? error.cause.message : "",
-                ]
+                ? [error.message, error.cause instanceof Error ? error.cause.message : ""]
                     .filter(Boolean)
                     .join(" ")
                 : String(error);
@@ -805,12 +809,8 @@ function hasHeader(headers, name) {
     return Object.keys(headers).some((key) => key.toLowerCase() === needle);
 }
 export function createStealthClient(baseUrl, defaultProfileOrOptions = DEFAULT_PROFILE, clientOptions = {}) {
-    const defaultProfile = typeof defaultProfileOrOptions === "string"
-        ? defaultProfileOrOptions
-        : DEFAULT_PROFILE;
-    const resolvedClientOptions = typeof defaultProfileOrOptions === "string"
-        ? clientOptions
-        : defaultProfileOrOptions;
+    const defaultProfile = typeof defaultProfileOrOptions === "string" ? defaultProfileOrOptions : DEFAULT_PROFILE;
+    const resolvedClientOptions = typeof defaultProfileOrOptions === "string" ? clientOptions : defaultProfileOrOptions;
     let sharedSession = null;
     function getSharedSession() {
         if (!sharedSession) {

package/dist/server/index.d.ts

@@ -1,3 +1,7 @@
 export { createServerApp, type ServeOptions, serve } from "./serve";
+export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test";
+export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens";
+export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction";
+export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, type SelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token";
 export type { AuthFlowRequest, AuthFlowResponse, AuthFlowSuccessResponse, ConnectionMode, OperationConnection, OperationErrorResponse, OperationRequest, OperationResponse, OperationSuccessResponse, } from "./types";
 export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types";

package/dist/server/index.js

@@ -1,2 +1,6 @@
 export { createServerApp, serve } from "./serve";
+export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, SelfTestRequestSchema, } from "./self-test";
+export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens";
+export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction";
+export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token";
 export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types";

package/dist/server/self-test-input-tokens.d.ts

@@ -0,0 +1 @@
+export declare function resolveHealthCheckInputDateTokens(value: unknown, now?: Date): unknown;

package/dist/server/self-test-input-tokens.js

@@ -0,0 +1,37 @@
+/**
+ * Relative-KST date token resolution for health-check case inputs, ported from
+ * the monorepo health-monitor (`apps/health-monitor/src/lib/health-check-input.ts`)
+ * so provider self-tests resolve durable probe inputs identically.
+ *
+ * Supported token: `+<days>d` or `+<days>d:YYYYMMDD` (1..365 days ahead, KST).
+ */
+const RELATIVE_KST_DATE_TOKEN = /^\+(\d{1,3})d(?::(YYYYMMDD))?$/i;
+function dateFromKstDaysAhead(daysAhead, now = new Date(), format = "YYYY-MM-DD") {
+    const kstNow = new Date(now.getTime() + 9 * 60 * 60 * 1000);
+    const date = new Date(Date.UTC(kstNow.getUTCFullYear(), kstNow.getUTCMonth(), kstNow.getUTCDate() + daysAhead));
+    const isoDate = date.toISOString().slice(0, 10);
+    return format === "YYYYMMDD" ? isoDate.replace(/-/g, "") : isoDate;
+}
+export function resolveHealthCheckInputDateTokens(value, now = new Date()) {
+    if (typeof value === "string") {
+        const relative = value.match(RELATIVE_KST_DATE_TOKEN);
+        if (!relative)
+            return value;
+        const daysAhead = Number(relative[1]);
+        if (!Number.isInteger(daysAhead) || daysAhead < 1 || daysAhead > 365) {
+            return value;
+        }
+        const format = relative[2]?.toUpperCase() === "YYYYMMDD" ? "YYYYMMDD" : "YYYY-MM-DD";
+        return dateFromKstDaysAhead(daysAhead, now, format);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => resolveHealthCheckInputDateTokens(entry, now));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key,
+            resolveHealthCheckInputDateTokens(entry, now),
+        ]));
+    }
+    return value;
+}

package/dist/server/self-test-redaction.d.ts

@@ -0,0 +1,20 @@
+import type { ProviderDefinition } from "../types";
+export declare const SELF_TEST_REDACTED_PLACEHOLDER = "[REDACTED]";
+/** Maximum length of any string echoed in a self-test response. */
+export declare const SELF_TEST_MAX_TEXT_LENGTH = 300;
+/**
+ * Collects every secret-shaped value known to the self-test runtime so probe
+ * results can be scrubbed before they leave the pod: master secrets, declared
+ * provider env secrets, health-probe credential env values, and request-supplied
+ * credential inputs.
+ */
+export declare function collectSelfTestSensitiveValues(provider: ProviderDefinition, options?: {
+    env?: Readonly<Record<string, string | undefined>>;
+    credentialInputs?: Readonly<Record<string, string>>;
+}): string[];
+/**
+ * Scrubs known secret values and header-shaped credentials from a string and
+ * caps its length. Every string embedded in a SelfTestResponse MUST pass
+ * through this before serialization.
+ */
+export declare function redactSelfTestText(text: string, sensitiveValues: readonly string[], maxLength?: number): string;