ciphermesh 1.0.0

package/src/crypto/Handshake.js

@@ -0,0 +1,219 @@
+import sodium from 'sodium-native';
+import { KEY_ROTATION_GRACE_MS } from '../shared/constants.js';
+import { DoubleRatchet } from './DoubleRatchet.js';
+
+export class Handshake {
+  #keyManager;
+  #peerKeys; // Map<sessionId, Buffer(publicKey)>
+  #previousPeerKeys; // Map<sessionId, { publicKey, timer }>
+  #ratchets; // Map<sessionId, DoubleRatchet>
+  #mySessionId;
+
+  constructor(keyManager) {
+    this.#keyManager = keyManager;
+    this.#peerKeys = new Map();
+    this.#previousPeerKeys = new Map();
+    this.#ratchets = new Map();
+    this.#mySessionId = null;
+  }
+
+  /**
+   * Set our session ID (called after JOIN_ACK).
+   * Also initializes ratchets for any already-registered peers.
+   */
+  setMySessionId(sessionId) {
+    this.#mySessionId = sessionId;
+
+    // Create ratchets for peers already registered
+    for (const [peerId, pubKey] of this.#peerKeys) {
+      if (!this.#ratchets.has(peerId)) {
+        this.#ratchets.set(
+          peerId,
+          new DoubleRatchet(this.#mySessionId, peerId, this.#keyManager.secretKey, pubKey),
+        );
+      }
+    }
+  }
+
+  /**
+   * Register a peer's public key for future encryption/decryption.
+   */
+  registerPeer(peerId, peerPublicKey) {
+    const pubBuf = Buffer.isBuffer(peerPublicKey)
+      ? peerPublicKey
+      : Buffer.from(peerPublicKey, 'base64');
+
+    if (pubBuf.length !== sodium.crypto_box_PUBLICKEYBYTES) {
+      throw new Error(`Invalid public key size: ${pubBuf.length}`);
+    }
+
+    this.#peerKeys.set(peerId, Buffer.from(pubBuf));
+
+    // Create ratchet if we already have our session ID
+    if (this.#mySessionId && !this.#ratchets.has(peerId)) {
+      this.#ratchets.set(
+        peerId,
+        new DoubleRatchet(this.#mySessionId, peerId, this.#keyManager.secretKey, pubBuf),
+      );
+    }
+  }
+
+  /**
+   * Get the ratchet for a peer.
+   */
+  getRatchet(peerId) {
+    return this.#ratchets.get(peerId) || null;
+  }
+
+  /**
+   * Update a peer's public key (key rotation).
+   * Keeps the old key for a grace period.
+   */
+  updatePeerKey(peerId, newPublicKey) {
+    const newBuf = Buffer.isBuffer(newPublicKey)
+      ? newPublicKey
+      : Buffer.from(newPublicKey, 'base64');
+
+    if (newBuf.length !== sodium.crypto_box_PUBLICKEYBYTES) {
+      throw new Error(`Invalid public key size: ${newBuf.length}`);
+    }
+
+    const oldKey = this.#peerKeys.get(peerId);
+    if (oldKey) {
+      // Clear any existing grace timer for this peer
+      const existing = this.#previousPeerKeys.get(peerId);
+      if (existing) {
+        clearTimeout(existing.timer);
+      }
+
+      const timer = setTimeout(() => {
+        this.#previousPeerKeys.delete(peerId);
+      }, KEY_ROTATION_GRACE_MS);
+
+      this.#previousPeerKeys.set(peerId, { publicKey: oldKey, timer });
+    }
+
+    this.#peerKeys.set(peerId, Buffer.from(newBuf));
+  }
+
+  /**
+   * Get the peer's current public key.
+   */
+  getPeerPublicKey(peerId) {
+    return this.#peerKeys.get(peerId);
+  }
+
+  /**
+   * Get the peer's previous public key (during grace period).
+   */
+  getPreviousPeerPublicKey(peerId) {
+    const entry = this.#previousPeerKeys.get(peerId);
+    return entry?.publicKey || null;
+  }
+
+  /**
+   * Get our own secret key (for passing to MessageCrypto).
+   */
+  get secretKey() {
+    return this.#keyManager.secretKey;
+  }
+
+  /**
+   * Get our previous secret key (for decrypting in-flight msgs after rotation).
+   */
+  get previousSecretKey() {
+    return this.#keyManager.previousSecretKey;
+  }
+
+  /**
+   * Remove a peer.
+   */
+  removePeer(peerId) {
+    this.#peerKeys.delete(peerId);
+    const prev = this.#previousPeerKeys.get(peerId);
+    if (prev) {
+      clearTimeout(prev.timer);
+      this.#previousPeerKeys.delete(peerId);
+    }
+
+    const ratchet = this.#ratchets.get(peerId);
+    if (ratchet) {
+      ratchet.destroy();
+      this.#ratchets.delete(peerId);
+    }
+  }
+
+  /**
+   * Re-map a ratchet from old peer ID to new peer ID (e.g., after reconnect).
+   */
+  migrateRatchet(oldPeerId, newPeerId) {
+    const ratchet = this.#ratchets.get(oldPeerId);
+    if (ratchet) {
+      this.#ratchets.delete(oldPeerId);
+      this.#ratchets.set(newPeerId, ratchet);
+    }
+    const peerKey = this.#peerKeys.get(oldPeerId);
+    if (peerKey) {
+      this.#peerKeys.delete(oldPeerId);
+      this.#peerKeys.set(newPeerId, peerKey);
+    }
+    const prevKey = this.#previousPeerKeys.get(oldPeerId);
+    if (prevKey) {
+      this.#previousPeerKeys.delete(oldPeerId);
+      this.#previousPeerKeys.set(newPeerId, prevKey);
+    }
+  }
+
+  /**
+   * Serialize all ratchets + peer keys for encrypted persistence.
+   */
+  serializeState() {
+    const ratchets = {};
+    for (const [peerId, ratchet] of this.#ratchets) {
+      ratchets[peerId] = ratchet.serialize();
+    }
+
+    const peerKeys = {};
+    for (const [peerId, pubKey] of this.#peerKeys) {
+      peerKeys[peerId] = pubKey.toString('base64');
+    }
+
+    return {
+      mySessionId: this.#mySessionId,
+      ratchets,
+      peerKeys,
+    };
+  }
+
+  /**
+   * Restore ratchets + peer keys from persisted state.
+   */
+  restoreState(data) {
+    this.#mySessionId = data.mySessionId;
+
+    for (const [peerId, pubKeyB64] of Object.entries(data.peerKeys || {})) {
+      this.#peerKeys.set(peerId, Buffer.from(pubKeyB64, 'base64'));
+    }
+
+    for (const [peerId, ratchetData] of Object.entries(data.ratchets || {})) {
+      this.#ratchets.set(peerId, DoubleRatchet.deserialize(ratchetData));
+    }
+  }
+
+  /**
+   * Destroy all state.
+   */
+  destroy() {
+    this.#peerKeys.clear();
+    for (const [, entry] of this.#previousPeerKeys) {
+      clearTimeout(entry.timer);
+    }
+    this.#previousPeerKeys.clear();
+
+    for (const [, ratchet] of this.#ratchets) {
+      ratchet.destroy();
+    }
+    this.#ratchets.clear();
+    this.#mySessionId = null;
+  }
+}

