@blamejs/core 0.8.52 → 0.8.58

package/lib/mail-auth.js

@@ -35,11 +35,13 @@
 var dns = require("node:dns");
 var dnsPromises = dns.promises;
 var zlib = require("node:zlib");
+var net = require("node:net");
 var lazyRequire = require("./lazy-require");
 var validateOpts = require("./validate-opts");
 var C = require("./constants");
 var dkim = require("./mail-dkim");
 var safeXml = require("./parsers/safe-xml");
+var publicSuffix = require("./public-suffix");
 var { MailAuthError } = require("./framework-error");
 
 var observability = lazyRequire(function () { return require("./observability"); });
@@ -361,8 +363,22 @@ async function _fetchDmarcRecord(domain, dnsLookup) {
   return matches[0];
 }
 
+// RFC 7489 base policy keys + DMARCbis (draft-ietf-dmarc-dmarcbis)
+// extensions:
+//   np=<none|quarantine|reject>  policy for non-existent subdomains
+//   psd=<y|n|u>                  applies-at-public-suffix-domain (TLD
+//                                operator publishes a DMARC record on
+//                                the suffix itself)
+// Validation tier: parse is config-time (operator-supplied DNS bytes);
+// throw on malformed v= / unrecognized np= or psd= values rather than
+// silently dropping — operators with a typo'd record otherwise see the
+// fallback policy applied without warning.
+var DMARCBIS_VALID_NP = { none: 1, quarantine: 1, reject: 1 };
+var DMARCBIS_VALID_PSD = { y: 1, n: 1, u: 1 };
+
 function _parseDmarcRecord(text) {
-  var policy = { v: null, p: null, sp: null, pct: 100, adkim: "r", aspf: "r" };  // allow:raw-byte-literal — RFC 7489 default pct
+  var policy = { v: null, p: null, sp: null, np: null, psd: null,
+                 pct: 100, adkim: "r", aspf: "r" };                              // allow:raw-byte-literal — RFC 7489 default pct
   var pairs = text.split(";");
   for (var i = 0; i < pairs.length; i += 1) {
     var kv = pairs[i].trim();
@@ -377,6 +393,22 @@ function _parseDmarcRecord(text) {
     else if (key === "pct")   policy.pct = parseInt(val, 10);
     else if (key === "adkim") policy.adkim = val.toLowerCase();
     else if (key === "aspf")  policy.aspf = val.toLowerCase();
+    else if (key === "np") {
+      var npVal = val.toLowerCase();
+      if (!DMARCBIS_VALID_NP[npVal]) {
+        throw new MailAuthError("mail-auth/dmarcbis-bad-tag",
+          "DMARC np= must be one of none|quarantine|reject, got " + JSON.stringify(val));
+      }
+      policy.np = npVal;
+    }
+    else if (key === "psd") {
+      var psdVal = val.toLowerCase();
+      if (!DMARCBIS_VALID_PSD[psdVal]) {
+        throw new MailAuthError("mail-auth/dmarcbis-bad-tag",
+          "DMARC psd= must be one of y|n|u, got " + JSON.stringify(val));
+      }
+      policy.psd = psdVal;
+    }
   }
   if (policy.v !== "DMARC1") {
     throw new MailAuthError("mail-auth/dmarc-bad-version",
@@ -401,7 +433,8 @@ function _alignmentCheck(fromDomain, authDomain, mode) {
 
 async function dmarcEvaluate(opts) {
   opts = opts || {};
-  validateOpts(opts, ["from", "spf", "dkim", "dnsLookup"], "mail.dmarc.evaluate");
+  validateOpts(opts, ["from", "spf", "dkim", "dnsLookup", "domainExists"],
+               "mail.dmarc.evaluate");
   if (typeof opts.from !== "string") {
     throw new MailAuthError("mail-auth/dmarc-bad-from",
       "dmarc.evaluate: opts.from must be the From-header email address");
@@ -411,47 +444,89 @@ async function dmarcEvaluate(opts) {
     throw new MailAuthError("mail-auth/dmarc-bad-from",
       "dmarc.evaluate: opts.from is missing the @domain part");
   }
+  fromDomain = fromDomain.toLowerCase();
+
+  // DMARCbis (draft-ietf-dmarc-dmarcbis) replaces the legacy "drop one
+  // label" org-domain heuristic with a proper Public Suffix List lookup.
+  // organizationalDomain returns null when the input IS a public suffix
+  // (e.g. "co.uk") OR when no PSL match resolves; either way, the
+  // org-domain walk below short-circuits.
+  var orgDomain = null;
+  try { orgDomain = publicSuffix.organizationalDomain(fromDomain); }
+  catch (_e) { orgDomain = null; }
 
   var policy = null;
   var policyOriginDomain = null;
   var orgDomainPolicyApplied = false;
+  var psdPolicyApplied = false;
   try {
     var rec = await _fetchDmarcRecord(fromDomain, opts.dnsLookup);
     if (rec) {
       policy = _parseDmarcRecord(rec);
       policyOriginDomain = fromDomain;
-    } else {
-      // RFC 7489 §6.6.3 — when no DMARC record exists at the From
-      // domain, the receiver MUST walk to the organizational domain
-      // and query for a record there, then apply that record's `sp=`
-      // subdomain policy (or fall back to `p=`). Without a PSL we
-      // approximate the org domain by dropping one label at a time —
-      // covers the common one-level-subdomain case (mail.example.com
-      // → example.com) but not multi-label public suffixes (.co.uk).
-      // Operators with PSL-aware needs override `dnsLookup` and
-      // implement the full lookup themselves.
-      var labels = fromDomain.split(".");
-      if (labels.length >= 3) {
-        var parent = labels.slice(1).join(".");
-        var parentRec = await _fetchDmarcRecord(parent, opts.dnsLookup);
-        if (parentRec) {
-          var parentPolicy = _parseDmarcRecord(parentRec);
-          // Apply sp= if set, else fall back to p=. The result is the
-          // policy the receiver applies to mail from this subdomain.
-          parentPolicy.p = parentPolicy.sp || parentPolicy.p;
-          policy = parentPolicy;
-          policyOriginDomain = parent;
-          orgDomainPolicyApplied = true;
+    } else if (orgDomain && orgDomain !== fromDomain) {
+      // RFC 7489 §6.6.3 + DMARCbis §4.6 — fall through to organizational
+      // domain. When the org-domain record sets sp= it applies to this
+      // subdomain; otherwise p= is the operative policy.
+      var orgRec = await _fetchDmarcRecord(orgDomain, opts.dnsLookup);
+      if (orgRec) {
+        var orgPolicy = _parseDmarcRecord(orgRec);
+        orgPolicy.p = orgPolicy.sp || orgPolicy.p;
+        policy = orgPolicy;
+        policyOriginDomain = orgDomain;
+        orgDomainPolicyApplied = true;
+      }
+    }
+
+    // DMARCbis §4.7 — when the org-domain record carries `psd=y`, OR
+    // the published record sits at the public suffix itself (TLD
+    // operator), the receiver continues lookup at the public suffix
+    // for downstream DSP cooperation. We honor the `psd=y` opt-in by
+    // surfacing the tag so operators can route on it; the explicit
+    // suffix walk below covers the suffix-record case.
+    if (!policy) {
+      var suffix = null;
+      try { suffix = publicSuffix.publicSuffix(fromDomain); }
+      catch (_e) { suffix = null; }
+      if (suffix && suffix !== fromDomain && suffix !== orgDomain) {
+        var psdRec = await _fetchDmarcRecord(suffix, opts.dnsLookup);
+        if (psdRec) {
+          var psdPolicy = _parseDmarcRecord(psdRec);
+          if (psdPolicy.psd === "y") {
+            psdPolicy.p = psdPolicy.sp || psdPolicy.p;
+            policy = psdPolicy;
+            policyOriginDomain = suffix;
+            psdPolicyApplied = true;
+          }
         }
       }
     }
   } catch (e) {
     return { result: "temperror", explanation: e.message,
-             policy: null, alignment: { spf: false, dkim: false } };
+             policy: null, alignment: { spf: false, dkim: false },
+             orgDomain: orgDomain };
   }
   if (!policy) {
     return { result: "none", explanation: "no DMARC record at _dmarc." + fromDomain,
-             policy: null, alignment: { spf: false, dkim: false } };
+             policy: null, alignment: { spf: false, dkim: false },
+             orgDomain: orgDomain };
+  }
+
+  // DMARCbis §4.8 — non-existent subdomain (NXDOMAIN on MX/A/AAAA for
+  // the message-from domain) gets the np= policy when published. The
+  // operator wires the existence check via opts.domainExists; absent
+  // that callback we conservatively treat the domain as existing
+  // (the np= path is opt-in observability, not a downgrade gate).
+  var npApplied = false;
+  if (typeof policy.np === "string" && typeof opts.domainExists === "function" &&
+      orgDomainPolicyApplied) {
+    var exists = true;
+    try { exists = await opts.domainExists(fromDomain); }
+    catch (_e) { exists = true; }
+    if (exists === false) {
+      policy = Object.assign({}, policy, { p: policy.np });
+      npApplied = true;
+    }
   }
 
   var spfDomain = (opts.spf && opts.spf.domain) || null;
@@ -492,7 +567,10 @@ async function dmarcEvaluate(opts) {
     result:     pass ? "pass" : "fail",
     policy:     policy,
     policyOriginDomain:    policyOriginDomain,
+    orgDomain:             orgDomain,
     orgDomainPolicyApplied: orgDomainPolicyApplied,
+    psdPolicyApplied:      psdPolicyApplied,
+    npPolicyApplied:       npApplied,
     alignment:  { spf: spfAligned, dkim: dkimAligned },
     recommendedAction: recommendedAction,
     explanation: pass
@@ -967,7 +1045,11 @@ async function arcEvaluate(rfc822, opts) {
   var trusted = {};
   for (var ti = 0; ti < opts.trustedSealers.length; ti += 1) {
     var d = opts.trustedSealers[ti];
-    if (typeof d === "string" && d.length > 0) trusted[d.toLowerCase()] = true;
+    if (typeof d !== "string" || d.length === 0) {
+      throw new MailAuthError("mail-auth/arc-trust-eval-failed",
+        "arc.evaluate: trustedSealers[" + ti + "] must be a non-empty domain string");
+    }
+    trusted[d.toLowerCase()] = true;
   }
 
   var verdict = await arcVerify(rfc822, opts);
@@ -977,39 +1059,82 @@ async function arcEvaluate(rfc822, opts) {
     trusted:        false,
     trustedHop:     null,
     trustedDomain:  null,
+    // RFC 8617 §6 trust evaluation extension surface (B6).
+    //   trust:        "trusted" | "unverified" | "failed"
+    //   trustedHops:  [{ instance, domain }] of every trusted sealer
+    //                 in the validated chain
+    //   finalAr:      verbatim AAR from the most-recent hop (the
+    //                 receiver's view of upstream auth results)
+    //   breakAt:      first instance whose AMS or AS failed, or null
+    //                 when every hop verified
+    trust:          verdict.chainStatus === "pass" ? "unverified" : "failed",
+    trustedHops:    [],
+    finalAr:        null,
+    breakAt:        null,
   };
   if (verdict.reason) out.reason = verdict.reason;
 
-  if (verdict.chainStatus !== "pass" || !Array.isArray(verdict.hops)) return out;
-
-  // Re-extract the d= of each hop's AS from the original headers — the
-  // verify-result shape doesn't carry it. Walk hops most-recent-first
-  // so we attribute the trust decision to the deepest trusted sealer.
+  // Re-extract per-hop d= (signing domain on AS) AND the AAR text from
+  // the original headers — the verify-result shape doesn't carry
+  // them. One pass over the header section.
   var headers = _parseHeaderLines(_splitHeaders(rfc822));
   var hopDomains = {};
+  var hopAr = {};
   for (var hi = 0; hi < headers.length; hi += 1) {
     var line = headers[hi];
     var colonAt = line.indexOf(":");
     if (colonAt === -1) continue;
     var name = line.slice(0, colonAt).trim().toLowerCase();
-    if (name !== "arc-seal") continue;
     var value = line.slice(colonAt + 1).trim();
-    var iMatch = value.match(/(?:^|[;,\s])i=(\d+)/);                              // allow:regex-no-length-cap — header bounded by RFC 5322 998
-    var dMatch = value.match(/(?:^|[;,\s])d=([^\s;]+)/);                          // allow:regex-no-length-cap — header bounded by RFC 5322 998
-    if (iMatch && dMatch) hopDomains[parseInt(iMatch[1], 10)] = dMatch[1].toLowerCase();
+    if (name === "arc-seal") {
+      var iMatch = value.match(/(?:^|[;,\s])i=(\d+)/);                            // allow:regex-no-length-cap — header bounded by RFC 5322 998
+      var dMatch = value.match(/(?:^|[;,\s])d=([^\s;]+)/);                        // allow:regex-no-length-cap — header bounded by RFC 5322 998
+      if (iMatch && dMatch) hopDomains[parseInt(iMatch[1], 10)] = dMatch[1].toLowerCase();
+    } else if (name === "arc-authentication-results") {
+      var arIMatch = value.match(/\bi\s*=\s*(\d+)/);                              // allow:regex-no-length-cap — header bounded by RFC 5322 998
+      if (arIMatch) hopAr[parseInt(arIMatch[1], 10)] = value;
+    }
   }
 
+  // finalAr — the most-recent hop's AAR. Always populated when the
+  // chain has at least one hop (regardless of pass/fail), so the
+  // operator can surface upstream auth context even on a broken chain.
+  if (verdict.hopCount > 0) {
+    out.finalAr = hopAr[verdict.hopCount] || null;
+  }
+
+  // breakAt — first instance whose AMS or AS failed.
+  if (Array.isArray(verdict.hops)) {
+    for (var bi = 0; bi < verdict.hops.length; bi += 1) {
+      var bhop = verdict.hops[bi];
+      if (!bhop) continue;
+      if (bhop.amsResult !== "pass" || bhop.asResult !== "pass") {
+        out.breakAt = bhop.instance;
+        break;
+      }
+    }
+  }
+
+  if (verdict.chainStatus !== "pass" || !Array.isArray(verdict.hops)) return out;
+
+  // Walk hops most-recent-first so we attribute the primary trust
+  // decision to the deepest (closest-to-receiver) trusted sealer, but
+  // also collect EVERY trusted hop so the operator can audit the
+  // full custody chain.
   for (var ri2 = verdict.hops.length - 1; ri2 >= 0; ri2 -= 1) {
     var hop = verdict.hops[ri2];
     if (!hop || hop.amsResult !== "pass" || hop.asResult !== "pass") continue;
     var domain = hopDomains[hop.instance];
     if (domain && trusted[domain]) {
-      out.trusted = true;
-      out.trustedHop = hop.instance;
-      out.trustedDomain = domain;
-      break;
+      out.trustedHops.push({ instance: hop.instance, domain: domain });
+      if (!out.trusted) {
+        out.trusted = true;
+        out.trustedHop = hop.instance;
+        out.trustedDomain = domain;
+      }
     }
   }
+  out.trust = out.trusted ? "trusted" : "unverified";
   return out;
 }
 
@@ -1323,6 +1448,103 @@ function _shapeAggregateReport(parsed) {
   return shaped;
 }
 
+// ---- iprev (RFC 8601 §3) — Forward-Confirmed Reverse DNS verifier ----
+//
+// The receiving SMTP server reverse-resolves the connecting peer's IP
+// to a PTR name, forward-resolves the PTR name to an A or AAAA set,
+// and confirms the original IP appears in the forward set. Spoofed
+// PTR records (attacker controls the rDNS zone but not the forward
+// zone) fail this check and SHOULD be reflected in the
+// Authentication-Results header so downstream policies can react.
+//
+// Surface:
+//   await b.mail.iprev.verify(ip)
+//   → { result: "pass"|"fail"|"permerror"|"temperror",
+//       ptr, forward, fcrdns, ip }
+//
+// Returns "permerror" on bad-shape input (not an IP literal); returns
+// "temperror" on ENODATA / ENOTFOUND / lookup failure (the receiver
+// retries on transient DNS faults). Pure-DNS — no operator state.
+
+async function iprevVerify(ip) {
+  if (typeof ip !== "string" || ip.length === 0) {
+    return { result: "permerror", ip: ip || null,
+             ptr: null, forward: [], fcrdns: false,
+             explanation: "ip must be a non-empty string" };
+  }
+  if (!net.isIP(ip)) {
+    return { result: "permerror", ip: ip,
+             ptr: null, forward: [], fcrdns: false,
+             explanation: "ip is not a valid IPv4 / IPv6 literal" };
+  }
+
+  var ptrs;
+  try { ptrs = await dnsPromises.reverse(ip); }
+  catch (e) {
+    var rcode = e && e.code;
+    if (rcode === "ENOTFOUND" || rcode === "ENODATA") {
+      return { result: "fail", ip: ip,
+               ptr: null, forward: [], fcrdns: false,
+               explanation: "no PTR record for " + ip };
+    }
+    return { result: "temperror", ip: ip,
+             ptr: null, forward: [], fcrdns: false,
+             explanation: "PTR lookup failed: " + ((e && e.message) || String(e)) };
+  }
+  if (!Array.isArray(ptrs) || ptrs.length === 0) {
+    return { result: "fail", ip: ip,
+             ptr: null, forward: [], fcrdns: false,
+             explanation: "PTR returned empty answer set" };
+  }
+
+  // RFC 8601 §3 — when multiple PTRs exist the receiver picks ONE
+  // and continues. We pick the first (matches mainstream MTA
+  // behavior) and stash the rest for operator visibility on the
+  // out-of-band metadata.
+  var ptr = String(ptrs[0]);
+  var isV6 = net.isIPv6(ip);
+  var forwardAddrs;
+  try {
+    forwardAddrs = isV6
+      ? await dnsPromises.resolve6(ptr)
+      : await dnsPromises.resolve4(ptr);
+  } catch (e) {
+    var fcode = e && e.code;
+    if (fcode === "ENOTFOUND" || fcode === "ENODATA") {
+      return { result: "fail", ip: ip,
+               ptr: ptr, forward: [], fcrdns: false,
+               explanation: "no forward record for PTR " + ptr };
+    }
+    if (fcode === "ETIMEOUT" || fcode === "ESERVFAIL") {
+      return { result: "temperror", ip: ip,
+               ptr: ptr, forward: [], fcrdns: false,
+               explanation: "forward lookup transient failure: " + fcode };
+    }
+    // Anything else — propagate as temperror; Node DNS surfaces some
+    // non-RFC error codes via the platform resolver. Permerror only
+    // for definitive negative answers above.
+    throw new MailAuthError("mail-auth/iprev-temperror",
+      "iprev.verify: forward lookup of " + ptr + " threw: " +
+      ((e && e.message) || String(e)));
+  }
+  var forward = Array.isArray(forwardAddrs) ? forwardAddrs.slice() : [];
+  var ipLc = ip.toLowerCase();
+  var fcrdns = false;
+  for (var i = 0; i < forward.length; i += 1) {
+    if (String(forward[i]).toLowerCase() === ipLc) { fcrdns = true; break; }
+  }
+  return {
+    result:      fcrdns ? "pass" : "fail",
+    ip:          ip,
+    ptr:         ptr,
+    forward:     forward,
+    fcrdns:      fcrdns,
+    explanation: fcrdns
+      ? "PTR " + ptr + " forward-resolves to " + ip
+      : "PTR " + ptr + " does not forward-resolve to " + ip,
+  };
+}
+
 module.exports = {
   spf: Object.freeze({
     verify:        spfVerify,
@@ -1339,6 +1561,9 @@ module.exports = {
     sign:          require("./mail-arc-sign").sign,           // allow:inline-require — re-export from sibling module
     ALLOWED_CV:    require("./mail-arc-sign").ALLOWED_CV,     // allow:inline-require — re-export from sibling module
   }),
+  iprev: Object.freeze({
+    verify:        iprevVerify,
+  }),
   authResults: Object.freeze({
     emit:          authResultsEmit,
   }),