@tavrn/e2ee 0.0.0-stage → 0.2.1

package/src/search/backend.ts

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Storage backend of the local search index: three key-value stores of opaque strings to opaque bytes.
+ * The index seals every value and derives every key with HMAC before it reaches the backend, so a
+ * backend never sees plaintext. Implementations: {@link MemorySearchBackend} (tests, tools), the
+ * IndexedDB backend of the web client (tavrn-web `src/search/idbBackend.ts`) and, later (phase 6), a SQLite
+ * backend of the Tauri app. Keep the interface minimal so that all of them stay simple; the shared
+ * behaviour is pinned by `backendContract` (`@tavrn/e2ee/search-contract`).
+ */
+
+export type SearchStore = "docs" | "postings" | "meta";
+
+export const SEARCH_STORES: readonly SearchStore[] = ["docs", "postings", "meta"];
+
+export interface SearchWrite {
+  store: SearchStore;
+  key: string;
+  /** null deletes the record. */
+  value: Uint8Array | null;
+}
+
+export interface SearchBackend {
+  get(store: SearchStore, key: string): Promise<Uint8Array | null>;
+  /** One result per key, in the order of `keys`; null for a missing record. */
+  getMany(store: SearchStore, keys: string[]): Promise<(Uint8Array | null)[]>;
+  /** Applies all writes atomically where the backend can (one IndexedDB transaction); null deletes. */
+  write(batch: SearchWrite[]): Promise<void>;
+  /** Every key of a store (meta and maintenance only; never needed on the search path). */
+  keys(store: SearchStore): Promise<string[]>;
+  /** Sum of value byte lengths (stats). */
+  size(): Promise<number>;
+  clear(): Promise<void>;
+}
+
+/** A {@link SearchBackend} in process memory. Values are copied on write and on read. */
+export class MemorySearchBackend implements SearchBackend {
+  private readonly stores = new Map<SearchStore, Map<string, Uint8Array>>(SEARCH_STORES.map((s) => [s, new Map()]));
+
+  private store(store: SearchStore): Map<string, Uint8Array> {
+    const m = this.stores.get(store);
+    if (!m) throw new Error(`unknown search store ${String(store)}`);
+    return m;
+  }
+
+  async get(store: SearchStore, key: string): Promise<Uint8Array | null> {
+    return this.store(store).get(key)?.slice() ?? null;
+  }
+
+  async getMany(store: SearchStore, keys: string[]): Promise<(Uint8Array | null)[]> {
+    const m = this.store(store);
+    return keys.map((k) => m.get(k)?.slice() ?? null);
+  }
+
+  async write(batch: SearchWrite[]): Promise<void> {
+    const copies = batch.map((w) => ({ m: this.store(w.store), key: w.key, value: w.value?.slice() ?? null }));
+    for (const w of copies) {
+      if (w.value) w.m.set(w.key, w.value);
+      else w.m.delete(w.key);
+    }
+  }
+
+  async keys(store: SearchStore): Promise<string[]> {
+    return [...this.store(store).keys()];
+  }
+
+  async size(): Promise<number> {
+    let n = 0;
+    for (const m of this.stores.values()) for (const v of m.values()) n += v.byteLength;
+    return n;
+  }
+
+  async clear(): Promise<void> {
+    for (const m of this.stores.values()) m.clear();
+  }
+
+  /** Every record (copies), for tests that inspect what is stored at rest. */
+  dump(): { store: SearchStore; key: string; value: Uint8Array }[] {
+    const out: { store: SearchStore; key: string; value: Uint8Array }[] = [];
+    for (const [store, m] of this.stores) for (const [key, value] of m) out.push({ store, key, value: value.slice() });
+    return out;
+  }
+}

