@apifuse/provider-sdk 2.2.0-beta.62 → 2.2.0-beta.64

package/src/runtime/resolver-vendors/browser.ts

@@ -8,6 +8,7 @@ import type {
 } from "../../types.js";
 import { type BrowserClientOptions, createBrowserClient } from "../browser.js";
 import type { TraceRecorder } from "../trace.js";
+import type { BrowserTelemetrySink } from "../browser-telemetry.js";
 import { resolverChallengeIssuingIdentity } from "./bindings.js";
 import { assertResolverHostAllowed, normalizedResolverHostname } from "./hosts.js";
 import {
@@ -31,6 +32,59 @@ type SupportedBrowserChallengeKind = keyof typeof SUCCESS_COOKIE_NAMES;
 
 type BrowserClientFactory = (options: BrowserClientOptions) => BrowserClient;
 
+const RESOLVER_PAGE_METHODS = new Set([
+	"goto",
+	"evaluate",
+	"fill",
+	"click",
+	"type",
+	"waitForSelector",
+	"content",
+	"screenshot",
+	"cookies",
+	"url",
+	"title",
+	"userAgent",
+]);
+
+function instrumentResolverBrowser(client: BrowserClient, recorder: TraceRecorder): BrowserClient {
+	const wrapPage = (page: BrowserPage): BrowserPage =>
+		new Proxy(page, {
+			get(target, property, receiver) {
+				const value = Reflect.get(target, property, receiver);
+				if (
+					typeof property !== "string" ||
+					!RESOLVER_PAGE_METHODS.has(property) ||
+					typeof value !== "function"
+				)
+					return value;
+				return (...args: unknown[]) =>
+					recorder.runSpan(`browser.page.${property}`, () => Reflect.apply(value, target, args));
+			},
+		});
+	return new Proxy(client, {
+		get(target, property, receiver) {
+			const value = Reflect.get(target, property, receiver);
+			if (property === "newPage" && typeof value === "function")
+				return () =>
+					recorder.runSpan("browser.newPage", async () =>
+						wrapPage(await Reflect.apply(value, target, [])),
+					);
+			if (property === "rawPage" && typeof value === "function")
+				return () =>
+					recorder.runSpan("browser.rawPage", async () =>
+						wrapPage(await Reflect.apply(value, target, [])),
+					);
+			if (property === "withIsolatedContext" && typeof value === "function")
+				return (handler: (page: BrowserPage) => Promise<unknown>) =>
+					recorder.runSpan("browser.withIsolatedContext", () =>
+						Reflect.apply(value, target, [(page: BrowserPage) => handler(wrapPage(page))]),
+					);
+			return value;
+		},
+	});
+}
+
 let createResolverBrowserClient: BrowserClientFactory = createBrowserClient;
 
 /** Internal test seam; deliberately not re-exported from the package root. */
@@ -53,6 +107,7 @@ export interface BrowserResolverVendorOptions {
 	readonly pollIntervalMs?: number;
 	readonly allowedHosts: readonly string[];
 	readonly createClient?: BrowserClientFactory;
+	readonly telemetry?: BrowserTelemetrySink;
 }
 
 export interface BrowserResolverVendorAdapter extends ResolverVendorAdapter {
@@ -67,9 +122,7 @@ export interface BrowserResolverVendorAdapter extends ResolverVendorAdapter {
 
 class BrowserSolveTimeoutError extends Error {
 	constructor(blockedRequests: readonly string[]) {
-		super(
-			`Browser resolver solve budget elapsed${formatBlockedRequests(blockedRequests)}`,
-		);
+		super(`Browser resolver solve budget elapsed${formatBlockedRequests(blockedRequests)}`);
 		this.name = "BrowserSolveTimeoutError";
 	}
 }
@@ -274,10 +327,7 @@ async function solveInPage(
 			],
 		},
 		async () => {
-			const userAgent = await raceWithAbort(
-				() => page.userAgent(),
-				signal,
-			);
+			const userAgent = await raceWithAbort(() => page.userAgent(), signal);
 			try {
 				await raceWithAbort(
 					() =>
@@ -467,7 +517,15 @@ export function createBrowserResolverVendorAdapter(
 					...(proxyUrl === undefined ? {} : { proxy: proxyUrl }),
 					requireCdpPool: cdpUrl !== undefined,
 					serviceWorkers: "block",
+					telemetry: options.telemetry,
 				});
+				/**
+				 * Direct vendor callers without a telemetry sink keep the historical trace shape.
+				 * Bound server requests record browser page spans under resolver.vendor.attempt,
+				 * with resolver.vendor.cleanup as a sibling of the browser context span.
+				 */
+				if (traceRecorder && options.telemetry)
+					client = instrumentResolverBrowser(client, traceRecorder);
 				const contextOperation = client.withIsolatedContext(async (page) => {
 					handlerEntered = true;
 					return await solveInPage(

package/src/runtime/resolver-vendors/hosts.ts

@@ -1,4 +1,25 @@
 import { ProviderError } from "../../errors.js";
+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 const RESOLVER_VENDOR_TRANSPORT_HOSTS = Object.freeze({
+	"2captcha": Object.freeze([] as const),
+	browser: Object.freeze([] as const),
+	capmonster: Object.freeze([] as const),
+	capsolver: Object.freeze([] as const),
+	custom: Object.freeze([] as const),
+	hypersolutions: Object.freeze(["ip.hypersolutions.co"] as const),
+}) satisfies Readonly<Record<ProviderResolverVendor, readonly string[]>>;
 
 export function normalizedResolverHostname(hostname: string): string {
 	return hostname.trim().toLowerCase().replace(/\.$/, "");
@@ -36,3 +57,25 @@ export function assertResolverHostAllowed(
 		fix: "Add the exact target hostname to the provider's allowedHosts declaration.",
 	});
 }
+
+export function assertResolverVendorTransportHosts(
+	vendor: ProviderResolverVendor,
+	declaredHosts: readonly string[],
+): void {
+	// 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: readonly string[] = 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/src/runtime/resolver-vendors/hypersolutions.ts

@@ -3,7 +3,7 @@ import { isIP } from "node:net";
 import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
 import { recordPaidResolverCreate } from "../resolver-usage.js";
 import type { TraceRecorder } from "../trace.js";
-import { assertResolverHostAllowed } from "./hosts.js";
+import { assertResolverHostAllowed, RESOLVER_VENDOR_TRANSPORT_HOSTS } from "./hosts.js";
 import {
 	ResolverChallengeVerdictError,
 	type ResolverIdentity,
@@ -21,7 +21,7 @@ const HYPER_IP_URL = "https://ip.hypersolutions.co/ip";
  * egress address the upstream will see. The payload-generation POST carries no
  * identity and goes direct, as in the measured zozotown source.
  */
-const HYPER_TRANSPORT_HOSTS = ["ip.hypersolutions.co"] as const;
+const HYPER_TRANSPORT_HOSTS = RESOLVER_VENDOR_TRANSPORT_HOSTS.hypersolutions;
 const IP_RESPONSE_MAX_BYTES = 4_096;
 /** Measured bound shared by the script, the Hyper envelope, and the payload submission. */
 const BODY_MAX_BYTES = 1_000_000;

package/src/runtime/resolver-vendors/types.ts

@@ -157,10 +157,11 @@ export interface ResolverVendorAdapter {
 	readonly id: ProviderResolverVendor;
 	readonly requiresTransport?: boolean | ((kind: ProviderChallengeKind) => boolean);
 	/**
-	 * Exact SDK-owned service hosts this adapter may reach through its bound transport.
-	 * Honored for every adapter the chain runs, so whoever supplies `adapters` to
-	 * `createResolverClient` is the trust boundary; the engine path
-	 * (`createResolverClientFromEnv`) only constructs registry adapters.
+	 * Exact SDK-owned service hosts this adapter may reach through its bound transport,
+	 * in addition to the provider's `allowedHosts`. Every host must appear in the
+	 * SDK-owned `RESOLVER_VENDOR_TRANSPORT_HOSTS` entry for `id`; the chain rejects any
+	 * other declaration with `RESOLVER_VENDOR_HOST_NOT_ALLOWED`, whoever supplied the
+	 * adapter. The transport handed to `solve` is revoked once `solve` settles.
 	 */
 	readonly transportAllowedHosts?: readonly string[];
 	supports(kind: ProviderChallengeKind): boolean;

package/src/runtime/resolver.ts

@@ -29,7 +29,10 @@ import {
 import { createBrowserResolverVendorAdapter } from "./resolver-vendors/browser.js";
 import { createCapsolverResolverVendorAdapter } from "./resolver-vendors/capsolver.js";
 import { createHypersolutionsResolverVendorAdapter } from "./resolver-vendors/hypersolutions.js";
-import { assertResolverHostAllowed } from "./resolver-vendors/hosts.js";
+import {
+	assertResolverHostAllowed,
+	assertResolverVendorTransportHosts,
+} from "./resolver-vendors/hosts.js";
 import { createTwoCaptchaResolverVendorAdapter } from "./resolver-vendors/twocaptcha.js";
 import {
 	RESOLVER_VENDOR_CAPABILITIES,
@@ -63,6 +66,7 @@ import {
 } from "./resolver-config.js";
 import { DEFAULT_STEALTH_PROFILE } from "./stealth.js";
 import type { TraceRecorder } from "./trace.js";
+import type { BrowserTelemetrySink } from "./browser-telemetry.js";
 import type {
 	ResolverTelemetryErrorClass,
 	ResolverTelemetryPhase,
@@ -127,6 +131,8 @@ export interface ResolverRuntimeOptions {
 	readonly cache?: ProviderCache;
 	/** Optional request-scoped observability sink; never used as resolver identity. */
 	readonly telemetry?: ResolverTelemetrySink;
+	/** Request-scoped browser sink used by the resolver-owned browser vendor. */
+	readonly browserTelemetry?: BrowserTelemetrySink;
 	/** Inputs for SDK-owned lazy proxy resolution. The SDK never accepts a caller-built identity. */
 	readonly proxyIntent?: {
 		readonly mode: ProviderProxyMode;
@@ -222,6 +228,7 @@ export type ResolverAdapterFactory = (
 	configuration: string | undefined,
 	timeoutMs: number,
 	allowedHosts: readonly string[],
+	telemetry?: BrowserTelemetrySink,
 ) => ResolverVendorAdapter;
 
 const resolverAdapterRegistry: Partial<Record<ProviderResolverVendor, ResolverAdapterFactory>> = {
@@ -242,11 +249,12 @@ const resolverAdapterRegistry: Partial<Record<ProviderResolverVendor, ResolverAd
 			timeoutMs,
 		});
 	},
-	browser(configuration, timeoutMs, allowedHosts) {
+	browser(configuration, timeoutMs, allowedHosts, telemetry) {
 		return createBrowserResolverVendorAdapter({
 			allowedHosts,
 			cdpUrl: configuration,
 			timeoutMs,
+			telemetry,
 		});
 	},
 	hypersolutions(configuration, timeoutMs, allowedHosts) {
@@ -306,7 +314,7 @@ const KNOWN_UNIMPLEMENTED_RESOLVER_VENDORS: ReadonlySet<ProviderResolverVendor>
 type ResolverChainEntry = {
 	readonly id: ProviderResolverVendor;
 	supports(kind: ProviderChallengeKind): boolean;
-	createAdapter(): ResolverVendorAdapter;
+	createAdapter(browserTelemetry?: BrowserTelemetrySink): ResolverVendorAdapter;
 };
 
 function normalizedEnvValue(env: EnvLike, key: string): string | undefined {
@@ -365,6 +373,7 @@ function createAdapter(
 	timeoutMs: number,
 	allowedHosts: readonly string[],
 	adapterFactories: Partial<Readonly<Record<ProviderResolverVendor, ResolverAdapterFactory>>>,
+	browserTelemetry?: BrowserTelemetrySink,
 ): ResolverVendorAdapter {
 	const factory = adapterFactories[vendor.vendor];
 	if (!factory && !KNOWN_UNIMPLEMENTED_RESOLVER_VENDORS.has(vendor.vendor)) {
@@ -377,7 +386,7 @@ function createAdapter(
 	}
 
 	if (factory) {
-		return factory(vendor.configuration, timeoutMs, allowedHosts);
+		return factory(vendor.configuration, timeoutMs, allowedHosts, browserTelemetry);
 	}
 	return createUnavailableAdapter(vendor.vendor, "not_implemented");
 }
@@ -480,15 +489,26 @@ function sanitizeCauseMessage(message: string): string {
 		.slice(0, 512);
 }
 
+function assertResolverTransportLive(revoked: boolean): void {
+	if (!revoked) return;
+	throw new ProviderError("Resolver transport was revoked when the vendor solve settled", {
+		code: "RESOLVER_TRANSPORT_REVOKED",
+		fix: "Complete every bound-transport call before solve() settles; the transport is per-attempt and must not be retained.",
+	});
+}
+
 function restrictResolverTransport(
 	transport: ResolverVendorTransport,
 	allowedHosts: readonly string[],
-): ResolverVendorTransport {
-	return {
+): { readonly transport: ResolverVendorTransport; revoke(): void } {
+	// A retained reference must fail closed once the adapter's solve has settled.
+	let revoked = false;
+	const restricted: ResolverVendorTransport = {
 		sessionHeaders: transport.sessionHeaders,
 		...(transport.getCookie
 			? {
 					getCookie(name, url) {
+						assertResolverTransportLive(revoked);
 						// Jar reads are gated like fetches: an adapter may only read state for declared hosts.
 						assertResolverHostAllowed(url, allowedHosts);
 						return transport.getCookie?.(name, url);
@@ -496,6 +516,7 @@ function restrictResolverTransport(
 				}
 			: {}),
 		async fetch(url, init) {
+			assertResolverTransportLive(revoked);
 			// Empty declarations remain deny-by-default, matching the adapter-factory/browser path.
 			assertResolverHostAllowed(url, allowedHosts);
 			const response = await transport.fetch(url, { ...init, redirect: "manual" });
@@ -511,6 +532,12 @@ function restrictResolverTransport(
 			return response;
 		},
 	};
+	return {
+		transport: restricted,
+		revoke() {
+			revoked = true;
+		},
+	};
 }
 
 function safeCause(error: ResolverVendorUnavailableError): ResolverChainAttempt["cause"] {
@@ -1042,7 +1069,8 @@ async function resolveResolverIdentity(
 }
 
 function createChainTelemetryBinding(options: Parameters<typeof createResolverChainClient>[0]) {
-	return (telemetry: ResolverTelemetrySink) => createResolverChainClient({ ...options, telemetry });
+	return (telemetry: ResolverTelemetrySink, browserTelemetry?: BrowserTelemetrySink) =>
+		createResolverChainClient({ ...options, telemetry, browserTelemetry });
 }
 
 function createResolverChainClient(options: {
@@ -1059,6 +1087,7 @@ function createResolverChainClient(options: {
 	readonly clientProfile?: string;
 	readonly allowedHosts?: readonly string[];
 	readonly telemetry?: ResolverTelemetrySink;
+	readonly browserTelemetry?: BrowserTelemetrySink;
 }): ResolverChainClient {
 	assertClientProfileTransportContract(options.clientProfile, options.transport);
 	const cache =
@@ -1167,7 +1196,7 @@ function createResolverChainClient(options: {
 				}
 				const attempts: ResolverChainAttempt[] = [];
 				for (const [entryIndex, entry] of supportingEntries.entries()) {
-					const adapter = entry.createAdapter();
+					const adapter = entry.createAdapter(options.browserTelemetry);
 					const attemptStartedAt = Date.now();
 					const diagnostics: ResolverAttemptDiagnostics = {};
 					const telemetryTraceRecorder = createResolverTelemetryTraceRecorder({
@@ -1179,7 +1208,11 @@ function createResolverChainClient(options: {
 					});
 					let solution: ChallengeSolution;
 					try {
-						const solveAttempt = () => {
+						const solveAttempt = async () => {
+							// Boundary first: an overreaching declaration is a caller fault even when no
+							// transport is configured, not a "missing_transport" vendor unavailability.
+							const adapterHosts = adapter.transportAllowedHosts ?? [];
+							assertResolverVendorTransportHosts(adapter.id, adapterHosts);
 							const requiresTransport = adapterRequiresTransport(adapter, challenge.kind);
 							const unrestrictedTransport =
 								options.transport ??
@@ -1192,10 +1225,10 @@ function createResolverChainClient(options: {
 							if (requiresTransport && unrestrictedTransport === undefined) {
 								throw new ResolverVendorUnavailableError(adapter.id, "missing_transport");
 							}
-							const transport = unrestrictedTransport
+							const boundTransport = unrestrictedTransport
 								? restrictResolverTransport(unrestrictedTransport, [
 										...(options.allowedHosts ?? []),
-										...(adapter.transportAllowedHosts ?? []),
+										...adapterHosts,
 									])
 								: undefined;
 							const usage: ResolverPaidUsageContext = {
@@ -1209,14 +1242,18 @@ function createResolverChainClient(options: {
 										}
 									: {}),
 							};
-							return adapter.solve(
-								challenge,
-								identity,
-								signal,
-								telemetryTraceRecorder,
-								transport,
-								usage,
-							);
+							try {
+								return await adapter.solve(
+									challenge,
+									identity,
+									signal,
+									telemetryTraceRecorder,
+									boundTransport?.transport,
+									usage,
+								);
+							} finally {
+								boundTransport?.revoke();
+							}
 						};
 						solution = traceRecorder
 							? await traceRecorder.runSpan("resolver.vendor.attempt", solveAttempt, {
@@ -1334,7 +1371,7 @@ function createResolverChainClient(options: {
 		},
 	};
 	resolverCaches.set(client, cache ?? null);
-	const reusableOptions = { ...options, telemetry: undefined };
+	const reusableOptions = { ...options, telemetry: undefined, browserTelemetry: undefined };
 	registerResolverTelemetryBinding(client, createChainTelemetryBinding(reusableOptions));
 	return client;
 }
@@ -1352,6 +1389,10 @@ export function createResolverClient(options: {
 	readonly allowedHosts?: readonly string[];
 	readonly telemetry?: ResolverTelemetrySink;
 }): ResolverChainClient {
+	for (const adapter of options.adapters) {
+		// Fail at construction, not on the first solve, when a supplied adapter oversteps its vendor.
+		assertResolverVendorTransportHosts(adapter.id, adapter.transportAllowedHosts ?? []);
+	}
 	return createResolverChainClient({
 		kinds: options.kinds,
 		entries: options.adapters.map((adapter) => ({
@@ -1459,12 +1500,13 @@ function createResolverClientFromEnvInternal(
 			return {
 				id: vendor,
 				supports: (kind: ProviderChallengeKind) => resolverVendorSupports(vendor, kind),
-				createAdapter: () =>
+				createAdapter: (browserTelemetry) =>
 					createAdapter(
 						resolveVendorAvailability(vendor, env),
 						timeoutMs,
 						allowedHosts,
 						adapterFactories,
+						browserTelemetry,
 					),
 			};
 		}),
@@ -1477,6 +1519,7 @@ function createResolverClientFromEnvInternal(
 		clientProfile: config.clientProfile,
 		allowedHosts,
 		telemetry: options.telemetry,
+		browserTelemetry: options.browserTelemetry,
 	});
 }