ciphermesh 2.11.0 → 2.12.0

package/CHANGELOG.md

@@ -3,6 +3,63 @@
 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** —

package/docs/PROTOCOL.md

@@ -155,6 +155,13 @@ and must be recognised by key.
 `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.
 
+`peer_left` is emitted for **every** way a session stops being in a room:
+leaving, switching, disconnecting, being kicked, being banned. That completeness
+is load-bearing rather than tidy. A sender chain (§7) is shared with exactly the
+members of a room, so the set of departures a client hears about is the set of
+moments it can rotate that chain at — and a departure it never hears about is a
+chain that outlives the membership it was drawn for.
+
 ### `ping` / `pong`
 
 Either direction, no payload beyond the framing.
@@ -245,6 +252,29 @@ message keys may be cached.
 The unicast path costs one encryption and one envelope **per recipient**. Sender
 keys make it one of each for the whole room.
 
+### When this path is used
+
+Three conditions, all required, each failing for a different reason:
+
+| Condition | Fails when |
+| --- | --- |
+| every member of the room advertises `sk1` | one peer is on an older build |
+| `join_ack.serverCaps` contains `sk1` | the hub is older |
+| the message is not deniable | see below |
+
+Any one false and the per-peer path runs unchanged. A sender **must** re-check
+per message rather than caching the answer: a single arrival can take a room off
+this path, and encrypting for a member who cannot decrypt is silent.
+
+**Deniable messages never take this path.** Deniability comes from 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 — sending a deniable message on it
+would publish precisely what deniability is for hiding.
+
+**Cover traffic takes whichever path real messages take.** A decoy that travelled
+the per-peer path while the room was sending group messages would be
+distinguishable from the thing it exists to imitate.
+
 ### The chain
 
 Each member owns a symmetric ratchet chain per room:
@@ -280,6 +310,23 @@ 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.
 
+**Who speaks first is not a free choice.** A client drops a ciphertext from a
+session it holds no public key for, and a joiner learns the room from its
+`join_ack` *before* the room learns of the joiner from `peer_joined`. A newcomer
+that distributed on arrival would be talking to peers who cannot yet hear it, and
+would have no way to discover that.
+
+So distribution is **answered, never announced**:
+
+1. the peers who already know the newcomer distribute to it (on `peer_joined`);
+2. the newcomer replies with its own to anyone whose distribution it receives and
+   who does not already hold its current chain.
+
+Receiving a distribution proves the sender holds your public key, so the reply
+cannot race. A sender must also distribute to any room member it has not yet
+given its current chain to before sending — the exchange above covers every
+ordinary path, and that check covers the rest.
+
 ### The message
 
 ```json
@@ -325,6 +372,21 @@ 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.
 
+Concretely, a departure rotates: leaving, switching rooms, disconnecting, being
+kicked, being banned. All five reach the client as `peer_left` (§4), which is why
+that message has to be emitted for all five and not only the voluntary ones — a
+departure the client never hears about is a chain that is never rotated, and a
+removed member whose copy still opens everything that follows.
+
+**An arrival does not rotate.** A distribution carries the chain's current
+counter, so a newcomer is handed what opens the next message and nothing before
+it. Rotating on arrival would cost a redistribution to the whole room and buy
+nothing.
+
+A full room switch drops every chain rather than rotating one: the client is no
+longer in the rooms those chains were drawn for, and carrying one across would
+use a chain drawn for one membership against another.
+
 ### What the relay does
 
 Validates the shape, checks the sender **is a member of `room`**, spends the same
@@ -405,6 +467,14 @@ 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.
 
+A kick or a ban emits **`peer_kicked` and then `peer_left`**, in that order, for
+the same session. `peer_kicked` carries an optional `sessionId` alongside the
+nickname; a client that has it can match the two and report one event once,
+while one that does not — every client before this — simply sees an ordinary
+departure and a kick notice. Nicknames could not do this job: `/nick` reassigns
+them, so unwinding a peer by name drops the wrong session as soon as two people
+have ever shared one.
+
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ciphermesh",
-  "version": "2.11.0",
+  "version": "2.12.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",
@@ -63,7 +63,7 @@
     "node-notifier": "10.0.1",
     "qrcode-terminal": "0.12.0",
     "sodium-native": "5.1.0",
