@prosopo/procaptcha-common 2.9.23 → 2.10.18

package/src/reactComponents/Honeypot.tsx

@@ -0,0 +1,133 @@
+// 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 {
+	type CSSProperties,
+	forwardRef,
+	useEffect,
+	useId,
+	useMemo,
+	useRef,
+	useState,
+} from "react";
+import { createPortal } from "react-dom";
+
+interface HoneypotProps {
+	encodedQuestion: string;
+}
+
+const offscreenStyle: CSSProperties = {
+	position: "absolute",
+	left: "-9999px",
+	top: "-9999px",
+	width: "1px",
+	height: "1px",
+	overflow: "hidden",
+	opacity: 0,
+};
+
+// Server wraps morse/semaphore in base64 (utf-8) for the wire. Strip the
+// base64 layer here so the rendered label is the raw morse/semaphore an agent
+// can recognise and engage with.
+const decodeBase64Utf8 = (b64: string): string => {
+	const binary = atob(b64);
+	const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+	return new TextDecoder().decode(bytes);
+};
+
+// Locate the dapp's enclosing <form> by stepping out of the widget's shadow
+// root into light DOM, then walking up via closest(). Returns null when the
+// widget isn't embedded inside a form.
+const findAncestorForm = (anchor: Element): HTMLFormElement | null => {
+	const root = anchor.getRootNode();
+	const lightDomEntry = root instanceof ShadowRoot ? root.host : anchor;
+	return lightDomEntry instanceof Element
+		? lightDomEntry.closest("form")
+		: null;
+};
+
+// Honeypot must live in light DOM, not in the widget's shadow root: if it
+// rendered there a bot would have to traverse `.shadowRoot` to reach it, and
+// @prosopo/catcher patches that getter to detect (and restart on) automated
+// access — wiping the value the bot just wrote before it can submit.
+//
+// Within light DOM we prefer the enclosing <form> so bots scraping
+// `form.querySelectorAll('input')` discover the bait naturally; document.body
+// is the fallback for widgets mounted outside any form.
+//
+// The decoded question is rendered as the input's <label>, not as its value.
+// Naive form-fillers leave the empty input alone — no signal, no false
+// positives. Agents that read the DOM as a prompt may decode the label and
+// write an answer into the empty field; that response rides up as
+// clientMetaData.hp.
+export const Honeypot = forwardRef<HTMLInputElement, HoneypotProps>(
+	({ encodedQuestion }, ref) => {
+		const id = useId();
+		// Opaque non-existent form id. Setting `form="..."` on an input with a
+		// value that doesn't match any form's id disassociates the input from
+		// every form: the browser excludes it from the parent form's submission
+		// set and from `form.elements`, while leaving it discoverable via
+		// `form.querySelectorAll('input')`. Built from useId so it's unique per
+		// Honeypot instance and guaranteed not to collide with the input's own id.
+		const detachedFormId = `${id}-d`;
+		const question = useMemo(
+			() => decodeBase64Utf8(encodedQuestion),
+			[encodedQuestion],
+		);
+		const anchorRef = useRef<HTMLSpanElement>(null);
+		const [portalTarget, setPortalTarget] = useState<HTMLElement | null>(null);
+
+		useEffect(() => {
+			const anchor = anchorRef.current;
+			if (!anchor) return;
+			setPortalTarget(findAncestorForm(anchor) ?? document.body);
+		}, []);
+
+		if (typeof document === "undefined") return null;
+
+		// Transient anchor while we resolve the portal target. Sits in the React
+		// tree (inside the shadow root) just long enough for the effect above to
+		// walk out to light DOM and find the form.
+		if (!portalTarget) {
+			return (
+				<span ref={anchorRef} aria-hidden="true" style={{ display: "none" }} />
+			);
+		}
+
+		// Input is nested inside the label (implicit association) instead of
+		// htmlFor-linked — biome's noLabelWithoutControl rule only recognises
+		// the descendant form of association at static-analysis time.
+		return createPortal(
+			<div aria-hidden="true" style={offscreenStyle}>
+				<label>
+					{question}
+					<input
+						ref={ref}
+						id={id}
+						form={detachedFormId}
+						type="text"
+						name="email_confirm"
+						defaultValue=""
+						tabIndex={-1}
+						autoComplete="off"
+						aria-hidden="true"
+					/>
+				</label>
+			</div>,
+			portalTarget,
+		);
+	},
+);
+
+Honeypot.displayName = "Honeypot";

