ciphermesh 1.2.1 → 2.1.0

package/README.md

@@ -42,7 +42,7 @@ forwarding, survives CGNAT).
 |-----|---------|----------|
 | 🔐 | **Real E2EE** | Curve25519 + XSalsa20-Poly1305 via libsodium, keys in `sodium_malloc` — never touch disk |
 | 🔄 | **Perfect Forward Secrecy** | Double Ratchet: one key per message, compromise today ≠ read yesterday |
-| 🕶️ | **Metadata resistance** | Fixed-bucket length padding on every ciphertext + opt-in cover traffic (`/cover`) to blur when you chat |
+| 🕶️ | **Metadata resistance** | **Sealed sender** — the relay never sees who sent a message — plus fixed-bucket length padding on every ciphertext and opt-in cover traffic (`/cover`) |
 | 🕵️ | **TOFU + SAS** | Key-change detection (MITM alarm), 6-digit voice-verifiable codes, and inline **✓/✗** trust badges next to names |
 | 🌐 | **LAN & internet** | Auto-detects Tailscale, shows the reachable address in the banner |
 | 📨 | **Invites with QR** | `/invite` prints a `ciphermesh://` string + QR — paste it, you're in the right room |
@@ -53,7 +53,9 @@ forwarding, survives CGNAT).
 | 💬 | **Modern chat feel** | Right-aligned own messages, per-user emoji avatars, replies with quotes, `:fire:` → 🔥 |
 | 🎞️ | **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 |
+| 🧩 | **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
 
@@ -131,12 +133,21 @@ QR code) to whoever you want to pull in.
 
 | Command | Description |
 |---------|-------------|
-| `/join <room>` | Enter/create a room |
-| `/rooms` | List rooms |
+| `/join <room> [password]` | Enter/create a room (password if it's private) |
+| `/create <room> <password>` | Create a **private room** 🔒 — see below |
+| `/rooms` | List rooms (🔒 marks private ones) |
 | `/room` | Current room |
 | `/owner` | Room owner |
 | `/kick` `/mute` `/ban` | Owner moderation |
 
+**Private rooms** are zero-knowledge: the password never leaves your machine.
+Joining derives an Ed25519 key from the password (Argon2id) and answers a
+server challenge with a signature — the server stores only a verifier, in
+memory, and it dies when the last member leaves (rooms are always ephemeral).
+On top of that, everything said in a private room carries an extra symmetric
+layer keyed by the password, so even a malicious relay that let someone in
+without verifying couldn't read a word. Share the password out-of-band.
+
 </details>
 
 <details>
@@ -148,8 +159,10 @@ QR code) to whoever you want to pull in.
 | `/verify <nick>` | SAS code (~40-bit) + QR + key randomart for out-of-band verification |
 | `/verify-confirm <nick>` | Mark peer as verified |
 | `/trust <nick>` / `/trustlist` | Accept new key / trust status |
+| `/contacts [add\|remove\|all]` | Contact book — persistent aliases on trust records ("this fingerprint is João"); shows in `/users`, rides along in identity backups |
 | `/backup [path]` | Encrypted backup of identity + verified peers (restore at startup) |
 | `/deniable [on\|off]` | Plausible-deniability mode |
+| `/lock` / `/autolock <min\|off>` | Lock the screen behind the session passphrase — manually or after idle time (`autoLock` in config). Privacy for the "stepped away" moment; `/panic` is for the worst one |
 | `/panic [yes]` | Duress wipe — securely erase all on-disk secrets (session, history, trust, keys) and exit |
 | `/cover [on\|constant\|off]` | Cover traffic — `on` = jittered decoys, `constant` = steady-rate paced channel |
 | `/theme [name]` | Nick colour theme: neon, matrix, mono, sunset, ocean |
@@ -183,7 +196,8 @@ A green **✓** next to a name marks a SAS-verified peer; a red **✗** flags a
 
 | Command | Description |
 |---------|-------------|
