@blamejs/pki 0.1.27 → 0.1.29

package/CHANGELOG.md

@@ -4,7 +4,28 @@ 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.27 — 2026-07-11
+## v0.1.29 — 2026-07-11
+
+A detached-backed BufferSource now fails closed with a typed error at every byte-input boundary.
+
+### Fixed
+
+- pki.webcrypto digest / sign / verify no longer silently process a detached-backed Buffer as EMPTY input (a fail-open where a transferred backing ArrayBuffer left the view zero-length); a detached BufferSource is now rejected with a typed webcrypto/data error, as is getRandomValues.
+- pki.asn1.decode, pki.cbor.decode, and pki.ct.parseSctList reject a detached-backed Buffer or view with a typed error (asn1/not-buffer, cbor/not-buffer, ct/bad-input) instead of a raw TypeError or a misleading truncated-input verdict. The underlying byte-view failure is threaded as the error cause.
+
+## v0.1.28 — 2026-07-10
+
+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.
 

package/README.md

@@ -222,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

@@ -36,6 +36,7 @@ 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");
@@ -65,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

@@ -105,8 +105,18 @@ function _className(bits) {
 }
 
 function _asBuffer(input, who) {
-  if (Buffer.isBuffer(input)) return input;
-  if (input instanceof Uint8Array) return Buffer.from(input);
+  // A Buffer is a Uint8Array, so it routes through the same guarded re-view --
+  // NOT a `Buffer.isBuffer` fast-path that returns it as-is. A detached backing
+  // ArrayBuffer (a transferred / structuredClone'd view) reads as zero-length;
+  // re-viewing through Buffer.from surfaces it as a typed error here rather than
+  // a misleading downstream truncated-DER verdict on an empty buffer.
+  if (Buffer.isBuffer(input) || input instanceof Uint8Array) {
+    try {
+      return Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+    } catch (e) {
+      throw new Asn1Error("asn1/not-buffer", who + ": input is not a usable byte view (detached backing buffer?)", e);
+    }
+  }
   throw new Asn1Error("asn1/not-buffer", who + ": expected a Buffer / Uint8Array");
 }
 

package/lib/cbor-det.js

@@ -57,8 +57,20 @@ var _utf8 = new TextDecoder("utf-8", { fatal: true });
 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);
+  // A Buffer is itself a Uint8Array, so it goes through the same guarded re-view
+  // -- NOT a `Buffer.isBuffer` fast-path that would return it as-is. A detached
+  // backing ArrayBuffer (a transferred / structuredClone'd view) has had its
+  // bytes removed and reads as zero-length; the fast-path would hand the byte
+  // walk an empty buffer. Always re-view through Buffer.from so a detached input
+  // fails closed here as a typed error rather than a raw TypeError deeper in the
+  // walk (or a misleading truncated-input verdict).
+  if (Buffer.isBuffer(input) || input instanceof Uint8Array) {
+    try {
+      return Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+    } catch (e) {
+      throw new CborError("cbor/not-buffer", who + ": input is not a usable byte view (detached backing buffer?)", e);
+    }
+  }
   throw new CborError("cbor/not-buffer", who + ": expected a Buffer / Uint8Array");
 }
 

package/lib/constants.js

@@ -176,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/ct.js

@@ -111,8 +111,18 @@ function _peelInner(extValue) {
 }
 
 function _toBuffer(v, field) {
-  if (Buffer.isBuffer(v)) return v;
-  if (v instanceof Uint8Array) return Buffer.from(v);
+  // A Buffer is a Uint8Array, so it routes through the same guarded re-view --
+  // NOT a `Buffer.isBuffer` fast-path that returns it as-is. A detached backing
+  // ArrayBuffer (a transferred / structuredClone'd view) reads as zero-length;
+  // re-viewing through Buffer.from surfaces it as a typed error here rather than
+  // a misleading downstream bad-DER verdict on an empty buffer.
+  if (Buffer.isBuffer(v) || v instanceof Uint8Array) {
+    try {
+      return Buffer.from(v.buffer, v.byteOffset, v.byteLength);
+    } catch (e) {
+      throw new CtError("ct/bad-input", field + " is not a usable byte view (detached backing buffer?)", e);
+    }
+  }
   throw new CtError("ct/bad-input", field + " must be a Buffer or Uint8Array");
 }
 
