ciphermesh 2.10.0 → 2.12.0

package/src/crypto/SenderKey.js

@@ -14,6 +14,82 @@ const KEY_SIZE = 32;
 const MSG_KEY_TAG = Buffer.from([0x01]);
 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 —
+// the relay must not stamp one, or it would be asserting an identity that today
+// is only ever carried sealed inside the envelope. So the packet names its
+// *chain* instead of its sender, and only members who hold the distribution can
+// map the two. To the relay it is a random string; it already knows which socket
+// sent the frame, so this tells it nothing new. It is drawn fresh on every
+// rotate(), so it never outlives the chain it labels.
+function newKeyId() {
+  const buf = Buffer.alloc(KEY_ID_SIZE);
+  sodium.randombytes_buf(buf);
+  return buf.toString('base64');
+}
+
+// ── Per-sender signatures ───────────────────────────────────────
+// A sender key is symmetric: every member of the room holds the chain that
+// decrypts a given sender, which means every member can also *produce*
+// ciphertext on it. Without something asymmetric on top, "Alice said this" is
+// only ever "somebody in this room said this" — and on a public relay, where
+// `general` has no owner and no admission control, that is a much wider set of
+// somebodies than in a P2P mesh.
+//
+// So each sender also holds an Ed25519 keypair for the life of its chain. The
+// public half travels in the distribution, over the pairwise sealed channel that
+// already authenticates who sent it; every packet carries a detached signature.
+// Forging a member now needs their signing key, not just membership.
+function newSigningKeypair() {
+  const publicKey = Buffer.alloc(sodium.crypto_sign_PUBLICKEYBYTES);
+  const secretKey = sodium.sodium_malloc(sodium.crypto_sign_SECRETKEYBYTES);
+  sodium.crypto_sign_keypair(publicKey, secretKey);
+  return { publicKey, secretKey };
+}
+
+// What the signature covers. Every field the relay could tamper with or replay
+// across chains: the label, the position in the chain, and the box itself.
+// Length-prefixed so no two different packets can serialise to the same bytes.
+function signedBytes({ keyId, counter, ciphertext, nonce }) {
+  const parts = [keyId, String(counter), ciphertext, nonce];
+  return Buffer.from(parts.map((p) => `${p.length}:${p}`).join('|'), 'utf-8');
+}
+
+function decodeSignPk(b64) {
+  if (typeof b64 !== 'string') {
+    return null;
+  }
+  let buf;
+  try {
+    buf = Buffer.from(b64, 'base64');
+  } catch {
+    return null;
+  }
+  return buf.length === sodium.crypto_sign_PUBLICKEYBYTES ? buf : null;
+}
 
 // A single sender's ratchet chain. Used to *send* (deriveNext) when it's your
 // own chain, or to *receive* (messageKeyFor) when it's a peer's distributed one.
@@ -41,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;
   }
 
@@ -56,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);
@@ -89,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();
   }
