@blamejs/pki 0.1.26 → 0.1.28

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.1.28 — 2026-07-11
+
+Merkle transparency proof verification joins the toolkit as pki.merkle.
+
+### Added
+
+- pki.merkle.leafHash / nodeHash / emptyRootHash -- the RFC 6962 / RFC 9162 tree hashes: a leaf is SHA-256(0x00 || entry), an interior node is SHA-256(0x01 || left || right), the empty tree is SHA-256(""). The domain-separation prefixes are applied unconditionally.
+- pki.merkle.verifyInclusion({ leafIndex, treeSize, leafHash, proof, rootHash }) -- verify an RFC 6962 / RFC 9162 audit proof by folding the leaf up the audit path and constant-time-comparing the reconstructed root to a trusted root. Returns true only when the proof binds the leaf to the root.
+- pki.merkle.verifyConsistency({ oldSize, newSize, oldRoot, newRoot, proof }) -- verify an append-only consistency proof by reconstructing BOTH the old and the new root and constant-time-comparing each; the append-only guarantee lives in the old-root leg.
+- The error taxonomy gains MerkleError (merkle/*). A node-count ceiling (C.LIMITS.MERKLE_MAX_PROOF_NODES) rejects a pathologically long proof before any hashing; the precise per-proof guard is the geometry check in each verifier.
+- Fuzz target merkle-verify (both fold algorithms and the hash producers over adversarial coordinates, hashes, and proofs) joins the per-PR and nightly fuzz matrices with a seed corpus.
+
+## v0.1.27 — 2026-07-10
+
+A strict deterministic-CBOR codec joins the toolkit as pki.cbor.
+
+### Added
+
+- pki.cbor.decode -- the RFC 8949 core-deterministic CBOR decoder. It returns a node carrying the major type, the argument (a lossless BigInt), zero-copy content / bytes views (the raw ranges an external verifier hashes), and children (array elements, ordered map key/value pairs, or a tag's one inner item). Every non-canonical shape fails closed with a stable cbor/* code; maxBytes, maxDepth, maxItems, and a per-bignum byte cap bound the work before allocation (so a container declaring millions of tiny elements fails closed rather than exhausting memory); allowTrailing decodes the first item of a CBOR Sequence.
+- The read.* leaf readers over a decoded node: read.uint / read.nint / read.int (uniform BigInt), read.byteString (zero-copy Buffer), read.textString (strict UTF-8), read.array, read.map (ordered key/value node pairs), read.boolean / read.nullValue / read.undefinedValue, read.float (half / single / double), and the tagged forms read.biguint (RFC 8949 tag 2 unsigned bignum, minimality and byte cap enforced), read.time (RFC 8949 tag 1 epoch time, bounded to the valid Date range), and read.oid (RFC 9090 tag 111, decoded through the shared OID-content codec so a malformed body surfaces the existing oid/* codes).
+- The error taxonomy gains CborError (cbor/*). The decoder is profile-parameterized, so a future CTAP2 canonical profile is a data addition rather than a new code path.
+- Fuzz target cbor-det-parse (the decode head-well-formedness and minimal-argument checks, the map ordering / uniqueness verify, the shortest-float rule, the strict-UTF-8 gate, and the size / depth / bignum caps, in both whole-buffer and CBOR-Sequence modes) joins the per-PR and nightly fuzz matrices with a seed corpus.
+
+### Changed
+
+- pki.oid.paramsMustBeAbsent graduated from experimental to stable: its dotted-OID-to-boolean surface has been unchanged since 0.1.21 and is exercised end-to-end by the algorithm-identifier decoder every format shares.
+
 ## v0.1.26 — 2026-07-10
 
 Test-coverage measurement and the OpenSSF Best Practices badge.

package/README.md

@@ -199,6 +199,7 @@ is callable today; nothing below is a stub.
 | Namespace | What it does |
 |---|---|
 | `pki.asn1` | Strict, bounded DER codec — `decode` (zero-copy node tree), `encode`, `build.*` canonical-DER value builders, `read.*` typed readers, `TAGS`, OID-content encode/decode |
+| `pki.cbor` | Strict, bounded RFC 8949 deterministic CBOR codec — `decode` (zero-copy node tree) + `read.*` typed leaf readers, fail-closed on every non-canonical shape (indefinite length, non-minimal argument, unsorted / duplicate map keys, non-shortest float, trailing bytes) |
 | `pki.oid` | Two-way OID ↔ name registry — `name`, `byName`, `register`, `toArcs`/`fromArcs`, `toDER`/`fromDER`; seeded with RFC 5280 + NIST PQC arcs |
 | `pki.webcrypto` | A W3C WebCrypto (`SubtleCrypto`) engine over `node:crypto` — `sign`/`verify`/`encrypt`/`decrypt`/`deriveBits`/`digest`/`generateKey`/`importKey`/`exportKey` across RSA, ECDSA, ECDH, Ed25519/Ed448, AES, HMAC, HKDF, PBKDF2, SHA — **and** post-quantum ML-DSA-44/65/87 and SLH-DSA signatures, plus ML-KEM-512/768/1024 key generation (KEM encapsulation on the roadmap). Zero-dependency, OpenSSL-interoperable |
 | `pki.schema` | The schema family — `parse` detects which PKI format DER / PEM encodes and routes to the right parser, `all` enumerates the registered formats, and the engine + per-format members are grouped here |
@@ -221,6 +222,7 @@ is callable today; nothing below is a stub.
 | `pki.schema.engine` | The declarative ASN.1 structure-schema engine every format parser composes — `walk` / `encode` / `embeddedDer` plus the schema combinators |
 | `pki.path` | RFC 5280 §6 certification-path validation — `validate` runs the §6.1 state machine (signature chaining, validity windows, name chaining, basic constraints and path length, key usage, name constraints, the certificate-policy tree) over an ordered path and a trust anchor, returning a structured verdict with per-check reason codes; `crlChecker` supplies CRL-based revocation. Pure and re-entrant, fail-closed — `validate`, `crlChecker` |
 | `pki.ct` | Parse RFC 6962 Certificate Transparency SCT lists — `parseSctList` decodes the `SignedCertificateTimestampList` a certificate or OCSP response carries in the SCT extension (a TLS-presentation-language payload inside the §3.3 double DER wrap) into per-SCT log id, exact `timestamp` (BigInt), named signature algorithm, and raw signature; `reconstructSignedData` rebuilds the exact `digitally-signed` preimage for external verification. Structure decoded, crypto surfaced raw, bounded decode, fail-closed — `parseSctList`, `reconstructSignedData` |
+| `pki.merkle` | RFC 6962 / RFC 9162 Merkle-tree proof verification — `leafHash` / `nodeHash` / `emptyRootHash` build the domain-separated (0x00 leaf / 0x01 node) SHA-256 tree hashes; `verifyInclusion` folds an audit proof back to a root and `verifyConsistency` reconstructs both the old and new root (the append-only guarantee), each constant-time-compared to a trusted checkpoint root. Fail-closed on bad geometry, sync hashing, transport-free — `leafHash`, `nodeHash`, `emptyRootHash`, `verifyInclusion`, `verifyConsistency` |
 | `pki.C` / `pki.constants` | Version-stable constants — functional scale helpers (`C.TIME.*`, `C.BYTES.*`), codec `LIMITS`, `version` |
 | `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError` / `Pkcs8Error` / `CmsError` / `OcspError` / `TspError` / `AttrCertError` / `CrmfError` / `Pkcs12Error` / `CmpError` / `PathError` / `CtError` / `JoseError` / `AcmeError`, each carrying a stable `code` in `domain/reason` form |
 | `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>` |

package/index.js

@@ -30,11 +30,13 @@
 var constants = require("./lib/constants");
 var errors    = require("./lib/framework-error");
 var asn1      = require("./lib/asn1-der");
+var cbor      = require("./lib/cbor-det");
 var oid       = require("./lib/oid");
 var webcrypto = require("./lib/webcrypto");
 var schema    = require("./lib/schema-all");
 var path      = require("./lib/path-validate");
 var ct        = require("./lib/ct");
+var merkle    = require("./lib/merkle");
 var est        = require("./lib/est");
 var jose       = require("./lib/jose");
 var acme       = require("./lib/acme");
@@ -47,6 +49,12 @@ module.exports = {
   errors:    errors,
   // `asn1` is the strict DER codec (decode/encode/build/read/TAGS).
   asn1:      asn1,
+  // `cbor` is the strict, fail-closed RFC 8949 deterministic CBOR codec
+  // (decode + read.* leaf readers), sibling to `asn1`. It rejects every
+  // non-deterministic shape -- indefinite length, a non-minimal argument,
+  // unsorted / duplicate map keys, a non-shortest float, trailing bytes --
+  // before it walks a byte, and surfaces zero-copy bytes / content views.
+  cbor:      cbor,
   oid:       oid,
   // `schema` is the family: the L2 structure-schema engine (schema.engine) and
   // the per-format parsers (schema.x509, ...) with detect-and-route schema.parse.
@@ -58,6 +66,12 @@ module.exports = {
   // SCT-list extension a certificate / OCSP response carries; the signature is
   // surfaced raw for external verification (pki.ct.reconstructSignedData).
   ct:        ct,
+  // `merkle` is the RFC 6962 / RFC 9162 Merkle-tree proof-verification core --
+  // pki.merkle.leafHash / nodeHash / emptyRootHash build the domain-separated
+  // (0x00 leaf / 0x01 node) SHA-256 tree hashes; pki.merkle.verifyInclusion and
+  // verifyConsistency fold an audit / consistency proof and constant-time-
+  // compare to a checkpoint root. Pure sync hashing, fail-closed, transport-free.
+  merkle:    merkle,
   // `est` is RFC 7030 / 8951 / 9908 Enrollment over Secure Transport -- the
   // transport-agnostic client codecs (base64 transfer, multipart splitter),
   // certs-only + serverkeygen validators over CMS, the enroll-attribute builders,

package/lib/asn1-der.js

@@ -168,6 +168,9 @@ function decode(input, opts) {
   var buf = _asBuffer(input, "decode");
   var maxBytes = _capOpt(opts.maxBytes, "maxBytes", constants.LIMITS.DER_MAX_BYTES);
   var maxDepth = _capOpt(opts.maxDepth, "maxDepth", constants.LIMITS.DER_MAX_DEPTH);
+  if (maxDepth > constants.LIMITS.MAX_DECODE_DEPTH_CEILING) {
+    throw new TypeError("decode: maxDepth " + maxDepth + " exceeds the stack-safe ceiling " + constants.LIMITS.MAX_DECODE_DEPTH_CEILING);
+  }
   if (buf.length > maxBytes) {
     throw new Asn1Error("asn1/too-large", "input " + buf.length + " bytes exceeds cap " + maxBytes);
   }

package/lib/cbor-det.js

@@ -0,0 +1,611 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.cbor
+ * @nav        Core
+ * @title      CBOR (deterministic)
+ * @order      35
+ * @slug       cbor
+ *
+ * @intro
+ *   A strict, fail-closed decoder for RFC 8949 Concise Binary Object
+ *   Representation, restricted to the Core Deterministic Encoding profile
+ *   (RFC 8949 sec. 4.2). It is the binary sibling of `pki.asn1`: an in-house
+ *   codec that owns its stack, rejects every non-canonical shape before it
+ *   returns a value, and bounds size and depth before it walks a byte.
+ *
+ *   Anything a lenient CBOR reader would tolerate -- an indefinite-length
+ *   item, a non-minimal ("preferred") integer / length / tag argument, a
+ *   non-shortest or non-canonical-NaN float, out-of-order or duplicate map
+ *   keys, ill-formed UTF-8, or trailing bytes -- is a permanent `CborError`
+ *   here, because deterministic CBOR is a canonical encoding and a producer
+ *   that violates it produced invalid bytes. There is no lenient mode.
+ *
+ *   `decode` returns a navigable node tree with zero-copy `bytes` / `content`
+ *   views (the raw ranges an external verifier hashes); the `read.*` leaf
+ *   readers turn a node into a JS value (a `BigInt` for every integer, a
+ *   `Buffer` for a byte string, a `Date` for an epoch time, a dotted string
+ *   for a tagged OID). It is the primitive the CBOR-encoded PKI surfaces
+ *   (C509 certificates, COSE / CWT) will compose.
+ *
+ * @card
+ *   `decode` (bounded, fail-closed, deterministic-only) + the `read.*` typed
+ *   leaf readers over its node tree.
+ */
+
+var constants = require("./constants");
+var frameworkError = require("./framework-error");
+var asn1 = require("./asn1-der");
+
+var CborError = frameworkError.CborError;
+
+// Reusable little-work scratch for IEEE-754 float decode + the shortest-form
+// round-trip checks. Single-threaded synchronous use, reset on every write.
+var _fbuf = new ArrayBuffer(8);
+var _fdv = new DataView(_fbuf);
+
+// Strict UTF-8 validator (fatal); a lone continuation / truncated sequence
+// throws instead of substituting U+FFFD -- the fail-open class the toolkit
+// refuses, mirroring asn1-der's strict text decode.
+var _utf8 = new TextDecoder("utf-8", { fatal: true });
+
+// The ECMAScript Date-valid window is +/- 8,640,000,000,000,000 ms; in seconds
+// that is +/- 8.64e12. read.time bounds an epoch value to this window BEFORE
+// narrowing the BigInt to a Number, so the narrowing is lossless (well under
+// 2^53) and the millisecond result stays a safe integer.
+var _MAX_EPOCH_SECONDS = 8640000000000n;
+
+function _asBuffer(input, who) {
+  if (Buffer.isBuffer(input)) return input;
+  if (input instanceof Uint8Array) return Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+  throw new CborError("cbor/not-buffer", who + ": expected a Buffer / Uint8Array");
+}
+
+// Config-time cap validation: a bad cap is an authoring bug, so it throws a
+// TypeError (not a CborError) exactly like asn1-der's _capOpt.
+function _capOpt(v, key, dflt) {
+  if (v === undefined) return dflt;
+  if (typeof v !== "number" || !Number.isInteger(v) || v < 0) {
+    throw new TypeError("decode: " + key + " must be a non-negative integer");
+  }
+  return v;
+}
+
+// Determinism profile -> a ruleset. v1 whitelists only "deterministic"
+// (RFC 8949 sec. 4.2 core); an unknown profile is a config-time TypeError, so
+// there is no path to a lenient decode. A future "ctap2" (length-first map
+// ordering) is a data row here, not a switch through the decoder.
+function _profile(name) {
+  var p = name === undefined ? "deterministic" : name;
+  if (p === "deterministic") return { mapKeyCompare: Buffer.compare };
+  throw new TypeError("decode: unknown profile " + JSON.stringify(p) + " (only \"deterministic\" is supported)");
+}
+
+function _assertUtf8(buf) {
+  try {
+    _utf8.decode(buf);
+  } catch (_e) {
+    throw new CborError("cbor/bad-utf8", "text string is not well-formed UTF-8");
+  }
+}
+
+// Decode the raw IEEE-754 bits (carried in the argument) to a JS double, per
+// the additional-info width: 25 half, 26 single, 27 double.
+function _readFloatBits(argument, ai) {
+  if (ai === 25) { _fdv.setUint16(0, Number(argument)); return _fdv.getFloat16(0); }
+  if (ai === 26) { _fdv.setUint32(0, Number(argument)); return _fdv.getFloat32(0); }
+  _fdv.setBigUint64(0, argument); return _fdv.getFloat64(0);
+}
+
+// Is d exactly representable as a half float? (round-trip through float16;
+// Object.is keeps -0 and the NaN/Inf cases honest).
+function _halfRoundtrips(d) {
+  _fdv.setFloat16(0, d);
+  return Object.is(_fdv.getFloat16(0), d);
+}
+
+// Is d exactly representable as a single float?
+function _singleRoundtrips(d) {
+  return Object.is(Math.fround(d), d);
+}
+
+// Recursive-descent decode of one CBOR item over [start, limit): fail-closed,
+// depth-budgeted, zero-copy. Mirrors asn1-der's _decodeTLV.
+function _decodeItem(buf, start, limit, depth, maxD, rules, state) {
+  if (depth > maxD) throw new CborError("cbor/too-deep", "nesting exceeds depth cap " + maxD);
+  state.n += 1;
+  if (state.n > state.max) throw new CborError("cbor/too-many-items", "decoded item count exceeds cap " + state.max);
+  var p = start;
+  if (p >= limit) throw new CborError("cbor/truncated", "expected an initial byte");
+  var ib = buf[p]; p += 1;
+  var mt = ib >> 5;
+  var ai = ib & 0x1f;
+
+  // Head well-formedness, before reading the argument.
+  if (ib === 0xff) throw new CborError("cbor/unexpected-break", "stray break byte (0xff) at an item head");
+  if (ai === 28 || ai === 29 || ai === 30) throw new CborError("cbor/reserved-ai", "reserved additional-info " + ai);
+  if (ai === 31) {
+    if (mt === 2 || mt === 3 || mt === 4 || mt === 5) {
+      throw new CborError("cbor/indefinite-length", "indefinite-length items are not valid deterministic CBOR");
+    }
+    throw new CborError("cbor/reserved-ai", "additional-info 31 is undefined for major type " + mt);
+  }
+
+  // The argument, minimal-checked, as a lossless BigInt.
+  var argument;
+  var contentStart;
+  if (ai <= 23) {
+    argument = BigInt(ai);
+    contentStart = p;
+  } else {
+    var nBytes = ai === 24 ? 1 : ai === 25 ? 2 : ai === 26 ? 4 : 8;
+    if (p + nBytes > limit) throw new CborError("cbor/truncated", "truncated " + nBytes + "-byte argument");
+    if (nBytes === 1) argument = BigInt(buf[p]);
+    else if (nBytes === 2) argument = BigInt(buf.readUInt16BE(p));
+    else if (nBytes === 4) argument = BigInt(buf.readUInt32BE(p));
+    else argument = buf.readBigUInt64BE(p);
+    p += nBytes;
+    // Preferred (shortest) argument -- for every major type but 7, where the
+    // "argument" is raw float bits governed by the shortest-float rule instead.
+    if (mt !== 7) {
+      var minForWidth = nBytes === 1 ? 24n : nBytes === 2 ? 256n : nBytes === 4 ? 65536n : 4294967296n;
+      if (argument < minForWidth) {
+        throw new CborError("cbor/non-minimal-argument", "argument " + argument + " is not in the shortest head form");
+      }
+    }
+    contentStart = p;
+  }
+
+  var content = null;
+  var children = null;
+  var end;
+
+  if (mt === 0 || mt === 1) {
+    end = contentStart;
+  } else if (mt === 2 || mt === 3) {
+    var len = Number(argument);
+    if (contentStart + len > limit) throw new CborError("cbor/truncated", "string content overruns the buffer");
+    content = buf.subarray(contentStart, contentStart + len);
+    if (mt === 3) _assertUtf8(content);
+    end = contentStart + len;
+  } else if (mt === 4) {
+    children = [];
+    var cp = contentStart;
+    for (var i = 0n; i < argument; i++) {
+      var el = _decodeItem(buf, cp, limit, depth + 1, maxD, rules, state);
+      children.push(el.node);
+      cp = el.end;
+    }
+    end = cp;
+  } else if (mt === 5) {
+    children = [];
+    var mp = contentStart;
+    for (var j = 0n; j < argument; j++) {
+      var k = _decodeItem(buf, mp, limit, depth + 1, maxD, rules, state);
+      mp = k.end;
+      var v = _decodeItem(buf, mp, limit, depth + 1, maxD, rules, state);
+      mp = v.end;
+      if (children.length > 0) {
+        var cmp = rules.mapKeyCompare(children[children.length - 1][0].bytes, k.node.bytes);
+        if (cmp > 0) throw new CborError("cbor/unsorted-map-keys", "map keys are not in bytewise-ascending order");
+        if (cmp === 0) throw new CborError("cbor/duplicate-map-key", "duplicate map key");
+      }
+      children.push([k.node, v.node]);
+    }
+    end = mp;
+  } else if (mt === 6) {
+    var inner = _decodeItem(buf, contentStart, limit, depth + 1, maxD, rules, state);
+    children = [inner.node];
+    end = inner.end;
+  } else {
+    // mt === 7: simple value or float.
+    if (ai <= 23) {
+      end = contentStart;
+    } else if (ai === 24) {
+      if (argument < 32n) {
+        throw new CborError("cbor/reserved-simple", "simple value " + argument + " must use the single-byte immediate form");
+      }
+      end = contentStart;
+    } else {
+      var d = _readFloatBits(argument, ai);
+      if (Number.isNaN(d)) {
+        if (!(ai === 25 && argument === 0x7e00n)) {
+          throw new CborError("cbor/non-canonical-nan", "a NaN must be the canonical half float 0xf97e00");
+        }
+      } else if (ai === 26) {
+        if (_halfRoundtrips(d)) throw new CborError("cbor/non-minimal-float", "a half-representable value must use the half form");
+      } else if (ai === 27) {
+        if (_halfRoundtrips(d) || _singleRoundtrips(d)) {
+          throw new CborError("cbor/non-minimal-float", "a value representable in a narrower float must use it");
+        }
+      }
+      end = contentStart;
+    }
+  }
+
+  var node = {
+    majorType: mt,
+    ai: ai,
+    argument: argument,
+    content: content,
+    children: children,
+    header: { start: start, end: contentStart },
+    contentStart: contentStart,
+    contentEnd: end,
+    length: end - contentStart,
+    bytes: buf.subarray(start, end),
+  };
+  return { node: node, end: end };
+}
+
+/**
+ * @primitive  pki.cbor.decode
+ * @signature  pki.cbor.decode(bytes, opts?) -> node
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 8949 sec. 4.2 (core deterministic encoding)
+ *
+ * Decode one Deterministically Encoded CBOR item into a navigable node tree.
+ * Every non-canonical shape is refused: an indefinite length, a non-minimal
+ * argument, unsorted or duplicate map keys, a non-shortest or non-canonical-
+ * NaN float, ill-formed UTF-8, a reserved additional-info value, or (unless
+ * `allowTrailing`) leftover bytes after the top-level item. Size, depth, and
+ * total item count are bounded, so a high-fanout container fails closed rather
+ * than exhausting memory. A node carries `majorType`, the `argument`
+ * (a lossless BigInt), a zero-copy `content` / `bytes` view, and `children`
+ * (array elements, map key/value pairs, or a tag's one inner item).
+ *
+ * @opts
+ *   maxBytes:       number,   // default: C.LIMITS.CBOR_MAX_BYTES (16 MiB)
+ *   maxDepth:       number,   // default: C.LIMITS.CBOR_MAX_DEPTH (64)
+ *   maxItems:       number,   // default: C.LIMITS.CBOR_MAX_ITEMS (1,000,000 total decoded items)
+ *   allowTrailing:  boolean,  // default: false -- true returns the first item and permits bytes after it (CBOR Sequence)
+ *   profile:        string,   // default: "deterministic" (the only value v1 accepts)
+ *
+ * @example
+ *   var node = pki.cbor.decode(Buffer.from("83010203", "hex"));
+ *   node.majorType;                       // 4 (array)
+ *   pki.cbor.read.uint(node.children[0]); // 1n
+ */
+function decode(input, opts) {
+  opts = opts || {};
+  var buf = _asBuffer(input, "decode");
+  var maxBytes = _capOpt(opts.maxBytes, "maxBytes", constants.LIMITS.CBOR_MAX_BYTES);
+  var maxDepth = _capOpt(opts.maxDepth, "maxDepth", constants.LIMITS.CBOR_MAX_DEPTH);
+  if (maxDepth > constants.LIMITS.MAX_DECODE_DEPTH_CEILING) {
+    throw new TypeError("decode: maxDepth " + maxDepth + " exceeds the stack-safe ceiling " + constants.LIMITS.MAX_DECODE_DEPTH_CEILING);
+  }
+  var maxItems = _capOpt(opts.maxItems, "maxItems", constants.LIMITS.CBOR_MAX_ITEMS);
+  var rules = _profile(opts.profile);
+  if (buf.length > maxBytes) throw new CborError("cbor/too-large", "input " + buf.length + " bytes exceeds cap " + maxBytes);
+  var r = _decodeItem(buf, 0, buf.length, 0, maxDepth, rules, { n: 0, max: maxItems });
+  if (!opts.allowTrailing && r.end !== buf.length) {
+    throw new CborError("cbor/trailing-bytes", (buf.length - r.end) + " trailing byte(s) after the top-level item");
+  }
+  return r.node;
+}
+
+function _expectMajor(node, mt, who) {
+  if (!node || node.majorType !== mt) {
+    throw new CborError("cbor/unexpected-major", who + ": expected major type " + mt);
+  }
+}
+
+// Assert a tag node with a specific tag number, and return its one inner item.
+function _tagInner(node, tagNum, who) {
+  if (!node || node.majorType !== 6 || node.argument !== BigInt(tagNum)) {
+    throw new CborError("cbor/unexpected-tag", who + ": expected tag " + tagNum);
+  }
+  return node.children[0];
+}
+
+/**
+ * @primitive  pki.cbor.read.uint
+ * @signature  pki.cbor.read.uint(node) -> 0n
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 8949 sec. 3.1 (major type 0)
+ *
+ * The unsigned integer value of a major-type-0 node, as a BigInt (uniform
+ * for every magnitude, so the type never varies with the value). Throws
+ * `cbor/unexpected-major` on any other major type.
+ *
+ * @example
+ *   pki.cbor.read.uint(node); // -> 0n
+ */
+function readUint(node) {
+  _expectMajor(node, 0, "read.uint");
+  return node.argument;
+}
+
+/**
+ * @primitive  pki.cbor.read.nint
+ * @signature  pki.cbor.read.nint(node) -> -1n
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 8949 sec. 3.1 (major type 1)
+ *
+ * The negative integer value of a major-type-1 node, as a BigInt
+ * (value = -1 - argument). Throws `cbor/unexpected-major` otherwise.
+ *
+ * @example
+ *   pki.cbor.read.nint(node); // -> -1n
+ */
+function readNint(node) {
+  _expectMajor(node, 1, "read.nint");
+  return -1n - node.argument;
+}
+
+/**
+ * @primitive  pki.cbor.read.int
+ * @signature  pki.cbor.read.int(node) -> -1n
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 8949 sec. 3.1 (major types 0 and 1)
+ *
+ * The signed integer value of a major-type-0 or -1 node, as a BigInt. Throws
+ * `cbor/unexpected-major` on any other major type.
+ *
+ * @example
+ *   pki.cbor.read.int(node); // -> -1n
+ */
+function readInt(node) {
+  if (node && node.majorType === 0) return node.argument;
+  if (node && node.majorType === 1) return -1n - node.argument;
+  throw new CborError("cbor/unexpected-major", "read.int: expected major type 0 or 1");
+}
+
+/**
+ * @primitive  pki.cbor.read.byteString
+ * @signature  pki.cbor.read.byteString(node) -> Buffer
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 8949 sec. 3.1 (major type 2)
+ *
+ * The zero-copy `Buffer` content of a major-type-2 byte string. Throws
+ * `cbor/unexpected-major` otherwise.
+ *
+ * @example
+ *   pki.cbor.read.byteString(node); // -> <Buffer 01 02 03 04>
+ */
+function readByteString(node) {
+  _expectMajor(node, 2, "read.byteString");
+  return node.content;
+}
+
+/**
+ * @primitive  pki.cbor.read.textString
+ * @signature  pki.cbor.read.textString(node) -> "text"
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 8949 sec. 3.1 (major type 3)
+ *
+ * The string value of a major-type-3 text string (already validated as
+ * well-formed UTF-8 at decode). Throws `cbor/unexpected-major` otherwise.
+ *
+ * @example
+ *   pki.cbor.read.textString(node); // -> "a"
+ */
+function readTextString(node) {
+  _expectMajor(node, 3, "read.textString");
+  return node.content.toString("utf8");
+}
+
+/**
+ * @primitive  pki.cbor.read.array
+ * @signature  pki.cbor.read.array(node) -> [node, ...]
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 8949 sec. 3.1 (major type 4)
+ *
+ * The element nodes of a major-type-4 array. Throws `cbor/unexpected-major`
+ * otherwise.
+ *
+ * @example
+ *   pki.cbor.read.array(node); // -> [node, node, node]
+ */
+function readArray(node) {
+  _expectMajor(node, 4, "read.array");
+  return node.children;
+}
+
+/**
+ * @primitive  pki.cbor.read.map
+ * @signature  pki.cbor.read.map(node) -> [[keyNode, valueNode], ...]
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 8949 sec. 3.1 (major type 5)
+ *
+ * The ordered key/value node pairs of a major-type-5 map (ordering and
+ * uniqueness already enforced at decode). Throws `cbor/unexpected-major`
+ * otherwise.
+ *
+ * @example
+ *   pki.cbor.read.map(node); // -> [[keyNode, valueNode]]
+ */
+function readMap(node) {
+  _expectMajor(node, 5, "read.map");
+  return node.children;
+}
+
+/**
+ * @primitive  pki.cbor.read.boolean
+ * @signature  pki.cbor.read.boolean(node) -> false
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 8949 sec. 3.3 (simple values 20 / 21)
+ *
+ * The boolean value of a simple-value node (false=20, true=21). Throws
+ * `cbor/unexpected-major` on a non-simple node, `cbor/bad-simple` on any
+ * other simple value.
+ *
+ * @example
+ *   pki.cbor.read.boolean(node); // -> true
+ */
+function readBoolean(node) {
+  _expectMajor(node, 7, "read.boolean");
+  if (node.ai === 20) return false;
+  if (node.ai === 21) return true;
+  throw new CborError("cbor/bad-simple", "read.boolean: simple value " + node.ai + " is not a boolean");
+}
+
+/**
+ * @primitive  pki.cbor.read.nullValue
+ * @signature  pki.cbor.read.nullValue(node) -> null
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 8949 sec. 3.3 (simple value 22)
+ *
+ * `null` for a simple-value-22 node. Throws `cbor/unexpected-major` on a
+ * non-simple node, `cbor/bad-simple` on any other simple value.
+ *
+ * @example
+ *   pki.cbor.read.nullValue(node); // -> null
+ */
+function readNull(node) {
+  _expectMajor(node, 7, "read.nullValue");
+  if (node.ai !== 22) throw new CborError("cbor/bad-simple", "read.nullValue: simple value " + node.ai + " is not null");
+  return null;
+}
+
+/**
+ * @primitive  pki.cbor.read.undefinedValue
+ * @signature  pki.cbor.read.undefinedValue(node) -> undefined
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 8949 sec. 3.3 (simple value 23)
+ *
+ * `undefined` for a simple-value-23 node. Throws `cbor/unexpected-major` on a
+ * non-simple node, `cbor/bad-simple` on any other simple value.
+ *
+ * @example
+ *   pki.cbor.read.undefinedValue(node); // -> undefined
+ */
+function readUndefined(node) {
+  _expectMajor(node, 7, "read.undefinedValue");
+  if (node.ai !== 23) throw new CborError("cbor/bad-simple", "read.undefinedValue: simple value " + node.ai + " is not undefined");
+  return undefined;
+}
+
+/**
+ * @primitive  pki.cbor.read.float
+ * @signature  pki.cbor.read.float(node) -> 1.5
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 8949 sec. 3.1 (major type 7 floats)
+ *
+ * The JS number (double) of a half / single / double float node (the
+ * shortest-form and canonical-NaN rules already enforced at decode). Throws
+ * `cbor/unexpected-major` on a non-major-7 node, `cbor/bad-simple` on a
+ * simple value that is not a float.
+ *
+ * @example
+ *   pki.cbor.read.float(node); // -> 1.5
+ */
+function readFloat(node) {
+  _expectMajor(node, 7, "read.float");
+  if (node.ai !== 25 && node.ai !== 26 && node.ai !== 27) {
+    throw new CborError("cbor/bad-simple", "read.float: node is a simple value, not a float");
+  }
+  return _readFloatBits(node.argument, node.ai);
+}
+
+/**
+ * @primitive  pki.cbor.read.biguint
+ * @signature  pki.cbor.read.biguint(node) -> 18446744073709551616n
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 8949 sec. 3.4.3 (tag 2 unsigned bignum)
+ *
+ * The BigInt value of a tag-2 unsigned bignum (a big-endian magnitude byte
+ * string, no sign octet). Enforces the byte cap
+ * (`cbor/biguint-too-large`), the no-leading-zero and prefer-basic-int
+ * minimality rules (`cbor/non-minimal-biguint`), and the wrapped content type
+ * (`cbor/bad-tag-content`); a wrong / absent tag throws `cbor/unexpected-tag`.
+ *
+ * @example
+ *   pki.cbor.read.biguint(node); // -> 18446744073709551616n
+ */
+function readBiguint(node) {
+  var inner = _tagInner(node, 2, "read.biguint");
+  if (inner.majorType !== 2) throw new CborError("cbor/bad-tag-content", "read.biguint: tag 2 must wrap a byte string");
+  var c = inner.content;
+  if (c.length > constants.LIMITS.CBOR_MAX_BIGUINT_BYTES) {
+    throw new CborError("cbor/biguint-too-large", "bignum " + c.length + " bytes exceeds cap " + constants.LIMITS.CBOR_MAX_BIGUINT_BYTES);
+  }
+  if (c.length > 0 && c[0] === 0x00) throw new CborError("cbor/non-minimal-biguint", "bignum has a leading zero byte");
+  if (c.length <= 8) throw new CborError("cbor/non-minimal-biguint", "a value that fits a basic integer must not use a bignum");
+  return BigInt("0x" + c.toString("hex"));
+}
+
+/**
+ * @primitive  pki.cbor.read.time
+ * @signature  pki.cbor.read.time(node) -> Date
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 8949 sec. 3.4.2 (tag 1 epoch date/time)
+ *
+ * The `Date` of a tag-1 epoch time (seconds since 1970-01-01T00:00Z, integer).
+ * Throws `cbor/unexpected-tag` on a wrong / absent tag, `cbor/bad-tag-content`
+ * when tag 1 does not wrap an integer, `cbor/bad-time` on an out-of-range value.
+ *
+ * @example
+ *   pki.cbor.read.time(node); // -> Date 2013-03-21T20:04:00.000Z
+ */
+function readTime(node) {
+  var inner = _tagInner(node, 1, "read.time");
+  if (inner.majorType !== 0 && inner.majorType !== 1) {
+    throw new CborError("cbor/bad-tag-content", "read.time: tag 1 must wrap an integer");
+  }
+  var secs = inner.majorType === 0 ? inner.argument : (-1n - inner.argument);
+  if (secs < -_MAX_EPOCH_SECONDS || secs > _MAX_EPOCH_SECONDS) {
+    throw new CborError("cbor/bad-time", "epoch time out of range");
+  }
+  var ns = Number(secs);
+  var d = new Date(ns < 0 ? -constants.TIME.seconds(-ns) : constants.TIME.seconds(ns));
+  if (isNaN(d.getTime())) throw new CborError("cbor/bad-time", "epoch time out of range");
+  return d;
+}
+
+/**
+ * @primitive  pki.cbor.read.oid
+ * @signature  pki.cbor.read.oid(node) -> "2.5.4.3"
+ * @since      0.1.27
+ * @status     experimental
+ * @spec       RFC 9090 (tag 111 CBOR OID)
+ *
+ * The dotted OID string of a tag-111 CBOR OID (a byte string carrying the BER
+ * object-identifier content octets, decoded through the shared
+ * `asn1.decodeOidContent`, so a malformed body surfaces the existing `oid/*`
+ * codes). Throws `cbor/unexpected-tag` on a wrong / absent tag,
+ * `cbor/bad-tag-content` when tag 111 does not wrap a byte string.
+ *
+ * @example
+ *   pki.cbor.read.oid(node); // -> "2.5.4.3"
+ */
+function readOid(node) {
+  var inner = _tagInner(node, 111, "read.oid");
+  if (inner.majorType !== 2) throw new CborError("cbor/bad-tag-content", "read.oid: tag 111 must wrap a byte string");
+  return asn1.decodeOidContent(inner.content);
+}
+
+module.exports = {
+  decode: decode,
+  read: {
+    uint:           readUint,
+    nint:           readNint,
+    int:            readInt,
+    byteString:     readByteString,
+    textString:     readTextString,
+    array:          readArray,
+    map:            readMap,
+    boolean:        readBoolean,
+    nullValue:      readNull,
+    undefinedValue: readUndefined,
+    float:          readFloat,
+    biguint:        readBiguint,
+    time:           readTime,
+    oid:            readOid,
+  },
+};

package/lib/constants.js

@@ -132,9 +132,37 @@ var BYTES = {
 var LIMITS = {
   DER_MAX_BYTES: BYTES.mib(16),
   DER_MAX_DEPTH: 64,
+  // Hard stack-safe ceiling on the recursion depth of the DER / CBOR
+  // decoders, independent of the (operator-tunable) maxDepth. Both decoders
+  // are recursive descent; a maxDepth raised above the engine's native call-
+  // stack limit would let deeply nested input overflow the C stack with a raw
+  // RangeError instead of the typed too-deep verdict, defeating the fail-closed
+  // contract. A maxDepth above this ceiling is refused at config time. 256 is
+  // four times the default cap and far deeper than any real PKI / CBOR nesting
+  // (a certificate is ~6 levels; the deepest bounded re-decode is 16), while
+  // staying well below the overflow threshold on any supported platform.
+  MAX_DECODE_DEPTH_CEILING: 256,
   PEM_MAX_BYTES: BYTES.mib(16),
   DER_MAX_INTEGER_BYTES: BYTES.kib(16),
   OID_MAX_SUBIDENTIFIER_BYTES: 32,
+  // Deterministic-CBOR codec ceilings (RFC 8949), the DER neighbours' siblings:
+  // a whole-document cap refused before the walk, a nesting cap, and a per-value
+  // bignum ceiling the document cap can't provide. Unlike DER_MAX_INTEGER_BYTES,
+  // the bignum cap carries NO +1 sign octet -- a CBOR tag-2/3 bignum body is pure
+  // unsigned big-endian magnitude (RFC 8949 sec. 3.4.3), so 16 KiB is the exact
+  // byte ceiling (covers an RSA-131072 modulus).
+  CBOR_MAX_BYTES: BYTES.mib(16),
+  CBOR_MAX_DEPTH: 64,
+  CBOR_MAX_BIGUINT_BYTES: BYTES.kib(16),
+  // Total decoded-item ceiling. A definite-length array or map can declare a
+  // huge element count that stays under the byte cap yet allocates one node per
+  // element -- e.g. a 16 MiB input of `9a00fffffb` followed by ~16 million
+  // one-byte items would build ~16 million nodes and exhaust memory before a
+  // typed verdict. The decoder counts every item it builds and refuses past this
+  // cap, so a high-fanout bomb fails closed with cbor/too-many-items instead of
+  // OOM-ing. 1,000,000 is far above any real CBOR-encoded PKI structure (a C509
+  // certificate or COSE message is hundreds of items) while bounding the tree.
+  CBOR_MAX_ITEMS: 1000000,
   // Certificate Transparency SCT-list bounds (RFC 6962 sec. 3.3). The outer sct_list
   // vector carries a 2-byte length prefix, so a well-formed list body is at most
   // 2^16-1 = 65535 bytes and the full TLS blob (prefix + body) is at most 65537.
@@ -148,6 +176,17 @@ var LIMITS = {
   // 2-5 SCTs; 256 is far above policy.
   SCT_MAX_BYTES: BYTES.kib(64) + 1,
   SCT_MAX_COUNT: 256,
+  // Merkle-proof node-count ceiling (RFC 6962 / RFC 9162). A DoS backstop that
+  // rejects a pathologically long proof array BEFORE the O(log n) fold does any
+  // digest work. 65 is the exact structural maximum: a tree size is a uint64, so
+  // an audit (inclusion) path is at most ceil(log2(2^64)) = 64 nodes, but a
+  // consistency proof is at most ceil(log2(newSize)) + 1 = 65 nodes (the extra
+  // node is the SUBPROOF terminal for a non-power-of-two old size near 2^64). Real
+  // CT logs are 2^30-2^40 (30-40-node proofs), so 65 is generous headroom while
+  // still bounding hostile work. The PRECISE per-proof guard is the geometry
+  // check in each verify (the node count must equal what the coordinates require);
+  // this is the coarse cap. A node count, not a byte size.
+  MERKLE_MAX_PROOF_NODES: 65,
   // Certification-path length ceiling: bounds the per-cert asymmetric verify
   // work on an untrusted certificate bundle (a real chain is well under this;
   // the operator may override via opts.maxPathCerts).

package/lib/framework-error.js

@@ -130,6 +130,15 @@ var ConstantsError = defineClass("ConstantsError");
 // decoder rejects is permanently invalid.
 var Asn1Error = defineClass("Asn1Error");
 
+// CborError -- malformed / non-deterministic CBOR: a reserved or indefinite
+// additional-info value, a stray break, a non-minimal ("preferred") argument,
+// a non-shortest or non-canonical-NaN float, an out-of-order or duplicate map
+// key, a non-minimal / oversized bignum, bad UTF-8, a wrong-typed tag body,
+// leftover trailing bytes, or a depth / size cap exceeded. RFC 8949 core-
+// deterministic encoding (sec. 4.2.1) is canonical, so anything the decoder
+// rejects is permanently invalid.
+var CborError = defineClass("CborError");
+
 // OidError -- a malformed object-identifier: fewer than two arcs, a first
 // arc outside 0..2, a second arc >= 40 under arcs 0/1, or a non-minimal
 // base-128 sub-identifier.
@@ -219,6 +228,16 @@ var SmimeError = defineClass("SmimeError", { withCause: true });
 // inner `asn1/*` decode error) as `.cause`.
 var CtError = defineClass("CtError", { withCause: true });
 
+// MerkleError -- a malformed input to the RFC 6962 / RFC 9162 Merkle-tree
+// proof-verification core: a tree coordinate that is not a non-negative integer
+// (or a Number above 2^53 where an exact BigInt is required), a leafIndex
+// outside its tree, an inverted consistency window, a hash chunk that is not 32
+// bytes, or a proof whose node count does not match the tree geometry. The final
+// root comparison is a constant-time boolean (root matched / did not), NOT an
+// error -- only a structurally malformed input throws. Carries an underlying
+// leaf fault as `.cause`.
+var MerkleError = defineClass("MerkleError", { withCause: true });
+
 // CsrattrsError -- a byte sequence that is not a well-formed RFC 8951 sec. 3.5
 // CsrAttrs (SEQUENCE OF AttrOrOID), or one violating an RFC 9908 semantic rule
 // (a repeated id-ExtensionReq, an extension-request values SET that is not
@@ -255,6 +274,7 @@ module.exports = {
   defineClass:      defineClass,
   ConstantsError:   ConstantsError,
   Asn1Error:        Asn1Error,
+  CborError:        CborError,
   OidError:         OidError,
   PemError:         PemError,
   CertificateError: CertificateError,
@@ -271,6 +291,7 @@ module.exports = {
   CmpError:         CmpError,
   PathError:        PathError,
   CtError:          CtError,
+  MerkleError:      MerkleError,
   SmimeError:       SmimeError,
   CsrattrsError:    CsrattrsError,
   EstError:         EstError,

package/lib/merkle.js

@@ -0,0 +1,345 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.merkle
+ * @nav        Transparency
+ * @title      Merkle
+ * @order      220
+ * @slug       merkle
+ *
+ * @intro
+ *   RFC 6962 (Certificate Transparency) / RFC 9162 (CT 2.0) Merkle-tree hash
+ *   and proof-verification core -- the load-bearing primitive a static-CT
+ *   client, a Merkle-Tree-Certificates relying party, and a sigstore / Rekor
+ *   inclusion check all compose. It is ALL strict verification over SHA-256:
+ *   zero new crypto.
+ *
+ *   `leafHash` / `nodeHash` / `emptyRootHash` build the tree hashes with the
+ *   two domain-separation prefixes fixed by the spec -- a leaf is
+ *   `SHA-256(0x00 || entry)`, an interior node is `SHA-256(0x01 || left ||
+ *   right)`, the empty tree is `SHA-256("")`. Those `0x00` / `0x01` prefixes
+ *   are the second-preimage defense: without them a leaf whose bytes equal a
+ *   valid interior node's preimage could be smuggled in as present.
+ *
+ *   `verifyInclusion` folds an audit path back to a root and constant-time-
+ *   compares it to a trusted checkpoint root; `verifyConsistency` reconstructs
+ *   BOTH the old and the new root from a consistency proof (the append-only
+ *   guarantee lives in the old-root leg). Both are fail-closed: a malformed
+ *   coordinate, an out-of-range index, an inverted window, a wrong hash length,
+ *   or a proof whose node count does not match the tree geometry throws a typed
+ *   `merkle/*` error; the ONLY boolean-`false` result is the final root
+ *   comparison ("root matched" vs "did not"). A `false` from `verifyInclusion`
+ *   means "not proven present against this root", never "validly absent" -- an
+ *   inclusion proof cannot express absence. Tree coordinates are uint64, carried
+ *   as `BigInt` so a large index is never `Number`-narrowed. This is NOT a DER
+ *   format: like `pki.ct` it is a companion module reached explicitly, never
+ *   routed by the detect-and-parse orchestrator.
+ *
+ * @card
+ *   `leafHash` / `nodeHash` / `emptyRootHash` + `verifyInclusion` /
+ *   `verifyConsistency` over sync SHA-256, fail-closed, transport-free.
+ */
+
+var nodeCrypto = require("node:crypto");
+var constants = require("./constants");
+var frameworkError = require("./framework-error");
+
+var MerkleError = frameworkError.MerkleError;
+
+var SHA256_BYTES = 32;
+var UINT64_MAX = 18446744073709551615n; // 2n ** 64n - 1n
+var LEAF_PREFIX = Buffer.from([0x00]);
+var NODE_PREFIX = Buffer.from([0x01]);
+var EMPTY = Buffer.alloc(0);
+
+function _sha256(buf) {
+  return nodeCrypto.createHash("sha256").update(buf).digest();
+}
+
+function _toBuffer(v, field) {
+  if (!Buffer.isBuffer(v) && !(v instanceof Uint8Array)) {
+    throw new MerkleError("merkle/bad-input", field + " must be a Buffer or Uint8Array");
+  }
+  try {
+    // A zero-copy view over the same bytes; this also surfaces a detached
+    // backing ArrayBuffer (a transferred / structuredClone'd view) as a typed
+    // error here rather than a raw TypeError from a later concat / digest.
+    return Buffer.from(v.buffer, v.byteOffset, v.byteLength);
+  } catch (e) {
+    throw new MerkleError("merkle/bad-input", field + " is not a usable byte view", e);
+  }
+}
+
+function _node32(v, field) {
+  var buf = _toBuffer(v, field);
+  if (buf.length !== SHA256_BYTES) {
+    throw new MerkleError("merkle/bad-hash-length", field + " must be exactly 32 bytes, got " + buf.length);
+  }
+  return buf;
+}
+
+// number | bigint -> a validated BigInt in [0, 2^64). A Number >= 2^53 (where
+// precision is lost), a negative / non-integer, or a non-number-non-bigint
+// throws -- the number-narrows-unbounded-integer discipline for uint64 tree
+// coordinates.
+function _coerceCoord(v, field) {
+  var b;
+  if (typeof v === "bigint") {
+    b = v;
+  } else if (typeof v === "number") {
+    if (!Number.isSafeInteger(v) || v < 0) {
+      throw new MerkleError("merkle/bad-input", field + " must be a non-negative safe integer or a BigInt (a Number >= 2^53 loses precision)");
+    }
+    b = BigInt(v);
+  } else {
+    throw new MerkleError("merkle/bad-input", field + " must be a number or a BigInt");
+  }
+  if (b < 0n || b > UINT64_MAX) {
+    throw new MerkleError("merkle/bad-input", field + " must be in [0, 2^64)");
+  }
+  return b;
+}
+
+function _proofNodes(proof) {
+  if (!Array.isArray(proof)) throw new MerkleError("merkle/bad-proof", "proof must be an array");
+  if (proof.length > constants.LIMITS.MERKLE_MAX_PROOF_NODES) {
+    throw new MerkleError("merkle/proof-too-large", "proof has " + proof.length + " nodes, exceeds " + constants.LIMITS.MERKLE_MAX_PROOF_NODES);
+  }
+  var out = [];
+  for (var i = 0; i < proof.length; i++) out.push(_node32(proof[i], "proof[" + i + "]"));
+  return out;
+}
+
+// Constant-time equality of two already-validated equal-length 32-byte buffers.
+function _ctEq(a, b) {
+  return a.length === b.length && nodeCrypto.timingSafeEqual(a, b);
+}
+
+/**
+ * @primitive  pki.merkle.leafHash
+ * @signature  pki.merkle.leafHash(entry) -> Buffer
+ * @since      0.1.28
+ * @status     experimental
+ * @spec       RFC 6962, RFC 9162
+ * @related    pki.merkle.nodeHash, pki.merkle.verifyInclusion
+ *
+ * The Merkle leaf hash `MTH({d}) = SHA-256(0x00 || entry)`. The `0x00` prefix
+ * is the leaf-domain second-preimage separation and is applied unconditionally.
+ * Throws `merkle/bad-input` if `entry` is not a Buffer / Uint8Array.
+ *
+ * @example
+ *   pki.merkle.leafHash(Buffer.from("leaf data")); // -> <Buffer 32-byte leaf hash>
+ */
+function leafHash(entry) {
+  var e = _toBuffer(entry, "entry");
+  return _sha256(Buffer.concat([LEAF_PREFIX, e]));
+}
+
+/**
+ * @primitive  pki.merkle.nodeHash
+ * @signature  pki.merkle.nodeHash(left, right) -> Buffer
+ * @since      0.1.28
+ * @status     experimental
+ * @spec       RFC 6962, RFC 9162
+ * @related    pki.merkle.leafHash
+ *
+ * The Merkle interior-node hash `SHA-256(0x01 || left || right)`. Both operands
+ * must be 32-byte hashes; the `0x01` prefix is applied unconditionally. Throws
+ * `merkle/bad-input` on a non-buffer operand, `merkle/bad-hash-length` on an
+ * operand that is not exactly 32 bytes.
+ *
+ * @example
+ *   var l = pki.merkle.leafHash(Buffer.from([0]));
+ *   var r = pki.merkle.leafHash(Buffer.from([1]));
+ *   pki.merkle.nodeHash(l, r); // -> <Buffer 32-byte node hash>
+ */
+function nodeHash(left, right) {
+  var l = _node32(left, "left");
+  var r = _node32(right, "right");
+  return _sha256(Buffer.concat([NODE_PREFIX, l, r]));
+}
+
+/**
+ * @primitive  pki.merkle.emptyRootHash
+ * @signature  pki.merkle.emptyRootHash() -> Buffer
+ * @since      0.1.28
+ * @status     experimental
+ * @spec       RFC 6962, RFC 9162
+ * @related    pki.merkle.verifyConsistency
+ *
+ * The Merkle tree head of the empty tree, `MTH({}) = SHA-256("")`
+ * (`e3b0c442...b855`). A fresh Buffer each call.
+ *
+ * @example
+ *   pki.merkle.emptyRootHash(); // -> <Buffer e3 b0 c4 42 ...>
+ */
+function emptyRootHash() {
+  return _sha256(EMPTY);
+}
+
+/**
+ * @primitive  pki.merkle.verifyInclusion
+ * @signature  pki.merkle.verifyInclusion(opts) -> boolean
+ * @since      0.1.28
+ * @status     experimental
+ * @spec       RFC 6962, RFC 9162
+ * @related    pki.merkle.leafHash, pki.merkle.verifyConsistency
+ *
+ * Verify an RFC 6962 / RFC 9162 audit (inclusion) proof: fold `leafHash` up the
+ * audit path and constant-time-compare the reconstructed root to `rootHash`.
+ * Returns `true` iff the proof binds the leaf to the root; a well-formed proof
+ * that does not match returns `false` ("not proven present against this root",
+ * NEVER "validly absent"). A malformed input -- a coordinate that is not a
+ * non-negative integer (or a Number >= 2^53), `treeSize` 0, `leafIndex >=
+ * treeSize`, a non-32-byte hash, or a proof whose node count does not match the
+ * tree geometry -- throws a typed `merkle/*` error.
+ *
+ * @opts
+ *   leafIndex:  number | bigint,  // 0-based leaf position (uint64; pass BigInt above 2^53)
+ *   treeSize:   number | bigint,  // total leaf count of the tree the root commits to
+ *   leafHash:   Buffer,           // 32-byte leaf hash (e.g. from pki.merkle.leafHash)
+ *   proof:      Buffer[],         // the audit path, each node a 32-byte hash
+ *   rootHash:   Buffer,           // 32-byte trusted checkpoint root
+ *
+ * @example
+ *   var lh = pki.merkle.leafHash(Buffer.from([0]));
+ *   pki.merkle.verifyInclusion({ leafIndex: 0, treeSize: 1, leafHash: lh, proof: [], rootHash: lh }); // -> true
+ */
+function verifyInclusion(opts) {
+  opts = opts || {};
+  var leafIndex = _coerceCoord(opts.leafIndex, "leafIndex");
+  var treeSize = _coerceCoord(opts.treeSize, "treeSize");
+  if (treeSize === 0n) throw new MerkleError("merkle/empty-tree", "an empty tree has no leaves to include");
+  if (leafIndex >= treeSize) throw new MerkleError("merkle/index-out-of-range", "leafIndex " + leafIndex + " is not less than treeSize " + treeSize);
+  var lh = _node32(opts.leafHash, "leafHash");
+  var rootHash = _node32(opts.rootHash, "rootHash");
+  var proof = _proofNodes(opts.proof);
+
+  var fn = leafIndex;
+  var sn = treeSize - 1n;
+  var r = lh;
+  for (var i = 0; i < proof.length; i++) {
+    var p = proof[i];
+    if (sn === 0n) throw new MerkleError("merkle/bad-proof-length", "proof is longer than the tree geometry allows");
+    if ((fn & 1n) === 1n || fn === sn) {
+      r = nodeHash(p, r);
+      if ((fn & 1n) === 0n) {
+        do { fn >>= 1n; sn >>= 1n; } while ((fn & 1n) === 0n && fn !== 0n);
+      }
+    } else {
+      r = nodeHash(r, p);
+    }
+    fn >>= 1n;
+    sn >>= 1n;
+  }
+  if (sn !== 0n) throw new MerkleError("merkle/bad-proof-length", "proof is shorter than the tree geometry requires");
+  return _ctEq(r, rootHash);
+}
+
+/**
+ * @primitive  pki.merkle.verifyConsistency
+ * @signature  pki.merkle.verifyConsistency(opts) -> boolean
+ * @since      0.1.28
+ * @status     experimental
+ * @spec       RFC 6962, RFC 9162
+ * @related    pki.merkle.verifyInclusion, pki.merkle.emptyRootHash
+ *
+ * Verify an RFC 6962 / RFC 9162 consistency proof between an older tree of
+ * `oldSize` leaves (root `oldRoot`) and a newer tree of `newSize` leaves (root
+ * `newRoot`). Reconstructs BOTH roots from the proof and constant-time-compares
+ * each; returns `true` iff both match (the append-only guarantee lives in the
+ * old-root leg -- a proof that yields a valid `newRoot` but the wrong `oldRoot`
+ * is a rewritten history and returns `false`). The empty tree is a prefix of
+ * every tree, so `oldSize` 0 checks `oldRoot == emptyRootHash()` -- and, when
+ * `newSize` is also 0, `newRoot == emptyRootHash()` too (both trees empty); for
+ * `newSize > 0` an empty-old proof places no binding on `newRoot` (an empty prior
+ * tree carries no append-only guarantee -- authenticate `newRoot` separately,
+ * e.g. via its checkpoint signature). Equal non-zero sizes require an empty proof
+ * and `oldRoot == newRoot`. A malformed input --
+ * `oldSize > newSize`, a non-empty proof where
+ * the geometry requires none (or empty where it requires one), a non-32-byte
+ * hash, or a wrong node count -- throws a typed `merkle/*` error.
+ *
+ * @opts
+ *   oldSize:  number | bigint,  // leaf count of the older tree (uint64)
+ *   newSize:  number | bigint,  // leaf count of the newer tree (>= oldSize)
+ *   oldRoot:  Buffer,           // 32-byte root of the older tree
+ *   newRoot:  Buffer,           // 32-byte root of the newer tree
+ *   proof:    Buffer[],         // the consistency proof, each node a 32-byte hash
+ *
+ * @example
+ *   var r = pki.merkle.leafHash(Buffer.from([0]));
+ *   pki.merkle.verifyConsistency({ oldSize: 1, newSize: 1, oldRoot: r, newRoot: r, proof: [] }); // -> true
+ */
+function verifyConsistency(opts) {
+  opts = opts || {};
+  var oldSize = _coerceCoord(opts.oldSize, "oldSize");
+  var newSize = _coerceCoord(opts.newSize, "newSize");
+  var oldRoot = _node32(opts.oldRoot, "oldRoot");
+  var newRoot = _node32(opts.newRoot, "newRoot");
+  var proof = _proofNodes(opts.proof);
+
+  if (oldSize > newSize) throw new MerkleError("merkle/old-size-exceeds-new", "oldSize " + oldSize + " exceeds newSize " + newSize);
+  if (oldSize === 0n) {
+    if (proof.length !== 0) throw new MerkleError("merkle/bad-proof-length", "an empty older tree admits only the empty consistency proof");
+    var er = emptyRootHash();
+    var oldEmpty = _ctEq(oldRoot, er);
+    // The empty tree is a prefix of every tree, so its own root must be the
+    // empty root. When the NEW tree is also empty, its root must be the empty
+    // root too (a bogus newRoot must not pass); when newSize > 0 an empty-old
+    // proof places no binding on newRoot.
+    if (newSize === 0n) {
+      var newEmpty = _ctEq(newRoot, er);
+      return oldEmpty && newEmpty;
+    }
+    return oldEmpty;
+  }
+  if (oldSize === newSize) {
+    if (proof.length !== 0) throw new MerkleError("merkle/sizes-equal-nonempty-proof", "equal tree sizes require an empty consistency proof");
+    return _ctEq(oldRoot, newRoot);
+  }
+  if (proof.length === 0) throw new MerkleError("merkle/empty-consistency-proof", "a non-trivial consistency proof must not be empty");
+
+  var path = proof;
+  if ((oldSize & (oldSize - 1n)) === 0n) {
+    // oldSize is an exact power of two: the old root is the first proof node
+    // (it is not otherwise carried in the proof).
+    path = [oldRoot].concat(proof);
+  }
+  var fn = oldSize - 1n;
+  var sn = newSize - 1n;
+  while ((fn & 1n) === 1n) { fn >>= 1n; sn >>= 1n; }
+  var fr = path[0];
+  var sr = path[0];
+  for (var i = 1; i < path.length; i++) {
+    var c = path[i];
+    if (sn === 0n) throw new MerkleError("merkle/bad-proof-length", "consistency proof is longer than the geometry allows");
+    if ((fn & 1n) === 1n || fn === sn) {
+      fr = nodeHash(c, fr);
+      sr = nodeHash(c, sr);
+      if ((fn & 1n) === 0n) {
+        do { fn >>= 1n; sn >>= 1n; } while ((fn & 1n) === 0n && fn !== 0n);
+      }
+    } else {
+      sr = nodeHash(sr, c);
+    }
+    fn >>= 1n;
+    sn >>= 1n;
+  }
+  if (sn !== 0n) throw new MerkleError("merkle/bad-proof-length", "consistency proof is shorter than the geometry requires");
+  // Evaluate BOTH constant-time compares unconditionally before combining, so a
+  // `&&` never short-circuits the second `timingSafeEqual` (which would leak,
+  // via timing, whether the old-root leg matched).
+  var okOld = _ctEq(fr, oldRoot);
+  var okNew = _ctEq(sr, newRoot);
+  return okOld && okNew;
+}
+
+module.exports = {
+  leafHash:          leafHash,
+  nodeHash:          nodeHash,
+  emptyRootHash:     emptyRootHash,
+  verifyInclusion:   verifyInclusion,
+  verifyConsistency: verifyConsistency,
+};

package/lib/oid.js

@@ -500,7 +500,7 @@ var _PARAMS_ABSENT = new Set();
  * @primitive  pki.oid.paramsMustBeAbsent
  * @signature  pki.oid.paramsMustBeAbsent(dotted) -> boolean
  * @since      0.1.21
- * @status     experimental
+ * @status     stable
  * @spec       RFC 9909, RFC 9814, RFC 9881, RFC 8410
  * @related    pki.oid.name, pki.oid.byName
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "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:51669f50-bf8f-4b65-8c89-e8fd503b0399",
+  "serialNumber": "urn:uuid:e10c86e3-914c-4324-abeb-585344830973",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-10T23:32:35.928Z",
+    "timestamp": "2026-07-11T04:47:27.941Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.26",
+      "bom-ref": "@blamejs/pki@0.1.28",
       "type": "application",
       "name": "pki",
-      "version": "0.1.26",
+      "version": "0.1.28",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.1.26",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.28",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.26",
+      "ref": "@blamejs/pki@0.1.28",
       "dependsOn": []
     }
   ]