ciphermesh 1.0.0 → 1.2.1

package/README.md

@@ -43,7 +43,7 @@ forwarding, survives CGNAT).
 | 🔐 | **Real E2EE** | Curve25519 + XSalsa20-Poly1305 via libsodium, keys in `sodium_malloc` — never touch disk |
 | 🔄 | **Perfect Forward Secrecy** | Double Ratchet: one key per message, compromise today ≠ read yesterday |
 | 🕶️ | **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 |
+| 🕵️ | **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

@@ -43,7 +43,7 @@ forwarding, imune a CGNAT).
 | 🔐 | **E2EE de verdade** | Curve25519 + XSalsa20-Poly1305 via libsodium, chaves em `sodium_malloc` — nunca tocam o disco |
 | 🔄 | **Perfect Forward Secrecy** | Double Ratchet: uma chave por mensagem — comprometer hoje ≠ ler ontem |
 | 🕶️ | **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 |
+| 🕵️ | **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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ciphermesh",
-  "version": "1.0.0",
+  "version": "1.2.1",
   "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

@@ -35,6 +35,8 @@ import { detectImageProtocol, encodeInlineImage } from '../shared/terminalGraphi
 import { suggestCommand } from '../shared/commandSuggest.js';
 import { nextCoverDelay, coverPayload, isCover } from '../shared/coverTraffic.js';
 import { recordVoiceNote, playVoiceNote, isAudioFile } from '../shared/voiceNote.js';
+import { trustBadge } from '../shared/trust.js';
+import { tipAt, TIPS } from '../shared/tips.js';
 import { setTheme, getThemeName, themeNames } from '../shared/themes.js';
 import { panicWipe } from '../shared/panic.js';
 import { farewellBanner } from '../shared/banner.js';
@@ -57,6 +59,8 @@ export class ChatController {
   #peerTypingTimers; // Map<sessionId, timeoutId>
   #fileTransfer;
   #pendingFileOffers = new Map(); // transferId -> { from, data, nickname }
+  #verifyNudged = new Set(); // peers already nudged to /verify this session
+  #tipIndex = -1; // rotates through TIPS for /tips
   #lastImagePath = null; // last received image (for /img full-res render)
   #lastAudioPath = null; // last received voice note (for /play)
   #keyRotationTimer;
@@ -464,6 +468,7 @@ export class ChatController {
     this.#ui.setOnlineCount(this.#peers.size + 1);
     this.#ui.setPeerNames([...this.#peers.values()].map((p) => p.nickname));
     this.#ui.handshakeConnect(peer.nickname);
+    this.#nudgeVerify(peer.nickname);
     this.#auditLog.log(AuditEvent.PEER_CONNECTED, { nickname: peer.nickname });
 
     // A newcomer doesn't know my presence — send only to them
@@ -472,6 +477,18 @@ export class ChatController {
     }
   }
 
+  // One-time-per-session nudge to verify an unverified peer's identity.
+  #nudgeVerify(nickname) {
+    const key = nickname.toLowerCase();
+    if (this.#trustStore.isVerified(nickname) || this.#verifyNudged.has(key)) {
+      return;
+    }
+    this.#verifyNudged.add(key);
+    this.#ui.addSystemMessage(
+      `🔑 ${nickname} is unverified — run /verify ${nickname} to confirm their identity`,
+    );
+  }
+
   // ── Peer left ─────────────────────────────────────────────────
   #onPeerLeft(msg) {
     const peer = this.#peers.get(msg.sessionId);
