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

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

@@ -0,0 +1,40 @@
+// An IP-bound artifact minted without any recorded egress identity is unsafe to
+// share. The Akamai kinds therefore reject direct caching, while Cloudflare
+// keeps its pre-existing direct-cache behavior pending measurement.
+export const RESOLVER_CHALLENGE_BINDINGS = {
+    turnstile: { cacheable: false, identityBinding: "none", directCacheable: false },
+    recaptcha_v2: { cacheable: false, identityBinding: "none", directCacheable: false },
+    recaptcha_v3: { cacheable: false, identityBinding: "none", directCacheable: false },
+    hcaptcha: { cacheable: false, identityBinding: "none", directCacheable: false },
+    cloudflare_interstitial: {
+        cacheable: true,
+        identityBinding: "identity_scoped",
+        directCacheable: true,
+    },
+    aws_waf: { cacheable: true, identityBinding: "portable", directCacheable: true },
+    akamai_sec_cpt: {
+        cacheable: true,
+        identityBinding: "identity_scoped",
+        directCacheable: false,
+    },
+    akamai_sensor: {
+        cacheable: true,
+        identityBinding: "identity_scoped",
+        directCacheable: false,
+    },
+};
+export function resolverChallengeIsCacheable(challenge) {
+    return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].cacheable;
+}
+export function resolverChallengeAllowsDirectCache(challenge) {
+    return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].directCacheable;
+}
+export function resolverChallengeIsIdentityScoped(challenge) {
+    return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].identityBinding === "identity_scoped";
+}
+export function resolverChallengeIssuingIdentity(challenge, identity) {
+    if (RESOLVER_CHALLENGE_BINDINGS[challenge.kind].identityBinding === "portable") {
+        return { userAgent: identity.userAgent };
+    }
+    return identity;
+}

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

@@ -0,0 +1,22 @@
+import type { BrowserClient, ChallengeSolution, ProviderChallenge } from "../../types.js";
+import { type BrowserClientOptions } from "../browser.js";
+import type { TraceRecorder } from "../trace.js";
+import { type ResolverIdentity, type ResolverVendorAdapter } from "./types.js";
+type BrowserClientFactory = (options: BrowserClientOptions) => BrowserClient;
+/** Internal test seam; deliberately not re-exported from the package root. */
+export declare function swapBrowserResolverClientFactoryForTests(factory: BrowserClientFactory | undefined): () => void;
+export interface BrowserResolverVendorOptions {
+    readonly cdpUrl?: string;
+    readonly timeoutMs: number;
+    readonly pollIntervalMs?: number;
+    readonly allowedHosts: readonly string[];
+    readonly createClient?: BrowserClientFactory;
+}
+export interface BrowserResolverVendorAdapter extends ResolverVendorAdapter {
+    readonly id: "browser";
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder): Promise<Extract<ChallengeSolution, {
+        readonly form: "cookies";
+    }>>;
+}
+export declare function createBrowserResolverVendorAdapter(options: BrowserResolverVendorOptions): BrowserResolverVendorAdapter;
+export {};

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

