ciphermesh 2.12.0 → 2.13.0

package/CHANGELOG.md

@@ -3,6 +3,124 @@
 Notable changes per release. Older versions are reconstructed from the git
 history — the commit bodies and pull requests remain the fuller record.
 
+## 2.13.0
+
+**Multi-device.** One identity, several devices, and none of them holding a copy
+of the others' secrets.
+
+Until now two machines could only share an identity by sharing its private key —
+`/backup` copies the whole thing — after which the relay refused the second
+nickname, each message reached exactly one of them, and a peer verifying both
+was shown the same fingerprint twice and told that was normal. That is replaced.
+
+An identity is now an Ed25519 key that only ever signs. Each device has its own
+message key, listed and signed by that identity. Adding a device grants it a
+signed place on the list; it never receives the identity secret, so a stolen
+phone is a stolen phone rather than a stolen identity, and only the device
+holding the secret can add or remove.
+
+`/room` also learned to say how the room is sending, and why.
+
+### Added
+
+- **`/device`: one identity, several devices.** A second device asks with
+  `/device request`, the device holding the identity key answers with
+  `/device add`, and the new one takes it with `/device accept`. Two short
+  strings, small enough for a QR code, and neither of them secret — a request is
+  a public key and a grant is a signed statement that goes to every peer anyway.
+
+  The identity secret never moves. A secondary can prove which identity it
+  belongs to and can publish that proof, but it cannot sign a new list, so
+  adding and removing stay with one device. Two costs come with that and are
+  worth knowing: losing that device means no more adding or removing, and a
+  secondary does not rotate its message key, because it could not re-sign the
+  list that names it.
+
+  `/device remove` signs a shorter list **and rotates the room**. A removed
+  device still holds every member's sender chain, and a chain ratchets forward —
+  dropping it from a list stops the relay delivering to it and does not stop it
+  reading. It keeps what it already received; that is what forward secrecy
+  means.
+
+- **Verification follows the identity, not the device.** Once both sides can,
+  `/verify` compares identity keys, so adding or rotating a device no longer
+  invalidates a verification. The switch is symmetric — both sides make it
+  together — so a pair is never shown two different codes, and `/verify` says
+  which of the two it is showing. Verifications you already have are carried
+  across silently, and only when a signed list names the very key you compared
+  digits over.
+
+- **Another of someone's devices is not "their key changed".** It still warns
+  the first time, because claiming an identity proves nothing on its own. When
+  the proof arrives the warning is answered out loud, and that key is quiet from
+  then on. Your own other device is recognised as yours: `/users` counts people
+  rather than connections, a line you sent from your phone is shown as yours,
+  and your own nickname in your own line does not notify you.
+
+- **`/room` reports how the room is sending, and why.** One ciphertext for the
+  room, or one envelope per member — and when it is the expensive one, the
+  reason: an older hub, deniable mode, or the peers by name.
+
+  ```
+  Sending: one ciphertext to the room (sender keys), read by 4
+  Sending: 4 envelopes per message — carol is on a build without sender keys
+  Sending: 2 envelopes per message — this relay cannot fan out a room-addressed message
+  ```
+
+  An older hub is reported ahead of older peers, because both can be true at
+  once and naming peers who are perfectly current sends you after the wrong
+  problem. P2P gets the same line for its own reasons: a mesh sends one frame
+  per peer either way, so there the saving is *encryptions*, and constant cover
+  is a reason to stay pairwise that the relay path does not have.
+
+### Fixed
+
+- **A second device no longer reads as an attack.** It arrives under the same
+  nickname with a key the trust record has never seen, which is the shape of a
+  man-in-the-middle and was reported as one.
+
+- **Guarded key memory is released, not merely zeroed.** `KeyManager` zeroed its
+  secret keys on `destroy()` and left the pages `mlock`'d until the garbage
+  collector happened to run the finaliser. An operating system caps how much a
+  process may lock, and the cap is small on Linux and unlimited on macOS — so
+  the failure was invisible in development and landed as an abort in whatever
+  allocated next. The same pattern was fixed elsewhere in 2.12.0; this is the
+  rest of it in that file.
+
+### Internal
+
+- **The per-peer send loop is not being retired, and the plan that said it might
+  be was wrong.** It was written up as a compatibility shim that ages out once
+  everybody upgrades. It is not: it is the pairwise send path, and two of the
+  four things that need it need it permanently — `/deniable`, because
+  deniability is a property of the pairwise construction, and sender-key
+  distribution, because a distribution is authenticated by the envelope it
+  arrives in and the group path cannot bootstrap itself. Recorded in
+  `docs/design/sender-keys-on-relay.md`.
+
+- **A design document for multi-device**, written from the code before any of
+  it moved, and kept as written with the decisions recorded in place. It is the
+  reason the arc could be built in eight landable steps.
+
+- **One nickname may be held by several devices of one identity.** The relay
+  admits the second only if its JOIN carries a list signed by the identity the
+  name is already using and naming that JOIN's own key. No challenge is issued
+  and none is needed: replaying somebody else's list buys a seat in a room whose
+  messages you cannot read. The name is released when the last device leaves.
+
+- **New capability `dl1`**, the first with no relay half — a device list travels
+  on the pairwise channel the relay already carries, so there is nothing for it
+  to agree to.
+
+- **Multi-device is not coming to the mesh**, and the mesh now says so. A P2P
+  peer is keyed by nickname, which is exactly what two of your devices share, so
+  it is a different design. `/device`, `/create`, `/invite` and `/nick` explain
+  why they need a relay instead of guessing at a typo — `/device` used to
+  suggest `/voice`.
+
+- Dependency bumps: `@noble/post-quantum` 0.7.0, `eslint` 10.8.1,
+  `globals` 17.11.0.
+
 ## 2.12.0
 
 Sender keys now send. 2.11.0 shipped the half that reads a group message; this

