ciphermesh 2.9.0 → 2.11.0

package/CHANGELOG.md

@@ -3,6 +3,132 @@
 Notable changes per release. Older versions are reconstructed from the git
 history — the commit bodies and pull requests remain the fuller record.
 
+## 2.11.0
+
+Groundwork for sender keys on the relay. **Nothing sends a group message yet** —
+this release is the half that has to be in the field first, and the reason is in
+"Added" below.
+
+### Added
+
+- **Capability negotiation in `JOIN`.** `PROTOCOL_VERSION` is checked for exact
+  equality, so it can only say "same" or "refuse to talk". It cannot express
+  _newer, but still willing to speak the old way_, which is the only thing that
+  makes a protocol change survivable on a public hub where people upgrade
+  whenever they upgrade.
+
+  A client now lists what it can do in its `JOIN`; the relay validates the list,
+  stores it, and hands it on verbatim with the peer list, without ever acting on
+  it. A feature turns on only when **every member of the room** advertises it, so
+  one peer on an older build holds the whole room on the old path — which is the
+  outcome that keeps a half-upgraded room readable.
+
+  The relay advertises its own abilities separately, in `join_ack.serverCaps`. No
+  client can promise those on the relay's behalf, and some features need the
+  relay to play along, so a capable room sitting on an older hub is still not a
+  room that can switch paths.
+
+- **Receiving group messages, and the relay fan-out that carries them.** The
+  relay path seals one envelope per peer, so a line in a room of fifty costs
+  fifty encryptions and fifty envelopes — against a 1 MiB/s byte budget, a padded
+  message to fifty people throttles the sender for saying one thing. Sender keys
+  make it one of each.
+
+  Reading ships a release ahead of writing on purpose. The switch is _every
+  member agrees_: if both arrived together it would only ever be true in rooms
+  where everybody upgraded in the same moment.
+
+  A room-addressed message carries no `to`, because there is no single recipient,
+  and no `from`, because the relay must not become the one place on this wire
+  that asserts who is speaking. A packet names its _chain_ instead — an opaque
+  label members resolve through the sender key they were handed over the pairwise
+  channel, and which the relay cannot invert.
+
+- **Per-sender signatures on group messages.** A sender chain is symmetric: every
+  member holds the key that decrypts a given sender, and can therefore also
+  produce ciphertext on it. Without something asymmetric on top, "Alice said
+  this" only ever meant "somebody in this room said this" — tolerable in a small
+  P2P mesh, not on a public hub where `general` has no owner and no admission
+  control.
+
+  Each sender now holds an Ed25519 keypair for the life of its chain, rotated
+  with it. Recipients verify before touching the ratchet, so an unauthenticated
+  packet carrying a large counter cannot make them derive and cache a thousand
+  message keys.
+
+- **`docs/PROTOCOL.md`.** The wire format field by field, with the limits, the
+  failure modes, and the reason attached wherever the relay is forbidden to do
+  something. It also states what the relay _does_ learn, because a specification
+  that lists only the protections is misleading.
+
+### Changed
+
+- **Room-addressed messages are never queued for absent members**, unlike
+  unicast. Not policy — arithmetic: a sender key handed over on someone's return
+  serialises the chain at its current counter, so the backlog is unreadable to
+  them whatever the relay does with it. Queueing would store ciphertext on the
+  relay that provably nobody can open.
+
+### Internal
+
+- **Frozen test vectors for sender keys.** The previous tests round-tripped a
+  sender against a receiver built from that same sender — a mirror, not a
+  reference, which agrees with itself however the KDF is defined. Swapping the
+  two domain tags left the old suite fully green while making two clients unable
+  to read each other. The vectors pin the absolute values, and moving them is a
+  protocol version bump rather than a regeneration.
+
+- **A guarantees test that lives apart from the features it checks.** In August a
+  squash reverted the entire plugin-approval control and nothing failed, because
+  that pull request's tests were reverted in the same commit. `test/guarantees.test.js`
+  asserts what the project promises — through the surfaces a user goes through,
+  and deliberately not next to any feature — so deleting a feature now leaves its
+  proof behind, failing. Verified by mutation rather than assumed.
+
+- **Branch protection and CODEOWNERS.** `dev` and `master` now require CI, and
+  refuse force pushes and deletions.
+
+## 2.10.0
+
+### Added
+
+- **\`--check\` for operators.** The deploy guide already explained every
+  footgun here, which is the problem: a document is read once, by whoever set
+  the machine up, while the misconfiguration lasts as long as the machine does.
+  The worst of them — \`TRUST_PROXY\` left off behind a reverse proxy — is
+  invisible from outside, because everything works and the per-IP cap, the rate
+  limit and the banlist simply apply to the proxy and protect nobody.
+
+  \`ciphermesh-server --check\` validates and exits without opening a socket, so
+  it is safe against a live host, and exits non-zero on an error so a deploy
+  script can gate on it. The same findings print at every startup, because a
+  warning you have to ask for is a warning nobody sees.
+
+- **Connection-rate limiting.** The relay capped how many sockets one address
+  could hold, and how many messages a session could send, but nothing capped how
+  fast an address could _open_ connections. Connect, run the hybrid handshake,
+  disconnect, repeat: the concurrency cap never trips because the sockets are
+  never held, and every attempt costs the relay an X25519 and an ML-KEM-768
+  operation while costing the client almost nothing. That asymmetry was the one
+  real denial-of-service route into a public hub.
+
+  An address that exceeds `CONNECTION_RATE_PER_MINUTE` (60 by default, still
+  LAN-friendly) is refused for a minute, then five, then thirty. An hour of
+  behaving clears the record, so a shared NAT gateway cannot accumulate strikes
+  forever, and the refusal says how long to wait so a well-behaved client backs
+  off instead of extending its own ban.
+
+- **A byte budget per connection** (`MAX_BYTES_PER_SECOND`,
+  `MAX_BYTES_BURST`). The message limit counts messages, and messages are padded
+  into buckets of up to 32 KiB, so a session sitting at the limit is a
+  multi-megabit stream. Bytes are the resource that runs out. The burst
+  allowance keeps a legitimate file transfer from looking like an attack.
+
+  Both are continuously refilling token buckets rather than fixed windows: a
+  fixed window lets a caller spend its whole allowance at the end of one window
+  and again at the start of the next, which is twice the intended rate at
+  exactly the moment an attacker aims for.
+
 ## 2.9.0
 
 ### Added

package/README.md

@@ -19,7 +19,7 @@
 
 **[ciphermesh.de](https://ciphermesh.de)** — the website, and the public hub anyone can join.
 
-**[🇧🇷 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) · [Contributing](CONTRIBUTING.md)
+**[🇧🇷 Leia em Português](README.pt-BR.md)** · [Setup Guide](docs/SETUP.md) · [Architecture](docs/ARCHITECTURE.md) · [Wire Protocol](docs/PROTOCOL.md) · [Security Policy](SECURITY.md) · [Hub Terms](TERMS.md) · [Contributing](CONTRIBUTING.md)
 
 <img src="docs/demo.svg" alt="CipherMesh terminal demo" width="720">
 
@@ -204,10 +204,11 @@ software was built for.
 | ----------------------------- | ----------------------------------------------------------------- |
 | `/help`                       | All commands                                                      |
 | `/tips`                       | Show a rotating security/UX tip                                   |
+| `/plugins`                    | List loaded plugins and the commands they add                     |
 | `/users`                      | Who's online (with away/status)                                   |
 | `/msg <nick> <text>`          | Private message (DM)                                              |
 | `/reply <text>`               | Reply quoting the last received message                           |
-| `/me <action>`                | Third-person action — _«felipe is compiling»_                     |
+| `/me <action>`                | Third-person action — _«ana is compiling»_                        |
 | `/watch [add\|remove\|clear]` | Alert on a keyword in **any** room, like a mention                |
 | `/invite [host:port]`         | Generate a `ciphermesh://` invite + QR code                       |
 | `/nick <new>`                 | Change nickname (before joining — recovers from "nickname taken") |
