@blamejs/core 0.12.46 → 0.12.48

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.48 (2026-05-25) — **`b.network.dns.dnssec` — local DNSSEC signature verification (RFC 4035).** Verify a DNS answer's RRSIG signature yourself instead of trusting the upstream resolver's AD bit. b.network.dns.dnssec.verifyRrset reconstructs the RFC 4034 §3.1.8.1 signed data — the RRSIG RDATA without the signature, followed by the RRset in canonical form (owner names lowercased, RRs ordered by canonical RDATA, the RRSIG's Original TTL) — and checks the signature against the DNSKEY, enforcing the inception / expiration window. Supports RSA/SHA-256 (alg 8), ECDSA P-256/SHA-256 (13), ECDSA P-384/SHA-384 (14), and Ed25519 (15) — the modern deployed set. verifyDs checks a delegation-signer digest against a DNSKEY (SHA-256 / SHA-384) and keyTag computes the RFC 4034 Appendix B key tag. The verification core is what a chain-walker composes; it defends against a compromised or on-path resolver that lies about authentication. **Added:** *`b.network.dns.dnssec.verifyRrset(opts)`* — Verifies an RRSIG over a canonicalised RRset against a DNSKEY. `opts` carries the owner `name`, the RR `type`, the wire-format `rdatas`, the parsed `rrsig` (algorithm / labels / originalTtl / inception / expiration / keyTag / signerName / signature), and the `dnskey` (algorithm + raw public key). The signed data is rebuilt per RFC 4034 §3.1.8.1: the RRSIG prefix (type covered | algorithm | labels | original TTL | expiration | inception | key tag | canonical signer name) followed by each RR in canonical form (lowercased owner | type | class | original TTL | rdlen | rdata), sorted by `Buffer.compare` on the RDATA. The validity window is enforced against `opts.at` (defaults to now; an invalid Date is refused, not treated as now). An RRSIG whose algorithm disagrees with the DNSKEY is refused before any key is built. RR types that embed domain names in their RDATA (NS, CNAME, SOA, MX, SRV, …) need RDATA-internal name-lowercasing this version does not perform, so they are refused with `dnssec/uncanonicalizable-type` rather than mis-validated; the security-critical DNSKEY / DS and the name-free address / text types (A, AAAA, TXT, CAA, TLSA, …) are fully supported. · *`b.network.dns.dnssec.verifyDs(opts)` / `b.network.dns.dnssec.keyTag(dnskeyRdata)`* — `verifyDs` confirms a delegation-signer record matches a DNSKEY: it checks the key tag, then compares the DS digest (SHA-256 type 2 / SHA-384 type 4) against the digest computed over the canonical owner name and the DNSKEY RDATA, constant-time. `keyTag` computes the RFC 4034 Appendix B 16-bit key tag from a DNSKEY's full RDATA — the identifier an RRSIG or DS uses to select the signing key. Together with `verifyRrset` these are the per-RRset building blocks a recursive chain-walk (root → TLD → zone) composes; the chain-walk itself, NSEC / NSEC3 denial-of-existence, and the bundled IANA root trust anchor are not part of this core.
+
+- v0.12.47 (2026-05-25) — **`b.cose.mac0` / `b.cose.macVerify0` — COSE_Mac0 (RFC 9052 §6.2).** Completes the COSE message-type set (COSE_Sign1 / COSE_Encrypt0 / COSE_Mac0) with single shared-key MACs. b.cose.mac0 produces a tagged COSE_Mac0 over a payload using HMAC-SHA-256/384/512 (the COSE-standard MAC algorithms; HMAC is symmetric, so its post-quantum strength is preserved). b.cose.macVerify0 recomputes the tag over the MAC_structure and compares it in constant time, with a mandatory algorithm allowlist. Use when both parties hold a shared key — e.g. an ECDH-derived key — and a non-repudiable signature is not wanted; detached payloads are supported (the proximity mdoc device-MAC variant and MACed CWTs are the consumers). Composes b.cbor + the framework's constant-time compare; no new runtime dependency. **Added:** *`b.cose.mac0(payload, opts)` / `b.cose.macVerify0(coseMac0, opts)`* — `mac0` emits a tagged COSE_Mac0 (tag 17) with `alg` (`HMAC-256/256` | `HMAC-384/384` | `HMAC-512/512`) in the protected header and the HMAC tag computed over the MAC_structure `["MAC0", protected, external_aad, payload]`; `detached: true` emits a nil payload. `macVerify0` reads the algorithm from the protected header (must be in the required `opts.algorithms` allowlist), recomputes the tag, and compares it constant-time — a wrong key, tampered tag, or `external_aad` mismatch is refused with `cose/bad-tag`; a detached payload is supplied via `opts.externalPayload`. `external_aad` binds context into the tag.
+
 - v0.12.46 (2026-05-25) — **`b.mdoc.verifyDeviceAuth` — ISO 18013-5 mdoc device authentication.** Completes mdoc verification with the holder-binding half (ISO 18013-5 §9.1.3, signature variant). verifyIssuerSigned proves the data is issuer-signed; verifyDeviceAuth proves the presenter controls the device key the issuer bound into the MSO, so a captured issuer-signed document cannot be replayed by anyone else. The device's COSE_Sign1 (deviceSigned.deviceAuth.deviceSignature) is verified over the detached DeviceAuthentication structure ["DeviceAuthentication", SessionTranscript, DocType, DeviceNameSpacesBytes] using the device key from verifyIssuerSigned().deviceKey (now surfaced) and the operator-supplied SessionTranscript that binds the proof to this exact exchange (the presentation protocol — e.g. OpenID4VP — defines the transcript). Composes the v0.12.45 b.cose detached-payload verify + importKey. The MAC variant (deviceMac / COSE_Mac0, used in proximity flows with a reader ephemeral key) is deferred and refused with mdoc/device-mac-unsupported. No new runtime dependency. **Added:** *`b.mdoc.verifyDeviceAuth(opts)` + `deviceKey` on the verifyIssuerSigned result* — `verifyDeviceAuth({ deviceKey, deviceSigned, docType, sessionTranscript, algorithms })` imports the device key (a COSE_Key via `b.cose.importKey`, or a KeyObject), reconstructs the detached `DeviceAuthentication` payload, and verifies the `deviceSignature` COSE_Sign1 against the mandatory algorithm allowlist — a mismatched `sessionTranscript` or `docType` fails the signature. `verifyIssuerSigned` now returns `deviceKey` (the MSO `deviceKeyInfo.deviceKey`) so the two checks chain. The MAC variant (`deviceMac`) is refused with `mdoc/device-mac-unsupported` pending COSE_Mac0 + reader-key support.
 
 - v0.12.45 (2026-05-25) — **`b.cose` adds detached-payload sign/verify + `b.cose.importKey` (COSE_Key).** Two RFC 9052 / 9053 completions to the COSE substrate, both useable today and the prerequisites for mdoc device authentication and C2PA claim verification. Detached payloads (RFC 9052 §4.1): b.cose.sign with detached:true emits a COSE_Sign1 whose payload slot is nil — the signature still covers the payload, and the caller transmits it out of band; b.cose.verify takes the payload back as opts.externalPayload and binds it into the Sig_structure. A detached token verified without externalPayload is refused, and supplying externalPayload for an attached token is refused as ambiguous. COSE_Key import (RFC 9052 §7): b.cose.importKey turns a COSE_Key CBOR map into a node:crypto public KeyObject for b.cose.verify, accepting EC2 (P-256 / P-384 / P-521) and OKP (Ed25519) with the curve allowlisted so an unexpected key type is refused. No new runtime dependency. **Added:** *Detached COSE_Sign1 payloads + `b.cose.importKey(coseKey)`* — `b.cose.sign(payload, { detached: true })` emits a nil-payload COSE_Sign1 (the signature covers the payload regardless); `b.cose.verify(coseSign1, { externalPayload })` reconstructs the Sig_structure from the supplied payload, refusing a detached token with no `externalPayload` (`cose/detached-no-payload`) and refusing `externalPayload` on an attached token (`cose/payload-ambiguous`). `b.cose.importKey(coseKey)` maps a COSE_Key map (`kty` 2/EC2 with `crv` P-256/384/521, or `kty` 1/OKP with Ed25519) to a public KeyObject, allowlisting `kty`/`crv` and refusing anything else with `cose/unsupported-key` — the verification key embedded in an mdoc MSO or COSE_Key header is consumed this way.

package/README.md

@@ -120,14 +120,14 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
   - In-process CIDR fence (`b.middleware.networkAllowlist`)
   - `Cache-Control: no-store` on every 401 from `requireAuth` / `requireAal` / `requireStepUp` per RFC 9111 §5.2.2.5
 - **Outbound HTTP client** — HTTP/1.1 + HTTP/2 with SSRF gate (cloud-metadata IPs hard-denied; private / loopback / link-local overridable per call); scheme + userinfo + per-host destination allowlist; redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`)
-- **Network configurability (`b.network`)** — env-driven NTP / NTS (RFC 8915), IPv4/IPv6 NTP, DNS with IPv6 / DoH / DoT (private-CA pinning) / cache / lookup timeout; outbound HTTP proxy (`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`); runtime DPI trust-store CA additions; application-level heartbeats; TCP socket defaults
+- **Network configurability (`b.network`)** — env-driven NTP / NTS (RFC 8915), IPv4/IPv6 NTP, DNS with IPv6 / DoH / DoT (private-CA pinning) / cache / lookup timeout; local DNSSEC signature verification (RFC 4035 — `b.network.dns.dnssec.verifyRrset` over a canonicalised RRset against RSA / ECDSA P-256·P-384 / Ed25519 DNSKEYs, plus DS-digest + key-tag) so a resolver client can verify an answer instead of trusting the upstream AD bit; outbound HTTP proxy (`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`); runtime DPI trust-store CA additions; application-level heartbeats; TCP socket defaults
 - **Error pages** — operator-rendered, no app-frame leakage (`b.errorPage`)
 ### Defensive parsers
 
 - **JSON / SQL / schema** — `b.safeJson` (with `maxKeys` cap defending CVE-2026-21717 V8 HashDoS), `b.safeBuffer`, `b.safeSql`, `b.safeSchema`
 - **URL + path** — `b.safeUrl` (IDN mixed-script / homograph refuse); `b.safeJsonPath` (refuses filter `?(...)`, deep-scan `$..`, script-shape `(@.x)` for safe Postgres JSONB ops)
 - **Binary codec** — `b.cbor` bounded deterministic CBOR (RFC 8949 §4.2): depth/size caps, indefinite-length + reserved-info + tag + duplicate-key refusal, `requireDeterministic` canonical-form check; the in-tree substrate under COSE / CWT / SCITT / WebAuthn attestation
-- **COSE signing + encryption** — `b.cose` COSE_Sign1 sign/verify (attached or detached payload) + COSE_Encrypt0 + `importKey` (COSE_Key → KeyObject) (RFC 9052) over `b.cbor`: classical ES256/384/512 + EdDSA (final COSE ids, interoperable today) plus ML-DSA-87 (PQC-forward, draft id); bounded + alg-allowlisted + crit-bypass-checked verification; single-recipient AEAD (ChaCha20/Poly1305 default, AES-GCM opt-in) with Enc_structure-bound AAD; the signed-statement substrate under SCITT / CWT / mdoc / C2PA
+- **COSE messages** — `b.cose` the full RFC 9052 message-type set over `b.cbor`: COSE_Sign1 sign/verify (attached or detached payload), COSE_Encrypt0 single-recipient AEAD, COSE_Mac0 shared-key HMAC (mac0/macVerify0), plus `importKey` (COSE_Key → KeyObject). Signatures use classical ES256/384/512 + EdDSA (final COSE ids, interoperable today) plus ML-DSA-87 (PQC-forward, draft id); bounded + alg-allowlisted + crit-bypass-checked verification; AEAD ChaCha20/Poly1305 default (AES-GCM opt-in); the signed-statement substrate under SCITT / CWT / mdoc / C2PA
 - **CBOR Web Token** — `b.cwt` CWT sign/verify (RFC 8392) over `b.cose`: standard-claim mapping (iss/sub/aud/exp/nbf/iat/cti) + `exp`/`nbf` clock-skew enforcement + `iss`/`aud` matching; the CBOR-native JWT for constrained / IoT / FIDO / verifiable-credential contexts
 - **Entity Attestation Token** — `b.eat` EAT sign/verify (RFC 9711) over `b.cwt`: device + software attestation claims (ueid / oemid / hwmodel / measurements / submods) with verifier-nonce freshness binding, `dbgstat` debug-status policy, and `eat_profile` pinning
 - **SCITT signed statements** — `b.scitt` sign/verify a signed, attributable claim about an artifact (signed SBOM, build attestation, release approval) over `b.cose`: the issuer + subject bind in the integrity-protected CWT_Claims header (RFC 9597); verification refuses any statement missing the iss/sub binding. The issuer side, on finalized RFCs; the transparency receipt (COSE Receipts draft) opts in on publication

package/lib/cose.js

@@ -53,6 +53,7 @@
 
 var nodeCrypto = require("node:crypto");
 var cbor = require("./cbor");
+var bCrypto = require("./crypto");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
@@ -548,6 +549,190 @@ function decrypt0(coseEncrypt0, opts) {
   return { plaintext: pt, alg: algName, protectedHeaders: protMap, unprotectedHeaders: unprotected };
 }
 
+// ---- COSE_Mac0 (RFC 9052 §6.2) — single shared-key MAC ----
+
+var COSE_MAC0_TAG = 17;                                                       // allow:raw-byte-literal — RFC 9052 COSE_Mac0 CBOR tag
+// HMAC algorithms (RFC 9053 §3.1). Only the full-length tags are offered —
+// the truncated HMAC 256/64 (id 4) is omitted. HMAC is symmetric, so its
+// post-quantum strength is fine; these are the COSE-standard MAC algs.
+var HMAC_NAME_TO_ID = { "HMAC-256/256": 5, "HMAC-384/384": 6, "HMAC-512/512": 7 };   // allow:raw-byte-literal — COSE HMAC algorithm ids (RFC 9053)
+var HMAC_ID_TO_NAME = {};
+Object.keys(HMAC_NAME_TO_ID).forEach(function (k) { HMAC_ID_TO_NAME[HMAC_NAME_TO_ID[k]] = k; });
+function _hmacHash(algId) {
+  switch (algId) {
+    case 5: return "sha256";
+    case 6: return "sha384";
+    case 7: return "sha512";
+    default: throw new CoseError("cose/unknown-alg", "cose: unrecognized HMAC COSE alg id " + algId);
+  }
+}
+
+// MAC_structure (§6.3) = [ "MAC0", body_protected (bstr), external_aad (bstr), payload (bstr) ].
+function _macStructure(protectedBstr, externalAad, payload) {
+  return cbor.encode(["MAC0", protectedBstr, externalAad, payload]);
+}
+
+/**
+ * @primitive b.cose.mac0
+ * @signature b.cose.mac0(payload, opts)
+ * @since     0.12.47
+ * @status    stable
+ * @related   b.cose.macVerify0, b.cose.sign
+ *
+ * Produce a tagged COSE_Mac0 (RFC 9052 §6.2) — a single shared-key MAC
+ * over <code>payload</code>. The MAC is HMAC-SHA-256 / 384 / 512 (the
+ * COSE-standard MAC algorithms; HMAC is symmetric, so post-quantum
+ * strength is preserved). Use when both parties hold a shared key (e.g.
+ * an ECDH-derived key) and a non-repudiable signature is not wanted.
+ * <code>detached: true</code> emits a nil payload, verified later with
+ * <code>opts.externalPayload</code>.
+ *
+ * @opts
+ *   {
+ *     alg:        string,   // "HMAC-256/256" | "HMAC-384/384" | "HMAC-512/512"
+ *     key:        Buffer,   // shared symmetric key
+ *     externalAad?: Buffer, // bound into the MAC
+ *     detached?:  boolean,  // emit a nil payload (caller re-supplies it on verify)
+ *     unprotectedHeaders?: object,
+ *   }
+ *
+ * @example
+ *   var mac = b.cose.mac0(Buffer.from("data"), { alg: "HMAC-256/256", key: sharedKey });
+ */
+function mac0(payload, opts) {
+  validateOpts.requireObject(opts, "cose.mac0", CoseError);
+  validateOpts(opts, ["alg", "key", "externalAad", "detached", "unprotectedHeaders"], "cose.mac0");
+  if (!(opts.alg in HMAC_NAME_TO_ID)) {
+    throw new CoseError("cose/unsignable-alg", "cose.mac0: alg must be one of " + Object.keys(HMAC_NAME_TO_ID).join(" / "));
+  }
+  var key = _bstr(opts.key);
+  var algId = HMAC_NAME_TO_ID[opts.alg];
+  var protMap = new Map();
+  protMap.set(HDR_ALG, algId);
+  var protectedBstr = cbor.encode(protMap);
+
+  var unprot = new Map();
+  if (opts.unprotectedHeaders && typeof opts.unprotectedHeaders === "object") {
+    var uk = Object.keys(opts.unprotectedHeaders);
+    for (var i = 0; i < uk.length; i++) unprot.set(Number(uk[i]), opts.unprotectedHeaders[uk[i]]);
+  }
+
+  var payloadBytes = _bstr(payload);
+  var externalAad = opts.externalAad == null ? Buffer.alloc(0) : _bstr(opts.externalAad);
+  var tag = nodeCrypto.createHmac(_hmacHash(algId), key).update(_macStructure(protectedBstr, externalAad, payloadBytes)).digest();
+
+  var mac0arr = [protectedBstr, unprot, opts.detached ? null : payloadBytes, tag];
+  return cbor.encode(new cbor.Tag(COSE_MAC0_TAG, mac0arr));
+}
+
+/**
+ * @primitive b.cose.macVerify0
+ * @signature b.cose.macVerify0(coseMac0, opts)
+ * @since     0.12.47
+ * @status    stable
+ * @related   b.cose.mac0
+ *
+ * Verify a COSE_Mac0 (RFC 9052 §6.2) and return its payload. The HMAC
+ * tag is recomputed over the MAC_structure and compared in constant
+ * time; the <code>alg</code> from the protected header must be in
+ * <code>opts.algorithms</code>. A detached (nil) payload is supplied via
+ * <code>opts.externalPayload</code>.
+ *
+ * @opts
+ *   {
+ *     algorithms:  string[],  // required — accepted HMAC alg names (allowlist)
+ *     key:         Buffer,    // the shared symmetric key
+ *     externalAad?: Buffer,
+ *     externalPayload?: Buffer, // required for a detached payload
+ *     maxBytes?:   number,
+ *     maxDepth?:   number,
+ *   }
+ *
+ * @example
+ *   var out = b.cose.macVerify0(mac, { algorithms: ["HMAC-256/256"], key: sharedKey });
+ *   // → { payload: <Buffer>, alg: "HMAC-256/256", protectedHeaders: Map, unprotectedHeaders: Map }
+ */
+function macVerify0(coseMac0, opts) {
+  validateOpts.requireObject(opts, "cose.macVerify0", CoseError);
+  validateOpts(opts, ["algorithms", "key", "externalAad", "externalPayload", "maxBytes", "maxDepth"], "cose.macVerify0");
+  if (!Array.isArray(opts.algorithms) || opts.algorithms.length === 0) {
+    throw new CoseError("cose/algorithms-required", "cose.macVerify0: opts.algorithms is required");
+  }
+  for (var ai = 0; ai < opts.algorithms.length; ai++) {
+    if (!(opts.algorithms[ai] in HMAC_NAME_TO_ID)) {
+      throw new CoseError("cose/unknown-alg", "cose.macVerify0: unknown algorithm '" + opts.algorithms[ai] + "'");
+    }
+  }
+  if (opts.key == null) throw new CoseError("cose/no-key", "cose.macVerify0: opts.key is required");
+  var key = _bstr(opts.key);
+
+  var decoded = cbor.decode(_bstr(coseMac0), { allowedTags: [COSE_MAC0_TAG], maxBytes: opts.maxBytes, maxDepth: opts.maxDepth });
+  var arr = (decoded instanceof cbor.Tag && decoded.tag === COSE_MAC0_TAG) ? decoded.value : decoded;
+  if (!Array.isArray(arr) || arr.length !== 4) {
+    throw new CoseError("cose/malformed", "cose.macVerify0: not a COSE_Mac0 (expected a 4-element array)");
+  }
+  var protectedBstr = arr[0];
+  var unprotected = arr[1];
+  var payload = arr[2];
+  var tag = arr[3];
+  if (!Buffer.isBuffer(protectedBstr) || !Buffer.isBuffer(tag)) {
+    throw new CoseError("cose/malformed", "cose.macVerify0: protected header and tag must be byte strings");
+  }
+  if (!(unprotected instanceof Map)) {
+    throw new CoseError("cose/malformed", "cose.macVerify0: unprotected header must be a CBOR map");
+  }
+  if (payload === null || payload === undefined) {
+    if (opts.externalPayload == null) {
+      throw new CoseError("cose/detached-no-payload", "cose.macVerify0: detached (nil) payload — pass opts.externalPayload");
+    }
+    payload = _bstr(opts.externalPayload);
+  } else if (opts.externalPayload != null) {
+    throw new CoseError("cose/payload-ambiguous", "cose.macVerify0: externalPayload supplied but the COSE_Mac0 carries an attached payload");
+  } else if (!Buffer.isBuffer(payload)) {
+    throw new CoseError("cose/malformed", "cose.macVerify0: payload must be a byte string (bstr)");
+  }
+
+  var protMap = protectedBstr.length === 0 ? new Map()
+    : cbor.decode(protectedBstr, { maxBytes: opts.maxBytes, maxDepth: opts.maxDepth });
+  if (!(protMap instanceof Map)) {
+    throw new CoseError("cose/malformed", "cose.macVerify0: protected header is not a CBOR map");
+  }
+  // crit-bypass defense (RFC 9052 §3.1) — same as b.cose.verify: every
+  // label a crit array names must be one this verifier understands AND
+  // be present in the protected header.
+  if (protMap.has(HDR_CRIT)) {
+    var crit = protMap.get(HDR_CRIT);
+    if (!Array.isArray(crit)) {
+      throw new CoseError("cose/bad-crit", "cose.macVerify0: crit (label 2) must be an array");
+    }
+    for (var ci = 0; ci < crit.length; ci++) {
+      if (UNDERSTOOD_LABELS.indexOf(crit[ci]) === -1) {
+        throw new CoseError("cose/crit-unknown",
+          "cose.macVerify0: crit lists header label " + crit[ci] + " which is not understood (RFC 9052 §3.1)");
+      }
+      if (!protMap.has(crit[ci])) {
+        throw new CoseError("cose/crit-absent",
+          "cose.macVerify0: crit lists label " + crit[ci] + " not present in the protected header");
+      }
+    }
+  }
+  var algId = protMap.get(HDR_ALG);
+  var algName = HMAC_ID_TO_NAME[algId];
+  if (algName === undefined) {
+    throw new CoseError("cose/unknown-alg", "cose.macVerify0: unrecognized protected MAC alg id " + algId);
+  }
+  if (opts.algorithms.indexOf(algName) === -1) {
+    throw new CoseError("cose/alg-not-allowed", "cose.macVerify0: alg '" + algName + "' is not in the allowlist");
+  }
+
+  var externalAad = opts.externalAad == null ? Buffer.alloc(0) : _bstr(opts.externalAad);
+  var expected = nodeCrypto.createHmac(_hmacHash(algId), key).update(_macStructure(protectedBstr, externalAad, payload)).digest();
+  if (!bCrypto.timingSafeEqual(expected, tag)) {
+    throw new CoseError("cose/bad-tag", "cose.macVerify0: MAC tag verification failed");
+  }
+  return { payload: payload, alg: algName, protectedHeaders: protMap, unprotectedHeaders: unprotected };
+}
+
 // ---- COSE_Key (RFC 9052 §7 / RFC 9053 §7) → KeyObject ----
 
 // COSE_Key EC2 curve identifiers (RFC 9053 §7.1) → JWK crv names. Only
@@ -623,8 +808,12 @@ module.exports = {
   verify:      verify,
   encrypt0:    encrypt0,
   decrypt0:    decrypt0,
+  mac0:        mac0,
+  macVerify0:  macVerify0,
   importKey:   importKey,
   ALGORITHMS:  ALG_NAME_TO_ID,
+  MAC_ALGORITHMS: HMAC_NAME_TO_ID,
+  COSE_MAC0_TAG: COSE_MAC0_TAG,
   AEAD_ALGORITHMS: AEAD_NAME_TO_ID,
   COSE_SIGN1_TAG: COSE_SIGN1_TAG,
   COSE_ENCRYPT0_TAG: COSE_ENCRYPT0_TAG,

package/lib/network-dnssec.js

@@ -0,0 +1,328 @@
+"use strict";
+/**
+ * @module b.network.dns.dnssec
+ * @nav    Network
+ * @title  DNSSEC validation
+ *
+ * @intro
+ *   Local DNSSEC signature verification (RFC 4033–4035 / 6605 / 8080) —
+ *   the cryptographic core that lets a resolver client verify a DNS
+ *   answer itself instead of trusting the upstream resolver's AD bit.
+ *   <code>b.network.dns.resolver</code> checks the AD flag; this module
+ *   verifies the actual RRSIG signature over the canonicalised RRset,
+ *   defending against a compromised or on-path resolver.
+ *
+ *   <code>verifyRrset</code> reconstructs the RFC 4034 §3.1.8.1 signed
+ *   data (the RRSIG RDATA without the signature, followed by the RRset
+ *   in canonical form — owner names lowercased, RRs ordered by canonical
+ *   RDATA, the RRSIG's Original TTL) and verifies it with the DNSKEY,
+ *   enforcing the signature's inception / expiration window. The DNSKEY
+ *   algorithms are RSA/SHA-256 (8), ECDSA P-256/SHA-256 (13), ECDSA
+ *   P-384/SHA-384 (14), and Ed25519 (15) — the modern, deployed set.
+ *   <code>verifyDs</code> checks a delegation-signer digest against a
+ *   DNSKEY (SHA-256 / SHA-384), and <code>keyTag</code> computes the
+ *   RFC 4034 Appendix B key tag.
+ *
+ *   <strong>Scope.</strong> This is the verification core. RR types that
+ *   carry domain names in their RDATA (NS, CNAME, SOA, MX, SRV, …) need
+ *   name-lowercasing inside the RDATA (RFC 4034 §6.2) that this version
+ *   does not perform, so they are refused with
+ *   <code>dnssec/uncanonicalizable-type</code> rather than mis-validated
+ *   — the security-critical DNSKEY / DS and the name-free address /
+ *   text types (A, AAAA, TXT, …) are fully supported. The recursive
+ *   chain-walk (root → TLD → zone), NSEC / NSEC3 denial-of-existence,
+ *   and the IANA root trust-anchor bundle are deferred: these primitives
+ *   are the per-RRset building blocks a chain-walker composes.
+ *
+ * @card
+ *   Local DNSSEC verification (RFC 4035) — verify an RRSIG over a
+ *   canonicalised RRset against a DNSKEY (RSA / ECDSA P-256·P-384 /
+ *   Ed25519), plus DS-digest + key-tag. Don't trust the upstream AD bit;
+ *   verify the signature. Name-bearing RR types are refused, not
+ *   mis-validated; chain-walk + NSEC3 deferred.
+ */
+
+var nodeCrypto = require("node:crypto");
+var bCrypto = require("./crypto");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var DnssecError = defineClass("DnssecError", { alwaysPermanent: true });
+
+// DNSSEC algorithm numbers (IANA DNSSEC Algorithm Numbers) → verify params.
+var ALGS = {
+  8:  { name: "RSASHA256",        kind: "rsa",   hash: "sha256" },                          // allow:raw-byte-literal — IANA DNSSEC algorithm number
+  13: { name: "ECDSAP256SHA256",  kind: "ec",    hash: "sha256", crv: "P-256", coord: 32 },   // allow:raw-byte-literal — P-256 coordinate size
+  14: { name: "ECDSAP384SHA384",  kind: "ec",    hash: "sha384", crv: "P-384", coord: 48 },   // allow:raw-byte-literal — P-384 coordinate size
+  15: { name: "ED25519",          kind: "okp",   hash: null,     crv: "Ed25519" },
+};
+
+// DS digest algorithms (IANA) → node hash.
+var DS_DIGESTS = { 2: "sha256", 4: "sha384" };
+
+// RR types whose RDATA contains NO embedded domain name, so the wire
+// RDATA is already in canonical form (RFC 4034 §6.2 needs no rewrite).
+// Name-bearing types are refused rather than silently mis-canonicalised.
+// (type numbers IANA): A 1, AAAA 28, TXT 16, DNSKEY 48, DS 43, CAA 257,
+// TLSA 52, SSHFP 44, HINFO 13, CDS 59, CDNSKEY 60, OPENPGPKEY 61, SMIMEA 53.
+var NAME_FREE_TYPE_NUMS = [1, 28, 16, 48, 43, 257, 52, 44, 13, 59, 60, 61, 53];          // allow:raw-byte-literal allow:raw-time-literal — IANA DNS type numbers (no embedded names)
+var TYPE_NUM = {
+  A: 1, NS: 2, CNAME: 5, SOA: 6, PTR: 12, MX: 15, TXT: 16, AAAA: 28, SRV: 33,
+  DS: 43, SSHFP: 44, RRSIG: 46, DNSKEY: 48, TLSA: 52, SMIMEA: 53, CDS: 59, CDNSKEY: 60, // allow:raw-byte-literal allow:raw-time-literal — IANA DNS type numbers
+  OPENPGPKEY: 61, CAA: 257, HINFO: 13,
+};
+
+function _bytes(x, what) {
+  if (Buffer.isBuffer(x)) return x;
+  if (x instanceof Uint8Array) return Buffer.from(x);
+  throw new DnssecError("dnssec/bad-bytes", "dnssec: " + what + " must be a Buffer");
+}
+
+// Canonical wire form of a domain name (RFC 4034 §6.2): each label
+// length-prefixed, ASCII lowercased, terminated by the root label.
+function _canonicalName(name) {
+  if (typeof name !== "string") throw new DnssecError("dnssec/bad-name", "dnssec: name must be a string");
+  var n = name.replace(/\.$/, "");
+  if (n === "") return Buffer.from([0]);
+  var labels = n.split(".");
+  var parts = [];
+  for (var i = 0; i < labels.length; i++) {
+    var lab = Buffer.from(labels[i].toLowerCase(), "ascii");
+    if (lab.length === 0 || lab.length > 63) {                                          // allow:raw-byte-literal — DNS label length cap (RFC 1035)
+      throw new DnssecError("dnssec/bad-name", "dnssec: invalid label in '" + name + "'");
+    }
+    parts.push(Buffer.from([lab.length]), lab);
+  }
+  parts.push(Buffer.from([0]));
+  return Buffer.concat(parts);
+}
+
+function _u16(n) { return Buffer.from([(n >> 8) & 0xff, n & 0xff]); }                    // allow:raw-byte-literal — 16-bit big-endian split
+function _u32(n) {
+  var b = Buffer.alloc(4);
+  b.writeUInt32BE(n >>> 0, 0);
+  return b;
+}
+function _typeNumber(type) {
+  if (typeof type === "number") return type;
+  var t = TYPE_NUM[String(type).toUpperCase()];
+  if (t === undefined) throw new DnssecError("dnssec/unknown-type", "dnssec: unknown RR type '" + type + "'");
+  return t;
+}
+
+// DNSKEY public-key RDATA → JWK (kty/crv allowlisted; RFC 3110 RSA,
+// RFC 6605 ECDSA, RFC 8080 Ed25519). publicKey is the key bytes after
+// the DNSKEY flags/protocol/algorithm fields.
+function _dnskeyToKey(algId, publicKey) {
+  var alg = ALGS[algId];
+  if (!alg) throw new DnssecError("dnssec/unsupported-alg", "dnssec: unsupported DNSKEY algorithm " + algId);
+  var pk = _bytes(publicKey, "dnskey publicKey");
+  if (alg.kind === "rsa") {
+    // RFC 3110: exponent length is 1 byte, or (if that byte is 0) the
+    // next 2 bytes; then exponent, then modulus.
+    var off = 0, explen = pk[0];
+    off = 1;
+    if (explen === 0) { explen = (pk[1] << 8) | pk[2]; off = 3; }                        // allow:raw-byte-literal — RFC 3110 3-byte exponent length
+    if (explen === 0 || off + explen >= pk.length) {
+      throw new DnssecError("dnssec/bad-key", "dnssec: malformed RSA DNSKEY public key");
+    }
+    var exponent = pk.slice(off, off + explen);
+    var modulus = pk.slice(off + explen);
+    return _jwkKey({ kty: "RSA", n: modulus.toString("base64url"), e: exponent.toString("base64url") });
+  }
+  if (alg.kind === "ec") {
+    if (pk.length !== alg.coord * 2) {
+      throw new DnssecError("dnssec/bad-key", "dnssec: " + alg.crv + " key must be " + (alg.coord * 2) + " bytes (x||y)");
+    }
+    return _jwkKey({ kty: "EC", crv: alg.crv, x: pk.slice(0, alg.coord).toString("base64url"), y: pk.slice(alg.coord).toString("base64url") });
+  }
+  // Ed25519
+  if (pk.length !== 32) throw new DnssecError("dnssec/bad-key", "dnssec: Ed25519 key must be 32 bytes");   // allow:raw-byte-literal — Ed25519 key size
+  return _jwkKey({ kty: "OKP", crv: "Ed25519", x: pk.toString("base64url") });
+}
+function _jwkKey(jwk) {
+  try { return nodeCrypto.createPublicKey({ key: jwk, format: "jwk" }); }
+  catch (e) { throw new DnssecError("dnssec/bad-key", "dnssec: could not import DNSKEY: " + ((e && e.message) || e)); }
+}
+
+/**
+ * @primitive b.network.dns.dnssec.keyTag
+ * @signature b.network.dns.dnssec.keyTag(dnskeyRdata)
+ * @since     0.12.48
+ * @status    stable
+ * @related   b.network.dns.dnssec.verifyDs, b.network.dns.dnssec.verifyRrset
+ *
+ * Compute the RFC 4034 Appendix B key tag of a DNSKEY from its full
+ * RDATA (flags || protocol || algorithm || public key) — the 16-bit
+ * identifier an RRSIG / DS references to select the signing key.
+ *
+ * @example
+ *   var tag = b.network.dns.dnssec.keyTag(dnskeyRdata);
+ */
+function keyTag(dnskeyRdata) {
+  var rd = _bytes(dnskeyRdata, "dnskeyRdata");
+  var acc = 0;
+  for (var i = 0; i < rd.length; i++) {
+    acc += (i & 1) ? rd[i] : (rd[i] << 8);                                               // allow:raw-byte-literal — RFC 4034 App B key-tag accumulation
+  }
+  acc += (acc >> 16) & 0xffff;                                                           // allow:raw-byte-literal — App B fold
+  return acc & 0xffff;                                                                   // allow:raw-byte-literal — App B 16-bit tag
+}
+
+/**
+ * @primitive b.network.dns.dnssec.verifyDs
+ * @signature b.network.dns.dnssec.verifyDs(opts)
+ * @since     0.12.48
+ * @status    stable
+ * @related   b.network.dns.dnssec.verifyRrset
+ *
+ * Verify a DS (Delegation Signer) record against a child DNSKEY — the
+ * link that lets a parent zone vouch for a child's key. The DS digest
+ * (SHA-256 / SHA-384) is recomputed over the owner name plus the DNSKEY
+ * RDATA and compared to the DS, with the key tag and algorithm checked.
+ *
+ * @opts
+ *   {
+ *     ownerName:    string,   // the child zone name (the DNSKEY owner)
+ *     dnskeyRdata:  Buffer,   // full DNSKEY RDATA (flags||protocol||alg||publicKey)
+ *     ds: { keyTag, algorithm, digestType, digest: Buffer },  // the parent DS
+ *   }
+ *
+ * @example
+ *   b.network.dns.dnssec.verifyDs({ ownerName: "example.com", dnskeyRdata: ksk, ds: parentDs });
+ */
+function verifyDs(opts) {
+  validateOpts.requireObject(opts, "dnssec.verifyDs", DnssecError);
+  validateOpts(opts, ["ownerName", "dnskeyRdata", "ds"], "dnssec.verifyDs");
+  var ds = opts.ds;
+  if (!ds || typeof ds !== "object") throw new DnssecError("dnssec/bad-ds", "dnssec.verifyDs: opts.ds is required");
+  var hashName = DS_DIGESTS[ds.digestType];
+  if (!hashName) throw new DnssecError("dnssec/unsupported-digest", "dnssec.verifyDs: unsupported DS digest type " + ds.digestType);
+  var rd = _bytes(opts.dnskeyRdata, "dnskeyRdata");
+  if (keyTag(rd) !== ds.keyTag) {
+    throw new DnssecError("dnssec/keytag-mismatch", "dnssec.verifyDs: DNSKEY key tag does not match the DS");
+  }
+  var digestInput = Buffer.concat([_canonicalName(opts.ownerName), rd]);
+  var expected = nodeCrypto.createHash(hashName).update(digestInput).digest();
+  var actual = _bytes(ds.digest, "ds.digest");
+  if (!bCrypto.timingSafeEqual(expected, actual)) {
+    throw new DnssecError("dnssec/ds-mismatch", "dnssec.verifyDs: DS digest does not match the DNSKEY");
+  }
+  return { ok: true, keyTag: ds.keyTag, digestType: ds.digestType };
+}
+
+/**
+ * @primitive b.network.dns.dnssec.verifyRrset
+ * @signature b.network.dns.dnssec.verifyRrset(opts)
+ * @since     0.12.48
+ * @status    stable
+ * @compliance soc2
+ * @related   b.network.dns.dnssec.verifyDs, b.network.dns.resolver.create
+ *
+ * Verify an RRSIG over an RRset against a DNSKEY (RFC 4035 §5.3). The
+ * signed data is reconstructed in canonical form — the RRSIG RDATA
+ * without the signature, then the RRset's records ordered by canonical
+ * RDATA with the RRSIG Original TTL — and the signature is verified with
+ * the DNSKEY (RSA/SHA-256, ECDSA P-256/384, Ed25519). The signature's
+ * inception / expiration window is enforced against <code>opts.at</code>.
+ * RR types carrying embedded domain names are refused
+ * (<code>dnssec/uncanonicalizable-type</code>) rather than mis-validated.
+ *
+ * @opts
+ *   {
+ *     name:    string,    // owner name of the RRset
+ *     type:    string|number, // RR type (e.g. "DNSKEY", "A")
+ *     class?:  number,    // default 1 (IN)
+ *     rdatas:  Buffer[],  // each record's wire-format RDATA
+ *     rrsig: {            // the RRSIG covering the RRset
+ *       algorithm, labels, originalTtl, expiration, inception, keyTag,
+ *       signerName: string, signature: Buffer,
+ *     },
+ *     dnskey: { algorithm, publicKey: Buffer },  // the signing DNSKEY (publicKey = bytes after flags/proto/alg)
+ *     at?:     Date,      // validity instant (default now); must be a valid Date
+ *   }
+ *
+ * @example
+ *   b.network.dns.dnssec.verifyRrset({ name: "example.com", type: "DNSKEY", rdatas: keys, rrsig: sig, dnskey: ksk });
+ */
+function verifyRrset(opts) {
+  validateOpts.requireObject(opts, "dnssec.verifyRrset", DnssecError);
+  validateOpts(opts, ["name", "type", "class", "rdatas", "rrsig", "dnskey", "at"], "dnssec.verifyRrset");
+  var rrsig = opts.rrsig;
+  var dnskey = opts.dnskey;
+  if (!rrsig || typeof rrsig !== "object") throw new DnssecError("dnssec/bad-rrsig", "dnssec.verifyRrset: opts.rrsig is required");
+  if (!dnskey || typeof dnskey !== "object") throw new DnssecError("dnssec/bad-key", "dnssec.verifyRrset: opts.dnskey is required");
+  if (!Array.isArray(opts.rdatas) || opts.rdatas.length === 0) {
+    throw new DnssecError("dnssec/empty-rrset", "dnssec.verifyRrset: opts.rdatas must be a non-empty array");
+  }
+  var alg = ALGS[rrsig.algorithm];
+  if (!alg) throw new DnssecError("dnssec/unsupported-alg", "dnssec.verifyRrset: unsupported algorithm " + rrsig.algorithm);
+  if (dnskey.algorithm !== rrsig.algorithm) {
+    throw new DnssecError("dnssec/alg-mismatch", "dnssec.verifyRrset: DNSKEY algorithm does not match the RRSIG");
+  }
+
+  var typeNum = _typeNumber(opts.type);
+  if (NAME_FREE_TYPE_NUMS.indexOf(typeNum) === -1) {
+    throw new DnssecError("dnssec/uncanonicalizable-type",
+      "dnssec.verifyRrset: RR type " + typeNum + " carries embedded names; RDATA-name canonicalisation is not supported (refused, not mis-validated)");
+  }
+
+  // Validity window (fail closed on a bad opts.at).
+  var atMs;
+  if (opts.at !== undefined && opts.at !== null) {
+    if (!(opts.at instanceof Date) || !isFinite(opts.at.getTime())) {
+      throw new DnssecError("dnssec/bad-at", "dnssec.verifyRrset: opts.at must be a valid Date");
+    }
+    atMs = opts.at.getTime();
+  } else {
+    atMs = Date.now();
+  }
+  var nowSec = Math.floor(atMs / 1000);                       // allow:raw-time-literal — ms→NumericDate seconds (RRSIG inception/expiration are seconds since epoch, RFC 4034 §3.1.5)
+  if (nowSec < (rrsig.inception >>> 0)) throw new DnssecError("dnssec/not-yet-valid", "dnssec.verifyRrset: RRSIG inception is in the future");
+  if (nowSec > (rrsig.expiration >>> 0)) throw new DnssecError("dnssec/expired", "dnssec.verifyRrset: RRSIG has expired");
+
+  var klass = typeof opts.class === "number" ? opts.class : 1;
+  var ownerWire = _canonicalName(opts.name);
+  var ttl = _u32(rrsig.originalTtl);
+
+  // Canonical RRset (RFC 4034 §6.3): order records by canonical RDATA.
+  var rdatas = opts.rdatas.map(function (r, i) { return _bytes(r, "rdatas[" + i + "]"); });
+  var sorted = rdatas.slice().sort(Buffer.compare);
+  var rrParts = [];
+  for (var i = 0; i < sorted.length; i++) {
+    rrParts.push(ownerWire, _u16(typeNum), _u16(klass), ttl, _u16(sorted[i].length), sorted[i]);
+  }
+
+  // RRSIG RDATA without the signature (RFC 4034 §3.1.8.1).
+  var rrsigPrefix = Buffer.concat([
+    _u16(typeNum), Buffer.from([rrsig.algorithm & 0xff, rrsig.labels & 0xff]),           // allow:raw-byte-literal — single-octet alg + labels fields
+    _u32(rrsig.originalTtl), _u32(rrsig.expiration), _u32(rrsig.inception),
+    _u16(rrsig.keyTag), _canonicalName(rrsig.signerName),
+  ]);
+  var signedData = Buffer.concat([rrsigPrefix].concat(rrParts));
+
+  var key = _dnskeyToKey(dnskey.algorithm, dnskey.publicKey);
+  var signature = _bytes(rrsig.signature, "rrsig.signature");
+  var ok;
+  try {
+    if (alg.kind === "okp") {
+      ok = nodeCrypto.verify(null, signedData, key, signature);
+    } else if (alg.kind === "ec") {
+      ok = nodeCrypto.verify(alg.hash, signedData, { key: key, dsaEncoding: "ieee-p1363" }, signature);
+    } else {
+      ok = nodeCrypto.verify(alg.hash, signedData, key, signature);
+    }
+  } catch (e) {
+    throw new DnssecError("dnssec/verify-threw", "dnssec.verifyRrset: signature verification threw: " + ((e && e.message) || e));
+  }
+  if (!ok) throw new DnssecError("dnssec/bad-signature", "dnssec.verifyRrset: RRSIG signature did not verify");
+  return { ok: true, algorithm: alg.name, keyTag: rrsig.keyTag, signerName: rrsig.signerName };
+}
+
+module.exports = {
+  verifyRrset: verifyRrset,
+  verifyDs:    verifyDs,
+  keyTag:      keyTag,
+  ALGORITHMS:  ALGS,
+  DnssecError: DnssecError,
+};

package/lib/network.js

@@ -35,6 +35,7 @@ var ntpCheck = require("./ntp-check");
 var nts      = require("./network-nts");
 var networkDns = require("./network-dns");
 networkDns.resolver = require("./network-dns-resolver");
+networkDns.dnssec = require("./network-dnssec");
 var networkProxy = require("./network-proxy");
 var networkTls = require("./network-tls");
 var heartbeat = require("./network-heartbeat");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.46",
+  "version": "0.12.48",
   "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:059bfa5a-606e-407b-a262-1ee1d810affc",
+  "serialNumber": "urn:uuid:230d6fb7-7a35-40e7-990b-d931f5a43248",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-25T10:03:10.245Z",
+    "timestamp": "2026-05-25T12:11:44.437Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.46",
+      "bom-ref": "@blamejs/core@0.12.48",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.46",
+      "version": "0.12.48",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.46",
+      "purl": "pkg:npm/%40blamejs/core@0.12.48",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.46",
+      "ref": "@blamejs/core@0.12.48",
       "dependsOn": []
     }
   ]