ciphermesh 2.10.0 → 2.12.0

package/CHANGELOG.md

@@ -3,6 +3,148 @@
 Notable changes per release. Older versions are reconstructed from the git
 history — the commit bodies and pull requests remain the fuller record.
 
+## 2.12.0
+
+Sender keys now send. 2.11.0 shipped the half that reads a group message; this
+is the half that writes one, and a line in a room of fifty costs one encryption
+instead of fifty.
+
+The switch is unchanged and still strict — every member of the room and the hub
+itself must say they can handle it. On a public hub the per-peer path remains
+the common case, and it is untouched.
+
+### Added
+
+- **Group sending on the relay.** 2.11.0 shipped the half that reads one; this
+  is the half that writes one. A line in a room of fifty cost fifty encryptions
+  and fifty envelopes — against the 1 MiB/s byte budget, a padded message to
+  fifty people throttled the sender for saying one thing. It now costs one of
+  each.
+
+  The switch is still the strict one: every member of the room advertises
+  `sk1`, **and** the hub does, **and** the message is not deniable. Any one
+  false and the per-peer path runs exactly as before, which on a public hub is
+  the common case rather than the exception. Nothing was removed.
+
+  Deniable messages stay pairwise permanently. Deniability comes from a key both
+  sides could have derived; a group packet is signed by one sender, which is the
+  opposite claim.
+
+- **Sender keys rotate on every membership change.** Leaving, switching rooms,
+  disconnecting, being kicked, being banned. A chain ratchets forward, so the
+  copy a member holds opens every message after it: removing someone stopped the
+  relay delivering to them and did not stop them reading. Rotation is what
+  closes that, and `test/guarantees.test.js` now asserts it from outside the
+  code that implements it.
+
+### Fixed
+
+- **A kick or a ban is announced as a departure, not only as a notification.**
+  Both moved the target out of the room and told the room `peer_kicked`, which
+  carries a nickname — and a nickname is not something a client can unwind a
+  member by, since `/nick` reassigns them. Every remaining client kept the
+  removed peer in its roster indefinitely. They now emit `peer_left` like every
+  other way out of a room, which is also what makes rotation reachable for the
+  two cases where it matters most.
+
+- **Peer capabilities survive a room switch.** `room_changed` and `room_joined`
+  carried them and the client dropped them, so after switching rooms every peer
+  looked incapable and the room silently never turned the group path on. No
+  error, no failure — just an optimisation that quietly never applied.
+
+- **Sender-key memory is released, not merely zeroed.** `sodium_malloc` pages are
+  `mlock`'d, and an operating system caps how much a process may lock at once.
+  Zeroing a spent key left its pages locked until the garbage collector happened
+  to run the buffer's finaliser, so a long session derived keys faster than it
+  released them. The ceiling is generous on macOS and small on Linux, where a
+  busy client would eventually have hit an allocation failure that aborts the
+  process rather than returning an error.
+
+## 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

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">
 

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