@prosopo/procaptcha-common 2.14.2 → 2.15.0

package/src/clientMetaData.ts

@@ -13,6 +13,7 @@
 // limitations under the License.
 
 import type { ClientMetaData } from "@prosopo/types";
+import { resolveClientSessionId } from "./protectSession.js";
 
 /**
  * Assembles the widget-controlled metadata attached to a captcha solution.
@@ -22,6 +23,12 @@ import type { ClientMetaData } from "@prosopo/types";
  * Returns `undefined` when nothing is set, so the submission body omits the
  * key entirely rather than carrying an empty object.
  *
+ * A site that renders no session id of its own but runs Prosopo Protect falls
+ * back to Protect's session id, which is the same value Protect's own
+ * challenge page renders the widget with. Read here rather than at render time
+ * because Protect initialises asynchronously and may not have a session yet
+ * when the widget mounts.
+ *
  * @param hp - live honeypot input value, if the honeypot was filled in
  * @param clientSessionId - the site's session id, if the widget was rendered
  *   with `data-sessionid` / `renderOptions.sessionId`
@@ -30,9 +37,10 @@ export const buildClientMetaData = (
 	hp?: string,
 	clientSessionId?: string,
 ): ClientMetaData | undefined => {
+	const sessionId = resolveClientSessionId(clientSessionId);
 	const clientMetaData: ClientMetaData = {
 		...(hp && { hp }),
-		...(clientSessionId && { clientSessionId }),
+		...(sessionId && { clientSessionId: sessionId }),
 	};
 
 	return Object.keys(clientMetaData).length > 0 ? clientMetaData : undefined;

package/src/index.ts

@@ -14,6 +14,7 @@
 
 export * from "./providers.js";
 export * from "./clientMetaData.js";
+export * from "./protectSession.js";
 export * from "./events/trust.js";
 export * from "./state/builder.js";
 export * from "./callbacks/defaultCallbacks.js";

package/src/protectSession.ts

@@ -0,0 +1,110 @@
+// 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 { INPUT_LIMITS } from "@prosopo/types";
+
+const PROTECT_GLOBAL = "prosopo_protect";
+const PROTECT_COOKIE = "prosopo_session";
+
+type ProtectGlobal = {
+	jti?: unknown;
+};
+
+const isProtectGlobal = (value: unknown): value is ProtectGlobal =>
+	typeof value === "object" && value !== null;
+
+/**
+ * `bumblebee-<uuid>` today, but the prefix names the edge that issued the
+ * session, so this only rejects what could not be an id at all.
+ *
+ * The length bound is load-bearing rather than defensive: the provider caps
+ * `clientSessionId` at `INPUT_LIMITS.ID` and rejects the whole solution body
+ * when it is longer, so an oversized value here would fail the solve rather
+ * than just losing the correlation.
+ */
+const isUsableJti = (value: string): boolean =>
+	value.length > 0 &&
+	value.length <= INPUT_LIMITS.ID &&
+	/^[A-Za-z0-9._-]+$/.test(value);
+
+const readGlobalJti = (): string | undefined => {
+	const global: unknown = Reflect.get(window, PROTECT_GLOBAL);
+	if (!isProtectGlobal(global) || typeof global.jti !== "string") {
+		return undefined;
+	}
+	const jti = global.jti.trim();
+	return isUsableJti(jti) ? jti : undefined;
+};
+
+const readCookieJti = (): string | undefined => {
+	if (typeof document === "undefined") {
+		return undefined;
+	}
+	for (const pair of document.cookie.split(";")) {
+		const separator = pair.indexOf("=");
+		if (
+			separator === -1 ||
+			pair.slice(0, separator).trim() !== PROTECT_COOKIE
+		) {
+			continue;
+		}
+		// The cookie is `{jti}|{jwt}`. The second half is a bearer token for the
+		// Protect session and must never leave the page.
+		const jti = pair
+			.slice(separator + 1)
+			.trim()
+			.split("|")[0];
+		return jti !== undefined && isUsableJti(jti) ? jti : undefined;
+	}
+	return undefined;
+};
+
+/**
+ * The Protect session id (JTI) for this page, when the site runs Prosopo
+ * Protect alongside the captcha.
+ *
+ * Protect publishes it two ways, both read here: `window.prosopo_protect.jti`,
+ * and the `prosopo_session` cookie it sets on the registrable domain (so a
+ * session minted at `protect.example.com` is visible on `www.example.com`).
+ * The global is preferred — it is the value Protect itself is using, whereas
+ * the cookie may have been rewritten by anything on the page.
+ *
+ * Undefined whenever the site does not run Protect, the widget is embedded
+ * cross-origin, or Protect has not finished initialising. Every caller treats
+ * that as "no correlation available", never as a fault.
+ */
+export const getProtectJti = (): string | undefined => {
+	if (typeof window === "undefined") {
+		return undefined;
+	}
+	try {
+		return readGlobalJti() ?? readCookieJti();
+	} catch {
+		// `document.cookie` throws in a sandboxed iframe, and a page is free to
+		// define `prosopo_protect` as a throwing getter.
+		return undefined;
+	}
+};
+
+/**
+ * The session id this widget reports to the provider: whatever the site asked
+ * for, and Protect's session id only when the site asked for nothing.
+ *
+ * One function so the precedence is stated once — the frictionless request and
+ * the solution submit have to agree on it, or the provider's own
+ * mismatch check would fire on a session it built both halves of.
+ */
+export const resolveClientSessionId = (
+	clientSessionId?: string,
+): string | undefined => clientSessionId || getProtectJti();

package/src/tests/clientMetaData.test.ts

@@ -12,9 +12,19 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 import { buildClientMetaData } from "../clientMetaData.js";
 
