@blamejs/pki 0.1.32 → 0.2.1

package/lib/schema-pkix.js

@@ -47,11 +47,8 @@ function pemDecode(text, label, PemError) {
   if (!m) throw new PemError("pem/no-block", "no PEM block found");
   if (label && m[1] !== label) throw new PemError("pem/label-mismatch", "expected " + JSON.stringify(label) + " block, got " + JSON.stringify(m[1]));
   var b64 = m[2].replace(/[\r\n\t ]+/g, "");
-  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(b64)) throw new PemError("pem/bad-base64", "PEM body is not valid base64");
-  if (b64.length % 4 !== 0) throw new PemError("pem/bad-base64", "PEM base64 body must be whole 4-character groups (RFC 4648 sec. 3.5)");
-  var der = Buffer.from(b64, "base64");
-  if (der.toString("base64") !== b64) throw new PemError("pem/bad-base64", "PEM base64 body is not canonical (RFC 4648 sec. 3.5)");
-  return der;
+  // Strict canonical base64 (RFC 4648 sec. 3.5) via the shared encoding guard.
+  return guard.encoding.base64(b64, null, function (c, msg) { return new PemError(c, msg); }, "pem/bad-base64", "PEM base64 body");
 }
 
 // pemDecodeAll(text, label, PemError): decode EVERY PEM block under the STRICT
@@ -72,10 +69,7 @@ function pemDecodeAll(text, label, PemError) {
     if (/\S/.test(text.slice(lastEnd, m.index))) throw new PemError("pem/explanatory-text", "explanatory text is not permitted around PEM blocks (RFC 8555 sec. 9.1)");
     if (m[1] !== label) throw new PemError("pem/label-mismatch", "expected " + JSON.stringify(label) + " block, got " + JSON.stringify(m[1]));
     var b64 = m[2].replace(/[\r\n\t ]+/g, "");
-    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(b64) || b64.length % 4 !== 0) throw new PemError("pem/bad-base64", "PEM body is not canonical base64 (RFC 4648 sec. 3.5)");
-    var der = Buffer.from(b64, "base64");
-    if (der.toString("base64") !== b64) throw new PemError("pem/bad-base64", "PEM base64 body is not canonical (RFC 4648 sec. 3.5)");
-    blocks.push(der);
+    blocks.push(guard.encoding.base64(b64, null, function (c, msg) { return new PemError(c, msg); }, "pem/bad-base64", "PEM base64 body"));
     lastEnd = re.lastIndex;
   }
   if (blocks.length === 0) throw new PemError("pem/no-block", "no PEM block found");
@@ -92,7 +86,10 @@ function pemEncode(der, label, PemError) {
   if (typeof label !== "string" || !/^[A-Z0-9]+( [A-Z0-9]+)*$/.test(label)) {
     throw new PemError("pem/bad-label", "pemEncode requires an uppercase A-Z0-9 label with single spaces");
   }
-  var buf = Buffer.isBuffer(der) ? der : Buffer.from(der);
+  // Re-view through the byte guard: a string input would silently utf8-armor into
+  // a bogus PEM, and a detached-backed Buffer would armor an empty body -- both
+  // fail closed (a Uint8Array / Buffer of real DER re-views cleanly).
+  var buf = guard.bytes.view(der, PemError, "pem/bad-input", "pemEncode DER input");
   var b64 = buf.toString("base64").replace(/(.{64})/g, "$1\n").replace(/\n$/, "");
   return "-----BEGIN " + label + "-----\n" + b64 + "\n-----END " + label + "-----\n";
 }
