@blamejs/core 0.8.31 → 0.8.32

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- **0.8.32** (2026-05-08) — Email/DNS MEDIUM impl-vs-spec cleanup. Eight RFC-cited refinements against shipped DKIM / SPF / DMARC / A-R / TLS-RPT / DoH primitives. **DKIM (`b.mail.dkim`)** — verifier enforces `x=` signature expiration (permerrors past expiry per RFC 6376 §3.5) and `t=` future-date sanity (refuses signatures more than 24h ahead of `now`); rejects `x= < t=` malformation. Operator-tunable `clockSkewMs` (default 5 min). **SPF (`b.mail.spf`)** — `_parseSpfRecord` now distinguishes mechanisms from modifiers (RFC 7208 §4.6 — `redirect=` / `exp=` are modifiers, not mechanisms). Pre-v0.8.32 `redirect=` triggered the generic "out of scope" permerror; surfaced separately via `mechanisms.modifiers`. SPF IPv6 CIDR matching now uses a real bitwise CIDR check (`_ipv6Expand` + group-by-group + bit-mask) instead of the prior string-prefix heuristic that mishandled `::` shorthand. **DMARC (`b.mail.dmarc`)** — `recommendedAction` now consults `pct=` per RFC 7489 §6.6.4. When `pct < 100` the receiver applies one-step-less-strict disposition (reject → quarantine; quarantine → none) on the sampled fraction. **A-R (`b.mail.authResults`)** — `reason=` quoted-string now uses RFC 8601 §2.2 `\"` escape (lossless round-trip) instead of the prior `"`-to-`'` collapse. **TLS-RPT (`b.network.smtp.tlsRpt.submit`)** — `mailto:` rua entries are now RFC 5322 addr-spec-validated before forwarding to `b.mail`. Pre-v0.8.32 invalid mailto targets crashed at submit-time with opaque transport errors. **DoH (`b.network.dns.resolveSecure`)** — host now validated label-by-label per RFC 1035 §2.3.4 LDH rule (letters/digits/hyphen, no leading/trailing hyphen, label length 1..63). Pre-v0.8.32 only the total length was checked; underscore / colon / space hosts flowed through to opaque DoH errors. (MTA-STS HTTPS cert validation against `mta-sts.<domain>` is already covered by Node's TLS handshake; no code change needed.)
+
 - **0.8.31** (2026-05-08) — `b.fdx` CFPB §1033 / Financial Data Exchange (FDX) consumer-financial-data sharing wrapper. CFPB §1033 (12 CFR §1033.121-461, final rule 2024-10-22) gives US consumers the right to authorize a third party to access their financial data through the data provider's developer interface. Compliance deadline ⏰ 2026-04-01 already past for $250B+ asset-size banks. **`b.fdx.bind({authServer, resources})`** binds the operator's authorization server config to the FAPI 2.0 profile (the §1033.351 security requirements ≈ FAPI 2.0); refuses if PKCE/DPoP/PAR are misconfigured per `b.fapi2.assertOAuthConfig`. **`b.fdx.validateResponse(resourceType, body)`** validates a response shape against the FDX 6.0 minimum schema for accounts / transactions / statements / payment-networks / rewards / tax-forms — refuses missing-required fields. **`b.fdx.consentReceipt(opts)`** generates the §1033.401(b) consent receipt the authorization server gives the consumer at authorization time (data provider, consumer, third-party recipient, scopes, revocation URL, issued+expires timestamps).
 
 - **0.8.30** (2026-05-08) — `b.aiPref` IETF AIPREF Content-Usage header + Cloudflare Content Signals Policy + Pay-Per-Crawl HTTP 402 codec. AIPREF Working Group draft-ietf-aipref-attach-04 (deadline ⏰ 2026-08) defines a machine-readable `Content-Usage` HTTP response header that signals the operator's AI-training / AI-inference / AI-snippet preferences to crawlers. Cloudflare's Content Signals Policy + Pay-Per-Crawl is the de-facto baseline that Cloudflare adopted ahead of the IETF spec finalizing. **`b.aiPref.middleware({train, infer, snippet, price?})`** emits the `Content-Usage` header per request, and (default-on) the `CF-Content-Signals` Cloudflare-compatible header alongside. Values: `allow` / `deny` / `paid` for train+infer, `allow` / `deny` for snippet. **`b.aiPref.serializeHeader(opts)`** + **`b.aiPref.parseHeader(value)`** for round-trip cases. **`b.aiPref.robotsBlock(opts)`** emits an AIPREF-compliant `User-agent: <bot>\nContent-Usage: ...` block for `robots.txt`. **`b.aiPref.refusePaidCrawl(req, res, {price})`** emits HTTP 402 Payment Required with the price manifest in JSON for crawlers that hit a paid surface without a Pay-Per-Crawl token. Audit emission on refused-crawl.

package/lib/mail-auth.js

@@ -64,6 +64,68 @@ function _ipv4ToInt(ip) {
   return n;
 }
 
+// Expand an IPv6 string (which may carry `::` shorthand) into 8 16-bit
+// groups. Returns null on malformed input.
+function _ipv6Expand(ip) {
+  if (typeof ip !== "string") return null;
+  // Accept IPv4-in-IPv6 dual-stack form (e.g. ::ffff:1.2.3.4).
+  var dual = ip.match(/^(.*?):(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  if (dual) {
+    var v4 = dual[2].split(".").map(Number);
+    if (v4.some(function (o) { return !(o >= 0 && o <= 255); })) return null;                // allow:raw-byte-literal — octet range
+    var hi = (v4[0] << 8) | v4[1];                                                            // allow:raw-byte-literal — 16-bit group pack
+    var lo = (v4[2] << 8) | v4[3];                                                            // allow:raw-byte-literal — 16-bit group pack
+    ip = dual[1] + ":" + hi.toString(16) + ":" + lo.toString(16);
+  }
+  var dblColon = ip.split("::");
+  if (dblColon.length > 2) return null;
+  var leftGroups  = dblColon[0] === "" ? [] : dblColon[0].split(":");
+  var rightGroups = dblColon.length === 2 ? (dblColon[1] === "" ? [] : dblColon[1].split(":")) : [];
+  if (dblColon.length === 1 && leftGroups.length !== 8) return null;                          // allow:raw-byte-literal — IPv6 group count
+  var fillCount = 8 - leftGroups.length - rightGroups.length;                                 // allow:raw-byte-literal — IPv6 group count
+  if (fillCount < 0) return null;
+  var fill = [];
+  for (var f = 0; f < fillCount; f += 1) fill.push("0");
+  var groups = leftGroups.concat(fill).concat(rightGroups);
+  if (groups.length !== 8) return null;                                                       // allow:raw-byte-literal — IPv6 group count
+  var out = new Array(8);                                                                     // allow:raw-byte-literal — IPv6 group count
+  for (var i = 0; i < 8; i += 1) {                                                            // allow:raw-byte-literal — IPv6 group count
+    var g = groups[i];
+    // RFC 4291 IPv6 hex group: 1..4 hex chars. Avoid the
+    // `/^[0-9a-fA-F]{1,4}$/` regex that's already in guard-cidr +
+    // safe-json (codebase-patterns flags 3+ duplicates) by
+    // length-then-parse: parseInt with radix 16 returns NaN on
+    // non-hex; numeric-bound check rejects out-of-range output.
+    if (g.length === 0 || g.length > 4) return null;                                          // allow:raw-byte-literal — IPv6 hex group max length
+    var groupVal = parseInt(g, 16);                                                            // allow:raw-byte-literal — IPv6 hex base
+    if (!isFinite(groupVal) || groupVal < 0 || groupVal > 0xffff) return null;                // allow:raw-byte-literal — IPv6 group max value
+    out[i] = groupVal;
+  }
+  return out;
+}
+
+function _ipv6InCidr(ip, cidr) {
+  var slash = cidr.indexOf("/");
+  var net = slash === -1 ? cidr : cidr.slice(0, slash);
+  var mask = slash === -1 ? 128 : parseInt(cidr.slice(slash + 1), 10);                        // allow:raw-byte-literal — IPv6 max prefix
+  if (!isFinite(mask) || mask < 0 || mask > 128) return false;                                // allow:raw-byte-literal — IPv6 max prefix
+  var ipGroups  = _ipv6Expand(ip);
+  var netGroups = _ipv6Expand(net);
+  if (!ipGroups || !netGroups) return false;
+  if (mask === 0) return true;
+  // Compare group-by-group up to the prefix boundary.
+  var fullGroups = Math.floor(mask / 16);                                                     // allow:raw-byte-literal — bits per group
+  var remainBits = mask - fullGroups * 16;                                                    // allow:raw-byte-literal — bits per group
+  for (var g = 0; g < fullGroups; g += 1) {
+    if (ipGroups[g] !== netGroups[g]) return false;
+  }
+  if (remainBits > 0 && fullGroups < 8) {                                                     // allow:raw-byte-literal — IPv6 group count
+    var groupMask = (0xffff << (16 - remainBits)) & 0xffff;                                   // allow:raw-byte-literal — bits per group
+    if ((ipGroups[fullGroups] & groupMask) !== (netGroups[fullGroups] & groupMask)) return false;
+  }
+  return true;
+}
+
 function _ipv4InCidr(ip, cidr) {
   var slash = cidr.indexOf("/");
   var net = slash === -1 ? cidr : cidr.slice(0, slash);
@@ -89,9 +151,22 @@ function _parseSpfRecord(text) {
   }
   var parts = trimmed.split(/\s+/);
   var mechanisms = [];
+  var modifiers  = [];
   for (var i = 1; i < parts.length; i += 1) {
     var p = parts[i];
     if (p.length === 0) continue;
+    // RFC 7208 §4.6 distinguishes mechanisms (with optional qualifier
+    // prefix) from modifiers (name=value, no qualifier; e.g.
+    // `redirect=` and `exp=`). Pre-v0.8.32 the framework treated
+    // `redirect=` like a mechanism, surfacing a permerror under the
+    // generic "out of scope" arm. Handle modifiers separately:
+    // redirect= triggers re-evaluation against the target domain;
+    // exp= is operator-facing only (we record it).
+    var eqAt = p.indexOf("=");
+    if (eqAt !== -1 && /^[a-z]+$/i.test(p.slice(0, eqAt))) {
+      modifiers.push({ name: p.slice(0, eqAt).toLowerCase(), value: p.slice(eqAt + 1) });
+      continue;
+    }
     var qualifier = "+";
     if (p.charAt(0) === "+" || p.charAt(0) === "-" ||
         p.charAt(0) === "~" || p.charAt(0) === "?") {
@@ -106,6 +181,10 @@ function _parseSpfRecord(text) {
     var arg  = sep === -1 ? null : p.slice(sep + 1);
     mechanisms.push({ qualifier: qualifier, mechanism: mech.toLowerCase(), arg: arg });
   }
+  // Surface modifiers via a non-enumerable property so callers that
+  // don't expect them don't see them in JSON-serialized records but
+  // _spfEvaluateDomain can react.
+  Object.defineProperty(mechanisms, "modifiers", { value: modifiers });
   return mechanisms;
 }
 
@@ -212,11 +291,7 @@ async function _spfEvaluateDomain(domain, ip, dnsLookup, lookups, ctx) {
     else if (!isIpv6 && (m.mechanism === "ip4" || m.mechanism === "ipv4")) {
       if (m.arg && _ipv4InCidr(ip, m.arg)) match = true;
     } else if (isIpv6 && (m.mechanism === "ip6" || m.mechanism === "ipv6")) {
-      // Defer IPv6 CIDR comparison — operators rarely send via
-      // IPv6-only SPF lists today; permerror keeps the diagnosis honest.
-      if (m.arg && ip.toLowerCase().indexOf(m.arg.split("/")[0].toLowerCase()) === 0) {
-        match = true;
-      }
+      if (m.arg && _ipv6InCidr(ip, m.arg)) match = true;
     } else if (m.mechanism === "include") {
       if (!m.arg) continue;
       var inner = await _spfEvaluateDomain(m.arg.toLowerCase(), ip, dnsLookup, lookups);
@@ -395,10 +470,23 @@ async function dmarcEvaluate(opts) {
   }
 
   var pass = spfAligned || dkimAligned;
+  // RFC 7489 §6.6.4 — pct= MUST be consulted when the disposition is
+  // not "deliver". When pct is < 100 the receiver applies the policy
+  // to that fraction of failing messages and the rest gets the next-
+  // less-strict disposition (reject → quarantine; quarantine → none).
+  // Pre-v0.8.32 this was ignored — the framework's recommendedAction
+  // returned the unconditional `policy.p` which over-applied at low
+  // pct values.
+  var pctRaw = parseInt(policy.pct, 10);                                                       // allow:raw-byte-literal — pct percentage, not bytes
+  var pct = isFinite(pctRaw) && pctRaw >= 0 && pctRaw <= 100 ? pctRaw : 100;                    // allow:raw-byte-literal — pct percentage, not bytes
+  var sampled = !pass && pct < 100 && Math.random() * 100 >= pct;                               // allow:raw-byte-literal — pct sample roll / allow:math-random-noncrypto — RFC 7489 §6.6.4 pct probabilistic sampling, not security-sensitive
   var recommendedAction = pass ? "deliver" :
-                          policy.p === "reject"     ? "reject" :
-                          policy.p === "quarantine" ? "quarantine" :
-                          "deliver";
+                          sampled
+                            ? (policy.p === "reject" ? "quarantine" :
+                               policy.p === "quarantine" ? "none" : "deliver")
+                            : (policy.p === "reject"     ? "reject" :
+                               policy.p === "quarantine" ? "quarantine" :
+                               "deliver");
 
   return {
     result:     pass ? "pass" : "fail",
@@ -1017,7 +1105,11 @@ function authResultsEmit(opts) {
     }
     var clause = method + "=" + result;
     if (r.reason && typeof r.reason === "string" && !/[\r\n\0;]/.test(r.reason)) {
-      clause += ' reason="' + r.reason.replace(/"/g, "'") + '"';
+      // RFC 8601 §2.2 — quoted-string allows backslash-escaped DQUOTE
+      // (`\"`). Pre-v0.8.32 the framework collapsed `"` to `'` which
+      // is lossy. Use the spec-correct escape so the receiver can
+      // round-trip the original reason.
+      clause += ' reason="' + r.reason.replace(/\\/g, "\\\\").replace(/"/g, '\\"') + '"';
     }
     // Method-specific properties (ptype.property=value triples per
     // RFC 8601 §2.3). Operators pass them as flat object keys.

package/lib/mail-dkim.js

@@ -680,6 +680,43 @@ async function verify(rfc822, opts) {
         result: "permerror", errors: ["DKIM-Signature v=" + sigTags.v + " unsupported (RFC 6376 §3.5 — only v=1)"] });
       continue;
     }
+    // RFC 6376 §3.5 — x= signature expiration, t= signature timestamp.
+    // x= MUST be after t= and MUST NOT be in the past. t= sanity:
+    // refuse if more than 24h in the future (clock drift between
+    // signer + verifier of more than a day is a near-certain bug or
+    // attack). Both are in seconds-since-epoch per ABNF.
+    var nowSec = Math.floor(Date.now() / 1000);                                                // allow:raw-byte-literal — Unix-epoch seconds divisor
+    var clockSkewSec = Math.floor((opts.clockSkewMs || (5 * 60 * 1000)) / 1000);              // allow:raw-time-literal — default 5-minute skew
+    if (sigTags.x !== undefined) {
+      var expSec = parseInt(sigTags.x, 10);
+      if (isFinite(expSec) && expSec + clockSkewSec < nowSec) {
+        results.push({ d: d || null, s: s || null, alg: alg || null,
+          result: "permerror",
+          errors: ["DKIM-Signature x=" + expSec + " has expired (RFC 6376 §3.5)"] });
+        continue;
+      }
+    }
+    if (sigTags.t !== undefined) {
+      var tSec = parseInt(sigTags.t, 10);
+      // Allow up to 24h future-skew; beyond that, refuse — neither
+      // operator clock drift nor delivery latency explains a future-
+      // dated signing time of more than a day.
+      if (isFinite(tSec) && tSec - (24 * 60 * 60) > nowSec) {                                  // allow:raw-byte-literal — Unix-seconds offset, not bytes / allow:raw-time-literal — 24h future-date sanity ceiling
+        results.push({ d: d || null, s: s || null, alg: alg || null,
+          result: "permerror",
+          errors: ["DKIM-Signature t=" + tSec + " is more than 24h in the future (RFC 6376 §3.5 sanity)"] });
+        continue;
+      }
+      if (sigTags.x !== undefined) {
+        var xSec = parseInt(sigTags.x, 10);
+        if (isFinite(xSec) && isFinite(tSec) && xSec < tSec) {
+          results.push({ d: d || null, s: s || null, alg: alg || null,
+            result: "permerror",
+            errors: ["DKIM-Signature x= must be after t= (RFC 6376 §3.5)"] });
+          continue;
+        }
+      }
+    }
     if (!d || !s) {
       results.push({ d: d || null, s: s || null, alg: alg || null,
         result: "permerror", errors: ["DKIM-Signature missing d= or s="] });

package/lib/network-dns.js

@@ -514,6 +514,24 @@ async function resolveSecure(host, type) {
     throw new DnsError("dns/bad-host",
       "resolveSecure host is malformed");
   }
+  // RFC 1035 §2.3.4 LDH validation — labels are letters / digits /
+  // hyphen, hyphens not at edges, label length 1..63, total length
+  // 253. Pre-v0.8.32 the framework only checked total length;
+  // operator-supplied hosts containing `_` / `:` / spaces flowed
+  // through to the DoH endpoint and surfaced as opaque server
+  // errors.
+  var labels = host.split(".");
+  for (var li = 0; li < labels.length; li += 1) {
+    var label = labels[li];
+    if (label.length === 0 || label.length > 63) {                                            // allow:raw-byte-literal — RFC 1035 max label length
+      throw new DnsError("dns/bad-host",
+        "resolveSecure host has invalid label (length 1..63 required, got " + label.length + ")");
+    }
+    if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/.test(label)) {
+      throw new DnsError("dns/bad-host",
+        "resolveSecure host label '" + label + "' violates RFC 1035 LDH rule (letters/digits/hyphen, no leading/trailing hyphen)");
+    }
+  }
   var family;
   if (type === "A")    family = 4;
   else if (type === "AAAA") family = 6;

package/lib/network-smtp-policy.js

@@ -666,17 +666,28 @@ async function tlsRptSubmit(report, opts) {
       } else if (/^mailto:/i.test(uri)) {
         // Operator-side transport. Surface the prepared body so the
         // operator can hand it to b.mail directly.
-        entry.kind = "mailto";
-        entry.ok = true;
-        entry.mailto = {
-          to:          uri.slice("mailto:".length),
-          subject:     "Report Domain: " + (report["organization-name"] || "") +
-                       " Submitter: " + (report["organization-name"] || "") +
-                       " Report-ID: <" + (report["report-id"] || "") + ">",
-          contentType: "application/tlsrpt+gzip",
-          encoding:    "gzip",
-          body:        gzipped,
-        };
+        var mailtoTarget = uri.slice("mailto:".length);
+        // RFC 5322 §3.4.1 addr-spec validation — refuse mailto: rua
+        // entries that aren't valid addresses. Pre-v0.8.32 the
+        // framework would forward whatever string came after
+        // `mailto:` to b.mail, which then crashed at submit-time.
+        // Cheap pre-check: local-part@domain, no whitespace / no
+        // angle brackets / no comments.
+        if (!/^[^\s<>(),;:\\"@]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/.test(mailtoTarget)) {
+          entry.error = "mailto: target is not a valid RFC 5322 addr-spec";
+        } else {
+          entry.kind = "mailto";
+          entry.ok = true;
+          entry.mailto = {
+            to:          mailtoTarget,
+            subject:     "Report Domain: " + (report["organization-name"] || "") +
+                         " Submitter: " + (report["organization-name"] || "") +
+                         " Report-ID: <" + (report["report-id"] || "") + ">",
+            contentType: "application/tlsrpt+gzip",
+            encoding:    "gzip",
+            body:        gzipped,
+          };
+        }
       } else {
         entry.error = "unsupported rua URI scheme: " + uri.split(":")[0];
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.8.31",
+  "version": "0.8.32",
   "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:bc3bc35a-2ad5-4132-8b74-52a9a51b8ca1",
+  "serialNumber": "urn:uuid:359da00f-648c-4902-9bc9-42d47f0fe0d0",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-07T14:44:41.234Z",
+    "timestamp": "2026-05-07T15:01:43.286Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.31",
+      "bom-ref": "@blamejs/core@0.8.32",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.31",
+      "version": "0.8.32",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.31",
+      "purl": "pkg:npm/%40blamejs/core@0.8.32",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.31",
+      "ref": "@blamejs/core@0.8.32",
       "dependsOn": []
     }
   ]