@apifuse/provider-sdk 2.2.0-beta.24 → 2.2.0-beta.26

package/dist/runtime/resolver.js

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
 import { ProviderError } from "../errors.js";
-import { resolverChallengeIsIdentityScoped, resolverChallengeIssuingIdentity, } from "./resolver-vendors/bindings.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";
+import { createTwoCaptchaResolverVendorAdapter } from "./resolver-vendors/twocaptcha.js";
 import { RESOLVER_VENDOR_CAPABILITIES, ResolverVendorUnavailableError, resolverVendorSupports, } from "./resolver-vendors/types.js";
 export const APIFUSE__RESOLVER__2CAPTCHA__API_KEY = "APIFUSE__RESOLVER__2CAPTCHA__API_KEY";
 export const APIFUSE__RESOLVER__CAPSOLVER__API_KEY = "APIFUSE__RESOLVER__CAPSOLVER__API_KEY";
@@ -14,8 +16,51 @@ const RESOLVER_SOLUTION_INDEX_CACHE_NAMESPACE = "resolver-solution-index";
 const MIN_RESOLVER_CACHE_TTL_MS = 1_000;
 const resolverCaches = new WeakMap();
 const solutionIssuerDigests = new WeakMap();
+const SAFE_CAUSE_MESSAGE_WORDS = new Set([
+    "abort",
+    "aborted",
+    "at",
+    "closed",
+    "connect",
+    "connection",
+    "dns",
+    "during",
+    "econnrefused",
+    "econnreset",
+    "error",
+    "etimedout",
+    "failed",
+    "failure",
+    "fetch",
+    "from",
+    "get",
+    "lookup",
+    "network",
+    "post",
+    "reading",
+    "refused",
+    "request",
+    "reset",
+    "response",
+    "socket",
+    "timed",
+    "timeout",
+    "tls",
+    "to",
+    "unavailable",
+    "upstream",
+    "while",
+    "writing",
+]);
 export const RESOLVER_INSTRUMENTATION_METADATA = Symbol.for("@apifuse/provider-sdk/runtime/resolver-instrumentation-metadata");
