create-astram-app 0.11.0 → 0.12.0

package/template/frontend/src/auth/CaptchaWidget.jsx

@@ -0,0 +1,108 @@
+/**
+ * CaptchaWidget — the CAPTCHA challenge on the sign-in pages (R7.6). Loads the provider's script
+ * once (an external <script src>; the CSP has no 'unsafe-inline'), renders explicitly into its
+ * own container with the endpoint's action, and keeps the solved token. The page reads it
+ * through the ref at submit time and resets the widget after each attempt (tokens are single
+ * use). reCAPTCHA v3 has no visible widget: `getToken()` runs `execute` with the action.
+ *
+ *   <CaptchaWidget ref={captchaRef} setup={setup} action={CAPTCHA_ACTIONS.login} />
+ *   const token = await captchaRef.current.getToken(); … captchaRef.current.reset();
+ *
+ * `setup` is a `{ status: 'on', provider, siteKey }` from `captchaSetup` (signInOptions.js); the
+ * page never mounts this for an off or misconfigured setup. The provider logic lives in
+ * captchaRender.js (tested with `node --test`).
+ */
+import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from 'react';
+import {
+  captchaScriptUrl,
+  loadCaptchaScript,
+  renderCaptcha,
+  whenProviderReady,
+} from './captchaRender.js';
+
+const CaptchaWidget = forwardRef(function CaptchaWidget({ setup, action }, ref) {
+  const containerRef = useRef(null);
+  const handleRef = useRef(null);
+  const tokenRef = useRef('');
+  const [failed, setFailed] = useState(false);
+  const { provider, siteKey } = setup;
+
+  useEffect(() => {
+    let live = true;
+    const url = captchaScriptUrl(provider, siteKey);
+    if (!url) {
+      setFailed(true);
+      return undefined;
+    }
+    loadCaptchaScript(url)
+      .then(() => whenProviderReady(window, provider))
+      .then(() => {
+        if (!live || !containerRef.current) return;
+        handleRef.current = renderCaptcha({
+          win: window,
+          container: containerRef.current,
+          provider,
+          siteKey,
+          action,
+          onToken: (token) => {
+            tokenRef.current = token;
+          },
+        });
+      })
+      .catch(() => {
+        if (live) setFailed(true);
+      });
+    return () => {
+      live = false;
+      try {
+        handleRef.current?.remove();
+      } catch {
+        /* the provider may already have torn the widget down */
+      }
+      handleRef.current = null;
+      tokenRef.current = '';
+    };
+  }, [provider, siteKey, action]);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      /** The token for this attempt, or '' when the challenge is not solved (or failed to load). */
+      async getToken() {
+        const handle = handleRef.current;
+        if (!handle) return '';
+        if (handle.invisible) {
+          try {
+            return (await handle.execute()) || '';
+          } catch {
+            return '';
+          }
+        }
+        return tokenRef.current;
+      },
+      /** Clear the spent token and show a fresh challenge. */
+      reset() {
+        tokenRef.current = '';
+        try {
+          handleRef.current?.reset();
+        } catch {
+          /* best-effort */
+        }
+      },
+    }),
+    [],
+  );
+
+  return (
+    <div className="space-y-1.5">
+      <div ref={containerRef} className="flex justify-center" />
+      {failed && (
+        <p role="alert" className="text-center text-sm text-destructive">
+          The verification check could not load. Check your connection and reload the page.
+        </p>
+      )}
+    </div>
+  );
+});
+
+export default CaptchaWidget;

package/template/frontend/src/auth/captchaProvider.js

