@rapidmx/web-client 0.3.0 → 0.4.0

package/apps/shared/components/settings/layout/SettingsShell.tsx

@@ -28,6 +28,7 @@ export const SETTINGS_SECTIONS: SettingsSectionDef[] = [
     { id: "read-receipts", href: "/settings/read-receipts", label: "Read Receipts" },
     { id: "booking-types", href: "/settings/booking-types", label: "Booking Links" },
     { id: "encryption", href: "/settings/encryption", label: "Encryption" },
+    { id: "sharing", href: "/settings/sharing", label: "Sharing" },
     { id: "privacy", href: "/settings/privacy", label: "Privacy & Data" },
 ];
 

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/search/LocalIndexLifecycle.tsx

@@ -0,0 +1,89 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// 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").
+ *
+ * **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
+ * 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.
+ */
+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 } from "./localIndexBuilder.js";
+import { destroyLocalIndex } from "./localIndexRpcClient.js";
+
+const POLL_INTERVAL_MS = 5_000;
+
+export interface LocalIndexLifecycleProps {
+    mailboxUid?: string;
+    mailboxKeys?: PublicKey[];
+    folders: Folder[];
+}
+
+/** 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 }: LocalIndexLifecycleProps) {
+    // 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<string | undefined>(undefined);
+    const wasUnlockedRef = useRef(false);
+
+    useEffect(() => {
+        if (!mailboxUid || folders.length === 0) {
+            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);
+        }
+
+        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;
+            } 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);
+            }
+            wasUnlockedRef.current = stillUnlocked;
+        }, POLL_INTERVAL_MS);
+
+        return () => clearInterval(interval);
+    }, [mailboxUid, folders]);
+
+    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);
+    }
+}

package/apps/shared/search/localIndexBuilder.ts

@@ -0,0 +1,179 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * 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.
+ */
+import { getMessageRawContent, listMessages, type Folder, type Message } from "@rapidmx/react-shared/mail/mailApi.js";
+import { evaluateMessageSecurity } from "@rapidmx/react-shared/crypto/messageSecurity.js";
+import type { UnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
+import type { LocalIndexEntity } from "./localIndexSchema.js";
+import { indexLocalEntities, initLocalIndex, setLocalIndexBuilding, setLocalIndexWindow } from "./localIndexRpcClient.js";
+import { deriveLocalIndexKey } from "./localIndexKey.js";
+import { getLocalIndexByteBudget } from "./localIndexSizePreference.js";
+
+/** The RFC 9788 placeholder subject every encrypted message's outer envelope carries server-side - see
+ * `apps/www/index.tsx`'s identical constant and its own doc comment for the full citation. */
+const ENCRYPTED_SUBJECT_PLACEHOLDER = "[...]";
+
+/** §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 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;
+}
+
+/** Folder types that actually hold messages - excludes `calendar`/`contacts`/other non-mail folder types
+ * `FolderType` also covers. Inbox and Sent first: the two folders a "did I find that email" search is
+ * overwhelmingly likely to land in, so they're covered soonest if the build is interrupted (tab closed,
+ * idle timeout) partway through. */
+const MESSAGE_FOLDER_TYPES = new Set(["inbox", "sent_items", "drafts", "deleted_items", "outbox", "junk"]);
+const FOLDER_PRIORITY: Record<string, number> = { inbox: 0, sent_items: 1 };
+
+const PAGE_SIZE = 100;
+const MAX_APPROX_BYTES_PER_MESSAGE_PADDING = 512; // subject/participants/flags overhead beyond raw text length
+
+/** `cutoff === undefined` means no time floor at all (an unbounded `windowConfig`) - every message is
+ * "within" it, so the caller's own end-of-folder check (`messages.length < PAGE_SIZE`) becomes the only
+ * stopping condition. */
+function isWithinTimeFloor(receivedDate: string, cutoff: Date | undefined): boolean {
+    return !cutoff || new Date(receivedDate).getTime() >= cutoff.getTime();
+}
+
+function estimateByteSize(entity: Pick<LocalIndexEntity, "subject" | "body" | "attachmentText" | "participants">): number {
+    const textLength =
+        (entity.subject?.length ?? 0) + (entity.body?.length ?? 0) + (entity.attachmentText?.length ?? 0) + entity.participants.length;
+    return textLength + MAX_APPROX_BYTES_PER_MESSAGE_PADDING;
+}
+
+/** Decrypts one message and shapes it into a `LocalIndexEntity`, or `undefined` when nothing usable was
+ * recovered (a decrypt failure, or a message that turns out not to actually be encrypted despite the
+ * placeholder subject) - mirrors `searchTier3.ts`'s own `!security.html && !security.subject` discard
+ * rule exactly, for the same reason. */
+async function buildEntity(message: Message, unlocked: UnlockedKeys): Promise<LocalIndexEntity | undefined> {
+    try {
+        const rawMime = await getMessageRawContent(message.uid);
+        const security = await evaluateMessageSecurity(rawMime, unlocked);
+        if (!security.subject && !security.html) {
+            return undefined;
+        }
+        const participants = [message.from.address, message.from.displayName, ...message.recipients.map((r) => r.address)]
+            .filter(Boolean)
+            .join(" ");
+        const setFlags = Object.entries(message.flags)
+            .filter(([, value]) => value)
+            .map(([key]) => key);
+        // Leading/trailing comma so `flags LIKE '%,x,%'` (localIndexSchema.ts's buildSearchPredicates())
+        // matches correctly even for the first/last flag in the list.
+        const flags = `,${setFlags.join(",")},`;
+        const entity: LocalIndexEntity = {
+            entityType: "message",
+            entityUid: message.uid,
+            mailboxUid: message.mailboxUid,
+            folderUid: message.folderUid,
+            dateForSort: message.receivedDate,
+            participants,
+            flags,
+            hasAttachments: message.hasAttachments,
+            subject: security.subject,
+            body: security.html,
+            byteSize: 0, // filled in below, after the fields above are known
+        };
+        entity.byteSize = estimateByteSize(entity);
+        return entity;
+    } catch {
+        // Best-effort, matching searchTier3.ts's own Promise.allSettled-per-candidate posture - one
+        // message's fetch/decrypt failure never aborts the rest of the build.
+        return undefined;
+    }
+}
+
+/** 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. Never throws - a failure partway through leaves whatever was indexed so far in place
+ * (spec §11's "incomplete-index UX... MUST indicate that coverage is partial" is served by `coverage()`
+ * truthfully reporting whatever `indexedFrom` this run actually reached, not by this function needing to
+ * succeed completely).
+ *
+ * `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 async function buildLocalIndex(
+    mailboxUid: string,
+    unlocked: UnlockedKeys,
+    folders: Folder[],
+    windowConfig: LocalIndexWindowConfig = { timeFloorMonths: WEB_TIME_FLOOR_MONTHS, byteBudgetBytes: getLocalIndexByteBudget() },
+): Promise<void> {
+    const indexKey = await deriveLocalIndexKey(unlocked.masterKey, mailboxUid);
+    await initLocalIndex({ mailboxUid, indexKey });
+    await setLocalIndexWindow(mailboxUid, windowConfig.timeFloorMonths, windowConfig.byteBudgetBytes);
+    await setLocalIndexBuilding(mailboxUid, true);
+    try {
+        let cutoff: Date | undefined;
+        if (windowConfig.timeFloorMonths > 0) {
+            cutoff = new Date();
+            cutoff.setMonth(cutoff.getMonth() - windowConfig.timeFloorMonths);
+        }
+
+        const mailFolders = folders
+            .filter((f) => MESSAGE_FOLDER_TYPES.has(f.type))
+            .sort((a, b) => (FOLDER_PRIORITY[a.type] ?? 99) - (FOLDER_PRIORITY[b.type] ?? 99));
+
+        for (const folder of mailFolders) {
+            let page = 0;
+            for (;;) {
+                const messages = await listMessages(folder.uid, { page, limit: PAGE_SIZE }).catch(() => []);
+                if (messages.length === 0) {
+                    break;
+                }
+                const encrypted = messages.filter((m) => m.subject === ENCRYPTED_SUBJECT_PLACEHOLDER);
+                if (encrypted.length > 0) {
+                    const entities = (await Promise.all(encrypted.map((m) => buildEntity(m, unlocked)))).filter(
+                        (e): e is LocalIndexEntity => e !== undefined,
+                    );
+                    if (entities.length > 0) {
+                        await indexLocalEntities(mailboxUid, entities);
+                    }
+                }
+                const oldestOnPage = messages[messages.length - 1];
+                if (!isWithinTimeFloor(oldestOnPage.receivedDate, cutoff) || messages.length < PAGE_SIZE) {
+                    break;
+                }
+                page += 1;
+            }
+        }
+    } finally {
+        await setLocalIndexBuilding(mailboxUid, false);
+    }
+}

package/apps/shared/search/localIndexKey.ts

@@ -0,0 +1,27 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Derives the page-encryption key for one mailbox's Tier 2 local index (`specs/search.md` §11
+ * "Persistence and protection... MUST be encrypted at rest under the mailbox master key (MK)... using
+ * the same AEAD construction"). Reuses `crypto/masterKey.ts`'s existing `hkdfDerive()` - the same HKDF
+ * primitive every other MK-derived key in this codebase already goes through.
+ *
+ * No persisted per-install salt: MK is already 32 bytes of uniform random key material (see
+ * `masterKey.ts`'s own `generateMasterKey()`), so a fixed, non-secret salt is standard HKDF practice
+ * here (RFC 5869 - a salt matters for stretching low-entropy input, not for re-randomizing input that's
+ * already uniformly random) and avoids needing to persist, transmit, or ever lose a random salt just to
+ * re-derive the same key on the next unlock.
+ */
+import { hkdfDerive } from "@rapidmx/react-shared/crypto/masterKey.js";
+
+/** Fixed, non-secret HKDF salt - see this module's own doc comment for why a fixed salt is fine here. */
+const FIXED_SALT = new TextEncoder().encode("rapidmx-local-search-index-v1");
+
+/** Derives this mailbox's local-index page-encryption key from its already-unlocked master key. Every
+ * call with the same `(masterKey, mailboxUid)` pair returns the identical key - callers never need to
+ * persist it themselves. */
+export async function deriveLocalIndexKey(masterKey: Uint8Array, mailboxUid: string): Promise<Uint8Array> {
+    return hkdfDerive(masterKey, FIXED_SALT, `local-search-index:${mailboxUid}`);
+}

package/apps/shared/search/localIndexRpcClient.ts

@@ -0,0 +1,116 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Main-thread Promise-based RPC wrapper around `localIndexWorker.ts`. One Worker per tab (spawned
+ * lazily, on first use, not at module load - a page that never touches search shouldn't pay for booting
+ * the WASM module at all), shared across every mailbox `init()`-ed this session - the Worker itself keeps
+ * a per-mailbox connection map (see that file's own doc comment).
+ *
+ * `postMessage` has no native request/response pairing, so every call generates its own numeric `id` and
+ * this module correlates the eventual matching response via a pending-request map - the same shape the
+ * `__spike__` validation harness used during development, now the real thing.
+ */
+import type { ParsedSearchQuery } from "@rapidmx/react-shared/search/queryGrammar.js";
+import type {
+    Coverage,
+    IndexEntitiesParams,
+    InitParams,
+    LocalIndexRequest,
+    LocalIndexResponse,
+    LocalSearchPage,
+    RemoveEntityParams,
+    SearchParams,
+    SetBuildingParams,
+    SetWindowParams,
+} from "./localIndexWorker.js";
+import type { LocalIndexEntity } from "./localIndexSchema.js";
+
+let worker: Worker | undefined;
+let nextRequestId = 1;
+const pending = new Map<number, { resolve: (value: unknown) => void; reject: (err: Error) => void }>();
+
+/** Every mailboxUid `initLocalIndex()` has opened this session, not yet `destroyLocalIndex()`-ed - lets
+ * `destroyAllLocalIndexes()` (called from `AppShell.tsx`'s sign-out, which has no mailboxUid of its own
+ * to pass - see that call site's own comment) destroy every open index without needing one threaded
+ * through. Mirrors `keySession.ts`'s own module-level `sessions` map in spirit - session-scoped,
+ * intentionally never persisted. */
+const initializedMailboxes = new Set<string>();
+
+function getWorker(): Worker {
+    if (!worker) {
+        worker = new Worker(new URL("./localIndexWorker.ts", import.meta.url), { type: "module" });
+        worker.addEventListener("message", (event: MessageEvent<LocalIndexResponse>) => {
+            const entry = pending.get(event.data.id);
+            if (!entry) {
+                return;
+            }
+            pending.delete(event.data.id);
+            if (event.data.ok) {
+                entry.resolve(event.data.result);
+            } else {
+                entry.reject(new Error(event.data.error));
+            }
+        });
+    }
+    return worker;
+}
+
+function call<T>(method: LocalIndexRequest["method"], params?: unknown): Promise<T> {
+    const id = nextRequestId++;
+    return new Promise<T>((resolve, reject) => {
+        pending.set(id, { resolve: resolve as (value: unknown) => void, reject });
+        getWorker().postMessage({ id, method, params } satisfies LocalIndexRequest);
+    });
+}
+
+export async function initLocalIndex(params: InitParams): Promise<void> {
+    await call("init", params);
+    initializedMailboxes.add(params.mailboxUid);
+}
+
+export function indexLocalEntities(mailboxUid: string, entities: LocalIndexEntity[]): Promise<void> {
+    return call("indexEntities", { mailboxUid, entities } satisfies IndexEntitiesParams);
+}
+
+export function removeLocalEntity(mailboxUid: string, entityUid: string): Promise<void> {
+    return call("removeEntity", { mailboxUid, entityUid } satisfies RemoveEntityParams);
+}
+
+export function searchLocal(mailboxUid: string, parsed: ParsedSearchQuery, limit: number, offset = 0): Promise<LocalSearchPage> {
+    return call("search", { mailboxUid, parsed, limit, offset } satisfies SearchParams);
+}
+
+export function getLocalCoverage(mailboxUid: string): Promise<Coverage> {
+    return call("coverage", mailboxUid);
+}
+
+export function setLocalIndexWindow(mailboxUid: string, timeFloorMonths: number, byteBudgetBytes: number): Promise<void> {
+    return call("setWindow", { mailboxUid, timeFloorMonths, byteBudgetBytes } satisfies SetWindowParams);
+}
+
+export function setLocalIndexBuilding(mailboxUid: string, building: boolean): Promise<void> {
+    return call("setBuilding", { mailboxUid, building } satisfies SetBuildingParams);
+}
+
+/** Destroys one mailbox's local index (both the SQLite connection and its on-disk OPFS storage) - spec
+ * §11 "MUST be destroyed on the same events that destroy private keys." Never throws: called from
+ * lifecycle hooks (idle timeout, logout, the manual "destroy keys now" button) where a destroy failure
+ * shouldn't block the key-destruction it's piggybacking on. */
+export async function destroyLocalIndex(mailboxUid: string): Promise<void> {
+    try {
+        await call("destroy", mailboxUid);
+    } catch {
+        // Best-effort - see this function's own doc comment.
+    } finally {
+        initializedMailboxes.delete(mailboxUid);
+    }
+}
+
+/** Destroys every mailbox's local index this session has opened - for a caller (`AppShell.tsx`'s
+ * sign-out) that has no specific mailboxUid of its own, the same "clear everything" shape
+ * `destroyUnlockedKeys()` itself offers when called with no argument. */
+export async function destroyAllLocalIndexes(): Promise<void> {
+    await Promise.all([...initializedMailboxes].map((mailboxUid) => destroyLocalIndex(mailboxUid)));
+}