@blamejs/core 0.14.22 → 0.14.24

package/lib/mail-auth.js

@@ -2090,6 +2090,239 @@ function authResultsEmit(opts) {
   return "Authentication-Results: " + head + ";\r\n  " + clauses.join(sep);
 }
 
+// ---- Inbound message-authentication pipeline (RFC 7489 §6.6) ----
+//
+// One call runs the receiver-side authentication set on a message as it
+// arrives: SPF (RFC 7208) on the envelope identity, DKIM (RFC 6376) on
+// the message bytes, DMARC (RFC 7489 / DMARCbis) policy + alignment on
+// the From-header domain, and — when an authserv-id is supplied — the
+// RFC 8601 Authentication-Results header the receiver prepends before
+// delivery. b.mail.server.mx composes this at DATA time via its
+// guardEnvelope opt; operators running their own listeners (or doing
+// post-delivery verification in an agent) call it directly:
+//
+//   var v = await b.mail.inbound.verify({
+//     ip:         "203.0.113.5",
+//     helo:       "mail.sender.example",
+//     mailFrom:   "bounce@sender.example",
+//     message:    rfc5322Bytes,                  // string or Buffer
+//     authservId: "mx.example.com",
+//   });
+//   // → { spf, dkim, from, dmarc, authResults }
+//   if (v.dmarc.recommendedAction === "reject") { /* refuse 550 5.7.1 */ }
+//
+// From-header discipline (RFC 7489 §6.6.1): DMARC evaluates exactly one
+// author domain. A message with zero From fields, several From fields,
+// or several author addresses in one field is the header-duplication
+// spoofing shape — an attacker pairs an aligned-but-hidden From with the
+// one the mail client displays (the CVE-2024-7208 / CVE-2024-7209
+// hosted-relay spoofing class rides on exactly this ambiguity). Those
+// messages return `dmarc.result: "permerror"` with
+// `recommendedAction: "reject"` instead of picking one of the Froms.
+
+// RFC 5322 §2.1 — the header block ends at the first empty line. SMTP
+// wire format is CRLF; bare-LF input is accepted defensively for
+// operator-fed strings that lost CRs in their own tooling.
+function _splitHeaderBlock(message) {
+  var idx = message.indexOf("\r\n\r\n");
+  if (idx !== -1) return { headers: message.slice(0, idx), body: message.slice(idx + 4) };
+  idx = message.indexOf("\n\n");
+  if (idx !== -1) return { headers: message.slice(0, idx), body: message.slice(idx + 2) };
+  return { headers: message, body: "" };
+}
+
+// Quote-aware single pass over a From field value (RFC 5322 phrase
+// quoting): counts angle-addr pairs that contain an `@` (a `<` inside
+// a quoted-string is display-name text — `"John <Jr.> Smith" <u@d>`
+// is one author, not two) and top-level commas (address-list
+// separators; a comma inside a quoted display-name like
+// `"Doe, John" <j@d>` does not count). Records the content of the
+// last @-bearing angle-addr for extraction.
+function _countFromAuthors(value) {
+  var inQuote = false, inAngle = false, escaped = false;
+  var angleAddrs = 0, topCommas = 0, angleStart = -1;
+  var lastAddr = null;
+  for (var i = 0; i < value.length; i += 1) {
+    var ch = value.charAt(i);
+    if (escaped) { escaped = false; continue; }
+    if (ch === "\\") { escaped = true; continue; }
+    if (ch === "\"" && !inAngle) { inQuote = !inQuote; continue; }
+    if (inQuote) continue;
+    if (ch === "<" && !inAngle) { inAngle = true; angleStart = i; continue; }
+    if (ch === ">" && inAngle) {
+      inAngle = false;
+      var inner = value.slice(angleStart + 1, i).trim();
+      if (inner.indexOf("@") !== -1) { angleAddrs += 1; lastAddr = inner; }
+      continue;
+    }
+    if (ch === "," && !inAngle) topCommas += 1;
+  }
+  return { angleAddrs: angleAddrs, topCommas: topCommas, lastAddr: lastAddr };
+}
+
+// Unfold (RFC 5322 §2.2.3), collect every From: field, and extract the
+// author address. `count` is the number of From fields, widened by
+// multiple-author detection inside a single field: several @-bearing
+// angle-addrs, or a bare address-list separated by top-level commas
+// (RFC 7489 §6.6.1 — a multi-author From is the header-duplication
+// spoofing shape and must not have "one" author picked from it).
+function _extractFromHeaders(headerBlock) {
+  var unfolded = headerBlock.replace(/\r?\n[ \t]+/g, " ");
+  var lines = unfolded.split(/\r?\n/);
+  var fromValues = [];
+  for (var i = 0; i < lines.length; i += 1) {
+    var m = /^From[ \t]*:(.*)$/i.exec(lines[i]);
+    if (m) fromValues.push(m[1].trim());
+  }
+  if (fromValues.length === 0) return { count: 0, address: null, domain: null };
+  var count = fromValues.length;
+  var value = fromValues[0];
+  var authors = _countFromAuthors(value);
+  if (count === 1) {
+    if (authors.angleAddrs > 1) count = authors.angleAddrs;
+    else if (authors.topCommas > 0) count = authors.topCommas + 1;
+  }
+  var address;
+  if (authors.angleAddrs >= 1) {
+    // count > 1 is refused by the caller before the address is used;
+    // for the single-author case this is that author's angle-addr.
+    address = authors.lastAddr;
+  } else {
+    // Bare addr-spec form. An RFC 5322 addr-spec cannot contain
+    // whitespace or commas — their presence means an address list or
+    // display-name soup; extracting "the" domain from it would pick
+    // one of several authors (the §6.6.1 forbidden move), so the
+    // field is treated as unparsable instead.
+    address = value.trim();
+    if (/[\s,]/.test(address)) address = null;
+  }
+  var at = address ? address.lastIndexOf("@") : -1;
+  var domain = (at > 0 && address && at < address.length - 1)
+    ? address.slice(at + 1).toLowerCase()
+    : null;
+  return { count: count, address: address || null, domain: domain };
+}
+
+async function inboundVerify(opts) {
+  validateOpts.requireObject(opts, "inbound.verify", MailAuthError, "mail-auth/inbound-bad-input");
+  validateOpts(opts, ["ip", "helo", "mailFrom", "message", "dnsLookup", "domainExists",
+                       "maxSignatures", "clockSkewMs", "minRsaBits", "authservId"],
+               "mail.inbound.verify");
+  validateOpts.requireNonEmptyString(opts.ip, "inbound.verify: ip",
+    MailAuthError, "mail-auth/inbound-bad-ip");
+  if (opts.authservId !== undefined && opts.authservId !== null) {
+    validateOpts.requireNonEmptyString(opts.authservId, "inbound.verify: authservId",
+      MailAuthError, "mail-auth/inbound-bad-authserv-id");
+  }
+  var message = opts.message;
+  if (Buffer.isBuffer(message)) {
+    // DKIM canonicalization re-encodes the string form as UTF-8
+    // (lib/mail-dkim.js hashes Buffer.from(canonicalized, "utf8")), so
+    // the byte→string decode must be utf8 for valid-UTF-8 content to
+    // round-trip exactly. Non-UTF-8 8-bit content cannot survive any
+    // decode + utf8 re-encode; such messages verify as DKIM fail and
+    // DMARC falls back to the SPF identity (RFC 7489 §4.2 — one
+    // aligned authenticator is sufficient to pass).
+    message = message.toString("utf8");
+  }
+  if (typeof message !== "string" || message.length === 0) {
+    throw new MailAuthError("mail-auth/inbound-bad-message",
+      "inbound.verify: message must be a non-empty string or Buffer (the full RFC 5322 message)");
+  }
+  var mailFrom = (typeof opts.mailFrom === "string" && opts.mailFrom.length > 0) ? opts.mailFrom : null;
+  var helo     = (typeof opts.helo === "string" && opts.helo.length > 0) ? opts.helo : null;
+
+  // SPF — envelope identity: MAIL FROM, falling back to HELO for the
+  // null reverse-path (RFC 7208 §2.4). DNS failures surface as the
+  // RFC's temperror result, not as throws.
+  var spf;
+  if (mailFrom || helo) {
+    spf = await spfVerify({
+      ip:        opts.ip,
+      mailFrom:  mailFrom || undefined,
+      helo:      helo || undefined,
+      dnsLookup: opts.dnsLookup,
+    });
+  } else {
+    spf = { result: "none", domain: null,
+            explanation: "no MAIL FROM or HELO identity supplied", lookupCount: 0 };
+  }
+
+  // DKIM — every signature on the message (bounded by maxSignatures;
+  // a signature-less message verifies as a single `none` entry).
+  var dkimVerifyOpts = { dnsLookup: opts.dnsLookup };
+  if (opts.clockSkewMs !== undefined) dkimVerifyOpts.clockSkewMs = opts.clockSkewMs;
+  if (opts.maxSignatures !== undefined) dkimVerifyOpts.maxSignatures = opts.maxSignatures;
+  if (opts.minRsaBits !== undefined) dkimVerifyOpts.minRsaBits = opts.minRsaBits;
+  var dkimResults = await dkim.verify(message, dkimVerifyOpts);
+
+  // From header + DMARC policy/alignment.
+  var from = _extractFromHeaders(_splitHeaderBlock(message).headers);
+  var dmarc;
+  if (from.count === 1 && from.address && from.domain) {
+    dmarc = await dmarcEvaluate({
+      from:         from.address,
+      spf:          spf,
+      dkim:         dkimResults,
+      dnsLookup:    opts.dnsLookup,
+      domainExists: opts.domainExists,
+    });
+    // RFC 7489 §6.6.2 — a fail verdict computed while an authenticator
+    // returned temperror is not final: the very lookup that failed
+    // transiently could have produced the aligned pass. Surface
+    // temperror so the caller defers (the sender retries) instead of
+    // permanently refusing a legitimate sender during a DNS blip. A
+    // pass verdict stands — one aligned authenticator is sufficient
+    // regardless of the other's transient failure.
+    if (dmarc.result === "fail" &&
+        (spf.result === "temperror" ||
+         dkimResults.some(function (d) { return d.result === "temperror"; }))) {
+      dmarc.result            = "temperror";
+      dmarc.recommendedAction = null;
+      dmarc.explanation       = (dmarc.explanation ? dmarc.explanation + "; " : "") +
+        "fail computed while an authenticator returned temperror — transient, retry";
+    }
+  } else {
+    dmarc = {
+      result:            "permerror",
+      recommendedAction: "reject",
+      policy:            null,
+      alignment:         { spf: false, dkim: false },
+      orgDomain:         null,
+      explanation: from.count === 0
+        ? "message has no From header (RFC 7489 §6.6.1)"
+        : (from.count > 1
+            ? "message carries " + from.count + " From authors (RFC 7489 §6.6.1 — multi-From spoofing shape)"
+            : "From header has no parsable author domain"),
+    };
+  }
+
+  // RFC 8601 Authentication-Results — only when the caller identifies
+  // itself (the authserv-id is the receiver's own name; there is no
+  // sensible default the framework could invent).
+  var authResults = null;
+  if (opts.authservId) {
+    var arResults = [];
+    var spfEntry = { method: "spf", result: spf.result };
+    if (mailFrom) spfEntry.smtpMailfrom = mailFrom;
+    else if (helo) spfEntry.smtpHelo = helo;
+    arResults.push(spfEntry);
+    for (var di = 0; di < dkimResults.length; di += 1) {
+      var d = dkimResults[di];
+      var dkimEntry = { method: "dkim", result: d.result };
+      if (typeof d.d === "string" && d.d.length > 0) dkimEntry.domain = d.d;
+      if (typeof d.s === "string" && d.s.length > 0) dkimEntry.selector = d.s;
+      arResults.push(dkimEntry);
+    }
+    var dmarcEntry = { method: "dmarc", result: dmarc.result };
+    if (from.address) dmarcEntry.from = from.address;
+    arResults.push(dmarcEntry);
+    authResults = authResultsEmit({ authservId: opts.authservId, results: arResults });
+  }
+
+  return { spf: spf, dkim: dkimResults, from: from, dmarc: dmarc, authResults: authResults };
+}
+
 // ---- DMARC aggregate (RUA) report parser (RFC 7489 §7.2 / draft-ietf-dmarc-aggregate-reporting) ----
 //
 // MTAs that publish a DMARC `rua=` policy receive aggregate reports
