@blamejs/core 0.16.35 → 0.16.36

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.16.x
 
+- v0.16.36 (2026-07-16) — **DKIM simple header canonicalization now signs and verifies the DKIM-Signature header verbatim, so simple-canon signatures round-trip and interoperate.** b.mail.dkim's simple header canonicalization (c=simple/... in a signature) signs and verifies each header exactly as it appears on the wire, per RFC 6376 §3.4.1. Two defects broke that for the DKIM-Signature header itself: the signer canonicalized the header UNFOLDED while emitting it FOLDED on the wire, and the verifier prefixed a spurious extra space to the parsed header value. Together they meant a simple-header-canonicalization signature never matched the bytes that were signed -- neither the framework's own signatures nor an RFC-compliant peer's would verify under simple canon. The signer now canonicalizes and emits the same folded header (appending the signature to the folded, b-emptied form), and the verifier canonicalizes the parsed header verbatim, so a simple-canon signature round-trips and is byte-compatible with other implementations. Relaxed canonicalization, the common default, is unchanged. Separately, a supply-chain gate now fails the build if a vendored component in lib/vendor/MANIFEST.json has no attribution entry in NOTICE. **Added:** *b.safeBuffer.byteLengthOfIfMeasurable — measure a value's byte length, or null when it is not a byte carrier* — byteLengthOfIfMeasurable(value) returns the byte length of a string, Buffer, or Uint8Array, and null for anything else (a plain Array, an array-like object, a number, null). It is the safe way to cap the size of an untrusted metadata bag whose byte field may be any shape: measure the cap only when the value is measurable, rather than gating byteLengthOf (which throws on a non-byte-carrier) on a hand-rolled length check that admits array-likes and crashes. The image and PDF content guards now compose it for their byte caps instead of each vetting the type inline. **Fixed:** *DKIM simple header canonicalization signs and verifies the DKIM-Signature header verbatim* — Under simple header canonicalization (RFC 6376 §3.4.1) the DKIM-Signature header is signed and verified byte-for-byte as it appears on the wire, including its folding. b.mail.dkim canonicalized the header UNFOLDED when computing the signature but emitted it FOLDED on the wire, and the verifier prepended an extra space to the parsed header value before canonicalizing -- so the bytes signed never matched the bytes verified. A simple-header-canonicalization signature therefore never verified, whether produced by the framework or by an RFC-compliant peer. The signer now canonicalizes the folded, b-emptied header and builds the wire header by appending the signature to it, and the verifier canonicalizes the parsed (folded) header verbatim -- including the DKIM-Signature field name exactly as it appears on the wire, so a peer that signs a lowercase dkim-signature: field name also verifies -- so a simple-canon signature round-trips and interoperates. This was fail-closed -- a broken simple-canon signature was reported as a verification failure, never a false pass -- and relaxed canonicalization (the common default, which normalizes folding and whitespace on both sides) was and remains correct. **Detectors:** *Every vendored component in the manifest must be attributed in NOTICE* — A gate fails the build when a component recorded in lib/vendor/MANIFEST.json has no attribution entry in the NOTICE file. Third-party components ship with their license and attribution obligations; this catches a vendored library or data file added to the manifest without its NOTICE entry before the package is published, rather than after a downstream scanner flags the omission.
+
 - v0.16.35 (2026-07-16) — **A resumed saga that later fails now compensates the steps it completed before the crash, and a webhook delivery retries a transient DNS failure during its safety re-check instead of dead-lettering.** Two durability fixes in the agent orchestration and webhook delivery primitives. b.agent.saga rebuilt its completed-step list from empty when a saga resumed from a persisted checkpoint, so a failure after the resume compensated only the steps that ran in that resumed pass -- the steps completed before the crash were never rolled back, defeating the saga's whole purpose (a charge committed before the crash would never be refunded when a later step failed). Resume now seeds the completed-step list with the steps that finished before the crash, so a failure compensates the full set in reverse order. Separately, b.webhook.dispatcher re-checks a delivery's destination for an SSRF rebind just before each attempt; that check resolves the destination host, and a transient resolver failure (a temporary DNS error) during it was treated as a permanent failure and dead-lettered the delivery on the first attempt. The re-check now dead-letters only a genuine SSRF refusal or malformed URL and treats a transient resolver fault as retryable, like every other transport error. **Added:** *b.webhook.dispatcher accepts a dnsLookup override for the destination SSRF check* — b.webhook.dispatcher now accepts an optional dnsLookup(host) resolver, forwarded to the SSRF destination check, so an operator can point destination resolution at a specific resolver (and a test can drive the transient-versus-permanent classification offline). It defaults to the framework's DNS-over-TLS resolver, unchanged. **Fixed:** *A resumed saga compensates the steps it completed before the crash, not only those in the resumed run* — b.agent.saga runs a sequence of steps and, on a step failure, compensates the completed steps in reverse order. When a saga resumed from a persisted checkpoint, it started its completed-step list empty, so a failure after the resume compensated only the steps that ran in the resumed pass -- the steps completed before the crash were left uncompensated. For a distributed transaction that is the exact failure the pattern exists to prevent: work committed before the crash (a charge, a reservation, an external call) would never be rolled back when a later step failed. Resume now seeds the completed-step list with the steps that finished before the crash, reconstructed from the saga definition, so a subsequent failure compensates the full completed set in reverse; compensation runs against the resumed state, which already reflects those steps' effects, and the failing step itself is not compensated. To keep that reseeding safe against replay, resume also refuses a saga the state store marks terminal (failed-and-compensated or completed) rather than re-running its compensators, and the state-store interface documents that compensators must be idempotent -- a crash mid-compensation can replay a compensation on the next resume, so compensating twice must be safe. · *Webhook delivery retries a transient DNS failure during its SSRF re-check instead of dead-lettering* — b.webhook.dispatcher re-validates a delivery's destination against SSRF (private / loopback / metadata IPs, or a rebind since registration) just before each attempt, which resolves the destination host. A transient resolver failure during that resolution -- a lookup timeout or system/resolve failure -- was caught and marked a permanent failure, dead-lettering the delivery on its first attempt rather than retrying. The re-check now classifies the failure: a genuine SSRF refusal or malformed URL dead-letters, a resolver failure honors the framework DNS resolver's own terminal-versus-transient verdict (a permanent failure such as a host with no addresses or a removed record dead-letters immediately, a transient one is retried on the backoff curve, capped at maxAttempts), matching how the dispatcher already treats a transient DNS error during the delivery POST itself. So a webhook is no longer lost to a momentary DNS blip, a genuine rebind to an internal address is still dead-lettered immediately, and a permanently unresolvable destination dead-letters without burning every retry attempt.
 
 - v0.16.34 (2026-07-16) — **The DPoP middleware returns the correct multiple-proof rejection when a request carries a repeated DPoP header, instead of mislabeling it as a missing proof.** RFC 9449 §4.1 permits only one DPoP header value per request. b.middleware.dpop rejected a request that carried the header as an array -- repeated DPoP: lines a custom server or proxy did not collapse -- but its array-shape check sat after the missing-header guard, and an array is not a string, so the missing-header guard always ran first. A duplicated DPoP proof was therefore rejected as a missing proof (and, when a DPoP nonce was required, answered with use_dpop_nonce, prompting the client into a pointless nonce-retry loop) rather than with the invalid_dpop_proof / multiple-DPoP-headers rejection the specification calls for. Both paths already refused the request, so this was never a fail-open -- only an incorrect diagnostic and a wasted round trip. The array-shape check now runs before the missing-header guard, so a repeated DPoP header is rejected with the correct error. **Fixed:** *DPoP middleware rejects a repeated DPoP header with the correct multiple-proof error* — b.middleware.dpop enforces the RFC 9449 §4.1 single-value rule, but its Array.isArray check for a repeated header (when a server or proxy delivered the DPoP header as an array rather than a comma-joined string) sat after the non-string / empty guard. Because an array fails the non-string check first, the dedicated multiple-DPoP-headers branch never ran: a duplicated proof was reported as a missing DPoP header, and under a required-nonce policy it returned use_dpop_nonce, driving the client into a fruitless nonce-retry loop. The array-shape check now runs first, so a repeated DPoP header is rejected with invalid_dpop_proof and a multiple-DPoP-headers message. This changes only the error code and message for that malformed-request case; both orderings already refused the request, so no valid request is affected.

