ciphermesh 2.10.0 → 2.11.0

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),

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] } : {}),
         });
       }
     }

package/src/server/WebSocketServer.js

@@ -11,6 +11,7 @@ import {
   ROOM_CHALLENGE_TTL_MS,
   ROOM_AUTH_MAX_FAILS,
   ROOM_AUTH_FAIL_WINDOW_MS,
+  SERVER_CAPABILITIES,
 } from '../shared/constants.js';
 import {
   MSG,
@@ -32,6 +33,7 @@ import {
   parseMessage,
   validateJoin,
   validateEncryptedMessage,
+  validateGroupMessage,
   validateKeyUpdate,
   validateChangeRoom,
   validateJoinRoom,
@@ -230,6 +232,10 @@ export class SecureWSServer {
         this.#handleEncryptedMessage(ws, msg);
         break;
 
+      case MSG.GROUP_MESSAGE:
+        this.#handleGroupMessage(ws, msg);
+        break;
+
       case MSG.KEY_UPDATE:
         this.#handleKeyUpdate(ws, msg);
         break;
@@ -303,6 +309,7 @@ export class SecureWSServer {
       msg.publicKey,
       room,
       validation.pqPublicKey,
+      validation.capabilities,
     );
     ws.sessionId = sessionId;
     ws.hasJoined = true;
@@ -313,7 +320,7 @@ export class SecureWSServer {
 
     // Send ACK with peer list (room-scoped)
     const peers = this.#sessionManager.getRoomPeers(room, sessionId);
-    const joinAck = createJoinAck(sessionId, peers, queued.length, room);
+    const joinAck = createJoinAck(sessionId, peers, queued.length, room, SERVER_CAPABILITIES);
     const ownerSid = this.#sessionManager.getRoomOwner(room);
     if (ownerSid) {
       const ownerSession = this.#sessionManager.getSession(ownerSid);
@@ -340,6 +347,7 @@ export class SecureWSServer {
         nickname: validation.nickname,
         publicKey: msg.publicKey,
         ...(validation.pqPublicKey ? { pqPublicKey: validation.pqPublicKey } : {}),
+        ...(validation.capabilities.length ? { caps: [...validation.capabilities] } : {}),
       }),
       sessionId,
     );
@@ -374,6 +382,63 @@ export class SecureWSServer {
     this.#messageRouter.route(ws.sessionId, msg);
   }
 
+  // One ciphertext in, one copy to each member of the room. The relay reads the
+  // room and nothing else: no `to` to route by, and no `from` to stamp on the
+  // way out — a room-addressed envelope must not become the one place the relay
+  // asserts who is speaking.
+  #handleGroupMessage(ws, msg) {
+    if (!ws.hasJoined || !ws.sessionId) {
+      ws.send(JSON.stringify(createError(ERR.INVALID_MESSAGE, 'JOIN first')));
+      return;
+    }
+
+    if (this.#sessionManager.isMuted(ws.sessionId)) {
+      ws.send(JSON.stringify(createError(ERR.INVALID_MESSAGE, 'You are muted')));
+      return;
+    }
+
+    const validation = validateGroupMessage(msg);
+    if (!validation.valid) {
+      ws.send(JSON.stringify(createError(ERR.INVALID_MESSAGE, validation.error)));
+      return;
+    }
+
+    // A member may only address a room it is in. Without this, one connection
+    // could inject into every room on the hub at once — the per-peer path has no
+    // equivalent, because it needs a sessionId it could only have been told.
+    if (!this.#sessionManager.isInRoom(ws.sessionId, validation.room)) {
+      ws.send(JSON.stringify(createError(ERR.INVALID_MESSAGE, 'Not in that room')));
+      return;
+    }
+
+    // Same per-sender budget as the unicast path. One frame in now costs the
+    // relay N frames out instead of one, so the limit that used to be applied
+    // N times per line is applied once — charging less here than there would
+    // turn the saving into an amplifier.
+    if (!this.#messageRouter.allowFrom(ws.sessionId)) {
+      ws.send(JSON.stringify(createError(ERR.RATE_LIMITED, 'Too many messages per second')));
+      return;
+    }
+
+    // Deliberately NOT queued for absent members, unlike the unicast path.
+    //
+    // A member who was away could not read it anyway: a sender key handed over
+    // on their return serialises the chain at its *current* counter, so anything
+    // sent while they were gone stays shut — the forward secrecy the ratchet
+    // buys, pinned in chat-controller.test.js. Queueing would therefore store
+    // ciphertext on the relay that provably nobody can open: all of the cost and
+    // the liability of holding it, and none of the delivery.
+    //
+    // The unicast queue survives because an envelope addressed to a peer is
+    // still openable when they come back with the same key. That is not true
+    // here, and it is the difference that decides it.
+    delete msg.from;
+    this.#sessionManager.broadcastToRoom(validation.room, msg, ws.sessionId);
+    // Never log the sender or the room membership this reveals — only that a
+    // fan-out happened. Correlating would defeat what sealed sender buys.
+    log.debug('group message fanned out');
+  }
+
   #handleKeyUpdate(ws, msg) {
     if (!ws.hasJoined || !ws.sessionId) {
       ws.send(JSON.stringify(createError(ERR.INVALID_MESSAGE, 'JOIN first')));

package/src/shared/constants.js

@@ -1,5 +1,40 @@
 export const PROTOCOL_VERSION = 2; // v2: sealed sender (encrypted_message carries `sealed`, no `from`)
 
+// ── Capability negotiation ─────────────────────────────────────
+// PROTOCOL_VERSION is an exact-equality gate, so it cannot express "newer, but
+// still able to talk to you". Capabilities fill that gap: a client lists what it
+// can do in JOIN, the relay hands the list on verbatim with the peer list, and a
+// feature turns on only when every member of the room advertises it. Absent or
+// empty means an older peer, which is the safe default rather than an error.
+export const CAP = {
+  // Group encryption on the relay path — one ciphertext for the whole room
+  // instead of one sealed envelope per peer. See
+  // docs/design/sender-keys-on-relay.md.
+  //
+  // From a client it means "I can *receive* a group message": I accept a sender
+  // key over the pairwise channel and can decrypt what that chain produces.
+  // From the relay it means "I can fan a room-addressed message out". Receive
+  // and fan-out land a release before anyone sends, so that by the time a sender
+  // exists, every advertised room can already read it.
+  SENDER_KEYS: 'sk1',
+};
+
+// What this client advertises. SENDER_KEYS is honest here: the receive path
+// exists. Nothing sends group messages yet.
+export const OWN_CAPABILITIES = [CAP.SENDER_KEYS];
+
+// What the relay advertises, in join_ack. A client cannot promise this on the
+// relay's behalf — the fan-out is the relay's job — so a sender has to check the
+// room *and* the hub it is sitting on before switching paths.
+export const SERVER_CAPABILITIES = [CAP.SENDER_KEYS];
+
+// Bounds. This list arrives from a public hub, so it is attacker-controlled.
+export const MAX_CAPABILITIES = 16;
+export const MAX_CAPABILITY_LENGTH = 24;
+
+// Ed25519 detached signature on a group message (src/crypto/SenderKey.js).
+export const SIGNATURE_SIZE = 64;
+
 // Network
 export const SERVER_PORT = 3600;
 export const HEARTBEAT_INTERVAL_MS = 30_000;