@prosopo/procaptcha-frictionless 2.8.22 → 2.11.0

package/dist/tests/customDetectBotSimd.test.js

@@ -0,0 +1,106 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+const mocks = vi.hoisted(() => ({
+    getFrictionlessCaptcha: vi.fn(),
+    getRandomActiveProvider: vi.fn(),
+    prefetchProviders: vi.fn(async () => undefined),
+    detect: vi.fn(),
+}));
+vi.mock("@prosopo/api", () => ({
+    ProviderApi: vi.fn(() => ({
+        getFrictionlessCaptcha: mocks.getFrictionlessCaptcha,
+    })),
+}));
+vi.mock("@prosopo/load-balancer", () => ({
+    getRandomActiveProvider: mocks.getRandomActiveProvider,
+    prefetchProviders: mocks.prefetchProviders,
+}));
+vi.mock("@prosopo/procaptcha-common", () => ({
+    ExtensionLoader: vi.fn(async () => {
+        return class FakeExtension {
+            getAccount() {
+                return Promise.resolve({
+                    account: { address: "5FakeUserAccountAddress" },
+                });
+            }
+        };
+    }),
+}));
+vi.mock("../detectorLoader.js", () => ({
+    DetectorLoader: vi.fn(async () => mocks.detect),
+}));
+import customDetectBot from "../customDetectBot.js";
+const baseConfig = {
+    account: { address: "5FakeSiteKey" },
+    defaultEnvironment: "production",
+    web2: true,
+    mode: "frictionless",
+};
+const makeDetectionResult = (getSimdReadings) => ({
+    token: "TOKEN",
+    encryptHeadHash: "HASH",
+    userAccount: { account: { address: "5FakeUserAccountAddress" } },
+    provider: {
+        provider: { url: "https://provider.test" },
+        providerAccount: "5Provider",
+    },
+    getSimdReadings,
+    mouseTracker: undefined,
+    touchTracker: undefined,
+    clickTracker: undefined,
+});
+const captchaResponse = {
+    captchaType: "pow",
+    sessionId: "SID",
+    status: "ok",
+};
+beforeEach(() => {
+    mocks.getFrictionlessCaptcha.mockReset();
+    mocks.getRandomActiveProvider.mockReset();
+    mocks.prefetchProviders.mockReset();
+    mocks.detect.mockReset();
+    mocks.prefetchProviders.mockResolvedValue(undefined);
+    mocks.getFrictionlessCaptcha.mockResolvedValue(captchaResponse);
+});
+describe("customDetectBot SIMD deferral", () => {
+    it("passes simdReadings as undefined to the frictionless POST even when getSimdReadings would return a value", async () => {
+        const getSimdReadings = vi.fn().mockResolvedValue("ENCODED_SIMD");
+        mocks.detect.mockResolvedValue(makeDetectionResult(getSimdReadings));
+        await customDetectBot(baseConfig, undefined, () => undefined);
+        expect(mocks.getFrictionlessCaptcha).toHaveBeenCalledTimes(1);
+        const args = mocks.getFrictionlessCaptcha.mock.calls[0];
+        expect(args?.[5]).toBeUndefined();
+    });
+    it("fires getSimdReadings after the frictionless POST is initiated (fire-and-forget)", async () => {
+        const callOrder = [];
+        mocks.getFrictionlessCaptcha.mockImplementation(() => {
+            callOrder.push("captcha-call");
+            return Promise.resolve(captchaResponse);
+        });
+        const getSimdReadings = vi.fn().mockImplementation(() => {
+            callOrder.push("simd-call");
+            return Promise.resolve("ENCODED_SIMD");
+        });
+        mocks.detect.mockResolvedValue(makeDetectionResult(getSimdReadings));
+        await customDetectBot(baseConfig, undefined, () => undefined);
+        expect(getSimdReadings).toHaveBeenCalledTimes(1);
+        expect(callOrder.indexOf("captcha-call")).toBeLessThan(callOrder.indexOf("simd-call"));
+    });
+    it("does not block the frictionless POST on a slow getSimdReadings", async () => {
+        let simdResolve;
+        const simdPromise = new Promise((resolve) => {
+            simdResolve = resolve;
+        });
+        const getSimdReadings = vi.fn().mockReturnValue(simdPromise);
+        mocks.detect.mockResolvedValue(makeDetectionResult(getSimdReadings));
+        const result = await customDetectBot(baseConfig, undefined, () => undefined);
+        expect(result.sessionId).toBe("SID");
+        simdResolve("ENCODED_SIMD");
+    });
+    it("skips the SIMD trigger when the detector doesn't expose getSimdReadings", async () => {
+        mocks.detect.mockResolvedValue(makeDetectionResult(undefined));
+        const result = await customDetectBot(baseConfig, undefined, () => undefined);
+        expect(result.sessionId).toBe("SID");
+        expect(mocks.getFrictionlessCaptcha).toHaveBeenCalledTimes(1);
+    });
+});
+//# sourceMappingURL=customDetectBotSimd.test.js.map

package/dist/tests/customDetectBotSimd.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"customDetectBotSimd.test.js","sourceRoot":"","sources":["../../src/tests/customDetectBotSimd.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prosopo/procaptcha-frictionless",
-	"version": "2.8.22",
+	"version": "2.11.0",
 	"author": "PROSOPO LIMITED <info@prosopo.io>",
 	"license": "Apache-2.0",
 	"main": "dist/index.js",
@@ -22,28 +22,30 @@
 	"scripts": {
 		"clean": "del-cli --verbose dist tsconfig.tsbuildinfo",
 		"test": "NODE_ENV=${NODE_ENV:-test}; npx vitest run --config ./vite.test.config.ts",
-		"build": "NODE_ENV=${NODE_ENV:-development}; vite build --config vite.esm.config.ts --mode $NODE_ENV",
+		"build": "npm run build:cross-env -- --mode ${NODE_ENV:-development}",
+		"build:cross-env": "vite build --config vite.esm.config.ts",
 		"build:tsc": "tsc --build --verbose",
 		"build:cjs": "NODE_ENV=${NODE_ENV:-development}; vite build --config vite.cjs.config.ts --mode $NODE_ENV",
 		"typecheck": "tsc --project tsconfig.types.json"
 	},
 	"browserslist": ["> 0.5%, last 2 versions, not dead"],
 	"dependencies": {
-		"@prosopo/api": "3.1.37",
-		"@prosopo/common": "3.1.26",
-		"@prosopo/detector": "3.3.18",
-		"@prosopo/load-balancer": "2.8.13",
-		"@prosopo/locale": "3.1.26",
-		"@prosopo/procaptcha-common": "2.9.19",
-		"@prosopo/procaptcha-pow": "2.8.27",
-		"@prosopo/procaptcha-react": "2.9.21",
-		"@prosopo/types": "3.6.4",
-		"@prosopo/widget-skeleton": "2.7.12",
+		"@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.1.26",
+		"@prosopo/config": "3.3.1",
 		"@types/node": "22.10.2",
 		"@vitest/coverage-v8": "3.2.4",
 		"concurrently": "9.0.1",
@@ -57,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";