package/README.md

@@ -225,7 +225,7 @@ software was built for.
 | `/leave [room]`                  | Leave a room; its buffer closes (the last room is protected)                                                                                                                                                                     |
 | `/create <room> <password>`      | Create a **private room** 🔒 — see below                                                                                                                                                                                         |
 | `/rooms`                         | List rooms (🔒 marks private ones)                                                                                                                                                                                               |
-| `/room`                          | Current room + your buffer list                                                                                                                                                                                                  |
+| `/room`                          | Current room, how it is sending it, and your buffer list                                                                                                                                                                                                  |
 | `/topic [text\|clear]`           | Show or set the room topic — shown in the status bar and synced to whoever joins later                                                                                                                                           |
 | `/owner`                         | Room owner                                                                                                                                                                                                                       |
 | `/kick` `/mute` `/ban`           | Owner moderation — bound to the public key, so a rename does not undo a ban                                                                                                                                                      |
@@ -251,12 +251,13 @@ without verifying couldn't read a word. Share the password out-of-band.
 
 | Command                          | Description                                                                                                                                                              |
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `/fingerprint [nick]`            | Key fingerprint + a deterministic **randomart** picture of the key                                                                                                       |
-| `/verify <nick>`                 | SAS code (~40-bit) + QR + key randomart for out-of-band verification                                                                                                     |
+| `/fingerprint [nick]`            | Key fingerprint, the identity fingerprint when there is one, and a deterministic **randomart** picture of the key                                                                                                       |
+| `/verify <nick>`                 | SAS code (~40-bit) + QR + key randomart for out-of-band verification; says whether the code is over identity keys or device keys                                                                                                     |
 | `/verify-confirm <nick>`         | Mark peer as verified                                                                                                                                                    |
 | `/trust <nick>` / `/trustlist`   | Accept new key / trust status                                                                                                                                            |
 | `/contacts [add\|remove\|all]`   | Contact book — persistent aliases on trust records ("this fingerprint is João"); shows in `/users`, rides along in identity backups                                      |
 | `/backup [path]`                 | Encrypted backup of identity + verified peers (restore at startup)                                                                                                       |
