@rapidmx/web-client 0.3.1 → 0.5.0

package/apps/shared/mail/findWellKnownFolderUid.ts

@@ -0,0 +1,13 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { FolderType, listFolders } from "@rapidmx/react-shared/mail/mailApi.js";
+
+/** The uid of a mailbox's well-known folder of `type` (e.g. its Contacts or Tasks folder), for creating an
+ * item in a mailbox other than the one an app currently has loaded. Resolves `undefined` if the mailbox has
+ * no such folder; rejects if the folder list can't be fetched. */
+export async function findWellKnownFolderUid(mailboxUid: string, type: FolderType): Promise<string | undefined> {
+    const folders = await listFolders(mailboxUid);
+    return folders.find((folder) => folder.type === type)?.uid;
+}

package/apps/shared/mail/listAllPages.ts

@@ -0,0 +1,39 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** Page size the list pages (Contacts, Tasks) request per call - restapi caps `limit` at 500. */
+export const LIST_PAGE_SIZE = 500;
+
+/** Safety cap on pages fetched - stops a server that ignores `page` (and keeps returning a full first
+ * page) from looping forever. 40 pages x 500 = 20,000 items. */
+export const MAX_LIST_PAGES = 40;
+
+export interface ListAllPagesResult<T> {
+    items: T[];
+    /** `true` when fetching stopped at `maxPages` with the last page still full - there may be more items
+     * the caller isn't showing, so it should say so rather than presenting `items` as the whole list. */
+    truncated: boolean;
+}
+
+/**
+ * Fetches every page of a zero-based `limit`/`page` list endpoint, stopping at the first short page
+ * (fewer than `pageSize` items) - so a folder with more items than one page holds is shown in full
+ * rather than silently cut off at the first page. Stops at `maxPages` regardless, reporting `truncated`.
+ */
+export async function listAllPages<T>(
+    fetchPage: (page: number) => Promise<T[]>,
+    pageSize: number = LIST_PAGE_SIZE,
+    maxPages: number = MAX_LIST_PAGES,
+): Promise<ListAllPagesResult<T>> {
+    const items: T[] = [];
+    for (let page = 0; page < maxPages; page++) {
+        const batch = await fetchPage(page);
+        items.push(...batch);
+        if (batch.length < pageSize) {
+            return { items, truncated: false };
+        }
+    }
+    return { items, truncated: true };
+}

package/apps/shared/search/LocalIndexLifecycle.tsx

