ciphermesh 2.12.0 → 2.14.0

package/docs/PROTOCOL.md

@@ -66,7 +66,8 @@ Every message carries three fields:
 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
+field like `pqPublicKey`, `caps`, `room` or `identityKey` be added without a
+version bump, and
 what lets an older relay pass through a message it does not fully understand.
 
 ---
@@ -83,7 +84,9 @@ through a public hub needs. Capabilities carry that.
 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.
+   the relay does — for features that need the relay to play along. A capability
+   whose feature rides a channel the relay already carries has no relay half and
+   is decided per peer; `dl1` is the first of those.
 
 Absent or empty means an older participant, which is a fallback, not an error.
 
@@ -97,12 +100,17 @@ a peer look capable of something it never claimed.
 |---|---|---|
 | `sk1` | client | I can *receive* a group message (§7) |
 | `sk1` | relay | I can fan a room-addressed message out |
+| `dl1` | client | I can read a signed device list handed to me over the pairwise channel (§7) |
 
 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.
 
+`dl1` has no relay half. A device list travels on the pairwise sealed channel
+the relay already carries, so there is nothing for the relay to agree to and
+nothing it can withhold beyond the frame itself.
+
 **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
@@ -116,7 +124,8 @@ plaintext. The all-members rule is what keeps the damage on that side.
 ```
 client                          relay                        other clients
   │  join(nickname, publicKey,    │                                  │
-  │       pqPublicKey?, caps?)    │                                  │
+  │       pqPublicKey?, caps?,    │                                  │
+  │       identityKey?)           │                                  │
   ├──────────────────────────────▶│                                  │
   │                               │  peer_joined(peer)               │
   │  join_ack(sessionId, peers,   ├─────────────────────────────────▶│
@@ -133,23 +142,47 @@ and must be recognised by key.
 
 | Field | Type | Required | Notes |
 |---|---|---|---|
-| `nickname` | string | yes | 1–20 chars, `^[a-zA-Z0-9_-]+$`, control characters stripped, case-insensitively unique among live sessions |
+| `nickname` | string | yes | 1–20 chars, `^[a-zA-Z0-9_-]+$`, control characters stripped, case-insensitively unique among live sessions — **except for another device of the same identity**, see below |
 | `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 |
+| `identityKey` | base64(32) | no | Ed25519 signing key for multi-device; absent = a client from before it existed |
+| `deviceList` | object | no | The signed list from §7, sent to claim a nickname another of your own devices already holds |
 
 ### `join_ack` (relay → client)
 
 | Field | Type | Notes |
 |---|---|---|
 | `sessionId` | string | UUID for this connection |
