turnstile.mjs

Functions

Imports

It imports no other module of this repo. No module of this repo imports it.

Source

1/**
2 * Cloudflare Turnstile, the bot check on a site's public forms that send email (txasm's sign-in link, Foxing's sign-up).
3 * One loader for the widget, so no site keeps its own copy.
4 *
5 * - `TURNSTILE_ORIGIN` is what a site lists under `script` and `frame` in its Content-Security-Policy sources.
6 * - `mountTurnstile(el, siteKey)` loads Cloudflare's script once per page, renders the widget into `el` and returns a
7 *   function that removes it. Browser only: call it from an effect, never during a server render.
8 * - The widget puts its token in a hidden `cf-turnstile-response` input inside `el`, so a form that holds `el` sends the
9 *   token with its other fields. `onToken` is for a form that sends it another way (Better Auth's x-captcha-response header).
10 * - The token is checked on the server, never here: `./sign-in` turns on Better Auth's captcha plugin for the email link.
11 */
12
13export const TURNSTILE_ORIGIN = "https://challenges.cloudflare.com";
14
15// render=explicit: the script must not scan the page for .cf-turnstile and render a second widget of its own.
16const SCRIPT_URL = `${TURNSTILE_ORIGIN}/turnstile/v0/api.js?render=explicit`;
17
18/**
19 * @typedef {{
20 *   render: (el: HTMLElement, options: { sitekey: string, callback?: (token: string) => void }) => string,
21 *   remove: (widgetId: string) => void,
22 * }} Turnstile
23 */
24
25/** @type {Promise<Turnstile> | undefined} */
26let loading;
27
28/** @returns {Promise<Turnstile>} */
29function loadTurnstile() {
30  const ready = /** @type {{ turnstile?: Turnstile }} */ (globalThis).turnstile;
31  if (ready) return Promise.resolve(ready);
32  loading ??= new Promise((resolve, reject) => {
33    const script = document.createElement("script");
34    script.src = SCRIPT_URL;
35    script.async = true;
36    script.onload = () => resolve(/** @type {Turnstile} */ (/** @type {{ turnstile?: Turnstile }} */ (globalThis).turnstile));
37    script.onerror = () => {
38      // Forgotten, so the next mount tries again rather than waiting on a script that never came.
39      loading = undefined;
40      script.remove();
41      reject(new Error("Turnstile's script did not load"));
42    };
43    document.head.append(script);
44  });
45  return loading;
46}
47
48/**
49 * Renders the widget into `el` once the script has loaded. The returned function removes it; called before the script
50 * loads, nothing is ever rendered (a React effect cleaned up on a quick re-render).
51 * @param {HTMLElement} el
52 * @param {string} siteKey
53 * @param {{ onToken?: (token: string) => void }} [options]
54 * @returns {() => void}
55 */
56export function mountTurnstile(el, siteKey, options = {}) {
57  /** @type {string | undefined} */
58  let widgetId;
59  let removed = false;
60  loadTurnstile().then(
61    (turnstile) => {
62      if (!removed) widgetId = turnstile.render(el, { sitekey: siteKey, callback: options.onToken });
63    },
64    (error) => console.error(error),
65  );
66  return () => {
67    removed = true;
68    if (widgetId !== undefined) /** @type {{ turnstile?: Turnstile }} */ (globalThis).turnstile?.remove(widgetId);
69  };
70}