create-astram-app 0.11.1 → 0.12.0

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

@@ -3,18 +3,38 @@
  */
 
 /**
- * Establish a session after login / MFA: persist it, then fetch the display profile and the
- * auth-facts projection.
+ * The scope the ShieldClient caches a projection under: the session's tenant and session id,
+ * so a projection fetched for one session or tenant is never served to another (KI #139).
+ *
+ * @param {{ tenantId?: string, sessionId?: string } | null | undefined} session
+ * @returns {{ tenantId: string | null, sessionId: string | null }}
+ */
+export function factsScopeOf(session) {
+  return { tenantId: session?.tenantId ?? null, sessionId: session?.sessionId ?? null };
+}
+
+/**
+ * Establish a session after login / MFA: reset the ShieldClient, persist the session, then
+ * fetch the display profile and the auth-facts projection.
+ *
+ * The reset comes first (KI #139): the ShieldClient is built once and outlives sessions, and a
+ * projection cached for the previous session would otherwise be served while the permission
+ * version has not moved (a root grant applied by a restart moves nothing).
  *
  * @param {{ session: object, tokens: { accessToken?: string }, identityHint?: string }} input
  * @param {{
+ *   resetShield: () => void,
  *   persist: (state: object) => void,
  *   setCurrentToken: (token: string | null) => void,
  *   loadProfile: (accessToken: string | undefined) => Promise<void>,
- *   refreshAuthFacts: (principalId: string | null) => Promise<void>,
+ *   refreshAuthFacts: (
+ *     principalId: string | null,
+ *     scope: { tenantId: string | null, sessionId: string | null },
+ *   ) => Promise<void>,
  * }} deps
  */
 export async function establishSession({ session, tokens, identityHint }, deps) {
+  deps.resetShield();
   deps.persist({ session, tokens, identityHint });
   // `persist` is a React setState: the token ref the shield transport reads is only synced on
   // the NEXT render. Publish the new token now, or the first auth-facts fetch goes out with no
@@ -22,6 +42,62 @@ export async function establishSession({ session, tokens, identityHint }, deps)
   deps.setCurrentToken(tokens?.accessToken ?? null);
   await Promise.all([
     deps.loadProfile(tokens?.accessToken),
-    deps.refreshAuthFacts(session?.principalId ?? null),
+    deps.refreshAuthFacts(session?.principalId ?? null, factsScopeOf(session)),
+  ]);
+}
+
+/**
+ * Drop everything derived from a session that must not outlive it: the ShieldClient's cached
+ * projection and step-up state (KI #139), the display profile, the auth facts and the
+ * re-enroll restriction. Runs on sign-out, session expiry and a session change in another tab.
+ *
+ * @param {{
+ *   resetShield: () => void,
+ *   setProfile: (profile: null) => void,
+ *   setAuthFacts: (facts: null) => void,
+ *   clearReenroll: () => void,
+ * }} deps
+ */
+export function clearSessionViews(deps) {
+  deps.resetShield();
+  deps.setProfile(null);
+  deps.setAuthFacts(null); // fail-closed: no session -> no cached facts to (mis)trust
+  deps.clearReenroll();
+}
+
+/**
+ * After a device confirm (account Two-factor page, or the restricted re-enroll screen): the server
+ * has already lifted a `reenroll` / `mfa_enrollment` restriction and dropped the grace deadline on
+ * the SAME token, but the client still holds what it fetched before. Reset the ShieldClient (its
+ * cached projection is the restricted one and the permission version has not moved, KI #139),
+ * refetch the auth facts and `/auth/me` (the grace banner reads its deadline), and only then lift
+ * the local restriction, so the user lands on a page whose nav and gates are already loaded (no
+ * flash of "denied"). A failed refetch still lifts it: the server has, and the poll catches up.
+ *
+ * @param {{
+ *   resetShield: () => void,
+ *   refreshAuthFacts: () => Promise<void>,
+ *   loadProfile: () => Promise<void>,
+ *   clearRestriction: () => void,
+ * }} deps
+ */
+export async function afterDeviceConfirmed(deps) {
+  deps.resetShield();
+  await Promise.allSettled([
+    Promise.resolve().then(() => deps.refreshAuthFacts()),
+    Promise.resolve().then(() => deps.loadProfile()),
   ]);
+  deps.clearRestriction();
+}
+
+/**
+ * Classify a session change another tab wrote to storage.
+ *
+ * @param {string | null | undefined} prevSessionId this tab's session id before the change
+ * @param {{ session?: { sessionId?: string } } | null | undefined} next the stored session
+ * @returns {'signed-out' | 'switched' | 'rotated'} `rotated` = same session, new tokens
+ */
+export function crossTabChange(prevSessionId, next) {
+  if (!next) return 'signed-out';
+  return next.session?.sessionId !== prevSessionId ? 'switched' : 'rotated';
 }

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

