@rapidmx/web-client 0.3.1 → 0.5.0

package/dist/apps/shared/components/contacts/KeyChangeReview.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useState } from "react";
+import { PinnedKeyChangedError, resolveKeyConflict } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+import Modal from "@rapidmx/react-shared/components/overlays/Modal.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { conflictSourceLabel, formatDate, groupFingerprint, keyChangeErrorMessage } from "./contactKeys.js";
+/**
+ * The old-versus-new comparison for a changed contact key, with Accept new key (confirmed in a dialog) and Keep current
+ * key, calling `resolveKeyConflict()` against the pinned fingerprint shown. Shared by a message's "signing key changed"
+ * notice and a contact's recorded key conflicts.
+ */
+export default function KeyChangeReview({ mailboxUid, address, useType, ownerName, current, proposed, certificate, canReject, canResolve, onResolved, onPinnedKeyChanged, }) {
+    const [confirmOpen, setConfirmOpen] = useState(false);
+    const [busy, setBusy] = useState(null);
+    const [error, setError] = useState(null);
+    const [forbidden, setForbidden] = useState(false);
+    const kind = useType === "sign" ? "signing" : "encryption";
+    const actionable = !!address && !!current && canResolve !== false && !forbidden;
+    async function resolve(action) {
+        setBusy(action);
+        setError(null);
+        try {
+            await resolveKeyConflict(mailboxUid, {
+                address: address,
+                useType,
+                action,
+                expectedPinnedFingerprint: current.fingerprint,
+                ...(action === "accept" && certificate !== undefined ? { certificate } : {}),
+            });
+            setConfirmOpen(false);
+            onResolved(action);
+        }
+        catch (err) {
+            setConfirmOpen(false);
+            if (err instanceof PinnedKeyChangedError) {
+                onPinnedKeyChanged();
+                return;
+            }
+            if (err instanceof ApiRequestError && err.status === 403) {
+                setForbidden(true);
+            }
+            setError(keyChangeErrorMessage(err));
+        }
+        finally {
+            setBusy(null);
+        }
+    }
+    const proposedSeen = proposed.observedAt !== undefined
+        ? `First seen ${formatDate(proposed.observedAt)}${proposed.source ? `, ${conflictSourceLabel(proposed.source)}` : ""}`
+        : "Only seen in this message";
+    return (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsxs("dl", { className: "grid grid-cols-1 sm:grid-cols-2 gap-2", children: [_jsxs("div", { className: "rounded-sm bg-surface p-2", children: [_jsx("dt", { className: "text-xs text-text-muted", children: "Current key" }), current ? (_jsxs("dd", { children: [_jsx("span", { className: "font-mono text-xs break-all", children: groupFingerprint(current.fingerprint) }), _jsxs("span", { className: "block text-xs text-text-muted", children: ["First seen ", formatDate(current.since)] })] })) : (_jsx("dd", { className: "text-xs text-text-muted", children: "The key you trust couldn\u2019t be loaded." }))] }), _jsxs("div", { className: "rounded-sm bg-surface p-2", children: [_jsx("dt", { className: "text-xs text-text-muted", children: "New key" }), _jsxs("dd", { children: [_jsx("span", { className: "font-mono text-xs break-all", children: groupFingerprint(proposed.fingerprint) }), proposed.emails && (_jsxs("span", { className: "block text-xs text-text-muted", children: ["Certificate for ", proposed.emails.length > 0 ? proposed.emails.join(", ") : "no email address"] })), _jsx("span", { className: "block text-xs text-text-muted", children: proposedSeen })] })] })] }), _jsxs("p", { children: ["This is routine when ", ownerName, " renews a certificate, but it can also mean someone is impersonating them. Confirm the new fingerprint with ", ownerName, " another way, such as a phone call, before accepting it."] }), error && _jsx(Alert, { children: error }), actionable && (_jsxs("div", { className: "flex flex-wrap gap-2", children: [_jsx(Button, { type: "button", className: "!w-auto", disabled: busy !== null, onClick: () => {
+                            setError(null);
+                            setConfirmOpen(true);
+                        }, children: "Accept new key" }), canReject && (_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", loading: busy === "reject", disabled: busy !== null, onClick: () => resolve("reject"), children: "Keep current key" }))] })), _jsx(Modal, { open: confirmOpen, onClose: () => busy === null && setConfirmOpen(false), title: "Accept the new key?", children: _jsxs("div", { className: "flex flex-col gap-3 text-sm", children: [_jsxs("p", { children: [useType === "sign"
+                                    ? `Mail from ${address} signed with this key will show as verified.`
+                                    : `Mail you send to ${address} will be encrypted to this key.`, " ", "The current ", kind, " key moves to this contact\u2019s key history."] }), _jsxs("dl", { className: "flex flex-col gap-1", children: [_jsx("dt", { className: "text-xs text-text-muted", children: "New key fingerprint" }), _jsx("dd", { className: "font-mono text-xs break-all", children: groupFingerprint(proposed.fingerprint) })] }), _jsxs("p", { className: "text-text-muted", children: ["Only accept it once you\u2019ve confirmed this fingerprint with ", ownerName, "."] }), _jsxs("div", { className: "flex gap-3", children: [_jsx(Button, { type: "button", className: "!w-auto", loading: busy === "accept", disabled: busy !== null, onClick: () => resolve("accept"), children: "Accept new key" }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", disabled: busy !== null, onClick: () => setConfirmOpen(false), children: "Cancel" })] })] }) })] }));
+}

package/dist/apps/shared/components/contacts/contactKeys.js

@@ -0,0 +1,64 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Display and error helpers for a contact's pinned keys and key changes (`KeyChangeReview`, `ContactDetailPane`,
+ * `MessageDetailPane`). */
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { PinnedKeyChangedError } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+export const KEY_CHANGE_STALE_MESSAGE = "This contact's keys changed while you were looking; reload to see the latest.";
+export const KEY_CHANGE_INVALID_MESSAGE = "The new key isn't a valid, current certificate for this address, so it can't be accepted. Nothing was changed.";
+export const KEY_CHANGE_FORBIDDEN_MESSAGE = "You don't have permission to change this contact's keys.";
+export const KEY_CHANGE_NOT_FOUND_MESSAGE = "There's no key change to resolve for this address any more. It may already have been resolved, or the contact was removed.";
+export const KEY_CHANGE_GENERIC_MESSAGE = "Couldn't update this contact's keys. Try again.";
+/** The error text for a failed `resolveKeyConflict()` other than `PinnedKeyChangedError` (which the caller reloads
+ * on and reports with `KEY_CHANGE_STALE_MESSAGE`). */
+export function keyChangeErrorMessage(err) {
+    if (err instanceof PinnedKeyChangedError) {
+        return KEY_CHANGE_STALE_MESSAGE;
+    }
+    if (err instanceof ApiRequestError && err.status === 400) {
+        return KEY_CHANGE_INVALID_MESSAGE;
+    }
+    if (err instanceof ApiRequestError && err.status === 403) {
+        return KEY_CHANGE_FORBIDDEN_MESSAGE;
+    }
+    if (err instanceof ApiRequestError && err.status === 404) {
+        return KEY_CHANGE_NOT_FOUND_MESSAGE;
+    }
+    return KEY_CHANGE_GENERIC_MESSAGE;
+}
+/** Groups a fingerprint into 4-character blocks (`ab12 cd34 ...`), ignoring any separators it came with, so it can be
+ * read out and compared over another channel. */
+export function groupFingerprint(fingerprint) {
+    const compact = fingerprint.replace(/[\s:]/g, "").toLowerCase();
+    return compact.match(/.{1,4}/g)?.join(" ") ?? compact;
+}
+/** Whether two fingerprints name the same key (case and separators ignored). */
+export function sameFingerprint(a, b) {
+    return a !== undefined && b !== undefined && a.replace(/[\s:]/g, "").toLowerCase() === b.replace(/[\s:]/g, "").toLowerCase();
+}
+/** A revoked key's label: `"superseded"` for a routine replacement, `"revoked"` for a compromised key or one revoked
+ * with no reason; `undefined` when the key isn't revoked. */
+export function revocationLabel(key) {
+    if (!key.revokedAt) {
+        return undefined;
+    }
+    return key.revocationReason === "superseded" ? "superseded" : "revoked";
+}
+/** Where a key conflict was observed, for display. */
+export function conflictSourceLabel(source) {
+    return source === "header" ? "from an incoming message" : "by key discovery";
+}
+/** When `key` (one of `contact`'s pinned keys) started being trusted: when it replaced the newest previous key of its
+ * use, else the contact's `keysFirstSeen`, else the key's own `notBefore`. */
+export function keyPinnedSince(contact, key) {
+    const replaced = (contact.previousKeys ?? []).filter((previous) => previous.useType === key.useType).map((previous) => previous.replacedAt);
+    if (replaced.length > 0) {
+        return Math.max(...replaced);
+    }
+    return contact.keysFirstSeen ?? key.notBefore;
+}
+export function formatDate(ms) {
+    return new Date(ms).toLocaleDateString();
+}

package/dist/apps/shared/components/escrow/layout/EscrowShell.js

@@ -9,11 +9,12 @@ import { HiOutlineClipboardDocumentList, HiOutlineFolderOpen } from "react-icons
 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 { getBranding } from "@rapidmx/react-shared/branding/brandingApi.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import BottomTabBar from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
-import { BrandingFooter, BrandingHeader } from "../../layout/BrandingChrome.js";
 import UserMenu from "../../layout/UserMenu.js";
+import { signOutOfConsole } from "../../admin/signOut.js";
+const DEFAULT_ICON_SRC = "/images/logo.svg";
 const NAV_ITEMS = [
     { id: "matters", href: "/escrow", label: "Matters", icon: HiOutlineFolderOpen },
     { id: "auditLog", href: "/escrow/audit-log", label: "Audit Log", icon: HiOutlineClipboardDocumentList },
@@ -37,8 +38,25 @@ const NAV_ITEMS = [
 export default function EscrowShell({ active, userUid, authServerUrl, children }) {
     const [status, setStatus] = useState("checking");
     const [error, setError] = useState(null);
-    const { branding, iconSrc } = useBranding();
+    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;
@@ -53,7 +71,8 @@ export default function EscrowShell({ active, userUid, authServerUrl, children }
         });
     }, [userUid]);
     function handleSignOut() {
-        window.location.href = authServerUrl ?? "/";
+        // Ends the auth-server session and tells other tabs, not just navigates - see `signOutOfConsole()`.
+        void signOutOfConsole(authServerUrl);
     }
     let content;
     if (!userUid || status === "checking") {
@@ -71,5 +90,5 @@ export default function EscrowShell({ active, userUid, authServerUrl, children }
                                         : "text-text-muted hover:bg-surface-alt hover:text-text",
                                 ].join(" "), children: _jsx(Icon, { size: 20, "aria-hidden": "true" }) }, id)))] }), _jsx(BottomTabBar, { apps: NAV_ITEMS, 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 _jsx(_Fragment, { children: content });
 }

package/dist/apps/shared/components/layout/AppShell.js

@@ -4,16 +4,46 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import "../../styles/app.css";
-import { useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { HiOutlineCalendarDays, HiOutlineClipboardDocumentList, HiOutlineEnvelope, 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 { flushComposeDrafts, markSigningOut } from "../mail/compose/composeFlushRegistry.js";
 import BottomTabBar 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 { 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";
+/** How long sign-out waits for auth-server's logout before navigating anyway. */
+export const LOGOUT_TIMEOUT_MS = 3000;
+/**
+ * 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) {
+    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 const APPS = [
     { id: "mail", href: "/", label: "Mail", icon: HiOutlineEnvelope },
     { id: "calendar", href: "/calendar", label: "Calendar", icon: HiOutlineCalendarDays },
@@ -38,12 +68,74 @@ const ACTIVE_LABELS = {
  */
 export default function AppShell({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, children, }) {
     const [stoppingImpersonation, setStoppingImpersonation] = useState(false);
+    const signingOutRef = useRef(false);
     const { branding, iconSrc } = useBranding();
     useRedirectIfUnauthenticated(userUid, authServerUrl);
     // Mounted here, not scoped to Mail/Settings (the only shells that actually read unlocked keys),
     // specifically so activity in *any* app resets the idle clock - see that hook's own doc comment.
     useIdleKeyTimeout();
-    function handleSignOut() {
+    // 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 || !trusted) {
+            return;
+        }
+        getSetupStatus()
+            .then((status) => {
+            if (status.required) {
+                window.location.href = "/admin/setup";
+            }
+        })
+            .catch(() => undefined);
+    }, [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) => {
+            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 ?? "/";
     }
     async function handleStopImpersonating() {
@@ -63,10 +155,10 @@ export default function AppShell({ active, userUid, authServerUrl, impersonating
     if (!userUid) {
         return _jsx("div", { className: "min-h-screen" });
     }
-    return (_jsx(ComposeProvider, { children: _jsxs("div", { className: "min-h-screen flex flex-col bg-surface-alt", children: [_jsx(BrandingHeader, { branding: branding }), impersonating && (_jsxs("div", { className: "h-10 shrink-0 bg-warning text-warning-contrast flex items-center justify-center gap-3 text-sm font-medium px-4", children: [_jsxs("span", { children: ["You are viewing as ", _jsx("strong", { children: userUid }), "."] }), _jsx("button", { type: "button", onClick: handleStopImpersonating, disabled: stoppingImpersonation, className: "underline hover:no-underline disabled:opacity-60", children: stoppingImpersonation ? "Returning to admin…" : "Return to admin" })] })), _jsxs("div", { className: "flex-1 flex min-h-0", children: [_jsxs("nav", { "aria-label": "Apps", className: "hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center py-3 gap-1", children: [_jsx("img", { src: iconSrc, width: "96", height: "96", alt: "", className: "mb-3" }), APPS.map(({ id, href, label, icon: Icon }) => (_jsx("a", { 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(" "), children: _jsx(Icon, { size: 20, "aria-hidden": "true" }) }, id)))] }), _jsx(BottomTabBar, { apps: APPS, 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: ACTIVE_LABELS[active] }), _jsx(UserMenu, { userUid: userUid, authServerUrl: authServerUrl, onSignOut: handleSignOut, showAdminLink: trusted, showSettingsLink: true })] }), _jsx("div", { className: "flex-1 flex min-h-0 pb-14 md:pb-0", children: children })] })] }), _jsx(BrandingFooter, { branding: branding })] }) }));
+    return (_jsx(UnlockPromptProvider, { children: _jsx(ComposeProvider, { userUid: userUid, trusted: !!trusted && !impersonating, children: _jsxs("div", { className: "min-h-screen flex flex-col bg-surface-alt", children: [_jsx(BrandingHeader, { branding: branding }), impersonating && (_jsxs("div", { className: "h-10 shrink-0 bg-warning text-warning-contrast flex items-center justify-center gap-3 text-sm font-medium px-4", children: [_jsxs("span", { children: ["You are viewing as ", _jsx("strong", { children: userUid }), "."] }), _jsx("button", { type: "button", onClick: handleStopImpersonating, disabled: stoppingImpersonation, className: "underline hover:no-underline disabled:opacity-60", children: stoppingImpersonation ? "Returning to admin…" : "Return to admin" })] })), _jsxs("div", { className: "flex-1 flex min-h-0", children: [_jsxs("nav", { "aria-label": "Apps", className: "hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center py-3 gap-1", children: [_jsx("img", { src: iconSrc, width: "96", height: "96", alt: "", className: "mb-3" }), APPS.map(({ id, href, label, icon: Icon }) => (_jsx("a", { 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(" "), children: _jsx(Icon, { size: 20, "aria-hidden": "true" }) }, id)))] }), _jsx(BottomTabBar, { apps: APPS, 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: ACTIVE_LABELS[active] }), _jsx(UserMenu, { userUid: userUid, authServerUrl: authServerUrl, onSignOut: handleSignOut, showAdminLink: trusted, showSettingsLink: true })] }), _jsx("div", { className: "flex-1 flex min-h-0 pb-14 md:pb-0", children: children })] })] }), _jsx(BrandingFooter, { branding: branding })] }) }) }));
 }