-| `peers` | object[] | `{ sessionId, nickname, publicKey, pqPublicKey?, caps? }` |
+| `peers` | object[] | `{ sessionId, nickname, publicKey, pqPublicKey?, caps?, identityKey? }` |
 | `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 |
 
+**`identityKey` is relayed verbatim and the relay cannot verify it.** It forwards
+whatever the JOIN carried, so a hostile relay can substitute one: presence in a
+`join_ack` is not evidence of anything. What makes an identity key trustworthy is
+a device list signed by it and checked by the client — never the relay repeating
+it. It is also not what a ban keys on; that stays the Curve25519 `publicKey`.
+
+**One nickname may be held by several devices of one identity.** A second
+session is admitted under a name already in use only if its JOIN carries a
+`deviceList` that
+
+1. is signed by the identity the existing sessions under that name are using,
+2. names *this* JOIN's own `publicKey`, and
+3. would not take the name past the eight-device limit.
+
+No challenge is issued and none is needed. Replaying a list somebody else
+published buys a seat in a room under a name whose messages you cannot read,
+because you do not hold the box secret the list names — and peers do their own
+checking, so they learn nothing from the relay having allowed it. The relay is
+doing admission control on a nickname here, not attesting to an identity.
+
+The name is released when the **last** of its sessions leaves, not the first.
+
 ### `peer_joined` / `peer_left` (relay → clients)
 
 `peer_joined` carries the same peer object as `join_ack.peers`. Both carry an
@@ -179,6 +212,36 @@ route, never to attest.
 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.
 
+**What a SAS compares is moving.** Historically the code is BLAKE2b over the two
+Curve25519 keys — the device keys — which means it is invalidated by a key
+rotation and says nothing about a person with more than one device. Once both
+sides advertise `dl1` **and** each holds the other's device list, the code is
+computed over the two Ed25519 identity keys instead, under a separate domain
+tag. The switch is symmetric: both sides reach that state together, so a pair
+never sees two different codes. Against a peer without `dl1` both sides compute
+the device code, exactly as before. `/verify` names which of the two it is
+showing.
+
+**Existing verifications are carried across, never re-asked.** A record verified
+against a device key gains its identity when a signed device list arrives that
+**names that same device key**, over the pairwise channel only the holder of
+that key could have written to. The identity is then vouched for by precisely
+what the user compared digits over. A list that does not name the key it arrived
+under binds nothing — it is not an attack, a rotation can race a distribution,
+but it proves nothing. A *second, different* identity for a record that already
+has one is never accepted silently; on a verified record it is reported in the
+same voice as a verified-key mismatch, and nothing is changed.
+
+**Another device is not a key that changed.** A peer's second device arrives
+under the same nickname with a box key the record has never seen — which is
+exactly the shape of a man-in-the-middle, and is reported as one. The alarm is
+never suppressed in advance: claiming the right `identityKey` in a JOIN proves
+nothing, since the relay forwards that field unchecked. It is *answered*, once a
+device list signed by the identity bound to that record names the key. From then
+on the key is recognised silently, and the record keeps the verified key as its
+primary — a device is added beside it, never over it. A list may only add
+devices to the record its own identity is bound to.
+
 **Hybrid post-quantum.** When both sides advertised `pqPublicKey`, the ratchet
 root is mixed once at initialisation:
 
@@ -398,6 +461,98 @@ 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.
 
+### Device lists
+
+A second thing travels the pairwise channel, gated on `dl1` and read by nothing
+yet: a **device list**, the set of box keys that belong to one identity, signed
+by the Ed25519 `identityKey` from §4. Multi-device is designed in
+`docs/design/multi-device.md`; this is the plumbing landing ahead of it. Today
+every list names exactly one device, because nothing can add a second.
+
+```json
+{ "action": "device_list",
+  "list": {
+    "identityPk": "b64(32)",
+    "counter": 1,
+    "devices": [ { "deviceId": "hex(32)", "boxPk": "b64(32)",
+                   "label": "", "createdAt": 1739800000000 } ],
+    "signature": "b64(64)"
+  },
+  "sentAt": 1739800000000 }
+```
+
+The signature covers a domain tag, the identity key, the counter, **the number
+of devices**, and every field of each one, each length-prefixed by its byte
+count. There is no ML-KEM key in a descriptor: a list is a set of claims about
+identity, a KEM key is transport material already advertised per session in
+JOIN, and carrying it cost 1584 bytes of base64 per device. The count is in there so a device cannot be dropped off the end
+unnoticed; byte prefixes are there so a multi-byte label cannot shift a field
+boundary.
+
+**`counter` only ever goes up, and the reader enforces it.** A list at the same
+counter is not newer and is refused, so an edit cannot slip in sideways; a lower
+one is a replay. Without this a relay that kept an old copy could play it back,
+and once revocation exists that is how a removed device would be put back. The
+sender's counter is persisted and moves whenever its descriptor does — a
+box-key rotation changes `boxPk`, so it changes the list.
+
+**What authenticates a list is the channel, not the seal.** `crypto_box_seal` is
+anonymous: anyone can seal a blob to you claiming any sender. The payload
+underneath is `crypto_box` to your key from the peer's, so it only opens if the
+sender holds that peer's box secret. That is what makes the list theirs. The
+`identityKey` the relay repeated in `join_ack` is a *hint* — it decides whether
+handing a list over is worth the round trip, and nothing more. A relay that
+tampers with it can stop the exchange happening; it cannot put words in a peer's
+mouth, because it cannot produce the payload.
+
+**Answered, not announced**, for the same reason as *Distribution* above: a
+newcomer learns the room before the room learns of the newcomer, so a client
+that announced itself on arrival would be talking to peers holding no key for
+it. Peers who already know you speak first; you answer, and you mark them as
+holding your list **before** sending, because on a synchronous transport their
+answer can arrive before the send call returns.
+
+**Revocation is a shorter list with a higher counter**, and the list is only
+half of it. A removed device still holds every member's sender chain, and a
+chain ratchets forward — dropping it from the list stops the relay delivering to
+it and does not stop it reading. So every reader that sees devices disappear
+from a list **rotates its own chain for the room**, exactly as it does when a
+member leaves.
+
+On the receiving side a list is a *replacement*, not an addition: the keys it
+names are the keys that are that person, and one that is no longer named stops
+being honoured — including the key the trust record was originally built on. A
+revoked primary that stayed trusted would make revocation decorative.
+
+Two limits, stated rather than discovered. A revoked device that is already
+connected keeps its session until it disconnects; it is refused on its next
+JOIN, because the list no longer names its key. And it keeps whatever it
+received before the rotation, which is what forward secrecy means and not a
+defect.
+
+**Provisioning happens off the wire.** A second device is added by the user
+carrying two short strings between the two machines, not by anything the relay
+sees:
+
+```
+ciphermesh-device://request/<base64url>   { deviceId, boxPk, label }
+ciphermesh-device://grant/<base64url>     { identityPk, list }
+```
+
+The identity secret never moves. A secondary holds only the public half and the
+list it was granted, so it can prove which identity it belongs to and can
+publish that list, but it cannot sign a new one — adding and revoking stay with
+the device that holds the secret. Neither string is confidential; a grant is
+caught if substituted, because it only applies when the list names the exact
+device that asked, by both id and key.
+
+A secondary therefore does not rotate its box key: it could not re-sign the list
+that names it, and the result would be a device nothing vouches for.
+
+**The label is empty**, and stays empty until there is a second device to tell
+apart. A hostname is the obvious filler and exactly the kind of thing that does
+not go on this wire.
+
 ---
 
 ## 8. Offline delivery

package/docs/SETUP.md

@@ -293,6 +293,24 @@ Run `/help` in the chat for the **full list**. The main ones:
   - Or: `netsh advfirewall firewall add rule name="CipherMesh" dir=in action=allow protocol=TCP localport=3600`
 - Test whether the port responds: `curl ws://IP:3600` or open `http://IP:3600` in the browser (it will error out, but if the port connects it is open)
 