@@ -294,6 +295,7 @@ A green **✓** next to a name marks a SAS-verified peer; a red **✗** flags a
 | Command                                 | Description                                                                                                                                                                            |
 | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `/away [reason]` / `/back`              | Mark yourself away — while away, unreads are counted (`[away · N new]`) and `/back` shows a summary                                                                                    |
+| `/autoaway <minutes\|off>`              | Go away by itself after that long without typing (1–240 minutes)                                                                                                                       |
 | `/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 — the emoji lands **on the message**, with a count when several people react                                                                                 |
@@ -325,7 +327,7 @@ All keys are optional (unknown keys are ignored):
 
 ```json
 {
-  "nickname": "felipe",
+  "nickname": "ana",
   "server": "wss://100.x.y.z:3600",
   "sound": false,
   "notify": true,

package/README.pt-BR.md

@@ -209,7 +209,7 @@ aquela para a qual este software foi feito.
 | `/users`                      | Quem está online (com away/status)                                      |
 | `/msg <nick> <texto>`         | Mensagem privada (DM)                                                   |
 | `/reply <texto>`              | Responde citando a última mensagem recebida                             |
-| `/me <ação>`                  | Ação em terceira pessoa — _«felipe está compilando»_                    |
+| `/me <ação>`                  | Ação em terceira pessoa — _«ana está compilando»_                    |
 | `/watch [add\|remove\|clear]` | Alerta quando uma palavra aparece em **qualquer** sala, como uma menção |
 | `/invite [host:porta]`        | Gera convite `ciphermesh://` + QR code                                  |
 | `/nick <novo>`                | Troca de apelido (antes de entrar — recupera de "apelido em uso")       |
@@ -328,7 +328,7 @@ mão. Todas as chaves são opcionais (chaves desconhecidas são ignoradas):
 
 ```json
 {
-  "nickname": "felipe",
+  "nickname": "ana",
   "server": "wss://100.x.y.z:3600",
   "sound": false,
   "notify": true,

package/docs/ARCHITECTURE.md

@@ -439,15 +439,21 @@ Defines the protocol's message types. All messages have:
 }
 ```
 
+> The normative description of the wire format lives in
+> **[docs/PROTOCOL.md](PROTOCOL.md)** — field by field, with the limits, the
+> failure modes and what the relay is forbidden to do. This chapter is the tour;
+> that document is the specification.
+
 Types:
 | Type | Direction | Description |
 |------|---------|-----------|
-| `join` | Client -> Server | The client wants to join (nickname + publicKey) |
+| `join` | Client -> Server | The client wants to join (nickname + publicKey + optional `caps`, see 6.10) |
 | `join_ack` | Server -> Client | The server confirms the join (sessionId + peer list) |
 | `peer_joined` | Server -> Clients | A new peer joined (nickname + publicKey) |
 | `peer_left` | Server -> Clients | A peer left |
 | `key_exchange` | Client -> Server -> Client | Public key exchange between peers |
 | `encrypted_message` | Client -> Server -> Client | Encrypted message |
+| `group_message` | Client -> Server -> Room | One ciphertext fanned out to a room's members (sender keys, see 6.11). No `to`, no `from` |
 | `change_room` | Client -> Server | Legacy single-room switch: leave every room, enter one (+ optional `roomAuthPk` when creating a private room) |
 | `room_changed` | Server -> Client | Room switch confirmed (+ `private` flag) |
 | `join_room` | Client -> Server | Multi-room: join an ADDITIONAL room, keeping current ones (same `roomAuthPk` option) |
@@ -514,10 +520,15 @@ export const FILE_CHUNK_SIZE = 49152;            // 48KB
   "version": 1,
   "timestamp": 1739800000000,
   "nickname": "Alice",
-  "publicKey": "base64(32 bytes da chave publica Curve25519)"
+  "publicKey": "base64(32 bytes da chave publica Curve25519)",
+  "caps": ["sk1"]
 }
 ```
 
+`caps` is optional (see 6.10). It is omitted entirely when the client has
+nothing to advertise, so the message is byte-identical to a pre-capability
+client's.
+
 ### 5.2 Join ACK (server -> client)
 
 ```json
