@rapidmx/web-client 0.5.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

@@ -5,7 +5,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 ///////////////////////////////////////////////////////////////////////////////
 import "../../styles/app.css";
 import { useEffect, useRef, useState } from "react";
-import { HiOutlineCalendarDays, HiOutlineClipboardDocumentList, HiOutlineEnvelope, HiOutlineUsers } from "react-icons/hi2";
+import { HiOutlineCalendarDays, HiOutlineClipboardDocumentList, HiOutlineEnvelope, HiOutlinePuzzlePiece, HiOutlineUsers, } from "react-icons/hi2";
 import { useRedirectIfUnauthenticated } from "@rapidmx/react-shared/auth/session.js";
 import { getSetupStatus } from "@rapidmx/react-shared/admin/setupApi.js";
 import { stopImpersonating } from "@rapidmx/react-shared/mail/mailApi.js";
@@ -21,6 +21,7 @@ import { SIGN_OUT_CHANNEL, destroyAllLocalIndexes } from "../../search/localInde
 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;
 /**
@@ -50,15 +51,13 @@ export const APPS = [
     { 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
@@ -66,7 +65,7 @@ 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();
@@ -155,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, 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: [
+    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/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/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/RecoveryCodeUnlock.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 React from "react";
+import { type PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+/** The same minimum every other "set an encryption password" form in this app uses. */
+export declare const MIN_PASSWORD_LENGTH = 8;
+/** Where recovery codes are regenerated. */
+export declare const ENCRYPTION_SETTINGS_HREF = "/settings/encryption";
+/** Deliberately generic: a wrong code and a vault with no recovery codes fail the same way. */
+export declare const RECOVERY_CODE_ERROR = "That recovery code didn't work.";
+export declare 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 declare 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 declare 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 declare 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 declare 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 declare 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 declare const REPLACE_GENERIC_MESSAGE = "Your new password couldn't be saved. Nothing was changed. Try again.";
+export declare 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.";
+/** What a successful recovery-code unlock hands to `RecoveryFollowUpModal`. */
+export interface RecoveryFollowUp {
+    mailboxUid: string;
+    recoveryMethodId?: string;
+    /** The codes left once the used one is consumed. */
+    remainingRecoveryCodes: number;
+    /** The vault's generation read *before* the unlock - see `startRecoveryUnlock()`. */
+    expectedMasterKeyGeneration?: number;
+    unopenableKeys: string[];
+}
+/**
+ * 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 declare function startRecoveryUnlock(mailboxUid: string, mailboxKeys: PublicKey[], code: string): Promise<RecoveryFollowUp>;
+/** A "use a recovery code instead" / "use your password instead" switch for an unlock form. */
+export declare function UnlockModeToggle({ mode, disabled, onChange, }: {
+    mode: "password" | "recovery";
+    disabled: boolean;
+    onChange: (mode: "password" | "recovery") => void;
+}): React.JSX.Element;
+export interface RecoveryFollowUpModalProps {
+    followUp: RecoveryFollowUp;
+    /** `false` hides the dialog without losing its progress (e.g. while another unlock dialog is on top). */
+    open?: boolean;
+    onDone: () => void;
+}
+/**
+ * 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 declare function RecoveryFollowUpModal({ followUp, open, onDone }: RecoveryFollowUpModalProps): React.JSX.Element;

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

@@ -0,0 +1,45 @@
+import React from "react";
+import { UnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
+import type { PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+/** Shown instead of "Incorrect password" when the password was right but the mailbox's encryption key itself
+ * won't open (`UnopenableEncryptionKeyError`) - retrying can't fix that, so it must not read as a typo. */
+export declare const UNOPENABLE_ENCRYPTION_KEY_MESSAGE = "Your password is correct, but one of your keys couldn't be opened, so encrypted mail can't be read or sent from this mailbox. Trying again won't help - contact support.";
+/** `UNOPENABLE_ENCRYPTION_KEY_MESSAGE`'s counterpart for a recovery-code unlock. */
+export declare const UNOPENABLE_ENCRYPTION_KEY_RECOVERY_MESSAGE = "Your recovery code is correct, but one of your keys couldn't be opened, so encrypted mail can't be read or sent from this mailbox. Trying again won't help - contact support.";
+/** The error text for a failed `unlockWithPassword()` (or, with `method` `"recovery"`, `unlockWithRecoveryCode()`). */
+export declare function unlockErrorMessage(err: unknown, method?: "password" | "recovery"): string;
+/**
+ * A non-blocking notice after an unlock that succeeded without some signing keys (`UnlockResult.unopenableKeys`):
+ * mail can still be read, but not signed with those keys on this device.
+ */
+export declare function UnopenableKeysNotice({ fingerprints, onDismiss }: {
+    fingerprints: string[];
+    onDismiss: () => void;
+}): React.JSX.Element;
+interface UnlockPromptContextValue {
+    /**
+     * Resolves immediately with this mailbox's already-unlocked keys if it has any this session -
+     * showing no UI at all. Otherwise shows an unlock dialog on top of whatever the user is currently
+     * doing and resolves once they enter the correct password, or rejects if they dismiss it.
+     */
+    requestUnlock(mailboxUid: string, mailboxKeys: PublicKey[]): Promise<UnlockedKeys>;
+}
+/**
+ * The on-demand counterpart to `KeyEnrollmentGate`'s blocking, first-sign-in-only provisioning flow.
+ * Per `specs/end-to-end_encryption.md`, unlocking is only actually *required* to (1) sign or encrypt an
+ * outgoing message, (2) read an already-encrypted message, or (3) change encryption settings that touch
+ * the master key - not merely to have a mailbox with an existing vault resolve. Mounted once in
+ * `AppShell.tsx` (shared by every top-level app shell: Mail, Calendar, Contacts, Tasks, Settings), so
+ * any of those three call sites (`ComposeWindow`'s sign/encrypt toggles, `MessageDetailPane`'s encrypted-
+ * message view, `Settings > Encryption`) can request an unlock right where it's needed via
+ * `useUnlockPrompt()`, instead of the whole app being blocked behind an unlock screen the moment a
+ * mailbox happens to resolve - see `KeyEnrollmentGate`'s `blocking` prop, which `MailShell` now sets to
+ * `false` for exactly this reason.
+ */
+export declare function UnlockPromptProvider({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** Throws outside an `<UnlockPromptProvider>` - every app shell mounts one (see `AppShell.tsx`), so
+ * reaching this from any real page is a wiring bug, not a runtime condition to degrade gracefully from. */
+export declare function useUnlockPrompt(): UnlockPromptContextValue;
+export {};

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

@@ -0,0 +1,23 @@
+import React from "react";
+export interface UserMenuProps {
+    userUid: string;
+    /** auth-server's base URL — where the caller's own profile (name/avatar) is fetched from, if configured. */
+    authServerUrl?: string;
+    onSignOut: () => void;
+    /** Shows an "Admin" item linking to `/admin`, above "Sign Out" — pass only for a trusted-role caller. */
+    showAdminLink?: boolean;
+    /** Shows a "Settings" item, above "Admin"/"Sign Out" — an account-scoped surface (like "Admin"), not
+     * a content-scoped one, so it lives here rather than as a 5th `AppShell` rail icon. Links straight to
+     * `/settings/auto-reply`, the only settings section that exists today; repoint this at a real
+     * `/settings` landing page once a second section (Mail Filters, Signatures) makes one worth building. */
+    showSettingsLink?: boolean;
+}
+/**
+ * The top-right "who am I" menu shared by `MailShell` and `AdminShell`: an avatar-button trigger that opens a
+ * dropdown showing the caller's avatar/name, an optional "Admin" link (trusted-role callers only), and
+ * "Sign Out". Name/avatar come from auth-server's own profile endpoint (`GET /api/profiles/me`) — this
+ * service has no local user directory (see `.claude/NOTES.md`) — and fall back to the bare uid/its first
+ * letter when unset or unreachable, which is a fully valid, expected state for most password-registered
+ * accounts (only OIDC sign-in currently populates a real avatar).
+ */
+export default function UserMenu({ userUid, authServerUrl, onSignOut, showAdminLink, showSettingsLink }: UserMenuProps): React.JSX.Element;

package/dist/apps/shared/components/mail/ConversationList.d.ts

@@ -0,0 +1,11 @@
+import React from "react";
+import { ConversationSummary } from "@rapidmx/react-shared/mail/conversationsApi.js";
+export interface ConversationListProps {
+    conversations: ConversationSummary[];
+    selectedId: string | null;
+    onSelect: (conversation: ConversationSummary) => void;
+}
+/** The "By conversation" counterpart to the per-message list `apps/www/index.tsx` renders inline for
+ * "By date" — conversations are mailbox-wide (see `conversationsApi.ts`), so there's no per-folder
+ * empty/loading state to distinguish here beyond what the page itself already handles. */
+export default function ConversationList({ conversations, selectedId, onSelect }: ConversationListProps): React.JSX.Element;

package/dist/apps/shared/components/mail/ConversationThreadPane.d.ts

@@ -0,0 +1,23 @@
+import React from "react";
+import { Folder } from "@rapidmx/react-shared/mail/mailApi.js";
+import { ConversationSummary } from "@rapidmx/react-shared/mail/conversationsApi.js";
+import { Label } from "@rapidmx/react-shared/mail/labelsApi.js";
+export interface ConversationThreadPaneProps {
+    conversation: ConversationSummary | null;
+    /** The mailbox's full folder list — a conversation can span folders (e.g. an Inbox message and the
+     * Sent Items copy of its reply), so each message's own recall eligibility is looked up individually
+     * against its own `folderUid` rather than assuming one folder for the whole thread. */
+    folders: Folder[];
+    /** The mailbox's labels, fetched once by the parent (`apps/www/index.tsx`) and passed through to
+     * every expanded message's own `MessageDetailPane` — see that component's own `labels` prop. */
+    labels?: Label[];
+}
+/**
+ * The merged, Gmail-style reading pane for "By conversation" mode — every message in the conversation
+ * fetched and stacked oldest-to-newest, all but the most recent collapsed to a one-line summary
+ * (sender + subject) until clicked. Reuses `MessageDetailPane` for each *expanded* message's own
+ * header/attachments/body-iframe rendering rather than re-implementing it; a collapsed row is its own
+ * lightweight summary, since mounting a full `MessageDetailPane` (and its iframe) for every message in
+ * a long thread up front would be wasteful.
+ */
+export default function ConversationThreadPane({ conversation, folders, labels }: ConversationThreadPaneProps): React.JSX.Element;

package/dist/apps/shared/components/mail/MessageDetailPane.d.ts

@@ -0,0 +1,93 @@
+import React from "react";
+import { Attachment, Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import { Label } from "@rapidmx/react-shared/mail/labelsApi.js";
+import { MessageSecurityResult } from "@rapidmx/react-shared/crypto/messageSecurity.js";
+/** The detail line under a `verified_at_first_open` badge. */
+export declare function verifiedAtFirstOpenMessage(result: MessageSecurityResult): string;
+export interface SenderNameCheck {
+    /** The display name contains an `@` or a look-alike - it reads as (part of) an address. */
+    looksLikeAddress: boolean;
+    /** It shows an address-shaped token that isn't `actualAddress` - e.g. `"ceo@corp.com" <x@corp-pay.com>`. */
+    misleading: boolean;
+}
+/** Whether a sender's display name poses as an address, and whether that address differs from the one actually sent
+ * from. Compatibility forms are folded first (NFKC turns the fullwidth and small @ into `@`), so a look-alike can't
+ * hide the token. */
+export declare function checkSenderName(displayName: string | undefined, actualAddress: string): SenderNameCheck;
+export declare const TRUST_SIGNER_CONFLICT_MESSAGE = "A different signing key is already trusted for this sender, so this one wasn't trusted. The sender's key may have changed; confirm with them before doing anything.";
+export declare const TRUST_SIGNER_INVALID_MESSAGE = "This certificate can't be trusted for this sender.";
+export declare const TRUST_SIGNER_FORBIDDEN_MESSAGE = "You don't have permission to trust signers for this mailbox.";
+export declare const TRUST_SIGNER_GENERIC_MESSAGE = "Couldn't trust this signer. Try again.";
+export declare const KEPT_CURRENT_SIGNING_KEY_MESSAGE = "You kept the current signing key for this sender. This message stays unverified.";
+/** The error text for a failed `trustSigner()`. */
+export declare function trustSignerErrorMessage(err: unknown): string;
+/** Groups a fingerprint into 4-character blocks (`AB12 CD34 ...`), ignoring any separators it came with, so it can be
+ * read out and compared with the sender over another channel. */
+export declare function formatFingerprint(fingerprint: string): string;
+/** Decodes CSS escapes first (so an escaped `u\72l(` can't hide from the checks below), then drops every
+ * `@import` and neutralizes every `url()`/`image-set()` reference that isn't a `data:`/`cid:` URI. */
+export declare function stripRemoteCssUrls(css: string): string;
+/** Sanitizes a client-rendered body for `srcDoc`, with the CSP meta as its very first element. */
+export declare function buildSecureSrcDoc(html: string): string;
+export interface MessageDetailPaneProps {
+    message: Message | null;
+    attachments: Attachment[];
+    /** Present only on the mobile detail route — renders a "back to messages" link above the header. Absent
+     * on the desktop reading pane, which never navigates away (selecting a different message just swaps
+     * `message` in place). */
+    backHref?: string;
+    /** Whether `message` currently lives in Sent Items — the only folder recall is offered from, matching
+     * Outlook's own restriction (and `BaseMessageRoute.recall()`'s own server-side check). Each caller
+     * computes this from its own already-loaded folder list rather than this component fetching folders
+     * itself. */
+    isSentItems?: boolean;
+    /** Called with the server's updated copy (carrying `recallRequestedAt`) after a successful recall, so
+     * the caller can patch its own in-memory message/list state — mirrors `mailDetailHooks.ts`'s
+     * `useMarkMessageRead`'s identical `onUpdated` callback. */
+    onRecalled?: (updated: Message) => void;
+    /** Whether `message` currently lives in Outbox — the only folder a scheduled send can be canceled
+     * from. Each caller computes this the same way it computes `isSentItems`. */
+    isOutbox?: boolean;
+    /** The mailbox's Drafts folder uid — required when `isOutbox` is `true`, since canceling a
+     * scheduled send moves the message back into Drafts (see `cancelScheduledSend()`'s own doc comment
+     * on why clearing `scheduledSendTime` alone doesn't do that). */
+    draftsFolderUid?: string;
+    /** Called with the server's updated copy (now back in Drafts, `scheduledSendTime` cleared) after
+     * successfully canceling a scheduled send. */
+    onScheduledSendCanceled?: (updated: Message) => void;
+    /** Whether `message` currently lives in the Inbox — Focused/Other classification is an Inbox-only
+     * concept (`FocusedInboxUtils.classifyMessage()` short-circuits to Focused for every other folder), so
+     * the "Move to Other"/"Move to Focused" control below only renders here, the same
+     * each-caller-computes-its-own-folder-type pattern `isSentItems`/`isOutbox` already use. */
+    isInbox?: boolean;
+    /** Called with the server's updated copy (carrying the new `inferenceClassification`) after a
+     * successful classify — mirrors `onRecalled`'s identical shape. */
+    onClassified?: (updated: Message) => void;
+    /** Called with the server's updated copy after approving/declining a pending delivery/read receipt —
+     * mirrors `onRecalled`'s identical shape. No gating prop needed (unlike `isSentItems`/`isOutbox`/
+     * `isInbox`): `deliveryReceiptPending`/`readReceiptPending` already live directly on `message` and are
+     * only ever `true` on a real delivered copy, so the banner below is self-gating. */
+    onReceiptHandled?: (updated: Message) => void;
+    /** Called with the server's updated copy (now filed under the mailbox's Archive folder) after a
+     * successful archive — mirrors `onRecalled`'s identical shape. Archiving itself is offered for any
+     * message except one currently in Drafts or Outbox (mirrors `BaseMessageRoute.archive()`'s own
+     * server-side 400 guard); Drafts is detected via `draftsFolderUid` (already passed by every caller
+     * for the Outbox-cancel flow) rather than a new prop. */
+    onArchived?: (updated: Message) => void;
+    /** Every label defined in this message's mailbox, for the label-assignment popover below — each
+     * caller fetches its own mailbox's labels the same way it already resolves `draftsFolderUid`
+     * (`listLabels()`). Absent/empty simply hides the Labels control - there's nothing to assign. */
+    labels?: Label[];
+    /** Called with the server's updated copy (carrying the new `labelUids`) after successfully toggling
+     * a label — always patches in place, never removes from a caller's list (unlike `onArchived`):
+     * changing labels never moves a message between folders. */
+    onLabelsChanged?: (updated: Message) => void;
+}
+/**
+ * A message's reading pane — header (subject/from/to/attachments) plus a sandboxed iframe for the body.
+ * Shared by the desktop inline pane (`apps/www/index.tsx`, always visible alongside the message list),
+ * the mobile detail route (`apps/www/messages/[uid].tsx`, a full page on its own reached by tapping
+ * a message row), and `ConversationThreadPane` (one per expanded message in a thread) — see each call
+ * site for how `message`/`attachments`/`isSentItems` are sourced.
+ */
+export default function MessageDetailPane(props: MessageDetailPaneProps): React.JSX.Element;

package/dist/apps/shared/components/mail/compose/ComposeContext.d.ts

@@ -0,0 +1,58 @@
+import React, { PropsWithChildren } from "react";
+export interface ComposeSession {
+    id: string;
+    /** The initial sending mailbox - absent means "the caller's own mailbox" (see `ComposeWindow`). */
+    mailboxUid?: string;
+    initialTo?: string;
+    initialCc?: string;
+    initialSubject?: string;
+    /** Pre-built HTML (already includes its own quote-attribution wrapper — see `composeQuoting.ts`)
+     * inserted below the resolved default signature. Absent for a fresh, non-reply/forward compose. */
+    initialQuotedHtml?: string;
+    /** Which of a signature's two "default" flags to resolve against — `"new"` (the default) uses
+     * `isDefaultForNewMessages`, `"reply_forward"` uses `isDefaultForReplyForward`. */
+    signatureContext: "new" | "reply_forward";
+    /** See `OpenComposeInput.suppressSigning`'s own doc comment. */
+    suppressSigning?: boolean;
+    minimized: boolean;
+}
+export interface OpenComposeInput {
+    /** The sending mailbox to start with. Omit for a fresh message (defaults to the caller's own mailbox);
+     * a reply/forward passes the original message's mailbox so a shared mailbox's mail replies from it.
+     * Either way the user can change it via the compose window's From field. */
+    mailboxUid?: string;
+    /** Prefills the To field — e.g. Contacts' "Email" toolbar action, or Reply/Reply All/Forward. */
+    to?: string;
+    /** Prefills the Cc field and reveals the Cc/Bcc row — Reply All only. */
+    cc?: string;
+    /** Prefills the Subject field — Reply/Reply All/Forward. */
+    subject?: string;
+    /** See `ComposeSession.initialQuotedHtml`'s own doc comment. */
+    quotedHtml?: string;
+    /** See `ComposeSession.signatureContext`'s own doc comment. Defaults to `"new"` — every existing
+     * caller (Contacts' "Email" action, the folder-sidebar "Compose" button) is a fresh compose. */
+    signatureContext?: "new" | "reply_forward";
+    /** `true` when the caller (`MessageDetailPane.tsx`'s Reply/Reply All) has already determined, via
+     * `composeSecurity.ts`'s `isLikelyMailingList()`, that the message being replied to came from a
+     * mailing list — a list that appends a footer after signing invalidates the signature (spec's own
+     * "Mailing lists" note), so the new compose window defaults its Sign toggle off rather than on.
+     * The user can still turn it back on manually; this only changes the *default*. */
+    suppressSigning?: boolean;
+}
+export interface ComposeContextValue {
+    /** Opens a new compose window, stacked alongside any already open (Gmail allows several at once). */
+    openCompose: (input: OpenComposeInput) => void;
+}
+/** Opens the floating Compose window from anywhere inside `AppShell` (any of the four webmail apps). */
+export declare function useCompose(): ComposeContextValue;
+/**
+ * Owns every currently-open Compose window and renders them stacked bottom-right, Gmail-style — see
+ * `ComposeWindow`'s own doc comment for why this replaced the old dedicated `/compose` page. Mounted
+ * once in `AppShell`, so every webmail app (Mail/Calendar/Contacts/Tasks) shares the same instance:
+ * opening Compose from Contacts' "Email" action, for instance, overlays the window on top of whatever
+ * app is currently showing, exactly like opening it from Mail's own sidebar button.
+ */
+export default function ComposeProvider({ children, userUid, trusted }: PropsWithChildren<{
+    userUid?: string;
+    trusted?: boolean;
+}>): React.JSX.Element;

package/dist/apps/shared/components/mail/compose/ComposeToolbar.d.ts

@@ -0,0 +1,15 @@
+import React from "react";
+import type { Editor } from "@tiptap/react";
+export interface ComposeToolbarProps {
+    /** `null` before the editor has mounted client-side (see `RichTextEditor`'s `immediatelyRender: false`
+     * doc comment) — every button is disabled in that state rather than the toolbar rendering nothing, so
+     * its layout doesn't shift the instant the editor becomes ready. */
+    editor: Editor | null;
+    /** Uploads `file` as an attachment on the current draft and resolves to a URL the browser can
+     * preview it at while composing — see `BaseMailComposeRoute.rewriteInlineImageSources()`'s doc
+     * comment for why that's not the final URL the message actually ships with. Resolves to `null`
+     * (rather than rejecting) on failure — `ComposeWindow`'s own implementation is responsible for
+     * surfacing the error itself, so a failed upload here just quietly doesn't insert an image. */
+    onUploadImage: (file: File) => Promise<string | null>;
+}
+export default function ComposeToolbar({ editor, onUploadImage }: ComposeToolbarProps): React.JSX.Element;

package/dist/apps/shared/components/mail/compose/ComposeWindow.d.ts

@@ -0,0 +1,37 @@
+import React from "react";
+import type { ComposeSession } from "./ComposeContext.js";
+export interface ComposeWindowProps {
+    session: ComposeSession;
+    onClose: () => void;
+    onToggleMinimize: () => void;
+    /** The signed-in user - identifies their own ("primary") mailbox, the default From when the session
+     * doesn't name a mailbox. */
+    userUid?: string;
+    /** The caller holds a trusted (admin) role - every mailbox is writable, so no per-mailbox access checks. */
+    trusted?: boolean;
+    /** How long (ms) after the last edit the draft is autosaved. Defaults to `DEFAULT_AUTOSAVE_DELAY_MS`;
+     * only overridden by tests. */
+    autosaveDelayMs?: number;
+    /** Backoff (ms) between automatic retries of a failed mailbox/encryption-policy load, one entry per retry.
+     * Defaults to `DEFAULT_CRYPTO_RETRY_DELAYS_MS`; only overridden by tests. */
+    cryptoRetryDelaysMs?: number[];
+}
+/** Debounce between the last edit and the draft autosave. */
+export declare const DEFAULT_AUTOSAVE_DELAY_MS = 2000;
+/** Automatic retries of a failed mailbox/encryption-policy load; after the last one only "Retry" tries again. */
+export declare const DEFAULT_CRYPTO_RETRY_DELAYS_MS: number[];
+/**
+ * A floating, Gmail-style compose window — overlays whatever app is currently showing instead of
+ * navigating to a dedicated page (see `ComposeContext.tsx`'s doc comment for why: a full-page compose
+ * form meant losing your place in the inbox/calendar/contacts view behind it, and every navigation to
+ * `/compose` re-ran this whole app's full mailbox/folder resolution waterfall from scratch). Owns its
+ * own draft lifecycle end to end (unlike the old page, which read the Drafts folder from `MailShell`'s
+ * context — this window can be opened from apps that never mount `MailShell` at all, e.g. Contacts'
+ * "Email" action, so it resolves its own Drafts folder from just a `mailboxUid`).
+ *
+ * Below the `md` breakpoint, a non-minimized session instead renders as a full-screen sheet (there's no
+ * room for a floating window, and the click-drag resize handles below become meaningless full-screen) —
+ * see `ComposeContext.tsx`'s own doc comment for how that interacts with several sessions being open at
+ * once.
+ */
+export default function ComposeWindow({ session, onClose, onToggleMinimize, userUid, trusted, autosaveDelayMs, cryptoRetryDelaysMs, }: ComposeWindowProps): React.JSX.Element;

package/dist/apps/shared/components/mail/compose/EmojiPicker.d.ts

@@ -0,0 +1,14 @@
+import React, { RefObject } from "react";
+export interface EmojiPickerProps {
+    anchorRef: RefObject<HTMLElement | null>;
+    onSelect: (native: string) => void;
+    onClose: () => void;
+}
+/**
+ * "Insert emoji" popup — a scrollable grid of every standard unicode emoji, grouped by category (see
+ * `emojiData.ts`). Deliberately no search box, unlike `GifPicker`'s — the user's own request only
+ * asked for a browsable grid here, and 8 category headers over ~1900 emojis is already a reasonably
+ * navigable amount without one. Rendered via `PopoverPortal` — see that component's own doc comment
+ * on why (escaping the toolbar's `overflow-hidden` ancestors).
+ */
+export default function EmojiPicker({ anchorRef, onSelect, onClose }: EmojiPickerProps): React.JSX.Element;