package/dist/apps/shared/components/layout/BrandingChrome.js

@@ -1,18 +1,53 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import DOMPurify from "dompurify";
+/** 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 }) {
-    if (!branding?.headerHtml) {
-        return null;
+export function sanitizeBrandingHtml(html) {
+    if (!DOMPurify.isSupported) {
+        return "";
     }
-    return _jsx("div", { dangerouslySetInnerHTML: { __html: branding.headerHtml } });
+    return DOMPurify.sanitize(html, { FORBID_TAGS: FORBIDDEN_TAGS, FORBID_ATTR: FORBIDDEN_ATTRS });
 }
-export function BrandingFooter({ branding }) {
-    if (!branding?.footerHtml) {
+function BrandingHtml({ html }) {
+    const clean = html ? sanitizeBrandingHtml(html) : "";
+    if (!clean) {
         return null;
     }
-    return _jsx("div", { dangerouslySetInnerHTML: { __html: branding.footerHtml } });
+    return _jsx("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 }) {
+    return _jsx(BrandingHtml, { html: branding?.headerHtml });
+}
+export function BrandingFooter({ branding }) {
+    return _jsx(BrandingHtml, { html: branding?.footerHtml });
 }

package/dist/apps/shared/components/layout/KeyEnrollmentGate.js

@@ -8,7 +8,9 @@ import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Button from "@rapidmx/react-shared/components/buttons/Button.js";
 import FormField from "@rapidmx/react-shared/components/forms/FormField.js";
-import { enrollKey, getKeyVault } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+import { enrollKey, getKeyVault, VaultAlreadyInitializedError } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+import { UnopenableKeysNotice, unlockErrorMessage } from "./UnlockPromptProvider.js";
+import { RecoveryFollowUpModal, UnlockModeToggle, startRecoveryUnlock } from "./RecoveryCodeUnlock.js";
 import { ENCRYPTION_PRIVATE_KEY_AAD_PURPOSE, getUnlockedKeys, unlockWithPassword, } from "@rapidmx/react-shared/crypto/keySession.js";
 import { buildAad, generateMasterKey, sealWithKey } from "@rapidmx/react-shared/crypto/masterKey.js";
 import { buildPasswordWrap, buildRecoveryWraps } from "@rapidmx/react-shared/crypto/masterKeyWraps.js";
@@ -48,13 +50,19 @@ async function provisionEncryptionKey(mailboxUid, mailboxAddress, password) {
  * `children` unchanged rather than blocking mail entirely - encryption is optional and gradual by design
  * (the spec's own "near zero frictionless experience" goal), not a hard prerequisite for reading mail.
  */