+const PROTECT_JTI = "bumblebee-0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0";
+
+const runProtect = (): void => {
+	Reflect.set(window, "prosopo_protect", { jti: PROTECT_JTI, ready: true });
+};
+
+afterEach(() => {
+	Reflect.deleteProperty(window, "prosopo_protect");
+});
+
 describe("buildClientMetaData", () => {
 	it("returns undefined when the widget has nothing to report", () => {
 		expect(buildClientMetaData(undefined, undefined)).toBeUndefined();
@@ -42,4 +52,20 @@ describe("buildClientMetaData", () => {
 			clientSessionId: "jti-1",
 		});
 	});
+
+	it("falls back to Protect's session id when the site rendered none", () => {
+		runProtect();
+
+		expect(buildClientMetaData(undefined, undefined)).toEqual({
+			clientSessionId: PROTECT_JTI,
+		});
+	});
+
+	it("leaves the site's own session id alone when Protect is also present", () => {
+		runProtect();
+
+		expect(buildClientMetaData(undefined, "site-session-1")).toEqual({
+			clientSessionId: "site-session-1",
+		});
+	});
 });

package/src/tests/protectSession.test.ts

@@ -0,0 +1,148 @@
+// 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 { INPUT_LIMITS } from "@prosopo/types";
+import { afterEach, describe, expect, it } from "vitest";
+import { getProtectJti, resolveClientSessionId } from "../protectSession.js";
+
+const JTI = "bumblebee-0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0";
+const JWT = "eyJhbGciOiJzcjI1NTE5In0.eyJqdGkiOiJ4In0.c2lnbmF0dXJl";
+
+const setCookie = (value: string): void => {
+	document.cookie = `prosopo_session=${value}; path=/`;
+};
+
+const clearCookie = (): void => {
+	document.cookie = "prosopo_session=; path=/; max-age=0";
+};
+
+const setGlobal = (value: unknown): void => {
+	Reflect.set(window, "prosopo_protect", value);
+};
+
+afterEach(() => {
+	Reflect.deleteProperty(window, "prosopo_protect");
+	clearCookie();
+});
+
+describe("getProtectJti", () => {
+	it("returns undefined when the site does not run Protect", () => {
+		expect(getProtectJti()).toBeUndefined();
+	});
+
+	it("reads the jti from the Protect global", () => {
+		setGlobal({ version: "0.1.0", jti: JTI, ready: true });
+
+		expect(getProtectJti()).toBe(JTI);
+	});
+
+	it("falls back to the session cookie when the global has no jti yet", () => {
+		setGlobal({ version: "0.1.0", ready: false });
+		setCookie(`${JTI}|${JWT}`);
+
+		expect(getProtectJti()).toBe(JTI);
+	});
+
+	it("never returns the jwt half of the cookie", () => {
+		setCookie(`${JTI}|${JWT}`);
+
+		const jti = getProtectJti();
+
+		expect(jti).toBe(JTI);
+		expect(jti).not.toContain(JWT);
+	});
+
+	it("reads a cookie that carries the jti alone", () => {
+		setCookie(JTI);
+
+		expect(getProtectJti()).toBe(JTI);
+	});
+
+	it("ignores an empty jti in the cookie", () => {
+		setCookie(`|${JWT}`);
+
+		expect(getProtectJti()).toBeUndefined();
+	});
+
+	it("ignores other cookies whose name merely ends in the same suffix", () => {
+		document.cookie = `not_prosopo_session=${JTI}; path=/`;
+
+		expect(getProtectJti()).toBeUndefined();
+
+		document.cookie = "not_prosopo_session=; path=/; max-age=0";
+	});
+
+	// The provider caps clientSessionId at INPUT_LIMITS.ID and rejects the whole
+	// solution body when it is longer, so an oversized value has to be dropped
+	// here rather than failing the solve.
+	it("ignores a jti longer than the provider accepts", () => {
+		setGlobal({ jti: "a".repeat(INPUT_LIMITS.ID + 1) });
+
+		expect(getProtectJti()).toBeUndefined();
+	});
+
+	it("accepts a jti exactly at the limit", () => {
+		const atLimit = "a".repeat(INPUT_LIMITS.ID);
+		setGlobal({ jti: atLimit });
+
+		expect(getProtectJti()).toBe(atLimit);
+	});
+
+	it("ignores a jti containing characters an id cannot have", () => {
+		setGlobal({ jti: "bumblebee-<script>" });
+
+		expect(getProtectJti()).toBeUndefined();
+	});
+
+	it("ignores a non-string jti", () => {
+		setGlobal({ jti: 42 });
+
+		expect(getProtectJti()).toBeUndefined();
+	});
+
+	it("survives a page that defines the global as a throwing getter", () => {
+		Object.defineProperty(window, "prosopo_protect", {
+			configurable: true,
+			get: () => {
+				throw new Error("nope");
+			},
+		});
+
+		expect(getProtectJti()).toBeUndefined();
+	});
+});
+
+describe("resolveClientSessionId", () => {
+	it("prefers the session id the site rendered the widget with", () => {
+		setGlobal({ jti: JTI });
+
+		expect(resolveClientSessionId("site-session-1")).toBe("site-session-1");
+	});
+
+	it("falls back to Protect when the site rendered no session id", () => {
+		setGlobal({ jti: JTI });
+
+		expect(resolveClientSessionId(undefined)).toBe(JTI);
+	});
+
+	it("treats an empty site session id as none", () => {
+		setGlobal({ jti: JTI });
+
+		expect(resolveClientSessionId("")).toBe(JTI);
+	});
+
+	it("returns undefined when neither is available", () => {
+		expect(resolveClientSessionId(undefined)).toBeUndefined();
+	});
+});