@blamejs/core 0.7.64 → 0.7.74

package/lib/mail-auth.js

@@ -34,10 +34,12 @@
 
 var dns = require("node:dns");
 var dnsPromises = dns.promises;
+var zlib = require("node:zlib");
 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 { MailAuthError } = require("./framework-error");
 
 var observability = lazyRequire(function () { return require("./observability"); });
@@ -744,17 +746,369 @@ function _runVerify(signedString, sigB64, algorithm, keyB64, label) {
 
 void C; // C is imported for future TIME constants in policy fetchers.
 
+// ---- ARC receiver-side trust evaluation (RFC 8617 §6) ----
+//
+// arc.verify confirms the cryptographic chain validates; arc.evaluate
+// is the operator-side trust decision: given a passing chain, did any
+// hop in the chain belong to a sealer the operator trusts? The trust
+// list is operator policy — typically the operator's own domain plus
+// upstream relays the operator has agreed to honor (mailing list
+// operators, MX-vendor middleware).
+//
+//   var rv = await b.mail.arc.evaluate(rfc822, {
+//     trustedSealers: ["example.com", "mailgun.net"],
+//   });
+//   // → { chainStatus: "pass", trusted: true, trustedHop: 2,
+//   //    trustedDomain: "mailgun.net" }
+
+async function arcEvaluate(rfc822, opts) {
+  if (typeof rfc822 !== "string" || rfc822.length === 0) {
+    throw new MailAuthError("mail-auth/arc-bad-input",
+      "arc.evaluate: rfc822 must be a non-empty string");
+  }
+  opts = opts || {};
+  if (!Array.isArray(opts.trustedSealers)) {
+    throw new MailAuthError("mail-auth/arc-bad-trusted-sealers",
+      "arc.evaluate: opts.trustedSealers must be an array of domain strings");
+  }
+  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;
+  }
+
+  var verdict = await arcVerify(rfc822, opts);
+  var out = {
+    chainStatus:    verdict.chainStatus,
+    hopCount:       verdict.hopCount,
+    trusted:        false,
+    trustedHop:     null,
+    trustedDomain:  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.
+  var headers = _parseHeaderLines(_splitHeaders(rfc822));
+  var hopDomains = {};
+  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();
+  }
+
+  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;
+    }
+  }
+  return out;
+}
+
+// ---- Authentication-Results header (RFC 8601) builder ----
+//
+// Build the A-R header value the receiving MTA prepends to the message
+// before delivery. Operators consume per-method results from
+// b.mail.spf.verify / b.mail.dmarc.evaluate / b.mail.arc.verify (or
+// .evaluate) and pass them to .emit; the framework formats the RFC
+// 8601-conformant header string.
+//
+//   var hdr = b.mail.authResults.emit({
+//     authservId: "mx.example.com",
+//     results: [
+//       { method: "spf",   result: "pass", smtpMailfrom: "user@sender.example" },
+//       { method: "dkim",  result: "pass", domain: "sender.example" },
+//       { method: "dmarc", result: "pass", from: "user@sender.example" },
+//       { method: "arc",   result: "pass" },
+//     ],
+//   });
+//   // → "Authentication-Results: mx.example.com;\r\n  spf=pass smtp.mailfrom=user@sender.example;\r\n  dkim=pass header.d=sender.example;\r\n  dmarc=pass header.from=user@sender.example;\r\n  arc=pass"
+
+var AR_VALID_RESULTS = {
+  pass: 1, fail: 1, neutral: 1, none: 1, softfail: 1, policy: 1,
+  permerror: 1, temperror: 1, hardfail: 1, bestguesspass: 1,
+};
+var AR_VALID_METHODS = {
+  auth: 1, dkim: 1, "dkim-adsp": 1, dmarc: 1, "domainkeys": 1,
+  "iprev": 1, "sender-id": 1, spf: 1, arc: 1, "smime": 1, dane: 1,
+  "vbr": 1, "dnswl": 1, "x-original-authentication-results": 1,
+};
+
+function authResultsEmit(opts) {
+  validateOpts.requireObject(opts, "authResults.emit", MailAuthError, "mail-auth/ar-bad-input");
+  validateOpts(opts, ["authservId", "results", "version", "fold"], "authResults.emit");
+  validateOpts.requireNonEmptyString(opts.authservId,
+    "authResults.emit: authservId", MailAuthError, "mail-auth/ar-bad-authserv-id");
+  if (/[\r\n\0]/.test(opts.authservId)) {
+    throw new MailAuthError("mail-auth/ar-bad-authserv-id",
+      "authResults.emit: authservId contains forbidden control characters");
+  }
+  if (!Array.isArray(opts.results)) {
+    throw new MailAuthError("mail-auth/ar-bad-results",
+      "authResults.emit: results must be an array");
+  }
+
+  var version = (opts.version === undefined || opts.version === null)
+    ? "1" : String(opts.version);
+  var head = opts.authservId + (version === "1" ? "" : " " + version);
+
+  if (opts.results.length === 0) {
+    // RFC 8601 §2.2 — when no methods evaluated, emit `none`.
+    return "Authentication-Results: " + head + "; none";
+  }
+
+  var clauses = [];
+  for (var i = 0; i < opts.results.length; i += 1) {
+    var r = opts.results[i];
+    if (!r || typeof r !== "object") {
+      throw new MailAuthError("mail-auth/ar-bad-result-entry",
+        "authResults.emit: results[" + i + "] must be an object");
+    }
+    var method = String(r.method || "").toLowerCase();
+    var result = String(r.result || "").toLowerCase();
+    if (!AR_VALID_METHODS[method]) {
+      throw new MailAuthError("mail-auth/ar-bad-method",
+        "authResults.emit: unknown method '" + r.method + "'");
+    }
+    if (!AR_VALID_RESULTS[result]) {
+      throw new MailAuthError("mail-auth/ar-bad-result",
+        "authResults.emit: unknown result '" + r.result + "' for method '" + method + "'");
+    }
+    var clause = method + "=" + result;
+    if (r.reason && typeof r.reason === "string" && !/[\r\n\0;]/.test(r.reason)) {
+      clause += ' reason="' + r.reason.replace(/"/g, "'") + '"';
+    }
+    // Method-specific properties (ptype.property=value triples per
+    // RFC 8601 §2.3). Operators pass them as flat object keys.
+    var props = {
+      smtpMailfrom: "smtp.mailfrom",
+      smtpHelo:     "smtp.helo",
+      domain:       "header.d",
+      selector:     "header.s",
+      from:         "header.from",
+      iprev:        "policy.iprev",
+      ip:           "policy.ip",
+      tls:          "policy.tls",
+    };
+    var propKeys = Object.keys(props);
+    for (var pk = 0; pk < propKeys.length; pk += 1) {
+      var k = propKeys[pk];
+      if (typeof r[k] === "string" && r[k].length > 0 && !/[\r\n\0;]/.test(r[k])) {
+        clause += " " + props[k] + "=" + r[k];
+      }
+    }
+    clauses.push(clause);
+  }
+
+  var fold = opts.fold !== false;
+  var sep = fold ? ";\r\n  " : "; ";
+  return "Authentication-Results: " + head + ";\r\n  " + clauses.join(sep);
+}
+
+// ---- DMARC aggregate (RUA) report parser (RFC 7489 §7.2 / draft-ietf-dmarc-aggregate-reporting) ----
+//
+// MTAs that publish a DMARC `rua=` policy receive aggregate reports
+// from peers — XML attached to a multipart/report mail body, often
+// gzip-compressed. This primitive accepts the report bytes (raw XML,
+// gzipped XML, or a parsed object) and returns a structured shape
+// with the metadata, published policy, and per-record evaluation
+// results.
+//
+//   var rv = b.mail.dmarc.parseAggregateReport(xmlBytes);
+//   // → {
+//   //     reportMetadata: { orgName, email, reportId, dateRange },
+//   //     policyPublished: { domain, adkim, aspf, p, sp, pct, ... },
+//   //     records: [{ sourceIp, count, dispositions, identifiers, authResults }]
+//   //   }
+
+var DMARC_RUA_MAX_REPORT_BYTES = C.BYTES.mib(8);
+var DMARC_RUA_MAX_RECORDS_PER_REPORT = 10000;                                     // allow:raw-byte-literal allow:raw-time-literal — record cap, not seconds
+
+function _arrayOf(value) {
+  if (value === undefined || value === null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function dmarcParseAggregateReport(input, opts) {
+  opts = opts || {};
+  var bytes;
+  if (Buffer.isBuffer(input)) bytes = input;
+  else if (typeof input === "string") bytes = Buffer.from(input, "utf8");
+  else if (input && typeof input === "object" && input.feedback) {
+    // operator already pre-parsed via safeXml; skip the parse step.
+    return _shapeAggregateReport(input);
+  }
+  else {
+    throw new MailAuthError("mail-auth/dmarc-rua-bad-input",
+      "dmarc.parseAggregateReport: input must be a Buffer, string, or pre-parsed object");
+  }
+  if (bytes.length > DMARC_RUA_MAX_REPORT_BYTES) {
+    throw new MailAuthError("mail-auth/dmarc-rua-too-large",
+      "dmarc.parseAggregateReport: report exceeds " + DMARC_RUA_MAX_REPORT_BYTES + " bytes");
+  }
+
+  // Auto-detect gzip via magic 0x1f 0x8b (RFC 1952). DMARC RUA reports
+  // are commonly zip- or gzip-compressed; the gzip magic check covers
+  // the bulk of real-world reports. ZIP archives need operator-side
+  // unzip first (the framework doesn't ship a ZIP primitive yet).
+  var contentType = (opts.contentType || "").toLowerCase();
+  var looksGzip = bytes.length >= 2 && bytes[0] === 0x1f && bytes[1] === 0x8b;
+  if (contentType.indexOf("gzip") !== -1 || looksGzip) {
+    try { bytes = zlib.gunzipSync(bytes, { maxOutputLength: DMARC_RUA_MAX_REPORT_BYTES }); }
+    catch (e) {
+      throw new MailAuthError("mail-auth/dmarc-rua-gunzip-failed",
+        "dmarc.parseAggregateReport: gunzip failed: " + ((e && e.message) || String(e)));
+    }
+  }
+
+  var parsed;
+  try { parsed = safeXml.parse(bytes.toString("utf8"), { maxBytes: DMARC_RUA_MAX_REPORT_BYTES }); }
+  catch (e) {
+    throw new MailAuthError("mail-auth/dmarc-rua-bad-xml",
+      "dmarc.parseAggregateReport: XML parse failed: " + ((e && e.message) || String(e)));
+  }
+  return _shapeAggregateReport(parsed);
+}
+
+function _shapeAggregateReport(parsed) {
+  if (!parsed || typeof parsed !== "object" || !parsed.feedback) {
+    throw new MailAuthError("mail-auth/dmarc-rua-no-feedback",
+      "dmarc.parseAggregateReport: report root must be <feedback>");
+  }
+  var feedback = parsed.feedback;
+  var rmRaw = feedback.report_metadata || {};
+  var ppRaw = feedback.policy_published || {};
+  var records = _arrayOf(feedback.record);
+  if (records.length > DMARC_RUA_MAX_RECORDS_PER_REPORT) {
+    throw new MailAuthError("mail-auth/dmarc-rua-too-many-records",
+      "dmarc.parseAggregateReport: report has " + records.length +
+      " records (cap " + DMARC_RUA_MAX_RECORDS_PER_REPORT + ")");
+  }
+
+  var dateRange = rmRaw.date_range || {};
+  var beginSec = parseInt(dateRange.begin, 10);
+  var endSec = parseInt(dateRange.end, 10);
+
+  var shaped = {
+    reportMetadata: {
+      orgName:    rmRaw.org_name || null,
+      email:      rmRaw.email || null,
+      reportId:   rmRaw.report_id || null,
+      extraContact: rmRaw.extra_contact_info || null,
+      dateRange: {
+        begin: isFinite(beginSec) ? beginSec : null,
+        end:   isFinite(endSec)   ? endSec   : null,
+      },
+    },
+    policyPublished: {
+      domain: ppRaw.domain || null,
+      adkim:  ppRaw.adkim  || null,
+      aspf:   ppRaw.aspf   || null,
+      p:      ppRaw.p      || null,
+      sp:     ppRaw.sp     || null,
+      pct:    ppRaw.pct === undefined ? null : parseInt(ppRaw.pct, 10),
+      fo:     ppRaw.fo     || null,
+    },
+    records: records.map(function (rec) {
+      var row = rec.row || {};
+      var pe = row.policy_evaluated || {};
+      var ids = rec.identifiers || {};
+      var ar = rec.auth_results || {};
+      var dkimResults = _arrayOf(ar.dkim).map(function (d) {
+        return {
+          domain:   d.domain   || null,
+          selector: d.selector || null,
+          result:   d.result   || null,
+          humanResult: d.human_result || null,
+        };
+      });
+      var spfResults = _arrayOf(ar.spf).map(function (s) {
+        return {
+          domain: s.domain || null,
+          result: s.result || null,
+          scope:  s.scope  || null,
+        };
+      });
+      var reasons = _arrayOf(pe.reason).map(function (r) {
+        return { type: r.type || null, comment: r.comment || null };
+      });
+      var count = parseInt(row.count, 10);
+      return {
+        sourceIp: row.source_ip || null,
+        count:    isFinite(count) ? count : null,
+        dispositions: {
+          disposition: pe.disposition || null,
+          dkim:        pe.dkim        || null,
+          spf:         pe.spf         || null,
+          reasons:     reasons,
+        },
+        identifiers: {
+          headerFrom:   ids.header_from   || null,
+          envelopeFrom: ids.envelope_from || null,
+          envelopeTo:   ids.envelope_to   || null,
+        },
+        authResults: {
+          dkim: dkimResults,
+          spf:  spfResults,
+        },
+      };
+    }),
+  };
+
+  // Convenience aggregates — most operators want the totals up front.
+  var totalCount = 0;
+  var passCount = 0;
+  var failCount = 0;
+  for (var i = 0; i < shaped.records.length; i += 1) {
+    var r = shaped.records[i];
+    if (typeof r.count === "number") totalCount += r.count;
+    var dispDkim = r.dispositions.dkim;
+    var dispSpf  = r.dispositions.spf;
+    if (dispDkim === "pass" || dispSpf === "pass") {
+      if (typeof r.count === "number") passCount += r.count;
+    } else {
+      if (typeof r.count === "number") failCount += r.count;
+    }
+  }
+  shaped.totals = {
+    messages:      totalCount,
+    aligned:       passCount,
+    notAligned:    failCount,
+  };
+  return shaped;
+}
+
 module.exports = {
   spf: Object.freeze({
     verify:        spfVerify,
     parseRecord:   _parseSpfRecord,
   }),
   dmarc: Object.freeze({
-    evaluate:      dmarcEvaluate,
-    parseRecord:   _parseDmarcRecord,
+    evaluate:                 dmarcEvaluate,
+    parseRecord:              _parseDmarcRecord,
+    parseAggregateReport:     dmarcParseAggregateReport,
   }),
   arc: Object.freeze({
     verify:        arcVerify,
+    evaluate:      arcEvaluate,
+  }),
+  authResults: Object.freeze({
+    emit:          authResultsEmit,
   }),
   MailAuthError: MailAuthError,
   SPF_DNS_LOOKUP_LIMIT: SPF_DNS_LOOKUP_LIMIT,

package/lib/mail-unsubscribe.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * mail-unsubscribe — RFC 8058 / RFC 2369 List-Unsubscribe support.
+ *
+ * Two pieces:
+ *   1. buildHeaders({ url, mailto, oneClick }) — produces the
+ *      `List-Unsubscribe` and (when oneClick) `List-Unsubscribe-Post`
+ *      header values that get merged into the outbound message.
+ *   2. handler({ onUnsubscribe }) — request-lifecycle middleware that
+ *      validates the RFC 8058 one-click POST body
+ *      (`List-Unsubscribe=One-Click`) and dispatches to the operator's
+ *      onUnsubscribe callback. Returns 200 OK with empty body on
+ *      success per RFC 8058 §3.1.
+ *
+ * Compliance context: Gmail + Yahoo bulk-sender requirements (Feb 2024)
+ * mandate one-click List-Unsubscribe for senders >= 5k/day. Microsoft
+ * 365 followed in 2025. Operators sending bulk transactional or
+ * marketing mail without these headers see escalating spam-folder /
+ * outright-reject rates.
+ *
+ *   var headers = b.mail.unsubscribe.buildHeaders({
+ *     url:      "https://example.com/u?token=...",
+ *     mailto:   "unsubscribe@example.com?subject=unsub-...",
+ *     oneClick: true,
+ *   });
+ *   // → {
+ *   //     "List-Unsubscribe": "<https://...>, <mailto:...>",
+ *   //     "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
+ *   //   }
+ *
+ *   var unsubMw = b.mail.unsubscribe.handler({
+ *     onUnsubscribe: async function (req, res) {
+ *       // Operator extracts the token from req.url / req.body and
+ *       // performs the unsubscribe. Returning resolves the request.
+ *       var token = new URL(req.url, "https://h").searchParams.get("token");
+ *       await db.markUnsubscribed(token);
+ *     },
+ *   });
+ *   app.post("/email/unsubscribe", unsubMw);
+ */
+
+var lazyRequire = require("./lazy-require");
+var safeUrl = require("./safe-url");
+
+var observability = lazyRequire(function () { return require("./observability"); });
+void observability;
+
+// Build the List-Unsubscribe + List-Unsubscribe-Post headers per
+// RFC 8058 + RFC 2369. Returns a headers object suitable for merging
+// into `b.mail.send({ headers })`.
+function buildHeaders(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new Error("buildHeaders: opts object required " +
+      "({ url?, mailto?, oneClick? })");
+  }
+  var parts = [];
+  if (typeof opts.url === "string" && opts.url.length > 0) {
+    // Validate URL — refuse non-https / non-http schemes.
+    var parsed = safeUrl.parse(opts.url, { allowedProtocols: safeUrl.ALLOW_HTTP_TLS });
+    if (!parsed) {
+      throw new Error("buildHeaders: opts.url must be a valid http(s) URL");
+    }
+    parts.push("<" + parsed.href + ">");
+  }
+  if (typeof opts.mailto === "string" && opts.mailto.length > 0) {
+    // mailto: is `mailto:addr` or `mailto:addr?subject=...&body=...`.
+    // Don't run safeUrl on it (mailto isn't in ALLOW_HTTP_TLS); just
+    // do a minimal shape check.
+    if (opts.mailto.indexOf("mailto:") === 0) {
+      parts.push("<" + opts.mailto + ">");
+    } else {
+      parts.push("<mailto:" + opts.mailto + ">");
+    }
+  }
+  if (parts.length === 0) {
+    throw new Error("buildHeaders: at least one of opts.url / opts.mailto required");
+  }
+  var headers = { "List-Unsubscribe": parts.join(", ") };
+  if (opts.oneClick === true) {
+    // RFC 8058 §2 — exact byte sequence required for one-click.
+    headers["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click";
+  }
+  return headers;
+}
+
+// RFC 8058 §3.1 one-click handler middleware.
+//
+// On POST, the body MUST contain `List-Unsubscribe=One-Click` (case-
+// sensitive, exact byte sequence). On match, the operator's
+// onUnsubscribe callback runs — the operator extracts the
+// per-recipient token from the URL or body and performs the
+// unsubscribe. Returning resolves the request with 200 OK.
+//
+// On non-POST or wrong body, the middleware refuses with 400.
+function handler(opts) {
+  opts = opts || {};
+  if (typeof opts.onUnsubscribe !== "function") {
+    throw new Error("mail.unsubscribe.handler: opts.onUnsubscribe " +
+      "must be a function (req, res) → Promise");
+  }
+  return async function unsubscribeMiddleware(req, res) {
+    if ((req.method || "").toUpperCase() !== "POST") {
+      res.statusCode = 405;
+      res.setHeader("Allow", "POST");
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("RFC 8058 one-click unsubscribe requires POST");
+      return;
+    }
+    var bodyChunks = [];
+    var totalLen = 0;
+    var maxBodyBytes = opts.maxBodyBytes || 4096;                                // allow:raw-byte-literal — RFC 8058 §3.1 body is short — `List-Unsubscribe=One-Click` plus operator additions
+    var bodyComplete = await new Promise(function (resolve) {
+      req.on("data", function (chunk) {
+        totalLen += chunk.length;
+        if (totalLen > maxBodyBytes) {
+          // Stop reading; we'll respond 413 below.
+          resolve(false);
+          return;
+        }
+        bodyChunks.push(chunk);
+      });
+      req.on("end", function () { resolve(true); });
+      req.on("error", function () { resolve(false); });
+    });
+    if (!bodyComplete) {
+      res.statusCode = 413;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("body exceeds max bytes for one-click unsubscribe");
+      return;
+    }
+    var body = Buffer.concat(bodyChunks).toString("utf8");
+    if (body.indexOf("List-Unsubscribe=One-Click") === -1) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("RFC 8058 §3.1: body must contain `List-Unsubscribe=One-Click`");
+      return;
+    }
+    try {
+      await opts.onUnsubscribe(req, res);
+      // If the operator didn't end the response, send 200 OK with
+      // empty body per RFC 8058 §3.1.
+      if (!res.writableEnded) {
+        res.statusCode = 200;
+        res.end();
+      }
+    } catch (err) {
+      if (!res.writableEnded) {
+        res.statusCode = 500;
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+        res.end("unsubscribe failed");
+      }
+      throw err;
+    }
+  };
+}
+
+module.exports = {
+  buildHeaders: buildHeaders,
+  handler:      handler,
+};