@rapidmx/web-client 0.4.0 → 0.6.0

package/dist/apps/shared/search/LocalIndexLifecycle.js

@@ -3,74 +3,78 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 /**
- * Mounts the Tier 2 local index's lifecycle for one mailbox: starts the background build once it's
- * unlocked, and destroys the index on the same events that destroy the unlocked keys themselves (spec
- * §11 "MUST be destroyed on the same events that destroy private keys: explicit logout, session
- * revocation, and the configurable idle timeout").
+ * 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, and its own two real call
- * sites are `useIdleKeyTimeout.ts` (in `react-shared`, not this repo) and the manual "Destroy keys now"
- * button in Settings - editing the former would mean a react-shared source change that (per this
- * session's own earlier finding) doesn't reach `web-client` without a package republish + patch refresh
- * cycle, which is out of scope for wiring up a destroy signal. Watching `getUnlockedKeys()` for a
- * present-to-absent transition instead catches *every* destroy path uniformly - idle timeout, the manual
+ * (`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.
  *
- * **Explicit logout is the one gap this polling doesn't reliably cover**: `AppShell.tsx`'s sign-out
- * navigates away immediately, which may not leave time for a poll tick to fire first. That case is
- * handled separately, directly in `AppShell.tsx`, via `destroyAllLocalIndexes()` - see that call site's
- * own comment.
+ * 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 { buildLocalIndex } from "./localIndexBuilder.js";
-import { destroyLocalIndex } from "./localIndexRpcClient.js";
-const POLL_INTERVAL_MS = 5000;
-/** Renders nothing - pure side-effect component, mounted by `MailShell.tsx` (which is where a
- * `mailboxUid` is actually known; `AppShell.tsx` itself is mailbox-agnostic, shared by every app). Each
- * `buildLocalIndex()` call below omits its `windowConfig` argument deliberately - that leaves the byte
- * budget to its own default, which already resolves per-device (Web vs. Electron) and per-user
- * preference (Settings > Encryption) on its own; see `localIndexBuilder.ts`/`localIndexSizePreference.ts`
- * for how. */
-export default function LocalIndexLifecycle({ mailboxUid, folders }) {
-    // Guards against re-triggering a build every time this component re-renders (e.g. on an unrelated
-    // folders-list refresh) for a mailbox already built/building this session.
-    const buildStartedForRef = useRef(undefined);
-    const wasUnlockedRef = useRef(false);
-    useEffect(() => {
-        if (!mailboxUid || folders.length === 0) {
+import { buildLocalIndex, cancelLocalIndexBuild } from "./localIndexBuilder.js";
+import { destroyLocalIndex, pruneInaccessibleLocalIndexes } from "./localIndexRpcClient.js";
+export const POLL_INTERVAL_MS = 5000;
+/** Renders nothing - pure side-effect component, mounted by `MailShell.tsx`. */
+export default function LocalIndexLifecycle({ mailboxUid, folders, accessibleMailboxUids }) {
+    // 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());
+    // The latest props, for the long-lived polling interval below.
+    const latestRef = useRef({ mailboxUid, folders });
+    latestRef.current = { mailboxUid, folders };
+    function startBuildIfUnlocked(targetMailboxUid, targetFolders) {
+        const unlocked = getUnlockedKeys(targetMailboxUid);
+        if (!unlocked || targetFolders.length === 0 || trackedRef.current.get(targetMailboxUid)) {
             return;
         }
-        const unlocked = getUnlockedKeys(mailboxUid);
-        wasUnlockedRef.current = !!unlocked;
-        if (unlocked && buildStartedForRef.current !== mailboxUid) {
-            buildStartedForRef.current = mailboxUid;
-            // Never an unhandled rejection - a broken local index (Worker/WASM/OPFS unsupported or
-            // unavailable, a corrupted store) is best-effort infrastructure, not a build the rest of the
-            // app depends on. searchTier2.ts's own callers already degrade gracefully independent of
-            // whether a build ever completed at all.
-            buildLocalIndex(mailboxUid, unlocked, folders).catch(() => undefined);
+        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(() => {
-            const stillUnlocked = !!getUnlockedKeys(mailboxUid);
-            if (wasUnlockedRef.current && !stillUnlocked) {
-                // A present-to-absent transition: something just destroyed this mailbox's unlocked keys
-                // (idle timeout or the manual "Destroy keys now" button - see this module's own doc
-                // comment on why this is observed rather than hooked directly).
-                void destroyLocalIndex(mailboxUid);
-                buildStartedForRef.current = undefined;
+            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);
+                }
             }
-            else if (!wasUnlockedRef.current && stillUnlocked && buildStartedForRef.current !== mailboxUid) {
-                // The mailbox was re-unlocked this session (e.g. via ComposeWindow's or
-                // MessageDetailPane's own on-demand unlock prompt) - start the build it missed the first
-                // time around.
-                buildStartedForRef.current = mailboxUid;
-                buildLocalIndex(mailboxUid, getUnlockedKeys(mailboxUid), folders).catch(() => undefined);
+            // 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);
             }
-            wasUnlockedRef.current = stillUnlocked;
         }, POLL_INTERVAL_MS);
         return () => clearInterval(interval);
-    }, [mailboxUid, folders]);
+    }, []);
+    // 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));
+        }
+    }, [accessibleKey]);
     return null;
 }

