@tavrn/e2ee 0.0.0-stage → 0.2.1

package/src/tabs.ts

@@ -0,0 +1,367 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Coordination of one MLS state between the tabs of a browser profile (they share one IndexedDB store).
+ *
+ * One tab **owns** the state: it holds a Web Lock (`navigator.locks`) named per node and account, runs every
+ * state-changing operation and alone writes the client state. The other tabs keep a read-only copy (loaded from the
+ * store) for synchronous reads and decryption, and **forward** their state-changing operations to the owner over a
+ * BroadcastChannel of the same name (request and response with ids, a timeout per request). The owner announces
+ * every write (`state`: copies reload before they read again) and the events the views need (`event`).
+ *
+ * **Hand-over:** when the owner tab closes (or signs out) the browser releases its lock and the next waiting tab gets
+ * it; that tab reloads the state from the store before it runs anything, then announces itself (`owner`). Requests
+ * in flight are sent once more, to the new owner (a tab that becomes the owner runs its own ones itself); a request
+ * that loses its owner a second time fails with `MlsError("owner_unavailable")`, like one that gets no answer
+ * within the timeout. Every forwarded operation can run twice without harm (joins and catch-ups are idempotent, a
+ * second commit is just one more epoch, an encryption whose result never arrived was never sent).
+ *
+ * Without Web Locks or BroadcastChannel (or in a single process such as a bot) there is no coordination: the
+ * manager works alone, as before (a second tab may then overwrite the state and rejoin after an invalid commit).
+ */
+import { TavrnApiError, type ProblemDetails } from "@tavrn/sdk";
+import { MlsError } from "./mls";
+
+/** The subset of the Web Locks API (`navigator.locks`) the election needs. */
+export interface TabLockManager {
+  request(name: string, options: { ifAvailable?: boolean; signal?: AbortSignal }, callback: (lock: unknown) => Promise<unknown>): Promise<unknown>;
+}
+
+/** The subset of `BroadcastChannel` the forwarding needs. */
+export interface TabChannel {
+  postMessage(message: unknown): void;
+  onmessage: ((e: { data: unknown }) => void) | null;
+  close(): void;
+}
+
+export interface TabOptions {
+  /**
+   * Lock and channel name, the same in every tab that shares the state: per node and account (and device), e.g.
+   * `tavrn-mls|<home node origin>|<address>/<device id>`.
+   */
+  name: string;
+  /** Default `navigator.locks` where available; null (or none available) = no coordination. */
+  locks?: TabLockManager | null;
+  /** Default `new BroadcastChannel(name)` where available; null (or none available) = no coordination. */
+  channel?: ((name: string) => TabChannel) | null;
+  /** How long a forwarded operation may take before it fails with `owner_unavailable` (default 30 s). */
+  timeoutMs?: number;
+}
+
+/** What the coordination needs from the tab (implemented by `openMlsManager`). */
+export interface TabHost {
+  /** Runs an operation in this tab, which owns the state (its own forwarded calls, or another tab's). */
+  serve(method: string, args: unknown[]): Promise<unknown>;
+  /** This tab got the lock after another owner left: load the stored state before anything runs here. */
+  takeOver(): Promise<void>;
+  /** The owner wrote the state: reload the copy before reading it again. */
+  stale(): void;
+  /** An event of the owner's manager, for this tab's views. */
+  event(e: unknown): void;
+}
+
+export const TAB_TIMEOUT_MS = 30_000;
+/** Request ids a new owner remembers to serve a request only once (a re-send may cross its announcement). */
+const SERVED_WINDOW = 1024;
+
+interface WireError {
+  name: string;
+  message: string;
+  code?: string;
+  problem?: ProblemDetails;
+}
+
+type Message =
+  | { v: 1; t: "req"; id: string; from: string; method: string; args: unknown[] }
+  | { v: 1; t: "res"; id: string; to: string; ok: true; value: unknown }
+  | { v: 1; t: "res"; id: string; to: string; ok: false; error: WireError }
+  | { v: 1; t: "owner"; from: string }
+  | { v: 1; t: "state"; from: string }
+  | { v: 1; t: "event"; from: string; event: unknown };
+
+interface Pending {
+  id: string;
+  method: string;
+  args: unknown[];
+  resolve(v: unknown): void;
+  reject(e: unknown): void;
+  timer: ReturnType<typeof setTimeout> | null;
+  /** Sent once more after its owner left (or run here after this tab took over). */
+  retried: boolean;
+}
+
+function defaultLocks(): TabLockManager | null {
+  const locks = (globalThis as { navigator?: { locks?: TabLockManager } }).navigator?.locks;
+  return locks && typeof locks.request === "function" ? locks : null;
+}
+
+function defaultChannel(): ((name: string) => TabChannel) | null {
+  const BC = (globalThis as { BroadcastChannel?: new (name: string) => TabChannel }).BroadcastChannel;
+  return typeof BC === "function" ? (name) => new BC(name) : null;
+}
+
+function randomId(): string {
+  const bytes = new Uint8Array(12);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+const unavailable = () => new MlsError("owner_unavailable");
+
+function toWire(e: unknown): WireError {
+  if (e instanceof TavrnApiError) return { name: "TavrnApiError", message: e.message, problem: JSON.parse(JSON.stringify(e.problem)) as ProblemDetails };
+  if (e instanceof MlsError) return { name: "MlsError", message: e.message, code: e.code };
+  if (e instanceof Error) return { name: e.name, message: e.message };
+  return { name: "Error", message: String(e) };
+}
+
+function fromWire(w: WireError): Error {
+  if (w.name === "TavrnApiError" && w.problem) return new TavrnApiError(w.problem);
+  if (w.name === "MlsError" && w.code) return new MlsError(w.code as MlsError["code"]);
+  const e = new Error(w.message);
+  e.name = w.name;
+  return e;
+}
+
+function isMessage(m: unknown): m is Message {
+  if (!m || typeof m !== "object") return false;
+  const o = m as Record<string, unknown>;
+  if (o.v !== 1) return false;
+  switch (o.t) {
+    case "req":
+      return typeof o.id === "string" && typeof o.from === "string" && typeof o.method === "string" && Array.isArray(o.args);
+    case "res":
+      return typeof o.id === "string" && typeof o.to === "string" && typeof o.ok === "boolean" && (o.ok || (!!o.error && typeof o.error === "object"));
+    case "owner":
+    case "state":
+      return typeof o.from === "string";
+    case "event":
+      return typeof o.from === "string" && "event" in o;
+    default:
+      return false;
+  }
+}
+
+export class TabCoordinator {
+  private readonly id = randomId();
+  private seq = 0;
+  private holds = false;
+  private serving = false;
+  private closed = false;
+  /** Resolves when this tab may run operations after a take-over (null while it is not taking over). */
+  private takingOver: Promise<void> | null = null;
+  private readonly pending = new Map<string, Pending>();
+  private readonly served = new Set<string>();
+  private readonly abort = new AbortController();
+  private release: () => void = () => undefined;
+  private readonly held = new Promise<void>((r) => (this.release = r));
+
+  private constructor(
+    private readonly opts: { name: string; locks: TabLockManager; timeoutMs: number },
+    private readonly channel: TabChannel,
+    private readonly host: TabHost,
+  ) {
+    channel.onmessage = (e) => this.receive(e.data);
+  }
+
+  /**
+   * Joins the coordination of `opts.name`: resolves once it is known whether this tab owns the state right now.
+   * Null when the browser lacks Web Locks or BroadcastChannel (the caller works alone, as before).
+   */
+  static async open(opts: TabOptions, host: TabHost): Promise<TabCoordinator | null> {
+    const locks = opts.locks === undefined ? defaultLocks() : opts.locks;
+    const makeChannel = opts.channel === undefined ? defaultChannel() : opts.channel;
+    if (!locks || !makeChannel) return null;
+    let channel: TabChannel;
+    try {
+      channel = makeChannel(opts.name);
+    } catch {
+      return null;
+    }
+    const tabs = new TabCoordinator({ name: opts.name, locks, timeoutMs: opts.timeoutMs ?? TAB_TIMEOUT_MS }, channel, host);
+    try {
+      await tabs.elect();
+    } catch {
+      tabs.close();
+      return null;
+    }
+    return tabs;
+  }
+
+  /** Whether this tab holds the lock (it may still be reloading the state after a take-over). */
+  get owner(): boolean {
+    return this.holds && !this.closed;
+  }
+
+  /** Whether this tab runs operations itself right now: it owns the state and has loaded it. */
+  get ready(): boolean {
+    return this.serving && !this.closed;
+  }
+
+  private elect(): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      this.opts.locks
+        .request(this.opts.name, { ifAvailable: true }, async (lock) => {
+          if (!lock) {
+            // Another tab owns the state: wait for the lock (hand-over) and forward until then.
+            this.wait();
+            resolve();
+            return;
+          }
+          this.holds = true;
+          this.serving = true;
+          resolve();
+          await this.held;
+        })
+        .catch(reject);
+    });
+  }
+
+  /** Queues for the lock: granted when the owner tab closes. */
+  private wait() {
+    this.opts.locks
+      .request(this.opts.name, { signal: this.abort.signal }, async () => {
+        if (this.closed) return;
+        this.holds = true;
+        this.takingOver = this.host.takeOver();
+        try {
+          await this.takingOver;
+        } catch {
+          // The state cannot be loaded here (locked meanwhile): leave the lock to the next tab.
+          this.close();
+          return;
+        }
+        this.takingOver = null;
+        this.serving = true;
+        this.post({ v: 1, t: "owner", from: this.id });
+        this.retryPending(true);
+        await this.held;
+      })
+      .catch(() => undefined);
+  }
+
+  /**
+   * Runs `method` in the owner tab: here when this tab owns the state (after a take-over has loaded it), otherwise
+   * forwarded. Fails with `MlsError("owner_unavailable")` without an answer in time or after losing two owners.
+   */
+  call(method: string, args: unknown[]): Promise<unknown> {
+    if (this.closed) return Promise.reject(unavailable());
+    if (this.serving) return this.serve(method, args);
+    if (this.holds && this.takingOver) return this.takingOver.then(() => this.serve(method, args));
+    return new Promise((resolve, reject) => {
+      const p: Pending = { id: `${this.id}:${++this.seq}`, method, args, resolve, reject, timer: null, retried: false };
+      this.pending.set(p.id, p);
+      this.send(p);
+    });
+  }
+
+  /** Owner: the stored state changed (the other tabs reload their copies). */
+  notifyState(): void {
+    if (this.ready) this.post({ v: 1, t: "state", from: this.id });
+  }
+
+  /** Owner: an event the other tabs' views need. */
+  notifyEvent(event: unknown): void {
+    if (this.ready) this.post({ v: 1, t: "event", from: this.id, event });
+  }
+
+  /** Leaves the coordination: releases the lock (the next tab takes over) and fails the calls in flight. */
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.release();
+    this.abort.abort();
+    for (const p of this.pending.values()) this.settle(p, unavailable(), false);
+    this.channel.onmessage = null;
+    try {
+      this.channel.close();
+    } catch {
+      /* already closed */
+    }
+  }
+
+  private serve(method: string, args: unknown[]): Promise<unknown> {
+    return Promise.resolve().then(() => this.host.serve(method, args));
+  }
+
+  /** Answers a request; a result the channel cannot clone becomes an error (the caller does not wait for nothing). */
+  private respond(id: string, to: string, value: unknown) {
+    if (this.closed) return;
+    try {
+      this.channel.postMessage({ v: 1, t: "res", id, to, ok: true, value } satisfies Message);
+    } catch (e) {
+      this.post({ v: 1, t: "res", id, to, ok: false, error: toWire(e) });
+    }
+  }
+
+  private post(m: Message) {
+    if (this.closed) return;
+    try {
+      this.channel.postMessage(m);
+    } catch {
+      /* closed channel: the timeouts take care of the calls */
+    }
+  }
+
+  private send(p: Pending) {
+    if (p.timer) clearTimeout(p.timer);
+    p.timer = setTimeout(() => this.settle(p, unavailable(), false), this.opts.timeoutMs);
+    this.post({ v: 1, t: "req", id: p.id, from: this.id, method: p.method, args: p.args });
+  }
+
+  private settle(p: Pending, value: unknown, ok: boolean) {
+    if (!this.pending.delete(p.id)) return;
+    if (p.timer) clearTimeout(p.timer);
+    if (ok) p.resolve(value);
+    else p.reject(value);
+  }
+
+  /** After a hand-over: every call in flight once more (here when this tab is the new owner); twice fails. */
+  private retryPending(here: boolean) {
+    for (const p of [...this.pending.values()]) {
+      if (p.retried) {
+        this.settle(p, unavailable(), false);
+        continue;
+      }
+      p.retried = true;
+      if (here) {
+        this.pending.delete(p.id);
+        if (p.timer) clearTimeout(p.timer);
+        this.serve(p.method, p.args).then(p.resolve, p.reject);
+      } else {
+        this.send(p);
+      }
+    }
+  }
+
+  private receive(data: unknown) {
+    if (this.closed || !isMessage(data)) return;
+    switch (data.t) {
+      case "req":
+        if (!this.serving || this.served.has(data.id)) return;
+        this.served.add(data.id);
+        if (this.served.size > SERVED_WINDOW) this.served.delete(this.served.values().next().value as string);
+        this.serve(data.method, data.args).then(
+          (value) => this.respond(data.id, data.from, value),
+          (e: unknown) => this.post({ v: 1, t: "res", id: data.id, to: data.from, ok: false, error: toWire(e) }),
+        );
+        return;
+      case "res": {
+        if (data.to !== this.id) return;
+        const p = this.pending.get(data.id);
+        if (!p) return;
+        if (data.ok) this.settle(p, data.value, true);
+        else this.settle(p, fromWire(data.error), false);
+        return;
+      }
+      case "owner":
+        if (!this.holds) this.retryPending(false);
+        return;
+      case "state":
+        if (!this.holds) this.host.stale();
+        return;
+      case "event":
+        if (!this.holds) this.host.event(data.event);
+        return;
+    }
+  }
+}

