@apifuse/provider-sdk 2.2.0-beta.28 → 2.2.0-beta.29

package/dist/runtime/resolver-vendors/twocaptcha.js

@@ -1,5 +1,5 @@
 import { assertResolverHostAllowed } from "./hosts.js";
-import { ResolverVendorUnavailableError, resolverVendorSupports, } from "./types.js";
+import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, resolverVendorSupports, } from "./types.js";
 const TWOCAPTCHA_VENDOR_ID = "2captcha";
 const DEFAULT_TWOCAPTCHA_BASE_URL = "https://api.2captcha.com";
 const DEFAULT_POLL_INTERVAL_MS = 3_000;
@@ -16,7 +16,46 @@ function isJsonRecord(value) {
 function abortReason(signal) {
     return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
 }
-function raceWithAbort(operation, signal, phase) {
+function containsSensitiveValue(value, sensitiveValues) {
+    const secrets = sensitiveValues.filter((secret) => secret.length > 0);
+    if (secrets.length === 0)
+        return false;
+    const seen = new Set();
+    const inspect = (candidate) => {
+        if (typeof candidate === "string") {
+            return secrets.some((secret) => candidate.includes(secret));
+        }
+        if (candidate === null ||
+            (typeof candidate !== "object" && typeof candidate !== "function")) {
+            return false;
+        }
+        if (seen.has(candidate))
+            return false;
+        seen.add(candidate);
+        try {
+            for (const property of Reflect.ownKeys(candidate)) {
+                if (typeof property === "string" && inspect(property))
+                    return true;
+                const descriptor = Object.getOwnPropertyDescriptor(candidate, property);
+                if (!descriptor)
+                    return true;
+                if ("value" in descriptor && inspect(descriptor.value))
+                    return true;
+                if (descriptor.get !== undefined || descriptor.set !== undefined)
+                    return true;
+            }
+        }
+        catch {
+            return true;
+        }
+        return false;
+    };
+    return inspect(value);
+}
+function safeCauseOptions(error, sensitiveValues) {
+    return containsSensitiveValue(error, sensitiveValues) ? {} : { cause: error };
+}
+function raceWithAbort(operation, signal, phase, sensitiveValues = []) {
     if (signal.aborted)
         return Promise.reject(abortReason(signal));
     return new Promise((resolve, reject) => {
@@ -36,7 +75,7 @@ function raceWithAbort(operation, signal, phase) {
                 return;
             }
             reject(new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
-                cause: error,
+                ...safeCauseOptions(error, sensitiveValues),
                 phase,
             }));
         });
@@ -92,17 +131,23 @@ function isAllocationExhausted(payload) {
     return (code === "error_zero_balance" ||
         /(?:insufficient|zero|no|not enough)\s+(?:balance|funds|credit)/u.test(`${code} ${description}`));
 }
+function isNegativeVerdict(payload) {
+    return errorText(payload, "errorCode").toLowerCase() === "error_captcha_unsolvable";
+}
 function unavailableForPayload(payload, phase) {
+    if (isNegativeVerdict(payload)) {
+        return new ResolverChallengeVerdictError(TWOCAPTCHA_VENDOR_ID, "solve_failed");
+    }
     return new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, isAllocationExhausted(payload) ? "allocation_exhausted" : "transport_failure", { phase });
 }
