@rapidmx/web-client 0.4.0 → 0.5.0

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

@@ -4,7 +4,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import "../../styles/app.css";
-import { useState, useEffect } 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";
@@ -12,11 +12,38 @@ 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 { 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";
+/** 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 },
@@ -41,15 +68,17 @@ 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();
-    // 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()
@@ -59,14 +88,54 @@ export default function AppShell({ active, userUid, authServerUrl, impersonating
             }
         })
             .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) => {
+            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() {
@@ -86,7 +155,7 @@ export default function AppShell({ active, userUid, authServerUrl, impersonating
     if (!userUid) {
         return _jsx("div", { className: "min-h-screen" });
     }
-    return (_jsx(UnlockPromptProvider, { children: _jsx(ComposeProvider, { userUid: userUid, 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: [
+    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"

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,7 +50,7 @@ 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, blocking = true, 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("");
@@ -56,6 +58,11 @@ export default function KeyEnrollmentGate({ mailboxUid, mailboxAddress, mailboxK
     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;
@@ -71,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(() => {
@@ -82,7 +89,7 @@ export default function KeyEnrollmentGate({ mailboxUid, mailboxAddress, mailboxK
         return () => {
             cancelled = true;
         };
-    }, [mailboxUid]);
+    }, [mailboxUid, canProvision]);
     async function handleUnlock(e) {
         e.preventDefault();
         setError(null);
@@ -90,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");
         }
     }
@@ -114,13 +128,28 @@ 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");
         }
@@ -141,14 +170,22 @@ export default function KeyEnrollmentGate({ mailboxUid, mailboxAddress, mailboxK
     }
     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-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." })] }));
     }

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

@@ -0,0 +1,174 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Unlocking with a recovery code, and what has to happen after it. A recovery code is single-use: once it has opened
+ * the keys, the user may set a new encryption password (`replacePasswordWrap()`), and then the used code is removed
+ * (`consumeRecoveryCode()`). The order matters - react-shared's `replacePasswordWrap()` refuses unless another own
+ * unlock method remains, and the not-yet-consumed code is that method.
+ *
+ * `UnlockPromptProvider` and `KeyEnrollmentGate` both unlock with `startRecoveryUnlock()`, settle whatever was waiting
+ * on the unlock straight away, and then show `RecoveryFollowUpModal` for the follow-up steps.
+ */
+import { useState } from "react";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { getUnlockedKeys, unlockWithRecoveryCode } from "@rapidmx/react-shared/crypto/keySession.js";
+import { getKeyVault } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+import { KeysLockedError } from "@rapidmx/react-shared/crypto/masterKey.js";
+import { PasswordWrapReplaceError, consumeRecoveryCode, replacePasswordWrap, } from "@rapidmx/react-shared/crypto/masterKeyWraps.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 FormField from "@rapidmx/react-shared/components/forms/FormField.js";
+/** The same minimum every other "set an encryption password" form in this app uses. */
+export const MIN_PASSWORD_LENGTH = 8;
+/** Where recovery codes are regenerated. */
+export const ENCRYPTION_SETTINGS_HREF = "/settings/encryption";
+/** Deliberately generic: a wrong code and a vault with no recovery codes fail the same way. */
+export const RECOVERY_CODE_ERROR = "That recovery code didn't work.";
+export const REPLACE_ROTATED_MESSAGE = "Your encryption keys were changed on another device after you unlocked, so your password wasn't changed and your recovery code wasn't used. Reload the page and unlock again.";
+export const REPLACE_MULTIPLE_PASSWORDS_MESSAGE = "This mailbox has more than one encryption password, so it can't be replaced here. Nothing was changed. Remove the extra password in Settings > Encryption first.";
+export const REPLACE_NO_OTHER_METHOD_MESSAGE = "Your password wasn't changed, because this mailbox would be left with no other way to unlock. Your recovery code may already have been used in another window. Nothing was changed.";
+export const REPLACE_ADD_FAILED_RESTORED_MESSAGE = "Your new password couldn't be saved, so your old password still works. Nothing was changed. Try again.";
+export const REPLACE_ADD_FAILED_NOT_RESTORED_MESSAGE = "Your new password couldn't be saved, and your old password couldn't be put back, so this mailbox has no password right now. Your recovery code still works. Try again, or keep the code for now.";
+export const REPLACE_LOCKED_MESSAGE = "Your encryption keys were locked before your new password could be set, so nothing was changed and your recovery code still works. Unlock with it again to set a new password.";
+export const REPLACE_GENERIC_MESSAGE = "Your new password couldn't be saved. Nothing was changed. Try again.";
+export const CONSUME_FAILED_MESSAGE = "The recovery code you used couldn't be removed, so it may still work. Regenerate your recovery codes in Settings > Encryption to make sure it can't be used again.";
+/**
+ * Unlocks `mailboxUid` with a recovery code (normalized by react-shared, so spacing and case don't matter). The
+ * vault's `masterKeyGeneration` is read first: if another device rotates the master key at any point after that read,
+ * the generation passed to `replacePasswordWrap()` later is stale and the replacement is refused, never written with
+ * a dead master key. A failed read just means no generation check. Rejects exactly as `unlockWithRecoveryCode()` does.
+ */
+export async function startRecoveryUnlock(mailboxUid, mailboxKeys, code) {
+    const expectedMasterKeyGeneration = await getKeyVault(mailboxUid).then((vault) => vault.masterKeyGeneration, () => undefined);
+    const result = await unlockWithRecoveryCode(mailboxUid, mailboxKeys, code);
+    return {
+        mailboxUid,
+        recoveryMethodId: result.recoveryMethodId,
+        remainingRecoveryCodes: result.remainingRecoveryCodes,
+        expectedMasterKeyGeneration,
+        unopenableKeys: result.unopenableKeys,
+    };
+}
+/** A "use a recovery code instead" / "use your password instead" switch for an unlock form. */
+export function UnlockModeToggle({ mode, disabled, onChange, }) {
+    return (_jsx(Button, { type: "button", variant: "text", className: "!w-auto", disabled: disabled, onClick: () => onChange(mode === "password" ? "recovery" : "password"), children: mode === "password" ? "Use a recovery code instead" : "Use your password instead" }));
+}
+function replaceFailure(err) {
+    if (err instanceof PasswordWrapReplaceError) {
+        switch (err.reason) {
+            case "master_key_rotated":
+                return { message: REPLACE_ROTATED_MESSAGE, blocked: { message: REPLACE_ROTATED_MESSAGE, reload: true } };
+            case "multiple_password_wraps":
+                return {
+                    message: REPLACE_MULTIPLE_PASSWORDS_MESSAGE,
+                    blocked: { message: REPLACE_MULTIPLE_PASSWORDS_MESSAGE, allowSecondary: true },
+                };
+            case "no_other_unlock_method":
+                return { message: REPLACE_NO_OTHER_METHOD_MESSAGE, blocked: { message: REPLACE_NO_OTHER_METHOD_MESSAGE } };
+            default:
+                return { message: err.restored ? REPLACE_ADD_FAILED_RESTORED_MESSAGE : REPLACE_ADD_FAILED_NOT_RESTORED_MESSAGE };
+        }
+    }
+    if (err instanceof KeysLockedError) {
+        return { message: REPLACE_LOCKED_MESSAGE, blocked: { message: REPLACE_LOCKED_MESSAGE } };
+    }
+    return { message: err instanceof ApiRequestError ? `${REPLACE_GENERIC_MESSAGE} (${err.message})` : REPLACE_GENERIC_MESSAGE };
+}
+/**
+ * The steps after a recovery-code unlock, shown once the keys are already open:
+ *
+ * 1. Offer a new encryption password. Optional ("Skip") - unless this was the last code, where it's required before the
+ * code is used up (otherwise only a forgotten password would remain); then "Keep this code for now" closes without
+ * consuming anything.
+ * 2. Remove the used code. A failure is reported but never blocks anything - the keys are already open.
+ * 3. Say how many codes are left, nudging towards regenerating them at two or fewer.
+ *
+ * Mount it with a `key` per follow-up so each unlock starts from step 1.
+ */
+export function RecoveryFollowUpModal({ followUp, open = true, onDone }) {
+    const { mailboxUid, recoveryMethodId, remainingRecoveryCodes, expectedMasterKeyGeneration } = followUp;
+    const required = remainingRecoveryCodes === 0;
+    const [step, setStep] = useState("password");
+    const [newPassword, setNewPassword] = useState("");
+    const [confirmPassword, setConfirmPassword] = useState("");
+    const [error, setError] = useState(null);
+    const [blocked, setBlocked] = useState(null);
+    const [busy, setBusy] = useState(false);
+    const [passwordSet, setPasswordSet] = useState(false);
+    const [consumeFailed, setConsumeFailed] = useState(false);
+    async function consume() {
+        let failed = !recoveryMethodId;
+        if (recoveryMethodId) {
+            try {
+                await consumeRecoveryCode(mailboxUid, recoveryMethodId);
+            }
+            catch (err) {
+                // 404: already gone (e.g. consumed from another tab) - that's the outcome wanted.
+                failed = !(err instanceof ApiRequestError && err.status === 404);
+            }
+        }
+        setConsumeFailed(failed);
+        setStep("done");
+    }
+    async function handleSetPassword(e) {
+        e.preventDefault();
+        if (newPassword.length < MIN_PASSWORD_LENGTH) {
+            setError(`Password must be at least ${MIN_PASSWORD_LENGTH} characters.`);
+            return;
+        }
+        if (newPassword !== confirmPassword) {
+            setError("Passwords do not match.");
+            return;
+        }
+        setError(null);
+        setBusy(true);
+        try {
+            // Read now, not at unlock time: an idle timeout or a lock elsewhere may have destroyed the keys since.
+            const unlocked = getUnlockedKeys(mailboxUid);
+            if (!unlocked || unlocked.destroyed) {
+                throw new KeysLockedError();
+            }
+            // Before consuming - the unused code is the other unlock method that makes replacing safe.
+            await replacePasswordWrap(mailboxUid, unlocked, newPassword, expectedMasterKeyGeneration);
+        }
+        catch (err) {
+            const failure = replaceFailure(err);
+            setBlocked(failure.blocked ?? null);
+            setError(failure.blocked ? null : failure.message);
+            setBusy(false);
+            return;
+        }
+        setNewPassword("");
+        setConfirmPassword("");
+        setPasswordSet(true);
+        await consume();
+        setBusy(false);
+    }
+    async function handleSkip() {
+        setError(null);
+        setBusy(true);
+        await consume();
+        setBusy(false);
+    }
+    const title = step === "done" ? "Recovery code used" : "Set a new encryption password";
+    const secondary = !blocked || !!blocked.allowSecondary;
+    function handleClose() {
+        if (busy) {
+            return;
+        }
+        // Closing the password step means the same as its secondary action - never a silent password change, and the
+        // last code is never consumed without a new password.
+        if (step === "password" && !required && secondary) {
+            void handleSkip();
+            return;
+        }
+        onDone();
+    }
+    return (_jsx(Modal, { open: open, onClose: handleClose, title: title, children: step === "password" ? (_jsxs(_Fragment, { children: [required ? (_jsx("p", { className: "text-sm text-text-muted mb-4", children: "That was your last recovery code. Set a new encryption password before it\u2019s used up - otherwise a password you\u2019ve forgotten would be the only way left to unlock this mailbox." })) : (_jsx("p", { className: "text-sm text-text-muted mb-4", children: "Your mailbox is unlocked. If you\u2019ve forgotten your encryption password, set a new one now. The recovery code you used will then be used up." })), blocked ? (_jsxs(_Fragment, { children: [_jsx(Alert, { children: blocked.message }), _jsxs("div", { className: "flex gap-2", children: [blocked.reload && (_jsx(Button, { type: "button", className: "!w-auto", onClick: () => window.location.reload(), children: "Reload page" })), !secondary && (_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onDone, children: "Close" }))] })] })) : (_jsxs("form", { onSubmit: handleSetPassword, children: [error && _jsx(Alert, { children: error }), _jsx(FormField, { label: "New encryption password", htmlFor: "recovery-new-password", children: _jsx("input", { id: "recovery-new-password", type: "password", className: "w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface", value: newPassword, onChange: (e) => setNewPassword(e.target.value), disabled: busy, autoComplete: "new-password", autoFocus: true }) }), _jsx(FormField, { label: "Confirm new password", htmlFor: "recovery-new-password-confirm", children: _jsx("input", { id: "recovery-new-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: busy, autoComplete: "new-password" }) }), _jsx(Button, { type: "submit", className: "!w-auto", loading: busy, disabled: busy, children: "Set password" })] })), secondary && (_jsx("div", { className: "mt-2", children: required ? (_jsx(Button, { type: "button", variant: "text", className: "!w-auto", disabled: busy, onClick: onDone, children: "Keep this code for now" })) : (_jsx(Button, { type: "button", variant: "text", className: "!w-auto", disabled: busy, onClick: handleSkip, children: "Skip" })) }))] })) : (_jsxs(_Fragment, { children: [passwordSet && _jsx("p", { className: "text-sm mb-3", children: "Your new encryption password is set." }), consumeFailed ? (_jsx("p", { role: "status", className: "mb-3 py-2 px-3 rounded-sm text-sm bg-warning/15 text-text", children: CONSUME_FAILED_MESSAGE })) : (_jsx("p", { className: "text-sm mb-3", children: "The recovery code you used has been used up and won\u2019t work again." })), _jsxs("p", { className: "text-sm mb-3", children: [remainingRecoveryCodes === 0
+                            ? "You have no recovery codes left."
+                            : `You have ${remainingRecoveryCodes} recovery ${remainingRecoveryCodes === 1 ? "code" : "codes"} left.`, remainingRecoveryCodes <= 2 && (_jsxs(_Fragment, { children: [" ", "Generate a new set in", " ", _jsx("a", { href: ENCRYPTION_SETTINGS_HREF, className: "text-primary-dark hover:underline", children: "Settings > Encryption" }), " ", "with Regenerate recovery codes."] }))] }), _jsx(Button, { type: "button", className: "!w-auto", onClick: onDone, children: "Done" })] })) }));
+}