@blamejs/core 0.7.73 → 0.7.74

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **0.7.74** (2026-05-06) — Email receive-side parity: DMARC aggregate (RUA) report parser + ARC trust evaluation + Authentication-Results header builder + TLS-RPT receive-side report parser. Closes the "framework can send mail compliantly but can't receive compliantly" gap. **`b.mail.dmarc.parseAggregateReport(xmlBytes, { contentType? })`** parses RFC 7489 §7.2 aggregate XML reports through the framework's existing `lib/parsers/safe-xml.js` (the existing security-focused XML parser handles XXE / DOCTYPE / entity-expansion defenses by default). Auto-detects gzip via magic bytes (`0x1f 0x8b`) or `Content-Type: application/gzip`. Returns `{ reportMetadata, policyPublished, records, totals }` with per-record source-IP / count / policy-evaluated dispositions / identifiers / DKIM + SPF auth results, plus aggregated `messages` / `aligned` / `notAligned` totals operators want for dashboards. Caps report size at 8 MiB and records-per-report at 10 000. **`b.mail.arc.evaluate(rfc822, { trustedSealers })`** wraps the existing `arc.verify` cryptographic chain check with the operator-side trust decision: given a passing chain, did any hop in the chain belong to a sealer the operator trusts? Returns `{ chainStatus, trusted, trustedHop, trustedDomain }` walking hops most-recent-first so the deepest trusted sealer wins. **`b.mail.authResults.emit({ authservId, results, fold? })`** builds the RFC 8601 Authentication-Results header value — operators consume per-method results from `b.mail.spf.verify` / `b.mail.dmarc.evaluate` / `b.mail.arc.verify`, hand them to `.emit`, and the framework formats the conformant header string with method-specific properties (`smtp.mailfrom`, `header.d`, `header.from`, `policy.iprev`, `policy.ip`, `policy.tls`). Refuses unknown methods / results at config-mistake time. **`b.network.smtp.tlsRpt.parseReport(body, { contentType? })`** is the receive-side counterpart to `tlsRpt.recordShape` / `tlsRpt.submit` — accepts a Buffer or string, auto-detects gzip, parses JSON, validates the RFC 8460 §4.4 required-fields shape (`organization-name`, `date-range`, `report-id`, `policies`), aggregates `total-successful-session-count` / `total-failure-session-count` across policies. Caps report size at 8 MiB and policies-per-report at 1024.
+
 - **0.7.73** (2026-05-06) — `b.auth.aal` + `b.middleware.requireAal({ minimum })` — NIST SP 800-63-4 Authentication Assurance Level bands. **`b.auth.aal.fromMethods({ password, totp, webauthn, ... })`** combines a set of operator-asserted authenticator methods into the resulting band: `AAL1` (single factor — memorized secret OR single-factor cryptographic), `AAL2` (multi-factor — memorized secret + OTP/SMS/hardware/mTLS), `AAL3` (phishing-resistant multi-factor — WebAuthn / passkey / hardware-+-PIN). Recognized methods: `password`, `pin`, `totp`, `sms`, `webauthn`, `passkey`, `hardware`, `mtls`. **`b.middleware.requireAal({ minimum, getAal?, audit?, realm? })`** gates routes by the request's AAL band — reads `req.user.aal` by default (or operator-supplied `getAal(req)`), compares against the minimum, returns 401 with `WWW-Authenticate: AAL-StepUp realm="...", required="AAL2"` on insufficient assurance. The bespoke scheme name signals to the operator's frontend that a step-up flow should be triggered (re-prompt for TOTP / passkey) without reusing the generic `Bearer` challenge namespace. Audit emits `auth.aal.granted` / `auth.aal.denied` (drop-silent on observability sink failure). The framework leaves AMR/ACR claim emission to the operator's IdP; the new `b.auth.aal.AMR` constants object provides consistent OIDC-conformant strings for operators emitting access tokens with AAL info. Also exposes `b.auth.aal.meets(actual, required)` for ad-hoc band comparisons outside the middleware. **CI vendor-manifest gate fix**: vendor files now have an explicit `.gitattributes` `lib/vendor/** -text binary` declaration so git never rewrites line endings between Windows and Linux checkouts. The `lib/vendor/noble-ciphers.cjs` file was renormalized to LF on disk and re-hashed in `lib/vendor/MANIFEST.json`. Closes the v0.7.65–0.7.72 npm-publish.yml smoke-test failures (`vendor manifest: @noble/ciphers :: server hash matches`).
 
 - **0.7.72** (2026-05-06) — `b.mail` gains EAI / SMTPUTF8 / Punycode-IDN support (RFC 6531 / 6532 / 6533 / 3492). **Internationalized email addresses** (`müller@münchen.example`) now validate through `b.mail.send()` — `_isValidEmail` detects non-ASCII content, converts the IDN domain to Punycode via Node's `url.domainToASCII`, and re-tests the assembled `local@ascii-domain` against the framework's pragmatic email regex. Local parts may legitimately contain Unicode under RFC 6531 §3.3 (the regex check substitutes a placeholder local for the format gate; the original local-part is still refused if it contains CRLF/NUL header-injection bytes). **`b.mail.toAscii(domain)`** and **`b.mail.toUnicode(domain)`** are the operator-facing wrappers around `node:url`'s IDN helpers — one obvious place to reach for Punycode encoding when handling addresses outside `send()`. **SMTP transport** now captures EHLO extension lines (250-X continuations) and detects `SMTPUTF8`. Messages whose from / to / cc / bcc / subject contain non-ASCII octets compute `requiresSmtpUtf8 = true`; when the peer advertises `SMTPUTF8` the transport appends ` SMTPUTF8` to `MAIL FROM:<...>` per RFC 6531 §3.4. When the peer does NOT advertise `SMTPUTF8` AND the message requires it, the transport refuses with `mail/smtp-failed: eai-required-not-supported` rather than emit a mangled wire (some peers would silently corrupt headers downstream). Pure-ASCII messages continue without the keyword (some legacy mailboxes reject `SMTPUTF8` outright on transactions that don't need it).

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.js

