@rapidmx/web-client 0.7.0 → 0.9.0

package/apps/shared/mail/mergeFirstPage.ts

@@ -0,0 +1,47 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** What `mergeFirstPage()` made of a fresh first page and the rows already on screen. */
+export interface MergedPage<T> {
+    /** The rows to show. */
+    rows: T[];
+    /** How many of the fresh page's rows were not on screen yet - the mail that arrived since. */
+    added: number;
+    /** `true` when `rows` is exactly the fresh page, because the whole listing fits on it. */
+    complete: boolean;
+}
+
+/**
+ * Folds a freshly fetched first page of a list into the rows already loaded (the first page plus whatever "load more"
+ * added), for the quiet refresh that follows a push event or a poll - so new mail appears without the list being reset,
+ * re-scrolled or re-selected the way a full reload would.
+ *
+ * - A page shorter than `pageSize` is the whole listing, so it simply replaces what is shown - which also drops what was
+ * deleted or moved elsewhere.
+ * - A full page is only the top of a longer listing. Its rows go first, in the server's order, followed by the loaded rows
+ * it did not repeat (older ones the reader has scrolled to). What was removed elsewhere from a long, partly loaded list
+ * stays until the next real load; nothing here can tell it from a row that merely slid off the first page.
+ * - A row in both keeps whichever copy `pick` prefers - by default the fresh one - so, for messages, a row the reader has
+ * just changed (a higher `version`) is not put back by a fetch that started before the change landed.
+ */
+export function mergeFirstPage<T>(
+    current: T[],
+    fresh: T[],
+    idOf: (row: T) => string,
+    pageSize: number,
+    pick: (current: T, fresh: T) => T = (_current, next) => next,
+): MergedPage<T> {
+    const currentById = new Map(current.map((row) => [idOf(row), row]));
+    const added = fresh.filter((row) => !currentById.has(idOf(row))).length;
+    const rows = fresh.map((row) => {
+        const existing = currentById.get(idOf(row));
+        return existing ? pick(existing, row) : row;
+    });
+    if (fresh.length < pageSize) {
+        return { rows, added, complete: true };
+    }
+    const freshIds = new Set(fresh.map(idOf));
+    return { rows: [...rows, ...current.filter((row) => !freshIds.has(idOf(row)))], added, complete: false };
+}

package/apps/shared/mail/useMailLiveUpdates.ts

