ciphermesh 1.0.0

package/src/crypto/MessageCrypto.js

@@ -0,0 +1,181 @@
+import sodium from 'sodium-native';
+import { MESSAGE_PAD_BUCKETS } from '../shared/constants.js';
+
+// ── Padding helpers ──────────────────────────────────────────
+
+/**
+ * Pad plaintext to a fixed-size bucket to hide message length.
+ * Format: [2 bytes length BE] + [plaintext] + [random padding]
+ */
+export function padMessage(message) {
+  // The length prefix is 2 bytes, so a single plaintext can't exceed 65535.
+  // Callers must keep payloads (e.g. file chunks) under this — fail loudly with
+  // a clear message rather than a cryptic writeUInt16BE RangeError.
+  if (message.length > 0xffff) {
+    throw new Error(`Payload too large to pad: ${message.length} bytes (max 65535)`);
+  }
+  const needed = 2 + message.length;
+
+  // Find smallest bucket that fits
+  let bucketSize = MESSAGE_PAD_BUCKETS[MESSAGE_PAD_BUCKETS.length - 1];
+  for (const size of MESSAGE_PAD_BUCKETS) {
+    if (size >= needed) {
+      bucketSize = size;
+      break;
+    }
+  }
+
+  // If message is larger than biggest bucket, no padding (e.g. file chunks)
+  if (needed > bucketSize) {
+    bucketSize = needed;
+  }
+
+  const padded = Buffer.alloc(bucketSize);
+  padded.writeUInt16BE(message.length, 0);
+  message.copy(padded, 2);
+
+  // Fill remaining bytes with random data
+  if (bucketSize > needed) {
+    const randomPart = padded.subarray(needed);
+    sodium.randombytes_buf(randomPart);
+  }
+
+  return padded;
+}
+
+/**
+ * Remove padding and extract original plaintext.
+ */
+export function unpadMessage(padded) {
+  if (padded.length < 2) {
+    return null;
+  }
+
+  const length = padded.readUInt16BE(0);
+  if (length + 2 > padded.length) {
+    return null;
+  }
+
+  return padded.subarray(2, 2 + length);
+}
+
+/**
+ * Unpad and copy plaintext into secure memory, then wipe the padded source.
+ * @param {Buffer} padded - Decrypted padded buffer
+ * @returns {Buffer|null} Plaintext in sodium_malloc, or null
+ */
+export function unpadSecure(padded) {
+  const unpadded = unpadMessage(padded);
+  if (!unpadded) {
+    sodium.sodium_memzero(padded);
+    return null;
+  }
+  const secure = sodium.sodium_malloc(unpadded.length);
+  unpadded.copy(secure);
+  sodium.sodium_memzero(padded);
+  return secure;
+}
+
+// ── Encrypt / Decrypt ────────────────────────────────────────
+
+/**
+ * Encrypt plaintext using crypto_box_easy (X25519 + XSalsa20-Poly1305).
+ * Applies padding before encryption to hide message length.
+ * @param {string|Buffer} plaintext
+ * @param {Buffer} nonce - 24 bytes
+ * @param {Buffer} recipientPublicKey - 32 bytes
+ * @param {Buffer} senderSecretKey - 32 bytes
+ * @returns {Buffer} ciphertext (padded length + 16 bytes MAC)
+ */
+export function encrypt(plaintext, nonce, recipientPublicKey, senderSecretKey) {
+  const message = Buffer.isBuffer(plaintext) ? plaintext : Buffer.from(plaintext, 'utf-8');
+  const padded = padMessage(message);
+  const ciphertext = Buffer.alloc(padded.length + sodium.crypto_box_MACBYTES);
+
+  sodium.crypto_box_easy(ciphertext, padded, nonce, recipientPublicKey, senderSecretKey);
+  sodium.sodium_memzero(padded);
+
+  return ciphertext;
+}
+
+/**
+ * Decrypt ciphertext using crypto_box_open_easy.
+ * Removes padding after decryption to recover original plaintext.
+ * @param {Buffer} ciphertext
+ * @param {Buffer} nonce - 24 bytes
+ * @param {Buffer} senderPublicKey - 32 bytes
+ * @param {Buffer} recipientSecretKey - 32 bytes
+ * @returns {Buffer|null} plaintext, or null if MAC verification failed
+ */
+export function decrypt(ciphertext, nonce, senderPublicKey, recipientSecretKey) {
+  if (ciphertext.length < sodium.crypto_box_MACBYTES) {
+    return null;
+  }
+
+  const padded = Buffer.alloc(ciphertext.length - sodium.crypto_box_MACBYTES);
+  const valid = sodium.crypto_box_open_easy(
+    padded,
+    ciphertext,
+    nonce,
+    senderPublicKey,
+    recipientSecretKey,
+  );
+
+  if (!valid) {
+    sodium.sodium_memzero(padded);
+    return null;
+  }
+
+  return unpadSecure(padded);
+}
+
+/**
+ * Try to decrypt with current keys, falling back to previous keys (grace period).
+ * @param {Buffer} ciphertext
+ * @param {Buffer} nonce
+ * @param {Buffer} senderPublicKey - current
+ * @param {Buffer} recipientSecretKey - current
+ * @param {Buffer|null} prevSenderPublicKey - previous sender key (if rotated)
+ * @param {Buffer|null} prevRecipientSecretKey - previous recipient key (if rotated)
+ * @returns {Buffer|null}
+ */
+export function decryptWithFallback(
+  ciphertext,
+  nonce,
+  senderPublicKey,
+  recipientSecretKey,
+  prevSenderPublicKey,
+  prevRecipientSecretKey,
+) {
+  // Try current keys first
+  const result = decrypt(ciphertext, nonce, senderPublicKey, recipientSecretKey);
+  if (result) {
+    return result;
+  }
+
+  // Try with sender's previous public key + our current secret key
+  if (prevSenderPublicKey) {
+    const r = decrypt(ciphertext, nonce, prevSenderPublicKey, recipientSecretKey);
+    if (r) {
+      return r;
+    }
+  }
+
+  // Try with our previous secret key + sender's current public key
+  if (prevRecipientSecretKey) {
+    const r = decrypt(ciphertext, nonce, senderPublicKey, prevRecipientSecretKey);
+    if (r) {
+      return r;
+    }
+  }
+
+  // Try with both previous keys
+  if (prevSenderPublicKey && prevRecipientSecretKey) {
+    const r = decrypt(ciphertext, nonce, prevSenderPublicKey, prevRecipientSecretKey);
+    if (r) {
+      return r;
+    }
+  }
+
+  return null;
+}

