@rapidmx/web-client 0.4.0 → 0.6.0

package/apps/shared/components/escrow/layout/EscrowShell.tsx

@@ -1,134 +1,148 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import "../../../styles/app.css";
-import React, { PropsWithChildren, ReactNode, useEffect, useState } from "react";
-import { HiOutlineClipboardDocumentList, HiOutlineFolderOpen } from "react-icons/hi2";
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import { listMatters } from "@rapidmx/react-shared/admin/mattersApi.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 BottomTabBar, { NavItem } from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
-import { BrandingFooter, BrandingHeader } from "../../layout/BrandingChrome.js";
-import UserMenu from "../../layout/UserMenu.js";
-
-export type EscrowSection = "matters" | "auditLog";
-
-export interface EscrowShellProps {
-    active: EscrowSection;
-    userUid?: string;
-    authServerUrl?: string;
-}
-
-type Status = "checking" | "error" | "authorized";
-
-const NAV_ITEMS: NavItem[] = [
-    { id: "matters", href: "/escrow", label: "Matters", icon: HiOutlineFolderOpen },
-    { id: "auditLog", href: "/escrow/audit-log", label: "Audit Log", icon: HiOutlineClipboardDocumentList },
-];
-
-/**
- * Gates every `apps/escrow` page behind "is this an authenticated caller at all" — deliberately **not**
- * the same "does a canary endpoint 403 me" pattern `AdminShell` uses for the trusted `admin` role.
- * `specs/end-to-end_encryption.md`'s "Separation of duties" makes holder-ness a per-`EscrowScope` grant
- * (`EscrowScope.holderUserUids`), checked directly against `holderUserUids` in every restapi route that
- * needs it (`requireEscrowHolder()`) — never a role, and never global. There is no canary endpoint a
- * non-holder gets a clean 403 from: `GET /escrow/matters` (`BaseMatterRoute.find()`) returns `200 []` for
- * *any* authenticated caller who holds no scope at all, the same as it would for a holder of zero matters
- * — so unlike `AdminShell`, this shell cannot distinguish "holds nothing" from "holds no scope at all" up
- * front, and does not try to. It only confirms the caller is signed in and the API is reachable; every
- * actual holder-gated action (create a Matter, approve/deny a request, read material) is enforced
- * server-side and surfaces its own 403 `ApiRequestError` on the specific page that attempted it, same as
- * any other gated action elsewhere in this codebase. A non-holder who reaches `/escrow` simply sees an
- * empty Matters list and gets a real error if they try to act on something they don't hold — this is a
- * deliberate, documented scope trim rather than an oversight (see this session's own report on it).
- */
-export default function EscrowShell({ active, userUid, authServerUrl, children }: PropsWithChildren<EscrowShellProps>) {
-    const [status, setStatus] = useState<Status>("checking");
-    const [error, setError] = useState<string | null>(null);
-    const { branding, iconSrc } = useBranding();
-
-    useRedirectIfUnauthenticated(userUid, authServerUrl);
-
-    useEffect(() => {
-        if (!userUid) {
-            return;
-        }
-        // limit=1 - this call exists only to confirm the API is reachable for this signed-in caller, not
-        // to read any real data (every page below fetches its own data itself).
-        listMatters({ limit: 1 })
-            .then(() => setStatus("authorized"))
-            .catch((err) => {
-                setError(err instanceof ApiRequestError ? err.message : "Could not verify escrow console access.");
-                setStatus("error");
-            });
-    }, [userUid]);
-
-    function handleSignOut() {
-        window.location.href = authServerUrl ?? "/";
-    }
-
-    let content: ReactNode;
-    if (!userUid || status === "checking") {
-        content = <div className="min-h-screen" />;
-    } else if (status === "error") {
-        content = (
-            <div className="min-h-screen flex items-center justify-center p-8">
-                <div className="w-full max-w-md">
-                    <Alert>{error}</Alert>
-                </div>
-            </div>
-        );
-    } else {
-        const activeItem = NAV_ITEMS.find((item) => item.id === active);
-        content = (
-            <div className="min-h-screen flex flex-col bg-surface-alt">
-                <div className="flex-1 flex min-h-0">
-                    <nav
-                        aria-label="Escrow sections"
-                        className="hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center py-3 gap-1"
-                    >
-                        <img src={iconSrc} width="96" height="96" alt="" className="mb-3" />
-                        {NAV_ITEMS.map(({ id, href, label, icon: Icon }) => (
-                            <a
-                                key={id}
-                                href={href}
-                                aria-label={label}
-                                aria-current={id === active ? "page" : undefined}
-                                title={label}
-                                className={[
-                                    "w-10 h-10 flex items-center justify-center rounded-sm",
-                                    id === active
-                                        ? "bg-primary/10 text-primary-dark"
-                                        : "text-text-muted hover:bg-surface-alt hover:text-text",
-                                ].join(" ")}
-                            >
-                                <Icon size={20} aria-hidden="true" />
-                            </a>
-                        ))}
-                    </nav>
-                    <BottomTabBar apps={NAV_ITEMS} active={active} />
-                    <div className="flex-1 flex flex-col min-w-0">
-                        <header className="h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6">
-                            <span className="font-display font-bold text-lg uppercase tracking-wide">{activeItem?.label}</span>
-                            <UserMenu userUid={userUid} authServerUrl={authServerUrl} onSignOut={handleSignOut} />
-                        </header>
-                        <div className="flex-1 pb-14 md:pb-0">
-                            <main className="max-w-6xl mx-auto px-6 py-8">{children}</main>
-                        </div>
-                    </div>
-                </div>
-            </div>
-        );
-    }
-
-    return (
-        <>
-            <BrandingHeader branding={branding} />
-            {content}
-            <BrandingFooter branding={branding} />
-        </>
-    );
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import "../../../styles/app.css";
+import React, { PropsWithChildren, ReactNode, useEffect, useState } from "react";
+import { HiOutlineClipboardDocumentList, HiOutlineFolderOpen } from "react-icons/hi2";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { listMatters } from "@rapidmx/react-shared/admin/mattersApi.js";
+import { useRedirectIfUnauthenticated } from "@rapidmx/react-shared/auth/session.js";
+import { getBranding } from "@rapidmx/react-shared/branding/brandingApi.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import BottomTabBar, { NavItem } from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
+import UserMenu from "../../layout/UserMenu.js";
+import { signOutOfConsole } from "../../admin/signOut.js";
+
+export type EscrowSection = "matters" | "auditLog";
+
+export interface EscrowShellProps {
+    active: EscrowSection;
+    userUid?: string;
+    authServerUrl?: string;
+}
+
+type Status = "checking" | "error" | "authorized";
+
+const DEFAULT_ICON_SRC = "/images/logo.svg";
+
+const NAV_ITEMS: NavItem[] = [
+    { id: "matters", href: "/escrow", label: "Matters", icon: HiOutlineFolderOpen },
+    { id: "auditLog", href: "/escrow/audit-log", label: "Audit Log", icon: HiOutlineClipboardDocumentList },
+];
+
+/**
+ * Gates every `apps/escrow` page behind "is this an authenticated caller at all" — deliberately **not**
+ * the same "does a canary endpoint 403 me" pattern `AdminShell` uses for the trusted `admin` role.
+ * `specs/end-to-end_encryption.md`'s "Separation of duties" makes holder-ness a per-`EscrowScope` grant
+ * (`EscrowScope.holderUserUids`), checked directly against `holderUserUids` in every restapi route that
+ * needs it (`requireEscrowHolder()`) — never a role, and never global. There is no canary endpoint a
+ * non-holder gets a clean 403 from: `GET /escrow/matters` (`BaseMatterRoute.find()`) returns `200 []` for
+ * *any* authenticated caller who holds no scope at all, the same as it would for a holder of zero matters
+ * — so unlike `AdminShell`, this shell cannot distinguish "holds nothing" from "holds no scope at all" up
+ * front, and does not try to. It only confirms the caller is signed in and the API is reachable; every
+ * actual holder-gated action (create a Matter, approve/deny a request, read material) is enforced
+ * server-side and surfaces its own 403 `ApiRequestError` on the specific page that attempted it, same as
+ * any other gated action elsewhere in this codebase. A non-holder who reaches `/escrow` simply sees an
+ * empty Matters list and gets a real error if they try to act on something they don't hold — this is a
+ * deliberate, documented scope trim rather than an oversight (see this session's own report on it).
+ */
+export default function EscrowShell({ active, userUid, authServerUrl, children }: PropsWithChildren<EscrowShellProps>) {
+    const [status, setStatus] = useState<Status>("checking");
+    const [error, setError] = useState<string | null>(null);
+    const [iconSrc, setIconSrc] = useState(DEFAULT_ICON_SRC);
+
+    useRedirectIfUnauthenticated(userUid, authServerUrl);
+
+    // Only the icon is taken from branding here. The escrow console deliberately skips `useBranding()`, which
+    // would inject the custom stylesheet, and never renders the admin-configured header/footer HTML - this
+    // console handles escrow key material, so no admin-supplied markup or CSS runs on it.
+    useEffect(() => {
+        let cancelled = false;
+        getBranding()
+            .then((branding) => {
+                if (!cancelled) setIconSrc(branding.iconUrl || branding.logoUrl || DEFAULT_ICON_SRC);
+            })
+            .catch(() => {
+                // Decorative only - keep the default icon.
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+
+    useEffect(() => {
+        if (!userUid) {
+            return;
+        }
+        // limit=1 - this call exists only to confirm the API is reachable for this signed-in caller, not
+        // to read any real data (every page below fetches its own data itself).
+        listMatters({ limit: 1 })
+            .then(() => setStatus("authorized"))
+            .catch((err) => {
+                setError(err instanceof ApiRequestError ? err.message : "Could not verify escrow console access.");
+                setStatus("error");
+            });
+    }, [userUid]);
+
+    function handleSignOut() {
+        // Ends the auth-server session and tells other tabs, not just navigates - see `signOutOfConsole()`.
+        void signOutOfConsole(authServerUrl);
+    }
+
+    let content: ReactNode;
+    if (!userUid || status === "checking") {
+        content = <div className="min-h-screen" />;
+    } else if (status === "error") {
+        content = (
+            <div className="min-h-screen flex items-center justify-center p-8">
+                <div className="w-full max-w-md">
+                    <Alert>{error}</Alert>
+                </div>
+            </div>
+        );
+    } else {
+        const activeItem = NAV_ITEMS.find((item) => item.id === active);
+        content = (
+            <div className="min-h-screen flex flex-col bg-surface-alt">
+                <div className="flex-1 flex min-h-0">
+                    <nav
+                        aria-label="Escrow sections"
+                        className="hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center py-3 gap-1"
+                    >
+                        <img src={iconSrc} width="96" height="96" alt="" className="mb-3" />
+                        {NAV_ITEMS.map(({ id, href, label, icon: Icon }) => (
+                            <a
+                                key={id}
+                                href={href}
+                                aria-label={label}
+                                aria-current={id === active ? "page" : undefined}
+                                title={label}
+                                className={[
+                                    "w-10 h-10 flex items-center justify-center rounded-sm",
+                                    id === active
+                                        ? "bg-primary/10 text-primary-dark"
+                                        : "text-text-muted hover:bg-surface-alt hover:text-text",
+                                ].join(" ")}
+                            >
+                                <Icon size={20} aria-hidden="true" />
+                            </a>
+                        ))}
+                    </nav>
+                    <BottomTabBar apps={NAV_ITEMS} active={active} />
+                    <div className="flex-1 flex flex-col min-w-0">
+                        <header className="h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6">
+                            <span className="font-display font-bold text-lg uppercase tracking-wide">{activeItem?.label}</span>
+                            <UserMenu userUid={userUid} authServerUrl={authServerUrl} onSignOut={handleSignOut} />
+                        </header>
+                        <div className="flex-1 pb-14 md:pb-0">
+                            <main className="max-w-6xl mx-auto px-6 py-8">{children}</main>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        );
+    }
+
+    return <>{content}</>;
+}

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

@@ -3,30 +3,66 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import "../../styles/app.css";
-import React, { PropsWithChildren, useState, useEffect } from "react";
+import React, { PropsWithChildren, useEffect, useRef, useState } from "react";
 import type { IconType } from "react-icons";
-import { HiOutlineCalendarDays, HiOutlineClipboardDocumentList, HiOutlineEnvelope, HiOutlineUsers } from "react-icons/hi2";
+import {
+    HiOutlineCalendarDays,
+    HiOutlineClipboardDocumentList,
+    HiOutlineEnvelope,
+    HiOutlinePuzzlePiece,
+    HiOutlineUsers,
+} from "react-icons/hi2";
 import { useRedirectIfUnauthenticated } from "@rapidmx/react-shared/auth/session.js";
 import { getSetupStatus } from "@rapidmx/react-shared/admin/setupApi.js";
 import { stopImpersonating } from "@rapidmx/react-shared/mail/mailApi.js";
 import useBranding from "@rapidmx/react-shared/branding/useBranding.js";
 import { useIdleKeyTimeout } from "@rapidmx/react-shared/crypto/useIdleKeyTimeout.js";
 import ComposeProvider from "../mail/compose/ComposeContext.js";
-import BottomTabBar from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
+import { flushComposeDrafts, markSigningOut } from "../mail/compose/composeFlushRegistry.js";
+import BottomTabBar, { NavItem } from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
 import { BrandingFooter, BrandingHeader } from "./BrandingChrome.js";
 import UserMenu from "./UserMenu.js";
 import { UnlockPromptProvider } from "./UnlockPromptProvider.js";
-import { destroyAllLocalIndexes } from "../../search/localIndexRpcClient.js";
+import { SIGN_OUT_CHANNEL, destroyAllLocalIndexes } from "../../search/localIndexRpcClient.js";
+import { authApiFetch } from "@rapidmx/react-shared/util/api.js";
+import { destroyUnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
+import { clearPinnedSignerCache } from "../mail/pinnedSigners.js";
+import { mergePluginNavItems, PluginNav, PluginNavProps } from "../../plugins/pluginNav.js";
+
+/** How long sign-out waits for auth-server's logout before navigating anyway. */
+export const LOGOUT_TIMEOUT_MS = 3_000;
+
+/**
+ * Calls auth-server's logout (`POST /api/auth/logout`, cross-origin with credentials), which clears the auth
+ * cookie and invalidates the session's refresh token. Bounded by `LOGOUT_TIMEOUT_MS` and never rejects - a
+ * failure (unreachable server, CORS) must not keep the user from leaving.
+ */
+async function logOutOfAuthServer(authServerUrl: string | undefined): Promise<void> {
+    if (!authServerUrl) {
+        return;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), LOGOUT_TIMEOUT_MS);
+    try {
+        await authApiFetch(authServerUrl, "/auth/logout", { method: "POST", signal: controller.signal });
+    } catch {
+        // Navigate anyway - see this function's doc comment.
+    } finally {
+        clearTimeout(timer);
+    }
+}
 
 export type AppShellApp = "mail" | "calendar" | "contacts" | "tasks";
 
 /** `"settings"` is a valid `active` value but deliberately has no entry in `APPS` below — Settings is
  * reached via a `UserMenu` item, not a 5th rail icon (see `SettingsShell.tsx`), so it highlights no
- * rail/tab icon at all; only the header title (`ACTIVE_LABELS` below) needs to account for it. */
-export type AppShellActive = AppShellApp | "settings";
+ * rail/tab icon at all; only the header title needs to account for it. Any other string is a plugin's
+ * `appRail` item id (see `PluginNav`). */
+export type AppShellActive = AppShellApp | "settings" | (string & {});
 
-export interface AppShellProps {
-    /** Which icon in the rail is highlighted as the current app — `"settings"` highlights none. */
+export interface AppShellProps extends PluginNavProps {
+    /** Which icon in the rail is highlighted as the current app — `"settings"` highlights none, and a plugin
+     * app page passes its own `appRail` item id. */
     active: AppShellActive;
     /** Populated automatically by the framework from an authenticated request (e.g. a valid `jwt` cookie). */
     userUid?: string;
@@ -58,15 +94,19 @@ export const APPS: AppDef[] = [
     { id: "tasks", href: "/tasks", label: "Tasks", icon: HiOutlineClipboardDocumentList },
 ];
 
-/** The header title for every valid `active` value — a superset of `APPS`' own labels since `"settings"`
- * has no rail icon (and so no `AppDef`) but still needs a header title. */
-const ACTIVE_LABELS: Record<AppShellActive, string> = {
-    mail: "Mail",
-    calendar: "Calendar",
-    contacts: "Contacts",
-    tasks: "Tasks",
-    settings: "Settings",
-};
+/** Ids plugin `appRail` items can't take besides `APPS`' own - `"settings"` has no rail icon but is still a
+ * core `active` value. */
+const RESERVED_APP_IDS = ["settings"];
+
+/** `APPS` followed by the plugins' `appRail` items (generic icon), core ids winning - see `mergePluginNavItems`. */
+export function appRailItems(pluginNav?: PluginNav): NavItem[] {
+    return mergePluginNavItems<NavItem>(
+        APPS,
+        pluginNav?.appRail,
+        ({ id, href, label }) => ({ id, href, label, icon: HiOutlinePuzzlePiece }),
+        RESERVED_APP_IDS,
+    );
+}
 
 /**
  * The persistent chrome shared by every webmail app (Mail, Calendar, Contacts, Tasks): a left icon rail for
@@ -82,9 +122,11 @@ export default function AppShell({
     impersonating,
     impersonationBaseUrl,
     trusted,
+    pluginNav,
     children,
 }: PropsWithChildren<AppShellProps>) {
     const [stoppingImpersonation, setStoppingImpersonation] = useState(false);
+    const signingOutRef = useRef(false);
     const { branding, iconSrc } = useBranding();
 
     useRedirectIfUnauthenticated(userUid, authServerUrl);
@@ -92,10 +134,11 @@ export default function AppShell({
     // specifically so activity in *any* app resets the idle clock - see that hook's own doc comment.
     useIdleKeyTimeout();
 
-    // An administrator on a server that hasn't finished first-run setup is sent to the setup wizard. Everyone else
-    // gets a 403 from the setup status check (it's admin-only), which is ignored along with any other failure.
+    // An administrator on a server that hasn't finished first-run setup is sent to the setup wizard. The status
+    // check is admin-only, so it's only made for a trusted caller - everyone else would just get a 403 on every
+    // page load. Any failure is ignored.
     useEffect(() => {
-        if (!userUid || impersonating) {
+        if (!userUid || impersonating || !trusted) {
             return;
         }
         getSetupStatus()
@@ -105,15 +148,56 @@ export default function AppShell({
                 }
             })
             .catch(() => undefined);
-    }, [userUid, impersonating]);
-
-    function handleSignOut() {
-        // Best-effort, fire-and-forget: the Tier 2 local index MUST be destroyed on explicit logout, the
-        // same as unlocked keys themselves (spec §11) - this component has no specific mailboxUid of its
-        // own to pass (it's shared by every app, not just Mail), so this destroys every mailbox's index
-        // the session has open rather than needing one threaded through. Not awaited - the navigation
-        // below shouldn't wait on it, and destroyAllLocalIndexes() never throws either way.
-        void destroyAllLocalIndexes();
+    }, [userUid, impersonating, trusted]);
+
+    // Another tab signing out (this app's `handleSignOut`, or the admin/escrow consoles' `signOutOfConsole()`)
+    // ended this session too - its auth cookie is gone - so this tab destroys its own unlocked keys and every
+    // local search index on the device, then leaves as well. The consoles have no local-index client of their
+    // own, so this is what actually removes the indexes after a console sign-out (the console also records a
+    // pending deletion, retried on the next mail load, in case no mail tab is open). `destroyAllLocalIndexes()`
+    // announces the sign-out on this same channel, which this tab then hears itself, so the ref is set first:
+    // each tab reacts once, and the tab that started the sign-out ignores its own announcement.
+    useEffect(() => {
+        if (!userUid || typeof BroadcastChannel === "undefined") {
+            return;
+        }
+        const channel = new BroadcastChannel(SIGN_OUT_CHANNEL);
+        channel.addEventListener("message", (event: MessageEvent<{ type?: string }>) => {
+            if (event.data?.type !== "sign-out" || signingOutRef.current) {
+                return;
+            }
+            signingOutRef.current = true;
+            // Compose windows must not ask "Leave site?" - that would let this forced navigation be cancelled.
+            markSigningOut();
+            destroyUnlockedKeys();
+            clearPinnedSignerCache();
+            // Bounded by its own timeout and never rejects - awaited so navigating doesn't kill the Worker mid-delete.
+            void destroyAllLocalIndexes().then(() => {
+                window.location.href = authServerUrl ?? "/";
+            });
+        });
+        return () => channel.close();
+    }, [userUid, authServerUrl]);
+
+    async function handleSignOut() {
+        signingOutRef.current = true;
+        // Before flushing and navigating: compose windows then skip their "Leave site?" prompt, which could
+        // otherwise cancel the sign-out's own navigation.
+        markSigningOut();
+        // Unlocked private keys never outlive an explicit sign-out.
+        destroyUnlockedKeys();
+        // Trusted signer pins read from contacts don't outlive the session either.
+        clearPinnedSignerCache();
+        // Open compose windows save edits still waiting on their autosave debounce while the session is still
+        // valid - logout invalidates it. Bounded the same way as logout itself, and never rejects.
+        await flushComposeDrafts(LOGOUT_TIMEOUT_MS);
+        // The Tier 2 local index MUST be destroyed on explicit logout, the same as unlocked keys themselves
+        // (spec §11). Destroys every index on this device (not only mailboxes opened this page load) and is
+        // awaited before navigating - a navigation tears down the Worker mid-delete otherwise.
+        // destroyAllLocalIndexes() is bounded by its own timeout and never rejects, so sign-out can't hang.
+        // In parallel, auth-server's logout clears the auth cookie and invalidates the session's refresh
+        // token - without it, "Sign Out" would only navigate away from a still-valid session.
+        await Promise.all([destroyAllLocalIndexes(), logOutOfAuthServer(authServerUrl)]);
         window.location.href = authServerUrl ?? "/";
     }
 
@@ -134,12 +218,18 @@ export default function AppShell({
         return <div className="min-h-screen" />;
     }
 
+    const apps = appRailItems(pluginNav);
+    // The header title: "settings" has no rail item, everything else is labelled by its own rail item.
+    const activeLabel = active === "settings" ? "Settings" : apps.find((app) => app.id === active)?.label;
+
     return (
         // Mounted here, not scoped to Mail/Settings, for the same reason as useIdleKeyTimeout() above -
         // ComposeWindow's sign/encrypt toggles and MessageDetailPane's encrypted-message view (both Mail)
         // are today's only useUnlockPrompt() callers, but this needs to be available to any app shell.
         <UnlockPromptProvider>
-            <ComposeProvider userUid={userUid}>
+            {/* An impersonating admin acts with the impersonated user's access, so their own trusted role
+                mustn't skip the per-mailbox checks. */}
+            <ComposeProvider userUid={userUid} trusted={!!trusted && !impersonating}>
             <div className="min-h-screen flex flex-col bg-surface-alt">
                 <BrandingHeader branding={branding} />
                 {impersonating && (
@@ -163,7 +253,7 @@ export default function AppShell({
                         className="hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center py-3 gap-1"
                     >
                         <img src={iconSrc} width="96" height="96" alt="" className="mb-3" />
-                        {APPS.map(({ id, href, label, icon: Icon }) => (
+                        {apps.map(({ id, href, label, icon: Icon }) => (
                             <a
                                 key={id}
                                 href={href}
@@ -181,10 +271,10 @@ export default function AppShell({
                             </a>
                         ))}
                     </nav>
-                    <BottomTabBar apps={APPS} active={active} />
+                    <BottomTabBar apps={apps} active={active} />
                     <div className="flex-1 flex flex-col min-w-0">
                         <header className="h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6">
-                            <span className="font-display font-bold text-lg uppercase tracking-wide">{ACTIVE_LABELS[active]}</span>
+                            <span className="font-display font-bold text-lg uppercase tracking-wide">{activeLabel}</span>
                             <UserMenu userUid={userUid} authServerUrl={authServerUrl} onSignOut={handleSignOut} showAdminLink={trusted} showSettingsLink />
                         </header>
                         <div className="flex-1 flex min-h-0 pb-14 md:pb-0">{children}</div>

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

@@ -3,23 +3,61 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React from "react";
+import DOMPurify from "dompurify";
 import { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
 
+/** Elements that could run script, restyle the whole page, collect input, or embed another page - stripped on
+ * top of DOMPurify's defaults (which already drop `<script>`, `on*` handlers, and `javascript:` URLs). */
+const FORBIDDEN_TAGS = [
+    "script",
+    "style",
+    "form",
+    "input",
+    "button",
+    "textarea",
+    "select",
+    "option",
+    "iframe",
+    "frame",
+    "frameset",
+    "object",
+    "embed",
+    "link",
+    "meta",
+    "base",
+    "svg",
+    "math",
+];
+const FORBIDDEN_ATTRS = ["action", "formaction", "srcdoc"];
+
 /**
- * Renders the admin-configured `Branding.headerHtml`/`footerHtml` (see `useBranding()`) — shared by every
- * chrome in this project (`AppShell`, `AdminShell`, and the public `apps/book` pages) so the setting applies
- * everywhere its own admin UI copy (`apps/admin/branding/index.tsx`) claims it does.
+ * Sanitizes admin-configured branding HTML before it's rendered. The server sanitizes on save too; this also
+ * covers anything stored before that. Returns `""` where there's no DOM to sanitize with (server-side
+ * rendering), so unsanitized HTML is never emitted.
  */
-export function BrandingHeader({ branding }: { branding: Branding | null }) {
-    if (!branding?.headerHtml) {
-        return null;
+export function sanitizeBrandingHtml(html: string): string {
+    if (!DOMPurify.isSupported) {
+        return "";
     }
-    return <div dangerouslySetInnerHTML={{ __html: branding.headerHtml }} />;
+    return DOMPurify.sanitize(html, { FORBID_TAGS: FORBIDDEN_TAGS, FORBID_ATTR: FORBIDDEN_ATTRS });
 }
 
-export function BrandingFooter({ branding }: { branding: Branding | null }) {
-    if (!branding?.footerHtml) {
+function BrandingHtml({ html }: { html: string | undefined }) {
+    const clean = html ? sanitizeBrandingHtml(html) : "";
+    if (!clean) {
         return null;
     }
-    return <div dangerouslySetInnerHTML={{ __html: branding.footerHtml }} />;
+    return <div dangerouslySetInnerHTML={{ __html: clean }} />;
+}
+
+/**
+ * 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.
+ */
+export function BrandingHeader({ branding }: { branding: Branding | null }) {
+    return <BrandingHtml html={branding?.headerHtml} />;
+}
+
+export function BrandingFooter({ branding }: { branding: Branding | null }) {
+    return <BrandingHtml html={branding?.footerHtml} />;
 }