package/lib/guard-image.js

@@ -194,15 +194,15 @@ function _detectIssues(metadata, opts) {
               snippet: "image metadata is not an object" }];
   }
 
-  // Measure the byte cap only for the types safeBuffer.byteLengthOf accepts
-  // (string / Buffer / Uint8Array). A hostile bag whose `bytes` is a plain
-  // Array or an array-like object still carries a numeric `.length` but is NOT
-  // measurable — measuring it threw TypeError, breaking validate's documented
-  // never-throw contract. Skip the cap for those (magic detection below is
-  // O(1)-bounded regardless of size) instead of crashing the caller.
+  // Measure the byte cap only for measurable values. A hostile bag whose
+  // `bytes` is a plain Array or array-like object carries a numeric `.length`
+  // but is NOT a byte-carrier — measuring it would throw, breaking validate's
+  // documented never-throw contract; byteLengthOfIfMeasurable returns null for
+  // those, so the cap is skipped (magic detection below is O(1)-bounded
+  // regardless of size) instead of crashing the caller.
   var bytes = metadata.bytes;
-  if (bytes && (Buffer.isBuffer(bytes) || typeof bytes === "string" || bytes instanceof Uint8Array) &&
-      safeBuffer.byteLengthOf(bytes) > opts.maxBytes) {
+  var byteCount = safeBuffer.byteLengthOfIfMeasurable(bytes);
+  if (byteCount !== null && byteCount > opts.maxBytes) {
     return [{ kind: "image-cap", severity: "high",
               ruleId: "image.image-cap",
               snippet: "image bytes exceed maxBytes " + opts.maxBytes }];

package/lib/guard-pdf.js

@@ -156,16 +156,16 @@ function _detectIssues(metadata, opts) {
               snippet: "pdf metadata is not an object" }];
   }
 
