@rapidmx/web-client 0.4.0 → 0.6.0

package/dist/apps/shared/components/layout/AppShell.d.ts

@@ -0,0 +1,49 @@
+import "../../styles/app.css";
+import React, { PropsWithChildren } from "react";
+import type { IconType } from "react-icons";
+import { NavItem } from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
+import { PluginNav, PluginNavProps } from "../../plugins/pluginNav.js";
+/** How long sign-out waits for auth-server's logout before navigating anyway. */
+export declare const LOGOUT_TIMEOUT_MS = 3000;
+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 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 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;
+    /** auth-server's base URL, injected via the route's `fetchProps`. */
+    authServerUrl?: string;
+    /**
+     * `true` when this session is an admin "log in as user" impersonation (a `jwt_impersonator` cookie is
+     * present) — see `MailShell`'s original doc comment, unchanged now that this lives here. Drives the
+     * "you are viewing as this user — stop impersonating" banner below.
+     */
+    impersonating?: boolean;
+    /** Where `mailApi.ts`'s `stopImpersonating()` should call — see `MailShell`'s original doc comment. */
+    impersonationBaseUrl?: string;
+    /** `true` when the caller's JWT carries a trusted role — shows an "Admin" item in the user menu below. */
+    trusted?: boolean;
+}
+export interface AppDef {
+    id: AppShellApp;
+    href: string;
+    label: string;
+    icon: IconType;
+}
+export declare const APPS: AppDef[];
+/** `APPS` followed by the plugins' `appRail` items (generic icon), core ids winning - see `mergePluginNavItems`. */
+export declare function appRailItems(pluginNav?: PluginNav): NavItem[];
+/**
+ * The persistent chrome shared by every webmail app (Mail, Calendar, Contacts, Tasks): a left icon rail for
+ * switching apps (full page loads — see `MailShell`'s original doc comment on this framework having no
+ * client-side router), a header with the current app's name and `UserMenu`, and the impersonation banner.
+ * Each app's own shell (e.g. `MailShell`) renders its own contextual sidebar + content as `children`, inside
+ * the area to the right of the icon rail and below the header.
+ */
+export default function AppShell({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }: PropsWithChildren<AppShellProps>): React.JSX.Element;

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

@@ -4,34 +4,60 @@ 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 { HiOutlineCalendarDays, HiOutlineClipboardDocumentList, HiOutlineEnvelope, HiOutlineUsers } from "react-icons/hi2";
+import { useEffect, useRef, useState } from "react";
+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 { 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";
+import { mergePluginNavItems } from "../../plugins/pluginNav.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 },
     { id: "contacts", href: "/contacts", label: "Contacts", icon: HiOutlineUsers },
     { 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 = {
-    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) {
+    return mergePluginNavItems(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
  * switching apps (full page loads — see `MailShell`'s original doc comment on this framework having no
@@ -39,17 +65,19 @@ const ACTIVE_LABELS = {
  * Each app's own shell (e.g. `MailShell`) renders its own contextual sidebar + content as `children`, inside
  * the area to the right of the icon rail and below the header.
  */
-export default function AppShell({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, children, }) {
+export default function AppShell({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, 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 +87,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,10 +154,13 @@ 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: [
+    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 (_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 })] }) }) }));
+                                        ].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: activeLabel }), _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.d.ts

