ciphermesh 2.10.0 → 2.11.0

package/docs/PROTOCOL.md

@@ -0,0 +1,486 @@
+# CipherMesh wire protocol
+
+Version **2**. This document describes the protocol as implemented, so that an
+audit has something to check against and a second implementation has something
+to build against.
+
+Where behaviour is pinned by test vectors, that is said explicitly — the vectors
+in `test/vectors/` are the normative artefact and this document describes them,
+not the other way round. Where the relay is *forbidden* to do something, the
+reason is given, because those are the places where an innocent-looking change
+silently removes a guarantee.
+
+Reference implementation: `src/protocol/` (framing and validation),
+`src/crypto/` (everything else), `src/server/WebSocketServer.js` (relay).
+
+---
+
+## 1. Transport
+
+WebSocket. TLS is expected in deployment and self-signed by default — **no
+security property in this document depends on the TLS certificate.** End-to-end
+trust comes from TOFU pinning and SAS verification of identity keys.
+
+| Property | Value | Source |
+|---|---|---|
+| Default port | 3600 | `SERVER_PORT` |
+| Max frame | 65 536 bytes | `MAX_PAYLOAD_SIZE` |
+| Heartbeat | 30 s | `HEARTBEAT_INTERVAL_MS` |
+| Idle session timeout | 300 s | `SESSION_TIMEOUT_MS` |
+| Must JOIN within | 15 s | `JOIN_TIMEOUT_MS` |
+
+Every frame is a single JSON object, UTF-8. Binary frames are not used; all
+byte strings are base64 in JSON fields.
+
+### Rate and resource limits
+
+A conforming relay may refuse service; a conforming client must cope with being
+refused. These are the reference values.
+
+| Limit | Value | Scope |
+|---|---|---|
+| Messages per second | 60 | per connection, **all** message types |
+| Routed messages per second | 30 | per session, `encrypted_message` and `group_message` |
+| Bytes per second | 1 MiB sustained, 4 MiB burst | per connection, charged on inbound frames before parsing |
+| Connections | 500 total, 20 per IP | per relay |
+| New connections | 60 per minute per IP | escalating bans on repeat |
+
+The byte budget is charged **before** parsing: the bytes have already been
+received by then, so refusing to spend further effort on them is the only saving
+left. A connection that exhausts it is closed with code 1008.
+
+---
+
+## 2. Framing
+
+Every message carries three fields:
+
+```json
+{ "type": "<string>", "version": 2, "timestamp": 1739800000000 }
+```
+
+`version` is checked for **exact equality** and a mismatch is fatal
+(`src/protocol/validators.js`). It is not a negotiation mechanism — see §3.
+
+`timestamp` is the sender's clock in milliseconds. The relay does not trust it
+and does not correct it; it exists for the recipient.
+
+Unknown fields are ignored. This is load-bearing: it is what lets an optional
+field like `pqPublicKey`, `caps` or `room` be added without a version bump, and
+what lets an older relay pass through a message it does not fully understand.
+
+---
+
+## 3. Capability negotiation
+
+`version` can only say "same" or "refuse to talk". It cannot express *newer, but
+still willing to speak the old way*, which is what a protocol change rolled
+through a public hub needs. Capabilities carry that.
+
+1. A client lists what it can do in `JOIN` (`caps: ["sk1"]`).
+2. The relay validates the list, stores it, and hands it on **verbatim** in
+   `join_ack` (per peer) and `peer_joined`. It never acts on a capability.
+3. The relay advertises **its own** abilities in `join_ack.serverCaps`. No client
+   can promise these on the relay's behalf.
+4. A feature turns on only when **every member of the room** advertises it *and*
+   the relay does.
+
+Absent or empty means an older participant, which is a fallback, not an error.
+
+**Bounds** (the list arrives from a public hub, so it is attacker-controlled):
+at most 16 entries, each 1–24 characters matching `^[a-z0-9][a-z0-9_-]*$`. A
+malformed list gets the whole `JOIN` **rejected**, not filtered — the relay hands
+this list to other clients, and forwarding the good half of a bad list would make
+a peer look capable of something it never claimed.
+
+| Capability | Advertised by | Meaning |
+|---|---|---|
+| `sk1` | client | I can *receive* a group message (§7) |
+| `sk1` | relay | I can fan a room-addressed message out |
+
+Neither means "I send group messages". Receive and fan-out ship a release ahead
+of send, because the switch is *every member agrees*: if reading and writing
+arrived together, the switch would only ever be true in rooms where everybody
+upgraded at the same moment.
+
+**What a hostile relay gains by editing these lists:** stripping a capability
+forces the room onto the older 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.
+
+---
+
+## 4. Session lifecycle
+
+```
+client                          relay                        other clients
+  │  join(nickname, publicKey,    │                                  │
+  │       pqPublicKey?, caps?)    │                                  │
+  ├──────────────────────────────▶│                                  │
+  │                               │  peer_joined(peer)               │
+  │  join_ack(sessionId, peers,   ├─────────────────────────────────▶│
+  │           room, serverCaps?)  │                                  │
+  │◀──────────────────────────────┤                                  │
+```
+
+A session is identified by a server-assigned `sessionId` (UUID). It is **not** an
+identity: identity is the Curve25519 public key, and nicknames are neither unique
+across time nor authenticated. A client that reconnects gets a new `sessionId`
+and must be recognised by key.
+
+### `join` (client → relay)
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `nickname` | string | yes | 1–20 chars, `^[a-zA-Z0-9_-]+$`, control characters stripped, case-insensitively unique among live sessions |
+| `publicKey` | base64(32) | yes | Curve25519 identity key |
+| `pqPublicKey` | base64(1184) | no | ML-KEM-768 encapsulation key; absent = classical-only peer |
+| `caps` | string[] | no | §3; omitted when empty |
+
+### `join_ack` (relay → client)
+
+| Field | Type | Notes |
+|---|---|---|
+| `sessionId` | string | UUID for this connection |
+| `peers` | object[] | `{ sessionId, nickname, publicKey, pqPublicKey?, caps? }` |
+| `room` | string | always `general` on join |
+| `queuedCount` | number | omitted when 0 |
+| `serverCaps` | string[] | omitted when empty |
+| `roomOwner` | string | nickname, when the room has one |
+| `motd` | string | operator notice, when configured |
+
+### `peer_joined` / `peer_left` (relay → clients)
+
+`peer_joined` carries the same peer object as `join_ack.peers`. Both carry an
+optional `room`; absent means the session's only room. Old clients ignore it.
+
+### `ping` / `pong`
+
+Either direction, no payload beyond the framing.
+
+---
+
+## 5. Identity and key agreement
+
+Each client holds a long-term Curve25519 keypair. Peers learn each other's public
+key from `join_ack` / `peer_joined` — that is, **from the relay**, which is why
+TOFU pinning and out-of-band SAS verification exist: the relay is trusted to
+route, never to attest.
+
+`key_update` (client → relay) announces a new public key; the relay forwards it
+as `peer_key_updated` to every session sharing a room. The previous key is kept
+briefly on both sides so messages in flight still open.
+
+**Hybrid post-quantum.** When both sides advertised `pqPublicKey`, the ratchet
+root is mixed once at initialisation:
+
+```
+root' = BLAKE2b(root ‖ ML-KEM-768.shared ‖ "ciphermesh/pq-hybrid-v3")
+```
+
+The KEM ciphertext rides in `payload.pqCiphertext` until the peer replies. The
+mix happens exactly once, before any chain key is derived, so the two sides
+cannot desynchronise: an envelope without the expected mix simply fails its MAC.
+
+---
+
+## 6. Pairwise messages
+
+`encrypted_message` is the unicast path. On the wire it is **only**:
+
+```json
+{
+  "type": "encrypted_message",
+  "version": 2,
+  "timestamp": 1739800001000,
+  "to": "<recipient sessionId>",
+  "sealed": "base64(crypto_box_seal({ from, payload }, recipientPublicKey))"
+}
+```
+
+There is deliberately **no `from`**. The sender's identity and the whole
+already-encrypted payload are sealed to the recipient's public key with an
+anonymous box. A relay implementation must:
+
+- route on `to` alone
+- strip any `from` a client sets, so it can never be forwarded
+- never log, store or stamp the sender
+
+The inner `payload`, once unsealed, is one of:
+
+**Ratcheted** (the normal case) — Double Ratchet, per-message keys:
+
+```json
+{ "ephemeralPublicKey": "b64", "counter": 0, "previousCounter": 0,
+  "ciphertext": "b64", "nonce": "b64(24)", "pqCiphertext": "b64?" }
+```
+
+**Static** (no ratchet yet) — `crypto_box_easy` under the two identity keys:
+
+```json
+{ "ciphertext": "b64", "nonce": "b64(24)" }
+```
+
+**Deniable** — symmetric `crypto_secretbox` under a derived shared key, marked
+`"deniable": true`. No signature, so neither party can prove authorship to a
+third party.
+
+Decrypted content is JSON. `text` and `sentAt` are the common case; an `action`
+field selects everything else (typing, receipts, reactions, edits, file
+transfer, topic, sender-key distribution — §7).
+
+### Replay and ordering
+
+Static and deniable messages carry a structured nonce: 8 bytes big-endian
+timestamp, then a per-peer counter. Recipients reject a nonce outside the
+freshness window or with a non-increasing counter. Ratcheted messages are
+protected by the ratchet's own counters, which also bound how many skipped
+message keys may be cached.
+
+---
+
+## 7. Group messages (sender keys)
+
+The unicast path costs one encryption and one envelope **per recipient**. Sender
+keys make it one of each for the whole room.
+
+### The chain
+
+Each member owns a symmetric ratchet chain per room:
+
+```
+messageKey  = BLAKE2b-256(key = chainKey, message = 0x01)
+chainKey'   = BLAKE2b-256(key = chainKey, message = 0x02)
+```
+
+Note the argument order: the one-byte domain tag is the *message*, the chain key
+is the *key*. Counters start at 0 and increment by one per message. Receivers may
+cache up to 1000 skipped keys for out-of-order delivery; a larger gap is refused,
+as is a counter already consumed.
+
+**Pinned in `test/vectors/sender-key.json`.** Those values are frozen: a change
+that forces them to move is a protocol version bump, not a regeneration.
+
+### Distribution
+
+A member hands their chain to another member over the **pairwise sealed
+channel**, never on the group path — the envelope is what authenticates who sent
+it. The payload is:
+
+```json
+{ "action": "sk_dist", "room": "general",
+  "dist": { "chainKey": "b64(32)", "counter": 7,
+            "keyId": "b64(16)", "signPk": "b64(32)" },
+  "sentAt": 1739800000000 }
+```
+
+A distribution serialises the chain at its **current** counter. A member who
+receives one mid-conversation therefore cannot read anything sent before it —
+that is forward secrecy, not a defect, and it is why the backlog question in §8
+answers itself.
+
+### The message
+
+```json
+{
+  "type": "group_message",
+  "version": 2,
+  "timestamp": 1739800001000,
+  "room": "general",
+  "keyId": "b64(16)",
+  "counter": 7,
+  "ciphertext": "b64",
+  "nonce": "b64(24)",
+  "signature": "b64(64)"
+}
+```
+
+No `to`, because there is no single recipient. **No `from`**, because the relay
+must not become the one place on this wire that asserts who is speaking.
+
+`keyId` names the sender's *chain*, not the sender. Members resolve it through
+the distribution they were handed; to the relay it is a random string, and it
+already knows which socket sent the frame, so it learns nothing from it. It is
+redrawn on every rotation and dropped when a member is removed.
+
+`signature` is Ed25519 over the length-prefixed concatenation of
+`keyId`, `counter`, `ciphertext`, `nonce`, under the `signPk` from the sender's
+distribution. **It is not optional.** A sender chain is symmetric — every member
+holds the key that decrypts a given sender, and can therefore also produce
+ciphertext on it — so without a signature "Alice said this" would only ever mean
+"somebody in this room said this".
+
+A recipient must **verify before touching the chain**. `messageKeyFor()` mutates
+state, so an unauthenticated packet carrying a large counter would otherwise be a
+way to make the receiver derive and cache a thousand message keys.
+
+A member whose distribution carried no usable `signPk` is registered but
+unverifiable: nothing they send is accepted. Fail closed.
+
+### Rotation
+
+`rotate()` replaces the chain, the `keyId` and the signing key together. It must
+follow **every** membership change, and the caller must redistribute afterwards —
+nothing signals a failure to do so, and the room simply stops being able to read
+the rotator.
+
+### What the relay does
+
+Validates the shape, checks the sender **is a member of `room`**, spends the same
+per-sender budget as the unicast path, and fans the message out to every other
+member. It cannot verify the signature — it holds no signing keys — and does not
+try.
+
+Room membership is not a formality: without it 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.
+
+---
+
+## 8. Offline delivery
+
+`encrypted_message` addressed to a session that has just left is queued by
+nickname + public key, for at most 1 hour, 100 per peer and 1000 in total. On
+rejoin with the **same public key** the queue is delivered with `to` rewritten to
+the new session. A different key drops the queue: it could not be opened anyway.
+
+**`group_message` is never queued.** 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: all of the storage
+and the liability, none of the delivery.
+
+---
+
+## 9. Rooms
+
+Room names are 1–30 characters, `^[a-zA-Z0-9_-]+$`, lowercased by the relay.
+`general` always exists and can never be private.
+
+| Message | Direction | Effect |
+|---|---|---|
+| `change_room` | c → r | Leave every room, enter one |
+| `room_changed` | r → c | Confirmed, with `peers` and `private` |
+| `join_room` | c → r | Enter an **additional** room |
+| `room_joined` | r → c | Confirmed |
+| `leave_room` / `room_left` | c ↔ r | Leave one; the last is refused |
+| `list_rooms` / `room_list` | c ↔ r | `[{ name, memberCount, private }]` |
+
+`change_room` and `join_room` carry an optional `roomAuthPk` — an Ed25519
+verifier key, present only when **creating** a private room.
+
+### Private rooms, without the relay learning the password
+
+```
+client                                   relay
+  │  join_room(room)                        │
+  ├────────────────────────────────────────▶│
+  │  room_challenge(room, nonce)            │
+  │◀────────────────────────────────────────┤
+  │  room_auth(room, nonce, signature)      │
+  ├────────────────────────────────────────▶│   verify against stored roomAuthPk
+  │  room_joined(room, peers, private)      │
+  │◀────────────────────────────────────────┤
+```
+
+The password is stretched with Argon2id into a room key and an Ed25519 keypair.
+Only the **verifier public key** is ever sent, at creation. Joining proves
+knowledge by signing `(room, nonce, sessionId)` — binding to the session, so a
+signature observed from another member cannot be replayed.
+
+Challenges expire in 60 s. Five failures in 60 s on one connection stops further
+attempts.
+
+Room content gets a second encryption layer under the room key, **inside** the
+transport layer: a message in a private room is room-encrypted and then sent
+through the pairwise or group path as usual.
+
+---
+
+## 10. Moderation
+
+`kick_peer`, `mute_peer` (with `durationMs`), `ban_peer` — owner only, with an
+optional `room`. Reasons are truncated to 200 characters. The relay broadcasts
+`peer_kicked` / `peer_muted` to the room. A muted session is refused for
+`encrypted_message` and `group_message` alike.
+
+These are relay-enforced conveniences and nothing more. A relay that ignores them
+breaks no cryptographic guarantee, which is why blocking is *also* implemented
+client-side, where it cannot be overruled.
+
+---
+
+## 11. Errors
+
+```json
+{ "type": "error", "version": 2, "timestamp": 0, "code": "...", "message": "..." }
+```
+
+| Code | Meaning |
+|---|---|
+| `NICKNAME_TAKEN` | Another live session holds it |
+| `INVALID_MESSAGE` | Failed validation, or sent before `join` |
+| `PEER_NOT_FOUND` | No such session, and nothing queued |
+| `RATE_LIMITED` | Over a per-second budget |
+| `PAYLOAD_TOO_LARGE` | Frame above `MAX_PAYLOAD_SIZE` |
+| `ROOM_AUTH_FAILED` | Bad signature, expired challenge, too many attempts |
+| `ROOM_EXISTS` | Cannot create; already there |
+
+Error messages are for humans and must never quote the content that caused them.
+
+---
+
+## 12. Padding
+
+Every plaintext is padded before encryption to the smallest bucket that fits:
+
+```
+128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768
+```
+
+Format: 2 bytes big-endian length, the plaintext, then random filler. A payload
+larger than the biggest bucket is sent unpadded — file chunks are the reason —
+and a single plaintext may not exceed 65 535 bytes.
+
+This is what makes "the relay sees a bucketed size" true rather than a slogan.
+It is asserted in `test/guarantees.test.js`.
+
+---
+
+## 13. What the relay learns
+
+Stated plainly, because a specification that only lists the protections is
+misleading.
+
+**It sees:** who is connected and under what nickname and public key; which
+rooms exist and who is in them; for a unicast message, the recipient; for a group
+message, the room; the timing and bucketed size of everything; and, since a
+connection is authenticated and persistent, which socket sent any given frame.
+
+**It does not see:** any plaintext; any private-room password; the sender named
+*in* a message; the contents of a sender-key distribution.
+
+**Sealed sender is a guarantee against an honest-but-curious relay**, the same
+one Signal makes. A malicious relay can correlate the sending socket to a
+session — inherent to a persistent authenticated connection, and not something
+this protocol claims to solve. P2P mode removes the relay entirely.
+
+**Sender keys give confidentiality and per-member authenticity within a room, not
+anonymity within it.** Members can tell each other apart, which is the point.
+
+---
+
+## 14. Conformance
+
+An implementation claiming compatibility should:
+
+- reproduce `test/vectors/sender-key.json` exactly
+- send no `from` on any frame, ever
+- reject a `join` whose `caps` is malformed rather than filtering it
+- verify a group signature before advancing the chain
+- treat an absent capability as an older peer, never as an error
+- never queue a `group_message`
+
+`test/guarantees.test.js` asserts the properties above that can be observed from
+outside a single implementation.

