@blamejs/core 0.12.51 → 0.12.53

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
 - v0.12.50 (2026-05-25) — **`b.network.dns.dnssec.verifyChain` — validate a DNSSEC delegation chain to a pinned root anchor.** Completes local DNSSEC verification: validate a full delegation chain from the root down to a zone against a pinned trust anchor (RFC 4035 §5), instead of trusting any single resolver. For each link, the zone's DNSKEY RRset must be self-signed by one of its keys, and that key must be vouched for either by a pinned anchor (at the root) or by a DS record served + signed by the already-trusted parent — so trust flows root → TLD → zone with no gap. The IANA root KSKs (KSK-2017 tag 20326, KSK-2024 tag 38696) ship as the default anchors; override with opts.trustAnchors for a private root. verifyChain returns the leaf zone's trusted DNSKEY set, which you then hand to verifyRrset / verifyDenial for the actual answer. Composes verifyRrset + verifyDs + the key tag; verified end-to-end against a live root→org chain. **Added:** *`b.network.dns.dnssec.verifyChain(opts)`* — Walks an ordered, root-first list of `links` ({ zone, dnskeys, dnskeyRrsig, dsRdatas?, dsRrsig? }). At each link it verifies the DNSKEY RRset's self-signature (composing `verifyRrset`), then establishes trust in the signing key: at the root by matching a pinned anchor's DS digest (`verifyDs`), at every delegation by verifying the parent-served DS RRset's signature with the already-trusted parent key and confirming the signing KSK matches one of those DS records. Returns `{ ok, zone, keys, path }` with the leaf zone's trusted DNSKEY set. Refuses a root key that matches no anchor (`dnssec/chain-anchor-mismatch`), a KSK that matches no parent DS (`dnssec/chain-ds-mismatch`), and a missing parent key (`dnssec/chain-no-parent-key`). The default `DEFAULT_ROOT_ANCHORS` are the published IANA root KSK DS records; `opts.trustAnchors` overrides them for a private or test root.

package/README.md

@@ -89,6 +89,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **Financial / Open Banking** — FAPI 2.0 Final composite posture (PAR + PKCE-S256 + DPoP-or-mTLS + RFC 9207); runtime enforcement helpers `b.fapi2.assertCallback` (refuses missing iss + bare-param under message-signing) and `b.fapi2.assertAuthzRequest` (refuses non-JAR); CFPB §1033 / FDX 6.0 consumer-financial-data-sharing wrapper (`b.fdx`)
 - **Data-subject coordination** — cross-table export / rectify / erase / restrict / objection (`b.subject`, `b.subject.eraseHard`); subject-level legal-hold registry consulted by erase + retention paths (FRCP Rule 26/37(e), GDPR Art 17(3)(e), SEC Rule 17a-4, HIPAA §164.530(j)(2)) (`b.legalHold`)
 - **Account safety** — adaptive bot-challenge staircase (`b.authBotChallenge`); session-to-device-posture binding with fail-closed verify (`b.sessionDeviceBinding`)
+- **Anonymous authorization** — Privacy Pass origin side (RFC 9577/9578 — `b.privacyPass`): issue a `WWW-Authenticate: PrivateToken` challenge and verify a presented Blind-RSA (type 0x0002) token against the issuer public key, with no issuer callback and no client identity
 ### Crypto
 
 - **At-rest envelope** — envelope-versioned PQC (ML-KEM-1024 + P-384 hybrid, XChaCha20-Poly1305, SHAKE256); vault sealing (`b.crypto`, `b.vault`)
@@ -96,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

@@ -394,6 +394,8 @@ var webPush = require("./lib/web-push-vapid");
 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");
