@blamejs/core 0.7.24 → 0.7.39

package/lib/mail-dkim.js

@@ -63,6 +63,12 @@ var ALLOWED_CANON = [
 ];
 var DEFAULT_HEADERS = ["from", "to", "subject", "date", "message-id"];
 
+// RSA modulus bit-size thresholds per RFC 8301 §3.1 + M³AAWG hardening
+// guidance. Anything below MIN must be considered failure; below WEAK
+// emits a warning so operators can quarantine while transitioning.
+var RSA_MIN_BITS  = 1024;                                                        // allow:raw-byte-literal — RFC 8301 RSA bit floor
+var RSA_WEAK_BITS = 2048;                                                        // allow:raw-byte-literal — RFC 8301 RSA bit weak threshold
+
 // ---- Canonicalization (RFC 6376 §3.4) ----
 
 function _canonHeaderRelaxed(name, value) {
@@ -184,11 +190,13 @@ function _foldSignatureHeader(unfolded) {
   var name = "DKIM-Signature: ";
   var rest = unfolded;
   if ((name + rest).length <= maxLine) return name + rest;
-  // Fold on tag boundaries (`; tag=value`). Keep the first chunk on
-  // the header line, subsequent chunks on continuation lines starting
-  // with TAB.
+  // Fold on tag boundaries (`; tag=value`). Each non-last chunk keeps
+  // its trailing `;` (RFC 6376 §3.2 — `;` is the tag-list separator,
+  // not a tag-end terminator; receivers' parsers expect it on the
+  // PRIOR line at fold points). Earlier shape ("v=1\r\n\ta=...;")
+  // missed the first separator and tripped strict parsers.
   var parts = rest.split("; ");
-  var lines = [name + parts[0]];
+  var lines = [name + parts[0] + (parts.length > 1 ? ";" : "")];
   for (var i = 1; i < parts.length; i++) {
     lines.push("\t" + parts[i] + (i < parts.length - 1 ? ";" : ""));
   }
@@ -379,6 +387,301 @@ function create(opts) {
 // Both signers are constructed eagerly at create-time (configuration
 // errors surface at boot, not at first send). The combined sign()
 // applies the RSA signer first, then the Ed25519 signer on top.
+// ---- DKIM-Signature verification (RFC 6376 §6) ----
+//
+// Counterpart to the signer. Walks every DKIM-Signature header in
+// the message, parses the tag list, fetches the signing public key
+// from DNS TXT at <selector>._domainkey.<domain>, canonicalizes the
+// body + headers per the c= tag, and runs nodeCrypto.verify.
+//
+// Surface:
+//
+//   var rv = await b.mail.dkim.verify(rfc822, {
+//     dnsLookup: async function (qname, type) { return [["v=DKIM1; k=rsa; p=BASE64..."]]; },
+//   });
+//   // → [{ d, s, alg, result, errors }, ...]
+//
+// One result per DKIM-Signature header (operators expect multiple
+// when senders dual-sign with RSA + Ed25519). Each result's `result`
+// is one of: "pass" / "fail" / "permerror" / "temperror" / "neutral".
+//
+// dnsLookup is operator-supplied so verify() composes with the
+// framework's b.network.dns (DoH / DoT / system) without taking a
+// hard dependency on it. When omitted, falls back to node:dns.
+
+function _parseDkimTagList(value) {
+  // RFC 6376 §3.2 — tags are `key=value` separated by `;`. Whitespace
+  // around `=` and `;` is allowed and stripped. The signer folds the
+  // DKIM-Signature header across CRLF + WSP; unfold first so tag
+  // boundaries land in the right place.
+  var unfolded = String(value).replace(/\r?\n[ \t]+/g, " ");
+  var tags = {};
+  var parts = unfolded.split(";");
+  for (var i = 0; i < parts.length; i += 1) {
+    var p = parts[i].trim();
+    if (p.length === 0) continue;
+    var eq = p.indexOf("=");
+    if (eq === -1) continue;
+    var key = p.slice(0, eq).trim().toLowerCase();
+    var val = p.slice(eq + 1).trim();
+    // Whitespace inside values is unfolded — RFC 6376 §3.2 says FWS
+    // (folding whitespace) is ignored within a tag value. Strip
+    // newlines + tabs while preserving the meaningful tokens.
+    val = val.replace(/\s+/g, "");
+    tags[key] = val;
+  }
+  return tags;
+}
+
+function _selectorTxtToKeyTags(txtRecords) {
+  // DKIM key record is a TXT record at <selector>._domainkey.<domain>.
+  // Format: "v=DKIM1; k=rsa; p=<base64>" (chunks may be split across
+  // multi-string TXT). Returns { v, k, p, t, h } or throws.
+  var joined = "";
+  if (Array.isArray(txtRecords)) {
+    for (var i = 0; i < txtRecords.length; i += 1) {
+      var rec = txtRecords[i];
+      joined = Array.isArray(rec) ? rec.join("") : String(rec);
+      if (joined.indexOf("v=DKIM1") === 0 || joined.indexOf("p=") !== -1) break;
+    }
+  } else {
+    joined = String(txtRecords || "");
+  }
+  if (joined.length === 0) {
+    throw new DkimError("dkim/key-not-found", "DKIM key record is empty");
+  }
+  return _parseDkimTagList(joined);
+}
+
+// Process-local cache for fetched DKIM key TXT records. Mailing-list
+// fan-out and bulk-replay scenarios frequently re-fetch the same
+// selector; without a cache the verifier hammers DNS. TTL bounded so
+// rotated keys propagate within minutes, not hours.
+var DKIM_KEY_CACHE = new Map();
+var DKIM_KEY_CACHE_TTL_MS = 5 * 60 * 1000;                                       // allow:raw-time-literal — TTL ms expression
+var DKIM_KEY_CACHE_MAX_ENTRIES = 1024;
+
+function _cacheGet(qname) {
+  var ent = DKIM_KEY_CACHE.get(qname);
+  if (!ent) return null;
+  if (ent.expires <= Date.now()) {
+    DKIM_KEY_CACHE.delete(qname);
+    return null;
+  }
+  return ent.tags;
+}
+
+function _cachePut(qname, tags) {
+  if (DKIM_KEY_CACHE.size >= DKIM_KEY_CACHE_MAX_ENTRIES) {
+    // Drop oldest (Map preserves insertion order). Cheap LRU-ish.
+    var oldest = DKIM_KEY_CACHE.keys().next().value;
+    if (oldest !== undefined) DKIM_KEY_CACHE.delete(oldest);
+  }
+  DKIM_KEY_CACHE.set(qname, { tags: tags, expires: Date.now() + DKIM_KEY_CACHE_TTL_MS });
+}
+
+function _resetDkimKeyCacheForTest() { DKIM_KEY_CACHE.clear(); }
+
+function _pemFromB64KeyMaterial(b64) {
+  // RSA: SubjectPublicKeyInfo DER in base64. Ed25519: raw 32-byte key
+  // OR SPKI DER. Wrap in PEM markers so node:crypto.createPublicKey
+  // accepts it.
+  var pem = "-----BEGIN PUBLIC KEY-----\n";
+  // 64-char wrap (PEM convention).
+  for (var i = 0; i < b64.length; i += 64) {                                     // allow:raw-byte-literal — PEM wrap width
+    pem += b64.slice(i, i + 64) + "\n";                                          // allow:raw-byte-literal — PEM wrap width
+  }
+  pem += "-----END PUBLIC KEY-----\n";
+  return pem;
+}
+
+async function _fetchDkimKey(domain, selector, dnsLookup) {
+  var qname = selector + "._domainkey." + domain;
+  var cached = _cacheGet(qname);
+  if (cached) return cached;
+  var records;
+  try {
+    if (dnsLookup) {
+      records = await dnsLookup(qname, "TXT");
+    } else {
+      var dnsModule = require("node:dns/promises");
+      records = await dnsModule.resolveTxt(qname);
+    }
+  } catch (e) {
+    if (e && (e.code === "ENOTFOUND" || e.code === "ENODATA")) {
+      throw new DkimError("dkim/key-not-found",
+        "no DKIM TXT record at " + qname);
+    }
+    throw new DkimError("dkim/key-lookup-temperror",
+      "DKIM TXT lookup for " + qname + " failed: " +
+      ((e && e.message) || String(e)));
+  }
+  var tags = _selectorTxtToKeyTags(records);
+  _cachePut(qname, tags);
+  return tags;
+}
+
+function _findDkimSignatureHeaders(parsedHeaders) {
+  var out = [];
+  for (var i = 0; i < parsedHeaders.length; i += 1) {
+    if (parsedHeaders[i].name.toLowerCase() === "dkim-signature") {
+      out.push({ index: i, name: parsedHeaders[i].name, value: parsedHeaders[i].value });
+    }
+  }
+  return out;
+}
+
+function _verifySingleSignature(rfc822, parsedHeaders, sigHeader, keyTags, sigTags) {
+  // Reconstruct what the signer canonicalized, per RFC 6376 §3.7.
+  var canonicalization = sigTags.c || "simple/simple";
+  var canonHeader = canonicalization.split("/")[0];
+  var canonBody   = canonicalization.split("/")[1];
+  var algorithm   = sigTags.a;
+
+  var split = _splitHeadersBody(rfc822);
+  var body = split.body;
+  if (sigTags.l !== undefined) {
+    // The framework refuses l= at SIGN-time per the M3AAWG / Gmail /
+    // Microsoft 365 guidance (v0.7.18). On VERIFY, an `l=` tag on an
+    // inbound signature signals append-after-signature exposure —
+    // operators decide acceptance. Honor the cap for the body hash so
+    // the signature still validates against legitimate senders that
+    // use l=, but flag in the result.
+    var lcap = parseInt(sigTags.l, 10);
+    if (isFinite(lcap) && lcap >= 0) body = body.slice(0, lcap);
+  }
+
+  // 1. Body-hash check.
+  var expectedBh = sigTags.bh;
+  if (typeof expectedBh !== "string") {
+    return { result: "permerror", errors: ["DKIM-Signature missing bh="] };
+  }
+  var actualBh = _bodyHashB64(body, algorithm, canonBody);
+  if (actualBh !== expectedBh) {
+    return { result: "fail", errors: ["body hash mismatch"] };
+  }
+
+  // 2. Canonicalize the headers in h= order, then the DKIM-Signature
+  //    header itself with the b= value emptied (per §3.7).
+  var headerNames = (sigTags.h || "").split(":").map(function (s) {
+    return s.trim().toLowerCase();
+  });
+  var lcNames = parsedHeaders.map(function (h) { return h.name.toLowerCase(); });
+  var canonicalizedHeaders = "";
+  for (var j = 0; j < headerNames.length; j += 1) {
+    var want = headerNames[j];
+    if (want.length === 0) continue;
+    var idx = lcNames.lastIndexOf(want);                                         // last-occurrence per the DKIM spec
+    if (idx === -1) continue;
+    var h = parsedHeaders[idx];
+    canonicalizedHeaders += canonHeader === "simple"
+      ? _canonHeaderSimple(h.name, h.value)
+      : _canonHeaderRelaxed(h.name, h.value);
+  }
+  // Strip the b= value from the DKIM-Signature header for the canonical
+  // form per §3.7.
+  var unsignedSigValue = sigHeader.value.replace(/(\bb=)[^;]*/i, "$1");
+  canonicalizedHeaders += canonHeader === "simple"
+    ? _canonHeaderSimple("DKIM-Signature", " " + unsignedSigValue).replace(/\r\n$/, "")
+    : _canonHeaderRelaxed("DKIM-Signature", unsignedSigValue).replace(/\r\n$/, "");
+
+  // 3. Verify the signature.
+  var sigB64 = sigTags.b;
+  if (typeof sigB64 !== "string") {
+    return { result: "permerror", errors: ["DKIM-Signature missing b="] };
+  }
+  var sigBuf = Buffer.from(sigB64, "base64");
+  var pem = _pemFromB64KeyMaterial(keyTags.p);
+  var keyObj;
+  try { keyObj = nodeCrypto.createPublicKey(pem); }
+  catch (e) {
+    return { result: "permerror",
+             errors: ["DKIM key parse failed: " + ((e && e.message) || String(e))] };
+  }
+
+  var nodeAlgo = algorithm === "rsa-sha256"     ? "sha256" :
+                 algorithm === "ed25519-sha256" ? null     : null;
+  if (algorithm !== "rsa-sha256" && algorithm !== "ed25519-sha256") {
+    return { result: "permerror",
+             errors: ["unsupported DKIM algorithm '" + algorithm + "'"] };
+  }
+
+  // Key-size enforcement (RFC 8301 §3.1, M³AAWG hardening guidance):
+  // RSA keys < 1024 bits MUST be considered failure; < 2048 is weak.
+  // The framework rejects < 1024 as a security baseline; < 2048 emits
+  // a warning in the result so operators can quarantine.
+  var warnings = [];
+  if (algorithm === "rsa-sha256" && keyObj.asymmetricKeyType === "rsa") {
+    var modBits = (keyObj.asymmetricKeyDetails && keyObj.asymmetricKeyDetails.modulusLength) || 0;
+    if (modBits > 0 && modBits < RSA_MIN_BITS) {
+      return { result: "fail",
+               errors: ["RSA key too small: " + modBits + " bits (RFC 8301 §3.1 minimum " + RSA_MIN_BITS + ")"] };
+    }
+    if (modBits > 0 && modBits < RSA_WEAK_BITS) {
+      warnings.push("rsa-key-weak: " + modBits + " bits (< " + RSA_WEAK_BITS + ")");
+    }
+  }
+  if (sigTags.l !== undefined) {
+    warnings.push("l-tag-present: append-after-signature exposure (RFC 6376 §8.2)");
+  }
+
+  var verified;
+  try {
+    verified = nodeCrypto.verify(nodeAlgo,
+      Buffer.from(canonicalizedHeaders, "utf8"), keyObj, sigBuf);
+  } catch (e) {
+    return { result: "permerror",
+             errors: ["DKIM verify threw: " + ((e && e.message) || String(e))] };
+  }
+  return verified
+    ? { result: "pass", errors: [], warnings: warnings }
+    : { result: "fail", errors: ["signature verification failed"], warnings: warnings };
+}
+
+async function verify(rfc822, opts) {
+  if (typeof rfc822 !== "string" || rfc822.length === 0) {
+    throw new DkimError("dkim/bad-input",
+      "verify(): rfc822 must be a non-empty string");
+  }
+  opts = opts || {};
+  validateOpts(opts, ["dnsLookup", "audit"], "mail.dkim.verify");
+
+  var split = _splitHeadersBody(rfc822);
+  var parsedHeaders = _parseHeaders(split.headers);
+  var sigHeaders = _findDkimSignatureHeaders(parsedHeaders);
+  if (sigHeaders.length === 0) {
+    return [{ result: "none", errors: ["no DKIM-Signature headers"] }];
+  }
+
+  var results = [];
+  for (var i = 0; i < sigHeaders.length; i += 1) {
+    var sigTags = _parseDkimTagList(sigHeaders[i].value);
+    var d = sigTags.d;
+    var s = sigTags.s;
+    var alg = sigTags.a;
+    if (!d || !s) {
+      results.push({ d: d || null, s: s || null, alg: alg || null,
+        result: "permerror", errors: ["DKIM-Signature missing d= or s="] });
+      continue;
+    }
+    var keyTags;
+    try { keyTags = await _fetchDkimKey(d, s, opts.dnsLookup); }
+    catch (e) {
+      var verdict = e.code === "dkim/key-lookup-temperror" ? "temperror" : "permerror";
+      results.push({ d: d, s: s, alg: alg, result: verdict, errors: [e.message] });
+      continue;
+    }
+    if (!keyTags.p) {
+      results.push({ d: d, s: s, alg: alg, result: "permerror",
+        errors: ["DKIM key record missing p="] });
+      continue;
+    }
+    var rv = _verifySingleSignature(rfc822, parsedHeaders, sigHeaders[i], keyTags, sigTags);
+    results.push(Object.assign({ d: d, s: s, alg: alg }, rv));
+  }
+  return results;
+}
+
 function dualSigner(opts) {
   if (!opts || !opts.rsa || !opts.eddsa) {
     throw new DkimError("dkim/dual-signer-missing",
@@ -412,6 +715,8 @@ function dualSigner(opts) {
 // directly without going through a full sign() round.
 module.exports = {
   create:      create,
+  verify:      verify,
+  _resetDkimKeyCacheForTest: _resetDkimKeyCacheForTest,
   dualSigner:  dualSigner,
   DkimError:   DkimError,
   _canonHeaderRelaxedForTest: _canonHeaderRelaxed,

package/lib/mail.js

@@ -70,6 +70,7 @@ var audit = lazyRequire(function () { return require("./audit"); });
 var httpClient = lazyRequire(function () { return require("./http-client"); });
 var guardEmail = lazyRequire(function () { return require("./guard-email"); });
 var mailDkim = require("./mail-dkim");
+var mailAuth = require("./mail-auth");
 var net = lazyRequire(function () { return require("net"); });
 var tls = lazyRequire(function () { return require("tls"); });
 var safeJson = require("./safe-json");
@@ -968,6 +969,13 @@ 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:       mailDkim,
+  // 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).
+  spf:        mailAuth.spf,
+  dmarc:      mailAuth.dmarc,
+  arc:        mailAuth.arc,
   // Test-only export: lets unit tests inspect the wire format without
   // standing up a TLS-capable SMTP fixture. Operators don't call this.
   _buildRfc822ForTest: _buildRfc822,