@@ -0,0 +1,224 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Folder, Mailbox, listFolders } from "@rapidmx/react-shared/mail/mailApi.js";
+import { getPushClient, PushEvent } from "@rapidmx/react-shared/mail/pushClient.js";
+import type { MailboxFolders } from "../components/mail/layout/MailShell.js";
+import { SIGN_OUT_CHANNEL } from "../search/localIndexRpcClient.js";
+
+/** How often the safety-net poll runs while the tab is visible. The push socket does the real work; this is for a network
+ * that blocks or silently drops it, and for events published while it was reconnecting (Redis pub/sub is never replayed). */
+export const LIVE_POLL_INTERVAL_MS = 45_000;
+
+/** Events arriving this close together are answered with one refresh - a burst of new mail is one refetch, not one each. */
+export const LIVE_EVENT_DEBOUNCE_MS = 400;
+
+/** What changed, as far as a list on screen is concerned. */
+export interface LiveUpdates {
+    /** Bumped each time the list should quietly refetch its first page. `0` until the first bump. */
+    tick: number;
+    /** The folders the events behind the latest bump touched - `null` when that isn't known (a poll, a reconnect, the tab
+     * coming back to the front), meaning any folder may have changed. */
+    folderUids: ReadonlySet<string> | null;
+}
+
+export const NO_LIVE_UPDATES: LiveUpdates = { tick: 0, folderUids: null };
+
+/** The class names `NotificationUtils.sendMessage()` publishes are the model's (`MessageMongo`, `MessageSQL`, `FolderMongo`). */
+const MESSAGE_EVENT = /^Message/;
+const FOLDER_EVENT = /^Folder/;
+const MESSAGE_ACTIONS = new Set(["create", "update", "delete"]);
+
+/**
+ * The channels to subscribe to, most important first (the push client keeps the first `PUSH_MAX_CHANNELS`): every
+ * mailbox's Inbox - where mail lands - then each mailbox's other folders in the sidebar's own order, then the mailbox uids
+ * themselves (which announce new folders). A folder is a channel of its own; subscribing to a mailbox does not deliver its
+ * folders' events.
+ */
+export function pushChannelsFor(mailboxFolders: MailboxFolders[], mailboxes: Mailbox[]): string[] {
+    const inboxes = mailboxFolders.flatMap((entry) => entry.folders.filter((folder) => folder.type === "inbox"));
+    const others = mailboxFolders.flatMap((entry) => entry.folders.filter((folder) => folder.type !== "inbox"));
+    return [...new Set([...inboxes, ...others].map((folder) => folder.uid).concat(mailboxes.map((mailbox) => mailbox.uid)))];
+}
+
+function isFolder(value: unknown): value is Folder {
+    const folder = value as Partial<Folder> | null;
+    return !!folder && typeof folder.uid === "string" && typeof folder.mailboxUid === "string" && typeof folder.type === "string";
+}
+
+/** The folder a message event is about: the message's own `folderUid`, else the channel it arrived on (when the server said). */
+function folderOfMessageEvent(event: PushEvent): string | undefined {
+    const data = event.data as { folderUid?: unknown } | null | undefined;
+    if (typeof data?.folderUid === "string") {
+        return data.folderUid;
+    }
+    return event.channel;
+}
+
+export interface UseMailLiveUpdatesOptions {
+    /** Nothing runs without a signed-in user. */
+    userUid?: string;
+    mailboxes: Mailbox[];
+    mailboxFolders: MailboxFolders[];
+    /** Called with a folder another client (or this one) created, so the sidebar shows it. Called only for one not already known. */
+    onFolderCreated: (folder: Folder) => void;
+}
+
+export interface MailLiveUpdates {
+    live: LiveUpdates;
+    /** The latest unread count of each folder that has been refreshed since load, by folder uid - what the sidebar's badges show
+     * instead of the count the folder list was loaded with. */
+    unreadCounts: Record<string, number>;
+}
+
+/**
+ * Keeps Mail current without a page reload. One shared push connection per tab (`getPushClient()`) is subscribed to every
+ * folder of every accessible mailbox; a message event for any of them, a reconnect, a poll of the safety net (every
+ * `LIVE_POLL_INTERVAL_MS` while the tab is visible - and the only mechanism, silently, where the socket can't connect), the
+ * tab coming back to the front or the browser coming back online, all end in the same debounced refresh: `live` is bumped
+ * (the list on screen refetches its first page - see `mergeFirstPage()`) and every folder's unread count is re-read.
+ *
+ * Sign-out closes the socket for good: another tab's or this one's, heard on the same channel `AppShell` listens on.
+ * Renders nothing and does nothing where there is no window (server-side rendering).
+ */
+export function useMailLiveUpdates({ userUid, mailboxes, mailboxFolders, onFolderCreated }: UseMailLiveUpdatesOptions): MailLiveUpdates {
+    const [live, setLive] = useState<LiveUpdates>(NO_LIVE_UPDATES);
+    const [unreadCounts, setUnreadCounts] = useState<Record<string, number>>({});
+    // The latest inputs, for the long-lived listeners below.
+    const latestRef = useRef({ mailboxes, mailboxFolders, onFolderCreated });
+    latestRef.current = { mailboxes, mailboxFolders, onFolderCreated };
+
+    const channels = useMemo(() => pushChannelsFor(mailboxFolders, mailboxes), [mailboxFolders, mailboxes]);
+    const channelKey = channels.join("|");
+    const channelsRef = useRef(channels);
+    channelsRef.current = channels;
+
+    useEffect(() => {
+        if (!userUid) {
+            return;
+        }
+        const client = getPushClient();
+        let stopped = false;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        let pendingFolders = new Set<string>();
+        let pendingUnknown = false;
+        let countsRun = 0;
+        let everOpen = false;
+
+        async function refreshCounts() {
+            const run = ++countsRun;
+            const results = await Promise.all(latestRef.current.mailboxes.map((mailbox) => listFolders(mailbox.uid).catch(() => undefined)));
+            if (stopped || run !== countsRun) {
+                return;
+            }
+            const fresh: Record<string, number> = {};
+            for (const folders of results) {
+                for (const folder of folders ?? []) {
+                    fresh[folder.uid] = folder.unreadCount;
+                }
+            }
+            setUnreadCounts((previous) => {
+                const changed = Object.entries(fresh).some(([uid, count]) => previous[uid] !== count);
+                return changed ? { ...previous, ...fresh } : previous;
+            });
+        }
+
+        // Never runs once `stopped`: whatever sets it clears the timer first.
+        function flush() {
+            timer = undefined;
+            const folderUids = pendingUnknown ? null : new Set(pendingFolders);
+            pendingFolders = new Set();
+            pendingUnknown = false;
+            setLive((previous) => ({ tick: previous.tick + 1, folderUids }));
+            void refreshCounts();
+        }
+
+        /** Asks for a refresh: of the given folders, or (no argument) of whatever may have changed. */
+        function schedule(folderUid?: string) {
+            if (stopped) {
+                return;
+            }
+            if (folderUid) {
+                pendingFolders.add(folderUid);
+            } else {
+                pendingUnknown = true;
+            }
+            timer ??= setTimeout(flush, LIVE_EVENT_DEBOUNCE_MS);
+        }
+
+        const offEvent = client.onEvent((event) => {
+            if (MESSAGE_EVENT.test(event.type) && MESSAGE_ACTIONS.has(event.action ?? "")) {
+                schedule(folderOfMessageEvent(event));
+            } else if (FOLDER_EVENT.test(event.type) && event.action === "create" && isFolder(event.data)) {
+                const folder = event.data;
+                const known = latestRef.current.mailboxFolders.some((entry) => entry.folders.some((f) => f.uid === folder.uid));
+                if (!known) {
+                    latestRef.current.onFolderCreated(folder);
+                }
+            }
+        });
+        // Anything published while the socket was down is gone for good, so every reconnect is followed by a refresh.
+        const offStatus = client.onStatus((status) => {
+            if (status === "open") {
+                if (everOpen) {
+                    schedule();
+                }
+                everOpen = true;
+            }
+        });
+
+        const poll = setInterval(() => {
+            if (document.visibilityState === "visible") {
+                schedule();
+            }
+        }, LIVE_POLL_INTERVAL_MS);
+        function refreshNow() {
+            if (document.visibilityState === "visible") {
+                client.reconnectNow();
+                schedule();
+            }
+        }
+        function handleOnline() {
+            client.reconnectNow();
+            schedule();
+        }
+        document.addEventListener("visibilitychange", refreshNow);
+        window.addEventListener("focus", refreshNow);
+        window.addEventListener("online", handleOnline);
+
+        // A sign-out, in this tab or another, ended the session behind the socket: close it for good and stop refreshing.
+        const signOut = typeof BroadcastChannel === "undefined" ? undefined : new BroadcastChannel(SIGN_OUT_CHANNEL);
+        signOut?.addEventListener("message", (event: MessageEvent<{ type?: string }>) => {
+            if (event.data?.type === "sign-out") {
+                stopped = true;
+                clearTimeout(timer);
+                client.close();
+            }
+        });
+
+        client.setChannels(channelsRef.current);
+        client.start();
+
+        return () => {
+            stopped = true;
+            clearTimeout(timer);
+            clearInterval(poll);
+            offEvent();
+            offStatus();
+            document.removeEventListener("visibilitychange", refreshNow);
+            window.removeEventListener("focus", refreshNow);
+            window.removeEventListener("online", handleOnline);
+            signOut?.close();
+        };
+    }, [userUid]);
+
+    useEffect(() => {
+        if (userUid) {
+            getPushClient().setChannels(channels);
+        }
+    }, [userUid, channelKey]);
+
+    return { live, unreadCounts };
+}