@@ -0,0 +1,23 @@
+// captchaProvider.js — which CAPTCHA provider this build's CSP allows (R7.6, D-10).
+//
+// The CSP <meta> is fixed at build time from VITE_CAPTCHA_PROVIDER (vite/captchaCsp.js), while the
+// server's provider comes from `GET /auth/login-options` at run time. The login page compares the
+// two with `captchaMismatch`: on any difference it shows the fixed misconfiguration notice, logs
+// both values and loads no widget. React-free so `node --test` can run it.
+
+/** Empty or missing → null; anything else is kept as is. */
+export function normalizeProvider(value) {
+  return typeof value === 'string' && value !== '' ? value : null;
+}
+
+// `import.meta.env` exists only under Vite (it is inlined at build time); under `node --test` it is
+// undefined and the build provider is null.
+const env = import.meta.env ?? {};
+
+/** The provider this build was made for, or null when VITE_CAPTCHA_PROVIDER was unset. */
+export const BUILD_CAPTCHA_PROVIDER = normalizeProvider(env.VITE_CAPTCHA_PROVIDER);
+
+/** True when the server's and the build's providers differ, including one side unset. */
+export function captchaMismatch(serverProvider, buildProvider) {
+  return normalizeProvider(serverProvider) !== normalizeProvider(buildProvider);
+}

package/template/frontend/src/auth/captchaProvider.test.mjs

@@ -0,0 +1,44 @@
+// captchaProvider.test.mjs — R7.6 / AC-15: the login page compares the server's CAPTCHA provider
+// (`GET /auth/login-options`) with the one this build's CSP was made for (VITE_CAPTCHA_PROVIDER).
+// Any difference, including a provider on one side only, is a mismatch.
+//
+//   node --test src/auth/captchaProvider.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { BUILD_CAPTCHA_PROVIDER, captchaMismatch, normalizeProvider } from './captchaProvider.js';
+
+describe('captchaMismatch', () => {
+  test('same provider on both sides → no mismatch', () => {
+    assert.equal(captchaMismatch('turnstile', 'turnstile'), false);
+    assert.equal(captchaMismatch('recaptcha-v3', 'recaptcha-v3'), false);
+  });
+
+  test('none on both sides → no mismatch', () => {
+    assert.equal(captchaMismatch(null, null), false);
+    assert.equal(captchaMismatch(undefined, ''), false);
+  });
+
+  test('different providers → mismatch', () => {
+    assert.equal(captchaMismatch('turnstile', 'recaptcha-v3'), true);
+    assert.equal(captchaMismatch('recaptcha-v2', 'recaptcha-v3'), true);
+  });
+
+  test('provider on one side only → mismatch, either way', () => {
+    assert.equal(captchaMismatch('turnstile', null), true);
+    assert.equal(captchaMismatch(null, 'turnstile'), true);
+    assert.equal(captchaMismatch('recaptcha-v2', ''), true);
+  });
+});
+
+describe('normalizeProvider / BUILD_CAPTCHA_PROVIDER', () => {
+  test('empty or missing → null; a value is kept as is', () => {
+    assert.equal(normalizeProvider(undefined), null);
+    assert.equal(normalizeProvider(null), null);
+    assert.equal(normalizeProvider(''), null);
+    assert.equal(normalizeProvider('turnstile'), 'turnstile');
+  });
+
+  test('outside a Vite build (no import.meta.env) the build provider is null', () => {
+    assert.equal(BUILD_CAPTCHA_PROVIDER, null);
+  });
+});

package/template/frontend/src/auth/captchaRender.js

