@blamejs/core 0.12.52 → 0.12.53

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.53 (2026-05-25) — **`b.contentDigest` — HTTP Content-Digest / Repr-Digest fields (RFC 9530).** Emit and verify the Content-Digest / Repr-Digest HTTP fields so a recipient can detect a corrupted or tampered message body. b.contentDigest.create builds the RFC 8941 dictionary value (sha-256=:base64:, sha-512=:base64:) over a body; b.contentDigest.verify recomputes each modern digest over the body and compares it in constant time. Only SHA-256 and SHA-512 are computed — the legacy algorithms RFC 9530 §6 marks insecure (MD5, SHA-1, the unix checksums) are ignored on verify, and a field carrying no modern digest is refused, so an attacker cannot downgrade integrity to an MD5-only digest. Content-Digest is the integrity companion to HTTP Message Signatures (b.httpSig, RFC 9421): sign the digest rather than the whole body. Verified against the RFC 9530 Appendix D worked examples. **Added:** *`b.contentDigest.create(body, opts?)` / `b.contentDigest.verify(fieldValue, body, opts?)`* — `create` returns a Content-Digest / Repr-Digest field value over the body — SHA-256 by default, or any subset of `["sha-256","sha-512"]` via `opts.algorithms` — and refuses insecure or unknown algorithms. `verify` parses the field, recomputes each SHA-256 / SHA-512 entry over the body, and compares constant-time; it throws `content-digest/mismatch` on any mismatch, ignores legacy / unknown entries, throws `content-digest/no-modern-digest` if the field has no SHA-256 / SHA-512 entry at all, and honours `opts.required` to force specific algorithms to be present and match. Composes the framework's structured-field helpers and constant-time compare; Repr-Digest is the same machinery over the selected representation (RFC 9110).
+
 - v0.12.52 (2026-05-25) — **`b.privacyPass` — Privacy Pass origin-side token verification (RFC 9577 / 9578).** Anonymous, publicly verifiable authorization: an origin issues a WWW-Authenticate: PrivateToken challenge and verifies a presented token cryptographically, without learning who the client is and without a callback to the issuer. b.privacyPass implements the publicly verifiable token type 0x0002 (Blind RSA, 2048-bit): the token's authenticator is an RSA Blind Signature (RFC 9474) checked as RSASSA-PSS (SHA-384, 48-byte salt) over token_input = token_type ‖ nonce ‖ challenge_digest ‖ token_key_id, using only the issuer's public key. The token is bound to that key (token_key_id) and, optionally, to the challenge it answers, so a token minted for another origin is refused. Blind RSA is the algorithm Privacy Pass defines on the wire — like the DNSSEC / DANE verifiers it validates an external protocol's signatures rather than introducing classical crypto as a framework default. Verified against the RFC 9578 §8.2 test vector. **Added:** *`b.privacyPass.verifyToken(opts)` / `parseToken` / `buildChallenge`* — `buildChallenge` builds a TokenChallenge (RFC 9577 §2.1) and the matching `WWW-Authenticate: PrivateToken challenge=…, token-key=…` header an origin returns to request a token, scoped to an issuer (and optionally an origin and a 32-byte redemption context). `parseToken` splits a token into its fields (type / nonce / challenge_digest / token_key_id / authenticator). `verifyToken` verifies a type 0x0002 (Blind RSA) token: it confirms the token's `token_key_id` is the SHA-256 of the supplied issuer public key, optionally that its `challenge_digest` matches `opts.challenge`, and that the authenticator is a valid RSASSA-PSS signature over the token input. Refuses unknown / privately verifiable token types (the VOPRF type 0x0001 needs the issuer secret and is an issuer-side operation), key-id and challenge mismatches, and tampered authenticators. Marked experimental while the issuance protocols see deployment.
 
 - v0.12.51 (2026-05-25) — **`b.network.dns.dane.matchCertificate` — DANE / TLSA certificate matching (RFC 6698 / 7671).** Pin a service's certificate through DNS instead of a public CA. matchCertificate checks a server certificate against a set of TLSA records: the selected data — the full certificate (selector 0) or its subjectPublicKeyInfo (selector 1) — is hashed per the matching type (exact / SHA-256 / SHA-512) and compared in constant time to the record's association data. For a DANE-EE (usage 3) record a match is self-authenticating — the TLSA pins the key, so no public-CA path is needed (the common SMTP-DANE case, RFC 7672); for the PKIX usages a match is reported as necessary-but-not-sufficient so the caller still runs PKIX. This is the payoff of the DNSSEC verifier: verify the TLSA RRset with b.network.dns.dnssec, then match the certificate. Verified against a live DNSSEC-signed TLSA record and the matching server certificate. **Added:** *`b.network.dns.dane.matchCertificate(opts)`* — Matches a leaf certificate (and optional `chain`) against a TLSA RRset (`{ usage, selector, matchingType, data }`). Selector 0 hashes the full certificate DER, selector 1 the subjectPublicKeyInfo; matching type 0 is an exact comparison, 1 SHA-256, 2 SHA-512 (SHA-1 and any other type are refused, not guessed). End-entity usages (PKIX-EE 1, DANE-EE 3) match the leaf; trust-anchor usages (PKIX-TA 0, DANE-TA 2) match the leaf or any supplied chain certificate. Returns `{ ok, matched, daneAuthenticated, trustAnchorMatch, pkixRequired, matchedCertIndex }` — `daneAuthenticated` is true only for a DANE-EE match (the key is pinned, no CA needed); `pkixRequired` flags the PKIX usages. Throws `dane/no-match` when nothing matches, and refuses unknown usage / selector / matching values and unparseable certificates. Verify the TLSA RRset with `b.network.dns.dnssec` first — an unauthenticated TLSA record proves nothing.