@@ -0,0 +1,98 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Mounts the Tier 2 local index's lifecycle: starts the background build for the active mailbox once it's
+ * unlocked, and destroys an index on the same events that destroy that mailbox's unlocked keys (spec §11
+ * "MUST be destroyed on the same events that destroy private keys: explicit logout, session revocation,
+ * and the configurable idle timeout").
+ *
+ * **Why polling, not hooking the existing destroy call sites directly**: `destroyUnlockedKeys()`
+ * (`react-shared/src/crypto/keySession.ts`) has no observer/callback hook. Watching `getUnlockedKeys()`
+ * for a present-to-absent transition catches *every* destroy path uniformly - idle timeout, the manual
+ * button, or anything else that calls it - without needing to know which one fired.
+ *
+ * Every mailbox this component has seen unlocked is tracked for the life of the mount - not just whichever
+ * is active right now - so switching mailboxes (or a folders-list refresh re-running the build effect)
+ * can never lose a pending unlocked-to-locked transition for a mailbox whose index was already built.
+ *
+ * **Explicit logout** navigates away immediately, which may not leave time for a poll tick - `AppShell.tsx`
+ * handles that case itself via `destroyAllLocalIndexes()`.
+ */
+import { useEffect, useRef } from "react";
+import { getUnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
+import type { PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+import type { Folder } from "@rapidmx/react-shared/mail/mailApi.js";
+import { buildLocalIndex, cancelLocalIndexBuild } from "./localIndexBuilder.js";
+import { destroyLocalIndex, pruneInaccessibleLocalIndexes } from "./localIndexRpcClient.js";
+
+export const POLL_INTERVAL_MS = 5_000;
+
+export interface LocalIndexLifecycleProps {
+    mailboxUid?: string;
+    mailboxKeys?: PublicKey[];
+    folders: Folder[];
+    /** Every mailbox the signed-in user can currently access. Once known, indexes on this device for any
+     * other mailbox (e.g. left behind by a different user who never signed out) are removed. */
+    accessibleMailboxUids?: string[];
+}
+
+/** Renders nothing - pure side-effect component, mounted by `MailShell.tsx`. */
+export default function LocalIndexLifecycle({ mailboxUid, folders, accessibleMailboxUids }: LocalIndexLifecycleProps) {
+    // mailboxUid -> whether it was unlocked at the last check. An entry exists for every mailbox whose
+    // build this component started; only ever changed by a real observed transition, never reset by an
+    // effect re-run.
+    const trackedRef = useRef(new Map<string, boolean>());
+    // The latest props, for the long-lived polling interval below.
+    const latestRef = useRef({ mailboxUid, folders });
+    latestRef.current = { mailboxUid, folders };
+
+    function startBuildIfUnlocked(targetMailboxUid: string, targetFolders: Folder[]) {
+        const unlocked = getUnlockedKeys(targetMailboxUid);
+        if (!unlocked || targetFolders.length === 0 || trackedRef.current.get(targetMailboxUid)) {
+            return;
+        }
+        trackedRef.current.set(targetMailboxUid, true);
+        // Never an unhandled rejection - a broken local index is best-effort infrastructure, not a build
+        // the rest of the app depends on.
+        buildLocalIndex(targetMailboxUid, unlocked, targetFolders).catch(() => undefined);
+    }
+
+    useEffect(() => {
+        if (mailboxUid) {
+            startBuildIfUnlocked(mailboxUid, folders);
+        }
+    }, [mailboxUid, folders]);
+
+    useEffect(() => {
+        const interval = setInterval(() => {
+            for (const [trackedUid, wasUnlocked] of trackedRef.current) {
+                if (wasUnlocked && !getUnlockedKeys(trackedUid)) {
+                    // A present-to-absent transition: something just destroyed this mailbox's keys.
+                    trackedRef.current.set(trackedUid, false);
+                    // Stop the pass still running with the now-destroyed keys; the destroy itself also makes
+                    // the Worker reject anything that pass still sends.
+                    void cancelLocalIndexBuild(trackedUid);
+                    void destroyLocalIndex(trackedUid);
+                }
+            }
+            // The active mailbox was (re-)unlocked since the last check, e.g. via an on-demand unlock prompt.
+            const { mailboxUid: activeUid, folders: activeFolders } = latestRef.current;
+            if (activeUid) {
+                startBuildIfUnlocked(activeUid, activeFolders);
+            }
+        }, POLL_INTERVAL_MS);
+        return () => clearInterval(interval);
+    }, []);
+
+    // A stable string key so a re-render with an equal-but-new array doesn't re-scan OPFS.
+    const accessibleKey = accessibleMailboxUids && accessibleMailboxUids.length > 0 ? JSON.stringify([...accessibleMailboxUids].sort()) : "";
+    useEffect(() => {
+        if (accessibleKey) {
+            void pruneInaccessibleLocalIndexes(JSON.parse(accessibleKey) as string[]);
+        }
+    }, [accessibleKey]);
+
+    return null;
+}

package/apps/shared/search/localIndexBlockCipher.ts

@@ -0,0 +1,83 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The actual AES-256-GCM block cipher `localIndexVFS.ts`'s `EncryptingVFS` uses to encrypt/decrypt one
+ * physical storage block - deliberately split out from that file so it can be exercised with real
+ * WebCrypto in a plain unit test, with no OPFS/Worker/wa-sqlite involved at all (none of those are
+ * available under Vitest's jsdom environment, matching the same "node" test environment convention
+ * `react-shared`'s other crypto modules already use for exactly this reason).
+ *
+ * See `localIndexVFS.ts`'s own doc comment for the full design rationale (page layout, why a fresh
+ * random nonce per write, why AAD binds to filename+block index). This module is pure mechanism; that
+ * one is where the design is explained.
+ */
+
+/** The logical SQLite page size `EncryptingVFS` is designed for - MUST match the `PRAGMA page_size` the
+ * database was created with (`localIndexWorker.ts` sets this before the first write). */
+export const LOGICAL_BLOCK_SIZE = 4096;
+const NONCE_LENGTH = 12;
+const TAG_LENGTH = 16;
+/** One physical block on disk: `nonce || ciphertext || tag`. */
+export const PHYSICAL_BLOCK_SIZE = LOGICAL_BLOCK_SIZE + NONCE_LENGTH + TAG_LENGTH;
+
+/** Thrown when a stored block fails AES-GCM authentication - a wrong/rotated key, on-disk corruption, or
+ * a block moved to the wrong position (see `localIndexVFS.ts`'s doc comment on why AAD binds position).
+ * The worker's caller treats this identically to a schema-version mismatch: discard the whole index and
+ * rebuild (spec §11 "Invalidation"). */
+export class PageCorruptedError extends Error {
+    /** The underlying `DOMException`/error `crypto.subtle.decrypt()` threw, or an inner-VFS read failure
+     * - kept as a plain field rather than the ES2022 `Error` constructor's `cause` option, since
+     * web-client's `tsconfig.json` targets ES2020. */
+    readonly cause: unknown;
+
+    constructor(filename: string, blockIndex: number, cause: unknown) {
+        super(`Local search index block ${blockIndex} of '${filename}' failed to decrypt.`);
+        this.cause = cause;
+    }
+}
+
+export async function importAesGcmKey(rawKey: Uint8Array): Promise<CryptoKey> {
+    return crypto.subtle.importKey("raw", rawKey as BufferSource, "AES-GCM", false, ["encrypt", "decrypt"]);
+}
+
+function buildBlockAad(filename: string, blockIndex: number): Uint8Array {
+    return new TextEncoder().encode(`rapidmx-local-index-block:${filename}:${blockIndex}`);
+}
+
+/** Encrypts one logical block (`plaintext`, exactly `LOGICAL_BLOCK_SIZE` bytes) into its physical,
+ * on-disk representation (`PHYSICAL_BLOCK_SIZE` bytes: a fresh random nonce followed by
+ * ciphertext+tag). */
+export async function encryptBlock(key: CryptoKey, filename: string, blockIndex: number, plaintext: Uint8Array): Promise<Uint8Array> {
+    const nonce = crypto.getRandomValues(new Uint8Array(NONCE_LENGTH));
+    const ciphertextAndTag = new Uint8Array(
+        await crypto.subtle.encrypt(
+            { name: "AES-GCM", iv: nonce as BufferSource, additionalData: buildBlockAad(filename, blockIndex) as BufferSource },
+            key,
+            plaintext as BufferSource,
+        ),
+    );
+    const physical = new Uint8Array(PHYSICAL_BLOCK_SIZE);
+    physical.set(nonce, 0);
+    physical.set(ciphertextAndTag, NONCE_LENGTH);
+    return physical;
+}
+
+/** Inverse of `encryptBlock()`. Throws `PageCorruptedError` (never a raw `DOMException`) on auth
+ * failure - a wrong key, tampered ciphertext, or a block swapped into the wrong position (caught by the
+ * position-bound AAD not matching). */
+export async function decryptBlock(key: CryptoKey, filename: string, blockIndex: number, physical: Uint8Array): Promise<Uint8Array> {
+    const nonce = physical.subarray(0, NONCE_LENGTH);
+    const ciphertextAndTag = physical.subarray(NONCE_LENGTH, PHYSICAL_BLOCK_SIZE);
+    try {
+        const plaintext = await crypto.subtle.decrypt(
+            { name: "AES-GCM", iv: nonce as BufferSource, additionalData: buildBlockAad(filename, blockIndex) as BufferSource },
+            key,
+            ciphertextAndTag as BufferSource,
+        );
+        return new Uint8Array(plaintext);
+    } catch (err) {
+        throw new PageCorruptedError(filename, blockIndex, err);
+    }
+}