package/src/search/contract.ts

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * The behaviour every {@link SearchBackend} must have, as a Vitest `describe` block. Exported from
+ * `@tavrn/e2ee/search-contract` (not from the main entry, which must not import Vitest) and run against
+ * every implementation: `backendContract("memory", () => new MemorySearchBackend())`.
+ */
+import { describe, expect, it } from "vitest";
+import type { SearchBackend, SearchWrite } from "./backend";
+
+const b = (...v: number[]) => new Uint8Array(v);
+
+export function backendContract(name: string, make: () => SearchBackend | Promise<SearchBackend>): void {
+  describe(`search backend contract: ${name}`, () => {
+    it("puts, reads and deletes records through write()", async () => {
+      const be = await make();
+      expect(await be.get("docs", "a")).toBeNull();
+      await be.write([{ store: "docs", key: "a", value: b(1, 2, 3) }]);
+      expect(Array.from((await be.get("docs", "a"))!)).toEqual([1, 2, 3]);
+      await be.write([{ store: "docs", key: "a", value: b(4) }]);
+      expect(Array.from((await be.get("docs", "a"))!)).toEqual([4]);
+      await be.write([{ store: "docs", key: "a", value: null }]);
+      expect(await be.get("docs", "a")).toBeNull();
+      // Deleting a missing record is not an error.
+      await be.write([{ store: "docs", key: "missing", value: null }]);
+    });
+
+    it("keeps the stores apart", async () => {
+      const be = await make();
+      await be.write([
+        { store: "docs", key: "k", value: b(1) },
+        { store: "postings", key: "k", value: b(2) },
+        { store: "meta", key: "k", value: b(3) },
+      ]);
+      expect(Array.from((await be.get("docs", "k"))!)).toEqual([1]);
+      expect(Array.from((await be.get("postings", "k"))!)).toEqual([2]);
+      expect(Array.from((await be.get("meta", "k"))!)).toEqual([3]);
+      await be.write([{ store: "postings", key: "k", value: null }]);
+      expect(await be.get("postings", "k")).toBeNull();
+      expect(await be.get("docs", "k")).not.toBeNull();
+    });
+
+    it("getMany keeps the order of the keys and returns null for misses", async () => {
+      const be = await make();
+      await be.write([
+        { store: "postings", key: "x", value: b(1) },
+        { store: "postings", key: "z", value: b(3) },
+      ]);
+      const got = await be.getMany("postings", ["z", "nope", "x", "z"]);
+      expect(got.map((v) => (v ? Array.from(v) : null))).toEqual([[3], null, [1], [3]]);
+      expect(await be.getMany("postings", [])).toEqual([]);
+    });
+
+    it("lists the keys of a store", async () => {
+      const be = await make();
+      await be.write([
+        { store: "meta", key: "m1", value: b(1) },
+        { store: "meta", key: "m2", value: b(2) },
+        { store: "docs", key: "d1", value: b(3) },
+      ]);
+      expect((await be.keys("meta")).sort()).toEqual(["m1", "m2"]);
+      expect(await be.keys("docs")).toEqual(["d1"]);
+      expect(await be.keys("postings")).toEqual([]);
+    });
+
+    it("size() sums the value lengths of all stores", async () => {
+      const be = await make();
+      expect(await be.size()).toBe(0);
+      await be.write([
+        { store: "docs", key: "a", value: new Uint8Array(100) },
+        { store: "postings", key: "b", value: new Uint8Array(20) },
+        { store: "meta", key: "c", value: new Uint8Array(3) },
+      ]);
+      expect(await be.size()).toBe(123);
+      await be.write([{ store: "docs", key: "a", value: null }]);
+      expect(await be.size()).toBe(23);
+    });
+
+    it("clear() empties every store", async () => {
+      const be = await make();
+      await be.write([
+        { store: "docs", key: "a", value: b(1) },
+        { store: "postings", key: "b", value: b(2) },
+        { store: "meta", key: "c", value: b(3) },
+      ]);
+      await be.clear();
+      for (const s of ["docs", "postings", "meta"] as const) expect(await be.keys(s)).toEqual([]);
+      expect(await be.size()).toBe(0);
+      expect(await be.get("docs", "a")).toBeNull();
+    });
+
+    it("applies a batch as a whole: every value is visible once write() resolves, the last write of a key wins", async () => {
+      const be = await make();
+      const batch: SearchWrite[] = Array.from({ length: 300 }, (_, i) => ({ store: "postings", key: `k${i}`, value: b(i % 256) }));
+      batch.push({ store: "postings", key: "k0", value: b(9, 9) });
+      batch.push({ store: "postings", key: "k1", value: null });
+      await be.write(batch);
+      const got = await be.getMany("postings", batch.slice(0, 300).map((w) => w.key));
+      expect(got.filter((v) => v !== null)).toHaveLength(299);
+      expect(Array.from(got[0]!)).toEqual([9, 9]);
+      expect(got[1]).toBeNull();
+      expect(Array.from(got[299]!)).toEqual([299 % 256]);
+    });
+
+    it("copies values: changing the input or a result afterwards does not change the stored value", async () => {
+      const be = await make();
+      const v = b(1, 2, 3);
+      await be.write([{ store: "docs", key: "a", value: v }]);
+      v[0] = 99;
+      const got = (await be.get("docs", "a"))!;
+      expect(Array.from(got)).toEqual([1, 2, 3]);
+      got[1] = 77;
+      expect(Array.from((await be.get("docs", "a"))!)).toEqual([1, 2, 3]);
+      const [many] = await be.getMany("docs", ["a"]);
+      many![2] = 55;
+      expect(Array.from((await be.get("docs", "a"))!)).toEqual([1, 2, 3]);
+    });
+
+    it("handles arbitrary string keys", async () => {
+      const be = await make();
+      const keys = ["", "a:b", "ü/ß\u0000x", "0123456789abcdef0123456789abcdef"];
+      await be.write(keys.map((key, i) => ({ store: "meta" as const, key, value: b(i) })));
+      expect((await be.getMany("meta", keys)).map((v) => (v ? v[0] : null))).toEqual([0, 1, 2, 3]);
+      expect((await be.keys("meta")).sort()).toEqual([...keys].sort());
+    });
+  });
+}

