@blamejs/core 0.18.54 → 0.18.56

package/lib/mail-server-net.js

@@ -3,6 +3,7 @@
 "use strict";
 
 var codepointClass = require("./codepoint-class");
+var bCrypto        = require("./crypto");
 
 // mail-server-net — the TCP-listener lifecycle shared by the mailbox / transfer
 // servers (b.mail.server.imap / pop3 / mx / managesieve / submission). Each of
@@ -16,6 +17,14 @@ var codepointClass = require("./codepoint-class");
 // EACCES) rejects the listen promise instead of crashing the process. That, plus
 // the listening/server state, is what createTcpListener owns.
 
+// The listener's own ceiling when an operator names none. Every mail listener
+// shares it, so a deployment that raises or lowers it does so in one place and
+// the five listeners cannot drift apart on what "too many" means. Set well
+// above any single-host mail deployment's working set and far below what an
+// unbounded accept loop will take: the point is that a ceiling EXISTS, since
+// the per-address cap alone leaves the total at (cap x source addresses).
+var DEFAULT_MAX_CONNECTIONS = 1024;
+
 // createTcpListener(net, cfg) — build a listener lifecycle.
 //   cfg.defaultPort      port used when listenOpts.port is omitted (an explicit
 //                        0 is honored, for an ephemeral test bind).
@@ -26,6 +35,15 @@ var codepointClass = require("./codepoint-class");
 //   cfg.listeningEvent   the "...listening" audit action.
 //   cfg.listeningExtra   optional () => object merged onto the listening event
 //                        payload (Submission reports implicitTls).
