@apifuse/provider-sdk 2.2.0-beta.30 → 2.2.0-beta.32

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

@@ -0,0 +1,563 @@
+import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
+import { redactSensitiveText } from "../request-options.js";
+import type { TraceRecorder } from "../trace.js";
+import { assertResolverHostAllowed } from "./hosts.js";
+import {
+	ResolverChallengeVerdictError,
+	type ResolverIdentity,
+	type ResolverVendorAdapter,
+	ResolverVendorUnavailableError,
+	type ResolverVendorUnavailableReason,
+	resolverVendorSupports,
+} from "./types.js";
+
+const CAPSOLVER_VENDOR_ID = "capsolver" as const;
+const DEFAULT_CAPSOLVER_BASE_URL = "https://api.capsolver.com";
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+type Delay = (ms: number, signal: AbortSignal) => Promise<void>;
+type CapsolverOperationPhase = "create_task" | "poll_result";
+
+export interface CapsolverResolverVendorOptions {
+	readonly apiKey?: string;
+	readonly timeoutMs?: number;
+	readonly pollIntervalMs?: number;
+	readonly allowedHosts: readonly string[];
+	readonly fetchImpl?: typeof fetch;
+	readonly baseUrl?: string;
+	/** Test-only clock override; supplying it disables the real-time deadline timer. */
+	readonly now?: () => number;
+	/** Test-only delay override used with `now` to exercise polling without sleeping. */
+	readonly delay?: Delay;
+}
+
+export interface CapsolverResolverVendorAdapter extends ResolverVendorAdapter {
+	readonly id: "capsolver";
+	solve(
+		challenge: ProviderChallenge,
+		identity: ResolverIdentity | undefined,
+		signal: AbortSignal,
+		traceRecorder?: TraceRecorder,
+	): Promise<Extract<ChallengeSolution, { readonly form: "token" }>>;
+}
+
+class CapsolverSolveTimeoutError extends Error {
+	constructor() {
+		super("Capsolver resolver solve budget elapsed");
+		this.name = "CapsolverSolveTimeoutError";
+	}
+}
+
+class CapsolverUnavailableError extends ResolverVendorUnavailableError {
+	readonly errorCode: string | undefined;
+	readonly errorDescription: string | undefined;
+	readonly responseStatus: number | undefined;
+	readonly responseContentType: string | undefined;
+	readonly responseLength: number | undefined;
+
+	constructor(
+		reason: ResolverVendorUnavailableReason,
+		options: {
+			readonly phase: CapsolverOperationPhase;
+			readonly cause?: unknown;
+			readonly errorCode?: string;
+			readonly errorDescription?: string;
+			readonly responseStatus?: number;
+			readonly responseContentType?: string;
+			readonly responseLength?: number;
+		},
+	) {
+		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;
+	}
+}
+
+type JsonRecord = Record<string, unknown>;
+
+interface CapsolverResponseErrorFields {
+	readonly errorId: number | undefined;
+	readonly errorCode: string | undefined;
+	readonly errorDescription: string | undefined;
+}
+
+interface CapsolverCreateTaskResponse extends CapsolverResponseErrorFields {
+	readonly taskId: string | number | undefined;
+}
+
+interface CapsolverPollResultResponse extends CapsolverResponseErrorFields {
+	readonly status: string | undefined;
+	readonly solution: { readonly token: string | undefined } | undefined;
+}
+
+class CapsolverVerdictError extends ResolverChallengeVerdictError {
+	readonly phase: CapsolverOperationPhase;
+	readonly errorCode: string | undefined;
+	readonly errorDescription: string | undefined;
+
+	constructor(options: {
+		readonly phase: CapsolverOperationPhase;
+		readonly errorCode?: string;
+		readonly errorDescription?: string;
+	}) {
+		super(CAPSOLVER_VENDOR_ID, "solve_failed", options);
+		this.phase = options.phase;
+		this.errorCode = options.errorCode;
+		this.errorDescription = options.errorDescription;
+	}
+}
+
+function isJsonRecord(value: unknown): value is JsonRecord {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function abortReason(signal: AbortSignal): unknown {
+	return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+
+function containsSensitiveValue(value: unknown, sensitiveValues: readonly string[]): boolean {
+	const secrets = sensitiveValues.filter((secret) => secret.length > 0);
+	if (secrets.length === 0) return false;
+	const seen = new Set<object>();
+
+	const inspect = (candidate: unknown): boolean => {
+		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: unknown,
+	sensitiveValues: readonly string[],
+): { readonly cause?: unknown } {
+	return containsSensitiveValue(error, sensitiveValues) ? {} : { cause: error };
+}
+
+function sanitizedJsonParseCause(): SyntaxError {
+	return new SyntaxError("Upstream response failed");
+}
+
+function raceWithAbort<T>(
+	operation: () => Promise<T>,
+	signal: AbortSignal,
+	phase?: CapsolverOperationPhase,
+	sensitiveValues: readonly string[] = [],
+): Promise<T> {
+	if (signal.aborted) return Promise.reject(abortReason(signal));
+
+	return new Promise<T>((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: unknown) => {
+				cleanup();
+				if (phase === undefined) {
+					reject(error);
+					return;
+				}
+				reject(
+					new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+						...safeCauseOptions(error, sensitiveValues),
+						phase,
+					}),
+				);
+			},
+		);
+	});
+}
+
+async function abortableDelay(ms: number, signal: AbortSignal): Promise<void> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		await raceWithAbort(
+			() =>
+				new Promise<void>((resolve) => {
+					timer = setTimeout(resolve, ms);
+				}),
+			signal,
+		);
+	} finally {
+		if (timer !== undefined) clearTimeout(timer);
+	}
+}
+
+function responseErrorFields(payload: JsonRecord): CapsolverResponseErrorFields {
+	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: JsonRecord): CapsolverCreateTaskResponse {
+	const taskId = payload.taskId;
+	return {
+		...responseErrorFields(payload),
+		taskId: typeof taskId === "string" || typeof taskId === "number" ? taskId : undefined,
+	};
+}
+
+function parsePollResultResponse(payload: JsonRecord): CapsolverPollResultResponse {
+	const solution = isJsonRecord(payload.solution) ? payload.solution : undefined;
+	return {
+		...responseErrorFields(payload),
+		status: typeof payload.status === "string" ? payload.status : undefined,
+		solution: solution
+			? { token: typeof solution.token === "string" ? solution.token : undefined }
+			: undefined,
+	};
+}
+
+function isAllocationExhausted(payload: CapsolverResponseErrorFields): boolean {
+	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: CapsolverResponseErrorFields): boolean {
+	return payload.errorCode?.toLowerCase() === "error_captcha_unsolvable";
+}
+
+function safeVendorDetail(value: string, sensitiveValues: readonly string[]): string {
+	const redacted = redactSensitiveText(value, sensitiveValues);
+	return containsSensitiveValue(redacted, sensitiveValues) ? "[REDACTED]" : redacted;
+}
+
+function vendorErrorDetails(
+	payload: CapsolverResponseErrorFields,
+	sensitiveValues: readonly string[],
+): { readonly errorCode?: string; readonly errorDescription?: string } {
+	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: CapsolverResponseErrorFields,
+	phase: CapsolverOperationPhase,
+	sensitiveValues: readonly string[],
+): ResolverVendorUnavailableError | ResolverChallengeVerdictError {
+	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<TResponse>(
+	fetchImpl: typeof fetch,
+	url: string,
+	body: JsonRecord,
+	signal: AbortSignal,
+	phase: CapsolverOperationPhase,
+	sensitiveValues: readonly string[],
+	parseResponse: (payload: JsonRecord) => TResponse,
+): Promise<{ readonly ok: boolean; readonly payload: TResponse }> {
+	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: string;
+	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: unknown;
+	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: string, path: string): string {
+	return `${baseUrl.replace(/\/+$/u, "")}/${path}`;
+}
+
+function spanErrorAttributes(
+	error: unknown,
+	phase: CapsolverOperationPhase,
+): Record<string, unknown> | undefined {
+	if (error instanceof ResolverVendorUnavailableError) {
+		return {
+			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 {
+			verdict_reason: error.reason,
+			transport_phase: error.phase,
+			vendor_error_code: error.errorCode,
+			vendor_error_description: error.errorDescription,
+		};
+	}
+	if (error instanceof CapsolverSolveTimeoutError) {
+		return {
+			unavailability_reason: "timeout",
+			transport_phase: phase,
+		};
+	}
+	return undefined;
+}
+
+export function createCapsolverResolverVendorAdapter(
+	options: CapsolverResolverVendorOptions,
+): CapsolverResolverVendorAdapter {
+	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) {
+			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}`);
+			}
+			if (challenge.kind !== "turnstile") {
+				throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "not_implemented", {
+					phase: "create_task",
+				});
+			}
+			const sensitiveValues = [
+				apiKey,
+				challenge.pageUrl,
+				challenge.siteKey,
+				...(challenge.action !== undefined ? [challenge.action] : []),
+				...(challenge.cdata !== undefined ? [challenge.cdata] : []),
+			];
+
+			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: CapsolverOperationPhase = "create_task";
+
+			try {
+				const createTask = async () => {
+					const metadata = {
+						...(challenge.action !== undefined ? { action: challenge.action } : {}),
+						...(challenge.cdata !== undefined ? { cdata: challenge.cdata } : {}),
+					};
+					const createResult = await postJson(
+						fetchImpl,
+						endpoint(baseUrl, "createTask"),
+						{
+							clientKey: apiKey,
+							task: {
+								type: "AntiTurnstileTaskProxyLess",
+								websiteURL: challenge.pageUrl,
+								websiteKey: challenge.siteKey,
+								...(challenge.action !== undefined || challenge.cdata !== undefined
+									? { metadata }
+									: {}),
+							},
+						},
+						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: {
+								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();
+
+						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 token = result.payload.solution?.token;
+						if (!token?.trim()) {
+							throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "transport_failure", {
+								phase,
+							});
+						}
+						return { form: "token" as const, token };
+					}
+				};
+				return traceRecorder
+					? await traceRecorder.runSpan("resolver.vendor.poll_result", pollResult, {
+							attributes: {
+								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/src/runtime/resolver.ts

@@ -24,6 +24,7 @@ import {
 	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 {
@@ -196,6 +197,13 @@ const resolverAdapterRegistry: Partial<Record<ProviderResolverVendor, ResolverAd
 			timeoutMs,
 		});
 	},
+	capsolver(configuration, timeoutMs, allowedHosts) {
+		return createCapsolverResolverVendorAdapter({
+			allowedHosts,
+			apiKey: configuration,
+			timeoutMs,
+		});
+	},
 	browser(configuration, timeoutMs, allowedHosts) {
 		return createBrowserResolverVendorAdapter({
 			allowedHosts,
@@ -246,7 +254,6 @@ export function swapResolverDefaultUserAgentForTests(
 // 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: ReadonlySet<ProviderResolverVendor> = new Set([
-	"capsolver",
 	"capmonster",
 	"custom",
 ]);

package/src/server/serve-implementation.ts

@@ -39,6 +39,7 @@ import { createProviderCache } from "../runtime/cache.js";
 import {
 	createProviderChoiceContext,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+	PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV,
 } from "../runtime/choice.js";
 import { createCredentialContext } from "../runtime/credential.js";
 import { createEnvContext } from "../runtime/env.js";
@@ -626,6 +627,7 @@ function createProviderContext(
 	const env = createEnvContext([
 		...(provider.secrets?.map((secret) => secret.name) ?? []),
 		PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+		PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV,
 	]);
 	const credential = createCredentialContext({
 		allowedKeys: provider.credential?.keys,