@rapidmx/web-client 0.4.0 → 0.6.0

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;

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

@@ -0,0 +1,13 @@
+import React, { RefObject } from "react";
+export interface GifPickerProps {
+    anchorRef: RefObject<HTMLElement | null>;
+    onSelect: (url: string) => void;
+    onClose: () => void;
+}
+/** "Insert GIF" popup — a search box plus a scrollable grid of Giphy thumbnails (trending by default,
+ * live-searched as the user types). Selecting one inserts its full-resolution URL into the message
+ * body — see `ComposeToolbar.tsx`'s own doc comment on why that's a plain `<img>` reference rather
+ * than an uploaded attachment (unlike "Insert image"): a GIF is already hosted at a stable public
+ * URL, so there's nothing to upload. Rendered via `PopoverPortal` — see that component's own doc
+ * comment on why (escaping the toolbar's `overflow-hidden` ancestors). */
+export default function GifPicker({ anchorRef, onSelect, onClose }: GifPickerProps): React.JSX.Element;

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

@@ -0,0 +1,34 @@
+import React from "react";
+export interface RichTextEditorProps {
+    value: string;
+    onChange: (value: string) => void;
+    height?: string;
+    /** When true, the editor fills its parent's height via flexbox instead of a fixed `height` — for
+     * embedding inside a flex-column container of variable height (the floating Compose window) where
+     * a literal pixel height can't be computed up front. `height` is ignored when this is set. */
+    fill?: boolean;
+    /** Passed straight through to `ComposeToolbar` — see its own doc comment on this prop. */
+    onUploadImage: (file: File) => Promise<string | null>;
+}
+/**
+ * A WYSIWYG rich-text editor for the Compose window's message body — replaces `MonacoHtmlEditor` (an HTML
+ * *source* editor) with a real Outlook-Home-tab-style formatting experience, built on TipTap/ProseMirror.
+ * Used by `ComposeWindow` (the floating overlay, not a dedicated page — see `ComposeContext.tsx`'s doc
+ * comment).
+ *
+ * `value` seeds the editor's initial content only — like `MonacoHtmlEditor`, this never re-syncs from a
+ * later `value` prop change; TipTap owns its own document once created. Live edits flow out as HTML (via
+ * `editor.getHTML()`) through `onChange`.
+ *
+ * `immediatelyRender: false` is required for this framework's SSR: the page embedding `ComposeWindow` is
+ * rendered server-side under plain Node before hydration (see `ReactRoute`), and TipTap's default
+ * (`immediatelyRender: true`) tries to mount its ProseMirror view during that very first render, which
+ * both can't work without a real DOM and produces a hydration mismatch. With it `false`, `useEditor`
+ * returns `null` until the editor actually mounts client-side after hydration — `ComposeToolbar`/
+ * `EditorContent` both already handle a `null` editor by rendering their disabled/empty state, so this
+ * needs no extra loading-placeholder logic here. Unlike `MonacoHtmlEditor`, no dynamic `import()` is
+ * needed to defer loading TipTap's modules off the SSR path — `immediatelyRender: false` alone is
+ * sufficient here since TipTap (unlike Monaco) never touches the DOM at module-evaluation time, only when
+ * an editor view actually mounts.
+ */
+export default function RichTextEditor({ value, onChange, height, fill, onUploadImage }: RichTextEditorProps): React.JSX.Element;

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

@@ -0,0 +1,16 @@
+import React, { RefObject } from "react";
+export interface ScheduleSendPickerProps {
+    anchorRef: RefObject<HTMLElement | null>;
+    onClose: () => void;
+    /** Called with the chosen instant as a UTC ISO string, already validated to be in the future. */
+    onSchedule: (scheduledSendTimeIso: string) => void;
+}
+/**
+ * The "Send later" popover next to Compose's Send button — same `PopoverPortal` shell
+ * `EmojiPicker`/`GifPicker`/`ResourcePicker` already use, just holding a single `datetime-local` input
+ * instead of a grid/list. Validates the chosen time is genuinely in the future before calling
+ * `onSchedule` — `@rapidmx/restapi`'s own `send()` only defers when `scheduledSendTime` is strictly
+ * later than "now", so a past/immediate pick here would silently send right away instead of scheduling,
+ * which would surprise a reader expecting the picker's own choice to be honored.
+ */
+export default function ScheduleSendPicker({ anchorRef, onClose, onSchedule }: ScheduleSendPickerProps): React.JSX.Element;

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

