create-astram-app 0.11.0 → 0.12.0

package/template/frontend/src/pages/users/signInAdmin.test.mjs

@@ -0,0 +1,183 @@
+// signInAdmin.test.mjs — auth capabilities R11.1–R11.3, R13.4, AC-27: the Users page "2FA"
+// column and the admin sign-in actions (reset 2FA, unlock, end sessions), each behind its
+// permission, hidden on the caller's own row, each asking for the admin's own 6-digit code.
+// UX only: the server decides every action.
+//
+//   node --test src/pages/users/signInAdmin.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  SIGN_IN_ACTIONS,
+  mfaStatusLabel,
+  mfaStatusVariant,
+  visibleSignInActions,
+  normalizeAdminCode,
+  isAdminCode,
+  signInActionOutcome,
+} from './signInAdmin.js';
+
+const ROW = { id: 'u-2', fields: { username: 'thabo' }, mfaStatus: 'required' };
+const ALL = () => true;
+
+describe('the 2FA column', () => {
+  test('labels for every server status', () => {
+    assert.equal(mfaStatusLabel('enrolled'), 'Enrolled');
+    assert.equal(mfaStatusLabel('required'), 'Required');
+    assert.equal(mfaStatusLabel('grace'), 'Grace period');
+    assert.equal(mfaStatusLabel('not_required'), 'Not required');
+  });
+
+  test('absent or unknown status → a dash (server does not compute it)', () => {
+    assert.equal(mfaStatusLabel(undefined), '—');
+    assert.equal(mfaStatusLabel('ENROLLED'), '—');
+  });
+
+  test('required stands out, enrolled reads as good', () => {
+    assert.equal(mfaStatusVariant('enrolled'), 'success');
+    assert.equal(mfaStatusVariant('required'), 'destructive');
+    assert.equal(mfaStatusVariant('grace'), 'warning');
+    assert.equal(mfaStatusVariant('not_required'), 'secondary');
+    assert.equal(mfaStatusVariant(undefined), 'secondary');
+  });
+});
+
+describe('SIGN_IN_ACTIONS', () => {
+  test('three actions, each on its own permission and service method', () => {
+    assert.deepEqual(
+      SIGN_IN_ACTIONS.map((a) => [a.key, a.permission, a.method, a.label]),
+      [
+        ['reset_mfa', 'identity:user:reset_mfa', 'resetUserMfa', 'Reset 2FA'],
+        ['unlock', 'identity:user:unlock', 'unlockUser', 'Unlock'],
+        ['end_sessions', 'identity:user:end_sessions', 'endUserSessions', 'End sessions'],
+      ],
+    );
+  });
+});
+
+describe('visibleSignInActions', () => {
+  test('all three for a caller holding all three keys', () => {
+    assert.deepEqual(
+      visibleSignInActions(ROW, { can: ALL, selfIds: ['me'] }).map((a) => a.key),
+      ['reset_mfa', 'unlock', 'end_sessions'],
+    );
+  });
+
+  test('each action only with its own key', () => {
+    const can = (k) => k === 'identity:user:unlock';
+    assert.deepEqual(
+      visibleSignInActions(ROW, { can, selfIds: [] }).map((a) => a.key),
+      ['unlock'],
+    );
+    assert.deepEqual(visibleSignInActions(ROW, { can: () => false, selfIds: [] }), []);
+  });
+
+  test("never on the signed-in user's own row (the server refuses self)", () => {
+    assert.deepEqual(visibleSignInActions(ROW, { can: ALL, selfIds: [null, 'u-2'] }), []);
+    assert.deepEqual(visibleSignInActions({ id: 'me' }, { can: ALL, selfIds: ['me'] }), []);
+  });
+
+  test('no row → nothing', () => {
+    assert.deepEqual(visibleSignInActions(null, { can: ALL, selfIds: [] }), []);
+  });
+});
+
+describe('the admin code', () => {
+  test('spaces are dropped; exactly six digits is a code', () => {
+    assert.equal(normalizeAdminCode(' 123 456 '), '123456');
+    assert.equal(isAdminCode('123456'), true);
+    for (const bad of ['12345', '1234567', '12a456', '', undefined]) {
+      assert.equal(isAdminCode(bad), false);
+    }
+  });
+});
+
+describe('signInActionOutcome', () => {
+  const reset = SIGN_IN_ACTIONS[0];
+  const unlock = SIGN_IN_ACTIONS[1];
+  const end = SIGN_IN_ACTIONS[2];
+
+  test('success → a per-action toast naming the user, dialog closes', () => {
+    assert.deepEqual(signInActionOutcome(reset, { ok: true }, 'thabo'), {
+      kind: 'success',
+      text: '2FA reset for thabo. They will set it up again at their next sign-in if required.',
+      close: true,
+    });
+    assert.equal(
+      signInActionOutcome(unlock, { ok: true }, 'thabo').text,
+      'thabo can sign in again.',
+    );
+    assert.equal(
+      signInActionOutcome(end, { ok: true }, 'thabo').text,
+      'All of thabo’s sessions were ended.',
+    );
+  });
+
+  test('admin without 2FA → set it up on your own account, dialog closes', () => {
+    assert.deepEqual(
+      signInActionOutcome(reset, { ok: false, status: 409, reason: 'admin_needs_mfa', error: 'x' }),
+      {
+        kind: 'error',
+        text: 'Set up two-step verification on your own account first.',
+        close: true,
+      },
+    );
+  });
+
+  test('partly applied → "Partly done — try again", dialog stays for a retry', () => {
+    assert.deepEqual(
+      signInActionOutcome(reset, {
+        ok: false,
+        status: 503,
+        reason: 'partially_applied',
+        error: 'x',
+      }),
+      { kind: 'error', text: 'Partly done — try again.', close: false },
+    );
+  });
+
+  test('wrong or missing code stays open for a new code', () => {
+    const invalid = signInActionOutcome(unlock, { ok: false, reason: 'invalid_code', error: 'x' });
+    assert.equal(invalid.close, false);
+    assert.equal(
+      invalid.text,
+      'That code is not valid. Enter a new code from your authenticator app.',
+    );
+    const missing = signInActionOutcome(unlock, { ok: false, reason: 'code_required', error: 'x' });
+    assert.equal(missing.close, false);
+    assert.equal(missing.text, 'Enter the 6-digit code from your authenticator app.');
+  });
+
+  test('rate limited, forbidden, not found close with their fixed text', () => {
+    assert.deepEqual(signInActionOutcome(end, { ok: false, reason: 'rate_limited', error: 'x' }), {
+      kind: 'error',
+      text: 'Too many code attempts. Wait a few minutes and try again.',
+      close: true,
+    });
+    assert.deepEqual(signInActionOutcome(end, { ok: false, reason: 'forbidden', error: 'x' }), {
+      kind: 'error',
+      text: 'You cannot do this for this user.',
+      close: true,
+    });
+    assert.equal(
+      signInActionOutcome(end, { ok: false, reason: 'not_found', error: 'x' }).close,
+      true,
+    );
+  });
+
+  test('unavailable / unreachable / unknown → the service message, stays open', () => {
+    const r = signInActionOutcome(end, {
+      ok: false,
+      reason: 'unavailable',
+      error: 'The service is temporarily unavailable. Nothing was changed; please try again.',
+    });
+    assert.deepEqual(r, {
+      kind: 'error',
+      text: 'The service is temporarily unavailable. Nothing was changed; please try again.',
+      close: false,
+    });
+    assert.equal(
+      signInActionOutcome(end, { ok: false, reason: 'failed' }).text,
+      'The action failed. Please try again.',
+    );
+  });
+});