package/src/search/index.ts

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: MPL-2.0
+/** The local encrypted search index (design note 4.4 "Search"). The backend contract test lives in `@tavrn/e2ee/search-contract`. */
+export * from "./tokenize";
+export * from "./keys";
+export * from "./backend";
+export * from "./searchIndex";

package/src/search/keys.ts

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Keys of the local search index. Two non-extractable WebCrypto keys are derived from the device's
+ * local storage key (ENCRYPTION.md §2.1) with HKDF-SHA-256: an HMAC key that turns every record name
+ * (message ids, conversation ids, lookup keys) into an opaque token, and an AES-256-GCM key that seals
+ * every record value. A stolen index store reveals record counts and sizes, nothing else.
+ */
+import { localStorageKey, type KeyStore } from "../keystore";
+
+export interface SearchKeys {
+  /** HMAC-SHA-256 key of the token keys (record names). */
+  mac: CryptoKey;
+  /** AES-256-GCM key of the record values. */
+  enc: CryptoKey;
+}
+
+/** Thrown while the key store (or the index, after `lock()`) is locked. */
+export class SearchLockedError extends Error {
+  override name = "search_locked";
+  constructor() {
+    super("The local search index is locked");
+  }
+}
+
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+function subtle(): SubtleCrypto {
+  const s = globalThis.crypto?.subtle;
+  if (!s) throw new Error("WebCrypto is unavailable");
+  return s;
+}
+
+function bytes(s: string): Uint8Array<ArrayBuffer> {
+  return enc.encode(s);
+}
+
+/**
+ * HKDF-SHA-256 (salt = 32 zero bytes) of the local key: info "tavrn search index v1 mac" → HMAC-SHA-256
+ * key, info "tavrn search index v1 enc" → AES-GCM-256 key. Both non-extractable.
+ */
+export async function deriveSearchKeys(localKey: Uint8Array): Promise<SearchKeys> {
+  const s = subtle();
+  const ikm = await s.importKey("raw", localKey as Uint8Array<ArrayBuffer>, "HKDF", false, ["deriveKey"]);
+  const salt = new Uint8Array(32);
+  const [mac, aes] = await Promise.all([
+    s.deriveKey(
+      { name: "HKDF", hash: "SHA-256", salt, info: bytes("tavrn search index v1 mac") },
+      ikm,
+      { name: "HMAC", hash: "SHA-256", length: 256 },
+      false,
+      ["sign"],
+    ),
+    s.deriveKey(
+      { name: "HKDF", hash: "SHA-256", salt, info: bytes("tavrn search index v1 enc") },
+      ikm,
+      { name: "AES-GCM", length: 256 },
+      false,
+      ["encrypt", "decrypt"],
+    ),
+  ]);
+  return { mac, enc: aes };
+}
+
+/** The search keys of the open account of `store`; throws {@link SearchLockedError} while it is locked. */
+export async function searchKeysFromStore(store: KeyStore): Promise<SearchKeys> {
+  if (!store.isUnlocked()) throw new SearchLockedError();
+  const master = store.masterSecret();
+  let local: Uint8Array | null = null;
+  try {
+    local = await localStorageKey(master, store.deviceId());
+    return await deriveSearchKeys(local);
+  } finally {
+    master.fill(0);
+    local?.fill(0);
+  }
+}
+
+const HEX = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"));
+
+/** The token key of a record name: hex(HMAC(mac, parts joined by NUL)), first 32 hex digits (128 bits). */
+export async function tokenKey(keys: SearchKeys, ...parts: string[]): Promise<string> {
+  const sig = new Uint8Array(await subtle().sign("HMAC", keys.mac, bytes(parts.join("\u0000"))));
+  let out = "";
+  for (let i = 0; i < 16; i++) out += HEX[sig[i]!];
+  return out;
+}
+
+/** iv (12 bytes) || AES-GCM(JSON of `value`), bound to `aad` (store name + NUL + record key). */
+export async function seal(keys: SearchKeys, aad: string, value: unknown): Promise<Uint8Array> {
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(12));
+  const ct = await subtle().encrypt({ name: "AES-GCM", iv, additionalData: bytes(aad) }, keys.enc, bytes(JSON.stringify(value)));
+  const out = new Uint8Array(12 + ct.byteLength);
+  out.set(iv);
+  out.set(new Uint8Array(ct), 12);
+  return out;
+}
+
+/** Opens a value of {@link seal}; throws if the key, the aad or the bytes do not match. */
+export async function open<T>(keys: SearchKeys, aad: string, sealed: Uint8Array): Promise<T> {
+  if (sealed.length < 12 + 16) throw new Error("sealed search record too short");
+  const plain = await subtle().decrypt(
+    { name: "AES-GCM", iv: sealed.slice(0, 12), additionalData: bytes(aad) },
+    keys.enc,
+    sealed.slice(12),
+  );
+  return JSON.parse(dec.decode(plain)) as T;
+}