@@ -0,0 +1,18 @@
+import React from "react";
+import { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
+/**
+ * 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 declare function sanitizeBrandingHtml(html: string): string;
+/**
+ * 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 declare function BrandingHeader({ branding }: {
+    branding: Branding | null;
+}): React.JSX.Element;
+export declare function BrandingFooter({ branding }: {
+    branding: Branding | null;
+}): React.JSX.Element;

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.d.ts

@@ -0,0 +1,51 @@
+import React from "react";
+import { PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+export interface KeyEnrollmentGateProps {
+    /** Undefined while the caller's mailbox hasn't resolved yet (or has none) - renders `children`
+     * unchanged in that case, so this component can be mounted unconditionally at a stable tree
+     * position (see this component's own doc comment for why that matters). */
+    mailboxUid?: string;
+    mailboxAddress?: string;
+    /** The mailbox's currently-published public keys (`Mailbox.keys`) - needed to unlock an
+     * already-enrolled vault (see `unlockWithPassword()`'s own signature), not just to provision a new
+     * one. Treated as empty when undefined - a mailbox with no public keys published yet has nothing to
+     * unlock, so this only affects the already-enrolled path. */
+    mailboxKeys?: PublicKey[];
+    /**
+     * `true` (default) preserves this component's original behavior: a mailbox with an existing vault
+     * but no unlocked session blocks `children` behind a full-page unlock form. Set to `false` for a
+     * mount point that shouldn't block merely because a mailbox resolved - `MailShell` does this, since
+     * unlocking is only actually required to sign/encrypt a compose, read an already-encrypted message,
+     * or change encryption settings (see `UnlockPromptProvider.tsx`'s `useUnlockPrompt()`, which those
+     * specific call sites use instead). Has no effect on first-time provisioning
+     * (`setup_password`/`enrolling`/`show_recovery_codes`), which still always blocks regardless - that
+     * only ever happens once per mailbox and is a genuine prerequisite, not the source of "unlock keeps
+     * popping up" friction this prop exists to avoid.
+     */
+    blocking?: boolean;
+    /**
+     * `true` when the caller may provision this mailbox's first encryption key - i.e. they own it and aren't
+     * an administrator impersonating them. `false` (default, so a caller that forgets it never provisions) for
+     * a shared/delegated mailbox the caller doesn't own, or an impersonated session: a mailbox with no vault yet then
+     * renders `children` instead of the "Protect your mailbox" setup, so a delegate never enrolls keys
+     * (and recovery codes) for someone else's mailbox. Unlocking an existing vault is unaffected.
+     */
+    canProvision?: boolean;
+    children: React.ReactNode;
+}
+/**
+ * Gates a mailbox's normal content behind one-time E2E encryption key setup, per
+ * `specs/end-to-end_encryption.md`'s "Generate signing and encryption keypairs on the client's device on
+ * first sign-in." Rendered by `MailShell` wrapping its own returned content unconditionally, not only
+ * once a mailbox is resolved — mounting this component at a *different* tree position depending on
+ * `mailboxUid`'s readiness (e.g. only wrapping once ready, rendering bare content beforehand) would make
+ * `children` (real `AppShell` chrome) itself remount the moment `mailboxUid` resolves, tearing down any
+ * state/effects it had already started. Always wrapping keeps `AppShell` mounted continuously across
+ * that transition; this component simply passes `children` through untouched while `mailboxUid` is
+ * still unresolved, and only starts its own check once a real `mailboxUid` is supplied.
+ *
+ * A `getKeyVault()` failure (network error, server not yet wired up to serve this endpoint) also renders
+ * `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, canProvision, children, }: KeyEnrollmentGateProps): React.JSX.Element | null;

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.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+/**
+ * Rendered by each app's shell (Mail/Calendar/Contacts/Tasks) *instead of* the normal `AppShell`
+ * chrome (icon rail, header, folder tree, ...) when the caller has no mailbox — a full-screen,
+ * 404-style takeover, not a small message nested inside the rest of the client UI, since there's
+ * nothing else in the app for a mailbox-less caller to do yet. Attempts self-service
+ * auto-provisioning — see `BaseMailboxRoute.autoProvision()`'s own doc comment in `@rapidmx/restapi`
+ * for the full contract — which is itself a no-op (a 404) unless an admin has both turned it on
+ * (`mail:auto_provision:enabled`) and configured at least one domain (`mail:domains`). Safe to render
+ * unconditionally in that place: any failure (disabled, no registered username, the identity service
+ * unreachable) just falls back to the same plain "no mailbox" message this replaces.
+ */
+export default function MailboxProvisioning(): React.JSX.Element;

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." })] }));
     }