@blamejs/core 0.18.53 → 0.18.55

package/lib/mail-server-imap.js

@@ -98,10 +98,18 @@
  *
  *   ## What v1 does NOT ship
  *
- *   - **SEARCH** — operator wires `opts.search(actor, mailbox, query)`
- *     when ready; the listener emits `BAD search-not-configured`
- *     until then. SEARCH expressions are operator-domain logic
- *     against the mailStore index.
+ *   - **SEARCH / COPY / MOVE** — operator-domain logic against the
+ *     mailStore index, supplied through `opts.overrides`; until then
+ *     the listener answers `NO <verb> not configured`. A handler
+ *     supplied once serves BOTH the plain and the `UID` form: the UID
+ *     verb dispatches back through the same registry entry and sets
+ *     `parsed.useUid`, which the handler reads to answer in unique
+ *     identifiers per RFC 9051 §6.4.9.
+ *   - **UID EXPUNGE (RFC 4315)** — refused unless the operator
+ *     supplies an EXPUNGE handler that reads the uid-set. The shipped
+ *     EXPUNGE takes no set and expunges every message flagged
+ *     `\Deleted`, so serving the UID form from it would delete
+ *     messages the client did not name.
  *   - **NOTIFY (RFC 5465)**, **METADATA (RFC 5464)**, **CATENATE
  *     (RFC 4469)**, **URLAUTH (RFC 4467)**, **IMAPSIEVE (RFC 6785)**,
  *     **COMPRESS=DEFLATE (RFC 4978)** — opt-in / refused.
@@ -121,7 +129,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 guardImapCommand = require("./guard-imap-command");
@@ -147,6 +154,7 @@ var codepointClass = require("./codepoint-class");
 // Centralized so the marker lives in one place
 // and the per-call sites read cleanly.
 var ERR_CLAMP = 200;                                                                                  // protocol-reply error-message clamp
+var CRLF_BYTES = Buffer.from("\r\n", "latin1");                                                       // RFC 9051 §2.2 line terminator, as octets
 var LINE_PREVIEW = 80;                                                                                // audit-line preview clamp
 
 // RFC 9051 §6.3.12 + RFC 5322 §3.3 date-time parser for IMAP APPEND.