@@ -530,12 +541,17 @@ export const FILE_CHUNK_SIZE = 49152;            // 48KB
     {
       "sessionId": "660e8400-e29b-41d4-a716-446655440001",
       "nickname": "Bob",
-      "publicKey": "base64(chave publica do Bob)"
+      "publicKey": "base64(chave publica do Bob)",
+      "caps": ["sk1"]
     }
-  ]
+  ],
+  "serverCaps": ["sk1"]
 }
 ```
 
+`caps` is what each peer can do; `serverCaps` is what the relay itself can do.
+Both are optional and both matter — see 6.11.
+
 ### 5.3 Encrypted Message (client -> server -> client)
 
 ```json
@@ -550,6 +566,63 @@ export const FILE_CHUNK_SIZE = 49152;            // 48KB
 
 **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.3b Group Message (client -> server -> room)
+
+```json
+{
+  "type": "group_message",
+  "version": 2,
+  "timestamp": 1739800001000,
+  "room": "general",
+  "keyId": "base64(16 random bytes labelling the sender's chain)",
+  "counter": 7,
+  "ciphertext": "base64(...)",
+  "nonce": "base64(24 bytes)",
+  "signature": "base64(64 bytes, Ed25519 over keyId|counter|ciphertext|nonce)"
+}
+```
+
+One ciphertext for the whole room, fanned out by the relay to every member
+except the sender. Note what is **not** here: no `to`, because there is no single
+recipient, and no `from`, because the relay must not be the thing that says who
+is speaking — on this wire, identity only ever travels sealed.
+
+Recipients pick the right sender chain with `keyId`, which they learned from the
+`sk_dist` payload that member sent them over the pairwise channel. That envelope
+authenticates the sender; the fan-out does not, and is not asked to. To the relay
+`keyId` is a random string, and it already knows which socket sent the frame, so
+it learns nothing from it.
+
+**Why the signature is not optional.** A sender chain is symmetric: every member
+holds the key that decrypts a given sender, which means every member can also
+*produce* ciphertext on it. Without something asymmetric on top, "Alice said
+this" only ever means "somebody in this room said this" — and `general` on a
+public hub has no owner and no admission control, so that is a very wide set of
+somebodies. Each sender therefore also holds an Ed25519 keypair for the life of
+its chain; the public half travels in the distribution, over the pairwise channel
+that already authenticates who sent it. Recipients verify **before** touching the
+ratchet, so an unauthenticated packet carrying a large counter cannot make them
+derive and cache a thousand message keys.
+
+The relay checks only that the sender is a member of `room` — without that, one
+connection could inject into every room on the hub at once, which the unicast
+path cannot do because it needs a `sessionId` it could only have been told. It
+cannot verify the signature and does not try: it holds no signing keys, and that
+is the recipient's job.
+
+**Not queued for absent members**, unlike the unicast path. A member who was away
+could not read it anyway — a sender key handed over on their return serialises
+the chain at its *current* counter, so anything sent while they were gone stays
+shut. Queueing would store ciphertext on the relay that provably nobody can open.
+The unicast queue survives because an envelope addressed to a peer *is* still
+openable when they come back with the same key; that difference is what decides
+it.
+
+**Not yet sent by anything.** As of this release clients can *receive* a group
+message; `#broadcastPayload` still seals one envelope per peer. Receive and
+fan-out ship first so that when the send path lands, the rooms it negotiates
+with can already read it.
+
 ### 5.4 Decrypted content (never travels in cleartext)
 
 After decrypting `payload.ciphertext`, the result is:
@@ -814,6 +887,56 @@ wrapper adds no metadata leak.
 
 ---
 
+### 6.11 Capability Negotiation
+
+`PROTOCOL_VERSION` is checked for exact equality, so it can only say "same" or
+"refuse to talk". It cannot express a client that is newer but still willing to
+speak the old way — which is what rolling a protocol change through a public hub
+needs, because people upgrade whenever they upgrade.
+
+Capabilities fill that gap:
+
+1. A client lists what it can do in its `JOIN` (`caps: ["sk1"]`).
+2. The relay validates the list, stores it, and hands it on **verbatim** with
+   the peer list (`join_ack`) and with `peer_joined`. The relay never acts on a
+   capability itself.
+3. The relay advertises **its own** abilities separately, in `join_ack.serverCaps`.
+   No client can promise these on the relay's behalf, and some features need the
+   relay to play along — the group fan-out is its job, not a peer's. A capable
+   room sitting on an older hub is still not a room that can switch paths.
+4. A feature turns on only when **every** member of the room advertises it
+   (`roomSupports()` in `src/protocol/capabilities.js`) **and** the relay does
+   (`relaySupportsCapability()`). One peer on an older build, or one older hub,
+   holds the whole room on the old path.
+
+**Compatibility:** the field is optional and omitted when empty, so a
+pre-capability client's `JOIN` is unchanged, and an older relay that does not
+know the field simply drops it — peers then see no capabilities and fall back,
+which is the safe direction.
+
+**Bounds:** the list arrives from a public hub, so it is capped at 16 entries of
+up to 24 lowercase characters each. A malformed list gets the whole `JOIN`
+rejected rather than filtered: the relay hands this to other clients, and
+forwarding the good half of a bad list would make a peer look capable of
+something it never claimed.
+
+**What a hostile relay can do with it:** stripping capabilities forces the room
+back onto the per-peer path, which is the status quo and reveals nothing new.
+Adding one a peer never claimed makes senders encrypt in a form that peer cannot
+read — denial of service, immediately visible, never a way to read plaintext.
+The all-members rule is what keeps the damage on that side of the line.
+
+| Capability | Advertised by | Meaning |
+|---|---|---|
+| `sk1` | client | I can **receive** a group message: I accept a sender key over the pairwise channel and can decrypt what that chain produces. |
+| `sk1` | relay | I can fan a room-addressed `group_message` out to a room's members. |
+
+Neither means "I send group messages" — nothing does yet. Receive and fan-out
+are deliberately a release ahead of send, because the switch is *every member
+agrees*: if the ability to read arrived with the ability to write, the switch
+would only ever be true in rooms where everybody upgraded at the same moment,
+which on a public hub is close to never. See `docs/design/sender-keys-on-relay.md`.
+
 ## 7. Handshake Protocol
 
 ### 7.1 Full Diagram