package/src/crypto/NonceManager.js

@@ -0,0 +1,72 @@
+import sodium from 'sodium-native';
+import {
+  NONCE_SIZE,
+  NONCE_TIMESTAMP_OFFSET,
+  NONCE_COUNTER_OFFSET,
+  NONCE_RANDOM_OFFSET,
+  NONCE_RANDOM_SIZE,
+  NONCE_MAX_AGE_MS,
+} from '../shared/constants.js';
+
+export class NonceManager {
+  #counter;
+  #peerCounters; // Map<peerId, lastCounter>
+
+  constructor() {
+    this.#counter = 0;
+    this.#peerCounters = new Map();
+  }
+
+  /**
+   * Generate a new 24-byte nonce:
+   * [8B timestamp][4B counter][12B random]
+   */
+  generate() {
+    const nonce = Buffer.alloc(NONCE_SIZE);
+
+    // 8 bytes: millisecond timestamp
+    const now = BigInt(Date.now());
+    nonce.writeBigUInt64BE(now, NONCE_TIMESTAMP_OFFSET);
+
+    // 4 bytes: monotonic counter
+    this.#counter = (this.#counter + 1) & 0xffffffff;
+    nonce.writeUInt32BE(this.#counter, NONCE_COUNTER_OFFSET);
+
+    // 12 bytes: random
+    const randomPart = nonce.subarray(NONCE_RANDOM_OFFSET, NONCE_RANDOM_OFFSET + NONCE_RANDOM_SIZE);
+    sodium.randombytes_buf(randomPart);
+
+    return nonce;
+  }
+
+  /**
+   * Validate an incoming nonce (anti-replay).
+   * Returns true if valid, false if replayed or too old.
+   */
+  validate(peerId, nonce) {
+    if (!Buffer.isBuffer(nonce) || nonce.length !== NONCE_SIZE) {
+      return false;
+    }
+
+    // Check timestamp freshness
+    const nonceTimestamp = Number(nonce.readBigUInt64BE(NONCE_TIMESTAMP_OFFSET));
+    const now = Date.now();
+    if (Math.abs(now - nonceTimestamp) > NONCE_MAX_AGE_MS) {
+      return false;
+    }
+
+    // Check counter is strictly increasing per peer
+    const counter = nonce.readUInt32BE(NONCE_COUNTER_OFFSET);
+    const lastCounter = this.#peerCounters.get(peerId) ?? -1;
+    if (counter <= lastCounter) {
+      return false;
+    }
+
+    this.#peerCounters.set(peerId, counter);
+    return true;
+  }
+
+  removePeer(peerId) {
+    this.#peerCounters.delete(peerId);
+  }
+}

package/src/crypto/SealedSender.js

@@ -0,0 +1,58 @@
+import sodium from 'sodium-native';
+
+// ── Sealed sender: anonymise the SENDER to the relay ────────────
+// The zero-knowledge relay routes by `to` and never needs `from`. Sealed sender
+// removes `from` from the wire envelope and instead carries the sender's
+// identity inside a libsodium *sealed box* (crypto_box_seal): the sender uses a
+// throwaway ephemeral keypair to encrypt to the recipient's static public key,
+// so the ciphertext is anonymous — only the recipient's secret key opens it, and
+// nothing in it identifies the sender to the relay. The recipient opens it,
+// learns `from`, then decrypts the inner (already E2E-encrypted) payload as usual.
+// (Recipient identity is still visible to the relay — that's inherent to routing.)
+
+// Anonymous seal of arbitrary bytes to a recipient public key.
+export function seal(inner, recipientPublicKey) {
+  const message = Buffer.isBuffer(inner) ? inner : Buffer.from(inner, 'utf-8');
+  const ciphertext = Buffer.alloc(message.length + sodium.crypto_box_SEALBYTES);
+  sodium.crypto_box_seal(ciphertext, message, recipientPublicKey);
+  return ciphertext;
+}
+
+// Open a sealed box; returns the plaintext Buffer, or null on failure/tamper.
+export function unseal(sealedCiphertext, recipientPublicKey, recipientSecretKey) {
+  if (sealedCiphertext.length < sodium.crypto_box_SEALBYTES) {
+    return null;
+  }
+  const out = Buffer.alloc(sealedCiphertext.length - sodium.crypto_box_SEALBYTES);
+  const ok = sodium.crypto_box_seal_open(
+    out,
+    sealedCiphertext,
+    recipientPublicKey,
+    recipientSecretKey,
+  );
+  if (!ok) {
+    sodium.sodium_memzero(out);
+    return null;
+  }
+  return out;
+}
+
+// Wrap an already-encrypted payload plus the sender's identity so the relay
+// can't see who sent it. Returns base64 for the wire `payload.sealed` field.
+export function sealEnvelope(from, payload, recipientPublicKey) {
+  const inner = Buffer.from(JSON.stringify({ from, payload }), 'utf-8');
+  return seal(inner, recipientPublicKey).toString('base64');
+}
+
+// Open a sealed envelope → { from, payload }, or null if it isn't for us.
+export function openEnvelope(sealedB64, recipientPublicKey, recipientSecretKey) {
+  const opened = unseal(Buffer.from(sealedB64, 'base64'), recipientPublicKey, recipientSecretKey);
+  if (!opened) {
+    return null;
+  }
+  try {
+    return JSON.parse(opened.toString('utf-8'));
+  } catch {
+    return null;
+  }
+}

package/src/crypto/SenderKey.js

@@ -0,0 +1,204 @@
+import sodium from 'sodium-native';
+import { NONCE_SIZE } from '../shared/constants.js';
+import { padMessage, unpadSecure } from './MessageCrypto.js';
+
+// ── Sender Keys: real group cryptography ────────────────────────
+// Each sender owns a symmetric ratchet chain per room. A message is encrypted
+// ONCE with the next message key and the same ciphertext is broadcast to every
+// member (O(1) instead of one pairwise encryption per peer). Members decrypt
+// with the sender's chain, which was distributed once over the pairwise channel.
+// Forward secrecy comes from ratcheting the chain forward every message and
+// rotating the whole chain on membership changes.
+
+const KEY_SIZE = 32;
+const MSG_KEY_TAG = Buffer.from([0x01]);
+const CHAIN_KEY_TAG = Buffer.from([0x02]);
+const DEFAULT_MAX_SKIP = 1000; // bound out-of-order / skipped message keys
+
+// A single sender's ratchet chain. Used to *send* (deriveNext) when it's your
+// own chain, or to *receive* (messageKeyFor) when it's a peer's distributed one.
+export class SenderChain {
+  #chainKey;
+  #counter;
+  #skipped; // Map<counter, messageKey> for out-of-order receipt
+  #maxSkip;
+
+  constructor(chainKey = null, counter = 0, maxSkip = DEFAULT_MAX_SKIP) {
+    this.#chainKey = sodium.sodium_malloc(KEY_SIZE);
+    if (chainKey) {
+      chainKey.copy(this.#chainKey);
+    } else {
+      sodium.randombytes_buf(this.#chainKey);
+    }
+    this.#counter = counter;
+    this.#skipped = new Map();
+    this.#maxSkip = maxSkip;
+  }
+
+  // Derive the current message key and ratchet the chain forward one step.
+  #step() {
+    const messageKey = sodium.sodium_malloc(KEY_SIZE);
+    sodium.crypto_generichash(messageKey, MSG_KEY_TAG, this.#chainKey);
+    const nextChainKey = sodium.sodium_malloc(KEY_SIZE);
+    sodium.crypto_generichash(nextChainKey, CHAIN_KEY_TAG, this.#chainKey);
+    sodium.sodium_memzero(this.#chainKey);
+    this.#chainKey = nextChainKey;
+    return messageKey;
+  }
+
+  // Sending: next message key + its counter.
+  deriveNext() {
+    const counter = this.#counter;
+    const messageKey = this.#step();
+    this.#counter++;
+    return { messageKey, counter };
+  }
+
+  // Receiving: the message key at `targetCounter`, caching skipped keys for
+  // out-of-order delivery. Returns null on replay (already consumed) or if the
+  // gap exceeds maxSkip. The caller must sodium_memzero the returned key.
+  messageKeyFor(targetCounter) {
+    if (this.#skipped.has(targetCounter)) {
+      const key = this.#skipped.get(targetCounter);
+      this.#skipped.delete(targetCounter);
+      return key;
+    }
+    if (targetCounter < this.#counter) {
+      return null; // already consumed → replay
+    }
+    if (targetCounter - this.#counter > this.#maxSkip) {
+      return null; // too far ahead
+    }
+    while (this.#counter < targetCounter) {
+      this.#skipped.set(this.#counter, this.#step());
+      this.#counter++;
+    }
+    const messageKey = this.#step();
+    this.#counter++;
+    return messageKey;
+  }
+
+  // Serialise the chain state so it can be handed to a new member (over the
+  // encrypted pairwise channel). Never send this in the clear.
+  serialize() {
+    return { chainKey: Buffer.from(this.#chainKey).toString('base64'), counter: this.#counter };
+  }
+
+  static deserialize({ chainKey, counter }) {
+    return new SenderChain(Buffer.from(chainKey, 'base64'), counter);
+  }
+
+  destroy() {
+    sodium.sodium_memzero(this.#chainKey);
+    for (const key of this.#skipped.values()) {
+      sodium.sodium_memzero(key);
+    }
+    this.#skipped.clear();
+  }
+}
+
+// Encrypt with a one-shot message key (length-padded, like the pairwise paths).
+export function groupEncrypt(messageKey, plaintext) {
+  const message = Buffer.isBuffer(plaintext) ? plaintext : Buffer.from(plaintext, 'utf-8');
+  const padded = padMessage(message);
+  const nonce = Buffer.alloc(NONCE_SIZE);
+  sodium.randombytes_buf(nonce);
+  const ciphertext = Buffer.alloc(padded.length + sodium.crypto_secretbox_MACBYTES);
+  sodium.crypto_secretbox_easy(ciphertext, padded, nonce, messageKey);
+  sodium.sodium_memzero(padded);
+  sodium.sodium_memzero(messageKey);
+  return { ciphertext, nonce };
+}
+
+export function groupDecrypt(messageKey, ciphertext, nonce) {
+  if (ciphertext.length < sodium.crypto_secretbox_MACBYTES) {
+    sodium.sodium_memzero(messageKey);
+    return null;
+  }
+  const padded = Buffer.alloc(ciphertext.length - sodium.crypto_secretbox_MACBYTES);
+  const ok = sodium.crypto_secretbox_open_easy(padded, ciphertext, nonce, messageKey);
+  sodium.sodium_memzero(messageKey);
+  if (!ok) {
+    sodium.sodium_memzero(padded);
+    return null;
+  }
+  return unpadSecure(padded);
+}
+
+// A per-room group session: your own sending chain + one receiving chain per
+// member. encrypt() runs once; every member decrypt()s the same ciphertext.
+export class GroupSession {
+  #own;
+  #members; // Map<memberId, SenderChain>
+
+  constructor() {
+    this.#own = new SenderChain();
+    this.#members = new Map();
+  }
+
+  encrypt(plaintext) {
+    const { messageKey, counter } = this.#own.deriveNext();
+    const { ciphertext, nonce } = groupEncrypt(messageKey, plaintext);
+    return {
+      counter,
+      ciphertext: ciphertext.toString('base64'),
+      nonce: nonce.toString('base64'),
+    };
+  }
+
+  decrypt(memberId, { counter, ciphertext, nonce }) {
+    const chain = this.#members.get(memberId);
+    if (!chain) {
+      return null;
+    }
+    const messageKey = chain.messageKeyFor(counter);
+    if (!messageKey) {
+      return null;
+    }
+    return groupDecrypt(
+      messageKey,
+      Buffer.from(ciphertext, 'base64'),
+      Buffer.from(nonce, 'base64'),
+    );
+  }
+
+  // The distribution message to hand a (new) member so they can decrypt you.
+  distribution() {
+    return this.#own.serialize();
+  }
+
+  addMember(memberId, distribution) {
+    const existing = this.#members.get(memberId);
+    if (existing) {
+      existing.destroy();
+    }
+    this.#members.set(memberId, SenderChain.deserialize(distribution));
+  }
+
+  removeMember(memberId) {
+    const chain = this.#members.get(memberId);
+    if (chain) {
+      chain.destroy();
+      this.#members.delete(memberId);
+    }
+  }
+
+  hasMember(memberId) {
+    return this.#members.has(memberId);
+  }
+
+  // Rotate your own chain (forward secrecy on membership change). Callers must
+  // redistribute the new distribution() to every member afterwards.
+  rotate() {
+    this.#own.destroy();
+    this.#own = new SenderChain();
+  }
+
+  destroy() {
+    this.#own.destroy();
+    for (const chain of this.#members.values()) {
+      chain.destroy();
+    }
+    this.#members.clear();
+  }
+}

package/src/crypto/StateManager.js

@@ -0,0 +1,138 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import sodium from 'sodium-native';
+
+const STATE_DIR = 'state';
+const STATE_FILE = 'session-state.enc.json';
+
+// Argon2id parameters. MODERATE is the current default for long-term key
+// material at rest; INTERACTIVE is the legacy default used to open files
+// written before the upgrade (their params are read from the envelope).
+export const KDF_DEFAULT = {
+  opslimit: sodium.crypto_pwhash_OPSLIMIT_MODERATE,
+  memlimit: sodium.crypto_pwhash_MEMLIMIT_MODERATE,
+};
+export const KDF_LEGACY = {
+  opslimit: sodium.crypto_pwhash_OPSLIMIT_INTERACTIVE,
+  memlimit: sodium.crypto_pwhash_MEMLIMIT_INTERACTIVE,
+};
+
+/**
+ * Derive a 32-byte KEK from a passphrase using Argon2id.
+ * @param {string} passphrase
+ * @param {Buffer} [salt] - 16 bytes. If omitted, generates a new one.
+ * @param {number} [opslimit] - Argon2id ops limit (defaults to MODERATE).
+ * @param {number} [memlimit] - Argon2id mem limit (defaults to MODERATE).
+ * @returns {{ kek: Buffer, salt: Buffer, opslimit: number, memlimit: number }}
+ */
+export function deriveKEK(
+  passphrase,
+  salt,
+  opslimit = KDF_DEFAULT.opslimit,
+  memlimit = KDF_DEFAULT.memlimit,
+) {
+  if (!salt) {
+    salt = Buffer.alloc(sodium.crypto_pwhash_SALTBYTES);
+    sodium.randombytes_buf(salt);
+  }
+  const kek = sodium.sodium_malloc(32);
+  sodium.crypto_pwhash(
+    kek,
+    Buffer.from(passphrase, 'utf-8'),
+    salt,
+    opslimit,
+    memlimit,
+    sodium.crypto_pwhash_ALG_ARGON2ID13,
+  );
+  return { kek, salt, opslimit, memlimit };
+}
+
+export class StateManager {
+  #stateDir;
+  #statePath;
+
+  constructor(baseDir = '.ciphermesh') {
+    this.#stateDir = join(baseDir, STATE_DIR);
+    if (!existsSync(this.#stateDir)) {
+      mkdirSync(this.#stateDir, { recursive: true });
+    }
+    this.#statePath = join(this.#stateDir, STATE_FILE);
+  }
+
+  deriveKEK(passphrase, salt) {
+    return deriveKEK(passphrase, salt);
+  }
+
+  /**
+   * Encrypt and save state to disk.
+   * @param {object} data - Plain object to serialize
+   * @param {Buffer} kek - 32-byte key encryption key
+   * @param {Buffer} salt - Salt used to derive KEK (stored alongside)
+   */
+  saveState(data, kek, salt, opslimit = KDF_DEFAULT.opslimit, memlimit = KDF_DEFAULT.memlimit) {
+    const plaintext = Buffer.from(JSON.stringify(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);
+
+    const envelope = {
+      salt: salt.toString('base64'),
+      nonce: nonce.toString('base64'),
+      ciphertext: ciphertext.toString('base64'),
+      opslimit,
+      memlimit,
+    };
+    writeFileSync(this.#statePath, JSON.stringify(envelope), { encoding: 'utf-8', mode: 0o600 });
+  }
+
+  /**
+   * Load and decrypt state from disk.
+   * @param {string} passphrase - Used to re-derive the KEK
+   * @returns {object|null} Parsed state or null if file missing/corrupt/wrong passphrase
+   */
+  loadState(passphrase) {
+    if (!existsSync(this.#statePath)) {
+      return null;
+    }
+
+    try {
+      const envelope = JSON.parse(readFileSync(this.#statePath, '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 → they were written with INTERACTIVE.
+      const opslimit = envelope.opslimit ?? KDF_LEGACY.opslimit;
+      const memlimit = envelope.memlimit ?? KDF_LEGACY.memlimit;
+      const { kek } = this.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);
+      sodium.sodium_memzero(kek);
+
+      if (!valid) {
+        sodium.sodium_memzero(plaintext);
+        return null;
+      }
+
+      const data = JSON.parse(plaintext.toString('utf-8'));
+      sodium.sodium_memzero(plaintext);
+      return data;
+    } catch {
+      return null;
+    }
+  }
+
+  hasState() {
+    return existsSync(this.#statePath);
+  }
+
+  clearState() {
+    if (existsSync(this.#statePath)) {
+      writeFileSync(this.#statePath, Buffer.alloc(256));
+      unlinkSync(this.#statePath);
+    }
+  }
+}