@rapidmx/web-client 0.7.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/admin/settings/MailboxPolicyForm.tsx

@@ -18,6 +18,23 @@ function toGb(bytes: number): string {
     return String(bytes / GB);
 }
 
+/** Whether a quota field's text is not the given number of bytes. */
+function differsFromBytes(text: string, bytes: number): boolean {
+    return Math.round(Number(text) * GB) !== bytes;
+}
+
+/** Puts a field back to the server's config value; nothing is saved until the form is. */
+function ResetToDefault({ label, shown, onClick }: { label: string; shown: boolean; onClick: () => void }) {
+    if (!shown) {
+        return null;
+    }
+    return (
+        <Button type="button" variant="text" className="!w-auto self-start text-xs -mt-2" onClick={onClick}>
+            Reset to server default ({label})
+        </Button>
+    );
+}
+
 /** The form's values as they were loaded or last saved. */
 interface Baseline {
     defaultQuotaGb: string;
@@ -35,8 +52,13 @@ export interface MailboxPolicyFormProps {
     embedded?: boolean;
 }
 
-/** The mailbox defaults editor, shared by the Mailbox Policy page and the setup wizard. */
+/**
+ * The mailbox defaults editor, shared by the Mailbox Policy page and the setup wizard. Each field can be reset to what
+ * the server's config currently says (`policy.defaults`), which lets an administrator take a newly deployed value
+ * without typing it in; the reset fills the field in and is saved with the rest of the form.
+ */
 export default function MailboxPolicyForm({ policy, onChange, onDirtyChange, embedded = false }: MailboxPolicyFormProps) {
+    const defaults = policy.defaults;
     const [defaultQuotaGb, setDefaultQuotaGb] = useState(toGb(policy.defaultQuotaBytes));
     const [autoProvisionEnabled, setAutoProvisionEnabled] = useState(policy.autoProvisionEnabled);
     const [autoProvisionQuotaGb, setAutoProvisionQuotaGb] = useState(toGb(policy.autoProvisionQuotaBytes));
@@ -119,6 +141,11 @@ export default function MailboxPolicyForm({ policy, onChange, onDirtyChange, emb
                     />
                     <span className="text-xs text-text-muted">The storage a mailbox starts with when an administrator creates it.</span>
                 </label>
+                <ResetToDefault
+                    label={defaults ? `${toGb(defaults.defaultQuotaBytes)} GB` : ""}
+                    shown={!!defaults && differsFromBytes(defaultQuotaGb, defaults.defaultQuotaBytes)}
+                    onClick={() => setDefaultQuotaGb(toGb(defaults!.defaultQuotaBytes))}
+                />
                 <label className="flex items-start gap-2 text-sm">
                     <input
                         type="checkbox"
@@ -134,19 +161,31 @@ export default function MailboxPolicyForm({ policy, onChange, onDirtyChange, emb
                         </span>
                     </span>
                 </label>
+                <ResetToDefault
+                    label={defaults?.autoProvisionEnabled ? "on" : "off"}
+                    shown={!!defaults && autoProvisionEnabled !== defaults.autoProvisionEnabled}
+                    onClick={() => setAutoProvisionEnabled(defaults!.autoProvisionEnabled)}
+                />
                 {autoProvisionEnabled && (
-                    <label className="flex flex-col gap-1.5 text-sm">
-                        <span className="font-semibold">Quota for self-created mailboxes (GB)</span>
-                        <input
-                            aria-label="Quota for self-created mailboxes (GB)"
-                            type="number"
-                            min={0}
-                            step="any"
-                            className={INPUT_CLASS}
-                            value={autoProvisionQuotaGb}
-                            onChange={(e) => setAutoProvisionQuotaGb(e.target.value)}
+                    <>
+                        <label className="flex flex-col gap-1.5 text-sm">
+                            <span className="font-semibold">Quota for self-created mailboxes (GB)</span>
+                            <input
+                                aria-label="Quota for self-created mailboxes (GB)"
+                                type="number"
+                                min={0}
+                                step="any"
+                                className={INPUT_CLASS}
+                                value={autoProvisionQuotaGb}
+                                onChange={(e) => setAutoProvisionQuotaGb(e.target.value)}
+                            />
+                        </label>
+                        <ResetToDefault
+                            label={defaults ? `${toGb(defaults.autoProvisionQuotaBytes)} GB` : ""}
+                            shown={!!defaults && differsFromBytes(autoProvisionQuotaGb, defaults.autoProvisionQuotaBytes)}
+                            onClick={() => setAutoProvisionQuotaGb(toGb(defaults!.autoProvisionQuotaBytes))}
                         />
-                    </label>
+                    </>
                 )}
                 <div>
                     <Button type="submit" loading={saving} disabled={saving} className="!w-auto">

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