-async function postJson(fetchImpl, url, body, signal, phase) {
+async function postJson(fetchImpl, url, body, signal, phase, sensitiveValues) {
     const response = await raceWithAbort(() => fetchImpl(url, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify(body),
         signal,
         redirect: "error",
-    }), signal, phase);
+    }), signal, phase, sensitiveValues);
     let responseText;
     try {
         responseText = await raceWithAbort(() => response.text(), signal, phase);
@@ -136,10 +181,13 @@ function taskIdFrom(payload) {
     const taskId = payload.taskId;
     return typeof taskId === "string" || typeof taskId === "number" ? taskId : undefined;
 }
-function tokenFrom(payload) {
+function tokenFrom(payload, challenge) {
     const solution = payload.solution;
     if (!isJsonRecord(solution))
         return undefined;
+    if (challenge.kind === "aws_waf") {
+        return typeof solution.existing_token === "string" ? solution.existing_token : undefined;
+    }
     if (typeof solution.gRecaptchaResponse === "string")
         return solution.gRecaptchaResponse;
     return typeof solution.token === "string" ? solution.token : undefined;
@@ -187,8 +235,16 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
             if (!resolverVendorSupports(TWOCAPTCHA_VENDOR_ID, challenge.kind)) {
                 throw new TypeError(`2captcha resolver does not support ${challenge.kind}`);
             }
-            if (challenge.kind !== "recaptcha_v2") {
-                // AWS WAF remains deferred because its challenge variant has no required site key.
+            if (challenge.kind !== "recaptcha_v2" && challenge.kind !== "aws_waf") {
+                throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "not_implemented", {
+                    phase: "create_task",
+                });
+            }
+            if (challenge.kind === "aws_waf" &&
+                (!challenge.siteKey?.trim() ||
+                    !challenge.captchaScript?.trim() ||
+                    !challenge.context?.trim() ||
+                    !challenge.iv?.trim())) {
                 throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "not_implemented", {
                     phase: "create_task",
                 });
@@ -211,17 +267,26 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
             let phase = "create_task";
             try {
                 const createTask = async () => {
-                    const createResult = await postJson(fetchImpl, endpoint(baseUrl, "createTask"), {
-                        clientKey: apiKey,
-                        task: {
+                    const task = challenge.kind === "aws_waf"
+                        ? {
+                            type: proxy ? "AmazonTask" : "AmazonTaskProxyless",
+                            websiteURL: challenge.pageUrl,
+                            websiteKey: challenge.siteKey,
+                            captchaScript: challenge.captchaScript,
+                            context: challenge.context,
+                            iv: challenge.iv,
+                            ...(identity ? { userAgent: identity.userAgent } : {}),
+                            ...(proxy ?? {}),
+                        }
+                        : {
                             type: proxy ? "RecaptchaV2Task" : "RecaptchaV2TaskProxyless",
                             websiteURL: challenge.pageUrl,
                             websiteKey: challenge.siteKey,
                             isInvisible: false,
                             ...(identity ? { userAgent: identity.userAgent } : {}),
                             ...(proxy ?? {}),
-                        },
-                    }, solveController.signal, phase);
+                        };
+                    const createResult = await postJson(fetchImpl, endpoint(baseUrl, "createTask"), { clientKey: apiKey, task }, solveController.signal, phase, [apiKey]);
                     const taskId = taskIdFrom(createResult.payload);
                     if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
                         throw unavailableForPayload(createResult.payload, phase);
@@ -248,7 +313,7 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
                         callerSignal.throwIfAborted();
                         if (now() - startedAt >= timeoutMs)
                             throw new TwoCaptchaSolveTimeoutError();
-                        const pollResult = await postJson(fetchImpl, endpoint(baseUrl, "getTaskResult"), { clientKey: apiKey, taskId }, solveController.signal, phase);
+                        const pollResult = await postJson(fetchImpl, endpoint(baseUrl, "getTaskResult"), { clientKey: apiKey, taskId }, solveController.signal, phase, [apiKey]);
                         if (!pollResult.ok || pollResult.payload.errorId !== 0) {
                             throw unavailableForPayload(pollResult.payload, phase);
                         }
@@ -257,7 +322,7 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
                         if (pollResult.payload.status !== "ready") {
                             throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", { phase });
                         }
-                        const token = tokenFrom(pollResult.payload);
+                        const token = tokenFrom(pollResult.payload, challenge);
                         if (!token?.trim()) {
                             throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", { phase });
                         }
@@ -284,10 +349,12 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
                         phase,
                     });
                 }
-                if (error instanceof ResolverVendorUnavailableError)
+                if (error instanceof ResolverVendorUnavailableError ||
+                    error instanceof ResolverChallengeVerdictError) {
                     throw error;
+                }
                 throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
-                    cause: error,
+                    ...safeCauseOptions(error, [apiKey]),
                     phase,
                 });
             }

