@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.51

package/dist/runtime/resolver.js

@@ -0,0 +1,771 @@
+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 { createCapsolverResolverVendorAdapter } from "./resolver-vendors/capsolver.js";
+import { assertResolverHostAllowed } from "./resolver-vendors/hosts.js";
+import { createTwoCaptchaResolverVendorAdapter } from "./resolver-vendors/twocaptcha.js";
+import { RESOLVER_VENDOR_CAPABILITIES, ResolverVendorUnavailableError, resolveProviderResolverVendors, 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_STEALTH_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";
+export { DEFAULT_RESOLVER_VENDOR_PREFERENCE, resolveProviderResolverVendors, } from "./resolver-vendors/types.js";
+const RESOLVER_SOLUTION_CACHE_NAMESPACE = "resolver-solution";
+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 resolverSolutionSources = 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",
+]);
+const resolverAdapterRegistry = {
+    "2captcha"(configuration, timeoutMs, allowedHosts) {
+        if (configuration === undefined) {
+            throw new Error("2captcha resolver adapter factory requires an API key");
+        }
+        return createTwoCaptchaResolverVendorAdapter({
+            allowedHosts,
+            apiKey: configuration,
+            timeoutMs,
+        });
+    },
+    capsolver(configuration, timeoutMs, allowedHosts) {
+        return createCapsolverResolverVendorAdapter({
+            allowedHosts,
+            apiKey: configuration,
+            timeoutMs,
+        });
+    },
+    browser(configuration, timeoutMs, allowedHosts) {
+        return createBrowserResolverVendorAdapter({
+            allowedHosts,
+            cdpUrl: configuration,
+            timeoutMs,
+        });
+    },
+};
+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;
+    };
+}
+let resolveDefaultResolverUserAgent = () => getStealthProfile(DEFAULT_STEALTH_PROFILE).userAgent;
+/** Internal test seam; deliberately not re-exported from the package root. */
+export function swapResolverDefaultUserAgentForTests(resolver) {
+    const original = resolveDefaultResolverUserAgent;
+    resolveDefaultResolverUserAgent =
+        resolver ?? (() => getStealthProfile(DEFAULT_STEALTH_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([
+    "capmonster",
+    "custom",
+]);
+function normalizedEnvValue(env, key) {
+    const value = env[key]?.trim();
+    return value ? value : undefined;
+}
+function readPositiveIntegerEnv(env, name) {
+    const raw = env[name]?.trim();
+    if (!raw)
+        return undefined;
+    if (!/^[1-9]\d*$/.test(raw)) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return raw;
+}
+function assertDeclaredKind(requestedKind, declaredKinds) {
+    if (declaredKinds.includes(requestedKind))
+        return;
+    const declared = declaredKinds.length > 0 ? declaredKinds.join(", ") : "none";
+    throw new ProviderError(`Resolver kind "${requestedKind}" is not declared; declared kinds: ${declared}`, {
+        code: "RESOLVER_KIND_NOT_DECLARED",
+        fix: `Add "${requestedKind}" to the provider's resolver.kinds declaration.`,
+    });
+}
+function createUnavailableAdapter(vendor, reason) {
+    return {
+        id: vendor,
+        supports(kind) {
+            return resolverVendorSupports(vendor, kind);
+        },
+        async solve() {
+            throw new ResolverVendorUnavailableError(vendor, reason);
+        },
+    };
+}
+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}"`);
+    }
+    if (!vendor.available) {
+        return createUnavailableAdapter(vendor.vendor, vendor.reason);
+    }
+    if (factory) {
+        return factory(vendor.configuration, timeoutMs, allowedHosts);
+    }
+    return createUnavailableAdapter(vendor.vendor, "not_implemented");
+}
+function assertKnownResolverVendor(vendor) {
+    if (Object.hasOwn(RESOLVER_VENDOR_CAPABILITIES, vendor))
+        return;
+    throw new Error(`Unknown resolver vendor "${vendor}" in resolver configuration`);
+}
+function throwUnsupportedKind(kind, usingDefaultVendors) {
+    throw new ProviderError(`Resolver vendor chain does not support kind "${kind}"`, {
+        code: "RESOLVER_KIND_UNSUPPORTED_BY_CHAIN",
+        fix: usingDefaultVendors
+            ? `No SDK default resolver vendor supports "${kind}". Declare an explicit resolver.vendors override with a supporting vendor.`
+            : `Add a resolver vendor that supports "${kind}" to the provider's resolver.vendors declaration.`,
+    });
+}
+function throwExhausted(attempts) {
+    const hasMissingChallengeInput = attempts.some((attempt) => attempt.reason === "missing_challenge_input");
+    const summary = attempts
+        .map(({ vendor, reason, missingFields }) => missingFields === undefined || missingFields.length === 0
+        ? `${vendor}: ${reason}`
+        : `${vendor}: ${reason} (missing fields: ${missingFields.join(", ")})`)
+        .join(", ");
+    throw new ProviderError(`Resolver vendor chain exhausted: ${summary}`, {
+        code: "RESOLVER_CHAIN_EXHAUSTED",
+        fix: hasMissingChallengeInput
+            ? "Capture the named challenge fields or configure another supporting resolver vendor."
+            : "Configure another supporting resolver vendor or restore an unavailable vendor.",
+        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);
+        if (parsed.username || parsed.password)
+            return "[REDACTED_PROXY_URL]";
+        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]" ||
+            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 &&
+            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,
+        ...(error.missingFields ? { missingFields: [...error.missingFields] } : {}),
+        ...(cause ? { cause } : {}),
+        ...(upstreamHost ? { upstreamHost } : {}),
+        ...(phase ? { phase } : {}),
+        ...(round !== undefined ? { round } : {}),
+    };
+}
+function unavailableSpanAttributes(error) {
+    const attempt = unavailableAttempt(error);
+    return {
+        unavailability_reason: error.reason,
+        missing_fields: error.missingFields,
+        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;
+}
+function resolverIdentityDigest(identity) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        proxyUrl: identity.proxyUrl ?? null,
+        userAgent: identity.userAgent,
+    }))
+        .digest("hex");
+}
+function resolverIdentityScopeDigest(identityScope) {
+    return createHash("sha256").update(JSON.stringify({ identityScope })).digest("hex");
+}
+function resolverSolutionCacheKey(cache, challenge, issuerDigest) {
+    return cache.key(RESOLVER_SOLUTION_CACHE_NAMESPACE, {
+        kind: challenge.kind,
+        origin: challengeOrigin(challenge),
+        issuerDigest,
+    });
+}
+function resolverSolutionIndexCacheKey(cache, challenge) {
+    return cache.key(RESOLVER_SOLUTION_INDEX_CACHE_NAMESPACE, {
+        kind: challenge.kind,
+        origin: challengeOrigin(challenge),
+    });
+}
+function isCachedResolverSolution(value) {
+    try {
+        if (value === null || typeof value !== "object")
+            return false;
+        const candidate = value;
+        if (typeof candidate.expiresAtMs !== "number" ||
+            typeof candidate.issuerDigest !== "string" ||
+            candidate.solution === null ||
+            typeof candidate.solution !== "object" ||
+            candidate.solution.form !== "cookies" ||
+            typeof candidate.solution.userAgent !== "string") {
+            return false;
+        }
+        const cookies = candidate.solution.cookies;
+        return (cookies !== null &&
+            typeof cookies === "object" &&
+            !Array.isArray(cookies) &&
+            Object.values(cookies).every((cookie) => typeof cookie === "string"));
+    }
+    catch {
+        return false;
+    }
+}
+function isResolverCacheIndex(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const entries = value.entries;
+    return (Array.isArray(entries) &&
+        entries.every((entry) => entry !== null &&
+            typeof entry === "object" &&
+            entry.direct === true &&
+            typeof entry.expiresAtMs === "number" &&
+            typeof entry.issuerDigest === "string"));
+}
+function solutionExpiryMs(solution) {
+    if (solution.form !== "cookies")
+        return undefined;
+    const expires = solution.expires ?? solution.sdkEstimatedExpires;
+    if (typeof expires !== "number" || !Number.isFinite(expires))
+        return undefined;
+    return expires * 1_000;
+}
+function rememberSolutionIssuer(solution, issuerDigest) {
+    if (typeof solution === "object" && solution !== null) {
+        solutionIssuerDigests.set(solution, issuerDigest);
+    }
+}
+function rememberSolutionSource(solution, source) {
+    if (typeof solution === "object" && solution !== null) {
+        resolverSolutionSources.set(solution, source);
+    }
+}
+/**
+ * Identify whether this exact SDK-returned solution object came from the cache
+ * or a vendor solve. Returns undefined for copied or caller-created objects.
+ */
+export function getResolverSolutionSource(solution) {
+    return resolverSolutionSources.get(solution);
+}
+async function readCachedSolution(cache, challenge, issuerDigest, now) {
+    const cached = await cache.get(resolverSolutionCacheKey(cache, challenge, issuerDigest));
+    if (!cached || !isCachedResolverSolution(cached.value))
+        return undefined;
+    if (cached.value.issuerDigest !== issuerDigest || cached.value.expiresAtMs <= now)
+        return undefined;
+    if (cached.value.solution.form !== "cookies")
+        return undefined;
+    const solution = {
+        ...cached.value.solution,
+        cookies: { ...cached.value.solution.cookies },
+    };
+    rememberSolutionIssuer(solution, issuerDigest);
+    rememberSolutionSource(solution, "cache");
+    return solution;
+}
+async function findCachedSolution(cache, challenge, identity, identityScope) {
+    const now = Date.now();
+    if (identityScope !== undefined && resolverChallengeIsIdentityScoped(challenge)) {
+        return await readCachedSolution(cache, challenge, resolverIdentityScopeDigest(identityScope), now);
+    }
+    if (identity) {
+        const lookupIdentity = resolverChallengeIssuingIdentity(challenge, identity);
+        return await readCachedSolution(cache, challenge, resolverIdentityDigest(lookupIdentity), now);
+    }
+    const index = await cache.get(resolverSolutionIndexCacheKey(cache, challenge));
+    if (!index || !isResolverCacheIndex(index.value))
+        return undefined;
+    for (const entry of index.value.entries) {
+        if (entry.expiresAtMs <= now)
+            continue;
+        const solution = await readCachedSolution(cache, challenge, entry.issuerDigest, now);
+        if (solution)
+            return solution;
+    }
+    return undefined;
+}
+async function writeResolverCacheIndex(cache, challenge, entries, now) {
+    const indexKey = resolverSolutionIndexCacheKey(cache, challenge);
+    const liveEntries = entries.filter((entry) => entry.expiresAtMs > now);
+    if (liveEntries.length === 0) {
+        await cache.delete(indexKey);
+        return;
+    }
+    const ttlMs = Math.max(1, Math.floor(Math.max(...liveEntries.map((entry) => entry.expiresAtMs)) - now));
+    await cache.set(indexKey, { entries: liveEntries }, { ttlMs });
+}
+async function cacheResolverSolution(cache, challenge, solution, identity, identityScope) {
+    if (!resolverChallengeIsCacheable(challenge))
+        return;
+    const expiresAtMs = solutionExpiryMs(solution);
+    const now = Date.now();
+    if (expiresAtMs === undefined)
+        return;
+    const ttlMs = Math.floor(expiresAtMs - now);
+    if (ttlMs <= MIN_RESOLVER_CACHE_TTL_MS)
+        return;
+    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);
+    if (scopedDigest !== undefined || identity.proxyUrl !== undefined)
+        return;
+    const indexKey = resolverSolutionIndexCacheKey(cache, challenge);
+    const current = await cache.get(indexKey);
+    const currentEntries = isResolverCacheIndex(current?.value) ? current.value.entries : [];
+    await writeResolverCacheIndex(cache, challenge, [
+        ...currentEntries.filter((entry) => entry.issuerDigest !== issuerDigest),
+        { direct: true, expiresAtMs, issuerDigest },
+    ], now);
+}
+async function invalidateResolverSolutionWithOutcome(resolver, challenge, solution) {
+    const metadata = resolver[RESOLVER_INSTRUMENTATION_METADATA];
+    const cacheOwner = metadata?.target ?? resolver;
+    const invalidate = async () => {
+        if (solution.form !== "cookies")
+            return "not_cookie_solution";
+        if (!resolverCaches.has(cacheOwner)) {
+            throw new Error("Resolver cache registration lookup failed during solution invalidation");
+        }
+        const cache = resolverCaches.get(cacheOwner);
+        if (cache === null || cache === undefined)
+            return "cache_disabled";
+        const issuerDigest = solutionIssuerDigests.get(solution);
+        if (!issuerDigest)
+            return "solution_not_cached";
+        await cache.delete(resolverSolutionCacheKey(cache, challenge, issuerDigest));
+        const index = await cache.get(resolverSolutionIndexCacheKey(cache, challenge));
+        if (!index)
+            return "entry_deleted";
+        if (!isResolverCacheIndex(index.value)) {
+            throw new Error("Resolver solution cache index is malformed during invalidation");
+        }
+        await writeResolverCacheIndex(cache, challenge, index.value.entries.filter((entry) => entry.issuerDigest !== issuerDigest), Date.now());
+        return "index_entry_deleted";
+    };
+    if (!metadata) {
+        return await invalidate();
+    }
+    return await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
+        attributes: { challenge_kind: challenge.kind },
+        onSuccess: (outcome) => ({ outcome }),
+    });
+}
+/** Remove the cached entry for the exact solution object returned by this resolver. */
+export async function invalidateResolverSolution(resolver, challenge, solution) {
+    await invalidateResolverSolutionWithOutcome(resolver, challenge, solution);
+}
+/**
+ * Remove a solution only when it was returned from the resolver cache. Providers
+ * should call this when an upstream serves the same challenge after a cached
+ * solution was applied, so the next `solve()` mints a fresh solution.
+ */
+export async function invalidateCachedResolverSolution(resolver, challenge, solution) {
+    if (getResolverSolutionSource(solution) !== "cache")
+        return false;
+    const outcome = await invalidateResolverSolutionWithOutcome(resolver, challenge, solution);
+    return outcome === "entry_deleted" || outcome === "index_entry_deleted";
+}
+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 = {
+        async solve(challenge, signal = new AbortController().signal, traceRecorder) {
+            assertDeclaredKind(challenge.kind, options.kinds);
+            if (options.unavailableReason) {
+                throw new ProviderError(options.unavailableReason, {
+                    code: "RESOLVER_UNAVAILABLE",
+                    fix: "Configure at least one declared resolver vendor or provide a test ResolverContext override.",
+                });
+            }
+            const supportingEntries = options.entries.filter((entry) => entry.supports(challenge.kind));
+            if (supportingEntries.length === 0) {
+                throwUnsupportedKind(challenge.kind, options.usingDefaultVendors ?? false);
+            }
+            signal.throwIfAborted();
+            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: identityResolution.unavailableReason ?? "missing_proxy_identity",
+                })));
+            }
+            if (options.cache && resolverChallengeIsCacheable(challenge)) {
+                const cached = await findCachedSolution(options.cache, challenge, identity, options.identityScope);
+                if (cached)
+                    return cached;
+            }
+            const attempts = [];
+            for (const entry of supportingEntries) {
+                const adapter = entry.createAdapter();
+                try {
+                    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, 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,
+                                resolver_identity_source: identityResolution.userAgentSource,
+                            },
+                            onError(error) {
+                                return error instanceof ResolverVendorUnavailableError
+                                    ? unavailableSpanAttributes(error)
+                                    : undefined;
+                            },
+                        })
+                        : await solveAttempt();
+                    if (options.cache &&
+                        resolverChallengeIsCacheable(challenge) &&
+                        solution.form === "cookies" &&
+                        solutionExpiryMs(solution) !== undefined) {
+                        const issuingIdentity = adapter.getIssuingIdentity?.(solution, identity, challenge) ??
+                            resolverChallengeIssuingIdentity(challenge, {
+                                ...(identity ? { proxyUrl: identity.proxyUrl } : {}),
+                                userAgent: solution.userAgent,
+                            });
+                        if (issuingIdentity) {
+                            await cacheResolverSolution(options.cache, challenge, solution, issuingIdentity, options.identityScope);
+                        }
+                    }
+                    rememberSolutionSource(solution, "vendor");
+                    return solution;
+                }
+                catch (error) {
+                    signal.throwIfAborted();
+                    if (!(error instanceof ResolverVendorUnavailableError))
+                        throw error;
+                    // Every vendor-unavailable result, including missing_challenge_input, falls
+                    // through so another adapter can solve with a different input contract.
+                    attempts.push(unavailableAttempt(error));
+                }
+            }
+            throwExhausted(attempts);
+        },
+    };
+    resolverCaches.set(client, options.cache ?? null);
+    return client;
+}
+export function createResolverClient(options) {
+    return createResolverChainClient({
+        kinds: options.kinds,
+        entries: options.adapters.map((adapter) => ({
+            id: adapter.id,
+            supports: (kind) => adapter.supports(kind),
+            createAdapter: () => adapter,
+        })),
+        unavailableReason: options.unavailableReason,
+        cache: options.cache,
+        identity: options.identity,
+        proxyIntent: options.proxyIntent,
+        transport: options.transport,
+        createTransport: options.createTransport,
+        clientProfile: options.clientProfile,
+        allowedHosts: options.allowedHosts,
+    });
+}
+function resolveVendorAvailability(vendor, env) {
+    if (vendor === "custom") {
+        return {
+            vendor,
+            available: false,
+            reason: "missing_transport",
+        };
+    }
+    if (vendor === "browser") {
+        return {
+            vendor,
+            available: true,
+            configuration: normalizedEnvValue(env, APIFUSE__CDP_POOL__URL),
+        };
+    }
+    const envKey = vendor === "2captcha"
+        ? APIFUSE__RESOLVER__2CAPTCHA__API_KEY
+        : vendor === "capsolver"
+            ? APIFUSE__RESOLVER__CAPSOLVER__API_KEY
+            : APIFUSE__RESOLVER__CAPMONSTER__API_KEY;
+    const configuration = normalizedEnvValue(env, envKey);
+    return configuration
+        ? { vendor, available: true, configuration }
+        : { vendor, available: false, reason: "missing_credentials" };
+}
+export function bindResolverSignal(resolver, defaultSignal) {
+    if (!defaultSignal)
+        return resolver;
+    const boundResolver = {
+        solve(challenge, signal = defaultSignal, traceRecorder) {
+            return resolver.solve(challenge, signal, traceRecorder);
+        },
+    };
+    if (resolverCaches.has(resolver)) {
+        resolverCaches.set(boundResolver, resolverCaches.get(resolver) ?? null);
+    }
+    return boundResolver;
+}
+function createResolverClientFromEnvInternal(config, env, options, adapterFactories) {
+    if (!config) {
+        return createUnsupportedResolverClient("Provider does not declare resolver capability");
+    }
+    assertClientProfileTransportContract(config.clientProfile, options.transport);
+    const vendors = resolveProviderResolverVendors(config);
+    if (config.vendors !== undefined && config.vendors.length === 0) {
+        return createResolverChainClient({
+            kinds: config.kinds,
+            entries: [],
+            unavailableReason: "Provider resolver vendor chain is empty",
+        });
+    }
+    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: vendors.map((configuredVendor) => {
+            assertKnownResolverVendor(configuredVendor);
+            const vendor = configuredVendor;
+            return {
+                id: vendor,
+                supports: (kind) => resolverVendorSupports(vendor, kind),
+                createAdapter: () => createAdapter(resolveVendorAvailability(vendor, env), timeoutMs, allowedHosts, adapterFactories),
+            };
+        }),
+        usingDefaultVendors: config.vendors === undefined,
+        cache: options.cache,
+        proxyIntent: options.proxyIntent,
+        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);
+}