@prosopo/procaptcha-frictionless 2.8.31 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prosopo/procaptcha-frictionless",
-	"version": "2.8.31",
+	"version": "2.11.0",
 	"author": "PROSOPO LIMITED <info@prosopo.io>",
 	"license": "Apache-2.0",
 	"main": "dist/index.js",
@@ -30,21 +30,22 @@
 	},
 	"browserslist": ["> 0.5%, last 2 versions, not dead"],
 	"dependencies": {
-		"@prosopo/api": "3.1.41",
-		"@prosopo/common": "3.1.28",
-		"@prosopo/detector": "3.4.0",
-		"@prosopo/load-balancer": "2.8.17",
-		"@prosopo/locale": "3.1.28",
-		"@prosopo/procaptcha-common": "2.9.23",
-		"@prosopo/procaptcha-pow": "2.8.31",
-		"@prosopo/procaptcha-react": "2.9.27",
-		"@prosopo/types": "3.8.0",
-		"@prosopo/widget-skeleton": "2.7.13",
+		"@prosopo/api": "3.4.8",
+		"@prosopo/common": "3.1.38",
+		"@prosopo/detector": "3.4.36",
+		"@prosopo/load-balancer": "2.9.10",
+		"@prosopo/locale": "3.2.4",
+		"@prosopo/procaptcha-common": "2.10.17",
+		"@prosopo/procaptcha-pow": "2.9.4",
+		"@prosopo/procaptcha-puzzle": "2.10.8",
+		"@prosopo/procaptcha-react": "2.9.66",
+		"@prosopo/types": "4.3.0",
+		"@prosopo/widget-skeleton": "2.8.3",
 		"dotenv": "16.4.5",
 		"react": "18.3.1"
 	},
 	"devDependencies": {
-		"@prosopo/config": "3.3.0",
+		"@prosopo/config": "3.3.1",
 		"@types/node": "22.10.2",
 		"@vitest/coverage-v8": "3.2.4",
 		"concurrently": "9.0.1",
@@ -58,7 +59,8 @@
 	},
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/prosopo/captcha.git"
+		"url": "git+https://github.com/prosopo/captcha.git",
+		"directory": "packages/procaptcha-frictionless"
 	},
 	"bugs": {
 		"url": "https://github.com/prosopo/captcha/issues"

package/src/ProcaptchaFrictionless.tsx

@@ -0,0 +1,286 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { loadI18next } from "@prosopo/locale";
+import {
+	Checkbox,
+	TestModeBanner,
+	getDefaultEvents,
+	isSecureBrowserContext,
+	providerRetry,
+} from "@prosopo/procaptcha-common";
+import {
+	CaptchaType,
+	type FrictionlessState,
+	type ModeType,
+	ProcaptchaConfigSchema,
+	type ProcaptchaFrictionlessProps,
+} from "@prosopo/types";
+import { darkTheme, lightTheme } from "@prosopo/widget-skeleton";
+import { useEffect, useRef, useState } from "react";
+import customDetectBot from "./customDetectBot.js";
+
+// Each session uses exactly one solver — chosen by the /frictionless response.
+const ProcaptchaLoader = async () =>
+	(await import("@prosopo/procaptcha-react")).Procaptcha;
+const ProcaptchaPuzzleLoader = async () =>
+	(await import("@prosopo/procaptcha-puzzle")).ProcaptchaPuzzle;
+const ProcaptchaPowLoader = async () =>
+	(await import("@prosopo/procaptcha-pow")).ProcaptchaPow;
+
+const renderPlaceholder = (
+	theme: string | undefined,
+	mode: ModeType,
+	errorMessage: string | undefined,
+	isTranslationLoaded: boolean,
+	translationFn: (key: string) => string,
+	loading: boolean,
+) => {
+	const checkboxTheme = "light" === theme ? lightTheme : darkTheme;
+
+	if (mode === "invisible") {
+		return null;
+	}
+
+	return (
+		<Checkbox
+			theme={checkboxTheme}
+			onChange={async () => {}}
+			checked={false}
+			labelText={isTranslationLoaded ? translationFn("WIDGET.I_AM_HUMAN") : ""}
+			error={errorMessage}
+			aria-label="human checkbox"
+			loading={loading}
+		/>
+	);
+};
+
+type FrictionlessLoadingState = {
+	loading: boolean;
+	attemptCount: number;
+	errorMessage?: string;
+};
+
+const defaultLoadingState = (
+	attemptCount: number,
+): FrictionlessLoadingState => ({
+	loading: false,
+	attemptCount: attemptCount || 0,
+});
+
+export const ProcaptchaFrictionless = ({
+	config,
+	callbacks,
+	restart,
+	i18n,
+	detectBot = customDetectBot,
+	container,
+}: ProcaptchaFrictionlessProps) => {
+	const stateRef = useRef(defaultLoadingState(0));
+	const events = getDefaultEvents(callbacks);
+
+	useEffect(() => {
+		if (config.language) {
+			if (i18n) {
+				if (i18n.language !== config.language) {
+					i18n.changeLanguage(config.language).then((r) => r);
+				}
+			} else {
+				loadI18next(false).then((i18n) => {
+					if (i18n.language !== config.language)
+						i18n.changeLanguage(config.language).then((r) => r);
+				});
+			}
+		}
+	}, [i18n, config.language]);
+
+	const [componentToRender, setComponentToRender] = useState(
+		renderPlaceholder(
+			config.theme,
+			config.mode,
+			stateRef.current.errorMessage,
+			i18n.isInitialized,
+			i18n.t,
+			true,
+		),
+	);
+
+	const resetState = (attemptCount?: number) => {
+		stateRef.current = defaultLoadingState(
+			attemptCount || stateRef.current.attemptCount,
+		);
+	};
+
+	const fallOverWithStyle = (errorMessage?: string, errorKey?: string) => {
+		// We could always re-render here after a period but this will result in never-ending requests to Providers when
+		// settings are incorrect, or the user is not human. We need to selectively re-render for events like
+		// `no session found` but not for other errors.
+		if (errorKey === "CAPTCHA.NO_SESSION_FOUND") {
+			setTimeout(() => {
+				restartComponentTimeout();
+			}, 0);
+		}
+		setComponentToRender(
+			renderPlaceholder(
+				config.theme,
+				config.mode,
+				errorMessage || "Cannot load CAPTCHA",
+				i18n.isInitialized,
+				i18n.t,
+				false,
+			),
+		);
+	};
+
+	const restartComponentTimeout = () => {
+		setTimeout(() => {
+			resetState(0);
+			events.onReset();
+			// `restart` frictionless widget after 10 seconds
+			restart();
+		}, 10000);
+	};
+
+	// Mount the captcha widget that matches the chosen type. Used both for the
+	// initial frictionless decision and for the post-pow escalation handoff —
+	// in the latter case the FrictionlessState carries the new sessionId minted
+	// by the provider when it decided PoW alone wasn't enough.
+	const renderForCaptchaType = async (
+		captchaType: string,
+		frictionlessState: FrictionlessState,
+	) => {
+		const onEscalate = (
+			next: CaptchaType.image | CaptchaType.puzzle,
+			newSessionId: string,
+		) => {
+			void renderForCaptchaType(next, {
+				...frictionlessState,
+				sessionId: newSessionId,
+			});
+		};
+
+		if (captchaType === CaptchaType.image) {
+			const Procaptcha = await ProcaptchaLoader();
+			setComponentToRender(
+				<Procaptcha
+					config={config}
+					callbacks={callbacks}
+					frictionlessState={frictionlessState}
+					i18n={i18n}
+				/>,
+			);
+		} else if (captchaType === CaptchaType.puzzle) {
+			const ProcaptchaPuzzle = await ProcaptchaPuzzleLoader();
+			setComponentToRender(
+				<ProcaptchaPuzzle
+					config={config}
+					callbacks={callbacks}
+					frictionlessState={frictionlessState}
+					i18n={i18n}
+				/>,
+			);
+		} else {
+			const ProcaptchaPow = await ProcaptchaPowLoader();
+			setComponentToRender(
+				<ProcaptchaPow
+					config={config}
+					callbacks={callbacks}
+					frictionlessState={frictionlessState}
+					i18n={i18n}
+					onEscalate={onEscalate}
+				/>,
+			);
+		}
+	};
+
+	const start = async () => {
+		// Procaptcha cannot run over plain HTTP (no SubtleCrypto etc.), which
+		// would otherwise fail later with a cryptic provider-selection error.
+		// Surface a clear, non-retrying message instead.
+		if (!isSecureBrowserContext()) {
+			const errorMessage = i18n.isInitialized
+				? i18n.t("WIDGET.INSECURE_CONTEXT")
+				: "Procaptcha requires a secure (HTTPS) connection";
+			events.onError(new Error(errorMessage));
+			fallOverWithStyle(errorMessage, "WIDGET.INSECURE_CONTEXT");
+			return;
+		}
+
+		await providerRetry(
+			async () => {
+				stateRef.current.attemptCount += 1;
+
+				const configOutput = ProcaptchaConfigSchema.parse(config);
+				const result = await detectBot(configOutput, container, restart);
+
+				if (result.error?.message) {
+					stateRef.current = {
+						...stateRef.current,
+						loading: false,
+						errorMessage: result.error?.message,
+					};
+					events.onError(new Error(result.error?.message));
+					fallOverWithStyle(result.error?.message, result.error?.key);
+					return;
+				}
+
+				const frictionlessState: FrictionlessState = {
+					provider: result.provider,
+					sessionId: result.sessionId,
+					userAccount: result.userAccount,
+					restart, // Pass restart function
+					behaviorCollector1: result.behaviorCollector1,
+					behaviorCollector2: result.behaviorCollector2,
+					behaviorCollector3: result.behaviorCollector3,
+					deviceCapability: result.deviceCapability,
+					encryptBehavioralData: result.encryptBehavioralData,
+					getSimdReadings: result.getSimdReadings,
+					hp: result.hp,
+				};
+
+				await renderForCaptchaType(result.captchaType, frictionlessState);
+
+				stateRef.current = {
+					...stateRef.current,
+					loading: false,
+				};
+			},
+			start,
+			resetState,
+			stateRef.current.attemptCount,
+			5,
+		).finally(() => {
+			if (stateRef.current.attemptCount >= 5) {
+				fallOverWithStyle();
+				restartComponentTimeout();
+			}
+		});
+	};
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: <explanation>
+	useEffect(() => {
+		const detectAndSetComponent = async () => {
+			await start();
+		};
+
+		detectAndSetComponent();
+	}, [config, callbacks, detectBot, config.language]);
+
+	return (
+		<>
+			<TestModeBanner siteKey={config.account?.address ?? ""} />
+			{componentToRender}
+		</>
+	);
+};

package/src/customDetectBot.ts

@@ -0,0 +1,160 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { ProviderApi } from "@prosopo/api";
+import { ProsopoEnvError } from "@prosopo/common";
+import {
+	getRandomActiveProvider,
+	prefetchProviders,
+} from "@prosopo/load-balancer";
+import { ExtensionLoader } from "@prosopo/procaptcha-common";
+import { EnvironmentTypesSchema } from "@prosopo/types";
+import type {
+	BotDetectionFunction,
+	ProcaptchaClientConfigOutput,
+} from "@prosopo/types";
+import type { BotDetectionFunctionResult } from "@prosopo/types";
+import { DetectorLoader } from "./detectorLoader.js";
+
+if (typeof window !== "undefined") {
+	const envHint =
+		typeof process !== "undefined"
+			? process.env?.PROSOPO_DEFAULT_ENVIRONMENT
+			: undefined;
+	const parsedEnv = EnvironmentTypesSchema.safeParse(envHint);
+	if (parsedEnv.success) {
+		prefetchProviders(parsedEnv.data).catch(() => undefined);
+	}
+}
+
+export const withTimeout = async <T>(
+	promise: Promise<T>,
+	ms: number,
+): Promise<T> => {
+	let timeoutId: NodeJS.Timeout | undefined;
+	const timeoutPromise = new Promise<never>((_, reject) => {
+		timeoutId = setTimeout(() => {
+			reject(new ProsopoEnvError("API.UNKNOWN"));
+		}, ms);
+	});
+
+	try {
+		const result = await Promise.race([promise, timeoutPromise]);
+		if (timeoutId) {
+			clearTimeout(timeoutId);
+		}
+		return result;
+	} catch (error) {
+		if (timeoutId) {
+			clearTimeout(timeoutId);
+		}
+		throw error;
+	}
+};
+
+const customDetectBot: BotDetectionFunction = async (
+	config: ProcaptchaClientConfigOutput,
+	container: HTMLElement | undefined,
+	restartFn: () => void,
+): Promise<BotDetectionFunctionResult> => {
+	const [ExtClass, detect] = await Promise.all([
+		ExtensionLoader(config.web2),
+		DetectorLoader(),
+		prefetchProviders(config.defaultEnvironment),
+	]);
+	const ext = new ExtClass();
+
+	const detectionResult = await detect(
+		config.defaultEnvironment,
+		getRandomActiveProvider,
+		container,
+		restartFn,
+		() => ext.getAccount(config),
+	);
+
+	const userAccount = detectionResult.userAccount;
+
+	if (!config.account.address) {
+		throw new ProsopoEnvError("GENERAL.SITE_KEY_MISSING");
+	}
+
+	// Get random active provider with timeout
+	const provider = detectionResult.provider;
+
+	if (!provider) {
+		throw new Error("Provider Selection Failed");
+	}
+
+	const providerApi = new ProviderApi(
+		provider.provider.url,
+		config.account.address,
+	);
+
+	// SIMD readings deliberately omitted from the frictionless hop. The WASM
+	// benchmark is a CPU-bound loop that contends with BotScoreWorker if it
+	// runs during detection; deferring it until after the POST is in flight
+	// lets it complete in the worker thread while the network round-trip
+	// burns. Readings still attach on the challenge GET and on solution
+	// submit (first-hop-wins server-side).
+	const captchaPromise = providerApi.getFrictionlessCaptcha(
+		detectionResult.token,
+		detectionResult.encryptHeadHash,
+		config.account.address,
+		userAccount.account.address,
+		config.mode,
+		undefined,
+	);
+	if (detectionResult.getSimdReadings) {
+		// Fire-and-forget: triggers the memoised prefetch inside the catcher
+		// so the next hop sees a hot benchmark. We never await the result here.
+		void detectionResult.getSimdReadings(60_000).catch(() => undefined);
+	}
+	const captcha = await withTimeout(captchaPromise, 10000);
+
+	// Fire-and-forget DNS observation beacon. Failures swallowed —
+	// observation must never break the captcha flow.
+	if (captcha.dns_url) {
+		try {
+			void fetch(captcha.dns_url, {
+				method: "GET",
+				mode: "no-cors",
+				credentials: "omit",
+				keepalive: true,
+				cache: "no-store",
+			}).catch(() => undefined);
+		} catch {
+			/* swallow */
+		}
+	}
+
+	return {
+		captchaType: captcha.captchaType,
+		sessionId: captcha.sessionId,
+		provider: provider,
+		status: captcha.status,
+		userAccount: userAccount,
+		error: captcha.error,
+		hp: captcha.hp,
+		// Map specific trackers to generic behavioral collectors
+		behaviorCollector1: detectionResult.mouseTracker,
+		behaviorCollector2: detectionResult.touchTracker,
+		behaviorCollector3: detectionResult.clickTracker,
+		deviceCapability: detectionResult.hasTouchSupport,
+		encryptBehavioralData: detectionResult.encryptBehavioralData,
+		packBehavioralData: detectionResult.packBehavioralData,
+		getSimdReadings: detectionResult.getSimdReadings,
+	};
+};
+
+export default customDetectBot;

package/src/detectorLoader.ts

@@ -0,0 +1,18 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+type DetectorType = typeof import("@prosopo/detector").default;
+
+export const DetectorLoader = async (): Promise<DetectorType> =>
+	(await import("@prosopo/detector")).default;

package/src/index.ts

@@ -0,0 +1,14 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+export * from "./ProcaptchaFrictionless.js";

package/src/tests/customDetectBot.test.ts

@@ -0,0 +1,77 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { ProsopoEnvError } from "@prosopo/common";
+import { describe, expect, it, vi } from "vitest";
+import { withTimeout } from "../customDetectBot.js";
+
+describe("withTimeout", () => {
+	it("should resolve with the promise result when promise resolves before timeout", async () => {
+		const result = "success";
+		const promise = Promise.resolve(result);
+
+		const response = await withTimeout(promise, 1000);
+
+		expect(response).toBe(result);
+	});
+
+	it("should reject with original error when promise rejects before timeout", async () => {
+		const errorMessage = "Original error";
+		const promise = Promise.reject(new Error(errorMessage));
+
+		await expect(withTimeout(promise, 1000)).rejects.toThrow(errorMessage);
+	});
+
+	it("should reject with timeout error when promise does not resolve within the timeout", async () => {
+		const promise = new Promise((resolve) => {
+			setTimeout(resolve, 500);
+		});
+
+		vi.useFakeTimers();
+
+		const timeoutPromise = withTimeout(promise, 100);
+
+		vi.advanceTimersByTime(200);
+
+		await expect(timeoutPromise).rejects.toThrow(ProsopoEnvError);
+		await expect(timeoutPromise).rejects.toEqual(
+			expect.objectContaining({
+				message: "API.UNKNOWN",
+				translationKey: "API.UNKNOWN",
+			}),
+		);
+
+		vi.useRealTimers();
+	});
+
+	it("should respect the provided timeout duration", async () => {
+		vi.useFakeTimers();
+
+		const fastResolve = Promise.resolve("success");
+		const fastResult = withTimeout(fastResolve, 1000);
+
+		const slowPromise = new Promise((resolve) => {
+			setTimeout(() => resolve("slow"), 2000);
+		});
+		const slowWithTimeout = withTimeout(slowPromise, 1000);
+
+		vi.advanceTimersByTime(500);
+		expect(await fastResult).toBe("success");
+
+		vi.advanceTimersByTime(600);
+		await expect(slowWithTimeout).rejects.toThrow(ProsopoEnvError);
+
+		vi.useRealTimers();
+	});
+});