+| `/device [list\|request\|add\|accept\|remove]` | 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 |
 | `/deniable [on\|off]`            | Plausible-deniability mode                                                                                                                                               |
 | `/lock` / `/autolock <min\|off>` | Lock the screen behind the session passphrase — manually or after idle time (`autoLock` in config). Privacy for the "stepped away" moment; `/panic` is for the worst one |
 | `/panic [yes]`                   | Duress wipe — securely erase all on-disk secrets (session, history, trust, keys) and exit                                                                                |

package/README.pt-BR.md

@@ -226,7 +226,7 @@ aquela para a qual este software foi feito.
 | `/leave [sala]`                  | Sai de uma sala; o buffer fecha (a última sala é protegida)                                                                                                                                                                                  |
 | `/create <sala> <senha>`         | Cria uma **sala privada** 🔒 — veja abaixo                                                                                                                                                                                                   |
 | `/rooms`                         | Lista salas (🔒 marca as privadas)                                                                                                                                                                                                           |
-| `/room`                          | Sala atual + sua lista de buffers                                                                                                                                                                                                            |
+| `/room`                          | Sala atual, como está enviando, e sua lista de buffers                                                                                                                                                                                                            |
 | `/topic [texto\|clear]`          | Mostra ou define o assunto da sala — aparece na barra de status e é sincronizado para quem entra depois                                                                                                                                      |
 | `/owner`                         | Dono da sala                                                                                                                                                                                                                                 |
 | `/kick` `/mute` `/ban`           | Moderação (dono da sala) — presa à chave pública, então trocar de apelido não desfaz um ban                                                                                                                                                  |
@@ -252,10 +252,11 @@ sem verificar não leria uma palavra. Combine a senha por outro canal.
 
 | Comando                          | Descrição                                                                                                                                                           |
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/fingerprint [nick]`            | Fingerprint + um **randomart** determinístico da chave                                                                                                              |
-| `/verify <nick>`                 | Código SAS (~40 bits) + QR + randomart da chave para verificar                                                                                                      |
+| `/fingerprint [nick]`            | Fingerprint, o fingerprint de identidade quando existe, e um **randomart** determinístico da chave                                                                                                              |
+| `/verify <nick>`                 | Código SAS (~40 bits) + QR + randomart da chave para verificar; diz se o código é sobre chaves de identidade ou de dispositivo                                                                                                      |
 | `/verify-confirm <nick>`         | Marca o peer como verificado                                                                                                                                        |
 | `/backup [caminho]`              | Backup cifrado da identidade + peers verificados (restaura no startup)                                                                                              |
+| `/device [list\|request\|add\|accept\|remove]` | Seus dispositivos sob uma identidade. A chave de identidade nunca sai do dispositivo que a guarda: um segundo dispositivo recebe um lugar assinado na lista, não uma cópia da identidade. Remover um rotaciona a sala, então nada dito depois chega até ele |
 | `/trust <nick>` / `/trustlist`   | Aceita chave nova / status de confiança                                                                                                                             |
 | `/contacts [add\|remove\|all]`   | Agenda — apelidos persistentes nos registros de confiança ("esse fingerprint é o João"); aparece no `/users` e viaja no backup de identidade                        |
 | `/deniable [on\|off]`            | Modo de negação plausível                                                                                                                                           |

package/docs/ARCHITECTURE.md

@@ -930,12 +930,18 @@ The all-members rule is what keeps the damage on that side of the line.
 |---|---|---|
 | `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`.
+| `dl1` | client | I can read a signed device list handed to me over the pairwise channel. Client-only: a device list rides the sealed channel the relay already carries, so there is no relay half to negotiate. |
+
+Neither means "I send group messages". Receive and fan-out shipped a release
+ahead of send — 2.11.0 and 2.12.0 — because the switch is *every member agrees*:
+if the ability to read had 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.
+
+The per-peer loop the switch falls back to is **not** going away; `/room` reports
+which path a room is on and why. See `docs/design/sender-keys-on-relay.md` for
+that decision, and `docs/design/multi-device.md` for the change that would
+multiply the fallback's cost by the number of devices per peer.
 
 ## 7. Handshake Protocol
 

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