@@ -409,6 +411,8 @@ module.exports = {
   fedcm:            fedcm,
   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/lib/privacy-pass.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * @module b.privacyPass
+ * @nav    Identity
+ * @title  Privacy Pass
+ *
+ * @intro
+ *   Origin / relying-party side of Privacy Pass (RFC 9577 HTTP
+ *   authentication scheme, RFC 9578 issuance protocols) — issue a token
+ *   challenge and verify a presented token without learning who the
+ *   client is. An origin asks for a token with a
+ *   <code>WWW-Authenticate: PrivateToken</code> challenge; the client
+ *   obtains a token from an issuer and presents it; the origin verifies
+ *   it cryptographically.
+ *
+ *   This implements the publicly verifiable token type
+ *   <strong>0x0002 (Blind RSA, 2048-bit)</strong>: the token's
+ *   authenticator is an RSA Blind Signature (RFC 9474) that any party
+ *   holding the issuer's public key can verify with RSASSA-PSS — so the
+ *   origin verifies tokens itself, with no issuer secret and no callback.
+ *   The privately verifiable VOPRF type (0x0001) requires the issuer's
+ *   secret key and is an issuer-side operation, not implemented here.
+ *
+ *   Blind RSA is the algorithm Privacy Pass defines on the wire; like
+ *   the framework's DNSSEC / DANE verifiers it validates an external
+ *   protocol's signatures (RSASSA-PSS, SHA-384) rather than introducing
+ *   classical crypto as a framework default.
+ *
+ * @card
+ *   Privacy Pass origin side (RFC 9577 / 9578). Issue a
+ *   <code>WWW-Authenticate: PrivateToken</code> challenge and verify a
+ *   presented Blind-RSA (type 0x0002) token against the issuer public
+ *   key — anonymous, publicly verifiable authorization with no issuer
+ *   callback.
+ */
+
+var nodeCrypto = require("node:crypto");
+var bCrypto = require("./crypto");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var PrivacyPassError = defineClass("PrivacyPassError", { alwaysPermanent: true });
+
+var TOKEN_TYPE_BLIND_RSA = 0x0002;
+// RFC 9578 §5.3 token type 0x0002: RSABSSA-SHA384-PSS, salt length 48.
+var PSS_HASH = "sha384";
+var PSS_SALT_LEN = 48;                                        // allow:raw-byte-literal — RFC 9578 §5.3 PSS salt length (= SHA-384 digest size)
+// Fixed-size token fields (RFC 9577 §2.2): type(2) nonce(32)
+// challenge_digest(32) token_key_id(32), then the authenticator.
+var TOKEN_PREFIX_LEN = 98;                                    // allow:raw-byte-literal — 2 + 32 + 32 + 32 (token_input length)
+
+// RFC 9577 §2.1 sends the challenge / token-key auth-params as base64url
+// WITH padding; Node's "base64url" output is unpadded, so pad to a
+// multiple of 4 so strict clients / proxies accept the header.
+function _b64urlPadded(buf) {
+  var s = Buffer.from(buf).toString("base64url");
+  while (s.length % 4 !== 0) s += "=";                        // allow:raw-byte-literal — base64 quantum is 4 chars
+  return s;
+}
+
+function _bytes(x, what) {
+  if (Buffer.isBuffer(x)) return x;
+  if (x instanceof Uint8Array) return Buffer.from(x);
+  if (typeof x === "string") return Buffer.from(x, "base64");
+  throw new PrivacyPassError("privacy-pass/bad-bytes", "privacyPass: " + what + " must be a Buffer / Uint8Array / base64 string");
+}
+
+// Import the issuer public key and capture the SubjectPublicKeyInfo
+// bytes used to derive token_key_id. When the caller supplies the
+// published SPKI DER directly, hash THOSE bytes — re-exporting an
+// rsa-pss KeyObject can re-encode the AlgorithmIdentifier and change the
+// digest. token_key_id is SHA-256 of the issuer's distributed key
+// (RFC 9577 §2.2), which is the SPKI as published.
+function _importIssuerKey(k) {
+  if (k && typeof k === "object" && typeof k.export === "function" && k.type === "public") {
+    return { key: k, spki: k.export({ format: "der", type: "spki" }) };
+  }
+  try {
+    if (Buffer.isBuffer(k) || k instanceof Uint8Array) {
+      var der = Buffer.from(k);
+      return { key: nodeCrypto.createPublicKey({ key: der, format: "der", type: "spki" }), spki: der };
+    }
+    // A "PUBLIC KEY" PEM body IS the SubjectPublicKeyInfo DER — decode it
+    // directly so token_key_id is SHA-256 of the issuer's exact bytes,
+    // not a re-encoding (Node can re-emit rsa-pss AlgorithmIdentifier
+    // parameters differently on export).
+    if (typeof k === "string" && /-----BEGIN PUBLIC KEY-----/.test(k)) {
+      var body = k.replace(/-----BEGIN PUBLIC KEY-----/, "").replace(/-----END PUBLIC KEY-----/, "").replace(/\s+/g, "");
+      var pemDer = Buffer.from(body, "base64");
+      return { key: nodeCrypto.createPublicKey(k), spki: pemDer };
+    }
+    var key = nodeCrypto.createPublicKey(k);                  // other key spec (best-effort SPKI export)
+    return { key: key, spki: key.export({ format: "der", type: "spki" }) };
+  } catch (e) {
+    throw new PrivacyPassError("privacy-pass/bad-key", "privacyPass: could not import issuerPublicKey: " + ((e && e.message) || e));
+  }
+}
+
+/**
+ * @primitive b.privacyPass.parseToken
+ * @signature b.privacyPass.parseToken(token)
+ * @since     0.12.52
+ * @status    experimental
+ * @related   b.privacyPass.verifyToken, b.privacyPass.buildChallenge
+ *
+ * Parse a Privacy Pass token (RFC 9577 §2.2) into its fields: the
+ * <code>tokenType</code>, the client <code>nonce</code>, the
+ * <code>challengeDigest</code> (SHA-256 of the TokenChallenge the token
+ * answers), the <code>tokenKeyId</code> (SHA-256 of the issuer public
+ * key), and the <code>authenticator</code>. Structural only — call
+ * <code>verifyToken</code> to check the signature.
+ *
+ * @example
+ *   var t = b.privacyPass.parseToken(tokenBytes);
+ *   // → { tokenType: 2, nonce, challengeDigest, tokenKeyId, authenticator }
+ */
+function parseToken(token) {
+  var b = _bytes(token, "token");
+  if (b.length < TOKEN_PREFIX_LEN + 1) throw new PrivacyPassError("privacy-pass/bad-token", "privacyPass.parseToken: token too short");
+  return {
+    tokenType:       b.readUInt16BE(0),
+    nonce:           b.slice(2, 34),
+    challengeDigest: b.slice(34, 66),
+    tokenKeyId:      b.slice(66, 98),
+    authenticator:   b.slice(98),
+    tokenInput:      b.slice(0, TOKEN_PREFIX_LEN),
+  };
+}
+
+/**
+ * @primitive b.privacyPass.verifyToken
+ * @signature b.privacyPass.verifyToken(opts)
+ * @since     0.12.52
+ * @status    experimental
+ * @compliance soc2
+ * @related   b.privacyPass.buildChallenge, b.privacyPass.parseToken
+ *
+ * Verify a publicly verifiable Privacy Pass token (type 0x0002, Blind
+ * RSA — RFC 9578 §8.2). The authenticator is checked as an RSASSA-PSS
+ * (SHA-384, MGF1-SHA-384, 48-byte salt) signature over
+ * <code>token_input = token_type ‖ nonce ‖ challenge_digest ‖
+ * token_key_id</code> using the issuer's public key. The token is bound
+ * to that key — its <code>token_key_id</code> must equal the SHA-256 of
+ * the supplied key's SubjectPublicKeyInfo — and, when
+ * <code>opts.challenge</code> is given, to that challenge (its SHA-256
+ * must equal the token's <code>challenge_digest</code>), so a token
+ * minted for a different origin's challenge is refused.
+ *
+ * @opts
+ *   {
+ *     token:            Buffer|base64,   // the presented token
+ *     issuerPublicKey:  KeyObject|Buffer(SPKI DER)|PEM,
+ *     challenge?:       Buffer|base64,   // the TokenChallenge this token must answer
+ *   }
+ *
+ * @example
+ *   var r = b.privacyPass.verifyToken({ token: tok, issuerPublicKey: issuerSpki });
+ *   // → { ok: true, tokenType: 2, nonce, challengeDigest, tokenKeyId }
+ */
+function verifyToken(opts) {
+  validateOpts.requireObject(opts, "privacyPass.verifyToken", PrivacyPassError);
+  validateOpts(opts, ["token", "issuerPublicKey", "challenge"], "privacyPass.verifyToken");
+  if (opts.issuerPublicKey === undefined || opts.issuerPublicKey === null) throw new PrivacyPassError("privacy-pass/bad-arg", "privacyPass.verifyToken: opts.issuerPublicKey is required");
+
+  var parsed = parseToken(opts.token);
+  if (parsed.tokenType !== TOKEN_TYPE_BLIND_RSA) {
+    throw new PrivacyPassError("privacy-pass/unsupported-token-type", "privacyPass.verifyToken: only token type 0x0002 (Blind RSA) is verifiable by the origin; got 0x" + parsed.tokenType.toString(16).padStart(4, "0"));  // allow:raw-byte-literal — base-16 radix + 4-hex-digit pad, not a size
+  }
+
+  var imported = _importIssuerKey(opts.issuerPublicKey);
+  var key = imported.key;
+  if (key.asymmetricKeyType !== "rsa" && key.asymmetricKeyType !== "rsa-pss") {
+    throw new PrivacyPassError("privacy-pass/bad-key", "privacyPass.verifyToken: issuerPublicKey must be an RSA key for token type 0x0002");
+  }
+
+  // Bind the token to the issuer key: token_key_id = SHA-256(SPKI).
+  var keyId = nodeCrypto.createHash("sha256").update(imported.spki).digest();
+  if (!bCrypto.timingSafeEqual(keyId, parsed.tokenKeyId)) {
+    throw new PrivacyPassError("privacy-pass/key-id-mismatch", "privacyPass.verifyToken: token_key_id does not match the issuer public key");
+  }
+
+  // Bind the token to the challenge, when supplied.
+  if (opts.challenge !== undefined && opts.challenge !== null) {
+    var cd = nodeCrypto.createHash("sha256").update(_bytes(opts.challenge, "challenge")).digest();
+    if (!bCrypto.timingSafeEqual(cd, parsed.challengeDigest)) {
+      throw new PrivacyPassError("privacy-pass/challenge-mismatch", "privacyPass.verifyToken: challenge_digest does not match opts.challenge");
+    }
+  }
+
+  var ok;
+  try {
+    ok = nodeCrypto.verify(PSS_HASH, parsed.tokenInput, { key: key, padding: nodeCrypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: PSS_SALT_LEN }, parsed.authenticator);
+  } catch (e) {
+    throw new PrivacyPassError("privacy-pass/verify-threw", "privacyPass.verifyToken: signature verification threw: " + ((e && e.message) || e));
+  }
+  if (!ok) throw new PrivacyPassError("privacy-pass/bad-authenticator", "privacyPass.verifyToken: token authenticator did not verify");
+  return { ok: true, tokenType: parsed.tokenType, nonce: parsed.nonce, challengeDigest: parsed.challengeDigest, tokenKeyId: parsed.tokenKeyId };
+}
+
+/**
+ * @primitive b.privacyPass.buildChallenge
+ * @signature b.privacyPass.buildChallenge(opts)
+ * @since     0.12.52
+ * @status    experimental
+ * @related   b.privacyPass.verifyToken
+ *
+ * Build a TokenChallenge (RFC 9577 §2.1) and the matching
+ * <code>WWW-Authenticate: PrivateToken</code> header value an origin
+ * returns to ask a client for a token. The challenge binds the token to
+ * this issuer (and optionally this origin and a redemption context);
+ * its SHA-256 is the <code>challenge_digest</code> that
+ * <code>verifyToken</code> checks.
+ *
+ * @opts
+ *   {
+ *     issuerName:        string,   // the token issuer's name
+ *     tokenType?:        number,   // default 0x0002 (Blind RSA)
+ *     originInfo?:       string,   // origin name(s) the token is scoped to (default: any)
+ *     redemptionContext?: Buffer,  // 0 or 32 bytes (default: empty)
+ *     tokenKey?:         Buffer|KeyObject,  // issuer SPKI, included as token-key= when given
+ *   }
+ *
+ * @example
+ *   var c = b.privacyPass.buildChallenge({ issuerName: "issuer.example", originInfo: "origin.example" });
+ *   res.setHeader("WWW-Authenticate", c.wwwAuthenticate);
+ */
+function buildChallenge(opts) {
+  validateOpts.requireObject(opts, "privacyPass.buildChallenge", PrivacyPassError);
+  validateOpts(opts, ["issuerName", "tokenType", "originInfo", "redemptionContext", "tokenKey"], "privacyPass.buildChallenge");
+  if (typeof opts.issuerName !== "string" || opts.issuerName === "") throw new PrivacyPassError("privacy-pass/bad-arg", "privacyPass.buildChallenge: opts.issuerName is required");
+  var tokenType = opts.tokenType === undefined ? TOKEN_TYPE_BLIND_RSA : opts.tokenType;
+  if (typeof tokenType !== "number" || !Number.isInteger(tokenType) || tokenType < 0 || tokenType > 0xffff) throw new PrivacyPassError("privacy-pass/bad-arg", "privacyPass.buildChallenge: tokenType must be a uint16");
+
+  var issuer = Buffer.from(opts.issuerName, "utf8");
+  if (issuer.length > 0xffff) throw new PrivacyPassError("privacy-pass/bad-arg", "privacyPass.buildChallenge: issuerName too long");
+  var origin = Buffer.alloc(0);
+  if (opts.originInfo !== undefined && opts.originInfo !== null) {
+    if (typeof opts.originInfo !== "string") throw new PrivacyPassError("privacy-pass/bad-arg", "privacyPass.buildChallenge: originInfo must be a string");
+    origin = Buffer.from(opts.originInfo, "utf8");
+    if (origin.length > 0xffff) throw new PrivacyPassError("privacy-pass/bad-arg", "privacyPass.buildChallenge: originInfo too long");
+  }
+  var rc = opts.redemptionContext !== undefined && opts.redemptionContext !== null ? _bytes(opts.redemptionContext, "redemptionContext") : Buffer.alloc(0);
+  if (rc.length !== 0 && rc.length !== 32) throw new PrivacyPassError("privacy-pass/bad-arg", "privacyPass.buildChallenge: redemptionContext must be empty or 32 bytes");  // allow:raw-byte-literal — RFC 9577 redemption_context is 0 or 32 bytes
+
+  var u16 = function (n) { return Buffer.from([(n >> 8) & 0xff, n & 0xff]); };
+  var challenge = Buffer.concat([
+    u16(tokenType),
+    u16(issuer.length), issuer,
+    Buffer.from([rc.length]), rc,
+    u16(origin.length), origin,
+  ]);
+
+  var parts = ['PrivateToken challenge="' + _b64urlPadded(challenge) + '"'];
+  if (opts.tokenKey !== undefined && opts.tokenKey !== null) {
+    var spki = (opts.tokenKey && typeof opts.tokenKey.export === "function") ? opts.tokenKey.export({ format: "der", type: "spki" }) : _bytes(opts.tokenKey, "tokenKey");
+    parts.push('token-key="' + _b64urlPadded(spki) + '"');
+  }
+  return { challenge: challenge, wwwAuthenticate: parts.join(", ") };
+}
+
+module.exports = {
+  parseToken:     parseToken,
+  verifyToken:    verifyToken,
+  buildChallenge: buildChallenge,
+  TOKEN_TYPE_BLIND_RSA: TOKEN_TYPE_BLIND_RSA,
+  PrivacyPassError: PrivacyPassError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.51",
+  "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:5b23f9db-6c61-4ca7-b708-bb0ac954fc34",
+  "serialNumber": "urn:uuid:20868c28-f68f-42c3-a926-c9e46216c41e",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-25T15:45:58.868Z",
+    "timestamp": "2026-05-25T18:23:33.227Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.51",
+      "bom-ref": "@blamejs/core@0.12.53",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.51",
+      "version": "0.12.53",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.51",
+      "purl": "pkg:npm/%40blamejs/core@0.12.53",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.51",
+      "ref": "@blamejs/core@0.12.53",
       "dependsOn": []
     }
   ]