ciphermesh 2.2.0 → 2.3.0

package/README.md

@@ -42,6 +42,7 @@ forwarding, survives CGNAT).
 |-----|---------|----------|
 | 🔐 | **Real E2EE** | Curve25519 + XSalsa20-Poly1305 via libsodium, keys in `sodium_malloc` — never touch disk |
 | 🔄 | **Perfect Forward Secrecy** | Double Ratchet: one key per message, compromise today ≠ read yesterday |
+| 🛡️ | **Hybrid post-quantum** | X25519 **+ ML-KEM-768** folded into the ratchet root — beats "harvest now, decrypt later" while staying ≥ classical security ([details](docs/ARCHITECTURE.md)) |
 | 🕶️ | **Metadata resistance** | **Sealed sender** — the relay never sees who sent a message — plus fixed-bucket length padding on every ciphertext and opt-in cover traffic (`/cover`) |
 | 🕵️ | **TOFU + SAS** | Key-change detection (MITM alarm), 6-digit voice-verifiable codes, and inline **✓/✗** trust badges next to names |
 | 🌐 | **LAN & internet** | Auto-detects Tailscale, shows the reachable address in the banner |
@@ -94,6 +95,13 @@ Prefer a prebuilt image? Pull the relay from GHCR (published on each release):
 docker run -p 3600:3600 ghcr.io/felipekreulich/secret-chat-lan:latest
 ```
 
+**No Node on the host?** Every release ships a standalone relay binary for
+macOS and Linux (arm64/x64) — download it from the
+[releases page](https://github.com/FelipeKreulich/secret-chat-lan/releases),
+`chmod +x`, run. Nothing to install. (The TUI client still needs Node/npx: it
+depends on blessed, which resolves its widgets at runtime and cannot be
+bundled.)
+
 **Everyone** (including the host):
 
 ```bash

package/README.pt-BR.md

@@ -42,6 +42,7 @@ forwarding, imune a CGNAT).
 |-----|---------|--------|
 | 🔐 | **E2EE de verdade** | Curve25519 + XSalsa20-Poly1305 via libsodium, chaves em `sodium_malloc` — nunca tocam o disco |
 | 🔄 | **Perfect Forward Secrecy** | Double Ratchet: uma chave por mensagem — comprometer hoje ≠ ler ontem |
+| 🛡️ | **Pós-quântico híbrido** | X25519 **+ ML-KEM-768** misturado na raiz do ratchet — vence o "grava hoje, decifra depois" mantendo segurança ≥ à clássica ([detalhes](docs/ARCHITECTURE.md)) |
 | 🕶️ | **Resistência a metadados** | **Sealed sender** — o relay nunca vê quem enviou a mensagem — + padding de comprimento em buckets fixos em todo ciphertext e cover traffic opcional (`/cover`) |
 | 🕵️ | **TOFU + SAS** | Alarme de troca de chave (MITM), código de 6 dígitos verificável por voz e badges de confiança **✓/✗** inline ao lado dos nomes |
 | 🌐 | **LAN e internet** | Detecta Tailscale sozinho e mostra o endereço alcançável no banner |
@@ -94,6 +95,13 @@ Prefere imagem pronta? Baixe o relay do GHCR (publicado a cada release):
 docker run -p 3600:3600 ghcr.io/felipekreulich/secret-chat-lan:latest
 ```
 
+**Sem Node na máquina?** Todo release traz um binário standalone do relay para
+macOS e Linux (arm64/x64) — baixe da
+[página de releases](https://github.com/FelipeKreulich/secret-chat-lan/releases),
+`chmod +x`, rode. Nada para instalar. (O cliente TUI ainda precisa de Node/npx:
+ele depende do blessed, que resolve os widgets em runtime e não pode ser
+empacotado.)
+
 **Todo mundo** (incluindo quem hospeda):
 
 ```bash

package/bin/server-binary.js

@@ -0,0 +1,7 @@
+// Entry point for the standalone relay binary (`bun build --compile`).
+//
+// Server-only on purpose: the TUI client depends on blessed, which resolves
+// its widgets through dynamic requires that no bundler can follow. The relay
+// has no such dependency, and "run a CipherMesh relay without installing
+// Node" is exactly what self-hosters need.
+import '../src/server/index.js';

package/docs/ARCHITECTURE.md