package/template/frontend/src/platform/httpClient.js

@@ -10,6 +10,8 @@
  * transport. Use the raw client directly only for the refresh call itself.
  */
 
+import { restrictionReasonOf } from '@astram/frontend-core';
+
 const BASE = '/api';
 
 async function toResponse(res) {
@@ -31,38 +33,48 @@ function withSignal(opts) {
 }
 
 /**
- * The app-wide enforced-re-enroll interceptor. When a request is rejected with a 403
- * whose body is EXACTLY `{ error: 'reenrollment_required' }` (the server's re-enroll
- * gate, §4), fire the supplied callback so the app can force the re-enroll screen.
- * Matched narrowly on that single error code so an unrelated future permission-deny 403
- * never trips it. Best-effort: a throwing callback must not break the HTTP result.
+ * The restriction a response carries (R2.3, R15.2), or null:
+ *  - a 403 whose body is EXACTLY one of the restriction codes (`reenrollment_required`,
+ *    `mfa_enrollment_required`), read by frontend-core's `restrictionReasonOf`, on any call;
+ *  - the restricted `/identity/auth-facts` answer (200, `restricted: <reason>`), so a password
+ *    sign-in into a restricted session is routed before any gated call is made.
+ * Matched narrowly so an unrelated permission-deny 403 never trips it.
  */
-function maybeSignalReenroll(result, onReenrollRequired) {
-  if (
-    typeof onReenrollRequired === 'function' &&
-    result.status === 403 &&
-    result.data &&
-    result.data.error === 'reenrollment_required'
-  ) {
-    try {
-      onReenrollRequired();
-    } catch {
-      /* the signal is best-effort — never let it break the request result */
-    }
+function restrictionOf(path, result) {
+  if (result.status === 403) return restrictionReasonOf(result.data);
+  if (result.ok && path.split('?')[0] === '/identity/auth-facts') {
+    const reason = result.data && result.data.restricted;
+    return reason === 'reenroll' || reason === 'mfa_enrollment' ? reason : null;
+  }
+  return null;
+}
+
+/**
+ * The app-wide restriction interceptor: fire the callbacks so the app can force the enrolment
+ * screen. Best-effort: a throwing callback must not break the HTTP result.
+ */
+function maybeSignalRestriction(path, result, { onRestricted, onReenrollRequired }) {
+  const reason = restrictionOf(path, result);
+  if (reason === null) return result;
+  try {
+    if (typeof onRestricted === 'function') onRestricted(reason);
+    if (reason === 'reenroll' && typeof onReenrollRequired === 'function') onReenrollRequired();
+  } catch {
+    /* the signal is best-effort — never let it break the request result */
   }
   return result;
 }
 
 /**
- * @param {{ onReenrollRequired?: () => void }} [config]
- *   `onReenrollRequired` — invoked when any response is a 403 `reenrollment_required`
- *   (the enforced-re-enroll gate). The consumer (AuthContext) uses it to flip the app
- *   into the forced re-enroll flow app-wide, regardless of which call triggered it.
+ * @param {{ onRestricted?: (reason: 'reenroll' | 'mfa_enrollment') => void,
+ *           onReenrollRequired?: () => void }} [config]
+ *   `onRestricted` — invoked when a response says the session is restricted (see
+ *   `restrictionOf`). The consumer (AuthContext) uses it to flip the app into the forced
+ *   enrolment flow app-wide, regardless of which call triggered it.
+ *   `onReenrollRequired` — the older callback, for `reenroll` only.
  * @returns {import('@astram/frontend-core').HttpClient}
  */
 export function createWebHttpClient(config = {}) {
-  const { onReenrollRequired } = config;
-
   return {
     async post(path, body, opts = {}) {
       try {
@@ -75,7 +87,7 @@ export function createWebHttpClient(config = {}) {
           body: JSON.stringify(body),
           ...withSignal(opts),
         });
-        return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
+        return maybeSignalRestriction(path, await toResponse(res), config);
       } catch {
         return { ok: false, status: 0, data: null };
       }
@@ -91,7 +103,7 @@ export function createWebHttpClient(config = {}) {
           body: JSON.stringify(body),
           ...withSignal(opts),
         });
-        return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
+        return maybeSignalRestriction(path, await toResponse(res), config);
       } catch {
         return { ok: false, status: 0, data: null };
       }
@@ -107,7 +119,7 @@ export function createWebHttpClient(config = {}) {
           body: JSON.stringify(body),
           ...withSignal(opts),
         });
-        return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
+        return maybeSignalRestriction(path, await toResponse(res), config);
       } catch {
         return { ok: false, status: 0, data: null };
       }
@@ -123,7 +135,7 @@ export function createWebHttpClient(config = {}) {
           body: JSON.stringify(body),
           ...withSignal(opts),
         });
