@blamejs/core 0.12.49 → 0.12.50

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- 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.
+
 - v0.12.49 (2026-05-25) — **`b.network.dns.dnssec.verifyDenial` — NSEC / NSEC3 denial-of-existence.** Prove a DNS name does not exist, or has no records of a given type, from the signed NSEC (RFC 4034 §4) or NSEC3 (RFC 5155) records a server returns. This is the other half of local DNSSEC verification: verifyRrset proves a positive answer, verifyDenial proves a negative — so a resolver client can confirm an NXDOMAIN / NODATA itself instead of trusting the upstream resolver. NSEC3 proofs run the closest-encloser / next-closer / covering-range logic over iterated-SHA-1 hashes, with the iteration count capped (default 500) to bound the work an attacker can force, and an Opt-Out NXDOMAIN refused unless explicitly accepted (opt-out only proves 'no signed records', not non-existence). The companion b.network.dns.dnssec.nsec3Hash computes the RFC 5155 §5 hash directly. NSEC verifyRrset support is also enabled: per RFC 6840 §5.1 the NSEC Next Domain Name is not downcased, so its RDATA is verbatim-canonical. **Added:** *`b.network.dns.dnssec.verifyDenial(opts)`* — Proves NXDOMAIN or NODATA from already-verified NSEC / NSEC3 records (supply one of `opts.nsec3` or `opts.nsec`). Like `verifyDs`, it checks the denial RELATION — closest-encloser matching, covering ranges, and type-bitmap absence — not the record signatures, which the caller verifies with `verifyRrset` first. NSEC3 supports name-error proofs (matching closest encloser + covered next-closer + covered wildcard), NODATA (matching record with the type and CNAME absent from the bitmap), Opt-Out DS NODATA, and wildcard NODATA. The iterated-SHA-1 count is capped by `opts.maxIterations` (default 500); an NXDOMAIN proof that depends on an Opt-Out NSEC3 is refused unless `opts.allowOptOut` is set. NSEC supports covering-name NXDOMAIN (with the source-of-synthesis wildcard) and matching-name NODATA. Verified end-to-end against a live iana.org NXDOMAIN proof. · *`b.network.dns.dnssec.nsec3Hash(name, opts)`* — Computes the RFC 5155 §5 NSEC3 hash of a name — iterated SHA-1 over the canonical (lowercased, root-terminated) wire form with the zone salt. The base32hex encoding of the result is the NSEC3 owner label. SHA-1 is the only hash IANA registers for NSEC3, so this is a wire-protocol constant rather than a cryptographic default. Useful for checking an owner label or analyzing a zone's hashing parameters. **Changed:** *`verifyRrset` now accepts NSEC and NSEC3 RRsets* — NSEC (type 47) and NSEC3 (type 50) are no longer refused as uncanonicalizable: NSEC3's next-owner is a hash, and per RFC 6840 §5.1 the NSEC Next Domain Name field is not downcased for DNSSEC canonical form, so both RDATAs are verbatim-canonical. This lets a caller verify the signatures on the records that `verifyDenial` then reasons over.
 
 - 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.

package/README.md

@@ -120,7 +120,7 @@ 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; 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, plus `verifyDenial` for NSEC / NSEC3 (RFC 5155) NXDOMAIN / NODATA proofs with iteration caps + Opt-Out handling) so a resolver client can verify both positive and negative answers 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
+- **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, plus `verifyDenial` for NSEC / NSEC3 (RFC 5155) NXDOMAIN / NODATA proofs with iteration caps + Opt-Out handling, plus `verifyChain` to validate a full root→TLD→zone delegation chain against the pinned IANA root anchors) so a resolver client can verify both positive and negative answers 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
 

package/lib/network-dnssec.js

@@ -721,12 +721,163 @@ function _commonSuffixLen(a, b) {
   return n;
 }
 