package/apps/www/index.tsx

@@ -44,6 +44,8 @@ import MailShell, {
     MailShellProps,
     useMailShell,
 } from "../shared/components/mail/layout/MailShell.js";
+import MailAddress from "../shared/components/mail/MailAddress.js";
+import { mergeFirstPage } from "../shared/mail/mergeFirstPage.js";
 import MessageDetailPane from "../shared/components/mail/MessageDetailPane.js";
 import ConversationList from "../shared/components/mail/ConversationList.js";
 import ConversationThreadPane from "../shared/components/mail/ConversationThreadPane.js";
@@ -447,7 +449,7 @@ export default function InboxPage(props: MailShellProps) {
 }
 
 function InboxContent({ userUid }: { userUid?: string }) {
-    const { folderUid, mailboxUid, mailboxes, mailboxFolders, aggregateFolderType, onFolderCreated } = useMailShell();
+    const { folderUid, mailboxUid, mailboxes, mailboxFolders, aggregateFolderType, onFolderCreated, live } = useMailShell();
     const isMobile = useIsMobile();
     const { requestUnlock } = useUnlockPrompt();
     const [messages, setMessages] = useState<Message[]>([]);
@@ -1009,6 +1011,67 @@ function InboxContent({ userUid }: { userUid?: string }) {
         activeMailboxUid,
     ]);
 
