@prosopo/procaptcha-frictionless 2.15.0 → 2.16.0

package/src/AuthenticatedBadge.tsx

@@ -0,0 +1,141 @@
+// 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.
+
+// Widget for the `authenticated` captcha outcome — no user-facing challenge,
+// just a visible acknowledgement that Web Bot Auth verification succeeded.
+// Mounts once, immediately encodes a ProcaptchaToken with the sessionId as
+// its commitmentId (matching what /client/authenticated/verify decodes) and
+// fires `onHuman`. The badge itself is purely presentational; the token
+// submission happens in the mount effect.
+//
+// The token carries empty signature bags (`{provider: {}, user: {}}`) — the
+// authenticated verify endpoint does not check the token's user or provider
+// signatures because there was no captcha challenge to sign. Only the dApp
+// server's signature on the timestamp is checked at verify time, and that
+// is applied by the dApp on the way to /verify (not by the widget here).
+
+import { getDefaultEvents } from "@prosopo/procaptcha-common";
+import {
+	type Account,
+	ApiParams,
+	CaptchaType,
+	type ProcaptchaCallbacks,
+	type RandomProvider,
+	encodeProcaptchaOutput,
+} from "@prosopo/types";
+import { type FC, useEffect, useRef } from "react";
+
+export type AuthenticatedBadgeProps = {
+	sessionId: string;
+	agent?: string;
+	dapp: string;
+	userAccount: Account;
+	provider: RandomProvider;
+	callbacks: ProcaptchaCallbacks;
+};
+
+const displayHost = (agent?: string): string => {
+	if (!agent) return "unknown";
+	try {
+		return new URL(agent).hostname;
+	} catch {
+		return agent;
+	}
+};
+
+export const AuthenticatedBadge: FC<AuthenticatedBadgeProps> = ({
+	sessionId,
+	agent,
+	dapp,
+	userAccount,
+	provider,
+	callbacks,
+}) => {
+	// One-shot: React 18 StrictMode double-invokes effects in development;
+	// this guard makes sure the token is emitted exactly once even under
+	// double-mount. Production doesn't double-invoke, so this is a
+	// belt-and-braces against local-dev confusion.
+	const emittedRef = useRef(false);
+
+	useEffect(() => {
+		if (emittedRef.current) return;
+		emittedRef.current = true;
+		const events = getDefaultEvents(callbacks);
+		const token = encodeProcaptchaOutput({
+			[ApiParams.providerUrl]: provider.provider.url,
+			[ApiParams.user]: userAccount.account.address,
+			[ApiParams.dapp]: dapp,
+			// Verify endpoint reads commitmentId as the sessionId — reusing
+			// the existing slot avoids a token codec bump for this one flow.
+			[ApiParams.commitmentId]: sessionId,
+			[ApiParams.timestamp]: Date.now().toString(),
+			[ApiParams.signature]: {
+				[ApiParams.provider]: {},
+				[ApiParams.user]: {},
+			},
+			[ApiParams.captchaType]: CaptchaType.authenticated,
+		});
+		events.onHuman(token);
+	}, [sessionId, dapp, userAccount, provider, callbacks]);
+
+	return (
+		<div
+			style={{
+				display: "inline-flex",
+				alignItems: "center",
+				gap: 8,
+				padding: "8px 12px",
+				borderRadius: 6,
+				background: "#eef2ff",
+				border: "1px solid #c7d2fe",
+				color: "#3730a3",
+				fontFamily:
+					"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+				fontSize: 13,
+				lineHeight: 1.4,
+			}}
+			// biome-ignore lint/a11y/useSemanticElements: doesn't make sense
+			role="status"
+			aria-label="Verified agent"
+		>
+			<svg
+				width="16"
+				height="16"
+				viewBox="0 0 24 24"
+				fill="none"
+				stroke="currentColor"
+				strokeWidth="2.5"
+				strokeLinecap="round"
+				strokeLinejoin="round"
+				aria-hidden="true"
+			>
+				<title>Verified</title>
+				<path d="M20 6L9 17l-5-5" />
+			</svg>
+			<span>
+				{agent ? (
+					<>
+						<strong>Verified agent</strong>: {displayHost(agent)}
+					</>
+				) : (
+					// No Signature-Agent URL on the response — the operator's Allow
+					// rule matched on a non-Web-Bot-Auth condition (IP CIDR, JA4,
+					// UA substring, ASN, country). Fall back to generic copy so
+					// the operator isn't misled about which qualifier fired.
+					<strong>Trusted request</strong>
+				)}
+			</span>
+		</div>
+	);
+};