package/docs/PLUGINS.md

@@ -1,7 +1,12 @@
 # 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.
+CipherMesh loads user plugins from `~/.ciphermesh/plugins/*.js` and routes
+unknown slash-commands to them. Plugins work in both relay and P2P mode.
+
+**Nothing there runs until you say so.** A file in that directory is found, not
+loaded. Run `/plugins` to see what is waiting and `/plugins allow <file>` to
+approve it — the approval is remembered in `~/.ciphermesh/config.json` under
+`pluginsAllowed`, so you are asked once per file.
 
 ## Quick start
 
@@ -10,8 +15,15 @@ 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.
+Then in the client:
+
+```
+/plugins              → shows roll.js and poll.js waiting
+/plugins allow roll   → approved, loaded, and remembered
+/plugins allow poll
+```
+
+Now `/roll 2d20+3` and `/poll Pizza tonight? | yes | obviously` work.
 
 ## Plugin format
 
@@ -19,8 +31,8 @@ A plugin is an ES module whose **default export** is:
 
 ```js
 export default {
-  name: 'roll',                       // required, unique
-  description: 'Roll dice',           // optional, shown by /plugins
+  name: 'roll', // required, unique
+  description: 'Roll dice', // optional, shown by /plugins
   commands: {
     // key = command name (with or without the leading slash)
     roll(args) {
@@ -31,16 +43,18 @@ export default {
 };
 ```
 
-Files that fail to import, or lack `name`/`commands`, are skipped silently.
+A file that fails to import, or lacks `name`/`commands`, is skipped — but if you
+approved it, `/plugins` says so. A plugin you asked for and did not get should
+not disappear without a word.
 
 ## 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*. |
+| 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.
 
@@ -54,13 +68,38 @@ 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.
+your privileges and full access to your keys in memory. There is no sandbox,
+and approving one does not create one.
 
 - 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.
 
+### What approval actually buys
+
+Before, any `.js` file appearing in that directory ran at the next start. The
+warning above protected only the people who had already read it, and anything
+able to write one file into a known path had code execution.
+
+Now the file is listed and left alone until you approve it. That is the whole
+guarantee, and it is worth being precise about its edges:
+
+- **It is a consent step, not a sandbox.** An approved plugin can do everything
+  the client can do. Approve for the same reasons you would run a script.
+- **Approval is per _file name_, not per plugin name.** That is forced, not
+  chosen: a plugin's own `name` lives inside the module, and reading it means
+  importing the module, and importing it is already running it. The check has
+  to work from the directory listing alone.
+- **Replacing an approved file is not a new decision.** `roll.js` stays
+  approved even if its contents change completely. If you did not put the new
+  contents there, you have a bigger problem than plugins — but do not read the
+  approval as a promise about what the file contains.
+
+There is no capability system, deliberately. Declaring what a plugin may do
+without being able to enforce it would make the risk look bounded when it is
+not, which is worse than the plain warning above.
+
 ## Included examples
 
 - [`examples/plugins/roll.js`](../examples/plugins/roll.js) — dice roller,