+// ---------------------------------------------------------------------------
+// Chain validation (RFC 4035 §5) — walk a delegation chain root → … → zone,
+// anchoring at a pinned trust anchor.
+// ---------------------------------------------------------------------------
+
+// IANA root zone trust anchors (DS / SHA-256). KSK-2017 (tag 20326) and
+// KSK-2024 (tag 38696), published at data.iana.org/root-anchors. An
+// operator pins their own via opts.trustAnchors.
+var DEFAULT_ROOT_ANCHORS = [
+  { keyTag: 20326, algorithm: 8, digestType: 2, digest: Buffer.from("E06D44B80B8F1D39A95C0B0D7C65D08458E880409BBC683457104237C7F8EC8D", "hex") },   // allow:raw-byte-literal — IANA root KSK-2017 DS
+  { keyTag: 38696, algorithm: 8, digestType: 2, digest: Buffer.from("683D2D0ACB8C9B712A1948B27F741219298D0A450D612C483AF444A4C0FB2B16", "hex") },   // allow:raw-byte-literal — IANA root KSK-2024 DS
+];
+
+function _dnskeyParts(rdata, what) {
+  var rd = _bytes(rdata, what || "dnskey rdata");
+  if (rd.length < 4) throw new DnssecError("dnssec/bad-key", "dnssec: DNSKEY RDATA too short");   // allow:raw-byte-literal — DNSKEY fixed header octets
+  return { flags: rd.readUInt16BE(0), algorithm: rd[3], publicKey: rd.slice(4) };
+}
+function _parseDsRdata(rd) {
+  if (rd.length < 5) throw new DnssecError("dnssec/bad-ds", "dnssec: DS RDATA too short");   // allow:raw-byte-literal — DS fixed header octets
+  return { keyTag: rd.readUInt16BE(0), algorithm: rd[2], digestType: rd[3], digest: rd.slice(4) };
+}
+// ALL DNSKEYs whose key tag matches — 16-bit key tags collide (RFC 4034
+// App B), so a verifier must try every candidate, not just the first.
+function _keysByTag(dnskeys, tag) {
+  var out = [];
+  for (var i = 0; i < dnskeys.length; i++) if (keyTag(dnskeys[i]) === tag) out.push(dnskeys[i]);
+  return out;
+}
+
+// Verify an RRset against EVERY DNSKEY whose tag matches the RRSIG,
+// returning the key that validated. A wrong colliding key yields
+// `dnssec/bad-signature` — that is not terminal, the next candidate is
+// tried; any other error (expired, alg) is terminal. RFC 4035 §5.3.1.
+function _verifyRrsetWithAnyKey(rrsetBase, rrsig, candidates, noKeyCode, noKeyMsg) {
+  if (candidates.length === 0) throw new DnssecError(noKeyCode, noKeyMsg);
+  var lastErr = null;
+  for (var i = 0; i < candidates.length; i++) {
+    var kp = _dnskeyParts(candidates[i]);
+    if (kp.algorithm !== rrsig.algorithm) { lastErr = new DnssecError("dnssec/alg-mismatch", "dnssec.verifyChain: candidate key algorithm does not match the RRSIG"); continue; }
+    try {
+      verifyRrset(Object.assign({}, rrsetBase, { rrsig: rrsig, dnskey: { algorithm: kp.algorithm, publicKey: kp.publicKey } }));
+      return candidates[i];
+    } catch (e) {
+      if (e && e.code === "dnssec/bad-signature") { lastErr = e; continue; }   // colliding non-signing key — try the next
+      throw e;
+    }
+  }
+  throw lastErr;
+}
+
+/**
+ * @primitive b.network.dns.dnssec.verifyChain
+ * @signature b.network.dns.dnssec.verifyChain(opts)
+ * @since     0.12.50
+ * @status    stable
+ * @compliance soc2
+ * @related   b.network.dns.dnssec.verifyRrset, b.network.dns.dnssec.verifyDs
+ *
+ * Validate a DNSSEC delegation chain from the root down to a zone, against
+ * a pinned trust anchor (RFC 4035 §5). For each link, the zone's DNSKEY
+ * RRset must be self-signed by one of its keys; that signing key must be
+ * vouched for either by a pinned anchor (root) or by a DS record served by
+ * the already-trusted parent. The DS RRset itself is verified against the
+ * parent's keys, so trust flows root → TLD → zone with no gap. The default
+ * anchors are the IANA root KSKs; override with <code>opts.trustAnchors</code>.
+ *
+ * This composes <code>verifyRrset</code> + <code>verifyDs</code> + the key
+ * tag; it returns the leaf zone's trusted DNSKEY set, which the caller then
+ * passes to <code>verifyRrset</code> / <code>verifyDenial</code> for the
+ * actual answer.
+ *
+ * @opts
+ *   {
+ *     links: [ {                        // ordered root-first
+ *       zone:        string,
+ *       dnskeys:     Buffer[],          // the zone's DNSKEY RRset RDATAs
+ *       dnskeyRrsig: { algorithm, labels, originalTtl, expiration, inception, keyTag, signerName, signature },
+ *       dsRdatas?:   Buffer[],          // DS RRset for this zone (served by parent; omit for root)
+ *       dsRrsig?:    { ... },           // RRSIG over the DS RRset (signed by parent; omit for root)
+ *     } ],
+ *     trustAnchors?: [ { keyTag, algorithm, digestType, digest: Buffer } ],  // default IANA root
+ *     at?:           Date,             // validity instant (default now)
+ *   }
+ *
+ * @example
+ *   var trusted = b.network.dns.dnssec.verifyChain({ links: [rootLink, orgLink] });
+ *   // → { ok: true, zone: "org.", keys: [ ...trusted org DNSKEY rdatas ] }
+ */
+function verifyChain(opts) {
+  validateOpts.requireObject(opts, "dnssec.verifyChain", DnssecError);
+  validateOpts(opts, ["links", "trustAnchors", "at"], "dnssec.verifyChain");
+  if (!Array.isArray(opts.links) || opts.links.length === 0) throw new DnssecError("dnssec/bad-arg", "dnssec.verifyChain: opts.links must be a non-empty array");
+  var anchors = opts.trustAnchors !== undefined ? opts.trustAnchors : DEFAULT_ROOT_ANCHORS;
+  if (!Array.isArray(anchors) || anchors.length === 0) throw new DnssecError("dnssec/bad-arg", "dnssec.verifyChain: opts.trustAnchors must be a non-empty array");
+
+  var trustedKeys = null, path = [];
+  for (var i = 0; i < opts.links.length; i++) {
+    var link = opts.links[i];
+    if (!link || typeof link.zone !== "string" || link.zone === "") throw new DnssecError("dnssec/bad-link", "dnssec.verifyChain: links[" + i + "].zone is required");
+    if (!Array.isArray(link.dnskeys) || link.dnskeys.length === 0) throw new DnssecError("dnssec/bad-link", "dnssec.verifyChain: links[" + i + "].dnskeys must be a non-empty array");
+    if (!link.dnskeyRrsig || typeof link.dnskeyRrsig !== "object") throw new DnssecError("dnssec/bad-link", "dnssec.verifyChain: links[" + i + "].dnskeyRrsig is required");
+
+    // 1. The DNSKEY RRset is self-signed by one of its own keys (trying
+    //    every key whose tag matches, since tags collide).
+    var signer = _verifyRrsetWithAnyKey(
+      { name: link.zone, type: "DNSKEY", rdatas: link.dnskeys, at: opts.at },
+      link.dnskeyRrsig,
+      _keysByTag(link.dnskeys, link.dnskeyRrsig.keyTag),
+      "dnssec/chain-no-signing-key", "dnssec.verifyChain: no DNSKEY in '" + link.zone + "' verifies the DNSKEY RRSIG"
+    );
+
+    // 2. Establish trust in the signing key.
+    var signerTag = keyTag(signer);
+    if (i === 0) {
+      // Root: the signing key must match a pinned anchor's DS digest.
+      var matched = false;
+      for (var a = 0; a < anchors.length; a++) {
+        if (anchors[a].keyTag !== signerTag) continue;
+        try { verifyDs({ ownerName: link.zone, dnskeyRdata: signer, ds: anchors[a] }); matched = true; break; } catch (_e) { /* try the next anchor */ }
+      }
+      if (!matched) throw new DnssecError("dnssec/chain-anchor-mismatch", "dnssec.verifyChain: root DNSKEY does not match any pinned trust anchor");
+    } else {
+      // Delegation: the parent (already trusted) signed a DS RRset for this
+      // zone, and the signing KSK matches one of those DS records.
+      if (!Array.isArray(link.dsRdatas) || link.dsRdatas.length === 0 || !link.dsRrsig || typeof link.dsRrsig !== "object") {
+        throw new DnssecError("dnssec/bad-link", "dnssec.verifyChain: links[" + i + "] needs dsRdatas + dsRrsig (DS served by the parent)");
+      }
+      _verifyRrsetWithAnyKey(
+        { name: link.zone, type: "DS", rdatas: link.dsRdatas, at: opts.at },
+        link.dsRrsig,
+        _keysByTag(trustedKeys, link.dsRrsig.keyTag),
+        "dnssec/chain-no-parent-key", "dnssec.verifyChain: no trusted parent key verifies the DS RRSIG for '" + link.zone + "'"
+      );
+      var dsMatched = false;
+      for (var d = 0; d < link.dsRdatas.length; d++) {
+        var dsObj = _parseDsRdata(_bytes(link.dsRdatas[d], "dsRdatas[" + d + "]"));
+        if (dsObj.keyTag !== signerTag) continue;
+        try { verifyDs({ ownerName: link.zone, dnskeyRdata: signer, ds: dsObj }); dsMatched = true; break; } catch (_e) { /* try the next DS */ }
+      }
+      if (!dsMatched) throw new DnssecError("dnssec/chain-ds-mismatch", "dnssec.verifyChain: the signing KSK of '" + link.zone + "' matches no parent-signed DS");
+    }
+
+    trustedKeys = link.dnskeys;
+    path.push(link.zone);
+  }
+  return { ok: true, zone: opts.links[opts.links.length - 1].zone, keys: trustedKeys, path: path };
+}
+
 module.exports = {
-  verifyRrset:  verifyRrset,
-  verifyDs:     verifyDs,
-  verifyDenial: verifyDenial,
-  nsec3Hash:    nsec3Hash,
-  keyTag:       keyTag,
-  ALGORITHMS:   ALGS,
-  DnssecError:  DnssecError,
+  verifyRrset:        verifyRrset,
+  verifyDs:           verifyDs,
+  verifyDenial:       verifyDenial,
+  verifyChain:        verifyChain,
+  nsec3Hash:          nsec3Hash,
+  keyTag:             keyTag,
+  ALGORITHMS:         ALGS,
+  DEFAULT_ROOT_ANCHORS: DEFAULT_ROOT_ANCHORS,
+  DnssecError:        DnssecError,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.49",
+  "version": "0.12.50",
   "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:abe5140c-7ec0-4872-8094-0863d2e0a821",
+  "serialNumber": "urn:uuid:73355867-afbb-4417-a3e0-56f83b718707",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-25T13:20:22.849Z",
+    "timestamp": "2026-05-25T14:43:55.314Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.49",
+      "bom-ref": "@blamejs/core@0.12.50",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.49",
+      "version": "0.12.50",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.49",
+      "purl": "pkg:npm/%40blamejs/core@0.12.50",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.49",
+      "ref": "@blamejs/core@0.12.50",
       "dependsOn": []
     }
   ]