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

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

@@ -0,0 +1,81 @@
+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(/\.$/, "");
+}
+
+export function assertResolverHostAllowed(
+	targetUrl: string,
+	allowedHosts: readonly string[],
+): void {
+	let targetUrlObject: URL;
+	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: 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

@@ -0,0 +1,480 @@
+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, RESOLVER_VENDOR_TRANSPORT_HOSTS } from "./hosts.js";
+import {
+	ResolverChallengeVerdictError,
+	type ResolverIdentity,
+	type ResolverPaidUsageContext,
+	type ResolverVendorAdapter,
+	type ResolverVendorTransport,
+	ResolverVendorUnavailableError,
+} from "./types.js";
+
+const HYPERSOLUTIONS_VENDOR_ID = "hypersolutions" as const;
+const HYPER_SBSD_URL = "https://akm.hypersolutions.co/sbsd";
+const HYPER_IP_URL = "https://ip.hypersolutions.co/ip";
+/**
+ * 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.
+ */
+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;
+
+type HyperPhase = "measure_ip" | "fetch_script" | "generate_payload" | "post_payload";
+
+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>;
+}
+
+type TransportResponse = Awaited<ReturnType<ResolverVendorTransport["fetch"]>>;
+
+function headerValue(headers: Readonly<Record<string, string>>, name: string): string | undefined {
+	const target = name.toLowerCase();
+	return Object.entries(headers)
+		.find(([header]) => header.toLowerCase() === target)?.[1]
+		?.trim();
+}
+
+function declaredLengthExceeds(declared: string | undefined, maxBytes: number): boolean {
+	return declared !== undefined && /^\d+$/u.test(declared) && BigInt(declared) > BigInt(maxBytes);
+}
+
+function transportFailure(phase: HyperPhase, cause?: unknown): ResolverVendorUnavailableError {
+	return new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "transport_failure", {
+		phase,
+		...(cause === undefined ? {} : { cause }),
+	});
+}
+
+function assertBoundedBody(response: TransportResponse, maxBytes: number, phase: HyperPhase): void {
+	if (
+		declaredLengthExceeds(headerValue(response.headers, "content-length"), maxBytes) ||
+		new TextEncoder().encode(response.body).byteLength > maxBytes
+	) {
+		throw transportFailure(phase);
+	}
+}
+
+function requireSuccess(status: number, phase: HyperPhase): void {
+	if (status >= 200 && status < 300) return;
+	if (phase === "measure_ip" || phase === "generate_payload") {
+		// Hyper's own service: a rejected key is a credential fault, anything else is transport.
+		throw new ResolverVendorUnavailableError(
+			HYPERSOLUTIONS_VENDOR_ID,
+			status === 401 || status === 403 ? "missing_credentials" : "transport_failure",
+			{ phase },
+		);
+	}
+	// The upstream refused the script GET or the payload POST: that is the challenge verdict.
+	throw new ResolverChallengeVerdictError(HYPERSOLUTIONS_VENDOR_ID, "solve_failed", { phase });
+}
+
+function parseObservedIp(body: string): string | undefined {
+	let value: unknown = body.trim();
+	try {
+		value = JSON.parse(body);
+	} catch {
+		// Hyper's reflector has returned both JSON and plain text in measured clients.
+	}
+	if (value && typeof value === "object" && !Array.isArray(value) && "ip" in value) {
+		value = value.ip;
+	}
+	if (typeof value !== "string") return undefined;
+	const candidate = value.trim();
+	return isIP(candidate) ? candidate : undefined;
+}
+
+function parsePayload(body: string): string | undefined {
+	try {
+		const parsed: unknown = JSON.parse(body);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !("payload" in parsed)) {
+			return undefined;
+		}
+		return typeof parsed.payload === "string" && parsed.payload.length > 0
+			? parsed.payload
+			: undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function scriptExchangeUrls(
+	scriptUrl: string,
+	laterChallengeToken: string | undefined,
+): {
+	readonly fetchUrl: string;
+	readonly postUrl: string;
+	readonly uuid: string;
+	readonly indices: readonly number[];
+} {
+	// `?v=&t=` is the hard SBSD variant and `?v=` is passive SBSD. A no-query
+	// Akamai script is a sensor-family artifact and stays outside this adapter.
+	const parsed = new URL(scriptUrl);
+	const uuid = parsed.searchParams.get("v")?.trim();
+	if (!uuid) {
+		throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "missing_challenge_input", {
+			missingFields: ["scriptUrl"],
+			phase: "fetch_script",
+		});
+	}
+	const scriptToken = parsed.searchParams.get("t")?.trim();
+	const laterToken = laterChallengeToken?.trim();
+	if (scriptToken && laterToken) {
+		throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "missing_challenge_input", {
+			missingFields: ["challengeToken"],
+			phase: "fetch_script",
+		});
+	}
+	// Clone the validated URL and only replace its query: reparsing `pathname`
+	// against `origin` would read a `//host/...` pathname as a network-path
+	// reference and swap the host that assertChallengeInput just admitted.
+	const fetchUrl = new URL(parsed);
+	fetchUrl.search = "";
+	fetchUrl.hash = "";
+	fetchUrl.searchParams.set("v", uuid);
+	if (scriptToken) fetchUrl.searchParams.set("t", scriptToken);
+	const postUrl = new URL(fetchUrl);
+	postUrl.search = "";
+	const postToken = laterToken || scriptToken;
+	if (postToken) postUrl.searchParams.set("t", postToken);
+	return {
+		fetchUrl: fetchUrl.toString(),
+		postUrl: postUrl.toString(),
+		uuid,
+		indices: postToken ? [0] : [0, 1],
+	};
+}
+
+function assertChallengeInput(
+	challenge: Extract<ProviderChallenge, { readonly kind: "akamai_sbsd" }>,
+	allowedHosts: readonly string[],
+): void {
+	const missingFields = [
+		...(challenge.pageUrl.trim() ? [] : ["pageUrl"]),
+		...(challenge.scriptUrl.trim() ? [] : ["scriptUrl"]),
+		...(challenge.stateCookieName === "sbsd_o" || challenge.stateCookieName === "bm_so"
+			? []
+			: ["stateCookieName"]),
+		...(challenge.challengeToken === undefined || challenge.challengeToken.trim()
+			? []
+			: ["challengeToken"]),
+	];
+	if (missingFields.length > 0) {
+		throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "missing_challenge_input", {
+			missingFields,
+		});
+	}
+	assertResolverHostAllowed(challenge.pageUrl, allowedHosts);
+	assertResolverHostAllowed(challenge.scriptUrl, allowedHosts);
+	if (new URL(challenge.pageUrl).origin !== new URL(challenge.scriptUrl).origin) {
+		// The state cookie is read for pageUrl and posted to scriptUrl; they must share an origin.
+		throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "missing_challenge_input", {
+			missingFields: ["scriptUrl"],
+		});
+	}
+}
+
+async function boundFetch(
+	transport: ResolverVendorTransport,
+	url: string,
+	init: Parameters<ResolverVendorTransport["fetch"]>[1],
+	phase: HyperPhase,
+): Promise<TransportResponse> {
+	try {
+		return await transport.fetch(url, init);
+	} catch (cause) {
+		if (
+			cause instanceof ResolverVendorUnavailableError ||
+			cause instanceof ResolverChallengeVerdictError
+		) {
+			throw cause;
+		}
+		// An abort is the caller's (or the adapter timeout's) verdict, not a transport fault.
+		if (init.signal.aborted) throw init.signal.reason ?? cause;
+		throw transportFailure(phase, cause);
+	}
+}
+
+async function readBoundedText(response: Response, maxBytes: number): Promise<string | undefined> {
+	if (declaredLengthExceeds(response.headers.get("content-length")?.trim(), maxBytes)) {
+		await response.body?.cancel();
+		return undefined;
+	}
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let received = 0;
+	let text = "";
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		received += value.byteLength;
+		if (received > maxBytes) {
+			await reader.cancel();
+			return undefined;
+		}
+		text += decoder.decode(value, { stream: true });
+	}
+	return text + decoder.decode();
+}
+
+async function generatePayload(
+	fetchImpl: typeof fetch,
+	apiKey: string,
+	body: string,
+	signal: AbortSignal,
+): Promise<{ readonly status: number; readonly body: string | undefined }> {
+	try {
+		const response = await fetchImpl(HYPER_SBSD_URL, {
+			method: "POST",
+			headers: {
+				accept: "application/json",
+				"content-type": "application/json",
+				"x-api-key": apiKey,
+			},
+			body,
+			signal,
+			redirect: "error",
+		});
+		// A body that fails mid-read is as much a transport fault as a refused connection.
+		return { status: response.status, body: await readBoundedText(response, BODY_MAX_BYTES) };
+	} catch (cause) {
+		if (signal.aborted) throw signal.reason ?? cause;
+		throw transportFailure("generate_payload", cause);
+	}
+}
+
+export function createHypersolutionsResolverVendorAdapter(
+	options: HypersolutionsResolverVendorOptions,
+): HypersolutionsResolverVendorAdapter {
+	const apiKey = options.apiKey?.trim();
+	const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+	return {
+		id: HYPERSOLUTIONS_VENDOR_ID,
+		requiresTransport: true,
+		transportAllowedHosts: HYPER_TRANSPORT_HOSTS,
+		supports: (kind) => kind === "akamai_sbsd",
+		async solve(challenge, _identity, signal, traceRecorder, transport, usage) {
+			const timeoutController = new AbortController();
+			const operationSignal = options.timeoutMs
+				? AbortSignal.any([signal, timeoutController.signal])
+				: signal;
+			const timeout = options.timeoutMs
+				? setTimeout(
+						// A named reason lets the usage span record `timeout`, not a caller abort.
+						() => timeoutController.abort(new DOMException("Hyper solve timed out", "TimeoutError")),
+						options.timeoutMs,
+					)
+				: undefined;
+			const runPhase = <T>(phase: HyperPhase, fn: () => Promise<T>): Promise<T> =>
+				traceRecorder ? traceRecorder.runSpan(`resolver.vendor.${phase}`, fn) : fn();
+			try {
+				if (challenge.kind !== "akamai_sbsd") {
+					throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "not_implemented");
+				}
+				if (!apiKey) {
+					throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "missing_credentials");
+				}
+				if (!transport?.getCookie) {
+					throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "missing_transport");
+				}
+				const sessionHeaders = transport.sessionHeaders;
+				const userAgent = sessionHeaders ? headerValue(sessionHeaders, "user-agent") : undefined;
+				const acceptLanguage = sessionHeaders
+					? headerValue(sessionHeaders, "accept-language")
+					: undefined;
+				if (!sessionHeaders || !userAgent || !acceptLanguage) {
+					throw new ResolverVendorUnavailableError(
+						HYPERSOLUTIONS_VENDOR_ID,
+						"missing_client_profile",
+					);
+				}
+				assertChallengeInput(challenge, options.allowedHosts);
+				const exchange = scriptExchangeUrls(challenge.scriptUrl, challenge.challengeToken);
+
+				// Hyper documents /ip as an authenticated service request but does not
+				// publish an explicit exclusion from request quota. Meter conservatively.
+				const ip = await recordPaidResolverCreate({
+					traceRecorder,
+					vendor: HYPERSOLUTIONS_VENDOR_ID,
+					kind: challenge.kind,
+					endpoint: "hyper:ip",
+					signal: operationSignal,
+					usage,
+					create: () =>
+						runPhase("measure_ip", async () => {
+					const ipResponse = await boundFetch(
+						transport,
+						HYPER_IP_URL,
+						{
+							method: "GET",
+							headers: {
+								accept: "application/json, text/plain;q=0.9",
+								"x-api-key": apiKey,
+							},
+							signal: operationSignal,
+							redirect: "manual",
+							maxBodyBytes: IP_RESPONSE_MAX_BYTES,
+						},
+						"measure_ip",
+					);
+					requireSuccess(ipResponse.status, "measure_ip");
+					assertBoundedBody(ipResponse, IP_RESPONSE_MAX_BYTES, "measure_ip");
+					const observedIp = parseObservedIp(ipResponse.body);
+					if (!observedIp) throw transportFailure("measure_ip");
+					return observedIp;
+						}),
+				});
+
+				const scriptResponse = await runPhase("fetch_script", async () => {
+					const scriptResponse = await boundFetch(
+						transport,
+						exchange.fetchUrl,
+						{
+							method: "GET",
+							headers: { ...sessionHeaders, Referer: challenge.pageUrl },
+							signal: operationSignal,
+							redirect: "manual",
+							maxBodyBytes: BODY_MAX_BYTES,
+						},
+						"fetch_script",
+					);
+					requireSuccess(scriptResponse.status, "fetch_script");
+					assertBoundedBody(scriptResponse, BODY_MAX_BYTES, "fetch_script");
+					if (!scriptResponse.body) {
+						throw new ResolverChallengeVerdictError(HYPERSOLUTIONS_VENDOR_ID, "solve_failed", {
+							phase: "fetch_script",
+						});
+					}
+					return scriptResponse;
+				});
+				const stateCookie = transport
+					.getCookie(challenge.stateCookieName, challenge.pageUrl)
+					?.trim();
+				if (!stateCookie) {
+					throw new ResolverVendorUnavailableError(
+						HYPERSOLUTIONS_VENDOR_ID,
+						"missing_challenge_input",
+						{ missingFields: [challenge.stateCookieName], phase: "fetch_script" },
+					);
+				}
+
+				let expires: number | undefined;
+				for (const [roundIndex, index] of exchange.indices.entries()) {
+					const round = roundIndex + 1;
+					const payload = await recordPaidResolverCreate({
+						traceRecorder,
+						vendor: HYPERSOLUTIONS_VENDOR_ID,
+						kind: challenge.kind,
+						endpoint: "hyper:sbsd_create",
+						round,
+						signal: operationSignal,
+						usage,
+						create: () =>
+							runPhase("generate_payload", async () => {
+						const hyperResponse = await generatePayload(
+							fetchImpl,
+							apiKey,
+							JSON.stringify({
+								index,
+								uuid: exchange.uuid,
+								o: stateCookie,
+								pageUrl: challenge.pageUrl,
+								userAgent,
+								script: scriptResponse.body,
+								ip,
+								acceptLanguage,
+							}),
+							operationSignal,
+						);
+						requireSuccess(hyperResponse.status, "generate_payload");
+						const generated =
+							hyperResponse.body === undefined ? undefined : parsePayload(hyperResponse.body);
+						if (!generated) {
+							throw new ResolverVendorUnavailableError(
+								HYPERSOLUTIONS_VENDOR_ID,
+								"transport_failure",
+								{ phase: "generate_payload", round },
+							);
+						}
+						return generated;
+							}),
+					});
+					const postResponse = await runPhase("post_payload", async () => {
+						const postResponse = await boundFetch(
+							transport,
+							exchange.postUrl,
+							{
+								method: "POST",
+								headers: {
+									...sessionHeaders,
+									"content-type": "application/json",
+									Referer: challenge.pageUrl,
+								},
+								body: JSON.stringify({ body: payload }),
+								signal: operationSignal,
+								redirect: "manual",
+								maxBodyBytes: BODY_MAX_BYTES,
+							},
+							"post_payload",
+						);
+						requireSuccess(postResponse.status, "post_payload");
+						assertBoundedBody(postResponse, BODY_MAX_BYTES, "post_payload");
+						return postResponse;
+					});
+					expires =
+						postResponse.cookies.find((cookie) => cookie.name === challenge.stateCookieName)
+							?.expires ?? expires;
+				}
+
+				// A 2xx payload POST is not proof of a solve and the state cookie is not
+				// required to rotate (measured zozotown source and Hyper's docs both verify
+				// only through the next protected GET, which is Phase 2).
+				return {
+					form: "cookie_state",
+					kind: "akamai_sbsd",
+					outcome: "payload_accepted",
+					verified: false,
+					stateCookieName: challenge.stateCookieName,
+					...(expires === undefined ? {} : { expires }),
+				};
+			} catch (error) {
+				if (timeoutController.signal.aborted && !signal.aborted) {
+					throw new ResolverVendorUnavailableError(HYPERSOLUTIONS_VENDOR_ID, "timeout");
+				}
+				throw error;
+			} finally {
+				if (timeout !== undefined) clearTimeout(timeout);
+			}
+		},
+	};
+}