@blamejs/core 0.18.53 → 0.18.55

package/lib/mail-helo.js

@@ -370,6 +370,16 @@ async function _runFcrdns(ip, resolver) {
   if (!rev) {
     return result;                                                                                      // unparseable IP — caller already rejected
   }
+  // The resolver must be able to answer the question before the answer means
+  // anything. A missing method is not a DNS condition, and letting it fall into
+  // the catch below turned a broken call into a clean "no reverse name" for
+  // every address the check ever ran on — `passed` stayed false, which looks
+  // exactly like an address with no PTR record.
+  if (typeof resolver.queryPtr !== "function") {
+    throw new MailHeloError("mail-helo/resolver-missing-queryptr",
+      "fcrdns requires resolver.queryPtr(name); the supplied resolver has none, " +
+      "so reverse DNS cannot be checked and a pass cannot be claimed");
+  }
   try {
     var ptr = await resolver.queryPtr(rev);
     if (ptr && ptr.rrs) {

package/lib/mail-rbl.js

@@ -253,9 +253,16 @@ function create(opts) {
     } catch (e) {
       // NXDOMAIN is the expected "not listed" response, not an error
       // condition. RFC 5782 §2.1.1 — absence of any A record means
-      // "not in list". Resolver surfaces this as resolver/nxdomain-or-
-      // error which we treat as the neutral verdict.
-      if (e && e.code === "resolver/nxdomain-or-error") {
+      // "not in list".
+      //
+      // ONLY NXDOMAIN. The resolver used to report every non-zero RCODE under
+      // one code, so this branch also caught SERVFAIL and REFUSED and returned
+      // the same clean verdict — a blocklist lookup that failed read exactly
+      // like a host that is not on the list. Anyone able to break the query
+      // could therefore clear themselves, which is the wrong direction for a
+      // blocklist to fail in. A failure now falls through to `rv.error` below,
+      // where the caller can see it.
+      if (e && e.code === "resolver/nxdomain") {
         // Neutral — not listed; not an error.
         return rv;
       }

package/lib/mail-send-deliver.js

@@ -11,7 +11,7 @@
  *   Turnkey outbound SMTP composer. Wraps the discovery chain
  *   (MX-lookup → MTA-STS-fetch + MX-allowlist match → DANE TLSA query
  *   → REQUIRETLS handshake hint) around the existing per-host
- *   `b.mail.smtpTransport` wire-layer, plus deferred-retry scheduling
+ *   `b.mail.transports.smtp` wire-layer, plus deferred-retry scheduling
  *   for transient failures and RFC 3464 DSN generation for permanent
  *   ones.
  *
@@ -32,14 +32,18 @@
  *       requireTls: true,
  *     });
  *     // → { delivered: [{ recipient, mxHost, tlsProtocol, ... }],
- *     //     deferred:  [{ recipient, reason, retryAfterMs }],
+ *     //     deferred:  [{ recipient, mxHost, reason, retryAfterMs }],
  *     //     failed:    [{ recipient, reason, dsnSent }] }
+ *     //   deferred.mxHost is the receiver that refused, or null when the
+ *     //   deferral happened before any host was reached (an MX lookup that
+ *     //   failed). A queue view without it cannot say which peer to chase.
  *
  *   Composes:
  *     - `b.network.smtp.policy.mtaSts.fetch` + `.matchMx`  → RFC 8461 enforcement
- *     - `b.network.smtp.policy.dane.tlsa`                  → RFC 7672 TLSA query
+ *     - `b.network.smtp.policy.dane.tlsa` + `.verifyChain` → RFC 7672 TLSA query
+ *                                                            and peer authentication
  *     - `b.network.dns.resolver` (operator-supplied)        → caching + DoH posture
- *     - `b.mail.smtpTransport`                              → SMTP wire layer
+ *     - `b.mail.transports.smtp`                            → SMTP wire layer
  *     - `b.mail.requireTls`                                 → RFC 8689 REQUIRETLS
  *     - `b.mailBounce`-style RFC 3464 DSN generation         → permanent-failure
  *                                                              report-mail
@@ -104,7 +108,16 @@ function _classifySmtpOutcome(err, response) {
   if (err) {
     var code = err.code || "";
     if (/^(ECONNREFUSED|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|ENOTFOUND)$/.test(code)) return "transient";
-    if (/mta-sts|tls-policy|dane|requiretls/i.test((err.code || "") + " " + (err.message || ""))) return "permanent";
+    // A DANE failure is about THIS HOST, not this recipient: the certificate
+    // did not match the records, or the records could not be used. The ordinary
+    // cause is a rollover part-way through DNS propagation, which resolves
+    // itself — and a DSN does not. Classified permanent it also skipped every
+    // remaining MX, so one host mid-rollover bounced mail the next host would
+    // have taken. RFC 7672 §2.2: try the other hosts, defer if none
+    // authenticates. Matched before the policy class below, which keeps its
+    // permanent verdict.
+    if (/\bdane\b/i.test((err.code || "") + " " + (err.message || ""))) return "transient";
+    if (/mta-sts|tls-policy|requiretls/i.test((err.code || "") + " " + (err.message || ""))) return "permanent";
   }
   return "transient";
 }
@@ -202,8 +215,22 @@ async function _resolveMx(domain, resolver, timeoutMs) {
     // .create()` wraps DoH and returns `{ rrs: [{ exchange, priority }],
     // ttl, ... }` — the wrapper carries TTL + provenance metadata.
     // Accept both shapes; refuse anything else.
+    //
+    // The resolver's records are NOT flat. b.network.dns decodes an MX RR into
+    // `{ name, type, typeName, ttl, decoded: { preference, exchange } }`, so
+    // reading `.exchange` off the record itself yields undefined — every MX
+    // host became undefined and the first thing to touch one failed. The
+    // comment above this normalisation asserted the flat shape, and no test
+    // caught the disagreement because every one of them passes a hand-written
+    // resolver returning exactly what the comment claimed. Only a query against
+    // a real DNS response shows the difference.
     if (mxs && !Array.isArray(mxs) && Array.isArray(mxs.rrs)) {
-      mxs = mxs.rrs;
+      mxs = mxs.rrs.map(function (rr) {
+        if (rr && rr.decoded && typeof rr.decoded.exchange === "string") {
+          return { exchange: rr.decoded.exchange, priority: rr.decoded.preference };
+        }
+        return rr;                                                               // already flat
+      });
     }
     if (!Array.isArray(mxs) || mxs.length === 0) {
       throw new DeliverError("deliver/no-mx",
@@ -277,15 +304,26 @@ async function _applyMtaStsPolicy(domain, mxs, policyMode, auditEmit) {
   return filtered;
 }
 
-// Apply DANE TLSA query per RFC 7672. Returns array of TLSA records
-// for the MX host, OR null when DANE is off / no records published.
-// The primitive composes the lookup; per-cert chain verification is
-// the operator's responsibility (or future b.network.smtp.policy.dane.
-// verifyChain extension).
-async function _fetchDaneTlsa(mxHost, port, daneMode, auditEmit) {
+// Apply DANE TLSA query per RFC 7672. Returns the array of TLSA records for
+// the MX host, or null when DANE is off, the records are unusable, or the peer
+// publishes none. The records are handed to the transport, which authenticates
+// the peer's certificate chain against them via dane.verifyChain — the lookup
+// on its own is discovery, and discovery is not what "enforce" promises.
+async function _fetchDaneTlsa(mxHost, port, daneMode, dnssecValidated, resolver, auditEmit) {
   if (daneMode === "off") return null;
+  // RFC 7672 §1.3: records that were not DNSSEC-validated MUST NOT be used.
+  // Under opportunistic with no assertion they are therefore unusable before
+  // they are fetched, so asking for them buys nothing and costs a DNS round
+  // trip per MX plus a warn on every delivery. `enforce` cannot reach here
+  // without the assertion — create() refuses that combination outright.
+  if (!dnssecValidated) return null;
   try {
-    var tlsa = await smtpPolicy().dane.tlsa(mxHost, port || DEFAULT_PORT_SMTP);
+    // The operator's resolver goes with the assertion: `dnssecValidated` is a
+    // statement about THEIR resolver, so the records have to come from it. A
+    // lookup that quietly used node:dns instead would let a non-validating
+    // system resolver supply spoofed TLSA data under a validated banner.
+    var tlsa = await smtpPolicy().dane.tlsa(mxHost, port || DEFAULT_PORT_SMTP,
+      { dnssecValidated: true, resolver: resolver || undefined });
     return tlsa && tlsa.length > 0 ? tlsa : null;
   } catch (e) {
     auditEmit("mail.send.deliver.dane.skip", "warn",
@@ -304,19 +342,25 @@ async function _fetchDaneTlsa(mxHost, port, daneMode, auditEmit) {
 // outbound relay) can wrap the wire-layer surface without monkey-
 // patching the framework's mail module.
 async function _tryHost(envelope, mxHost, hostnameLocal, opts) {
-  var factory = opts.transportFactory || mailModule().smtpTransport;
+  // `transports.smtp`, which is the name `lib/mail.js` actually exports. It was
+  // reached for as `smtpTransport` — a name nothing defines — so the default was
+  // `undefined`, calling it threw, the throw was classified as a transient peer
+  // problem, and an operator who did not pass `transportFactory` got every
+  // recipient deferred 4.4.4 forever with no socket ever opened. The option is
+  // documented as an override, so the default is the path most callers take.
+  var factory = opts.transportFactory || mailModule().transports.smtp;
   var transport = factory({
     host:         mxHost,
     port:         opts.port || DEFAULT_PORT_SMTP,
     ehloName:     hostnameLocal,
     timeoutMs:    opts.perHostTimeoutMs || DEFAULT_PER_HOST_TIMEOUT_MS,
     requireTls:   envelope.requireTls === true,
-    // tls / dane verification is handed off to smtpTransport when
-    // the operator wires opts.dane (TLSA pinning) via the message
-    // shape; v1 of deliver doesn't auto-pin from the TLSA record set
-    // because chain-verification needs the cert byte-level surface
-    // smtpTransport doesn't expose yet. Operators with strict DANE
-    // posture pass dane: tlsa[] into smtpTransport directly.
+    // The TLSA records fetched for THIS MX host. The transport matches the
+    // peer's certificate chain against them once the handshake completes and
+    // refuses the send on a mismatch (RFC 7672 §2.2). Absent when the peer
+    // publishes none, or when DANE is off — the transport then behaves as it
+    // always did.
+    dane:         envelope.tlsa || undefined,
   });
   return transport.send({
     from: envelope.from,
@@ -356,14 +400,21 @@ async function _deliverOne(envelope, recipient, ctx) {
   }
   var lastErr = null;
   var lastResponse = null;
+  // The host the deferral is about. Null until one is tried, so a recipient
+  // deferred before any peer was reached reports "no host" rather than
+  // omitting the field — a consumer can then tell that apart from a host that
+  // simply was not recorded.
+  var lastMxHost = null;
   for (var i = 0; i < mxs.length; i += 1) {
     var mx = mxs[i];
-    // DANE per-MX lookup. Skipped today for verification (operator
-    // composes directly into smtpTransport.dane); this branch carries
-    // the discovery so the audit chain records the policy posture
-    // applied to each delivery attempt.
+    lastMxHost = mx.exchange;
+    // DANE per-MX lookup. The records go to the transport, which matches the
+    // peer's certificate chain against them during the handshake.
+    var mxTlsa = null;
     try {
-      await _fetchDaneTlsa(mx.exchange, ctx.port, ctx.policy.dane, ctx.auditEmit);
+      mxTlsa = await _fetchDaneTlsa(mx.exchange, ctx.port, ctx.policy.dane,
+                                    ctx.policy.dnssecValidated, ctx.resolver,
+                                    ctx.auditEmit);
     } catch (daneErr) {
       // DANE "enforce": a TLSA lookup failure means this MX host cannot
       // be used for authenticated delivery (RFC 7672 §2.2). Fail this
@@ -385,6 +436,7 @@ async function _deliverOne(envelope, recipient, ctx) {
         recipient:  recipient,
         rfc822:     envelope.rfc822,
         requireTls: envelope.requireTls,
+        tlsa:       mxTlsa,
       }, mx.exchange, ctx.hostname, ctx);
       ctx.auditEmit("mail.send.deliver.delivered", "success", {
         recipient: recipient, mxHost: mx.exchange, mxPriority: mx.priority,
@@ -411,8 +463,13 @@ async function _deliverOne(envelope, recipient, ctx) {
     }
   }
   // All MX hosts returned transient — overall outcome is transient
-  // (defer + retry).
+  // (defer + retry). `mxHost` names the last host tried, because a queue an
+  // operator reads on a bad day has to answer WHICH receiver refused: a domain
+  // with several MX hosts defers on one of them, and that decides whether to
+  // wait, to contact that receiver, or to look at one's own transport security
+  // against that host.
   return { recipient: recipient, outcome: "transient",
+           mxHost: lastMxHost,
            reason: (lastErr && lastErr.message) || "all MX hosts failed transiently",
            reasonCode: (lastResponse && lastResponse.code) || "4.4.4" };
 }
@@ -428,7 +485,7 @@ async function _deliverOne(envelope, recipient, ctx) {
  * Build a turnkey delivery handle. Returns a `deliver(envelope)`
  * function that takes a single multi-recipient envelope, resolves
  * MX records per recipient domain, applies the operator's configured
- * MTA-STS / DANE policy, attempts delivery via `b.mail.smtpTransport`,
+ * MTA-STS / DANE policy, attempts delivery via `b.mail.transports.smtp`,
  * and returns a per-recipient outcome split into `delivered` /
  * `deferred` / `failed` arrays.
  *
@@ -437,6 +494,23 @@ async function _deliverOne(envelope, recipient, ctx) {
  * after the budget elapses. The primitive does not own a background
  * scheduler — operator job-runner owns the retry lifecycle.
  *
+ * DANE (RFC 7672) authenticates the peer, not just its DNS. When the peer
+ * publishes TLSA records, they are fetched and the certificate chain it
+ * presents during the handshake is matched against them; a peer whose chain
+ * matches none of its own records is refused and the next MX is tried.
+ *
+ * The TLSA lookup goes through `opts.resolver` when one is supplied, because
+ * the DNSSEC assertion below is a statement about THAT resolver. A resolver
+ * that cannot answer TLSA is refused rather than bypassed.
+ *
+ * Because RFC 7672 §1.3 forbids using records that were not DNSSEC-validated
+ * and node:dns does not expose the AD bit, only the operator can say whether
+ * their resolver validates. `policy.dnssecValidated: true` is that statement,
+ * and `dane: "enforce"` requires it: without it every peer that publishes TLSA
+ * would be refused while every peer that publishes none was delivered to.
+ * Under `"opportunistic"` the records are unusable without it, so none are
+ * fetched.
+ *
  * Failed recipients trigger DSN composition: a RFC 3464 multipart/
  * report message is built per failed recipient and handed to the
  * operator-supplied `dsn.onPermanentFailure(envelope, recipientResult,
@@ -452,6 +526,7 @@ async function _deliverOne(envelope, recipient, ctx) {
  *   policy: {
  *     mtaSts:   "enforce" | "testing" | "off",  // default "enforce" — RFC 8461 posture
  *     dane:     "opportunistic" | "enforce" | "off",  // default "opportunistic" — RFC 7672
+ *     dnssecValidated: boolean,            // default false — assert the resolver DNSSEC-validates; required by dane "enforce"
  *   },
  *   retry: {
  *     maxAttempts:  number,                // default 5
@@ -521,7 +596,7 @@ function create(opts) {
   var port = opts.port || DEFAULT_PORT_SMTP;
 
   var policy = opts.policy || {};
-  validateOpts(policy, ["mtaSts", "dane"], "mail.send.deliver.create.policy");
+  validateOpts(policy, ["mtaSts", "dane", "dnssecValidated"], "mail.send.deliver.create.policy");
   var policyMtaSts = policy.mtaSts || "enforce";
   if (["enforce", "testing", "off"].indexOf(policyMtaSts) === -1) {
     throw new DeliverError("deliver/bad-policy-mtaSts",
@@ -532,6 +607,25 @@ function create(opts) {
     throw new DeliverError("deliver/bad-policy-dane",
       "mail.send.deliver.create.policy.dane must be opportunistic|enforce|off");
   }
+  // RFC 7672 §1.3 forbids using TLSA records that were not DNSSEC-validated,
+  // and node:dns does not surface the AD bit, so only the operator can say
+  // whether their resolver validates. Without that assertion `enforce` refuses
+  // every peer that publishes TLSA while delivering normally to every peer that
+  // publishes none — the sender's misconfiguration charged to the recipient who
+  // did the work. It is a property of this sender's resolver, so it is settled
+  // once at create() rather than surfacing per-peer as a delivery failure.
+  if (policy.dnssecValidated !== undefined && typeof policy.dnssecValidated !== "boolean") {
+    throw new DeliverError("deliver/bad-policy-dnssec",
+      "mail.send.deliver.create.policy.dnssecValidated must be a boolean when set");
+  }
+  var daneDnssecValidated = policy.dnssecValidated === true;
+  if (policyDane === "enforce" && !daneDnssecValidated) {
+    throw new DeliverError("deliver/dane-no-dnssec",
+      "policy.dane \"enforce\" requires policy.dnssecValidated: true — TLSA records " +
+      "must be DNSSEC-validated before use (RFC 7672 §1.3), and without that " +
+      "assertion enforce can only refuse the peers that publish them. Set it when " +
+      "the resolver validates DNSSEC; otherwise use \"opportunistic\" or \"off\"");
+  }
 
   var retryOpts = opts.retry || {};
   validateOpts(retryOpts, ["maxAttempts", "backoffMs"], "mail.send.deliver.create.retry");
@@ -578,8 +672,22 @@ function create(opts) {
       throw new DeliverError("deliver/bad-envelope",
         "deliver: envelope is required");
     }
-    validateOpts.requireNonEmptyString(envelope.from,
-      "deliver.envelope.from", DeliverError, "deliver/bad-envelope-from");
+    // The EMPTY string is a value here, not a missing one: RFC 5321 §4.5.5
+    // requires the null reverse path `MAIL FROM:<>` for a delivery status
+    // notification, and `b.mail.transports.smtp` already turns `""` into
+    // exactly that. Refusing it as "non-empty required" meant this composer
+    // could not send the one message shape the spec reserves a syntax for, and
+    // its own documented DSN example put a real address in the reverse path —
+    // so a bounce that failed would bounce back to the bounce's sender.
+    //
+    // The framework's other readers of an envelope sender already know this:
+    // `b.mail.spf.verify` treats an empty `mailFrom` as the null sender and
+    // falls back to the HELO identity, which is RFC 7208 §2.4 exactly.
+    if (typeof envelope.from !== "string") {
+      throw new DeliverError("deliver/bad-envelope-from",
+        "deliver.envelope.from must be a string — use \"\" for the null " +
+        "reverse path (MAIL FROM:<>) that RFC 5321 requires of a DSN");
+    }
     if (!Array.isArray(envelope.to) || envelope.to.length === 0) {
       throw new DeliverError("deliver/bad-envelope-to",
         "deliver.envelope.to must be a non-empty array");
@@ -596,7 +704,8 @@ function create(opts) {
 
     var ctx = {
       resolver:           opts.resolver || null,
-      policy:             { mtaSts: policyMtaSts, dane: policyDane },
+      policy:             { mtaSts: policyMtaSts, dane: policyDane,
+                            dnssecValidated: daneDnssecValidated },
       hostname:           opts.hostname,
       port:               port,
       mxLookupTimeoutMs:  mxLookupTimeoutMs,
@@ -638,6 +747,10 @@ function create(opts) {
           var idx = Math.min(attempts - 1, backoffMs.length - 1);
           deferred.push({
             recipient:     res.recipient,
+            // The receiver the deferral is about, or null when none was
+            // reached. A queue that records the reason and the retry time and
+            // not the peer cannot answer the first question an operator asks.
+            mxHost:        res.mxHost === undefined ? null : res.mxHost,
             reason:        res.reason,
             reasonCode:    res.reasonCode,
             attempt:       attempts,
@@ -648,7 +761,13 @@ function create(opts) {
       }
       // permanent (either direct or transient-converted-to-permanent)
       var dsnSent = false;
-      if (dsnOpts) {
+      // A message sent with the NULL reverse path gets no DSN. RFC 5321 §4.5.5
+      // is explicit, and the reason is the whole point of the null sender: the
+      // DSN's `To:` is the original `from`, so bouncing a bounce addresses it
+      // to nobody and, where the peer is less careful, to itself. This is the
+      // loop the empty reverse path exists to stop, and it is reachable the
+      // moment `""` is accepted above.
+      if (dsnOpts && envelope.from !== "") {
         try {
           var dsnMessage = _buildDsnMessage({
             dsnFrom:         dsnOpts.from,