@@ -741,6 +741,42 @@ fingerprint = SHA-256(publicKey)
             = "A1B2:C3D4:E5F6:7890"
 ```
 
+### 6.10 Hybrid Post-Quantum Handshake (X25519 + ML-KEM-768)
+
+Protects against **"harvest now, decrypt later"**: traffic recorded today stays
+unreadable to a future quantum adversary. The construction is **hybrid** — the
+KEM secret is folded INTO the classical root, never replacing it, so security
+is at least that of X25519 even if ML-KEM were broken (`src/crypto/PQHybrid.js`).
+
+```
+Each client publishes an ML-KEM-768 key alongside its X25519 key (join,
+peer lists, peer_joined). Per pair, at ratchet creation:
+
+  initiator (lower sessionId):
+      (ct, ss) = ML-KEM.Encaps(peer.pqPublicKey)
+      root' = BLAKE2b(root ‖ ss ‖ "ciphermesh/pq-hybrid-v3")
+      → ct rides in the message envelope (sealed to the recipient)
+
+  responder, on the first envelope carrying ct:
+      ss = ML-KEM.Decaps(ct, mySecretKey)
+      root' = BLAKE2b(root ‖ ss ‖ "ciphermesh/pq-hybrid-v3")   ← same value
+```
+
+**Why this can't desynchronize:** the mix happens exactly once, at ratchet
+initialization, before any chain key is derived — never mid-stream. There is no
+window in which one side has mixed and the other has not while messages are in
+flight: an envelope without the `ct` simply fails its MAC (fails closed, never
+garbles). Once the peer replies successfully, the initiator stops attaching
+`ct` (~1KB saved per envelope).
+
+**Compatibility:** a peer without `pqPublicKey` (pre-2.3 client) gets a
+classical-only session — same behaviour as before. `/trustlist` shows `[PQ]`
+next to peers whose session is hybrid.
+
+**Not yet hybrid (documented, planned for v3.1):** sealed-sender envelopes and
+the private-room content layer remain classical; they protect metadata and
+room content respectively, not the message stream's forward secrecy.
+
 ### 6.9 Private Rooms (password-protected, zero-knowledge)
 
 `/create <room> <password>` creates a room the server can gate **without ever

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ciphermesh",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Secure terminal chat for the local network (LAN) with real end-to-end encryption (E2EE) using libsodium",
   "type": "module",
   "main": "src/client/index.js",
@@ -51,6 +51,7 @@
     "docker:logs": "docker compose logs -f"
   },
   "dependencies": {
+    "@noble/post-quantum": "0.6.1",
     "blessed": "0.1.81",
     "bonjour-service": "1.4.3",
     "boxen": "8.0.1",

package/src/client/ChatController.js

@@ -206,7 +206,9 @@ export class ChatController {
   // attached the listener).
   #onConnected() {
     this.#ui.setConnectionState('online');
-    this.#connection.send(createJoin(this.#nickname, this.#keyManager.publicKeyB64));
+    this.#connection.send(
+      createJoin(this.#nickname, this.#keyManager.publicKeyB64, this.#keyManager.pqPublicKeyB64),
+    );
   }
 
   // ── Connection event handlers ─────────────────────────────────
@@ -536,7 +538,7 @@ export class ChatController {
         // Migrate ratchet from old sessionId to new sessionId
         this.#handshake.migrateRatchet(oldSid, peer.sessionId);
       } else if (!oldSid) {
-        this.#handshake.registerPeer(peer.sessionId, peer.publicKey);
+        this.#handshake.registerPeer(peer.sessionId, peer.publicKey, peer.pqPublicKey);
       }
 
       this.#checkTrust(peer.nickname, peer.publicKey);
@@ -740,7 +742,7 @@ export class ChatController {
         publicKey: peer.publicKey,
         rooms: new Set([room]),
       });
-      this.#handshake.registerPeer(peer.sessionId, peer.publicKey);
+      this.#handshake.registerPeer(peer.sessionId, peer.publicKey, peer.pqPublicKey);
     }
     this.#checkTrust(peer.nickname, peer.publicKey);
     this.#auditLog.log(AuditEvent.PEER_CONNECTED, { nickname: peer.nickname, room });
@@ -864,6 +866,7 @@ export class ChatController {
           ephPub,
           msg.payload.counter,
           msg.payload.previousCounter,
+          msg.payload.pqCiphertext ? Buffer.from(msg.payload.pqCiphertext, 'base64') : null,
         );
       }
 
@@ -1516,7 +1519,7 @@ export class ChatController {
           break;
         }
         this.#ui.addInfoMessage('Trust status:');
-        for (const p of peerList) {
+        for (const [sid, p] of this.#peers) {
           const record = this.#trustStore.getPeerRecord(p.nickname);
           let status;
           if (!record) {
@@ -1526,8 +1529,11 @@ export class ChatController {
           } else {
             status = 'trusted (TOFU)';
           }
-          this.#ui.addInfoMessage(`  ${p.nickname}: ${status}`);
+          // [PQ] = this session's ratchet root also includes an ML-KEM secret.
+          const pq = this.#handshake.isHybrid(sid) ? ' {green-fg}[PQ]{/green-fg}' : '';
+          this.#ui.addInfoMessage(`  ${p.nickname}: ${status}${pq}`);
         }
+        this.#ui.addInfoMessage('  [PQ] = hybrid post-quantum session (X25519 + ML-KEM-768)');
         break;
       }
 
@@ -2440,7 +2446,9 @@ export class ChatController {
         // "nickname taken"): the server still accepts a JOIN on this socket.
         this.#nickname = newNick;
         this.#ui.setNickname(newNick);
-        this.#connection.send(createJoin(newNick, this.#keyManager.publicKeyB64));
+        this.#connection.send(
+          createJoin(newNick, this.#keyManager.publicKeyB64, this.#keyManager.pqPublicKeyB64),
+        );
         this.#ui.addSystemMessage(`Trying to join as ${newNick}...`);
         break;
       }
@@ -2668,7 +2676,7 @@ export class ChatController {
         rooms: new Set([msg.room]),
       });
       if (!this.#handshake.getRatchet(peer.sessionId)) {
-        this.#handshake.registerPeer(peer.sessionId, peer.publicKey);
+        this.#handshake.registerPeer(peer.sessionId, peer.publicKey, peer.pqPublicKey);
       }
       this.#checkTrust(peer.nickname, peer.publicKey);
     }
@@ -2703,7 +2711,7 @@ export class ChatController {
           rooms: new Set([msg.room]),
         });
         if (!this.#handshake.getRatchet(peer.sessionId)) {
-          this.#handshake.registerPeer(peer.sessionId, peer.publicKey);
+          this.#handshake.registerPeer(peer.sessionId, peer.publicKey, peer.pqPublicKey);
         }
       }
       this.#checkTrust(peer.nickname, peer.publicKey);

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;
+}

package/src/protocol/messages.js

@@ -45,8 +45,14 @@ function base(type) {
   return { type, version: PROTOCOL_VERSION, timestamp: Date.now() };
 }
 
-export function createJoin(nickname, publicKeyB64) {
-  return { ...base(MSG.JOIN), nickname, publicKey: publicKeyB64 };
+// pqPublicKey (v3, optional): ML-KEM-768 encapsulation key for the hybrid
+// post-quantum handshake. Absent = classical-only peer (pre-2.3 client).
+export function createJoin(nickname, publicKeyB64, pqPublicKeyB64 = null) {
+  const msg = { ...base(MSG.JOIN), nickname, publicKey: publicKeyB64 };
+  if (pqPublicKeyB64) {
+    msg.pqPublicKey = pqPublicKeyB64;
+  }
+  return msg;
 }
 
 export function createJoinAck(sessionId, peers, queuedCount = 0, room = 'general') {
@@ -85,18 +91,20 @@ export function createEncryptedMessage(from, to, ciphertextB64, nonceB64) {
 }
 
 export function createRatchetedMessage(from, to, payload) {
-  return {
-    ...base(MSG.ENCRYPTED_MESSAGE),
-    from,
-    to,
-    payload: {
-      ephemeralPublicKey: payload.ephemeralPublicKey.toString('base64'),
-      counter: payload.counter,
-      previousCounter: payload.previousCounter,
-      ciphertext: payload.ciphertext.toString('base64'),
-      nonce: payload.nonce.toString('base64'),
-    },
+  const inner = {
+    ephemeralPublicKey: payload.ephemeralPublicKey.toString('base64'),
+    counter: payload.counter,
+    previousCounter: payload.previousCounter,
+    ciphertext: payload.ciphertext.toString('base64'),
+    nonce: payload.nonce.toString('base64'),
   };
+  // Hybrid PQ: the KEM ciphertext rides along until the peer has folded it in.
+  // It is sealed to the recipient like everything else — the relay sees only
+  // an opaque blob.
+  if (payload.pqCiphertext) {
+    inner.pqCiphertext = payload.pqCiphertext.toString('base64');
+  }
+  return { ...base(MSG.ENCRYPTED_MESSAGE), from, to, payload: inner };
 }
 
 // Sealed-sender envelope (protocol v2): the relay sees only the recipient and an

package/src/protocol/validators.js

@@ -7,6 +7,7 @@ import {
   ROOM_AUTH_SIG_SIZE,
   ROOM_CHALLENGE_NONCE_SIZE,
 } from '../shared/constants.js';
+import { PQ_PUBLIC_KEY_SIZE } from '../crypto/PQHybrid.js';
 
 // ── Helpers ────────────────────────────────────────────────────
 function isString(v) {
@@ -86,7 +87,11 @@ export function validateJoin(msg) {
   if (!isValidBase64(msg.publicKey, PUBLIC_KEY_SIZE)) {
     return { valid: false, error: 'Invalid public key' };
   }
-  return { valid: true, nickname: nick };
+  // Optional ML-KEM-768 key (hybrid PQ). Absent = classical-only client.
+  if (msg.pqPublicKey !== undefined && !isValidBase64(msg.pqPublicKey, PQ_PUBLIC_KEY_SIZE)) {
+    return { valid: false, error: 'Invalid post-quantum public key' };
+  }
+  return { valid: true, nickname: nick, pqPublicKey: msg.pqPublicKey || null };
 }
 
 // Sealed sender (protocol v2): the relay only ever sees the recipient and an

package/src/server/SessionManager.js

@@ -30,12 +30,13 @@ export class SessionManager {
     return this.#nicknames.has(nickname.toLowerCase());
   }
 
-  addSession(ws, nickname, publicKey, room = 'general') {
+  addSession(ws, nickname, publicKey, room = 'general', pqPublicKey = null) {
     const sessionId = randomUUID();
     const session = {
       ws,
       nickname,
       publicKey,
+      pqPublicKey, // ML-KEM-768 key, relayed verbatim (server never uses it)
       connectedAt: Date.now(),
       rooms: new Set(),
     };
@@ -102,6 +103,7 @@ export class SessionManager {
           sessionId: id,
           nickname: session.nickname,
           publicKey: session.publicKey,
+          ...(session.pqPublicKey ? { pqPublicKey: session.pqPublicKey } : {}),
         });
       }
     }

package/src/server/WebSocketServer.js

@@ -259,7 +259,13 @@ export class SecureWSServer {
     }
 
     const room = 'general';
-    const sessionId = this.#sessionManager.addSession(ws, validation.nickname, msg.publicKey, room);
+    const sessionId = this.#sessionManager.addSession(
+      ws,
+      validation.nickname,
+      msg.publicKey,
+      room,
+      validation.pqPublicKey,
+    );
     ws.sessionId = sessionId;
     ws.hasJoined = true;
     clearTimeout(ws.joinTimer);
@@ -292,6 +298,7 @@ export class SecureWSServer {
         sessionId,
         nickname: validation.nickname,
         publicKey: msg.publicKey,
+        ...(validation.pqPublicKey ? { pqPublicKey: validation.pqPublicKey } : {}),
       }),
       sessionId,
     );
@@ -508,7 +515,12 @@ export class SecureWSServer {
     this.#sessionManager.broadcastToRoom(
       room,
       createPeerJoined(
-        { sessionId: ws.sessionId, nickname: session.nickname, publicKey: session.publicKey },
+        {
+          sessionId: ws.sessionId,
+          nickname: session.nickname,
+          publicKey: session.publicKey,
+          ...(session.pqPublicKey ? { pqPublicKey: session.pqPublicKey } : {}),
+        },
         room,
       ),
       ws.sessionId,
@@ -642,6 +654,7 @@ export class SecureWSServer {
           sessionId: ws.sessionId,
           nickname: session.nickname,
           publicKey: session.publicKey,
+          ...(session.pqPublicKey ? { pqPublicKey: session.pqPublicKey } : {}),
         },
         result.newRoom,
       ),