ciphermesh 2.4.0 → 2.6.0

package/README.md

@@ -16,7 +16,7 @@
 [![Node](https://img.shields.io/badge/node-%E2%89%A5%2020-brightgreen)](package.json)
 [![Crypto](https://img.shields.io/badge/E2EE-libsodium-7b2dff)](docs/ARCHITECTURE.md)
 
-**[🇧🇷 Leia em Português](README.pt-BR.md)** · [Setup Guide](docs/SETUP.md) · [Architecture](docs/ARCHITECTURE.md) · [Security Policy](SECURITY.md)
+**[🇧🇷 Leia em Português](README.pt-BR.md)** · [Setup Guide](docs/SETUP.md) · [Architecture](docs/ARCHITECTURE.md) · [Security Policy](SECURITY.md) · [Hub Terms](TERMS.md)
 
 <img src="docs/demo.svg" alt="CipherMesh terminal demo" width="720">
 
@@ -55,17 +55,35 @@ forwarding, survives CGNAT).
 | 🎞️ | **Animated UI** | Splash intro, reconnect spinner, live transfer bars (shimmer + ETA), a lock-closing handshake on connect, and a pulsing "new messages ↓" pill |
 | 👻 | **Deniable & ephemeral** | Symmetric-crypto deniable mode; ephemeral messages *burn away* char-by-char when they expire |
 | 🔒 | **Private rooms** | `/create <room> <password>` — zero-knowledge: the password never leaves your machine (Argon2id → Ed25519 challenge-response) and room content gets an extra symmetric layer the relay can't fake its way into |
-| 🛰️ | **Serverless P2P mode** | mDNS peer discovery on the LAN — no relay at all |
+| 🗂️ | **Multi-room buffers** | Be in several rooms at once — **Alt+1..9** switches, unread badges per room. Which room a message belongs to travels *inside* the encrypted payload: the relay never learns it |
+| 🩺 | **It explains itself** | `/doctor` diagnoses a failing connection layer by layer — address, DNS, TCP, TLS, protocol — and tells you what to do about each failure |
+| 🔐 | **Screen lock** | `/lock` and `/autolock` put the session behind your passphrase when you step away; `/panic` is still there for the worse moment |
+| 🛰️ | **Serverless P2P mode** | mDNS peer discovery on the LAN — no relay at all, and nearly the same command set |
 | 🧩 | **Plugins** | Drop a JS file in `~/.ciphermesh/plugins` and get new slash-commands — `/roll` and `/poll` examples included ([Plugin API](docs/PLUGINS.md)) |
 
 ## 🚀 Quick start
 
-Run it without cloning (once published to npm):
+**Talk to someone in under a minute** — no install, no account, no server of
+your own:
 
 ```bash
-npx ciphermesh          # client (default)
-npx ciphermesh server   # relay server
-npx ciphermesh p2p      # serverless P2P
+npx ciphermesh@latest
+```
+
+At the `Server` prompt type **`ciphermesh.de`** — a public relay anyone can
+use. Share a room name with whoever you want to talk to (`/join ourroom`) and
+you are chatting end-to-end encrypted.
+
+> The hub is run as a personal project under these **[terms](TERMS.md)**. It is
+> a zero-knowledge relay: nobody operating it can read your messages — that is
+> a property of the software, not a promise. Prefer your own? Every command
+> below works the same on a relay you host.
+
+Other modes:
+
+```bash
+npx ciphermesh server   # run your own relay
+npx ciphermesh p2p      # serverless, mDNS peer discovery on the LAN
 ```
 
 macOS/Linux with Homebrew (see [`Formula/ciphermesh.rb`](Formula/ciphermesh.rb)):
@@ -212,6 +230,7 @@ A green **✓** next to a name marks a SAS-verified peer; a red **✗** flags a
 | `/img [path]` | Render the last received image in **full resolution** (kitty/iTerm2) |
 | `/search <term>` | Search the encrypted local history (on disk, across sessions) |
 | `/find [term]` — **Ctrl+F** | Search **this room's scrollback** and press Enter to **jump to the message**, highlighted |
+| `/doctor [host:port]` | Diagnose why a connection fails: address, DNS, TCP port, TLS (CA vs self-signed) and protocol version — each failure with what to do about it |
 | `/history [n]` | Last n messages from history |
 | `/retention <7d\|24h\|30m>` | Purge local history older than the given age |
 | `/export [path]` | Export history as .txt or .json (plaintext!) |
@@ -226,8 +245,8 @@ A green **✓** next to a name marks a SAS-verified peer; a red **✗** flags a
 | `/away [reason]` / `/back` | Mark yourself away — while away, unreads are counted (`[away · N new]`) and `/back` shows a summary |
 | `/mentions [n]` | Recent mentions of you this session (who, where, when) |
 | `/status <text\|off>` | Free-form status — emojis welcome (`/status :fire: coding`) |
-| `/react <emoji>` | React to the last message |
-| `/edit` `/delete` | Edit/delete your last message |
+| `/react <emoji>` | React to the last message — the emoji lands **on the message**, with a count when several people react |
+| `/edit` `/delete` | Edit or delete your last message — the **original line is rewritten in place** (marked *(edited)*) or replaced by a tombstone, instead of a new line you have to mentally staple to it |
 | `/pin` `/unpin` `/pins` | Pin messages |
 | `/sound` `/notify` | Sound / desktop notifications |
 | `/dnd [on\|off\|mentions\|HH:MM-HH:MM]` | Do-not-disturb, mentions-only, or quiet hours |
@@ -284,11 +303,19 @@ All keys are optional (unknown keys are ignored):
   active chatting from idle. Decoys are dropped silently by the receiver.
 - **Anti-replay** via monotonic nonces, **key rotation** every hour with a
   grace window, **secure memory wipe** (`sodium_memzero`) after use.
-- **Duress wipe** (`/panic sim`): overwrites and deletes every on-disk secret
+- **Duress wipe** (`/panic yes`): overwrites and deletes every on-disk secret
   (session state, history, trust store, audit log), zeroes the in-memory keys,
   and exits without saving — for a lost or seized device.
 - Session state and local history are encrypted at rest with
   **Argon2id + XSalsa20-Poly1305** — no passphrase, no persistence.
+- **Hybrid post-quantum**: each pairwise session mixes an ML-KEM-768 secret
+  into the ratchet root at setup, so recorded traffic stays unreadable to a
+  future quantum adversary. It is *added* to X25519, never replaces it —
+  security is at least the classical one. `/trustlist` shows `[PQ]`.
+- **Private rooms** never send the password anywhere: it derives an Ed25519
+  key (Argon2id) that answers a server challenge, and the room content carries
+  an extra symmetric layer — a malicious relay that let someone in without
+  verifying still could not read a word.
 - Threat analysis and protocol details: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
   Found something? See [SECURITY.md](SECURITY.md).
 
@@ -296,12 +323,14 @@ All keys are optional (unknown keys are ignored):
 
 ```bash
 npm run server:dev      # relay with auto-reload
-npm test                # 287 tests (crypto, ratchet, fuzz, controllers, transfers…)
+npm test                # 418 tests (crypto, ratchet, fuzz, controllers, transfers…)
 npm run validate        # lint + prettier + tests — what the CI runs
 ```
 
-CI runs on every push/PR (Node 20 & 22). Tags `v*` trigger tests + a GitHub
-Release automatically.
+CI runs on every push/PR (Node 20 & 22), plus CodeQL and a dependency audit.
+A `v*` tag runs the full suite and then publishes: npm (via OIDC Trusted
+Publishing — no tokens), a GitHub Release, the Docker image on GHCR, and
+standalone relay binaries for macOS and Linux.
 
 ## 📄 License
 

package/README.pt-BR.md

@@ -16,7 +16,7 @@
 [![Node](https://img.shields.io/badge/node-%E2%89%A5%2020-brightgreen)](package.json)
 [![Crypto](https://img.shields.io/badge/E2EE-libsodium-7b2dff)](docs/ARCHITECTURE.md)
 
-**[🇺🇸 Read in English](README.md)** · [Guia de Setup](docs/SETUP.md) · [Arquitetura](docs/ARCHITECTURE.md) · [Política de Segurança](SECURITY.md)
+**[🇺🇸 Read in English](README.md)** · [Guia de Setup](docs/SETUP.md) · [Arquitetura](docs/ARCHITECTURE.md) · [Política de Segurança](SECURITY.md) · [Termos do Hub](TERMS.md)
 
 <img src="docs/demo.svg" alt="Demo do CipherMesh no terminal" width="720">
 
@@ -55,17 +55,36 @@ forwarding, imune a CGNAT).
 | 🎞️ | **Interface animada** | Splash na abertura, spinner de reconexão, barra de transferência viva (shimmer + ETA), cadeado fechando no handshake e um selo pulsante "novas mensagens ↓" |
 | 👻 | **Deniable e efêmeras** | Modo de negação plausível (crypto simétrica); mensagens efêmeras *queimam* caractere a caractere ao expirar |
 | 🔒 | **Salas privadas** | `/create <sala> <senha>` — zero-knowledge: a senha nunca sai da sua máquina (Argon2id → challenge-response Ed25519) e o conteúdo da sala ganha uma camada simétrica extra que nem um relay malicioso atravessa |
-| 🛰️ | **Modo P2P sem servidor** | Descoberta de peers via mDNS na LAN — sem relay nenhum |
+| 🗂️ | **Buffers multi-sala** | Fique em várias salas ao mesmo tempo — **Alt+1..9** alterna, com não-lidas por sala. A qual sala cada mensagem pertence viaja *dentro* do payload cifrado: o relay nunca fica sabendo |
+| 🩺 | **Ele se explica sozinho** | `/doctor` diagnostica uma conexão que falha camada por camada — endereço, DNS, TCP, TLS, protocolo — e diz o que fazer em cada falha |
+| 🔐 | **Trava de tela** | `/lock` e `/autolock` põem a sessão atrás da sua passphrase quando você sai da frente; o `/panic` continua ali para o pior momento |
+| 🛰️ | **Modo P2P sem servidor** | Descoberta de peers via mDNS na LAN — sem relay nenhum, e com quase o mesmo conjunto de comandos |
 | 🧩 | **Plugins** | Solta um arquivo JS em `~/.ciphermesh/plugins` e ganha comandos novos — exemplos `/roll` e `/poll` inclusos ([API de plugins](docs/PLUGINS.md)) |
 
 ## 🚀 Começando
 
-Rode sem clonar (depois de publicado no npm):
+**Converse com alguém em menos de um minuto** — sem instalar, sem conta, sem
+servidor próprio:
 
 ```bash
-npx ciphermesh          # cliente (padrão)
-npx ciphermesh server   # servidor relay
-npx ciphermesh p2p      # P2P sem servidor
+npx ciphermesh@latest
+```
+
+No prompt `Server`, digite **`ciphermesh.de`** — um relay público que qualquer
+pessoa pode usar. Combine um nome de sala com quem você quer conversar
+(`/join nossasala`) e pronto: vocês estão conversando com criptografia
+ponta-a-ponta.
+
+> O hub é mantido como projeto pessoal sob estes **[termos](TERMS.md)**. É um
+> relay zero-knowledge: quem o opera não consegue ler suas mensagens — isso é
+> uma propriedade do software, não uma promessa. Prefere o seu próprio? Todos
+> os comandos abaixo funcionam igual num relay que você hospeda.
+
+Outros modos:
+
+```bash
+npx ciphermesh server   # rode o seu próprio relay
+npx ciphermesh p2p      # sem servidor, descoberta por mDNS na LAN
 ```
 
 macOS/Linux com Homebrew (veja [`Formula/ciphermesh.rb`](Formula/ciphermesh.rb)):
@@ -213,6 +232,7 @@ Um **✓** verde ao lado de um nome indica um peer verificado por SAS; um **✗*
 | `/retention <7d\|24h\|30m>` | Purga o histórico local mais antigo que o tempo dado |
 | `/search <termo>` | Busca no histórico local cifrado (em disco, entre sessões) |
 | `/find [termo]` — **Ctrl+F** | Busca **no histórico da sala na tela** e, com Enter, **salta para a mensagem** destacada |
+| `/doctor [host:porta]` | Diagnostica por que a conexão falha: endereço, DNS, porta TCP, TLS (CA ou self-signed) e versão de protocolo — cada falha com o que fazer |
 | `/history [n]` | Últimas n mensagens do histórico |
 | `/export [caminho]` | Exporta o histórico em .txt ou .json (texto plano!) |
 
@@ -226,8 +246,8 @@ Um **✓** verde ao lado de um nome indica um peer verificado por SAS; um **✗*
 | `/away [motivo]` / `/back` | Marca/remove ausência — enquanto ausente, não-lidas são contadas (`[away · N new]`) e o `/back` mostra um resumo |
 | `/mentions [n]` | Menções recentes a você na sessão (quem, onde, quando) |
 | `/status <texto\|off>` | Status livre — emoji à vontade (`/status :fire: codando`) |
-| `/react <emoji>` | Reage à última mensagem |
-| `/edit` `/delete` | Edita/apaga sua última mensagem |
+| `/react <emoji>` | Reage à última mensagem — o emoji aparece **na própria mensagem**, com contagem quando várias pessoas reagem |
+| `/edit` `/delete` | Edita ou apaga sua última mensagem — a **linha original é reescrita no lugar** (marcada *(edited)*) ou vira uma lápide, em vez de uma linha nova que você precisa juntar mentalmente à original |
 | `/pin` `/unpin` `/pins` | Fixa mensagens |
 | `/sound` `/notify` | Notificações sonoras / desktop |
 | `/dnd [on\|off\|mentions\|HH:MM-HH:MM]` | Não perturbe, só menções, ou horário silencioso |
@@ -291,6 +311,14 @@ mão. Todas as chaves são opcionais (chaves desconhecidas são ignoradas):
   memória e sai sem salvar — para um device perdido ou apreendido.
 - Estado de sessão e histórico local são cifrados em repouso com
   **Argon2id + XSalsa20-Poly1305** — sem passphrase, nada persiste.
+- **Pós-quântico híbrido**: cada sessão mistura um segredo ML-KEM-768 na raiz
+  do ratchet na inicialização, então tráfego gravado hoje continua ilegível
+  para um adversário quântico futuro. Ele é *somado* ao X25519, nunca o
+  substitui — a segurança é no mínimo a clássica. O `/trustlist` mostra `[PQ]`.
+- **Salas privadas** nunca enviam a senha a lugar nenhum: ela deriva uma chave
+  Ed25519 (Argon2id) que responde a um desafio do servidor, e o conteúdo da
+  sala carrega uma camada simétrica extra — um relay malicioso que deixasse
+  alguém entrar sem verificar ainda assim não leria uma palavra.
 - Análise de ameaças e detalhes do protocolo: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
   Achou algo? Veja [SECURITY.md](SECURITY.md).
 
@@ -298,7 +326,7 @@ mão. Todas as chaves são opcionais (chaves desconhecidas são ignoradas):
 
 ```bash
 npm run server:dev      # relay com auto-reload
-npm test                # 287 testes (crypto, ratchet, fuzz, controllers, transferências…)
+npm test                # 418 testes (crypto, ratchet, fuzz, controllers, transferências…)
 npm run validate        # lint + prettier + testes — o mesmo que o CI roda
 ```
 

package/package.json

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

@@ -60,6 +60,7 @@ import {
   matchesKeyword,
 } from '../shared/dnd.js';
 import { saveLastSession } from '../shared/lastSession.js';
+import { diagnose, formatDiagnosis } from '../shared/doctor.js';
 import { COMMANDS } from './UI.js';
 
 const TYPING_SEND_INTERVAL = 2000; // debounce: max 1 typing event per 2s
@@ -120,6 +121,9 @@ export class ChatController {
   #watchWords = new Set(); // /watch — keywords that alert like a mention does
   #awayUnread = 0; // messages received while away
   #awayMentions = 0; // …of which mentioned me
+  #messageLines = new Map(); // messageId → { lineIndex, nickname, text, opts, room }
+  #reactions = new Map(); // messageId → Map<emoji, count>
+  #reconnectAttempts = 0; // consecutive reconnects, for the /doctor nudge
   #autoLockMs = 0; // idle screen-lock timeout (0 = off)
   #autoLockTimer = null;
   // Multi-room buffers (IRC style): lines live in the UI; membership, unread
@@ -212,6 +216,7 @@ export class ChatController {
   // the initial JOIN would be lost — the 'connected' event fired before we
   // attached the listener).
   #onConnected() {
+    this.#reconnectAttempts = 0;
     this.#ui.setConnectionState('online');
     this.#connection.send(
       createJoin(this.#nickname, this.#keyManager.publicKeyB64, this.#keyManager.pqPublicKeyB64),
@@ -237,6 +242,12 @@ export class ChatController {
     this.#connection.on('reconnecting', (delay) => {
       this.#ui.setConnectionState('reconnecting');
       this.#ui.addSystemMessage(`Reconnecting in ${delay / 1000}s...`);
+      // After a few failures this is not a blip — point at the tool that can
+      // actually explain it, once, instead of looping silently forever.
+      this.#reconnectAttempts++;
+      if (this.#reconnectAttempts === 3) {
+        this.#ui.addInfoMessage('Still failing? Run /doctor to find out where it breaks.');
+      }
     });
 
     this.#connection.on('cert-ca-valid', ({ issuer }) => {
@@ -575,6 +586,15 @@ export class ChatController {
       this.#ui.addSystemMessage(`Online: ${peerNames.join(', ')}`);
     }
 
+    // Server notice (MOTD): the operator's only channel to everyone, since
+    // they cannot read or inject anything into the conversations themselves.
+    if (typeof msg.motd === 'string' && msg.motd.trim()) {
+      this.#ui.addInfoMessage('── Server notice ──');
+      for (const line of msg.motd.split('\n').slice(0, 10)) {
+        this.#ui.addInfoMessage(`  ${line}`);
+      }
+    }
+
     if (msg.queuedCount > 0) {
       this.#ui.addSystemMessage(`${msg.queuedCount} pending message(s) being delivered`);
     }
@@ -1159,9 +1179,17 @@ export class ChatController {
       }
 
       if (data.action === 'reaction') {
-        this.#ui.toBuffer(msgRoom, () => {
-          this.#ui.addSystemMessage(`${data.emoji} ${peer.nickname} reacted to a message`);
-        });
+        // Hang the reaction off the message itself; only fall back to a log
+        // line when the target is not on screen (older or another room).
+        const applied =
+          roomActive && data.targetMessageId
+            ? this.#applyReaction(data.targetMessageId, data.emoji)
+            : false;
+        if (!applied) {
+          this.#ui.toBuffer(msgRoom, () => {
+            this.#ui.addSystemMessage(`${data.emoji} ${peer.nickname} reacted to a message`);
+          });
+        }
         if (roomActive) {
           this.#ui.playNotification();
         }
@@ -1170,7 +1198,14 @@ export class ChatController {
 
       if (data.action === 'edit_message') {
         const author = this.#messageAuthors.get(data.messageId);
-        if (author && author === peer.nickname) {
+        if (!author || author !== peer.nickname) {
+          return; // only the author may rewrite their own message
+        }
+        const entry = this.#editableMessage(data.messageId);
+        if (entry) {
+          entry.text = data.newText;
+          this.#ui.replaceMessageText(entry.lineIndex, entry.nickname, data.newText, entry.opts);
+        } else {
           this.#ui.toBuffer(msgRoom, () => {
             this.#ui.addSystemMessage(`${peer.nickname} edited: ${data.newText} (edited)`);
           });
@@ -1180,7 +1215,14 @@ export class ChatController {
 
       if (data.action === 'delete_message') {
         const author = this.#messageAuthors.get(data.messageId);
-        if (author && author === peer.nickname) {
+        if (!author || author !== peer.nickname) {
+          return;
+        }
+        const entry = this.#editableMessage(data.messageId);
+        if (entry) {
+          this.#ui.tombstoneMessage(entry.lineIndex, peer.nickname);
+          this.#messageLines.delete(data.messageId);
+        } else {
           this.#ui.toBuffer(msgRoom, () => {
             this.#ui.addSystemMessage(`${peer.nickname} deleted a message`);
           });
@@ -1299,11 +1341,12 @@ export class ChatController {
       const trust = trustBadge(this.#trustStore.getPeerRecord(peer.nickname), peer.publicKey);
       // File the message into its buffer (live log when active, stored otherwise).
       let lineIndex = -1;
+      let renderInfo = null;
       this.#ui.toBuffer(msgRoom, () => {
         if (data.replyTo?.nickname && typeof data.replyTo.excerpt === 'string') {
           this.#ui.addQuoteLine(String(data.replyTo.nickname), data.replyTo.excerpt.slice(0, 80));
         }
-        ({ lineIndex } = data.isAction
+        ({ lineIndex, render: renderInfo } = data.isAction
           ? this.#ui.addActionMessage(peer.nickname, data.text)
           : this.#ui.addMessage(
               peer.nickname,
@@ -1315,6 +1358,9 @@ export class ChatController {
               trust,
             ));
       });
+      if (roomActive && data.messageId) {
+        this.#rememberMessage(data.messageId, lineIndex, peer.nickname, data.text, renderInfo);
+      }
       this.#noteBufferUnread(msgRoom, mentioned);
       const notify = shouldNotify(this.#dndMode, this.#dndWindow, nowMinutes(), mentioned);
       if (notify) {
@@ -1440,6 +1486,7 @@ export class ChatController {
         );
         this.#ui.addInfoMessage('  /search <term>       - Search the encrypted local history');
         this.#ui.addInfoMessage('  /find [term]         - Find in this room and jump (Ctrl+F)');
+        this.#ui.addInfoMessage('  /doctor [host:port]  - Diagnose why a connection fails');
         this.#ui.addInfoMessage('  /history [n]         - Last n messages from history');
         this.#ui.addInfoMessage('  /export [path]       - Export the history (.txt or .json)');
         this.#ui.addInfoMessage('  /audit [N]           - Show the last N audit events');
@@ -2171,6 +2218,21 @@ export class ChatController {
         break;
       }
 
+      case '/doctor': {
+        const target = parts.slice(1).join(' ').trim() || this.#connection.url || '';
+        this.#ui.addInfoMessage(`Diagnosing ${target} …`);
+        diagnose(target)
+          .then((steps) => {
+            for (const line of formatDiagnosis(steps)) {
+              this.#ui.addInfoMessage(line);
+            }
+          })
+          .catch((err) => {
+            this.#ui.addErrorMessage(`Diagnostics failed to run: ${err.message}`);
+          });
+        break;
+      }
+
       case '/find': {
         const term = parts.slice(1).join(' ').trim();
         // Opens the same overlay as Ctrl+F, pre-filled when a term is given.
@@ -2283,9 +2345,12 @@ export class ChatController {
           sentAt: Date.now(),
         });
         this.#broadcastPayload(reactionPayload);
-        this.#ui.addSystemMessage(
-          `${emoji} You reacted to ${this.#lastReceivedNickname}'s message`,
-        );
+        // Show it on the message right away instead of announcing it.
+        if (!this.#applyReaction(this.#lastReceivedMessageId, emoji)) {
+          this.#ui.addSystemMessage(
+            `${emoji} You reacted to ${this.#lastReceivedNickname}'s message`,
+          );
+        }
         break;
       }
 
@@ -2306,7 +2371,19 @@ export class ChatController {
           sentAt: Date.now(),
         });
         this.#broadcastPayload(editPayload);
-        this.#ui.addSystemMessage(`You edited: ${editText} (edited)`);
+        // Rewrite our own line in place, like the peers will.
+        const editEntry = this.#editableMessage(this.#lastSentMessageId);
+        if (editEntry) {
+          editEntry.text = editText;
+          this.#ui.replaceMessageText(
+            editEntry.lineIndex,
+            editEntry.nickname,
+            editText,
+            editEntry.opts,
+          );
+        } else {
+          this.#ui.addSystemMessage(`You edited: ${editText} (edited)`);
+        }
         break;
       }
 
@@ -2321,8 +2398,14 @@ export class ChatController {
           sentAt: Date.now(),
         });
         this.#broadcastPayload(deletePayload);
+        const delEntry = this.#editableMessage(this.#lastSentMessageId);
+        if (delEntry) {
+          this.#ui.tombstoneMessage(delEntry.lineIndex, this.#nickname);
+          this.#messageLines.delete(this.#lastSentMessageId);
+        } else {
+          this.#ui.addSystemMessage('You deleted a message');
+        }
         this.#lastSentMessageId = null;
-        this.#ui.addSystemMessage('You deleted a message');
         break;
       }
 
@@ -3019,6 +3102,55 @@ export class ChatController {
     this.#ui.appendBadge(tracked.lineIndex, tracked.baseLine, `{green-fg}${marker}{/green-fg}`);
   }
 
+  // Remember where a message was drawn so reactions/edits/deletes can change
+  // it in place. Bounded like the receipt tracker.
+  #rememberMessage(messageId, lineIndex, nickname, text, render) {
+    if (!messageId || lineIndex === undefined || lineIndex < 0) {
+      return;
+    }
+    this.#messageLines.set(messageId, {
+      lineIndex,
+      nickname,
+      text,
+      opts: render?.opts || {},
+      room: this.#currentRoom,
+    });
+    if (this.#messageLines.size > 200) {
+      const oldest = this.#messageLines.keys().next().value;
+      this.#messageLines.delete(oldest);
+      this.#reactions.delete(oldest);
+    }
+  }
+
+  // A message can only be redrawn while its room is the one on screen.
+  #editableMessage(messageId) {
+    const entry = this.#messageLines.get(messageId);
+    if (!entry || entry.room !== this.#currentRoom) {
+      return null;
+    }
+    return entry;
+  }
+
+  #applyReaction(messageId, emoji) {
+    const entry = this.#editableMessage(messageId);
+    if (!entry) {
+      return false;
+    }
+    const counts = this.#reactions.get(messageId) || new Map();
+    counts.set(emoji, (counts.get(emoji) || 0) + 1);
+    this.#reactions.set(messageId, counts);
+
+    // Re-render the line, then hang the reactions off the end of it.
+    const badge = [...counts.entries()].map(([e, n]) => (n > 1 ? `${e}${n}` : e)).join(' ');
+    this.#ui.replaceMessageText(entry.lineIndex, entry.nickname, entry.text, {
+      ...entry.opts,
+      edited: entry.opts?.edited,
+    });
+    const rebuilt = this.#ui.getLine(entry.lineIndex);
+    this.#ui.appendBadge(entry.lineIndex, rebuilt, badge);
+    return true;
+  }
+
   #trackSentMessage(messageId, lineIndex) {
     const baseLine = this.#ui.getLine(lineIndex);
     if (baseLine === null || baseLine === undefined) {
@@ -3321,9 +3453,10 @@ export class ChatController {
       this.#ui.addQuoteLine(replyTo.nickname, replyTo.excerpt, true);
     }
     const ephLabel = this.#ephemeralMode ? this.#formatDuration(this.#ephemeralDurationMs) : null;
-    const { lineIndex } = isAction
+    const { lineIndex, render } = isAction
       ? this.#ui.addActionMessage(this.#nickname, text)
       : this.#ui.addMessage(this.#nickname, text, false, ephLabel, this.#deniableMode);
+    this.#rememberMessage(messageId, lineIndex, this.#nickname, text, render);
 
     if (this.#ephemeralMode) {
       this.#scheduleEphemeralRemoval(lineIndex, this.#ephemeralDurationMs, this.#nickname);

package/src/client/UI.js

@@ -46,6 +46,7 @@ const COMMAND_INFO = [
   ['/notify', 'Desktop notifications'],
   ['/search', 'Search history (on disk)'],
   ['/find', 'Find in this room and jump to it'],
+  ['/doctor', 'Diagnose why a connection fails'],
   ['/history', 'Recent messages from history'],
   ['/export', 'Export history'],
   ['/backup', 'Back up identity + trust'],
@@ -112,6 +113,7 @@ export const COMMANDS = [
   '/invite',
   '/search',
   '/find',
+  '/doctor',
   '/history',
   '/export',
   '/backup',
@@ -1781,6 +1783,64 @@ export class UI extends EventEmitter {
     trust = 'none',
   ) {
     this.#daySeparator();
+    const isSelfNow = nickname === this.#nickname || nickname.includes('\u2192');
+    const opts = {
+      isDM,
+      ephemeralLabel,
+      deniable,
+      mentioned,
+      trust,
+      grouped: !isSelfNow && !isDM && this.#lastSender === nickname,
+      stamp: time(),
+    };
+    const line = this.#composeMessageLine(nickname, text, opts);
+
+    this.#lines.push(line);
+    this.#chatLog.log(line);
+    this.#screen.render();
+    this.#lastSender = isSelfNow ? 'self' : nickname;
+    if (!isSelfNow) {
+      this.#noteIncoming(mentioned || isDM);
+    }
+    return { lineIndex: this.#lines.length - 1, render: { nickname, opts } };
+  }
+
+  /**
+   * Rewrite an existing message line with new text — used by /edit, so an
+   * edited message changes IN PLACE instead of arriving as a separate line the
+   * reader has to mentally staple to the original.
+   */
+  replaceMessageText(lineIndex, nickname, newText, opts) {
+    this.updateLine(
+      lineIndex,
+      this.#composeMessageLine(nickname, newText, { ...opts, edited: true }),
+    );
+  }
+
+  /** Replace a message with a tombstone (used by /delete). */
+  tombstoneMessage(lineIndex, nickname) {
+    this.updateLine(
+      lineIndex,
+      ` {white-fg}[${time()}]{/white-fg} {#666666-fg}\ud83d\udeab ${blessed.escape(
+        nickname,
+      )} deleted a message{/#666666-fg}`,
+    );
+  }
+
+  // Builds a message line. Shared by addMessage and replaceMessageText so an
+  // edited message keeps exactly the layout it had (alignment, grouping,
+  // badges) instead of drifting into a different shape.
+  #composeMessageLine(nickname, text, opts) {
+    const {
+      isDM = false,
+      ephemeralLabel = null,
+      deniable = false,
+      mentioned = false,
+      trust = 'none',
+      grouped = false,
+      edited = false,
+      stamp = time(),
+    } = opts || {};
 
     const color = nickColor(nickname);
     const isSelf = nickname === this.#nickname || nickname.includes('\u2192');
@@ -1802,24 +1862,15 @@ export class UI extends EventEmitter {
 
     // Consecutive messages from the same peer collapse the avatar/name into a
     // compact continuation bullet (cleaner layout).
-    const grouped = !isSelf && !isDM && this.#lastSender === nickname;
+    const editedMark = edited ? ' {#8888aa-fg}(edited){/#8888aa-fg}' : '';
     const core = grouped
-      ? `{${tag}}\u00b7{/${tag}} ${renderMarkdown(text)}`
-      : `${avatar} {${tag}}${nickname}{/${tag}}${trustGlyph}${dmLabel}: ${renderMarkdown(text)}`;
+      ? `{${tag}}\u00b7{/${tag}} ${renderMarkdown(text)}${editedMark}`
+      : `${avatar} {${tag}}${nickname}{/${tag}}${trustGlyph}${dmLabel}: ${renderMarkdown(text)}${editedMark}`;
 
     // My own messages on the right (timestamp at the end), others on the left
-    const line = isSelf
-      ? this.#alignRight(`${core}${ephLabel}${denLabel} {white-fg}[${time()}]{/white-fg}`)
-      : `${bar}{white-fg}[${time()}]{/white-fg}${ephLabel}${denLabel} ${mentionMark}${core}`;
-
-    this.#lines.push(line);
-    this.#chatLog.log(line);
-    this.#screen.render();
-    this.#lastSender = isSelf ? 'self' : nickname;
-    if (!isSelf) {
-      this.#noteIncoming(mentioned || isDM);
-    }
-    return { lineIndex: this.#lines.length - 1 };
+    return isSelf
+      ? this.#alignRight(`${core}${ephLabel}${denLabel} {white-fg}[${stamp}]{/white-fg}`)
+      : `${bar}{white-fg}[${stamp}]{/white-fg}${ephLabel}${denLabel} ${mentionMark}${core}`;
   }
 
   #daySeparator() {

package/src/p2p/P2PChatController.js

@@ -23,6 +23,7 @@ import { isImageFile, renderImagePreview, loadImageBuffers } from '../client/Ima
 import { detectImageProtocol, encodeInlineImage } from '../shared/terminalGraphics.js';
 import { AuditLog, AuditEvent } from '../shared/AuditLog.js';
 import { applyShortcodes } from '../shared/emoji.js';
+import { diagnose, formatDiagnosis } from '../shared/doctor.js';
 import { deriveSharedKey, encryptDeniable, decryptDeniable } from '../crypto/DeniableEncrypt.js';
 import { GroupSession } from '../crypto/SenderKey.js';
 import { suggestCommand } from '../shared/commandSuggest.js';
@@ -90,6 +91,10 @@ export class P2PChatController {
   #autoLockTimer = null;
   #roomTopics = new Map(); // room → { text, by, at } (E2EE among peers)
   #historyStore; // encrypted local history (opt-in, needs a passphrase)
+  #receiptsEnabled = true; // /receipts — send read confirmations
+  #sentMessageLines = new Map(); // messageId → { lineIndex, baseLine, room }
+  #messageReaders = new Map(); // messageId → Set<nickname>
+  #pendingReceipts = new Map(); // messageId → Set<nickname> acked before we tracked it
   #lastReceivedMessageId;
   #lastReceivedNickname;
   #lastSentMessageId;
@@ -610,6 +615,11 @@ export class P2PChatController {
       return;
     }
 
+    if (data.action === 'read_receipt') {
+      this.#onReadReceipt(fromNickname, data.messageId);
+      return;
+    }
+
     if (data.action === 'set_topic') {
       const room = typeof data.room === 'string' ? data.room : this.#currentRoom;
       if (typeof data.text === 'string') {
@@ -690,6 +700,23 @@ export class P2PChatController {
       this.#ui.playNotification();
     }
 
+    // Confirm the read to the author — an ordinary E2EE payload, sent only to
+    // them. Never for ephemeral or deniable messages: acknowledging those
+    // would defeat the point of not leaving a trace.
+    if (
+      this.#receiptsEnabled &&
+      data.messageId &&
+      !data.ephemeral &&
+      !isDeniable &&
+      !data.deniable
+    ) {
+      this.#broadcastPayload(
+        JSON.stringify({ action: 'read_receipt', messageId: data.messageId, sentAt: Date.now() }),
+        false,
+        fromNickname,
+      );
+    }
+
     if (data.ephemeral && data.ephemeral > 0) {
       this.#scheduleEphemeralRemoval(lineIndex, data.ephemeral, fromNickname);
     }
@@ -906,6 +933,49 @@ export class P2PChatController {
     const cmd = parts[0].toLowerCase();
 
     switch (cmd) {
+      case '/doctor': {
+        const target = parts.slice(1).join(' ').trim();
+        if (!target) {
+          this.#ui.addErrorMessage(
+            'Usage: /doctor <host:port>  — P2P finds peers over mDNS, so give an address to test',
+          );
+          break;
+        }
+        this.#ui.addInfoMessage(`Diagnosing ${target} …`);
+        diagnose(target)
+          .then((steps) => {
+            for (const line of formatDiagnosis(steps)) {
+              this.#ui.addInfoMessage(line);
+            }
+          })
+          .catch((err) => {
+            this.#ui.addErrorMessage(`Diagnostics failed to run: ${err.message}`);
+          });
+        break;
+      }
+
+      case '/find': {
+        // Pure UI: searches the lines on screen, so it works the same here.
+        this.#ui.openFinder(parts.slice(1).join(' ').trim());
+        break;
+      }
+
+      case '/receipts': {
+        const arg = parts[1]?.toLowerCase();
+        if (arg === 'off') {
+          this.#receiptsEnabled = false;
+          this.#ui.addInfoMessage('Read receipts disabled — you no longer send read confirmations');
+        } else if (arg === 'on') {
+          this.#receiptsEnabled = true;
+          this.#ui.addInfoMessage('Read receipts enabled');
+        } else {
+          this.#ui.addInfoMessage(
+            `Read receipts: ${this.#receiptsEnabled ? 'enabled' : 'disabled'}. Use /receipts on or /receipts off`,
+          );
+        }
+        break;
+      }
+
       case '/search': {
         if (!this.#historyStore?.isOpen) {
           this.#ui.addErrorMessage('History disabled — start with a passphrase');
@@ -1263,6 +1333,9 @@ export class P2PChatController {
         this.#ui.addInfoMessage('  /history [n]         - Last n messages from history');
         this.#ui.addInfoMessage('  /export [path]       - Export the history');
         this.#ui.addInfoMessage('  /retention <time>    - Local history retention');
+        this.#ui.addInfoMessage('  /receipts [on|off]   - Read receipts (✓✓)');
+        this.#ui.addInfoMessage('  /find [term]         - Find in this room and jump (Ctrl+F)');
+        this.#ui.addInfoMessage('  /doctor <host:port>  - Diagnose why a connection fails');
         this.#ui.addInfoMessage('  /watch [add|remove|clear] - Alert on a keyword');
         this.#ui.addInfoMessage('  /help                - Show this help');
         this.#ui.addInfoMessage('  /tips                - Show a security/UX tip');
@@ -2363,9 +2436,68 @@ export class P2PChatController {
 
     if (this.#ephemeralMode) {
       this.#scheduleEphemeralRemoval(lineIndex, this.#ephemeralDurationMs, this.#nickname);
+    } else if (!this.#deniableMode) {
+      this.#trackSentMessage(messageId, lineIndex);
+    }
+  }
+
+  // ── Read receipts ────────────────────────────────────────────
+  #trackSentMessage(messageId, lineIndex) {
+    const baseLine = this.#ui.getLine(lineIndex);
+    if (baseLine === null || baseLine === undefined) {
+      return;
+    }
+    this.#sentMessageLines.set(messageId, { lineIndex, baseLine, room: this.#currentRoom });
+
+    // A peer on the same machine (or a very fast link) can acknowledge before
+    // we finish rendering our own echo. Apply anything that arrived early.
+    const early = this.#pendingReceipts.get(messageId);
+    if (early) {
+      this.#pendingReceipts.delete(messageId);
+      for (const nickname of early) {
+        this.#onReadReceipt(nickname, messageId);
+      }
+    }
+
+    // Bound memory: keep only the most recent 200 tracked messages
+    if (this.#sentMessageLines.size > 200) {
+      const oldest = this.#sentMessageLines.keys().next().value;
+      this.#sentMessageLines.delete(oldest);
+      this.#messageReaders.delete(oldest);
     }
   }
 
+  #onReadReceipt(nickname, messageId) {
+    const tracked = this.#sentMessageLines.get(messageId);
+    if (!tracked) {
+      // Arrived before we tracked our own message — remember it (bounded) and
+      // let #trackSentMessage apply it a moment later.
+      if (messageId && this.#pendingReceipts.size < 200) {
+        const set = this.#pendingReceipts.get(messageId) || new Set();
+        set.add(nickname);
+        this.#pendingReceipts.set(messageId, set);
+      }
+      return;
+    }
+    // Line indexes only address the room currently on screen.
+    if (tracked.room && tracked.room !== this.#currentRoom) {
+      return;
+    }
+
+    let readers = this.#messageReaders.get(messageId);
+    if (!readers) {
+      readers = new Set();
+      this.#messageReaders.set(messageId, readers);
+    }
+    if (readers.has(nickname)) {
+      return;
+    }
+    readers.add(nickname);
+
+    const marker = readers.size > 1 ? `✓✓ ${readers.size}` : '✓✓';
+    this.#ui.appendBadge(tracked.lineIndex, tracked.baseLine, `{green-fg}${marker}{/green-fg}`);
+  }
+
   // ── Send encrypted DM to one peer ────────────────────────────
   #sendMessageToPeer(peerNickname, text) {
     const peerPublicKey = this.#handshake.getPeerPublicKey(peerNickname);

package/src/server/SessionManager.js

@@ -303,6 +303,17 @@ export class SessionManager {
 
   // ── Private rooms ────────────────────────────────────────────
 
+  /** Number of live rooms (used for the server-wide room cap). */
+  get roomCount() {
+    let n = 0;
+    for (const members of this.#rooms.values()) {
+      if (members.size > 0) {
+        n++;
+      }
+    }
+    return n;
+  }
+
   roomHasMembers(room) {
     const members = this.#rooms.get(room);
     return !!members && members.size > 0;

package/src/server/WebSocketServer.js

@@ -5,10 +5,7 @@ import { createLogger } from '../shared/logger.js';
 import {
   HEARTBEAT_INTERVAL_MS,
   MAX_PAYLOAD_SIZE,
-  MAX_CONNECTIONS_TOTAL,
-  MAX_CONNECTIONS_PER_IP,
   JOIN_TIMEOUT_MS,
-  MESSAGE_RATE_LIMIT_PER_SECOND,
   ROOM_CHALLENGE_NONCE_SIZE,
   ROOM_CHALLENGE_TTL_MS,
   ROOM_AUTH_MAX_FAILS,
@@ -44,6 +41,7 @@ import {
   validateBanPeer,
 } from '../protocol/validators.js';
 import { verifyRoomChallenge } from '../crypto/RoomKey.js';
+import { parseServerConfig, clientAddress, normalizeIp } from './config.js';
 
 const log = createLogger('ws-server');
 
@@ -55,12 +53,14 @@ export class SecureWSServer {
   #offlineQueue;
   #heartbeatInterval;
   #connectionsByIp;
+  #config;
 
-  constructor(sessionManager, messageRouter, offlineQueue, port, tlsOptions) {
+  constructor(sessionManager, messageRouter, offlineQueue, port, tlsOptions, config = null) {
     this.#sessionManager = sessionManager;
     this.#messageRouter = messageRouter;
     this.#offlineQueue = offlineQueue;
     this.#connectionsByIp = new Map();
+    this.#config = config || parseServerConfig();
 
     if (tlsOptions) {
       this.#httpsServer = createHttpsServer(tlsOptions);
@@ -86,20 +86,27 @@ export class SecureWSServer {
   }
 
   #clientIp(req) {
-    return req?.socket?.remoteAddress || 'unknown';
+    return normalizeIp(clientAddress(req, this.#config.trustProxy));
   }
 
   #handleConnection(ws, req) {
     const ip = this.#clientIp(req);
 
+    // Operator banlist — the one lever that does not require reading messages.
+    if (this.#config.bannedIps.has(ip)) {
+      log.warn(`Rejected banned address ${ip}`);
+      ws.close(1008, 'Address not allowed');
+      return;
+    }
+
     // Global connection cap (the new socket is already counted in clients).
-    if (this.#wss.clients.size > MAX_CONNECTIONS_TOTAL) {
+    if (this.#wss.clients.size > this.#config.maxConnectionsTotal) {
       ws.close(1013, 'Server full');
       return;
     }
     // Per-IP connection cap.
     const ipCount = this.#connectionsByIp.get(ip) || 0;
-    if (ipCount >= MAX_CONNECTIONS_PER_IP) {
+    if (ipCount >= this.#config.maxConnectionsPerIp) {
       log.warn(`Too many connections from ${ip}, rejecting`);
       ws.close(1013, 'Too many connections from this IP');
       return;
@@ -166,7 +173,7 @@ export class SecureWSServer {
       ws.msgCount = 0;
     }
     ws.msgCount++;
-    return ws.msgCount <= MESSAGE_RATE_LIMIT_PER_SECOND;
+    return ws.msgCount <= this.#config.messageRateLimitPerSecond;
   }
 
   #handleMessage(ws, data) {
@@ -283,6 +290,9 @@ export class SecureWSServer {
         joinAck.roomOwner = ownerSession.nickname;
       }
     }
+    if (this.#config.motd) {
+      joinAck.motd = this.#config.motd;
+    }
     ws.send(JSON.stringify(joinAck));
 
     // Deliver queued messages with updated recipient sessionId
@@ -376,6 +386,10 @@ export class SecureWSServer {
       return;
     }
 
+    if (this.#roomCapExceeded(ws, validation.room)) {
+      return;
+    }
+
     // Creating a private room: register the password verifier, but only for
     // a room that doesn't exist yet (rooms die when the last member leaves).
     if (validation.roomAuthPk) {
@@ -414,6 +428,38 @@ export class SecureWSServer {
     this.#finishRoomSwitch(ws, session, result);
   }
 
+  // Room caps. Multi-room lets one connection open many rooms, so both a
+  // per-session and a server-wide ceiling are needed; without them a single
+  // client can exhaust the room table by itself.
+  #roomCapExceeded(ws, room) {
+    if (this.#sessionManager.isInRoom(ws.sessionId, room)) {
+      return false; // already there, not a new room
+    }
+    const mine = this.#sessionManager.getSessionRooms(ws.sessionId).length;
+    if (mine >= this.#config.maxRoomsPerSession) {
+      ws.send(
+        JSON.stringify(
+          createError(
+            ERR.INVALID_MESSAGE,
+            `You are in too many rooms (max ${this.#config.maxRoomsPerSession}) — /leave one first`,
+          ),
+        ),
+      );
+      return true;
+    }
+    // Only a room that does not exist yet adds to the server total.
+    if (
+      !this.#sessionManager.roomHasMembers(room) &&
+      this.#sessionManager.roomCount >= this.#config.maxRoomsTotal
+    ) {
+      ws.send(
+        JSON.stringify(createError(ERR.INVALID_MESSAGE, 'The server has too many rooms right now')),
+      );
+      return true;
+    }
+    return false;
+  }
+
   // Multi-room: join an ADDITIONAL room, keeping current memberships.
   #handleJoinRoom(ws, msg) {
     if (!ws.hasJoined || !ws.sessionId) {
@@ -432,6 +478,9 @@ export class SecureWSServer {
       ws.send(JSON.stringify(createError(ERR.INVALID_MESSAGE, 'You are banned from this room')));
       return;
     }
+    if (this.#roomCapExceeded(ws, validation.room)) {
+      return;
+    }
 
     // Creating a private room additively.
     if (validation.roomAuthPk) {
@@ -908,7 +957,7 @@ export class SecureWSServer {
           ws.sessionId,
         );
       }
-      log.info(`${session.nickname} saiu | Online: ${this.#sessionManager.size}`);
+      log.info(`${session.nickname} left | Online: ${this.#sessionManager.size}`);
     }
   }
 

package/src/server/config.js

@@ -0,0 +1,112 @@
+// Server limits and operator settings, read from the environment so whoever
+// hosts a relay can tighten it for the open internet without touching code.
+//
+// The defaults are the LAN-friendly ones the project always had. A public
+// relay should lower the connection caps and set TRUST_PROXY — see deploy/.
+import { readFileSync } from 'node:fs';
+import {
+  MAX_CONNECTIONS_TOTAL,
+  MAX_CONNECTIONS_PER_IP,
+  MESSAGE_RATE_LIMIT_PER_SECOND,
+} from '../shared/constants.js';
+
+const DEFAULTS = {
+  maxConnectionsTotal: MAX_CONNECTIONS_TOTAL,
+  maxConnectionsPerIp: MAX_CONNECTIONS_PER_IP,
+  messageRateLimitPerSecond: MESSAGE_RATE_LIMIT_PER_SECOND,
+  // Multi-room means ONE connection can open many rooms; without a cap a
+  // single client could exhaust the room table on its own.
+  maxRoomsTotal: 500,
+  maxRoomsPerSession: 10,
+};
+
+function positiveInt(raw, fallback) {
+  const n = Number.parseInt(raw, 10);
+  return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+
+function readMotd(env) {
+  if (env.MOTD_FILE) {
+    try {
+      return readFileSync(env.MOTD_FILE, 'utf-8').trim().slice(0, 500);
+    } catch {
+      return ''; // a missing file must never stop the server from booting
+    }
+  }
+  return String(env.MOTD || '')
+    .trim()
+    .slice(0, 500);
+}
+
+function readBannedIps(env) {
+  const inline = String(env.BANNED_IPS || '');
+  let fromFile = '';
+  if (env.BANNED_IPS_FILE) {
+    try {
+      fromFile = readFileSync(env.BANNED_IPS_FILE, 'utf-8');
+    } catch {
+      fromFile = '';
+    }
+  }
+  // Strip comments PER LINE before splitting: a naive split would turn
+  // "# abuse 2026-08" into three bogus banlist entries.
+  const entries = `${inline}\n${fromFile}`
+    .split('\n')
+    .map((line) => line.split('#')[0])
+    .flatMap((line) => line.split(/[\s,]+/))
+    .map((ip) => ip.trim())
+    .filter(Boolean);
+  return new Set(entries);
+}
+
+/**
+ * Build the server configuration from an environment object.
+ * Pure — exported so tests can feed it any env.
+ */
+export function parseServerConfig(env = process.env) {
+  return {
+    maxConnectionsTotal: positiveInt(env.MAX_CONNECTIONS_TOTAL, DEFAULTS.maxConnectionsTotal),
+    maxConnectionsPerIp: positiveInt(env.MAX_CONNECTIONS_PER_IP, DEFAULTS.maxConnectionsPerIp),
+    messageRateLimitPerSecond: positiveInt(
+      env.MESSAGE_RATE_LIMIT,
+      DEFAULTS.messageRateLimitPerSecond,
+    ),
+    maxRoomsTotal: positiveInt(env.MAX_ROOMS_TOTAL, DEFAULTS.maxRoomsTotal),
+    maxRoomsPerSession: positiveInt(env.MAX_ROOMS_PER_SESSION, DEFAULTS.maxRoomsPerSession),
+    // Behind a reverse proxy every connection arrives from the proxy, so the
+    // per-IP cap would apply to the proxy itself and protect nobody. Only
+    // trust the forwarded header when the operator says there IS a proxy —
+    // otherwise any client could forge its own address.
+    trustProxy: String(env.TRUST_PROXY || '').toLowerCase() === 'true',
+    motd: readMotd(env),
+    bannedIps: readBannedIps(env),
+  };
+}
+
+/**
+ * The client address to rate-limit and ban on.
+ * @param {object} req - the upgrade request
+ * @param {boolean} trustProxy
+ */
+export function clientAddress(req, trustProxy) {
+  const socketIp = req?.socket?.remoteAddress || 'unknown';
+  if (!trustProxy) {
+    return socketIp;
+  }
+  // X-Forwarded-For is "client, proxy1, proxy2" — the FIRST entry is the
+  // original client. It is only trustworthy because the operator declared
+  // that a proxy sits in front and overwrites it.
+  const forwarded = req?.headers?.['x-forwarded-for'];
+  if (typeof forwarded === 'string' && forwarded.length > 0) {
+    const first = forwarded.split(',')[0].trim();
+    if (first) {
+      return first;
+    }
+  }
+  return socketIp;
+}
+
+/** Normalize an address for comparison (strips the IPv6-mapped IPv4 prefix). */
+export function normalizeIp(ip) {
+  return String(ip || '').replace(/^::ffff:/, '');
+}

package/src/shared/doctor.js

@@ -0,0 +1,250 @@
+// Connection doctor: answers "why can't I connect?" in the order the failures
+// actually happen, so a user without a terminal debugger can fix it alone.
+//
+// Every step reports what was checked, whether it passed, and — when it fails
+// — what to do about it. A failing step stops the run: there is no point
+// testing TLS when the TCP port never opened.
+import { connect as netConnect } from 'node:net';
+import { connect as tlsConnect } from 'node:tls';
+import { lookup as dnsLookup } from 'node:dns';
+import { PROTOCOL_VERSION } from './constants.js';
+
+const DEFAULT_TIMEOUT_MS = 6000;
+
+/** Split "wss://host:3600" (or "host:3600") into its parts. */
+export function parseTarget(raw) {
+  const value = String(raw || '').trim();
+  if (!value) {
+    return null;
+  }
+  const withScheme = /^wss?:\/\//.test(value) ? value : `wss://${value}`;
+  try {
+    const url = new URL(withScheme);
+    // No explicit port: mirror what the WebSocket client will actually do —
+    // wss:// goes to 443 and ws:// to 80. Assuming 3600 here would have made
+    // /doctor test a different port than the one the chat connects to, which
+    // is exactly the confusion the command exists to prevent.
+    const defaultPort = url.protocol === 'wss:' ? 443 : 80;
+    const port = Number(url.port) || defaultPort;
+    if (!url.hostname || !Number.isInteger(port) || port < 1 || port > 65535) {
+      return null;
+    }
+    return { host: url.hostname, port, tls: url.protocol === 'wss:', url: withScheme };
+  } catch {
+    return null;
+  }
+}
+
+const isIpLiteral = (host) => /^[\d.]+$/.test(host) || host.includes(':');
+
+function step(name, ok, detail, hint = null) {
+  return hint ? { name, ok, detail, hint } : { name, ok, detail };
+}
+
+function resolveHost(host, deps) {
+  return new Promise((resolve) => {
+    deps.lookup(host, (err, address) => resolve(err ? null : address));
+  });
+}
+
+function probeTcp(host, port, timeoutMs, deps) {
+  return new Promise((resolve) => {
+    const socket = deps.netConnect({ host, port });
+    const done = (result) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.on('connect', () => done({ ok: true }));
+    socket.on('timeout', () => done({ ok: false, reason: 'timeout' }));
+    socket.on('error', (err) => done({ ok: false, reason: err.code || err.message }));
+  });
+}
+
+function probeTls(host, port, timeoutMs, deps) {
+  return new Promise((resolve) => {
+    // SNI is a hostname field: Node throws outright if given an IP, and on a
+    // LAN the target is almost always an IP. Send it only when we have a name.
+    const sni = isIpLiteral(host) ? {} : { servername: host };
+    // Diagnostic socket only: it completes the handshake, reads the
+    // certificate, reports it and closes — no data is ever sent over it.
+    // rejectUnauthorized is off precisely so a self-signed LAN certificate
+    // still reaches this point and can be DESCRIBED to the user instead of
+    // failing opaquely. The real chat connection does not run this way: it
+    // enforces strict verification for hosts that ever presented a CA-valid
+    // certificate (see crypto/CertPinStore.js).
+    const socket = deps.tlsConnect({ host, port, rejectUnauthorized: false, ...sni });
+    const done = (result) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.on('secureConnect', () => {
+      const cert = socket.getPeerCertificate?.() || {};
+      done({
+        ok: true,
+        authorized: socket.authorized === true,
+        // WHY it failed matters: a self-signed LAN cert is expected, but a
+        // hostname mismatch means you reached a different server entirely —
+        // usually stale DNS. Reporting both as "self-signed" hides that.
+        reason: socket.authorizationError || null,
+        subject: cert.subject?.CN || null,
+        issuer: cert.issuer?.O || cert.issuer?.CN || 'unknown',
+        fingerprint: cert.fingerprint256 || null,
+      });
+    });
+    socket.on('timeout', () => done({ ok: false, reason: 'timeout' }));
+    socket.on('error', (err) => done({ ok: false, reason: err.code || err.message }));
+  });
+}
+
+/**
+ * Run the connection checks against `target`.
+ *
+ * @param {string} target - what the user typed at the Server prompt
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs]
+ * @param {object} [opts.deps] - injectable node primitives (tests)
+ * @returns {Promise<Array<{name, ok, detail, hint?}>>}
+ */
+export async function diagnose(target, opts = {}) {
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const deps = {
+    lookup: dnsLookup,
+    netConnect,
+    tlsConnect,
+    ...(opts.deps || {}),
+  };
+  const steps = [];
+
+  const parsed = parseTarget(target);
+  if (!parsed) {
+    steps.push(
+      step(
+        'Address',
+        false,
+        `cannot parse "${target}"`,
+        'Use host:port — for example 192.168.1.10:3600 — or a ciphermesh:// invite.',
+      ),
+    );
+    return steps;
+  }
+  steps.push(
+    step('Address', true, `${parsed.host}:${parsed.port} (${parsed.tls ? 'TLS' : 'plain'})`),
+  );
+
+  if (/^(localhost|127\.|::1)/.test(parsed.host)) {
+    steps.push(
+      step(
+        'Target',
+        true,
+        'localhost — this points at YOUR machine',
+        'To reach someone else, use THEIR address. localhost never leaves this computer.',
+      ),
+    );
+  }
+
+  if (!isIpLiteral(parsed.host)) {
+    const address = await resolveHost(parsed.host, deps);
+    steps.push(
+      address
+        ? step('DNS', true, `${parsed.host} → ${address}`)
+        : step(
+            'DNS',
+            false,
+            `cannot resolve ${parsed.host}`,
+            'Check the name, or use the IP directly.',
+          ),
+    );
+    if (!address) {
+      return steps;
+    }
+  }
+
+  const tcp = await probeTcp(parsed.host, parsed.port, timeoutMs, deps);
+  if (!tcp.ok) {
+    steps.push(
+      step(
+        'TCP port',
+        false,
+        `port ${parsed.port} unreachable (${tcp.reason})`,
+        tcp.reason === 'timeout'
+          ? 'Something is dropping the packets: a firewall on either side, or client isolation on the Wi-Fi router. If you can ping the host but not open the port, that is the usual cause.'
+          : 'Nothing is listening there. Is the server running, and is the port right?',
+      ),
+    );
+    return steps;
+  }
+  steps.push(step('TCP port', true, `${parsed.host}:${parsed.port} is open`));
+
+  if (parsed.tls) {
+    const tls = await probeTls(parsed.host, parsed.port, timeoutMs, deps);
+    if (!tls.ok) {
+      steps.push(
+        step(
+          'TLS',
+          false,
+          `handshake failed (${tls.reason})`,
+          'The port answered but did not negotiate TLS. Is that really a CipherMesh relay?',
+        ),
+      );
+      return steps;
+    }
+    if (tls.authorized) {
+      steps.push(step('TLS', true, `verified against a public CA (${tls.issuer})`));
+    } else if (tls.reason === 'ERR_TLS_CERT_ALTNAME_INVALID') {
+      // The certificate is valid but belongs to someone else: you are talking
+      // to the wrong machine. Almost always a stale or wrong DNS record.
+      steps.push(
+        step(
+          'TLS',
+          false,
+          `the certificate is for "${tls.subject || '?'}", not ${parsed.host}`,
+          'You reached a different server than you meant to. Check the DNS record for this name, ' +
+            'and flush your resolver cache if it was changed recently.',
+        ),
+      );
+      return steps;
+    } else {
+      steps.push(
+        step(
+          'TLS',
+          true,
+          `self-signed certificate (normal on a LAN)${tls.reason ? ` — ${tls.reason}` : ''}`,
+          'Trust is pinned on first use — compare fingerprints out-of-band if you want certainty.',
+        ),
+      );
+    }
+  }
+
+  steps.push(
+    step(
+      'Protocol',
+      true,
+      `this client speaks v${PROTOCOL_VERSION}`,
+      'If the server refuses with a protocol mismatch, update BOTH sides: npx ciphermesh@latest, or git pull && npm install from source.',
+    ),
+  );
+
+  return steps;
+}
+
+/** Render diagnose() output as lines ready for the chat log. */
+export function formatDiagnosis(steps) {
+  const lines = [];
+  for (const s of steps) {
+    lines.push(`${s.ok ? '✓' : '✗'} ${s.name}: ${s.detail}`);
+    if (s.hint) {
+      lines.push(`    ↳ ${s.hint}`);
+    }
+  }
+  const failed = steps.find((s) => !s.ok);
+  lines.push(
+    failed
+      ? `Blocked at "${failed.name}". Fix that first — the checks after it were skipped.`
+      : 'All checks passed. If the chat still fails, the problem is above the network layer.',
+  );
+  return lines;
+}