+    // New mail without a reload. `live` is bumped by a push event, a reconnect, the safety-net poll or the tab coming back (see
+    // `useMailLiveUpdates()`); this then quietly refetches the first page of whatever is listed and folds it in - unlike the
+    // effect above it resets nothing: not the selection, the open thread, select mode, the scroll position or the rows
+    // already paged in, and nothing it fetches is marked read. It stands aside for a search (whose rows aren't a folder's),
+    // a listing still loading and a "load more" in flight, and for events about folders the list isn't showing - a
+    // conversation list, which can span folders, refreshes for any. Any failure is silent: the next tick tries again.
+    const liveRunRef = useRef(0);
+    useEffect(() => {
+        if (live.tick === 0 || isSearching || loading || loadMoreInFlightRef.current || (!folderUid && !aggregateFolderType)) {
+            return;
+        }
+        if (!preferences.showAsConversations && live.folderUids) {
+            const shown = new Set(
+                aggregateFolderType
+                    ? mailboxFolders.flatMap((entry) => entry.folders.filter((f) => f.type === aggregateFolderType).map((f) => f.uid))
+                    : [folderUid!],
+            );
+            if (![...live.folderUids].some((uid) => shown.has(uid))) {
+                return;
+            }
+        }
+        // Superseded by a newer refresh, or by any reload of the list itself (which bumps the search run id).
+        const listRun = searchRunIdRef.current;
+        const myRun = ++liveRunRef.current;
+        const isCurrent = () => searchRunIdRef.current === listRun && liveRunRef.current === myRun;
+        void (async () => {
+            try {
+                if (preferences.showAsConversations) {
+                    const fresh = await listConversations(activeMailboxUid, conversationParams(0));
+                    if (!isCurrent()) {
+                        return;
+                    }
+                    const merged = mergeFirstPage(conversationsRef.current, fresh, conversationKey, MESSAGE_PAGE_SIZE);
+                    setConversations(merged.rows);
+                    listedOffsetRef.current = merged.complete ? fresh.length : listedOffsetRef.current + merged.added;
+                    setHasMore(!merged.complete);
+                } else if (aggregateFolderType) {
+                    // No paging here (see `fetchAggregateMessages()`): the fresh merged first pages are the list.
+                    const fresh = await fetchAggregateMessages(mailboxFolders, aggregateFolderType, effectiveFilter);
+                    if (isCurrent()) {
+                        setMessages(fresh);
+                    }
+                } else {
+                    const fresh = await listMessages(folderUid!, listParams);
+                    if (!isCurrent()) {
+                        return;
+                    }
+                    // A row the reader has just changed (a higher version) is not put back by a fetch that began before.
+                    const merged = mergeFirstPage(messagesRef.current, fresh, messageUid, MESSAGE_PAGE_SIZE, (current, next) =>
+                        current.version > next.version ? current : next,
+                    );
+                    setMessages(merged.rows);
+                    listedOffsetRef.current = merged.complete ? fresh.length : listedOffsetRef.current + merged.added;
+                    setHasMore(!merged.complete);
+                }
+            } catch {
+                // Quiet by design - see above.
+            }
+        })();
+    }, [live.tick]);
+
     function handleSearchAllMail() {
         setSearchAllMailKey(searchAllMailScope);
     }