package/README.md

@@ -97,7 +97,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **Field-level + crypto-shred** — `b.cryptoField.eraseRow`; per-column data residency tagging + per-row keys (`K_row = HKDF(K_table, rowId)`) so erasing the per-row key makes WAL / replica residuals undecryptable (`b.cryptoField.declareColumnResidency`, `b.cryptoField.declarePerRowKey`)
 - **AAD-bound sealed columns** — AEAD tag tied to `(table, rowId, column, schemaVersion)`; copy-paste between rows or schema-version replay surfaces as refused decrypt (`b.vault.aad`)
 - **Signed webhooks + API encryption** — SLH-DSA-SHAKE-256f default; ML-DSA-65 opt-in; ECIES API encryption (`b.webhook`, `b.crypto`)
-- **HPKE / HTTP signatures** — RFC 9180 HPKE with ML-KEM-1024 + HKDF-SHA3-512 + ChaCha20-Poly1305 (`b.crypto.hpke`); RFC 9421 HTTP Message Signatures with derived components and ed25519 / ML-DSA-65 (`b.crypto.httpSig`)
+- **HPKE / HTTP signatures** — RFC 9180 HPKE with ML-KEM-1024 + HKDF-SHA3-512 + ChaCha20-Poly1305 (`b.crypto.hpke`); RFC 9421 HTTP Message Signatures with derived components and ed25519 / ML-DSA-65 (`b.crypto.httpSig`); RFC 9530 Content-Digest / Repr-Digest body-integrity fields (SHA-256 / SHA-512, legacy algorithms refused — `b.contentDigest`) to sign the digest rather than the whole body
 - **CMS codec** — RFC 5652 Cryptographic Message Syntax encoder + decoder with PQC signers (ML-DSA-65 / ML-DSA-87 / SLH-DSA-SHAKE-256f; RFC 9909 + 9881) and KEMRecipientInfo recipients (ML-KEM-1024; RFC 9629 + 9936); ChaCha20-Poly1305 content encryption (RFC 8103) so Efail-class malleability cannot apply (`b.cms`)
 - **Stream throttle** — shared token-bucket bandwidth limiter (RFC 2697 srTCM shape); N concurrent `node:stream` pipelines draw from one operator-configured `bytesPerSec` budget (`b.streamThrottle`)
 - **TLS-RPT receiver** — RFC 8460 inbound aggregate-report ingest; HTTPS POST handler + §4.4 schema parser with gzip-bomb / ratio-bomb / depth-bomb defenses (`b.mail.deploy.parseTlsRptReport` / `b.mail.deploy.tlsRptIngestHttp`)