@@ -0,0 +1,377 @@
+import { isProviderError } from "../../errors.js";
+import { createBrowserClient } from "../browser.js";
+import { resolverChallengeIssuingIdentity } from "./bindings.js";
+import { assertResolverHostAllowed, normalizedResolverHostname } from "./hosts.js";
+import { ResolverVendorUnavailableError, } from "./types.js";
+const BROWSER_VENDOR_ID = "browser";
+const DEFAULT_COOKIE_POLL_INTERVAL_MS = 100;
+const NAVIGATION_BLOCKED_ERROR_TEXT = "net::ERR_BLOCKED_BY_CLIENT";
+const AWS_WAF_CHALLENGE_INFRASTRUCTURE_HOST_SUFFIX = ".awswaf.com";
+const RESOLVER_DOCUMENT_CONTENT_SECURITY_POLICY = "connect-src http: https:; worker-src 'none'";
+const SUCCESS_COOKIE_NAMES = {
+    aws_waf: "aws-waf-token",
+    cloudflare_interstitial: "cf_clearance",
+};
+let createResolverBrowserClient = createBrowserClient;
+/** Internal test seam; deliberately not re-exported from the package root. */
+export function swapBrowserResolverClientFactoryForTests(factory) {
+    const original = createResolverBrowserClient;
+    createResolverBrowserClient = factory ?? createBrowserClient;
+    let restored = false;
+    return () => {
+        if (restored)
+            return;
+        restored = true;
+        createResolverBrowserClient = original;
+    };
+}
+class BrowserSolveTimeoutError extends Error {
+    constructor(blockedRequests) {
+        super(`Browser resolver solve budget elapsed${formatBlockedRequests(blockedRequests)}`);
+        this.name = "BrowserSolveTimeoutError";
+    }
+}
+class BrowserNavigationBlockedError extends Error {
+    navigationUrl;
+    blockedUrls;
+    code = "RESOLVER_BROWSER_NAVIGATION_BLOCKED";
+    constructor(navigationUrl, blockedUrls, options) {
+        super(`Browser resolver navigation was blocked for ${navigationUrl}${formatBlockedRequests(blockedUrls)}`, options);
+        this.navigationUrl = navigationUrl;
+        this.blockedUrls = blockedUrls;
+        this.name = "BrowserNavigationBlockedError";
+    }
+}
+function formatBlockedRequests(blockedRequests) {
+    if (blockedRequests.length === 0)
+        return "";
+    const displayed = blockedRequests.slice(0, 5);
+    const remainder = blockedRequests.length - displayed.length;
+    return `; blocked ${blockedRequests.length} requests: [${displayed.join(", ")}]${remainder > 0 ? ` (+${remainder} more)` : ""}`;
+}
+function isNavigationBlockedError(error) {
+    return error instanceof Error && error.message.includes(NAVIGATION_BLOCKED_ERROR_TEXT);
+}
+class BrowserCleanupTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Browser resolver cleanup exceeded ${timeoutMs}ms`);
+        this.name = "BrowserCleanupTimeoutError";
+    }
+}
+function abortReason(signal) {
+    return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+function raceWithAbort(operation, signal) {
+    if (signal.aborted) {
+        return Promise.reject(abortReason(signal));
+    }
+    return new Promise((resolve, reject) => {
+        const cleanup = () => signal.removeEventListener("abort", onAbort);
+        const onAbort = () => {
+            cleanup();
+            reject(abortReason(signal));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        operation().then((value) => {
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            cleanup();
+            reject(error);
+        });
+    });
+}
+async function runBoundedCleanup(cleanup, timeoutMs, challengeKind, operation, traceRecorder) {
+    let timeout;
+    const boundedCleanup = async () => {
+        try {
+            await Promise.race([
+                cleanup(),
+                new Promise((_resolve, reject) => {
+                    timeout = setTimeout(() => reject(new BrowserCleanupTimeoutError(timeoutMs)), timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+        }
+    };
+    if (!traceRecorder) {
+        await boundedCleanup().catch(() => undefined);
+        return;
+    }
+    await traceRecorder
+        .runSpan("resolver.vendor.cleanup", boundedCleanup, {
+        attributes: {
+            vendor: BROWSER_VENDOR_ID,
+            challenge_kind: challengeKind,
+            operation,
+        },
+        onError(error) {
+            return {
+                error_message: error instanceof Error ? error.message : String(error),
+                ...(error instanceof Error && error.stack ? { error_stack: error.stack } : {}),
+            };
+        },
+    })
+        .catch(() => undefined);
+}
+async function abortableDelay(ms, signal) {
+    let timer;
+    try {
+        await raceWithAbort(() => new Promise((resolve) => {
+            timer = setTimeout(resolve, ms);
+        }), signal);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function isSupportedKind(kind) {
+    return Object.hasOwn(SUCCESS_COOKIE_NAMES, kind);
+}
+function cookieDomainSpecificity(cookie) {
+    return normalizedResolverHostname(cookie.domain.replace(/^\./, "")).length;
+}
+function isHostOnlyCookieFor(cookie, hostname) {
+    return (!cookie.domain.startsWith(".") &&
+        normalizedResolverHostname(cookie.domain) === normalizedResolverHostname(hostname));
+}
+function cookieAppliesToUrl(cookie, url) {
+    const cookieDomain = normalizedResolverHostname(cookie.domain.replace(/^\./, ""));
+    const requestHostname = normalizedResolverHostname(url.hostname);
+    const domainMatches = cookieDomain.length > 0 &&
+        (requestHostname === cookieDomain ||
+            (cookie.domain.startsWith(".") && requestHostname.endsWith(`.${cookieDomain}`)));
+    if (!domainMatches || (cookie.secure && url.protocol !== "https:"))
+        return false;
+    const requestPath = url.pathname || "/";
+    const cookiePath = cookie.path;
+    return (cookiePath.startsWith("/") &&
+        (requestPath === cookiePath ||
+            (requestPath.startsWith(cookiePath) &&
+                (cookiePath.endsWith("/") || requestPath[cookiePath.length] === "/"))));
+}
+function selectSuccessCookie(cookies, successCookieName, pageUrl) {
+    const url = new URL(pageUrl);
+    return cookies
+        .filter((cookie) => cookie.name === successCookieName && cookieAppliesToUrl(cookie, url))
+        .sort((left, right) => Number(isHostOnlyCookieFor(right, url.hostname)) -
+        Number(isHostOnlyCookieFor(left, url.hostname)) ||
+        cookieDomainSpecificity(right) - cookieDomainSpecificity(left) ||
+        right.path.length - left.path.length)[0];
+}
+async function solveInPage(page, challengeKind, pageUrl, allowedHosts, successCookieName, pollIntervalMs, gotoTimeoutMs, blockedRequests, signal) {
+    return await page.withResourcePolicy({
+        allowedMethods: ["GET", "HEAD", "POST"],
+        documentContentSecurityPolicy: RESOLVER_DOCUMENT_CONTENT_SECURITY_POLICY,
+        routes: [
+            {
+                match: () => true,
+                handle: (request) => {
+                    if (isResolverBrowserRequestAllowed(request.url, challengeKind, allowedHosts)) {
+                        return { action: "continue" };
+                    }
+                    blockedRequests.add(request.url);
+                    return { action: "block" };
+                },
+            },
+        ],
+    }, async () => {
+        const userAgent = await raceWithAbort(() => page.userAgent(), signal);
+        try {
+            await raceWithAbort(() => page.goto(pageUrl, {
+                timeout: gotoTimeoutMs,
+                waitUntil: "domcontentloaded",
+            }), signal);
+        }
+        catch (error) {
+            if (!isNavigationBlockedError(error))
+                throw error;
+            throw new BrowserNavigationBlockedError(pageUrl, [...blockedRequests], { cause: error });
+        }
+        while (true) {
+            const cookies = await raceWithAbort(() => page.cookies(), signal);
+            const successCookie = selectSuccessCookie(cookies, successCookieName, pageUrl);
+            if (successCookie) {
+                return {
+                    form: "cookies",
+                    cookies: { [successCookieName]: successCookie.value },
+                    userAgent,
+                    ...(successCookie.expires === undefined ? {} : { expires: successCookie.expires }),
+                };
+            }
+            await abortableDelay(pollIntervalMs, signal);
+        }
+    });
+}
+function isResolverBrowserRequestAllowed(targetUrl, challengeKind, allowedHosts) {
+    try {
+        assertResolverHostAllowed(targetUrl, allowedHosts);
+        return true;
+    }
+    catch {
+        if (challengeKind !== "aws_waf")
+            return false;
+    }
+    let target;
+    try {
+        target = new URL(targetUrl);
+    }
+    catch {
+        return false;
+    }
+    const hostname = normalizedResolverHostname(target.hostname);
+    return (target.protocol === "https:" &&
+        hostname.length > AWS_WAF_CHALLENGE_INFRASTRUCTURE_HOST_SUFFIX.length &&
+        hostname.endsWith(AWS_WAF_CHALLENGE_INFRASTRUCTURE_HOST_SUFFIX));
+}
+const POOL_ALLOCATION_EXHAUSTED_CODES = new Set([
+    -32_001, // queue full
+    -32_002, // acquire timed out
+    -32_003, // shutting down
+]);
+function poolErrorCode(error) {
+    const code = error.code;
+    return typeof code === "number" ? code : undefined;
+}
+function knownUnavailableReason(error, beforePageSolve = false) {
+    // Source-grounded mappings:
+    // - apps/cdp-pool/src/index.ts: the JSON-RPC codes and messages below.
+    // - src/runtime/browser.ts: BROWSER_CDP_POOL_REQUIRED and the two WebSocket messages.
+    // The pool's numeric JSON-RPC code is authoritative and is preferred whenever present.
+    // The message substrings remain as a fallback for pool builds predating code
+    // propagation; they are exact strings verified against the pool source. -32004 (unknown
+    // lease) and -32006 (missing allowedHosts) are deliberately unmapped: both are caller
+    // bugs, and the next vendor would fail identically, so they propagate unchanged.
+    if (isProviderError(error)) {
+        return error.code === "BROWSER_CDP_POOL_REQUIRED" ? "missing_credentials" : undefined;
+    }
+    if (!(error instanceof Error))
+        return undefined;
+    const code = poolErrorCode(error);
+    if (code !== undefined) {
+        return POOL_ALLOCATION_EXHAUSTED_CODES.has(code) ? "allocation_exhausted" : undefined;
+    }
+    if (error.message.includes("CDP pool acquire queue is full") ||
+        error.message.includes("CDP pool acquire timed out") ||
+        error.message.includes("CDP pool is shutting down")) {
+        return "allocation_exhausted";
+    }
+    if (error.message.includes("Unable to connect to WebSocket endpoint") ||
+        error.message.includes("WebSocket closed")) {
+        return "transport_failure";
+    }
+    // Browser creation, Playwright launch, and CDP connection all happen before the
+    // isolated-page handler is entered. Errors after that boundary belong to the
+    // challenge solve and must retain their existing classification.
+    return beforePageSolve ? "transport_failure" : undefined;
+}
+async function closeBrowserClient(client, timeoutMs, challengeKind, traceRecorder) {
+    const close = client?.close;
+    if (!close)
+        return;
+    await runBoundedCleanup(() => close.call(client), timeoutMs, challengeKind, "client.close", traceRecorder);
+}
+export function createBrowserResolverVendorAdapter(options) {
+    const createClient = options.createClient ?? createResolverBrowserClient;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_COOKIE_POLL_INTERVAL_MS;
+    return {
+        id: BROWSER_VENDOR_ID,
+        supports(kind) {
+            return isSupportedKind(kind);
+        },
+        getIssuingIdentity(solution, requestedIdentity, challenge) {
+            if (solution.form !== "cookies" || !isSupportedKind(challenge.kind))
+                return undefined;
+            return resolverChallengeIssuingIdentity(challenge, {
+                ...(requestedIdentity ? { proxyUrl: requestedIdentity.proxyUrl } : {}),
+                userAgent: solution.userAgent,
+            });
+        },
+        async solve(challenge, identity, callerSignal, traceRecorder) {
+            const cdpUrl = options.cdpUrl?.trim();
+            const proxyUrl = identity?.proxyUrl;
+            if (!cdpUrl && proxyUrl === undefined) {
+                throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "missing_credentials");
+            }
+            if (!isSupportedKind(challenge.kind)) {
+                throw new TypeError(`Browser resolver does not support ${challenge.kind}`);
+            }
+            assertResolverHostAllowed(challenge.pageUrl, options.allowedHosts);
+            const challengeKind = challenge.kind;
+            callerSignal.throwIfAborted();
+            if (proxyUrl !== undefined && proxyUrl.length === 0) {
+                throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "missing_proxy_identity");
+            }
+            if (cdpUrl && proxyUrl !== undefined) {
+                // The current pool acquire protocol cannot bind a proxy to its browser context.
+                // Refuse so the chain can choose a vendor that can honor the resolved identity.
+                throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "not_implemented");
+            }
+            const blockedRequests = new Set();
+            const solveController = new AbortController();
+            const onCallerAbort = () => solveController.abort(abortReason(callerSignal));
+            callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+            const timeout = setTimeout(() => solveController.abort(new BrowserSolveTimeoutError([...blockedRequests])), options.timeoutMs);
+            let client;
+            let handlerEntered = false;
+            try {
+                client = createClient({
+                    allowedHosts: [...options.allowedHosts],
+                    cdpUrl: cdpUrl ?? "",
+                    ...(proxyUrl === undefined ? {} : { proxy: proxyUrl }),
+                    requireCdpPool: cdpUrl !== undefined,
+                    serviceWorkers: "block",
+                });
+                const contextOperation = client.withIsolatedContext(async (page) => {
+                    handlerEntered = true;
+                    return await solveInPage(page, challengeKind, challenge.pageUrl, options.allowedHosts, SUCCESS_COOKIE_NAMES[challengeKind], pollIntervalMs, options.timeoutMs, blockedRequests, solveController.signal);
+                });
+                try {
+                    return await raceWithAbort(() => contextOperation, solveController.signal);
+                }
+                catch (error) {
+                    if (solveController.signal.aborted) {
+                        if (handlerEntered) {
+                            await runBoundedCleanup(() => contextOperation, options.timeoutMs, challengeKind, "context.close", traceRecorder);
+                            throw error;
+                        }
+                        await closeBrowserClient(client, options.timeoutMs, challengeKind, traceRecorder);
+                        void contextOperation.catch(() => undefined);
+                    }
+                    throw error;
+                }
+            }
+            catch (error) {
+                if (callerSignal.aborted)
+                    throw abortReason(callerSignal);
+                if (error instanceof BrowserSolveTimeoutError) {
+                    throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "timeout", {
+                        cause: error,
+                    });
+                }
+                if (error instanceof BrowserNavigationBlockedError) {
+                    throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "transport_failure", {
+                        cause: error,
+                    });
+                }
+                if (error instanceof ResolverVendorUnavailableError) {
+                    throw error;
+                }
+                const reason = knownUnavailableReason(error, !handlerEntered);
+                if (reason) {
+                    throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, reason, { cause: error });
+                }
+                throw error;
+            }
+            finally {
+                clearTimeout(timeout);
+                callerSignal.removeEventListener("abort", onCallerAbort);
+                await closeBrowserClient(client, options.timeoutMs, challengeKind, traceRecorder);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,22 @@
+import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
+import type { TraceRecorder } from "../trace.js";
+import { type ResolverIdentity, type ResolverVendorAdapter } from "./types.js";
+type Delay = (ms: number, signal: AbortSignal) => Promise<void>;
+export interface CapsolverResolverVendorOptions {
+    readonly apiKey?: string;
+    readonly timeoutMs?: number;
+    readonly pollIntervalMs?: number;
+    readonly allowedHosts: readonly string[];
+    readonly fetchImpl?: typeof fetch;
+    readonly baseUrl?: string;
+    /** Test-only clock override; supplying it disables the real-time deadline timer. */
+    readonly now?: () => number;
+    /** Test-only delay override used with `now` to exercise polling without sleeping. */
+    readonly delay?: Delay;
+}
+export interface CapsolverResolverVendorAdapter extends ResolverVendorAdapter {
+    readonly id: "capsolver";
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder): Promise<ChallengeSolution>;
+}
+export declare function createCapsolverResolverVendorAdapter(options: CapsolverResolverVendorOptions): CapsolverResolverVendorAdapter;
+export {};