@@ -1742,7 +1805,7 @@ function InboxContent({ userUid }: { userUid?: string }) {
                                         ].join(" ")}
                                     >
                                         <div className="flex items-center justify-between gap-2 text-sm">
-                                            <span className="truncate">{message.from.displayName || message.from.address}</span>
+                                            <MailAddress recipient={message.from} />
                                             <span className="text-xs text-text-muted shrink-0">
                                                 {new Date(message.receivedDate).toLocaleDateString()}
                                             </span>

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

@@ -0,0 +1,24 @@
+/**
+ * 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 declare const ELEVATION_REQUIRED_CODE = "api-104";
+/** `sessionStorage` key holding the time (`Date.now()`) the browser was last sent to auth-server to elevate. */
+export declare 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 declare const ELEVATION_RETRY_WINDOW_MS: number;
+/** Whether `err` is a 403 from an elevation-gated endpoint for a caller whose token isn't elevated. */
+export declare function isElevationRequired(err: unknown): boolean;
+/** 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 declare function elevationUrl(authServerUrl: string, returnTo: string): string;
+/** 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 declare function elevationAttemptedRecently(now?: number): boolean;
+/** 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 declare function recordElevationAttempt(now?: number): void;
+/** Forgets any recorded attempt - once elevation has worked, or when the user asks to try again. */
+export declare function clearElevationAttempt(): void;

package/dist/apps/shared/components/admin/elevation.js

@@ -0,0 +1,56 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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) {
+    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, returnTo) {
+    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 = Date.now()) {
+    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 = Date.now()) {
+    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() {
+    try {
+        sessionStorage.removeItem(ELEVATION_ATTEMPT_KEY);
+    }
+    catch {
+        // Nothing was recorded.
+    }
+}

package/dist/apps/shared/components/admin/layout/AdminShell.d.ts

@@ -24,9 +24,17 @@ export interface AdminShellProps extends PluginNavProps {
  * off-rail sections' - see `mergePluginNavItems`. */
 export declare 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>): React.JSX.Element;

package/dist/apps/shared/components/admin/layout/AdminShell.js

@@ -11,9 +11,11 @@ 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 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 } from "../../../plugins/pluginNav.js";
 /** Sections shown in the persistent icon rail / mobile tab bar — every admin area reachable from
@@ -84,14 +86,24 @@ export function adminNavItems(pluginNav) {
     return mergePluginNavItems(NAV_ITEMS, pluginNav?.adminNav, ({ id, href, label }) => ({ id, href, label, icon: HiOutlinePuzzlePiece }), OFF_RAIL_ITEMS.map((item) => item.id));
 }
 /**
- * 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 }) {
     const [status, setStatus] = useState("checking");
     const [error, setError] = useState(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);
     useEffect(() => {
@@ -100,6 +112,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") {
@@ -116,6 +130,19 @@ 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;
@@ -124,6 +151,16 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
             setStatus("error");
         });
     }, [userUid]);
+    /** Remembers the attempt, then sends the browser to auth-server to confirm the user's identity. */
+    function startElevation(authServer) {
+        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);
@@ -132,6 +169,12 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
     if (!userUid || status === "checking") {
         content = _jsx("div", { className: "min-h-screen" });
     }