package/src/trust.ts

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * The trust record of an account (ENCRYPTION.md §7 "Trust record"): the pinned identity keys of other users (§3.3),
+ * the verified contacts (FEDERATION.md §10.2) and the account's own devices this account attested (device id → device
+ * key, §4.7). It is kept in the local store and, encrypted under the backup key, as a backup blob on the home node, so
+ * that it survives a sign-out and reaches every device of the account: a contact's key that changed while the user
+ * was signed out still raises the "security key changed" warning, and only a device key the account attested itself
+ * is ever attested again as retired.
+ *
+ * ```text
+ * blob      = 0x01 || nonce(12) || AES-256-GCM(backup_key, nonce, aad, plaintext)
+ * aad       = "tavrn trust v1" || 0x00 || account address
+ * plaintext = {"v":1,"pins":{…},"verified":{…},"devices":{"<device id>":"<base64url device key>"}}
+ * ```
+ *
+ * Path: `PUT /users/me/backups/<home domain>/00000000000000000000000000` (the ULID of time 0, never a conversation).
+ * The node cannot read or forge it; at worst it serves an older blob or none (entries merge, nothing is replaced).
+ */
+import { b64urlDecode } from "@tavrn/sdk";
+import type { Pin, VerifiedContact } from "./mls";
+
+/** The conversation ULID under which the trust record is stored as a backup (time 0, no conversation has it). */
+export const TRUST_BACKUP_ULID = "00000000000000000000000000";
+
+export interface TrustRecord {
+  pins: Record<string, Pin>;
+  verified: Record<string, VerifiedContact>;
+  /** Own devices attested by this account: device id → base64url device key. */
+  devices: Record<string, string>;
+}
+
+function aad(account: string): Uint8Array<ArrayBuffer> {
+  return new TextEncoder().encode(`tavrn trust v1\u0000${account}`);
+}
+
+async function aesKey(backupKey: Uint8Array, usage: KeyUsage): Promise<CryptoKey> {
+  return globalThis.crypto.subtle.importKey("raw", backupKey as Uint8Array<ArrayBuffer>, { name: "AES-GCM" }, false, [usage]);
+}
+
+/** Encrypts a trust record of `account` under the backup key. */
+export async function sealTrust(backupKey: Uint8Array, account: string, record: TrustRecord): Promise<Uint8Array> {
+  const nonce = globalThis.crypto.getRandomValues(new Uint8Array(12));
+  const plain = new TextEncoder().encode(JSON.stringify({ v: 1, pins: record.pins, verified: record.verified, devices: record.devices }));
+  const ct = new Uint8Array(await globalThis.crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce, additionalData: aad(account) }, await aesKey(backupKey, "encrypt"), plain));
+  const out = new Uint8Array(1 + 12 + ct.length);
+  out[0] = 1;
+  out.set(nonce, 1);
+  out.set(ct, 13);
+  return out;
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+
+/** Decrypts and checks a trust record of `account`; null when it does not open or is malformed. */
+export async function openTrust(backupKey: Uint8Array, account: string, blob: Uint8Array): Promise<TrustRecord | null> {
+  if (blob.length < 1 + 12 + 16 || blob[0] !== 1) return null;
+  let plain: ArrayBuffer;
+  try {
+    plain = await globalThis.crypto.subtle.decrypt(
+      { name: "AES-GCM", iv: blob.slice(1, 13), additionalData: aad(account) },
+      await aesKey(backupKey, "decrypt"),
+      blob.slice(13),
+    );
+  } catch {
+    return null;
+  }
+  let v: unknown;
+  try {
+    v = JSON.parse(new TextDecoder().decode(plain));
+  } catch {
+    return null;
+  }
+  if (!isObject(v) || v.v !== 1 || !isObject(v.pins) || !isObject(v.verified) || !isObject(v.devices)) return null;
+  const pins: Record<string, Pin> = {};
+  for (const [a, p] of Object.entries(v.pins)) {
+    if (!isObject(p) || typeof p.key !== "string") continue;
+    pins[a] = { key: p.key, ...(p.changed === true ? { changed: true } : {}), ...(p.rotated === true ? { rotated: true } : {}) };
+  }
+  const verified: Record<string, VerifiedContact> = {};
+  for (const [a, c] of Object.entries(v.verified)) {
+    if (!isObject(c) || c.address !== a || typeof c.identity_public_key !== "string" || typeof c.verified_at !== "string") continue;
+    if (c.method !== "qr" && c.method !== "numeric") continue;
+    verified[a] = {
+      address: a,
+      identity_public_key: c.identity_public_key,
+      verified_at: c.verified_at,
+      method: c.method,
+      ...(typeof c.rotated_to === "string" ? { rotated_to: c.rotated_to } : {}),
+      ...(c.refresh_dismissed === true ? { refresh_dismissed: true } : {}),
+    };
+  }
+  const devices: Record<string, string> = {};
+  for (const [d, k] of Object.entries(v.devices)) {
+    if (typeof k !== "string") continue;
+    try {
+      if (b64urlDecode(k).length === 32) devices[d] = k;
+    } catch {
+      /* malformed entry */
+    }
+  }
+  return { pins, verified, devices };
+}
+
+/**
+ * Adds what `from` has and `into` lacks (in place); entries `into` has stay as they are. Verified contacts named in
+ * `removed` (removed on this device, not uploaded yet) are not taken over. True when `into` changed.
+ */
+export function mergeTrust(into: TrustRecord, from: TrustRecord, removed: ReadonlySet<string> = new Set()): boolean {
+  let changed = false;
+  for (const [a, p] of Object.entries(from.pins)) {
+    if (!into.pins[a]) {
+      into.pins[a] = p;
+      changed = true;
+    }
+  }
+  for (const [a, c] of Object.entries(from.verified)) {
+    if (!into.verified[a] && !removed.has(a)) {
+      into.verified[a] = c;
+      changed = true;
+    }
+  }
+  for (const [d, k] of Object.entries(from.devices)) {
+    if (!into.devices[d]) {
+      into.devices[d] = k;
+      changed = true;
+    }
+  }
+  return changed;
+}

