ciphermesh 1.2.0 → 2.0.0

package/README.md

@@ -42,8 +42,8 @@ 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 |
-| 🕶️ | **Metadata resistance** | Fixed-bucket length padding on every ciphertext + opt-in cover traffic (`/cover`) to blur when you chat |
-| 🕵️ | **TOFU + SAS** | Key-change detection (MITM alarm) and 6-digit voice-verifiable codes |
+| 🕶️ | **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 |
 | 📨 | **Invites with QR** | `/invite` prints a `ciphermesh://` string + QR — paste it, you're in the right room |
 | ✓✓ | **Encrypted read receipts** | The ✓✓ travels as ordinary ciphertext — the server can't tell it apart |
@@ -116,6 +116,7 @@ QR code) to whoever you want to pull in.
 | Command | Description |
 |---------|-------------|
 | `/help` | All commands |
+| `/tips` | Show a rotating security/UX tip |
 | `/users` | Who's online (with away/status) |
 | `/msg <nick> <text>` | Private message (DM) |
 | `/reply <text>` | Reply quoting the last received message |
@@ -156,6 +157,8 @@ QR code) to whoever you want to pull in.
 | `/receipts [on\|off]` | Send read receipts (✓✓) |
 | `/audit [n]` | Local audit log |
 
+A green **✓** next to a name marks a SAS-verified peer; a red **✗** flags a key that changed since you last saw it (possible MITM). A newly-arrived unverified peer triggers a one-time reminder to `/verify` them.
+
 </details>
 
 <details>

package/README.pt-BR.md

@@ -42,8 +42,8 @@ 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 |
-| 🕶️ | **Resistência a metadados** | Padding de comprimento em buckets fixos em todo ciphertext + cover traffic opcional (`/cover`) pra borrar quando você conversa |
-| 🕵️ | **TOFU + SAS** | Alarme de troca de chave (MITM) e código de 6 dígitos verificável por voz |
+| 🕶️ | **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 |
 | 📨 | **Convites com QR** | `/invite` gera uma string `ciphermesh://` + QR — colou, caiu na sala certa |
 | ✓✓ | **Read receipts cifrados** | O ✓✓ viaja como ciphertext comum — o servidor não distingue de mensagem |
@@ -116,6 +116,7 @@ quem você quiser puxar pra conversa.
 | Comando | Descrição |
 |---------|-----------|
 | `/help` | Todos os comandos |
+| `/tips` | Mostra uma dica rotativa de segurança/UX |
 | `/users` | Quem está online (com away/status) |
 | `/msg <nick> <texto>` | Mensagem privada (DM) |
 | `/reply <texto>` | Responde citando a última mensagem recebida |
@@ -156,6 +157,8 @@ quem você quiser puxar pra conversa.
 | `/receipts [on\|off]` | Envio de confirmação de leitura (✓✓) |
 | `/audit [n]` | Log de auditoria local |
 
+Um **✓** verde ao lado de um nome indica um peer verificado por SAS; um **✗** vermelho sinaliza uma chave que mudou desde a última vez (possível MITM). Um peer novo não-verificado dispara um lembrete único para `/verify`.
+
 </details>
 
 <details>

package/docs/ARCHITECTURE.md

@@ -533,18 +533,14 @@ export const FILE_CHUNK_SIZE = 49152;            // 48KB
 ```json
 {
   "type": "encrypted_message",
-  "version": 1,
+  "version": 2,
   "timestamp": 1739800001000,
-  "from": "550e8400-e29b-41d4-a716-446655440000",
   "to": "660e8400-e29b-41d4-a716-446655440001",
-  "payload": {
-    "ciphertext": "base64(mensagem cifrada com crypto_box_easy)",
-    "nonce": "base64(24 bytes do nonce usado)"
-  }
+  "sealed": "base64( crypto_box_seal({ from, payload }, recipientPublicKey) )"
 }
 ```
 
-**Note**: The `payload` field is completely opaque to the server. It only reads `from` and `to` for routing.
+**Note (sealed sender, v2)**: The relay sees only `to` (for routing) and an opaque `sealed` blob. The sender (`from`) *and* the whole already-E2E-encrypted `payload` are sealed to the recipient's public key with libsodium `crypto_box_seal` — an anonymous box only the recipient can open. The relay therefore learns **neither who sent the message nor what's inside**, and it never stamps, stores, or logs a sender. The recipient opens the seal to recover `{ from, payload }`, then decrypts the payload as before. (See §10 for the exact — honest — guarantee and its limits.)
 
 ### 5.4 Decrypted content (never travels in cleartext)
 