+//   cfg.maxConnections   the listener's own ceiling on concurrently accepted
+//                        sockets. The per-address cap in b.mail.server.rateLimit
+//                        bounds ONE peer; it says nothing about how many peers
+//                        there are, so the process-wide total was the per-address
+//                        cap times however many source addresses the caller could
+//                        speak from — a number a botnet, a NAT pool or a single
+//                        v6 /64 makes large. Enforced by the runtime, which closes
+//                        the excess socket before handleConnection ever sees it,
+//                        so a refusal costs no descriptor and no state machine.
 // Returns { listen, getServer, isListening, markClosed } — the server wires its
 // own close() through getServer()/isListening()/markClosed().
 function createTcpListener(net, cfg) {
@@ -40,6 +58,7 @@ function createTcpListener(net, cfg) {
     var port = listenOpts.port === undefined ? cfg.defaultPort : listenOpts.port;
     var address = listenOpts.address || "0.0.0.0";
     server = net.createServer(function (socket) { cfg.handleConnection(socket); });
+    server.maxConnections = cfg.maxConnections || DEFAULT_MAX_CONNECTIONS;
     return new Promise(function (resolve, reject) {
       server.once("error", reject);
       server.listen(port, address, function () {
@@ -110,6 +129,7 @@ function createStoreServer(net, cfg) {
   var ErrorClass = cfg.errorClass;
   var listener = createTcpListener(net, {
     defaultPort:      cfg.defaultPort,
+    maxConnections:   cfg.maxConnections,
     handleConnection: cfg.handleConnection,
     errorFactory:     function (code, message) { return new ErrorClass(cfg.errorCodePrefix + code, message); },
     emit:             cfg.emit,
@@ -122,7 +142,137 @@ function createStoreServer(net, cfg) {
       closedEvent: cfg.eventBase + ".closed",
     });
   }
-  return { listen: listener.listen, close: close };
+  return {
+    listen:          listener.listen,
+    close:           close,
+    connectionCount: function () { return cfg.connections.size; },
+  };
+}
+
+// trackConnection(socket, cfg) — the other half of admitConnection, and the
+// reason it is here rather than written out per listener.
+//
+// A connection occupies two ledgers: the rate limiter's per-address count, and
+// the listener's live-socket set that shutdown drains. Both are released by the
+// SAME event — the socket closing — and it does not matter who closed it. Five
+// listeners each wrote that pairing by hand and one of them registered only the
+// release, so a peer that opened a connection, took the greeting and dropped TCP
+// freed its rate-limit slot (and could reconnect at once) while its set entry
+// stayed forever. Nothing authenticates before that point, so the growth was
+// unauthenticated and unbounded.
+//
+// Registering both in one handler is what makes the pair impossible to
+// half-write.
+//   cfg.connections    the listener's live-socket Set.
+//   cfg.rateLimit      the resolved b.mail.server.rateLimit.
+//   cfg.remoteAddress  the address admitConnection returned.
+//   cfg.closeSource    optional socket whose "close" drives teardown, when the
+//                      tracked socket is a wrapper (Submission's implicit-TLS
+//                      path tracks the TLSSocket but the raw socket is the one
+//                      that carries the FIN).
+function trackConnection(socket, cfg) {
+  cfg.connections.add(socket);
+  var source = cfg.closeSource || socket;
+  source.once("close", function () {
+    cfg.rateLimit.releaseConnection(cfg.remoteAddress);
+    cfg.connections.delete(socket);
+  });
+}
+
+// createBodyRateWindow(rateLimit) — the body-rate floor, measured over BOUNDED
+// windows instead of the whole transfer.
+//
+// A lifetime average lets an early burst pay for an arbitrarily slow tail: at
+// the default 100 B/s an 8 MiB burst buys about a day of credit and 50 MiB buys
+// six, which a peer spends holding a connection and its slot in the per-address
+// cap while sending a byte at a time. The floor was enforced and still
+// bypassable, which is the worse of the two states — it reads as covered.
+//
+// Each window has to meet the floor on its own, so nothing sent earlier pays
+// for what is sent now. A window only rolls forward once it has run long enough
+// to be a real judgement; inside that stretch no verdict is reached, so a
+// sender pausing to read from its own spool is not cut off for the pause, and a
+// fast chunk cannot keep resetting the clock to dodge the next measurement.
+//
+// `now` is a parameter rather than a call to the clock so the whole thing can
+// be driven across days of simulated time without waiting for them.
+//   rateLimit  the resolved b.mail.server.rateLimit (owns the floor + grace).
+function createBodyRateWindow(rateLimit) {
+  var windowStart = 0;
+  var windowBytes = 0;
+  return {
+    // Open the first window. `bytesSeen` is the caller's running total AT THIS
+    // MOMENT, which becomes the baseline every later reading is measured
+    // against — so the caller is free to keep one connection-lifetime counter
+    // incremented at the wire boundary rather than a per-transfer one. That
+    // matters where a listener re-feeds part of a chunk through its own parser:
+    // a counter maintained inside the parser credits those bytes twice, and a
+    // peer that pipelines a one-byte payload with the next command gets roughly
+    // double the rate it is actually sending.
+    start: function (now, bytesSeen) {
+      windowStart = now;
+      windowBytes = bytesSeen || 0;
+    },
+    // `bytesSeen` is the running total for the whole body; the window's own
+    // count is derived, so the caller keeps one counter rather than two.
+    starved: function (bytesSeen, now) {
+      var elapsed = now - windowStart;
+      if (rateLimit.bodyRateStarved(bytesSeen - windowBytes, elapsed)) return true;
+      // The limiter says how long a window must run before rolling, because the
+      // limiter is what decides when a measurement is old enough to mean
+      // something. Rolling on a number held HERE would ask a limiter that
+      // judges over a longer stretch only ever before it can answer: every call
+      // returning "too early", the window resetting underneath it, and its rate
+      // protection silently disabled while looking wired.
+      if (elapsed >= rateLimit.bodyRateWindowMs()) {
+        windowStart = now;
+        windowBytes = bytesSeen;
+      }
+      return false;
+    },
+  };
+}
+
+// acceptConnection(rawSocket, cfg) — everything a listener does between the TCP
+// accept and its own state machine: gate the address, mint the connection id,
+// wrap the socket if the protocol starts in TLS, and enter both ledgers.
+//
+// Every listener performed these four steps in the same order, and the parts
+// that differ between them are three strings and an optional wrap. Keeping the
+// order in one place is what stops a fifth listener from being written with one
+// of the steps missing, which is how the tracking-set entry and the rate-limit
+// slot came apart in the first place.
+//
+// Returns null when the address was refused — the caller returns immediately;
+// the refusal line and teardown are already done.
+//   cfg.rateLimit      the resolved b.mail.server.rateLimit.
+//   cfg.connections    the listener's live-socket Set.
+//   cfg.emit           the listener's audit emitter.
+//   cfg.refusedEvent   the "<...>.rate_limit_refused" audit action.
+//   cfg.refusalLine    the protocol's refusal bytes.
+//   cfg.idPrefix       "imapconn-" / "mxconn-" / … prefix for the connection id.
+//   cfg.wrap           optional (rawSocket) => socket, for a protocol that
+//                      starts inside TLS. The RAW socket still drives teardown:
+//                      a handshake that never completes closes it without the
+//                      wrapper ever being established.
+function acceptConnection(rawSocket, cfg) {
+  var remoteAddress = admitConnection(rawSocket, cfg.rateLimit, cfg.emit, {
+    refusedEvent: cfg.refusedEvent,
+    refusalLine:  cfg.refusalLine,
+  });
+  if (remoteAddress === null) return null;
+  var socket = cfg.wrap ? cfg.wrap(rawSocket) : rawSocket;
+  trackConnection(socket, {
+    connections:   cfg.connections,
+    rateLimit:     cfg.rateLimit,
+    remoteAddress: remoteAddress,
+    closeSource:   socket === rawSocket ? null : rawSocket,
+  });
+  return {
+    socket:        socket,
+    remoteAddress: remoteAddress,
+    connectionId:  cfg.idPrefix + bCrypto.generateToken(8),                                           // connection-id length
+  };
 }
 
 // admitConnection(socket, rateLimit, emit, cfg) — the per-connection rate-limit
@@ -299,6 +449,10 @@ module.exports = {
   runSaslStep:       runSaslStep,
   createStoreServer: createStoreServer,
   admitConnection:   admitConnection,
+  trackConnection:   trackConnection,
+  acceptConnection:  acceptConnection,
+  createBodyRateWindow: createBodyRateWindow,
+  DEFAULT_MAX_CONNECTIONS: DEFAULT_MAX_CONNECTIONS,
   validateDomainHardened: validateDomainHardened,
   saslChallengeOrNull: saslChallengeOrNull,
   replyTextOrFallback:  replyTextOrFallback,

package/lib/mail-server-pop3.js

@@ -52,9 +52,10 @@
  *     `authFailuresPerIpPer15Min` cap applies to USER+PASS / APOP /
  *     AUTH refusals.
  *
- *   - **Slow-loris on RETR / TOP** — per-connection `idleTimeoutMs`
- *     bounds dead connections; `b.mail.server.rateLimit.minBytesPerSecond`
- *     bounds trickle-receive class.
+ *   - **Slow-loris** — per-connection `idleTimeoutMs` bounds a peer that
+ *     stops making progress, in either direction: a client that sends no
+ *     further command, and one that stops taking a RETR / TOP response.
+ *     `maxLineBytes` bounds a command line that never ends.
  *
  *   ## Audit lifecycle
  *
@@ -107,7 +108,6 @@
 var net = require("node:net");
 var safeBuffer = require("./safe-buffer");
 var C = require("./constants");
-var bCrypto = require("./crypto");
 var numericBounds = require("./numeric-bounds");
 var validateOpts = require("./validate-opts");
 var guardPop3Command = require("./guard-pop3-command");
@@ -152,6 +152,7 @@ var ERR_CLAMP = 200;
  *   greeting:          string,                   // default "blamejs POP3"
  *   maxLineBytes:      number,                   // default 1024
  *   idleTimeoutMs:     number,                   // default 10 min
+ *   maxConnections:    number,                   // default 1024 — listener-wide ceiling
  *   commitTimeoutMs:   number,                   // default 30 s (UPDATE-state mailStore.commitPop3Drop cap)
  *   profile:           "strict" | "balanced" | "permissive",
  *   auth: {
@@ -189,7 +190,7 @@ function create(opts) {
       "getMessage/listMessages/markDelete; compose b.mailStore.create or operator-supplied backend)");
   }
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
-    ["maxLineBytes", "idleTimeoutMs", "commitTimeoutMs"],
+    ["maxLineBytes", "idleTimeoutMs", "commitTimeoutMs", "maxConnections"],
     "mail.server.pop3.", MailServerPop3Error, "mail-server-pop3/bad-bound");
 
   var greeting        = opts.greeting        || DEFAULT_GREETING_VENDOR;
@@ -239,23 +240,18 @@ function create(opts) {
   var _emit = auditEmit.emit;
 
   function _handleConnection(rawSocket) {
-    var remoteAddress = mailServerNet.admitConnection(rawSocket, rateLimit, _emit, {
+    var accepted = mailServerNet.acceptConnection(rawSocket, {
+      rateLimit:    rateLimit,
+      connections:  connections,
+      emit:         _emit,
       refusedEvent: "mail.server.pop3.rate_limit_refused",
       refusalLine:  "-ERR Too many connections from your IP\r\n",
+      idPrefix:     "pop3conn-",
     });
-    if (remoteAddress === null) return;
-    var connectionId = "pop3conn-" + bCrypto.generateToken(8);                                       // connection-id length
-    var socket = rawSocket;
-    connections.add(socket);
-    // Single close handler covers BOTH operator-driven `_close(socket)`
-    // and client-initiated disconnects (TCP FIN / RST without a
-    // server-side close call) — releases the rate-limit slot AND
-    // removes the socket from the tracking set so it can't accumulate
-    // stale entries across long-lived deployments.
-    rawSocket.once("close", function () {
-      rateLimit.releaseConnection(remoteAddress);
-      connections.delete(socket);
-    });
+    if (accepted === null) return;
+    var remoteAddress = accepted.remoteAddress;
+    var connectionId  = accepted.connectionId;
+    var socket        = accepted.socket;
 
     var state = {
       id:            connectionId,
@@ -900,6 +896,7 @@ function create(opts) {
   // ---- Lifecycle ----------------------------------------------------------
   return mailServerNet.createStoreServer(net, {
     defaultPort:      110,                                                                            // RFC 1939 POP3 port (IANA)
+    maxConnections:   opts.maxConnections,
     handleConnection: _handleConnection,
     errorClass:       MailServerPop3Error,
     errorCodePrefix:  "mail-server-pop3/",

package/lib/mail-server-rate-limit.js

@@ -45,6 +45,11 @@
  *     trickling one byte per minute to hold a connection for hours
  *     within the idle window.
  *
+ *     It measures bytes ARRIVING, so it applies to the two listeners
+ *     that take a message body: `b.mail.server.mx` and
+ *     `b.mail.server.submission`. A peer that stops taking a response
+ *     is a different condition, and idleTimeoutMs is what bounds it.
+ *
  *   ## What this module is NOT
  *
  *   - **Not an HTTP rate-limiter.** `b.middleware.rateLimit` covers
@@ -114,6 +119,14 @@ var DEFAULTS = Object.freeze({
 });
 
 var CONNECTION_RATE_WINDOW_MS = C.TIME.minutes(1);
+// How long a DATA body is given before its byte rate is judged. Below this the
+// measurement means nothing: the first chunk arrives with almost no elapsed
+// time, so any rate computed from it is noise, and a sender that pauses briefly
+// to read from its own spool would be cut off for it. Ten seconds at the
+// default 100 B/s floor means a peer must have delivered a kilobyte before it
+// is asked to justify itself, which no real MTA fails and a one-byte-per-minute
+// trickler cannot reach.
+var BODY_RATE_GRACE_MS = C.TIME.seconds(10);
 var AUTH_FAILURE_WINDOW_MS    = C.TIME.minutes(15);
 var RCPT_FAILURE_WINDOW_MS    = C.TIME.minutes(1);
 
@@ -294,8 +307,45 @@ function create(opts) {
   }
 
   function minBytesPerSecond() { return cfg.disabled ? 0 : cfg.minBytesPerSecond; }
+
+  // How long one body-rate window must run before a verdict from it means
+  // anything, and therefore how often the caller rolls its window forward.
+  //
+  // It lives on the limiter because the limiter is what decides when a
+  // measurement is old enough to judge. A caller holding its own number would
+  // ask a limiter with a longer interval only ever before it can answer, and
+  // that limiter's protection would be off while appearing to be wired.
+  function bodyRateWindowMs() { return BODY_RATE_GRACE_MS; }
   function isDisabled() { return cfg.disabled; }
 
+  // Is a DATA body arriving below the configured floor?
+  //
+  // The module has documented this floor since it shipped and nothing enforced
+  // it: the value was validated, defaulted and exposed as a getter that no
+  // listener ever called. `idleTimeoutMs` cuts a fully stalled connection, but
+  // a peer trickling a byte every few seconds resets that timer forever and
+  // holds a connection — and its slot in the per-address cap — for as long as
+  // it likes. This is the check that ends it.
+  //
+  // Both listeners reach it, so the policy lives here with the number rather
+  // than in two copies that can drift. Nothing is stored, so a connection needs
+  // no teardown to release it.
+  //
+  // `bytes` and `elapsedMs` describe ONE WINDOW, not the whole transfer. The
+  // difference is the whole defence: measured across the lifetime of a body, an
+  // early burst pays for an arbitrarily slow tail — at the default floor an
+  // 8 MiB burst buys about a day and 50 MiB buys six. The caller owns the
+  // window because the window is per-connection state and this limiter is
+  // shared across every connection; b.mail.server.net's createBodyRateWindow is
+  // what both listeners use to keep those windows identical.
+  function bodyRateStarved(bytes, elapsedMs) {
+    if (cfg.disabled) return false;
+    if (cfg.minBytesPerSecond <= 0) return false;
+    if (!(elapsedMs >= BODY_RATE_GRACE_MS)) return false;   // too early to judge
+    var seconds = elapsedMs / C.TIME.seconds(1);
+    return (bytes / seconds) < cfg.minBytesPerSecond;
+  }
+
   return {
     admitConnection:    admitConnection,
     releaseConnection:  releaseConnection,
@@ -304,6 +354,8 @@ function create(opts) {
     checkRcptAdmit:     checkRcptAdmit,
     noteRcptFailure:    noteRcptFailure,
     minBytesPerSecond:  minBytesPerSecond,
+    bodyRateStarved:    bodyRateStarved,
+    bodyRateWindowMs:   bodyRateWindowMs,
     isDisabled:         isDisabled,
   };
 }
@@ -316,20 +368,61 @@ function create(opts) {
  * @related   b.mail.server.rateLimit.create
  *
  * Resolve a rate-limit `spec` into a limiter. `false` disables limiting
- * (a disabled limiter that always admits), an already-built limiter — one
- * exposing `admitConnection` — passes through unchanged, and anything else
- * is treated as `create()` options. Every mail server (IMAP / POP3 / SMTP
- * MX / Submission / ManageSieve) composes this at the top of its `create()`
- * so the spec contract is identical across protocols.
+ * (a disabled limiter that always admits), an already-built limiter passes
+ * through unchanged, and anything else is treated as `create()` options.
+ * Every mail server (IMAP / POP3 / SMTP MX / Submission / ManageSieve)
+ * composes this at the top of its `create()` so the spec contract is
+ * identical across protocols.
+ *
+ * A custom limiter is recognised by `admitConnection` and must implement the
+ * whole interface the listeners call — `admitConnection`, `releaseConnection`,
+ * `checkAuthAdmit`, `noteAuthFailure`, `checkRcptAdmit`, `noteRcptFailure`,
+ * `minBytesPerSecond`, `bodyRateStarved`, `bodyRateWindowMs` — or resolve
+ * refuses at config time
+ * and names what is missing. A partial object used to be accepted here and
+ * fail later from inside a connection handler, on whichever request first
+ * reached a method it did not have. The supported way to customise part of the
+ * behaviour is to build `create({...})` and override what you want to change,
+ * so a method added in a later release cannot silently go unimplemented.
  *
  * @example
  *   var b = require("blamejs");
  *   var rl = b.mail.server.rateLimit.resolve(false);   // disabled
  *   // → a limiter whose admitConnection always admits
  */
+// What a listener actually calls on a limiter. `admitConnection` alone used to
+// be the whole sniff, so an operator-supplied object carrying only that was
+// accepted here and then failed later, from inside a connection handler, on the
+// first request that reached one of the other calls — a TypeError mid-request
+// rather than an error at boot. `releaseConnection` has been called on every
+// socket close for as long as the listeners have tracked connections, so an
+// incomplete limiter was already breaking before the body-rate floor was added;
+// the floor only made it break sooner and more visibly.
+//
+// Config-time refusal naming the gap is the right tier for this: the operator
+// learns at boot, not from a message that died mid-transaction.
+var LIMITER_INTERFACE = Object.freeze([
+  "admitConnection", "releaseConnection",
+  "checkAuthAdmit", "noteAuthFailure",
+  "checkRcptAdmit", "noteRcptFailure",
+  "minBytesPerSecond", "bodyRateStarved", "bodyRateWindowMs",
+]);
+
 function resolve(spec) {
   if (spec === false) return create({ disabled: true });
-  if (spec && typeof spec.admitConnection === "function") return spec;
+  if (spec && typeof spec.admitConnection === "function") {
+    var missing = LIMITER_INTERFACE.filter(function (m) {
+      return typeof spec[m] !== "function";
+    });
+    if (missing.length > 0) {
+      throw new MailServerRateLimitError("mail-server-rate-limit/incomplete-limiter",
+        "mail.server.rateLimit.resolve: a custom limiter must implement the whole " +
+        "interface the listeners call; missing: " + missing.join(", ") + ". Wrap " +
+        "b.mail.server.rateLimit.create({...}) and override the parts you want to " +
+        "change, so a method added later cannot silently go unimplemented.");
+    }
+    return spec;
+  }
   return create(spec || {});
 }
 
@@ -338,4 +431,9 @@ module.exports = {
   resolve:                      resolve,
   MailServerRateLimitError:     MailServerRateLimitError,
   DEFAULTS:                     DEFAULTS,
+  // How long a body-rate measurement must run before it means anything.
+  // Exported because the listener side owns the WINDOW — this limiter answers
+  // "is this rate below the floor", and the caller decides which stretch of
+  // the transfer to ask about.
+  BODY_RATE_GRACE_MS:           BODY_RATE_GRACE_MS,
 };