@@ -0,0 +1,125 @@
+// captchaRender.js — the provider half of <CaptchaWidget> (R7.6): which script to load, loading
+// it once as an external <script src> (the CSP has no 'unsafe-inline', so never an inline script
+// or an `onload=` URL callback), and the explicit render per provider. React-free; the browser
+// globals are passed in so `node --test` can run it with fakes.
+//
+//   turnstile     https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit
+//                 turnstile.render(el, { sitekey, action, callback, … }) → widget id
+//   recaptcha-v2  https://www.google.com/recaptcha/api.js?render=explicit (checkbox)
+//                 grecaptcha.render(el, { sitekey, callback, … }) → widget id
+//   recaptcha-v3  https://www.google.com/recaptcha/api.js?render=<siteKey> (no visible widget)
+//                 grecaptcha.execute(siteKey, { action }) at submit time
+//
+// Tokens are single use: the caller resets the widget after every attempt.
+
+const TURNSTILE_URL = 'https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit';
+const RECAPTCHA_URL = 'https://www.google.com/recaptcha/api.js';
+
+/** The provider's script URL, or null for an unknown provider. */
+export function captchaScriptUrl(provider, siteKey) {
+  if (provider === 'turnstile') return TURNSTILE_URL;
+  if (provider === 'recaptcha-v2') return `${RECAPTCHA_URL}?render=explicit`;
+  if (provider === 'recaptcha-v3') return `${RECAPTCHA_URL}?render=${encodeURIComponent(siteKey)}`;
+  return null;
+}
+
+/**
+ * A loader that appends each script URL once and shares the pending promise. A failed load is
+ * forgotten so a later mount can retry.
+ * @param {Document} doc
+ * @returns {(url: string) => Promise<void>}
+ */
+export function createScriptLoader(doc) {
+  const pending = new Map();
+  return (url) => {
+    const known = pending.get(url);
+    if (known) return known;
+    const loaded = new Promise((resolve, reject) => {
+      const el = doc.createElement('script');
+      el.src = url;
+      el.async = true;
+      el.onload = () => resolve();
+      el.onerror = () => {
+        pending.delete(url);
+        reject(new Error('CAPTCHA script failed to load'));
+      };
+      doc.head.appendChild(el);
+    });
+    pending.set(url, loaded);
+    return loaded;
+  };
+}
+
+/** Resolves once the provider's API can render (reCAPTCHA needs `grecaptcha.ready`). */
+export function whenProviderReady(win, provider) {
+  if (provider === 'turnstile') return Promise.resolve();
+  return new Promise((resolve) => {
+    if (win.grecaptcha && typeof win.grecaptcha.ready === 'function') win.grecaptcha.ready(resolve);
+    else resolve();
+  });
+}
+
+/**
+ * Render the widget into `container`. `onToken(token)` gets each solved token and '' when it
+ * expires or errors. Throws when the provider's global is missing (the script did not load).
+ * @returns {{ invisible: boolean, execute: () => Promise<string>, reset: () => void,
+ *             remove: () => void }}
+ */
+export function renderCaptcha({ win, container, provider, siteKey, action, onToken }) {
+  const clear = () => onToken('');
+  if (provider === 'turnstile') {
+    const api = win.turnstile;
+    if (!api) throw new Error('Turnstile is not loaded');
+    const id = api.render(container, {
+      sitekey: siteKey,
+      action,
+      callback: (token) => onToken(token),
+      'expired-callback': clear,
+      'error-callback': clear,
+    });
+    return {
+      invisible: false,
+      execute: async () => '',
+      reset: () => api.reset(id),
+      remove: () => api.remove?.(id),
+    };
+  }
+  const api = win.grecaptcha;
+  if (!api) throw new Error('reCAPTCHA is not loaded');
+  if (provider === 'recaptcha-v2') {
+    // The v2 checkbox has no action; the server checks the hostname (R7.4).
+    const id = api.render(container, {
+      sitekey: siteKey,
+      callback: (token) => onToken(token),
+      'expired-callback': clear,
+      'error-callback': clear,
+    });
+    return {
+      invisible: false,
+      execute: async () => '',
+      reset: () => api.reset(id),
+      remove: () => {},
+    };
+  }
+  if (provider === 'recaptcha-v3') {
+    return {
+      invisible: true,
+      execute: () =>
+        new Promise((resolve, reject) => {
+          api.ready(() => {
+            Promise.resolve(api.execute(siteKey, { action })).then(resolve, reject);
+          });
+        }),
+      reset: () => {},
+      remove: () => {},
+    };
+  }
+  throw new Error(`Unknown CAPTCHA provider: ${provider}`);
+}
+
+let browserLoader = null;
+/** The page-wide loader over `document` (created on first use). */
+export function loadCaptchaScript(url) {
+  if (!browserLoader) browserLoader = createScriptLoader(document);
+  return browserLoader(url);
+}

package/template/frontend/src/auth/captchaRender.test.mjs