@@ -228,6 +236,7 @@ function _validateMailboxName(name, opts) {
  *   maxLineBytes:      number,           // default 8192
  *   maxLiteralBytes:   number,           // default 64 MiB
  *   idleTimeoutMs:     number,           // default 30 min
+ *   maxConnections:    number,           // default 1024 — listener-wide ceiling
  *   profile:           "strict" | "balanced" | "permissive",
  *   auth: {
  *     mechanisms:      ["PLAIN", "LOGIN", "SCRAM-SHA-256", "EXTERNAL", "XOAUTH2"],
@@ -237,6 +246,15 @@ function _validateMailboxName(name, opts) {
  *   rateLimit:         b.mail.server.rateLimit handle | opts | false,
  *   audit:             b.audit                // optional
  *
+ * `fetchRange` may return each row's `payload` as a Buffer, and should whenever
+ * the row carries message content. RFC 9051 §4.3 makes a literal a counted
+ * sequence of octets, and a string cannot hold one: a message octet that is not
+ * valid UTF-8 does not survive being encoded on the way to the socket, and the
+ * count the response announced stops matching the number of octets it wrote —
+ * which is what tells a client where the response ends. A Buffer payload is
+ * framed and written as the octets it holds. A string payload is unchanged and
+ * remains right for the rows that carry only attributes, such as `FLAGS (\Seen)`.
+ *
  * @example
  *   var imap = b.mail.server.imap.create({
  *     tlsContext: b.mail.server.tls.context({ certFile, keyFile }).secureContext,
@@ -264,7 +282,7 @@ function create(opts) {
       "mail.server.imap.create: mailStore is required (compose b.mailStore.create({ backend: ... }))");
   }
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
-    ["maxLineBytes", "maxLiteralBytes", "idleTimeoutMs"],
+    ["maxLineBytes", "maxLiteralBytes", "idleTimeoutMs", "maxConnections"],
     "mail.server.imap.", MailServerImapError, "mail-server-imap/bad-bound");
 
   var greeting          = opts.greeting        || DEFAULT_GREETING_VENDOR;
@@ -283,16 +301,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.imap.rate_limit_refused",
       refusalLine:  "* BAD Too many connections from your IP\r\n",
+      idPrefix:     "imapconn-",
     });
-    if (remoteAddress === null) return;
-    rawSocket.once("close", function () { rateLimit.releaseConnection(remoteAddress); });
-
-    var connectionId = "imapconn-" + bCrypto.generateToken(8);                                       // connection-id length
-    var socket = rawSocket;
-    connections.add(socket);
+    if (accepted === null) return;
+    var remoteAddress = accepted.remoteAddress;
+    var connectionId  = accepted.connectionId;
+    var socket        = accepted.socket;
 
     var state = {
       id:            connectionId,
@@ -450,7 +470,14 @@ function create(opts) {
         synchronizing: !parsed.literalNonSync,
       };
       if (!parsed.literalNonSync) {
-        _writeUntagged(socket, "+ Ready for literal data");
+        // RFC 9051 §7.5 — a synchronizing literal is answered with a command
+        // continuation request: a line that BEGINS with `+`. Written as an
+        // untagged response, the wire carried `* + Ready for literal data`,
+        // which is not one, so a conforming client waited for a `+` line that
+        // never came and APPEND could not complete. The non-synchronizing
+        // route is no escape either: the strict profile's guard refuses
+        // LITERAL+ and CAPABILITY does not advertise it.
+        _writeContinuation(socket, "Ready for literal data");
       }
       return;
     }
@@ -731,7 +758,7 @@ function create(opts) {
               } else if (event.kind === "LIST") {
                 _writeUntagged(socket, "LIST " + event.payload);
               } else if (event.kind === "FETCH") {
-                _writeUntagged(socket, (event.seq || "") + " FETCH (" + (event.payload || "") + ")");
+                _writeUntagged(socket, _fetchResponse(event.seq || "", event.payload));
               }
             } catch (_e) { /* drop-silent — socket may already be closed */ }
           });
@@ -967,56 +994,49 @@ function create(opts) {
     }
     _emit("mail.server.imap.auth_attempt",
       { connectionId: state.id, mechanism: mechName, remoteAddress: state.remoteAddress });