@@ -812,6 +829,7 @@ export class ChatController {
 
       const mentioned = this.#mentionsMe(data.text) && !data.isDM;
       const ephLabel = data.ephemeral ? this.#formatDuration(data.ephemeral) : null;
+      const trust = trustBadge(this.#trustStore.getPeerRecord(peer.nickname), peer.publicKey);
       const { lineIndex } = this.#ui.addMessage(
         peer.nickname,
         data.text,
@@ -819,6 +837,7 @@ export class ChatController {
         ephLabel,
         isDeniable || !!data.deniable,
         mentioned,
+        trust,
       );
       const notify = shouldNotify(this.#dndMode, this.#dndWindow, nowMinutes(), mentioned);
       if (notify) {
@@ -889,6 +908,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');
@@ -906,6 +926,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(
@@ -1201,6 +1222,12 @@ export class ChatController {
         this.#ui.addInfoMessage(`Current room: #${this.#currentRoom}`);
         break;
 
+      case '/tips': {
+        this.#tipIndex = (this.#tipIndex + 1) % TIPS.length;
+        this.#ui.addTip(tipAt(this.#tipIndex));
+        break;
+      }
+
       case '/deniable': {
         const denArg = parts[1]?.toLowerCase();
         if (denArg === 'off') {

package/src/client/UI.js

@@ -15,6 +15,7 @@ const INPUT_MAX_LINES = 8; // input box grows up to this many text lines
 // Command → one-line description for the Ctrl+K fuzzy command palette.
 const COMMAND_INFO = [
   ['/help', 'Show help'],
+  ['/tips', 'Show a security/UX tip'],
   ['/users', 'List online users'],
   ['/msg', 'Private message (DM)'],
   ['/reply', 'Reply to the last message'],
@@ -64,6 +65,7 @@ const COMMAND_INFO = [
 
 export const COMMANDS = [
   '/help',
+  '/tips',
   '/nick',
   '/users',
   '/fingerprint',
@@ -455,6 +457,7 @@ export class UI extends EventEmitter {
   #shimmerTimer;
   #shimmerPos;
   #unseenCount;
+  #unseenMentions;
   #pillTimer;
   #pillFrame;
   #palette;
@@ -501,6 +504,7 @@ export class UI extends EventEmitter {
     this.#shimmerTimer = null;
     this.#shimmerPos = 0;
     this.#unseenCount = 0;
+    this.#unseenMentions = 0;
     this.#pillTimer = null;
     this.#pillFrame = 0;
     this.#paletteOpen = false;
@@ -508,10 +512,18 @@ export class UI extends EventEmitter {
     this.#emojiOpen = false;
     this.#emojiQuery = '';
 
+    // blessed's terminfo parser can't compile the modern Setulc (underline
+    // colour) capability that terminals like ghostty ship, so it dumps a
+    // compile error when it resets the terminal on exit (e.g. Ctrl+C). Those
+    // terminals are xterm-256color-compatible for everything we render — images
+    // use their own escape sequences, not blessed — so pin tput to xterm-256color
+    // and sidestep the broken capability.
+    const term = process.env.TERM || '';
     this.#screen = blessed.screen({
       smartCSR: true,
       fullUnicode: true, // renders emojis and characters outside the BMP
       title: 'CipherMesh',
+      terminal: /ghostty/i.test(term) ? 'xterm-256color' : undefined,
     });
 
     // ── Header ──────────────────────────────────────────
@@ -1320,6 +1332,7 @@ export class UI extends EventEmitter {
     ephemeralLabel = null,
     deniable = false,
     mentioned = false,
+    trust = 'none',
   ) {
     this.#daySeparator();
 
@@ -1330,6 +1343,15 @@ export class UI extends EventEmitter {
     const dmLabel = isDM ? ' {magenta-fg}(DM){/magenta-fg}' : '';
     const ephLabel = ephemeralLabel ? ` {yellow-fg}[${ephemeralLabel}]{/yellow-fg}` : '';
     const denLabel = deniable ? ' {magenta-fg}[D]{/magenta-fg}' : '';
+    // Trust badge next to the name: check = SAS-verified, cross = key changed.
+    const trustGlyph =
+      trust === 'verified'
+        ? ' {green-fg}✓{/green-fg}'
+        : trust === 'mismatch'
+          ? ' {red-fg}✗{/red-fg}'
+          : '';
+    // A yellow left rule makes a line that @-mentions you jump out of the log.
+    const bar = mentioned && !isSelf ? '{yellow-fg}▏{/yellow-fg}' : ' ';
     const mentionMark = mentioned && !isSelf ? '{yellow-fg}\ud83d\udd14 {/yellow-fg}' : '';
 
     // Consecutive messages from the same peer collapse the avatar/name into a
@@ -1337,19 +1359,19 @@ export class UI extends EventEmitter {
     const grouped = !isSelf && !isDM && this.#lastSender === nickname;
     const core = grouped
       ? `{${tag}}\u00b7{/${tag}} ${renderMarkdown(text)}`
-      : `${avatar} {${tag}}${nickname}{/${tag}}${dmLabel}: ${renderMarkdown(text)}`;
+      : `${avatar} {${tag}}${nickname}{/${tag}}${trustGlyph}${dmLabel}: ${renderMarkdown(text)}`;
 
     // 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}`)
-      : ` {white-fg}[${time()}]{/white-fg}${ephLabel}${denLabel} ${mentionMark}${core}`;
+      : `${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();
+      this.#noteIncoming(mentioned || isDM);
     }
     return { lineIndex: this.#lines.length - 1 };
   }
@@ -1424,6 +1446,33 @@ export class UI extends EventEmitter {
     this.#screen.render();
   }
 
+  // A one-line security/UX tip (💡). Plain text — no blessed tags interpreted.
+  addTip(text) {
+    this.#lastSender = null;
+    const line = ` {yellow-fg}💡{/yellow-fg} {#9a9ad0-fg}${blessed.escape(text)}{/#9a9ad0-fg}`;
+    this.#lines.push(line);
+    this.#chatLog.log(line);
+    this.#screen.render();
+  }
+
+  // A framed "getting started" panel for the empty chat. `lines` may contain
+  // blessed tags (the caller styles them); the title is escaped.
+  addWelcome(title, lines) {
+    this.#lastSender = null;
+    const push = (l) => {
+      this.#lines.push(l);
+      this.#chatLog.log(l);
+    };
+    push('');
+    push(`  {#7b2dff-fg}╭─{/#7b2dff-fg} {bold}${blessed.escape(title)}{/bold}`);
+    for (const l of lines) {
+      push(`  {#7b2dff-fg}│{/#7b2dff-fg}  ${l}`);
+    }
+    push(`  {#7b2dff-fg}╰──────────────────────────────────────────{/#7b2dff-fg}`);
+    push('');
+    this.#screen.render();
+  }
+
   addQuoteLine(nickname, excerpt, alignRight = false) {
     const quoted = `{#888888-fg}↩ ${blessed.escape(nickname)}: "${blessed.escape(excerpt)}"{/#888888-fg}`;
     const line = alignRight ? this.#alignRight(quoted) : `   ${quoted}`;
@@ -1463,7 +1512,8 @@ export class UI extends EventEmitter {
     if (scrolledUp !== this.#scrolledUp) {
       this.#scrolledUp = scrolledUp;
       if (!scrolledUp) {
-        this.#unseenCount = 0; // back at the bottom — everything is seen
+        this.#unseenCount = 0;
+        this.#unseenMentions = 0; // back at the bottom — everything is seen
       }
       this.#refreshScrollIndicator();
     }
@@ -1472,9 +1522,12 @@ export class UI extends EventEmitter {
 
   // Count a fresh arrival while the user is reading history, and pulse the
   // "new messages" pill so they know to page down.
-  #noteIncoming() {
+  #noteIncoming(important = false) {
     if (this.#scrolledUp) {
       this.#unseenCount++;
+      if (important) {
+        this.#unseenMentions++;
+      }
       this.#refreshScrollIndicator();
     }
   }
@@ -1504,7 +1557,9 @@ export class UI extends EventEmitter {
 
   #renderPill() {
     const n = this.#unseenCount;
-    const plural = n === 1 ? 'new message' : 'new messages';
+    const plural =
+      (n === 1 ? 'new message' : 'new messages') +
+      (this.#unseenMentions > 0 ? `, ${this.#unseenMentions} @you` : '');
     const bright = this.#pillFrame % 2 === 0;
     const label = bright
       ? `{black-fg}{yellow-bg} ↓ ${n} ${plural} — PageDown {/yellow-bg}{/black-fg}`

package/src/client/index.js

@@ -18,6 +18,7 @@ import { parseInvite } from '../shared/invite.js';
 import { importBackup } from '../crypto/IdentityBackup.js';
 import { questionHidden } from '../shared/prompt.js';
 import { loadConfig, startupCommands } from '../shared/config.js';
+import { randomTip } from '../shared/tips.js';
 import { setTheme } from '../shared/themes.js';
 import { Connection } from './Connection.js';
 import { UI } from './UI.js';
@@ -196,8 +197,14 @@ const controller = new ChatController(
 );
 
 ui.setFingerprint(controller.fingerprint);
-ui.addInfoMessage(`Your fingerprint: ${controller.fingerprint}`);
-ui.addInfoMessage('Use /help to see available commands');
+ui.addWelcome('Welcome to CipherMesh', [
+  `{#8888aa-fg}Your fingerprint{/#8888aa-fg}  ${controller.fingerprint}`,
+  '',
+  '{white-fg}No peers yet — bring someone in:{/white-fg}',
+  '  {cyan-fg}/invite{/cyan-fg}  QR + link for your room       {cyan-fg}/help{/cyan-fg}  all commands',
+  '  {cyan-fg}/verify <nick>{/cyan-fg}  confirm a peer out-of-band (a green ✓ appears)',
+]);
+ui.addTip(randomTip());
 
 if (restoredState?.handshake) {
   ui.addSystemMessage('Previous session restored — ratchets preserved');

package/src/p2p/P2PChatController.js

@@ -31,6 +31,8 @@ import { setTheme, getThemeName, themeNames } from '../shared/themes.js';
 import { panicWipe } from '../shared/panic.js';
 import { farewellBanner } from '../shared/banner.js';
 import { parseDndWindow, shouldNotify, nowMinutes, mentionsMe } from '../shared/dnd.js';
+import { trustBadge } from '../shared/trust.js';
+import { tipAt, TIPS } from '../shared/tips.js';
 import { COMMANDS } from '../client/UI.js';
 
 const TYPING_SEND_INTERVAL = 2000;
@@ -50,6 +52,8 @@ export class P2PChatController {
   #peerTypingTimers;
   #fileTransfer;
   #pendingFileOffers = new Map(); // transferId -> { data, nickname }
+  #verifyNudged = new Set(); // peers already nudged to /verify this session
+  #tipIndex = -1; // rotates through TIPS for /tips
   #knownPeers = new Set(); // nicknames seen this session (for store-and-forward)
   #sfQueue = new Map(); // nickname -> [{ payload, queuedAt }] for offline peers
   #currentRoom = 'general';
@@ -191,6 +195,7 @@ export class P2PChatController {
     this.#ui.setOnlineCount(this.#peers.size + 1);
     this.#ui.setPeerNames([...this.#peers.keys()]);
     this.#ui.handshakeConnect(nickname);
+    this.#nudgeVerify(nickname);
     this.#auditLog.log(AuditEvent.PEER_CONNECTED, { nickname });
 
     this.#knownPeers.add(nickname);
@@ -204,6 +209,18 @@ export class P2PChatController {
     this.#flushSFQueue(nickname);
   }
 
+  // One-time-per-session nudge to verify an unverified peer's identity.
+  #nudgeVerify(nickname) {
+    const key = nickname.toLowerCase();
+    if (this.#trustStore.isVerified(nickname) || this.#verifyNudged.has(key)) {
+      return;
+    }
+    this.#verifyNudged.add(key);
+    this.#ui.addSystemMessage(
+      `🔑 ${nickname} is unverified — run /verify ${nickname} to confirm their identity`,
+    );
+  }
+
   // ── Store-and-forward (P2P) ──────────────────────────────────
   #enqueueSF(nickname, payload) {
     let queue = this.#sfQueue.get(nickname);
@@ -539,6 +556,10 @@ export class P2PChatController {
     }
     const mentioned = mentionsMe(data.text, this.#nickname) && !data.isDM;
     const ephLabel = data.ephemeral ? this.#formatDuration(data.ephemeral) : null;
+    const trust = trustBadge(
+      this.#trustStore.getPeerRecord(fromNickname),
+      this.#findPeer(fromNickname)?.publicKey,
+    );
     const { lineIndex } = this.#ui.addMessage(
       fromNickname,
       data.text,
@@ -546,6 +567,7 @@ export class P2PChatController {
       ephLabel,
       isDeniable || !!data.deniable,
       mentioned,
+      trust,
     );
     const notify = shouldNotify(this.#dndMode, this.#dndWindow, nowMinutes(), mentioned);
     if (notify) {
@@ -655,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');
@@ -663,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(
@@ -1296,6 +1320,12 @@ export class P2PChatController {
         this.#ui.addInfoMessage(`Current room: #${this.#currentRoom}`);
         break;
 
+      case '/tips': {
+        this.#tipIndex = (this.#tipIndex + 1) % TIPS.length;
+        this.#ui.addTip(tipAt(this.#tipIndex));
+        break;
+      }
+
       case '/kick':
       case '/mute':
       case '/ban':

package/src/p2p/index.js

@@ -16,6 +16,7 @@ import { KeyManager } from '../crypto/KeyManager.js';
 import { StateManager } from '../crypto/StateManager.js';
 import { questionHidden } from '../shared/prompt.js';
 import { loadConfig, startupCommands } from '../shared/config.js';
+import { randomTip } from '../shared/tips.js';
 import { setTheme } from '../shared/themes.js';
 import { importBackup } from '../crypto/IdentityBackup.js';
 import { Discovery } from './Discovery.js';
@@ -182,9 +183,13 @@ const controller = new P2PChatController(
 );
 
 ui.setFingerprint(controller.fingerprint);
-ui.addInfoMessage(`Your fingerprint: ${controller.fingerprint}`);
-ui.addInfoMessage('P2P mode — peers discovered automatically via mDNS');
-ui.addInfoMessage('Use /help to see available commands');
+ui.addWelcome('Welcome to CipherMesh — P2P', [
+  `{#8888aa-fg}Your fingerprint{/#8888aa-fg}  ${controller.fingerprint}`,
+  '',
+  '{white-fg}Discovering peers on the LAN via mDNS…{/white-fg}',
+  '  {cyan-fg}/help{/cyan-fg}  all commands        {cyan-fg}/verify <nick>{/cyan-fg}  confirm a peer',
+]);
+ui.addTip(randomTip());
 
 if (restoredState?.handshake) {
   ui.addSystemMessage('Previous session restored — ratchets preserved');

package/src/shared/tips.js

@@ -0,0 +1,30 @@
+// Short, security-forward tips surfaced one-at-a-time at startup and via /tips.
+// Kept dependency-free so it can be unit-tested and reused by both modes.
+
+export const TIPS = [
+  'Run /verify <nick> to confirm a peer out-of-band — a green ✓ then appears next to their name.',
+  '/invite generates a QR code + ciphermesh:// link to pull someone into your room.',
+  '/ephemeral 5m makes new messages self-destruct after the timer.',
+  '/cover on adds decoy traffic so the relay can’t tell when you’re really chatting.',
+  '/panic wipes every on-disk secret and exits — for a lost or seized device.',
+  '/backup saves your identity + verified peers as an encrypted file.',
+  'Ctrl+K opens the command palette; Ctrl+E the emoji picker; PgUp/PgDn scrolls.',
+  'A ✗ next to a name means their key changed since you last saw it — verify before trusting.',
+  '/deniable on switches to plausibly-deniable messages (no cryptographic proof you sent them).',
+  'No server? Run it in P2P mode — peers find each other on the LAN via mDNS, no relay at all.',
+];
+
+// Pick a tip by index (wraps around). Deterministic — the caller decides the
+// index (e.g. a random one at startup, or an incrementing one for /tips).
+export function tipAt(index, tips = TIPS) {
+  if (tips.length === 0) {
+    return '';
+  }
+  const i = ((index % tips.length) + tips.length) % tips.length;
+  return tips[i];
+}
+
+// One random tip — used at startup. (Runtime only; not used in workflow scripts.)
+export function randomTip(tips = TIPS) {
+  return tipAt(Math.floor(Math.random() * tips.length), tips);
+}

package/src/shared/trust.js

@@ -0,0 +1,31 @@
+// Pure trust-verdict helpers, decoupled from the TrustStore so they can be
+// unit-tested and shared by both controllers. The store records peers as
+// { fingerprint, publicKey, firstSeen, lastSeen, verified }.
+
+export const TrustBadge = {
+  VERIFIED: 'verified', // SAS-confirmed identity
+  MISMATCH: 'mismatch', // stored key != current key (possible MITM / rotation)
+  NONE: 'none', // unknown peer, or TOFU-trusted but identity unconfirmed
+};
+
+// Decide which badge to show next to a peer, from their stored record (or null)
+// and the public key they are presenting right now.
+//   - no record            -> NONE  (brand-new peer)
+//   - key changed          -> MISMATCH
+//   - verified & key match -> VERIFIED
+//   - else                 -> NONE  (TOFU-trusted, not verified)
+export function trustBadge(record, currentPublicKey) {
+  // No record, or we don't know the key they're presenting right now (e.g. a
+  // store-and-forward message from a peer who isn't currently connected) — we
+  // can't make a claim, so show nothing rather than a false mismatch.
+  if (!record || !currentPublicKey) {
+    return TrustBadge.NONE;
+  }
+  if (record.publicKey !== currentPublicKey) {
+    return TrustBadge.MISMATCH;
+  }
+  if (record.verified) {
+    return TrustBadge.VERIFIED;
+  }
+  return TrustBadge.NONE;
+}