-        return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
+        return maybeSignalRestriction(path, await toResponse(res), config);
       } catch {
         return { ok: false, status: 0, data: null };
       }
@@ -134,7 +146,7 @@ export function createWebHttpClient(config = {}) {
           headers: opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {},
           ...withSignal(opts),
         });
-        return maybeSignalReenroll(await toResponse(res), onReenrollRequired);
+        return maybeSignalRestriction(path, await toResponse(res), config);
       } catch {
         return { ok: false, status: 0, data: null };
       }

package/template/frontend/src/platform/httpClient.test.mjs

@@ -58,3 +58,74 @@ describe('createWebHttpClient — abort signal forwarding', () => {
     });
   }
 });
+
+// R2.3, R13.2, AC-25: both restriction reasons route to the enrolment page. A 403 carries the
+// code on any call; the restricted `/identity/auth-facts` answer (R15.2) carries it in a 200, so
+// a password sign-in into a restricted session is routed before any gated call is made.
+describe('createWebHttpClient — restriction routing', () => {
+  const respond = (status, body) => {
+    globalThis.fetch = async () => ({ ok: status < 400, status, json: async () => body });
+  };
+
+  test('403 mfa_enrollment_required → onRestricted("mfa_enrollment") on any method', async () => {
+    for (const call of [
+      (c) => c.get('/identity/users'),
+      (c) => c.post('/x', {}),
+      (c) => c.patch('/x', {}),
+      (c) => c.put('/x', {}),
+      (c) => c.delete('/x', {}),
+    ]) {
+      respond(403, { error: 'mfa_enrollment_required' });
+      const reasons = [];
+      const r = await call(createWebHttpClient({ onRestricted: (why) => reasons.push(why) }));
+      assert.equal(r.status, 403);
+      assert.deepEqual(reasons, ['mfa_enrollment']);
+    }
+  });
+
+  test('403 reenrollment_required → onRestricted("reenroll") and the old onReenrollRequired', async () => {
+    respond(403, { error: 'reenrollment_required' });
+    const reasons = [];
+    let legacy = 0;
+    await createWebHttpClient({
+      onRestricted: (why) => reasons.push(why),
+      onReenrollRequired: () => legacy++,
+    }).get('/x');
+    assert.deepEqual(reasons, ['reenroll']);
+    assert.equal(legacy, 1);
+  });
+
+  test('the old onReenrollRequired alone is not fired for mfa_enrollment', async () => {
+    respond(403, { error: 'mfa_enrollment_required' });
+    let legacy = 0;
+    await createWebHttpClient({ onReenrollRequired: () => legacy++ }).get('/x');
+    assert.equal(legacy, 0);
+  });
+
+  test('any other 403 never routes', async () => {
+    respond(403, { error: 'forbidden' });
+    const reasons = [];
+    await createWebHttpClient({ onRestricted: (why) => reasons.push(why) }).get('/x');
+    assert.deepEqual(reasons, []);
+  });
+
+  test('restricted auth-facts (200, restricted: <reason>) routes; other 200s with that key do not', async () => {
+    respond(200, { principalId: 'p', facts: [], restricted: 'mfa_enrollment' });
+    const reasons = [];
+    const c = createWebHttpClient({ onRestricted: (why) => reasons.push(why) });
+    await c.get('/identity/auth-facts');
+    assert.deepEqual(reasons, ['mfa_enrollment']);
+    await c.get('/identity/users?restricted=1');
+    assert.deepEqual(reasons, ['mfa_enrollment']);
+  });
+
+  test('a throwing callback never breaks the result', async () => {
+    respond(403, { error: 'mfa_enrollment_required' });
+    const r = await createWebHttpClient({
+      onRestricted: () => {
+        throw new Error('boom');
+      },
+    }).get('/x');
+    assert.equal(r.status, 403);
+  });
+});