package/src/reactComponents/Reload.tsx

@@ -0,0 +1,99 @@
+// 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 { darkTheme, lightTheme } from "@prosopo/widget-skeleton";
+import { type ButtonHTMLAttributes, type FC, useMemo, useState } from "react";
+
+interface ReloadButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+	themeColor: "light" | "dark";
+	onReload: () => void;
+}
+
+const buttonStyleBase = {
+	border: "none",
+	paddingTop: "6px",
+	paddingBottom: "6px",
+	cursor: "pointer",
+	height: "39px",
+	width: "39px",
+	borderRadius: "50%",
+	display: "flex",
+};
+
+export const ReloadButton: FC<ReloadButtonProps> = ({
+	themeColor,
+	onReload,
+}: ReloadButtonProps) => {
+	const theme = useMemo(
+		() => (themeColor === "light" ? lightTheme : darkTheme),
+		[themeColor],
+	);
+	const [hover, setHover] = useState(false);
+	const buttonStyle = useMemo(() => {
+		const baseStyle = {
+			...buttonStyleBase,
+			backgroundColor: theme.palette.background.default,
+			color: hover
+				? theme.palette.primary.contrastText
+				: theme.palette.background.contrastText,
+			border: `1px solid ${theme.palette.grey[500]}`,
+			borderRadius: "50%",
+			transition: "background-color 0.3s",
+			boxShadow: `0px 1px 3px 0px ${theme.palette.grey[500]}`,
+			justifyContent: "center",
+			alignItems: "center",
+			margin: "0 auto",
+		};
+		return {
+			...baseStyle,
+			backgroundColor: hover
+				? theme.palette.grey[700]
+				: theme.palette.background.default,
+		};
+	}, [hover, theme]);
+	return (
+		<button
+			className="reload-button"
+			aria-label="Reload"
+			type="button"
+			style={buttonStyle}
+			onMouseEnter={() => setHover(true)}
+			onMouseLeave={() => setHover(false)}
+			onClick={(e) => {
+				e.preventDefault();
+				onReload();
+			}}
+		>
+			<svg
+				width="16px"
+				height="16px"
+				viewBox="0 0 16 16"
+				version="1.1"
+				xmlns="http://www.w3.org/2000/svg"
+				xmlnsXlink="http://www.w3.org/1999/xlink"
+				style={{ display: "flex" }}
+			>
+				<title>reload</title>
+				<path
+					shapeRendering="optimizeQuality"
+					fill={
+						hover ? theme.palette.primary.contrastText : theme.palette.grey[700]
+					}
+					transform={"scale(0.0416)"}
+					d="M234.666667,149.333333 L234.666667,106.666667 L314.564847,106.664112 C287.579138,67.9778918 242.745446,42.6666667 192,42.6666667 C109.525477,42.6666667 42.6666667,109.525477 42.6666667,192 C42.6666667,274.474523 109.525477,341.333333 192,341.333333 C268.201293,341.333333 331.072074,284.258623 340.195444,210.526102 L382.537159,215.817985 C370.807686,310.617565 289.973536,384 192,384 C85.961328,384 1.42108547e-14,298.038672 1.42108547e-14,192 C1.42108547e-14,85.961328 85.961328,1.42108547e-14 192,1.42108547e-14 C252.316171,1.42108547e-14 306.136355,27.8126321 341.335366,71.3127128 L341.333333,1.42108547e-14 L384,1.42108547e-14 L384,149.333333 L234.666667,149.333333 Z"
+				/>
+			</svg>
+		</button>
+	);
+};

