ciphermesh 2.5.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)):
@@ -285,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).
 
@@ -297,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)):
@@ -292,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).
 
@@ -299,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.5.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

@@ -586,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`);
     }

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

@@ -20,7 +20,12 @@ export function parseTarget(raw) {
   const withScheme = /^wss?:\/\//.test(value) ? value : `wss://${value}`;
   try {
     const url = new URL(withScheme);
-    const port = Number(url.port) || 3600;
+    // 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;
     }
@@ -81,6 +86,11 @@ function probeTls(host, port, timeoutMs, deps) {
       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,
       });
@@ -182,16 +192,31 @@ export async function diagnose(target, opts = {}) {
       );
       return steps;
     }
-    steps.push(
-      tls.authorized
-        ? step('TLS', true, `verified against a public CA (${tls.issuer})`)
-        : step(
-            'TLS',
-            true,
-            'self-signed certificate (normal on a LAN)',
-            'Trust is pinned on first use — compare fingerprints out-of-band if you want certainty.',
-          ),
-    );
+    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(