+### Shift+Enter does not insert a newline
+
+A terminal cannot tell Shift+Enter from Enter unless the application asks it to,
+so on startup CipherMesh requests the two protocols that make the difference
+visible — the kitty keyboard protocol and xterm's `modifyOtherKeys`. Terminals
+that implement neither simply ignore the request.
+
+On those, use **Alt+Enter** or **Ctrl+J**, which work everywhere.
+
+If a terminal reacts badly to the request, `CIPHERMESH_LEGACY_KEYS=1` turns the
+negotiation off and hands the terminal to blessed untouched:
+
+```bash
+CIPHERMESH_LEGACY_KEYS=1 ciphermesh
+```
+
+Alt+Enter and Ctrl+J keep working in that mode; only Shift+Enter is lost.
+
 ### "npm install" fails on sodium-native
 
 `sodium-native` needs to compile C code. Requirements:

package/docs/commands.json

@@ -1,8 +1,8 @@
 {
   "$comment": "Generated by scripts/generate-commands.mjs — do not edit. Which commands exist comes from the case labels in the two controllers; prose comes from README.md and the Ctrl+K palette.",
   "counts": {
-    "total": 67,
-    "relay": 67,
+    "total": 68,
+    "relay": 68,
     "p2p": 64
   },
   "groups": [
@@ -196,7 +196,7 @@
         {
           "name": "/room",
           "args": "",
-          "summary": "Current room + your buffer list",
+          "summary": "Current room, how it is sending it, and your buffer list",
           "modes": [
             "relay",
             "p2p"
@@ -289,6 +289,14 @@
             "p2p"
           ]
         },
+        {
+          "name": "/device",
+          "args": "[list\\|request\\|add\\|accept\\|remove]",
+          "summary": "Your devices under one identity. The identity key never leaves the device that holds it, so a second device is granted a signed place on the list rather than a copy of your identity. Removing one rotates the room, so nothing said afterwards reaches it",
+          "modes": [
+            "relay"
+          ]
+        },
         {
           "name": "/ephemeral",
           "args": "<30s\\|5m\\|1h\\|off>",
@@ -301,7 +309,7 @@
         {
           "name": "/fingerprint",
           "args": "[nick]",
-          "summary": "Key fingerprint + a deterministic **randomart** picture of the key",
+          "summary": "Key fingerprint, the identity fingerprint when there is one, and a deterministic **randomart** picture of the key",
           "modes": [
             "relay",
             "p2p"
@@ -364,7 +372,7 @@
         {
           "name": "/verify",
           "args": "<nick>",
-          "summary": "SAS code (~40-bit) + QR + key randomart for out-of-band verification",
+          "summary": "SAS code (~40-bit) + QR + key randomart for out-of-band verification; says whether the code is over identity keys or device keys",
           "modes": [
             "relay",
             "p2p"
@@ -574,7 +582,7 @@
         {
           "name": "/notify",
           "args": "",
-          "summary": "Sound / desktop notifications",
+          "summary": "Desktop notifications — rate-limited, and muted for the session (with a line saying why) if the OS refuses them",
           "modes": [
             "relay",
             "p2p"
@@ -610,7 +618,7 @@
         {
           "name": "/sound",
           "args": "",
-          "summary": "Sound / desktop notifications",
+          "summary": "Sound alerts on incoming messages",
           "modes": [
             "relay",
             "p2p"

package/docs/design/multi-device.md

@@ -0,0 +1,290 @@
+# Multi-device
+
+Status: **shipped**, steps 1 to 7; step 8 answered and declined. Written
+2026-08-23 from the code as it stood, and implemented across #493, #494, #496,
+#497, #498, #499, #500, #501 and #502 the same day. Item 4 of #481.
+
+The document is kept as written rather than rewritten in the past tense, the way
+`sender-keys-on-relay.md` is: the decisions are recorded in place, under the
+hard parts they answer.
+
+This follows the shape of [sender-keys-on-relay.md](sender-keys-on-relay.md),
+which was written the same way and turned out to be worth it. Where that
+document got something wrong — step 5 — the mistake is left visible.
+
+## The problem, measured
+
+Multi-device is not a missing feature. It is a **reachable configuration that
+produces the wrong thing**, and the client has a command that walks people into
+it.
+
+`/backup` writes `{ identity: keyManager.serialize(), trust: ... }` encrypted
+with the session passphrase — and `serialize()` includes the secret key. On
+another machine, the startup prompt _"Restore identity from a backup? (path or
+Enter)"_ reads it straight back in. Both machines now hold the same X25519
+secret key. What follows is what the code actually does, not what it ought to:
+
+- **They cannot both use the name.** `WebSocketServer` rejects a JOIN whose
+  nickname is taken (`isNicknameTaken`, line 296). The second device gets
+  `NICKNAME_TAKEN`. One person is in the room as two people under two names.
+- **Nothing notices they are the same identity.** `addSession` has no
+  uniqueness check on `publicKey`, so the relay is perfectly happy to hold two
+  sessions with one key, and treats them as unrelated peers. So does every
+  other client.
+- **Each message reaches exactly one of them.** `MessageRouter.route` delivers
+  to `msg.to`, a session id. Both devices _could_ open the envelope — same
+  secret key — but only one is sent it. Which one depends on which session the
+  sender's peer map happened to address. Read a conversation on your laptop,
+  and half of it is on your phone.
+- **Verification teaches the wrong lesson.** `TrustStore` is
+  `Map<lowerNickname, record>`, so a peer verifies each device separately, as
+  two different people. And `computeSAS` hashes the two X25519 keys, so both
+  comparisons produce **the same digits** — the peer is asked to verify one
+  fingerprint under two names and told that is normal.
+- **Losing one device loses the identity.** One secret key, copied. There is no
+  way to revoke a device: `KeyManager.rotate()` replaces the identity
+  everywhere at once, for everybody, and the peers see a key change they cannot
+  distinguish from an impersonation attempt.
+- **One thing is accidentally right.** Bans key on `session.publicKey`
+  (`WebSocketServer` lines 480, 573, 754, 1039), so banning one device does
+  correctly ban them all.
+
+So the honest summary is not "we do not have multi-device". It is: **the
+project ships a way to get two devices, and the result is a doubled presence, a
+halved conversation, a fingerprint that means less than the user is told, and a
+key that cannot be revoked.** Everything below is about replacing that with
+something defensible.
+
+## What multi-device has to mean here
+
+The shape is not novel and there is no reason to invent one. **Per-device keys
+under one identity:**
+
+- A long-term **identity key** (Ed25519) that signs and is never used to
+  encrypt a message.
+- A **device key** (X25519, plus the ML-KEM half) per device, exactly what
+  `KeyManager` already produces — but no longer the identity.
+- A **device list**: the set of device keys currently valid for an identity,
+  signed by the identity key, with a monotonic counter so an old list cannot be
+  replayed over a newer one.
+- The thing users verify becomes the **identity key**, not a device key.
+
+That last point is the one that makes the rest usable. If verification stays on
+the device key, then adding a device invalidates every verification you have,
+and a person with three devices is three SAS comparisons — nine, pairwise, in a
+room of two such people. Moving verification up one level means you verify a
+person once and their devices inherit it, which is the only version anyone will
+actually do.
+
+## What changes
+
+1. `KeyManager` grows an **identity keypair** alongside the device keypair, and
+   `fingerprint` is computed from the identity key.
+2. A device publishes a **descriptor** — its X25519 key, its ML-KEM key, a
+   label, a creation time — signed by the identity key.
+3. A **device list** (identity key + descriptors + counter, signed) is
+   distributed to peers over the pairwise channel, the same way a sender key is
+   and for the same reason: it is authenticated by opening the envelope it
+   arrived in, never asserted by the relay.
+4. A pairwise send goes to **every live device** of the recipient. A group send
+   still goes out once; only distribution multiplies.
+5. Your own other devices are recipients too, which is what makes a message you
+   sent from your phone appear on your laptop.
+6. **Revocation** is a new signed list with the device removed and the counter
+   raised. Peers drop the key on receipt.
+
+## The hard parts
+
+### The fingerprint changes meaning
+
+Every existing verified record was verified against a device key. Moving the
+fingerprint to the identity key makes all of them stale at once, and a stale
+verification is exactly what `TrustResult.VERIFIED_MISMATCH` is built to scream
+about — so a careless rollout tells every user, simultaneously, that everyone
+they trust has been replaced.
+
+This is the single most dangerous part of the change. It cannot ride a
+capability check the way sender keys did, because it is not about what the
+_other_ side can do; it is about what a local file means.
+
+### The nickname is the identity, as far as the relay is concerned
+
+Nicknames are unique and rooms are keyed by session. Two options, both with a
+cost:
+
+- **The relay learns about identities.** N sessions may share a nickname if
+  they prove the same identity key. This is the honest model and it is a
+  protocol change on the relay, plus a proof-of-possession on JOIN so the name
+  cannot be taken by asserting somebody else's identity.
+- **Devices get distinct names.** No relay change, and it leaks how many
+  devices you have to everyone in the room — metadata this project otherwise
+  works hard to withhold.
+
+The first is more work and is the right one. It should not be decided by which
+is easier to build.
+
+### Fan-out multiplies, and #481 just decided to keep the loop
+
+Item 3 of #481 concluded the per-peer loop stays — deniability and sender-key
+distribution both need it permanently. With D devices per peer that loop
+becomes **N × D**, and sender-key _distribution_ becomes N × D too, even though
+the group send itself stays at one.
+
+That is the same scaling wall sender keys were built to remove, re-entered
+through a different door. It has to be sized before anything ships:
+`/room` already reports the send path and the cost, so the measurement has
+somewhere to live.
+
+### Sealed sender leaks the device count
+
+An envelope is sealed to one recipient key. Per-device keys mean one envelope
+per device, and the relay can count them. Today the relay learns the recipient
+and not the sender; after this it learns _how many devices the recipient has_,
+which is a stable fingerprint of a person across sessions. Padding the fan-out
+to a fixed bucket is the obvious answer and it is not free.
+
+### Rotation on membership change now fires on device churn
+
+`#rotateGroupFor` runs when a member leaves, because a departed member holds a
+chain that ratchets forward. With devices, closing a laptop is a departure.
+Rotating the room every time somebody's second device sleeps is expensive and
+makes a real guarantee look like noise.
+
+The rule probably becomes: rotate when the **last** device of a member leaves,
+or when a device is **revoked**. That is a different predicate from the one in
+the code today and it needs its own test per route in, exactly as the departure
+routes did in #482.
+
+### Where the identity key lives
+
+If it is on every device, losing any device loses the identity. If it is on one
+primary, that device is a single point of failure for ever adding another. The
+Signal answer is a primary that provisions, and it is probably right here too —
+but this project has no second channel to provision over except the pairwise
+one it is trying to bootstrap, so the provisioning step needs a real design of
+its own.
+
+**Decided (2026-08-23): the identity secret never moves.** A secondary device
+generates its own box keypair and receives only the identity's *public* half
+plus a device list signed by it. A stolen phone is then a stolen phone rather
+than a stolen identity, and a secondary cannot add or revoke devices — only the
+device holding the secret can.
+
+The provisioning channel is the user, and it is two hops because neither side
+can sign for the other: the new device has to say what its key is before the
+identity can sign for it, and has to be told what identity it belongs to
+afterwards.
+
+```
+B: /device request        → ciphermesh-device://request/…   (~150 characters)
+A: /device add <request>  → ciphermesh-device://grant/…     (~740 characters)
+B: /device accept <grant>
+```
+
+Neither string is secret — a request is a public key, a grant is a signed
+statement that was going to be broadcast to every peer anyway — so interception
+achieves nothing. Substitution is caught: a grant only applies if the list names
+the exact device that asked, by both id and key.
+
+Two costs, both accepted rather than hidden:
+
+- **Losing the primary means no more adding or revoking.** The standard
+  trade-off, and the safer side of it.
+- **A secondary cannot rotate its box key**, because it cannot re-sign the list
+  that names it. `KeyManager.rotate()` is a no-op there. Fixing that needs a
+  channel for a secondary to ask the primary to re-sign, which does not exist
+  yet.
+
+**Also decided: no ML-KEM key in a device descriptor.** A list is a set of
+claims about identity; a KEM key is transport material, already advertised per
+session in JOIN, and a device could change it without changing who it is.
+Carrying it cost 1 584 bytes of base64 per device — the difference between a
+grant that fits in a QR code and one that does not. Changed while the format
+was still unreleased, which is the only time it is free.
+
+### Message history for a device that was not there
+
+A device added today cannot read what the room said yesterday: a sender key
+handed over serialises the chain at its _current_ counter. That is already
+decided for the offline queue in
+[sender-keys-on-relay.md](sender-keys-on-relay.md) and the arithmetic is the
+same here. "A new device starts from now" is a defensible answer. It has to be
+said out loud, in the UI, at the moment somebody adds one — not discovered.
+
+## What to be careful about
+
+- **The mlock ceiling.** `sodium_malloc` pages are locked and Linux caps how
+  much a process may lock. #481 already recorded a SIGABRT from exactly this,
+  surfacing in an unrelated ratchet call because it was the next allocation to
+  fail. Per-device keys multiply guarded allocations by D, per peer, per room.
+  This is the failure this change is most likely to hit, and it is invisible on
+  macOS, where the limit is unlimited. Instrument `sodium_malloc` by call site
+  before, not after.
+- **`DoubleRatchet.js` has the same zero-without-free pattern at 19 sites.**
+  Noted and deliberately not fixed in #481 because 1,164 allocations is nowhere
+  near a limit. Multiply by D and re-check that judgement.
+- **P2P is a different problem.** `P2PChatController` keys peers by _nickname_
+  and has no session ids and no relay. Multi-device in the mesh is not the same
+  design, and pretending one document covers both is how the relay path ended
+  up with assumptions from the mesh baked into it. Out of scope for v1, and say
+  so in the UI.
+- **The offline queue keys on nickname + publicKey.** Both halves change
+  meaning. Re-read `OfflineQueue.dequeue` against the new model rather than
+  assuming it still lines up.
+- **A device list is a replay target.** The counter is not optional, and
+  "highest counter wins" has to be enforced on receipt, not on send.
+
+## Suggested order
+
+The sender-keys rollout worked because each step was landable on its own and
+the risky one arrived after its safety net. Same shape:
+
+*Steps 1 to 5 are done; the notes below are as written, with what shipped
+recorded against each.*
+
+1. **`DeviceIdentity`: an identity keypair, a signed device descriptor, and
+   frozen vectors** — a crypto module with no callers. Nothing on the wire,
+   nothing in the UI, no behaviour change. **Shipped (#493).**
+2. **Carry the identity key in `KeyManager`, persisted and backed up,
+   advertised in JOIN and used by nobody.** This is the trick that worked for
+   the Ed25519 sender signature: land the field while the wire is still free.
+3. **A signed device list, distributed pairwise, behind a capability** — still
+   one device per identity. The plumbing is exercised before it carries weight.
+4. **Move verification to the identity key**, with the device fingerprint still
+   shown, a migration for existing records, and a loud, deliberate story for
+   `VERIFIED_MISMATCH`.
+5. **A second device, receive-only.** Provisioning, and the relay change that
+   lets two sessions share a nickname.
+6. **Sending from a second device, and own-device fan-out.** The point at which
+   a conversation stops being split.
+7. **Revocation**, with a test per route out — the way #482 did for departures.
+8. **Only then**, the mesh, if at all.
+
+   **Decided (2026-08-23): not at all, for now.** Multi-device in the mesh is
+   not merely unimplemented — it is a different design. `P2PChatController`
+   keys its peers by **nickname** (`#peers` is `Map<peerNickname, …>`) and has
+   no session ids, so two devices of one person collide on the very thing the
+   peer map is indexed by. Supporting them means re-keying the mesh's whole
+   model of who a peer is, and doing that inside this arc would have meant
+   designing a second system while shipping the first.
+
+   What shipped instead is honesty. `/device`, `/create`, `/invite` and `/nick`
+   are relay-only, and the mesh now says why rather than guessing at a typo —
+   `/device` previously suggested `/voice`, which sends somebody looking in
+   entirely the wrong place. `test/commands-json.test.js` pins the relay-only
+   set, so a fifth cannot join it unnoticed.
+
+   The prerequisite for revisiting this is a mesh peer identified by something
+   other than a name.
+
+Steps 1 and 2 are safe enough to do before the rest is agreed. Step 4 is the
+one to slow down on.
+
+## Why it is worth it
+
+It is the largest functional gap in the project, and unlike the others it is
+one the product actively invites people into: `/backup` is in the README's
+command table and the restore prompt is the second thing the client asks at
+startup. Together they produce the configuration described at the top. The
+choice is not between multi-device and no multi-device. It is between a
+designed one and the accidental one that exists now.

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

@@ -1,8 +1,13 @@
 # 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.
+Status: **shipped.** Written 2026-08-07, straight after measuring the problem,
+so the next session started from the constraints rather than rediscovering
+them. The receive half shipped in 2.11.0 and the send half, with rotation on
+every membership change, in 2.12.0. Steps 1-4 below are done; step 5 is
+answered in place and the answer is no.
+
+The document is kept as written rather than rewritten in the past tense: what
+it got wrong is as useful as what it got right, and step 5 got it wrong.
 
 ## The problem, measured
 
@@ -110,6 +115,32 @@ order they should be considered:
 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.
 
+   **Decided (2026-08-23): it is not retired, and the framing was wrong.** Step
+   5 was written as though the per-peer loop were a compatibility shim that
+   ages out once everyone upgrades. It is not. It is the pairwise send path,
+   and four separate things still require it — two of them permanently:
+
+   - **`/deniable` is a user-facing mode.** Deniability is a property of the
+     pairwise construction: a symmetric key both sides could have derived, so
+     neither can prove the other wrote it. A group packet is signed by exactly
+     one sender — that is what closed member forgery above. Sending a deniable
+     message on the group path would publish the opposite of what was asked
+     for, so `#canSendToGroup` refuses it. No amount of upgrading changes this.
+   - **Sender-key distribution rides the pairwise channel**, and has to: a
+     distribution is authenticated by opening the envelope it arrived in, never
+     asserted by the relay. The group path cannot bootstrap itself.
+   - **One older peer holds the room** — transitional in principle, permanent
+     in practice on a public hub, which is exactly the case this project was
+     built for.
+   - **An older hub cannot fan out a room-addressed message.** Same shape.
+
+   So there is no release in which deleting the loop is correct. What was
+   actually missing is that nobody could *see* which path a room was on: a room
+   pays fifty times over for one line and the only symptom is that it feels
+   slow. `/room` now reports the path and, when it is the expensive one, the
+   reason — the older hub, or the peers by name. That makes the cost
+   attributable, which is what step 5 was really reaching for.
+
 ## Why it is worth it
 
 It is the one change that is simultaneously a feature, a fix and an