package/src/reactComponents/TestModeBanner.tsx

@@ -0,0 +1,75 @@
+// 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.
+
+/** @jsxImportSource @emotion/react */
+
+import { TestSiteKeyMode, getTestSiteKeyMode } from "@prosopo/types";
+import { type FC, useEffect } from "react";
+
+interface TestModeBannerProps {
+	siteKey: string;
+}
+
+// Renders a prominent warning when the widget is configured with one of the
+// reserved CI test site keys (always-pass / always-fail). Renders nothing for a
+// normal site key. This is the user-facing safeguard that stops a test key from
+// being shipped to production unnoticed.
+export const TestModeBanner: FC<TestModeBannerProps> = ({
+	siteKey,
+}: TestModeBannerProps) => {
+	const mode: TestSiteKeyMode | null = getTestSiteKeyMode(siteKey);
+
+	useEffect(() => {
+		if (mode !== null) {
+			console.warn(
+				`[Procaptcha] WARNING: site key "${siteKey}" is a TEST key that ALWAYS ${
+					mode === TestSiteKeyMode.Pass ? "PASSES" : "FAILS"
+				}. Never use it in production.`,
+			);
+		}
+	}, [mode, siteKey]);
+
+	if (mode === null) {
+		return null;
+	}
+
+	const action =
+		mode === TestSiteKeyMode.Pass ? "ALWAYS PASSES" : "ALWAYS FAILS";
+
+	return (
+		// biome-ignore lint/a11y/useSemanticElements: the "alert" role has no native HTML element equivalent
+		<div
+			role="alert"
+			data-cy="test-mode-banner"
+			css={{
+				width: "100%",
+				boxSizing: "border-box",
+				padding: "6px 10px",
+				backgroundColor: "#fff3cd",
+				color: "#664d03",
+				border: "1px solid #ffe69c",
+				borderRadius: "4px",
+				fontSize: "11px",
+				lineHeight: "1.3",
+				fontFamily:
+					"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+				textAlign: "center",
+			}}
+		>
+			{`⚠ Test mode: this site key ${action}. Do not use in production.`}
+		</div>
+	);
+};
+
+export default TestModeBanner;

package/src/state/builder.ts