package/src/ProcaptchaFrictionless.tsx

@@ -33,6 +33,7 @@ import {
 import { darkTheme, lightTheme } from "@prosopo/widget-skeleton";
 import type { KeyboardEvent, MouseEvent, TouchEvent } from "react";
 import { useEffect, useRef, useState } from "react";
+import { AuthenticatedBadge } from "./AuthenticatedBadge.js";
 import customDetectBot from "./customDetectBot.js";
 import { evaluateFrictionlessResult } from "./frictionlessResultGuard.js";
 import {
@@ -42,6 +43,8 @@ import {
 	normaliseRetryCoords,
 } from "./sessionInvalidatedRecovery.js";
 
+const NO_SESSION_FOUND_KEY = "CAPTCHA.NO_SESSION_FOUND";
+
 // Each session uses exactly one solver — chosen by the /frictionless response.
 const ProcaptchaLoader = async () =>
 	(await import("@prosopo/procaptcha-react")).Procaptcha;
@@ -94,7 +97,7 @@ const defaultLoadingState = (
 	attemptCount: number,
 ): FrictionlessLoadingState => ({
 	loading: false,
-	attemptCount: attemptCount || 0,
+	attemptCount,
 });
 
 export const ProcaptchaFrictionless = ({
@@ -113,10 +116,22 @@ export const ProcaptchaFrictionless = ({
 	// to click the checkbox a second time and the checkbox click position is
 	// preserved in the eventual solution salt.
 	const pendingRetryCoordsRef = useRef<RetryCoords | null>(null);
-	// One-shot outer guard so a persistently broken session doesn't loop.
-	// After we've retried once, a second NO_SESSION_FOUND falls back to the
-	// inner widget's own `frictionlessState.restart()` path.
-	const sessionInvalidatedFiredRef = useRef(false);
+	// Bounded outer guard so a persistently broken session doesn't loop. Each
+	// re-mint costs a /frictionless round trip, so the count is capped — but
+	// it is a count rather than a one-shot, because a widget legitimately
+	// mints a new session every time the user presses reload. `onReload`
+	// clears it for the same reason. When the budget is spent we fall over
+	// visibly (see `onSessionInvalidated`) instead of leaving the user on a
+	// dead "No session found" checkbox.
+	const sessionInvalidatedAttemptsRef = useRef(0);
+	// Escalation sessions we have already mounted a widget for. The provider
+	// mints exactly one escalation session per PoW solution and consumes it on
+	// the first challenge fetch, so a repeat handoff for the same id can only
+	// produce a widget that 400s with NO_SESSION_FOUND. The PoW manager fires
+	// `onEscalate` from inside its `providerRetry`-wrapped `submit()`, so a
+	// throw anywhere after the handoff re-runs submit and escalates a second
+	// time on the same envelope.
+	const escalatedSessionIdsRef = useRef(new Set<string>());
 	// Bumped on every mount so the replacement widget gets a fresh React
 	// `key`. Without it a re-render for the same captcha type reconciles onto
 	// the existing element, and the inner widget keeps the manager it built on
@@ -161,9 +176,14 @@ export const ProcaptchaFrictionless = ({
 		),
 	);
 
+	// `??`, not `||`: every caller that wants the counter back at zero passes
+	// literal 0, and `0 || current` silently kept the old count. `start()` then
+	// tripped its own `attemptCount >= 5` fall-over after five *cumulative*
+	// runs in a widget lifetime — five reload presses were enough to strand the
+	// user on the error placeholder even though every one of them succeeded.
 	const resetState = (attemptCount?: number) => {
 		stateRef.current = defaultLoadingState(
-			attemptCount || stateRef.current.attemptCount,
+			attemptCount ?? stateRef.current.attemptCount,
 		);
 	};
 
@@ -212,6 +232,12 @@ export const ProcaptchaFrictionless = ({
 			newSessionId: string,
 			coords?: RetryCoords,
 		) => {
+			// Idempotent per escalation session — see `escalatedSessionIdsRef`.
+			// Without this a re-run of the PoW widget's `submit()` mounts a
+			// second widget against the session the first one already spent,
+			// which the provider answers with 400 CAPTCHA.NO_SESSION_FOUND.
+			if (escalatedSessionIdsRef.current.has(newSessionId)) return;
+			escalatedSessionIdsRef.current.add(newSessionId);
 			void renderForCaptchaType(
 				next,
 				{
@@ -225,23 +251,38 @@ export const ProcaptchaFrictionless = ({
 
 		// The provider returned NO_SESSION_FOUND on the inner widget's
 		// challenge fetch — the sessionId minted upstream is no longer usable
-		// (usually because a duplicate /captcha/{type} POST from a WebView
-		// mount storm consumed it first). Re-run the frictionless flow to
+		// (a duplicate /captcha/{type} POST consumed it first, or the widget
+		// re-sent an id it had already spent). Re-run the frictionless flow to
 		// mint a fresh session, then re-mount the inner widget with the
 		// preserved checkbox click coords so the user is not asked to click a
-		// second time. One-shot per outer widget lifetime — if the retry
-		// also fails, fall through to the inner widget's existing
-		// `frictionlessState.restart()` path.
+		// second time.
+		//
+		// The inner widget cannot recover on its own here: it always takes
+		// this branch and returns before its own `frictionlessState.restart()`
+		// fallback, and its guard ref is fresh on every re-mount. So whatever
+		// this handler declines to do, nothing else does — hence the terminal
+		// `fallOverWithStyle` rather than a silent return once the retry
+		// budget is spent.
 		const onSessionInvalidated = (x?: number, y?: number) => {
 			const { shouldRestart } = handleSessionInvalidated(
 				x,
 				y,
-				sessionInvalidatedFiredRef,
+				sessionInvalidatedAttemptsRef,
 				pendingRetryCoordsRef,
 			);
-			if (!shouldRestart) return;
-			resetState(0);
-			void start();
+			if (shouldRestart) {
+				resetState(0);
+				void start();
+				return;
+			}
+			// Budget spent. Surface the error on the checkbox and let
+			// `fallOverWithStyle`'s NO_SESSION_FOUND branch schedule the
+			// 10-second full restart, so the user always has a way back.
+			const message = i18n.isInitialized
+				? i18n.t(NO_SESSION_FOUND_KEY)
+				: "No session found";
+			events.onError(new Error(message));
+			fallOverWithStyle(message, NO_SESSION_FOUND_KEY);
 		};
 
 		// The user pressed reload on the challenge. The provider consumed this
@@ -253,6 +294,9 @@ export const ProcaptchaFrictionless = ({
 		const onReload = (x?: number, y?: number) => {
 			pendingRetryCoordsRef.current = normaliseRetryCoords(x, y);
 			nextMountAutoStartRef.current = true;
+			// A reload mints a genuinely new session, so the invalidation
+			// budget for the *previous* one shouldn't count against it.
+			sessionInvalidatedAttemptsRef.current = 0;
 			resetState(0);
 			void start();
 		};
@@ -275,7 +319,31 @@ export const ProcaptchaFrictionless = ({
 		mountCountRef.current += 1;
 		const mountKey = mountCountRef.current;
 
-		if (captchaType === CaptchaType.image) {
+		if (captchaType === CaptchaType.authenticated) {
+			// Web Bot Auth pre-verified pass-through. No challenge, no
+			// interaction — the badge component encodes and fires the token
+			// on mount. Skip the loader chain the other branches use because
+			// there is no captcha module to lazy-import here.
+			if (!frictionlessState.sessionId) {
+				events.onError(
+					new Error(
+						"authenticated captcha response missing sessionId — provider is misbehaving",
+					),
+				);
+				fallOverWithStyle();
+				return;
+			}
+			setComponentToRender(
+				<AuthenticatedBadge
+					sessionId={frictionlessState.sessionId}
+					agent={frictionlessState.agent}
+					dapp={config.account.address ?? ""}
+					userAccount={frictionlessState.userAccount}
+					provider={frictionlessState.provider}
+					callbacks={callbacks}
+				/>,
+			);
+		} else if (captchaType === CaptchaType.image) {
 			const Procaptcha = await ProcaptchaLoader();
 			setComponentToRender(
 				<Procaptcha
@@ -374,6 +442,7 @@ export const ProcaptchaFrictionless = ({
 					encryptBehavioralData: result.encryptBehavioralData,
 					getSimdReadings: result.getSimdReadings,
 					hp: result.hp,
+					agent: result.agent,
 				};
 
 				await renderForCaptchaType(result.captchaType, frictionlessState);

package/src/customDetectBot.ts

@@ -297,6 +297,7 @@ const customDetectBot: BotDetectionFunction = async (
 			userAccount: userAccount,
 			error: captcha.error,
 			hp: captcha.hp,
+			agent: captcha.agent,
 		};
 	}
 
@@ -357,6 +358,7 @@ const customDetectBot: BotDetectionFunction = async (
 		userAccount: userAccount,
 		error: captcha.error,
 		hp: captcha.hp,
+		agent: captcha.agent,
 		// Map specific trackers to generic behavioral collectors
 		behaviorCollector1: detectionResult.mouseTracker,
 		behaviorCollector2: detectionResult.touchTracker,

package/src/detectorLoader.ts

@@ -59,22 +59,62 @@ export type DetectorType = (
 	userAccount: Account;
 }>;
 
+interface LoaderAttempt {
+	readonly url: string;
+	readonly release: () => void;
+}
+
+const blobAttempt = (script: string): LoaderAttempt => {
+	const url = URL.createObjectURL(
+		new Blob([script], { type: "text/javascript" }),
+	);
+	return { url, release: (): void => URL.revokeObjectURL(url) };
+};
+
+const dataAttempt = (script: string): LoaderAttempt => ({
+	url: `data:text/javascript;charset=utf-8,${encodeURIComponent(script)}`,
+	release: (): void => undefined,
+});
+
+/** Injection point for tests; real callers never pass this. */
+export type ModuleImporter = (url: string) => Promise<unknown>;
+
+const defaultImporter: ModuleImporter = (url) =>
+	import(/* @vite-ignore */ /* webpackIgnore: true */ url);
+
 /**
- * Loads a detector from a provider-served obfuscated ESM string (the per-session
- * pool bundle). Evaluated via a blob URL — the served module is self-contained
- * (no imports), so dynamic `import()` of the blob yields its default export.
+ * Loads a detector from a provider-served obfuscated ESM string (the
+ * per-session pool bundle). The module is self-contained, so a dynamic
+ * `import()` yields its default export.
+ *
+ * A blob URL is tried first, then a `data:` URL. The two are gated by
+ * different CSP directives and sites commonly allow one without the other — a
+ * `script-src` of `*` matches neither, and a policy listing `data:` for
+ * scripts and `blob:` only for workers blocks the blob path outright. Without
+ * the fallback every session on such a site loses the detector, sends an empty
+ * token, and can never pass frictionlessly.
+ *
+ * A blocked attempt logs a CSP violation before the import rejects. That noise
+ * is the cost of recovering the session.
  */
 export const DetectorLoaderFromScript = async (
 	script: string,
+	importModule: ModuleImporter = defaultImporter,
 ): Promise<DetectorType> => {
-	const blob = new Blob([script], { type: "text/javascript" });
-	const url = URL.createObjectURL(blob);
-	try {
-		const mod = (await import(/* @vite-ignore */ url)) as {
-			default: DetectorType;
-		};
-		return mod.default;
-	} finally {
-		URL.revokeObjectURL(url);
+	let lastError: unknown = new Error("no loader attempt ran");
+	for (const build of [blobAttempt, dataAttempt]) {
+		let attempt: LoaderAttempt | undefined;
+		try {
+			attempt = build(script);
+			const mod = (await importModule(attempt.url)) as {
+				default: DetectorType;
+			};
+			return mod.default;
+		} catch (err) {
+			lastError = err;
+		} finally {
+			attempt?.release();
+		}
 	}
+	throw lastError;
 };

package/src/sessionInvalidatedRecovery.ts

@@ -49,23 +49,43 @@ export const normaliseRetryCoords = (
 };
 
 /**
- * Semantics of the outer recovery handler. Returns whether the caller
- * should proceed to re-run the frictionless flow (`start()`), and mutates
- * the passed refs to record the one-shot fire + pending coords.
+ * How many times a single outer widget will re-mint a session in response to
+ * `CAPTCHA.NO_SESSION_FOUND` on the inner widget before giving up and handing
+ * over to the terminal fallback.
  *
- * Second calls are ignored (one-shot per outer widget lifetime) so a
- * persistently broken session doesn't loop.
+ * This used to be one-shot per outer widget lifetime, which stranded users:
+ * the inner widget always takes the `onSessionInvalidated` branch (its own
+ * guard ref is fresh on every re-mount, because the outer widget bumps its
+ * mount key) and returns without touching its own `restart()` fallback. Once
+ * the outer one-shot was spent nothing at all handled the second failure, so
+ * the checkbox sat on "No session found" forever. A widget legitimately mints
+ * many sessions over its lifetime — every reload press is a new one — so a
+ * single lifetime-wide attempt is far too coarse a bound.
+ */
+export const MAX_SESSION_INVALIDATED_RETRIES = 3;
+
+/**
+ * Semantics of the outer recovery handler. Returns whether the caller should
+ * proceed to re-run the frictionless flow (`start()`), and mutates the passed
+ * refs to record the attempt + pending coords.
+ *
+ * Bounded rather than one-shot: a persistently broken session still stops
+ * looping, but the caller is told (`exhausted`) so it can fall back visibly
+ * instead of silently doing nothing.
  */
 export const handleSessionInvalidated = (
 	x: number | undefined,
 	y: number | undefined,
-	firedRef: MutableRef<boolean>,
+	attemptsRef: MutableRef<number>,
 	pendingCoordsRef: MutableRef<RetryCoords | null>,
-): { shouldRestart: boolean } => {
-	if (firedRef.current) return { shouldRestart: false };
-	firedRef.current = true;
+	maxAttempts: number = MAX_SESSION_INVALIDATED_RETRIES,
+): { shouldRestart: boolean; exhausted: boolean } => {
+	if (attemptsRef.current >= maxAttempts) {
+		return { shouldRestart: false, exhausted: true };
+	}
+	attemptsRef.current += 1;
 	pendingCoordsRef.current = normaliseRetryCoords(x, y);
-	return { shouldRestart: true };
+	return { shouldRestart: true, exhausted: false };
 };
 
 /**

package/src/tests/detectorLoader.test.ts

@@ -0,0 +1,108 @@
+// 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.
+
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+	DetectorLoaderFromScript,
+	type DetectorType,
+	type ModuleImporter,
+} from "../detectorLoader.js";
+
+const SCRIPT = "export default () => ({ token: 'x' });";
+
+const detector = (() => undefined) as unknown as DetectorType;
+
+describe("DetectorLoaderFromScript", () => {
+	const created: string[] = [];
+	const revoked: string[] = [];
+
+	beforeEach(() => {
+		created.length = 0;
+		revoked.length = 0;
+		let counter = 0;
+		URL.createObjectURL = vi.fn((): string => {
+			const url = `blob:https://example.test/${counter++}`;
+			created.push(url);
+			return url;
+		});
+		URL.revokeObjectURL = vi.fn((url: string): void => {
+			revoked.push(url);
+		});
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("uses a blob URL when the import succeeds", async () => {
+		const seen: string[] = [];
+		const importer: ModuleImporter = async (url) => {
+			seen.push(url);
+			return { default: detector };
+		};
+
+		await expect(DetectorLoaderFromScript(SCRIPT, importer)).resolves.toBe(
+			detector,
+		);
+
+		expect(seen).toHaveLength(1);
+		expect(seen[0]).toMatch(/^blob:/);
+		expect(revoked).toEqual(created);
+	});
+
+	it("falls back to a data URL when the blob import is blocked by CSP", async () => {
+		const seen: string[] = [];
+		const importer: ModuleImporter = async (url) => {
+			seen.push(url);
+			if (url.startsWith("blob:")) {
+				// What Chrome throws when script-src omits blob:
+				throw new TypeError("Failed to fetch dynamically imported module");
+			}
+			return { default: detector };
+		};
+
+		await expect(DetectorLoaderFromScript(SCRIPT, importer)).resolves.toBe(
+			detector,
+		);
+
+		expect(seen).toHaveLength(2);
+		expect(seen[0]).toMatch(/^blob:/);
+		expect(seen[1]).toMatch(/^data:text\/javascript;charset=utf-8,/);
+		expect(decodeURIComponent(seen[1]?.split(",")[1] ?? "")).toBe(SCRIPT);
+	});
+
+	it("revokes the blob URL even when its import fails", async () => {
+		const importer: ModuleImporter = async (url) => {
+			if (url.startsWith("blob:")) throw new Error("blocked");
+			return { default: detector };
+		};
+
+		await DetectorLoaderFromScript(SCRIPT, importer);
+
+		expect(revoked).toEqual(created);
+	});
+
+	it("rethrows the last error when both schemes are blocked", async () => {
+		const importer: ModuleImporter = async (url) => {
+			throw new Error(`blocked: ${url.slice(0, 5)}`);
+		};
+
+		await expect(DetectorLoaderFromScript(SCRIPT, importer)).rejects.toThrow(
+			"blocked: data:",
+		);
+		expect(revoked).toEqual(created);
+	});
+});