package/dist/runtime/resolver-vendors/types.d.ts

@@ -55,8 +55,8 @@ export interface ResolverVendorAdapter {
     getIssuingIdentity?(solution: ChallengeSolution, requestedIdentity: ResolverIdentity | undefined, challenge: ProviderChallenge): ResolverIssuingIdentity | undefined;
     solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder, transport?: ResolverVendorTransport): Promise<ChallengeSolution>;
 }
-export type ResolverVendorUnavailableReason = "missing_credentials" | "missing_proxy_identity" | "missing_transport" | "allocation_exhausted" | "transport_failure" | "timeout" | "not_implemented";
-export type ResolverChallengeVerdictReason = "human_puzzle";
+export type ResolverVendorUnavailableReason = "missing_credentials" | "missing_proxy_identity" | "missing_client_profile" | "missing_transport" | "allocation_exhausted" | "transport_failure" | "timeout" | "not_implemented";
+export type ResolverChallengeVerdictReason = "human_puzzle" | "solve_failed";
 type ResolverErrorOptions = {
     /** Raw cause; adapters must not place bodies, cookies, headers, credentials, or proxy URLs here. */
     readonly cause?: unknown;

package/dist/runtime/resolver-vendors/types.js

@@ -56,7 +56,9 @@ export class ResolverChallengeVerdictError extends Error {
     vendor;
     reason;
     constructor(vendor, reason, options = {}) {
-        super(`Resolver vendor ${vendor} returned a challenge verdict: ${reason}`);
+        super(reason === "solve_failed"
+            ? `Resolver vendor ${vendor} attempted the challenge but did not solve it`
+            : `Resolver vendor ${vendor} returned a challenge verdict: ${reason}`);
         this.vendor = vendor;
         this.reason = reason;
         this.name = "ResolverChallengeVerdictError";

package/dist/runtime/resolver.d.ts

@@ -1,3 +1,4 @@
+import { type ProxyResolutionOptions } from "../config/loader.js";
 import type { ChallengeSolution, ProviderCache, ProviderChallenge, ProviderChallengeKind, ProviderProxyMode, ProviderResolverConfig, ProviderResolverVendor, ResolverContext } from "../types.js";
 import { type ResolverIdentity, type ResolverVendorAdapter, type ResolverVendorTransport } from "./resolver-vendors/types.js";
 import type { TraceRecorder } from "./trace.js";
@@ -10,8 +11,14 @@ type ResolverChainClient = ResolverContext & {
 export interface ResolverRuntimeOptions {
     readonly allowedHosts?: readonly string[];
     readonly cache?: ProviderCache;
-    /** Provider-declared proxy intent. The SDK never accepts a caller-built identity. */
-    readonly proxyMode?: ProviderProxyMode;
+    /** Inputs for SDK-owned lazy proxy resolution. The SDK never accepts a caller-built identity. */
+    readonly proxyIntent?: {
+        readonly mode: ProviderProxyMode;
+        readonly upstream: NonNullable<ProxyResolutionOptions["upstream"]>;
+        readonly affinityKey?: ProxyResolutionOptions["affinityKey"];
+        readonly telemetry?: ProxyResolutionOptions["telemetry"];
+        readonly userAgent?: string;
+    };
     /** Server-owned context/proxy scope used only for identity-bound cache entries. */
     readonly identityScope?: string;
     /** SDK-owned transport already bound to the resolved proxy lease and client profile. */
@@ -30,6 +37,8 @@ export type ResolverInstrumentationMetadata = {
 export type ResolverAdapterFactory = (configuration: string, timeoutMs: number, allowedHosts: readonly string[]) => ResolverVendorAdapter;
 export declare const RESOLVER_ADAPTER_REGISTRY: Partial<Readonly<Record<ProviderResolverVendor, ResolverAdapterFactory>>>;
 export declare function swapResolverAdapterFactoryForTests(vendor: ProviderResolverVendor, factory: ResolverAdapterFactory | undefined): () => void;
+/** Internal test seam; deliberately not re-exported from the package root. */
+export declare function swapResolverDefaultUserAgentForTests(resolver: (() => string | undefined) | undefined): () => void;
 /** Remove the cached entry for the exact solution object returned by this resolver. */
 export declare function invalidateResolverSolution(resolver: ResolverContext, challenge: ProviderChallenge, solution: ChallengeSolution): Promise<void>;
 export declare function createResolverClient(options: {
@@ -38,7 +47,7 @@ export declare function createResolverClient(options: {
     readonly unavailableReason?: string;
     readonly cache?: ProviderCache;
     readonly identity?: ResolverIdentity;
-    readonly proxyMode?: ProviderProxyMode;
+    readonly proxyIntent?: ResolverRuntimeOptions["proxyIntent"];
     readonly transport?: ResolverVendorTransport;
     readonly createTransport?: ResolverRuntimeOptions["createTransport"];
     readonly clientProfile?: string;

package/dist/runtime/resolver.js

@@ -1,5 +1,7 @@
 import { createHash } from "node:crypto";
+import { resolveProxyConfigAsync, } from "../config/loader.js";
 import { ProviderError } from "../errors.js";
+import { getStealthProfile } from "../stealth/profiles.js";
 import { resolverChallengeAllowsDirectCache, resolverChallengeIsCacheable, resolverChallengeIsIdentityScoped, resolverChallengeIssuingIdentity, } from "./resolver-vendors/bindings.js";
 import { createBrowserResolverVendorAdapter } from "./resolver-vendors/browser.js";
 import { assertResolverHostAllowed } from "./resolver-vendors/hosts.js";
@@ -7,6 +9,7 @@ import { createTwoCaptchaResolverVendorAdapter } from "./resolver-vendors/twocap
 import { RESOLVER_VENDOR_CAPABILITIES, ResolverVendorUnavailableError, resolverVendorSupports, } from "./resolver-vendors/types.js";
 import { createUnsupportedResolverClient, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
 import { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./resolver-config.js";
+import { DEFAULT_PROFILE } from "./stealth.js";
 export { createUnsupportedResolverClient, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
 export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./resolver-config.js";
 const RESOLVER_SOLUTION_CACHE_NAMESPACE = "resolver-solution";
@@ -84,6 +87,20 @@ export function swapResolverAdapterFactoryForTests(vendor, factory) {
             resolverAdapterRegistry[vendor] = original;
     };
 }
+let resolveDefaultResolverUserAgent = () => getStealthProfile(DEFAULT_PROFILE).userAgent;
+/** Internal test seam; deliberately not re-exported from the package root. */
+export function swapResolverDefaultUserAgentForTests(resolver) {
+    const original = resolveDefaultResolverUserAgent;
+    resolveDefaultResolverUserAgent =
+        resolver ?? (() => getStealthProfile(DEFAULT_PROFILE).userAgent);
+    let restored = false;
+    return () => {
+        if (restored)
+            return;
+        restored = true;
+        resolveDefaultResolverUserAgent = original;
+    };
+}
 // This is the sole allowlist for declared vendors whose registry entry may be absent.
 // Remove a vendor here when its adapter is registered.
 const KNOWN_UNIMPLEMENTED_RESOLVER_VENDORS = new Set([
@@ -172,6 +189,8 @@ function adapterRequiresTransport(adapter, kind) {
 function sanitizeDiagnosticUrl(rawUrl) {
     try {
         const parsed = new URL(rawUrl);
+        if (parsed.username || parsed.password)
+            return "[REDACTED_PROXY_URL]";
         return `${parsed.protocol}//${parsed.host}`;
     }
     catch {
@@ -187,7 +206,9 @@ function sanitizeCauseMessage(message) {
         .split(/\s+/)
         .filter(Boolean)
         .map((token) => {
-        if (token === "[REDACTED]" || /^[a-z][a-z\d+.-]*:\/\/[^\s]+$/i.test(token))
+        if (token === "[REDACTED]" ||
+            token === "[REDACTED_PROXY_URL]" ||
+            /^[a-z][a-z\d+.-]*:\/\/[^\s]+$/i.test(token))
             return token;
         const word = token.replace(/^[^a-z\d]+|[^a-z\d]+$/gi, "");
         return word.length > 0 &&
@@ -449,6 +470,47 @@ export async function invalidateResolverSolution(resolver, challenge, solution)
         onSuccess: (outcome) => ({ outcome }),
     });
 }
+async function resolveResolverIdentity(proxyIntent) {
+    const userAgentSource = proxyIntent.userAgent ? "declared" : "defaulted";
+    let proxyUrl;
+    try {
+        const resolved = await resolveProxyConfigAsync({
+            upstream: proxyIntent.upstream,
+            affinityKey: proxyIntent.affinityKey,
+            telemetry: proxyIntent.telemetry
+                ? {
+                    ...proxyIntent.telemetry,
+                    recordProxyResolution(event) {
+                        proxyIntent.telemetry?.recordProxyResolution({
+                            ...event,
+                            userAgentSource,
+                        });
+                    },
+                }
+                : undefined,
+        });
+        proxyUrl = resolved.url;
+        if (!proxyUrl)
+            return { unavailableReason: "missing_proxy_identity", userAgentSource };
+    }
+    catch {
+        // Lease failures contain infrastructure detail that must not cross the resolver
+        // boundary. A required policy is classified by the existing fail-closed guard.
+        return { unavailableReason: "missing_proxy_identity", userAgentSource };
+    }
+    try {
+        const userAgent = proxyIntent.userAgent || resolveDefaultResolverUserAgent();
+        if (!userAgent)
+            return { unavailableReason: "missing_client_profile", userAgentSource };
+        return {
+            identity: { proxyUrl, userAgent },
+            userAgentSource,
+        };
+    }
+    catch {
+        return { unavailableReason: "missing_client_profile", userAgentSource };
+    }
+}
 function createResolverChainClient(options) {
     assertClientProfileTransportContract(options.clientProfile, options.transport);
     const client = {
@@ -464,18 +526,23 @@ function createResolverChainClient(options) {
             if (supportingEntries.length === 0)
                 throwUnsupportedKind(challenge.kind);
             signal.throwIfAborted();
-            // A required proxy policy is checked before the cache. Solutions minted under a
-            // previous release are shared and long-lived, so consulting the cache first would
-            // keep reporting success without a proxy identity until every old entry expired.
-            const requiredProxyIdentityMissing = options.proxyMode === "required" && options.identity === undefined;
+            const identityResolution = options.proxyIntent
+                ? await resolveResolverIdentity(options.proxyIntent)
+                : { identity: options.identity };
+            const identity = identityResolution.identity;
+            signal.throwIfAborted();
+            // Resolve a required proxy lease before consulting the cache. Solutions minted
+            // under a previous release are shared and long-lived, but a portable cached token
+            // must not bypass the upstream admission policy when no lease can be resolved.
+            const requiredProxyIdentityMissing = options.proxyIntent?.mode === "required" && identity === undefined;
             if (requiredProxyIdentityMissing) {
                 throwExhausted(supportingEntries.map((entry) => ({
                     vendor: entry.id,
-                    reason: "missing_proxy_identity",
+                    reason: identityResolution.unavailableReason ?? "missing_proxy_identity",
                 })));
             }
             if (options.cache && resolverChallengeIsCacheable(challenge)) {
-                const cached = await findCachedSolution(options.cache, challenge, options.identity, options.identityScope);
+                const cached = await findCachedSolution(options.cache, challenge, identity, options.identityScope);
                 if (cached)
                     return cached;
             }
@@ -498,7 +565,7 @@ function createResolverChainClient(options) {
                         const transport = unrestrictedTransport
                             ? restrictResolverTransport(unrestrictedTransport, options.allowedHosts ?? [])
                             : undefined;
-                        return adapter.solve(challenge, options.identity, signal, traceRecorder, transport);
+                        return adapter.solve(challenge, identity, signal, traceRecorder, transport);
                     };
                     const solution = traceRecorder
                         ? await traceRecorder.runSpan("resolver.vendor.attempt", solveAttempt, {
@@ -506,6 +573,7 @@ function createResolverChainClient(options) {
                                 vendor: adapter.id,
                                 challenge_kind: challenge.kind,
                                 client_profile: options.clientProfile,
+                                resolver_identity_source: identityResolution.userAgentSource,
                             },
                             onError(error) {
                                 return error instanceof ResolverVendorUnavailableError
@@ -518,9 +586,9 @@ function createResolverChainClient(options) {
                         resolverChallengeIsCacheable(challenge) &&
                         solution.form === "cookies" &&
                         solutionExpiryMs(solution) !== undefined) {
-                        const issuingIdentity = adapter.getIssuingIdentity?.(solution, options.identity, challenge) ??
+                        const issuingIdentity = adapter.getIssuingIdentity?.(solution, identity, challenge) ??
                             resolverChallengeIssuingIdentity(challenge, {
-                                ...(options.identity ? { proxyUrl: options.identity.proxyUrl } : {}),
+                                ...(identity ? { proxyUrl: identity.proxyUrl } : {}),
                                 userAgent: solution.userAgent,
                             });
                         if (issuingIdentity) {
@@ -553,7 +621,7 @@ export function createResolverClient(options) {
         unavailableReason: options.unavailableReason,
         cache: options.cache,
         identity: options.identity,
-        proxyMode: options.proxyMode,
+        proxyIntent: options.proxyIntent,
         transport: options.transport,
         createTransport: options.createTransport,
         clientProfile: options.clientProfile,
@@ -620,7 +688,7 @@ function createResolverClientFromEnvInternal(config, env, options, adapterFactor
             };
         }),
         cache: options.cache,
-        proxyMode: options.proxyMode,
+        proxyIntent: options.proxyIntent,
         identityScope: options.identityScope,
         transport: options.transport,
         createTransport: options.createTransport,

package/dist/runtime/stealth.d.ts

@@ -1,6 +1,7 @@
 import type { BrowserProfile, EmulationOS } from "wreq-js";
 import type { ProxyResolutionOptions } from "../config/loader.js";
 import type { StealthClient, StealthResponse } from "../types.js";
+export declare const DEFAULT_PROFILE = "chrome-146";
 export type StealthClientOptions = ProxyResolutionOptions & {
     warn?: (message: string) => void;
     /**

package/dist/runtime/stealth.js

@@ -7,7 +7,7 @@ import { createProxyAuthIpDeniedError, createProxyEdgeAuthRejectedError, createP
 import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, 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";
-const DEFAULT_PROFILE = "chrome-146";
+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_POOL_REFRESHES = 1;
 const PROXY_CONNECT_FAILURE_CODE = "proxy_connect_failed";

package/dist/server/serve-implementation.js

@@ -358,6 +358,7 @@ function createProviderContext(provider, request, operationId, options, state =
     const baseUrl = getProviderBaseUrl(provider);
     const stealthBaseUrl = getProviderStealthBaseUrl(provider);
     const stealthProfile = getProviderStealthProfile(provider);
+    const proxyPolicy = resolveNativeProxyPolicy(provider);
     const proxyClientOptions = {
         upstream: { proxy: provider.proxy },
         affinityKey: resolveProviderProxyAffinityKey(provider, request, operationId),
@@ -444,7 +445,15 @@ function createProviderContext(provider, request, operationId, options, state =
                     allowedHosts: provider.allowedHosts,
                     cache,
                     identityScope: resolverIdentityScope,
-                    proxyMode: resolveNativeProxyPolicy(provider)?.mode,
+                    ...(proxyPolicy
+                        ? {
+                            proxyIntent: {
+                                mode: proxyPolicy.mode,
+                                ...proxyClientOptions,
+                                ...(stealthProfile ? { userAgent: stealthProfile.userAgent } : {}),
+                            },
+                        }
+                        : {}),
                 }), signal)
             : bindResolverSignalWithoutRuntime(options.resolver ??
                 createUnsupportedResolverClient("Provider does not declare resolver capability"), signal),
@@ -487,6 +496,7 @@ function createAuthFlowContext(provider, request, options, signal) {
     const baseUrl = getProviderBaseUrl(provider);
     const stealthBaseUrl = getProviderStealthBaseUrl(provider);
     const stealthProfile = getProviderStealthProfile(provider);
+    const proxyPolicy = resolveNativeProxyPolicy(provider);
     const contextData = request.context ?? {};
     const flowContextStore = createFlowContextStore(provider.context?.keys ?? Object.keys(contextData), contextData);
     const proxyClientOptions = {
@@ -559,7 +569,15 @@ function createAuthFlowContext(provider, request, options, signal) {
                         allowedHosts: provider.allowedHosts,
                         cache,
                         identityScope: resolverIdentityScope,
-                        proxyMode: resolveNativeProxyPolicy(provider)?.mode,
+                        ...(proxyPolicy
+                            ? {
+                                proxyIntent: {
+                                    mode: proxyPolicy.mode,
+                                    ...proxyClientOptions,
+                                    ...(stealthProfile ? { userAgent: stealthProfile.userAgent } : {}),
+                                },
+                            }
+                            : {}),
                     }), signal)
                 : bindResolverSignalWithoutRuntime(options.resolver ??
                     createUnsupportedResolverClient("Provider does not declare resolver capability"), signal),

package/dist/testing/index.d.ts

@@ -1,2 +1,3 @@
 export { describeTransform, snapshotTransform, toMatchShape } from "./helpers.js";
+export { resetProviderCacheForTests } from "../runtime/cache.js";
 export { runStandardTests, type StandardTestsManifest, type StandardTestsOptions, type StandardTestsResult, type StandardTestsUpstreamCall, type StandardTestsUpstreamResponse, type StandardTestsUpstreamStub, } from "./run.js";

package/dist/testing/index.js

@@ -1,2 +1,3 @@
 export { describeTransform, snapshotTransform, toMatchShape } from "./helpers.js";
+export { resetProviderCacheForTests } from "../runtime/cache.js";
 export { runStandardTests, } from "./run.js";

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.28",
+	"version": "2.2.0-beta.29",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -77,9 +77,9 @@
 			"default": "./dist/runtime/prevalidate.js"
 		},
 		"./runtime/resolver": {
-			"types": "./dist/runtime/resolver.d.ts",
-			"import": "./dist/runtime/resolver.js",
-			"default": "./dist/runtime/resolver.js"
+			"types": "./dist/runtime/resolver-public.d.ts",
+			"import": "./dist/runtime/resolver-public.js",
+			"default": "./dist/runtime/resolver-public.js"
 		},
 		"./runtime/stealth": {
 			"types": "./dist/runtime/stealth.d.ts",

package/src/auth.ts

@@ -296,6 +296,25 @@ export interface DefineCredentialsAuthOptions<
 	):
 		| CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>
 		| Promise<CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>>;
+	/**
+	 * Optional re-mint of an expired session from the stored credential, wired
+	 * to `auth.flow.refresh`.
+	 *
+	 * Credential-auth upstreams routinely invalidate a session well before the
+	 * `expiresAt` the provider advertised, which leaves every operation failing
+	 * with a reauth error until a human repeats the whole interactive login.
+	 * Implement this to re-establish the session from what is already stored on
+	 * the connection; the result is resolved exactly like `login`, so it may
+	 * also raise a challenge when the upstream demands one. Omit it when the
+	 * upstream has no non-interactive path and re-authentication genuinely
+	 * requires the user.
+	 */
+	refresh?(
+		ctx: FlowContext,
+		input: Partial<CredentialsAuthInput<TFields>>,
+	):
+		| CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>
+		| Promise<CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>>;
 }
 
 export interface DefinedCredentialsAuth {
@@ -376,6 +395,27 @@ function normalizeInput<TFields extends CredentialsAuthFields>(
 	return result as CredentialsAuthInput<TFields>;
 }
 
+/**
+ * Refresh variant of {@link normalizeInput}. `login` coerces every declared
+ * field to a string because the interactive turn has already enforced that they
+ * are present; refresh runs with no user present, so an absent field is omitted
+ * rather than turned into an empty string. That keeps "the user did not supply
+ * this" distinguishable from "the user supplied an empty value".
+ */
+function normalizePartialInput<TFields extends CredentialsAuthFields>(
+	fields: TFields,
+	input: Record<string, unknown> | undefined,
+): Partial<CredentialsAuthInput<TFields>> {
+	const result: Record<string, string> = {};
+	for (const name of Object.keys(fields)) {
+		const value = input?.[name];
+		if (typeof value === "string") {
+			result[name] = value;
+		}
+	}
+	return result as Partial<CredentialsAuthInput<TFields>>;
+}
+
 function assertCredentialKeys<TCredentialKeys extends readonly string[]>(
 	credentialKeys: TCredentialKeys,
 	credential: Record<string, unknown>,
@@ -716,6 +756,44 @@ export function defineCredentialsAuth<
 						completeTurnId,
 					);
 				},
+				// Only advertise refresh when the provider implements it: the
+				// protocol treats the hook's presence as "this connection can be
+				// re-established without the user", and exposing a stub that
+				// cannot actually re-mint would turn a recoverable expiry into a
+				// silent failure.
+				...(options.refresh
+					? {
+							refresh: async (ctx: FlowContext, rawInput?: Record<string, unknown>) => {
+								// A pending challenge belongs to the interactive flow that
+								// raised it; finish it there rather than restarting.
+								const pending = getPendingChallenge(ctx);
+								if (pending) {
+									return await continuePendingChallenge(
+										ctx,
+										options.credentialKeys,
+										challenges,
+										pending,
+										rawInput,
+										completeTurnId,
+									);
+								}
+
+								// Refresh runs without user input, so fields are optional
+								// here — unlike `continue`, missing ones are not a retry.
+								const result = await options.refresh!(
+									ctx,
+									normalizePartialInput(options.fields, rawInput),
+								);
+								return await resolveAuthResult(
+									ctx,
+									options.credentialKeys,
+									challenges,
+									result,
+									completeTurnId,
+								);
+							},
+						}
+					: {}),
 			},
 		},
 		credential: {

package/src/config/loader.ts

@@ -103,8 +103,11 @@ export type SmartproxyAllocatorBodyClass =
 	| "text_without_proxies"
 	| "usable_proxy_endpoints";
 
+export type ProxyUserAgentSource = "declared" | "defaulted";
+
 export type ProxyResolutionTelemetryEvent = {
 	provider: ProxyVendorName;
+	userAgentSource?: ProxyUserAgentSource;
 	protocol?: ProxyProtocol;
 	cacheStatus: ProxyCacheStatus;
 	cacheHit: boolean;

package/src/index.ts

@@ -55,7 +55,6 @@ export {
 	createBypassProviderCache,
 	createProviderCache,
 	type ProviderCacheOptions,
-	resetProviderCacheForTests,
 } from "./runtime/cache.js";
 export {
 	type CreateProviderChoiceContextOptions,