package/src/crypto/HistoryStore.js

@@ -0,0 +1,241 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import sodium from 'sodium-native';
+import { deriveKEK, KDF_LEGACY } from './StateManager.js';
+
+const HISTORY_DIR = 'history';
+const HISTORY_FILE = 'history.enc.json';
+const MAX_ENTRIES = 5000;
+const FLUSH_DELAY_MS = 3000;
+
+/**
+ * Opt-in encrypted local message history.
+ * Whole file is an envelope { salt, nonce, ciphertext } — same scheme as
+ * StateManager (Argon2id KEK + XSalsa20-Poly1305). Only active when the
+ * user provides a passphrase at startup.
+ */
+export class HistoryStore {
+  #path;
+  #kek;
+  #salt;
+  #entries;
+  #flushTimer;
+  #open;
+  #opslimit;
+  #memlimit;
+
+  constructor(baseDir = '.ciphermesh') {
+    const dir = join(baseDir, HISTORY_DIR);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    this.#path = join(dir, HISTORY_FILE);
+    this.#kek = null;
+    this.#salt = null;
+    this.#entries = [];
+    this.#flushTimer = null;
+    this.#open = false;
+    this.#opslimit = null;
+    this.#memlimit = null;
+  }
+
+  /**
+   * Derive the KEK and decrypt existing history (if any).
+   * @returns {boolean} false when the passphrase does not match the file
+   */
+  open(passphrase) {
+    if (!existsSync(this.#path)) {
+      const derived = deriveKEK(passphrase);
+      this.#kek = derived.kek;
+      this.#salt = derived.salt;
+      this.#opslimit = derived.opslimit;
+      this.#memlimit = derived.memlimit;
+      this.#open = true;
+      return true;
+    }
+
+    try {
+      const envelope = JSON.parse(readFileSync(this.#path, 'utf-8'));
+      const salt = Buffer.from(envelope.salt, 'base64');
+      const nonce = Buffer.from(envelope.nonce, 'base64');
+      const ciphertext = Buffer.from(envelope.ciphertext, 'base64');
+
+      // Legacy files have no stored params → written with INTERACTIVE.
+      const opslimit = envelope.opslimit ?? KDF_LEGACY.opslimit;
+      const memlimit = envelope.memlimit ?? KDF_LEGACY.memlimit;
+      const { kek } = deriveKEK(passphrase, salt, opslimit, memlimit);
+      const plaintext = Buffer.alloc(ciphertext.length - sodium.crypto_secretbox_MACBYTES);
+      const valid = sodium.crypto_secretbox_open_easy(plaintext, ciphertext, nonce, kek);
+      if (!valid) {
+        sodium.sodium_memzero(kek);
+        sodium.sodium_memzero(plaintext);
+        return false;
+      }
+
+      this.#entries = JSON.parse(plaintext.toString('utf-8'));
+      sodium.sodium_memzero(plaintext);
+      this.#kek = kek;
+      this.#salt = salt;
+      this.#opslimit = opslimit;
+      this.#memlimit = memlimit;
+      this.#open = true;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  get isOpen() {
+    return this.#open;
+  }
+
+  get size() {
+    return this.#entries.length;
+  }
+
+  append({ room, nickname, text, isDM = false }) {
+    if (!this.#open) {
+      return;
+    }
+    this.#entries.push({ ts: Date.now(), room, nickname, text, isDM });
+    if (this.#entries.length > MAX_ENTRIES) {
+      this.#entries.splice(0, this.#entries.length - MAX_ENTRIES);
+    }
+    this.#scheduleFlush();
+  }
+
+  search(term, limit = 50) {
+    if (!this.#open || !term) {
+      return [];
+    }
+    const needle = term.toLowerCase();
+    const found = this.#entries.filter(
+      (e) => e.text.toLowerCase().includes(needle) || e.nickname.toLowerCase().includes(needle),
+    );
+    return found.slice(-limit);
+  }
+
+  recent(count = 20) {
+    if (!this.#open) {
+      return [];
+    }
+    return this.#entries.slice(-count);
+  }
+
+  /**
+   * Drop history entries older than maxAgeMs and persist. Returns how many
+   * were removed. Used by the /retention command for a disk-retention policy.
+   */
+  purgeOlderThan(maxAgeMs) {
+    if (!this.#open) {
+      return 0;
+    }
+    const cutoff = Date.now() - maxAgeMs;
+    const before = this.#entries.length;
+    this.#entries = this.#entries.filter((e) => e.ts >= cutoff);
+    const removed = before - this.#entries.length;
+    if (removed > 0) {
+      this.flush();
+    }
+    return removed;
+  }
+
+  /**
+   * Export history as PLAINTEXT — .json when the path ends with .json,
+   * otherwise a human-readable .txt.
+   * @returns {number} entries written
+   */
+  exportTo(filePath) {
+    if (!this.#open) {
+      return 0;
+    }
+    let out;
+    if (filePath.toLowerCase().endsWith('.json')) {
+      out = JSON.stringify(this.#entries, null, 2);
+    } else {
+      out =
+        this.#entries
+          .map((e) => {
+            const when = new Date(e.ts).toLocaleString('en-US', {
+              day: '2-digit',
+              month: '2-digit',
+              year: 'numeric',
+              hour: '2-digit',
+              minute: '2-digit',
+            });
+            const dm = e.isDM ? ' (DM)' : '';
+            return `[${when}] [#${e.room}]${dm} ${e.nickname}: ${e.text}`;
+          })
+          .join('\n') + '\n';
+    }
+    writeFileSync(filePath, out, 'utf-8');
+    return this.#entries.length;
+  }
+
+  #scheduleFlush() {
+    if (this.#flushTimer) {
+      return;
+    }
+    this.#flushTimer = setTimeout(() => {
+      this.#flushTimer = null;
+      this.flush();
+    }, FLUSH_DELAY_MS);
+  }
+
+  flush() {
+    if (!this.#open) {
+      return;
+    }
+    const plaintext = Buffer.from(JSON.stringify(this.#entries), 'utf-8');
+    const nonce = Buffer.alloc(sodium.crypto_secretbox_NONCEBYTES);
+    sodium.randombytes_buf(nonce);
+    const ciphertext = Buffer.alloc(plaintext.length + sodium.crypto_secretbox_MACBYTES);
+    sodium.crypto_secretbox_easy(ciphertext, plaintext, nonce, this.#kek);
+    sodium.sodium_memzero(plaintext);
+
+    const envelope = {
+      salt: this.#salt.toString('base64'),
+      nonce: nonce.toString('base64'),
+      ciphertext: ciphertext.toString('base64'),
+      opslimit: this.#opslimit,
+      memlimit: this.#memlimit,
+    };
+    writeFileSync(this.#path, JSON.stringify(envelope), { encoding: 'utf-8', mode: 0o600 });
+  }
+
+  destroy() {
+    if (this.#flushTimer) {
+      clearTimeout(this.#flushTimer);
+      this.#flushTimer = null;
+    }
+    if (this.#open) {
+      this.flush();
+      sodium.sodium_memzero(this.#kek);
+      this.#kek = null;
+      this.#open = false;
+    }
+  }
+
+  // Securely delete the encrypted history from disk (panic / duress). Overwrites
+  // before unlinking (best effort) and drops the in-memory key.
+  wipe() {
+    if (this.#flushTimer) {
+      clearTimeout(this.#flushTimer);
+      this.#flushTimer = null;
+    }
+    this.#entries = [];
+    if (this.#kek) {
+      sodium.sodium_memzero(this.#kek);
+      this.#kek = null;
+    }
+    this.#open = false;
+    try {
+      if (existsSync(this.#path)) {
+        writeFileSync(this.#path, Buffer.alloc(Math.max(256, statSync(this.#path).size)));
+        unlinkSync(this.#path);
+      }
+    } catch {
+      /* best effort */
+    }
+  }
+}

package/src/crypto/IdentityBackup.js

@@ -0,0 +1,70 @@
+import sodium from 'sodium-native';
+import { deriveKEK, KDF_LEGACY } from './StateManager.js';
+
+const BACKUP_VERSION = 1;
+
+/**
+ * Encrypt an identity+trust backup with a passphrase (Argon2id KEK +
+ * XSalsa20-Poly1305), returning a self-describing JSON envelope string.
+ * The envelope stores the KDF params so it is portable and future-proof.
+ *
+ * @param {object} data - e.g. { identity, trust }
+ * @param {string} passphrase
+ * @returns {string} JSON envelope
+ */
+export function exportBackup(data, passphrase) {
+  const { kek, salt, opslimit, memlimit } = deriveKEK(passphrase);
+  const plaintext = Buffer.from(JSON.stringify({ version: BACKUP_VERSION, ...data }), 'utf-8');
+  const nonce = Buffer.alloc(sodium.crypto_secretbox_NONCEBYTES);
+  sodium.randombytes_buf(nonce);
+
+  const ciphertext = Buffer.alloc(plaintext.length + sodium.crypto_secretbox_MACBYTES);
+  sodium.crypto_secretbox_easy(ciphertext, plaintext, nonce, kek);
+  sodium.sodium_memzero(plaintext);
+  sodium.sodium_memzero(kek);
+
+  return JSON.stringify({
+    kind: 'ciphermesh-backup',
+    salt: salt.toString('base64'),
+    nonce: nonce.toString('base64'),
+    ciphertext: ciphertext.toString('base64'),
+    opslimit,
+    memlimit,
+  });
+}
+
+/**
+ * Decrypt a backup envelope. Returns the data object or null on wrong
+ * passphrase / corruption.
+ * @param {string} raw - the JSON envelope
+ * @param {string} passphrase
+ * @returns {object|null}
+ */
+export function importBackup(raw, passphrase) {
+  try {
+    const env = JSON.parse(raw);
+    if (env.kind !== 'ciphermesh-backup') {
+      return null;
+    }
+    const salt = Buffer.from(env.salt, 'base64');
+    const nonce = Buffer.from(env.nonce, 'base64');
+    const ciphertext = Buffer.from(env.ciphertext, 'base64');
+    const opslimit = env.opslimit ?? KDF_LEGACY.opslimit;
+    const memlimit = env.memlimit ?? KDF_LEGACY.memlimit;
+
+    const { kek } = deriveKEK(passphrase, salt, opslimit, memlimit);
+    const plaintext = Buffer.alloc(ciphertext.length - sodium.crypto_secretbox_MACBYTES);
+    const ok = sodium.crypto_secretbox_open_easy(plaintext, ciphertext, nonce, kek);
+    sodium.sodium_memzero(kek);
+
+    if (!ok) {
+      sodium.sodium_memzero(plaintext);
+      return null;
+    }
+    const data = JSON.parse(plaintext.toString('utf-8'));
+    sodium.sodium_memzero(plaintext);
+    return data;
+  } catch {
+    return null;
+  }
+}

package/src/crypto/KeyManager.js

@@ -0,0 +1,134 @@
+// @ts-nocheck
+import sodium from 'sodium-native';
+import { createHash } from 'node:crypto';
+import { KEY_ROTATION_GRACE_MS } from '../shared/constants.js';
+
+export class KeyManager {
+  #publicKey;
+  #secretKey;
+  #fingerprint;
+  #previousPublicKey;
+  #previousSecretKey;
+  #graceTimer;
+
+  constructor() {
+    this.#publicKey = Buffer.alloc(sodium.crypto_box_PUBLICKEYBYTES);
+    this.#secretKey = sodium.sodium_malloc(sodium.crypto_box_SECRETKEYBYTES);
+    this.#previousPublicKey = null;
+    this.#previousSecretKey = null;
+    this.#graceTimer = null;
+
+    sodium.crypto_box_keypair(this.#publicKey, this.#secretKey);
+
+    this.#fingerprint = KeyManager.computeFingerprint(this.#publicKey);
+  }
+
+  get publicKey() {
+    return this.#publicKey;
+  }
+
+  get secretKey() {
+    return this.#secretKey;
+  }
+
+  get publicKeyB64() {
+    return this.#publicKey.toString('base64');
+  }
+
+  get fingerprint() {
+    return this.#fingerprint;
+  }
+
+  get previousPublicKey() {
+    return this.#previousPublicKey;
+  }
+
+  get previousSecretKey() {
+    return this.#previousSecretKey;
+  }
+
+  /**
+   * Generate a new keypair, keeping the old one for a grace period.
+   */
+  rotate() {
+    // Clear any existing grace timer
+    if (this.#graceTimer) {
+      clearTimeout(this.#graceTimer);
+      this.destroyPrevious();
+    }
+
+    // Move current keys to previous
+    this.#previousPublicKey = this.#publicKey;
+    this.#previousSecretKey = this.#secretKey;
+
+    // Generate new keypair
+    this.#publicKey = Buffer.alloc(sodium.crypto_box_PUBLICKEYBYTES);
+    this.#secretKey = sodium.sodium_malloc(sodium.crypto_box_SECRETKEYBYTES);
+    sodium.crypto_box_keypair(this.#publicKey, this.#secretKey);
+
+    this.#fingerprint = KeyManager.computeFingerprint(this.#publicKey);
+
+    // Auto-destroy previous keys after grace period
+    this.#graceTimer = setTimeout(() => {
+      this.destroyPrevious();
+      this.#graceTimer = null;
+    }, KEY_ROTATION_GRACE_MS);
+  }
+
+  destroyPrevious() {
+    if (this.#previousSecretKey) {
+      sodium.sodium_memzero(this.#previousSecretKey);
+    }
+    this.#previousSecretKey = null;
+    this.#previousPublicKey = null;
+  }
+
+  static computeFingerprint(publicKey) {
+    const hash = createHash('sha256').update(publicKey).digest();
+    const parts = [];
+    for (let i = 0; i < 8; i += 2) {
+      parts.push(
+        hash
+          .subarray(i, i + 2)
+          .toString('hex')
+          .toUpperCase(),
+      );
+    }
+    return parts.join(':');
+  }
+
+  destroy() {
+    if (this.#graceTimer) {
+      clearTimeout(this.#graceTimer);
+    }
+    this.destroyPrevious();
+    if (this.#secretKey) {
+      sodium.sodium_memzero(this.#secretKey);
+    }
+    this.#secretKey = null;
+    this.#publicKey = null;
+    this.#fingerprint = null;
+  }
+
+  serialize() {
+    return {
+      publicKey: this.#publicKey.toString('base64'),
+      secretKey: this.#secretKey.toString('base64'),
+    };
+  }
+
+  static deserialize(data) {
+    const km = new KeyManager(); // generates throwaway keys
+    sodium.sodium_memzero(km.#secretKey); // wipe throwaway
+
+    km.#publicKey = Buffer.from(data.publicKey, 'base64');
+    const tempSec = Buffer.from(data.secretKey, 'base64');
+    km.#secretKey = sodium.sodium_malloc(sodium.crypto_box_SECRETKEYBYTES);
+    tempSec.copy(km.#secretKey);
+    sodium.sodium_memzero(tempSec);
+    km.#fingerprint = KeyManager.computeFingerprint(km.#publicKey);
+    km.#previousPublicKey = null;
+    km.#previousSecretKey = null;
+    return km;
+  }
+}