@rapidmx/web-client 0.8.0 → 0.9.0

package/README.md

@@ -32,7 +32,7 @@ any release.
 | --- | --- |
 | `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/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. |
 

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>
                 </>
             )}

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

@@ -7,6 +7,7 @@ import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { DnsRecordCheck, Domain, getDnsSetup, getDomain, verifyDomain } from "@rapidmx/react-shared/admin/domainsApi.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+import CopyButton from "@rapidmx/react-shared/components/buttons/CopyButton.js";
 
 const RECORD_TYPE_LABELS: Record<DnsRecordCheck["type"], string> = {
     ownership: "Ownership (TXT)",
@@ -16,6 +17,31 @@ const RECORD_TYPE_LABELS: Record<DnsRecordCheck["type"], string> = {
     dmarc: "DMARC",
 };
 
+/** How each record is named in a Copy button's accessible name ("Copy value for the SPF record"). */
+const RECORD_TYPE_NAMES: Record<DnsRecordCheck["type"], string> = {
+    ownership: "ownership TXT",
+    mx: "MX",
+    spf: "SPF",
+    dkim: "DKIM",
+    dmarc: "DMARC",
+};
+
+/** An MX record's recommended value is `"<priority> <mail server>"` - two separate fields in a DNS provider's form. */
+function splitMxValue(value: string): { priority: string; server: string } | null {
+    const match = /^(\d+)\s+(\S+)$/.exec(value.trim());
+    return match ? { priority: match[1], server: match[2] } : null;
+}
+
+/** A value to type into a DNS provider's form, shown in full (long DKIM keys wrap) with a Copy button beside it. */
+function CopyableValue({ value, copyLabel }: { value: string; copyLabel: string }) {
+    return (
+        <div className="flex items-start gap-2">
+            <code className="flex-1 min-w-0 text-xs break-all">{value}</code>
+            <CopyButton value={value} label={copyLabel} />
+        </div>
+    );
+}
+
 export interface DomainDnsSetupProps {
     uid: string;
     /** Called with the domain every time it's (re)loaded - e.g. after "Verify now". */
@@ -33,7 +59,6 @@ export default function DomainDnsSetup({ uid, onLoaded }: DomainDnsSetupProps) {
     const [error, setError] = useState<string | null>(null);
     const [verifying, setVerifying] = useState(false);
     const [verifyError, setVerifyError] = useState<string | null>(null);
-    const [copied, setCopied] = useState(false);
 
     function reload(id: string) {
         setLoading(true);
@@ -71,16 +96,6 @@ export default function DomainDnsSetup({ uid, onLoaded }: DomainDnsSetupProps) {
         }
     }
 
-    async function handleCopy(value: string) {
-        try {
-            await navigator.clipboard.writeText(value);
-            setCopied(true);
-            setTimeout(() => setCopied(false), 2000);
-        } catch {
-            // Clipboard access can be denied by the browser — the value is still selectable/copyable by hand.
-        }
-    }
-
     if (loading) {
         return <p className="text-sm text-text-muted">Loading&hellip;</p>;
     }
@@ -88,8 +103,9 @@ export default function DomainDnsSetup({ uid, onLoaded }: DomainDnsSetupProps) {
         return <Alert>{error ?? "Domain not found."}</Alert>;
     }
 
-    const ownershipValue =
-        dnsSetup.find((c) => c.type === "ownership")?.recommendedValue ?? `rapidmx-domain-verification=${domain.verificationToken}`;
+    const ownership = dnsSetup.find((c) => c.type === "ownership");
+    const ownershipValue = ownership?.recommendedValue ?? `rapidmx-domain-verification=${domain.verificationToken}`;
+    const ownershipName = ownership?.recordName || domain.name;
 
     return (
         <div className="flex flex-col gap-5">
@@ -118,14 +134,18 @@ export default function DomainDnsSetup({ uid, onLoaded }: DomainDnsSetupProps) {
                         <p className="text-sm mb-2">
                             Add the following TXT record to <strong>{domain.name}</strong> to prove ownership, then verify:
                         </p>
-                        <div className="flex items-center gap-2">
-                            <code className="flex-1 text-xs bg-surface-alt border border-border rounded-sm py-2 px-3 overflow-x-auto whitespace-nowrap">
-                                {ownershipValue}
-                            </code>
-                            <Button type="button" variant="secondary" className="!w-auto shrink-0" onClick={() => handleCopy(ownershipValue)}>
-                                {copied ? "Copied" : "Copy"}
-                            </Button>
-                        </div>
+                        <dl className="grid grid-cols-[auto_1fr] items-start gap-x-4 gap-y-2 text-sm">
+                            <dt className="text-text-muted py-2">Type</dt>
+                            <dd className="py-2">TXT</dd>
+                            <dt className="text-text-muted py-2">Name / host</dt>
+                            <dd className="bg-surface-alt border border-border rounded-sm py-1.5 px-3">
+                                <CopyableValue value={ownershipName} copyLabel="Copy name for the ownership TXT record" />
+                            </dd>
+                            <dt className="text-text-muted py-2">Value</dt>
+                            <dd className="bg-surface-alt border border-border rounded-sm py-1.5 px-3">
+                                <CopyableValue value={ownershipValue} copyLabel="Copy value for the ownership TXT record" />
+                            </dd>
+                        </dl>
                         {verifyError && (
                             <div className="mt-3">
                                 <Alert>{verifyError}</Alert>
@@ -145,7 +165,7 @@ export default function DomainDnsSetup({ uid, onLoaded }: DomainDnsSetupProps) {
                         <table className="w-full text-sm border-collapse">
                             <thead>
                                 <tr>
-                                    {["Record", "Status", "Recommended value"].map((h) => (
+                                    {["Record", "Status", "Name / host", "Recommended value"].map((h) => (
                                         <th
                                             key={h}
                                             className="text-left text-xs uppercase tracking-wide text-text-muted py-2 px-2.5 border-b border-border"
@@ -158,7 +178,10 @@ export default function DomainDnsSetup({ uid, onLoaded }: DomainDnsSetupProps) {
                             <tbody>
                                 {dnsSetup.map((check) => (
                                     <tr key={check.type}>
-                                        <td className="py-2.5 px-2.5 border-b border-border">{RECORD_TYPE_LABELS[check.type]}</td>
+                                        <td className="py-2.5 px-2.5 border-b border-border">
+                                            {RECORD_TYPE_LABELS[check.type]}
+                                            <div className="text-xs text-text-muted">Type: {check.recordKind}</div>
+                                        </td>
                                         <td className="py-2.5 px-2.5 border-b border-border">
                                             {!check.configured ? (
                                                 <span className="text-xs text-text-muted">Not configured</span>
@@ -173,15 +196,54 @@ export default function DomainDnsSetup({ uid, onLoaded }: DomainDnsSetupProps) {
                                             )}
                                         </td>
                                         <td className="py-2.5 px-2.5 border-b border-border text-text-muted">
-                                            <code className="text-xs">{check.recommendedValue ?? "—"}</code>
+                                            {check.recordName ? (
+                                                <CopyableValue
+                                                    value={check.recordName}
+                                                    copyLabel={`Copy name for the ${RECORD_TYPE_NAMES[check.type]} record`}
+                                                />
+                                            ) : (
+                                                <code className="text-xs">—</code>
+                                            )}
+                                        </td>
+                                        <td className="py-2.5 px-2.5 border-b border-border text-text-muted">
+                                            {check.recommendedValue ? (
+                                                <DnsRecordValue check={check} value={check.recommendedValue} />
+                                            ) : (
+                                                <code className="text-xs">—</code>
+                                            )}
                                         </td>
                                     </tr>
                                 ))}
                             </tbody>
                         </table>
                     </div>
+                    <p className="text-xs text-text-muted mt-3">
+                        Some DNS providers want the name relative to the domain (for example <code>@</code> for the domain itself) rather
+                        than the full name.
+                    </p>
                 </div>
             )}
         </div>
     );
 }
+
+/** The value cell of a checklist row: an MX value as its two form fields (priority and mail server), anything else whole. */
+function DnsRecordValue({ check, value }: { check: DnsRecordCheck; value: string }) {
+    const recordName = RECORD_TYPE_NAMES[check.type];
+    const mx = check.type === "mx" ? splitMxValue(value) : null;
+    if (!mx) {
+        return <CopyableValue value={value} copyLabel={`Copy value for the ${recordName} record`} />;
+    }
+    return (
+        <div className="flex flex-col gap-1.5">
+            <div className="flex items-start gap-2">
+                <span className="text-xs w-20 shrink-0 pt-1">Priority</span>
+                <CopyableValue value={mx.priority} copyLabel={`Copy priority for the ${recordName} record`} />
+            </div>
+            <div className="flex items-start gap-2">
+                <span className="text-xs w-20 shrink-0 pt-1">Mail server</span>
+                <CopyableValue value={mx.server} copyLabel={`Copy mail server for the ${recordName} record`} />
+            </div>
+        </div>
+    );
+}

package/apps/shared/components/layout/BrandingChrome.tsx

@@ -51,8 +51,9 @@ function BrandingHtml({ html }: { html: string | undefined }) {
 }
 
 /**
- * Renders the admin-configured `Branding.headerHtml`/`footerHtml` (see `useBranding()`), sanitized - shared by
- * the webmail and admin chromes. The escrow console deliberately renders no branding HTML at all.
+ * Renders the admin-configured `Branding.headerHtml`/`footerHtml` (see `useBranding()`), sanitized. The webmail
+ * chrome (`AppShell`) shows both; the admin console shows only the footer - its header is the console's own - and the
+ * escrow console deliberately renders no branding HTML at all.
  */
 export function BrandingHeader({ branding }: { branding: Branding | null }) {
     return <BrandingHtml html={branding?.headerHtml} />;

package/apps/shared/components/layout/MailboxProvisioning.tsx

@@ -10,6 +10,28 @@ import Button from "@rapidmx/react-shared/components/buttons/Button.js";
 
 type Status = "checking" | "needs_selection" | "creating" | "unavailable" | "retryable";
 
+/** What the "Retry" screen says: the server couldn't read its provisioning policy (503) ... */
+const RETRY_POLICY_TEXT = "We couldn\u2019t check whether a mailbox can be set up for you. Please try again.";
+/** ... or couldn't reach the identity service (auth-server) it looks the caller's username up in (502). */
+const RETRY_IDENTITY_TEXT = "We couldn\u2019t reach the identity service to set up your mailbox. Please try again.";
+
+/** The longest server message shown as the reason a mailbox isn't available - a real reason is a sentence. */
+const MAX_REASON_LENGTH = 200;
+
+/**
+ * The reason to show under "No mailbox available": the server's own message, for a refusal it made on purpose - a
+ * 4xx such as 404 "Automatic mailbox provisioning is not enabled." or 404 "No username is registered for this account."
+ * Never for a 5xx (whose message is whatever went wrong inside the server) or a failure that never reached it (a network
+ * error's message is browser jargon), and only its first line, capped in length. `null` when there's nothing safe to show.
+ */
+function unavailableReason(err: unknown): string | null {
+    if (!(err instanceof ApiRequestError) || err.status < 400 || err.status >= 500) {
+        return null;
+    }
+    const line = err.message.split(/\r?\n/)[0].trim();
+    return line ? line.slice(0, MAX_REASON_LENGTH) : null;
+}
+
 /**
  * Rendered by each app's shell (Mail/Calendar/Contacts/Tasks) *instead of* the normal `AppShell`
  * chrome (icon rail, header, folder tree, ...) when the caller has no mailbox — a full-screen,
@@ -18,14 +40,20 @@ type Status = "checking" | "needs_selection" | "creating" | "unavailable" | "ret
  * auto-provisioning — see `BaseMailboxRoute.autoProvision()`'s own doc comment in `@rapidmx/restapi`
  * for the full contract — which is itself a no-op (a 404) unless an admin has both turned it on
  * (`mail:auto_provision:enabled`) and configured at least one domain (`mail:domains`). Safe to render
- * unconditionally in that place: any failure (disabled, no registered username, the identity service
- * unreachable) just falls back to the same plain "no mailbox" message this replaces.
+ * unconditionally in that place: a failure ends in one of two screens. A 502 (the identity service couldn't be
+ * reached) or 503 (the server couldn't read its provisioning policy) is transient and offers "Retry". Anything
+ * else is "No mailbox available - ask an administrator", now with the server's own reason above that advice when it
+ * refused deliberately (a 4xx, e.g. "Automatic mailbox provisioning is not enabled.") so the caller and the
+ * administrator they ask can tell why - see `unavailableReason()`.
  */
 export default function MailboxProvisioning() {
     const [status, setStatus] = useState<Status>("checking");
     const [options, setOptions] = useState<MailboxAutoProvisionAliasOption[]>([]);
     const [selected, setSelected] = useState("");
     const [error, setError] = useState<string | null>(null);
+    // Why the caller has no mailbox (see `unavailableReason()`), and what the retry screen says.
+    const [reason, setReason] = useState<string | null>(null);
+    const [retryText, setRetryText] = useState(RETRY_POLICY_TEXT);
 
     // Bumped by "Retry" to re-run the check below.
     const [attempt, setAttempt] = useState(0);
@@ -48,9 +76,18 @@ export default function MailboxProvisioning() {
                     window.location.reload();
                 }
             })
-            // A 503 means the server couldn't read its own provisioning policy right now - not that there's no
-            // mailbox to be had - so it gets a retry instead of the permanent "ask an administrator" message.
-            .catch((err) => setStatus(err instanceof ApiRequestError && err.status === 503 ? "retryable" : "unavailable"));
+            // A 503 means the server couldn't read its own provisioning policy right now, and a 502 that it couldn't
+            // reach the identity service - neither says there's no mailbox to be had - so they get a retry instead of
+            // the permanent "ask an administrator" message.
+            .catch((err) => {
+                if (err instanceof ApiRequestError && (err.status === 503 || err.status === 502)) {
+                    setRetryText(err.status === 502 ? RETRY_IDENTITY_TEXT : RETRY_POLICY_TEXT);
+                    setStatus("retryable");
+                } else {
+                    setReason(unavailableReason(err));
+                    setStatus("unavailable");
+                }
+            });
     }, [attempt]);
 
     async function handleConfirm() {
@@ -100,7 +137,7 @@ export default function MailboxProvisioning() {
         content = (
             <>
                 <h1 className="text-lg font-bold uppercase tracking-wide">Couldn&rsquo;t check right now</h1>
-                <p className="text-sm text-text-muted">We couldn&rsquo;t check whether a mailbox can be set up for you. Please try again.</p>
+                <p className="text-sm text-text-muted">{retryText}</p>
                 <Button type="button" onClick={() => setAttempt((n) => n + 1)} className="!w-auto self-center">
                     Retry
                 </Button>
@@ -110,6 +147,7 @@ export default function MailboxProvisioning() {
         content = (
             <>
                 <h1 className="text-lg font-bold uppercase tracking-wide">No mailbox available</h1>
+                {reason && <p className="text-sm">{reason}</p>}
                 <p className="text-sm text-text-muted">Ask an administrator to create one for you.</p>
             </>
         );

package/apps/shared/components/layout/UserMenu.tsx

@@ -3,11 +3,12 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React, { useEffect, useRef, useState } from "react";
-import { formatProfileName, getMyProfile, Profile, profileInitials } from "@rapidmx/react-shared/auth/profileApi.js";
+import { formatProfileName, getMyProfile, getMyUsername, Profile, profileInitials } from "@rapidmx/react-shared/auth/profileApi.js";
 
 export interface UserMenuProps {
     userUid: string;
-    /** auth-server's base URL — where the caller's own profile (name/avatar) is fetched from, if configured. */
+    /** auth-server's base URL — where the caller's own profile (name/avatar) and username are fetched from, and what
+     * the "Account" item links into, if configured. Without it the menu shows the bare uid and has no "Account" item. */
     authServerUrl?: string;
     onSignOut: () => void;
     /** Shows an "Admin" item linking to `/admin`, above "Sign Out" — pass only for a trusted-role caller. */
@@ -40,25 +41,48 @@ function Avatar({ profile, initials, large }: { profile?: Profile; initials: str
 }
 
 /**
- * The top-right "who am I" menu shared by `MailShell` and `AdminShell`: an avatar-button trigger that opens a
- * dropdown showing the caller's avatar/name, an optional "Admin" link (trusted-role callers only), and
- * "Sign Out". Name/avatar come from auth-server's own profile endpoint (`GET /api/profiles/me`) — this
- * service has no local user directory (see `.claude/NOTES.md`) — and fall back to the bare uid/its first
- * letter when unset or unreachable, which is a fully valid, expected state for most password-registered
- * accounts (only OIDC sign-in currently populates a real avatar).
+ * The top-right "who am I" menu shared by every shell (`AppShell`, `AdminShell`, `EscrowShell`): an avatar-button
+ * trigger that opens a dropdown showing the caller's avatar/name, an "Account" link to auth-server's account page,
+ * an optional "Settings" and "Admin" link, and "Sign Out". This service has no local user directory (see
+ * `.claude/NOTES.md`), so the name and avatar come from auth-server, and the displayed name (and the initials badge)
+ * falls back down a chain: the profile's name (`GET /api/profiles/me`), else the caller's username - their first
+ * verified `name` alias (`GET /api/aliases?type=name`, asked for only when the profile gave no name) - else the bare
+ * uid. Either lookup can fail (auth-server's CORS list not including this origin, or no profile document at all - a
+ * 404 for some accounts) and neither ever surfaces as an error. The avatar image comes from the profile alone.
  */
 export default function UserMenu({ userUid, authServerUrl, onSignOut, showAdminLink, showSettingsLink }: UserMenuProps) {
     const [open, setOpen] = useState(false);
     const [profile, setProfile] = useState<Profile | undefined>(undefined);
+    const [username, setUsername] = useState<string | undefined>(undefined);
     const containerRef = useRef<HTMLDivElement>(null);
 
     useEffect(() => {
         if (!authServerUrl) {
             return;
         }
-        getMyProfile(authServerUrl)
-            .then(setProfile)
-            .catch(() => undefined);
+        let cancelled = false;
+        void (async () => {
+            let loaded: Profile | undefined;
+            try {
+                loaded = await getMyProfile(authServerUrl);
+            } catch {
+                // Unreachable, blocked, or no profile document (404) - fall through to the username.
+            }
+            if (cancelled) {
+                return;
+            }
+            setProfile(loaded);
+            // The username is only the fallback for a missing name - no second request when the profile has one.
+            if (!formatProfileName(loaded)) {
+                const alias = await getMyUsername(authServerUrl);
+                if (!cancelled) {
+                    setUsername(alias);
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
     }, [authServerUrl]);
 
     useEffect(() => {
@@ -83,8 +107,10 @@ export default function UserMenu({ userUid, authServerUrl, onSignOut, showAdminL
         };
     }, [open]);
 
-    const name = formatProfileName(profile) ?? userUid;
-    const initials = profileInitials(profile, userUid);
+    const name = formatProfileName(profile) ?? username ?? userUid;
+    const initials = profileInitials(profile, userUid, username);
+    // Tolerates a configured URL with a trailing slash, which would otherwise produce `//account`.
+    const accountUrl = authServerUrl ? `${authServerUrl.replace(/\/+$/, "")}/account` : undefined;
 
     return (
         <div className="relative" ref={containerRef}>
@@ -117,6 +143,15 @@ export default function UserMenu({ userUid, authServerUrl, onSignOut, showAdminL
                         <Avatar profile={profile} initials={initials} large />
                         <span className="text-sm font-semibold text-text truncate">{name}</span>
                     </div>
+                    {accountUrl && (
+                        <a
+                            role="menuitem"
+                            href={accountUrl}
+                            className="block px-3.5 py-2 text-sm text-text hover:bg-surface-alt"
+                        >
+                            Account
+                        </a>
+                    )}
                     {showSettingsLink && (
                         <a
                             role="menuitem"