@blamejs/pki 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +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.2.2 — 2026-07-12
+
+Hybrid Public Key Encryption (RFC 9180) joins the toolkit as pki.hpke.
+
+### Added
+
+- pki.hpke.setupS(suiteIds, recipientPublicKey, opts) / pki.hpke.setupR(suiteIds, enc, recipientPrivateKey, opts) establish a sender / recipient HPKE context (RFC 9180 sec. 5.1); the returned context exposes seal(aad, pt) / open(aad, ct) with the sequence-counter nonce and a message-limit guard, and export(exporterContext, L) for the secret-export interface. pki.hpke.seal / pki.hpke.open are the single-shot wrappers (sec. 6). pki.hpke.suites carries the RFC 9180 sec. 7 KEM / KDF / AEAD / MODE code points. Keys are node KeyObjects or serialized bytes; the offered suites are DHKEM P-256, P-521, X25519, and X448, HKDF-SHA256 / HKDF-SHA512, the three AEADs plus export-only, and all four modes. RFC 9180.
+- The error taxonomy gains HpkeError (hpke/*): a malformed, low-order, or otherwise invalid encapsulated or KEM key (hpke/bad-key, so a Diffie-Hellman that fails during derivation surfaces as a typed error, never a raw fault), an unknown or unsupported ciphersuite code point (hpke/unknown-suite, never a silent default), an unsupported mode (hpke/unknown-mode, so an out-of-registry mode is rejected rather than key-scheduled), an authenticated mode invoked without the sender's key (hpke/auth-key-required), inconsistent PSK inputs (hpke/inconsistent-psk), an AEAD tag that does not verify (hpke/open-failed, returning no plaintext), a sequence-number overflow (hpke/message-limit, before any nonce reuse), a seal/open against an export-only suite (hpke/export-only), and a wrong-direction context call (hpke/wrong-role, so a recipient context cannot seal nor a sender context open -- they share a key and base nonce).
+
+## v0.2.1 — 2026-07-11
+
+Stateful hash-based signature verification (HSS/LMS) joins the toolkit as pki.shbs.
+
+### Added
+
+- pki.shbs.verify(publicKey, message, signature) verifies an HSS (Hierarchical Signature System) signature -- the wire form RFC 9802 (X.509) and RFC 9708 (CMS) carry for id-alg-hss-lms-hashsig -- returning true only if every level of the hierarchy verifies. pki.shbs.verifyLms(publicKey, message, signature) verifies a single-tree LMS signature (the component HSS composes, and a standalone algorithm). Both take the raw octet blobs the parsers surface (a certificate's subjectPublicKeyInfo.publicKey.bytes, tbsBytes, and signatureValue.bytes); a malformed blob -- bad length, an unknown or unapproved typecode, truncation, a typecode the public key does not commit to -- throws a typed ShbsError, and a well-formed but wrong signature returns false. RFC 8554 / RFC 9802 / RFC 9708 / NIST SP 800-208.
+- The OID registry gains id-alg-hss-lms-hashsig (1.2.840.113549.1.9.16.3.17), id-alg-xmss-hashsig, and id-alg-xmssmt-hashsig, all with parameters MUST be absent (RFC 9802 sec. 4) -- a stateful-hash-signature AlgorithmIdentifier carrying any parameters now fails closed at the shared algorithm-identifier gate, inherited by every format the toolkit parses. The error taxonomy gains ShbsError (shbs/*).
+
+### Changed
+
+- XMSS / XMSS^MT verification and automatic HSS/LMS verification inside pki.path.validate are not in this release -- see the roadmap. The former awaits an authoritative interoperability test vector (RFC 8391 ships none and NIST ACVP does not yet cover XMSS); the latter awaits a real HSS-signed certificate to prove the certification-path wiring end to end. Operators verify today by handing the raw certificate / CMS blobs to pki.shbs.verify directly.
+
 ## v0.2.0 — 2026-07-11
 
 Trust-store ingestion, sharded-CRL revocation, and a hardened input-guard layer.

package/README.md

@@ -224,6 +224,8 @@ is callable today; nothing below is a stub.
 | `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.trust` | Mozilla / CCADB trust-store ingestion — `parseCertdata` reads the NSS `certdata.txt` object stream and `parseCcadbCsv` the CCADB CSV export into one identical constraint-carrying anchor shape: the per-purpose trust bits (only `CKT_NSS_TRUSTED_DELEGATOR` grants) and the per-purpose distrust-after dates the bare root list omits. Certificate and trust objects pair by byte-exact issuer + serial (never adjacency) and are cross-checked against the parsed DER, so metadata can never attach to the wrong root; `anchor()` hands an entry to `pki.path.validate({ trustAnchor, checkPurpose })`. Offline, fail-closed, bounded — `parseCertdata`, `parseCcadbCsv`, `anchor` |
+| `pki.shbs` | Stateful hash-based signature **verification** — HSS/LMS (RFC 8554), carried in X.509 by RFC 9802 and CMS by RFC 9708, profiled by NIST SP 800-208 (CNSA 2.0 firmware signing). `verify` checks an HSS signature (every level must pass) and `verifyLms` a single-tree LMS, over the raw public-key / signature blobs the parsers already surface. Pure public-input SHA-256 / SHAKE256 hashing, a data-driven typecode registry, bounds-before-slice reads; a malformed blob throws a typed `ShbsError`, a well-formed-but-wrong signature returns `false`. **Verify only by design** — stateful signing needs atomic one-time-key state that belongs in an HSM — `verify`, `verifyLms` |
+| `pki.hpke` | Hybrid Public Key Encryption (RFC 9180) — the encrypt-to-a-public-key primitive behind TLS ECH, MLS, and OHTTP. `setupS`/`setupR` establish a sender/recipient context (KEM encapsulation + HKDF key schedule); the context's `seal`/`open` AEAD-encrypt with a sequence-counter nonce and `export` derives further secrets; `seal`/`open` are single-shot wrappers. DHKEM (P-256, P-521, X25519, X448) × HKDF-SHA256/SHA512 × AES-GCM/ChaCha20Poly1305/export-only × all four modes, proven against the RFC 9180 Appendix A vectors. DHKEM(P-384) and HKDF-SHA384 are RFC-registered but Appendix A ships no vector for them, so they fail closed until an authoritative KAT exists. Pure composition over `node:crypto`; ML-KEM / X-Wing are a registry data-row extension pending stable drafts — `suites`, `setupS`, `setupR`, `seal`, `open` |
 | `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

@@ -37,6 +37,8 @@ var schema    = require("./lib/schema-all");
 var path      = require("./lib/path-validate");
 var ct        = require("./lib/ct");
 var merkle    = require("./lib/merkle");
+var shbs      = require("./lib/shbs");
+var hpke      = require("./lib/hpke");
 var est        = require("./lib/est");
 var jose       = require("./lib/jose");
 var acme       = require("./lib/acme");
@@ -73,6 +75,15 @@ module.exports = {
   // verifyConsistency fold an audit / consistency proof and constant-time-
   // compare to a checkpoint root. Pure sync hashing, fail-closed, transport-free.
   merkle:    merkle,
+  // `shbs` verifies stateful hash-based signatures -- HSS/LMS (RFC 8554),
+  // carried by RFC 9802 (X.509) and RFC 9708 (CMS), profiled by NIST SP 800-208.
+  // VERIFY ONLY by design: stateful signing requires atomic one-time-key index
+  // state that belongs in an HSM, so this module never mints a signature.
+  shbs:      shbs,
+  // `hpke` is RFC 9180 Hybrid Public Key Encryption -- the KEM + HKDF key
+  // schedule + AEAD context construction behind TLS ECH / MLS / OHTTP. Pure
+  // composition over node:crypto; the classical DHKEM suites, all four modes.
+  hpke:      hpke,
   // `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/constants.js

@@ -237,6 +237,10 @@ var LIMITS = {
   // relayed response with a huge certs list would drive unbounded pre-auth
   // signature verifies. 32 is generous headroom over a real chain.
   OCSP_MAX_CERTS: 32,
+  // HSS hierarchy depth (RFC 8554 sec. 6.1: L is 1..8). The HSS verifier caps
+  // its per-level parse loop at this from the registry, never at the blob's own
+  // Nspk, so a hostile signature cannot drive an unbounded level walk.
+  HSS_MAX_LEVELS: 8,
   // Trust-store ingestion ceilings (Mozilla/NSS certdata.txt + CCADB CSV).
   // Every cap is refused BEFORE the offending allocation with a typed trust/*
   // error -- never a silent truncate. A live certdata.txt is a few MiB and a

package/lib/framework-error.js

@@ -281,6 +281,8 @@ var AcmeError = defineClass("AcmeError", { withCause: true });
 // not a trusted delegator for. Carries the underlying leaf fault (an x509/* or
 // asn1/* error) as `.cause`.
 var TrustError = defineClass("TrustError", { withCause: true });
+var ShbsError = defineClass("ShbsError", { withCause: true });
+var HpkeError = defineClass("HpkeError", { withCause: true });
 
 module.exports = {
   PkiError:         PkiError,
@@ -304,6 +306,8 @@ module.exports = {
   CmpError:         CmpError,
   PathError:        PathError,
   CtError:          CtError,
+  ShbsError:        ShbsError,
+  HpkeError:        HpkeError,
   MerkleError:      MerkleError,
   SmimeError:       SmimeError,
   CsrattrsError:    CsrattrsError,

package/lib/hpke.js

@@ -0,0 +1,487 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module pki.hpke
+ * @nav        Protocols
+ * @title      HPKE
+ * @intro Hybrid Public Key Encryption (RFC 9180) -- the standard construction
+ *   behind TLS Encrypted Client Hello, MLS, and OHTTP that turns a recipient KEM
+ *   public key into an encapsulated key plus an AEAD-encrypting context. This is
+ *   the RFC 9180 base construction: the DHKEM suites P-256, P-521, X25519, and
+ *   X448, HKDF-SHA256 / HKDF-SHA512, the three AEADs plus export-only, and all
+ *   four modes (base / psk / auth / auth-psk), each proven against the RFC 9180
+ *   Appendix A known-answer vectors. DHKEM(P-384) and HKDF-SHA384 are RFC-registered
+ *   but Appendix A ships no test vector for them, so they are omitted (a request
+ *   fails closed) until an authoritative KAT is available. Pure composition over
+ *   node:crypto -- no ASN.1, no schema engine. Post-quantum KEMs (ML-KEM, X-Wing)
+ *   are a data-row extension the registry is shaped to admit once their
+ *   specifications stabilize.
+ *   The RFC 9180 sec. 7 registry code points live in pki.hpke.suites
+ *   (KEM / KDF / AEAD / MODE), passed to the setup functions to select a suite.
+ * @spec RFC 9180
+ * @card Encrypt to a KEM public key (RFC 9180; the ECH / MLS / OHTTP primitive).
+ */
+
+var nodeCrypto = require("crypto");
+var frameworkError = require("./framework-error");
+var guard = require("./guard-all");
+
+var HpkeError = frameworkError.HpkeError;
+function _err(code, message, cause) { return new HpkeError(code, message, cause); }
+
+// ---- I2OSP + byte helpers ----------------------------------------------------
+
+function i2osp(n, len) {
+  var b = Buffer.alloc(len);
+  var v = BigInt(n);
+  for (var i = len - 1; i >= 0; i--) { b[i] = Number(v & 0xffn); v >>= 8n; }
+  return b;
+}
+function concat(arr) { return Buffer.concat(arr); }
+function xor(a, b) { var o = Buffer.alloc(a.length); for (var i = 0; i < a.length; i++) o[i] = a[i] ^ b[i]; return o; }
+
+var HPKE_V1 = Buffer.from("HPKE-v1", "ascii");
+function L(s) { return Buffer.from(s, "ascii"); }
+
+// ---- registries (RFC 9180 sec. 7, Tables 2/3/5 -- data, not switch) ----------
+
+// KDF: id -> { hash (node name), Nh }.
+// HKDF-SHA384 (0x0002) and DHKEM(P-384) (0x0011) are registered by RFC 9180 sec.
+// 7 but Appendix A / the cited [TestVectors] file ship no known-answer vector for
+// them, so they are omitted here until an authoritative KAT exists -- a request
+// for either fails closed as hpke/unknown-suite rather than running crypto no
+// test vector proves. They admit as a one-row addition the moment a KAT lands.
+var KDFS = {
+  0x0001: { hash: "sha256", Nh: 32 },
+  0x0003: { hash: "sha512", Nh: 64 },
+};
+// AEAD: id -> { cipher (node name), Nk, Nn, Nt } or exportOnly.
+var AEADS = {
+  0x0001: { cipher: "aes-128-gcm", Nk: 16, Nn: 12, Nt: 16 },
+  0x0002: { cipher: "aes-256-gcm", Nk: 32, Nn: 12, Nt: 16 },
+  0x0003: { cipher: "chacha20-poly1305", Nk: 32, Nn: 12, Nt: 16 },
+  0xFFFF: { exportOnly: true, Nn: 12 },
+};
+// KEM: id -> DHKEM group descriptor. `group` is the node keygen/import family;
+// `kdf` is the KEM-internal KDF (its ExtractAndExpand); Nsecret = that KDF's Nh.
+var KEMS = {
+  0x0010: { kind: "ec", curve: "P-256", nodeCurve: "prime256v1", kdf: 0x0001, Nsecret: 32, Npub: 65 },
+  0x0012: { kind: "ec", curve: "P-521", nodeCurve: "secp521r1", kdf: 0x0003, Nsecret: 64, Npub: 133 },
+  0x0020: { kind: "okp", curve: "X25519", oid: "2b656e", kdf: 0x0001, Nsecret: 32, Npub: 32 },
+  0x0021: { kind: "okp", curve: "X448", oid: "2b656f", kdf: 0x0003, Nsecret: 64, Npub: 56 },
+};
+
+var MODE_BASE = 0x00, MODE_PSK = 0x01, MODE_AUTH = 0x02, MODE_AUTH_PSK = 0x03;
+
+// Format a code point for an error message without assuming it is a number: a
+// missing suiteIds member arrives as undefined, and undefined.toString(16) would
+// crash the very error path meant to report it.
+function _idStr(id) { return typeof id === "number" ? "0x" + id.toString(16) : String(id); }
+function _kem(id) { var s = KEMS[id]; if (!s) throw _err("hpke/unknown-suite", "unsupported KEM id " + _idStr(id)); return s; }
+function _kdf(id) { var s = KDFS[id]; if (!s) throw _err("hpke/unknown-suite", "unsupported KDF id " + _idStr(id)); return s; }
+function _aead(id) { var s = AEADS[id]; if (!s) throw _err("hpke/unknown-suite", "unsupported AEAD id " + _idStr(id)); return s; }
+
+// ---- labeled KDF (RFC 9180 sec. 4): HKDF Extract/Expand SPLIT over HMAC -------
+// suite_id is the caller's ("KEM"||... for the KEM layer, "HPKE"||... for the
+// rest). Extract = HMAC(salt-or-zeros, ikm); Expand = RFC 5869 sec. 2.3 feedback.
+
+function _extract(hash, Nh, salt, ikm) {
+  var key = (salt && salt.length) ? salt : Buffer.alloc(Nh);
+  return nodeCrypto.createHmac(hash, key).update(ikm).digest();
+}
+function _expand(hash, Nh, prk, info, len) {
+  if (len > 255 * Nh) throw _err("hpke/export-length", "requested length " + len + " exceeds 255*Nh");
+  var out = [], t = Buffer.alloc(0), n = Math.ceil(len / Nh);
+  for (var i = 1; i <= n; i++) {
+    t = nodeCrypto.createHmac(hash, prk).update(concat([t, info, Buffer.from([i])])).digest();
+    out.push(t);
+  }
+  return concat(out).subarray(0, len);
+}
+function _labeledExtract(kdf, suiteId, salt, label, ikm) {
+  return _extract(kdf.hash, kdf.Nh, salt, concat([HPKE_V1, suiteId, L(label), ikm]));
+}
+function _labeledExpand(kdf, suiteId, prk, label, info, len) {
+  return _expand(kdf.hash, kdf.Nh, prk, concat([i2osp(len, 2), HPKE_V1, suiteId, L(label), info]), len);
+}
+
+// ---- KEM key (de)serialization + Diffie-Hellman (node:crypto) ----------------
+
+var OKP_SPKI = { X25519: "302a300506032b656e032100", X448: "3042300506032b656f033900" };
+var OKP_PKCS8 = { X25519: "302e020100300506032b656e04220420", X448: "3046020100300506032b656f043a0438" };
+
+// Deserialize a serialized KEM public key (enc / pkRm / pkSm) into a node
+// KeyObject. EC is an uncompressed 0x04 point (SerializePublicKey, sec. 7.1.1);
+// OKP is the raw curve point. A wrong length / shape fails closed.
+function _importPublic(kem, raw) {
+  if (!Buffer.isBuffer(raw) || raw.length !== kem.Npub) {
+    throw _err("hpke/bad-key", kem.curve + " public key must be " + kem.Npub + " bytes");
+  }
+  try {
+    if (kem.kind === "ec") {
+      if (raw[0] !== 0x04) throw _err("hpke/bad-key", "EC public key must be an uncompressed 0x04 point (RFC 9180 sec. 7.1.4)");
+      var half = (raw.length - 1) / 2;
+      var jwk = { kty: "EC", crv: kem.curve, x: raw.subarray(1, 1 + half).toString("base64url"), y: raw.subarray(1 + half).toString("base64url") };
+      return nodeCrypto.createPublicKey({ key: jwk, format: "jwk" });
+    }
+    return nodeCrypto.createPublicKey({ key: Buffer.from(OKP_SPKI[kem.curve] + raw.toString("hex"), "hex"), format: "der", type: "spki" });
+  } catch (e) {
+    if (e instanceof HpkeError) throw e;
+    throw _err("hpke/bad-key", "invalid " + kem.curve + " public key", e);
+  }
+}
+// Serialize a node public KeyObject back to the RFC 9180 wire encoding.
+function _exportPublic(kem, keyObject) {
+  var jwk = keyObject.export({ format: "jwk" });
+  if (kem.kind === "ec") return concat([Buffer.from([0x04]), _b64u(jwk.x), _b64u(jwk.y)]);
+  return _b64u(jwk.x);
+}
+// Node's own JWK export -- decode its canonical base64url coordinates through the
+// guard so the alphabet/canonicality check is the single shared choke point.
+function _b64u(s) { return guard.encoding.base64url(s, null, _err, "hpke/bad-key", "JWK coordinate"); }
+
+// Import a serialized KEM private key (skRm / skEm / skSm) into a node KeyObject,
+// given the matching serialized public key for the EC JWK (or none for OKP).
+function _importPrivate(kem, rawSk, rawPk) {
+  try {
+    if (kem.kind === "ec") {
+      var jwk = { kty: "EC", crv: kem.curve, d: rawSk.toString("base64url") };
+      if (rawPk) { jwk.x = rawPk.subarray(1, 1 + (rawPk.length - 1) / 2).toString("base64url"); jwk.y = rawPk.subarray(1 + (rawPk.length - 1) / 2).toString("base64url"); }
+      return nodeCrypto.createPrivateKey({ key: jwk, format: "jwk" });
+    }
+    return nodeCrypto.createPrivateKey({ key: Buffer.from(OKP_PKCS8[kem.curve] + rawSk.toString("hex"), "hex"), format: "der", type: "pkcs8" });
+  } catch (e) {
+    throw _err("hpke/bad-key", "invalid " + kem.curve + " private key", e);
+  }
+}
+// The single KEM Diffie-Hellman choke point. node:crypto throws a raw
+// ERR_OSSL_FAILED_DURING_DERIVATION when the peer point is low-order / invalid
+// (an all-zero X25519 shared secret, a point not on the curve). RFC 9180 sec.
+// 4.1: Decap raises an error on DH failure -- surface it as a typed hpke/bad-key
+// so no raw OpenSSL error escapes any encap / decap path.
+function _dh(privateKey, publicKey) {
+  try {
+    return nodeCrypto.diffieHellman({ privateKey: privateKey, publicKey: publicKey });
+  } catch (e) {
+    throw _err("hpke/bad-key", "KEM Diffie-Hellman failed: invalid or low-order public key", e);
+  }
+}
+function _generate(kem) {
+  if (kem.kind === "ec") return nodeCrypto.generateKeyPairSync("ec", { namedCurve: kem.nodeCurve });
+  return nodeCrypto.generateKeyPairSync(kem.curve.toLowerCase());
+}
+
+// ---- DHKEM (RFC 9180 sec. 4.1) -----------------------------------------------
+
+function _kemSuiteId(kemId) { return concat([L("KEM"), i2osp(kemId, 2)]); }
+function _extractAndExpand(kem, dh, kemContext) {
+  var kdf = _kdf(kem.kdf), sid = _kemSuiteId(_kemId(kem));
+  var eaePrk = _labeledExtract(kdf, sid, Buffer.alloc(0), "eae_prk", dh);
+  return _labeledExpand(kdf, sid, eaePrk, "shared_secret", kemContext, kem.Nsecret);
+}
+function _kemId(kem) { for (var k in KEMS) if (KEMS[k] === kem) return Number(k); return 0; }
+
+// Encap(pkR) -> { sharedSecret, enc }. An injected ephemeral (skE, pkEnc) makes
+// the KAT deterministic; otherwise a fresh ephemeral is generated.
+function _ephemeral(kem, eph) {
+  if (eph) return { skE: _importPrivate(kem, eph.skm, eph.pkm), enc: _buf(eph.pkm) };
+  var kp = _generate(kem);
+  return { skE: kp.privateKey, enc: _exportPublic(kem, kp.publicKey) };
+}
+function _encap(kem, pkR, pkRm, eph) {
+  var e = _ephemeral(kem, eph);
+  var dh = _dh(e.skE, pkR);
+  return { sharedSecret: _extractAndExpand(kem, dh, concat([e.enc, pkRm])), enc: e.enc };
+}
+function _decap(kem, enc, skR, pkRm) {
+  var pkE = _importPublic(kem, enc);
+  var dh = _dh(skR, pkE);
+  return _extractAndExpand(kem, dh, concat([enc, pkRm]));
+}
+function _authEncap(kem, pkR, pkRm, skS, pkSm, eph) {
+  var e = _ephemeral(kem, eph);
+  var dh = concat([_dh(e.skE, pkR), _dh(skS, pkR)]);
+  return { sharedSecret: _extractAndExpand(kem, dh, concat([e.enc, pkRm, pkSm])), enc: e.enc };
+}
+function _authDecap(kem, enc, skR, pkRm, pkS, pkSm) {
+  var pkE = _importPublic(kem, enc);
+  var dh = concat([_dh(skR, pkE), _dh(skR, pkS)]);
+  return _extractAndExpand(kem, dh, concat([enc, pkRm, pkSm]));
+}
+
+// ---- key schedule (RFC 9180 sec. 5.1) ----------------------------------------
+
+function _hpkeSuiteId(kemId, kdfId, aeadId) { return concat([L("HPKE"), i2osp(kemId, 2), i2osp(kdfId, 2), i2osp(aeadId, 2)]); }
+
+function _verifyPsk(mode, psk, pskId) {
+  var gotPsk = psk.length > 0, gotId = pskId.length > 0;
+  if (gotPsk !== gotId) throw _err("hpke/inconsistent-psk", "psk and psk_id must be provided together (RFC 9180 sec. 5.1)");
+  if (gotPsk && (mode === MODE_BASE || mode === MODE_AUTH)) throw _err("hpke/inconsistent-psk", "a PSK was provided for a non-PSK mode");
+  if (!gotPsk && (mode === MODE_PSK || mode === MODE_AUTH_PSK)) throw _err("hpke/inconsistent-psk", "mode requires a PSK");
+}
+
+function _keySchedule(suite, mode, sharedSecret, info, psk, pskId, role) {
+  _verifyPsk(mode, psk, pskId);
+  var kdf = suite.kdf, sid = suite.suiteId, aead = suite.aead;
+  var pskIdHash = _labeledExtract(kdf, sid, Buffer.alloc(0), "psk_id_hash", pskId);
+  var infoHash = _labeledExtract(kdf, sid, Buffer.alloc(0), "info_hash", info);
+  var ksc = concat([Buffer.from([mode]), pskIdHash, infoHash]);
+  var secret = _labeledExtract(kdf, sid, sharedSecret, "secret", psk);
+  var exporterSecret = _labeledExpand(kdf, sid, secret, "exp", ksc, kdf.Nh);
+  var key = null, baseNonce = null;
+  if (!aead.exportOnly) {
+    key = _labeledExpand(kdf, sid, secret, "key", ksc, aead.Nk);
+    baseNonce = _labeledExpand(kdf, sid, secret, "base_nonce", ksc, aead.Nn);
+  }
+  return new Context(suite, key, baseNonce, exporterSecret, role);
+}
+
+// ---- AEAD context (RFC 9180 sec. 5.2 / 5.3) ----------------------------------
+
+// role is "S" (sender: seal only) or "R" (recipient: open only). Sender and
+// recipient derive the same key + base_nonce, so a wrong-direction call would
+// reuse a nonce (RFC 9180 sec. 5.2); export is available to both.
+function Context(suite, key, baseNonce, exporterSecret, role) {
+  this._suite = suite; this._key = key; this._baseNonce = baseNonce;
+  this._exporterSecret = exporterSecret; this._seq = 0n; this._role = role;
+}
+Context.prototype._nonce = function () {
+  var aead = this._suite.aead;
+  var seqBytes = i2osp(this._seq, aead.Nn);
+  return xor(this._baseNonce, seqBytes);
+};
+Context.prototype._inc = function () {
+  var aead = this._suite.aead;
+  if (this._seq >= (1n << BigInt(8 * aead.Nn)) - 1n) throw _err("hpke/message-limit", "AEAD sequence number would overflow (RFC 9180 sec. 5.2)");
+  this._seq += 1n;
+};
+Context.prototype.seal = function (aad, pt) {
+  var aead = this._suite.aead;
+  if (this._role !== "S") throw _err("hpke/wrong-role", "seal is only available on a sender context (RFC 9180 sec. 5.2)");
+  if (aead.exportOnly) throw _err("hpke/export-only", "seal is not available for an export-only AEAD");
+  var nonce = this._nonce();
+  var c = nodeCrypto.createCipheriv(aead.cipher, this._key, nonce, { authTagLength: aead.Nt });
+  if (aad && aad.length) c.setAAD(aad);
+  var body = concat([c.update(_buf(pt)), c.final()]);
+  var ct = concat([body, c.getAuthTag()]);
+  this._inc();
+  return ct;
+};
+Context.prototype.open = function (aad, ct) {
+  var aead = this._suite.aead;
+  if (this._role !== "R") throw _err("hpke/wrong-role", "open is only available on a recipient context (RFC 9180 sec. 5.2)");
+  if (aead.exportOnly) throw _err("hpke/export-only", "open is not available for an export-only AEAD");
+  ct = _buf(ct);
+  if (ct.length < aead.Nt) throw _err("hpke/open-failed", "ciphertext is shorter than the AEAD tag");
+  var nonce = this._nonce();
+  var d = nodeCrypto.createDecipheriv(aead.cipher, this._key, nonce, { authTagLength: aead.Nt });
+  if (aad && aad.length) d.setAAD(aad);
+  d.setAuthTag(ct.subarray(ct.length - aead.Nt));
+  var pt;
+  try { pt = concat([d.update(ct.subarray(0, ct.length - aead.Nt)), d.final()]); }
+  catch (e) { throw _err("hpke/open-failed", "AEAD authentication failed (RFC 9180 sec. 5.2)", e); }
+  this._inc();
+  return pt;
+};
+Context.prototype.export = function (exporterContext, len) {
+  if (!Number.isInteger(len) || len < 0) throw _err("hpke/export-length", "export length must be a non-negative integer");
+  return _labeledExpand(this._suite.kdf, this._suite.suiteId, this._exporterSecret, "sec", _buf(exporterContext), len);
+};
+function _buf(x) { return Buffer.isBuffer(x) ? x : Buffer.from(x || []); }
+
+// ---- suite resolution + setup ------------------------------------------------
+
+function _suite(ids) {
+  if (!ids || typeof ids !== "object") throw _err("hpke/unknown-suite", "suiteIds must be an object { kem, kdf, aead } from pki.hpke.suites");
+  var kemId = ids.kem, kdfId = ids.kdf, aeadId = ids.aead;
+  var kem = _kem(kemId), kdf = _kdf(kdfId), aead = _aead(aeadId);
+  return { kem: kem, kdf: kdf, aead: aead, kemId: kemId, kdfId: kdfId, aeadId: aeadId, suiteId: _hpkeSuiteId(kemId, kdfId, aeadId) };
+}
+
+// A KEM key argument is a node KeyObject or serialized bytes: a public key as a
+// raw buffer (or { pkm }), a private key as { skm, pkm } (raw scalar + public
+// point). A KAT drives the deterministic path via those serialized forms.
+function _recipPublic(suite, pk) {
+  if (Buffer.isBuffer(pk)) return { key: _importPublic(suite.kem, pk), pkm: pk };
+  if (pk && pk.pkm) return { key: _importPublic(suite.kem, pk.pkm), pkm: pk.pkm };
+  // A node KeyObject: derive its wire form. A null/undefined/invalid value must
+  // fail closed here rather than let node's export throw a raw error upward.
+  try {
+    return { key: pk, pkm: _exportPublic(suite.kem, pk) };
+  } catch (e) {
+    if (e instanceof HpkeError) throw e;
+    throw _err("hpke/bad-key", "invalid KEM public key (expected a node KeyObject, a raw buffer, or { pkm })", e);
+  }
+}
+function _recipPrivate(suite, sk) {
+  if (sk && sk.skm) return { key: _importPrivate(suite.kem, sk.skm, sk.pkm), pkm: sk.pkm };
+  // A raw scalar alone cannot be imported (an EC private key needs its public
+  // point for the JWK), so the serialized private form is { skm, pkm }; reject a
+  // bare buffer, and fail any other bad key closed rather than let node's
+  // createPublicKey throw a raw error out of the setup path.
+  if (Buffer.isBuffer(sk)) throw _err("hpke/bad-key", "a serialized private key must be provided as { skm, pkm } (raw scalar + public point), not a bare buffer");
+  try {
+    var pkm = _exportPublic(suite.kem, nodeCrypto.createPublicKey(sk));
+    return { key: sk, pkm: pkm };
+  } catch (e) {
+    if (e instanceof HpkeError) throw e;
+    throw _err("hpke/bad-key", "invalid recipient private key (expected a node KeyObject or { skm, pkm })", e);
+  }
+}
+
+// Resolve and validate the HPKE mode: RFC 9180 sec. 5.1 defines exactly base /
+// psk / auth / auth-psk. An unknown mode must fail closed, never key-schedule
+// with an out-of-registry mode byte.
+function _mode(opts) {
+  var mode = (opts.mode == null) ? MODE_BASE : opts.mode;
+  if (mode !== MODE_BASE && mode !== MODE_PSK && mode !== MODE_AUTH && mode !== MODE_AUTH_PSK) {
+    throw _err("hpke/unknown-mode", "unsupported HPKE mode " + JSON.stringify(mode) + " (RFC 9180 sec. 5.1 defines base / psk / auth / auth-psk)");
+  }
+  return mode;
+}
+
+// pki.hpke.suites -- the RFC 9180 sec. 7 registry code points (KEM / KDF / AEAD /
+// MODE), passed to the setup functions to select a ciphersuite (documented in the
+// @module @intro; a data registry, not a callable primitive).
+var suites = {
+  KEM: { DHKEM_P256_HKDF_SHA256: 0x0010, DHKEM_P521_HKDF_SHA512: 0x0012, DHKEM_X25519_HKDF_SHA256: 0x0020, DHKEM_X448_HKDF_SHA512: 0x0021 },
+  KDF: { HKDF_SHA256: 0x0001, HKDF_SHA512: 0x0003 },
+  AEAD: { AES_128_GCM: 0x0001, AES_256_GCM: 0x0002, CHACHA20_POLY1305: 0x0003, EXPORT_ONLY: 0xFFFF },
+  MODE: { BASE: MODE_BASE, PSK: MODE_PSK, AUTH: MODE_AUTH, AUTH_PSK: MODE_AUTH_PSK },
+};
+
+// setup*S(suiteIds, pkR, opts) -> { enc, context }. opts: { info, psk, pskId,
+// senderKey (auth), eph (KAT determinism) }. setup*R(suiteIds, enc, skR, opts).
+
+/**
+ * @primitive pki.hpke.setupS
+ * @signature pki.hpke.setupS(suiteIds, recipientPublicKey, opts?) -> { enc, context }
+ * @since 0.2.2
+ * @status experimental
+ * @spec RFC 9180
+ * @related pki.hpke.setupR, pki.hpke.seal
+ *
+ * Establish a sender HPKE context for a recipient KEM public key: encapsulate a
+ * shared secret and run the key schedule, returning the encapsulated key `enc`
+ * (send it to the recipient) and a `context` whose `.seal(aad, pt)` /
+ * `.export(ctx, L)` encrypt and derive further secrets. `suiteIds` is
+ * `{ kem, kdf, aead }` from `pki.hpke.suites`; `recipientPublicKey` is a node
+ * KeyObject or the serialized public key bytes. `opts.mode` selects base / psk /
+ * auth / auth-psk (default base); `opts.info`, `opts.psk`/`opts.pskId`, and
+ * `opts.senderKey` (auth modes) supply the corresponding inputs.
+ *
+ * @example
+ *   var s = pki.hpke.suites, ids = { kem: s.KEM.DHKEM_X25519_HKDF_SHA256, kdf: s.KDF.HKDF_SHA256, aead: s.AEAD.AES_128_GCM };
+ *   var pkR = Buffer.from("8c7781768956b9dd38997c5a83ab5b9315270a9f73d87d676573c5bca74e3e48", "hex");
+ *   var sender = pki.hpke.setupS(ids, pkR, { info: Buffer.from("app") });
+ *   var ct = sender.context.seal(Buffer.from("aad"), Buffer.from("secret"));
+ */
+function _setupS(ids, pkR, opts) {
+  opts = opts || {};
+  var suite = _suite(ids);
+  var mode = _mode(opts);
+  var r = _recipPublic(suite, pkR);
+  var kem = suite.kem, k;
+  if (mode === MODE_AUTH || mode === MODE_AUTH_PSK) {
+    if (kem.kind !== "ec" && kem.kind !== "okp") throw _err("hpke/auth-unsupported", "the KEM does not support authenticated modes");
+    if (opts.senderKey == null) throw _err("hpke/auth-key-required", "an authenticated mode requires opts.senderKey (the sender's KEM private key, RFC 9180 sec. 5.1.3)");
+    var s = _recipPrivate(suite, opts.senderKey);
+    k = _authEncap(kem, r.key, r.pkm, s.key, s.pkm, opts.eph);
+  } else {
+    k = _encap(kem, r.key, r.pkm, opts.eph);
+  }
+  var ctx = _keySchedule(suite, mode, k.sharedSecret, _buf(opts.info), _buf(opts.psk), _buf(opts.pskId), "S");
+  return { enc: k.enc, context: ctx, sharedSecret: k.sharedSecret };
+}
+/**
+ * @primitive pki.hpke.setupR
+ * @signature pki.hpke.setupR(suiteIds, enc, recipientPrivateKey, opts?) -> context
+ * @since 0.2.2
+ * @status experimental
+ * @spec RFC 9180
+ * @related pki.hpke.setupS, pki.hpke.open
+ *
+ * Establish the recipient HPKE context from the sender's encapsulated key `enc`
+ * and the recipient KEM private key (a node KeyObject or `{ skm, pkm }` -- the
+ * raw private scalar plus its public point),
+ * recovering the same shared secret and key schedule. The returned `context`
+ * `.open(aad, ct)` decrypts and `.export(ctx, L)` derives secrets. `opts` mirrors
+ * `setupS` (mode / info / psk / pskId), with `opts.senderPublicKey` for the auth
+ * modes. A ciphertext whose tag does not verify throws `hpke/open-failed`.
+ *
+ * @example
+ *   var s = pki.hpke.suites, ids = { kem: s.KEM.DHKEM_X25519_HKDF_SHA256, kdf: s.KDF.HKDF_SHA256, aead: s.AEAD.AES_128_GCM };
+ *   var pkR = Buffer.from("8c7781768956b9dd38997c5a83ab5b9315270a9f73d87d676573c5bca74e3e48", "hex");
+ *   var skR = Buffer.from("009f2181fba5f8908632c10ea1137c40a849728fde016c4602458b943a5dc048", "hex");
+ *   var sender = pki.hpke.setupS(ids, pkR);
+ *   var recipient = pki.hpke.setupR(ids, sender.enc, { skm: skR, pkm: pkR });
+ *   var pt = recipient.open(Buffer.alloc(0), sender.context.seal(Buffer.alloc(0), Buffer.from("hi")));
+ */
+function _setupR(ids, enc, skR, opts) {
+  opts = opts || {};
+  var suite = _suite(ids);
+  var mode = _mode(opts);
+  var r = _recipPrivate(suite, skR);
+  var kem = suite.kem, ss;
+  if (mode === MODE_AUTH || mode === MODE_AUTH_PSK) {
+    if (opts.senderPublicKey == null) throw _err("hpke/auth-key-required", "an authenticated mode requires opts.senderPublicKey (the sender's KEM public key, RFC 9180 sec. 5.1.3)");
+    var pkS = _recipPublic(suite, opts.senderPublicKey);
+    ss = _authDecap(kem, _buf(enc), r.key, r.pkm, pkS.key, pkS.pkm);
+  } else {
+    ss = _decap(kem, _buf(enc), r.key, r.pkm);
+  }
+  return _keySchedule(suite, mode, ss, _buf(opts.info), _buf(opts.psk), _buf(opts.pskId), "R");
+}
+
+/**
+ * @primitive pki.hpke.seal
+ * @signature pki.hpke.seal(suiteIds, recipientPublicKey, opts, aad, pt) -> { enc, ct }
+ * @since 0.2.2
+ * @status experimental
+ * @spec RFC 9180
+ * @related pki.hpke.open, pki.hpke.setupS
+ *
+ * Single-shot HPKE encryption (RFC 9180 sec. 6): set up a sender context and
+ * encrypt one plaintext, returning the encapsulated key `enc` and ciphertext
+ * `ct`. Equivalent to `setupS` followed by one `context.seal`. `opts` is the
+ * `setupS` options object (mode / info / psk / senderKey).
+ *
+ * @example
+ *   var s = pki.hpke.suites, ids = { kem: s.KEM.DHKEM_X25519_HKDF_SHA256, kdf: s.KDF.HKDF_SHA256, aead: s.AEAD.AES_256_GCM };
+ *   var pkR = Buffer.from("8c7781768956b9dd38997c5a83ab5b9315270a9f73d87d676573c5bca74e3e48", "hex");
+ *   var out = pki.hpke.seal(ids, pkR, {}, Buffer.from("aad"), Buffer.from("msg"));
+ */
+function seal(ids, pkR, opts, aad, pt) {
+  var s = _setupS(ids, pkR, opts);
+  return { enc: s.enc, ct: s.context.seal(_buf(aad), _buf(pt)) };
+}
+
+/**
+ * @primitive pki.hpke.open
+ * @signature pki.hpke.open(suiteIds, enc, recipientPrivateKey, opts, aad, ct) -> pt
+ * @since 0.2.2
+ * @status experimental
+ * @spec RFC 9180
+ * @related pki.hpke.seal, pki.hpke.setupR
+ *
+ * Single-shot HPKE decryption (RFC 9180 sec. 6): set up a recipient context from
+ * `enc` and decrypt one ciphertext, returning the plaintext. A tag that does not
+ * verify throws `hpke/open-failed` and returns no plaintext.
+ *
+ * @example
+ *   var s = pki.hpke.suites, ids = { kem: s.KEM.DHKEM_X25519_HKDF_SHA256, kdf: s.KDF.HKDF_SHA256, aead: s.AEAD.AES_256_GCM };
+ *   var pkR = Buffer.from("8c7781768956b9dd38997c5a83ab5b9315270a9f73d87d676573c5bca74e3e48", "hex");
+ *   var skR = Buffer.from("009f2181fba5f8908632c10ea1137c40a849728fde016c4602458b943a5dc048", "hex");
+ *   var o = pki.hpke.seal(ids, pkR, {}, Buffer.alloc(0), Buffer.from("m"));
+ *   var pt = pki.hpke.open(ids, o.enc, { skm: skR, pkm: pkR }, {}, Buffer.alloc(0), o.ct);
+ */
+function open(ids, enc, skR, opts, aad, ct) {
+  return _setupR(ids, enc, skR, opts).open(_buf(aad), _buf(ct));
+}
+
+module.exports = {
+  suites: suites,
+  setupS: _setupS, setupR: _setupR,
+  seal: seal, open: open,
+};

package/lib/oid.js

@@ -201,7 +201,14 @@ var FAMILIES = {
   // CEK-HKDF content-encryption wrapper (RFC 9709) a KEMRecipientInfo names, plus
   // the RSA-KEM SPKI algorithm (RFC 9690). Parameters are absent for the HKDFs.
   smimeAlg: { base: [1, 2, 840, 113549, 1, 9, 16, 3], of: {
-    "id-rsa-kem": 14, hkdfWithSha256: 28, hkdfWithSha384: 29, hkdfWithSha512: 30, cekHkdfSha256: 31 } },
+    "id-rsa-kem": 14, "id-alg-hss-lms-hashsig": 17,
+    hkdfWithSha256: 28, hkdfWithSha384: 29, hkdfWithSha512: 30, cekHkdfSha256: 31 } },
+
+  // PKIX algorithms arc -- the stateful hash-based signature algorithm
+  // identifiers (RFC 9802 sec. 4). HSS/LMS additionally has the SMIME
+  // id-alg-hss-lms-hashsig OID above (RFC 9708 / RFC 9802 share it).
+  pkixAlg: { base: [1, 3, 6, 1, 5, 5, 7, 6], of: {
+    "id-alg-xmss-hashsig": 34, "id-alg-xmssmt-hashsig": 35 } },
 
   // RSA-KEM key-transport algorithm (RFC 9690, obsoletes RFC 5990) on the ISO
   // 18033-2 arc -- the kem OID an RSA KEMRecipientInfo carries (distinct from the
