ciphermesh 2.9.0 → 2.11.0

package/src/server/ConnectionGuard.js

@@ -0,0 +1,158 @@
+// Limits on how *fast* a source may connect, and how much it may push once in.
+//
+// The existing caps bound how many sockets exist at once and how many messages
+// a session sends per second. Neither bounds the two things that actually cost
+// the relay:
+//
+//   1. Handshake churn. Connect, run the hybrid handshake, disconnect, repeat.
+//      Every attempt makes the relay do X25519 and ML-KEM-768 work while the
+//      attacker does almost nothing, and a concurrency cap never trips because
+//      the sockets are never held open.
+//
+//   2. Bandwidth. The message limit counts messages, and messages are padded
+//      into buckets up to 32 KiB, so a session at the limit is a multi-megabit
+//      stream. The resource that runs out is bytes, not messages.
+//
+// Both are token buckets, and both take their clock as an argument so the tests
+// can move time without sleeping.
+import { MAX_PAYLOAD_SIZE } from '../shared/constants.js';
+
+/** A bucket that refills continuously rather than resetting on a boundary. */
+class TokenBucket {
+  #capacity;
+  #perMs;
+  #tokens;
+  #last;
+
+  constructor(capacity, perMs, now) {
+    this.#capacity = capacity;
+    this.#perMs = perMs;
+    this.#tokens = capacity;
+    this.#last = now;
+  }
+
+  /** Spend `cost` if it is there. Returns false without spending if it is not. */
+  take(cost, now) {
+    // A fixed window lets a caller spend the whole allowance at the end of one
+    // window and again at the start of the next, which is twice the intended
+    // rate for a moment. Refilling by elapsed time has no such seam.
+    this.#tokens = Math.min(this.#capacity, this.#tokens + (now - this.#last) * this.#perMs);
+    this.#last = now;
+
+    if (this.#tokens < cost) {
+      return false;
+    }
+    this.#tokens -= cost;
+    return true;
+  }
+
+  /** True once the bucket is full again — the entry is then worth forgetting. */
+  idle(now) {
+    return this.#tokens + (now - this.#last) * this.#perMs >= this.#capacity;
+  }
+}
+
+/**
+ * How long a source is refused after going too fast, by how many times it has
+ * done so. Short enough that a burst of reconnects after a relay restart is
+ * forgiven; long enough that a script grinding away gets nothing done.
+ */
+const BAN_STEPS_MS = [60_000, 300_000, 1_800_000];
+
+/** Strikes are forgotten after this long behaving, so the ban never ratchets up forever. */
+const STRIKE_DECAY_MS = 3_600_000;
+
+export class ConnectionRateLimiter {
+  #perMinute;
+  #entries = new Map();
+
+  constructor(perMinute) {
+    this.#perMinute = perMinute;
+  }
+
+  /**
+   * @returns {{allowed: boolean, retryAfterMs: number}} — `retryAfterMs` is
+   *   worth telling the client, since a well-behaved one can then back off
+   *   instead of hammering and extending its own ban.
+   */
+  check(ip, now = Date.now()) {
+    let entry = this.#entries.get(ip);
+    if (!entry) {
+      entry = {
+        bucket: new TokenBucket(this.#perMinute, this.#perMinute / 60_000, now),
+        strikes: 0,
+        bannedUntil: 0,
+        lastStrike: 0,
+      };
+      this.#entries.set(ip, entry);
+    }
+
+    if (now < entry.bannedUntil) {
+      return { allowed: false, retryAfterMs: entry.bannedUntil - now };
+    }
+
+    if (entry.bucket.take(1, now)) {
+      return { allowed: true, retryAfterMs: 0 };
+    }
+
+    // Behaving for an hour wipes the record. Without this a long-lived NAT
+    // gateway would collect strikes over months and end up permanently at the
+    // longest ban for one bad afternoon.
+    if (entry.lastStrike && now - entry.lastStrike > STRIKE_DECAY_MS) {
+      entry.strikes = 0;
+    }
+
+    const step = BAN_STEPS_MS[Math.min(entry.strikes, BAN_STEPS_MS.length - 1)];
+    entry.strikes += 1;
+    entry.lastStrike = now;
+    entry.bannedUntil = now + step;
+
+    return { allowed: false, retryAfterMs: step };
+  }
+
+  /**
+   * Forget sources that have gone quiet. Called on a timer — without it the map
+   * is a slow memory leak keyed by anything that ever connected, which is a
+   * denial of service of its own.
+   */
+  prune(now = Date.now()) {
+    for (const [ip, entry] of this.#entries) {
+      if (now < entry.bannedUntil) {
+        continue;
+      }
+      if (entry.lastStrike && now - entry.lastStrike <= STRIKE_DECAY_MS) {
+        continue;
+      }
+      if (entry.bucket.idle(now)) {
+        this.#entries.delete(ip);
+      }
+    }
+  }
+
+  get size() {
+    return this.#entries.size;
+  }
+}
+
+/**
+ * A sustained bytes-per-second budget for one connection, with a burst
+ * allowance so a legitimate file transfer is not mistaken for an attack.
+ *
+ * One of these lives on the socket, so it disappears with it and there is
+ * nothing to prune.
+ */
+export class ByteBudget {
+  #bucket;
+
+  constructor(perSecond, burst, now = Date.now()) {
+    // A burst smaller than one frame could never be paid for, so the connection
+    // would wedge shut instead of being throttled. Callers get the larger of
+    // the two rather than a silently broken socket.
+    this.#bucket = new TokenBucket(Math.max(burst, MAX_PAYLOAD_SIZE), perSecond / 1000, now);
+  }
+
+  /** @returns {boolean} false when the connection has outrun its budget. */
+  allow(bytes, now = Date.now()) {
+    return this.#bucket.take(bytes, now);
+  }
+}

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

@@ -2,6 +2,7 @@ import { createServer as createHttpsServer } from 'node:https';
 import { randomBytes } from 'node:crypto';
 import { WebSocketServer as WSServer } from 'ws';
 import { createLogger } from '../shared/logger.js';
+import { ByteBudget, ConnectionRateLimiter } from './ConnectionGuard.js';
 import {
   HEARTBEAT_INTERVAL_MS,
   MAX_PAYLOAD_SIZE,
@@ -10,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,
@@ -31,6 +33,7 @@ import {
   parseMessage,
   validateJoin,
   validateEncryptedMessage,
+  validateGroupMessage,
   validateKeyUpdate,
   validateChangeRoom,
   validateJoinRoom,
@@ -54,6 +57,7 @@ export class SecureWSServer {
   #heartbeatInterval;
   #connectionsByIp;
   #config;
+  #rateLimiter;
 
   constructor(sessionManager, messageRouter, offlineQueue, port, tlsOptions, config = null) {
     this.#sessionManager = sessionManager;
@@ -61,6 +65,7 @@ export class SecureWSServer {
     this.#offlineQueue = offlineQueue;
     this.#connectionsByIp = new Map();
     this.#config = config || parseServerConfig();
+    this.#rateLimiter = new ConnectionRateLimiter(this.#config.connectionRatePerMinute);
 
     if (tlsOptions) {
       this.#httpsServer = createHttpsServer(tlsOptions);
@@ -99,6 +104,21 @@ export class SecureWSServer {
       return;
     }
 
+    // How FAST this source is connecting, before how many it holds. Churn —
+    // connect, handshake, disconnect, repeat — never trips the concurrency cap
+    // below, and each attempt costs an X25519 and an ML-KEM-768 operation. The
+    // socket is already upgraded by the time we get here, but closing now is
+    // what matters: the expensive work happens at JOIN, and this never reaches
+    // it.
+    const rate = this.#rateLimiter.check(ip);
+    if (!rate.allowed) {
+      log.warn(`Connecting too fast from ${ip}, refusing for ${rate.retryAfterMs}ms`);
+      // Tell them how long, so a well-behaved client backs off instead of
+      // hammering and extending its own ban.
+      ws.close(1013, `Try again in ${Math.ceil(rate.retryAfterMs / 1000)}s`);
+      return;
+    }
+
     // Global connection cap (the new socket is already counted in clients).
     if (this.#wss.clients.size > this.#config.maxConnectionsTotal) {
       ws.close(1013, 'Server full');
@@ -119,6 +139,8 @@ export class SecureWSServer {
     ws.hasJoined = false;
     ws.msgWindowStart = Date.now();
     ws.msgCount = 0;
+    // Bytes, not messages. Lives on the socket, so it goes away with it.
+    ws.byteBudget = new ByteBudget(this.#config.maxBytesPerSecond, this.#config.maxBytesBurst);
 
     // Drop sockets that connect but never JOIN (slowloris / resource hold).
     ws.joinTimer = setTimeout(() => {
@@ -182,6 +204,17 @@ export class SecureWSServer {
       return;
     }
 
+    // Charged before parsing: the bytes have already been received and buffered
+    // by this point, so refusing to spend effort on them is the only saving
+    // left, and a sender that ignores the warning is disconnected rather than
+    // allowed to keep paying nothing.
+    if (!ws.byteBudget.allow(data.length ?? 0)) {
+      log.warn(`Byte budget exhausted for ${ws.clientIp}, closing`);
+      ws.send(JSON.stringify(createError(ERR.RATE_LIMITED, 'Sending too much, too fast')));
+      ws.close(1008, 'Byte budget exhausted');
+      return;
+    }
+
     const raw = data.toString('utf-8');
     const { valid, error, msg } = parseMessage(raw);
 
@@ -199,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;
@@ -272,6 +309,7 @@ export class SecureWSServer {
       msg.publicKey,
       room,
       validation.pqPublicKey,
+      validation.capabilities,
     );
     ws.sessionId = sessionId;
     ws.hasJoined = true;
@@ -282,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);
@@ -309,6 +347,7 @@ export class SecureWSServer {
         nickname: validation.nickname,
         publicKey: msg.publicKey,
         ...(validation.pqPublicKey ? { pqPublicKey: validation.pqPublicKey } : {}),
+        ...(validation.capabilities.length ? { caps: [...validation.capabilities] } : {}),
       }),
       sessionId,
     );
@@ -343,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')));
@@ -971,6 +1067,10 @@ export class SecureWSServer {
         ws.isAlive = false;
         ws.ping();
       }
+      // Forget quiet sources. Without this the rate limiter's map is keyed by
+      // everything that ever connected, which is a slow leak an attacker can
+      // drive on purpose.
+      this.#rateLimiter.prune();
     }, HEARTBEAT_INTERVAL_MS);
   }
 

package/src/server/config.js

@@ -8,6 +8,9 @@ import {
   MAX_CONNECTIONS_TOTAL,
   MAX_CONNECTIONS_PER_IP,
   MESSAGE_RATE_LIMIT_PER_SECOND,
+  CONNECTION_RATE_PER_MINUTE,
+  MAX_BYTES_PER_SECOND,
+  MAX_BYTES_BURST,
 } from '../shared/constants.js';
 
 const DEFAULTS = {
@@ -18,6 +21,12 @@ const DEFAULTS = {
   // single client could exhaust the room table on its own.
   maxRoomsTotal: 500,
   maxRoomsPerSession: 10,
+  // How fast one source may open connections, as opposed to how many it may
+  // hold at once. The concurrency cap above never trips against churn.
+  connectionRatePerMinute: CONNECTION_RATE_PER_MINUTE,
+  // Bytes, not messages — see ConnectionGuard.
+  maxBytesPerSecond: MAX_BYTES_PER_SECOND,
+  maxBytesBurst: MAX_BYTES_BURST,
 };
 
 function positiveInt(raw, fallback) {
@@ -73,6 +82,12 @@ export function parseServerConfig(env = process.env) {
     ),
     maxRoomsTotal: positiveInt(env.MAX_ROOMS_TOTAL, DEFAULTS.maxRoomsTotal),
     maxRoomsPerSession: positiveInt(env.MAX_ROOMS_PER_SESSION, DEFAULTS.maxRoomsPerSession),
+    connectionRatePerMinute: positiveInt(
+      env.CONNECTION_RATE_PER_MINUTE,
+      DEFAULTS.connectionRatePerMinute,
+    ),
+    maxBytesPerSecond: positiveInt(env.MAX_BYTES_PER_SECOND, DEFAULTS.maxBytesPerSecond),
+    maxBytesBurst: positiveInt(env.MAX_BYTES_BURST, DEFAULTS.maxBytesBurst),
     // Behind a reverse proxy every connection arrives from the proxy, so the
     // per-IP cap would apply to the proxy itself and protect nobody. Only
     // trust the forwarded header when the operator says there IS a proxy —

package/src/server/index.js

@@ -11,6 +11,7 @@ import { OfflineQueue } from './OfflineQueue.js';
 import { SecureWSServer } from './WebSocketServer.js';
 import { startPresenceServer } from './presence.js';
 import { loadOrGenerateCerts } from './CertManager.js';
+import { preflight, formatPreflight } from './preflight.js';
 
 const log = createLogger('server');
 
@@ -53,6 +54,23 @@ function getLocalIPs() {
   return { ips, inDocker };
 }
 
+// ── Configuration check ────────────────────────────────────────
+// `--check` validates and exits without opening a socket, so it is safe to run
+// against a live host. The same findings are printed at every startup too,
+// because a warning you have to ask for is a warning nobody sees.
+const findings = preflight();
+if (process.argv.includes('--check')) {
+  for (const line of formatPreflight(findings)) console.log(line);
+  // Non-zero on an error so a deploy script can gate on it. Warnings do not
+  // fail, or the check becomes something people learn to ignore.
+  process.exit(findings.some((f) => f.level === 'error') ? 1 : 0);
+}
+
+for (const finding of findings) {
+  if (finding.level === 'error') log.error(finding.text);
+  else log.warn(finding.text);
+}
+
 // ── Bootstrap ──────────────────────────────────────────────────
 const port = parseInt(process.env.PORT, 10) || SERVER_PORT;
 

package/src/server/preflight.js

@@ -0,0 +1,96 @@
+import { parseServerConfig } from './config.js';
+import { CONNECTION_RATE_PER_MINUTE, MAX_CONNECTIONS_PER_IP } from '../shared/constants.js';
+
+/**
+ * What is wrong with this relay's configuration, before it starts serving.
+ *
+ * The deploy guide already explains every footgun here. That is the problem: a
+ * document is read once, by whoever set the machine up, and never again — while
+ * the misconfiguration lasts as long as the machine does. The worst of them,
+ * `TRUST_PROXY` left off behind a reverse proxy, is invisible from the outside:
+ * everything works, the per-IP cap and the banlist simply apply to the proxy
+ * and protect nobody. Nothing breaks, so nobody looks.
+ *
+ * Pure and exported so `--check` and startup share one implementation and
+ * cannot disagree about what counts as a problem.
+ *
+ * @returns {Array<{level: 'error'|'warn', text: string}>}
+ */
+export function preflight(env = process.env) {
+  const config = parseServerConfig(env);
+  const findings = [];
+
+  const error = (text) => findings.push({ level: 'error', text });
+  const warn = (text) => findings.push({ level: 'warn', text });
+
+  // Behind a proxy, every connection arrives from the proxy. The per-IP limits
+  // then bound the proxy's own traffic, which is all of it.
+  const behindProxy = Boolean(env.CIPHERMESH_DOMAIN || env.BEHIND_PROXY);
+  if (behindProxy && !config.trustProxy) {
+    error(
+      'TRUST_PROXY is off but this looks like it is behind a reverse proxy. ' +
+        'Every connection will appear to come from the proxy, so the per-IP cap, ' +
+        'the connection rate limit and the banlist protect nobody.',
+    );
+  }
+
+  // And the mirror image, which is worse: trusting a header anyone can set.
+  if (config.trustProxy && !behindProxy) {
+    warn(
+      'TRUST_PROXY is on. If this relay is reachable directly, a client can forge ' +
+        'X-Forwarded-For and walk straight past the per-IP cap and the banlist.',
+    );
+  }
+
+  const isPublic = behindProxy || env.PUBLIC_RELAY === 'true';
+  if (isPublic) {
+    // The defaults are generous because the project started on LANs, where the
+    // people connecting are in the same building as the machine.
+    if (config.maxConnectionsPerIp >= MAX_CONNECTIONS_PER_IP) {
+      warn(
+        `MAX_CONNECTIONS_PER_IP is ${config.maxConnectionsPerIp}, the LAN default. ` +
+          'On the open internet 3-5 is plenty and costs real users nothing.',
+      );
+    }
+    if (config.connectionRatePerMinute >= CONNECTION_RATE_PER_MINUTE) {
+      warn(
+        `CONNECTION_RATE_PER_MINUTE is ${config.connectionRatePerMinute}, the LAN default. ` +
+          '10-20 still leaves room for a reconnect storm after a restart.',
+      );
+    }
+    if (env.TLS === 'false' && !behindProxy) {
+      error('TLS is disabled and nothing appears to be terminating it in front.');
+    }
+  }
+
+  if (env.LOG_LEVEL?.toLowerCase() === 'debug') {
+    warn(
+      'LOG_LEVEL is debug. Nothing logs message content at any level — there is a ' +
+        'test that proves it — but debug writes more metadata to disk than a ' +
+        'running relay needs to.',
+    );
+  }
+
+  // A banlist file that is not there is almost always a mount that is not
+  // there, and it fails open: everyone gets in and nothing says otherwise.
+  if (env.BANNED_IPS_FILE && config.bannedIps.size === 0) {
+    warn(
+      'BANNED_IPS_FILE is set but no addresses were loaded from it. ' +
+        'If the file is missing or unreadable the banlist is simply empty.',
+    );
+  }
+
+  if (env.MOTD_FILE && !config.motd) {
+    warn('MOTD_FILE is set but nothing was read from it.');
+  }
+
+  return findings;
+}
+
+/** Human-readable lines for `--check`. */
+export function formatPreflight(findings) {
+  if (findings.length === 0) {
+    return ['Configuration looks fine.'];
+  }
+  return findings.map(({ level, text }) => `${level === 'error' ? 'ERROR' : 'warn '}  ${text}`);
+}