@@ -0,0 +1,27 @@
+/** Saves a compose window's unsaved edits (or waits for a save already on the wire), resolving to `false` when
+ * something the window holds is still unsaved afterwards (any other value counts as saved). Never rejects. */
+export type ComposeFlush = () => Promise<unknown>;
+/**
+ * Marks the app as signing out (explicitly, or forced by a sign-out in another tab), so compose windows stop
+ * asking the browser to confirm leaving the page - the "Leave site?" prompt would otherwise let the user cancel
+ * the sign-out's own navigation and stay on a page whose session is being ended. Call it before flushing drafts
+ * and navigating. `clearSigningOut()` undoes it (a sign-out that didn't leave the page after all).
+ */
+export declare function markSigningOut(): void;
+/** Undoes `markSigningOut()`. */
+export declare function clearSigningOut(): void;
+/** Whether `markSigningOut()` has been called (and not cleared). */
+export declare function isSigningOut(): boolean;
+/**
+ * Registers an open compose window's draft flush, so leaving the app on purpose (Sign Out) can save the
+ * last edits still waiting on the autosave debounce before the session ends. Returns the unregister
+ * function. Module-level rather than React context: `AppShell` (the sign-out handler) renders the
+ * `ComposeProvider` itself, so it can't read that provider's context.
+ */
+export declare function registerComposeFlush(flush: ComposeFlush): () => void;
+/**
+ * Runs every registered flush and waits for all of them, but no longer than `timeoutMs`. Resolves to `true`
+ * only when every window reported its content saved in time (a window whose save failed also shows the user
+ * why, with Discard / Keep editing). Never rejects.
+ */
+export declare function flushComposeDrafts(timeoutMs: number): Promise<boolean>;

package/dist/apps/shared/components/mail/compose/composeFlushRegistry.js

@@ -0,0 +1,50 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+const flushers = new Set();
+let signingOut = false;
+/**
+ * Marks the app as signing out (explicitly, or forced by a sign-out in another tab), so compose windows stop
+ * asking the browser to confirm leaving the page - the "Leave site?" prompt would otherwise let the user cancel
+ * the sign-out's own navigation and stay on a page whose session is being ended. Call it before flushing drafts
+ * and navigating. `clearSigningOut()` undoes it (a sign-out that didn't leave the page after all).
+ */
+export function markSigningOut() {
+    signingOut = true;
+}
+/** Undoes `markSigningOut()`. */
+export function clearSigningOut() {
+    signingOut = false;
+}
+/** Whether `markSigningOut()` has been called (and not cleared). */
+export function isSigningOut() {
+    return signingOut;
+}
+/**
+ * Registers an open compose window's draft flush, so leaving the app on purpose (Sign Out) can save the
+ * last edits still waiting on the autosave debounce before the session ends. Returns the unregister
+ * function. Module-level rather than React context: `AppShell` (the sign-out handler) renders the
+ * `ComposeProvider` itself, so it can't read that provider's context.
+ */
+export function registerComposeFlush(flush) {
+    flushers.add(flush);
+    return () => {
+        flushers.delete(flush);
+    };
+}
+/**
+ * Runs every registered flush and waits for all of them, but no longer than `timeoutMs`. Resolves to `true`
+ * only when every window reported its content saved in time (a window whose save failed also shows the user
+ * why, with Discard / Keep editing). Never rejects.
+ */
+export async function flushComposeDrafts(timeoutMs) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), timeoutMs);
+    });
+    const all = Promise.all([...flushers].map((flush) => flush().catch(() => false))).then((results) => results.every((result) => result !== false));
+    const saved = await Promise.race([all, timeout]);
+    clearTimeout(timer);
+    return saved;
+}

package/dist/apps/shared/components/mail/layout/MailShell.d.ts

