@prosopo/procaptcha-frictionless 2.12.4 → 2.12.5

package/src/ProcaptchaFrictionless.tsx

@@ -30,6 +30,11 @@ import {
 import { darkTheme, lightTheme } from "@prosopo/widget-skeleton";
 import { useEffect, useRef, useState } from "react";
 import customDetectBot from "./customDetectBot.js";
+import {
+	type RetryCoords,
+	consumeRetryMountProps,
+	handleSessionInvalidated,
+} from "./sessionInvalidatedRecovery.js";
 
 // Each session uses exactly one solver — chosen by the /frictionless response.
 const ProcaptchaLoader = async () =>
@@ -89,6 +94,16 @@ export const ProcaptchaFrictionless = ({
 }: ProcaptchaFrictionlessProps) => {
 	const stateRef = useRef(defaultLoadingState(0));
 	const events = getDefaultEvents(callbacks);
+	// Coords carried over from an `onSessionInvalidated` event on the inner
+	// widget. Consumed once by the next `renderForCaptchaType` — the resumed
+	// widget mounts with `autoStart` + `startCoords` so the user doesn't have
+	// 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);
 
 	useEffect(() => {
 		if (config.language) {
@@ -175,6 +190,35 @@ 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
+		// 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.
+		const onSessionInvalidated = (x?: number, y?: number) => {
+			const { shouldRestart } = handleSessionInvalidated(
+				x,
+				y,
+				sessionInvalidatedFiredRef,
+				pendingRetryCoordsRef,
+			);
+			if (!shouldRestart) return;
+			resetState(0);
+			void start();
+		};
+
+		// Consume any pending retry coords now — the resumed widget owns them
+		// for exactly one auto-fired `manager.start(x, y)`. Cleared so a
+		// subsequent escalation/re-render doesn't accidentally re-inject.
+		const { autoStart: resumedAutoStart, startCoords } = consumeRetryMountProps(
+			pendingRetryCoordsRef,
+			autoStart,
+		);
+
 		if (captchaType === CaptchaType.image) {
 			const Procaptcha = await ProcaptchaLoader();
 			setComponentToRender(
@@ -183,7 +227,9 @@ export const ProcaptchaFrictionless = ({
 					callbacks={callbacks}
 					frictionlessState={frictionlessState}
 					i18n={i18n}
-					autoStart={autoStart}
+					autoStart={resumedAutoStart}
+					startCoords={startCoords}
+					onSessionInvalidated={onSessionInvalidated}
 				/>,
 			);
 		} else if (captchaType === CaptchaType.puzzle) {
@@ -194,7 +240,9 @@ export const ProcaptchaFrictionless = ({
 					callbacks={callbacks}
 					frictionlessState={frictionlessState}
 					i18n={i18n}
-					autoStart={autoStart}
+					autoStart={resumedAutoStart}
+					startCoords={startCoords}
+					onSessionInvalidated={onSessionInvalidated}
 				/>,
 			);
 		} else {
@@ -206,6 +254,9 @@ export const ProcaptchaFrictionless = ({
 					frictionlessState={frictionlessState}
 					i18n={i18n}
 					onEscalate={onEscalate}
+					autoStart={resumedAutoStart}
+					startCoords={startCoords}
+					onSessionInvalidated={onSessionInvalidated}
 				/>,
 			);
 		}

package/src/sessionInvalidatedRecovery.ts

@@ -0,0 +1,78 @@
+// 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.
+
+// Shared, unit-testable pieces of the ProcaptchaFrictionless recovery path
+// for CAPTCHA.NO_SESSION_FOUND on the inner widget. The React component
+// mutates refs directly; these helpers isolate the logic that decides how a
+// re-mount should be parameterised so it can be exercised without a renderer.
+
+export type RetryCoords = { x: number; y: number };
+
+/**
+ * Ref-like container used by ProcaptchaFrictionless. Extracted so tests
+ * can pass a plain `{current}` object.
+ */
+export type MutableRef<T> = { current: T };
+
+/**
+ * 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.
+ *
+ * - Second calls are ignored (one-shot per outer widget lifetime) so a
+ *   persistently broken session doesn't loop.
+ * - Coords are recorded only for a real trusted checkbox click. A partial
+ *   pair (only x or only y numeric) is treated as "no coords" so we
+ *   never accidentally embed `NaN` into the solution salt.
+ * - `(0, 0)` is treated as "no coords" too — that's what the widgets
+ *   emit for an `autoStart` mount (post-PoW escalation) or an untrusted
+ *   pointer event on the checkbox, neither of which is a real click. The
+ *   resumed widget re-uses the same default and the outcome on the wire
+ *   is identical; we discard the pair here so future readers can tell
+ *   the two apart.
+ */
+export const handleSessionInvalidated = (
+	x: number | undefined,
+	y: number | undefined,
+	firedRef: MutableRef<boolean>,
+	pendingCoordsRef: MutableRef<RetryCoords | null>,
+): { shouldRestart: boolean } => {
+	if (firedRef.current) return { shouldRestart: false };
+	firedRef.current = true;
+	const bothNumeric = typeof x === "number" && typeof y === "number";
+	const isRealClick = bothNumeric && (x !== 0 || y !== 0);
+	pendingCoordsRef.current = isRealClick ? { x, y } : null;
+	return { shouldRestart: true };
+};
+
+/**
+ * Compute the props a resumed inner widget mounts with. Consumes the
+ * pending coords ref (sets it back to `null`) so the next render doesn't
+ * accidentally re-inject stale coords into a fresh escalation.
+ *
+ * `escalationAutoStart` reflects the caller's own `autoStart` argument to
+ * `renderForCaptchaType` — post-PoW escalations keep the historic
+ * autoStart=true behaviour when no retry coords are pending.
+ */
+export const consumeRetryMountProps = (
+	pendingCoordsRef: MutableRef<RetryCoords | null>,
+	escalationAutoStart: boolean,
+): { autoStart: boolean; startCoords: RetryCoords | undefined } => {
+	const startCoords = pendingCoordsRef.current ?? undefined;
+	pendingCoordsRef.current = null;
+	return {
+		autoStart: escalationAutoStart || Boolean(startCoords),
+		startCoords,
+	};
+};

package/src/tests/sessionInvalidatedRecovery.test.ts

@@ -0,0 +1,129 @@
+// 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 { describe, expect, it } from "vitest";
+import {
+	type MutableRef,
+	type RetryCoords,
+	consumeRetryMountProps,
+	handleSessionInvalidated,
+} from "../sessionInvalidatedRecovery.js";
+
+const ref = <T>(initial: T): MutableRef<T> => ({ current: initial });
+
+describe("handleSessionInvalidated", () => {
+	it("records both coords and signals a restart on the first fire", () => {
+		const firedRef = ref(false);
+		const coordsRef = ref<RetryCoords | null>(null);
+
+		const result = handleSessionInvalidated(120, 340, firedRef, coordsRef);
+
+		expect(result).toEqual({ shouldRestart: true });
+		expect(firedRef.current).toBe(true);
+		expect(coordsRef.current).toEqual({ x: 120, y: 340 });
+	});
+
+	it("treats (0, 0) as 'no coords' — that's the autoStart / untrusted-event default, not a real click", () => {
+		const firedRef = ref(false);
+		const coordsRef = ref<RetryCoords | null>(null);
+
+		const result = handleSessionInvalidated(0, 0, firedRef, coordsRef);
+
+		expect(result).toEqual({ shouldRestart: true });
+		expect(coordsRef.current).toBeNull();
+	});
+
+	it("carries a real click even if only one axis is at the origin", () => {
+		const firedRef = ref(false);
+		const coordsRef = ref<RetryCoords | null>(null);
+
+		handleSessionInvalidated(0, 340, firedRef, coordsRef);
+
+		expect(coordsRef.current).toEqual({ x: 0, y: 340 });
+	});
+
+	it("stores no coords when x or y is undefined (autoStart / non-trusted event)", () => {
+		const firedRef = ref(false);
+		const coordsRef = ref<RetryCoords | null>(null);
+
+		const result = handleSessionInvalidated(
+			undefined,
+			undefined,
+			firedRef,
+			coordsRef,
+		);
+
+		expect(result).toEqual({ shouldRestart: true });
+		expect(firedRef.current).toBe(true);
+		expect(coordsRef.current).toBeNull();
+	});
+
+	it("stores no coords when only one axis is present — never emit NaN into the salt", () => {
+		const firedRef = ref(false);
+		const coordsRef = ref<RetryCoords | null>(null);
+
+		handleSessionInvalidated(120, undefined, firedRef, coordsRef);
+
+		expect(coordsRef.current).toBeNull();
+	});
+
+	it("is one-shot per outer widget lifetime — a second call is a no-op", () => {
+		const firedRef = ref(false);
+		const coordsRef = ref<RetryCoords | null>(null);
+
+		handleSessionInvalidated(100, 200, firedRef, coordsRef);
+		const second = handleSessionInvalidated(500, 600, firedRef, coordsRef);
+
+		expect(second).toEqual({ shouldRestart: false });
+		// The second call must not overwrite the first attempt's coords.
+		expect(coordsRef.current).toEqual({ x: 100, y: 200 });
+	});
+});
+
+describe("consumeRetryMountProps", () => {
+	it("returns pending retry coords and forces autoStart", () => {
+		const coordsRef = ref<RetryCoords | null>({ x: 42, y: 99 });
+
+		const mount = consumeRetryMountProps(coordsRef, false);
+
+		expect(mount).toEqual({
+			autoStart: true,
+			startCoords: { x: 42, y: 99 },
+		});
+	});
+
+	it("clears the coords ref so a subsequent render doesn't re-inject stale values", () => {
+		const coordsRef = ref<RetryCoords | null>({ x: 42, y: 99 });
+
+		consumeRetryMountProps(coordsRef, false);
+
+		expect(coordsRef.current).toBeNull();
+	});
+
+	it("propagates escalationAutoStart when no retry is pending (post-PoW escalation path)", () => {
+		const coordsRef = ref<RetryCoords | null>(null);
+
+		const mount = consumeRetryMountProps(coordsRef, true);
+
+		expect(mount).toEqual({ autoStart: true, startCoords: undefined });
+	});
+
+	it("returns autoStart=false, startCoords=undefined for the initial checkbox mount", () => {
+		const coordsRef = ref<RetryCoords | null>(null);
+
+		const mount = consumeRetryMountProps(coordsRef, false);
+
+		expect(mount).toEqual({ autoStart: false, startCoords: undefined });
+	});
+});