-    "ws": "8.21.1"
+    "ws": "8.21.3"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",

package/src/client/ChatController.js

@@ -18,6 +18,7 @@ import {
   createKickPeer,
   createMutePeer,
   createBanPeer,
+  createGroupMessage,
   ERR,
 } from '../protocol/messages.js';
 import { sealEnvelope, openEnvelope } from '../crypto/SealedSender.js';
@@ -34,8 +35,9 @@ import {
   EMOJI_MAP,
   COVER_CONSTANT_MS,
   OWN_CAPABILITIES,
+  CAP,
 } from '../shared/constants.js';
-import { normalizeCaps, roomSupports } from '../protocol/capabilities.js';
+import { normalizeCaps, peerSupports, roomSupports } from '../protocol/capabilities.js';
 import { GroupSession } from '../crypto/SenderKey.js';
 import { KeyManager } from '../crypto/KeyManager.js';
 import { Handshake } from '../crypto/Handshake.js';
@@ -86,7 +88,9 @@ export class ChatController {
   #peers; // Map<sessionId, { nickname, publicKey, caps }>
   #groups = new Map(); // room -> GroupSession (sender keys; receive only for now)
   #groupBuffer = new Map(); // keyId -> group msgs waiting on their sender key
+  #distributed = new Map(); // room -> Set<sessionId> holding our current chain
   #serverCaps = []; // what the relay advertised in join_ack
+  #kickedSessions = new Set(); // sessionIds announced kicked, awaiting their peer_left
   #lastTypingSent;
   #peerTypingTimers; // Map<sessionId, timeoutId>
   #fileTransfer;
@@ -850,6 +854,17 @@ export class ChatController {
       });
     }
 
