voidlogue-crypto 1.0.0

package/src/vault.js

@@ -0,0 +1,286 @@
+/**
+ * vault.js — Voidlogue Conversation Vault
+ *
+ * PIN-based local encryption for saved conversations.
+ * The PIN never leaves the device. Email + codename are
+ * encrypted with AES-256-GCM keyed by PBKDF2(PIN, salt).
+ *
+ * Labels are ALWAYS encrypted — never stored in plaintext.
+ * Labels are encrypted with the PIN-derived key.
+ *
+ * Storage keys in localStorage:
+ *   voidlogue_conv_{roomHash}  — encrypted blob
+ *   voidlogue_convlist         — plaintext index (hashes + encrypted labels)
+ */
+
+const ENC = new TextEncoder();
+const DEC = new TextDecoder();
+const PBKDF2_ITER = 100_000;
+const MAX_ATTEMPTS = 5;
+const LOCKOUT_MS = 15 * 60 * 1000; // 15 minutes
+const LABEL_PBKDF2_ITER = 60_000;
+
+function randomB64(bytes) {
+  const array = crypto.getRandomValues(new Uint8Array(bytes));
+  let binary = '';
+  for (let i = 0; i < array.length; i++) {
+    binary += String.fromCharCode(array[i]);
+  }
+  return btoa(binary);
+}
+
+async function deriveKey(pin, saltB64) {
+  const salt = Uint8Array.from(atob(saltB64), c => c.charCodeAt(0));
+  const km = await crypto.subtle.importKey(
+    "raw", ENC.encode(String(pin)), "PBKDF2", false, ["deriveKey"]
+  );
+  return crypto.subtle.deriveKey(
+    { name: "PBKDF2", salt, iterations: PBKDF2_ITER, hash: "SHA-256" },
+    km,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+
+async function deriveLabelKey(passphrase, saltB64) {
+  const salt = Uint8Array.from(atob(saltB64), c => c.charCodeAt(0));
+  const km = await crypto.subtle.importKey(
+    "raw", ENC.encode(passphrase), "PBKDF2", false, ["deriveKey"]
+  );
+  return crypto.subtle.deriveKey(
+    { name: "PBKDF2", salt, iterations: LABEL_PBKDF2_ITER, hash: "SHA-256" },
+    km,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+
+async function encryptLabel(label, keyOrPassphrase) {
+  if (!label) return { encrypted: "", hint: "(no label)" };
+  let key, salt;
+  if (typeof keyOrPassphrase === "string") {
+    salt = randomB64(16);
+    key = await deriveLabelKey(keyOrPassphrase, salt);
+  } else {
+    key = keyOrPassphrase;
+  }
+  const ivBytes = crypto.getRandomValues(new Uint8Array(12));
+  const iv = btoa(String.fromCharCode(...ivBytes));
+  const ct = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv: ivBytes },
+    key,
+    ENC.encode(label)
+  );
+  const data = btoa(String.fromCharCode(...new Uint8Array(ct)));
+  return salt ? { encrypted: data, iv, salt } : { encrypted: data, iv };
+}
+
+async function decryptLabel(entry, keyOrPassphrase) {
+  if (!entry || !entry.encrypted) return "";
+  let key;
+  if (typeof keyOrPassphrase === "string") {
+    if (!entry.salt) throw new Error("missing_salt");
+    key = await deriveLabelKey(keyOrPassphrase, entry.salt);
+  } else {
+    key = keyOrPassphrase;
+  }
+  const iv = Uint8Array.from(atob(entry.iv), c => c.charCodeAt(0));
+  const ct = Uint8Array.from(atob(entry.encrypted), c => c.charCodeAt(0));
+  const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, ct);
+  return DEC.decode(pt);
+}
+
+export const LabelCipher = {
+  encrypt: encryptLabel,
+  decrypt: decryptLabel,
+  deriveKey: deriveLabelKey,
+};
+
+export const Vault = {
+
+  /** Save email + codename encrypted with PIN. hint encrypted with PIN-derived key. */
+  async save(roomHash, email, codename, pin, hint = "") {
+    const salt = randomB64(16);
+    const ivBytes = crypto.getRandomValues(new Uint8Array(12));
+    const iv = btoa(String.fromCharCode(...ivBytes));
+    const key = await deriveKey(pin, salt);
+    const ct = await crypto.subtle.encrypt(
+      { name: "AES-GCM", iv: ivBytes },
+      key,
+      ENC.encode(JSON.stringify({ email, codename }))
+    );
+    const blob = {
+      salt, iv,
+      data: btoa(String.fromCharCode(...new Uint8Array(ct))),
+      attempts: 0,
+      lockedUntil: null,
+    };
+
+    const codenameSalt = randomB64(16);
+    const codenameIvBytes = crypto.getRandomValues(new Uint8Array(12));
+    const codenameIv = btoa(String.fromCharCode(...codenameIvBytes));
+    const codenameKey = await deriveKey(codename, codenameSalt);
+    const codenameCt = await crypto.subtle.encrypt(
+      { name: "AES-GCM", iv: codenameIvBytes },
+      codenameKey,
+      ENC.encode(JSON.stringify({ email }))
+    );
+    blob.codenameSalt = codenameSalt;
+    blob.codenameIv = codenameIv;
+    blob.codenameData = btoa(String.fromCharCode(...new Uint8Array(codenameCt)));
+
+
+    localStorage.setItem(`voidlogue_conv_${roomHash}`, JSON.stringify(blob));
+
+    const labelEntry = await encryptLabel(hint, key);
+    await this._updateIndex(roomHash, labelEntry);
+    return true;
+  },
+
+  /** Verify codename against the codename-encrypted verification blob. Returns {email} or throws. */
+  async verifyCodename(roomHash, codename) {
+    const raw = localStorage.getItem(`voidlogue_conv_${roomHash}`);
+    if (!raw) throw new Error("not_found");
+    const blob = JSON.parse(raw);
+    if (!blob.codenameSalt || !blob.codenameIv || !blob.codenameData) {
+      throw new Error("no_codename_blob");
+    }
+    const salt = Uint8Array.from(atob(blob.codenameSalt), c => c.charCodeAt(0));
+    const iv = Uint8Array.from(atob(blob.codenameIv), c => c.charCodeAt(0));
+    const ct = Uint8Array.from(atob(blob.codenameData), c => c.charCodeAt(0));
+    const key = await deriveKey(codename, blob.codenameSalt);
+    const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, ct);
+    const { email } = JSON.parse(DEC.decode(pt));
+    return { email };
+  },
+
+  /** Decrypt with PIN. Returns {email, codename, hint} or {error, ...}. */
+  async load(roomHash, pin) {
+    const raw = localStorage.getItem(`voidlogue_conv_${roomHash}`);
+    if (!raw) return { error: "not_found" };
+    const blob = JSON.parse(raw);
+
+    if (blob.lockedUntil && Date.now() < blob.lockedUntil) {
+      const mins = Math.ceil((blob.lockedUntil - Date.now()) / 60000);
+      return { error: "locked", minutesRemaining: mins };
+    }
+
+    try {
+      const key = await deriveKey(pin, blob.salt);
+      const iv  = Uint8Array.from(atob(blob.iv),   c => c.charCodeAt(0));
+      const ct  = Uint8Array.from(atob(blob.data),  c => c.charCodeAt(0));
+      const pt  = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, ct);
+      const { email, codename } = JSON.parse(DEC.decode(pt));
+      blob.attempts = 0; blob.lockedUntil = null;
+      localStorage.setItem(`voidlogue_conv_${roomHash}`, JSON.stringify(blob));
+
+      let hint = "";
+      try {
+        const entry = this._getEncryptedHint(roomHash);
+        hint = entry ? await decryptLabel(entry, key) : "";
+      } catch (_) { /* hint decrypt failed, continue without it */ }
+
+      return { email, codename, hint };
+    } catch {
+      blob.attempts = (blob.attempts || 0) + 1;
+      if (blob.attempts >= MAX_ATTEMPTS) {
+        blob.lockedUntil = Date.now() + LOCKOUT_MS;
+        blob.attempts = 0;
+        localStorage.setItem(`voidlogue_conv_${roomHash}`, JSON.stringify(blob));
+        return { error: "locked", minutesRemaining: 15 };
+      }
+      const attemptsLeft = MAX_ATTEMPTS - blob.attempts;
+      localStorage.setItem(`voidlogue_conv_${roomHash}`, JSON.stringify(blob));
+      return { error: "wrong_pin", attemptsLeft };
+    }
+  },
+
+  /** Re-encrypt with new PIN after user re-enters email + codename. */
+  async resetPin(roomHash, email, codename, newPin) {
+    const entry = this._getEncryptedHint(roomHash);
+    return this.save(roomHash, email, codename, newPin, entry ? "(restored)" : "");
+  },
+
+  /** Re-encrypt label with a new key. */
+  async updateLabel(roomHash, newHint, keyOrPassphrase) {
+    const entry = await encryptLabel(newHint, keyOrPassphrase);
+    await this._updateIndex(roomHash, entry);
+  },
+
+  /** Remove a conversation from vault and index. */
+  delete(roomHash) {
+    localStorage.removeItem(`voidlogue_conv_${roomHash}`);
+    const list = this.list().filter(c => c.roomHash !== roomHash);
+    localStorage.setItem("voidlogue_convlist", JSON.stringify(list));
+  },
+
+  /** Returns the plaintext index of saved conversations. */
+  list() {
+    try {
+      return JSON.parse(localStorage.getItem("voidlogue_convlist") || "[]");
+    } catch { return []; }
+  },
+
+  /** Returns true if conversation has a PIN-protected vault entry. */
+  has(roomHash) {
+    const raw = localStorage.getItem(`voidlogue_conv_${roomHash}`);
+    if (!raw) return false;
+    try {
+      const blob = JSON.parse(raw);
+      return !!blob.salt && !!blob.data;
+    } catch { return false; }
+  },
+
+  /** Returns true if conversation has any vault entry. */
+  hasAny(roomHash) {
+    if (this.has(roomHash)) return true;
+    return this.list().some(c => c.roomHash === roomHash);
+  },
+
+  /** Returns lockout info without attempting a decrypt. */
+  lockoutStatus(roomHash) {
+    const raw = localStorage.getItem(`voidlogue_conv_${roomHash}`);
+    if (!raw) return null;
+    const blob = JSON.parse(raw);
+    if (blob.lockedUntil && Date.now() < blob.lockedUntil) {
+      return { locked: true, minutesRemaining: Math.ceil((blob.lockedUntil - Date.now()) / 60000) };
+    }
+    return { locked: false, attemptsUsed: blob.attempts || 0 };
+  },
+
+  /** Wipe everything — called by panic clear. */
+  wipeAll() {
+    const list = this.list();
+    list.forEach(c => localStorage.removeItem(`voidlogue_conv_${c.roomHash}`));
+    localStorage.removeItem("voidlogue_convlist");
+  },
+
+  _getEncryptedHint(roomHash) {
+    return this.list().find(c => c.roomHash === roomHash)?.hint || null;
+  },
+
+  async _updateIndex(roomHash, labelEntry) {
+    const list = this.list().filter(c => c.roomHash !== roomHash);
+    list.unshift({ roomHash, hint: labelEntry, savedAt: Date.now() });
+    localStorage.setItem("voidlogue_convlist", JSON.stringify(list));
+  },
+
+  /** Migrate any plaintext labels to encrypted format. Call once on app start. */
+  async migratePlaintextLabels() {
+    if (localStorage.getItem("voidlogue_labels_migrated")) return;
+    const list = this.list();
+    let changed = false;
+    for (const entry of list) {
+      if (!entry.hint || typeof entry.hint === "string") {
+        entry.hint = { encrypted: "", hint: "(no label)" };
+        changed = true;
+      }
+    }
+    if (changed) {
+      localStorage.setItem("voidlogue_convlist", JSON.stringify(list));
+    }
+    localStorage.setItem("voidlogue_labels_migrated", "1");
+  },
+};