@@ -1098,9 +1098,10 @@ module.exports = {
   // 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,
+  spf:         mailAuth.spf,
+  dmarc:       mailAuth.dmarc,
+  arc:         mailAuth.arc,
+  authResults: mailAuth.authResults,
   // 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,

package/lib/network-smtp-policy.js

@@ -60,6 +60,7 @@ var lazyRequire = require("./lazy-require");
 var validateOpts = require("./validate-opts");
 var crypto = require("./crypto");
 var safeUrl = require("./safe-url");
+var safeJson = require("./safe-json");
 var C = require("./constants");
 var { SmtpPolicyError } = require("./framework-error");
 
@@ -535,6 +536,115 @@ async function tlsRptSubmit(report, opts) {
   return { submitted: results.length, results: results };
 }
 
+// ---- TLS-RPT receive-side report parsing (RFC 8460 §4) ----
+//
+// MTAs that publish a TLS-RPT rua endpoint receive `application/
+// tlsrpt+gzip` (or `application/json`) HTTPS POSTs from peers. The
+// receiver parses the report, attributes failures to the right policy/
+// MX-host pair, and feeds the data into the operator's observability
+// stack. This primitive is the receive-side counterpart to
+// tlsRpt.recordShape / tlsRpt.submit on the send side.
+
+var TLS_RPT_MAX_REPORT_BYTES = C.BYTES.mib(8);
+var TLS_RPT_MAX_POLICIES_PER_REPORT = 1024;                                       // allow:raw-byte-literal allow:raw-time-literal — count cap, not seconds
+
+function tlsRptParseReport(body, opts) {
+  opts = opts || {};
+  if (body === null || body === undefined) {
+    throw new SmtpPolicyError("smtp/tls-rpt-bad-input",
+      "tlsRpt.parseReport: body is required (Buffer | string)");
+  }
+  var bodyBuf;
+  if (Buffer.isBuffer(body)) bodyBuf = body;
+  else if (typeof body === "string") bodyBuf = Buffer.from(body, "utf8");
+  else {
+    throw new SmtpPolicyError("smtp/tls-rpt-bad-input",
+      "tlsRpt.parseReport: body must be a Buffer or string");
+  }
+  if (bodyBuf.length > TLS_RPT_MAX_REPORT_BYTES) {
+    throw new SmtpPolicyError("smtp/tls-rpt-too-large",
+      "tlsRpt.parseReport: report exceeds " + TLS_RPT_MAX_REPORT_BYTES + " bytes");
+  }
+
+  // Decompress if the operator passes contentType: "application/tlsrpt+gzip"
+  // OR if the body sniffs as gzip (magic 0x1f 0x8b).
+  var contentType = (opts.contentType || "").toLowerCase();
+  var looksGzip = bodyBuf.length >= 2 && bodyBuf[0] === 0x1f && bodyBuf[1] === 0x8b;
+  if (contentType.indexOf("gzip") !== -1 || looksGzip) {
+    try { bodyBuf = zlib.gunzipSync(bodyBuf, { maxOutputLength: TLS_RPT_MAX_REPORT_BYTES }); }
+    catch (e) {
+      throw new SmtpPolicyError("smtp/tls-rpt-gunzip-failed",
+        "tlsRpt.parseReport: gunzip failed: " + ((e && e.message) || String(e)));
+    }
+  }
+
+  var report;
+  try { report = safeJson.parse(bodyBuf.toString("utf8"), { maxBytes: TLS_RPT_MAX_REPORT_BYTES }); }
+  catch (e) {
+    throw new SmtpPolicyError("smtp/tls-rpt-bad-json",
+      "tlsRpt.parseReport: JSON parse failed: " + ((e && e.message) || String(e)));
+  }
+  if (!report || typeof report !== "object") {
+    throw new SmtpPolicyError("smtp/tls-rpt-bad-shape",
+      "tlsRpt.parseReport: report must be an object");
+  }
+
+  // Validate the RFC 8460 §4.4 required fields. Optional fields are
+  // surfaced as-is when present (some operators ship `contact-info`,
+  // some don't).
+  var requiredKeys = ["organization-name", "date-range", "report-id", "policies"];
+  for (var ri = 0; ri < requiredKeys.length; ri += 1) {
+    if (!Object.prototype.hasOwnProperty.call(report, requiredKeys[ri])) {
+      throw new SmtpPolicyError("smtp/tls-rpt-missing-field",
+        "tlsRpt.parseReport: report missing required field '" + requiredKeys[ri] + "' (RFC 8460 §4.4)");
+    }
+  }
+  if (!report["date-range"] ||
+      typeof report["date-range"]["start-datetime"] !== "string" ||
+      typeof report["date-range"]["end-datetime"] !== "string") {
+    throw new SmtpPolicyError("smtp/tls-rpt-bad-date-range",
+      "tlsRpt.parseReport: date-range must have start-datetime + end-datetime");
+  }
+  if (!Array.isArray(report.policies)) {
+    throw new SmtpPolicyError("smtp/tls-rpt-bad-policies",
+      "tlsRpt.parseReport: policies must be an array");
+  }
+  if (report.policies.length > TLS_RPT_MAX_POLICIES_PER_REPORT) {
+    throw new SmtpPolicyError("smtp/tls-rpt-too-many-policies",
+      "tlsRpt.parseReport: report has " + report.policies.length +
+      " policies (cap " + TLS_RPT_MAX_POLICIES_PER_REPORT + ")");
+  }
+
+  // Aggregate counters operators most commonly want surfaced.
+  var totalSuccess = 0;
+  var totalFailure = 0;
+  for (var pi = 0; pi < report.policies.length; pi += 1) {
+    var entry = report.policies[pi];
+    if (entry && entry.summary) {
+      var s = entry.summary["total-successful-session-count"];
+      var f = entry.summary["total-failure-session-count"];
+      if (typeof s === "number" && isFinite(s)) totalSuccess += s;
+      if (typeof f === "number" && isFinite(f)) totalFailure += f;
+    }
+  }
+
+  return {
+    organization:    report["organization-name"],
+    contact:         report["contact-info"] || null,
+    reportId:        report["report-id"],
+    dateRange: {
+      start: report["date-range"]["start-datetime"],
+      end:   report["date-range"]["end-datetime"],
+    },
+    policies:        report.policies,
+    totals: {
+      successful:    totalSuccess,
+      failure:       totalFailure,
+    },
+    raw:             report,
+  };
+}
+
 module.exports = {
   mtaSts: Object.freeze({
     fetch:   mtaStsFetch,
@@ -550,6 +660,7 @@ module.exports = {
     recordShape: tlsRptRecordShape,
     fetchPolicy: tlsRptFetchPolicy,
     submit:      tlsRptSubmit,
+    parseReport: tlsRptParseReport,
   }),
   SmtpPolicyError: SmtpPolicyError,
 };

package/package.json

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

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:55a0114a-f249-481f-b122-6997247485a1",
+  "serialNumber": "urn:uuid:a82c1893-13c0-448e-a951-71bc3d182da3",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T03:31:31.641Z",
+    "timestamp": "2026-05-06T03:56:40.534Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.73",
+      "bom-ref": "@blamejs/core@0.7.74",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.73",
+      "version": "0.7.74",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.73",
+      "purl": "pkg:npm/%40blamejs/core@0.7.74",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.73",
+      "ref": "@blamejs/core@0.7.74",
       "dependsOn": []
     }
   ]