ciphermesh 2.2.0 → 2.4.0

package/src/crypto/DoubleRatchet.js

@@ -1,6 +1,7 @@
 import sodium from 'sodium-native';
 import { RATCHET_MAX_SKIP, RATCHET_SKIP_KEY_MAX_AGE_MS } from '../shared/constants.js';
 import { padMessage, unpadSecure } from './MessageCrypto.js';
+import { pqEncapsulate, pqDecapsulate, mixPQIntoRoot } from './PQHybrid.js';
 
 const SCALARMULT_BYTES = 32;
 const KEY_SIZE = 32;
@@ -18,14 +19,20 @@ export class DoubleRatchet {
   #skippedKeys; // Map<"ephHex:counter", { msgKey, timestamp }>
   #initialized;
   #needSendRatchet; // true when we need a DH ratchet step before next send
+  #pqCiphertext; // KEM ct to advertise while the peer may not have mixed yet
+  #pqSecretKey; // our ML-KEM secret key (responder side)
+  #pqApplied; // true once a KEM secret is folded into the root
 
   /**
    * @param {string} mySessionId
    * @param {string} peerSessionId
    * @param {Buffer} myStaticSecretKey
    * @param {Buffer} peerStaticPublicKey
+   * @param {object} [pq] - hybrid post-quantum material (optional)
+   * @param {Buffer} [pq.peerPublicKey] - peer's ML-KEM public key
+   * @param {Buffer} [pq.mySecretKey] - our ML-KEM secret key
    */
-  constructor(mySessionId, peerSessionId, myStaticSecretKey, peerStaticPublicKey) {
+  constructor(mySessionId, peerSessionId, myStaticSecretKey, peerStaticPublicKey, pq = null) {
     this.#skippedKeys = new Map();
     this.#sendCounter = 0;
     this.#recvCounter = 0;
@@ -47,6 +54,29 @@ export class DoubleRatchet {
 
     const isInitiator = mySessionId < peerSessionId;
 
+    // ── Hybrid post-quantum (optional) ────────────────────────
+    // The initiator encapsulates to the peer's ML-KEM key right here and
+    // folds the secret into the root BEFORE any chain is derived; the
+    // ciphertext rides along in outgoing envelopes so the responder can
+    // decapsulate and fold the same secret before its first decrypt. Because
+    // the mix only ever happens at initialization, no in-flight message can
+    // straddle the change — there is nothing to desynchronize.
+    this.#pqCiphertext = null;
+    this.#pqSecretKey = pq?.mySecretKey || null;
+    this.#pqApplied = false;
+
+    if (isInitiator && pq?.peerPublicKey) {
+      const encaps = pqEncapsulate(pq.peerPublicKey);
+      if (encaps) {
+        const mixed = mixPQIntoRoot(this.#rootKey, encaps.sharedSecret);
+        sodium.sodium_memzero(this.#rootKey);
+        this.#rootKey = mixed;
+        sodium.sodium_memzero(encaps.sharedSecret);
+        this.#pqCiphertext = encaps.ciphertext;
+        this.#pqApplied = true;
+      }
+    }
+
     if (isInitiator) {
       // Initiator generates ephemeral keypair immediately
       this.#myEphKeyPair = this.#generateEphemeralKeyPair();
@@ -185,13 +215,24 @@ export class DoubleRatchet {
     // Wipe message key immediately
     sodium.sodium_memzero(messageKey);
 
-    return {
+    const envelope = {
       ciphertext,
       nonce,
       ephemeralPublicKey: this.#myEphKeyPair.publicKey,
       counter,
       previousCounter: this.#previousSendCount,
     };
+    // Keep advertising the KEM ciphertext until the peer answers (their reply
+    // proves they folded it in). Cheap: ~1KB on a handful of messages.
+    if (this.#pqCiphertext) {
+      envelope.pqCiphertext = this.#pqCiphertext;
+    }
+    return envelope;
+  }
+
+  /** True when this ratchet's root includes an ML-KEM secret. */
+  get isHybrid() {
+    return this.#pqApplied;
   }
 
   // ── Decrypt ─────────────────────────────────────────────────
@@ -203,13 +244,27 @@ export class DoubleRatchet {
    * @param {Buffer} ephPub - sender's ephemeral public key
    * @param {number} counter
    * @param {number} prevCounter
+   * @param {Buffer} [pqCt] - sender's ML-KEM ciphertext (hybrid handshake)
    * @returns {Buffer|null} plaintext or null on failure
    */
-  decrypt(ciphertext, nonce, ephPub, counter, prevCounter) {
+  decrypt(ciphertext, nonce, ephPub, counter, prevCounter, pqCt = null) {
     if (!this.#initialized) {
       return null;
     }
 
+    // Hybrid: fold the peer's KEM secret into the root before deriving any
+    // chain from it. Once only — the initiator did the same at construction.
+    if (pqCt && !this.#pqApplied && this.#pqSecretKey) {
+      const ss = pqDecapsulate(pqCt, this.#pqSecretKey);
+      if (ss) {
+        const mixed = mixPQIntoRoot(this.#rootKey, ss);
+        sodium.sodium_memzero(this.#rootKey);
+        this.#rootKey = mixed;
+        sodium.sodium_memzero(ss);
+        this.#pqApplied = true;
+      }
+    }
+
     // Reject malformed inputs before any allocation or crypto. A short
     // ciphertext (< MAC), wrong-size nonce/key, or non-integer counter from a
     // hostile peer must return null — never crash (Buffer.alloc(-2)) or desync.
@@ -347,6 +402,10 @@ export class DoubleRatchet {
     this.#recvChainKey = txChainKey;
     this.#recvCounter = txCounter;
 
+    // A message we could actually decrypt proves the peer's root matches ours,
+    // so they already folded the KEM secret — stop paying ~1KB per envelope.
+    this.#pqCiphertext = null;
+
     this.#cleanupSkippedKeys();
     return result;
   }
@@ -456,6 +515,8 @@ export class DoubleRatchet {
     }
     this.#skippedKeys.clear();
     this.#peerEphPublicKey = null;
+    this.#pqCiphertext = null;
+    this.#pqSecretKey = null;
     this.#initialized = false;
   }
 
@@ -490,6 +551,10 @@ export class DoubleRatchet {
       initialized: this.#initialized,
       needSendRatchet: this.#needSendRatchet,
       skippedKeys: skipped,
+      // Hybrid state: the root is already mixed, so `pqApplied` must survive
+      // to keep a restored session from folding a second secret in.
+      pqApplied: this.#pqApplied,
+      pqCiphertext: this.#pqCiphertext?.toString('base64') || null,
     };
   }
 
@@ -533,6 +598,8 @@ export class DoubleRatchet {
     r.#sendCounter = data.sendCounter;
     r.#recvCounter = data.recvCounter;
     r.#previousSendCount = data.previousSendCount;
+    r.#pqApplied = !!data.pqApplied;
+    r.#pqCiphertext = data.pqCiphertext ? Buffer.from(data.pqCiphertext, 'base64') : null;
 
     if (r.#myEphKeyPair) {
       sodium.sodium_memzero(r.#myEphKeyPair.secretKey);

package/src/crypto/Handshake.js

@@ -5,6 +5,7 @@ import { DoubleRatchet } from './DoubleRatchet.js';
 export class Handshake {
   #keyManager;
   #peerKeys; // Map<sessionId, Buffer(publicKey)>
+  #peerPQKeys; // Map<sessionId, Buffer(ML-KEM public key)>
   #previousPeerKeys; // Map<sessionId, { publicKey, timer }>
   #ratchets; // Map<sessionId, DoubleRatchet>
   #mySessionId;
@@ -12,11 +13,26 @@ export class Handshake {
   constructor(keyManager) {
     this.#keyManager = keyManager;
     this.#peerKeys = new Map();
+    this.#peerPQKeys = new Map();
     this.#previousPeerKeys = new Map();
     this.#ratchets = new Map();
     this.#mySessionId = null;
   }
 
+  // Hybrid material handed to every new ratchet: the peer's KEM public key
+  // (absent for pre-v3 clients → classical-only) plus our KEM secret key.
+  #pqFor(peerId) {
+    return {
+      peerPublicKey: this.#peerPQKeys.get(peerId) || null,
+      mySecretKey: this.#keyManager.pqSecretKey || null,
+    };
+  }
+
+  /** True when this peer's ratchet root includes an ML-KEM secret. */
+  isHybrid(peerId) {
+    return this.#ratchets.get(peerId)?.isHybrid === true;
+  }
+
   /**
    * Set our session ID (called after JOIN_ACK).
    * Also initializes ratchets for any already-registered peers.
@@ -29,7 +45,13 @@ export class Handshake {
       if (!this.#ratchets.has(peerId)) {
         this.#ratchets.set(
           peerId,
-          new DoubleRatchet(this.#mySessionId, peerId, this.#keyManager.secretKey, pubKey),
+          new DoubleRatchet(
+            this.#mySessionId,
+            peerId,
+            this.#keyManager.secretKey,
+            pubKey,
+            this.#pqFor(peerId),
+          ),
         );
       }
     }
@@ -37,8 +59,9 @@ export class Handshake {
 
   /**
    * Register a peer's public key for future encryption/decryption.
+   * @param {string|Buffer} [peerPQPublicKey] - their ML-KEM key (hybrid)
    */
-  registerPeer(peerId, peerPublicKey) {
+  registerPeer(peerId, peerPublicKey, peerPQPublicKey = null) {
     const pubBuf = Buffer.isBuffer(peerPublicKey)
       ? peerPublicKey
       : Buffer.from(peerPublicKey, 'base64');
@@ -48,12 +71,24 @@ export class Handshake {
     }
 
     this.#peerKeys.set(peerId, Buffer.from(pubBuf));
+    if (peerPQPublicKey) {
+      const pq = Buffer.isBuffer(peerPQPublicKey)
+        ? peerPQPublicKey
+        : Buffer.from(peerPQPublicKey, 'base64');
+      this.#peerPQKeys.set(peerId, pq);
+    }
 
     // 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),
+        new DoubleRatchet(
+          this.#mySessionId,
+          peerId,
+          this.#keyManager.secretKey,
+          pubBuf,
+          this.#pqFor(peerId),
+        ),
       );
     }
   }
@@ -130,6 +165,7 @@ export class Handshake {
    */
   removePeer(peerId) {
     this.#peerKeys.delete(peerId);
+    this.#peerPQKeys.delete(peerId);
     const prev = this.#previousPeerKeys.get(peerId);
     if (prev) {
       clearTimeout(prev.timer);
@@ -157,6 +193,11 @@ export class Handshake {
       this.#peerKeys.delete(oldPeerId);
       this.#peerKeys.set(newPeerId, peerKey);
     }
+    const pqKey = this.#peerPQKeys.get(oldPeerId);
+    if (pqKey) {
+      this.#peerPQKeys.delete(oldPeerId);
+      this.#peerPQKeys.set(newPeerId, pqKey);
+    }
     const prevKey = this.#previousPeerKeys.get(oldPeerId);
     if (prevKey) {
       this.#previousPeerKeys.delete(oldPeerId);

package/src/crypto/KeyManager.js

@@ -2,6 +2,7 @@
 import sodium from 'sodium-native';
 import { createHash } from 'node:crypto';
 import { KEY_ROTATION_GRACE_MS } from '../shared/constants.js';
+import { generatePQKeyPair } from './PQHybrid.js';
 
 export class KeyManager {
   #publicKey;
@@ -10,6 +11,7 @@ export class KeyManager {
   #previousPublicKey;
   #previousSecretKey;
   #graceTimer;
+  #pqKeyPair; // ML-KEM-768 — the hybrid half (see crypto/PQHybrid.js)
 
   constructor() {
     this.#publicKey = Buffer.alloc(sodium.crypto_box_PUBLICKEYBYTES);
@@ -19,10 +21,25 @@ export class KeyManager {
     this.#graceTimer = null;
 
     sodium.crypto_box_keypair(this.#publicKey, this.#secretKey);
+    this.#pqKeyPair = generatePQKeyPair();
 
     this.#fingerprint = KeyManager.computeFingerprint(this.#publicKey);
   }
 
+  // The identity fingerprint stays X25519-only on purpose: it is what users
+  // already verified out-of-band, and the KEM key adds no authentication.
+  get pqPublicKey() {
+    return this.#pqKeyPair.publicKey;
+  }
+
+  get pqPublicKeyB64() {
+    return this.#pqKeyPair.publicKey.toString('base64');
+  }
+
+  get pqSecretKey() {
+    return this.#pqKeyPair.secretKey;
+  }
+
   get publicKey() {
     return this.#publicKey;
   }
@@ -114,6 +131,8 @@ export class KeyManager {
     return {
       publicKey: this.#publicKey.toString('base64'),
       secretKey: this.#secretKey.toString('base64'),
+      pqPublicKey: this.#pqKeyPair.publicKey.toString('base64'),
+      pqSecretKey: this.#pqKeyPair.secretKey.toString('base64'),
     };
   }
 
@@ -129,6 +148,14 @@ export class KeyManager {
     km.#fingerprint = KeyManager.computeFingerprint(km.#publicKey);
     km.#previousPublicKey = null;
     km.#previousSecretKey = null;
+    // Restore the KEM pair when present; older backups simply get the fresh
+    // one generated above (peers re-encapsulate on the next handshake).
+    if (data.pqPublicKey && data.pqSecretKey) {
+      km.#pqKeyPair = {
+        publicKey: Buffer.from(data.pqPublicKey, 'base64'),
+        secretKey: Buffer.from(data.pqSecretKey, 'base64'),
+      };
+    }
     return km;
   }
 }

package/src/crypto/PQHybrid.js

@@ -0,0 +1,76 @@
+// Hybrid post-quantum layer: ML-KEM-768 (FIPS 203) mixed INTO the classical
+// X25519 root key, never replacing it. Security is therefore >= the classical
+// construction: an attacker must break BOTH to read a message. This is the
+// conservative pattern Signal (PQXDH) and Apple (PQ3) adopted, and it targets
+// "harvest now, decrypt later" — traffic recorded today stays unreadable to a
+// future quantum adversary.
+//
+// sodium-native has no ML-KEM, so this uses @noble/post-quantum (audited,
+// pure JS). Only the KEM comes from there; all symmetric crypto stays libsodium.
+import sodium from 'sodium-native';
+import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
+
+export const PQ_PUBLIC_KEY_SIZE = 1184; // ML-KEM-768 encapsulation key
+export const PQ_SECRET_KEY_SIZE = 2400; // ML-KEM-768 decapsulation key
+export const PQ_CIPHERTEXT_SIZE = 1088;
+export const PQ_SHARED_SECRET_SIZE = 32;
+
+const PQ_MIX_CONTEXT = 'ciphermesh/pq-hybrid-v3';
+
+/** Generate an ML-KEM-768 keypair. Buffers, to match the rest of the codebase. */
+export function generatePQKeyPair() {
+  const { publicKey, secretKey } = ml_kem768.keygen();
+  return { publicKey: Buffer.from(publicKey), secretKey: Buffer.from(secretKey) };
+}
+
+/**
+ * Encapsulate to a peer's ML-KEM public key.
+ * @returns {{ ciphertext: Buffer, sharedSecret: Buffer }|null} null on bad input
+ */
+export function pqEncapsulate(peerPublicKey) {
+  try {
+    const pk = Buffer.isBuffer(peerPublicKey)
+      ? peerPublicKey
+      : Buffer.from(peerPublicKey, 'base64');
+    if (pk.length !== PQ_PUBLIC_KEY_SIZE) {
+      return null;
+    }
+    const { cipherText, sharedSecret } = ml_kem768.encapsulate(new Uint8Array(pk));
+    return { ciphertext: Buffer.from(cipherText), sharedSecret: Buffer.from(sharedSecret) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decapsulate a ciphertext with our ML-KEM secret key.
+ * @returns {Buffer|null} 32-byte shared secret, or null if it doesn't apply
+ */
+export function pqDecapsulate(ciphertext, secretKey) {
+  try {
+    const ct = Buffer.isBuffer(ciphertext) ? ciphertext : Buffer.from(ciphertext, 'base64');
+    if (ct.length !== PQ_CIPHERTEXT_SIZE || !secretKey) {
+      return null;
+    }
+    const ss = ml_kem768.decapsulate(new Uint8Array(ct), new Uint8Array(secretKey));
+    return Buffer.from(ss);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fold a KEM shared secret into an existing root key:
+ *   root' = BLAKE2b(root ‖ ss ‖ context)
+ *
+ * Because the classical root is an input, the result is at least as strong as
+ * the classical key even if ML-KEM were broken outright. Returns a NEW locked
+ * buffer; the caller owns zeroing the old root.
+ */
+export function mixPQIntoRoot(rootKey, sharedSecret) {
+  const input = Buffer.concat([rootKey, sharedSecret, Buffer.from(PQ_MIX_CONTEXT, 'utf-8')]);
+  const mixed = sodium.sodium_malloc(32);
+  sodium.crypto_generichash(mixed, input);
+  sodium.sodium_memzero(input);
+  return mixed;
+}