package/src/wasm.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MPL-2.0
+import init, { initSync } from "@tavrn/crypto";
+
+let ready: Promise<void> | null = null;
+
+/** True in Node.js (also under jsdom test environments), false in browsers and workers. */
+function isNode(): boolean {
+  const p = (globalThis as { process?: { versions?: { node?: unknown } } }).process;
+  return typeof p?.versions?.node === "string";
+}
+
+/**
+ * Node.js: reads `tavrn_crypto_bg.wasm` from the installed `@tavrn/crypto` package and instantiates it
+ * synchronously. The Node built-ins are imported at run time under computed names, so that browser
+ * bundlers never try to resolve them.
+ */
+async function loadInNode(): Promise<void> {
+  const fsName = "node:fs/promises";
+  const moduleName = "node:module";
+  const { readFile } = (await import(/* @vite-ignore */ fsName)) as typeof import("node:fs/promises");
+  const { createRequire } = (await import(/* @vite-ignore */ moduleName)) as typeof import("node:module");
+  const path = createRequire(import.meta.url).resolve("@tavrn/crypto/tavrn_crypto_bg.wasm");
+  initSync({ module: await readFile(path) });
+}
+
+/**
+ * Loads and instantiates the WebAssembly module of `@tavrn/crypto` once, in browsers with `init()`
+ * (fetches the .wasm next to the module, which bundlers emit as an asset) and in Node.js from the
+ * package directory. Every function that uses the crypto package awaits this first. When the module was
+ * already initialized (e.g. by a test with `initSync`), this resolves immediately.
+ */
+export function ensureCrypto(): Promise<void> {
+  ready ??= (isNode() ? loadInNode() : init().then(() => undefined)).catch((e: unknown) => {
+    ready = null;
+    throw e;
+  });
+  return ready;
+}