-| `/away [reason]` / `/back` | Mark yourself away |
+| `/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 |
@@ -194,11 +208,23 @@ A green **✓** next to a name marks a SAS-verified peer; a red **✗** flags a
 
 </details>
 
-Typing `:fire:` anywhere becomes 🔥 (Tab autocompletes shortcodes). **Ctrl+K** opens a fuzzy command palette, **Ctrl+E** an emoji picker. PageUp/PageDown scroll the history. **Alt+Enter** (or Shift+Enter where the terminal supports it, plus Ctrl+J) inserts a newline for multi-line messages; Enter sends. Markdown works: \`code\`, **bold**, *italic*, links, plus fenced \`\`\` code blocks and | tables |. Received images preview inline (half-blocks) and render full-res with `/img` on kitty/iTerm2. Day separators and message grouping keep the log clean.
+Typing `:fire:` anywhere becomes 🔥 (Tab autocompletes shortcodes). **Ctrl+K** opens a fuzzy command palette, **Ctrl+E** an emoji picker. PageUp/PageDown scroll the history. **Alt+Enter** (or Shift+Enter where the terminal supports it, plus Ctrl+J) inserts a newline for multi-line messages; Enter sends. Pasting multi-line text (code included) keeps its line breaks — paste, check, Enter. Markdown works: \`code\`, **bold**, *italic*, links, plus fenced \`\`\` code blocks and | tables |. Received images preview inline (half-blocks) and render full-res with `/img` on kitty/iTerm2. Day separators and message grouping keep the log clean.
+
+### First run & config file
+
+On your very first run, a **30-second setup wizard** walks you through nickname,
+colour theme and default server (with a 3-line crash course on how the
+encryption works), then saves everything so later runs go straight to the chat.
+Re-run it anytime with `ciphermesh --setup`; skip it in scripts/CI with
+`--no-onboard`.
 
-### Config file
+CipherMesh also remembers your **last session**: the server prompt defaults to
+where you were, and after connecting you land back in your last room
+automatically (private rooms excluded — their names never touch disk). Start
+clean with `ciphermesh --fresh`.
 
-Drop a `~/.ciphermesh/config.json` to set defaults and skip the prompts. All keys are optional (unknown keys are ignored):
+The wizard writes `~/.ciphermesh/config.json` — you can also edit it by hand.
+All keys are optional (unknown keys are ignored):
 
 ```json
 {
@@ -211,6 +237,7 @@ Drop a `~/.ciphermesh/config.json` to set defaults and skip the prompts. All key
   "cover": "constant",
   "theme": "matrix",
   "autoAway": 10,
+  "autoLock": 5,
   "dnd": "22:00-08:00"
 }
 ```

package/README.pt-BR.md

@@ -42,7 +42,7 @@ forwarding, imune a CGNAT).
 |-----|---------|--------|
 | 🔐 | **E2EE de verdade** | Curve25519 + XSalsa20-Poly1305 via libsodium, chaves em `sodium_malloc` — nunca tocam o disco |
 | 🔄 | **Perfect Forward Secrecy** | Double Ratchet: uma chave por mensagem — comprometer hoje ≠ ler ontem |
-| 🕶️ | **Resistência a metadados** | Padding de comprimento em buckets fixos em todo ciphertext + cover traffic opcional (`/cover`) pra borrar quando você conversa |
+| 🕶️ | **Resistência a metadados** | **Sealed sender** — o relay nunca vê quem enviou a mensagem — + padding de comprimento em buckets fixos em todo ciphertext e cover traffic opcional (`/cover`) |
 | 🕵️ | **TOFU + SAS** | Alarme de troca de chave (MITM), código de 6 dígitos verificável por voz e badges de confiança **✓/✗** inline ao lado dos nomes |
 | 🌐 | **LAN e internet** | Detecta Tailscale sozinho e mostra o endereço alcançável no banner |
 | 📨 | **Convites com QR** | `/invite` gera uma string `ciphermesh://` + QR — colou, caiu na sala certa |
@@ -53,7 +53,9 @@ forwarding, imune a CGNAT).
 | 💬 | **Cara de app moderno** | Suas mensagens à direita, avatar de emoji por usuário, reply com citação, `:fire:` → 🔥 |
 | 🎞️ | **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 |
+| 🧩 | **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
 
@@ -131,12 +133,21 @@ quem você quiser puxar pra conversa.
 
 | Comando | Descrição |
 |---------|-----------|
-| `/join <sala>` | Entra/cria uma sala |
-| `/rooms` | Lista salas |
+| `/join <sala> [senha]` | Entra/cria uma sala (senha se for privada) |
+| `/create <sala> <senha>` | Cria uma **sala privada** 🔒 — veja abaixo |
+| `/rooms` | Lista salas (🔒 marca as privadas) |
 | `/room` | Sala atual |
 | `/owner` | Dono da sala |
 | `/kick` `/mute` `/ban` | Moderação (dono da sala) |
 