@@ -501,6 +508,9 @@ var _PARAMS_ABSENT = new Set();
   // HKDF key-derivation identifiers (RFC 8619 sec. 2: when any of these appear
   // within AlgorithmIdentifier, the parameters component SHALL be absent).
   "hkdfWithSha256", "hkdfWithSha384", "hkdfWithSha512",
+  // Stateful hash-based signatures (RFC 9802 sec. 4 / RFC 9708): the parameters
+  // field MUST be absent for HSS/LMS, XMSS, and XMSS^MT public keys and signatures.
+  "id-alg-hss-lms-hashsig", "id-alg-xmss-hashsig", "id-alg-xmssmt-hashsig",
 ].forEach(function (nm) {
   var d = byName(nm);
   // A seed-list typo must fail at module load -- admitting undefined would

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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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:ef020f83-b6b5-464b-aefb-b888959cf51c",
+  "serialNumber": "urn:uuid:78e0173e-dadb-4062-861f-ed7ded314dab",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-11T23:26:22.326Z",
+    "timestamp": "2026-07-12T03:33:57.948Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.0",
+      "bom-ref": "@blamejs/pki@0.2.2",
       "type": "application",
       "name": "pki",
-      "version": "0.2.0",
+      "version": "0.2.2",
       "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.2.0",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.2",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.0",
+      "ref": "@blamejs/pki@0.2.2",
       "dependsOn": []
     }
   ]