@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

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

@@ -0,0 +1,544 @@
+import { getStealthProfile } from "../../stealth/profiles.js";
+import { redactSensitiveText } from "../request-options.js";
+import { DEFAULT_STEALTH_PROFILE } from "../stealth.js";
+import { recordPaidResolverCreate } from "../resolver-usage.js";
+import { resolverSpanAttributes } from "../resolver-span-attributes.js";
+import { assertResolverHostAllowed } from "./hosts.js";
+import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, recordResolverVendorPoll, resolverVendorSupports, } from "./types.js";
+const CAPSOLVER_VENDOR_ID = "capsolver";
+const DEFAULT_CAPSOLVER_BASE_URL = "https://api.capsolver.com";
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_TIMEOUT_MS = 120_000;
+const SDK_ESTIMATED_COOKIE_TTL_MS_BY_CHALLENGE_KIND = {
+    // CapSolver omits expiry, so use one conservative hour despite measured
+    // AWS WAF lifetimes of days.
+    aws_waf: 60 * 60 * 1_000,
+};
+class CapsolverSolveTimeoutError extends Error {
+    constructor() {
+        super("Capsolver resolver solve budget elapsed");
+        this.name = "CapsolverSolveTimeoutError";
+    }
+}
+class CapsolverUnavailableError extends ResolverVendorUnavailableError {
+    errorCode;
+    errorDescription;
+    responseStatus;
+    responseContentType;
+    responseLength;
+    constructor(reason, options) {
+        super(CAPSOLVER_VENDOR_ID, reason, options);
+        this.errorCode = options.errorCode;
+        this.errorDescription = options.errorDescription;
+        this.responseStatus = options.responseStatus;
+        this.responseContentType = options.responseContentType;
+        this.responseLength = options.responseLength;
+    }
+}
+class CapsolverVerdictError extends ResolverChallengeVerdictError {
+    phase;
+    errorCode;
+    errorDescription;
+    constructor(options) {
+        super(CAPSOLVER_VENDOR_ID, "solve_failed", options);
+        this.phase = options.phase;
+        this.errorCode = options.errorCode;
+        this.errorDescription = options.errorDescription;
+    }
+}
+function isJsonRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function abortReason(signal) {
+    return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+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 sanitizedJsonParseCause() {
+    return new SyntaxError("Upstream response failed");
+}
+function raceWithAbort(operation, signal, phase, sensitiveValues = []) {
+    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();
+            if (phase === undefined) {
+                reject(error);
+                return;
+            }
+            reject(new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+                ...safeCauseOptions(error, sensitiveValues),
+                phase,
+            }));
+        });
+    });
+}
+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 responseErrorFields(payload) {
+    return {
+        errorId: typeof payload.errorId === "number" ? payload.errorId : undefined,
+        errorCode: typeof payload.errorCode === "string" ? payload.errorCode : undefined,
+        errorDescription: typeof payload.errorDescription === "string" ? payload.errorDescription : undefined,
+    };
+}
+function parseCreateTaskResponse(payload) {
+    const taskId = payload.taskId;
+    return {
+        ...responseErrorFields(payload),
+        taskId: typeof taskId === "string" || typeof taskId === "number" ? taskId : undefined,
+    };
+}
+function parsePollResultResponse(payload) {
+    const solution = isJsonRecord(payload.solution) ? payload.solution : undefined;
+    const cookies = solution && isJsonRecord(solution.cookies)
+        ? Object.fromEntries(Object.entries(solution.cookies).filter((entry) => typeof entry[1] === "string"))
+        : undefined;
+    return {
+        ...responseErrorFields(payload),
+        status: typeof payload.status === "string" ? payload.status : undefined,
+        solution: solution
+            ? {
+                token: typeof solution.token === "string" ? solution.token : undefined,
+                cookie: typeof solution.cookie === "string" ? solution.cookie : undefined,
+                gRecaptchaResponse: typeof solution.gRecaptchaResponse === "string"
+                    ? solution.gRecaptchaResponse
+                    : undefined,
+                cookies,
+                userAgent: typeof solution.userAgent === "string" ? solution.userAgent : undefined,
+            }
+            : undefined,
+    };
+}
+function proxyForCapsolver(proxyUrl) {
+    try {
+        const url = new URL(proxyUrl);
+        const protocol = url.protocol.slice(0, -1).toLowerCase();
+        const scheme = protocol === "http" || protocol === "socks5" ? protocol : undefined;
+        const port = Number(url.port || (scheme === "socks5" ? 1080 : 80));
+        if (!scheme || !url.hostname || !Number.isInteger(port) || port <= 0 || port > 65_535) {
+            return undefined;
+        }
+        const username = url.username ? decodeURIComponent(url.username) : "";
+        const password = url.password ? decodeURIComponent(url.password) : "";
+        if (username.includes(":") || password.includes(":"))
+            return undefined;
+        const value = `${scheme}:${url.hostname}:${port}${username || password ? `:${username}:${password}` : ""}`;
+        return { value, sensitive: [proxyUrl, value, username, password].filter(Boolean) };
+    }
+    catch {
+        return undefined;
+    }
+}
+function isAllocationExhausted(payload) {
+    const code = payload.errorCode?.toLowerCase() ?? "";
+    const description = payload.errorDescription?.toLowerCase() ?? "";
+    return (code === "error_zero_balance" ||
+        /(?:insufficient|zero|no|not enough)\s+(?:balance|funds|credit)/u.test(`${code} ${description}`));
+}
+function isNegativeVerdict(payload) {
+    return payload.errorCode?.toLowerCase() === "error_captcha_unsolvable";
+}
+function safeVendorDetail(value, sensitiveValues) {
+    const redacted = redactSensitiveText(value, sensitiveValues);
+    return containsSensitiveValue(redacted, sensitiveValues) ? "[REDACTED]" : redacted;
+}
+function vendorErrorDetails(payload, sensitiveValues) {
+    const errorCode = payload.errorCode?.trim();
+    const errorDescription = payload.errorDescription?.trim();
+    return {
+        ...(errorCode ? { errorCode: safeVendorDetail(errorCode, sensitiveValues) } : {}),
+        ...(errorDescription
+            ? { errorDescription: safeVendorDetail(payload.errorDescription ?? "", sensitiveValues) }
+            : {}),
+    };
+}
+function unavailableForPayload(payload, phase, sensitiveValues) {
+    const details = vendorErrorDetails(payload, sensitiveValues);
+    if (isNegativeVerdict(payload)) {
+        return new CapsolverVerdictError({ phase, ...details });
+    }
+    return new CapsolverUnavailableError(isAllocationExhausted(payload) ? "allocation_exhausted" : "transport_failure", { phase, ...details });
+}
+async function postJson(fetchImpl, url, body, signal, phase, sensitiveValues, parseResponse) {
+    const response = await raceWithAbort(() => fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal,
+        redirect: "error",
+    }), signal, phase, sensitiveValues);
+    let responseText;
+    try {
+        responseText = await raceWithAbort(() => response.text(), signal, phase, sensitiveValues);
+    }
+    catch (error) {
+        if (error instanceof ResolverVendorUnavailableError)
+            throw error;
+        throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+            cause: error,
+            phase,
+        });
+    }
+    let payload;
+    try {
+        payload = JSON.parse(responseText);
+    }
+    catch {
+        const contentType = response.headers.get("content-type");
+        throw new CapsolverUnavailableError("transport_failure", {
+            cause: sanitizedJsonParseCause(),
+            phase,
+            responseStatus: response.status,
+            responseContentType: contentType
+                ? safeVendorDetail(contentType.slice(0, 128), sensitiveValues)
+                : undefined,
+            responseLength: responseText.length,
+        });
+    }
+    if (!isJsonRecord(payload)) {
+        throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+            phase,
+        });
+    }
+    return { ok: response.ok, payload: parseResponse(payload) };
+}
+function endpoint(baseUrl, path) {
+    return `${baseUrl.replace(/\/+$/u, "")}/${path}`;
+}
+function spanErrorAttributes(error, phase) {
+    if (error instanceof ResolverVendorUnavailableError) {
+        return resolverSpanAttributes({
+            unavailability_reason: error.reason,
+            transport_phase: error.phase,
+            ...(error instanceof CapsolverUnavailableError
+                ? {
+                    vendor_error_code: error.errorCode,
+                    vendor_error_description: error.errorDescription,
+                    response_status: error.responseStatus,
+                    response_content_type: error.responseContentType,
+                    response_length: error.responseLength,
+                }
+                : {}),
+        });
+    }
+    if (error instanceof CapsolverVerdictError) {
+        return resolverSpanAttributes({
+            verdict_reason: error.reason,
+            transport_phase: error.phase,
+            vendor_error_code: error.errorCode,
+            vendor_error_description: error.errorDescription,
+        });
+    }
+    if (error instanceof CapsolverSolveTimeoutError) {
+        return resolverSpanAttributes({
+            unavailability_reason: "timeout",
+            transport_phase: phase,
+        });
+    }
+    return undefined;
+}
+export function createCapsolverResolverVendorAdapter(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const baseUrl = options.baseUrl ?? DEFAULT_CAPSOLVER_BASE_URL;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const now = options.now ?? Date.now;
+    const delay = options.delay ?? abortableDelay;
+    return {
+        id: CAPSOLVER_VENDOR_ID,
+        supports(kind) {
+            return resolverVendorSupports(CAPSOLVER_VENDOR_ID, kind);
+        },
+        async solve(challenge, identity, callerSignal, traceRecorder, _transport, usage) {
+            const apiKey = options.apiKey?.trim();
+            if (!apiKey) {
+                throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "missing_credentials", {
+                    phase: "create_task",
+                });
+            }
+            if (!resolverVendorSupports(CAPSOLVER_VENDOR_ID, challenge.kind)) {
+                throw new TypeError(`Capsolver resolver does not support ${challenge.kind}`);
+            }
+            const proxy = identity ? proxyForCapsolver(identity.proxyUrl) : undefined;
+            if (challenge.kind === "cloudflare_interstitial" && !identity) {
+                throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "missing_proxy_identity", {
+                    phase: "create_task",
+                });
+            }
+            if (challenge.kind !== "aws_waf" && identity && !proxy) {
+                throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+                    phase: "create_task",
+                });
+            }
+            const challengeFields = challenge;
+            const sensitiveValues = [
+                apiKey,
+                challenge.pageUrl,
+                ...(typeof challengeFields.siteKey === "string" ? [challengeFields.siteKey] : []),
+                ...(typeof challengeFields.action === "string" ? [challengeFields.action] : []),
+                ...(typeof challengeFields.cdata === "string" ? [challengeFields.cdata] : []),
+                ...(typeof challengeFields.blockedHtml === "string" ? [challengeFields.blockedHtml] : []),
+                ...(typeof challengeFields.captchaScript === "string" ? [challengeFields.captchaScript] : []),
+                ...(typeof challengeFields.context === "string" ? [challengeFields.context] : []),
+                ...(typeof challengeFields.iv === "string" ? [challengeFields.iv] : []),
+                ...(proxy?.sensitive ?? []),
+            ];
+            assertResolverHostAllowed(challenge.pageUrl, options.allowedHosts);
+            callerSignal.throwIfAborted();
+            const solveController = new AbortController();
+            const onCallerAbort = () => solveController.abort(abortReason(callerSignal));
+            callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+            const timeout = options.now
+                ? undefined
+                : setTimeout(() => solveController.abort(new CapsolverSolveTimeoutError()), timeoutMs);
+            const startedAt = now();
+            let phase = "create_task";
+            try {
+                const createTask = async () => {
+                    // AWS WAF tokens are portable (ADR 0006 lease A→B), so minting can use solver
+                    // egress independently of the redemption proxy. Passing the caller proxy makes
+                    // allowlisted allocators such as Smartproxy reject solver workers with
+                    // "custom proxy connect failed" (production measurement, 2026-09-02).
+                    const task = challenge.kind === "aws_waf"
+                        ? {
+                            type: "AntiAwsWafTaskProxyLess",
+                            websiteURL: challenge.pageUrl,
+                            ...(challenge.siteKey !== undefined ? { awsKey: challenge.siteKey } : {}),
+                            ...(challenge.iv !== undefined ? { awsIv: challenge.iv } : {}),
+                            ...(challenge.context !== undefined ? { awsContext: challenge.context } : {}),
+                            ...(challenge.captchaScript !== undefined
+                                ? { awsChallengeJS: challenge.captchaScript }
+                                : {}),
+                            ...(identity?.userAgent ? { userAgent: identity.userAgent } : {}),
+                        }
+                        : challenge.kind === "turnstile"
+                            ? {
+                                type: "AntiTurnstileTaskProxyLess",
+                                websiteURL: challenge.pageUrl,
+                                websiteKey: challenge.siteKey,
+                                ...(challenge.action !== undefined || challenge.cdata !== undefined
+                                    ? {
+                                        metadata: {
+                                            ...(challenge.action !== undefined ? { action: challenge.action } : {}),
+                                            ...(challenge.cdata !== undefined ? { cdata: challenge.cdata } : {}),
+                                        },
+                                    }
+                                    : {}),
+                            }
+                            : challenge.kind === "recaptcha_v2"
+                                ? {
+                                    type: proxy ? "ReCaptchaV2Task" : "ReCaptchaV2TaskProxyLess",
+                                    websiteURL: challenge.pageUrl,
+                                    websiteKey: challenge.siteKey,
+                                    ...(proxy ? { proxy: proxy.value } : {}),
+                                }
+                                : challenge.kind === "recaptcha_v3"
+                                    ? {
+                                        type: proxy ? "ReCaptchaV3Task" : "ReCaptchaV3TaskProxyLess",
+                                        websiteURL: challenge.pageUrl,
+                                        websiteKey: challenge.siteKey,
+                                        pageAction: challenge.action,
+                                        ...(challenge.minScore !== undefined ? { minScore: challenge.minScore } : {}),
+                                        ...(proxy ? { proxy: proxy.value } : {}),
+                                    }
+                                    : challenge.kind === "hcaptcha"
+                                        ? {
+                                            type: proxy ? "HCaptchaTask" : "HCaptchaTaskProxyLess",
+                                            websiteURL: challenge.pageUrl,
+                                            websiteKey: challenge.siteKey,
+                                            ...(proxy ? { proxy: proxy.value } : {}),
+                                        }
+                                        : challenge.kind === "cloudflare_interstitial"
+                                            ? {
+                                                type: "AntiCloudflareTask",
+                                                websiteURL: challenge.pageUrl,
+                                                proxy: proxy?.value,
+                                                ...(identity?.userAgent ? { userAgent: identity.userAgent } : {}),
+                                                ...(challenge.kind === "cloudflare_interstitial" && challenge.blockedHtml !== undefined
+                                                    ? { html: challenge.blockedHtml }
+                                                    : {}),
+                                            }
+                                            : (() => {
+                                                throw new TypeError(`Capsolver resolver does not support ${challenge.kind}`);
+                                            })();
+                    return await recordPaidResolverCreate({
+                        traceRecorder,
+                        vendor: CAPSOLVER_VENDOR_ID,
+                        kind: challenge.kind,
+                        endpoint: "capsolver:create_task",
+                        signal: solveController.signal,
+                        usage,
+                        create: async () => {
+                            const createResult = await postJson(fetchImpl, endpoint(baseUrl, "createTask"), { clientKey: apiKey, task }, solveController.signal, phase, sensitiveValues, parseCreateTaskResponse);
+                            const taskId = createResult.payload.taskId;
+                            if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
+                                throw unavailableForPayload(createResult.payload, phase, sensitiveValues);
+                            }
+                            return taskId;
+                        },
+                    });
+                };
+                const taskId = traceRecorder
+                    ? await traceRecorder.runSpan("resolver.vendor.create_task", createTask, {
+                        attributes: resolverSpanAttributes({
+                            vendor: CAPSOLVER_VENDOR_ID,
+                            challenge_kind: challenge.kind,
+                        }),
+                        onError: (error) => spanErrorAttributes(error, "create_task"),
+                    })
+                    : await createTask();
+                phase = "poll_result";
+                const pollResult = async () => {
+                    while (true) {
+                        callerSignal.throwIfAborted();
+                        const remainingMs = timeoutMs - (now() - startedAt);
+                        if (remainingMs <= 0)
+                            throw new CapsolverSolveTimeoutError();
+                        await delay(Math.min(pollIntervalMs, remainingMs), solveController.signal);
+                        callerSignal.throwIfAborted();
+                        if (now() - startedAt >= timeoutMs)
+                            throw new CapsolverSolveTimeoutError();
+                        recordResolverVendorPoll(traceRecorder);
+                        const result = await postJson(fetchImpl, endpoint(baseUrl, "getTaskResult"), { clientKey: apiKey, taskId }, solveController.signal, phase, sensitiveValues, parsePollResultResponse);
+                        if (!result.ok || result.payload.errorId !== 0) {
+                            throw unavailableForPayload(result.payload, phase, sensitiveValues);
+                        }
+                        switch (result.payload.status) {
+                            case "idle":
+                            case "processing":
+                                continue;
+                            case "ready":
+                                break;
+                            default:
+                                throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+                                    phase,
+                                });
+                        }
+                        const solutionValue = challenge.kind === "aws_waf"
+                            ? result.payload.solution?.cookie
+                            : (result.payload.solution?.token ?? result.payload.solution?.gRecaptchaResponse);
+                        if (challenge.kind === "cloudflare_interstitial") {
+                            const cookies = result.payload.solution?.cookies;
+                            const clearance = cookies?.cf_clearance ?? solutionValue;
+                            if (!clearance?.trim()) {
+                                throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+                                    phase,
+                                });
+                            }
+                            return {
+                                form: "cookies",
+                                cookies: cookies && Object.keys(cookies).length > 0 ? cookies : { cf_clearance: clearance },
+                                userAgent: result.payload.solution?.userAgent ??
+                                    identity?.userAgent ??
+                                    getStealthProfile(DEFAULT_STEALTH_PROFILE).userAgent,
+                            };
+                        }
+                        if (!solutionValue?.trim()) {
+                            throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+                                phase,
+                            });
+                        }
+                        return challenge.kind === "aws_waf"
+                            ? {
+                                form: "cookies",
+                                cookies: { "aws-waf-token": solutionValue },
+                                userAgent: identity?.userAgent ?? getStealthProfile(DEFAULT_STEALTH_PROFILE).userAgent,
+                                sdkEstimatedExpires: (now() + SDK_ESTIMATED_COOKIE_TTL_MS_BY_CHALLENGE_KIND.aws_waf) / 1_000,
+                            }
+                            : { form: "token", token: solutionValue };
+                    }
+                };
+                return traceRecorder
+                    ? await traceRecorder.runSpan("resolver.vendor.poll_result", pollResult, {
+                        attributes: resolverSpanAttributes({
+                            vendor: CAPSOLVER_VENDOR_ID,
+                            challenge_kind: challenge.kind,
+                        }),
+                        onError: (error) => spanErrorAttributes(error, "poll_result"),
+                    })
+                    : await pollResult();
+            }
+            catch (error) {
+                if (callerSignal.aborted)
+                    throw abortReason(callerSignal);
+                if (error instanceof CapsolverSolveTimeoutError ||
+                    solveController.signal.reason instanceof CapsolverSolveTimeoutError) {
+                    throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "timeout", {
+                        cause: error,
+                        phase,
+                    });
+                }
+                if (error instanceof ResolverVendorUnavailableError ||
+                    error instanceof ResolverChallengeVerdictError) {
+                    throw error;
+                }
+                throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+                    ...safeCauseOptions(error, sensitiveValues),
+                    phase,
+                });
+            }
+            finally {
+                if (timeout !== undefined)
+                    clearTimeout(timeout);
+                callerSignal.removeEventListener("abort", onCallerAbort);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,23 @@
+import type { ProviderResolverVendor } from "../../types.js";
+/**
+ * Exact SDK-owned service hosts each vendor's adapter may reach through its bound
+ * transport, in addition to the provider's declared `allowedHosts`. This table is
+ * the trust boundary for `ResolverVendorAdapter.transportAllowedHosts`: a
+ * declaration outside its vendor's entry is rejected, whoever supplied the adapter.
+ * Only Hyper's observed-IP reflector rides the identity-bound transport (ADR-0008
+ * v1.1 amend, PR #251); every other vendor talks to its own service directly.
+ * Frozen at runtime, not just in the type: the Hyper adapter hands its entry out by
+ * reference as `transportAllowedHosts`, so a mutable table would let any holder of a
+ * registry adapter widen the boundary for every later adapter in the process.
+ */
+export declare const RESOLVER_VENDOR_TRANSPORT_HOSTS: Readonly<{
+    "2captcha": readonly [];
+    browser: readonly [];
+    capmonster: readonly [];
+    capsolver: readonly [];
+    custom: readonly [];
+    hypersolutions: readonly ["ip.hypersolutions.co"];
+}>;
+export declare function normalizedResolverHostname(hostname: string): string;
+export declare function assertResolverHostAllowed(targetUrl: string, allowedHosts: readonly string[]): void;
+export declare function assertResolverVendorTransportHosts(vendor: ProviderResolverVendor, declaredHosts: readonly string[]): void;

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

@@ -0,0 +1,68 @@
+import { ProviderError } from "../../errors.js";
+/**
+ * Exact SDK-owned service hosts each vendor's adapter may reach through its bound
+ * transport, in addition to the provider's declared `allowedHosts`. This table is
+ * the trust boundary for `ResolverVendorAdapter.transportAllowedHosts`: a
+ * declaration outside its vendor's entry is rejected, whoever supplied the adapter.
+ * Only Hyper's observed-IP reflector rides the identity-bound transport (ADR-0008
+ * v1.1 amend, PR #251); every other vendor talks to its own service directly.
+ * Frozen at runtime, not just in the type: the Hyper adapter hands its entry out by
+ * reference as `transportAllowedHosts`, so a mutable table would let any holder of a
+ * registry adapter widen the boundary for every later adapter in the process.
+ */
+export const RESOLVER_VENDOR_TRANSPORT_HOSTS = Object.freeze({
+    "2captcha": Object.freeze([]),
+    browser: Object.freeze([]),
+    capmonster: Object.freeze([]),
+    capsolver: Object.freeze([]),
+    custom: Object.freeze([]),
+    hypersolutions: Object.freeze(["ip.hypersolutions.co"]),
+});
+export function normalizedResolverHostname(hostname) {
+    return hostname.trim().toLowerCase().replace(/\.$/, "");
+}
+export function assertResolverHostAllowed(targetUrl, allowedHosts) {
+    let targetUrlObject;
+    try {
+        targetUrlObject = new URL(targetUrl);
+    }
+    catch {
+        throw new ProviderError("Resolver target URL is invalid", {
+            code: "RESOLVER_HOST_NOT_ALLOWED",
+            fix: "Use a valid URL whose exact hostname appears in the provider's allowedHosts declaration.",
+        });
+    }
+    if (targetUrlObject.protocol !== "http:" && targetUrlObject.protocol !== "https:") {
+        throw new ProviderError(`Resolver target URL scheme "${targetUrlObject.protocol}" is not allowed`, {
+            code: "RESOLVER_HOST_NOT_ALLOWED",
+            fix: "Use an http or https URL whose exact hostname appears in the provider's allowedHosts declaration.",
+        });
+    }
+    const targetHost = normalizedResolverHostname(targetUrlObject.hostname);
+    const isAllowed = allowedHosts.some((host) => {
+        const declaredHost = normalizedResolverHostname(host);
+        return declaredHost.length > 0 && !declaredHost.includes("*") && declaredHost === targetHost;
+    });
+    if (isAllowed)
+        return;
+    throw new ProviderError(`Resolver target host "${targetHost}" is not declared`, {
+        code: "RESOLVER_HOST_NOT_ALLOWED",
+        fix: "Add the exact target hostname to the provider's allowedHosts declaration.",
+    });
+}
+export function assertResolverVendorTransportHosts(vendor, declaredHosts) {
+    // A vendor id outside the table (only reachable from untyped callers) owns no hosts and
+    // is rejected below like any other overreach; `hasOwn` keeps prototype keys out too.
+    const ownedHosts = Object.hasOwn(RESOLVER_VENDOR_TRANSPORT_HOSTS, vendor)
+        ? RESOLVER_VENDOR_TRANSPORT_HOSTS[vendor]
+        : [];
+    for (const declaredHost of declaredHosts) {
+        const normalizedHost = normalizedResolverHostname(declaredHost);
+        if (ownedHosts.some((host) => normalizedResolverHostname(host) === normalizedHost))
+            continue;
+        throw new ProviderError(`Resolver vendor "${vendor}" may not declare transport host "${normalizedHost}"`, {
+            code: "RESOLVER_VENDOR_HOST_NOT_ALLOWED",
+            fix: "Remove the host from transportAllowedHosts: an adapter reaches only the provider's allowedHosts plus the SDK-owned service hosts of its vendor.",
+        });
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
+import type { TraceRecorder } from "../trace.js";
+import { type ResolverIdentity, type ResolverPaidUsageContext, type ResolverVendorAdapter, type ResolverVendorTransport } from "./types.js";
+/**
+ * Only the observed-IP reflector rides the bound transport: Hyper must see the
+ * egress address the upstream will see. The payload-generation POST carries no
+ * identity and goes direct, as in the measured zozotown source.
+ */
+declare const HYPER_TRANSPORT_HOSTS: readonly ["ip.hypersolutions.co"];
+export interface HypersolutionsResolverVendorOptions {
+    readonly apiKey?: string;
+    readonly timeoutMs?: number;
+    readonly allowedHosts: readonly string[];
+    /** Direct egress used only for the Hyper payload-generation POST. */
+    readonly fetchImpl?: typeof fetch;
+}
+export type AkamaiSbsdChallengeSolution = Extract<ChallengeSolution, {
+    readonly form: "cookie_state";
+}>;
+export interface HypersolutionsResolverVendorAdapter extends ResolverVendorAdapter {
+    readonly id: "hypersolutions";
+    readonly requiresTransport: true;
+    readonly transportAllowedHosts: typeof HYPER_TRANSPORT_HOSTS;
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder, transport?: ResolverVendorTransport, usage?: ResolverPaidUsageContext): Promise<AkamaiSbsdChallengeSolution>;
+}
+export declare function createHypersolutionsResolverVendorAdapter(options: HypersolutionsResolverVendorOptions): HypersolutionsResolverVendorAdapter;
+export {};