package/template/frontend/src/platform/shieldTransport.js

@@ -52,15 +52,15 @@
  * never throws" fail-closed guarantee that `AuthContext.refreshAuthFacts` relies on. So
  * this implementation MUST NEVER THROW.
  *
- * Freshness is decided by `cached.permissionsVersion >= current` (client.ts:392) — a
- * cache is stale (refetch) whenever `current` is NOT LESS than the cached version. So the
- * fail-closed way to say "I can't tell you the real version" is to RETURN a number that
- * can never compare `<=` any real cached version: `Number.POSITIVE_INFINITY`. That makes
- * every comparison `cached.permissionsVersion >= Infinity` evaluate `false` — always
- * stale, always refetch — mirroring the SDK's own NaN-version adversarial test
- * (`adversarial.test.ts` "ATTACK 2": a version that can never compare `>=` current is
- * always treated as stale, never phantom-fresh). This is fail-closed WITHOUT throwing:
- * an unreadable version can never be mistaken for "cache is fresh".
+ * Freshness is decided by `cached.permissionsVersion === current` (`isProjectionFresh`;
+ * @astram/sdk < 0.2.1 used `>=`): the version is an opaque token (the guard folds root
+ * status into it, KI #139), and any difference means stale (refetch). So the fail-closed
+ * way to say "I can't tell you the real version" is to RETURN a number no real cached
+ * version can match under either rule: `Number.POSITIVE_INFINITY`. Every comparison
+ * then reads stale — always refetch — mirroring the SDK's own NaN-version adversarial
+ * test (`adversarial.test.ts` "ATTACK 2": an unmatched version is always treated as
+ * stale, never phantom-fresh). This is fail-closed WITHOUT throwing: an unreadable
+ * version can never be mistaken for "cache is fresh".
  *
  * A non-ok probe (status 0 network failure, 401 session concern, >=500 server/store
  * outage) is exactly this "can't-know" case → returns `Number.POSITIVE_INFINITY` (forces
@@ -146,9 +146,9 @@ export function createWebShieldTransport({ http, getToken }) {
      * by any try/catch, so a throw here would escape `getAuthFacts` uncaught).
      *
      * A non-ok probe (status 0 / 401 / >=500 — the SAME "can't-know" set
-     * `fetchProjection` treats as transient) returns `Number.POSITIVE_INFINITY`: it can
-     * never compare `<=` a real cached version, so `cached.permissionsVersion >= current`
-     * is always `false` — always stale, always refetch. Fail-closed WITHOUT throwing:
+     * `fetchProjection` treats as transient) returns `Number.POSITIVE_INFINITY`: no real
+     * cached version equals it (or is `>=` it, for an older SDK), so the cache always
+     * reads stale — always refetch. Fail-closed WITHOUT throwing:
      * an unreadable version is never mistaken for "the cache is fresh".
      *
      * A malformed 200 body (missing/non-numeric `data.version`) is treated the same

package/template/frontend/src/shell/AppShell.jsx

@@ -22,6 +22,7 @@ import {
 } from '@/components/ui/dropdown-menu';
 import ThemeToggle from '@/theme/ThemeToggle';
 import Sidebar from './Sidebar';
+import GraceBanner from './GraceBanner';
 
 /** A header icon-action button with a tooltip (ffs pattern). */
 function IconAction({ icon: Icon, label, dot }) {
@@ -228,6 +229,9 @@ export default function AppShell({ children, title: _title, section: _section })
           </header>
         </TooltipProvider>
 
+        {/* 2FA grace period (R2.4): the deadline and a link to set it up. */}
+        <GraceBanner />
+
         <main className="engineering-grid flex-1 overflow-y-auto">{children}</main>
       </div>
     </div>

package/template/frontend/src/shell/GraceBanner.jsx

@@ -0,0 +1,28 @@
+/**
+ * GraceBanner — the 2FA grace-period notice on signed-in pages (R2.4, R13.2, AC-25). Shown while
+ * `/auth/me` carries `mfaEnrollmentDeadline`; links to Account → Two-factor; hidden on the
+ * enrolment pages. The wording and date formatting live in graceDeadline.js (tested).
+ */
+import { Link, useLocation } from 'react-router-dom';
+import { ShieldAlert } from 'lucide-react';
+import { useAuth } from '@/auth/AuthContext';
+import { graceBannerFor } from './graceDeadline';
+
+export default function GraceBanner() {
+  const { profile } = useAuth();
+  const { pathname } = useLocation();
+  const banner = graceBannerFor(profile, pathname);
+  if (!banner) return null;
+  return (
+    <div
+      role="status"
+      className="flex flex-wrap items-center gap-x-3 gap-y-1 border-b border-[var(--warn)]/40 bg-[var(--warn)]/10 px-4 py-2 text-sm"
+    >
+      <ShieldAlert className="size-4 shrink-0 text-[var(--warn)]" aria-hidden="true" />
+      <span className="text-foreground">{banner.text}</span>
+      <Link to={banner.href} className="font-medium text-primary hover:underline">
+        {banner.linkLabel}
+      </Link>
+    </div>
+  );
+}

package/template/frontend/src/shell/graceDeadline.js

@@ -0,0 +1,50 @@
+// graceDeadline.js — the 2FA grace-period banner on signed-in pages (R2.4, R13.2, AC-25).
+// `/auth/me` returns `mfaEnrollmentDeadline` (ISO-8601, UTC) while the user is required to set up
+// two-step verification and still in grace. The banner names that deadline in the viewer's local
+// date and time and links to Account → Two-factor. React-free so `node --test` can run it.
+
+/** Account → Two-factor (the page where a device is added). */
+export const TWO_FACTOR_PATH = '/account/2fa';
+
+// The enrolment pages themselves: no banner there.
+const HIDDEN_ON = new Set([TWO_FACTOR_PATH, '/account/reenroll']);
+
+/** `/account/2fa/` and `/account/2fa` are the same page (the router matches both). */
+function withoutTrailingSlash(pathname) {
+  const p = typeof pathname === 'string' ? pathname.replace(/\/+$/, '') : '';
+  return p === '' ? '/' : p;
+}
+
+/**
+ * The deadline as a local date and time, or null when missing / unparsable.
+ * @param {string | undefined} iso
+ * @param {{ locale?: string, timeZone?: string }} [fmt] defaults: the browser's locale and zone
+ */
+export function formatDeadline(iso, fmt = {}) {
+  if (typeof iso !== 'string' || iso === '') return null;
+  const when = new Date(iso);
+  if (Number.isNaN(when.getTime())) return null;
+  return new Intl.DateTimeFormat(fmt.locale, {
+    dateStyle: 'medium',
+    timeStyle: 'short',
+    ...(fmt.timeZone ? { timeZone: fmt.timeZone } : {}),
+  }).format(when);
+}
+
+/**
+ * The banner for this profile on this page, or null.
+ * @param {{ mfaEnrollmentDeadline?: string } | null | undefined} profile from `/auth/me`
+ * @param {string} pathname the current route
+ * @param {{ locale?: string, timeZone?: string }} [fmt]
+ * @returns {{ text: string, href: string, linkLabel: string } | null}
+ */
+export function graceBannerFor(profile, pathname, fmt) {
+  if (HIDDEN_ON.has(withoutTrailingSlash(pathname))) return null;
+  const when = formatDeadline(profile?.mfaEnrollmentDeadline, fmt);
+  if (when === null) return null;
+  return {
+    text: `Your organisation requires two-step verification. Set it up before ${when}.`,
+    href: TWO_FACTOR_PATH,
+    linkLabel: 'Set up two-step verification',
+  };
+}

package/template/frontend/src/shell/graceDeadline.test.mjs

@@ -0,0 +1,59 @@
+// graceDeadline.test.mjs — in a 2FA grace period the signed-in pages show the deadline from
+// `/auth/me` (R2.4, R13.2, AC-25). Hidden on the enrolment pages themselves.
+//
+//   node --test src/shell/graceDeadline.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { TWO_FACTOR_PATH, formatDeadline, graceBannerFor } from './graceDeadline.js';
+
+const fmt = { locale: 'en-GB', timeZone: 'UTC' };
+const deadline = '2026-10-20T09:30:00.000Z';
+
+describe('formatDeadline', () => {
+  test('local date and time in the given locale / zone', () => {
+    assert.equal(formatDeadline(deadline, fmt), '20 Oct 2026, 09:30');
+  });
+  test('another zone shifts the time', () => {
+    assert.equal(
+      formatDeadline(deadline, { locale: 'en-GB', timeZone: 'Asia/Kolkata' }),
+      '20 Oct 2026, 15:00',
+    );
+  });
+  test('missing or unparsable → null', () => {
+    assert.equal(formatDeadline(undefined, fmt), null);
+    assert.equal(formatDeadline('not a date', fmt), null);
+  });
+});
+
+describe('graceBannerFor', () => {
+  test('profile with a deadline → the banner text and the Two-factor link', () => {
+    assert.deepEqual(graceBannerFor({ mfaEnrollmentDeadline: deadline }, '/dashboard', fmt), {
+      text: 'Your organisation requires two-step verification. Set it up before 20 Oct 2026, 09:30.',
+      href: TWO_FACTOR_PATH,
+      linkLabel: 'Set up two-step verification',
+    });
+    assert.equal(TWO_FACTOR_PATH, '/account/2fa');
+  });
+  test('no profile or no deadline → no banner', () => {
+    assert.equal(graceBannerFor(null, '/dashboard', fmt), null);
+    assert.equal(graceBannerFor({ name: 'A' }, '/dashboard', fmt), null);
+  });
+  test('an unparsable deadline → no banner (never "before Invalid Date")', () => {
+    assert.equal(graceBannerFor({ mfaEnrollmentDeadline: 'x' }, '/dashboard', fmt), null);
+  });
+  test('hidden on the enrolment pages', () => {
+    assert.equal(graceBannerFor({ mfaEnrollmentDeadline: deadline }, '/account/2fa', fmt), null);
+    assert.equal(
+      graceBannerFor({ mfaEnrollmentDeadline: deadline }, '/account/reenroll', fmt),
+      null,
+    );
+  });
+  test('hidden on the enrolment pages with a trailing slash too', () => {
+    const p = { mfaEnrollmentDeadline: deadline };
+    assert.equal(graceBannerFor(p, '/account/2fa/', fmt), null);
+    assert.equal(graceBannerFor(p, '/account/reenroll/', fmt), null);
+    assert.equal(graceBannerFor(p, '/account/2fa//', fmt), null);
+    assert.notEqual(graceBannerFor(p, '/account/2fa-other', fmt), null);
+    assert.notEqual(graceBannerFor(p, '/', fmt), null);
+  });
+});

package/template/frontend/src/shell/nav.js

@@ -23,6 +23,15 @@
  *                 cross-tenant-grants` / `GET .../inbox` / `GET .../offerable-types`,
  *                 all gated `role:read` — reading/managing cross-tenant grants IS role
  *                 administration; the OFFER write is separately `cross_tenant_grant:share`)
+ *   - Org structure → `identity:company_department:read` (org-catalog.controller.ts `GET
+ *                 companies/:companyUuid/departments`; the branches list is
+ *                 `company_branch:read`, and both bundles that grant one grant the other.
+ *                 `gate` takes one key, so the entry and the route (App.jsx) use the
+ *                 department key; a caller holding only `company_branch:read` is not served
+ *                 the page. Writes are department|branch:create|update|delete, enforced
+ *                 server-side per route)
+ *   - Security  → `identity:security_policy:read` (security-policy.controller.ts `GET
+ *                 security-policies`; add/edit/delete are security_policy:create|update|delete)
  * Dashboard / Account are left UNGATED — self/owned surfaces every authenticated
  * caller may reach (no admin-only list route backs them).
  */
@@ -33,6 +42,8 @@ import {
   History,
   KeyRound,
   LayoutDashboard,
+  Lock,
+  Network,
   ShieldCheck,
   UserCog,
   Users,
@@ -54,6 +65,14 @@ export const NAV_SECTIONS = [
         matchPrefix: true,
         gate: 'identity:company:read',
       },
+      {
+        icon: Network,
+        label: 'Org structure',
+        path: '/org-structure',
+        badge: null,
+        matchPrefix: true,
+        gate: 'identity:company_department:read',
+      },
       {
         icon: Users,
         label: 'Users',
@@ -116,6 +135,16 @@ export const NAV_SECTIONS = [
     label: 'Settings',
     // `/account` redirects to `/account/profile`; `matchPrefix` keeps the nav item
     // highlighted across ALL /account/* sub-tabs (profile / password / 2fa).
-    items: [{ icon: UserCog, label: 'Account', path: '/account', badge: null, matchPrefix: true }],
+    items: [
+      { icon: UserCog, label: 'Account', path: '/account', badge: null, matchPrefix: true },
+      {
+        icon: Lock,
+        label: 'Security',
+        path: '/security',
+        badge: null,
+        matchPrefix: true,
+        gate: 'identity:security_policy:read',
+      },
+    ],
   },
 ];