ciphermesh 2.9.0 → 2.10.0

package/src/client/ChatController.js

@@ -61,6 +61,7 @@ import {
 } from '../shared/dnd.js';
 import { saveLastSession } from '../shared/lastSession.js';
 import { diagnose, formatDiagnosis } from '../shared/doctor.js';
+import { pluginsCommand } from '../shared/pluginCommand.js';
 import { COMMANDS } from './UI.js';
 
 const TYPING_SEND_INTERVAL = 2000; // debounce: max 1 typing event per 2s
@@ -1518,7 +1519,9 @@ export class ChatController {
         this.#ui.addInfoMessage(
           '  /panic [yes]         - Wipe EVERYTHING from disk and exit (duress)',
         );
-        this.#ui.addInfoMessage('  /plugins             - List loaded plugins');
+        this.#ui.addInfoMessage(
+          '  /plugins [allow <file>] - List plugins; approve one before it runs',
+        );
         this.#ui.addInfoMessage('  /quit                - Leave the chat');
         this.#ui.addInfoMessage('Tip: PageUp/PageDown scroll the chat history');
         this.#ui.addInfoMessage('Tip: shortcodes like :fire: become emoji — Tab autocompletes');
@@ -2603,16 +2606,17 @@ export class ChatController {
       }
 
       case '/plugins': {
-        if (!this.#pluginManager || this.#pluginManager.pluginCount === 0) {
-          this.#ui.addInfoMessage('No plugins loaded. Place .js files in ~/.ciphermesh/plugins/');
-        } else {
-          const names = this.#pluginManager.getPluginNames();
-          this.#ui.addInfoMessage(`Plugins loaded (${names.length}): ${names.join(', ')}`);
-          const cmds = this.#pluginManager.getCommandNames();
-          if (cmds.length > 0) {
-            this.#ui.addInfoMessage(`Commands: ${cmds.join(', ')}`);
+        pluginsCommand(this.#pluginManager, parts.slice(1)).then((lines) => {
+          for (const { kind, text } of lines) {
+            if (kind === 'error') {
+              this.#ui.addErrorMessage(text);
+            } else if (kind === 'system') {
+              this.#ui.addSystemMessage(text);
+            } else {
+              this.#ui.addInfoMessage(text);
+            }
           }
-        }
+        });
         break;
       }
 

package/src/client/UI.js

@@ -1798,7 +1798,10 @@ export class UI extends EventEmitter {
     this.#lines.push(line);
     this.#chatLog.log(line);
     this.#screen.render();
-    this.#lastSender = isSelfNow ? 'self' : nickname;
+    // The sentinel is written as an escape, not typed as a raw byte: a bare
+    // NUL anywhere in the source makes this entire file count as binary, and
+    // a binary file is skipped by grep and shown without a diff on GitHub.
+    this.#lastSender = isSelfNow ? '\u0000self' : nickname;
     if (!isSelfNow) {
       this.#noteIncoming(mentioned || isDM);
     }

package/src/client/index.js

@@ -210,7 +210,12 @@ await bootSequence([
   'XSalsa20-Poly1305 cipher',
   'Double Ratchet — forward secrecy',
   'TOFU trust store',
-  { label: 'Loading plugins', task: () => pluginManager.loadAll() },
+  {
+    label: 'Loading plugins',
+    // Only what the user approved. An unapproved file is left alone —
+    // importing it would already be running it.
+    task: () => pluginManager.loadAll(undefined, config.pluginsAllowed),
+  },
   {
     label: 'Connecting to relay',
     timeoutMs: 3500,

package/src/p2p/P2PChatController.js

@@ -41,6 +41,7 @@ import {
 } from '../shared/dnd.js';
 import { trustBadge } from '../shared/trust.js';
 import { tipAt, TIPS } from '../shared/tips.js';
+import { pluginsCommand } from '../shared/pluginCommand.js';
 import { COMMANDS } from '../client/UI.js';
 
 const TYPING_SEND_INTERVAL = 2000;
@@ -1388,7 +1389,9 @@ export class P2PChatController {
         this.#ui.addInfoMessage(
           '  /panic [yes]         - Wipe EVERYTHING from disk and exit (duress)',
         );
-        this.#ui.addInfoMessage('  /plugins             - List loaded plugins');
+        this.#ui.addInfoMessage(
+          '  /plugins [allow <file>] - List plugins; approve one before it runs',
+        );
         this.#ui.addInfoMessage('  /quit                - Exit the chat');
         break;
 
@@ -2058,16 +2061,17 @@ export class P2PChatController {
         break;
 
       case '/plugins': {
-        if (!this.#pluginManager || this.#pluginManager.pluginCount === 0) {
-          this.#ui.addInfoMessage('No plugins loaded. Put .js files in ~/.ciphermesh/plugins/');
-        } else {
-          const names = this.#pluginManager.getPluginNames();
-          this.#ui.addInfoMessage(`Plugins loaded (${names.length}): ${names.join(', ')}`);
-          const cmds = this.#pluginManager.getCommandNames();
-          if (cmds.length > 0) {
-            this.#ui.addInfoMessage(`Commands: ${cmds.join(', ')}`);
+        pluginsCommand(this.#pluginManager, parts.slice(1)).then((lines) => {
+          for (const { kind, text } of lines) {
+            if (kind === 'error') {
+              this.#ui.addErrorMessage(text);
+            } else if (kind === 'system') {
+              this.#ui.addSystemMessage(text);
+            } else {
+              this.#ui.addInfoMessage(text);
+            }
           }
-        }
+        });
         break;
       }
 

package/src/p2p/index.js

@@ -165,7 +165,12 @@ await bootSequence([
       }
     },
   },
-  { label: 'Loading plugins', task: () => pluginManager.loadAll() },
+  {
+    label: 'Loading plugins',
+    // Only what the user approved. An unapproved file is left alone —
+    // importing it would already be running it.
+    task: () => pluginManager.loadAll(undefined, config.pluginsAllowed),
+  },
 ]);
 
 // ── Initialize components ──────────────────────────────────────

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/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,
@@ -54,6 +55,7 @@ export class SecureWSServer {
   #heartbeatInterval;
   #connectionsByIp;
   #config;
+  #rateLimiter;
 
   constructor(sessionManager, messageRouter, offlineQueue, port, tlsOptions, config = null) {
     this.#sessionManager = sessionManager;
@@ -61,6 +63,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 +102,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 +137,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 +202,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);
 
@@ -971,6 +1002,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}`);
+}