+    else if (status === "elevating") {
+        content = (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8", children: _jsx("p", { role: "status", className: "text-sm text-text-muted", children: "Redirecting to confirm your identity\u2026" }) }));
+    }
+    else if (status === "elevationFailed") {
+        content = (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8", children: _jsxs("div", { className: "w-full max-w-md flex flex-col items-start", children: [_jsx(Alert, { children: "Confirming your identity didn\u2019t take effect, so the administrator console is still locked. Try again, and if this keeps happening, sign out and sign back in." }), _jsx(Button, { type: "button", className: "!w-auto", onClick: handleRetryElevation, children: "Try again" })] }) }));
+    }
     else if (status === "denied") {
         content = (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8", children: _jsx("div", { className: "w-full max-w-md", children: _jsx(Alert, { children: "You do not have administrator access." }) }) }));
     }
@@ -148,5 +191,5 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
                                         : "text-text-muted hover:bg-surface-alt hover:text-text",
                                 ].join(" "), children: _jsx(Icon, { size: 20, "aria-hidden": "true" }) }, id)))] }), _jsx(BottomTabBar, { apps: navItems, active: active }), _jsxs("div", { className: "flex-1 flex flex-col min-w-0", children: [_jsxs("header", { className: "h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6", children: [_jsx("span", { className: "font-display font-bold text-lg uppercase tracking-wide", children: activeItem?.label }), _jsx(UserMenu, { userUid: userUid, authServerUrl: authServerUrl, onSignOut: handleSignOut })] }), _jsx("div", { className: "flex-1 pb-14 md:pb-0", children: _jsx("main", { className: "max-w-6xl mx-auto px-6 py-8", children: children }) })] })] }) }));
     }
-    return (_jsxs(_Fragment, { children: [_jsx(BrandingHeader, { branding: branding }), content, _jsx(BrandingFooter, { branding: branding })] }));
+    return (_jsxs(_Fragment, { children: [content, _jsx(BrandingFooter, { branding: branding })] }));
 }

package/dist/apps/shared/components/admin/settings/BrandingForm.js

@@ -104,7 +104,7 @@ export default function BrandingForm({ branding, onChange, embedded = false }) {
             setSaving(false);
         }
     }
