@prosopo/procaptcha-common 2.9.19 → 2.10.17

package/src/extensionLoader.ts

@@ -0,0 +1,17 @@
+// 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 const ExtensionLoader = async (web2: boolean) =>
+	web2
+		? (await import("@prosopo/account/extension/ExtensionWeb2")).default
+		: (await import("@prosopo/account/extension/ExtensionWeb3")).default;

package/src/index.ts

@@ -0,0 +1,24 @@
+// 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 "./providers.js";
+export * from "./state/builder.js";
+export * from "./callbacks/defaultCallbacks.js";
+export * from "./callbacks/defaultEvents.js";
+export * from "./extensionLoader.js";
+export * from "./elements/window.js";
+export * from "./reactComponents/Reload.js";
+export * from "./reactComponents/Checkbox.js";
+export * from "./reactComponents/Honeypot.js";
+export * from "./reactComponents/TestModeBanner.js";

package/src/providers.ts

@@ -0,0 +1,49 @@
+// 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 { getRandomActiveProvider } from "@prosopo/load-balancer";
+import type { EnvironmentTypes } from "@prosopo/types";
+
+export const getProcaptchaRandomActiveProvider = async (
+	defaultEnvironment: EnvironmentTypes,
+) => {
+	const randomNumberU8a = window.crypto.getRandomValues(new Uint8Array(10));
+	const randomNumber = randomNumberU8a.reduce((a, b) => a + b, 0);
+	return await getRandomActiveProvider(defaultEnvironment, randomNumber);
+};
+
+export const providerRetry = async (
+	currentFn: () => Promise<void>,
+	retryFn: () => Promise<void>,
+	stateReset: () => void,
+	attemptCount: number,
+	retryMax: number,
+) => {
+	try {
+		await currentFn();
+	} catch (err) {
+		if (attemptCount >= retryMax) {
+			console.error(err);
+			console.error(
+				`Max retries (${attemptCount} of ${retryMax}) reached, aborting`,
+			);
+			return stateReset();
+		}
+		console.error(err);
+		// hit an error, disallow user's claim to be human
+		stateReset();
+		// trigger a retry to attempt a new provider until it passes
+		await retryFn();
+	}
+};

package/src/reactComponents/Checkbox.tsx

@@ -0,0 +1,203 @@
+// 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 { css } from "@emotion/react";
+import styled from "@emotion/styled";
+import {
+	type Theme,
+	WIDGET_CHECKBOX_SPINNER_CSS_CLASS,
+} from "@prosopo/widget-skeleton";
+import {
+	type ButtonHTMLAttributes,
+	type CSSProperties,
+	type FC,
+	useMemo,
+	useState,
+} from "react";
+
+interface CheckboxProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+	theme: Theme;
+	checked: boolean;
+	// biome-ignore lint/suspicious/noExplicitAny: don't know what it will be
+	onChange: (event: any) => Promise<void>;
+	labelText: string;
+	error?: string;
+	loading: boolean;
+}
+
+const checkboxBefore = css`{
+    &:before {
+        content: '""';
+        position: absolute;
+        height: 100%;
+        width: 100%;
+    }
+}`;
+
+const baseStyle: CSSProperties = {
+	width: "28px",
+	height: "28px",
+	minWidth: "14px",
+	minHeight: "14px",
+	top: "auto",
+	left: "auto",
+	opacity: "1",
+	borderRadius: "12.5%",
+	appearance: "none",
+	cursor: "pointer",
+	margin: "0",
+	borderStyle: "solid",
+	borderWidth: "1px",
+};
+
+const ID_LETTERS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+const FAQ_LINK = process.env.PROSOPO_DOCS_URL
+	? `${new URL(`${process.env.PROSOPO_DOCS_URL}/en/basics/faq/`).href}/`
+	: "https://docs.prosopo.io/en/basics/faq/";
+
+const generateRandomId = () => {
+	return Array.from(
+		{ length: 8 },
+		() => ID_LETTERS[Math.floor(Math.random() * ID_LETTERS.length)],
+	).join("");
+};
+
+interface ResponsiveLabelProps {
+	htmFor?: string;
+}
+
+export const Checkbox: FC<CheckboxProps> = ({
+	theme,
+	onChange,
+	checked,
+	labelText,
+	error,
+	loading,
+}: CheckboxProps) => {
+	const checkboxStyleBase: CSSProperties = {
+		...baseStyle,
+		border: `1px solid ${theme.palette.background.contrastText}`,
+	};
+	const [hover, setHover] = useState(false);
+
+	const ResponsiveLabel = styled.label<ResponsiveLabelProps>`
+		color: ${theme.palette.background.contrastText};
+		position: relative;
+		display: flex !important;
+		cursor: pointer;
+		user-select: none;
+		font-weight: normal;
+		font-family: ${theme.font.fontFamily};
+		@container prosopo-widget (max-width: 169px) {
+			display: none;
+		}
+		@container prosopo-widget (min-width: 170px) {
+			font-size: 10px;
+		}
+		@container prosopo-widget (min-width: 220px) {
+			font-size: 12px;
+		}
+		@container prosopo-widget (min-width: 250px) {
+			font-size: 14px;
+		}
+		@container prosopo-widget (min-width: 270px) {
+			font-size: 16px;
+		}
+	`;
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: TODO fix
+	const checkboxStyle: CSSProperties = useMemo(() => {
+		return {
+			...checkboxStyleBase,
+			borderColor: hover
+				? theme.palette.background.contrastText
+				: theme.palette.border,
+			appearance: checked ? "auto" : "none",
+			flex: 1,
+			margin: "15px",
+			minWidth: "28px",
+			minHeight: "28px",
+		};
+	}, [hover, theme, checked]);
+	const id = generateRandomId();
+
+	return (
+		<span
+			style={{
+				display: "inline-flex",
+				alignItems: "center",
+				minHeight: "58px",
+			}}
+		>
+			{loading ? (
+				<div
+					className={WIDGET_CHECKBOX_SPINNER_CSS_CLASS}
+					aria-label="Loading spinner"
+				/>
+			) : (
+				<input
+					name={id}
+					id={id}
+					onMouseEnter={() => setHover(true)}
+					onMouseLeave={() => setHover(false)}
+					css={checkboxBefore}
+					type={"checkbox"}
+					aria-live={"assertive"}
+					aria-label={labelText}
+					onKeyDown={(e) => {
+						if (!e.isTrusted) {
+							return;
+						}
+						if (e.key === "Enter") {
+							e.preventDefault();
+							e.stopPropagation();
+							setHover(false);
+							onChange(e);
+						}
+					}}
+					onChange={(e) => {
+						if (!e.isTrusted) {
+							return;
+						}
+						e.preventDefault();
+						e.stopPropagation();
+						setHover(false);
+						onChange(e);
+					}}
+					checked={checked}
+					style={checkboxStyle}
+					disabled={error !== undefined}
+					className={loading ? "prosopo-checkbox__loading-spinner" : ""}
+					data-cy={"captcha-checkbox"}
+				/>
+			)}
+			{error ? (
+				<ResponsiveLabel htmFor={id}>
+					<a
+						css={{
+							color: theme.palette.error.main,
+						}}
+						href={FAQ_LINK}
+					>
+						{error}
+					</a>
+				</ResponsiveLabel>
+			) : (
+				<ResponsiveLabel htmFor={id}>{labelText}</ResponsiveLabel>
+			)}
+		</span>
+	);
+};
+export default Checkbox;

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;