@@ -939,17 +935,29 @@ a server change and is not wired up there yet.)
 | **Denial of Service** | Rate limiting + maxPayload | Partial |
 | **Forward secrecy** | Double Ratchet — a unique key per message | Mitigated |
 | **Metadata analysis** | Message padding + fixed sizes | Partial |
+| **Relay learns who SENT each message** | Sealed sender — the sender + payload are sealed to the recipient; the relay routes by recipient only and never stamps, stores, or logs a sender | Partial (honest relay) |
 
 ### 10.2 What the server CAN deduce (metadata)
 
 Even without reading content, the server knows:
-- **Who** is online
-- **Who** talks to whom
+- **Who** is online (the roster: nicknames + public keys, from JOIN)
+- **To whom** each message is routed (the recipient) — *the **sender** is hidden by sealed sender; an honest relay never learns who sent a given message*
 - **When** messages are sent — *mitigated by cover traffic (optional)*
 - **Approximate size** of messages — *mitigated: only the padding bucket leaks*
 - **Frequency** of communication — *mitigated by cover traffic (optional)*
 
 Implemented mitigations:
+- **Sealed sender** (`crypto/SealedSender.js`, protocol v2): every
+  `encrypted_message` carries only `to` + an opaque `sealed` blob. The sender's
+  identity and the inner payload are wrapped in a libsodium `crypto_box_seal`
+  (anonymous box) to the recipient's key; the relay routes by recipient and
+  **never stamps, stores, or logs who sent a message**. *Honest guarantee &
+  limits:* this protects against an honest-but-curious relay, offline-queue
+  compromise, and network observers — the same model as Signal's sealed sender.
+  It does **not** anonymise the sender against a *malicious* relay that
+  correlates the sending socket (inherent to a persistent authenticated
+  connection), the **recipient** is still visible (routing needs it), and P2P
+  mode has no relay at all.
 - **Length padding** (`MessageCrypto.padMessage`, buckets
   `[128..32768]`): applied on all three encryption paths (static, ratchet, and
   deniable) before encrypting. The server sees only which bucket, not the real size.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ciphermesh",
-  "version": "1.2.0",
+  "version": "2.0.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",

package/src/client/ChatController.js