@@ -106,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;
@@ -129,28 +208,51 @@ export function groupDecrypt(messageKey, ciphertext, nonce) {
 // member. encrypt() runs once; every member decrypt()s the same ciphertext.
 export class GroupSession {
   #own;
+  #ownKeyId;
+  #signPk; // Ed25519 — proves *which member* wrote a packet
+  #signSk;
   #members; // Map<memberId, SenderChain>
+  #byKeyId; // Map<keyId, memberId> — which chain opens an incoming packet
+  #memberSignPk; // Map<memberId, Buffer> — who is allowed to have written it
 
   constructor() {
     this.#own = new SenderChain();
+    this.#ownKeyId = newKeyId();
+    ({ publicKey: this.#signPk, secretKey: this.#signSk } = newSigningKeypair());
     this.#members = new Map();
+    this.#byKeyId = new Map();
+    this.#memberSignPk = new Map();
   }
 
   encrypt(plaintext) {
     const { messageKey, counter } = this.#own.deriveNext();
     const { ciphertext, nonce } = groupEncrypt(messageKey, plaintext);
-    return {
+    const packet = {
+      keyId: this.#ownKeyId,
       counter,
       ciphertext: ciphertext.toString('base64'),
       nonce: nonce.toString('base64'),
     };
+    const signature = Buffer.alloc(sodium.crypto_sign_BYTES);
+    sodium.crypto_sign_detached(signature, signedBytes(packet), this.#signSk);
+    packet.signature = signature.toString('base64');
+    return packet;
   }
 
-  decrypt(memberId, { counter, ciphertext, nonce }) {
+  decrypt(memberId, { keyId, counter, ciphertext, nonce, signature }) {
     const chain = this.#members.get(memberId);
     if (!chain) {
       return null;
     }
+
+    // Verify BEFORE touching the chain. Two reasons, and the second is the one
+    // that is easy to miss: a bad signature must not be able to advance the
+    // ratchet or fill the skipped-key cache, or an unauthenticated packet with a
+    // large counter becomes a way to make the receiver derive a thousand keys.
+    if (!this.#verify(memberId, { keyId, counter, ciphertext, nonce, signature })) {
+      return null;
+    }
+
     const messageKey = chain.messageKeyFor(counter);
     if (!messageKey) {
       return null;
@@ -162,9 +264,51 @@ export class GroupSession {
     );
   }
 
+  #verify(memberId, packet) {
+    const signPk = this.#memberSignPk.get(memberId);
+    if (!signPk || typeof packet.signature !== 'string' || typeof packet.keyId !== 'string') {
+      return false;
+    }
+    // The label on the packet has to be the one this member distributed.
+    // Verifying against the stored label instead would leave keyId outside
+    // everything that protects it — the AEAD does not cover it either — so
+    // decrypt() could be talked into checking one member's signature against
+    // another member's label.
+    if (this.#byKeyId.get(packet.keyId) !== memberId) {
+      return false;
+    }
+    let sig;
+    try {
+      sig = Buffer.from(packet.signature, 'base64');
+    } catch {
+      return false;
+    }
+    if (sig.length !== sodium.crypto_sign_BYTES) {
+      return false;
+    }
+    return sodium.crypto_sign_verify_detached(sig, signedBytes(packet), signPk);
+  }
+
   // The distribution message to hand a (new) member so they can decrypt you.
+  // `keyId` labels the chain; `signPk` is what stops any *other* member using
+  // that chain to write in your name.
   distribution() {
-    return this.#own.serialize();
+    return {
+      ...this.#own.serialize(),
+      keyId: this.#ownKeyId,
+      signPk: this.#signPk.toString('base64'),
+    };
+  }
+
+  // Which member does an incoming packet's keyId belong to? Null for a label we
+  // were never given a distribution for — an unknown sender, or one that
+  // rotated without telling us yet.
+  memberForKeyId(keyId) {
+    return this.#byKeyId.get(keyId) ?? null;
+  }
+
+  get keyId() {
+    return this.#ownKeyId;
   }
 
   addMember(memberId, distribution) {
@@ -172,15 +316,48 @@ export class GroupSession {
     if (existing) {
       existing.destroy();
     }
+    // Drop any label this member held before — a redistribution after rotate()
+    // replaces the chain, and leaving the old keyId mapped would route the
+    // member's next packet to a chain that can no longer open it.
+    this.#forgetKeyIdsOf(memberId);
     this.#members.set(memberId, SenderChain.deserialize(distribution));
+    if (typeof distribution?.keyId === 'string') {
+      this.#byKeyId.set(distribution.keyId, memberId);
+    }
+    // A distribution without a usable signing key leaves the member registered
+    // but unreadable: #verify fails closed, so nothing they send is accepted.
+    // Better a member who cannot be heard than one who cannot be attributed.
+    const signPk = decodeSignPk(distribution?.signPk);
+    if (signPk) {
+      this.#memberSignPk.set(memberId, signPk);
+    } else {
+      this.#memberSignPk.delete(memberId);
+    }
   }
 
+  // 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) {
+    for (const [id, owner] of this.#byKeyId) {
+      if (owner === memberId) {
+        this.#byKeyId.delete(id);
+      }
+    }
   }
 
   hasMember(memberId) {
@@ -192,13 +369,27 @@ export class GroupSession {
   rotate() {
     this.#own.destroy();
     this.#own = new SenderChain();
+    this.#ownKeyId = newKeyId();
+    // 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.
+    //
+    // 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();
+    freeKey(this.#signSk);
+    this.#signSk = null;
     for (const chain of this.#members.values()) {
       chain.destroy();
     }
     this.#members.clear();
+    this.#byKeyId.clear();
+    this.#memberSignPk.clear();
   }
 }

package/src/p2p/P2PChatController.js

@@ -2392,9 +2392,11 @@ export class P2PChatController {
       return;
     }
     const plaintext = this.#getGroup(msg.room).decrypt(fromNickname, {
+      keyId: msg.keyId,
       counter: msg.counter,
       ciphertext: msg.ciphertext,
       nonce: msg.nonce,
+      signature: msg.signature,
     });
     if (!plaintext) {
       // No sender key yet (rare race) — buffer until sk_dist arrives.

package/src/protocol/capabilities.js

@@ -0,0 +1,74 @@
+import { MAX_CAPABILITIES, MAX_CAPABILITY_LENGTH, OWN_CAPABILITIES } from '../shared/constants.js';
+
+// ── Capability negotiation ─────────────────────────────────────
+//
+// `PROTOCOL_VERSION` is checked for exact equality, so it can only say "same" or
+// "refuse to talk". It cannot express a client that is newer but still willing
+// to speak the old way, which is precisely what rolling a protocol change
+// through a public hub needs. Capabilities carry that: advertised in JOIN,
+// relayed verbatim with the peer list, and read here.
+//
+// The rule for turning a feature on is deliberately the strict one — *every*
+// member of the room must advertise it. One peer on an older build is enough to
+// keep the whole room on the old path, which is the outcome that keeps a
+// half-upgraded room readable.
+
+/**
+ * Defensive read of a capability list that arrived over the wire.
+ *
+ * The relay validates what it accepts, but a client should not depend on the
+ * relay having done so — this list is used to decide how to encrypt.
+ *
+ * @returns {string[]} the valid entries, or an empty list
+ */
+export function normalizeCaps(caps) {
+  if (!Array.isArray(caps)) {
+    return [];
+  }
+  const clean = [];
+  for (const cap of caps.slice(0, MAX_CAPABILITIES)) {
+    if (typeof cap !== 'string' || cap.length === 0 || cap.length > MAX_CAPABILITY_LENGTH) {
+      continue;
+    }
+    if (!/^[a-z0-9][a-z0-9_-]*$/.test(cap) || clean.includes(cap)) {
+      continue;
+    }
+    clean.push(cap);
+  }
+  return clean;
+}
+
+/** Does a single peer record advertise `cap`? */
+export function peerSupports(peer, cap) {
+  return normalizeCaps(peer?.caps).includes(cap);
+}
+
+/**
+ * Can the whole room use `cap`?
+ *
+ * True only when this client advertises it and so does every peer. An empty
+ * room is vacuously true — there is nobody who could fail to understand.
+ *
+ * A hostile relay can edit these lists, so it is worth being explicit about what
+ * that buys it. Stripping capabilities forces the room back onto the per-peer
+ * path, which is the status quo and reveals nothing new. Adding a capability a
+ * peer never claimed makes senders encrypt in a form that peer cannot read —
+ * denial of service, visible immediately as a room that stopped working, and
+ * never a way to read plaintext. The strict-consensus rule is what keeps the
+ * damage on that side of the line.
+ *
+ * @param {Iterable<{caps?: string[]}>} peers - the room's peers, excluding self
+ * @param {string} cap
+ * @param {string[]} [own] - what this build advertises
+ */
+export function roomSupports(peers, cap, own = OWN_CAPABILITIES) {
+  if (!normalizeCaps(own).includes(cap)) {
+    return false;
+  }
+  for (const peer of peers) {
+    if (!peerSupports(peer, cap)) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/protocol/messages.js

@@ -7,6 +7,7 @@ export const MSG = {
   PEER_JOINED: 'peer_joined',
   PEER_LEFT: 'peer_left',
   ENCRYPTED_MESSAGE: 'encrypted_message',
+  GROUP_MESSAGE: 'group_message',
   ERROR: 'error',
   KEY_UPDATE: 'key_update',
   PEER_KEY_UPDATED: 'peer_key_updated',
@@ -47,19 +48,31 @@ function base(type) {
 
 // pqPublicKey (v3, optional): ML-KEM-768 encapsulation key for the hybrid
 // post-quantum handshake. Absent = classical-only peer (pre-2.3 client).
-export function createJoin(nickname, publicKeyB64, pqPublicKeyB64 = null) {
+// caps (optional): what this client can do beyond the baseline protocol. Omitted
+// when empty so the wire is byte-identical to a pre-capability client.
+export function createJoin(nickname, publicKeyB64, pqPublicKeyB64 = null, caps = null) {
   const msg = { ...base(MSG.JOIN), nickname, publicKey: publicKeyB64 };
   if (pqPublicKeyB64) {
     msg.pqPublicKey = pqPublicKeyB64;
   }
+  if (Array.isArray(caps) && caps.length > 0) {
+    msg.caps = [...caps];
+  }
   return msg;
 }
 
-export function createJoinAck(sessionId, peers, queuedCount = 0, room = 'general') {
+// serverCaps: what the relay itself can do, as opposed to what each peer can.
+// A client cannot advertise on the relay's behalf, and some features (group
+// fan-out) need the relay to play along. Omitted when empty so an ack from a
+// pre-capability relay and one from a relay with nothing to offer look alike.
+export function createJoinAck(sessionId, peers, queuedCount = 0, room = 'general', caps = null) {
   const ack = { ...base(MSG.JOIN_ACK), sessionId, peers, room };
   if (queuedCount > 0) {
     ack.queuedCount = queuedCount;
   }
+  if (Array.isArray(caps) && caps.length > 0) {
+    ack.serverCaps = [...caps];
+  }
   return ack;
 }
 
@@ -81,6 +94,30 @@ export function createPeerLeft(sessionId, nickname, room = null) {
   return msg;
 }
 
+// Room-addressed group message. One ciphertext for the whole room, fanned out by
+// the relay to the room's members.
+//
+// There is deliberately no `to` and no `from`. The relay routes on `room`, which
+// it already knows the sender is in, and it must not stamp a sender on the way
+// out — identity on this project's wire is only ever carried sealed. Recipients
+// resolve `keyId` to a member through the sender key they were handed over the
+// pairwise channel, so the label means something to members and nothing to the
+// relay.
+// `signature` is what makes the sender a *person* rather than just a member: the
+// chain is symmetric, so without it any member of the room could write in
+// anyone's name. See src/crypto/SenderKey.js.
+export function createGroupMessage(room, packet) {
+  return {
+    ...base(MSG.GROUP_MESSAGE),
+    room,
+    keyId: packet.keyId,
+    counter: packet.counter,
+    ciphertext: packet.ciphertext,
+    nonce: packet.nonce,
+    signature: packet.signature,
+  };
+}
+
 export function createEncryptedMessage(from, to, ciphertextB64, nonceB64) {
   return {
     ...base(MSG.ENCRYPTED_MESSAGE),
@@ -212,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/protocol/validators.js

@@ -6,6 +6,9 @@ import {
   ROOM_AUTH_PK_SIZE,
   ROOM_AUTH_SIG_SIZE,
   ROOM_CHALLENGE_NONCE_SIZE,
+  MAX_CAPABILITIES,
+  MAX_CAPABILITY_LENGTH,
+  SIGNATURE_SIZE,
 } from '../shared/constants.js';
 import { PQ_PUBLIC_KEY_SIZE } from '../crypto/PQHybrid.js';
 
@@ -49,6 +52,34 @@ function sanitizeNickname(nick) {
   return clean;
 }
 
+// Capability list off the wire. Absent is the normal case — every client before
+// capabilities existed — and means "supports nothing extra", not "malformed".
+// Anything present but misshapen is rejected rather than filtered: the relay
+// stores this list and hands it to other clients, and quietly forwarding junk
+// makes a peer look capable of something it never claimed.
+// Returns an array on success, or null to signal rejection.
+function sanitizeCapabilities(caps) {
+  if (caps === undefined || caps === null) {
+    return [];
+  }
+  if (!Array.isArray(caps) || caps.length > MAX_CAPABILITIES) {
+    return null;
+  }
+  const clean = [];
+  for (const cap of caps) {
+    if (!isString(cap) || cap.length === 0 || cap.length > MAX_CAPABILITY_LENGTH) {
+      return null;
+    }
+    if (!/^[a-z0-9][a-z0-9_-]*$/.test(cap)) {
+      return null;
+    }
+    if (!clean.includes(cap)) {
+      clean.push(cap);
+    }
+  }
+  return clean;
+}
+
 // ── Parse + validate incoming JSON ─────────────────────────────
 export function parseMessage(raw) {
   if (typeof raw === 'string' && raw.length > MAX_PAYLOAD_SIZE) {
@@ -100,7 +131,19 @@ export function validateJoin(msg) {
   if (msg.pqPublicKey !== undefined && !isValidBase64(msg.pqPublicKey, PQ_PUBLIC_KEY_SIZE)) {
     return { valid: false, error: 'Invalid post-quantum public key' };
   }
-  return { valid: true, nickname: nick, pqPublicKey: msg.pqPublicKey || null };
+  const capabilities = sanitizeCapabilities(msg.caps);
+  if (capabilities === null) {
+    return {
+      valid: false,
+      error: `Invalid capability list (max ${MAX_CAPABILITIES} entries of up to ${MAX_CAPABILITY_LENGTH} lowercase chars)`,
+    };
+  }
+  return {
+    valid: true,
+    nickname: nick,
+    pqPublicKey: msg.pqPublicKey || null,
+    capabilities,
+  };
 }
 
 // Sealed sender (protocol v2): the relay only ever sees the recipient and an
@@ -125,6 +168,35 @@ export function validateKeyUpdate(msg) {
   return { valid: true };
 }
 
+// Room-addressed group message. Like validateEncryptedMessage, the relay cannot
+// and must not inspect the content — it checks only what it needs to route:
+// a well-formed room, an opaque chain label, a sane counter, and a non-empty
+// envelope. Membership of `room` is the caller's check, not this one's.
+export function validateGroupMessage(msg) {
+  if (!isString(msg.room) || msg.room.length === 0 || msg.room.length > 30) {
+    return { valid: false, error: 'Invalid room name (1-30 chars)' };
+  }
+  if (!/^[a-zA-Z0-9_-]+$/.test(msg.room)) {
+    return { valid: false, error: 'Room name must be alphanumeric, dash or underscore' };
+  }
+  if (!isString(msg.keyId) || msg.keyId.length === 0 || msg.keyId.length > 64) {
+    return { valid: false, error: 'Invalid sender key id' };
+  }
+  if (!isNumber(msg.counter) || !Number.isInteger(msg.counter) || msg.counter < 0) {
+    return { valid: false, error: 'Invalid counter' };
+  }
+  if (!isValidBase64(msg.ciphertext) || !isValidBase64(msg.nonce)) {
+    return { valid: false, error: 'Missing or invalid group ciphertext' };
+  }
+  // Presence and size only. The relay holds no signing keys and could not
+  // verify this if it wanted to — that is the recipient's job, and the recipient
+  // does it before touching the ratchet.
+  if (!isValidBase64(msg.signature, SIGNATURE_SIZE)) {
+    return { valid: false, error: 'Missing or invalid group signature' };
+  }
+  return { valid: true, room: msg.room.toLowerCase() };
+}
+
 export function validateChangeRoom(msg) {
   if (!isString(msg.room) || msg.room.length === 0 || msg.room.length > 30) {
     return { valid: false, error: 'Invalid room name (1-30 chars)' };

package/src/server/MessageRouter.js

@@ -59,6 +59,15 @@ export class MessageRouter {
     }
   }
 
+  /**
+   * Spend one unit of a sender's per-second budget without routing anything.
+   * For paths that deliver themselves (the room fan-out) but must not get a
+   * cheaper allowance than route() gives the unicast path.
+   */
+  allowFrom(senderSessionId) {
+    return this.#checkRateLimit(senderSessionId);
+  }
+
   #checkRateLimit(sessionId) {
     const now = Date.now();
     const entry = this.#rateCounts.get(sessionId);

package/src/server/SessionManager.js

@@ -30,13 +30,14 @@ export class SessionManager {
     return this.#nicknames.has(nickname.toLowerCase());
   }
 
-  addSession(ws, nickname, publicKey, room = 'general', pqPublicKey = null) {
+  addSession(ws, nickname, publicKey, room = 'general', pqPublicKey = null, capabilities = []) {
     const sessionId = randomUUID();
     const session = {
       ws,
       nickname,
       publicKey,
       pqPublicKey, // ML-KEM-768 key, relayed verbatim (server never uses it)
+      capabilities, // advertised in JOIN, relayed verbatim — the relay never acts on these
       connectedAt: Date.now(),
       rooms: new Set(),
     };
@@ -104,6 +105,7 @@ export class SessionManager {
           nickname: session.nickname,
           publicKey: session.publicKey,
           ...(session.pqPublicKey ? { pqPublicKey: session.pqPublicKey } : {}),
+          ...(session.capabilities?.length ? { caps: [...session.capabilities] } : {}),
         });
       }
     }