@rapidmx/web-client 0.8.0 → 0.10.0

package/README.md

@@ -1,88 +1,192 @@
-# RapidMX: Web Client
-
-[![npm version](https://img.shields.io/npm/v/@rapidmx/web-client)](https://www.npmjs.com/package/@rapidmx/web-client)
-
-RapidMX's webmail (`apps/www`), admin console (`apps/admin`) and escrow console (`apps/escrow`) React UI. The pages are
-served and hydrated by [`rapidmx/server`](https://github.com/RapidMX/server) through `@rapidrest/react`'s file-convention
-routes, and `@rapidmx/electron-client` reuses the same components. Platform-agnostic API clients, hooks and generic UI
-primitives live in [`@rapidmx/react-shared`](https://github.com/RapidMX/react-shared).
-
-## Package layout
-
-The package ships the TSX sources (`apps/`) and a compiled mirror (`dist/apps/`, JavaScript plus `.d.ts` declarations).
-There is no root export. Every module is its own subpath, mapped by `package.json`'s `exports` from
-`@rapidmx/web-client/<path>.js` to `dist/apps/<path>.js`:
-
-```ts
-import SettingsShell from "@rapidmx/web-client/shared/components/settings/layout/SettingsShell.js";
-```
-
-`@rapidmx/web-client/shared/styles/app.css` is the Tailwind entry point and design tokens.
-
-## Plugin UI surface
-
-Server plugins can ship their own pages (see the plugin manifest's `ui` field in `@rapidmx/restapi`). The server builds
-them together with this package, so they share one React, one `@rapidmx/react-shared` state and one stylesheet. The
-modules below are the **supported surface for plugin pages**. Anything else under `apps/` is internal and may change in
-any release.
-
-### Shells
-
-| Import | Use |
-| --- | --- |
-| `shared/components/layout/AppShell.js` | Chrome for webmail apps: app rail, header, user menu, impersonation banner, compose and unlock providers. `active` is a core app or the plugin's `appRail` item id. |
-| `shared/components/settings/layout/SettingsShell.js` | Settings chrome with the section list and mailbox switcher. `active` is the plugin's `settingsSections` item id. `useSettingsShell()` gives the selected `mailboxUid` and the accessible `mailboxes`. |
-| `shared/components/admin/layout/AdminShell.js` | Admin console chrome, gated on administrator access. `active` is the plugin's `adminNav` item id. |
-| `shared/components/layout/BrandingChrome.js` | `BrandingHeader` and `BrandingFooter`, for pages that don't use a shell, such as public pages. |
-| `shared/plugins/pluginNav.js` | The `PluginNav`, `PluginUiNavItem` and `PluginNavProps` types. |
-
-Every www and admin page receives a `pluginNav` prop from the server. It lists the settings sections, admin sections and
-app rail entries of every enabled plugin whose UI built. The shells append those entries after their own, with a generic
-icon. An entry whose id matches a core entry is skipped, and so is one whose `href` isn't a same-origin path. Pass the
-page props straight to the shell so the navigation shows:
-
-```tsx
-import React from "react";
-import SettingsShell, {
-    SettingsShellProps,
-    useSettingsShell,
-} from "@rapidmx/web-client/shared/components/settings/layout/SettingsShell.js";
-
-export default function RemindersSettingsPage(props: Omit<SettingsShellProps, "active">) {
-    return (
-        <SettingsShell {...props} active="reminders">
-            <RemindersSettings />
-        </SettingsShell>
-    );
-}
-
-function RemindersSettings() {
-    const { mailboxUid } = useSettingsShell();
-    return <p>Settings for {mailboxUid}</p>;
-}
-```
-
-Public and escrow pages get no `pluginNav`.
-
-### From `@rapidmx/react-shared`
-
-Plugin pages import these directly from `@rapidmx/react-shared`, which the server resolves to the same copy the shells
-use:
-
-- `branding/useBranding.js`: `useBranding()`, for the branding and icon of pages outside a shell;
-- `auth/session.js`: `useRedirectIfUnauthenticated()`, already called by every shell;
-- `util/api.js`: `apiFetch()` and `ApiRequestError`, for calling the plugin's own API routes;
-- `mail/mailApi.js`: mailboxes and folders, such as `listMailboxes()` and `listFolders()`;
-- `components/buttons/Button.js`, `components/feedback/Alert.js` and `components/feedback/Skeleton.js`;
-- `components/forms/FormField.js`;
-- `components/overlays/Modal.js` and `components/overlays/Drawer.js`;
-- `components/pickers/MiniDatePicker.js`.
-
-## Development
-
-```sh
-yarn install
-yarn test        # vitest with coverage gates
-yarn lint
-yarn build       # tsc into dist/apps
-```
+# RapidMX: Web Client
+
+[![npm version](https://img.shields.io/npm/v/@rapidmx/web-client)](https://www.npmjs.com/package/@rapidmx/web-client)
+
+RapidMX's webmail (`apps/www`), admin console (`apps/admin`) and escrow console (`apps/escrow`) React UI. The pages are
+served and hydrated by [`rapidmx/server`](https://github.com/RapidMX/server) through `@rapidrest/react`'s file-convention
+routes, and `@rapidmx/electron-client` reuses the same components. Platform-agnostic API clients, hooks and generic UI
+primitives live in [`@rapidmx/react-shared`](https://github.com/RapidMX/react-shared).
+
+## Package layout
+
+The package ships the TSX sources (`apps/`) and a compiled mirror (`dist/apps/`, JavaScript plus `.d.ts` declarations).
+There is no root export. Every module is its own subpath, mapped by `package.json`'s `exports` from
+`@rapidmx/web-client/<path>.js` to `dist/apps/<path>.js`:
+
+```ts
+import SettingsShell from "@rapidmx/web-client/shared/components/settings/layout/SettingsShell.js";
+```
+
+`@rapidmx/web-client/shared/styles/app.css` is the Tailwind entry point and design tokens.
+
+## Navigation without page loads
+
+`@rapidrest/react` has no router: every page is a server-rendered document that hydrates only its own page component. The
+`www` pages (Mail, Calendar, Contacts, Tasks, Settings and their subpages) therefore render a small client-side router
+themselves, and go between one another - and between the folders of Mail - without a page load:
+
+- each `apps/www` page's default export is `routedPage("/its/route", Page)` (`apps/www/_routedPage.tsx`). The server
+  renders and the browser hydrates exactly what it did before; the first load is unchanged. `apps/www/_routes.ts` lists the
+  pages, each with a dynamic `import()` so it is a chunk of its own (a test keeps it in step with the files);
+- one `AppShell` chrome (the app rail, header, user menu, impersonation banner, compose windows in progress, the unlock
+  prompt and the idle-key timer) stays mounted, and only the page inside it is replaced. A page's own shell
+  (`MailShell`, `CalendarShell`, ...) still renders `AppShell`; inside the router that is only its children;
+- **links stay ordinary links.** Every same-origin `<a href>` to a route in the table is taken over - plain left clicks
+  only, so ctrl/cmd/shift/middle click, `target`, `download`, `#hash` links and links marked `data-full-reload` keep
+  the browser's behaviour, and pages that are not in the table (the admin and escrow consoles, plugin pages, other sites) are
+  reached with a page load. The address bar always holds the real, shareable URL (`/?mailboxUid=&folderUid=`), and back and
+  forward work;
+- a page's code is fetched when the pointer, focus or a press reaches a link to it, and for the app rail's pages when the
+  browser is idle after load (not with data saving on); if it can't be loaded the router falls back to a page load;
+- after a page change focus moves to the content region (`#app-content`), the window scrolls to the top, `document.title`
+  follows the page and a polite live region announces it.
+
+Code that decides where to go uses the two hooks in `shared/navigation/AppRouter.js`:
+
+```tsx
+import { useLocation, useNavigate } from "@rapidmx/web-client/shared/navigation/AppRouter.js";
+
+const navigate = useNavigate(); // navigate("/contacts"), navigate("/?mailboxUid=a&folderUid=b", { replace: true })
+const { pathname, search, hash } = useLocation(); // empty until read after the first render, so server and browser agree
+```
+
+`navigate()` changes the page without a load when the URL is a route of the app and is an ordinary navigation otherwise
+(outside the router too, where it is `window.location.href = ...`). Page props are the same for every `www` page except
+`params`, which the router recomputes from the URL. Plugin pages are not part of the router (they render their own
+`AppShell` chrome) and are opened with a page load.
+
+The compose window, the reading pane, S/MIME and the emoji list are also chunks of their own, loaded on demand or fetched
+when the browser is idle, so a page's first JavaScript is React and what the first screen draws.
+
+## Keyboard shortcuts
+
+One keyboard layer, `shared/keyboard/`, lives in the persistent app frame (`AppChrome`), so the shortcuts work in every view -
+Mail, Calendar, Contacts, Tasks and Settings - and a page change only changes which of them are registered. `?` (or `Ctrl+/`)
+opens a "Keyboard shortcuts" dialog, also reached from the account menu, that lists what is available *here* - the global
+shortcuts plus those of the view on screen (and of an open compose window) - with the platform's own key names. `mod` below is
+**Ctrl** on Windows and Linux and **Cmd** on a Mac; the navigation set is Ctrl+Shift on every platform (Cmd+Shift collides with the
+browsers' own, so it is not offered).
+
+| Where | Key | Does |
+| --- | --- | --- |
+| Everywhere | `Ctrl+Shift+A` | Account (auth-server's account page; only offered when one is configured) |
+| | `Ctrl+Shift+S` / `B` / `M` / `C` / `L` | Settings / Contacts / Mail / Calendar / To-Do |
+| | `?` or `Ctrl+/` | Keyboard shortcuts |
+| Mail | `Alt+N` | New message |
+| | `mod+R` / `mod+Shift+R` / `mod+Shift+F` | Reply / Reply all / Forward the selected message |
+| | `mod+D` or `Delete` | Delete the selected message or conversation (moves it to Deleted Items) |
+| | `E` or `Backspace` | Archive |
+| | `mod+Shift+V` | Move to folder |
+| | `Ctrl+Q` / `mod+U` | Mark as read / unread (`Ctrl+Q` on a Mac too: `Cmd+Q` quits) |
+| | `Insert` | Flag or unflag |
+| | `Down` or `J` / `Up` or `K` | Next / previous message (conversation) |
+| | `Ctrl+.` / `Ctrl+,` | Next / previous unread |
+| | `Enter` / `Escape` | Open the selected message on its own page / clear the selection (leave select mode, clear the search) |
+| | `/` or `mod+E` | Search |
+| Compose window | `mod+Enter` | Send |
+| | `mod+S` | Save draft |
+| | `Escape` | Close, keeping the draft (the existing "keep draft / discard" question still applies) |
+| | `Alt+N` | Another new message |
+| Calendar | `Alt+N` | New event |
+| | `T` | Today |
+| | `Left` / `Right` (or `mod+Left` / `mod+Right`) | Previous / next period |
+| | `Ctrl+Alt+1` / `2` / `3` / `4` | Day / work week / week / month |
+| Contacts | `Alt+N` | New contact |
+| | `/` or `mod+E` | Search |
+| Tasks | `Alt+N` | New task (moves to the "Add a task" field) |
+
+In the desktop client (`@rapidmx/electron-client`, which exposes `window.rapidmx`) `Ctrl+N` (`Cmd+N` on a Mac) also creates - a new
+message, event, contact or task in the current view - and `Ctrl+Shift+T` also goes to Tasks; browsers keep both for themselves, which is
+why the web client uses `Alt+N` and `Ctrl+Shift+L`.
+
+How it behaves:
+
+- **Views register only what they can do.** A view claims a shortcut with `useShortcut(SHORTCUTS.mail.reply, handler, { enabled })`
+  for as long as it is mounted and able to do it (Reply exists only while a message is selected, Archive not for Drafts or Outbox),
+  so there are no dead keys and the help dialog is always accurate. `SHORTCUTS` in `shared/keyboard/keymap.js` is the one key map;
+  handlers are looked up when the key is pressed. A handler that returns `false` declines the key.
+- **Scopes.** `global`, the view's own (`mail`, `calendar`, `contacts`, `tasks`), `compose` (while focus is inside a compose window; it
+  beats the view behind it) and `dialog`: while a modal dialog (`aria-modal`) is open only its own shortcuts and its own Escape work.
+- **Typing is never taken.** Bare keys (`J`, `E`, `?`, `Delete`) do nothing while focus is in a text field, select or the rich-text
+  editor, and caret keys with a modifier (word jumps) stay the field's. Chords with Ctrl/Alt/Cmd work from a field, except Option on
+  a Mac and Ctrl+Alt (AltGr) elsewhere, which type characters. Copy, Cut, Paste, Select all, Undo, Redo and Find are never
+  bound. Enter and Space are left to a focused button or link, and an open menu keeps its own keys. Events already
+  `defaultPrevented` (the editor's own bindings, a menu), IME composition and held-key repeats of one-shot actions are ignored, and
+  the browser's default is prevented only when a handler actually ran.
+- **Layouts.** A key is matched on `event.key` (so it follows AZERTY or Dvorak) with `event.code` as the fallback when `event.key` is
+  not a Latin character - macOS Option+N, or a Cyrillic layout.
+- **Hints.** Buttons that a shortcut also does carry `aria-keyshortcuts` and a tooltip such as "Reply (Ctrl+R)"; their accessible
+  names are unchanged (`useShortcutProps()` gives a control both).
+
+Known limits: a browser keeps a few keys for itself (`Ctrl+N`, `Ctrl+T`, `Ctrl+W` are never delivered to a page, and some browsers claim
+`Ctrl+Shift+A/B/C/M/S`); and a message body is shown in a sandboxed iframe, which forwards no key events, so after clicking into a
+message body press Tab or click the list before using a shortcut. In the compose body the editor's own bindings win over `Ctrl+Shift+S`, `B`
+and `L` (strike-through, quote, align left).
+
+## Plugin UI surface
+
+Server plugins can ship their own pages (see the plugin manifest's `ui` field in `@rapidmx/restapi`). The server builds
+them together with this package, so they share one React, one `@rapidmx/react-shared` state and one stylesheet. The
+modules below are the **supported surface for plugin pages**. Anything else under `apps/` is internal and may change in
+any release.
+
+### Shells
+
+| Import | Use |
+| --- | --- |
+| `shared/components/layout/AppShell.js` | Chrome for webmail apps: app rail, header, user menu, impersonation banner, compose and unlock providers. `active` is a core app or the plugin's `appRail` item id. The user menu shows an "Admin Console" item to an administrator even when their session isn't elevated (it asks auth-server for the user's own roles, using the `trustedRoles` page prop) and, in Mail, the new-mail pop-up switch. |
+| `shared/components/settings/layout/SettingsShell.js` | Settings chrome with the section list and mailbox switcher. `active` is the plugin's `settingsSections` item id. `useSettingsShell()` gives the selected `mailboxUid` and the accessible `mailboxes`. |
+| `shared/components/admin/layout/AdminShell.js` | Admin console chrome, gated on administrator access - an administrator whose session isn't elevated is sent to auth-server's `/auth/elevate` page and returned. `active` is the plugin's `adminNav` item id. |
+| `shared/components/layout/BrandingChrome.js` | `BrandingHeader` and `BrandingFooter`, for pages that don't use a shell, such as public pages. |
+| `shared/plugins/pluginNav.js` | The `PluginNav`, `PluginUiNavItem` and `PluginNavProps` types. |
+
+Every www and admin page receives a `pluginNav` prop from the server. It lists the settings sections, admin sections and
+app rail entries of every enabled plugin whose UI built. The shells append those entries after their own, with a generic
+icon. An entry whose id matches a core entry is skipped, and so is one whose `href` isn't a same-origin path. Pass the
+page props straight to the shell so the navigation shows:
+
+```tsx
+import React from "react";
+import SettingsShell, {
+    SettingsShellProps,
+    useSettingsShell,
+} from "@rapidmx/web-client/shared/components/settings/layout/SettingsShell.js";
+
+export default function RemindersSettingsPage(props: Omit<SettingsShellProps, "active">) {
+    return (
+        <SettingsShell {...props} active="reminders">
+            <RemindersSettings />
+        </SettingsShell>
+    );
+}
+
+function RemindersSettings() {
+    const { mailboxUid } = useSettingsShell();
+    return <p>Settings for {mailboxUid}</p>;
+}
+```
+
+Public and escrow pages get no `pluginNav`.
+
+### From `@rapidmx/react-shared`
+
+Plugin pages import these directly from `@rapidmx/react-shared`, which the server resolves to the same copy the shells
+use:
+
+- `branding/useBranding.js`: `useBranding()`, for the branding and icon of pages outside a shell;
+- `auth/session.js`: `useRedirectIfUnauthenticated()`, already called by every shell;
+- `util/api.js`: `apiFetch()` and `ApiRequestError`, for calling the plugin's own API routes;
+- `mail/mailApi.js`: mailboxes and folders, such as `listMailboxes()` and `listFolders()`;
+- `components/buttons/Button.js`, `components/feedback/Alert.js` and `components/feedback/Skeleton.js`;
+- `components/forms/FormField.js`;
+- `components/overlays/Modal.js` and `components/overlays/Drawer.js`;
+- `components/pickers/MiniDatePicker.js`.
+
+## Development
+
+```sh
+yarn install
+yarn test        # vitest with coverage gates
+yarn lint
+yarn build       # tsc into dist/apps
+```

package/apps/shared/auth/accountUrl.ts

@@ -0,0 +1,9 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** auth-server's account page, or `undefined` when no auth-server is configured. Tolerates a configured URL with a trailing slash. */
+export function accountUrlOf(authServerUrl: string | undefined): string | undefined {
+    return authServerUrl ? `${authServerUrl.replace(/\/+$/, "")}/account` : undefined;
+}

package/apps/shared/auth/adminAccess.ts

@@ -0,0 +1,99 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { authApiFetch } from "@rapidmx/react-shared/util/api.js";
+
+/**
+ * Whether the signed-in user holds an administrator role, learned without elevating.
+ *
+ * The JWT the browser carries can't say: auth-server strips every trusted role from a token that isn't elevated
+ * (`TokenUtils.resolveTokenUser()`), so `trusted` (from the JWT) is false for a real administrator until they confirm
+ * their identity on auth-server's elevation page. The role itself lives on the caller's own `User` record, which they may
+ * always read - `GET {authServerUrl}/api/users/me` (the same call auth-server's own UI makes "to check for admin access") -
+ * so the answer is read from there, with the same cross-origin credentials the profile lookups use.
+ *
+ * This only decides whether a menu item is shown. The `/admin` pages and API stay authoritative: they check the role and
+ * the elevation themselves, and the link only navigates (`/admin` then runs the elevation redirect), so a wrong answer
+ * - a stale cache, a tampered `sessionStorage` - can show a link that leads to "no administrator access", never more.
+ */
+
+/** The roles the server treats as trusted when it isn't configured otherwise (`trusted_roles`, default `["admin"]`). */
+export const DEFAULT_TRUSTED_ROLES: readonly string[] = ["admin"];
+
+/** `sessionStorage` key prefix of a remembered answer; the user's uid follows, so another account signing in in the same
+ * tab never inherits it. */
+export const ADMIN_ACCESS_KEY_PREFIX = "rapidmx-admin-access:";
+
+/** How long a remembered answer is trusted - long enough that navigating between the apps costs no request, short enough
+ * that a role granted or removed shows up within the sitting. */
+export const ADMIN_ACCESS_TTL_MS = 30 * 60 * 1000;
+
+/** Lookups in flight, by key, so two components asking at once make one request. */
+const lookups = new Map<string, Promise<boolean | undefined>>();
+
+/** Forgets the lookups in flight (tests). */
+export function resetAdminAccessLookups(): void {
+    lookups.clear();
+}
+
+function readRemembered(key: string, now: number): boolean | undefined {
+    try {
+        const stored = JSON.parse(sessionStorage.getItem(key) ?? "null") as { admin?: unknown; at?: unknown } | null;
+        if (typeof stored?.admin === "boolean" && typeof stored.at === "number" && now - stored.at >= 0 && now - stored.at < ADMIN_ACCESS_TTL_MS) {
+            return stored.admin;
+        }
+    } catch {
+        // Unreadable, or storage unavailable - ask again.
+    }
+    return undefined;
+}
+
+function remember(key: string, admin: boolean, now: number): void {
+    try {
+        sessionStorage.setItem(key, JSON.stringify({ admin, at: now }));
+    } catch {
+        // Storage unavailable - the next page load asks again.
+    }
+}
+
+/**
+ * Resolves `true` when `userUid`'s own `User` record on auth-server carries one of `trustedRoles`, `false` when it
+ * doesn't, and `undefined` when that couldn't be established (unreachable, blocked by CORS, not signed in, an unexpected
+ * body, or a record that isn't this user's). Only a real answer is remembered; a failure is asked again on the next page.
+ * Never rejects.
+ */
+export function lookUpAdminAccess(
+    authServerUrl: string,
+    userUid: string,
+    trustedRoles: readonly string[] = DEFAULT_TRUSTED_ROLES,
+    now: number = Date.now(),
+): Promise<boolean | undefined> {
+    const key = `${ADMIN_ACCESS_KEY_PREFIX}${userUid}`;
+    const remembered = readRemembered(key, now);
+    if (remembered !== undefined) {
+        return Promise.resolve(remembered);
+    }
+    const inFlight = lookups.get(key);
+    if (inFlight) {
+        return inFlight;
+    }
+    const lookup = (async (): Promise<boolean | undefined> => {
+        try {
+            const user = await authApiFetch<{ uid?: unknown; roles?: unknown } | null>(authServerUrl, "/users/me");
+            if (!user || user.uid !== userUid || !Array.isArray(user.roles)) {
+                return undefined;
+            }
+            const admin = user.roles.some((role) => typeof role === "string" && trustedRoles.includes(role));
+            remember(key, admin, now);
+            return admin;
+        } catch {
+            return undefined;
+        } finally {
+            // Answered: what was learned is in storage; a failure may be asked again.
+            lookups.delete(key);
+        }
+    })();
+    lookups.set(key, lookup);
+    return lookup;
+}

package/apps/shared/components/admin/elevation.ts

@@ -0,0 +1,61 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+
+/**
+ * The `ApiRequestError.code` a `@RequiresElevation()` endpoint answers a caller whose token isn't elevated with
+ * (a 403 - `ApiErrors.AUTH_REQUIRES_ELEVATION` in `@rapidrest/service-core`). Distinct from `api-103` (the caller is
+ * elevated but lacks the trusted role), which no amount of elevating fixes.
+ */
+export const ELEVATION_REQUIRED_CODE = "api-104";
+
+/** `sessionStorage` key holding the time (`Date.now()`) the browser was last sent to auth-server to elevate. */
+export const ELEVATION_ATTEMPT_KEY = "rapidmx-admin-elevation-attempt";
+
+/** How long after sending the browser to elevate a second `api-104` is taken to mean the elevation didn't take
+ * effect (e.g. auth-server's elevated cookie never reaching this origin), rather than a fresh need to elevate. */
+export const ELEVATION_RETRY_WINDOW_MS = 2 * 60 * 1000;
+
+/** Whether `err` is a 403 from an elevation-gated endpoint for a caller whose token isn't elevated. */
+export function isElevationRequired(err: unknown): boolean {
+    return err instanceof ApiRequestError && err.status === 403 && err.code === ELEVATION_REQUIRED_CODE;
+}
+
+/** auth-server's elevation page: it sends the browser back to `returnTo` once the user has confirmed their
+ * identity, or to its own account page if they cancel. */
+export function elevationUrl(authServerUrl: string, returnTo: string): string {
+    return `${authServerUrl}/auth/elevate?return_to=${encodeURIComponent(returnTo)}`;
+}
+
+/** Whether the browser was sent to elevate within `ELEVATION_RETRY_WINDOW_MS` of `now`. `false` when nothing was
+ * recorded, the record is unreadable or from the future, or storage is unavailable. */
+export function elevationAttemptedRecently(now: number = Date.now()): boolean {
+    try {
+        const recorded = Number(sessionStorage.getItem(ELEVATION_ATTEMPT_KEY));
+        const elapsed = now - recorded;
+        return recorded > 0 && elapsed >= 0 && elapsed < ELEVATION_RETRY_WINDOW_MS;
+    } catch {
+        return false;
+    }
+}
+
+/** Remembers, for this tab, that the browser is about to be sent to elevate. A no-op where storage is unavailable
+ * (then only the first-round protection is lost - elevating needs the user to confirm each time round). */
+export function recordElevationAttempt(now: number = Date.now()): void {
+    try {
+        sessionStorage.setItem(ELEVATION_ATTEMPT_KEY, String(now));
+    } catch {
+        // See the doc comment.
+    }
+}
+
+/** Forgets any recorded attempt - once elevation has worked, or when the user asks to try again. */
+export function clearElevationAttempt(): void {
+    try {
+        sessionStorage.removeItem(ELEVATION_ATTEMPT_KEY);
+    } catch {
+        // Nothing was recorded.
+    }
+}

package/apps/shared/components/admin/layout/AdminShell.tsx

@@ -26,9 +26,17 @@ import { getSetupStatus } from "@rapidmx/react-shared/admin/setupApi.js";
 import { useRedirectIfUnauthenticated } from "@rapidmx/react-shared/auth/session.js";
 import useBranding from "@rapidmx/react-shared/branding/useBranding.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
 import BottomTabBar, { NavItem } from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
-import { BrandingFooter, BrandingHeader } from "../../layout/BrandingChrome.js";
+import { BrandingFooter } from "../../layout/BrandingChrome.js";
 import UserMenu from "../../layout/UserMenu.js";
+import {
+    clearElevationAttempt,
+    elevationAttemptedRecently,
+    elevationUrl,
+    isElevationRequired,
+    recordElevationAttempt,
+} from "../elevation.js";
 import { signOutOfConsole } from "../signOut.js";
 import { mergePluginNavItems, PluginNav, PluginNavProps } from "../../../plugins/pluginNav.js";
 
@@ -68,7 +76,9 @@ export interface AdminShellProps extends PluginNavProps {
     impersonationBaseUrl?: string;
 }
 
-type Status = "checking" | "denied" | "error" | "authorized";
+/** `elevating`: the browser is being sent to auth-server to confirm the user's identity. `elevationFailed`: it was
+ * sent a moment ago and the console still isn't elevated - see `elevation.ts`. */
+type Status = "checking" | "denied" | "elevating" | "elevationFailed" | "error" | "authorized";
 
 /** Sections shown in the persistent icon rail / mobile tab bar — every admin area reachable from
  * anywhere in the console. Deliberately excludes `quarantine`/`ingestQueue`: those are scoped to a
@@ -148,14 +158,24 @@ export function adminNavItems(pluginNav?: PluginNav): NavItem[] {
 }
 
 /**
- * Gates every `apps/admin` page behind the `admin` trusted role. Uses `GET /api/admin/release-notes` (any
- * `BaseAdminRoute` endpoint works — this one is side-effect-free) purely as a canary: a 200 means the
- * caller's JWT carries a trusted role, a 403 means it doesn't. There is no local step-up/elevation flow
- * (that would need a cross-origin call to auth-server's own elevation endpoint — not wired up yet).
+ * Gates every `apps/admin` page behind the `admin` trusted role, and behind an elevated session. Uses
+ * `GET /api/admin/release-notes` (any `BaseAdminRoute` endpoint works — this one is side-effect-free) purely as a
+ * canary. The endpoint is class-level `@RequiresElevation()`, checked *before* the trusted-role check, so a 200 means the
+ * caller's JWT is elevated and carries a trusted role: show the console. Otherwise:
+ *
+ * 403 `api-104` means the JWT isn't elevated (an administrator's normal sign-in). There is no local step-up form; the
+ * browser is sent to auth-server's `/auth/elevate?return_to=<this page>`, which returns it here once the user has
+ * confirmed their identity (or to its own account page if they cancel). Sent at most once per
+ * `ELEVATION_RETRY_WINDOW_MS`, so an elevated cookie that never reaches this origin can't bounce the browser back
+ * and forth - see `elevation.ts`, and the "didn't take effect" alert with its own "Try again" below.
+ *
+ * 403 `api-103` (elevated, but not an administrator), any other 403, and 401 mean "no administrator access".
  */
 export default function AdminShell({ active, userUid, authServerUrl, pluginNav, children }: PropsWithChildren<AdminShellProps>) {
     const [status, setStatus] = useState<Status>("checking");
     const [error, setError] = useState<string | null>(null);
+    // `branding` only feeds the footer below: the admin-configured header is for the webmail and public pages, not the
+    // console. `useBranding()` is still what injects the custom stylesheet and supplies the rail's icon.
     const { branding, iconSrc } = useBranding();
 
     useRedirectIfUnauthenticated(userUid, authServerUrl);
@@ -166,6 +186,8 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
         }
         apiFetch("/admin/release-notes")
             .then(async () => {
+                // Elevated (or elevation isn't needed): a later expiry of the elevation may send the user round again.
+                clearElevationAttempt();
                 // Until first-run setup is finished, every other admin page sends the admin to the wizard. A failed
                 // check never blocks the console - the admin can still reach setup from the Mailboxes page.
                 if (active !== "setup") {
@@ -181,6 +203,17 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
                 setStatus("authorized");
             })
             .catch((err) => {
+                if (isElevationRequired(err)) {
+                    // Without auth-server's URL there is nowhere to send the browser to elevate.
+                    if (!authServerUrl) {
+                        setStatus("denied");
+                    } else if (elevationAttemptedRecently()) {
+                        setStatus("elevationFailed");
+                    } else {
+                        startElevation(authServerUrl);
+                    }
+                    return;
+                }
                 if (err instanceof ApiRequestError && (err.status === 403 || err.status === 401)) {
                     setStatus("denied");
                     return;
@@ -190,6 +223,18 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
             });
     }, [userUid]);
 
+    /** Remembers the attempt, then sends the browser to auth-server to confirm the user's identity. */
+    function startElevation(authServer: string) {
+        recordElevationAttempt();
+        setStatus("elevating");
+        window.location.href = elevationUrl(authServer, window.location.href);
+    }
+
+    function handleRetryElevation() {
+        clearElevationAttempt();
+        startElevation(authServerUrl!);
+    }
+
     function handleSignOut() {
         // Ends the auth-server session and tells other tabs, not just navigates - see `signOutOfConsole()`.
         void signOutOfConsole(authServerUrl);
@@ -198,6 +243,28 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
     let content: ReactNode;
     if (!userUid || status === "checking") {
         content = <div className="min-h-screen" />;
+    } else if (status === "elevating") {
+        content = (
+            <div className="min-h-screen flex items-center justify-center p-8">
+                <p role="status" className="text-sm text-text-muted">
+                    Redirecting to confirm your identity&hellip;
+                </p>
+            </div>
+        );
+    } else if (status === "elevationFailed") {
+        content = (
+            <div className="min-h-screen flex items-center justify-center p-8">
+                <div className="w-full max-w-md flex flex-col items-start">
+                    <Alert>
+                        Confirming your identity didn&rsquo;t take effect, so the administrator console is still locked. Try again,
+                        and if this keeps happening, sign out and sign back in.
+                    </Alert>
+                    <Button type="button" className="!w-auto" onClick={handleRetryElevation}>
+                        Try again
+                    </Button>
+                </div>
+            </div>
+        );
     } else if (status === "denied") {
         content = (
             <div className="min-h-screen flex items-center justify-center p-8">
@@ -260,7 +327,6 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
 
     return (
         <>
-            <BrandingHeader branding={branding} />
             {content}
             <BrandingFooter branding={branding} />
         </>

package/apps/shared/components/admin/settings/BrandingForm.tsx

@@ -131,7 +131,8 @@ export default function BrandingForm({ branding, onChange, embedded = false }: B
                     <h1 className="text-xl font-bold uppercase tracking-wide mb-1">Branding</h1>
                     <p className="text-sm text-text-muted mb-5">
                         Customize the logo, nav-header icon, product name, and chrome shown to every visitor of the
-                        webmail and admin console — including anonymous booking-page visitors.
+                        webmail and admin console — including anonymous booking-page visitors. The header appears on the
+                        webmail and public pages, not in the admin console; the footer appears in both.
                     </p>
                 </>
             )}