-    return (_jsxs("div", { className: "max-w-2xl", children: [!embedded && (_jsxs(_Fragment, { children: [_jsx("h1", { className: "text-xl font-bold uppercase tracking-wide mb-1", children: "Branding" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "Customize the logo, nav-header icon, product name, and chrome shown to every visitor of the webmail and admin console \u2014 including anonymous booking-page visitors." })] })), error && _jsx(Alert, { children: error }), saved && !error && _jsx("div", { className: "mb-4 text-sm text-success font-medium", children: "Saved." }), _jsxs("div", { className: "flex flex-col gap-6", children: [_jsxs("section", { className: "flex flex-col gap-3", children: [_jsx(SectionHeading, { className: "text-sm font-bold uppercase tracking-wide text-text-muted", children: "Logo" }), _jsxs("div", { className: "flex items-center gap-4", children: [_jsx("img", { src: branding.logoUrl || "/images/logo.svg", alt: "Current logo", width: "64", height: "64", className: "border border-border rounded-sm bg-surface-alt p-1" }), _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", loading: assetBusy === "logo-upload", disabled: assetBusy !== null, onClick: () => logoFileRef.current?.click(), children: "Upload logo" }), _jsx("input", { ref: logoFileRef, type: "file", accept: RASTER_IMAGE_ACCEPT, "aria-label": "Upload logo", className: "hidden", onChange: handleLogoFileChange }), branding.logoUrl && (_jsx(Button, { type: "button", variant: "text", disabled: assetBusy !== null, loading: assetBusy === "logo-delete", onClick: () => void runAsset("logo-delete", async () => {
+    return (_jsxs("div", { className: "max-w-2xl", children: [!embedded && (_jsxs(_Fragment, { children: [_jsx("h1", { className: "text-xl font-bold uppercase tracking-wide mb-1", children: "Branding" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "Customize the logo, nav-header icon, product name, and chrome shown to every visitor of the webmail and admin console \u2014 including anonymous booking-page visitors. The header appears on the webmail and public pages, not in the admin console; the footer appears in both." })] })), error && _jsx(Alert, { children: error }), saved && !error && _jsx("div", { className: "mb-4 text-sm text-success font-medium", children: "Saved." }), _jsxs("div", { className: "flex flex-col gap-6", children: [_jsxs("section", { className: "flex flex-col gap-3", children: [_jsx(SectionHeading, { className: "text-sm font-bold uppercase tracking-wide text-text-muted", children: "Logo" }), _jsxs("div", { className: "flex items-center gap-4", children: [_jsx("img", { src: branding.logoUrl || "/images/logo.svg", alt: "Current logo", width: "64", height: "64", className: "border border-border rounded-sm bg-surface-alt p-1" }), _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", loading: assetBusy === "logo-upload", disabled: assetBusy !== null, onClick: () => logoFileRef.current?.click(), children: "Upload logo" }), _jsx("input", { ref: logoFileRef, type: "file", accept: RASTER_IMAGE_ACCEPT, "aria-label": "Upload logo", className: "hidden", onChange: handleLogoFileChange }), branding.logoUrl && (_jsx(Button, { type: "button", variant: "text", disabled: assetBusy !== null, loading: assetBusy === "logo-delete", onClick: () => void runAsset("logo-delete", async () => {
                                                     await deleteBrandingLogo();
                                                     return { ...branding, logoUrl: undefined };
                                                 }), children: "Remove logo" }))] })] }), _jsxs("label", { className: "flex flex-col gap-1.5 text-sm", children: [_jsx("span", { className: "font-semibold", children: "Or use an external image URL" }), _jsxs("div", { className: "flex gap-2", children: [_jsx("input", { "aria-label": "Logo URL", className: INPUT_CLASS, value: logoUrlInput, onChange: (e) => setLogoUrlInput(e.target.value) }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", disabled: assetBusy !== null || logoUrlInput === (branding.logoUrl ?? ""), loading: assetBusy === "logo-url", onClick: () => void runAsset("logo-url", () => updateBranding({ logoUrl: logoUrlInput })), children: "Set" })] })] })] }), _jsxs("section", { className: "flex flex-col gap-3", children: [_jsx(SectionHeading, { className: "text-sm font-bold uppercase tracking-wide text-text-muted", children: "Icon" }), _jsx("p", { className: "text-xs text-text-muted -mt-1", children: "A compact mark for navigation headers, independent of the full logo above. Falls back to the logo, then a default asset, when not set." }), _jsxs("div", { className: "flex items-center gap-4", children: [_jsx("img", { src: branding.iconUrl || branding.logoUrl || "/images/logo.svg", alt: "Current icon", width: "64", height: "64", className: "border border-border rounded-sm bg-surface-alt p-1" }), _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", loading: assetBusy === "icon-upload", disabled: assetBusy !== null, onClick: () => iconFileRef.current?.click(), children: "Upload icon" }), _jsx("input", { ref: iconFileRef, type: "file", accept: RASTER_IMAGE_ACCEPT, "aria-label": "Upload icon", className: "hidden", onChange: handleIconFileChange }), branding.iconUrl && (_jsx(Button, { type: "button", variant: "text", disabled: assetBusy !== null, loading: assetBusy === "icon-delete", onClick: () => void runAsset("icon-delete", async () => {