@@ -0,0 +1,57 @@
+import React, { PropsWithChildren } from "react";
+import { Folder, Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
+import { AppShellProps } from "../../layout/AppShell.js";
+export type MailShellProps = Omit<AppShellProps, "active">;
+/** One mailbox's own mail folders (already filtered to `MAIL_FOLDER_TYPES` and unsorted) - one entry per
+ * mailbox in `mailboxes`, fetched in parallel so every accessible mailbox's folder tree can render
+ * simultaneously (see `MailShell`'s own doc comment on why this replaced the old single-mailbox `folders`
+ * field). `error` is set (and `folders` left empty) for a mailbox whose own `listFolders()` call failed -
+ * one mailbox's fetch failure must never blank out every other mailbox's section. */
+export interface MailboxFolders {
+    mailbox: Mailbox;
+    folders: Folder[];
+    error?: string;
+}
+/** The well-known mail folder types an "aggregate" pseudo-folder can merge across every accessible
+ * mailbox - a fixed, small set: `outbox` is deliberately excluded (transient per-mailbox send-queue
+ * state, not a "merge across mailboxes" concept), and there's no aggregate concept for `calendar`/
+ * `contacts`/`tasks`/`notes`/`user` folders (Mail's own sidebar already excludes those - see
+ * `MAIL_FOLDER_TYPES`). */
+export declare const AGGREGATE_FOLDER_TYPES: readonly ["inbox", "sent_items", "drafts", "deleted_items", "junk"];
+export type AggregateFolderType = (typeof AGGREGATE_FOLDER_TYPES)[number];
+export interface MailShellContextValue {
+    /** The mailbox currently selected (`?mailboxUid=`) - `undefined` while an aggregate pseudo-folder is
+     * active instead (`aggregateFolderType` set), since there's no single mailbox to speak of then. */
+    mailboxUid?: string;
+    /** The folder currently selected (`?folderUid=`, or the selected mailbox's Inbox) - `undefined` in
+     * aggregate mode, for the same reason. */
+    folderUid?: string;
+    /** Set only when an aggregate pseudo-folder (`?aggregate=inbox` etc.) is selected instead of a real,
+     * single mailbox+folder - mutually exclusive with `mailboxUid`/`folderUid` above. */
+    aggregateFolderType?: AggregateFolderType;
+    mailboxes: Mailbox[];
+    /** Every accessible mailbox's own mail folders - replaces the old single-mailbox `folders: Folder[]`
+     * now that every mailbox's tree renders at once (see `MailboxFolders`'s own doc comment). */
+    mailboxFolders: MailboxFolders[];
+}
+/** Reads the mailbox/folder a page is currently showing, as resolved by the enclosing `MailShell`. */
+export declare function useMailShell(): MailShellContextValue;
+/** Page size of the one `listMailboxes()` call this shell makes. */
+export declare const MAILBOX_LIST_LIMIT = 100;
+/**
+ * Mail's own contextual sidebar (every accessible mailbox's own folder tree, plus a merged "All Mailboxes"
+ * aggregate section) + content area, rendered inside the shared `AppShell` chrome (icon rail, header,
+ * impersonation banner — see that component). There is no client-side router in this framework (see
+ * `ReactRoute`'s file-convention resolver) — the selected mailbox/folder (or aggregate pseudo-folder) live
+ * in the URL's `?mailboxUid=`/`?folderUid=`/`?aggregate=` query params, read once on mount (never during
+ * the initial render itself, matching every other query-param reader in this codebase — e.g.
+ * `apps/admin/quarantine`'s `readMailboxUid()` — so the server-rendered and just-hydrated client markup
+ * match).
+ *
+ * Every accessible mailbox's folder tree renders at once - there is no "switch mailbox" affordance
+ * anymore (the mailbox `<select>` this shell used to have is gone) - so a single-mailbox user sees zero
+ * behavior change from before this, and a multi-mailbox user sees every mailbox's folders (and the new
+ * aggregate section) simultaneously, matching the shared-mailbox feature's own "display as a separate set
+ * of folders" requirement.
+ */
+export default function MailShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }: PropsWithChildren<MailShellProps>): React.JSX.Element;