package/src/voidshield.js

@@ -0,0 +1,353 @@
+/**
+ * VoidShield — Voidlogue Client-Side Cryptography
+ * =================================================
+ * Version: 1.0.0
+ * License: MIT
+ * Repository: https://github.com/voidlogue/voidlogue-crypto
+ *
+ * All cryptographic operations run entirely in the browser using the
+ * Web Crypto API. Nothing sensitive ever reaches the server as plaintext.
+ *
+ * Exports:
+ *   VoidShield  — crypto primitives for Conversation and Revelation
+ *   generateCodename — EFF-wordlist passphrase generator
+ *
+ * Cryptographic primitives:
+ *   Hashing:         SHA-256 via SubtleCrypto.digest
+ *   Key derivation:  PBKDF2 (SHA-256, 100,000 iterations)
+ *   Encryption:      AES-256-GCM with random 96-bit IV per message
+ *   Randomness:      crypto.getRandomValues (rejection-sampling for uniformity)
+ *
+ * What this proves (open-source audit surface):
+ *   - Room hashes are derived client-side. The server receives only an opaque
+ *     hash and can never reverse it to learn email addresses or codenames.
+ *   - Message encryption keys are derived from the codename and never sent
+ *     to the server. The server stores only ciphertext it cannot decrypt.
+ *   - Revelation keys are derived from the recipient's security fields — values
+ *     the server never holds. Delivery does not require decryption.
+ */
+
+import { EFF_WORDLIST } from "./eff_wordlist.js";
+
+// ── INTERNAL CONSTANTS ────────────────────────────────────────────────────
+// These salts are intentionally public — security depends on key secrecy,
+// not salt secrecy. Published here for independent verification.
+const APP_SALT    = "voidlogue-v1-room-salt-2026";
+const REV_SALT    = "voidlogue-revelation-v1";
+const PBKDF2_ITER = 100_000;
+const CHUNK_BYTES = 256 * 1024; // 256 KB per media chunk
+const ENC         = new TextEncoder();
+const DEC         = new TextDecoder();
+
+// ── BASE64 HELPERS ────────────────────────────────────────────────────────
+const b64  = buf =>
+  btoa(String.fromCharCode(...new Uint8Array(buf instanceof ArrayBuffer ? buf : buf.buffer)));
+const ub64 = s =>
+  Uint8Array.from(atob(s), c => c.charCodeAt(0));
+
+// ── VOIDSHIELD ────────────────────────────────────────────────────────────
+
+/**
+ * VoidShield — cryptographic primitives for Voidlogue.
+ *
+ * All methods are pure (no side-effects, no DOM access, no localStorage).
+ * Safe to use in any JavaScript environment that provides the Web Crypto API.
+ */
+export const VoidShield = {
+
+  // ── Hashing ──────────────────────────────────────────────────────────────
+
+  /**
+   * SHA-256 of `input`, returned as lowercase hex string.
+   * @param {string} input
+   * @returns {Promise<string>} 64-character hex string
+   */
+  async hex(input) {
+    const buf = await crypto.subtle.digest("SHA-256", ENC.encode(input));
+    return [...new Uint8Array(buf)]
+      .map(b => b.toString(16).padStart(2, "0"))
+      .join("");
+  },
+
+  // ── Conversation ─────────────────────────────────────────────────────────
+
+  /**
+   * Derives a room hash from two email addresses and a shared codename.
+   *
+   * The sort ensures the hash is identical regardless of which party derives
+   * it first. The server receives only this opaque hash — never the emails
+   * or the codename.
+   *
+   * Algorithm:
+   *   hA = SHA-256(emailA.toLowerCase().trim())
+   *   hB = SHA-256(emailB.toLowerCase().trim())
+   *   roomHash = SHA-256(sort([hA, hB]).join(":") + ":" + codename + ":" + APP_SALT)
+   *
+   * @param {string} emailA
+   * @param {string} emailB
+   * @param {string} codename
+   * @returns {Promise<string>} 64-character hex room hash
+   */
+  async roomId(emailA, emailB, codename) {
+    const [hA, hB] = await Promise.all([
+      this.hex(emailA.toLowerCase().trim()),
+      this.hex(emailB.toLowerCase().trim()),
+    ]);
+    return this.hex(`${[hA, hB].sort().join(":")}:${codename}:${APP_SALT}`);
+  },
+
+  /**
+   * Validates a user-entered codename meets minimum entropy requirements.
+   * @param {string} codename
+   * @returns {{ valid: boolean, reason?: string }}
+   */
+  validateCodename(codename) {
+    if (!codename || codename.length < 8)
+      return { valid: false, reason: "Codename must be at least 8 characters." };
+    if (codename.length > 128)
+      return { valid: false, reason: "Codename must be 128 characters or less." };
+    if (/^\d+$/.test(codename))
+      return { valid: false, reason: "Codename cannot be only numbers." };
+    if (new Set(codename.toLowerCase()).size < 4)
+      return { valid: false, reason: "Codename must have at least 4 unique characters." };
+    return { valid: true };
+  },
+
+  /**
+   * Derives an AES-256-GCM key from a codename and room hash via PBKDF2.
+   *
+   * The derived key is non-extractable — the browser will not allow it to
+   * be exported or inspected. It can only be used for encrypt/decrypt.
+   *
+   * @param {string} codename  shared secret
+   * @param {string} roomHash  used as PBKDF2 salt
+   * @returns {Promise<CryptoKey>}
+   */
+  async deriveKey(codename, roomHash) {
+    const km = await crypto.subtle.importKey(
+      "raw", ENC.encode(codename), "PBKDF2", false, ["deriveKey"]
+    );
+    return crypto.subtle.deriveKey(
+      { name: "PBKDF2", salt: ENC.encode(roomHash), iterations: PBKDF2_ITER, hash: "SHA-256" },
+      km,
+      { name: "AES-GCM", length: 256 },
+      false,
+      ["encrypt", "decrypt"]
+    );
+  },
+
+  /**
+   * AES-256-GCM encrypt plaintext string.
+   * A fresh random 96-bit IV is generated for every call.
+   *
+   * @param {string} plaintext
+   * @param {CryptoKey} key
+   * @returns {Promise<{ ciphertextB64: string, ivB64: string }>}
+   */
+  async encrypt(plaintext, key) {
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ct = await crypto.subtle.encrypt(
+      { name: "AES-GCM", iv }, key, ENC.encode(plaintext)
+    );
+    return { ciphertextB64: b64(ct), ivB64: b64(iv) };
+  },
+
+  /**
+   * AES-256-GCM decrypt.
+   * Throws DOMException if ciphertext has been tampered with (authentication
+   * tag mismatch — inherent to AES-GCM).
+   *
+   * @param {string} ciphertextB64
+   * @param {string} ivB64
+   * @param {CryptoKey} key
+   * @returns {Promise<string>} plaintext
+   */
+  async decrypt(ciphertextB64, ivB64, key) {
+    const pt = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv: ub64(ivB64) }, key, ub64(ciphertextB64)
+    );
+    return DEC.decode(pt);
+  },
+
+  // ── Media (chunked encryption) ────────────────────────────────────────────
+
+  /**
+   * Encrypts a File in 256 KB chunks for Revelation media attachments.
+   * Each chunk has an independent random IV.
+   *
+   * @param {File} file
+   * @param {CryptoKey} key
+   * @returns {Promise<Array<{ ciphertextB64, ivB64, index, totalChunks }>>}
+   */
+  async encryptMedia(file, key) {
+    const buffer = await file.arrayBuffer();
+    const total  = Math.ceil(buffer.byteLength / CHUNK_BYTES);
+    const chunks = [];
+    for (let i = 0, offset = 0; offset < buffer.byteLength; i++, offset += CHUNK_BYTES) {
+      const iv = crypto.getRandomValues(new Uint8Array(12));
+      const ct = await crypto.subtle.encrypt(
+        { name: "AES-GCM", iv }, key, buffer.slice(offset, offset + CHUNK_BYTES)
+      );
+      chunks.push({ ciphertextB64: b64(ct), ivB64: b64(iv), index: i, totalChunks: total });
+    }
+    return chunks;
+  },
+
+  /**
+   * Async generator — decrypts and yields each chunk buffer in index order.
+   *
+   * @param {Array} chunks
+   * @param {CryptoKey} key
+   * @yields {ArrayBuffer}
+   */
+  async *decryptMediaStream(chunks, key) {
+    for (const c of [...chunks].sort((a, b) => a.index - b.index)) {
+      yield await crypto.subtle.decrypt(
+        { name: "AES-GCM", iv: ub64(c.ivB64) }, key, ub64(c.ciphertextB64)
+      );
+    }
+  },
+
+  // ── Revelation ────────────────────────────────────────────────────────────
+
+  /**
+   * Derives a Revelation encryption key from sender email, recipient email,
+   * and recipient security field values.
+   *
+   * The server never holds any of these inputs. Delivery does not require
+   * decryption — the server relays encrypted bytes it cannot read.
+   *
+   * For anonymous revelations, pass "__anon__" as senderEmail.
+   *
+   * @param {string} senderEmail    raw email or "__anon__"
+   * @param {string} recipientEmail raw recipient email
+   * @param {string[]} fieldValues  raw security field values (e.g. ["Alice", "1990-01-01"])
+   * @returns {Promise<CryptoKey>}
+   */
+  async deriveRevelationKey(senderEmail, recipientEmail, fieldValues = []) {
+    const [hS, hR] = await Promise.all([
+      this.hex(senderEmail.toLowerCase().trim()),
+      this.hex(recipientEmail.toLowerCase().trim()),
+    ]);
+    const fh = await Promise.all(fieldValues.map(v => this.hex(this._norm(v))));
+    const input = [[hS, hR].sort().join(":"), ...fh].join(":");
+    const km = await crypto.subtle.importKey(
+      "raw", ENC.encode(input), "PBKDF2", false, ["deriveKey"]
+    );
+    return crypto.subtle.deriveKey(
+      { name: "PBKDF2", salt: ENC.encode(REV_SALT), iterations: PBKDF2_ITER, hash: "SHA-256" },
+      km,
+      { name: "AES-GCM", length: 256 },
+      false,
+      ["encrypt", "decrypt"]
+    );
+  },
+
+  /**
+   * Revelation key derivation using pre-computed email hashes.
+   *
+   * Used by the recipient's ReadingView where the server provides the sender's
+   * email hash (computed at send time) rather than the raw email. The recipient
+   * never types the sender's email.
+   *
+   * @param {string} senderEmailHash    64-char hex SHA-256 of sender email
+   * @param {string} recipientEmailHash 64-char hex SHA-256 of recipient email
+   * @param {string[]} fieldValues      raw security field values
+   * @returns {Promise<CryptoKey>}
+   */
+  async deriveRevelationKeyFromHashes(senderEmailHash, recipientEmailHash, fieldValues = []) {
+    const fh = await Promise.all(fieldValues.map(v => this.hex(this._norm(v))));
+    const input = [[senderEmailHash, recipientEmailHash].sort().join(":"), ...fh].join(":");
+    const km = await crypto.subtle.importKey(
+      "raw", ENC.encode(input), "PBKDF2", false, ["deriveKey"]
+    );
+    return crypto.subtle.deriveKey(
+      { name: "PBKDF2", salt: ENC.encode(REV_SALT), iterations: PBKDF2_ITER, hash: "SHA-256" },
+      km,
+      { name: "AES-GCM", length: 256 },
+      false,
+      ["encrypt", "decrypt"]
+    );
+  },
+
+  /**
+   * Hash a security field value for server-side storage and comparison.
+   * Raw values are never sent to the server.
+   *
+   * @param {string} value raw field value
+   * @returns {Promise<string>} 64-char hex hash
+   */
+  async hashFieldValue(value) {
+    return this.hex(this._norm(value));
+  },
+
+  // ── Identity ──────────────────────────────────────────────────────────────
+
+  /**
+   * Derives a room-scoped sender identifier.
+   * SHA-256(uuid + ":" + roomHash) — opaque, cannot be used to join rooms.
+   *
+   * @param {string} uuid     user's internal UUID
+   * @param {string} roomHash derived room hash
+   * @returns {Promise<string>} 64-char hex sender hash
+   */
+  async senderHash(uuid, roomHash) {
+    return this.hex(`${uuid}:${roomHash}`);
+  },
+
+  // ── Randomness ────────────────────────────────────────────────────────────
+
+  /**
+   * Cryptographically uniform random integer in [0, max).
+   *
+   * Uses rejection sampling to eliminate modular bias — unlike a simple
+   * `getRandomValues() % max` which biases toward lower values when max
+   * is not a power of two.
+   *
+   * @param {number} max exclusive upper bound
+   * @returns {number}
+   */
+  secureRandom(max) {
+    const buf = new Uint32Array(1);
+    const lim = Math.floor(0x100000000 / max) * max;
+    do { crypto.getRandomValues(buf); } while (buf[0] >= lim);
+    return buf[0] % max;
+  },
+
+  // ── Internal ─────────────────────────────────────────────────────────────
+
+  /**
+   * Normalise a field value for consistent hashing.
+   * Lowercases, strips whitespace, hyphens, underscores, and dots.
+   * @internal
+   */
+  _norm(v) {
+    return String(v).toLowerCase().replace(/[\s\-_.]/g, "").trim();
+  },
+};
+
+// ── CODENAME GENERATOR ────────────────────────────────────────────────────
+
+/**
+ * Generates a random passphrase from the EFF long wordlist.
+ *
+ * Default: 3 words (≈38 bits of entropy from 7776-word pool).
+ * Increase wordCount for higher-security codenames:
+ *   4 words ≈ 51 bits
+ *   5 words ≈ 64 bits
+ *   6 words ≈ 77 bits
+ *
+ * The EFF wordlist is intentionally public. Security comes from the
+ * randomness of selection, not the secrecy of the word list.
+ *
+ * @param {number} wordCount number of words (2–8)
+ * @returns {string} hyphen-separated passphrase
+ */
+export function generateCodename(wordCount = 3) {
+  const count = Math.max(2, Math.min(8, wordCount));
+  const words = [];
+  for (let i = 0; i < count; i++) {
+    words.push(EFF_WORDLIST[VoidShield.secureRandom(EFF_WORDLIST.length)]);
+  }
+  return words.join("-");
+}