-export const RESOLVER_ADAPTER_REGISTRY = {
+const resolverAdapterRegistry = {
+    "2captcha"(configuration, timeoutMs, allowedHosts) {
+        return createTwoCaptchaResolverVendorAdapter({
+            allowedHosts,
+            apiKey: configuration,
+            timeoutMs,
+        });
+    },
     browser(configuration, timeoutMs, allowedHosts) {
         return createBrowserResolverVendorAdapter({
             allowedHosts,
@@ -24,10 +69,27 @@ export const RESOLVER_ADAPTER_REGISTRY = {
         });
     },
 };
+export const RESOLVER_ADAPTER_REGISTRY = resolverAdapterRegistry;
+export function swapResolverAdapterFactoryForTests(vendor, factory) {
+    const original = resolverAdapterRegistry[vendor];
+    if (factory === undefined)
+        delete resolverAdapterRegistry[vendor];
+    else
+        resolverAdapterRegistry[vendor] = factory;
+    let restored = false;
+    return () => {
+        if (restored)
+            return;
+        restored = true;
+        if (original === undefined)
+            delete resolverAdapterRegistry[vendor];
+        else
+            resolverAdapterRegistry[vendor] = 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([
-    "2captcha",
     "capsolver",
     "capmonster",
     "custom",
@@ -65,8 +127,8 @@ function createUnavailableAdapter(vendor, reason) {
         },
     };
 }
-function createAdapter(vendor, timeoutMs, allowedHosts) {
-    const factory = RESOLVER_ADAPTER_REGISTRY[vendor.vendor];
+function createAdapter(vendor, timeoutMs, allowedHosts, adapterFactories) {
+    const factory = adapterFactories[vendor.vendor];
     if (!factory && !KNOWN_UNIMPLEMENTED_RESOLVER_VENDORS.has(vendor.vendor)) {
         throw new Error(`Resolver adapter factory is missing for implemented vendor "${vendor.vendor}"`);
     }
@@ -97,6 +159,117 @@ function throwExhausted(attempts) {
         details: attempts,
     });
 }
+function assertClientProfileTransportContract(clientProfile, transport) {
+    if (clientProfile === undefined || transport === undefined)
+        return;
+    throw new ProviderError(`Resolver client profile "${clientProfile}" cannot be applied to a pre-bound transport`, {
+        code: "RESOLVER_CLIENT_PROFILE_TRANSPORT_CONFLICT",
+        fix: "Remove the pre-bound transport and provide createTransport({ clientProfile, identityScope }) so the SDK can apply the provider-declared profile.",
+    });
+}
+function adapterRequiresTransport(adapter, kind) {
+    return typeof adapter.requiresTransport === "function"
+        ? adapter.requiresTransport(kind)
+        : adapter.requiresTransport === true;
+}
+function sanitizeDiagnosticUrl(rawUrl) {
+    try {
+        const parsed = new URL(rawUrl);
+        return `${parsed.protocol}//${parsed.host}`;
+    }
+    catch {
+        return "[REDACTED_URL]";
+    }
+}
+function sanitizeCauseMessage(message) {
+    const withoutUrls = message.replace(/\b[a-z][a-z\d+.-]*:\/\/[^\s"'<>]+/gi, sanitizeDiagnosticUrl);
+    const withoutAssignments = withoutUrls.replace(/(?:^|\s)[^\s=]+=[^\s]*/g, " [REDACTED]");
+    const safeTokens = withoutAssignments
+        .replaceAll("\r", " ")
+        .replaceAll("\n", " ")
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((token) => {
+        if (token === "[REDACTED]" || /^[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 && word.length <= 32 && SAFE_CAUSE_MESSAGE_WORDS.has(word.toLowerCase())
+            ? token
+            : "[REDACTED]";
+    });
+    return safeTokens
+        .filter((token, index) => token !== "[REDACTED]" || safeTokens[index - 1] !== token)
+        .join(" ")
+        .slice(0, 512);
+}
+function restrictResolverTransport(transport, allowedHosts) {
+    return {
+        async fetch(url, init) {
+            // Empty declarations remain deny-by-default, matching the adapter-factory/browser path.
+            assertResolverHostAllowed(url, allowedHosts);
+            const response = await transport.fetch(url, { ...init, redirect: "manual" });
+            const hasLocationHeader = Object.keys(response.headers).some((name) => name.toLowerCase() === "location");
+            if (response.status >= 300 && response.status < 400 && hasLocationHeader) {
+                throw new ProviderError("Resolver transport refused a redirect response", {
+                    code: "RESOLVER_HOST_NOT_ALLOWED",
+                    fix: "Use a non-redirecting http or https URL on a host declared in allowedHosts.",
+                });
+            }
+            return response;
+        },
+    };
+}
+function safeCause(error) {
+    if (error.cause === undefined)
+        return undefined;
+    const cause = error.cause;
+    const rawName = cause instanceof Error ? cause.name : "Error";
+    return {
+        name: /^[a-z\d_.:-]{1,64}$/i.test(rawName) ? rawName : "Error",
+        message: sanitizeCauseMessage(cause instanceof Error ? cause.message : String(cause)),
+    };
+}
+function safeUpstreamHost(host) {
+    if (host === undefined)
+        return undefined;
+    const trimmed = host.trim();
+    if (/^[a-z\d.-]+$/i.test(trimmed))
+        return trimmed.toLowerCase();
+    try {
+        return new URL(trimmed).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+function safePhase(phase) {
+    return phase !== undefined && /^[a-z\d_.:-]{1,64}$/i.test(phase) ? phase : undefined;
+}
+function unavailableAttempt(error) {
+    const cause = safeCause(error);
+    const upstreamHost = safeUpstreamHost(error.upstreamHost);
+    const phase = safePhase(error.phase);
+    const round = Number.isSafeInteger(error.round) && error.round > 0 ? error.round : undefined;
+    return {
+        vendor: error.vendor,
+        reason: error.reason,
+        ...(cause ? { cause } : {}),
+        ...(upstreamHost ? { upstreamHost } : {}),
+        ...(phase ? { phase } : {}),
+        ...(round !== undefined ? { round } : {}),
+    };
+}
+function unavailableSpanAttributes(error) {
+    const attempt = unavailableAttempt(error);
+    return {
+        unavailability_reason: error.reason,
+        cause_name: attempt.cause?.name,
+        cause_message: attempt.cause?.message,
+        upstream_host: attempt.upstreamHost,
+        transport_phase: attempt.phase,
+        transport_round: attempt.round,
+    };
+}
 function challengeOrigin(challenge) {
     return new URL(challenge.pageUrl).origin;
 }
@@ -211,7 +384,9 @@ async function writeResolverCacheIndex(cache, challenge, entries, now) {
     const ttlMs = Math.max(1, Math.floor(Math.max(...liveEntries.map((entry) => entry.expiresAtMs)) - now));
     await cache.set(indexKey, { entries: liveEntries }, { ttlMs });
 }
-async function cacheBrowserSolution(cache, challenge, solution, identity, identityScope) {
+async function cacheResolverSolution(cache, challenge, solution, identity, identityScope) {
+    if (!resolverChallengeIsCacheable(challenge))
+        return;
     const expiresAtMs = solutionExpiryMs(solution);
     const now = Date.now();
     if (expiresAtMs === undefined)
@@ -222,6 +397,11 @@ async function cacheBrowserSolution(cache, challenge, solution, identity, identi
     const scopedDigest = identityScope !== undefined && resolverChallengeIsIdentityScoped(challenge)
         ? resolverIdentityScopeDigest(identityScope)
         : undefined;
+    if (!resolverChallengeAllowsDirectCache(challenge) &&
+        scopedDigest === undefined &&
+        identity.proxyUrl === undefined) {
+        return;
+    }
     const issuerDigest = scopedDigest ?? resolverIdentityDigest(identity);
     await cache.set(resolverSolutionCacheKey(cache, challenge, issuerDigest), { expiresAtMs, issuerDigest, solution }, { ttlMs });
     rememberSolutionIssuer(solution, issuerDigest);
@@ -271,6 +451,7 @@ export async function invalidateResolverSolution(resolver, challenge, solution)
     });
 }
 function createResolverChainClient(options) {
+    assertClientProfileTransportContract(options.clientProfile, options.transport);
     const client = {
         async solve(challenge, signal = new AbortController().signal, traceRecorder) {
             assertDeclaredKind(challenge.kind, options.kinds);
@@ -284,7 +465,7 @@ function createResolverChainClient(options) {
             if (supportingEntries.length === 0)
                 throwUnsupportedKind(challenge.kind);
             signal.throwIfAborted();
-            if (options.cache && supportingEntries.some((entry) => entry.id === "browser")) {
+            if (options.cache && resolverChallengeIsCacheable(challenge)) {
                 const cached = await findCachedSolution(options.cache, challenge, options.identity, options.identityScope);
                 if (cached)
                     return cached;
@@ -293,24 +474,48 @@ function createResolverChainClient(options) {
             for (const entry of supportingEntries) {
                 const adapter = entry.createAdapter();
                 try {
-                    const solveAttempt = () => adapter.solve(challenge, options.identity, signal, traceRecorder);
+                    const solveAttempt = () => {
+                        const requiresTransport = adapterRequiresTransport(adapter, challenge.kind);
+                        const unrestrictedTransport = options.transport ??
+                            (requiresTransport
+                                ? options.createTransport?.({
+                                    clientProfile: options.clientProfile,
+                                    identityScope: options.identityScope,
+                                })
+                                : undefined);
+                        if (requiresTransport && unrestrictedTransport === undefined) {
+                            throw new ResolverVendorUnavailableError(adapter.id, "missing_transport");
+                        }
+                        const transport = unrestrictedTransport
+                            ? restrictResolverTransport(unrestrictedTransport, options.allowedHosts ?? [])
+                            : undefined;
+                        return adapter.solve(challenge, options.identity, signal, traceRecorder, transport);
+                    };
                     const solution = traceRecorder
                         ? await traceRecorder.runSpan("resolver.vendor.attempt", solveAttempt, {
                             attributes: {
                                 vendor: adapter.id,
                                 challenge_kind: challenge.kind,
+                                client_profile: options.clientProfile,
                             },
                             onError(error) {
                                 return error instanceof ResolverVendorUnavailableError
-                                    ? { unavailability_reason: error.reason }
+                                    ? unavailableSpanAttributes(error)
                                     : undefined;
                             },
                         })
                         : await solveAttempt();
-                    if (options.cache && entry.id === "browser" && solution.form === "cookies") {
-                        const issuingIdentity = adapter.getIssuingIdentity?.(solution, options.identity, challenge);
+                    if (options.cache &&
+                        resolverChallengeIsCacheable(challenge) &&
+                        solution.form === "cookies" &&
+                        solutionExpiryMs(solution) !== undefined) {
+                        const issuingIdentity = adapter.getIssuingIdentity?.(solution, options.identity, challenge) ??
+                            resolverChallengeIssuingIdentity(challenge, {
+                                ...(options.identity ? { proxyUrl: options.identity.proxyUrl } : {}),
+                                userAgent: solution.userAgent,
+                            });
                         if (issuingIdentity) {
-                            await cacheBrowserSolution(options.cache, challenge, solution, issuingIdentity, options.identityScope);
+                            await cacheResolverSolution(options.cache, challenge, solution, issuingIdentity, options.identityScope);
                         }
                     }
                     return solution;
@@ -319,7 +524,7 @@ function createResolverChainClient(options) {
                     signal.throwIfAborted();
                     if (!(error instanceof ResolverVendorUnavailableError))
                         throw error;
-                    attempts.push({ vendor: adapter.id, reason: error.reason });
+                    attempts.push(unavailableAttempt(error));
                 }
             }
             throwExhausted(attempts);
@@ -339,6 +544,10 @@ export function createResolverClient(options) {
         unavailableReason: options.unavailableReason,
         cache: options.cache,
         identity: options.identity,
+        transport: options.transport,
+        createTransport: options.createTransport,
+        clientProfile: options.clientProfile,
+        allowedHosts: options.allowedHosts,
     });
 }
 function resolveVendorAvailability(vendor, env) {
@@ -384,10 +593,11 @@ export function bindResolverSignal(resolver, defaultSignal) {
     }
     return boundResolver;
 }
-export function createResolverClientFromEnv(config, env = process.env, options = {}) {
+function createResolverClientFromEnvInternal(config, env, options, adapterFactories) {
     if (!config) {
         return createUnsupportedResolverClient("Provider does not declare resolver capability");
     }
+    assertClientProfileTransportContract(config.clientProfile, options.transport);
     if (config.vendors.length === 0) {
         return createResolverChainClient({
             kinds: config.kinds,
@@ -397,6 +607,7 @@ export function createResolverClientFromEnv(config, env = process.env, options =
     }
     const timeoutValue = readPositiveIntegerEnv(env, APIFUSE__RESOLVER__TIMEOUT_MS);
     const timeoutMs = timeoutValue === undefined ? DEFAULT_RESOLVER_TIMEOUT_MS : Number(timeoutValue);
+    const allowedHosts = [...(options.allowedHosts ?? [])];
     return createResolverChainClient({
         kinds: config.kinds,
         entries: config.vendors.map((configuredVendor) => {
@@ -405,10 +616,21 @@ export function createResolverClientFromEnv(config, env = process.env, options =
             return {
                 id: vendor,
                 supports: (kind) => resolverVendorSupports(vendor, kind),
-                createAdapter: () => createAdapter(resolveVendorAvailability(vendor, env), timeoutMs, options.allowedHosts ?? []),
+                createAdapter: () => createAdapter(resolveVendorAvailability(vendor, env), timeoutMs, allowedHosts, adapterFactories),
             };
         }),
         cache: options.cache,
         identityScope: options.identityScope,
+        transport: options.transport,
+        createTransport: options.createTransport,
+        clientProfile: config.clientProfile,
+        allowedHosts,
     });
 }
+export function createResolverClientFromEnv(config, env = process.env, options = {}) {
+    return createResolverClientFromEnvInternal(config, env, options, RESOLVER_ADAPTER_REGISTRY);
+}
+/** Internal test seam; deliberately not re-exported from the package root. */
+export function createResolverClientFromEnvForTests(config, env, options, adapterFactories) {
+    return createResolverClientFromEnvInternal(config, env, options, adapterFactories);
+}

package/dist/runtime/stealth.d.ts

@@ -1,4 +1,4 @@
-import type { ImpitResponse } from "impit";
+import type { BrowserProfile, EmulationOS } from "wreq-js";
 import type { ProxyResolutionOptions } from "../config/loader.js";
 import type { StealthClient, StealthResponse } from "../types.js";
 export type StealthClientOptions = ProxyResolutionOptions & {
@@ -12,12 +12,34 @@ export type StealthClientOptions = ProxyResolutionOptions & {
         insecureSkipVerify?: boolean;
     };
 };
-type StealthTransportResponse = Pick<ImpitResponse, "arrayBuffer" | "headers" | "json" | "ok" | "status" | "text"> & {
-    body?: ReadableStream<Uint8Array>;
-    abort?: () => void;
+type StealthTransportHeaders = {
+    entries(): IterableIterator<[string, string]>;
+    get(name: string): string | null;
+    getSetCookie?: () => string[];
+};
+type StealthTransportBody = {
+    cancel(): Promise<void>;
+    getReader(): {
+        read(): Promise<{
+            done: boolean;
+            value?: Uint8Array;
+        }>;
+        cancel(): Promise<void>;
+        releaseLock(): void;
+    };
+};
+type StealthTransportResponse = {
+    arrayBuffer(): Promise<ArrayBuffer>;
+    headers: StealthTransportHeaders;
+    status: number;
+    body?: StealthTransportBody | null;
     url?: string;
     redirected?: boolean;
 };
+export declare function resolveWreqProfile(profileName: string, wreqProfiles: readonly BrowserProfile[]): {
+    browser: BrowserProfile;
+    os: EmulationOS;
+};
 export declare function normalizeResponse(response: StealthTransportResponse, requestUrl?: string, maxBodyBytes?: number): Promise<StealthResponse>;
 export declare function createStealthClient(baseUrl: string, defaultProfileOrOptions?: string | StealthClientOptions, clientOptions?: StealthClientOptions): StealthClient;
 export {};