@rapidmx/web-client 0.4.0 → 0.5.0

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

@@ -0,0 +1,60 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** 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>;
+
+const flushers = new Set<ComposeFlush>();
+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(): void {
+    signingOut = true;
+}
+
+/** Undoes `markSigningOut()`. */
+export function clearSigningOut(): void {
+    signingOut = false;
+}
+
+/** Whether `markSigningOut()` has been called (and not cleared). */
+export function isSigningOut(): boolean {
+    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: ComposeFlush): () => void {
+    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: number): Promise<boolean> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<boolean>((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/apps/shared/components/mail/layout/MailShell.tsx

@@ -99,6 +99,9 @@ function aggregateUnreadCount(mailboxFolders: MailboxFolders[], type: AggregateF
 
 type Status = "checking" | "error" | "ready";
 
+/** 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
@@ -168,7 +171,7 @@ export default function MailShell({
         if (!userUid) {
             return;
         }
-        listMailboxes({ limit: 100 })
+        listMailboxes({ limit: MAILBOX_LIST_LIMIT })
             .then((result) => {
                 setMailboxes(result);
                 setStatus("ready");
@@ -201,7 +204,7 @@ export default function MailShell({
             return;
         }
         setFoldersLoading(true);
-        Promise.all(
+        void Promise.all(
             mailboxes.map((mailbox) =>
                 listFolders(mailbox.uid)
                     .then((result): MailboxFolders => ({ mailbox, folders: result.filter((f) => MAIL_FOLDER_TYPES.has(f.type)) }))
@@ -387,11 +390,18 @@ export default function MailShell({
             // 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}
+            // 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}
         >
             <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}
             />
             <AppShell
                 active="mail"

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

@@ -0,0 +1,124 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 {
+    Contact,
+    PINNED_FINGERPRINT_MAX_PAGES,
+    PINNED_FINGERPRINT_PAGE_SIZE,
+    SignerKeyState,
+    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 = 60_000;
+
+const contactsCache = new Map<string, { loadedAt: number; contacts: Promise<Contact[]> }>();
+
+/** Forgets every cached contact list - on sign-out, a key-session lock, after the reader changes their contacts, and
+ * in tests. */
+export function clearPinnedSignerCache(): void {
+    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(): void {
+    if (lockSubscribed) {
+        return;
+    }
+    lockSubscribed = true;
+    subscribeKeySession((event) => {
+        if (event.state === "locked") {
+            clearPinnedSignerCache();
+        }
+    });
+}
+
+async function loadMailboxContacts(mailboxUid: string): Promise<Contact[]> {
+    const folders = await listFolders(mailboxUid);
+    const contacts: Contact[] = [];
+    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: string): Promise<Contact[]> {
+    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: string, address: string): Promise<string[]> {
+    return pinnedSigningFingerprintsFor(await cachedMailboxContacts(mailboxUid), address);
+}
+
+/** 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 async function getSignerKeyState(mailboxUid: string, address: string): Promise<SenderKeyState> {
+    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/apps/shared/components/mail/verificationSeals.ts

@@ -0,0 +1,125 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { type Message, setMessageVerificationSeal } 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 const VAULT_GENERATION_TTL_MS = 60_000;
+
+/** 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<string, { loadedAt: number; generation: Promise<number | undefined> }>();
+/** `messageUid:generation` for every write sent (or in flight) this session. */
+const attemptedWrites = new Set<string>();
+/** Seals this session stored, by message uid. */
+const storedSeals = new Map<string, SealToWrite>();
+
+let lockSubscribed = false;
+
+/** Forgets the cached vault generations and this session's seal writes - in tests. */
+export function clearVerificationSealCache(): void {
+    generationCache.clear();
+    attemptedWrites.clear();
+    storedSeals.clear();
+}
+
+function subscribeToLocksOnce(): void {
+    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: string): Promise<number | undefined> {
+    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: string): Promise<number | undefined> {
+    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: Pick<Message, "uid" | "verificationSeal" | "verificationSealGeneration">): {
+    seal?: string;
+    sealGeneration?: number;
+} {
+    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: string, generation: number): boolean {
+    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: string, sealToWrite: SealToWrite): Promise<boolean> {
+    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/apps/shared/components/mail/writableMailboxes.ts

@@ -0,0 +1,101 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Which of the caller's accessible mailboxes they can actually create things in (send from, create
+ * events/contacts/to-dos in). `listMailboxes()` returns view-only shares too, and `Mailbox` itself carries
+ * no per-caller access role, so a "viewer" delegate used to be offered mailboxes every create would 403 in.
+ *
+ * The signal: an owned mailbox (or any mailbox, for a trusted caller) is always writable; for any other,
+ * `getMyMailboxAccess()`'s `canCreate` - the server's own ACL evaluation of the exact action a create needs.
+ * One request per mailbox per page load: results are cached in a module-level map, with concurrent callers
+ * sharing one in-flight request. A failure (network, an older server without that route) is "unknown" and
+ * isn't cached: the server still enforces access on the create itself, and hiding a usable mailbox over a
+ * transient error would be worse than offering one that later errors.
+ *
+ * Nothing waits on these checks: pickers list every mailbox straight away and drop view-only ones as each
+ * answer arrives.
+ */
+import { useEffect, useMemo, useState } from "react";
+import type { Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
+import { getMyMailboxAccess } from "@rapidmx/react-shared/mail/mailboxAccessApi.js";
+
+/** `true` writable, `false` known view-only, `undefined` couldn't tell (treated as writable). */
+export type MailboxWritability = boolean | undefined;
+
+const inFlight = new Map<string, Promise<MailboxWritability>>();
+const settled = new Map<string, boolean>();
+
+/** Forgets every cached answer - for tests, and anything that changes the caller's access mid-session. */
+export function clearMailboxWritabilityCache(): void {
+    inFlight.clear();
+    settled.clear();
+}
+
+function isImplicitlyWritable(mailbox: Mailbox, userUid: string | undefined, trusted: boolean | undefined): boolean {
+    return !!trusted || (!!userUid && mailbox.ownerUserUid === userUid);
+}
+
+/** The already-known answer for `mailbox`, without making a request. */
+export function peekMailboxWritability(mailbox: Mailbox, userUid: string | undefined, trusted?: boolean): MailboxWritability {
+    return isImplicitlyWritable(mailbox, userUid, trusted) ? true : settled.get(mailbox.uid);
+}
+
+/** Whether the caller can create items in `mailbox`. Never rejects. */
+export function getMailboxWritability(mailbox: Mailbox, userUid: string | undefined, trusted?: boolean): Promise<MailboxWritability> {
+    const known = peekMailboxWritability(mailbox, userUid, trusted);
+    if (known !== undefined) {
+        return Promise.resolve(known);
+    }
+    let request = inFlight.get(mailbox.uid);
+    if (!request) {
+        request = getMyMailboxAccess(mailbox.uid).then(
+            (access) => {
+                settled.set(mailbox.uid, access.canCreate);
+                inFlight.delete(mailbox.uid);
+                return access.canCreate;
+            },
+            () => {
+                // Not cached - a later check may succeed.
+                inFlight.delete(mailbox.uid);
+                return undefined;
+            },
+        );
+        inFlight.set(mailbox.uid, request);
+    }
+    return request;
+}
+
+/** Per-mailbox writability answers for `mailboxes`, filled in as each one arrives (already-known answers are
+ * present from the first render). */
+export function useMailboxWritability(mailboxes: Mailbox[], userUid: string | undefined, trusted?: boolean): Record<string, MailboxWritability> {
+    const [answers, setAnswers] = useState<Record<string, MailboxWritability>>({});
+    useEffect(() => {
+        let cancelled = false;
+        for (const mailbox of mailboxes) {
+            void getMailboxWritability(mailbox, userUid, trusted).then((writable) => {
+                if (!cancelled) {
+                    setAnswers((prev) => ({ ...prev, [mailbox.uid]: writable }));
+                }
+            });
+        }
+        return () => {
+            cancelled = true;
+        };
+    }, [mailboxes, userUid, trusted]);
+    return useMemo(() => {
+        const merged: Record<string, MailboxWritability> = {};
+        for (const mailbox of mailboxes) {
+            merged[mailbox.uid] = answers[mailbox.uid] ?? peekMailboxWritability(mailbox, userUid, trusted);
+        }
+        return merged;
+    }, [answers, mailboxes, userUid, trusted]);
+}
+
+/** `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 function useWritableMailboxes(mailboxes: Mailbox[], userUid: string | undefined, keepUid?: string, trusted?: boolean): Mailbox[] {
+    const writability = useMailboxWritability(mailboxes, userUid, trusted);
+    return useMemo(() => mailboxes.filter((mb) => mb.uid === keepUid || writability[mb.uid] !== false), [mailboxes, writability, keepUid]);
+}