@@ -9,6 +9,7 @@ import {
   createJoin,
   createEncryptedMessage,
   createRatchetedMessage,
+  createSealedMessage,
   createKeyUpdate,
   createChangeRoom,
   createListRooms,
@@ -17,6 +18,7 @@ import {
   createBanPeer,
   ERR,
 } from '../protocol/messages.js';
+import { sealEnvelope, openEnvelope } from '../crypto/SealedSender.js';
 import { KEY_ROTATION_INTERVAL_MS, EMOJI_MAP, COVER_CONSTANT_MS } from '../shared/constants.js';
 import { KeyManager } from '../crypto/KeyManager.js';
 import { Handshake } from '../crypto/Handshake.js';
@@ -507,6 +509,19 @@ export class ChatController {
 
   // ── Received encrypted message ────────────────────────────────
   #onEncryptedMessage(msg) {
+    // Sealed sender: the relay handed us only `to` + an opaque blob. Open it
+    // with our identity key to recover the real sender + payload; from here the
+    // rest of the handler is unchanged. A blob that isn't for us (or is tampered)
+    // simply fails to open and is dropped.
+    if (typeof msg.sealed === 'string') {
+      const opened = this.#openSealed(msg.sealed);
+      if (!opened || typeof opened.from !== 'string' || !opened.payload) {
+        return;
+      }
+      // Rebind to a fresh object — never mutate the received message.
+      msg = { ...msg, from: opened.from, payload: opened.payload };
+    }
+
     const peer = this.#peers.get(msg.from);
     if (!peer) {
       this.#ui.addErrorMessage('Message from unknown peer');
@@ -908,6 +923,7 @@ export class ChatController {
       case '/help':
         this.#ui.addInfoMessage('Available commands:');
         this.#ui.addInfoMessage('  /help                - Show this help');
+        this.#ui.addInfoMessage('  /tips                - Show a security/UX tip');
         this.#ui.addInfoMessage('  /users               - List online users');
         this.#ui.addInfoMessage('  /msg <nick> <text>   - Send a private message (DM)');
         this.#ui.addInfoMessage('  /reply <text>        - Reply to the last received message');
@@ -925,6 +941,7 @@ export class ChatController {
         this.#ui.addInfoMessage('  /verify-confirm <nick> - Confirm peer verification');
         this.#ui.addInfoMessage("  /trust <nick>        - Accept a peer's new key");
         this.#ui.addInfoMessage("  /trustlist           - Peers' trust status");
+        this.#ui.addInfoMessage('  (✓ = verified peer · ✗ = key changed — shown next to a name)');
         this.#ui.addInfoMessage('  /clear               - Clear the chat');
         this.#ui.addInfoMessage('  /file <path>         - Send a file (max 50MB)');
         this.#ui.addInfoMessage(
@@ -2119,6 +2136,28 @@ export class ChatController {
     }
   }
 
+  // Sealed sender: wrap an outgoing wire message so the relay sees only `to` and
+  // an opaque blob. The sender identity (`from`) + the payload are sealed to the
+  // recipient's key — only they can open it.
+  #sealAndSend(recipientPublicKey, wireMsg) {
+    const sealed = sealEnvelope(wireMsg.from, wireMsg.payload, recipientPublicKey);
+    this.#connection.send(createSealedMessage(wireMsg.to, sealed));
+  }
+
+  // Open a sealed envelope with our identity key, falling back to the previous
+  // key during the post-rotation grace window. Returns { from, payload } or null.
+  #openSealed(sealedB64) {
+    let opened = openEnvelope(sealedB64, this.#keyManager.publicKey, this.#keyManager.secretKey);
+    if (!opened && this.#keyManager.previousPublicKey) {
+      opened = openEnvelope(
+        sealedB64,
+        this.#keyManager.previousPublicKey,
+        this.#keyManager.previousSecretKey,
+      );
+    }
+    return opened;
+  }
+
   // ── Send encrypted payload to a single peer ────────────────────
   #sendPayloadToPeer(peerId, payload) {
     const peerPublicKey = this.#handshake.getPeerPublicKey(peerId);
@@ -2130,7 +2169,7 @@ export class ChatController {
     if (ratchet && ratchet.isInitialized) {
       try {
         const result = ratchet.encrypt(payload);
-        this.#connection.send(createRatchetedMessage(this.#sessionId, peerId, result));
+        this.#sealAndSend(peerPublicKey, createRatchetedMessage(this.#sessionId, peerId, result));
         return;
       } catch {
         // Fall through to static path
@@ -2144,7 +2183,8 @@ export class ChatController {
       peerPublicKey,
       this.#handshake.secretKey,
     );
-    this.#connection.send(
+    this.#sealAndSend(
+      peerPublicKey,
       createEncryptedMessage(
         this.#sessionId,
         peerId,
@@ -2260,7 +2300,7 @@ export class ChatController {
           nonce.toString('base64'),
         );
         msg.payload.deniable = true;
-        this.#connection.send(msg);
+        this.#sealAndSend(peerPublicKey, msg);
         continue;
       }
 
@@ -2269,7 +2309,7 @@ export class ChatController {
       if (ratchet && ratchet.isInitialized) {
         try {
           const result = ratchet.encrypt(payload);
-          this.#connection.send(createRatchetedMessage(this.#sessionId, peerId, result));
+          this.#sealAndSend(peerPublicKey, createRatchetedMessage(this.#sessionId, peerId, result));
           continue;
         } catch {
           // Ratchet failed — fall through to static path
@@ -2285,7 +2325,8 @@ export class ChatController {
         this.#handshake.secretKey,
       );
 
-      this.#connection.send(
+      this.#sealAndSend(
+        peerPublicKey,
         createEncryptedMessage(
           this.#sessionId,
           peerId,

package/src/p2p/P2PChatController.js

@@ -677,6 +677,7 @@ export class P2PChatController {
       case '/help':
         this.#ui.addInfoMessage('Available commands (P2P mode):');
         this.#ui.addInfoMessage('  /help                - Show this help');
+        this.#ui.addInfoMessage('  /tips                - Show a security/UX tip');
         this.#ui.addInfoMessage('  /users               - List connected peers');
         this.#ui.addInfoMessage('  /msg <nick> <text>   - Send a private message (DM)');
         this.#ui.addInfoMessage('  /fingerprint         - Show your fingerprint');
@@ -685,6 +686,7 @@ export class P2PChatController {
         this.#ui.addInfoMessage('  /verify-confirm <nick> - Confirm verification');
         this.#ui.addInfoMessage('  /trust <nick>        - Accept a new key');
         this.#ui.addInfoMessage('  /trustlist           - Trust status');
+        this.#ui.addInfoMessage('  (✓ = verified peer · ✗ = key changed — shown next to a name)');
         this.#ui.addInfoMessage('  /clear               - Clear the chat');
         this.#ui.addInfoMessage('  /file <path>         - Send a file (max 50MB)');
         this.#ui.addInfoMessage(

package/src/protocol/messages.js

@@ -81,6 +81,13 @@ export function createRatchetedMessage(from, to, payload) {
   };
 }
 
+// Sealed-sender envelope (protocol v2): the relay sees only the recipient and an
+// opaque blob. The sender's identity + the inner payload are sealed to the
+// recipient's key (see crypto/SealedSender.js). There is deliberately no `from`.
+export function createSealedMessage(to, sealedB64) {
+  return { ...base(MSG.ENCRYPTED_MESSAGE), to, sealed: sealedB64 };
+}
+
 export function createError(code, message) {
   return { ...base(MSG.ERROR), code, message };
 }

package/src/protocol/validators.js

@@ -86,33 +86,18 @@ export function validateJoin(msg) {
   return { valid: true, nickname: nick };
 }
 
+// Sealed sender (protocol v2): the relay only ever sees the recipient and an
+// opaque sealed blob — never the sender or the inner payload. So there is
+// nothing to validate here beyond routing target + a non-empty base64 envelope
+// (the overall size is already capped in validateMessage). The recipient's
+// unseal is fail-safe on garbage, so the relay needn't inspect further.
 export function validateEncryptedMessage(msg) {
-  if (!isString(msg.from) || !isString(msg.to)) {
-    return { valid: false, error: 'Missing from/to fields' };
+  if (!isString(msg.to)) {
+    return { valid: false, error: 'Missing to field' };
   }
-  if (!isObject(msg.payload)) {
-    return { valid: false, error: 'Missing payload' };
+  if (!isValidBase64(msg.sealed)) {
+    return { valid: false, error: 'Missing or invalid sealed envelope' };
   }
-  if (!isString(msg.payload.ciphertext) || !isString(msg.payload.nonce)) {
-    return { valid: false, error: 'Invalid payload structure' };
-  }
-  if (!isValidBase64(msg.payload.nonce, 24)) {
-    return { valid: false, error: 'Invalid nonce' };
-  }
-
-  // Ratcheted message: validate extra fields
-  if (msg.payload.ephemeralPublicKey !== undefined) {
-    if (!isValidBase64(msg.payload.ephemeralPublicKey, PUBLIC_KEY_SIZE)) {
-      return { valid: false, error: 'Invalid ephemeral public key' };
-    }
-    if (!Number.isInteger(msg.payload.counter) || msg.payload.counter < 0) {
-      return { valid: false, error: 'Invalid counter' };
-    }
-    if (!Number.isInteger(msg.payload.previousCounter) || msg.payload.previousCounter < 0) {
-      return { valid: false, error: 'Invalid previousCounter' };
-    }
-  }
-
   return { valid: true };
 }
 

package/src/server/MessageRouter.js

@@ -53,7 +53,9 @@ export class MessageRouter {
 
     if (recipientSession.ws.readyState === 1) {
       recipientSession.ws.send(JSON.stringify(msg));
-      log.debug(`${senderSessionId.slice(0, 8)} -> ${msg.to.slice(0, 8)}`);
+      // Sealed sender: never log who sent it — only that something was routed to
+      // the recipient. Correlating sender->recipient in logs would defeat it.
+      log.debug(`routed -> ${msg.to.slice(0, 8)}`);
     }
   }
 

package/src/server/WebSocketServer.js

@@ -293,8 +293,11 @@ export class SecureWSServer {
       return;
     }
 
-    // Ensure the 'from' field matches the sender's actual session
-    msg.from = ws.sessionId;
+    // Sealed sender: the relay routes purely by `to`. It deliberately does NOT
+    // learn, stamp, store, or log who sent this — the sender's identity is
+    // sealed inside the envelope for the recipient only. Strip any stray `from`
+    // a client might set so it can never be forwarded.
+    delete msg.from;
 
     this.#messageRouter.route(ws.sessionId, msg);
   }

package/src/shared/constants.js

@@ -1,4 +1,4 @@
-export const PROTOCOL_VERSION = 1;
+export const PROTOCOL_VERSION = 2; // v2: sealed sender (encrypted_message carries `sealed`, no `from`)
 
 // Network
 export const SERVER_PORT = 3600;