@@ -0,0 +1,137 @@
+// 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 type {
+	Account,
+	CaptchaResponseBody,
+	ProcaptchaApiInterface,
+	ProcaptchaState,
+	ProcaptchaStateUpdateFn,
+	TCaptchaSubmitResult,
+} from "@prosopo/types";
+
+type useRefType = <T>(defaultValue: T) => { current: T };
+type useStateType = <T>(defaultValue: T) => [T, (value: T) => void];
+
+export const buildUpdateState =
+	(state: ProcaptchaState, onStateUpdate: ProcaptchaStateUpdateFn) =>
+	(nextState: Partial<ProcaptchaState>) => {
+		// mutate the current state. Note that this is in order of properties in the nextState object.
+		// e.g. given {b: 2, c: 3, a: 1}, b will be set, then c, then a. This is because JS stores fields in insertion order by default, unless you override it with a class or such by changing the key enumeration order.
+		Object.assign(state, nextState);
+		// then call the update function for the frontend to do the same
+		onStateUpdate(nextState);
+	};
+
+/**
+ * Wrap a ref to be the same format as useState.
+ * @param useRef the useRef function from react
+ * @param defaultValue the default value if the state is not already initialised
+ * @returns a ref in the same format as a state, e.g. [value, setValue]
+ */
+const useRefAsState = <T>(
+	useRef: useRefType,
+	defaultValue: T,
+): [T, (value: T) => void] => {
+	const ref = useRef<T>(defaultValue);
+	const setter = (value: T) => {
+		ref.current = value;
+	};
+	const value: T = ref.current;
+	return [value, setter];
+};
+
+export const useProcaptcha = (
+	useState: useStateType,
+	useRef: useRefType,
+): [ProcaptchaState, ProcaptchaStateUpdateFn] => {
+	const [isHuman, setIsHuman] = useState(false);
+	const [index, setIndex] = useState(0);
+	const [solutions, setSolutions] = useState(
+		[] as [string, number, number][][],
+	);
+	const [captchaApi, setCaptchaApi] = useRefAsState<
+		ProcaptchaApiInterface | undefined
+	>(useRef, undefined);
+	const [showModal, setShowModal] = useState(false);
+	const [challenge, setChallenge] = useState<CaptchaResponseBody | undefined>(
+		undefined,
+	);
+	const [loading, setLoading] = useState(false);
+	const [account, setAccount] = useState<Account | undefined>(undefined);
+	const [dappAccount, setDappAccount] = useState<string | undefined>(undefined);
+	const [submission, setSubmission] = useRefAsState<
+		TCaptchaSubmitResult | undefined
+	>(useRef, undefined);
+	const [timeout, setTimeout] = useRefAsState<NodeJS.Timeout | undefined>(
+		useRef,
+		undefined,
+	);
+	const [successfullChallengeTimeout, setSuccessfullChallengeTimeout] =
+		useRefAsState<NodeJS.Timeout | undefined>(useRef, undefined);
+	const [sendData, setSendData] = useState(false);
+	const [attemptCount, setAttemptCount] = useState(0);
+	const [error, setError] = useState<
+		{ message: string; key: string } | undefined
+	>(undefined);
+	const [sessionId, setSessionId] = useState<string | undefined>(undefined);
+	return [
+		// the state
+		{
+			isHuman,
+			index,
+			solutions,
+			captchaApi,
+			showModal,
+			challenge,
+			loading,
+			account,
+			dappAccount,
+			submission,
+			timeout,
+			successfullChallengeTimeout,
+			sendData,
+			attemptCount,
+			error,
+			sessionId,
+		},
+		// and method to update the state
+		(nextState: Partial<ProcaptchaState>) => {
+			if (nextState.account !== undefined) setAccount(nextState.account);
+			if (nextState.isHuman !== undefined) setIsHuman(nextState.isHuman);
+			if (nextState.index !== undefined) setIndex(nextState.index);
+			// force a copy of the array to ensure a re-render
+			// nutshell: react doesn't look inside an array for changes, hence changes to the array need to result in a fresh array
+			if (nextState.solutions !== undefined)
+				setSolutions(nextState.solutions.slice());
+			if (nextState.captchaApi !== undefined)
+				setCaptchaApi(nextState.captchaApi);
+			if (nextState.showModal !== undefined) setShowModal(nextState.showModal);
+			if (nextState.challenge !== undefined) setChallenge(nextState.challenge);
+			if (nextState.loading !== undefined) setLoading(nextState.loading);
+			if (nextState.showModal !== undefined) setShowModal(nextState.showModal);
+			if (nextState.dappAccount !== undefined)
+				setDappAccount(nextState.dappAccount);
+			if (nextState.submission !== undefined)
+				setSubmission(nextState.submission);
+			if (nextState.timeout !== undefined) setTimeout(nextState.timeout);
+			if (nextState.successfullChallengeTimeout !== undefined)
+				setSuccessfullChallengeTimeout(nextState.timeout);
+			if (nextState.sendData !== undefined) setSendData(nextState.sendData);
+			if (nextState.attemptCount !== undefined)
+				setAttemptCount(nextState.attemptCount);
+			if (nextState.error !== undefined) setError(nextState.error);
+			if (nextState.sessionId !== undefined) setSessionId(nextState.sessionId);
+		},
+	];
+};