@@ -199,10 +209,7 @@ function _parseSct(r, sctLen) {
  *   }
  */
 function parseSctList(extValue) {
-  if (!Buffer.isBuffer(extValue) && !(extValue instanceof Uint8Array)) {
-    throw new CtError("ct/bad-input", "parseSctList expects the SCT-list extension value as a Buffer or Uint8Array");
-  }
-  var blob = _peelInner(Buffer.isBuffer(extValue) ? extValue : Buffer.from(extValue));
+  var blob = _peelInner(_toBuffer(extValue, "the SCT-list extension value"));
   if (blob.length > C.LIMITS.SCT_MAX_BYTES) {
     throw new CtError("ct/too-large", "SCT list " + blob.length + " bytes exceeds the cap " + C.LIMITS.SCT_MAX_BYTES);
   }

package/lib/framework-error.js

@@ -127,8 +127,9 @@ var ConstantsError = defineClass("ConstantsError");
 // Asn1Error -- malformed / non-canonical DER: truncated TLV, indefinite
 // length, non-minimal length or integer, leftover trailing bytes, depth
 // or size cap exceeded. DER is a canonical encoding, so anything the
-// decoder rejects is permanently invalid.
-var Asn1Error = defineClass("Asn1Error");
+// decoder rejects is permanently invalid. withCause threads a raw byte-view
+// failure (a detached backing ArrayBuffer) as the cause rather than discarding it.
+var Asn1Error = defineClass("Asn1Error", { withCause: true });
 
 // CborError -- malformed / non-deterministic CBOR: a reserved or indefinite
 // additional-info value, a stray break, a non-minimal ("preferred") argument,
@@ -136,8 +137,9 @@ var Asn1Error = defineClass("Asn1Error");
 // 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");
+// rejects is permanently invalid. withCause threads a raw byte-view failure
+// (a detached backing ArrayBuffer) as the cause rather than discarding it.
+var CborError = defineClass("CborError", { withCause: true });
 
 // 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
@@ -228,6 +230,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
@@ -281,6 +293,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/webcrypto.js

@@ -47,9 +47,20 @@ var MAX_RANDOM_BYTES = 65536;
 // ---- value helpers ---------------------------------------------------
 
 function _toBuf(data, who) {
-  if (Buffer.isBuffer(data)) return data;
-  if (data instanceof ArrayBuffer) return Buffer.from(data);
-  if (ArrayBuffer.isView(data)) return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+  var isAb = data instanceof ArrayBuffer;
+  // A Buffer is itself an ArrayBuffer view, so it is handled by the view arm --
+  // NOT a `Buffer.isBuffer` fast-path that would return it as-is. A detached
+  // backing ArrayBuffer (a transferred / structuredClone'd Buffer, view, or
+  // ArrayBuffer) has had its bytes removed and reads as zero-length; the
+  // fast-path would silently hash / sign EMPTY (a fail-OPEN). Always re-view
+  // through Buffer.from so a detached input fails closed here as a typed error.
+  if (isAb || ArrayBuffer.isView(data)) {
+    try {
+      return isAb ? Buffer.from(data) : Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    } catch (e) {
+      throw new WebCryptoError("webcrypto/data", (who || "input") + ": input is not a usable byte source (detached backing buffer?)", e);
+    }
+  }
   throw new WebCryptoError("webcrypto/data", (who || "input") + ": expected BufferSource (ArrayBuffer / TypedArray / Buffer)");
 }
 
@@ -718,7 +729,15 @@ Crypto.prototype.getRandomValues = function getRandomValues(typedArray) {
   if (typedArray.byteLength > MAX_RANDOM_BYTES) {
     throw new WebCryptoError("webcrypto/data", "getRandomValues: byteLength exceeds " + MAX_RANDOM_BYTES);
   }
-  nodeCrypto.randomFillSync(Buffer.from(typedArray.buffer, typedArray.byteOffset, typedArray.byteLength));
+  var view;
+  try {
+    // A detached backing ArrayBuffer surfaces as a typed error rather than a
+    // raw TypeError from Buffer.from over the transferred/cloned view.
+    view = Buffer.from(typedArray.buffer, typedArray.byteOffset, typedArray.byteLength);
+  } catch (e) {
+    throw new WebCryptoError("webcrypto/data", "getRandomValues: byte view is not usable (detached backing buffer?)", e);
+  }
+  nodeCrypto.randomFillSync(view);
   return typedArray;
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "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:cdf3408c-61a7-4b5e-ac8a-dfd37f45e9e6",
+  "serialNumber": "urn:uuid:26032baa-c793-470f-863c-569dc97c186e",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-11T01:50:55.133Z",
+    "timestamp": "2026-07-11T05:58:59.165Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.27",
+      "bom-ref": "@blamejs/pki@0.1.29",
       "type": "application",
       "name": "pki",
-      "version": "0.1.27",
+      "version": "0.1.29",
       "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.27",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.29",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.27",
+      "ref": "@blamejs/pki@0.1.29",
       "dependsOn": []
     }
   ]