+**Salas privadas** são zero-knowledge: a senha nunca sai da sua máquina. Ao
+entrar, o cliente deriva uma chave Ed25519 da senha (Argon2id) e responde um
+desafio do servidor com uma assinatura — o servidor guarda só um verificador,
+em memória, que morre quando a última pessoa sai (salas são sempre efêmeras).
+Além disso, tudo que é dito numa sala privada carrega uma camada simétrica
+extra derivada da senha: mesmo um relay malicioso que deixasse alguém entrar
+sem verificar não leria uma palavra. Combine a senha por outro canal.
+
 </details>
 
 <details>
@@ -149,7 +160,9 @@ quem você quiser puxar pra conversa.
 | `/verify-confirm <nick>` | Marca o peer como verificado |
 | `/backup [caminho]` | Backup cifrado da identidade + peers verificados (restaura no startup) |
 | `/trust <nick>` / `/trustlist` | Aceita chave nova / status de confiança |
+| `/contacts [add\|remove\|all]` | Agenda — apelidos persistentes nos registros de confiança ("esse fingerprint é o João"); aparece no `/users` e viaja no backup de identidade |
 | `/deniable [on\|off]` | Modo de negação plausível |
+| `/lock` / `/autolock <min\|off>` | Trava a tela atrás da passphrase da sessão — na mão ou após inatividade (`autoLock` no config). Privacidade para o "saí um minuto"; o `/panic` é para o pior minuto |
 | `/panic [sim]` | Wipe de coação — apaga com segurança todos os segredos do disco (sessão, histórico, confiança, chaves) e sai |
 | `/cover [on\|constant\|off]` | Cover traffic — `on` = iscas com jitter, `constant` = canal de taxa constante |
 | `/theme [nome]` | Tema de cores dos nicks: neon, matrix, mono, sunset, ocean |
@@ -183,7 +196,8 @@ Um **✓** verde ao lado de um nome indica um peer verificado por SAS; um **✗*
 
 | Comando | Descrição |
 |---------|-----------|
-| `/away [motivo]` / `/back` | Marca/remove ausência |
+| `/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 |
@@ -195,11 +209,23 @@ Um **✓** verde ao lado de um nome indica um peer verificado por SAS; um **✗*
 </details>
 
 Digitar `:fire:` em qualquer lugar vira 🔥 (Tab autocompleta shortcodes).
-**Ctrl+K** abre uma paleta de comandos fuzzy, **Ctrl+E** um seletor de emoji. PageUp/PageDown rolam o histórico. **Alt+Enter** (ou Shift+Enter onde o terminal suporta, além de Ctrl+J) insere uma nova linha para mensagens de várias linhas; Enter envia. Markdown funciona: \`código\`, **negrito**, *itálico*, links, além de blocos de código \`\`\` e | tabelas |. Imagens recebidas têm preview inline (half-blocks) e renderizam em alta resolução com `/img` no kitty/iTerm2. Separadores de dia e agrupamento de mensagens deixam o log limpo.
+**Ctrl+K** abre uma paleta de comandos fuzzy, **Ctrl+E** um seletor de emoji. PageUp/PageDown rolam o histórico. **Alt+Enter** (ou Shift+Enter onde o terminal suporta, além de Ctrl+J) insere uma nova linha para mensagens de várias linhas; Enter envia. Colar texto multi-linha (código incluso) preserva as quebras — cola, confere, Enter. Markdown funciona: \`código\`, **negrito**, *itálico*, links, além de blocos de código \`\`\` e | tabelas |. Imagens recebidas têm preview inline (half-blocks) e renderizam em alta resolução com `/img` no kitty/iTerm2. Separadores de dia e agrupamento de mensagens deixam o log limpo.
+
+### Primeira execução & arquivo de config
+
+Na primeiríssima execução, um **wizard de 30 segundos** te guia por nickname,
+tema de cores e servidor padrão (com um mini-curso de 3 linhas de como a
+criptografia funciona) e salva tudo — das próximas vezes você cai direto no
+chat. Refaça quando quiser com `ciphermesh --setup`; pule em scripts/CI com
+`--no-onboard`.
 
-### Arquivo de config
+O CipherMesh também lembra a sua **última sessão**: o prompt de servidor passa
+a ter como padrão onde você estava, e depois de conectar você volta sozinho
+para a última sala (salas privadas ficam de fora — o nome delas nunca toca o
+disco). Para começar do zero: `ciphermesh --fresh`.
 
-Crie um `~/.ciphermesh/config.json` para definir padrões e pular os prompts. Todas as chaves são opcionais (chaves desconhecidas são ignoradas):
+O wizard grava o `~/.ciphermesh/config.json` — que você também pode editar na
+mão. Todas as chaves são opcionais (chaves desconhecidas são ignoradas):
 
 ```json
 {
@@ -212,6 +238,7 @@ Crie um `~/.ciphermesh/config.json` para definir padrões e pular os prompts. To
   "cover": "constant",
   "theme": "matrix",
   "autoAway": 10,
+  "autoLock": 5,
   "dnd": "22:00-08:00"
 }
 ```

package/bin/ciphermesh.js

@@ -19,6 +19,11 @@ Usage:
 Options:
   -h, --help            show this help
   -v, --version         show the version
+
+Client options:
+  --setup               re-run the first-run setup wizard
+  --no-onboard          skip the first-run wizard (scripts/CI)
+  --fresh               forget the last session (server/room) and start clean
 `;
 
 const arg = process.argv[2];