@@ -0,0 +1,182 @@
+// captchaRender.test.mjs — the CAPTCHA widget's provider logic (R7.6): which script, loaded once,
+// explicit render with the endpoint's action, single-use tokens reset after each attempt.
+// The browser globals are fakes, so this runs under plain Node.
+//
+//   node --test src/auth/captchaRender.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { captchaScriptUrl, createScriptLoader, renderCaptcha } from './captchaRender.js';
+
+describe('captchaScriptUrl', () => {
+  test('turnstile → explicit render', () => {
+    assert.equal(
+      captchaScriptUrl('turnstile', 'k'),
+      'https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit',
+    );
+  });
+  test('recaptcha-v2 → explicit render', () => {
+    assert.equal(
+      captchaScriptUrl('recaptcha-v2', 'k'),
+      'https://www.google.com/recaptcha/api.js?render=explicit',
+    );
+  });
+  test('recaptcha-v3 → render=<siteKey>, encoded', () => {
+    assert.equal(
+      captchaScriptUrl('recaptcha-v3', 'a b&c'),
+      'https://www.google.com/recaptcha/api.js?render=a%20b%26c',
+    );
+  });
+  test('unknown provider → null (no script)', () => {
+    assert.equal(captchaScriptUrl('hcaptcha', 'k'), null);
+  });
+});
+
+function fakeDocument() {
+  const appended = [];
+  return {
+    appended,
+    createElement: (tag) => ({
+      tag,
+      set src(v) {
+        this._src = v;
+      },
+      get src() {
+        return this._src;
+      },
+    }),
+    head: { appendChild: (el) => appended.push(el) },
+  };
+}
+
+describe('createScriptLoader — one <script src> per URL, never inline', () => {
+  test('appends a single external script and shares the promise', async () => {
+    const doc = fakeDocument();
+    const load = createScriptLoader(doc);
+    const a = load('https://x/api.js');
+    const b = load('https://x/api.js');
+    assert.equal(a, b);
+    assert.equal(doc.appended.length, 1);
+    const el = doc.appended[0];
+    assert.equal(el.tag, 'script');
+    assert.equal(el.src, 'https://x/api.js');
+    assert.equal(el.async, true);
+    assert.equal(el.text ?? '', '');
+    el.onload();
+    await a;
+  });
+  test('a failed load rejects and a later call retries', async () => {
+    const doc = fakeDocument();
+    const load = createScriptLoader(doc);
+    const a = load('https://x/api.js');
+    doc.appended[0].onerror();
+    await assert.rejects(a);
+    load('https://x/api.js');
+    assert.equal(doc.appended.length, 2);
+  });
+});
+
+describe('renderCaptcha', () => {
+  test('turnstile: explicit render with the action; token via callback; reset clears it', () => {
+    const calls = [];
+    let opts;
+    const win = {
+      turnstile: {
+        render: (el, o) => {
+          opts = o;
+          calls.push(['render', el]);
+          return 'w1';
+        },
+        reset: (id) => calls.push(['reset', id]),
+        remove: (id) => calls.push(['remove', id]),
+      },
+    };
+    const tokens = [];
+    const h = renderCaptcha({
+      win,
+      container: 'EL',
+      provider: 'turnstile',
+      siteKey: 'sk',
+      action: 'login',
+      onToken: (t) => tokens.push(t),
+    });
+    assert.equal(opts.sitekey, 'sk');
+    assert.equal(opts.action, 'login');
+    opts.callback('tok-1');
+    assert.deepEqual(tokens, ['tok-1']);
+    opts['expired-callback']();
+    assert.deepEqual(tokens, ['tok-1', '']);
+    h.reset();
+    h.remove();
+    assert.deepEqual(calls, [
+      ['render', 'EL'],
+      ['reset', 'w1'],
+      ['remove', 'w1'],
+    ]);
+  });
+
+  test('recaptcha-v2: checkbox render (no action), reset by widget id', () => {
+    let opts;
+    const resets = [];
+    const win = {
+      grecaptcha: {
+        render: (_el, o) => {
+          opts = o;
+          return 7;
+        },
+        reset: (id) => resets.push(id),
+      },
+    };
+    const tokens = [];
+    const h = renderCaptcha({
+      win,
+      container: 'EL',
+      provider: 'recaptcha-v2',
+      siteKey: 'sk',
+      action: 'login',
+      onToken: (t) => tokens.push(t),
+    });
+    assert.equal(opts.sitekey, 'sk');
+    assert.equal('action' in opts, false);
+    opts.callback('tok-2');
+    assert.deepEqual(tokens, ['tok-2']);
+    h.reset();
+    assert.deepEqual(resets, [7]);
+  });
+
+  test('recaptcha-v3: no visible widget; execute(siteKey, {action}) gives the token', async () => {
+    const executed = [];
+    const win = {
+      grecaptcha: {
+        ready: (cb) => cb(),
+        execute: async (key, o) => {
+          executed.push([key, o.action]);
+          return 'tok-3';
+        },
+      },
+    };
+    const h = renderCaptcha({
+      win,
+      container: 'EL',
+      provider: 'recaptcha-v3',
+      siteKey: 'sk',
+      action: 'forgot_password',
+      onToken: () => {},
+    });
+    assert.equal(h.invisible, true);
+    assert.equal(await h.execute(), 'tok-3');
+    assert.deepEqual(executed, [['sk', 'forgot_password']]);
+  });
+
+  test('provider global missing → throws (the caller shows an error, never a fake token)', () => {
+    assert.throws(() =>
+      renderCaptcha({
+        win: {},
+        container: 'EL',
+        provider: 'turnstile',
+        siteKey: 'sk',
+        action: 'login',
+        onToken: () => {},
+      }),
+    );
+  });
+});