+    // A newcomer holds no chain of ours, so give them one before anything is
+    // sent on it. Ordered ahead of the presence and topic sends below because
+    // those may themselves go out on the group path.
+    //
+    // No rotation here. Someone arriving is not someone gaining access to the
+    // past: a serialised chain carries its *current* counter, so what they are
+    // handed opens what comes next and nothing before it.
+    if (room === this.#currentRoom) {
+      this.#distributeSenderKey(room, peer.sessionId);
+    }
+
     // A newcomer doesn't know my presence — send only to them
     if (this.#away || this.#statusText) {
       this.#sendPayloadToPeer(peer.sessionId, this.#presencePayload());
@@ -896,11 +911,19 @@ export class ChatController {
     }
     const goneEntirely = !entry || !room || entry.rooms.size === 0;
 
-    // Drop their sender chain for the room they left. Their own rotation is what
-    // gives forward secrecy — this only stops us holding a key we can no longer
-    // be sent anything on.
-    if (room) {
-      this.#groups.get(room)?.removeMember(msg.sessionId);
+    // Two separate things, and only the second is forward secrecy.
+    //
+    // Dropping *their* chain stops us holding a key we can no longer be sent
+    // anything on. Rotating *ours* is what stops them reading what the room says
+    // next — a chain ratchets forward, so the copy they were handed opens every
+    // message after it until we draw a new one.
+    //
+    // Which rooms rotate is decided by which ones actually lost a member, not by
+    // which ones we happen to hold a session for: every rotation costs a
+    // redistribution to everyone remaining.
+    const lostFrom = new Set();
+    if (room && this.#groups.get(room)?.removeMember(msg.sessionId)) {
+      lostFrom.add(room);
     }
 
     if (goneEntirely) {
@@ -908,15 +931,27 @@ export class ChatController {
       this.#handshake.removePeer(msg.sessionId);
       this.#nonceManager.removePeer(msg.sessionId);
       this.#allPeers.delete(msg.sessionId);
-      for (const group of this.#groups.values()) {
-        group.removeMember(msg.sessionId);
+      for (const [groupRoom, group] of this.#groups) {
+        if (group.removeMember(msg.sessionId)) {
+          lostFrom.add(groupRoom);
+        }
       }
     }
 
+    for (const lost of lostFrom) {
+      this.#rotateGroupFor(lost);
+    }
+
+    // A kick already announced itself. Do every bit of the state work, and say
+    // nothing — "was kicked" followed by "left" describes one event twice.
+    const wasKicked = this.#kickedSessions.delete(msg.sessionId);
+
     if (!room || room === this.#currentRoom) {
       this.#rebuildActivePeers();
-      this.#ui.handshakeDisconnect(nickname);
-    } else {
+      if (!wasKicked) {
+        this.#ui.handshakeDisconnect(nickname);
+      }
+    } else if (!wasKicked) {
       this.#ui.toBuffer(room, () => {
         this.#ui.addSystemMessage(`${nickname} left #${room}`);
       });
@@ -924,13 +959,21 @@ export class ChatController {
     this.#auditLog.log(AuditEvent.PEER_DISCONNECTED, { nickname });
   }
 
-  // ── Sender keys on the relay: the receive half ────────────────
+  // ── Sender keys on the relay ──────────────────────────────────
   //
-  // Sending is deliberately absent — #broadcastPayload still seals one envelope
-  // per peer. This is the half that has to be in the field first: a room only
-  // switches to group sending once every member advertises it, so the ability to
-  // read one must ship a release before the ability to write one, or the switch
-  // never becomes true for anybody.
+  // The receive half shipped a release ahead of this one, on purpose: a room
+  // switches to group sending only once every member advertises that it can
+  // read one, so the readers had to be in the field before the writers or the
+  // switch would never have become true for anybody.
+  //
+  // Three things have to hold before a line goes out once instead of N times,
+  // and they fail for different reasons:
+  //
+  //   1. every member of the room advertises `sk1`   — an old peer
+  //   2. the relay advertises `sk1`                  — an old hub
+  //   3. the message is not deniable                 — see #canSendToGroup
+  //
+  // Any one of them false and the per-peer loop runs, unchanged.
 
   #getGroup(room) {
     let group = this.#groups.get(room);
@@ -951,6 +994,162 @@ export class ChatController {
     }
     this.#getGroup(data.room).addMember(fromSessionId, data.dist);
     this.#flushGroupBuffer(data.dist.keyId);
+
+    // Answer with ours if they do not have it. This is what makes distribution
+    // reliable without anything having to know who joined in which order:
+    // whoever knows the other first speaks, and the reply cannot race, because
+    // receiving this proves they already hold our public key.
+    if (!this.#hasDistributedTo(data.room, fromSessionId)) {
+      this.#distributeSenderKey(data.room, fromSessionId);
+    }
+  }
+
+  // A full room switch: every buffer is dropped and we exist only in `room`.
+  // The chains follow. Carrying one across would mean a chain drawn for one
+  // room's membership being used against another's, and a keyId that outlives
+  // the set of people it was ever meant to label.
+  #dropAllGroups() {
+    for (const group of this.#groups.values()) {
+      group.destroy();
+    }
+    this.#groups.clear();
+    this.#groupBuffer.clear();
+    this.#distributed.clear();
+  }
+
+  // Hand our sender key for `room` to one peer, or to everyone in it.
+  //
+  // Always pairwise. The envelope is what proves who the key belongs to; a
+  // distribution arriving on the group path would be a chain vouching for
+  // itself, and the relay would be the only thing asserting whose it was.
+  //
+  // Never sent to a peer that may not know us yet. A client drops a ciphertext
+  // from a session it has no public key for, and it learns ours from the
+  // `peer_joined` the relay sends *after* our `join_ack` — so a newcomer
+  // announcing itself into the room on arrival is talking to people who cannot
+  // hear it. That is why nothing distributes on join: the peers who already
+  // know us distribute to us (#onPeerJoined), and we answer (#onSenderKeyDistribution).
+  #distributeSenderKey(room, toPeer = null) {
+    const recipients = (toPeer ? [toPeer] : [...this.#peers.keys()]).filter((id) =>
+      this.#worthDistributingTo(id),
+    );
+    if (recipients.length === 0) {
+      return;
+    }
+
+    // Only now: distribution() is what draws the chain, and a chain is guarded
+    // memory. See #worthDistributingTo.
+    const payload = JSON.stringify({
+      action: 'sk_dist',
+      room,
+      dist: this.#getGroup(room).distribution(),
+      sentAt: Date.now(),
+    });
+    let sent = this.#distributed.get(room);
+    if (!sent) {
+      sent = new Set();
+      this.#distributed.set(room, sent);
+    }
+    // Record before sending, never after.
+    //
+    // Sending re-enters this object. The peer receives the distribution, finds
+    // it holds none of ours, and answers — and its answer can arrive before
+    // #sendPayloadToPeer has returned. Marking afterwards means both sides
+    // consult a record neither has written yet, each answers the other's
+    // answer, and the exchange never converges.
+    //
+    // On a real socket that is a burst of duplicate distributions rather than a
+    // hang, which is why it is worth stating: the bug is re-entrancy, and the
+    // synchronous case is only the one that makes it obvious.
+    for (const peerId of recipients) {
+      sent.add(peerId);
+    }
+    for (const peerId of recipients) {
+      this.#sendPayloadToPeer(peerId, payload);
+    }
+  }
+
+  // A sender key is only ever useful to a peer that can read a group message,
+  // on a hub that can fan one out. Handing one to anybody else is a wasted
+  // round trip — and, less obviously, a wasted allocation.
+  //
+  // Chains live in sodium_malloc'd memory, which is mlock'd. Linux caps how much
+  // a process may lock (RLIMIT_MEMLOCK), and the cap is small; drawing a chain
+  // per room per peer regardless of whether it could ever be used exhausted it,
+  // and sodium_malloc then returns NULL. That surfaced as a SIGABRT in an
+  // unrelated ratchet call — the first allocation to fail, not the one at fault.
+  #worthDistributingTo(peerId) {
+    if (!this.relaySupportsCapability(CAP.SENDER_KEYS)) {
+      return false;
+    }
+    const peer = this.#peers.get(peerId);
+    return peer ? peerSupports(peer, CAP.SENDER_KEYS) : false;
+  }
+
+  // Has this peer been given our *current* chain for this room? Reset by
+  // rotate(), because after one the answer is no for everybody.
+  #hasDistributedTo(room, peerId) {
+    return this.#distributed.get(room)?.has(peerId) ?? false;
+  }
+
+  // Someone is no longer in `room`: draw a new chain and hand it to whoever is
+  // left.
+  //
+  // This is the forward secrecy the design promises, and the reason the relay
+  // now reports a kick as a departure (#482). Without it a removed member keeps
+  // the chain they were given, and a chain ratchets *forward* — holding it at
+  // counter N opens every counter after N. Being removed from a room would stop
+  // the relay delivering to them and would not stop them reading.
+  //
+  // rotate() has no failure to check and no value to return. The distribution
+  // that follows is the whole point, so the two must not drift apart: a rotation
+  // whose redistribution never happens is a room that quietly stopped being able
+  // to read this client, with nothing raised anywhere.
+  #rotateGroupFor(room) {
+    const group = this.#groups.get(room);
+    if (!group) {
+      return;
+    }
+    group.rotate();
+    this.#distributed.delete(room); // a new chain: nobody has it
+    if (room === this.#currentRoom) {
+      this.#distributeSenderKey(room);
+    }
+  }
+
+  // Can this payload go out once, addressed to the room, instead of N times?
+  #canSendToGroup(deniable) {
+    // 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 for exactly that reason, so
+    // sending a deniable message on it would publish the opposite of what was
+    // asked for.
+    if (deniable) {
+      return false;
+    }
+    if (this.#peers.size === 0) {
+      return false;
+    }
+    return (
+      this.roomSupportsCapability(CAP.SENDER_KEYS) && this.relaySupportsCapability(CAP.SENDER_KEYS)
+    );
+  }
+
+  // One encryption, one frame, the whole room. The payload arrives already
+  // room-tagged and already through the private-room layer when there is one —
+  // both happen before the path splits, so a group message and a pairwise one
+  // carry exactly the same bytes inside.
+  #sendRoomGroup(room, payload) {
+    // Nobody can read a packet on a chain they were never given. The exchange
+    // above covers every ordinary path; this covers the rest, and costs one
+    // Set lookup per member when there is nothing to do.
+    for (const [peerId] of this.#peers) {
+      if (!this.#hasDistributedTo(room, peerId)) {
+        this.#distributeSenderKey(room, peerId);
+      }
+    }
+    const packet = this.#getGroup(room).encrypt(payload);
+    this.#connection.send(createGroupMessage(room, packet));
   }
 
   #onGroupMessage(msg) {