package/docs/ARCHITECTURE.md

@@ -448,7 +448,12 @@ Types:
 | `peer_left` | Server -> Clients | A peer left |
 | `key_exchange` | Client -> Server -> Client | Public key exchange between peers |
 | `encrypted_message` | Client -> Server -> Client | Encrypted message |
-| `error` | Server -> Client | Error (duplicate nickname, etc.) |
+| `change_room` | Client -> Server | Enter/create a room (+ optional `roomAuthPk` verifier when creating a private room) |
+| `room_changed` | Server -> Client | Room switch confirmed (+ `private` flag) |
+| `list_rooms` / `room_list` | Client <-> Server | Room list (each room carries a `private` flag) |
+| `room_challenge` | Server -> Client | Target room is private — sign this nonce (see 6.9) |
+| `room_auth` | Client -> Server | Ed25519 signature proving password knowledge (see 6.9) |
+| `error` | Server -> Client | Error (duplicate nickname, wrong room password, etc.) |
 | `ping` / `pong` | Bidirectional | Heartbeat |
 
 #### `src/protocol/validators.js` — Validation
@@ -533,18 +538,14 @@ export const FILE_CHUNK_SIZE = 49152;            // 48KB
 ```json
 {
   "type": "encrypted_message",
-  "version": 1,
+  "version": 2,
   "timestamp": 1739800001000,
-  "from": "550e8400-e29b-41d4-a716-446655440000",
   "to": "660e8400-e29b-41d4-a716-446655440001",
-  "payload": {
-    "ciphertext": "base64(mensagem cifrada com crypto_box_easy)",
-    "nonce": "base64(24 bytes do nonce usado)"
-  }
+  "sealed": "base64( crypto_box_seal({ from, payload }, recipientPublicKey) )"
 }
 ```
 
-**Note**: The `payload` field is completely opaque to the server. It only reads `from` and `to` for routing.
+**Note (sealed sender, v2)**: The relay sees only `to` (for routing) and an opaque `sealed` blob. The sender (`from`) *and* the whole already-E2E-encrypted `payload` are sealed to the recipient's public key with libsodium `crypto_box_seal` — an anonymous box only the recipient can open. The relay therefore learns **neither who sent the message nor what's inside**, and it never stamps, stores, or logs a sender. The recipient opens the seal to recover `{ from, payload }`, then decrypts the payload as before. (See §10 for the exact — honest — guarantee and its limits.)
 
 ### 5.4 Decrypted content (never travels in cleartext)
 