-  // Measure the byte cap only for the types safeBuffer.byteLengthOf accepts
-  // (string / Buffer / Uint8Array). A hostile bag whose `bytes` is a plain
-  // Array or an array-like object still carries a numeric `.length` but is NOT
-  // measurable — measuring it threw TypeError, breaking validate's documented
-  // never-throw-on-hostile-metadata contract. Skip the cap for those (magic
-  // detection reads only the leading bytes, O(1)-bounded regardless of the
-  // reported size) instead of crashing the caller.
+  // Measure the byte cap only for measurable values. A hostile bag whose
+  // `bytes` is a plain Array or array-like object carries a numeric `.length`
+  // but is NOT a byte-carrier — measuring it would throw, breaking validate's
+  // documented never-throw-on-hostile-metadata contract; byteLengthOfIfMeasurable
+  // returns null for those, so the cap is skipped (magic detection reads only
+  // the leading bytes, O(1)-bounded regardless of the reported size) instead of
+  // crashing the caller.
   var bytes = metadata.bytes;
-  if (bytes && (Buffer.isBuffer(bytes) || typeof bytes === "string" || bytes instanceof Uint8Array) &&
-      safeBuffer.byteLengthOf(bytes) > opts.maxBytes) {
+  var byteCount = safeBuffer.byteLengthOfIfMeasurable(bytes);
+  if (byteCount !== null && byteCount > opts.maxBytes) {
     return [{ kind: "pdf-cap", severity: "high",
               ruleId: "pdf.pdf-cap",
               snippet: "pdf bytes exceed maxBytes " + opts.maxBytes }];

package/lib/mail-dkim.js

@@ -413,18 +413,42 @@ function create(opts) {
         });
       } catch (_e) { /* drop-silent */ }
     }
