@tavrn/e2ee 0.0.0-stage → 0.2.2

package/src/identity.ts

@@ -0,0 +1,216 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * The account's current identity key and its rotation with continuity (ENCRYPTION.md §2.1, §9a). Generation 0 is
+ * the key derived from the master secret; after a rotation the current key is a random one, kept in the key store
+ * as {@link IDENTITY_SEED} and on the home node wrapped under the master secret (`identity_blob`). Every device of
+ * the account follows the published key when the keys document's continuity chain leads to it from the derived key.
+ */
+import { IdentityKey, continuityKeys, continuityReaches, signContinuity, unwrapIdentityKey, verifyDeviceAttestation, wrapIdentityKey } from "@tavrn/crypto";
+import { TavrnApiError, b64urlDecode, b64urlEncode, type TavrnApi } from "@tavrn/sdk";
+import { E2eeError } from "./errors";
+import { withMasterSecret, type KeyStore } from "./keystore";
+import { ensureCrypto } from "./wasm";
+
+/** Name of the rotated identity key (32-byte seed) in the key store; absent at generation 0. */
+export const IDENTITY_SEED = "identity-seed";
+
+/** A continuity statement as the keys document carries it (base64url keys and signatures). */
+export interface ContinuityStatement {
+  old_key: string;
+  new_key: string;
+  at: string;
+  sig_old: string;
+  sig_new: string;
+}
+
+/** The parts of a keys document (`GET /users/{username}/keys`) the identity checks use. */
+export interface IdentityDocument {
+  identity_public_key?: string | null;
+  continuity?: ContinuityStatement[] | null;
+}
+
+/**
+ * Longest chain that is followed, as in the crypto core: a longer one (only a hostile node serves one) is not even
+ * serialized.
+ */
+export const MAX_CHAIN = 10_000;
+
+/** Is `to` reachable from `from` through valid, consecutive statements of `chain`? `true` for `from === to`. */
+export function chainReaches(chain: readonly ContinuityStatement[] | null | undefined, from: string, to: string): boolean {
+  if (from === to) return true;
+  if (!chain?.length || chain.length > MAX_CHAIN) return false;
+  return continuityReaches(JSON.stringify(chain), from, to);
+}
+
+/**
+ * The keys that lead to `current` through valid statements of `chain`, `current` included: attestations made under
+ * them (retired devices, ENCRYPTION.md §3.3) stay trustworthy after a rotation. One call into the crypto core, which
+ * verifies every statement at most once.
+ */
+export function chainKeys(chain: readonly ContinuityStatement[] | null | undefined, current: string): Set<string> {
+  if (!chain?.length || chain.length > MAX_CHAIN) return new Set([current]);
+  return new Set(continuityKeys(JSON.stringify(chain), current));
+}
+
+/** RFC 3339 time without fractions (the form the node checks against its clock). */
+export function rfc3339(ms: number): string {
+  return new Date(ms).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+/** Runs `fn` with the store's current identity key (the rotated one if present, else the derived one), freed afterwards. */
+export async function withIdentityKey<T>(store: KeyStore, fn: (key: IdentityKey) => T): Promise<T> {
+  await ensureCrypto();
+  const seed = await store.getSecret(IDENTITY_SEED);
+  let key: IdentityKey;
+  if (seed) {
+    try {
+      key = IdentityKey.fromBytes(seed);
+    } finally {
+      seed.fill(0);
+    }
+  } else {
+    key = withMasterSecret(store, (m) => IdentityKey.fromMaster(m));
+  }
+  try {
+    return fn(key);
+  } finally {
+    key.free();
+  }
+}
+
+/** The current identity public key of the open account (base64url). */
+export function ownIdentityPublicKey(store: KeyStore): Promise<string> {
+  return withIdentityKey(store, (k) => b64urlEncode(k.publicKey()));
+}
+
+/** The identity public key derived from the master secret (generation 0, base64url). */
+export function derivedIdentityKey(store: KeyStore): string {
+  return withMasterSecret(store, (m) => b64urlEncode(m.identityPublicKey()));
+}
+
+/**
+ * The rotated identity key (seed) that a master secret leads to for the published key, or null at generation 0
+ * (ENCRYPTION.md §2.4 client rules): the derived key equals the published key, or the chain reaches the published key
+ * from the derived one and the blob unwraps with the master secret to exactly that key. Anything else is
+ * `identity_mismatch`. The caller zeroes the returned seed.
+ */
+export async function resolveIdentity(
+  api: Pick<TavrnApi, "keys">,
+  doc: IdentityDocument,
+  derived: string,
+  unwrap: (blob: Uint8Array) => IdentityKey,
+): Promise<Uint8Array | null> {
+  const published = doc.identity_public_key ?? null;
+  if (!published || published === derived) return null;
+  if (!chainReaches(doc.continuity, derived, published)) throw new E2eeError("identity_mismatch");
+  let blob: string;
+  try {
+    blob = (await api.keys.identityBlob()).identity_blob;
+  } catch (e) {
+    if (e instanceof TavrnApiError && e.status === 404) throw new E2eeError("identity_mismatch");
+    throw e;
+  }
+  let key: IdentityKey;
+  try {
+    key = unwrap(b64urlDecode(blob));
+  } catch {
+    throw new E2eeError("identity_mismatch");
+  }
+  try {
+    if (b64urlEncode(key.publicKey()) !== published) throw new E2eeError("identity_mismatch");
+    return key.toBytes();
+  } finally {
+    key.free();
+  }
+}
+
+/**
+ * Brings the open store's identity key in line with the published one (another device rotated, ENCRYPTION.md §9a):
+ * `current` when nothing changed, `rotated` when the new key was taken over from the blob. Throws
+ * {@link E2eeError} `identity_mismatch` when the published key is not reachable from this master secret.
+ */
+export async function syncIdentity(
+  api: Pick<TavrnApi, "keys">,
+  store: KeyStore,
+  username: string,
+  address: string,
+  doc?: IdentityDocument,
+): Promise<"current" | "rotated"> {
+  await ensureCrypto();
+  if (!store.isUnlocked()) throw new E2eeError("locked");
+  const keys = doc ?? (await api.keys.get(username));
+  const published = keys.identity_public_key ?? null;
+  const own = await ownIdentityPublicKey(store);
+  if (!published || published === own) return "current";
+  const derived = derivedIdentityKey(store);
+  // Forward only: a device that already follows a rotated key accepts a newer key only when the chain leads to it
+  // from that key. Otherwise the home node could roll the device back to an older generation (whose key may be the
+  // compromised one the rotation retired) by serving the old chain and blob again.
+  if (own !== derived && !chainReaches(keys.continuity, own, published)) throw new E2eeError("identity_mismatch");
+  const seed = await resolveIdentity(api, keys, derived, (blob) => withMasterSecret(store, (m) => unwrapIdentityKey(m, blob, address)));
+  if (!seed) {
+    await store.deleteSecret(IDENTITY_SEED);
+    return "rotated";
+  }
+  try {
+    await store.putSecret(IDENTITY_SEED, seed);
+  } finally {
+    seed.fill(0);
+  }
+  return "rotated";
+}
+
+/** What a rotation needs from the API. */
+export interface RotationContext {
+  api: Pick<TavrnApi, "keys">;
+  username: string;
+  address: string;
+  store: KeyStore;
+  /** Clock (tests). */
+  now?: () => number;
+}
+
+/**
+ * Rotates the identity key with continuity (ENCRYPTION.md §9a): new random key, statement signed by the current and
+ * the new key, the new key wrapped under the master secret, every device of the keys document attested again. The
+ * node asks for a reauth token (`auth.reauth_required`; the web client confirms and repeats). Refuses with
+ * `rotation_devices` when a listed device does not verify under the current key (the document and the local state
+ * disagree) and with `identity_mismatch` when this device is not on the published key.
+ */
+export async function rotateIdentity(ctx: RotationContext): Promise<{ identity_public_key: string; identity_generation: number }> {
+  await ensureCrypto();
+  const { store, address } = ctx;
+  if (!store.isUnlocked()) throw new E2eeError("locked");
+  const doc = await ctx.api.keys.get(ctx.username);
+  const current = await ownIdentityPublicKey(store);
+  if (doc.identity_public_key !== current) throw new E2eeError("identity_mismatch");
+  const currentBytes = b64urlDecode(current);
+  const devices = doc.devices.map((d) => {
+    const key = b64urlDecode(d.device_public_key);
+    if (!verifyDeviceAttestation(address, d.device_id, key, b64urlDecode(d.identity_signature), currentBytes)) throw new E2eeError("rotation_devices");
+    return { id: d.device_id, key };
+  });
+  const fresh = IdentityKey.generate();
+  try {
+    const at = rfc3339(ctx.now?.() ?? Date.now());
+    const continuity = JSON.parse(await withIdentityKey(store, (old) => signContinuity(old, fresh, at))) as ContinuityStatement;
+    const blob = withMasterSecret(store, (m) => wrapIdentityKey(m, fresh, address));
+    const attestations = devices.map((d) => ({ device_id: d.id, identity_signature: b64urlEncode(fresh.attestDevice(address, d.id, d.key)) }));
+    const res = await ctx.api.keys.rotateIdentity({
+      new_identity_public_key: b64urlEncode(fresh.publicKey()),
+      continuity,
+      identity_blob: b64urlEncode(blob),
+      attestations,
+    });
+    // If this fails, the next start takes the key from the blob (syncIdentity).
+    const seed = fresh.toBytes();
+    try {
+      await store.putSecret(IDENTITY_SEED, seed);
+    } finally {
+      seed.fill(0);
+    }
+    return res;
+  } finally {
+    fresh.free();
+  }
+}

package/src/index.ts

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * @tavrn/e2ee – the client side of tavrn's end-to-end encryption, shared by the web client and bots:
+ * the MLS session manager, the content and attachment codecs, plaintext signatures, the account flows
+ * (device attestation, KeyPackages, secret storage, recovery key) and the {@link KeyStore} abstraction.
+ * Environment-neutral (browsers and Node.js); the file store for Node.js is exported from
+ * `@tavrn/e2ee/node`.
+ */
+export { ensureCrypto } from "./wasm";
+export {
+  LocalKeyMismatchError,
+  localAad,
+  localStorageKey,
+  readJsonSecret,
+  withBackupKey,
+  withMasterSecret,
+  writeJsonSecret,
+  type CryptoStatus,
+  type KeyStore,
+} from "./keystore";
+export { MemoryKeyStore } from "./storage/memory";
+export {
+  CLIENT_STATE,
+  E2eeError,
+  KEY_PACKAGE_BATCH,
+  KEY_PACKAGE_MIN,
+  addPasskeySecret,
+  deviceLoginProof,
+  ensureDevice,
+  forgetIdentityKeepDevice,
+  loadClient,
+  localDeviceLost,
+  localIdentityKey,
+  localStatus,
+  passkeyEntryIds,
+  regenerateRecoveryKey,
+  resetIdentity,
+  saveClient,
+  setupAccount,
+  unlockWithPasskeyPrf,
+  unlockWithRecoveryKey,
+  wipeLocal,
+  type DeviceProof as LocalDeviceProof,
+  type E2eeContext,
+  type E2eeErrorCode,
+} from "./account";
+export * from "./mls";
+export * from "./cleanup";
+export * from "./trust";
+export { META, PINS, VERIFIED, openMlsManager, reloadOwnIdentity, type OpenMlsOptions } from "./session";
+export { TAB_TIMEOUT_MS, TabCoordinator, type TabChannel, type TabHost, type TabLockManager, type TabOptions } from "./tabs";
+export * from "./content";
+export * from "./embeds";
+export * from "./sealed";
+export * from "./commands";
+export * from "./components";
+export * from "./plaintext";
+export * from "./history";
+export * from "./files";
+export * from "./poll";
+export * from "./search";
+export {
+  IDENTITY_SEED,
+  chainKeys,
+  chainReaches,
+  derivedIdentityKey,
+  ownIdentityPublicKey,
+  resolveIdentity,
+  rotateIdentity,
+  syncIdentity,
+  withIdentityKey,
+  type ContinuityStatement,
+  type IdentityDocument,
+  type RotationContext,
+} from "./identity";

package/src/keystore.ts

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Local key storage (ENCRYPTION.md §2.1 "local storage key"). A `KeyStore` keeps, per account, the
+ * device id, the 32-byte master secret and named secrets (the exported MLS client state, pins, MLS
+ * bookkeeping, verified contacts), everything encrypted at rest under
+ * `local_key = MasterSecret.localStorageKey(deviceId)`.
+ *
+ * Implementations: the IndexedDB store of the web client (tavrn-web `src/crypto/store.ts`, with "lock on
+ * close"), {@link MemoryKeyStore} (tests, short-lived tools) and the file store for Node.js
+ * (`FileKeyStore` from `@tavrn/e2ee/node`, the state directory of a bot).
+ *
+ * At most one account is open ("unlocked") at a time; the secret accessors act on that account and
+ * throw while the store is locked.
+ */
+import { MasterSecret } from "@tavrn/crypto";
+import { E2eeError } from "./errors";
+import { ensureCrypto } from "./wasm";
+
+export type CryptoStatus = "none" | "locked" | "unlocked";
+
+export interface KeyStore {
+  /** Whether this store holds the account's master secret, and whether it is readable right now. */
+  status(account: string): Promise<CryptoStatus>;
+  /** Device id the account's local data belongs to, or null if there is none. */
+  deviceIdOf(account: string): Promise<string | null>;
+  /**
+   * Opens the store without user interaction (a persisted local key); false if that is not possible
+   * (no data, "lock on close", or a store that always needs the master secret).
+   */
+  resume(account: string): Promise<boolean>;
+  /**
+   * Stores a master secret for this device and unlocks. Replaces earlier data of the account, including
+   * its named secrets.
+   */
+  saveMaster(account: string, deviceId: string, master: Uint8Array): Promise<void>;
+  /** Unlocks existing data with the master secret; throws {@link LocalKeyMismatchError} if it does not open it. */
+  unlockWithMaster(account: string, master: Uint8Array): Promise<void>;
+  isUnlocked(account?: string): boolean;
+  /** Forgets the key and the master secret in memory (data stays stored). */
+  lock(): void;
+  /** Deletes all local data of the account and locks if it was open. */
+  wipe(account: string): Promise<void>;
+  /** Account address of the open store, or null. */
+  account(): string | null;
+  /** Device id of the open account. */
+  deviceId(): string;
+  /** A copy of the 32-byte master secret; the caller should `fill(0)` it after use. */
+  masterSecret(): Uint8Array;
+  putSecret(name: string, value: Uint8Array): Promise<void>;
+  getSecret(name: string): Promise<Uint8Array | null>;
+  deleteSecret(name: string): Promise<void>;
+}
+
+/** Thrown when a master secret does not open this device's local data (stale entry or reset elsewhere). */
+export class LocalKeyMismatchError extends Error {
+  constructor() {
+    super("The master secret does not match the local data of this device");
+    this.name = "local_key_mismatch";
+  }
+}
+
+/** Additional data of every sealed value: binds it to the account and the entry name. */
+export function localAad(account: string, name: string): Uint8Array<ArrayBuffer> {
+  return new TextEncoder().encode(`tavrn local v1\u0000${account}\u0000${name}`);
+}
+
+/** The raw 32-byte local storage key of `deviceId` (ENCRYPTION.md §2.1); the caller zeroes it after use. */
+export async function localStorageKey(master: Uint8Array, deviceId: string): Promise<Uint8Array> {
+  await ensureCrypto();
+  const ms = MasterSecret.fromBytes(master);
+  try {
+    return ms.localStorageKey(deviceId);
+  } finally {
+    ms.free();
+  }
+}
+
+/** Runs `fn` with the store's master secret as a WASM object, freed afterwards. Requires an unlocked store. */
+export function withMasterSecret<T>(store: KeyStore, fn: (m: MasterSecret) => T): T {
+  const bytes = store.masterSecret();
+  const master = MasterSecret.fromBytes(bytes);
+  bytes.fill(0);
+  try {
+    return fn(master);
+  } finally {
+    master.free();
+  }
+}
+
+/**
+ * Runs `fn` with a fresh copy of the backup key (ENCRYPTION.md §2.1), zeroed afterwards; null while the
+ * store is locked. Used for data the user keeps encrypted on the home node (whiteboard scenes).
+ */
+export function withBackupKey<T>(store: KeyStore, fn: (key: Uint8Array) => T): T | null {
+  if (!store.isUnlocked()) return null;
+  const key = withMasterSecret(store, (m) => m.backupKey());
+  try {
+    return fn(key);
+  } finally {
+    key.fill(0);
+  }
+}
+
+/**
+ * Reads a named secret holding JSON; `fallback` if it is missing or unreadable. With `strict`, a secret that exists
+ * but does not parse throws `E2eeError("state_unreadable")` instead (and stays stored): for data whose loss must not
+ * go unnoticed, such as the key pins (a silent reset would trust every changed key again).
+ */
+export async function readJsonSecret<T>(store: KeyStore, name: string, fallback: T, opts: { strict?: boolean } = {}): Promise<T> {
+  const bytes = await store.getSecret(name);
+  if (!bytes) return fallback;
+  try {
+    return JSON.parse(new TextDecoder().decode(bytes)) as T;
+  } catch {
+    if (opts.strict) throw new E2eeError("state_unreadable");
+    return fallback;
+  } finally {
+    bytes.fill(0);
+  }
+}
+
+/** Stores a value as a JSON secret; does nothing while the store is locked (e.g. after sign-out). */
+export async function writeJsonSecret(store: KeyStore, name: string, value: unknown): Promise<void> {
+  if (!store.isUnlocked()) return;
+  await store.putSecret(name, new TextEncoder().encode(JSON.stringify(value)));
+}

package/src/lru.ts

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: MPL-2.0
+/** Small bounded caches of the session manager (a session may run for weeks: a bot, a tab that stays open). */
+
+/**
+ * A `Map` with at most `limit` entries: a read moves its entry to the newest end, a write beyond the limit evicts the
+ * least recently used entry (`Map` keeps insertion order).
+ */
+export class LruMap<K, V> {
+  private readonly map = new Map<K, V>();
+
+  constructor(readonly limit: number) {
+    if (!Number.isSafeInteger(limit) || limit < 1) throw new RangeError("LruMap: limit must be a positive integer");
+  }
+
+  get size(): number {
+    return this.map.size;
+  }
+
+  /** The value of `key`, marked as recently used. */
+  get(key: K): V | undefined {
+    const value = this.map.get(key);
+    if (value === undefined) return undefined;
+    this.map.delete(key);
+    this.map.set(key, value);
+    return value;
+  }
+
+  /** The value of `key` without changing its age. */
+  peek(key: K): V | undefined {
+    return this.map.get(key);
+  }
+
+  has(key: K): boolean {
+    return this.map.has(key);
+  }
+
+  set(key: K, value: V): this {
+    this.map.delete(key);
+    this.map.set(key, value);
+    if (this.map.size > this.limit) {
+      const oldest = this.map.keys().next();
+      if (!oldest.done) this.map.delete(oldest.value);
+    }
+    return this;
+  }
+
+  delete(key: K): boolean {
+    return this.map.delete(key);
+  }
+
+  clear(): void {
+    this.map.clear();
+  }
+
+  /** Deletes every entry `drop` selects. */
+  deleteWhere(drop: (value: V, key: K) => boolean): void {
+    for (const [k, v] of [...this.map]) if (drop(v, k)) this.map.delete(k);
+  }
+}
+
+/**
+ * A 53-bit hash of a string (cyrb53, public domain), as a fingerprint of a ciphertext in a decrypt cache entry: the
+ * cache key names the message and the sender fields its ciphertext is bound to (author, device, epoch), the
+ * fingerprint tells a changed ciphertext of that message apart without keeping it. NOT a cryptographic hash: second
+ * preimages are cheap to compute, so it is only used where a collision can at most answer with the earlier, verified
+ * result of the same message from the same sender, and never to decide whether a signature or a plaintext is valid.
+ */
+export function fingerprint(s: string, seed = 0): string {
+  let h1 = 0xdeadbeef ^ seed;
+  let h2 = 0x41c6ce57 ^ seed;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 2654435761);
+    h2 = Math.imul(h2 ^ c, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+  return `${s.length.toString(36)}.${(4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36)}`;
+}
+
+/**
+ * Nonces seen in the last `keepMs` (replay windows of signed arguments and component values): each one counts until
+ * `keepMs` after it was seen. Expired nonces are swept from the oldest end (insertion order follows the clock), so a
+ * check costs O(1) amortized instead of a scan of the whole window.
+ */
+export class NonceWindow {
+  private readonly seen = new Map<string, number>();
+
+  constructor(private readonly keepMs: number) {}
+
+  get size(): number {
+    return this.seen.size;
+  }
+
+  /** Whether `nonce` was remembered within the window at `now`. */
+  has(nonce: string, now: number): boolean {
+    this.sweep(now);
+    const at = this.seen.get(nonce);
+    return at !== undefined && now - at <= this.keepMs;
+  }
+
+  remember(nonce: string, now: number): void {
+    this.seen.delete(nonce);
+    this.seen.set(nonce, now);
+  }
+
+  private sweep(now: number): void {
+    for (const [nonce, at] of this.seen) {
+      if (now - at <= this.keepMs) break;
+      this.seen.delete(nonce);
+    }
+  }
+}