package/dist/apps/shared/components/mail/layout/MailShell.js

@@ -57,6 +57,8 @@ function sortedFoldersOf(folders) {
 function aggregateUnreadCount(mailboxFolders, type) {
     return mailboxFolders.reduce((total, mf) => total + (mf.folders.find((f) => f.type === type)?.unreadCount ?? 0), 0);
 }
+/** Page size of the one `listMailboxes()` call this shell makes. */
+export const MAILBOX_LIST_LIMIT = 100;
 /**
  * A separate component (not inlined into `MailShell`'s own render) so `useCompose()` resolves against
  * `ComposeProvider` correctly: that provider is rendered *inside* the `AppShell` that `MailShell` itself
@@ -88,7 +90,7 @@ function ComposeButton() {
  * aggregate section) simultaneously, matching the shared-mailbox feature's own "display as a separate set
  * of folders" requirement.
  */
-export default function MailShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, children, }) {
+export default function MailShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }) {
     const [status, setStatus] = useState("checking");
     const [error, setError] = useState(null);
     const [mailboxes, setMailboxes] = useState([]);
@@ -108,7 +110,7 @@ export default function MailShell({ userUid, authServerUrl, impersonating, imper
         if (!userUid) {
             return;
         }
-        listMailboxes({ limit: 100 })
+        listMailboxes({ limit: MAILBOX_LIST_LIMIT })
             .then((result) => {
             setMailboxes(result);
             setStatus("ready");
@@ -138,7 +140,7 @@ export default function MailShell({ userUid, authServerUrl, impersonating, imper
             return;
         }
         setFoldersLoading(true);
-        Promise.all(mailboxes.map((mailbox) => listFolders(mailbox.uid)
+        void Promise.all(mailboxes.map((mailbox) => listFolders(mailbox.uid)
             .then((result) => ({ mailbox, folders: result.filter((f) => MAIL_FOLDER_TYPES.has(f.type)) }))
             .catch((err) => ({
             mailbox,
@@ -210,5 +212,12 @@ export default function MailShell({ userUid, authServerUrl, impersonating, imper
         // (ComposeWindow, MessageDetailPane) request an unlock on demand via useUnlockPrompt() instead.
         // First-time provisioning (a mailbox with no vault at all yet) still always blocks - see this
         // prop's own doc comment on KeyEnrollmentGateProps.
-        blocking: false, children: [_jsx(LocalIndexLifecycle, { mailboxUid: activeMailboxUid, mailboxKeys: activeMailbox?.keys, folders: mailboxFolders.find((mf) => mf.mailbox.uid === activeMailboxUid)?.folders ?? [] }), _jsx(AppShell, { active: "mail", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, children: inner })] }));
+        blocking: false, 
+        // A shared/delegated mailbox the caller doesn't own is never provisioned from here - its keys
+        // belong to its owner (or its admins), not to whoever happens to open it first - and neither is
+        // the impersonated user's own mailbox: an administrator must never choose its password/recovery codes.
+        canProvision: !impersonating && activeMailbox?.ownerUserUid === userUid, children: [_jsx(LocalIndexLifecycle, { mailboxUid: activeMailboxUid, mailboxKeys: activeMailbox?.keys, folders: mailboxFolders.find((mf) => mf.mailbox.uid === activeMailboxUid)?.folders ?? [], 
+                // A full page may be truncated - pruning against it would delete indexes of accessible mailboxes
+                // beyond the limit, so it's only trusted as the complete list when it came back short.
+                accessibleMailboxUids: status === "ready" && mailboxes.length < MAILBOX_LIST_LIMIT ? mailboxes.map((mb) => mb.uid) : undefined }), _jsx(AppShell, { active: "mail", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, pluginNav: pluginNav, children: inner })] }));
 }

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

@@ -0,0 +1,33 @@
+/**
+ * The trusted signing-key fingerprints for a received message's sender, for `evaluateMessageSecurity()`'s
+ * `pinnedSignerFingerprints`: the keys key discovery already pinned on the contacts in the reading mailbox's own
+ * contacts folder(s). Reads only stored contacts - never triggers a Discovery lookup, which must not happen on
+ * message receipt.
+ *
+ * `MessageDetailPane` renders once per opened message (and once per message in a thread), so each mailbox's
+ * contact list is fetched once and reused for `CONTACTS_CACHE_TTL_MS`; a failed load isn't cached. Any failure
+ * leaves the caller with no pins, which `evaluateMessageSecurity()` reports as an unverified signer - never as
+ * verified.
+ *
+ * The cache is dropped (`clearPinnedSignerCache()`) whenever a key session locks (subscribed on first use), on sign-out
+ * (`AppShell`), and after the reader adds, edits or deletes contacts (the contacts pages) - so a contact removed
+ * because its key was revoked doesn't keep vouching for signatures until the TTL runs out.
+ */
+import { SignerKeyState } from "@rapidmx/react-shared/contacts/contactsApi.js";
+/** How long one mailbox's loaded contact list is reused before it is fetched again. */
+export declare const CONTACTS_CACHE_TTL_MS = 60000;
+/** Forgets every cached contact list - on sign-out, a key-session lock, after the reader changes their contacts, and
+ * in tests. */
+export declare function clearPinnedSignerCache(): void;
+/** The sender `address`'s pinned signing fingerprints from `mailboxUid`'s contacts. Rejects if they can't be loaded. */
+export declare function getPinnedSignerFingerprints(mailboxUid: string, address: string): Promise<string[]>;
+/** A sender's signing-key state (`signerKeyStateFor()`) plus what a key-changed notice needs to show and link. */
+export interface SenderKeyState extends SignerKeyState {
+    /** The contact holding the first pinned signing key, else the one holding the conflict, else the first match. */
+    contactUid?: string;
+    /** When the first pinned signing key started being trusted - see `keyPinnedSince()`. */
+    pinnedSince?: number;
+}
+/** The sender `address`'s signing-key state from `mailboxUid`'s (cached) contacts, for a "signing key changed" comparison
+ * or to spot a recorded conflict. Reads stored contacts only. Rejects if they can't be loaded. */
+export declare function getSignerKeyState(mailboxUid: string, address: string): Promise<SenderKeyState>;

package/dist/apps/shared/components/mail/pinnedSigners.js

@@ -0,0 +1,98 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The trusted signing-key fingerprints for a received message's sender, for `evaluateMessageSecurity()`'s
+ * `pinnedSignerFingerprints`: the keys key discovery already pinned on the contacts in the reading mailbox's own
+ * contacts folder(s). Reads only stored contacts - never triggers a Discovery lookup, which must not happen on
+ * message receipt.
+ *
+ * `MessageDetailPane` renders once per opened message (and once per message in a thread), so each mailbox's
+ * contact list is fetched once and reused for `CONTACTS_CACHE_TTL_MS`; a failed load isn't cached. Any failure
+ * leaves the caller with no pins, which `evaluateMessageSecurity()` reports as an unverified signer - never as
+ * verified.
+ *
+ * The cache is dropped (`clearPinnedSignerCache()`) whenever a key session locks (subscribed on first use), on sign-out
+ * (`AppShell`), and after the reader adds, edits or deletes contacts (the contacts pages) - so a contact removed
+ * because its key was revoked doesn't keep vouching for signatures until the TTL runs out.
+ */
+import { PINNED_FINGERPRINT_MAX_PAGES, PINNED_FINGERPRINT_PAGE_SIZE, listContacts, pinnedSigningFingerprintsFor, signerKeyStateFor, } from "@rapidmx/react-shared/contacts/contactsApi.js";
+import { keyPinnedSince } from "../contacts/contactKeys.js";
+import { listFolders } from "@rapidmx/react-shared/mail/mailApi.js";
+import { subscribeKeySession } from "@rapidmx/react-shared/crypto/keySession.js";
+/** How long one mailbox's loaded contact list is reused before it is fetched again. */
+export const CONTACTS_CACHE_TTL_MS = 60000;
+const contactsCache = new Map();
+/** Forgets every cached contact list - on sign-out, a key-session lock, after the reader changes their contacts, and
+ * in tests. */
+export function clearPinnedSignerCache() {
+    contactsCache.clear();
+}
+let lockSubscribed = false;
+/** Subscribes (once, lazily - a module-level subscription would run in every page that merely imports this) to key
+ * session changes, clearing the cache whenever any mailbox's keys are locked. */
+function subscribeToLocksOnce() {
+    if (lockSubscribed) {
+        return;
+    }
+    lockSubscribed = true;
+    subscribeKeySession((event) => {
+        if (event.state === "locked") {
+            clearPinnedSignerCache();
+        }
+    });
+}
+async function loadMailboxContacts(mailboxUid) {
+    const folders = await listFolders(mailboxUid);
+    const contacts = [];
+    for (const folder of folders.filter((f) => f.type === "contacts")) {
+        for (let page = 0; page < PINNED_FINGERPRINT_MAX_PAGES; page++) {
+            const batch = await listContacts(folder.uid, { limit: PINNED_FINGERPRINT_PAGE_SIZE, page });
+            contacts.push(...batch);
+            if (batch.length < PINNED_FINGERPRINT_PAGE_SIZE) {
+                break;
+            }
+        }
+    }
+    return contacts;
+}
+/** `mailboxUid`'s contacts, from the cache when fresh. Rejects if they can't be loaded. */
+function cachedMailboxContacts(mailboxUid) {
+    subscribeToLocksOnce();
+    let entry = contactsCache.get(mailboxUid);
+    if (!entry || Date.now() - entry.loadedAt > CONTACTS_CACHE_TTL_MS) {
+        const created = { loadedAt: Date.now(), contacts: loadMailboxContacts(mailboxUid) };
+        contactsCache.set(mailboxUid, created);
+        created.contacts.catch(() => {
+            if (contactsCache.get(mailboxUid) === created) {
+                contactsCache.delete(mailboxUid);
+            }
+        });
+        entry = created;
+    }
+    return entry.contacts;
+}
+/** The sender `address`'s pinned signing fingerprints from `mailboxUid`'s contacts. Rejects if they can't be loaded. */
+export async function getPinnedSignerFingerprints(mailboxUid, address) {
+    return pinnedSigningFingerprintsFor(await cachedMailboxContacts(mailboxUid), address);
+}
+/** The sender `address`'s signing-key state from `mailboxUid`'s (cached) contacts, for a "signing key changed" comparison
+ * or to spot a recorded conflict. Reads stored contacts only. Rejects if they can't be loaded. */
+export async function getSignerKeyState(mailboxUid, address) {
+    const contacts = await cachedMailboxContacts(mailboxUid);
+    const state = signerKeyStateFor(contacts, address);
+    const wanted = address.trim().toLowerCase();
+    const matching = contacts.filter((contact) => contact.emails.some((email) => email.address.trim().toLowerCase() === wanted));
+    // `signerKeyStateFor()` keeps the contacts' own key objects, so the holder is found by identity.
+    const pinned = state.pinned[0];
+    const holder = matching.find((candidate) => (candidate.keys ?? []).includes(pinned));
+    const contact = holder ??
+        matching.find((candidate) => (candidate.keyConflicts ?? []).some((conflict) => conflict.useType === "sign")) ??
+        matching[0];
+    return {
+        ...state,
+        ...(contact ? { contactUid: contact.uid } : {}),
+        ...(holder ? { pinnedSince: keyPinnedSince(holder, pinned) } : {}),
+    };
+}

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

@@ -0,0 +1,22 @@
+import { type Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { SealToWrite } from "@rapidmx/react-shared/crypto/messageSecurity.js";
+/** How long one mailbox's vault generation is reused before it is read again. */
+export declare const VAULT_GENERATION_TTL_MS = 60000;
+/** Forgets the cached vault generations and this session's seal writes - in tests. */
+export declare function clearVerificationSealCache(): void;
+/** Reads `mailboxUid`'s current vault `masterKeyGeneration`, uncached: `undefined` when the vault can't be read or
+ * reports none. Never rejects. */
+export declare function readVaultGeneration(mailboxUid: string): Promise<number | undefined>;
+/** `mailboxUid`'s current vault `masterKeyGeneration`, or `undefined` when it can't be read. Never rejects. */
+export declare function getVaultGeneration(mailboxUid: string): Promise<number | undefined>;
+/** The seal to check `message` against: the one this session stored for it when that is newer than the message's own
+ * copy (which may predate the write), else the message's `verificationSeal`/`verificationSealGeneration`. */
+export declare function currentVerificationSeal(message: Pick<Message, "uid" | "verificationSeal" | "verificationSealGeneration">): {
+    seal?: string;
+    sealGeneration?: number;
+};
+/** Whether `sendVerificationSeal()` would still send a seal for `messageUid` at `generation`. */
+export declare function verificationSealPending(messageUid: string, generation: number): boolean;
+/** Stores `sealToWrite` on `messageUid`, best effort - see this module's doc comment. Resolves `true` when a request was
+ * sent, `false` when the write was skipped as already attempted. Never rejects. */
+export declare function sendVerificationSeal(messageUid: string, sealToWrite: SealToWrite): Promise<boolean>;

package/dist/apps/shared/components/mail/verificationSeals.js

@@ -0,0 +1,112 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The web client's side of verification seals (`@rapidmx/react-shared`'s `crypto/verificationSeal.ts`): the vault's
+ * current `masterKeyGeneration` a seal is checked and written under, and best-effort seal writes.
+ *
+ * **Vault generation.** `getVaultGeneration()` reads `KeyVault.masterKeyGeneration` once per mailbox and reuses it for
+ * `VAULT_GENERATION_TTL_MS`; a failed read isn't cached. A vault that doesn't report a non-negative integer generation
+ * (a server predating it) counts as unavailable, and callers then evaluate without seals at all. The cache is dropped
+ * whenever a key session locks (subscribed on first use), so a rekey followed by a re-unlock is picked up.
+ *
+ * **Writes.** `sendVerificationSeal()` stores `sealToWrite` with `setMessageVerificationSeal()` and never rejects. Each
+ * message is written at most once per master key generation per page session - a seal carries the time it was built,
+ * so every evaluation of the same message produces a different one, and sending each would only draw 409s. A `409`
+ * (the server kept its seal), `400`, `403` or `404` is final; any other failure (a network error) lets a later
+ * evaluation try again, never a retry loop. A stored seal is remembered (`currentVerificationSeal()`) so a message
+ * reopened before its list copy is refreshed opens that seal instead of building another.
+ */
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { getKeyVault } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+import { subscribeKeySession } from "@rapidmx/react-shared/crypto/keySession.js";
+import { setMessageVerificationSeal } from "@rapidmx/react-shared/mail/mailApi.js";
+/** How long one mailbox's vault generation is reused before it is read again. */
+export const VAULT_GENERATION_TTL_MS = 60000;
+/** Statuses after which a seal write is never attempted again for that message and generation. */
+const FINAL_WRITE_STATUSES = new Set([400, 403, 404, 409]);
+const generationCache = new Map();
+/** `messageUid:generation` for every write sent (or in flight) this session. */
+const attemptedWrites = new Set();
+/** Seals this session stored, by message uid. */
+const storedSeals = new Map();
+let lockSubscribed = false;
+/** Forgets the cached vault generations and this session's seal writes - in tests. */
+export function clearVerificationSealCache() {
+    generationCache.clear();
+    attemptedWrites.clear();
+    storedSeals.clear();
+}
+function subscribeToLocksOnce() {
+    if (lockSubscribed) {
+        return;
+    }
+    lockSubscribed = true;
+    subscribeKeySession((event) => {
+        if (event.state === "locked") {
+            generationCache.clear();
+        }
+    });
+}
+/** Reads `mailboxUid`'s current vault `masterKeyGeneration`, uncached: `undefined` when the vault can't be read or
+ * reports none. Never rejects. */
+export async function readVaultGeneration(mailboxUid) {
+    try {
+        const { masterKeyGeneration } = await getKeyVault(mailboxUid);
+        return Number.isSafeInteger(masterKeyGeneration) && masterKeyGeneration >= 0 ? masterKeyGeneration : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `mailboxUid`'s current vault `masterKeyGeneration`, or `undefined` when it can't be read. Never rejects. */
+export function getVaultGeneration(mailboxUid) {
+    subscribeToLocksOnce();
+    const entry = generationCache.get(mailboxUid);
+    if (entry && Date.now() - entry.loadedAt <= VAULT_GENERATION_TTL_MS) {
+        return entry.generation;
+    }
+    const created = { loadedAt: Date.now(), generation: readVaultGeneration(mailboxUid) };
+    generationCache.set(mailboxUid, created);
+    void created.generation.then((generation) => {
+        // Only a readable generation is reused; an unavailable one is read again next time.
+        if (generation === undefined && generationCache.get(mailboxUid) === created) {
+            generationCache.delete(mailboxUid);
+        }
+    });
+    return created.generation;
+}
+/** The seal to check `message` against: the one this session stored for it when that is newer than the message's own
+ * copy (which may predate the write), else the message's `verificationSeal`/`verificationSealGeneration`. */
+export function currentVerificationSeal(message) {
+    const stored = storedSeals.get(message.uid);
+    if (stored && (message.verificationSealGeneration === undefined || stored.masterKeyGeneration > message.verificationSealGeneration)) {
+        return { seal: stored.seal, sealGeneration: stored.masterKeyGeneration };
+    }
+    return { seal: message.verificationSeal, sealGeneration: message.verificationSealGeneration };
+}
+/** Whether `sendVerificationSeal()` would still send a seal for `messageUid` at `generation`. */
+export function verificationSealPending(messageUid, generation) {
+    return !attemptedWrites.has(`${messageUid}:${generation}`);
+}
+/** Stores `sealToWrite` on `messageUid`, best effort - see this module's doc comment. Resolves `true` when a request was
+ * sent, `false` when the write was skipped as already attempted. Never rejects. */
+export async function sendVerificationSeal(messageUid, sealToWrite) {
+    const key = `${messageUid}:${sealToWrite.masterKeyGeneration}`;
+    if (attemptedWrites.has(key)) {
+        return false;
+    }
+    attemptedWrites.add(key);
+    try {
+        await setMessageVerificationSeal(messageUid, sealToWrite.seal, sealToWrite.masterKeyGeneration);
+        storedSeals.set(messageUid, sealToWrite);
+    }
+    catch (err) {
+        // `VerificationSealConflictError` is an `ApiRequestError` with status 409.
+        if (!(err instanceof ApiRequestError && FINAL_WRITE_STATUSES.has(err.status))) {
+            attemptedWrites.delete(key);
+        }
+    }
+    return true;
+}

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

@@ -0,0 +1,15 @@
+import type { Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
+/** `true` writable, `false` known view-only, `undefined` couldn't tell (treated as writable). */
+export type MailboxWritability = boolean | undefined;
+/** Forgets every cached answer - for tests, and anything that changes the caller's access mid-session. */
+export declare function clearMailboxWritabilityCache(): void;
+/** The already-known answer for `mailbox`, without making a request. */
+export declare function peekMailboxWritability(mailbox: Mailbox, userUid: string | undefined, trusted?: boolean): MailboxWritability;
+/** Whether the caller can create items in `mailbox`. Never rejects. */
+export declare function getMailboxWritability(mailbox: Mailbox, userUid: string | undefined, trusted?: boolean): Promise<MailboxWritability>;
+/** Per-mailbox writability answers for `mailboxes`, filled in as each one arrives (already-known answers are
+ * present from the first render). */
+export declare function useMailboxWritability(mailboxes: Mailbox[], userUid: string | undefined, trusted?: boolean): Record<string, MailboxWritability>;
+/** `mailboxes` minus any known to be view-only, always keeping `keepUid` (the picker's current/default value,
+ * so the control never shows a value missing from its own options). Lists everything until told otherwise. */
+export declare function useWritableMailboxes(mailboxes: Mailbox[], userUid: string | undefined, keepUid?: string, trusted?: boolean): Mailbox[];