-export default function KeyEnrollmentGate({ mailboxUid, mailboxAddress, mailboxKeys, children }) {
+export default function KeyEnrollmentGate({ mailboxUid, mailboxAddress, mailboxKeys, blocking = true, canProvision = false, children, }) {
     const [status, setStatus] = useState(mailboxUid ? "checking" : "ready");
     const [password, setPassword] = useState("");
     const [confirmPassword, setConfirmPassword] = useState("");
     const [error, setError] = useState(null);
     const [recoveryCodes, setRecoveryCodes] = useState([]);
     const [codesSaved, setCodesSaved] = useState(false);
+    const [codesCopied, setCodesCopied] = useState(false);
+    const [unopenableKeys, setUnopenableKeys] = useState(null);
+    const [unlockMode, setUnlockMode] = useState("password");
+    const [recoveryCode, setRecoveryCode] = useState("");
+    // Set after a recovery-code unlock: `children` render at once, with the follow-up steps in a dialog on top.
+    const [followUp, setFollowUp] = useState(null);
     useEffect(() => {
         if (!mailboxUid) {
             return;
@@ -70,7 +78,7 @@ export default function KeyEnrollmentGate({ mailboxUid, mailboxAddress, mailboxK
         getKeyVault(mailboxUid)
             .then((vault) => {
             if (!cancelled) {
-                setStatus(vault.wrappedKeys.length > 0 ? "unlock" : "setup_password");
+                setStatus(vault.wrappedKeys.length > 0 ? "unlock" : canProvision ? "setup_password" : "ready");
             }
         })
             .catch(() => {
@@ -81,7 +89,7 @@ export default function KeyEnrollmentGate({ mailboxUid, mailboxAddress, mailboxK
         return () => {
             cancelled = true;
         };
-    }, [mailboxUid]);
+    }, [mailboxUid, canProvision]);
     async function handleUnlock(e) {
         e.preventDefault();
         setError(null);
@@ -89,14 +97,21 @@ export default function KeyEnrollmentGate({ mailboxUid, mailboxAddress, mailboxK
         try {
             // Only reachable via "unlock", which the effect above only ever sets once mailboxUid was
             // defined.
-            await unlockWithPassword(mailboxUid, mailboxKeys ?? [], password);
+            const result = await (unlockMode === "recovery"
+                ? startRecoveryUnlock(mailboxUid, mailboxKeys ?? [], recoveryCode)
+                : unlockWithPassword(mailboxUid, mailboxKeys ?? [], password));
+            const recovery = unlockMode === "recovery" ? result : null;
+            if (result.unopenableKeys.length > 0) {
+                setUnopenableKeys(result.unopenableKeys);
+            }
+            setRecoveryCode("");
+            setFollowUp(recovery);
             setStatus("ready");
         }
-        catch {
-            // Deliberately generic - see `unlockWithPassword()`'s own doc comment: it throws the same way
-            // for "no password wrap enrolled" and "wrong password" today, and this UI has no way to tell
-            // those apart without leaking which is which to a potential attacker guessing passwords.
-            setError("Incorrect password.");
+        catch (err) {
+            // "Incorrect password." (or "That recovery code didn't work.") unless the secret was right but the
+            // encryption key won't open - see `unlockErrorMessage()`.
+            setError(unlockErrorMessage(err, unlockMode));
             setStatus("unlock");
         }
     }
@@ -113,30 +128,64 @@ export default function KeyEnrollmentGate({ mailboxUid, mailboxAddress, mailboxK
         setError(null);
         setStatus("enrolling");
         try {
+            // The vault was only checked on mount - another tab or device may have set encryption up since.
+            // Provisioning now would publish a second master key, orphaning whichever setup lost the race, so
+            // re-check right before generating anything. restapi's enrollKey() also refuses (409) wraps for a
+            // vault that already has them, for a race inside this window.
             // Only reachable via "setup_password", which the effect above only ever sets once mailboxUid
             // was defined (and mailboxAddress necessarily came with it - see KeyEnrollmentGateProps).
+            const fresh = await getKeyVault(mailboxUid);
+            if (fresh.wrappedKeys.length > 0 || fresh.masterKeyWraps.length > 0) {
+                setStatus("already_set_up");
+                return;
+            }
             const { recoveryCodes: codes } = await provisionEncryptionKey(mailboxUid, mailboxAddress, password);
             setRecoveryCodes(codes);
             setStatus("show_recovery_codes");
         }
         catch (err) {
+            // Only a 409 that is really "the vault already has wraps" - an unrelated lost optimistic-lock race is shown
+            // as an ordinary error.
+            if (err instanceof VaultAlreadyInitializedError) {
+                setStatus("already_set_up");
+                return;
+            }
             setError(err instanceof ApiRequestError ? err.message : "Could not set up encryption for this mailbox.");
             setStatus("setup_password");
         }
     }
+    async function handleCopyCodes() {
+        try {
+            await navigator.clipboard.writeText(recoveryCodes.join("\n"));
+            setCodesCopied(true);
+            setTimeout(() => setCodesCopied(false), 2000);
+        }
+        catch {
+            // Clipboard access can be denied by the browser - the codes are still selectable/copyable by
+            // hand from the list below.
+        }
+    }
     if (status === "checking") {
         return null;
     }
-    if (status === "unlock" || status === "unlocking") {
+    if ((status === "unlock" || status === "unlocking") && blocking) {
         const unlocking = status === "unlocking";
-        return (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8", children: [_jsx("h1", { className: "text-lg font-bold mb-2", children: "Unlock your mailbox" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "Enter your encryption password to unlock signing and reading protected mail this session." }), error && _jsx(Alert, { children: error }), _jsxs("form", { onSubmit: handleUnlock, children: [_jsx(FormField, { label: "Encryption password", htmlFor: "key-unlock-password", children: _jsx("input", { id: "key-unlock-password", type: "password", className: "w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface", value: password, onChange: (e) => setPassword(e.target.value), disabled: unlocking, autoComplete: "current-password" }) }), _jsx(Button, { type: "submit", loading: unlocking, disabled: unlocking, children: "Unlock" })] })] }) }));
+        return (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8", children: [_jsx("h1", { className: "text-lg font-bold mb-2", children: "Unlock your mailbox" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: unlockMode === "password"
+                            ? "Enter your encryption password to unlock signing and reading protected mail this session."
+                            : "Enter one of your recovery codes to unlock signing and reading protected mail this session. Each code works once." }), error && _jsx(Alert, { children: error }), _jsxs("form", { onSubmit: handleUnlock, children: [unlockMode === "password" ? (_jsx(FormField, { label: "Encryption password", htmlFor: "key-unlock-password", children: _jsx("input", { id: "key-unlock-password", type: "password", className: "w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface", value: password, onChange: (e) => setPassword(e.target.value), disabled: unlocking, autoComplete: "current-password" }) })) : (_jsx(FormField, { label: "Recovery code", htmlFor: "key-unlock-recovery-code", children: _jsx("input", { id: "key-unlock-recovery-code", type: "text", className: "w-full text-sm font-mono border border-border rounded-sm py-1.5 px-2 bg-surface", value: recoveryCode, onChange: (e) => setRecoveryCode(e.target.value), disabled: unlocking, autoComplete: "off", autoCapitalize: "characters", spellCheck: false }) })), _jsx(Button, { type: "submit", loading: unlocking, disabled: unlocking, children: "Unlock" })] }), _jsx("div", { className: "mt-3", children: _jsx(UnlockModeToggle, { mode: unlockMode, disabled: unlocking, onChange: (next) => {
+                                setUnlockMode(next);
+                                setError(null);
+                            } }) })] }) }));
     }
     if (status === "setup_password" || status === "enrolling") {
         const enrolling = status === "enrolling";
         return (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8", children: [_jsx("h1", { className: "text-lg font-bold mb-2", children: "Protect your mailbox" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "Choose a password to protect your encryption keys. This is separate from your sign-in password and is never sent to the server." }), error && _jsx(Alert, { children: error }), _jsxs("form", { onSubmit: handleSetPassword, children: [_jsx(FormField, { label: "Encryption password", htmlFor: "key-enrollment-password", children: _jsx("input", { id: "key-enrollment-password", type: "password", className: "w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface", value: password, onChange: (e) => setPassword(e.target.value), disabled: enrolling, autoComplete: "new-password" }) }), _jsx(FormField, { label: "Confirm password", htmlFor: "key-enrollment-password-confirm", children: _jsx("input", { id: "key-enrollment-password-confirm", type: "password", className: "w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface", value: confirmPassword, onChange: (e) => setConfirmPassword(e.target.value), disabled: enrolling, autoComplete: "new-password" }) }), _jsx(Button, { type: "submit", loading: enrolling, disabled: enrolling, children: "Continue" })] })] }) }));
     }
+    if (status === "already_set_up") {
+        return (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8", children: [_jsx("h1", { className: "text-lg font-bold mb-2", children: "Encryption is already set up" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "This mailbox\u2019s encryption was set up in another tab or on another device while this page was open, so nothing was changed here. Reload the page and unlock with the password chosen there." }), _jsx(Button, { type: "button", onClick: () => window.location.reload(), children: "Reload" })] }) }));
+    }
     if (status === "show_recovery_codes") {
-        return (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8", children: [_jsx("h1", { className: "text-lg font-bold mb-2", children: "Save your recovery codes" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "If you lose your password, these codes are the only way to recover your encrypted mail. Each code can be used once. Store them somewhere safe \u2014 they will not be shown again." }), _jsx("ul", { className: "grid grid-cols-2 gap-2 mb-5 font-mono text-sm", children: recoveryCodes.map((code) => (_jsx("li", { className: "bg-surface-alt rounded-sm py-1.5 px-2 text-center", children: code }, code))) }), _jsxs("label", { className: "flex items-center gap-2 text-sm mb-4", children: [_jsx("input", { type: "checkbox", checked: codesSaved, onChange: (e) => setCodesSaved(e.target.checked) }), "I have saved these recovery codes in a safe place."] }), _jsx(Button, { type: "button", disabled: !codesSaved, onClick: () => setStatus("ready"), children: "Continue" })] }) }));
+        return (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8", children: [_jsx("h1", { className: "text-lg font-bold mb-2", children: "Save your recovery codes" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "If you lose your password, these codes are the only way to recover your encrypted mail. Each code can be used once. Store them somewhere safe \u2014 they will not be shown again." }), _jsx("ul", { className: "grid grid-cols-2 gap-2 mb-3 font-mono text-sm", children: recoveryCodes.map((code) => (_jsx("li", { className: "bg-surface-alt rounded-sm py-1.5 px-2 text-center", children: code }, code))) }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto mb-5", onClick: handleCopyCodes, children: codesCopied ? "Copied" : "Copy codes to clipboard" }), _jsxs("label", { className: "flex items-center gap-2 text-sm mb-4", children: [_jsx("input", { type: "checkbox", checked: codesSaved, onChange: (e) => setCodesSaved(e.target.checked) }), "I have saved these recovery codes in a safe place."] }), _jsx(Button, { type: "button", disabled: !codesSaved, onClick: () => setStatus("ready"), children: "Continue" })] }) }));
     }
-    return _jsx(_Fragment, { children: children });
+    return (_jsxs(_Fragment, { children: [children, unopenableKeys && _jsx(UnopenableKeysNotice, { fingerprints: unopenableKeys, onDismiss: () => setUnopenableKeys(null) }), followUp && _jsx(RecoveryFollowUpModal, { followUp: followUp, onDone: () => setFollowUp(null) })] }));
 }

package/dist/apps/shared/components/layout/MailboxProvisioning.js

@@ -24,7 +24,10 @@ export default function MailboxProvisioning() {
     const [options, setOptions] = useState([]);
     const [selected, setSelected] = useState("");
     const [error, setError] = useState(null);
+    // Bumped by "Retry" to re-run the check below.
+    const [attempt, setAttempt] = useState(0);
     useEffect(() => {
+        setStatus("checking");
         autoProvisionMailbox()
             .then((result) => {
             if (result.status === "needs_selection") {
@@ -42,8 +45,10 @@ export default function MailboxProvisioning() {
                 window.location.reload();
             }
         })
-            .catch(() => setStatus("unavailable"));
-    }, []);
+            // 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"));
+    }, [attempt]);
     async function handleConfirm() {
         // `selected` only ever takes a value from `options` itself (the initial default, or the
         // <select>'s own onChange, which can only report one of its own rendered <option> values), so
@@ -68,6 +73,9 @@ export default function MailboxProvisioning() {
         const creating = status === "creating";
         content = (_jsxs("div", { className: "w-full flex flex-col gap-3", children: [_jsx("p", { className: "text-sm text-text-muted text-center", children: "Choose your mailbox address to get started:" }), error && _jsx(Alert, { children: error }), _jsx("select", { "aria-label": "Mailbox address", className: "text-sm border border-border rounded-sm py-1.5 px-2 bg-surface", value: selected, onChange: (e) => setSelected(e.target.value), disabled: creating, children: options.map((option) => (_jsx("option", { value: option.primarySmtpAddress, children: option.primarySmtpAddress }, option.primarySmtpAddress))) }), _jsx(Button, { type: "button", onClick: handleConfirm, loading: creating, disabled: creating, className: "!w-auto self-center", children: "Continue" })] }));
     }
+    else if (status === "retryable") {
+        content = (_jsxs(_Fragment, { children: [_jsx("h1", { className: "text-lg font-bold uppercase tracking-wide", children: "Couldn\u2019t check right now" }), _jsx("p", { className: "text-sm text-text-muted", children: "We couldn\u2019t check whether a mailbox can be set up for you. Please try again." }), _jsx(Button, { type: "button", onClick: () => setAttempt((n) => n + 1), className: "!w-auto self-center", children: "Retry" })] }));
+    }
     else {
         content = (_jsxs(_Fragment, { children: [_jsx("h1", { className: "text-lg font-bold uppercase tracking-wide", children: "No mailbox available" }), _jsx("p", { className: "text-sm text-text-muted", children: "Ask an administrator to create one for you." })] }));
     }