@@ -2971,6 +3204,9 @@ module.exports = {
   authResults: Object.freeze({
     emit:          authResultsEmit,
   }),
+  inbound: Object.freeze({
+    verify:        inboundVerify,
+  }),
   MailAuthError: MailAuthError,
   SPF_DNS_LOOKUP_LIMIT: SPF_DNS_LOOKUP_LIMIT,
 };

package/lib/mail-dkim.js

@@ -1242,6 +1242,7 @@ module.exports = {
   RSA_MIN_BITS:               RSA_MIN_BITS,
   RSA_LEGACY_MIN_BITS:        RSA_LEGACY_MIN_BITS,
   DKIM_MAX_SIGNATURES_PER_MESSAGE: DKIM_MAX_SIGNATURES_PER_MESSAGE,
+  DKIM_MAX_SIGNATURES_PER_MESSAGE_CEILING: DKIM_MAX_SIGNATURES_PER_MESSAGE_CEILING,
   DKIM_CLOCK_SKEW_MS_MAX:     DKIM_CLOCK_SKEW_MS_MAX,
   _canonHeaderRelaxedForTest: _canonHeaderRelaxed,
   _canonBodyRelaxedForTest:   _canonBodyRelaxed,

package/lib/mail-server-mx.js

@@ -73,6 +73,8 @@
  *   - `mail.server.mx.rbl_refused`       — connecting IP on a DNS blocklist (zones)
  *   - `mail.server.mx.greylist_deferred` — (ip, from, rcpt) first-seen 450 deferral
  *   - `mail.server.mx.data_refused`      — refusal reason + SMTP code (5xx vs 4xx)
+ *   - `mail.server.mx.envelope_verdict`  — DATA-phase SPF/DKIM/DMARC results + action (accept / quarantine / reject / defer) + gate mode
+ *   - `mail.server.mx.envelope_error`    — DATA-phase authentication pipeline failure or timeout (disposition follows onTemperror)
  *   - `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
@@ -111,13 +113,20 @@
  *   (connecting-IP DNS blocklist, evaluated once per connection) and
  *   `opts.greylist` ((ip, from, rcpt) first-seen deferral) evaluate at
  *   RCPT TO and surface their verdicts on the `rcpt_to` event. The
- *   message-authentication gates (`b.guardEnvelope` SPF/DKIM/DMARC
- *   alignment) require the inbound SPF + DKIM verification results as
- *   inputs; that inbound-auth pipeline composes `b.mail.spf` +
- *   `b.mail.dmarc` + DKIM verification and lands as a follow-up, at
- *   which point the DATA-phase envelope/DMARC gate wires in. Until
- *   then operators run those checks on the delivered message via the
- *   agent handoff.
+ *   message-authentication gate (`opts.guardEnvelope`) runs at DATA
+ *   completion through `b.mail.inbound.verify` — SPF (RFC 7208) on the
+ *   envelope identity, DKIM (RFC 6376) on the message bytes, DMARC
+ *   (RFC 7489) policy + alignment on the From-header domain — and in
+ *   enforce mode refuses before the agent handoff: 550 5.7.26
+ *   (RFC 7372) when the sender's published policy says reject, 550
+ *   5.7.1 on the RFC 7489 §6.6.1 multi-From spoofing shape, 451 4.7.0
+ *   on DNS temperror or pipeline timeout (operator-tunable via
+ *   `onTemperror` / `timeoutMs`). Accepted messages carry the verdict
+ *   to the agent handoff as `auth` and gain the receiver's RFC 8601
+ *   Authentication-Results header — any sender-attached header forging
+ *   this receiver's authserv-id is stripped first (§5) — so downstream
+ *   consumers act on authenticated results instead of re-verifying;
+ *   monitor mode annotates without refusing.
  *
  * @card
  *   Inbound SMTP / MX listener. RFC 5321 state machine with SMTP-
@@ -144,6 +153,12 @@ var mailServerTls = require("./mail-server-tls");
 var { defineClass } = require("./framework-error");
 
 var audit = lazyRequire(function () { return require("./audit"); });
+// Lazy like the sibling host primitives' guard loads — the inbound
+// authentication pipeline (and the DKIM verifier whose range
+// constants the boot validation mirrors) only loads when an operator
+// wires opts.guardEnvelope.
+var mailAuth = lazyRequire(function () { return require("./mail-auth"); });
+var dkim = lazyRequire(function () { return require("./mail-dkim"); });
 
 var MailServerMxError = defineClass("MailServerMxError", { alwaysPermanent: true });
 
@@ -178,6 +193,59 @@ 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;
 
+// Map the b.mail.inbound.verify verdict to the DATA-phase gate action.
+// The sender's published DMARC policy drives it (RFC 7489 §6.3 p= /
+// §6.6.2 disposition): reject → refuse at the wire; quarantine →
+// deliver annotated (an MX cannot spam-folder — the downstream agent
+// owns disposition); none / pass → accept. DNS temperror defers or
+// accepts per the operator's onTemperror choice. permerror carries a
+// reject recommendation only for the multi-From spoofing shape
+// (RFC 7489 §6.6.1), set by the pipeline itself.
+function _envelopeActionFor(inbound, gate) {
+  var dmarc = inbound.dmarc || {};
+  if (dmarc.result === "temperror") {
+    return gate.onTemperror === "accept" ? "accept" : "defer";
+  }
+  if (dmarc.recommendedAction === "reject") return "reject";
+  if (dmarc.recommendedAction === "quarantine") return "quarantine";
+  return "accept";
+}
+
+// RFC 8601 §5 — an MTA adding its own Authentication-Results header
+// MUST first remove any existing instance claiming its authserv-id: a
+// sender can pre-attach a forged header carrying the receiver's name
+// ("Authentication-Results: mx.example.com; dmarc=pass") and downstream
+// consumers that trust the receiver's A-R header would read the forged
+// verdict instead of the computed one. Headers naming OTHER
+// authserv-ids are prior-hop information and stay. Operates on the
+// header block only — the block is decoded as latin1 (byte-preserving
+// round-trip) and the body bytes are never decoded at all, so 8-bit
+// content is untouched.
+function _stripForgedAuthResults(messageBuf, authservId) {
+  if (!authservId) return messageBuf;
+  var sepIdx = messageBuf.indexOf("\r\n\r\n");
+  var headerEnd = sepIdx === -1 ? messageBuf.length : sepIdx + 2;
+  var head = messageBuf.slice(0, headerEnd).toString("latin1");
+  var rest = messageBuf.slice(headerEnd);
+  if (head.toLowerCase().indexOf("authentication-results:") === -1) return messageBuf;
+  var lines = head.split("\r\n");
+  var out = [];
+  var skipping = false;
+  var prefix = "authentication-results:";
+  var wantId = authservId.toLowerCase();
+  for (var i = 0; i < lines.length; i += 1) {
+    var line = lines[i];
+    if (skipping && (line.charAt(0) === " " || line.charAt(0) === "\t")) continue;  // folded continuation
+    skipping = false;
+    if (line.slice(0, prefix.length).toLowerCase() === prefix) {
+      var idTok = line.slice(prefix.length).trim().split(/[;\s]/)[0].toLowerCase();
+      if (idTok === wantId) { skipping = true; continue; }
+    }
+    out.push(line);
+  }
+  return Buffer.concat([Buffer.from(out.join("\r\n"), "latin1"), rest]);
+}
+
 /**
  * @primitive b.mail.server.mx.create
  * @signature b.mail.server.mx.create(opts)
@@ -202,6 +270,16 @@ var RE_SIZE      = /SIZE=(\d+)/i;
  *   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
+ *   guardEnvelope:     true | {        // optional gate — DATA-phase SPF/DKIM/DMARC via b.mail.inbound.verify
+ *     mode?:          "enforce" | "monitor",   // default: enforce (monitor when profile is permissive)
+ *     onTemperror?:   "defer" | "accept",      // DNS temperror disposition; default "defer" (451 4.7.5)
+ *     authservId?:    string,                  // RFC 8601 authserv-id; default localDomains[0]
+ *     dnsLookup?:     function,                // async (qname, type) override for SPF/DKIM/DMARC lookups
+ *     maxSignatures?: number,                  // DKIM verify cap (1-16)
+ *     clockSkewMs?:   number,                  // DKIM timestamp skew tolerance
+ *     minRsaBits?:    number,                  // DKIM minimum RSA key size
+ *     timeoutMs?:     number,                  // pipeline wall-clock ceiling; default 20s (timeout → temperror disposition)
+ *   },
  *
  * @example
  *   var tls = b.network.tls.context({ cert: certPem, key: keyPem });
@@ -269,6 +347,92 @@ function create(opts) {
     rateLimit = mailServerRateLimit.create(opts.rateLimit || {});
   }
 
+  // DATA-phase message-authentication gate. `guardEnvelope: true`
+  // gates with defaults; an object tunes it. Like the sibling gates
+  // (helo / rbl / greylist) the phase is skipped when the operator
+  // doesn't wire it — the gate needs live DNS to evaluate the
+  // sender's published policy, which closed-network deployments may
+  // not have.
+  var envelopeGate = null;
+  if (opts.guardEnvelope !== undefined && opts.guardEnvelope !== false) {
+    if (opts.guardEnvelope !== true &&
+        (typeof opts.guardEnvelope !== "object" || opts.guardEnvelope === null ||
+         Array.isArray(opts.guardEnvelope))) {
+      throw new MailServerMxError("mail-server-mx/bad-opts",
+        "mail.server.mx.create: guardEnvelope must be true, false, or a config object");
+    }
+    var ge = opts.guardEnvelope === true ? {} : opts.guardEnvelope;
+    validateOpts(ge, ["mode", "onTemperror", "authservId", "dnsLookup",
+                      "maxSignatures", "clockSkewMs", "minRsaBits", "timeoutMs"],
+                 "mail.server.mx.guardEnvelope");
+    var geMode = (ge.mode === undefined || ge.mode === null)
+      ? (profile === "permissive" ? "monitor" : "enforce")
+      : ge.mode;
+    if (geMode !== "enforce" && geMode !== "monitor") {
+      throw new MailServerMxError("mail-server-mx/bad-opts",
+        "mail.server.mx.create: guardEnvelope.mode must be 'enforce' or 'monitor'");
+    }
+    var geOnTemperror = (ge.onTemperror === undefined || ge.onTemperror === null)
+      ? "defer" : ge.onTemperror;
+    if (geOnTemperror !== "defer" && geOnTemperror !== "accept") {
+      throw new MailServerMxError("mail-server-mx/bad-opts",
+        "mail.server.mx.create: guardEnvelope.onTemperror must be 'defer' or 'accept'");
+    }
+    if (ge.authservId !== undefined && ge.authservId !== null) {
+      validateOpts.requireNonEmptyString(ge.authservId,
+        "mail.server.mx.create: guardEnvelope.authservId",
+        MailServerMxError, "mail-server-mx/bad-opts");
+    }
+    if (ge.dnsLookup !== undefined && ge.dnsLookup !== null &&
+        typeof ge.dnsLookup !== "function") {
+      throw new MailServerMxError("mail-server-mx/bad-opts",
+        "mail.server.mx.create: guardEnvelope.dnsLookup must be a function");
+    }
+    // DKIM bounds caught at boot, not at the first DATA — mirroring
+    // the exact ranges b.mail.dkim.verify enforces per call, so an
+    // operator typo fails startup instead of turning every live
+    // message into an envelope_error + temperror disposition.
+    numericBounds.requireAllPositiveFiniteIntIfPresent(ge,
+      ["maxSignatures", "clockSkewMs", "minRsaBits", "timeoutMs"],
+      "mail.server.mx.guardEnvelope.", MailServerMxError, "mail-server-mx/bad-bound");
+    if (ge.maxSignatures !== undefined && ge.maxSignatures !== null &&
+        ge.maxSignatures > dkim().DKIM_MAX_SIGNATURES_PER_MESSAGE_CEILING) {
+      throw new MailServerMxError("mail-server-mx/bad-bound",
+        "mail.server.mx.create: guardEnvelope.maxSignatures " + ge.maxSignatures +
+        " exceeds the DKIM verifier ceiling " +
+        dkim().DKIM_MAX_SIGNATURES_PER_MESSAGE_CEILING +
+        " (RFC 6376 §6.1 fan-out DoS bound)");
+    }
+    if (ge.clockSkewMs !== undefined && ge.clockSkewMs !== null &&
+        ge.clockSkewMs > dkim().DKIM_CLOCK_SKEW_MS_MAX) {
+      throw new MailServerMxError("mail-server-mx/bad-bound",
+        "mail.server.mx.create: guardEnvelope.clockSkewMs " + ge.clockSkewMs +
+        " exceeds the DKIM verifier ceiling " + dkim().DKIM_CLOCK_SKEW_MS_MAX +
+        " (RFC 6376 §3.5 back-dating replay defense)");
+    }
+    envelopeGate = Object.freeze({
+      mode:          geMode,
+      onTemperror:   geOnTemperror,
+      // RFC 8601 authserv-id — the receiver's own name on the
+      // Authentication-Results header. Defaults to the first local
+      // domain; with neither, the header is skipped (the verdict
+      // still reaches the agent handoff).
+      authservId:    ge.authservId || localDomains[0] || null,
+      dnsLookup:     ge.dnsLookup || undefined,
+      maxSignatures: ge.maxSignatures,
+      clockSkewMs:   ge.clockSkewMs,
+      minRsaBits:    ge.minRsaBits,
+      // Wall-clock ceiling for the whole pipeline (SPF include chains
+      // + per-signature DKIM key fetches + DMARC policy walk). A
+      // message stuffed with signatures pointing at slow resolvers
+      // must not pin the connection slot — on timeout the message
+      // takes the temperror disposition (defer / accept per
+      // onTemperror).
+      timeoutMs:     (ge.timeoutMs === undefined || ge.timeoutMs === null)
+        ? C.TIME.seconds(20) : ge.timeoutMs,
+    });
+  }
+
   // Default-on operator-supplied-domain hardening. opts.localDomains
   // and the HELO / MAIL FROM / RCPT TO domain validations all route
   // through `b.guardDomain` for IDN homograph / Punycode-spoof defense
@@ -885,6 +1049,110 @@ function create(opts) {
           return;
         }
       }
+      // DATA-phase message authentication (opts.guardEnvelope) — SPF /
+      // DKIM / DMARC through b.mail.inbound.verify, refusing before the
+      // agent handoff so a policy-failing message never reaches storage.
+      var inboundAuth = null;
+      if (envelopeGate) {
+        var inboundVerdict = null;
+        try {
+          // Wall-clock ceiling around the whole pipeline — a message
+          // stuffed with signatures pointing at slow resolvers must
+          // not pin the connection slot. Timeout surfaces as
+          // SafeAsyncError(async/timeout) into the catch below.
+          inboundVerdict = await safeAsync.withTimeout(
+            mailAuth().inbound.verify({
+              ip:            state.remoteAddress,
+              helo:          state.helo || undefined,
+              mailFrom:      state.mailFrom || undefined,
+              message:       dedotted,
+              dnsLookup:     envelopeGate.dnsLookup,
+              maxSignatures: envelopeGate.maxSignatures,
+              clockSkewMs:   envelopeGate.clockSkewMs,
+              minRsaBits:    envelopeGate.minRsaBits,
+              authservId:    envelopeGate.authservId || undefined,
+            }),
+            envelopeGate.timeoutMs,
+            { name: "mail.server.mx.guardEnvelope" });
+        } catch (err) {
+          // Pipeline infrastructure failure or wall-clock timeout (not
+          // an authentication verdict). Same disposition as a DNS
+          // temperror: defer so the sender retries, or accept
+          // unauthenticated when the operator chose availability via
+          // onTemperror.
+          _emit("mail.server.mx.envelope_error", {
+            connectionId: state.id,
+            mailFrom:     state.mailFrom,
+            error:        (err && err.message) || String(err),
+          }, "failure");
+          if (envelopeGate.mode === "enforce" && envelopeGate.onTemperror === "defer") {
+            _writeReply(socket, REPLY_451_LOCAL_ERROR,
+              "4.7.0 Message authentication could not be completed; try again later");
+            _resetTransaction(state);
+            return;
+          }
+        }
+        if (inboundVerdict) {
+          var envAction = _envelopeActionFor(inboundVerdict, envelopeGate);
+          var dkimSummary = inboundVerdict.dkim.some(function (d) { return d.result === "pass"; })
+            ? "pass"
+            : (inboundVerdict.dkim[0] ? inboundVerdict.dkim[0].result : "none");
+          _emit("mail.server.mx.envelope_verdict", {
+            connectionId: state.id,
+            mailFrom:     state.mailFrom,
+            fromDomain:   inboundVerdict.from.domain,
+            spf:          inboundVerdict.spf.result,
+            dkim:         dkimSummary,
+            dmarc:        inboundVerdict.dmarc.result,
+            action:       envAction,
+            mode:         envelopeGate.mode,
+          }, (envAction === "reject" || envAction === "defer") ? "denied" : "success");
+          if (envelopeGate.mode === "enforce" && envAction === "reject") {
+            // RFC 7372 §3.2 — 5.7.26 ("multiple authentication checks
+            // failed") for a DMARC evaluation that failed; the
+            // multi-From / unparsable-author permerror shape is a
+            // message-acceptability refusal and keeps the generic
+            // 5.7.1.
+            var enhanced = inboundVerdict.dmarc.result === "fail" ? "5.7.26" : "5.7.1";
+            _writeReply(socket, REPLY_550_MAILBOX_UNAVAIL,
+              enhanced + " Message refused by sender authentication policy (DMARC " +
+              inboundVerdict.dmarc.result + "; SPF " + inboundVerdict.spf.result +
+              ", DKIM " + dkimSummary + ")");
+            _resetTransaction(state);
+            return;
+          }
+          if (envelopeGate.mode === "enforce" && envAction === "defer") {
+            _writeReply(socket, REPLY_451_LOCAL_ERROR,
+              "4.7.0 Sender authentication temporarily unavailable (DNS); try again later");
+            _resetTransaction(state);
+            return;
+          }
+          // Accept / quarantine / monitor mode: the verdict rides to
+          // the agent handoff as `auth`, and the receiver's RFC 8601
+          // Authentication-Results header is prepended so downstream
+          // consumers (spam-foldering quarantined mail included) act
+          // on authenticated results instead of re-verifying.
+          if (inboundVerdict.authResults) {
+            // RFC 8601 §5 — strip any sender-attached A-R header
+            // claiming this receiver's authserv-id before prepending
+            // the computed one (forged-verdict shadowing defense).
+            dedotted = _stripForgedAuthResults(dedotted, envelopeGate.authservId);
+            dedotted = Buffer.concat([
+              Buffer.from(inboundVerdict.authResults + "\r\n", "utf8"),
+              dedotted,
+            ]);
+          }
+          inboundAuth = {
+            spf:        inboundVerdict.spf,
+            dkim:       inboundVerdict.dkim,
+            dmarc:      inboundVerdict.dmarc,
+            from:       inboundVerdict.from,
+            action:     envAction,
+            mode:       envelopeGate.mode,
+            quarantine: envAction === "quarantine",
+          };
+        }
+      }
       // 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).
@@ -897,6 +1165,7 @@ function create(opts) {
           remote:   { address: state.remoteAddress, port: state.remotePort },
           tls:      state.tls,
           helo:     state.helo,
+          auth:     inboundAuth,
           connectionId: state.id,
         }).then(function (ack) {
           _emit("mail.server.mx.delivered",

package/lib/mail.js

@@ -1944,15 +1944,19 @@ module.exports = {
   // default, ed25519-sha256 opt-in). Wire it into the smtp transport
   // via opts.dkimSigner. See lib/mail-dkim.js for the full surface.
   dkim:       dkim,
-  // Inbound mail authentication-results verification: SPF (RFC 7208),
-  // DMARC (RFC 7489), ARC (RFC 8617). Outbound DKIM signing lives in
-  // .dkim above; per-hop DKIM verification is deferred (composes with
-  // the existing canonicalization helpers in lib/mail-dkim.js).
+  // Inbound mail authentication verification: SPF (RFC 7208), DKIM
+  // verify (RFC 6376, on .dkim above alongside outbound signing),
+  // DMARC (RFC 7489), ARC (RFC 8617). `.inbound.verify` is the
+  // one-call receiver pipeline — SPF + DKIM + From-header extraction +
+  // DMARC policy + the RFC 8601 Authentication-Results header —
+  // composed by b.mail.server.mx at DATA time via its guardEnvelope
+  // opt and callable directly by operator-built listeners.
   spf:         mailAuth.spf,
   dmarc:       mailAuth.dmarc,
   arc:         mailAuth.arc,
   iprev:       mailAuth.iprev,
   authResults: mailAuth.authResults,
+  inbound:     mailAuth.inbound,
   bimi:        mailBimi,
   // Test-only export: lets unit tests inspect the wire format without
   // standing up a TLS-capable SMTP fixture. Operators don't call this.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.14.22",
+  "version": "0.14.24",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",