@@ -5,7 +5,15 @@
 //   node --test src/auth/sessionFlow.test.mjs
 import { test, describe } from 'node:test';
 import assert from 'node:assert/strict';
-import { establishSession } from './sessionFlow.js';
+import { readFileSync } from 'node:fs';
+import { createShieldClient } from '@astram/sdk';
+import {
+  afterDeviceConfirmed,
+  clearSessionViews,
+  crossTabChange,
+  establishSession,
+  factsScopeOf,
+} from './sessionFlow.js';
 import { createWebShieldTransport } from '../platform/shieldTransport.js';
 
 const fake = (label) => `fake-${label}`;
@@ -31,6 +39,7 @@ describe('establishSession', () => {
     await establishSession(
       { session: { principalId: 'p1' }, tokens: { accessToken: ACCESS }, identityHint: 'a' },
       {
+        resetShield: () => {},
         persist: () => {}, // setState: the ref is NOT updated until a later render
         setCurrentToken: (t) => {
           tokenRef.current = t;
@@ -51,6 +60,7 @@ describe('establishSession', () => {
     await establishSession(
       { session: { principalId: 'p1' }, tokens: { accessToken: ACCESS } },
       {
+        resetShield: () => {},
         persist: () => order.push('persist'),
         setCurrentToken: () => order.push('token'),
         loadProfile: async (t) => order.push(`profile:${t === ACCESS}`),
@@ -61,3 +71,204 @@ describe('establishSession', () => {
     assert.deepEqual(order.slice(2).sort(), ['facts:p1', 'profile:true']);
   });
 });
+
+// KI #139 (NAES beta 2026-10-15): a user was added to SHIELD_ROOT_IDS, the server restarted, and
+// the user signed out and in again in the same tab. /identity/auth-facts returned the admin keys,
+// but the admin nav stayed empty until a full reload: the ShieldClient (built once) kept the
+// previous session's projection and served it while the permission version had not moved.
+describe('session boundaries reset the ShieldClient (KI #139)', () => {
+  const S1 = { sessionId: 's-1', principalId: 'p1', tenantId: 't-1' };
+  const S2 = { sessionId: 's-2', principalId: 'p1', tenantId: 't-1' };
+
+  test('establishSession resets the client before fetching facts, scoped to the session', async () => {
+    const order = [];
+    await establishSession(
+      { session: S1, tokens: { accessToken: ACCESS } },
+      {
+        resetShield: () => order.push('reset'),
+        persist: () => order.push('persist'),
+        setCurrentToken: () => order.push('token'),
+        loadProfile: async () => order.push('profile'),
+        refreshAuthFacts: async (p, scope) => order.push(`facts:${p}:${JSON.stringify(scope)}`),
+      },
+    );
+    assert.equal(order[0], 'reset');
+    assert.ok(order.includes('facts:p1:{"tenantId":"t-1","sessionId":"s-1"}'), order.join(' '));
+  });
+
+  test('clearSessionViews resets the client and clears every session view', () => {
+    const calls = [];
+    clearSessionViews({
+      resetShield: () => calls.push('reset'),
+      setProfile: (v) => calls.push(`profile:${v}`),
+      setAuthFacts: (v) => calls.push(`facts:${v}`),
+      clearReenroll: () => calls.push('reenroll'),
+    });
+    assert.deepEqual(calls, ['reset', 'profile:null', 'facts:null', 'reenroll']);
+  });
+
+  test('crossTabChange tells a sign-out and a different session from a token rotation', () => {
+    assert.equal(crossTabChange('s-1', null), 'signed-out');
+    assert.equal(crossTabChange('s-1', { session: S2 }), 'switched');
+    assert.equal(crossTabChange(null, { session: S1 }), 'switched');
+    assert.equal(crossTabChange('s-1', { session: S1 }), 'rotated');
+  });
+
+  test('factsScopeOf keys the projection by tenant and session', () => {
+    assert.deepEqual(factsScopeOf(S1), { tenantId: 't-1', sessionId: 's-1' });
+    assert.deepEqual(factsScopeOf(null), { tenantId: null, sessionId: null });
+  });
+
+  test('sign out, become root, sign in again: the new session sees the root facts', async () => {
+    // The server: same tenant version before and after the restart (nothing bumped it).
+    const server = { facts: [{ action: 'identity:user:read', allowed: true }], version: 4 };
+    const http = {
+      get: async (path) =>
+        path === '/identity/auth-facts'
+          ? {
+              ok: true,
+              status: 200,
+              data: {
+                principalId: 'p1',
+                facts: server.facts,
+                projectedAt: 1,
+                permissionsVersion: server.version,
+              },
+            }
+          : { ok: true, status: 200, data: { version: server.version } },
+    };
+    const shield = createShieldClient({
+      transport: createWebShieldTransport({ http, getToken: () => ACCESS }),
+    });
+    let authFacts = null;
+    const sessionDeps = {
+      resetShield: () => shield.reset(),
+      persist: () => {},
+      setCurrentToken: () => {},
+      loadProfile: async () => {},
+      refreshAuthFacts: async (p, scope) => {
+        authFacts = await shield.getAuthFacts(p, scope);
+      },
+    };
+
+    await establishSession({ session: S1, tokens: { accessToken: ACCESS } }, sessionDeps);
+    assert.deepEqual(
+      authFacts.facts.map((f) => f.action),
+      ['identity:user:read'],
+    );
+
+    // Sign out (AuthContext.logout → resetSessionViews), then the server restarts with the
+    // user in SHIELD_ROOT_IDS.
+    clearSessionViews({
+      resetShield: () => shield.reset(),
+      setProfile: () => {},
+      setAuthFacts: (v) => {
+        authFacts = v;
+      },
+      clearReenroll: () => {},
+    });
+    server.facts = [
+      { action: 'identity:user:read', allowed: true },
+      { action: 'identity:role:update', allowed: true },
+    ];
+
+    await establishSession({ session: S2, tokens: { accessToken: ACCESS } }, sessionDeps);
+    assert.deepEqual(
+      authFacts.facts.map((f) => f.action),
+      ['identity:user:read', 'identity:role:update'],
+    );
+  });
+
+  // AuthContext.jsx is JSX (no runner here), so check its wiring to the helpers above.
+  test('AuthContext wires every session boundary to the reset', () => {
+    const src = readFileSync(new URL('./AuthContext.jsx', import.meta.url), 'utf8');
+    const count = (needle) => src.split(needle).length - 1;
+    // resetSessionViews (logout, expiry, cross-tab), establishSession (login, MFA) and
+    // deviceConfirmed (a device confirm lifts a restriction) all reset.
+    assert.equal(count('resetShield: () => shield.reset()'), 3);
+    assert.ok(src.includes('clearSessionViews({'), 'resetSessionViews uses clearSessionViews');
+    const logout = src.slice(src.indexOf('const logout = async'), src.indexOf('rawAuth.logout('));
+    assert.ok(logout.includes('resetSessionViews()'), 'logout resets the session views');
+    const at = src.lastIndexOf('expired: () => {'); // the first one is the ref's no-op default
+    const expired = src.slice(at, at + 300);
+    assert.ok(expired.includes('resetSessionViews()'), 'expiry resets the session views');
+    assert.ok(src.includes('crossTabChange(prevSessionId, next)'), 'cross-tab change classified');
+    // Every facts fetch is scoped to the session it is for.
+    assert.equal(count('shield.getAuthFacts(principalId, scope)'), 1);
+    assert.ok(!/refreshAuthFacts\(principalOf\([a-z]+\)\)/.test(src), 'no unscoped facts fetch');
+  });
+});
+
+// QA pass 1 (P1): after a device confirm on a restricted session (reenroll / mfa_enrollment) the
+// nav and gated pages stayed denied until the 60 s poll, and the grace banner stayed: nothing
+// refetched the auth facts (the ShieldClient still held the restricted projection) or /auth/me.
+describe('afterDeviceConfirmed', () => {
+  test('resets the client, refetches facts and profile, then lifts the restriction', async () => {
+    const calls = [];
+    let releaseFacts;
+    const factsDone = new Promise((r) => (releaseFacts = r));
+    const run = afterDeviceConfirmed({
+      resetShield: () => calls.push('reset'),
+      refreshAuthFacts: async () => {
+        calls.push('facts:start');
+        await factsDone;
+        calls.push('facts:done');
+      },
+      loadProfile: async () => calls.push('profile'),
+      clearRestriction: () => calls.push('clear'),
+    });
+    await Promise.resolve();
+    assert.ok(
+      !calls.includes('clear'),
+      'restriction kept until the facts are back (no deny flash)',
+    );
+    releaseFacts();
+    await run;
+    assert.equal(calls[0], 'reset', 'reset before any fetch (KI #139)');
+    assert.ok(calls.indexOf('facts:done') < calls.indexOf('clear'));
+    assert.ok(calls.indexOf('profile') < calls.indexOf('clear'));
+    assert.equal(calls.at(-1), 'clear');
+  });
+
+  test('a failed refetch still lifts the restriction (server already lifted it)', async () => {
+    const calls = [];
+    await afterDeviceConfirmed({
+      resetShield: () => {},
+      refreshAuthFacts: async () => {
+        throw new Error('down');
+      },
+      loadProfile: async () => {
+        throw new Error('down');
+      },
+      clearRestriction: () => calls.push('clear'),
+    });
+    assert.deepEqual(calls, ['clear']);
+  });
+
+  test('the template wires every device confirm through it', () => {
+    const ctx = readFileSync(new URL('./AuthContext.jsx', import.meta.url), 'utf8');
+    assert.ok(ctx.includes('afterDeviceConfirmed({'), 'AuthContext runs afterDeviceConfirmed');
+    assert.ok(/deviceConfirmed[,:]/.test(ctx), 'useAuth() exposes deviceConfirmed');
+    const two = readFileSync(
+      new URL('../pages/account/TwoFactorPage.jsx', import.meta.url),
+      'utf8',
+    );
+    const confirm = two.slice(
+      two.indexOf('const onConfirm = async'),
+      two.indexOf('// ---- Rename'),
+    );
+    assert.ok(
+      confirm.includes('await deviceConfirmed()'),
+      'TwoFactorPage refetches on every confirm, with or without a parent callback',
+    );
+    assert.ok(
+      confirm.indexOf('await deviceConfirmed()') < confirm.indexOf('onDeviceConfirmed?.()'),
+      'parent callback after the refetch',
+    );
+    const reenroll = readFileSync(
+      new URL('../pages/account/ReenrollPage.jsx', import.meta.url),
+      'utf8',
+    );
+    assert.ok(!reenroll.includes('clearReenroll()'), 'ReenrollPage no longer lifts the gate early');
+  });
+});

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

@@ -0,0 +1,64 @@
+// signInOptions.js — the sign-in pages' label and CAPTCHA decisions (R13.2, R7.6, D-10).
+//
+// `GET /auth/login-options` (via `authService.loginOptions()`) says which names the server
+// accepts and whether CAPTCHA is on. The page label follows `signInWith`; the CAPTCHA widget
+// loads only when the server's provider matches the one this build's CSP allows
+// (`BUILD_CAPTCHA_PROVIDER`), otherwise the page shows a fixed notice and loads nothing.
+// React-free so `node --test` can run it; the pages stay thin views over these rules.
+import { captchaMismatch } from './captchaProvider.js';
+
+/** The fixed misconfiguration notice (R7.6): server and build name different providers. */
+export const MISCONFIGURED_NOTICE =
+  'Sign-in protection is misconfigured, contact your administrator';
+
+/** The CAPTCHA action per endpoint; the server checks it (R7.4). */
+export const CAPTCHA_ACTIONS = Object.freeze({
+  login: 'login',
+  forgot: 'forgot_password',
+  reset: 'reset_password',
+});
+
+/**
+ * The sign-in field label. "Email" until the options are known (or when they fail to load),
+ * "Email or username" once the server says login names are accepted.
+ * @param {string[] | null | undefined} signInWith
+ */
+export function signInLabel(signInWith) {
+  return Array.isArray(signInWith) && signInWith.includes('username')
+    ? 'Email or username'
+    : 'Email';
+}
+
+/**
+ * The CAPTCHA state for this page.
+ *   { status: 'off' }                                        — the server has no CAPTCHA
+ *   { status: 'on', provider, siteKey, mode }                — load the widget when visible
+ *   { status: 'misconfigured', serverProvider, buildProvider } — show the notice, load nothing
+ * @param {{ provider: string, siteKey: string, mode: string } | null | undefined} captcha
+ *   the `captcha` block from loginOptions()
+ * @param {string | null} buildProvider `BUILD_CAPTCHA_PROVIDER`
+ */
+export function captchaSetup(captcha, buildProvider) {
+  if (!captcha) return { status: 'off' };
+  if (captchaMismatch(captcha.provider, buildProvider)) {
+    return {
+      status: 'misconfigured',
+      serverProvider: captcha.provider,
+      buildProvider: buildProvider ?? null,
+    };
+  }
+  return { status: 'on', provider: captcha.provider, siteKey: captcha.siteKey, mode: captcha.mode };
+}
+
+/**
+ * Whether the widget is shown: CAPTCHA on and either `always` mode or the server asked for it
+ * after a failed attempt (`captchaRequired`).
+ */
+export function captchaVisible(setup, required) {
+  return setup?.status === 'on' && (setup.mode === 'always' || required === true);
+}
+
+/** The service-call options for a token: `{ captchaToken }`, or undefined when there is none. */
+export function captchaOpts(token) {
+  return typeof token === 'string' && token !== '' ? { captchaToken: token } : undefined;
+}

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

@@ -0,0 +1,94 @@
+// signInOptions.test.mjs — the login page's label and CAPTCHA decisions (R13.2, R7.6, D-10,
+// AC-23, AC-24). React-free, so the page stays a thin view over these rules.
+//
+//   node --test src/auth/signInOptions.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  CAPTCHA_ACTIONS,
+  MISCONFIGURED_NOTICE,
+  captchaOpts,
+  captchaSetup,
+  captchaVisible,
+  signInLabel,
+} from './signInOptions.js';
+
+const turnstile = { provider: 'turnstile', siteKey: 'site-key', mode: 'adaptive' };
+
+describe('signInLabel — the label follows signInWith (AC-23)', () => {
+  test('email only → "Email"', () => {
+    assert.equal(signInLabel(['email']), 'Email');
+  });
+  test('email + username → "Email or username"', () => {
+    assert.equal(signInLabel(['email', 'username']), 'Email or username');
+  });
+  test('not loaded yet (or failed) → "Email"', () => {
+    assert.equal(signInLabel(null), 'Email');
+    assert.equal(signInLabel(undefined), 'Email');
+  });
+});
+
+describe('captchaSetup — server provider vs the build (R7.6, D-10)', () => {
+  test('server CAPTCHA off → off, even when the build names a provider', () => {
+    assert.deepEqual(captchaSetup(null, 'turnstile'), { status: 'off' });
+    assert.deepEqual(captchaSetup(undefined, null), { status: 'off' });
+  });
+  test('same provider → on, with the site key and mode', () => {
+    assert.deepEqual(captchaSetup(turnstile, 'turnstile'), {
+      status: 'on',
+      provider: 'turnstile',
+      siteKey: 'site-key',
+      mode: 'adaptive',
+    });
+  });
+  test('different provider → misconfigured, naming both values', () => {
+    assert.deepEqual(captchaSetup(turnstile, 'recaptcha-v3'), {
+      status: 'misconfigured',
+      serverProvider: 'turnstile',
+      buildProvider: 'recaptcha-v3',
+    });
+  });
+  test('server on, build made without a provider → misconfigured (no widget can load under the CSP)', () => {
+    assert.equal(captchaSetup(turnstile, null).status, 'misconfigured');
+  });
+  test('the notice is the fixed text', () => {
+    assert.equal(
+      MISCONFIGURED_NOTICE,
+      'Sign-in protection is misconfigured, contact your administrator',
+    );
+  });
+});
+
+describe('captchaVisible — renders captcha on demand (AC-24)', () => {
+  const on = captchaSetup(turnstile, 'turnstile');
+  const always = captchaSetup({ ...turnstile, mode: 'always' }, 'turnstile');
+  test('adaptive: hidden until the server asks', () => {
+    assert.equal(captchaVisible(on, false), false);
+    assert.equal(captchaVisible(on, true), true);
+  });
+  test('always: shown from the start', () => {
+    assert.equal(captchaVisible(always, false), true);
+  });
+  test('off or misconfigured: never shown, even when the server asks', () => {
+    assert.equal(captchaVisible({ status: 'off' }, true), false);
+    assert.equal(captchaVisible(captchaSetup(turnstile, 'recaptcha-v2'), true), false);
+  });
+});
+
+describe('captchaOpts — the retry sends the token', () => {
+  test('a token → { captchaToken }', () => {
+    assert.deepEqual(captchaOpts('tok'), { captchaToken: 'tok' });
+  });
+  test('no token → undefined (nothing sent)', () => {
+    assert.equal(captchaOpts(''), undefined);
+    assert.equal(captchaOpts(null), undefined);
+  });
+});
+
+test('action names match the endpoints the server checks (R7.4)', () => {
+  assert.deepEqual(CAPTCHA_ACTIONS, {
+    login: 'login',
+    forgot: 'forgot_password',
+    reset: 'reset_password',
+  });
+});

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

@@ -0,0 +1,34 @@
+// useSignInOptions — reads `GET /auth/login-options` once per mount for the sign-in pages
+// (login, forgot password, reset / set password): the login label's `signInWith` and the
+// CAPTCHA setup checked against this build's provider (R7.6, D-10). On a provider mismatch it
+// logs one console error naming both values; the page shows the fixed notice and loads no widget.
+// A failed load reads as "email only, CAPTCHA off" (the server still enforces its own rules).
+import { useEffect, useState } from 'react';
+import { BUILD_CAPTCHA_PROVIDER } from './captchaProvider.js';
+import { captchaSetup } from './signInOptions.js';
+
+const INITIAL = { loaded: false, signInWith: null, captcha: { status: 'off' } };
+
+/** @param {import('@astram/frontend-core').AuthService} auth */
+export function useSignInOptions(auth) {
+  const [options, setOptions] = useState(INITIAL);
+  useEffect(() => {
+    let live = true;
+    void auth.loginOptions().then((r) => {
+      if (!live) return;
+      const captcha = r.ok ? captchaSetup(r.captcha, BUILD_CAPTCHA_PROVIDER) : { status: 'off' };
+      if (captcha.status === 'misconfigured') {
+        console.error(
+          `Sign-in protection is misconfigured: the server uses CAPTCHA provider ` +
+            `"${captcha.serverProvider}" but this build was made for ` +
+            `"${captcha.buildProvider ?? 'none'}" (VITE_CAPTCHA_PROVIDER). No widget is loaded.`,
+        );
+      }
+      setOptions({ loaded: true, signInWith: r.ok ? r.signInWith : null, captcha });
+    });
+    return () => {
+      live = false;
+    };
+  }, [auth]);
+  return options;
+}

package/template/frontend/src/pages/ForgotPassword.jsx

@@ -4,11 +4,18 @@
  * (through AuthContext). ANTI-ENUMERATION: the server always returns the same 204 and
  * this page ALWAYS shows the SAME neutral confirmation — it never reveals whether an
  * account matched.
+ *
+ * CAPTCHA (R7.6): when the server has CAPTCHA on, the widget always shows here and its token
+ * goes with the request (the server answers 204 either way and checks the token after). A
+ * provider mismatch with this build shows the fixed notice and loads no widget.
  */
-import { useState } from 'react';
+import { useRef, useState } from 'react';
 import { Link } from 'react-router-dom';
-import { ArrowLeft, Loader2, MailCheck } from 'lucide-react';
+import { AlertCircle, ArrowLeft, Loader2, MailCheck } from 'lucide-react';
 import { useAuth } from '@/auth/AuthContext';
+import CaptchaWidget from '@/auth/CaptchaWidget';
+import { useSignInOptions } from '@/auth/useSignInOptions';
+import { CAPTCHA_ACTIONS, MISCONFIGURED_NOTICE, captchaOpts } from '@/auth/signInOptions';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
@@ -25,14 +32,29 @@ export default function ForgotPassword() {
   const [identityHint, setIdentityHint] = useState('');
   const [sent, setSent] = useState(false);
   const [busy, setBusy] = useState(false);
+  const [error, setError] = useState('');
+  const signIn = useSignInOptions(auth);
+  const showCaptcha = signIn.captcha.status === 'on';
+  const captchaRef = useRef(null);
 
   const onSubmit = async (e) => {
     e.preventDefault();
+    setError('');
     if (busy || !identityHint.trim()) return;
     setBusy(true);
+    let token = '';
+    if (showCaptcha) {
+      token = (await captchaRef.current?.getToken()) ?? '';
+      if (!token) {
+        setBusy(false);
+        setError('Complete the verification check, then send the link.');
+        return;
+      }
+    }
     // requestReset ALWAYS resolves ok (mirrors the server's anti-enumeration); we
     // show the SAME neutral confirmation whether or not an account matched.
-    await auth.requestReset(identityHint.trim());
+    await auth.requestReset(identityHint.trim(), captchaOpts(token));
+    if (showCaptcha) captchaRef.current?.reset(); // single-use token
     setBusy(false);
     setSent(true);
   };
@@ -65,6 +87,23 @@ export default function ForgotPassword() {
             </div>
           </div>
 
+          {!sent && signIn.captcha.status === 'misconfigured' && (
+            <div
+              role="alert"
+              className="mb-4 flex items-start gap-2 rounded-lg border border-destructive/30 bg-destructive/10 px-3 py-2.5 text-sm text-destructive"
+            >
+              <AlertCircle className="mt-0.5 size-4 shrink-0" />
+              <span>{MISCONFIGURED_NOTICE}</span>
+            </div>
+          )}
+
+          {!sent && error && (
+            <div className="mb-4 flex items-start gap-2 rounded-lg border border-destructive/30 bg-destructive/10 px-3 py-2.5 text-sm text-destructive">
+              <AlertCircle className="mt-0.5 size-4 shrink-0" />
+              <span>{error}</span>
+            </div>
+          )}
+
           {sent ? (
             <div className="flex items-start gap-2 rounded-lg border border-primary/30 bg-primary/10 px-3 py-3 text-sm text-primary">
               <MailCheck className="mt-0.5 size-4 shrink-0" />
@@ -82,6 +121,13 @@ export default function ForgotPassword() {
                   placeholder="you@example.com"
                 />
               </div>
+              {showCaptcha && (
+                <CaptchaWidget
+                  ref={captchaRef}
+                  setup={signIn.captcha}
+                  action={CAPTCHA_ACTIONS.forgot}
+                />
+              )}
               <Button type="submit" disabled={busy} className="w-full">
                 {busy ? (
                   <Loader2 className="size-4 animate-spin" />