@blamejs/core 0.12.50 → 0.12.51

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- 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.
 
 - 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.

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, 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
+- **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; DANE / TLSA certificate matching (RFC 6698/7671 — `b.network.dns.dane.matchCertificate`) to pin a service's key through DNSSEC instead of a public CA; 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-dane.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * @module b.network.dns.dane
+ * @nav    Network
+ * @title  DANE / TLSA
+ *
+ * @intro
+ *   DNS-Based Authentication of Named Entities (RFC 6698, updated by
+ *   RFC 7671) — match a server certificate against a TLSA record so the
+ *   DNS, not a public CA, vouches for which key a service uses. This is
+ *   the payoff of DNSSEC: verify the TLSA RRset with
+ *   <code>b.network.dns.dnssec</code> first, then
+ *   <code>matchCertificate</code> checks the certificate against it.
+ *
+ *   A TLSA record carries a certificate usage (PKIX-TA 0, PKIX-EE 1,
+ *   DANE-TA 2, DANE-EE 3 — RFC 7218 mnemonics), a selector (full
+ *   certificate 0, or subjectPublicKeyInfo 1), and a matching type
+ *   (exact 0, SHA-256 1, SHA-512 2). The selected certificate data is
+ *   hashed per the matching type and compared, in constant time, to the
+ *   record's association data. For DANE-EE(3) a match means the
+ *   certificate IS the pinned end-entity key — no public-CA path is
+ *   needed (the common SMTP-DANE case, RFC 7672). For the PKIX usages a
+ *   match is necessary but the caller still performs PKIX validation.
+ *
+ * @card
+ *   DANE / TLSA certificate matching (RFC 6698 / 7671). Pin a service's
+ *   key through DNSSEC instead of a public CA — verify the TLSA RRset,
+ *   then match the certificate (DANE-EE / DANE-TA / PKIX usages,
+ *   full-cert or SPKI selector, SHA-256 / SHA-512).
+ */
+
+var nodeCrypto = require("node:crypto");
+var bCrypto = require("./crypto");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var DaneError = defineClass("DaneError", { alwaysPermanent: true });
+
+// RFC 6698 §2.1 + RFC 7218 mnemonics.
+var USAGES = { 0: "PKIX-TA", 1: "PKIX-EE", 2: "DANE-TA", 3: "DANE-EE" };
+var SELECTORS = { 0: "Cert", 1: "SPKI" };
+// Matching types: 0 = exact match on the selected data, 1 = SHA-256,
+// 2 = SHA-512. SHA-1 is not registered for TLSA, so anything else is
+// refused rather than guessed.
+var MATCHING = { 0: null, 1: "sha256", 2: "sha512" };
+
+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, "hex");
+  throw new DaneError("dane/bad-bytes", "dane: " + what + " must be a Buffer / Uint8Array / hex string");
+}
+
+function _selectedData(x509, selector) {
+  if (selector === 0) return Buffer.from(x509.raw);                                   // full certificate DER
+  if (selector === 1) return x509.publicKey.export({ format: "der", type: "spki" });  // subjectPublicKeyInfo DER
+  throw new DaneError("dane/unsupported-selector", "dane: unsupported TLSA selector " + selector + " (0 = full cert, 1 = SPKI)");
+}
+
+function _associationOf(selected, matchingType) {
+  if (matchingType === 0) return selected;
+  var hashName = MATCHING[matchingType];
+  if (!hashName) throw new DaneError("dane/unsupported-matching", "dane: unsupported TLSA matching type " + matchingType + " (0 = exact, 1 = SHA-256, 2 = SHA-512)");
+  return nodeCrypto.createHash(hashName).update(selected).digest();
+}
+
+function _parseCert(der, what) {
+  try { return new nodeCrypto.X509Certificate(_bytes(der, what)); }
+  catch (e) { throw new DaneError("dane/bad-certificate", "dane: could not parse " + what + ": " + ((e && e.message) || e)); }
+}
+
+// Validate a TLSA enum field: it must be an actual integer that is an
+// OWN key of the lookup table. Rejecting non-numbers stops a string like
+// "1" (which coerces on key lookup but then fails the strict-=== usage
+// checks below), and the own-property test stops prototype keys such as
+// "__proto__" that `in` / `[x] !== undefined` would wrongly accept.
+function _enumField(v, table, code, label, i) {
+  if (typeof v !== "number" || !Number.isInteger(v) || !Object.prototype.hasOwnProperty.call(table, v)) {
+    throw new DaneError(code, "dane: tlsa[" + i + "] " + label + " must be a numeric " + Object.keys(table).join(" / ") + " (got " + JSON.stringify(v) + ")");
+  }
+}
+function _normaliseTlsa(rec, i) {
+  if (!rec || typeof rec !== "object") throw new DaneError("dane/bad-tlsa", "dane: tlsa[" + i + "] must be an object");
+  _enumField(rec.usage, USAGES, "dane/unsupported-usage", "certificate usage", i);
+  _enumField(rec.selector, SELECTORS, "dane/unsupported-selector", "selector", i);
+  _enumField(rec.matchingType, MATCHING, "dane/unsupported-matching", "matching type", i);
+  return { usage: rec.usage, selector: rec.selector, matchingType: rec.matchingType, data: _bytes(rec.data, "tlsa[" + i + "].data") };
+}
+
+/**
+ * @primitive b.network.dns.dane.matchCertificate
+ * @signature b.network.dns.dane.matchCertificate(opts)
+ * @since     0.12.51
+ * @status    stable
+ * @compliance soc2
+ * @related   b.network.dns.dnssec.verifyChain, b.network.dns.dnssec.verifyRrset
+ *
+ * Match a server certificate against a set of (DNSSEC-verified) TLSA
+ * records (RFC 6698 / 7671). For each record the selected data — the
+ * full certificate DER (selector 0) or its subjectPublicKeyInfo
+ * (selector 1) — is hashed per the matching type (exact / SHA-256 /
+ * SHA-512) and compared, constant-time, to the record's association
+ * data. End-entity usages (PKIX-EE 1, DANE-EE 3) are matched against the
+ * leaf certificate; trust-anchor usages (PKIX-TA 0, DANE-TA 2) are
+ * matched against the leaf and any supplied <code>chain</code>.
+ *
+ * Returns the matching record plus what the caller must still do: a
+ * DANE-EE match is self-sufficient (the TLSA pins the key); a DANE-TA
+ * match still needs chain-to-anchor verification; PKIX usages still need
+ * full PKIX validation. Throws <code>dane/no-match</code> if nothing
+ * matches. Verify the TLSA RRset with <code>b.network.dns.dnssec</code>
+ * before trusting the records — an unauthenticated TLSA proves nothing.
+ *
+ * @opts
+ *   {
+ *     tlsa: [ { usage, selector, matchingType, data: Buffer|hex } ],  // the TLSA RRset
+ *     certificate: Buffer,   // leaf certificate (DER)
+ *     chain?:      Buffer[],  // intermediate / CA certs (DER), for TA usages
+ *   }
+ *
+ * @example
+ *   var r = b.network.dns.dane.matchCertificate({ tlsa: records, certificate: leafDer });
+ *   // → { ok: true, matched: { usage: 3, selector: 1, matchingType: 1 }, daneAuthenticated: true, pkixRequired: false }
+ */
+function matchCertificate(opts) {
+  validateOpts.requireObject(opts, "dane.matchCertificate", DaneError);
+  validateOpts(opts, ["tlsa", "certificate", "chain"], "dane.matchCertificate");
+  if (!Array.isArray(opts.tlsa) || opts.tlsa.length === 0) throw new DaneError("dane/bad-arg", "dane.matchCertificate: opts.tlsa must be a non-empty array");
+  var records = opts.tlsa.map(_normaliseTlsa);
+  var leaf = _parseCert(opts.certificate, "certificate");
+  var chain = Array.isArray(opts.chain) ? opts.chain.map(function (c, i) { return _parseCert(c, "chain[" + i + "]"); }) : [];
+
+  for (var i = 0; i < records.length; i++) {
+    var rec = records[i];
+    var eeUsage = rec.usage === 1 || rec.usage === 3;       // PKIX-EE / DANE-EE → leaf only
+    var certs = eeUsage ? [leaf] : [leaf].concat(chain);    // TA usages may match a chain cert
+    for (var c = 0; c < certs.length; c++) {
+      var assoc = _associationOf(_selectedData(certs[c], rec.selector), rec.matchingType);
+      if (bCrypto.timingSafeEqual(assoc, rec.data)) {
+        return {
+          ok: true,
+          matched: { usage: rec.usage, usageName: USAGES[rec.usage], selector: rec.selector, matchingType: rec.matchingType },
+          matchedCertIndex: c,                              // 0 = leaf, >0 = chain[c-1]
+          daneAuthenticated: rec.usage === 3,               // DANE-EE: TLSA pins the key, no CA path needed
+          trustAnchorMatch: rec.usage === 0 || rec.usage === 2,
+          pkixRequired: rec.usage === 0 || rec.usage === 1,
+        };
+      }
+    }
+  }
+  throw new DaneError("dane/no-match", "dane.matchCertificate: no TLSA record matched the certificate" + (chain.length ? " or chain" : ""));
+}
+
+module.exports = {
+  matchCertificate: matchCertificate,
+  USAGES:           USAGES,
+  SELECTORS:        SELECTORS,
+  DaneError:        DaneError,
+};

package/lib/network.js

@@ -36,6 +36,7 @@ var nts      = require("./network-nts");
 var networkDns = require("./network-dns");
 networkDns.resolver = require("./network-dns-resolver");
 networkDns.dnssec = require("./network-dnssec");
+networkDns.dane = require("./network-dane");
 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.50",
+  "version": "0.12.51",
   "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:73355867-afbb-4417-a3e0-56f83b718707",
+  "serialNumber": "urn:uuid:5b23f9db-6c61-4ca7-b708-bb0ac954fc34",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-25T14:43:55.314Z",
+    "timestamp": "2026-05-25T15:45:58.868Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.50",
+      "bom-ref": "@blamejs/core@0.12.51",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.50",
+      "version": "0.12.51",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.50",
+      "purl": "pkg:npm/%40blamejs/core@0.12.51",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.50",
+      "ref": "@blamejs/core@0.12.51",
       "dependsOn": []
     }
   ]