package/template/frontend/src/auth/passwordVisibility.js

@@ -0,0 +1,9 @@
+// passwordVisibility.js — the show/hide toggle on a password field (R13.5, AC-22): the input
+// type and the toggle button's accessible label, the same wording as the login page.
+
+/** @param {boolean} shown */
+export function passwordVisibility(shown) {
+  return shown
+    ? { type: 'text', toggleLabel: 'Hide password' }
+    : { type: 'password', toggleLabel: 'Show password' };
+}

package/template/frontend/src/auth/passwordVisibility.test.mjs

@@ -0,0 +1,12 @@
+// passwordVisibility.test.mjs — the show/hide toggle on the reset / set-password fields (R13.5,
+// AC-22): "toggles password visibility" with an accessible label.
+//
+//   node --test src/auth/passwordVisibility.test.mjs
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { passwordVisibility } from './passwordVisibility.js';
+
+test('toggles password visibility', () => {
+  assert.deepEqual(passwordVisibility(false), { type: 'password', toggleLabel: 'Show password' });
+  assert.deepEqual(passwordVisibility(true), { type: 'text', toggleLabel: 'Hide password' });
+});

package/template/frontend/src/auth/reenrollWording.js

@@ -0,0 +1,29 @@
+// reenrollWording.js — the enrolment screen's words per restriction reason (R2.3, R13.2).
+// Both reasons pin the session to the same page (`/account/reenroll`); only the framing differs:
+// `reenroll` after a recovery-code sign-in, `mfa_enrollment` when a security policy requires 2FA
+// and the account has none.
+
+const REENROLL = Object.freeze({
+  title: 'Finish securing your account',
+  body:
+    'You signed in with a recovery code. Add a new authenticator device below to re-secure your ' +
+    'account — the rest of the app stays locked until you do.',
+  securedTitle: 'Your account is secured again',
+  securedBody:
+    'A new authenticator device is active. Save any recovery codes shown below, then continue.',
+});
+
+const MFA_ENROLLMENT = Object.freeze({
+  title: 'Set up two-step verification',
+  body:
+    'Your organisation requires two-step verification for your account. Add an authenticator ' +
+    'device below — the rest of the app stays locked until you do.',
+  securedTitle: 'Two-step verification is on',
+  securedBody:
+    'Your authenticator device is active. Save the recovery codes shown below, then continue.',
+});
+
+/** @param {'reenroll' | 'mfa_enrollment' | null | undefined} reason */
+export function reenrollWording(reason) {
+  return reason === 'mfa_enrollment' ? MFA_ENROLLMENT : REENROLL;
+}

