@blamejs/pki 0.8.31 → 0.8.48

package/lib/lint.js

@@ -3972,6 +3972,89 @@ var RFC9881_RULES = [
 var RFC9909_RULES = [
   _pqcSigKeyUsageRule("lint/rfc9909/slhdsa-key-usage", "rfc9909", "RFC 9909 6", "SLH-DSA", _isSlhDsa),
 ];
+/** @internal Section 4.1 states the criticality at SHOULD NOT ("This extension SHOULD NOT be marked
+ * critical", the section adding that marking it "would severely impact interoperability"), so it is
+ * graded at warn here rather than held to a value by the shared criticality table, which carries only
+ * the MUSTs. The same reason keeps issuerAltName out of the CRL table. Placement is a MUST in the same
+ * section: "For certificate chains, this extension MUST only be included in the end-entity
+ * certificate", so the two clauses are two rows at two strengths. */
+var OID_SAPKI = oid.byName("subjectAltPublicKeyInfo");
+var OID_ALT_ALG = oid.byName("altSignatureAlgorithm");
+var OID_ALT_VAL = oid.byName("altSignatureValue");
+/** @internal ITU-T X.509 (2019) clause 9.8. Two clauses at two strengths, and the difference matters.
+ * Clause 9.8.3 states the pairing as a shall: "When the altSignatureAlgorithm extension is included in
+ * a particular value that is an instance of a data type that supports extensions, the altSignatureValue
+ * extension shall also be included." Clause 7.2.2 requires the full set in a certificate: one "shall
+ * contain alternative public key information in the subjectAltPublicKeyInfo extension ..., an
+ * alternative signature algorithm value in the altSignatureAlgorithm extension ... and an alternative
+ * signature value in the altSignatureValue extension". Criticality is stated only in NOTEs recommending
+ * non-critical, with the clauses saying the extensions "may be flagged as critical or as non-critical",
+ * so that row is a warning and never an error: grading a NOTE as an error would invent a requirement
+ * level the text does not state. */
+var X509_ALTSIG_RULES = [
+  {
+    id: "lint/x509-altsig/algorithm-without-value", severity: "error", source: "x509-altsig", citation: "ITU-T X.509 (2019) 9.8.3",
+    message: "a value carrying altSignatureAlgorithm must also carry altSignatureValue",
+    appliesTo: function (cert, ctx) { return !!ctx.raw("altSignatureAlgorithm"); },
+    check: function (cert, ctx) {
+      return ctx.raw("altSignatureValue") ? null : { context: { present: "altSignatureAlgorithm", missing: "altSignatureValue" } };
+    },
+  },
+  {
+    id: "lint/x509-altsig/value-without-algorithm", severity: "error", source: "x509-altsig", citation: "ITU-T X.509 (2019) 9.8.3",
+    message: "a value carrying altSignatureValue must also carry altSignatureAlgorithm, which states how to verify it",
+    appliesTo: function (cert, ctx) { return !!ctx.raw("altSignatureValue"); },
+    check: function (cert, ctx) {
+      return ctx.raw("altSignatureAlgorithm") ? null : { context: { present: "altSignatureValue", missing: "altSignatureAlgorithm" } };
+    },
+  },
+  {
+    id: "lint/x509-altsig/incomplete-set", severity: "error", source: "x509-altsig", citation: "ITU-T X.509 (2019) 7.2.2",
+    message: "a certificate carrying the alternative cryptographic algorithm extensions must carry all three",
+    appliesTo: function (cert, ctx) {
+      return !!(ctx.raw("subjectAltPublicKeyInfo") || ctx.raw("altSignatureAlgorithm") || ctx.raw("altSignatureValue"));
+    },
+    check: function (cert, ctx) {
+      var missing = ["subjectAltPublicKeyInfo", "altSignatureAlgorithm", "altSignatureValue"]
+        .filter(function (n) { return !ctx.raw(n); });
+      return missing.length ? { context: { missing: missing.join(", ") } } : null;
+    },
+  },
+  {
+    id: "lint/x509-altsig/critical", severity: "warn", source: "x509-altsig", citation: "ITU-T X.509 (2019) 9.8.2 / 9.8.3",
+    message: "the alternative cryptographic algorithm extensions are recommended non-critical",
+    check: function (cert) {
+      var rows = [];
+      (cert.extensions || []).forEach(function (e) {
+        if (e.critical !== true) return;
+        if (e.oid !== OID_SAPKI && e.oid !== OID_ALT_ALG && e.oid !== OID_ALT_VAL) return;
+        rows.push({ context: { extension: e.name || e.oid, recommended: "non-critical", was: "critical" } });
+      });
+      return rows.length ? rows : null;
+    },
+  },
+];
+
+var RFC9763_RULES = [
+  {
+    id: "lint/rfc9763/related-certificate-critical", severity: "warn", source: "rfc9763", citation: "RFC 9763 4.1",
+    message: "the relatedCertificate extension should not be marked critical",
+    appliesTo: function (cert, ctx) { return !!ctx.raw("relatedCertificate"); },
+    check: function (cert, ctx) {
+      var e = ctx.raw("relatedCertificate");
+      return e.critical === true ? { context: { extension: "relatedCertificate", recommended: "non-critical", was: "critical" } } : null;
+    },
+  },
+  {
+    id: "lint/rfc9763/related-certificate-on-ca", severity: "error", source: "rfc9763", citation: "RFC 9763 4.1",
+    message: "the relatedCertificate extension must only be included in the end-entity certificate",
+    appliesTo: function (cert, ctx) { return !!ctx.raw("relatedCertificate"); },
+    check: function (cert, ctx) {
+      var bc = ctx.decode("basicConstraints");
+      return (bc && bc.value && bc.value.cA === true) ? { context: { extension: "relatedCertificate", cA: true } } : null;
+    },
+  },
+];
 
 /** @internal RFC 5280 sec. 5 states the criticality of each CRL extension it profiles, and sec. 5.3
  * does the same for the entry extensions. certificateIssuer is critical (sec. 5.3.3) because a
@@ -6329,6 +6412,8 @@ var PROFILES = Object.assign(Object.create(null), {
   "rfc9881": RFC9881_RULES.concat(RFC5280_EXTENSION_SYNTAX_RULES),
   "rfc9909": RFC9909_RULES.concat(RFC5280_EXTENSION_SYNTAX_RULES),
   "rfc9935": RFC9935_RULES.concat(RFC5280_EXTENSION_SYNTAX_RULES),
+  "rfc9763": RFC9763_RULES.concat(RFC5280_EXTENSION_SYNTAX_RULES),
+  "x509-altsig": X509_ALTSIG_RULES.concat(RFC5280_EXTENSION_SYNTAX_RULES),
   "cabf-tls": CABF_TLS_RULES.concat(RFC5280_EXTENSION_SYNTAX_RULES),
   "cabf-smime": CABF_SMIME_RULES.concat(RFC5280_EXTENSION_SYNTAX_RULES),
   "cabf-cs": CABF_CS_RULES.concat(RFC5280_EXTENSION_SYNTAX_RULES),
@@ -6351,6 +6436,7 @@ var PROFILES = Object.assign(Object.create(null), {
     .concat(RFC5280_EXTENSION_SYNTAX_RULES),
 });
 var ALL_RULES = RFC5280_RULES.concat(RFC9881_RULES).concat(RFC9909_RULES).concat(RFC9935_RULES)
+  .concat(RFC9763_RULES).concat(X509_ALTSIG_RULES)
   .concat(CABF_TLS_RULES).concat(CABF_SMIME_RULES).concat(CABF_CS_RULES).concat(ETSI_QC_RULES)
   /** @internal The root-program rows are in the registry so `rules()` enumerates them, and stay
    * inert under the default set because each one asks whether the caller named the profile. */
@@ -6363,11 +6449,89 @@ var CABF_TLS_CSR_RULES = CABF_TLS_RULES.filter(function (r) {
 /** @internal A requested extension whose value does not decode is the same fault in a request as
  *  in a certificate, so the request profiles take the same row the certificate profiles do. */
 var CSR_STRUCTURAL_RULES = RFC2986_CSR_RULES.concat(RFC5280_EXTENSION_SYNTAX_RULES);
+
+var OID_SOP_ATTR = oid.byName("statementOfPossession");
+var SOP_SIGNATURE_USAGES = ["digitalSignature", "nonRepudiation", "keyCertSign", "cRLSign"];
+/** @internal RFC 9883 sec. 6 states one prohibition outright: "The privateKeyPossessionStatement
+ * attribute MUST NOT be used to obtain a signature certificate." Sec. 4 states the same requirement as a
+ * property of the request: "the subjectPKInfo MUST contain the public key for the key establishment
+ * algorithm". The attribute exists so a key-establishment key, which cannot sign, can still be certified;
+ * a request carrying it while asking for a signature key usage, or naming a subject key that can only
+ * sign, is asking for the certificate those sentences forbid. The two name comparisons sec. 3 states are
+ * deliberately absent here: each ends in "the certificate policy MUST describe how the CA can determine
+ * that the two subject names identify the same entity", which is a question no linter can answer, and
+ * `pki.possession.verifyRequest` reports the comparison for a caller's policy to resolve. */
+function _csrHasPossessionStatement(csr) {
+  return (csr.attributes || []).some(function (a) { return a.type === OID_SOP_ATTR; });
+}
+/** @internal The same table `pki.possession.verifyRequest` reads, so the linter and the verifier grade one
+ *  request alike. Read off the requested key usages alone, this row passed a request that named no usage
+ *  while asking to certify a key that can only ever sign, which is the sec. 4 MUST on the subjectPKInfo and
+ *  the sec. 6 prohibition both, and which the verifier refuses; `pki.csr.sign` under this profile then
+ *  emitted it. */
+var _isSignatureOnlyKey = pkix.signatureOnlyKeyOid(NS);
+function _csrSubjectKeyOid(csr) {
+  return csr.subjectPublicKeyInfo && csr.subjectPublicKeyInfo.algorithm
+    ? csr.subjectPublicKeyInfo.algorithm.oid : null;
+}
+var RFC9883_CSR_RULES = [
+  {
+    id: "lint/rfc9883/signature-certificate-requested", severity: "error", source: "rfc9883", citation: "RFC 9883 4 and 6",
+    message: "a request carrying a possession statement must not ask for a signature certificate",
+    appliesTo: function (csr) { return _csrHasPossessionStatement(csr); },
+    check: function (csr, ctx) {
+      /** @internal The subject key decides on its own when it can only sign, so this is read whether or
+       *  not the request names a usage. A key that can do either says nothing here and is judged by the
+       *  usages the request asks for. */
+      var keyOid = _csrSubjectKeyOid(csr);
+      if (_isSignatureOnlyKey(keyOid)) {
+        return { context: { subjectKeyAlgorithm: oid.name(keyOid) || keyOid } };
+      }
+      var ku = ctx.decode("keyUsage");
+      var value = ku && ku.value;
+      if (!value) return null;
+      var asked = SOP_SIGNATURE_USAGES.filter(function (u) { return value[u] === true; });
+      return asked.length ? { context: { keyUsage: asked.join(", ") } } : null;
+    },
+  },
+  {
+    id: "lint/rfc9883/statement-value-undecodable", severity: "error", source: "rfc9883", citation: "RFC 9883 3",
+    message: "a statementOfPossession attribute value must be a well-formed PrivateKeyPossessionStatement",
+    appliesTo: function (csr) { return _csrHasPossessionStatement(csr); },
+    check: function (csr) {
+      var rows = [];
+      (csr.attributes || []).forEach(function (a) {
+        if (a.type !== OID_SOP_ATTR) return;
+        if (a.privateKeyPossessionStatement === undefined) {
+          rows.push({ context: { attribute: a.name || a.type } });
+        }
+      });
+      return rows.length ? rows : null;
+    },
+  },
+  /** @internal Sec. 3 states the attribute's syntax in the singular and nothing anywhere in RFC 9883 says
+   *  which of several a CA should honor, so a request carrying more than one leaves every check sec. 3 asks
+   *  for without a subject: the checks would be made against one statement while the CA certifies a request
+   *  that carries another naming a different certificate. `pki.possession.verifyRequest` refuses such a
+   *  request with `possession/bad-request`, and without this row the linter graded it conforming and
+   *  `pki.csr.sign` under this profile would emit it. */
+  {
+    id: "lint/rfc9883/statement-attribute-repeated", severity: "error", source: "rfc9883", citation: "RFC 9883 3",
+    message: "a request must carry one statementOfPossession attribute, not several",
+    appliesTo: function (csr) { return _csrHasPossessionStatement(csr); },
+    check: function (csr) {
+      var count = 0;
+      (csr.attributes || []).forEach(function (a) { if (a.type === OID_SOP_ATTR) count += 1; });
+      return count > 1 ? { context: { attributes: String(count) } } : null;
+    },
+  },
+];
 var CSR_PROFILES = Object.assign(Object.create(null), {
   "rfc2986": CSR_STRUCTURAL_RULES,
   "cabf-tls": CSR_STRUCTURAL_RULES.concat(CABF_TLS_CSR_RULES),
+  "rfc9883": RFC9883_CSR_RULES.concat(RFC5280_EXTENSION_SYNTAX_RULES),
 });
-var ALL_CSR_RULES = CSR_STRUCTURAL_RULES;
+var ALL_CSR_RULES = CSR_STRUCTURAL_RULES.concat(RFC9883_CSR_RULES);
 
 function _subjectIsNonEmpty(csr) {
   var rdns = csr.subject && csr.subject.rdns;

package/lib/merkle.js

@@ -42,34 +42,59 @@
  *   `verifyConsistency` over sync SHA-256, fail-closed, transport-free.
  */
 
-var nodeCrypto = require("node:crypto");
 var constants = require("./constants");
 var frameworkError = require("./framework-error");
 var guard = require("./guard-all");
+var intrinsic = require("./guard-intrinsic");
+
+/** @internal The operations this module decides with, bound at load. A proof is assembled by
+ *  concatenation, so a replaced `Array.prototype.concat` chooses which nodes the proof carries and in
+ *  what order, and a replaced `Buffer.concat` chooses the bytes a node hash covers. Taking the captures
+ *  also puts this file in the live-read gate's scope, which is how it stays converted. */
+var _concat = intrinsic.concat;
+var _bufferConcat = intrinsic.bufferConcat;
+var _bufferFrom = intrinsic.bufferFrom;
+var _bufferAlloc = intrinsic.bufferAlloc;
+var _isArray = intrinsic.isArray;
+var _assign = intrinsic.assign;
+var _create = intrinsic.create;
+var _BigInt = intrinsic.BigInt;
 
 var MerkleError = frameworkError.MerkleError;
 
 function _merkleErr(c, m) { return new MerkleError(c, m); }
 
 var SHA256_BYTES = 32;
-var LEAF_PREFIX = Buffer.from([0x00]);
-var NODE_PREFIX = Buffer.from([0x01]);
-var EMPTY = Buffer.alloc(0);
+var LEAF_PREFIX = _bufferFrom([0x00]);
+var NODE_PREFIX = _bufferFrom([0x01]);
+var EMPTY = _bufferAlloc(0);
 
 function _sha256(buf) {
-  return nodeCrypto.createHash("sha256").update(buf).digest();
+  return guard.crypto.digest("sha256", buf);
 }
 
+/** @internal A COPY, not a view. Reading each slot once is not enough when what is read shares the
+ *  caller's store: a getter handing out one scratch buffer per leaf satisfies the read-once rule and still
+ *  leaves every collected leaf pointing at the same bytes, so collecting the second overwrote the first
+ *  and the root of [A, B] came out as the root of [B, B] with nothing reporting it. Each value is 32 bytes
+ *  by the check above, so copying costs nothing worth measuring, and every byte this module folds, hashes
+ *  or compares is then its own. */
 function _toBuffer(v, field) {
-  return guard.bytes.view(v, MerkleError, "merkle/bad-input", field);
+  return guard.bytes.snapshot(v, MerkleError, "merkle/bad-input", field);
 }
 
+/** @internal The width is read on a VIEW, before the copy. A node is exactly 32 bytes, and the check
+ *  enforcing that ran on the copy, so a value handed where a hash belongs was duplicated in full and
+ *  only then refused: measured, `root([Buffer.alloc(64 * 1024 * 1024)])` allocated another 64 MiB to
+ *  reject one leaf. Viewing allocates nothing, and the size comes off the view rather than off the
+ *  caller's own `length`, which can be shadowed independently of the bytes. */
 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);
+  var viewed = guard.bytes.source(v, MerkleError, "merkle/bad-input", field);
+  var size = guard.bytes.lengthOf(viewed);
+  if (size !== SHA256_BYTES) {
+    throw new MerkleError("merkle/bad-hash-length", field + " must be exactly 32 bytes, got " + size);
   }
-  return buf;
+  return guard.bytes.snapshot(viewed, MerkleError, "merkle/bad-input", field);
 }
 
 function _coerceCoord(v, field) {
@@ -77,19 +102,86 @@ function _coerceCoord(v, field) {
 }
 
 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;
+  if (!_isArray(proof)) throw new MerkleError("merkle/bad-proof", "proof must be an array");
+  /** @internal Through the same guard as the leaf array, for the same reason: the node cap reads the
+   *  length and a hand-rolled walk reads it again. The verifiers were not exposed the way the producers
+   *  were, because a proof the walk collected short folds to a root that does not match the one supplied,
+   *  so the comparison refuses it. That is fail-closed by consequence rather than by rule, and the rule is
+   *  cheaper to keep here than to re-derive at each verifier. */
+  return guard.list.copyMap(proof, function (slot, i) { return _node32(slot, "proof[" + i + "]"); },
+    function (n) {
+      if (n > constants.LIMITS.MERKLE_MAX_PROOF_NODES) {
+        throw new MerkleError("merkle/proof-too-large",
+          "proof has " + n + " nodes, exceeds " + constants.LIMITS.MERKLE_MAX_PROOF_NODES);
+      }
+    });
 }
 
 function _ctEq(a, b) {
   return guard.crypto.constantTimeEqual(a, b);
 }
 
+var NO_CONSISTENCY_CLAIM =
+  "an empty older tree (oldSize 0) makes no consistency claim about a non-empty newer tree: " +
+  "RFC 6962 sec. 2.1.2 defines the proof for 0 < oldSize < newSize, and nothing here binds " +
+  "newRoot. Verify an inclusion proof against the new tree, or start from a signed tree head " +
+  "you already trust";
+
+/** @internal Each slot is read once, into the buffer the length check and every later fold both
+ *  use, so an array whose accessor answers differently on a second read cannot put one value past
+ *  the check and a different one into the tree. The COUNT is read once as well, by
+ *  `guard.list.copyMap`, which is the point of going through it: a hand-rolled
+ *  `for (i = 0; i < v.length; i++)` re-reads the length after every slot access, so a getter on one slot
+ *  that shortened the array left the cap approving four leaves and the walk collecting one, and the root
+ *  committed to a tree the caller never supplied. A slot past a length that shrank reads as undefined and
+ *  `_node32` refuses it, so the array is refused rather than folded short. */
+function _leafArray(v, field) {
+  if (!_isArray(v)) {
+    throw new MerkleError("merkle/bad-input", field + " must be an array of 32-byte leaf hashes");
+  }
+  return guard.list.copyMap(v, function (slot, i) { return _node32(slot, field + "[" + i + "]"); },
+    function (n) {
+      if (n > constants.LIMITS.MERKLE_MAX_LEAVES) {
+        throw new MerkleError("merkle/too-many-leaves",
+          field + " holds " + n + " leaves, exceeds " + constants.LIMITS.MERKLE_MAX_LEAVES);
+      }
+    });
+}
+
+/** @internal RFC 6962 sec. 2.1's "largest power of two smaller than n", for n >= 2. Doubled from
+ *  1 rather than derived through a logarithm: the leaf count is bounded well inside the exact
+ *  integer range, and a float log would round at the boundary sizes this splits on. */
+function _splitPoint(n) {
+  var k = 1;
+  while (k * 2 < n) k *= 2;
+  return k;
+}
+
+/** @internal MTH(D[lo:hi]) for hi > lo. The empty tree is answered by the caller. */
+function _mth(leaves, lo, hi) {
+  if (hi - lo === 1) return leaves[lo];
+  var k = _splitPoint(hi - lo);
+  return nodeHash(_mth(leaves, lo, lo + k), _mth(leaves, lo + k, hi));
+}
+
+/** @internal PATH(m, D[lo:hi]) of RFC 6962 sec. 2.1.1, with m relative to lo. */
+function _path(leaves, lo, hi, m) {
+  if (hi - lo === 1) return [];
+  var k = _splitPoint(hi - lo);
+  if (m < k) return _concat(_path(leaves, lo, lo + k, m), [_mth(leaves, lo + k, hi)]);
+  return _concat(_path(leaves, lo + k, hi, m - k), [_mth(leaves, lo, lo + k)]);
+}
+
+/** @internal SUBPROOF(m, D[lo:hi], b) of RFC 6962 sec. 2.1.2, with m relative to lo. The split
+ *  compares m <= k here where PATH compares m < k, which is what puts the old tree's own root in
+ *  the proof exactly when the caller did not already hold it. */
+function _subproof(leaves, lo, hi, m, b) {
+  if (m === hi - lo) return b ? [] : [_mth(leaves, lo, hi)];
+  var k = _splitPoint(hi - lo);
+  if (m <= k) return _concat(_subproof(leaves, lo, lo + k, m, b), [_mth(leaves, lo + k, hi)]);
+  return _concat(_subproof(leaves, lo + k, hi, m - k, false), [_mth(leaves, lo, lo + k)]);
+}
+
 /**
  * @primitive  pki.merkle.leafHash
  * @signature  pki.merkle.leafHash(entry) -> Buffer
@@ -107,7 +199,7 @@ function _ctEq(a, b) {
  */
 function leafHash(entry) {
   var e = _toBuffer(entry, "entry");
-  return _sha256(Buffer.concat([LEAF_PREFIX, e]));
+  return _sha256(_bufferConcat([LEAF_PREFIX, e]));
 }
 
 /**
@@ -131,7 +223,7 @@ function leafHash(entry) {
 function nodeHash(left, right) {
   var l = _node32(left, "left");
   var r = _node32(right, "right");
-  return _sha256(Buffer.concat([NODE_PREFIX, l, r]));
+  return _sha256(_bufferConcat([NODE_PREFIX, l, r]));
 }
 
 /**
@@ -180,7 +272,7 @@ function emptyRootHash() {
  *   var lh = pki.merkle.leafHash(Buffer.from([0]));
  *   pki.merkle.verifyInclusion({ leafIndex: 0, treeSize: 1, leafHash: lh, proof: [], rootHash: lh }); // -> true
  */
-var _INCLUSION_KEYS = Object.assign(Object.create(null), { leafIndex: 1, treeSize: 1, leafHash: 1, rootHash: 1, proof: 1 });
+var _INCLUSION_KEYS = _assign(_create(null), { leafIndex: 1, treeSize: 1, leafHash: 1, rootHash: 1, proof: 1 });
 function verifyInclusion(opts) {
   opts = opts || {};
   guard.identifier.assertKnownKeys(opts, _INCLUSION_KEYS, function (c, m) { return new MerkleError(c, m); },
@@ -252,7 +344,7 @@ function verifyInclusion(opts) {
  *   var r = pki.merkle.leafHash(Buffer.from([0]));
  *   pki.merkle.verifyConsistency({ oldSize: 1, newSize: 1, oldRoot: r, newRoot: r, proof: [] }); // -> true
  */
-var _CONSISTENCY_KEYS = Object.assign(Object.create(null), { oldSize: 1, newSize: 1, oldRoot: 1, newRoot: 1, proof: 1 });
+var _CONSISTENCY_KEYS = _assign(_create(null), { oldSize: 1, newSize: 1, oldRoot: 1, newRoot: 1, proof: 1 });
 function verifyConsistency(opts) {
   opts = opts || {};
   guard.identifier.assertKnownKeys(opts, _CONSISTENCY_KEYS, function (c, m) { return new MerkleError(c, m); },
@@ -271,11 +363,7 @@ function verifyConsistency(opts) {
       // allow:constant-time-compare-short-circuited -- oldRoot, newRoot, and er are public Merkle tree roots, not secrets, so short-circuiting the second compare leaks nothing confidential
       return _ctEq(oldRoot, er) && _ctEq(newRoot, er);
     }
-    throw new MerkleError("merkle/no-consistency-claim",
-      "an empty older tree (oldSize 0) makes no consistency claim about a non-empty newer tree: " +
-      "RFC 6962 sec. 2.1.2 defines the proof for 0 < oldSize < newSize, and nothing here binds " +
-      "newRoot. Verify an inclusion proof against the new tree, or start from a signed tree head " +
-      "you already trust");
+    throw new MerkleError("merkle/no-consistency-claim", NO_CONSISTENCY_CLAIM);
   }
   if (oldSize === newSize) {
     if (proof.length !== 0) throw new MerkleError("merkle/sizes-equal-nonempty-proof", "equal tree sizes require an empty consistency proof");
@@ -285,7 +373,7 @@ function verifyConsistency(opts) {
 
   var path = proof;
   if ((oldSize & (oldSize - 1n)) === 0n) {
-    path = [oldRoot].concat(proof);
+    path = _concat([oldRoot], proof);
   }
   var fn = oldSize - 1n;
   var sn = newSize - 1n;
@@ -313,10 +401,128 @@ function verifyConsistency(opts) {
   return okOld && okNew;
 }
 
+/**
+ * @primitive  pki.merkle.root
+ * @signature  pki.merkle.root(leafHashes) -> Buffer
+ * @since      0.8.34
+ * @status     stable
+ * @spec       RFC 6962, RFC 9162
+ * @related    pki.merkle.leafHash, pki.merkle.inclusionProof, pki.merkle.verifyInclusion
+ *
+ * The RFC 6962 Merkle Tree Hash `MTH(D[n])` over a whole tree, returned as a
+ * 32-byte root ready to pass to `verifyInclusion` as `rootHash`. Takes leaf
+ * HASHES, the same form `verifyInclusion` takes as `leafHash`; map entries
+ * through `pki.merkle.leafHash` first. An empty array is the empty tree and
+ * returns `emptyRootHash()`.
+ *
+ * Throws `merkle/bad-input` if `leafHashes` is not an array or a leaf is not a
+ * Buffer / Uint8Array, `merkle/bad-hash-length` if a leaf is not exactly 32
+ * bytes, and `merkle/too-many-leaves` above `C.LIMITS.MERKLE_MAX_LEAVES`.
+ *
+ * @example
+ *   var leaves = [Buffer.from([0]), Buffer.from([1])].map(pki.merkle.leafHash);
+ *   pki.merkle.root(leaves); // -> <Buffer 32-byte tree head>
+ */
+function root(leafHashes) {
+  var leaves = _leafArray(leafHashes, "leafHashes");
+  if (leaves.length === 0) return emptyRootHash();
+  return _mth(leaves, 0, leaves.length);
+}
+
+/**
+ * @primitive  pki.merkle.inclusionProof
+ * @signature  pki.merkle.inclusionProof(opts) -> Buffer[]
+ * @since      0.8.34
+ * @status     stable
+ * @spec       RFC 6962, RFC 9162
+ * @related    pki.merkle.verifyInclusion, pki.merkle.root
+ *
+ * Produce the RFC 6962 sec. 2.1.1 audit path `PATH(leafIndex, D[n])` for one
+ * leaf of a tree held in memory. The returned array is the `proof` that
+ * `verifyInclusion` folds against `root(leafHashes)`.
+ *
+ * The tree size is the length of `leafHashes` and is not a separate option, so
+ * a size and a leaf array cannot disagree. Throws `merkle/empty-tree` on an
+ * empty tree, `merkle/index-out-of-range` for a `leafIndex` at or above the leaf
+ * count, and the `leafHashes` errors `root` throws.
+ *
+ * @opts
+ *   leafHashes:  Buffer[],       // the whole tree, each leaf a 32-byte hash
+ *   leafIndex:   number | bigint, // 0-based position of the leaf to prove
+ *
+ * @example
+ *   var leaves = [Buffer.from([0]), Buffer.from([1])].map(pki.merkle.leafHash);
+ *   pki.merkle.inclusionProof({ leafHashes: leaves, leafIndex: 0 }); // -> [<Buffer ...>]
+ */
+var _INCLUSION_PROOF_KEYS = _assign(_create(null), { leafHashes: 1, leafIndex: 1 });
+function inclusionProof(opts) {
+  opts = opts || {};
+  guard.identifier.assertKnownKeys(opts, _INCLUSION_PROOF_KEYS, _merkleErr,
+    "merkle/bad-input", "unknown inclusionProof option ");
+  var leaves = _leafArray(opts.leafHashes, "leafHashes");
+  var n = leaves.length;
+  if (n === 0) throw new MerkleError("merkle/empty-tree", "an empty tree has no leaves to include");
+  var leafIndex = _coerceCoord(opts.leafIndex, "leafIndex");
+  var m = guard.range.int(leafIndex, 0n, _BigInt(n - 1), _merkleErr,
+    "merkle/index-out-of-range", "leafIndex");
+  return _path(leaves, 0, n, m);
+}
+
+/**
+ * @primitive  pki.merkle.consistencyProof
+ * @signature  pki.merkle.consistencyProof(opts) -> Buffer[]
+ * @since      0.8.34
+ * @status     stable
+ * @spec       RFC 6962, RFC 9162
+ * @related    pki.merkle.verifyConsistency, pki.merkle.root
+ *
+ * Produce the RFC 6962 sec. 2.1.2 consistency proof `PROOF(oldSize, D[n])`
+ * between an older tree of `oldSize` leaves and the tree held in `leafHashes`.
+ * The returned array is the `proof` that `verifyConsistency` checks against
+ * `root(leafHashes.slice(0, oldSize))` and `root(leafHashes)`.
+ *
+ * The newer size is the length of `leafHashes` and is not a separate option.
+ * Equal sizes produce the empty proof, which is what the verifier requires
+ * there. Throws `merkle/old-size-exceeds-new` when `oldSize` is past the leaf
+ * count and `merkle/no-consistency-claim` for an `oldSize` of 0 against a
+ * non-empty tree, matching `verifyConsistency`: RFC 6962 sec. 2.1.2 defines the
+ * proof for `0 < oldSize < newSize`, so there is no proof to produce.
+ *
+ * @opts
+ *   leafHashes:  Buffer[],        // the newer tree, each leaf a 32-byte hash
+ *   oldSize:     number | bigint, // leaf count of the older tree
+ *
+ * @example
+ *   var leaves = [Buffer.from([0]), Buffer.from([1])].map(pki.merkle.leafHash);
+ *   pki.merkle.consistencyProof({ leafHashes: leaves, oldSize: 1 }); // -> [<Buffer ...>]
+ */
+var _CONSISTENCY_PROOF_KEYS = _assign(_create(null), { leafHashes: 1, oldSize: 1 });
+function consistencyProof(opts) {
+  opts = opts || {};
+  guard.identifier.assertKnownKeys(opts, _CONSISTENCY_PROOF_KEYS, _merkleErr,
+    "merkle/bad-input", "unknown consistencyProof option ");
+  var leaves = _leafArray(opts.leafHashes, "leafHashes");
+  var n = leaves.length;
+  var oldSize = _coerceCoord(opts.oldSize, "oldSize");
+  if (oldSize > _BigInt(n)) {
+    throw new MerkleError("merkle/old-size-exceeds-new", "oldSize " + oldSize + " exceeds newSize " + n);
+  }
+  if (oldSize === 0n) {
+    if (n === 0) return [];
+    throw new MerkleError("merkle/no-consistency-claim", NO_CONSISTENCY_CLAIM);
+  }
+  var m = guard.range.int(oldSize, 1n, _BigInt(n), _merkleErr, "merkle/bad-input", "oldSize");
+  if (m === n) return [];
+  return _subproof(leaves, 0, n, m, true);
+}
+
 module.exports = {
   leafHash:          leafHash,
   nodeHash:          nodeHash,
   emptyRootHash:     emptyRootHash,
+  root:              root,
   verifyInclusion:   verifyInclusion,
   verifyConsistency: verifyConsistency,
+  inclusionProof:    inclusionProof,
+  consistencyProof:  consistencyProof,
 };