-    // Append the unsigned DKIM-Signature header without trailing CRLF
-    // per RFC 6376 §3.7.
-    var dkimHeaderForSigning = canonHeader === "simple"
-      ? _canonHeaderSimple("DKIM-Signature", " " + unsignedSigValue)
-      : _canonHeaderRelaxed("DKIM-Signature", unsignedSigValue);
+    // Append the unsigned DKIM-Signature header (b= value emptied) without a
+    // trailing CRLF per RFC 6376 §3.7. Under SIMPLE header canonicalization the
+    // header is signed and verified BYTE-FOR-BYTE as it appears on the wire —
+    // including its folding — so the signer must canonicalize the FOLDED form,
+    // exactly as the verifier does when it strips b= from the parsed (folded)
+    // wire header. (Relaxed unfolds on both sides, so it signs the unfolded
+    // value.) The empty-b header folds identically to the final header up to the
+    // last `b=` line (folding breaks only at "; " tag boundaries and b= is the
+    // last tag), so we can build the wire header by appending the signature to
+    // this folded empty-b header, and the verifier recovers exactly these bytes.
+    var foldedEmptyB = _foldSignatureHeader(unsignedSigValue);
+    var dkimHeaderForSigning;
+    if (canonHeader === "simple") {
+      // Simple canon is verbatim (RFC 6376 §3.4.1): the canonical form of the
+      // DKIM-Signature header (b= emptied) is the folded wire header exactly as
+      // it will appear — which is precisely foldedEmptyB ("DKIM-Signature: " +
+      // the folded, b-emptied value). No re-spacing or re-canonicalization.
+      dkimHeaderForSigning = foldedEmptyB;
+    } else {
+      dkimHeaderForSigning = _canonHeaderRelaxed("DKIM-Signature", unsignedSigValue);
+    }
     canonicalizedHeaders += dkimHeaderForSigning.replace(/\r\n$/, "");
 
     var signature = _signString(canonicalizedHeaders, keyObject, algorithm);
-    // Replace the empty `b=` placeholder with the actual base64 signature.
-    var finalSigValue = sigTags.slice(0, -1).concat(["b=" + signature]).join("; ");
 