package/template/frontend/src/auth/reenrollWording.test.mjs

@@ -0,0 +1,23 @@
+// reenrollWording.test.mjs — the enrolment screen's heading follows the restriction reason
+// (R2.3, R13.2): re-enrol after a recovery-code login, or first enrolment required by policy.
+//
+//   node --test src/auth/reenrollWording.test.mjs
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { reenrollWording } from './reenrollWording.js';
+
+test('mfa_enrollment → the policy wording', () => {
+  const w = reenrollWording('mfa_enrollment');
+  assert.equal(w.title, 'Set up two-step verification');
+  assert.match(w.body, /organisation requires two-step verification/);
+  assert.equal(w.securedTitle, 'Two-step verification is on');
+});
+
+test('reenroll, null or unknown → the recovery-code wording (unchanged)', () => {
+  for (const reason of ['reenroll', null, undefined, 'other']) {
+    const w = reenrollWording(reason);
+    assert.equal(w.title, 'Finish securing your account');
+    assert.match(w.body, /recovery code/);
+    assert.equal(w.securedTitle, 'Your account is secured again');
+  }
+});

package/template/frontend/src/auth/routeGate.js

@@ -6,6 +6,16 @@
 /** The single forced-re-enroll screen path (the enforcement's frontend twin). */
 export const REENROLL_PATH = '/account/reenroll';
 
+/**
+ * Where a restricted session is pinned (R2.3, R13.2). Both reasons — `reenroll` (after a
+ * recovery-code sign-in) and `mfa_enrollment` (a policy requires 2FA and none is set up) — use
+ * the same enrolment page; the page words its heading per reason. No reason → null.
+ * @param {'reenroll' | 'mfa_enrollment' | null | undefined} reason
+ */
+export function restrictionPath(reason) {
+  return reason === 'reenroll' || reason === 'mfa_enrollment' ? REENROLL_PATH : null;
+}
+
 /**
  * `factsReady` is true once the auth-facts projection has resolved for this session. A failed
  * load resolves to an EMPTY projection (the SDK is fail-closed), so it is "ready" with no

package/template/frontend/src/auth/routeGate.test.mjs

@@ -5,7 +5,7 @@
 //   node --test src/auth/routeGate.test.mjs
 import { test, describe } from 'node:test';
 import assert from 'node:assert/strict';
-import { decideRoute, REENROLL_PATH } from './routeGate.js';
+import { decideRoute, REENROLL_PATH, restrictionPath } from './routeGate.js';
 
 const base = { isAuthenticated: true, mustReenroll: false, pathname: '/users', canGate: false };
 
@@ -57,3 +57,24 @@ describe('decideRoute', () => {
     );
   });
 });
+
+// R2.3, R13.2, AC-25: a 403 mfa_enrollment_required routes to the same enrolment page as
+// reenrollment_required.
+describe('restrictionPath', () => {
+  test('both restriction reasons → the enrolment page', () => {
+    assert.equal(restrictionPath('reenroll'), REENROLL_PATH);
+    assert.equal(restrictionPath('mfa_enrollment'), REENROLL_PATH);
+  });
+  test('no reason → null', () => {
+    assert.equal(restrictionPath(null), null);
+    assert.equal(restrictionPath(undefined), null);
+  });
+  test('an mfa_enrollment restriction pins every other route like re-enrol', () => {
+    const mustReenroll = restrictionPath('mfa_enrollment') !== null;
+    assert.equal(decideRoute({ ...base, mustReenroll, factsReady: true }), 'reenroll');
+    assert.equal(
+      decideRoute({ ...base, mustReenroll, pathname: REENROLL_PATH, factsReady: true }),
+      'render',
+    );
+  });
+});