@@ -270,10 +267,12 @@ function attrValueToString(ns) {
     if (typeof value === "string" && value.charAt(0) === "\\") return asn1.build.utf8(value.slice(1));
     if (typeof value === "string" && value.charAt(0) === "#") {
       var hex = value.slice(1);
-      if (!/^(?:[0-9A-Fa-f]{2})+$/.test(hex)) {
+      if (hex.length === 0) {
         throw ns.E(ns.prefix + "/bad-atv", "a #hex attribute value must be a non-empty even run of hex digits (RFC 4514 sec. 2.4)");
       }
-      var raw = Buffer.from(hex, "hex");
+      // Strict canonical hex via the shared encoding guard (even-length, canonical,
+      // no silent truncation at the first non-hex character).
+      var raw = guard.encoding.hex(hex, null, ns.E, ns.prefix + "/bad-atv", "a #hex attribute value");
       try { asn1.decode(raw); }
       catch (e) { throw ns.E(ns.prefix + "/bad-atv", "a #hex attribute value must encode exactly one DER TLV", e); }
       return raw;
@@ -550,6 +549,36 @@ function generalNames(ns, opts) {
   return schema.seqOf(gn, { assert: "sequence", min: 1, code: code, what: opts.what || "GeneralNames", build: build });
 }
 
+// DistributionPointName ::= CHOICE { fullName [0] IMPLICIT GeneralNames,
+// nameRelativeToCRLIssuer [1] IMPLICIT RelativeDistinguishedName } (RFC 5280
+// sec. 4.2.1.13). The caller hands the CHOICE node itself -- the alternative
+// INSIDE the [0]-tagged distributionPoint field wrapper (a context tag on a
+// CHOICE-typed field is always EXPLICIT, so the wire nests [0]{ [0]|[1] ... }).
+// fullName surfaces each element's RAW GeneralName DER as { kind: "fullName",
+// names: [Buffer, ...] } -- the byte-exact comparison key the sec. 5.2.5
+// "identical encoding MUST be used" correspondence rule requires;
+// nameRelativeToCRLIssuer surfaces its full [1]-tagged TLV as { kind: "rdn",
+// bytes: Buffer } (byte-identical [1] TLVs are byte-identical RDN fragments).
+// An empty fullName (GeneralNames is SIZE 1..MAX), a malformed element, or any
+// other alternative throws the caller's `code`. Shared by the
+// cRLDistributionPoints / freshestCRL extension decoders and the CRL checker's
+// IssuingDistributionPoint decode, so the two sides of the sec. 6.3.3(b)(2)(i)
+// correspondence comparison cannot drift.
+function distributionPointName(ns, node, code) {
+  if (node && node.tagClass === "context" && node.tagNumber === 0) {
+    var gns = schema.walk(generalNames(ns, { implicitTag: 0, code: code, what: "DistributionPointName fullName" }), node, ns).result;
+    return { kind: "fullName", names: gns.names.map(function (n) { return n.bytes; }) };
+  }
+  if (node && node.tagClass === "context" && node.tagNumber === 1) {
+    // [1] IMPLICIT RelativeDistinguishedName -- the context tag replaces the
+    // SET tag, so the node's direct children are the AttributeTypeAndValues.
+    schema.walk(schema.implicitSetOf(1, attributeTypeAndValue(ns), {
+      min: 1, code: code, what: "DistributionPointName nameRelativeToCRLIssuer" }), node, ns);
+    return { kind: "rdn", bytes: node.bytes };
+  }
+  throw ns.E(code, "DistributionPointName must be fullName [0] or nameRelativeToCRLIssuer [1] (RFC 5280 sec. 4.2.1.13)");
+}
+
 // certExtensionDecoders(ns) -- the ns-parameterized RFC 5280 sec. 4.2.1 extension
 // VALUE decoders. `x509.parse` surfaces each extension as { oid, name, critical,
 // value } with `value` the raw inner OCTET-STRING content (a Buffer); the path
@@ -837,6 +866,54 @@ function certExtensionDecoders(ns) {
     return { poison: true };
   }
 
+  // cRLDistributionPoints ::= SEQUENCE SIZE (1..MAX) OF DistributionPoint
+  // (RFC 5280 sec. 4.2.1.13); DistributionPoint ::= SEQUENCE {
+  // distributionPoint [0] DistributionPointName OPTIONAL, reasons [1]
+  // ReasonFlags OPTIONAL, cRLIssuer [2] GeneralNames OPTIONAL }. "a
+  // DistributionPoint MUST NOT consist of only the reasons field; either
+  // distributionPoint or cRLIssuer MUST be present" -- a reasons-only (or
+  // empty) DistributionPoint is malformed. The DistributionPointName is
+  // surfaced through the shared helper (raw name encodings -- the sec. 5.2.5
+  // correspondence key); `reasons` stays a raw BIT STRING ({ unusedBits,
+  // bytes }); cRLIssuer is a validated GeneralNames with decoded values.
+  // FreshestCRL ::= CRLDistributionPoints (sec. 4.2.1.15), so the SAME decoder
+  // serves both OIDs -- one codec, both registry rows.
+  function crlDistributionPoints(buf) {
+    var C = ns.prefix + "/bad-crl-distribution-points";
+    var kids = seqChildren(buf, C, "CRLDistributionPoints");
+    if (kids.length < 1) throw ns.E(C, "CRLDistributionPoints must contain at least one DistributionPoint (RFC 5280 sec. 4.2.1.13)");
+    return kids.map(function (dp) {
+      if (dp.tagClass !== "universal" || dp.tagNumber !== _T.SEQUENCE || !dp.children) {
+        throw ns.E(C, "DistributionPoint must be a SEQUENCE { distributionPoint?, reasons?, cRLIssuer? }");
+      }
+      var out = { distributionPoint: null, reasons: null, cRLIssuer: null };
+      var lastTag = -1;
+      dp.children.forEach(function (f) {
+        if (f.tagClass !== "context") throw ns.E(C, "DistributionPoint fields are context-tagged [0]/[1]/[2]");
+        if (f.tagNumber <= lastTag) throw ns.E(C, "DistributionPoint fields must be unique and in ascending order (DER)");
+        lastTag = f.tagNumber;
+        if (f.tagNumber === 0) {
+          // distributionPoint [0] EXPLICIT-wraps the DistributionPointName CHOICE.
+          if (!f.children || f.children.length !== 1) throw ns.E(C, "DistributionPoint distributionPoint [0] must wrap exactly one DistributionPointName");
+          out.distributionPoint = distributionPointName(ns, f.children[0], C);
+        } else if (f.tagNumber === 1) {
+          var bs;
+          try { bs = asn1.read.bitStringImplicit(f, 1); }
+          catch (e) { throw ns.E(C, "DistributionPoint reasons [1] must be an IMPLICIT ReasonFlags BIT STRING", e); }
+          out.reasons = { unusedBits: bs.unusedBits, bytes: bs.bytes };
+        } else if (f.tagNumber === 2) {
+          out.cRLIssuer = schema.walk(generalNames(ns, { implicitTag: 2, decodeValue: true, code: C, what: "DistributionPoint cRLIssuer" }), f, ns).result;
+        } else {
+          throw ns.E(C, "DistributionPoint has an unexpected field [" + f.tagNumber + "]");
+        }
+      });
+      if (out.distributionPoint === null && out.cRLIssuer === null) {
+        throw ns.E(C, "a DistributionPoint must include distributionPoint or cRLIssuer -- it MUST NOT consist of only the reasons field (RFC 5280 sec. 4.2.1.13)");
+      }
+      return out;
+    });
+  }
+
   // byName returns undefined for an unregistered name; keying a decoder row
   // under "undefined" would silently drop that extension from dispatch (the
   // consumer would treat the extension as structurally unvalidated / absent),
@@ -861,6 +938,8 @@ function certExtensionDecoders(ns) {
   byOid[O("subjectKeyIdentifier")] = subjectKeyIdentifier;
   byOid[O("signedCertificateTimestampList")] = sctList;
   byOid[O("precertificatePoison")] = precertPoison;
+  byOid[O("cRLDistributionPoints")] = crlDistributionPoints;
+  byOid[O("freshestCRL")] = crlDistributionPoints;
   return { byOid: byOid };
 }
 
@@ -1069,6 +1148,7 @@ module.exports = {
   name: name,
   generalName: generalName,
   generalNames: generalNames,
+  distributionPointName: distributionPointName,
   generalizedTime: generalizedTime,
   utf8Text: utf8Text,
   rawNonEmptySequence: rawNonEmptySequence,

package/lib/shbs.js

@@ -0,0 +1,348 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module pki.shbs
+ * @nav        Signatures
+ * @title      Stateful hash-based
+ * @intro Stateful hash-based signature VERIFICATION -- HSS/LMS (RFC 8554),
+ *   carried in X.509 by RFC 9802 and in CMS by RFC 9708, profiled by NIST
+ *   SP 800-208. VERIFY ONLY, by deliberate design: stateful hash-based SIGNING
+ *   is catastrophic to get wrong -- each one-time key must be used exactly once,
+ *   so the private key embeds a monotonic index whose state must advance and
+ *   persist atomically across every signature and every process restart. A single
+ *   index reuse (a restored VM snapshot, a crashed writer, a concurrent signer)
+ *   forfeits security and can leak enough one-time-key material to forge, which is
+ *   why SP 800-208 sec. 8 constrains signing-state handling to hardware. So this
+ *   module NEVER mints a signature -- it verifies signatures produced in an HSM
+ *   elsewhere. Verification is pure public-input SHA-256 / SHAKE256 hashing
+ *   (no secret, no side-channel surface), so a pure-JavaScript verifier is safe.
+ * @spec RFC 8554, RFC 9802, RFC 9708, NIST SP 800-208
+ * @card Verify HSS/LMS signatures (post-quantum, CNSA 2.0 firmware signing).
+ */
+
+var nodeCrypto = require("crypto");
+var frameworkError = require("./framework-error");
+var guard = require("./guard-all");
+var constants = require("./constants");
+
+var ShbsError = frameworkError.ShbsError;
+function _err(code, message, cause) { return new ShbsError(code, message, cause); }
+
+// ---- big-endian serialization (RFC 8554 sec. 3.1: network byte order) --------
+
+function u8(x) { return Buffer.from([x & 0xff]); }
+function u16(x) { return Buffer.from([(x >> 8) & 0xff, x & 0xff]); }
+function u32(x) { return Buffer.from([(x >>> 24) & 0xff, (x >>> 16) & 0xff, (x >>> 8) & 0xff, x & 0xff]); }
+
+// Domain separators (RFC 8554 sec. 7.1). All exceed 264 (the max Winternitz
+// digit index i) so a security-string D can never collide with a chain-hash i,
+// which occupies the same 2-byte offset (sec. 9.1).
+var D_PBLC = 0x8080;   // LM-OTS public-key finalize
+var D_MESG = 0x8181;   // message hash
+var D_LEAF = 0x8282;   // LMS leaf hash
+var D_INTR = 0x8383;   // LMS interior node hash
+
+// ---- typecode registry (IANA Leighton-Micali Signatures; NIST SP 800-208) ----
+// LMS   0x05..0x18 : {m, h, hashFamily}. LM-OTS 0x01..0x10 : {n, w, hashFamily}.
+// p and ls are DERIVED from (n, w) per RFC 8554 sec. 4.1 / Appendix B so the
+// table stays data, not a switch, and a wrong hardcoded p cannot creep in.
+
+function _ilog2(x) { var r = 0; while (x > 1) { x = Math.floor(x / 2); r += 1; } return r; }
+
+// RFC 8554 Appendix B: u = ceil(8n/w) hash digits; v = the checksum digit count;
+// p = u + v total Winternitz digits; ls = the left-shift aligning the checksum's
+// significant bits into the digit positions coef reads.
+function _deriveWinternitz(n, w) {
+  var u = Math.ceil((8 * n) / w);
+  var v = Math.ceil((_ilog2((Math.pow(2, w) - 1) * u) + 1) / w);
+  return { p: u + v, ls: 16 - v * w };
+}
+
+var LMS_SETS = {};
+var LMOTS_SETS = {};
+(function seed() {
+  var heights = [5, 10, 15, 20, 25];   // H5..H25 in typecode order
+  var ws = [1, 2, 4, 8];               // W1..W8 in typecode order
+  // LMS families in IANA order: SHA-256/M32 (0x05), SHA-256/M24 (0x0A),
+  // SHAKE/M32 (0x0F), SHAKE/M24 (0x14).
+  [{ base: 0x05, m: 32, f: "sha256" }, { base: 0x0A, m: 24, f: "sha256" },
+   { base: 0x0F, m: 32, f: "shake256" }, { base: 0x14, m: 24, f: "shake256" }].forEach(function (fam) {
+    heights.forEach(function (h, i) { LMS_SETS[fam.base + i] = { code: fam.base + i, m: fam.m, h: h, hashFamily: fam.f }; });
+  });
+  // LM-OTS families: SHA-256/N32 (0x01), SHA-256/N24 (0x05), SHAKE/N32 (0x09),
+  // SHAKE/N24 (0x0D).
+  [{ base: 0x01, n: 32, f: "sha256" }, { base: 0x05, n: 24, f: "sha256" },
+   { base: 0x09, n: 32, f: "shake256" }, { base: 0x0D, n: 24, f: "shake256" }].forEach(function (fam) {
+    ws.forEach(function (w, i) {
+      var d = _deriveWinternitz(fam.n, w);
+      LMOTS_SETS[fam.base + i] = { code: fam.base + i, n: fam.n, w: w, p: d.p, ls: d.ls, hashFamily: fam.f };
+    });
+  });
+})();
+
+function _lmsSet(code) {
+  var s = LMS_SETS[code];
+  if (!s) throw _err("shbs/unsupported-parameter-set", "unrecognized or unapproved LMS typecode 0x" + code.toString(16));
+  return s;
+}
+function _lmotsSet(code) {
+  var s = LMOTS_SETS[code];
+  if (!s) throw _err("shbs/unsupported-parameter-set", "unrecognized or unapproved LM-OTS typecode 0x" + code.toString(16));
+  return s;
+}
+
+// hashFamily + output length -> the n-byte hash of the concatenated inputs.
+// SHA-256 truncated to n (n=24 is SHA-256/192); SHAKE256 with an n-byte output.
+function _hash(family, n, parts) {
+  var h;
+  if (family === "shake256") h = nodeCrypto.createHash("shake256", { outputLength: n });
+  else h = nodeCrypto.createHash("sha256");
+  for (var i = 0; i < parts.length; i++) h.update(parts[i]);
+  var d = h.digest();
+  return (family === "shake256" || n === 32) ? d : d.subarray(0, n);
+}
+
+// ---- bounded big-endian reader (bounds-before-slice; the ct.js TlsReader model
+// for a non-DER positional wire, kept shbs-local -- shbs needs u32 typecodes +
+// fixed-n reads, not CT's length-prefixed vector helpers) --------------------
+
+function Reader(buf, code, label) { this.buf = buf; this.pos = 0; this.code = code; this.label = label; }
+Reader.prototype._need = function (k) {
+  if (k < 0 || this.pos + k > this.buf.length) {
+    throw _err(this.code, this.label + " is truncated (needed " + k + " byte(s) at offset " + this.pos + ", have " + (this.buf.length - this.pos) + ")");
+  }
+};
+Reader.prototype.u32 = function () { this._need(4); var v = this.buf.readUInt32BE(this.pos); this.pos += 4; return v; };
+Reader.prototype.take = function (k) { this._need(k); var b = this.buf.subarray(this.pos, this.pos + k); this.pos += k; return b; };
+Reader.prototype.remaining = function () { return this.buf.length - this.pos; };
+Reader.prototype.atEnd = function () { return this.pos === this.buf.length; };
+
+// ---- Winternitz digit + checksum (RFC 8554 sec. 3.1.3 / sec. 4.4) ------------
+
+// coef(S, i, w): the i-th w-bit digit of S, big-endian WITHIN each byte (digit 0
+// is the high-order w bits of byte 0). RFC 8554 sec. 3.1.3.
+function _coef(S, i, w) {
+  var idx = Math.floor((i * w) / 8);
+  if (idx >= S.length) throw _err("shbs/bad-signature", "Winternitz coefficient index out of range");
+  var shift = 8 - (w * (i % (8 / w)) + w);
+  return ((1 << w) - 1) & (S[idx] >> shift);
+}
+
+// Cksm(Q) per RFC 8554 sec. 4.4: sum over the u message digits of (2^w-1 - digit),
+// left-shifted by ls, as a 2-byte big-endian value. Computed over Q ALONE; the
+// coefficient index space in the chain walk spans Q || Cksm(Q).
+function _cksm(Q, set) {
+  var w = set.w, sum = 0, u = Math.ceil((8 * set.n) / w);
+  for (var i = 0; i < u; i++) sum += ((1 << w) - 1) - _coef(Q, i, w);
+  sum = (sum << set.ls) & 0xffff;
+  return u16(sum);
+}
+
+// ---- LM-OTS public-key candidate Kc (RFC 8554 Algorithm 4b) ------------------
+// I, q identify the LMS leaf; otsSet is resolved from the PUBLIC KEY's otstype
+// (the authority); C + y[] come from the signature. Returns the n-byte Kc.
+
+function _lmotsKc(otsSet, I, q, C, y, message) {
+  var n = otsSet.n, w = otsSet.w, p = otsSet.p, f = otsSet.hashFamily;
+  var qb = u32(q);
+  var Q = _hash(f, n, [I, qb, u16(D_MESG), C, message]);
+  var Qc = Buffer.concat([Q, _cksm(Q, otsSet)]);
+  var z = [I, qb, u16(D_PBLC)];
+  for (var i = 0; i < p; i++) {
+    var a = _coef(Qc, i, w);
+    var tmp = y[i];
+    // Chain to 2^w - 1 total applications; the bound is EXCLUSIVE (last j = 2^w-2),
+    // matching key generation (RFC 8554 sec. 4.5 vs Algorithm 4b step 3).
+    for (var j = a; j < (1 << w) - 1; j++) tmp = _hash(f, n, [I, qb, u16(i), u8(j), tmp]);
+    z.push(tmp);
+  }
+  return _hash(f, n, z);
+}
+
+// ---- LMS verification core (RFC 8554 Algorithm 6 / 6a) -----------------------
+// pubBytes = lmstype(4) || otstype(4) || I(16) || T[1](m); sigBytes an LMS
+// signature. Returns true iff the recomputed Merkle root equals T[1]. Throws
+// ShbsError on any structural fault; a well-formed-but-wrong signature -> false.
+
+function _lmsVerify(pubBytes, message, sigBytes) {
+  // -- public key (the authority for both typecodes; RFC 8554 Algorithm 6) --
+  if (pubBytes.length < 8) throw _err("shbs/bad-public-key", "LMS public key is shorter than 8 bytes");
+  var pr = new Reader(pubBytes, "shbs/bad-public-key", "LMS public key");
+  var lmsSet = _lmsSet(pr.u32());
+  var otsSet = _lmotsSet(pr.u32());
+  var m = lmsSet.m, h = lmsSet.h;
+  if (pubBytes.length !== 24 + m) throw _err("shbs/bad-public-key", "LMS public key must be exactly " + (24 + m) + " bytes");
+  var I = pr.take(16);
+  var T1 = pr.take(m);
+
+  // -- signature (RFC 8554 Algorithm 6a). q first, then the LM-OTS signature,
+  //    then the LMS typecode (AFTER the LM-OTS sig), then the auth path. --
+  if (sigBytes.length < 8) throw _err("shbs/bad-signature", "LMS signature is shorter than 8 bytes");
+  var sr = new Reader(sigBytes, "shbs/bad-signature", "LMS signature");
+  var q = sr.u32();
+  var otsSigType = sr.u32();
+  // The public key -- never the attacker-controlled signature -- is the authority
+  // (downgrade defense): a signature whose OTS typecode does not equal the one the
+  // public key commits to cannot verify against it. RFC 8554 Algorithm 6a checks
+  // the typecode (step 2c, and 2g for the LMS type below) BEFORE the length (steps
+  // 2d / 2i), and returns INVALID -- a verification FAILURE (false), not a
+  // structural error. So a mismatch is `false` at this point EVEN for a blob too
+  // short to be a complete signature: the mismatch is decidable once q + typecode
+  // are read (the bounded reader already threw if those 8 bytes are absent). A
+  // matching typecode with a truncated body still throws below (bounds-before-
+  // slice). Re-sizing the body by the signature's own mismatched typecode -- to
+  // "fully validate before returning false" -- would violate this order and reject
+  // a legitimate typecode-mutation test vector as malformed instead of INVALID.
+  if (otsSigType !== otsSet.code) return false;
+  var n = otsSet.n, p = otsSet.p;
+  var C = sr.take(n);
+  var y = [];
+  for (var yi = 0; yi < p; yi++) y.push(sr.take(n));
+  var sigLmsType = sr.u32();
+  if (sigLmsType !== lmsSet.code) return false;   // RFC 8554 Algorithm 6a step 2g -> INVALID
+  var path = [];
+  for (var pi = 0; pi < h; pi++) path.push(sr.take(m));
+  if (!sr.atEnd()) throw _err("shbs/bad-signature", "LMS signature has " + sr.remaining() + " trailing byte(s)");
+  // RFC 8554 Algorithm 6a step 2i: a leaf index q >= 2^h is INVALID -- a
+  // verification FAILURE (false), NOT a structural error. Checked here, AFTER the
+  // exact-length validation above (a truncated / trailing blob already threw
+  // typed), against the REGISTRY height, never the blob. 2^h fits Number (h<=25).
+  if (q >= Math.pow(2, h)) return false;
+
+  // -- recompute the LM-OTS public-key candidate, then fold the Merkle path --
+  var Kc = _lmotsKc(otsSet, I, q, C, y, message);
+  var nodeNum = Math.pow(2, h) + q;
+  var tmp = _hash(lmsSet.hashFamily, m, [I, u32(nodeNum), u16(D_LEAF), Kc]);
+  for (var i2 = 0; nodeNum > 1; i2++) {
+    var parent = Math.floor(nodeNum / 2);
+    if (nodeNum % 2 === 1) {
+      // odd node_num: the current node is a RIGHT child, sibling on the LEFT.
+      tmp = _hash(lmsSet.hashFamily, m, [I, u32(parent), u16(D_INTR), path[i2], tmp]);
+    } else {
+      tmp = _hash(lmsSet.hashFamily, m, [I, u32(parent), u16(D_INTR), tmp, path[i2]]);
+    }
+    nodeNum = parent;
+  }
+  // The root comparison is over PUBLIC values (T1 is in the public key, tmp is
+  // derived from public inputs -- no secret, hence the module's "no side-channel
+  // surface" note), so constant time is not strictly required. It routes through
+  // the shared crypto guard anyway, for one length-checked comparison primitive
+  // across the hash-tree verifiers (pki.merkle folds its root the same way).
+  return guard.crypto.constantTimeEqual(tmp, T1);
+}
+
+// Consume exactly one LMS public key from a reader (an HSS inner key), returning
+// its raw bytes; sized off the LMS typecode it leads with.
+function _consumeLmsPublicKey(r) {
+  var start = r.pos;
+  var code = r.u32();       // lmstype
+  r.u32();                  // otstype (validated when the key is verified)
+  var m = _lmsSet(code).m;
+  r.take(16 + m);           // I || T[1]
+  return r.buf.subarray(start, r.pos);
+}
+
+// The exact byte length (12 + n*(p+1) + m*h) of an LMS signature verified under
+// `keyBytes` -- the AUTHORITATIVE public key for its level. The concatenated HSS
+// blob is split by the public key's typecodes, never the attacker-controlled
+// signature's own: so a typecode-mutated signature is sliced to the length the
+// key expects and then _lmsVerify returns false (a verification failure, RFC 8554
+// Algorithm 6a 2c/2g), consistent with verifyLms, instead of throwing on a
+// mis-sized slice. Bounds-guarded (no direct read that could escape as a raw
+// RangeError on a truncated inner key).
+function _lmsSigLen(keyBytes) {
+  if (keyBytes.length < 8) throw _err("shbs/bad-public-key", "LMS public key is shorter than 8 bytes");
+  var lmsSet = _lmsSet(keyBytes.readUInt32BE(0));
+  var otsSet = _lmotsSet(keyBytes.readUInt32BE(4));
+  return 12 + otsSet.n * (otsSet.p + 1) + lmsSet.m * lmsSet.h;
+}
+
+// ---- HSS verification (RFC 8554 sec. 6.3) ------------------------------------
+
+function _hssVerify(pubBytes, message, sigBytes) {
+  if (pubBytes.length < 4) throw _err("shbs/bad-public-key", "HSS public key is shorter than 4 bytes");
+  var pr = new Reader(pubBytes, "shbs/bad-public-key", "HSS public key");
+  var L = pr.u32();
+  if (L < 1 || L > constants.LIMITS.HSS_MAX_LEVELS) throw _err("shbs/bad-public-key", "HSS level count L=" + L + " is outside 1.." + constants.LIMITS.HSS_MAX_LEVELS);
+  var topKey = pr.buf.subarray(pr.pos);   // the top-level LMS public key -- its
+  // structure (including an under-length blob) is validated by _lmsVerify below
+  // (the < 8 and exact-24+m checks), so no direct read here that would bypass the
+  // bounded reader and escape as a raw RangeError on a truncated key.
+
+  var sr = new Reader(sigBytes, "shbs/bad-signature", "HSS signature");
+  var Nspk = sr.u32();
+  // The level-count gate, checked BEFORE parsing any component (RFC 8554 sec. 6.3).
+  if (Nspk + 1 !== L) throw _err("shbs/bad-signature", "HSS Nspk+1 (" + (Nspk + 1) + ") does not equal the public-key level count L (" + L + ")");
+
+  var key = topKey;
+  for (var i = 0; i < Nspk; i++) {
+    // Slice this level's LMS signature by the AUTHORITATIVE key's length (so a
+    // typecode mismatch is a false verdict via _lmsVerify, not a mis-sized throw).
+    var sig = sr.take(_lmsSigLen(key));
+    var nextKey = _consumeLmsPublicKey(sr);
+    // Each level signs the SERIALIZED next-level LMS public key; that recovered
+    // key becomes the verification key for the level below (chain of trust).
+    if (!_lmsVerify(key, nextKey, sig)) return false;
+    key = nextKey;
+  }
+  // The final signature is the remainder; _lmsVerify parses it, applies the
+  // public-key-authoritative typecode check (mismatch -> false), and rejects a
+  // trailing / truncated remainder (bounds-before-slice + its own atEnd check).
+  return _lmsVerify(key, message, sr.buf.subarray(sr.pos));
+}
+
+// ---- public surface ----------------------------------------------------------
+
+function _asBytes(x, label) { return guard.bytes.source(x, ShbsError, "shbs/bad-input", label); }
+
+/**
+ * @primitive pki.shbs.verify
+ * @signature pki.shbs.verify(publicKey, message, signature) -> boolean
+ * @since 0.2.1
+ * @status experimental
+ * @spec RFC 8554 sec. 6, RFC 9802, RFC 9708
+ * @related pki.shbs.verifyLms
+ *
+ * Verify an HSS (Hierarchical Signature System) signature over `message` under
+ * `publicKey` -- the wire form RFC 9802 (X.509) and RFC 9708 (CMS) carry for
+ * `id-alg-hss-lms-hashsig`. The public key and signature are the raw HSS octet
+ * blobs the certificate / CMS parsers already surface (no ASN.1 wrapping). Every
+ * level of the hierarchy must verify: a single failing level yields false.
+ * Returns true for a valid signature, false for a well-formed signature that does
+ * not verify; a malformed blob (bad length, unknown or unapproved typecode,
+ * truncation, a typecode disagreeing between the key and the signature) throws a
+ * typed `ShbsError`. VERIFY ONLY -- this module never signs.
+ *
+ * @example
+ *   var cert = pki.schema.x509.parse(der);
+ *   var ok = pki.shbs.verify(cert.subjectPublicKeyInfo.publicKey.bytes,
+ *                            cert.tbsBytes, cert.signatureValue.bytes);
+ */
+function verify(publicKey, message, signature) {
+  return _hssVerify(_asBytes(publicKey, "public key"), _asBytes(message, "message"), _asBytes(signature, "signature"));
+}
+
+/**
+ * @primitive pki.shbs.verifyLms
+ * @signature pki.shbs.verifyLms(publicKey, message, signature) -> boolean
+ * @since 0.2.1
+ * @status experimental
+ * @spec RFC 8554 sec. 5
+ * @related pki.shbs.verify
+ *
+ * Verify a single-tree LMS (Leighton-Micali Signature) over `message` -- the
+ * component an HSS hierarchy composes at each level, and a standalone algorithm
+ * in its own right. Same verdict contract as `pki.shbs.verify`: true / false for
+ * a well-formed signature, a typed `ShbsError` for a malformed blob.
+ *
+ * @example
+ *   // lmsPublicKey / lmsSignature are raw LMS blobs (an HSS level, or a bare
+ *   // LMS-signed artifact). Shown here on arbitrary bytes, which fail closed.
+ *   var ok = pki.shbs.verifyLms(bytes, bytes, bytes);
+ */
+function verifyLms(publicKey, message, signature) {
+  return _lmsVerify(_asBytes(publicKey, "public key"), _asBytes(message, "message"), _asBytes(signature, "signature"));
+}
+
+module.exports = { verify: verify, verifyLms: verifyLms };