-    var dkimHeaderLine = _foldSignatureHeader(finalSigValue) + "\r\n";
+    // Wire header. Under simple canon, append the signature to the SAME folded
+    // empty-b header we signed, so a verifier parsing the folded wire and
+    // stripping b= reconstructs the signed bytes exactly. Under relaxed, re-fold
+    // the completed value (folding is normalized away on verify).
+    var dkimHeaderLine;
+    if (canonHeader === "simple") {
+      dkimHeaderLine = foldedEmptyB + signature + "\r\n";
+    } else {
+      var finalSigValue = sigTags.slice(0, -1).concat(["b=" + signature]).join("; ");
+      dkimHeaderLine = _foldSignatureHeader(finalSigValue) + "\r\n";
+    }
 
     _emit("dkim.sign.success", {
       bodyLength: body.length,
@@ -816,13 +840,23 @@ function _verifySingleSignature(rfc822, parsedHeaders, sigHeader, keyTags, sigTa
   // structure instead.
   var unsignedSigValue = _stripBTagValue(sigHeader.value);
   // The signature header is canonicalized under its true field name (§3.7).
-  // For the ARC reuse the header on the wire is ARC-Message-Signature, signed
-  // under that name; the synthetic renames it to DKIM-Signature only so this
-  // verifier finds it, so the canonical form must restore the real name or the
-  // b= value never matches what the relay signed.
-  var sigCanonName = verifyOpts.arcAmsReuse ? "ARC-Message-Signature" : "DKIM-Signature";
+  // Under simple canon the name is verbatim, so it must be the EXACT on-wire
+  // spelling the peer signed (sigHeader.name — _findDkimSignatureHeaders matches
+  // the field name case-insensitively and _parseHeaders preserves its casing),
+  // not a hardcoded "DKIM-Signature"; a peer that emits `dkim-signature:` signs
+  // that lowercase name and would otherwise never verify. (Relaxed canon
+  // lowercases the name, so the on-wire spelling doesn't matter there.) For the
+  // ARC reuse the header on the wire is ARC-Message-Signature, signed under that
+  // name; the synthetic renames it to DKIM-Signature only so this verifier finds
+  // it, so the canonical form must restore the real ARC name.
+  var sigCanonName = verifyOpts.arcAmsReuse ? "ARC-Message-Signature" : sigHeader.name;
+  // Simple canon is verbatim: the parsed sigHeader.value already carries the
+  // single space the wire places after the colon and its folding, so it is
+  // canonicalized as-is (b= emptied) — NOT re-spaced. (A prior `" " +` prefix
+  // here injected a spurious second space, so simple-canon signatures — ours
+  // and any RFC-compliant peer's — never matched what was signed.)
   canonicalizedHeaders += canonHeader === "simple"
-    ? _canonHeaderSimple(sigCanonName, " " + unsignedSigValue).replace(/\r\n$/, "")
+    ? _canonHeaderSimple(sigCanonName, unsignedSigValue).replace(/\r\n$/, "")
     : _canonHeaderRelaxed(sigCanonName, unsignedSigValue).replace(/\r\n$/, "");
 
   // 3. Verify the signature.

package/lib/safe-buffer.js

@@ -366,6 +366,38 @@ function byteLengthOf(value, encoding) {
     "Buffer, or Uint8Array; got " + (value === null ? "null" : typeof value));
 }
 
+/**
+ * @primitive b.safeBuffer.byteLengthOfIfMeasurable
+ * @signature b.safeBuffer.byteLengthOfIfMeasurable(value)
+ * @since     0.16.36
+ * @related   b.safeBuffer.byteLengthOf
+ *
+ * Like `byteLengthOf`, but returns `null` for a value that is not a
+ * measurable byte-carrier (a plain `Array`, an array-like object with a
+ * numeric `.length`, a number, ...) instead of throwing.
+ *
+ * For capping the size of an UNTRUSTED metadata bag whose byte field may be
+ * any shape: a content guard measures its cap only when the value is
+ * measurable and treats an unmeasurable value as uncapped-here — its
+ * magic/shape inspection reads only the leading bytes, so it is O(1)-bounded
+ * regardless of a claimed `.length` — rather than throwing out of its
+ * documented never-throw-on-hostile-metadata inspection contract. Route a
+ * hostile-metadata byte cap through this instead of gating `byteLengthOf` on
+ * a hand-rolled `typeof x.length === "number"` check (which admits array-likes
+ * and crashes `byteLengthOf`).
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeBuffer.byteLengthOfIfMeasurable("abc");          // → 3
+ *   b.safeBuffer.byteLengthOfIfMeasurable([1, 2, 3]);      // → null (a plain Array)
+ *   b.safeBuffer.byteLengthOfIfMeasurable({ length: 1e9 }); // → null (array-like)
+ */
+function byteLengthOfIfMeasurable(value) {
+  if (typeof value === "string") return Buffer.byteLength(value, "utf8");
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) return value.length;
+  return null;
+}
+
 // ---- boundedChunkCollector ----
 //
 // Replaces the unbounded `chunks.push(c); ... Buffer.concat(chunks)`
@@ -912,6 +944,7 @@ module.exports = {
   toBuffer:              toBuffer,
   makeByteCoercer:       makeByteCoercer,
   byteLengthOf:          byteLengthOf,
+  byteLengthOfIfMeasurable: byteLengthOfIfMeasurable,
   boundedChunkCollector: boundedChunkCollector,
   collectStream: collectStream,
   secureZero:            secureZero,

package/package.json

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

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:19f33cb5-0c9f-4b8e-81a7-381d0d4b9eaf",
+  "serialNumber": "urn:uuid:e5683da5-8c6c-4bc9-84ad-1d58dcca68c4",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-16T15:13:48.546Z",
+    "timestamp": "2026-07-16T17:16:56.426Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.16.35",
+      "bom-ref": "@blamejs/core@0.16.36",
       "type": "application",
       "name": "blamejs",
-      "version": "0.16.35",
+      "version": "0.16.36",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.16.35",
+      "purl": "pkg:npm/%40blamejs/core@0.16.36",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.16.35",
+      "ref": "@blamejs/core@0.16.36",
       "dependsOn": []
     }
   ]