@rapidmx/web-client 0.4.0 → 0.6.0

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

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/UnlockPromptProvider.js

@@ -1,14 +1,36 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 ///////////////////////////////////////////////////////////////////////////////
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { createContext, useCallback, useContext, useState } from "react";
-import { getUnlockedKeys, unlockWithPassword } from "@rapidmx/react-shared/crypto/keySession.js";
+import { createContext, useCallback, useContext, useRef, useState } from "react";
+import { getUnlockedKeys, unlockWithPassword, UnopenableEncryptionKeyError, } from "@rapidmx/react-shared/crypto/keySession.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";
+import { RECOVERY_CODE_ERROR, RecoveryFollowUpModal, UnlockModeToggle, startRecoveryUnlock, } from "./RecoveryCodeUnlock.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 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 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 function unlockErrorMessage(err, method = "password") {
+    // Deliberately generic otherwise - see `unlockWithPassword()`'s own doc comment: a wrong password and a
+    // missing password wrap fail the same way, and telling them apart would help someone guessing passwords.
+    if (method === "recovery") {
+        return err instanceof UnopenableEncryptionKeyError ? UNOPENABLE_ENCRYPTION_KEY_RECOVERY_MESSAGE : RECOVERY_CODE_ERROR;
+    }
+    return err instanceof UnopenableEncryptionKeyError ? UNOPENABLE_ENCRYPTION_KEY_MESSAGE : "Incorrect password.";
+}
+/**
+ * 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 function UnopenableKeysNotice({ fingerprints, onDismiss }) {
+    return (_jsxs("div", { role: "status", className: "fixed bottom-4 right-4 z-50 max-w-sm bg-surface border border-border rounded-md p-3 text-sm shadow-lg flex flex-col gap-2", children: [_jsxs("p", { children: ["Unlocked, but ", fingerprints.length === 1 ? "one of your signing keys" : `${fingerprints.length} of your signing keys`, " ", "couldn\u2019t be opened, so mail can\u2019t be signed with ", fingerprints.length === 1 ? "it" : "them", ". Contact support."] }), _jsx("p", { className: "font-mono text-xs break-all text-text-muted", children: fingerprints.join(", ") }), _jsx("div", { children: _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onDismiss, children: "Dismiss" }) })] }));
+}
 const UnlockPromptContext = createContext(null);
 /**
  * The on-demand counterpart to `KeyEnrollmentGate`'s blocking, first-sign-in-only provisioning flow.
@@ -23,23 +45,45 @@ const UnlockPromptContext = createContext(null);
  * `false` for exactly this reason.
  */
 export function UnlockPromptProvider({ children }) {
-    const [pending, setPending] = useState(null);
+    const [pending, setPendingState] = useState(null);
+    // Mirrors `pending` synchronously, so two requests issued in the same tick see each other.
+    const pendingRef = useRef(null);
     const [password, setPassword] = useState("");
     const [error, setError] = useState(null);
     const [unlocking, setUnlocking] = useState(false);
+    const [unopenableKeys, setUnopenableKeys] = useState(null);
+    const [mode, setMode] = useState("password");
+    const [code, setCode] = useState("");
+    // The steps after a recovery-code unlock (new password, using up the code). Shown only once the waiters are
+    // already settled - see `RecoveryCodeUnlock.tsx`.
+    const [followUp, setFollowUp] = useState(null);
+    function setPending(next) {
+        pendingRef.current = next;
+        setPendingState(next);
+    }
     const requestUnlock = useCallback((mailboxUid, mailboxKeys) => {
         const existing = getUnlockedKeys(mailboxUid);
         if (existing) {
             return Promise.resolve(existing);
         }
         return new Promise((resolve, reject) => {
+            const current = pendingRef.current;
+            if (current?.mailboxUid === mailboxUid) {
+                current.waiters.push({ resolve, reject });
+                return;
+            }
+            // A different mailbox's dialog is replacing this one - settle its callers rather than leaving
+            // their promises hanging forever.
+            current?.waiters.forEach((waiter) => waiter.reject(new Error("Unlock superseded by another request.")));
             setPassword("");
+            setCode("");
+            setMode("password");
             setError(null);
-            setPending({ mailboxUid, mailboxKeys, resolve, reject });
+            setPending({ mailboxUid, mailboxKeys, waiters: [{ resolve, reject }] });
         });
     }, []);
     function handleCancel() {
-        pending?.reject(new Error("Unlock cancelled."));
+        pendingRef.current?.waiters.forEach((waiter) => waiter.reject(new Error("Unlock cancelled.")));
         setPending(null);
     }
     async function handleSubmit(e) {
@@ -49,22 +93,37 @@ export function UnlockPromptProvider({ children }) {
         setError(null);
         setUnlocking(true);
         try {
-            await unlockWithPassword(request.mailboxUid, request.mailboxKeys, password);
-            // Always reachable: unlockWithPassword() just populated keySession.ts's session store for
+            const result = await (mode === "recovery"
+                ? startRecoveryUnlock(request.mailboxUid, request.mailboxKeys, code)
+                : unlockWithPassword(request.mailboxUid, request.mailboxKeys, password));
+            const recovery = mode === "recovery" ? result : null;
+            // Always reachable: the unlock just populated keySession.ts's session store for
             // this exact mailboxUid, or threw before we get here.
             const unlocked = getUnlockedKeys(request.mailboxUid);
-            request.resolve(unlocked);
-            setPending(null);
+            request.waiters.forEach((waiter) => waiter.resolve(unlocked));
+            if (pendingRef.current === request) {
+                setPending(null);
+            }
+            if (result.unopenableKeys.length > 0) {
+                setUnopenableKeys(result.unopenableKeys);
+            }
+            setCode("");
+            setFollowUp(recovery);
         }
-        catch {
-            // Deliberately generic - see KeyEnrollmentGate's identical handleUnlock() for why.
-            setError("Incorrect password.");
+        catch (err) {
+            setError(unlockErrorMessage(err, mode));
         }
         finally {
             setUnlocking(false);
         }
     }
-    return (_jsxs(UnlockPromptContext.Provider, { value: { requestUnlock }, children: [children, _jsxs(Modal, { open: !!pending, onClose: handleCancel, title: "Unlock your mailbox", children: [_jsx("p", { className: "text-sm text-text-muted mb-5", children: "Enter your encryption password to continue." }), error && _jsx(Alert, { children: error }), _jsxs("form", { onSubmit: handleSubmit, children: [_jsx(FormField, { label: "Encryption password", htmlFor: "unlock-prompt-password", children: _jsx("input", { id: "unlock-prompt-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", autoFocus: true }) }), _jsxs("div", { className: "flex gap-2", children: [_jsx(Button, { type: "submit", loading: unlocking, disabled: unlocking, children: "Unlock" }), _jsx(Button, { type: "button", variant: "secondary", onClick: handleCancel, disabled: unlocking, children: "Cancel" })] })] })] })] }));
+    function handleModeChange(next) {
+        setMode(next);
+        setError(null);
+    }
+    return (_jsxs(UnlockPromptContext.Provider, { value: { requestUnlock }, children: [children, unopenableKeys && _jsx(UnopenableKeysNotice, { fingerprints: unopenableKeys, onDismiss: () => setUnopenableKeys(null) }), followUp && (_jsx(RecoveryFollowUpModal, { followUp: followUp, open: !pending, onDone: () => setFollowUp(null) }, `${followUp.mailboxUid}:${followUp.recoveryMethodId}`)), _jsxs(Modal, { open: !!pending, onClose: handleCancel, title: "Unlock your mailbox", children: [_jsx("p", { className: "text-sm text-text-muted mb-5", children: mode === "password"
+                            ? "Enter your encryption password to continue."
+                            : "Enter one of your recovery codes to continue. Each code works once." }), error && _jsx(Alert, { children: error }), _jsxs("form", { onSubmit: handleSubmit, children: [mode === "password" ? (_jsx(FormField, { label: "Encryption password", htmlFor: "unlock-prompt-password", children: _jsx("input", { id: "unlock-prompt-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", autoFocus: true }) })) : (_jsx(FormField, { label: "Recovery code", htmlFor: "unlock-prompt-recovery-code", children: _jsx("input", { id: "unlock-prompt-recovery-code", type: "text", className: "w-full text-sm font-mono border border-border rounded-sm py-1.5 px-2 bg-surface", value: code, onChange: (e) => setCode(e.target.value), disabled: unlocking, autoComplete: "off", autoCapitalize: "characters", spellCheck: false, autoFocus: true }) })), _jsxs("div", { className: "flex gap-2", children: [_jsx(Button, { type: "submit", loading: unlocking, disabled: unlocking, children: "Unlock" }), _jsx(Button, { type: "button", variant: "secondary", onClick: handleCancel, disabled: unlocking, children: "Cancel" })] })] }), _jsx("div", { className: "mt-3", children: _jsx(UnlockModeToggle, { mode: mode, disabled: unlocking, onChange: handleModeChange }) })] })] }));
 }
 /** 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. */

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/ConversationThreadPane.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { getMessage, listAttachments, setMessageRead } from "@rapidmx/react-shared/mail/mailApi.js";
 import MessageDetailPane from "./MessageDetailPane.js";
@@ -22,16 +22,31 @@ export default function ConversationThreadPane({ conversation, folders, labels }
     const [expandedUids, setExpandedUids] = useState(new Set());
     const [loading, setLoading] = useState(false);
     const [error, setError] = useState(null);
+    // Bumped on every conversation switch - any in-flight load/attachments/mark-read response carrying an
+    // older generation belongs to a superseded conversation and is dropped rather than applied.
+    const generationRef = useRef(0);
+    // Message uids a mark-read / attachments request has already been issued for in the current
+    // generation, so re-running the effect below (every `messages`/`expandedUids` change) while one is
+    // still in flight never fires a duplicate - which for mark-read would also carry a stale `version`.
+    const markReadRequestedRef = useRef(new Set());
+    const attachmentsRequestedRef = useRef(new Set());
     useEffect(() => {
+        const generation = ++generationRef.current;
+        markReadRequestedRef.current = new Set();
+        attachmentsRequestedRef.current = new Set();
+        setMessages({});
+        setAttachmentsByUid({});
+        setExpandedUids(new Set());
         if (!conversation) {
-            setMessages({});
-            setExpandedUids(new Set());
+            setLoading(false);
             return;
         }
         setLoading(true);
         setError(null);
         Promise.all(conversation.messageUids.map((uid) => getMessage(uid)))
             .then((loaded) => {
+            if (generation !== generationRef.current)
+                return;
             setMessages(Object.fromEntries(loaded.map((m) => [m.uid, m])));
             // `messageUids` always has at least one entry — a `ConversationSummary` only ever
             // exists because it was grouped from real messages (see
@@ -39,32 +54,55 @@ export default function ConversationThreadPane({ conversation, folders, labels }
             const latestUid = conversation.messageUids[conversation.messageUids.length - 1];
             setExpandedUids(new Set([latestUid]));
         })
-            .catch((err) => setError(err instanceof ApiRequestError ? err.message : "Could not load this conversation."))
-            .finally(() => setLoading(false));
+            .catch((err) => {
+            if (generation !== generationRef.current)
+                return;
+            setError(err instanceof ApiRequestError ? err.message : "Could not load this conversation.");
+        })
+            .finally(() => {
+            if (generation === generationRef.current)
+                setLoading(false);
+        });
     }, [conversation?.conversationId]);
     // Lazily loads attachments and marks-as-read only for messages the reader has actually expanded —
     // mirrors `mailDetailHooks.ts`'s `useMessageAttachments`/`useMarkMessageRead`, reimplemented here
     // (rather than called in a loop, which the rules of hooks don't allow) since a thread can expand
     // more than one message at once, unlike the single-selected-message case those hooks were built for.
     useEffect(() => {
+        const generation = generationRef.current;
         for (const uid of expandedUids) {
             const message = messages[uid];
             if (!message)
                 continue;
-            if (message.hasAttachments && !attachmentsByUid[uid]) {
+            if (message.hasAttachments && !attachmentsRequestedRef.current.has(uid)) {
+                attachmentsRequestedRef.current.add(uid);
                 listAttachments(message.folderUid, uid)
-                    .then((loaded) => setAttachmentsByUid((prev) => ({ ...prev, [uid]: loaded })))
+                    .then((loaded) => {
+                    if (generation === generationRef.current) {
+                        setAttachmentsByUid((prev) => ({ ...prev, [uid]: loaded }));
+                    }
+                })
                     .catch(() => {
                     // Best-effort, same as the mark-as-read catch below — `attachmentsByUid[uid] ??
-                    // []` already renders no attachments while this stays unset, so there is nothing
-                    // further to do on failure.
+                    // []` already renders no attachments while this stays unset; forgetting the
+                    // request just lets a later re-expand retry it.
+                    attachmentsRequestedRef.current.delete(uid);
                 });
             }
-            if (!message.flags.read) {
+            // `message` is this render's latest copy, so the request carries its current `version`.
+            if (!message.flags.read && !markReadRequestedRef.current.has(uid)) {
+                markReadRequestedRef.current.add(uid);
                 setMessageRead(message, true)
-                    .then((updated) => setMessages((prev) => ({ ...prev, [uid]: updated })))
+                    .then((updated) => {
+                    if (generation !== generationRef.current)
+                        return;
+                    // Never clobber a newer copy another action (label/classify/...) already patched in.
+                    setMessages((prev) => (prev[uid].version > updated.version ? prev : { ...prev, [uid]: updated }));
+                })
                     .catch(() => {
-                    // Best-effort — matches `useMarkMessageRead`'s own doc comment.
+                    // Best-effort — matches `useMarkMessageRead`'s own doc comment. Forgetting the
+                    // request lets a later effect run (e.g. a re-expand) retry with a fresh copy.
+                    markReadRequestedRef.current.delete(uid);
                 });
             }
         }