package/docs/design/sender-keys-on-relay.md

@@ -0,0 +1,118 @@
+# Sender keys on the relay
+
+Status: **design, not implemented.** Written 2026-08-07, straight after
+measuring the problem, so the next session starts from the constraints rather
+than rediscovering them.
+
+## The problem, measured
+
+`ChatController.#broadcastPayload` loops over every peer in the room and seals
+one envelope each:
+
+```js
+for (const [peerId] of this.#peers) {
+  const peerPublicKey = this.#handshake.getPeerPublicKey(peerId);
+  ...
+  this.#sealAndSend(peerPublicKey, msg);
+}
+```
+
+One typed line in a room of N people is **N encryptions and N envelopes on the
+wire**. Cost grows linearly with room size, on the sender's CPU and on the
+sender's uplink — the two places least able to absorb it.
+
+2.10.0 made this a ceiling rather than a slope. `MAX_BYTES_PER_SECOND` bounds a
+connection at 1 MiB/s by default, and messages are padded into buckets of up to
+32 KiB. A 32 KiB bucket sent to fifty people is 1.6 MiB for one line: the sender
+is throttled, or disconnected, for saying one thing.
+
+P2P does not have this problem. `P2PChatController` already uses
+`GroupSession` from `src/crypto/SenderKey.js`, encrypts once, and distributes
+the sender key per member. The code is written and tested; it is only the relay
+path that never adopted it.
+
+## What changes
+
+1. Each member holds a **sender chain** for the room and distributes its
+   `distribution()` to every other member — sealed per member, once, rather
+   than per message.
+2. A message is encrypted **once** with the sender's chain and handed to the
+   relay with a room destination rather than a peer destination.
+3. The relay fans the single ciphertext out to the room's members. It still
+   cannot read anything, and it still never learns the sender under sealed
+   sender.
+4. On any membership change, the leaver's departure triggers `rotate()` and a
+   redistribution — exactly what `P2PChatController` does today at lines 320
+   and 487, with the comment already written there.
+
+Cost per message goes from N encryptions and N envelopes to **one and one**.
+Distribution cost is N, but paid on join and on membership change rather than
+on every line.
+
+## The hard part: two versions in one room
+
+This is a protocol change. A 2.11 client encrypting once to a group and a 2.10
+client expecting an envelope addressed to it **cannot read each other**. The hub
+is public and people upgrade whenever they upgrade, so "everyone updates at
+once" is not available.
+
+Rolling this out badly breaks live conversations for strangers. Options, in the
+order they should be considered:
+
+- **Negotiate, do not assume.** The JOIN acknowledgement already carries each
+  peer's public key; it can carry a capability list too. A sender uses group
+  encryption only when *every* member of the room advertises it, and falls back
+  to the current per-peer loop otherwise. Costs a room-wide check per send,
+  which is cheap and already computed.
+- **Both paths coexist for at least one minor.** Deleting the fan-out in the
+  same release that adds sender keys leaves no way back if the new path has a
+  bug that only shows at scale — which is exactly the kind of bug it would have.
+- **The relay needs a room-addressed message type** that does not exist yet.
+  It must not weaken sealed sender: today the relay learns the recipient and not
+  the sender, and a room-addressed envelope must not accidentally invert that.
+
+## What to be careful about
+
+- **Rotation must be wired to every departure**, not just voluntary leaves.
+  `/kick`, `/mute`, `/ban` and a dropped connection all change membership. The
+  P2P side rotates on `peer_left`; the relay side has more ways to lose a member.
+- **`SenderKey.rotate()` is a caller responsibility** — its own comment says
+  so. The distribution has to follow it or the room silently stops being able to
+  read the rotator.
+- **Private rooms add a second layer** (`encryptRoomPayload` with the
+  password-derived key). Group encryption goes *inside* that, not instead of it.
+- **The offline queue** stores envelopes addressed to a peer. A room-addressed
+  message needs an answer for someone who was offline when it was sent, and
+  "they get the sender key on rejoin but not the backlog" is a decision to make
+  deliberately rather than discover.
+
+  **Decided (2026-08-10): room-addressed messages are not queued.** The reason is
+  not policy but 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 hold ciphertext nobody can
+  open: all of the storage and the liability, none of the delivery. The unicast
+  queue survives because an envelope addressed to a peer is still openable when
+  they return with the same key. Pinned in `test/group-receive.test.js`.
+
+- **Sender keys are symmetric, so any member can forge another.** Not in the
+  original list, and it does not matter much in a P2P mesh where membership is
+  small and deliberate. It matters on a public hub. **Closed (2026-08-10)** with
+  an Ed25519 key per sender chain, distributed alongside the chain and verified
+  before the ratchet is touched. Doing it before the send path existed meant it
+  cost a field on a wire nobody was using yet.
+
+## Suggested order
+
+1. Test vectors for `SenderKey` distribution and rotation, so both sides of the
+   change are pinned before either moves.
+2. Capability advertisement in JOIN, with the fallback path left untouched.
+3. Group send/receive behind that capability, both paths live.
+4. Rotation wired to every membership change, with a test per route in.
+5. Only then, consider retiring the per-peer loop — a release later, at least.
+
+## Why it is worth it
+
+It is the one change that is simultaneously a feature, a fix and an
+improvement: it removes a scaling limit the project just made visible to itself,
+it reuses code that already exists and is already tested, and it is the
+difference between the hub holding a room of five and a room of fifty.

package/package.json

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