-    state.authPending = { mechanism: mechName, tag: tag, step: 0 };
+    state.authPending = { mech: mechName, tag: tag, step: 0 };
     _runAuthStep(state, socket, initialResp);
   }
 
   function _runAuthStep(state, socket, clientResp) {
     var pending = state.authPending;
-    Promise.resolve()
-      .then(function () {
-        return authConfig.verify(pending.mechanism, {
-          step:           pending.step,
-          clientResponse: clientResp,
-          tls:            state.tls,
-          remoteAddress:  state.remoteAddress,
-        });
-      })
-      .then(function (result) {
-        pending.step += 1;
-        if (result && result.pending && typeof result.challenge === "string") {
-          // Server-side challenge — `+ <base64>` per RFC 9051 §6.2.2.
-          _writeContinuation(socket, result.challenge);
-          return;
-        }
-        if (result && result.ok === true && result.actor) {
-          state.actor = result.actor;
-          state.stage = "authenticated";
-          var savedTag = pending.tag;
-          state.authPending = null;
-          _emit("mail.server.imap.auth_success",
-            { connectionId: state.id, mechanism: pending.mechanism,
-              tenantId: result.actor.tenantId || null });
-          _writeTagged(socket, savedTag, "OK [CAPABILITY " + _capabilityLine(state) + "] AUTHENTICATE completed");
-          return;
-        }
-        var failTag = pending.tag;
-        state.authPending = null;
-        rateLimit.noteAuthFailure(state.remoteAddress);
-        _emit("mail.server.imap.auth_failed",
-          { connectionId: state.id, mechanism: pending.mechanism,
-            reason: (result && result.reason) || "verify-returned-fail" }, "denied");
-        _writeTagged(socket, failTag, "NO Authentication credentials invalid");
-      })
-      .catch(function (err) {
-        var failTag = pending.tag;
+    function _fail(reason, outcome, reply) {
+      var failTag = pending.tag;
+      state.authPending = null;
+      rateLimit.noteAuthFailure(state.remoteAddress);
+      _emit("mail.server.imap.auth_failed",
+        { connectionId: state.id, mechanism: pending.mech, reason: reason }, outcome);
+      _writeTagged(socket, failTag, reply);
+    }
+    mailServerNet.runSaslStep({
+      exchange:       pending,
+      verify:         authConfig.verify,
+      credentials:    { tls: state.tls, remoteAddress: state.remoteAddress },
+      clientResponse: clientResp,
+      // Server-side challenge — `+ <base64>` per RFC 9051 §6.2.2.
+      writeChallenge: function (ch) { return _writeContinuation(socket, ch); },
+      onChallengeUnsafe: function () {
+        _fail("challenge-contains-line-terminator", "denied", "NO Authentication failed");
+      },
+      onSuccess: function (result) {
+        state.actor = result.actor;
+        state.stage = "authenticated";
+        var savedTag = pending.tag;
         state.authPending = null;
-        rateLimit.noteAuthFailure(state.remoteAddress);
-        _emit("mail.server.imap.auth_failed",
-          { connectionId: state.id, mechanism: pending.mechanism,
-            reason: (err && err.message) || String(err) }, "failure");
-        _writeTagged(socket, failTag, "NO Authentication failed");
-      });
+        _emit("mail.server.imap.auth_success",
+          { connectionId: state.id, mechanism: pending.mech,
+            tenantId: result.actor.tenantId || null });
+        _writeTagged(socket, savedTag,
+          "OK [CAPABILITY " + _capabilityLine(state) + "] AUTHENTICATE completed");
+      },
+      onFailure: function (result) {
+        _fail((result && result.reason) || "verify-returned-fail", "denied",
+              "NO Authentication credentials invalid");
+      },
+      onError: function (err) {
+        _fail((err && err.message) || String(err), "failure", "NO Authentication failed");
+      },
+    });
   }
 
   function _handleLogin(state, socket, tag, args) {
@@ -1582,10 +1602,20 @@ function create(opts) {
         for (var i = 0; i < rs.length; i += 1) {
           var r = rs[i];
           var payload = r.payload || "";
-          if (includeModseq && r.modseq !== undefined && !/MODSEQ\s*\(/.test(payload)) {
-            payload = (payload ? payload + " " : "") + "MODSEQ (" + r.modseq + ")";
+          // A Buffer payload is the backend saying "these are the message's
+          // own octets". It is assembled and written as octets end to end, so
+          // the count in the literal header is the count that reaches the wire.
+          // Concatenating it into a string instead re-encoded it as UTF-8, and
+          // the response then announced one length and sent another.
+          var octets = Buffer.isBuffer(payload);
+          var asText = octets ? payload.toString("latin1") : String(payload);
+          if (includeModseq && r.modseq !== undefined && !/MODSEQ\s*\(/.test(asText)) {
+            var modseqAttr = (asText ? " " : "") + "MODSEQ (" + r.modseq + ")";
+            payload = octets
+              ? Buffer.concat([payload, Buffer.from(modseqAttr, "latin1")])
+              : asText + modseqAttr;
           }
-          _writeUntagged(socket, r.seq + " FETCH (" + payload + ")");
+          _writeUntagged(socket, _fetchResponse(r.seq, payload));
         }
         _writeTagged(socket, tag, "OK FETCH completed");
       })
@@ -1713,29 +1743,49 @@ function create(opts) {
     var subArgs = sub[2];
     if (subVerb === "FETCH") return _handleFetch(state, socket, tag, subArgs, true);
     if (subVerb === "STORE") return _handleStore(state, socket, tag, subArgs, true);
-    // RFC 9051 §6.4.9 also defines UID SEARCH / UID COPY / UID MOVE /
-    // UID EXPUNGE; deferred from the initial listener slice.
+    // Every other sub-command RFC 9051 §6.4.9 defines — SEARCH, COPY, MOVE,
+    // EXPUNGE — goes back through the registry to the SAME entry the
+    // unprefixed verb dispatches to, carrying `useUid` so the handler answers
+    // in unique identifiers.
     //
-    //   SEARCH:  composes with the existing _handleSearch path; needs
-    //            the searchRange path threaded through `useUid: true`.
-    //   COPY:    composes with the existing _handleCopy path; needs
-    //            the mailStore.copyRange opt accepted.
-    //   MOVE:    RFC 6851; same shape as COPY plus an atomic-delete
-    //            step on the source mailbox.
-    //   EXPUNGE: RFC 4315 UIDPLUS; expunges by uid-set instead of by
-    //            \Deleted-flag scan.
+    // The listener ships no search, copy or move of its own: those are
+    // operator-domain, and the registry holds a "not configured" default that
+    // a consumer replaces through `opts.overrides`. Dispatching the UID forms
+    // here instead of through the registry made that seam reachable from one
+    // side only — a consumer who supplied SEARCH got the sequence form served
+    // and the UID form refused, and the only way to supply the UID form was to
+    // replace the whole UID verb, taking the working UID FETCH and UID STORE
+    // with it. A client that keeps a cross-session cache asks for the UID form
+    // precisely because a sequence number does not survive the session, so the
+    // refusal fell on the clients doing the durable thing.
     //
-    // Re-open condition: operator surfaces a real IMAP client that
-    // refuses to fall back to seq-number variants (most modern
-    // clients — mutt / Thunderbird / Apple Mail / Outlook — already
-    // use the seq-number forms when UID variants are unavailable).
-    //
-    // Operator escape hatch today: clients that issue these UID
-    // sub-commands receive `BAD` and retry against the seq-number
-    // variant (SEARCH / COPY / MOVE / EXPUNGE) which the listener
-    // does serve.
-    _writeTagged(socket, tag, "BAD UID " + subVerb +
-                 " is not yet implemented; client may retry with the seq-number form");
+    // Going through the registry also keeps the tenant check, the guard
+    // validation and the audit emission on the UID path, which a direct call
+    // from here would have skipped.
+    // An allowlist, not "whatever the registry holds". UID takes the five
+    // sub-commands §6.4.9 names plus EXPUNGE from RFC 4315; sending anything
+    // else through would dispatch a real handler that knows nothing about UIDs
+    // — `UID SELECT INBOX` would select a mailbox, and `UID UID …` would
+    // recurse.
+    if (subVerb !== "SEARCH" && subVerb !== "COPY" &&
+        subVerb !== "MOVE"   && subVerb !== "EXPUNGE") {
+      _writeTagged(socket, tag, "BAD UID " + subVerb + " is not a UID sub-command");
+      return;
+    }
+    // EXPUNGE is the one that cannot be forwarded blind. RFC 4315 §2.1 makes
+    // `UID EXPUNGE <uid-set>` expunge ONLY the named messages, while the
+    // listener's own EXPUNGE expunges every message flagged \Deleted and takes
+    // no set at all. Forwarding to it would delete messages the client did not
+    // name, which is worse than not answering. A consumer who supplies their
+    // own EXPUNGE reads `useUid` and the set, so theirs can serve it.
+    if (subVerb === "EXPUNGE" && _registry.source("EXPUNGE") !== "operator-override") {
+      _writeTagged(socket, tag,
+        "NO UID EXPUNGE needs a uid-set-aware EXPUNGE handler; " +
+        "the default expunges by \\Deleted flag and would exceed the set");
+      return;
+    }
+    return _registry.dispatch(subVerb, state, socket,
+      { tag: tag, args: subArgs, useUid: true });
   }
 
   function _handleIdle(state, socket, tag) {
@@ -1754,17 +1804,63 @@ function create(opts) {
     state.idle = { tag: tag, timer: timer };
   }
 
+  // One line onto the socket, as OCTETS.
+  //
+  // RFC 9051 §4.3 makes a literal a counted sequence of octets, so a response
+  // carrying message content has to reach the wire as the octets the backend
+  // holds. `socket.write(string)` encodes as UTF-8, which replaces every
+  // sequence that is not valid UTF-8 and changes the length — so the count the
+  // response announced and the number of octets it wrote disagreed, and a
+  // client, which uses that count to find the end of the response, read the
+  // next response as part of this one.
+  //
+  // A Buffer `msg` is written through untouched. A string keeps its UTF-8
+  // encoding, which is what RFC 9051 §5.1 asks for in the one place a response
+  // string is not ASCII: a mailbox name, once the client has enabled UTF8=ACCEPT.
+  // Encoding those latin1 instead would keep the low byte of each character and
+  // corrupt every name outside Latin-1 — the same defect this fixes, moved.
+  function _writeLine(socket, prefix, msg) {
+    try {
+      if (Buffer.isBuffer(msg)) {
+        socket.write(Buffer.concat([Buffer.from(prefix, "latin1"), msg, CRLF_BYTES]));
+      } else {
+        socket.write(prefix + msg + "\r\n");
+      }
+    } catch (_e) { /* socket may be down */ }
+  }
+  // One untagged FETCH response. A Buffer payload is the backend saying "these
+  // are the message's own octets", and the response is assembled as octets so
+  // the count in the literal header is the count that reaches the wire; a
+  // string payload is attributes and stays a string.
+  //
+  // Two places build one of these — the FETCH command and a NOTIFY push — and
+  // a second copy of this is how the octet handling ends up right in one and
+  // wrong in the other, which is what it was.
+  function _fetchResponse(seq, payload) {
+    if (Buffer.isBuffer(payload)) {
+      return Buffer.concat([
+        Buffer.from(seq + " FETCH (", "latin1"), payload, Buffer.from(")", "latin1"),
+      ]);
+    }
+    return seq + " FETCH (" + (payload || "") + ")";
+  }
+
   function _writeTagged(socket, tag, msg) {
-    try { socket.write(tag + " " + msg + "\r\n"); }
-    catch (_e) { /* socket may be down */ }
+    _writeLine(socket, tag + " ", msg);
   }
   function _writeUntagged(socket, msg) {
-    try { socket.write("* " + msg + "\r\n"); }
-    catch (_e) { /* socket may be down */ }
+    _writeLine(socket, "* ", msg);
   }
+  // RFC 9051 §7.5 continuation. Returns false when the operator's challenge
+  // carries CR / LF / NUL: those end the line early and the remainder is read
+  // by the client as a second server response. Not hypothetical for a SCRAM or
+  // CRAM mechanism, whose challenge is composed partly from the client's own
+  // nonce, so client bytes reach this write.
   function _writeContinuation(socket, msg) {
-    try { socket.write("+ " + msg + "\r\n"); }
-    catch (_e) { /* socket may be down */ }
+    var safe = mailServerNet.saslChallengeOrNull(msg);
+    if (safe === null) return false;
+    _writeLine(socket, "+ ", safe);
+    return true;
   }
   function _close(socket, state) {
     // The drain loop's `if (state.stage === "closed") return;` guard
@@ -1789,6 +1885,7 @@ function create(opts) {
   // ---- Lifecycle ----------------------------------------------------------
   return mailServerNet.createStoreServer(net, {
     defaultPort:      143,                                                                              // RFC 9051 IMAP port (IANA)
+    maxConnections:   opts.maxConnections,
     handleConnection: _handleConnection,
     errorClass:       MailServerImapError,
     errorCodePrefix:  "mail-server-imap/",

package/lib/mail-server-jmap.js

@@ -158,6 +158,11 @@ void C;
  *                         // capabilities the server advertises beyond core
  *   accountsFor:         async function (actor) → { primaryAccounts, accounts },
  *                         // operator-supplied accountId enumeration
+ *   webSocket:           boolean,   // default true — false stops advertising the
+ *                         // RFC 8887 WebSocket transport (capability and the
+ *                         // top-level webSocketUrl alias), for a deployment
+ *                         // that has not wired the upgrade handler
+ *   webSocketUrl:        string,    // default "/jmap/ws" — where the upgrade lives
  *   profile:             "strict" | "balanced" | "permissive",
  *   posture:             "hipaa" | "pci-dss" | "gdpr" | "soc2",
  *   audit:               b.audit                                       // optional
@@ -199,6 +204,20 @@ function create(opts) {
   var profile = opts.profile || DEFAULT_PROFILE;
   var posture = opts.posture || null;
   var serverCapabilities = opts.serverCapabilities || {};
+  // RFC 8887 §3 — whether this deployment offers the WebSocket transport. It
+  // was advertised unconditionally: the capability was injected when the
+  // consumer omitted the key, and merged back in when they supplied one, so a
+  // deployment that had not wired the upgrade handler still sent conforming
+  // clients to an endpoint that could not upgrade. The only value that
+  // suppressed it was `undefined`, and only because JSON.stringify drops such
+  // keys — an accident of serialization rather than an answer. `false` is now
+  // that answer, and a value that is neither true nor false is a
+  // misconfiguration rather than a silent default back to advertising.
+  validateOpts.optionalBoolean(opts.webSocket,
+    "mail.server.jmap.create: opts.webSocket (false stops advertising the RFC 8887 " +
+    "WebSocket transport, for a deployment that has not wired the upgrade handler)",
+    MailServerJmapError, "mail-server-jmap/bad-websocket");
+  var webSocketEnabled = opts.webSocket !== false;
 
   // JMAP method registry. Wrap operator-supplied `opts.methods` map
   // through `b.mail.serverRegistry` so per-handler resource budgets
@@ -569,14 +588,19 @@ function create(opts) {
         var defaultCaps = { "urn:ietf:params:jmap:core": {} };
         var hasOperatorWsCap = Object.prototype.hasOwnProperty.call(
           serverCapabilities, "urn:ietf:params:jmap:websocket");
-        if (!hasOperatorWsCap) {
+        if (webSocketEnabled && !hasOperatorWsCap) {
           defaultCaps["urn:ietf:params:jmap:websocket"] = {
             url:          opts.webSocketUrl || "/jmap/ws",
             supportsPush: true,
           };
         }
+        var caps = Object.assign({}, defaultCaps, serverCapabilities);
+        // `webSocket: false` is the deployment's answer, so it outranks a
+        // capability the consumer also listed in serverCapabilities — otherwise
+        // the merge above would put back exactly what was declined.
+        if (!webSocketEnabled) delete caps["urn:ietf:params:jmap:websocket"];
         var session = {
-          capabilities: Object.assign({}, defaultCaps, serverCapabilities),
+          capabilities: caps,
           accounts:     info.accounts || {},
           primaryAccounts: info.primaryAccounts || {},
           username:     actor.username || actor.id || "unknown",
@@ -587,10 +611,13 @@ function create(opts) {
           // RFC 8887 §3 — `webSocketUrl` advertises the JMAP WS
           // endpoint. Operator overrides via opts.webSocketUrl; default
           // mounts at `/jmap/ws`.
-          urlEndpointResolution: serverCapabilities["urn:ietf:params:jmap:websocket"]
+          urlEndpointResolution: (webSocketEnabled && serverCapabilities["urn:ietf:params:jmap:websocket"])
             ? { useEndpoint: opts.webSocketUrl || "/jmap/ws", urlPrefix: "" }
             : undefined,
-          webSocketUrl:   opts.webSocketUrl || "/jmap/ws",
+          // The top-level alias goes with the capability. Leaving it behind
+          // would still point a client at an endpoint that cannot upgrade,
+          // which is the whole thing `webSocket: false` is declining.
+          webSocketUrl:   webSocketEnabled ? (opts.webSocketUrl || "/jmap/ws") : undefined,
           state:        sessionState,
         };
         res.statusCode = 200;