package/index.js

@@ -395,6 +395,7 @@ var fedcm = require("./lib/fedcm");
 var dbsc = require("./lib/dbsc");
 var importmapIntegrity = require("./lib/importmap-integrity");
 var privacyPass = require("./lib/privacy-pass");
+var contentDigest = require("./lib/content-digest");
 var standardWebhooks = require("./lib/standard-webhooks");
 var lro = require("./lib/lro");
 var jsonApi = require("./lib/jsonapi");
@@ -411,6 +412,7 @@ module.exports = {
   dbsc:             dbsc,
   importmapIntegrity: importmapIntegrity,
   privacyPass:      privacyPass,
+  contentDigest:    contentDigest,
   standardWebhooks: standardWebhooks,
   lro:              lro,
   jsonApi:          jsonApi,

package/lib/content-digest.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * @module b.contentDigest
+ * @nav    HTTP
+ * @title  Content-Digest
+ *
+ * @intro
+ *   HTTP Digest Fields (RFC 9530) — emit and verify the
+ *   <code>Content-Digest</code> / <code>Repr-Digest</code> fields that
+ *   carry a hash of a message body so a recipient can detect corruption
+ *   or tampering in transit. The field is an RFC 8941 dictionary of
+ *   <code>algorithm=:base64-digest:</code> entries; this module computes
+ *   and checks the modern algorithms (SHA-256, SHA-512) and ignores the
+ *   legacy ones (MD5, SHA-1, the unix checksums) that RFC 9530 §6 marks
+ *   insecure — refusing to accept a body whose only digest is a legacy
+ *   algorithm.
+ *
+ *   Content-Digest is the integrity companion to HTTP Message Signatures
+ *   (<code>b.httpSig</code>, RFC 9421): rather than signing a whole body,
+ *   sign its <code>Content-Digest</code> and let this module bind the
+ *   digest to the bytes.
+ *
+ * @card
+ *   HTTP Content-Digest / Repr-Digest (RFC 9530). Emit and verify a
+ *   SHA-256 / SHA-512 digest of a message body; legacy algorithms are
+ *   ignored and a body with no modern digest is refused. Pairs with
+ *   <code>b.httpSig</code> — sign the digest, not the bytes.
+ */
+
+var nodeCrypto = require("node:crypto");
+var bCrypto = require("./crypto");
+var structuredFields = require("./structured-fields");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var ContentDigestError = defineClass("ContentDigestError", { alwaysPermanent: true });
+
+// RFC 9530 IANA "Hash Algorithms for HTTP Digest Fields": Active vs
+// (insecure) deprecated. Active algorithms map to a Node hash name.
+var ACTIVE = { "sha-256": "sha256", "sha-512": "sha512" };
+var DEPRECATED = { "md5": 1, "sha": 1, "unixsum": 1, "unixcksum": 1, "adler": 1, "crc32c": 1 };
+
+// Decode an RFC 8941 Byte Sequence payload as STRICT, canonical base64.
+// Node's base64 decoder silently drops invalid characters and tolerates
+// bad padding, so `:<digest>!!!!:` or non-canonical padding would decode
+// to the same bytes and wrongly verify — a real risk when the
+// Content-Digest field is itself covered by an HTTP Message Signature.
+// Decoding then re-encoding and requiring the exact input back rejects
+// stray characters, whitespace, wrong padding, and non-zero trailing
+// bits in one canonical check (Node always re-emits canonical base64).
+function _strictBase64(s, what) {
+  if (typeof s !== "string" || s.length === 0) {
+    throw new ContentDigestError("content-digest/bad-field", "contentDigest: " + what + " is empty");
+  }
+  var buf = Buffer.from(s, "base64");
+  if (buf.length === 0 || buf.toString("base64") !== s) {
+    throw new ContentDigestError("content-digest/bad-field", "contentDigest: " + what + " is not canonical base64");
+  }
+  return buf;
+}
+
+function _bodyBytes(body, what) {
+  if (Buffer.isBuffer(body)) return body;
+  if (body instanceof Uint8Array) return Buffer.from(body);
+  if (typeof body === "string") return Buffer.from(body, "utf8");
+  throw new ContentDigestError("content-digest/bad-body", "contentDigest: " + what + " must be a Buffer / Uint8Array / string");
+}
+
+/**
+ * @primitive b.contentDigest.create
+ * @signature b.contentDigest.create(body, opts?)
+ * @since     0.12.53
+ * @status    stable
+ * @compliance soc2
+ * @related   b.contentDigest.verify, b.httpSig
+ *
+ * Build a <code>Content-Digest</code> (or <code>Repr-Digest</code>) field
+ * value over a message body (RFC 9530 §2): an RFC 8941 dictionary of
+ * <code>algorithm=:base64(digest):</code> members. Defaults to SHA-256;
+ * pass <code>algorithms</code> to emit several. Only the modern
+ * algorithms are offered — the digest is over the exact body bytes.
+ *
+ * @opts
+ *   {
+ *     algorithms: string[],  // subset of ["sha-256","sha-512"]; default ["sha-256"]
+ *   }
+ *
+ * @example
+ *   b.contentDigest.create('{"hello": "world"}');
+ *   // → "sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:"
+ */
+function create(body, opts) {
+  opts = opts || {};
+  validateOpts.requireObject(opts, "contentDigest.create", ContentDigestError);
+  validateOpts(opts, ["algorithms"], "contentDigest.create");
+  var bytes = _bodyBytes(body, "body");
+  var algos = opts.algorithms === undefined ? ["sha-256"] : opts.algorithms;
+  if (!Array.isArray(algos) || algos.length === 0) throw new ContentDigestError("content-digest/bad-arg", "contentDigest.create: opts.algorithms must be a non-empty array");
+  var members = algos.map(function (a) {
+    var name = String(a).toLowerCase();
+    var nodeAlg = ACTIVE[name];
+    if (!nodeAlg) {
+      if (DEPRECATED[name]) throw new ContentDigestError("content-digest/insecure-algorithm", "contentDigest.create: '" + name + "' is a deprecated/insecure digest algorithm (RFC 9530 §6); use sha-256 or sha-512");
+      throw new ContentDigestError("content-digest/unsupported-algorithm", "contentDigest.create: unsupported digest algorithm '" + name + "'");
+    }
+    var digest = nodeCrypto.createHash(nodeAlg).update(bytes).digest("base64");
+    return name + "=:" + digest + ":";                       // RFC 8941 Byte Sequence value
+  });
+  return members.join(", ");
+}
+
+/**
+ * @primitive b.contentDigest.verify
+ * @signature b.contentDigest.verify(fieldValue, body, opts?)
+ * @since     0.12.53
+ * @status    stable
+ * @compliance soc2
+ * @related   b.contentDigest.create, b.httpSig
+ *
+ * Verify a <code>Content-Digest</code> / <code>Repr-Digest</code> field
+ * value against a body (RFC 9530). Every modern (SHA-256 / SHA-512) entry
+ * is recomputed over the body and compared in constant time; a mismatch
+ * is refused. Legacy / unknown algorithms are ignored, but a field that
+ * carries <em>no</em> modern digest is refused (so an attacker cannot
+ * downgrade to an MD5-only digest). <code>opts.required</code> forces
+ * specific algorithms to be present and to match.
+ *
+ * @opts
+ *   {
+ *     required: string[],   // algorithms that MUST be present and match (e.g. ["sha-256"])
+ *   }
+ *
+ * @example
+ *   b.contentDigest.verify("sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:", '{"hello": "world"}');
+ *   // → { ok: true, verified: ["sha-256"] }
+ */
+function verify(fieldValue, body, opts) {
+  opts = opts || {};
+  validateOpts.requireObject(opts, "contentDigest.verify", ContentDigestError);
+  validateOpts(opts, ["required"], "contentDigest.verify");
+  if (typeof fieldValue !== "string" || fieldValue.trim() === "") throw new ContentDigestError("content-digest/bad-field", "contentDigest.verify: fieldValue must be a non-empty string");
+  structuredFields.refuseControlBytes(fieldValue, { ErrorClass: ContentDigestError, code: "content-digest/bad-field", label: "contentDigest fieldValue" });
+  var bytes = _bodyBytes(body, "body");
+
+  var members = structuredFields.splitTopLevel(fieldValue, ",");
+  var seen = Object.create(null);
+  var verified = [];
+  for (var i = 0; i < members.length; i++) {
+    var m = members[i].trim();
+    if (m === "") continue;
+    var eq = m.indexOf("=");
+    if (eq < 1) throw new ContentDigestError("content-digest/bad-field", "contentDigest.verify: malformed dictionary member");
+    var name = m.slice(0, eq).trim().toLowerCase();
+    var raw = m.slice(eq + 1).trim();
+    var nodeAlg = ACTIVE[name];
+    if (!nodeAlg) continue;                                  // ignore legacy / unknown entries
+    if (raw.length < 2 || raw.charAt(0) !== ":" || raw.charAt(raw.length - 1) !== ":") {
+      throw new ContentDigestError("content-digest/bad-field", "contentDigest.verify: '" + name + "' value is not an RFC 8941 byte sequence (:base64:)");
+    }
+    var claimed = _strictBase64(raw.slice(1, -1), name + " digest");
+    var actual = nodeCrypto.createHash(nodeAlg).update(bytes).digest();
+    if (!bCrypto.timingSafeEqual(actual, claimed)) {
+      throw new ContentDigestError("content-digest/mismatch", "contentDigest.verify: " + name + " digest does not match the body");
+    }
+    seen[name] = 1;
+    verified.push(name);
+  }
+
+  if (opts.required !== undefined && opts.required !== null) {
+    if (!Array.isArray(opts.required)) throw new ContentDigestError("content-digest/bad-arg", "contentDigest.verify: opts.required must be an array");
+    for (var r = 0; r < opts.required.length; r++) {
+      var req = String(opts.required[r]).toLowerCase();
+      if (!ACTIVE[req]) throw new ContentDigestError("content-digest/unsupported-algorithm", "contentDigest.verify: required algorithm '" + req + "' is not a modern digest");
+      if (!seen[req]) throw new ContentDigestError("content-digest/missing-algorithm", "contentDigest.verify: required digest '" + req + "' is not present");
+    }
+  }
+
+  if (verified.length === 0) {
+    throw new ContentDigestError("content-digest/no-modern-digest", "contentDigest.verify: no modern (sha-256 / sha-512) digest present — refusing to trust a legacy-only digest");
+  }
+  return { ok: true, verified: verified };
+}
+
+module.exports = {
+  create:             create,
+  verify:             verify,
+  ACTIVE_ALGORITHMS:  Object.keys(ACTIVE),
+  ContentDigestError: ContentDigestError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.52",
+  "version": "0.12.53",
   "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:455224f5-2973-4bdf-8fc9-c8553709b68b",
+  "serialNumber": "urn:uuid:20868c28-f68f-42c3-a926-c9e46216c41e",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-25T17:01:11.242Z",
+    "timestamp": "2026-05-25T18:23:33.227Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.52",
+      "bom-ref": "@blamejs/core@0.12.53",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.52",
+      "version": "0.12.53",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.52",
+      "purl": "pkg:npm/%40blamejs/core@0.12.53",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.52",
+      "ref": "@blamejs/core@0.12.53",
       "dependsOn": []
     }
   ]