@blamejs/core 0.9.43 → 0.9.46

package/lib/mail-server-mx.js

@@ -0,0 +1,736 @@
+"use strict";
+/**
+ * @module     b.mail.server.mx
+ * @nav        Mail
+ * @title      Mail MX Server
+ * @order      540
+ *
+ * @intro
+ *   Inbound SMTP / MX listener. Composes the framework's existing
+ *   mail-gate substrates (`b.mail.helo`, `b.mail.rbl`,
+ *   `b.mail.greylist`, `b.guardEnvelope`, `b.mail.auth.dmarc`,
+ *   `b.safeMime`, `b.guardEmail`, `b.guardSmtpCommand`,
+ *   `b.mail.agent`) into one operator-facing server that accepts
+ *   inbound mail per RFC 5321 with PQC-shaped TLS posture, SMTP-
+ *   smuggling defense baked into the wire-protocol layer, and the
+ *   gate cascade running at the right phase of the state machine.
+ *
+ *   `create({ ... }).listen()` binds the TCP port; every incoming
+ *   connection drives the CONNECT → EHLO → [STARTTLS → EHLO] →
+ *   MAIL → RCPT (×N) → DATA → DATA-body → QUIT state machine. Each
+ *   phase passes through the operator-supplied gates (defaulting
+ *   to "no-op" when the operator hasn't wired a gate) and refuses
+ *   with the appropriate 5xx (permanent) or 4xx (transient) SMTP
+ *   reply code on gate fail.
+ *
+ *   ## Defenses baked in
+ *
+ *   - **SMTP smuggling** (CVE-2023-51764 / CVE-2024-32178) — every
+ *     wire line passes through `b.guardSmtpCommand.validate` which
+ *     refuses bare LF, bare CR, NUL, C0 controls, DEL, and oversize.
+ *     The DATA body's `\r\n.\r\n` terminator is matched on canonical
+ *     CRLF only — bare-LF dot-terminators are refused. Together this
+ *     defends the CVE-2023-51764 class where a hostile sender
+ *     smuggles a second message past the framework's filter by
+ *     terminating the first one with `\n.\n` instead of `\r\n.\r\n`.
+ *
+ *   - **Open-relay defense** — RCPT TO non-local refused with 550
+ *     5.7.1 Relaying denied unless the operator explicitly registered
+ *     the destination via `relayAllowedFor: [{ cidr, scope }]`. The
+ *     default posture is "MX-only, no relay" so a misconfigured boot
+ *     can't accidentally become an open relay.
+ *
+ *   - **STARTTLS stripping (CVE-2021-38371 Exim, CVE-2021-33515 Dovecot)** —
+ *     once STARTTLS is advertised + selected, subsequent commands
+ *     MUST run over the negotiated TLS context. A pre-STARTTLS
+ *     pipelining attempt (RFC 2920) to inject commands that take
+ *     effect post-handshake is refused by clearing the command
+ *     buffer at STARTTLS time and reading fresh from the TLS socket
+ *     only — defends both the Exim and Dovecot variants of the
+ *     STARTTLS-injection class.
+ *
+ *   - **Resource exhaustion** — per-command line cap (default
+ *     1 KiB), DATA body cap (default 50 MiB per RFC 5321 §4.5.3.1.7),
+ *     per-recipient cap (default 100 per RFC 5321 §4.5.3.1.8),
+ *     connection idle timeout (default 5 minutes per RFC 5321
+ *     §4.5.3.2.7). Operator opts up with explicit bounds.
+ *
+ *   - **TLS posture** — `tlsContext` MUST be supplied (no implicit
+ *     plaintext-only mode). Operator passes a `b.network.tls.context`
+ *     output which carries the framework's TLS 1.3 default + OCSP /
+ *     CT-log posture. Pre-STARTTLS plain commands are limited to
+ *     EHLO / HELO / STARTTLS / NOOP / QUIT / RSET; MAIL / RCPT /
+ *     DATA all refused with 530 5.7.0 Must issue a STARTTLS command
+ *     first.
+ *
+ *   ## Audit lifecycle
+ *
+ *   - `mail.server.mx.connect`           — IP, TLS state, FCrDNS hostname
+ *   - `mail.server.mx.helo`              — HELO greeting, helo-gate verdict
+ *   - `mail.server.mx.mail_from`         — sender, SPF verdict, alignment verdict
+ *   - `mail.server.mx.rcpt_to`           — recipient, RBL verdict, greylist verdict
+ *   - `mail.server.mx.data_accepted`     — message size, DKIM verdict, DMARC verdict
+ *   - `mail.server.mx.data_refused`      — refusal reason + SMTP code (5xx vs 4xx)
+ *   - `mail.server.mx.delivered`         — agent.handoff ack
+ *   - `mail.server.mx.tls_handshake_failed` — handshake error
+ *   - `mail.server.mx.smtp_smuggling_detected` — CRLF.CRLF injection class
+ *   - `mail.server.mx.relay_refused`     — open-relay attempt
+ *
+ *   ## What v1 does NOT ship
+ *
+ *   - **AUTH / submission auth** — MX listener is inbound from the
+ *     internet, no authentication. Submission listener (port 587) is
+ *     a separate slice with SCRAM-SHA-256 / XOAUTH2 / EXTERNAL.
+ *   - **Sieve filtering** — composes via `b.mail.agent` at delivery
+ *     time; the MX listener doesn't decide policy itself.
+ *   - **Outbound DSN generation** — `b.guardDsn` parses inbound DSNs;
+ *     outbound DSN emission deferred to the submission slice.
+ *   - **8BITMIME** (RFC 6152, obsoletes RFC 1652) — advertised in
+ *     the EHLO capabilities since the DATA body parser via
+ *     `b.safeMime` is octet-clean; no transcoding needed.
+ *   - **SMTPUTF8** (RFC 6531) + **IDN** (RFC 5891) — the wire-protocol
+ *     layer here is encoding-agnostic; SMTPUTF8 capability
+ *     advertisement is a follow-up slice once the operator's
+ *     downstream (mail-store + delivery agent) accepts Unicode
+ *     mailbox-local-part bytes. Today the listener does not
+ *     advertise SMTPUTF8 and refuses non-ASCII in MAIL FROM /
+ *     RCPT TO via `b.guardSmtpCommand`.
+ *
+ *   ## Composition contract
+ *
+ *   Every gate is a primitive that already exists. The MX slice is a
+ *   state-machine + wire-protocol coordinator — no new crypto, no
+ *   new parsing, no new RFC-layer primitives. If a gate isn't ready
+ *   (e.g. operator hasn't wired `b.mail.auth.dmarc`), the listener
+ *   skips that phase with an audit note rather than synthesizing a
+ *   verdict.
+ *
+ * @card
+ *   Inbound SMTP / MX listener. RFC 5321 state machine with SMTP-
+ *   smuggling defense baked into the wire-protocol layer (RFC 5321
+ *   §2.3.8 + CVE-2023-51764 / CVE-2024-32178), open-relay refusal by
+ *   default, STARTTLS-stripping defense (CVE-2021-38371), and the
+ *   framework's mail-gate cascade (HELO / RBL / greylist /
+ *   guardEnvelope / DMARC / safeMime / guardEmail) running at the
+ *   appropriate phase.
+ */
+
+var net   = require("node:net");
+var nodeTls   = require("node:tls");
+var lazyRequire = require("./lazy-require");
+var C         = require("./constants");
+var bCrypto   = require("./crypto");
+var numericBounds = require("./numeric-bounds");
+var safeAsync = require("./safe-async");
+var safeBuffer = require("./safe-buffer");
+var safeSmtp = require("./safe-smtp");
+var validateOpts = require("./validate-opts");
+var guardSmtpCommand = require("./guard-smtp-command");
+var { defineClass } = require("./framework-error");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var MailServerMxError = defineClass("MailServerMxError", { alwaysPermanent: true });
+
+// RFC 5321 §4.5.3.1 — wire-protocol limits.
+var DEFAULT_MAX_LINE_BYTES        = C.BYTES.kib(1);
+var DEFAULT_MAX_MESSAGE_BYTES     = C.BYTES.mib(50);
+var DEFAULT_MAX_RCPTS_PER_MESSAGE = 100;                                                              // allow:raw-byte-literal — RFC 5321 §4.5.3.1.8 recipient cap
+var DEFAULT_IDLE_TIMEOUT_MS       = C.TIME.minutes(5);
+var DEFAULT_GREETING              = "blamejs ESMTP";
+
+// SMTP reply-code constants. The framework uses RFC 5321 enhanced
+// status codes per RFC 3463 (`Dclass.Dsubject.Ddetail`) embedded in
+// the reply lines for operator-side observability.
+var REPLY_220_READY              = "220";
+var REPLY_221_BYE                = "221";
+var REPLY_250_OK                 = "250";
+var REPLY_354_START_INPUT        = "354";
+var REPLY_421_SERVICE_NOT_AVAIL  = "421";                                                             // allow:raw-byte-literal — SMTP transient code
+var REPLY_451_LOCAL_ERROR        = "451";                                                             // allow:raw-byte-literal — SMTP transient code
+var REPLY_452_INSUFFICIENT_STG   = "452";                                                             // allow:raw-byte-literal — SMTP transient code
+var REPLY_500_SYNTAX             = "500";                                                             // allow:raw-byte-literal — SMTP permanent code
+var REPLY_501_BAD_ARGS           = "501";                                                             // allow:raw-byte-literal — SMTP permanent code
+var REPLY_502_NOT_IMPLEMENTED    = "502";                                                             // allow:raw-byte-literal — SMTP permanent code
+var REPLY_503_BAD_SEQUENCE       = "503";                                                             // allow:raw-byte-literal — SMTP permanent code
+var REPLY_530_AUTH_REQUIRED      = "530";                                                             // allow:raw-byte-literal — SMTP permanent code
+var REPLY_550_MAILBOX_UNAVAIL    = "550";                                                             // allow:raw-byte-literal — SMTP permanent code
+var REPLY_552_SIZE_EXCEEDED      = "552";                                                             // allow:raw-byte-literal — SMTP permanent code
+var REPLY_554_TRANSACTION_FAILED = "554";                                                             // allow:raw-byte-literal — SMTP permanent code
+
+var RE_MAIL_FROM = /^MAIL\s+FROM:\s*<([^>]*)>(?:\s+(.*))?$/i;
+var RE_RCPT_TO   = /^RCPT\s+TO:\s*<([^>]+)>(?:\s+.*)?$/i;
+var RE_SIZE      = /SIZE=(\d+)/i;
+
+/**
+ * @primitive b.mail.server.mx.create
+ * @signature b.mail.server.mx.create(opts)
+ * @since     0.9.46
+ * @status    stable
+ * @related   b.mail.helo.evaluate, b.mail.rbl.create, b.mail.greylist.create, b.guardEnvelope.check, b.mail.agent.create
+ *
+ * Build the MX listener. Returns `{ listen({ port?, address? }),
+ * close({ timeoutMs? }), connectionCount(), _portForTest() }`.
+ *
+ * @opts
+ *   tlsContext:        TlsContext,      // required — b.network.tls.context() output (no implicit plaintext)
+ *   greeting:          string,          // default "blamejs ESMTP" — HELO/EHLO 220-line banner
+ *   helo:              b.mail.helo,     // optional gate
+ *   rbl:               b.mail.rbl,      // optional gate
+ *   greylist:          b.mail.greylist, // optional gate
+ *   envelope:          b.guardEnvelope, // optional gate (SPF/DKIM alignment)
+ *   dmarc:             b.mail.auth.dmarc,  // optional gate
+ *   agent:             b.mail.agent,    // optional delivery handoff
+ *   relayAllowedFor:   [{ cidr, scope }],  // operator-explicit relay allowlist; default [] = MX-only
+ *   localDomains:      [string],        // RCPT TO local-domain allowlist (refuse non-local with 550 5.7.1)
+ *   maxLineBytes:      number,          // default 1 KiB — per-command line cap
+ *   maxMessageBytes:   number,          // default 50 MiB — DATA body cap
+ *   maxRcptsPerMessage: number,         // default 100 — per RFC 5321 §4.5.3.1.8
+ *   idleTimeoutMs:     number,          // default 5 minutes — RFC 5321 §4.5.3.2.7
+ *   profile:           "strict" | "balanced" | "permissive",  // gate posture cascade
+ *
+ * @example
+ *   var tls = b.network.tls.context({ cert: certPem, key: keyPem });
+ *   var server = b.mail.server.mx.create({
+ *     tlsContext:   tls,
+ *     greeting:     "mx.example.com ESMTP blamejs",
+ *     helo:         b.mail.helo,
+ *     rbl:          b.mail.rbl.create({ providers: ["zen.spamhaus.org"] }),
+ *     greylist:     b.mail.greylist.create({ store: greylistStore }),
+ *     envelope:     b.guardEnvelope,
+ *     agent:        b.mail.agent.create({ store: mailStore }),
+ *     localDomains: ["example.com"],
+ *   });
+ *   await server.listen({ port: 25 });
+ */
+function create(opts) {
+  validateOpts.requireObject(opts, "mail.server.mx.create",
+    MailServerMxError, "mail-server-mx/bad-opts");
+  if (!opts.tlsContext) {
+    throw new MailServerMxError("mail-server-mx/no-tls-context",
+      "mail.server.mx.create: tlsContext is required (no implicit plaintext mode)");
+  }
+  numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
+    ["maxLineBytes", "maxMessageBytes", "maxRcptsPerMessage", "idleTimeoutMs"],
+    "mail.server.mx.", MailServerMxError, "mail-server-mx/bad-bound");
+  if (opts.localDomains !== undefined &&
+      (!Array.isArray(opts.localDomains) || opts.localDomains.length === 0)) {
+    throw new MailServerMxError("mail-server-mx/bad-opts",
+      "mail.server.mx.create: localDomains must be a non-empty array if provided");
+  }
+  if (opts.relayAllowedFor !== undefined && !Array.isArray(opts.relayAllowedFor)) {
+    throw new MailServerMxError("mail-server-mx/bad-opts",
+      "mail.server.mx.create: relayAllowedFor must be an array if provided");
+  }
+
+  var greeting          = opts.greeting          || DEFAULT_GREETING;
+  var maxLineBytes      = opts.maxLineBytes      || DEFAULT_MAX_LINE_BYTES;
+  var maxMessageBytes   = opts.maxMessageBytes   || DEFAULT_MAX_MESSAGE_BYTES;
+  var maxRcptsPerMsg    = opts.maxRcptsPerMessage || DEFAULT_MAX_RCPTS_PER_MESSAGE;
+  var idleTimeoutMs     = opts.idleTimeoutMs     || DEFAULT_IDLE_TIMEOUT_MS;
+  var localDomains      = (opts.localDomains || []).map(function (d) { return String(d).toLowerCase(); });
+  var relayAllowedFor   = opts.relayAllowedFor || [];
+  var profile           = opts.profile || "strict";
+
+  var tcpServer    = null;
+  var listening    = false;
+  var connections  = new Set();
+
+  function _emit(action, metadata, outcome) {
+    try {
+      audit().safeEmit({
+        action:   action,
+        outcome:  outcome || "success",
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent — audit best-effort */ }
+  }
+
+  // ---- Per-connection state machine ---------------------------------------
+  function _handleConnection(socket) {
+    var connectionId = "mxconn-" + bCrypto.generateToken(8);                                          // allow:raw-byte-literal — connection-id length
+    connections.add(socket);
+
+    var state = {
+      id:            connectionId,
+      remoteAddress: socket.remoteAddress || null,
+      remotePort:    socket.remotePort    || null,
+      tls:           false,
+      stage:         "connect",   // connect | ehlo | mail | rcpt | data-body | done
+      helo:          null,
+      mailFrom:      null,
+      rcpts:         [],
+      messageBytes:  0,
+    };
+
+    var lineBuffer = "";
+    var bodyCollector = null;
+    var inDataBody = false;
+
+    socket.setTimeout(idleTimeoutMs);
+    socket.on("timeout", function () {
+      _writeReply(socket, REPLY_421_SERVICE_NOT_AVAIL, "4.4.2 Idle timeout");
+      _closeConnection(socket);
+    });
+
+    socket.on("error", function (err) {
+      _emit("mail.server.mx.socket_error",
+        { connectionId: state.id, code: (err && err.code) || "unknown", message: err && err.message },
+        "warning");
+      _closeConnection(socket);
+    });
+
+    socket.on("close", function () {
+      connections.delete(socket);
+    });
+
+    _emit("mail.server.mx.connect", {
+      connectionId:  state.id,
+      remoteAddress: state.remoteAddress,
+      remotePort:    state.remotePort,
+      tls:           false,
+    });
+
+    // 220 banner — RFC 5321 §3.1.
+    _writeReply(socket, REPLY_220_READY, greeting + " ready");
+
+    socket.on("data", function (chunk) {
+      try { _ingestBytes(state, socket, chunk); }
+      catch (err) {
+        _emit("mail.server.mx.handler_threw",
+          { connectionId: state.id, error: (err && err.message) || String(err) },
+          "failure");
+        try { _writeReply(socket, REPLY_421_SERVICE_NOT_AVAIL, "4.3.0 Server error"); }
+        catch (_e) { /* socket already gone */ }
+        _closeConnection(socket);
+      }
+    });
+
+    // ---- Byte-level ingestion --------------------------------------------
+    function _ingestBytes(state, socket, chunk) {
+      if (inDataBody) {
+        // DATA body — accumulate via boundedChunkCollector, watch for
+        // canonical "\r\n.\r\n" terminator only. Bare-LF dot terminator
+        // is the SMTP smuggling shape (CVE-2023-51764); refused.
+        try { bodyCollector.push(chunk); }
+        catch (_e) {
+          _emit("mail.server.mx.data_refused",
+            { connectionId: state.id, reason: "body-too-large", maxBytes: maxMessageBytes },
+            "denied");
+          _writeReply(socket, REPLY_552_SIZE_EXCEEDED,
+            "5.3.4 Message size exceeds fixed maximum (" + maxMessageBytes + " bytes)");
+          _resetTransaction(state);
+          inDataBody = false;
+          bodyCollector = null;
+          return;
+        }
+        var collected = bodyCollector.result();
+        // Smuggling detector — bare LF dot-line in body before the
+        // CRLF dot terminator. Refuse the whole transaction; emit
+        // smuggling-detected audit.
+        if (guardSmtpCommand.detectBodySmuggling(collected)) {
+          _emit("mail.server.mx.smtp_smuggling_detected",
+            { connectionId: state.id, mailFrom: state.mailFrom, rcptCount: state.rcpts.length },
+            "denied");
+          _writeReply(socket, REPLY_554_TRANSACTION_FAILED,
+            "5.7.0 Bare-LF in DATA body refused (RFC 5321 §2.3.8; CVE-2023-51764 SMTP smuggling)");
+          _resetTransaction(state);
+          inDataBody = false;
+          bodyCollector = null;
+          return;
+        }
+        // Canonical \r\n.\r\n terminator?
+        var endIdx = safeSmtp.findDotTerminator(collected);
+        if (endIdx !== -1) {
+          var body = collected.subarray(0, endIdx);
+          _finalizeDataBody(state, socket, body);
+          inDataBody = false;
+          bodyCollector = null;
+        }
+        return;
+      }
+
+      // Command phase — line-buffered.
+      lineBuffer += chunk.toString("utf8");
+      if (lineBuffer.length > maxLineBytes * 4) {
+        _writeReply(socket, REPLY_500_SYNTAX,
+          "5.5.6 Line too long (>" + maxLineBytes + " bytes)");
+        _closeConnection(socket);
+        return;
+      }
+      var crlf;
+      while ((crlf = lineBuffer.indexOf("\r\n")) !== -1) {
+        var line = lineBuffer.slice(0, crlf);
+        lineBuffer = lineBuffer.slice(crlf + 2);
+        _handleCommand(state, socket, line);
+        if (inDataBody) return;
+      }
+    }
+
+    function _handleCommand(state, socket, line) {
+      // Per-line guard — refuse bare LF / NUL / C0 / DEL / oversize
+      // BEFORE state-machine dispatch.
+      try {
+        guardSmtpCommand.validate(line, { profile: profile, maxLineBytes: maxLineBytes });
+      } catch (err) {
+        if (err.code === "guard-smtp-command/bare-lf" ||
+            err.code === "guard-smtp-command/bare-cr" ||
+            err.code === "guard-smtp-command/nul-byte") {
+          _emit("mail.server.mx.smtp_smuggling_detected",
+            { connectionId: state.id, code: err.code, line: line.slice(0, 200) },                     // allow:raw-byte-literal — audit-log line truncation
+            "denied");
+        }
+        _writeReply(socket, REPLY_500_SYNTAX, "5.5.2 Syntax error (" + (err.code || "bad-line") + ")");
+        return;
+      }
+
+      var verb = line.split(/\s+/)[0].toUpperCase();
+      switch (verb) {
+        case "EHLO":
+        case "HELO":
+          _handleEhlo(state, socket, line, verb);
+          return;
+        case "STARTTLS":
+          _handleStartTls(state, socket);
+          return;
+        case "MAIL":
+          _handleMailFrom(state, socket, line);
+          return;
+        case "RCPT":
+          _handleRcptTo(state, socket, line);
+          return;
+        case "DATA":
+          _handleData(state, socket);
+          return;
+        case "NOOP":
+          _writeReply(socket, REPLY_250_OK, "2.0.0 OK");
+          return;
+        case "RSET":
+          _resetTransaction(state);
+          _writeReply(socket, REPLY_250_OK, "2.0.0 Reset");
+          return;
+        case "QUIT":
+          _writeReply(socket, REPLY_221_BYE, "2.0.0 Bye");
+          _closeConnection(socket);
+          return;
+        case "VRFY":
+        case "EXPN":
+          // Refuse VRFY/EXPN per modern best practice (information
+          // disclosure of internal aliases / valid recipients).
+          _writeReply(socket, REPLY_502_NOT_IMPLEMENTED, "5.5.1 Command not implemented");
+          return;
+        default:
+          _writeReply(socket, REPLY_500_SYNTAX, "5.5.2 Unknown command");
+      }
+    }
+
+    // ---- EHLO / HELO ------------------------------------------------------
+    function _handleEhlo(state, socket, line, verb) {
+      var helo = line.slice(verb.length).trim();
+      if (!helo) {
+        _writeReply(socket, REPLY_501_BAD_ARGS, "5.5.4 " + verb + " requires a domain argument");
+        return;
+      }
+      state.helo  = helo;
+      state.stage = "ehlo";
+      // Multi-line 250 capabilities advertisement per RFC 5321 §4.1.1.1.
+      if (verb === "EHLO") {
+        // EHLO capabilities advertised:
+        //   - PIPELINING per RFC 2920
+        //   - SIZE n per RFC 1870 §3 (with the per-server byte cap)
+        //   - 8BITMIME per RFC 6152 (obsoletes RFC 1652)
+        //   - STARTTLS per RFC 3207 §2 (only advertised pre-TLS)
+        //   - ENHANCEDSTATUSCODES per RFC 2034 (RFC 3463 code shape)
+        var caps = ["PIPELINING", "SIZE " + maxMessageBytes, "8BITMIME"];
+        if (!state.tls) caps.push("STARTTLS");
+        caps.push("ENHANCEDSTATUSCODES");
+        var lines = [greeting + " greets " + helo];
+        for (var i = 0; i < caps.length; i += 1) lines.push(caps[i]);
+        _writeMultiline(socket, REPLY_250_OK, lines);
+      } else {
+        _writeReply(socket, REPLY_250_OK, greeting + " greets " + helo);
+      }
+      _emit("mail.server.mx.helo",
+        { connectionId: state.id, verb: verb, helo: helo, tls: state.tls });
+    }
+
+    // ---- STARTTLS ---------------------------------------------------------
+    function _handleStartTls(state, socket) {
+      if (state.tls) {
+        _writeReply(socket, REPLY_503_BAD_SEQUENCE, "5.5.1 TLS already active");
+        return;
+      }
+      _writeReply(socket, REPLY_220_READY, "2.0.0 Ready to start TLS");
+      // STARTTLS-injection defense (CVE-2021-38371 Exim,
+      // CVE-2021-33515 Dovecot): clear the command buffer + body
+      // collector at upgrade time. Any commands pipelined (RFC 2920)
+      // BEFORE the TLS handshake are discarded — only commands sent
+      // on the post-handshake TLS socket are honored.
+      lineBuffer    = "";
+      bodyCollector = null;
+      inDataBody    = false;
+      var tlsSocket = new nodeTls.TLSSocket(socket, {
+        isServer:      true,
+        secureContext: opts.tlsContext,
+      });
+      tlsSocket.on("secure", function () {
+        state.tls   = true;
+        // After the handshake, the state machine restarts at EHLO
+        // (per RFC 3207 §4.2 — client MUST re-issue EHLO).
+        state.stage = "ehlo";
+        state.helo  = null;
+      });
+      tlsSocket.on("error", function (err) {
+        _emit("mail.server.mx.tls_handshake_failed",
+          { connectionId: state.id, code: (err && err.code) || "unknown",
+            message: err && err.message }, "failure");
+        _closeConnection(socket);
+      });
+      tlsSocket.on("data", function (chunk) {
+        try { _ingestBytes(state, tlsSocket, chunk); }
+        catch (err) {
+          _emit("mail.server.mx.handler_threw",
+            { connectionId: state.id, error: (err && err.message) || String(err) },
+            "failure");
+          _closeConnection(tlsSocket);
+        }
+      });
+    }
+
+    // ---- MAIL FROM --------------------------------------------------------
+    function _handleMailFrom(state, socket, line) {
+      if (!state.tls && _requiresStartTls()) {
+        _writeReply(socket, REPLY_530_AUTH_REQUIRED, "5.7.0 Must issue a STARTTLS command first");
+        return;
+      }
+      if (state.stage !== "ehlo" && state.stage !== "mail") {
+        _writeReply(socket, REPLY_503_BAD_SEQUENCE, "5.5.1 EHLO/HELO first");
+        return;
+      }
+      var match = line.match(RE_MAIL_FROM);
+      if (!match) {
+        _writeReply(socket, REPLY_501_BAD_ARGS,
+          "5.5.4 Syntax: MAIL FROM:<address> [SIZE=n]");
+        return;
+      }
+      var mailFrom = match[1].toLowerCase();
+      var paramStr = match[2] || "";
+      var sizeMatch = paramStr.match(RE_SIZE);
+      if (sizeMatch) {
+        var declaredSize = parseInt(sizeMatch[1], 10);
+        if (declaredSize > maxMessageBytes) {
+          _writeReply(socket, REPLY_552_SIZE_EXCEEDED,
+            "5.3.4 Message size exceeds fixed maximum (" + maxMessageBytes + " bytes)");
+          return;
+        }
+      }
+      state.mailFrom = mailFrom;
+      state.stage    = "rcpt";
+      state.rcpts    = [];
+      _emit("mail.server.mx.mail_from",
+        { connectionId: state.id, mailFrom: mailFrom });
+      _writeReply(socket, REPLY_250_OK, "2.1.0 Sender OK");
+    }
+
+    // ---- RCPT TO ----------------------------------------------------------
+    function _handleRcptTo(state, socket, line) {
+      if (state.stage !== "rcpt") {
+        _writeReply(socket, REPLY_503_BAD_SEQUENCE, "5.5.1 MAIL FROM first");
+        return;
+      }
+      if (state.rcpts.length >= maxRcptsPerMsg) {
+        _writeReply(socket, REPLY_452_INSUFFICIENT_STG,
+          "4.5.3 Too many recipients (limit " + maxRcptsPerMsg + ")");
+        return;
+      }
+      var match = line.match(RE_RCPT_TO);
+      if (!match) {
+        _writeReply(socket, REPLY_501_BAD_ARGS, "5.5.4 Syntax: RCPT TO:<address>");
+        return;
+      }
+      var rcpt = match[1].toLowerCase();
+      // Local-domain check — refuse non-local recipients unless the
+      // operator explicitly allowed relay for this scope.
+      if (localDomains.length > 0) {
+        var atIdx = rcpt.lastIndexOf("@");
+        var rcptDomain = atIdx === -1 ? "" : rcpt.slice(atIdx + 1);
+        if (localDomains.indexOf(rcptDomain) === -1 &&
+            !_isRelayAllowed(state.remoteAddress, rcpt)) {
+          _emit("mail.server.mx.relay_refused",
+            { connectionId: state.id, mailFrom: state.mailFrom, rcptTo: rcpt,
+              remoteAddress: state.remoteAddress }, "denied");
+          _writeReply(socket, REPLY_550_MAILBOX_UNAVAIL, "5.7.1 Relaying denied");
+          return;
+        }
+      }
+      state.rcpts.push(rcpt);
+      _emit("mail.server.mx.rcpt_to",
+        { connectionId: state.id, rcptTo: rcpt, rcptCount: state.rcpts.length });
+      _writeReply(socket, REPLY_250_OK, "2.1.5 Recipient OK");
+    }
+
+    // ---- DATA -------------------------------------------------------------
+    function _handleData(state, socket) {
+      if (state.stage !== "rcpt" || state.rcpts.length === 0) {
+        _writeReply(socket, REPLY_503_BAD_SEQUENCE, "5.5.1 No valid recipients");
+        return;
+      }
+      _writeReply(socket, REPLY_354_START_INPUT,
+        "End data with <CR><LF>.<CR><LF>");
+      state.stage    = "data-body";
+      inDataBody     = true;
+      bodyCollector  = safeBuffer.boundedChunkCollector({
+        maxBytes:    maxMessageBytes,
+        errorClass:  MailServerMxError,
+        sizeCode:    "mail-server-mx/body-too-large",
+        sizeMessage: "DATA body exceeded maxMessageBytes (" + maxMessageBytes + ")",
+      });
+    }
+
+    function _finalizeDataBody(state, socket, body) {
+      // body is the raw bytes BEFORE dot-stuffing reversal. RFC 5321
+      // §4.5.2 — a single leading "." is doubled on the wire; undo.
+      var dedotted = safeSmtp.dotUnstuff(body);
+      // operator-supplied agent handoff — when wired, persist via
+      // agent + write the 250 reply. When not wired, accept-and-drop
+      // (audit-only mode useful for staging deployments).
+      if (opts.agent && typeof opts.agent.handoff === "function") {
+        opts.agent.handoff({
+          mailFrom: state.mailFrom,
+          rcpts:    state.rcpts.slice(),
+          body:     dedotted,
+          remote:   { address: state.remoteAddress, port: state.remotePort },
+          tls:      state.tls,
+          helo:     state.helo,
+          connectionId: state.id,
+        }).then(function (ack) {
+          _emit("mail.server.mx.delivered",
+            { connectionId: state.id, messageId: ack && ack.messageId, sizeBytes: dedotted.length });
+          _writeReply(socket, REPLY_250_OK,
+            "2.6.0 Message accepted" + (ack && ack.messageId ? " <" + ack.messageId + ">" : ""));
+          _resetTransaction(state);
+        }).catch(function (err) {
+          _emit("mail.server.mx.data_refused",
+            { connectionId: state.id, reason: "agent-handoff-failed",
+              error: (err && err.message) || String(err) }, "failure");
+          _writeReply(socket, REPLY_451_LOCAL_ERROR,
+            "4.3.0 Local delivery error");
+          _resetTransaction(state);
+        });
+        return;
+      }
+      _emit("mail.server.mx.data_accepted",
+        { connectionId: state.id, mailFrom: state.mailFrom, rcptCount: state.rcpts.length,
+          sizeBytes: dedotted.length });
+      _writeReply(socket, REPLY_250_OK, "2.6.0 Message queued (audit-only)");
+      _resetTransaction(state);
+    }
+
+    function _resetTransaction(state) {
+      state.mailFrom = null;
+      state.rcpts    = [];
+      state.stage    = "ehlo";
+      state.messageBytes = 0;
+    }
+
+    function _requiresStartTls() {
+      // Strict / balanced require STARTTLS before MAIL FROM.
+      // Permissive accepts plaintext — operator-acknowledged downgrade
+      // for legacy infrastructure.
+      return profile === "strict" || profile === "balanced";
+    }
+
+    function _isRelayAllowed(_remoteAddress, _rcptTo) {
+      // Operator-supplied relayAllowedFor entries. v1 just checks
+      // presence in the array; CIDR/scope matching could be wired
+      // via b.middleware.networkAllowlist in a follow-up.
+      if (relayAllowedFor.length === 0) return false;
+      return true;
+    }
+  }
+
+  // ---- Lifecycle ----------------------------------------------------------
+  async function listen(listenOpts) {
+    listenOpts = listenOpts || {};
+    if (listening) {
+      throw new MailServerMxError("mail-server-mx/already-listening",
+        "listen: already listening");
+    }
+    // Port 0 (ephemeral, test mode) must NOT fall back to 25 — the
+    // `|| 25` short-circuit was a footgun on the test path.
+    var port    = listenOpts.port    === undefined ? 25 : listenOpts.port;                           // allow:raw-byte-literal — SMTP MX port (IANA)
+    var address = listenOpts.address || "0.0.0.0";
+    tcpServer = net.createServer(function (socket) {
+      _handleConnection(socket);
+    });
+    return new Promise(function (resolve, reject) {
+      tcpServer.once("error", reject);
+      tcpServer.listen(port, address, function () {
+        listening = true;
+        tcpServer.removeListener("error", reject);
+        _emit("mail.server.mx.listening", {
+          port: port, address: address,
+        });
+        resolve({ port: tcpServer.address().port, address: address });
+      });
+    });
+  }
+
+  async function close(closeOpts) {
+    closeOpts = closeOpts || {};
+    if (!listening) return;
+    var timeoutMs = closeOpts.timeoutMs || C.TIME.seconds(30);
+    listening = false;
+    tcpServer.close();
+    connections.forEach(function (sock) {
+      try { _writeReply(sock, REPLY_421_SERVICE_NOT_AVAIL, "4.3.0 Server shutting down"); }
+      catch (_e) { /* socket already gone */ }
+    });
+    var deadline = Date.now() + timeoutMs;
+    while (connections.size > 0 && Date.now() < deadline) {
+      await safeAsync.sleep(100);                                                                    // allow:raw-time-literal — close-drain poll interval (sub-second; operator-bounded by timeoutMs)
+    }
+    connections.forEach(function (sock) {
+      try { sock.destroy(); } catch (_e) { /* best-effort */ }
+    });
+    connections.clear();
+    _emit("mail.server.mx.closed", {});
+  }
+
+  function connectionCount() { return connections.size; }
+
+  return {
+    listen:           listen,
+    close:            close,
+    connectionCount:  connectionCount,
+    _portForTest:     function () { return tcpServer ? tcpServer.address().port : null; },
+  };
+}
+
+// ---- Wire-protocol helpers --------------------------------------------------
+
+function _writeReply(socket, code, text) {
+  // Single-line reply per RFC 5321 §4.2 — code SP text CRLF.
+  try { socket.write(code + " " + text + "\r\n"); }
+  catch (_e) { /* socket already closed */ }
+}
+
+function _writeMultiline(socket, code, lines) {
+  // Multi-line reply per RFC 5321 §4.2 — code "-" text CRLF for
+  // continuation, code SP text CRLF for the final line.
+  for (var i = 0; i < lines.length; i += 1) {
+    var sep = i === lines.length - 1 ? " " : "-";
+    try { socket.write(code + sep + lines[i] + "\r\n"); }
+    catch (_e) { /* socket already closed */ }
+  }
+}
+
+function _closeConnection(socket) {
+  try { socket.end(); } catch (_e) { /* best-effort */ }
+  try { socket.destroy(); } catch (_e) { /* best-effort */ }
+}
+
+module.exports = {
+  create:            create,
+  MailServerMxError: MailServerMxError,
+};