@@ -737,6 +738,41 @@ fingerprint = SHA-256(publicKey)
             = "A1B2:C3D4:E5F6:7890"
 ```
 
+### 6.9 Private Rooms (password-protected, zero-knowledge)
+
+`/create <room> <password>` creates a room the server can gate **without ever
+seeing the password** (`src/crypto/RoomKey.js`):
+
+```
+seed(64B) = Argon2id(password, salt = BLAKE2b("ciphermesh/room-v1:" + room))
+          ├── authSeed (32B) → Ed25519 keypair   (join authentication)
+          └── roomKey  (32B) → secretbox key     (room content layer)
+```
+
+**Join authentication (challenge-response):**
+```
+1. Creator sends change_room + roomAuthPk (the Ed25519 PUBLIC key).
+   The server stores it as the room's verifier — in memory only.
+2. A joiner sends change_room → server replies room_challenge { nonce }.
+3. The joiner signs "ciphermesh/room-auth-v1:room:nonce:sessionId" with the
+   password-derived secret key → room_auth { signature }.
+4. The server verifies against the stored verifier. Wrong password ⇒ a
+   different keypair ⇒ invalid signature ⇒ ROOM_AUTH_FAILED.
+```
+
+The signature binds room, nonce **and** sessionId, so it can't be replayed by
+another connection. Wrong-password attempts are throttled per connection, and
+each guess costs the attacker a full Argon2id derivation client-side. When the
+last member leaves, the room dies and the verifier with it — same ephemeral
+lifecycle as public rooms.
+
+**Content layer:** every payload sent in a private room is wrapped as
+`{ rk: 1, n, c }` — `crypto_secretbox(payload, roomKey)` — *before* the normal
+pairwise encryption (ratchet/sealed sender). So even a malicious relay that
+skipped verification and injected a member could not read the room: reading
+requires the password. The outer layer already pads ciphertexts, so the
+wrapper adds no metadata leak.
+
 ---
 
 ## 7. Handshake Protocol
@@ -939,17 +975,29 @@ a server change and is not wired up there yet.)
 | **Denial of Service** | Rate limiting + maxPayload | Partial |
 | **Forward secrecy** | Double Ratchet — a unique key per message | Mitigated |
 | **Metadata analysis** | Message padding + fixed sizes | Partial |
+| **Relay learns who SENT each message** | Sealed sender — the sender + payload are sealed to the recipient; the relay routes by recipient only and never stamps, stores, or logs a sender | Partial (honest relay) |
 
 ### 10.2 What the server CAN deduce (metadata)
 
 Even without reading content, the server knows:
-- **Who** is online
-- **Who** talks to whom
+- **Who** is online (the roster: nicknames + public keys, from JOIN)
+- **To whom** each message is routed (the recipient) — *the **sender** is hidden by sealed sender; an honest relay never learns who sent a given message*
 - **When** messages are sent — *mitigated by cover traffic (optional)*
 - **Approximate size** of messages — *mitigated: only the padding bucket leaks*
 - **Frequency** of communication — *mitigated by cover traffic (optional)*
 
 Implemented mitigations:
+- **Sealed sender** (`crypto/SealedSender.js`, protocol v2): every
+  `encrypted_message` carries only `to` + an opaque `sealed` blob. The sender's
+  identity and the inner payload are wrapped in a libsodium `crypto_box_seal`
+  (anonymous box) to the recipient's key; the relay routes by recipient and
+  **never stamps, stores, or logs who sent a message**. *Honest guarantee &
+  limits:* this protects against an honest-but-curious relay, offline-queue
+  compromise, and network observers — the same model as Signal's sealed sender.
+  It does **not** anonymise the sender against a *malicious* relay that
+  correlates the sending socket (inherent to a persistent authenticated
+  connection), the **recipient** is still visible (routing needs it), and P2P
+  mode has no relay at all.
 - **Length padding** (`MessageCrypto.padMessage`, buckets
   `[128..32768]`): applied on all three encryption paths (static, ratchet, and
   deniable) before encrypting. The server sees only which bucket, not the real size.

package/docs/PLUGINS.md

@@ -0,0 +1,69 @@
+# CipherMesh Plugin API
+
+CipherMesh loads user plugins at startup from `~/.ciphermesh/plugins/*.js` and
+routes unknown slash-commands to them. Plugins work in both relay and P2P mode.
+
+## Quick start
+
+```bash
+mkdir -p ~/.ciphermesh/plugins
+cp examples/plugins/roll.js examples/plugins/poll.js ~/.ciphermesh/plugins/
+```
+
+Restart the client — `/plugins` lists what loaded, and `/roll 2d20+3` /
+`/poll Pizza tonight? | yes | obviously` just work.
+
+## Plugin format
+
+A plugin is an ES module whose **default export** is:
+
+```js
+export default {
+  name: 'roll',                       // required, unique
+  description: 'Roll dice',           // optional, shown by /plugins
+  commands: {
+    // key = command name (with or without the leading slash)
+    roll(args) {
+      // args: string[] — everything typed after the command, split on spaces
+      return { send: '🎲 4' };
+    },
+  },
+};
+```
+
+Files that fail to import, or lack `name`/`commands`, are skipped silently.
+
+## Handler return values
+
+| Return | Effect |
+|--------|--------|
+| `{ send: '<text>' }` | The text is **sent to the current room** as a normal end-to-end-encrypted message (and echoed locally). Markdown and multi-line text work. |
+| `{ info: '<text>' }` | Shown **only locally** as an info line. |
+| `'<text>'` (plain string) | Same as `{ info }` — the original API, still supported. |
+| `null` / `undefined` / throw | Treated as "not handled": the user sees *Unknown command*. |
+
+Handlers are synchronous — return the final value directly.
+
+## Precedence and naming
+
+Built-in commands always win: a plugin command named `/help` or `/join` is
+never reached. Plugin commands are only tried when no built-in matches. If two
+plugins register the same command, the one loaded last wins (load order is the
+directory listing).
+
+## Security model — read this
+
+A plugin is **arbitrary JavaScript running inside your chat process**, with
+your privileges and full access to your keys in memory. There is no sandbox.
+
+- Only install plugins you wrote or read line-by-line.
+- Treat a plugin file like you treat `curl | sh`.
+- Plugins are never synced, auto-updated or downloaded by CipherMesh — the
+  only way code gets into `~/.ciphermesh/plugins/` is you putting it there.
+
+## Included examples
+
+- [`examples/plugins/roll.js`](../examples/plugins/roll.js) — dice roller,
+  D&D notation (`/roll 2d20+3`), result goes to the room.
+- [`examples/plugins/poll.js`](../examples/plugins/poll.js) — quick poll
+  (`/poll question | opt A | opt B`), voted with the built-in `/react`.

package/examples/plugins/poll.js

@@ -0,0 +1,28 @@
+// CipherMesh example plugin: quick poll voted with reactions.
+// Install: cp poll.js ~/.ciphermesh/plugins/
+const NUMBERS = ['1️⃣', '2️⃣', '3️⃣', '4️⃣', '5️⃣', '6️⃣', '7️⃣', '8️⃣', '9️⃣'];
+
+export default {
+  name: 'poll',
+  description: 'Create a poll: /poll <question> | <option> | <option> [| …]',
+  commands: {
+    poll(args) {
+      const raw = args.join(' ');
+      if (!raw.includes('|')) {
+        return { info: 'Usage: /poll <question> | <option> | <option> [| …]' };
+      }
+      const [question, ...options] = raw
+        .split('|')
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (!question || options.length < 2 || options.length > NUMBERS.length) {
+        return { info: `A poll needs a question and 2-${NUMBERS.length} options.` };
+      }
+      const lines = [`📊 **${question}**`];
+      options.forEach((opt, i) => lines.push(`${NUMBERS[i]} ${opt}`));
+      lines.push(`Vote by reacting — e.g. /react ${NUMBERS[0]}`);
+      // `send` → delivered to the whole room as a normal E2EE message.
+      return { send: lines.join('\n') };
+    },
+  },
+};

package/examples/plugins/roll.js

@@ -0,0 +1,24 @@
+// CipherMesh example plugin: dice roller (D&D notation).
+// Install: cp roll.js ~/.ciphermesh/plugins/
+export default {
+  name: 'roll',
+  description: 'Roll dice: /roll [NdM+K] — e.g. /roll, /roll d20, /roll 2d20+3',
+  commands: {
+    roll(args) {
+      const spec = (args[0] || 'd6').toLowerCase();
+      const m = spec.match(/^(\d{0,2})d(\d{1,4})([+-]\d{1,4})?$/);
+      if (!m) {
+        return { info: 'Usage: /roll [NdM(+K)] — e.g. /roll 2d20+3' };
+      }
+      const count = Math.min(parseInt(m[1] || '1', 10) || 1, 20);
+      const sides = Math.max(2, parseInt(m[2], 10));
+      const modifier = parseInt(m[3] || '0', 10);
+      const rolls = Array.from({ length: count }, () => 1 + Math.floor(Math.random() * sides));
+      const total = rolls.reduce((a, b) => a + b, 0) + modifier;
+      const detail =
+        count > 1 || modifier ? ` (${rolls.join(' + ')}${modifier ? ` ${m[3]}` : ''})` : '';
+      // `send` → delivered to the whole room as a normal E2EE message.
+      return { send: `🎲 rolled ${spec}: **${total}**${detail}` };
+    },
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ciphermesh",
-  "version": "1.2.1",
+  "version": "2.1.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",
@@ -11,6 +11,7 @@
     "bin",
     "src",
     "docs",
+    "examples",
     "README.md",
     "README.pt-BR.md",
     "LICENSE"