package/dist/apps/shared/search/localIndexBlockCipher.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 declare const LOGICAL_BLOCK_SIZE = 4096;
+/** One physical block on disk: `nonce || ciphertext || tag`. */
+export declare const PHYSICAL_BLOCK_SIZE: number;
+/** 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 declare 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);
+}
+export declare function importAesGcmKey(rawKey: Uint8Array): Promise<CryptoKey>;
+/** 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 declare function encryptBlock(key: CryptoKey, filename: string, blockIndex: number, plaintext: Uint8Array): Promise<Uint8Array>;
+/** 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 declare function decryptBlock(key: CryptoKey, filename: string, blockIndex: number, physical: Uint8Array): Promise<Uint8Array>;

package/dist/apps/shared/search/localIndexBuilder.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The Tier 2 local index's background builder (`specs/search.md` §11 "Initial build... incrementally,
+ * newest-first"). Runs on the main thread - the actual storage I/O and encryption happen in
+ * `localIndexWorker.ts` (off the UI thread, per that file's own doc comment); this module's own work is
+ * orchestration (deciding what to fetch) plus already-async fetch/decrypt calls, not CPU-heavy work that
+ * would itself need to move off-thread.
+ *
+ * **Known scoping simplification**: walks the mailbox's real mail folders one at a time (a fixed,
+ * reasonable priority order - Inbox and Sent first), each already newest-first via `listMessages()`'s own
+ * default sort, rather than a true interleaved k-way merge producing one single globally-newest-first
+ * stream across folders. A message in, say, Sent slightly older than the *oldest-processed-so-far*
+ * message in Inbox can therefore be indexed slightly out of true global date order relative to it. Given
+ * the byte-budget eviction below is itself date-based (oldest `date_for_sort` first, enforced by
+ * `localIndexWorker.ts`'s own `applyEviction()` after every insert - see that file), a small amount of
+ * cross-folder interleaving imprecision here does not affect *what* ultimately survives the window, only
+ * the exact order entities are inserted (and therefore briefly evicted-and-reinserted) in.
+ *
+ * Only encrypted messages (`subject === "[...]"`) are indexed - see `ENCRYPTED_SUBJECT_PLACEHOLDER`'s
+ * own precedent in `apps/www/index.tsx`'s inbox-list decrypt work. An unencrypted message is already
+ * fully searchable via Tier 1; indexing it here too would spend this index's bounded byte budget on
+ * content that didn't need it.
+ *
+ * **Verification seals.** A message this pass decrypts that has no seal for the vault's current `masterKeyGeneration` is
+ * evaluated with `evaluateMessageSecurityWithSeal()`, against the sender's pinned signing keys from the reader's
+ * contacts (`pinnedSigners.ts`, the message pane's own source, looked up once per sender per pass), so a verified
+ * message gets its seal without being opened (see `apps/shared/components/mail/verificationSeals.ts`). Pins only change
+ * the security state, never the recovered subject or body this index stores. Seal writes are best effort and bounded:
+ * at most `SEAL_WRITE_CONCURRENCY` in flight, at most `MAX_SEAL_WRITES_PER_PASS` per pass (past it, messages are
+ * evaluated without seals), failures ignored, and nothing new starts once the pass is aborted or its keys are destroyed.
+ * A seal carries only a hash, fingerprint, state and time, never plaintext. With no readable vault generation the pass
+ * seals nothing. Signed-only (unencrypted) messages aren't sealed here: this pass never fetches their raw MIME (see
+ * above), and fetching it only to seal would cost a download per message; they are sealed when opened.
+ */
+import { type Folder } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { UnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
+/** §11's Window Sizing table's time-floor column - explicitly unvalidated starting-point default per the
+ * spec's own §16 "Measurement Task" ("cannot be supplied by design work... MUST NOT be treated as
+ * validated"). Used as-is rather than invented/adjusted here. Not user-adjustable today (unlike the byte
+ * budget - see `localIndexSizePreference.ts`) - nothing in this codebase has asked for that yet. */
+export declare const WEB_TIME_FLOOR_MONTHS = 12;
+/** Either bound as `0` means "no limit": `applyEviction()` (`localIndexWorker.ts`) already treats a
+ * falsy byte budget as unconfigured/unenforced, and `buildLocalIndex()` below mirrors that same
+ * convention for `timeFloorMonths` so a single `0` means the same thing in both dimensions. */
+export interface LocalIndexWindowConfig {
+    timeFloorMonths: number;
+    byteBudgetBytes: number;
+}
+/** How many times a pass walks a folder whose total count changed during the walk. `listMessages()` only
+ * pages by offset, so a message removed from an already-walked page shifts a later one onto it unseen;
+ * only a folder whose count held steady across a whole walk is trusted for completeness and pruning. */
+export declare const MAX_WALK_ATTEMPTS = 3;
+/** Subtracted from the pass's start time before it's recorded as the end of guaranteed coverage - a
+ * message's server-assigned `receivedDate` can be ahead of this device's clock. */
+export declare const CLOCK_SKEW_MARGIN_MS: number;
+/** How many raw-MIME fetch+decrypt calls run at once - a page of 100 encrypted messages used to fire all
+ * 100 requests simultaneously. */
+export declare const FETCH_CONCURRENCY = 6;
+/** How many verification seal writes run at once during a pass. */
+export declare const SEAL_WRITE_CONCURRENCY = 2;
+/** The most verification seals one pass writes. */
+export declare const MAX_SEAL_WRITES_PER_PASS = 200;
+/** Runs one full incremental build pass for `mailboxUid`: sets the window, walks mail folders newest-first
+ * (per this module's own doc comment on the folder-order simplification), decrypts and indexes only
+ * `"[...]"`-subject messages until each folder's own coverage passes the time floor, then clears the
+ * `building` flag. Messages already indexed at the same version are skipped, fetches run at most
+ * `FETCH_CONCURRENCY` at a time, and messages older than the eviction watermark (`WindowState.evictedBefore`)
+ * are neither fetched nor walked past. A failure partway through leaves whatever was indexed so far in place
+ * and records the pass as incomplete (spec §11's "incomplete-index UX... MUST indicate that coverage is
+ * partial" - see `Coverage.complete`). Rows the server no longer lists (deleted or moved elsewhere by any
+ * client) are pruned only within folders whose count held steady for a whole walk (see `MAX_WALK_ATTEMPTS`).
+ *
+ * Only one pass runs per mailbox (a newer call cancels the older), and every Worker call carries this pass's
+ * generation, so a pass outlived by a destroy can't write anything (see `cancelLocalIndexBuild()`).
+ *
+ * `windowConfig` defaults to this device's own configured byte budget (`getLocalIndexByteBudget()` -
+ * 500 MB in a browser tab, 1 GB in Electron, or whatever the user has since set in Settings > Encryption)
+ * alongside the fixed time floor above. Evaluated fresh on every call with no explicit override, so a
+ * preference change in Settings takes effect starting with this mailbox's next build pass (its next
+ * unlock), without requiring a reload.
+ */
+export declare function buildLocalIndex(mailboxUid: string, unlocked: UnlockedKeys, folders: Folder[], windowConfig?: LocalIndexWindowConfig): Promise<void>;
+/** Stops a mailbox's running build pass, if any (e.g. its keys were just destroyed), resolving once it has
+ * wound down. The Worker independently rejects the pass's later calls once the index is destroyed (see
+ * `GenerationParams`); this just stops the fetching and decrypting too. Never rejects. */
+export declare function cancelLocalIndexBuild(mailboxUid: string): Promise<void>;