@@ -3170,6 +3369,11 @@ export class ChatController {
       this.#allPeers.set(peer.sessionId, {
         nickname: peer.nickname,
         publicKey: peer.publicKey,
+        // The relay sends these here exactly as it does in join_ack. Dropping
+        // them made every peer look incapable after a room switch, which is not
+        // an error anywhere — it is a room that silently never turns the group
+        // path on, because one absent capability is enough to hold all of it.
+        caps: normalizeCaps(peer.caps),
         rooms: new Set([msg.room]),
       });
       if (!this.#handshake.getRatchet(peer.sessionId)) {
@@ -3179,6 +3383,12 @@ export class ChatController {
     }
 
     this.#rebuildActivePeers();
+    // A switch drops every buffer, so it drops every chain with them. Carrying
+    // one across would mean a chain drawn for one room's membership being used
+    // against another's, and a keyId outliving the set of people it labelled.
+    // The new room's chain is drawn on first use and distributed by the same
+    // exchange as any other.
+    this.#dropAllGroups();
     this.#auditLog.log(AuditEvent.ROOM_CHANGED, { room: msg.room });
     this.#announceJoinedRoom(
       msg.room,
@@ -3205,6 +3415,7 @@ export class ChatController {
         this.#allPeers.set(peer.sessionId, {
           nickname: peer.nickname,
           publicKey: peer.publicKey,
+          caps: normalizeCaps(peer.caps),
           rooms: new Set([msg.room]),
         });
         if (!this.#handshake.getRatchet(peer.sessionId)) {
@@ -3263,6 +3474,18 @@ export class ChatController {
 
   // ── Handle PEER_KICKED ────────────────────────────────────
   #onPeerKicked(msg) {
+    // The relay sends this immediately before the peer_left for the same
+    // session. Remember it so the departure is reported as a kick and not
+    // announced twice; the state work still happens in #onPeerLeft, which is
+    // the one place that knows how to unwind a member.
+    if (typeof msg.sessionId === 'string') {
+      // A kick whose peer_left never arrives (an older relay) must not park an
+      // entry here forever.
+      if (this.#kickedSessions.size >= 64) {
+        this.#kickedSessions.clear();
+      }
+      this.#kickedSessions.add(msg.sessionId);
+    }
     if (msg.nickname.toLowerCase() === this.#nickname.toLowerCase()) {
       const reason = msg.reason ? ` (reason: ${msg.reason})` : '';
       this.#ui.addErrorMessage(`You were kicked from the room${reason}`);
@@ -3558,6 +3781,15 @@ export class ChatController {
       payload = encryptRoomPayload(payload, this.#activeSecrets.roomKey);
     }
 
+    // One ciphertext for the room, when the room and the relay can both take
+    // one. Everything above this line has already run, so the bytes inside are
+    // identical either way — including cover traffic, which has to travel the
+    // path real messages travel or it stops resembling them.
+    if (this.#canSendToGroup(deniable)) {
+      this.#sendRoomGroup(this.#currentRoom, payload);
+      return;
+    }
+
     for (const [peerId] of this.#peers) {
       const peerPublicKey = this.#handshake.getPeerPublicKey(peerId);
       if (!peerPublicKey) {
@@ -3810,11 +4042,7 @@ export class ChatController {
       this.#historyStore.destroy();
     }
     this.#fileTransfer.destroy();
-    for (const group of this.#groups.values()) {
-      group.destroy();
-    }
-    this.#groups.clear();
-    this.#groupBuffer.clear();
+    this.#dropAllGroups();
     this.#handshake.destroy();
     this.#keyManager.destroy();
     this.#connection.close();

package/src/crypto/SenderKey.js

@@ -16,6 +16,26 @@ const CHAIN_KEY_TAG = Buffer.from([0x02]);
 const DEFAULT_MAX_SKIP = 1000; // bound out-of-order / skipped message keys
 const KEY_ID_SIZE = 16;
 
+// Release a key allocated with sodium_malloc.
+//
+// `sodium_memzero` alone is not enough, and the difference is not academic.
+// sodium_malloc'd pages are **mlock'd**, and an operating system caps how much
+// a process may lock at once — RLIMIT_MEMLOCK, which on Linux is small and on
+// macOS is typically unlimited. Zeroing a key leaves its pages locked until the
+// garbage collector happens to run the buffer's finaliser, so a process that
+// derives keys faster than it collects them walks into an allocation failure it
+// never sees coming: sodium_malloc returns NULL, and the crash lands on whatever
+// unrelated call allocated next.
+//
+// sodium_free zeroes before releasing, so this is strictly stronger than the
+// memzero it replaces. Null-safe and idempotent by convention: every caller
+// drops its reference immediately after, so nothing can reach freed memory.
+function freeKey(buf) {
+  if (buf) {
+    sodium.sodium_free(buf);
+  }
+}
+
 // An opaque label for a sender chain, handed out with the distribution.
 //
 // On the relay path a group message arrives by fan-out with no sender on it —
@@ -97,8 +117,9 @@ export class SenderChain {
     sodium.crypto_generichash(messageKey, MSG_KEY_TAG, this.#chainKey);
     const nextChainKey = sodium.sodium_malloc(KEY_SIZE);
     sodium.crypto_generichash(nextChainKey, CHAIN_KEY_TAG, this.#chainKey);
-    sodium.sodium_memzero(this.#chainKey);
+    const spent = this.#chainKey;
     this.#chainKey = nextChainKey;
+    freeKey(spent); // released, not merely zeroed — the hot path, once per message
     return messageKey;
   }
 
@@ -112,7 +133,8 @@ export class SenderChain {
 
   // Receiving: the message key at `targetCounter`, caching skipped keys for
   // out-of-order delivery. Returns null on replay (already consumed) or if the
-  // gap exceeds maxSkip. The caller must sodium_memzero the returned key.
+  // gap exceeds maxSkip. The caller owns the returned key and must release it —
+  // groupDecrypt does, on every path including the failures.
   messageKeyFor(targetCounter) {
     if (this.#skipped.has(targetCounter)) {
       const key = this.#skipped.get(targetCounter);
@@ -145,9 +167,10 @@ export class SenderChain {
   }
 
   destroy() {
-    sodium.sodium_memzero(this.#chainKey);
+    freeKey(this.#chainKey);
+    this.#chainKey = null;
     for (const key of this.#skipped.values()) {
-      sodium.sodium_memzero(key);
+      freeKey(key);
     }
     this.#skipped.clear();
   }
@@ -162,18 +185,18 @@ export function groupEncrypt(messageKey, plaintext) {
   const ciphertext = Buffer.alloc(padded.length + sodium.crypto_secretbox_MACBYTES);
   sodium.crypto_secretbox_easy(ciphertext, padded, nonce, messageKey);
   sodium.sodium_memzero(padded);
-  sodium.sodium_memzero(messageKey);
+  freeKey(messageKey);
   return { ciphertext, nonce };
 }
 
 export function groupDecrypt(messageKey, ciphertext, nonce) {
   if (ciphertext.length < sodium.crypto_secretbox_MACBYTES) {
-    sodium.sodium_memzero(messageKey);
+    freeKey(messageKey);
     return null;
   }
   const padded = Buffer.alloc(ciphertext.length - sodium.crypto_secretbox_MACBYTES);
   const ok = sodium.crypto_secretbox_open_easy(padded, ciphertext, nonce, messageKey);
-  sodium.sodium_memzero(messageKey);
+  freeKey(messageKey);
   if (!ok) {
     sodium.sodium_memzero(padded);
     return null;
@@ -312,14 +335,21 @@ export class GroupSession {
     }
   }
 
+  // Returns whether this actually removed a member. Callers rotate on a real
+  // membership change and must not rotate on a departure they have already
+  // handled: every rotation costs a redistribution to everyone remaining, and a
+  // redistribution that crosses an incoming message is a message the recipient
+  // has to buffer.
   removeMember(memberId) {
     const chain = this.#members.get(memberId);
+    const had = this.#members.has(memberId) || this.#memberSignPk.has(memberId);
     if (chain) {
       chain.destroy();
       this.#members.delete(memberId);
     }
     this.#forgetKeyIdsOf(memberId);
     this.#memberSignPk.delete(memberId);
+    return had;
   }
 
   #forgetKeyIdsOf(memberId) {
@@ -343,13 +373,18 @@ export class GroupSession {
     // The signing key rotates with the chain it authenticates. Keeping it would
     // let anyone holding the old public key keep attributing new packets to a
     // chain that was rotated precisely because the room membership changed.
-    sodium.sodium_memzero(this.#signSk);
+    //
+    // Released rather than zeroed: rotation runs on every membership change, so
+    // a room with any churn would otherwise accumulate locked pages for the life
+    // of the session.
+    freeKey(this.#signSk);
     ({ publicKey: this.#signPk, secretKey: this.#signSk } = newSigningKeypair());
   }
 
   destroy() {
     this.#own.destroy();
-    sodium.sodium_memzero(this.#signSk);
+    freeKey(this.#signSk);
+    this.#signSk = null;
     for (const chain of this.#members.values()) {
       chain.destroy();
     }

package/src/protocol/messages.js

@@ -249,8 +249,17 @@ export function createBanPeer(targetNickname, reason = '') {
   return { ...base(MSG.BAN_PEER), targetNickname, reason };
 }
 
-export function createPeerKicked(nickname, reason = '') {
-  return { ...base(MSG.PEER_KICKED), nickname, reason };
+// `sessionId` (optional) names *which* session was removed. `nickname` cannot:
+// it is not unique over time — /nick reassigns it — and a client that removed a
+// peer by name would drop the wrong session whenever two people had ever shared
+// one. Older clients ignore the field; it exists so a kick can be matched to the
+// `peer_left` that follows it and reported as a kick rather than a departure.
+export function createPeerKicked(nickname, reason = '', sessionId = null) {
+  const msg = { ...base(MSG.PEER_KICKED), nickname, reason };
+  if (sessionId) {
+    msg.sessionId = sessionId;
+  }
+  return msg;
 }
 
 export function createPeerMuted(nickname, durationMs) {

package/src/server/WebSocketServer.js

@@ -776,6 +776,27 @@ export class SecureWSServer {
     this.#finishRoomSwitch(ws, session, result);
   }
 
+  // One session stopped being in one room. Every way out of a room ends here:
+  // leaving, switching, disconnecting, and — since this was the gap — being
+  // kicked or banned.
+  //
+  // Kick and ban used to announce only `peer_kicked`, which carries a nickname
+  // and no session. Clients had nothing to remove a member *by*, so the removed
+  // peer stayed in every remaining roster. Harmless-looking while the relay path
+  // seals one envelope per peer; not harmless at all once a room encrypts once
+  // to a shared chain, because "who is still in this room" is then the input to
+  // when that chain must be rotated away from someone.
+  #emitRoomDeparture(room, sessionId, nickname) {
+    if (!room || !sessionId) {
+      return;
+    }
+    this.#sessionManager.broadcastToRoom(
+      room,
+      createPeerLeft(sessionId, nickname || 'Unknown', room),
+      sessionId,
+    );
+  }
+
   // Shared tail of a successful room switch: notify every old room and send
   // the ROOM_CHANGED (with the private flag) to the mover.
   #finishRoomSwitch(ws, session, result) {
@@ -902,11 +923,14 @@ export class SecureWSServer {
     if (result) {
       const targetSession = this.#sessionManager.getSession(targetSessionId);
 
-      // Notify old room
+      // Notify old room. The kick goes first so a client can mark the session
+      // before the peer_left lands and report it as a kick rather than a
+      // departure; both travel the same socket, so the order holds.
       this.#sessionManager.broadcastToRoom(
         room,
-        createPeerKicked(validation.targetNickname, validation.reason),
+        createPeerKicked(validation.targetNickname, validation.reason, targetSessionId),
       );
+      this.#emitRoomDeparture(room, targetSessionId, targetSession?.nickname);
 
       // Notify target with room change + kick reason
       const newPeers = this.#sessionManager.getRoomPeers('general', targetSessionId);
@@ -1018,8 +1042,9 @@ export class SecureWSServer {
     if (result) {
       this.#sessionManager.broadcastToRoom(
         room,
-        createPeerKicked(validation.targetNickname, validation.reason || 'banned'),
+        createPeerKicked(validation.targetNickname, validation.reason || 'banned', targetSessionId),
       );
+      this.#emitRoomDeparture(room, targetSessionId, targetSession?.nickname);
 
       const newPeers = this.#sessionManager.getRoomPeers('general', targetSessionId);
       targetSession.ws.send(JSON.stringify(createRoomChanged('general', newPeers)));