@blamejs/pki 0.7.30 → 0.7.31

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.7.31 — 2026-09-12
+
+HPKE encrypts to an ML-KEM public key.
+
+### Added
+
+- pki.hpke.suites.KEM.ML_KEM_512, ML_KEM_768 and ML_KEM_1024 (0x0040, 0x0041, 0x0042). The HPKE binding is FIPS 203 encapsulation and decapsulation with the 32-byte ML-KEM shared secret as the HPKE shared secret and the 64-byte seed as the private key. setupS and seal take the recipient's encapsulation key as raw bytes, as { pkm }, or as a node:crypto KeyObject; setupR and open take { skm } holding the seed, with pkm optional, or a KeyObject. The base and psk modes and every KDF and AEAD apply; the auth and auth-psk modes, which the ML-KEM KEMs do not define (draft-ietf-hpke-pq sec. 7.2), are refused with hpke/auth-unsupported at both ends. An encapsulation key that fails the FIPS 203 sec. 7.2 check (length or a coefficient at or above q) is refused at import, and an encapsulated key of the wrong length is refused before decapsulation, each as hpke/bad-key. The recipient side of the draft's A.1, A.2 and A.3 vectors (ML-KEM-512 and -768 with HKDF-SHA256, ML-KEM-1024 with HKDF-SHA384) is a full known answer: the vector's encapsulated key decapsulated under its seed, all ten decryptions and all five exports. The sender side is proven by round trip: node:crypto takes no encapsulation randomness, so a fixed ephemeral (opts.eph) is refused on an ML-KEM suite with hpke/bad-input rather than ignored.
+- pki.hpke.suites.KDF.HKDF_SHA384 (0x0002), for any KEM. The draft-ietf-hpke-pq A.3 vector proves it in the key schedule. DHKEM(P-384) stays unoffered: no known-answer vector pairs it with an HKDF key schedule.
+
+### Changed
+
+- A serialized HPKE private key, { skm, pkm } on setupR, open, opts.eph and opts.senderKey, passes one door for every suite. skm must be a Buffer of exactly the suite's private-key length, an EC scalar additionally in [1, n-1]; the public key is derived from it; and pkm, now optional, must equal that derivation when given. Before this a DHKEM recipient given { skm } alone escaped as a raw TypeError, and a pkm of the wrong length or of another key was fed into the KEM context unchecked, producing a context that could open nothing. A node:crypto KeyObject is checked against the suite's curve or ML-KEM parameter set, and a public KeyObject where a private one is due is refused rather than tried; each refusal is hpke/bad-key naming what was checked.
+- opts.senderKey on setupS and opts.senderPublicKey on setupR are refused with hpke/bad-input in the base and psk modes, where they were previously left unused: a caller who supplied one without mode auth or auth-psk was not authenticating the exchange. A value of undefined or null is still absent. opts.eph is { skm, pkm } or absent (undefined or null); another value, such as 0 or an empty string, is refused with hpke/bad-input instead of being read as absent.
+- pki.hpke.setupS and setupR read each option once, at entry, into a snapshot. mode was read at the default and again at the use, so an option supplied through an accessor could answer auth to the first read and base to the second and get an unauthenticated setup; senderKey was read at its presence check and again at import.
+- The HKDF expand step wipes every block it computed when a later block's HMAC fails, as it already did on the succeeding path. A private KeyObject handed where a public key is due (the recipient key on setupS and seal, senderPublicKey on setupR) now has its public half taken before export, so no JWK carrying the private scalar is produced.
+- The fuzz target for the HPKE recipient path decapsulates under an ML-KEM-768 seed as well as an X25519 key, and selects HKDF-SHA384 among the KDFs.
+
 ## v0.7.30 — 2026-09-12
 
 The Sigstore bundle verifier decides with operations bound when the module loads.

package/README.md

@@ -247,7 +247,7 @@ comment blocks, is at [pkijs.com](https://pkijs.com).
 | `pki.merkle` | Merkle-tree proof verification (RFC 6962 / RFC 9162). `leafHash`, `nodeHash`, and `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, which is the append-only guarantee; each is 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 and CCADB trust-store ingestion. `parseCertdata` reads the NSS `certdata.txt` object stream and `parseCcadbCsv` the CCADB CSV export, both into one constraint-carrying anchor shape: the per-purpose trust bits, where 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 and serial rather than adjacency and are cross-checked against the parsed DER, so metadata cannot attach to the wrong root. `anchor()` hands an entry to `pki.path.validate({ trustAnchors, checkPurpose })`, and `anchor(entry, { nameConstraints })` attaches the namespace a root program trusts a root for when that is narrower than the root certificate states, a `{ permitted, excluded }` pair of `{ tag, base }` subtrees that `validate` seeds as the RFC 5280 §6.1.1(h)(i) initial value, intersecting with each certificate's own constraints. 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 in CMS by RFC 9708, profiled by NIST SP 800-208 for CNSA 2.0 firmware signing. `verify` checks an HSS signature, where every level must pass, and `verifyLms` a single-tree LMS, over the raw public-key and signature blobs the parsers already surface. Pure public-input SHA-256 and SHAKE256 hashing, a data-driven typecode registry, and bounds-before-slice reads; a malformed blob throws a typed `ShbsError` while a well-formed but wrong signature returns `false`. Verification only by design, since stateful signing needs atomic one-time-key state that belongs in an HSM. `pki.path.validate` verifies an HSS-signed certificate on its own, so a chain reaching one needs no separate call: the signature covers the whole tbsCertificate rather than a digest of it (RFC 9802 §7.1), and a CertificateList naming the algorithm takes the same route. It is proven against the self-signed certificate RFC 9802 Appendix A publishes — `verify`, `verifyLms` |
-| `pki.hpke` | Hybrid Public Key Encryption (RFC 9180), the encrypt-to-a-public-key primitive behind TLS ECH, MLS, and OHTTP. `setupS` and `setupR` establish a sender or recipient context (KEM encapsulation plus the HKDF key schedule); the context's `seal` and `open` AEAD-encrypt with a sequence-counter nonce, and `export` derives further secrets; the module-level `seal` and `open` are single-shot wrappers. DHKEM (P-256, P-521, X25519, X448) by HKDF-SHA256/SHA512 by AES-GCM / ChaCha20Poly1305 / export-only, across 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 and X-Wing are a registry data-row extension pending stable drafts — `suites`, `setupS`, `setupR`, `seal`, `open` |
+| `pki.hpke` | Hybrid Public Key Encryption (RFC 9180), the encrypt-to-a-public-key primitive behind TLS ECH, MLS, and OHTTP. `setupS` and `setupR` establish a sender or recipient context (KEM encapsulation plus the HKDF key schedule); the context's `seal` and `open` AEAD-encrypt with a sequence-counter nonce, and `export` derives further secrets; the module-level `seal` and `open` are single-shot wrappers. DHKEM (P-256, P-521, X25519, X448) in all four modes, proven against the RFC 9180 Appendix A vectors, and the post-quantum ML-KEM-512/768/1024 KEMs (IANA 0x0040 to 0x0042) in the base and psk modes, proven against the draft-ietf-hpke-pq Appendix A vectors; HKDF-SHA256/SHA384/SHA512 by AES-GCM / ChaCha20Poly1305 / export-only. DHKEM(P-384) has no vector under an HKDF key schedule and fails closed. Pure composition over `node:crypto`; the PQ/T hybrid KEMs are a registry data-row extension once the CFRG combiner draft stabilizes — `suites`, `setupS`, `setupR`, `seal`, `open` |
 | `pki.kem` | Composite ML-KEM key establishment (draft-ietf-lamps-pq-composite-kem), a post-quantum ML-KEM hybridized with a traditional RSA-OAEP, ECDH, X25519, or X448 so the established secret holds if either component is later broken. `encapsulate` turns a recipient's composite `SubjectPublicKeyInfo` into a 256-bit shared secret and a ciphertext; `decapsulate` recovers the same secret from the ciphertext and the composite PKCS#8 private key. Each component KEM runs independently and the two secrets are mixed through a SHA3-256 combiner that binds the traditional ciphertext, the traditional public key, and a per-algorithm label. The twelve algorithms pair ML-KEM-768 and ML-KEM-1024 with RSA-OAEP 2048/3072/4096, ECDH over P-256/P-384/P-521 and brainpoolP256r1/P384r1, X25519, and X448, each verified against the draft Appendix G known-answer vectors; a malformed key or ciphertext, an unsupported algorithm, or a component decapsulation failure throws a typed `KemError` — `encapsulate`, `decapsulate` |
 | `pki.sigstore` | Offline verifier for a Sigstore bundle, the artifact `npm publish --provenance` produces and the registry serves. `verifyBundle` composes five fail-closed legs against caller-pinned trust (Fulcio CA roots and Rekor log keys, never trusted from the bundle): the DSSE signature over its PAE preimage under the Fulcio leaf key, the ephemeral Fulcio certificate chain validated as of the Rekor log time, the RFC 9162 inclusion proof folded to a Rekor-signed tree root, the log entry bound to this exact signature, and the in-toto SLSA subject digest the caller confirms against the published artifact. It reuses the X.509 parser, the RFC 5280 path validator, and the Merkle verifier; the net-new codecs are the DSSE PAE byte-builder and a fail-closed JSON reader. `verified: true` says the artifact was signed and logged, not that a party you trust signed it — Fulcio issues to anyone who completes an OIDC flow, so who signed is decided only by `opts.identity`, and `identityChecked` reports which of its fields were compared. An identity policy naming no field, or a field name that is not one of the three, is refused rather than satisfied — either would accept every signer while reading as a policy in force. A sixth leg is opt-in: pinning the certificate-transparency logs in `opts.ctLogs` checks the receipt Fulcio embeds in the certificate it issues (RFC 6962 §3.2), verified over the certificate as it stood before the receipt was added and under the key of the log that issued it, so the verdict says the signing certificate was public when it was issued rather than handed out quietly. At least one receipt must verify against a pinned log, the verdict reports `sctChecked` and `validScts`, and an empty log set is refused rather than read as a policy that checks nothing. Both content arms are read: a DSSE-wrapped in-toto attestation, and a message signature over an artifact's own bytes, which `cosign sign-blob` produces. For that arm `opts.artifact` supplies the bytes, and they are held to the hash the Rekor `hashedrekord` entry records before the signature is checked over them; the `messageDigest` the bundle carries is covered by no signature, so it is compared against the computed digest and never used in its place. `contentType` names the arm and the verdict has one shape for both — `pae`, `parseBundle`, `verifyBundle` |
 | `pki.inspect` | Human-readable inspection, the pure-JS equivalent of `openssl x509/crl/req/cms -text`. `certificate(pem \| der \| parsed)` renders an OpenSSL-style report: version, serial, signature algorithm, issuer and subject distinguished names, validity, public-key details (curve or modulus size plus the raw point or modulus), every decoded extension with its critical flag, and the signature. `crl`, `csr`, and `cms` render the other formats the same way — a CRL like `openssl crl -text`, a CSR like `openssl req -text`, and a CMS message like `openssl cms -cmsout -print`, with a stable summary for a non-SignedData ContentInfo — and `any(input)` detects the format and routes to the right report. Built over the strict parsers and the two-way OID registry with one set of field renderers, it names extension and algorithm OIDs an OpenSSL build shows only as raw bytes. No OpenSSL dependency, and the format is stable and OpenSSL-familiar rather than pinned to one OpenSSL version. A certificate policy's user notice renders as text, both its explicit text and a notice reference with the notice numbers that identify it, rather than hex, and a malformed part falls back to a hex dump rather than throwing — `certificate`, `crl`, `csr`, `cms`, `any` |

package/lib/hpke.js

@@ -8,16 +8,18 @@
  * @fullname   HPKE (Hybrid Public Key Encryption, RFC 9180)
  * @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.
+ *   public key into an encapsulated key plus an AEAD-encrypting context. Two KEM
+ *   families run the RFC 9180 key schedule: the DHKEM suites P-256, P-521, X25519,
+ *   and X448 in all four modes (base / psk / auth / auth-psk), proven against the
+ *   RFC 9180 Appendix A known-answer vectors, and the post-quantum ML-KEM-512 /
+ *   -768 / -1024 KEMs (IANA code points 0x0040 to 0x0042, draft-ietf-hpke-pq) in
+ *   the base and psk modes, proven against that draft's Appendix A vectors. The
+ *   KDFs are HKDF-SHA256 / HKDF-SHA384 / HKDF-SHA512; the AEADs are AES-128-GCM,
+ *   AES-256-GCM, ChaCha20Poly1305, and export-only. DHKEM(P-384) is RFC-registered
+ *   but no known-answer vector pairs it with an HKDF key schedule, so a request
+ *   for it fails closed. The PQ/T hybrid KEMs and the SHAKE-based KDFs of the HPKE
+ *   revision are a data-row extension once their specifications stabilize. Pure
+ *   composition over node:crypto: no ASN.1, no schema engine.
  *   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
@@ -28,7 +30,11 @@ var nodeCrypto = require("crypto");
 var frameworkError = require("./framework-error");
 var guard = require("./guard-all");
 var intrinsic = require("./guard-intrinsic");
+var oid = require("./oid");
 var _hasOwn = intrinsic.hasOwn;
+var _isBuffer = intrinsic.isBuffer, _bufferFrom = intrinsic.bufferFrom, _bufferAlloc = intrinsic.bufferAlloc;
+var _bufferConcat = intrinsic.bufferConcat, _bufferEquals = intrinsic.bufferEquals, _compare = intrinsic.compare;
+var _subarray = intrinsic.subarray;
 
 var HpkeError = frameworkError.HpkeError;
 function _err(code, message, cause) { return new HpkeError(code, message, cause); }
@@ -49,6 +55,7 @@ function L(s) { return Buffer.from(s, "ascii"); }
 
 var KDFS = intrinsic.assign(intrinsic.create(null), {
   0x0001: { hash: "sha256", Nh: 32 },
+  0x0002: { hash: "sha384", Nh: 48 },
   0x0003: { hash: "sha512", Nh: 64 },
 });
 var AEADS = intrinsic.assign(intrinsic.create(null), {
@@ -57,11 +64,18 @@ var AEADS = intrinsic.assign(intrinsic.create(null), {
   0x0003: { cipher: "chacha20-poly1305", Nk: 32, Nn: 12, Nt: 16 },
   0xFFFF: { exportOnly: true, Nn: 12 },
 });
+function _mlKemRow(name, oidName, node) {
+  var p = oid.kemParams(oidName);
+  return { kind: "mlkem", name: name, node: node, Nsecret: p.ss, Npub: p.ek, Nenc: p.ct, Nsk: 64 };
+}
 var KEMS = intrinsic.assign(intrinsic.create(null), {
-  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 },
+  0x0010: { kind: "ec", name: "P-256", curve: "P-256", nodeCurve: "prime256v1", kdf: 0x0001, Nsecret: 32, Npub: 65, Nsk: 32 },
+  0x0012: { kind: "ec", name: "P-521", curve: "P-521", nodeCurve: "secp521r1", kdf: 0x0003, Nsecret: 64, Npub: 133, Nsk: 66 },
+  0x0020: { kind: "okp", name: "X25519", curve: "X25519", kdf: 0x0001, Nsecret: 32, Npub: 32, Nsk: 32 },
+  0x0021: { kind: "okp", name: "X448", curve: "X448", kdf: 0x0003, Nsecret: 64, Npub: 56, Nsk: 56 },
+  0x0040: _mlKemRow("ML-KEM-512", "id-ml-kem-512", "ml-kem-512"),
+  0x0041: _mlKemRow("ML-KEM-768", "id-ml-kem-768", "ml-kem-768"),
+  0x0042: _mlKemRow("ML-KEM-1024", "id-ml-kem-1024", "ml-kem-1024"),
 });
 
 var MODE_BASE = 0x00, MODE_PSK = 0x01, MODE_AUTH = 0x02, MODE_AUTH_PSK = 0x03;
@@ -78,19 +92,24 @@ function _extract(hash, Nh, salt, ikm) {
 }
 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++) {
-    var fed = concat([t, info, Buffer.from([i])]);
-    t = nodeCrypto.createHmac(hash, prk).update(fed).digest();
+  var out = [], t = Buffer.alloc(0), n = Math.ceil(len / Nh), fed = null, joined = null;
+  try {
+    for (var i = 1; i <= n; i++) {
+      fed = concat([t, info, Buffer.from([i])]);
+      t = nodeCrypto.createHmac(hash, prk).update(fed).digest();
+      guard.secret.zeroize(fed, HpkeError, "hpke/bad-input", "an expand feedback input");
+      fed = null;
+      out.push(t);
+    }
+    joined = concat(out);
+    var exact = Buffer.alloc(len);
+    joined.copy(exact, 0, 0, len);
+    return exact;
+  } finally {
     guard.secret.zeroize(fed, HpkeError, "hpke/bad-input", "an expand feedback input");
-    out.push(t);
+    guard.secret.zeroize(joined, HpkeError, "hpke/bad-input", "the KDF accumulator");
+    for (var oi = 0; oi < out.length; oi++) guard.secret.zeroize(out[oi], HpkeError, "hpke/bad-input", "a KDF block");
   }
-  var joined = concat(out);
-  var exact = Buffer.alloc(len);
-  joined.copy(exact, 0, 0, len);
-  guard.secret.zeroize(joined, HpkeError, "hpke/bad-input", "the KDF accumulator");
-  for (var oi = 0; oi < out.length; oi++) guard.secret.zeroize(out[oi], HpkeError, "hpke/bad-input", "a KDF block");
-  return exact;
 }
 function _labeledExtract(kdf, suiteId, salt, label, ikm) {
   var labeled = concat([HPKE_V1, suiteId, L(label), ikm]);
@@ -104,10 +123,27 @@ function _labeledExpand(kdf, suiteId, prk, label, info, len) {
 
 var OKP_SPKI = intrinsic.assign(intrinsic.create(null), { X25519: "302a300506032b656e032100", X448: "3042300506032b656f033900" });
 var OKP_PKCS8 = intrinsic.assign(intrinsic.create(null), { X25519: "302e020100300506032b656e04220420", X448: "3046020100300506032b656f043a0438" });
+var EC_SEC1 = intrinsic.assign(intrinsic.create(null), {
+  "P-256": { head: "30310201010420", tail: "a00a06082a8648ce3d030107",
+    order: "ffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551" },
+  "P-521": { head: "30500201010442", tail: "a00706052b81040023",
+    order: "01ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffa51868783bf2f966b7fcc0148f709a5d03bb5c9b8899c47aebb6fb71e91386409" },
+});
+var ML_KEM_SPKI = intrinsic.assign(intrinsic.create(null), {
+  "ML-KEM-512": "30820332300b06096086480165030404010382032100",
+  "ML-KEM-768": "308204b2300b0609608648016503040402038204a100",
+  "ML-KEM-1024": "30820632300b06096086480165030404030382062100",
+});
+var ML_KEM_PKCS8 = intrinsic.assign(intrinsic.create(null), {
+  "ML-KEM-512": "3054020100300b060960864801650304040104428040",
+  "ML-KEM-768": "3054020100300b060960864801650304040204428040",
+  "ML-KEM-1024": "3054020100300b060960864801650304040304428040",
+});
+function _hex(h) { return _bufferFrom(h, "hex"); }
 
 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");
+  if (!_isBuffer(raw) || raw.length !== kem.Npub) {
+    throw _err("hpke/bad-key", kem.name + " public key must be " + kem.Npub + " bytes");
   }
   try {
     if (kem.kind === "ec") {
@@ -116,31 +152,62 @@ function _importPublic(kem, raw) {
       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" });
+    var prefix = kem.kind === "mlkem" ? ML_KEM_SPKI[kem.name] : OKP_SPKI[kem.curve];
+    return nodeCrypto.createPublicKey({ key: _bufferConcat([_hex(prefix), raw]), format: "der", type: "spki" });
   } catch (e) {
     if (e instanceof HpkeError) throw e;
-    throw _err("hpke/bad-key", "invalid " + kem.curve + " public key", e);
+    throw _err("hpke/bad-key", "invalid " + kem.name + " public key" +
+      (kem.kind === "mlkem" ? " (FIPS 203 sec. 7.2 encapsulation key check)" : ""), e);
   }
 }
 function _exportPublic(kem, keyObject) {
-  var jwk = keyObject.export({ format: "jwk" });
+  var pub = keyObject.type === "public" ? keyObject : nodeCrypto.createPublicKey(keyObject);
+  if (kem.kind === "mlkem") {
+    var der = pub.export({ format: "der", type: "spki" }), prefix = _hex(ML_KEM_SPKI[kem.name]);
+    if (der.length !== prefix.length + kem.Npub || !_bufferEquals(_subarray(der, 0, prefix.length), prefix)) {
+      throw _err("hpke/bad-key", "the KeyObject is not an " + kem.name + " key");
+    }
+    return _subarray(der, prefix.length);
+  }
+  var jwk = pub.export({ format: "jwk" });
+  if (jwk.crv !== kem.curve) throw _err("hpke/bad-key", "the KeyObject is not a " + kem.name + " key");
   if (kem.kind === "ec") return concat([Buffer.from([0x04]), _b64u(jwk.x), _b64u(jwk.y)]);
   return _b64u(jwk.x);
 }
 function _b64u(s) { return guard.encoding.base64url(s, null, _err, "hpke/bad-key", "JWK coordinate"); }
 
-function _importPrivate(kem, rawSk, rawPk) {
+function _scalarInRange(d, order) {
+  return _compare(d, _bufferAlloc(d.length)) > 0 && _compare(d, order) < 0;
+}
+function _importPrivate(kem, rawSk) {
+  if (!_isBuffer(rawSk) || rawSk.length !== kem.Nsk) {
+    throw _err("hpke/bad-key", kem.name + " private key must be " +
+      (kem.kind === "mlkem" ? "the 64-byte seed" : "the " + kem.Nsk + "-byte scalar") + " as a Buffer");
+  }
+  var der;
+  if (kem.kind === "ec") {
+    var sec1 = EC_SEC1[kem.curve];
+    if (!_scalarInRange(rawSk, _hex(sec1.order))) throw _err("hpke/bad-key", kem.name + " private scalar is outside [1, n-1]");
+    der = _bufferConcat([_hex(sec1.head), rawSk, _hex(sec1.tail)]);
+  } else {
+    der = _bufferConcat([_hex(kem.kind === "mlkem" ? ML_KEM_PKCS8[kem.name] : OKP_PKCS8[kem.curve]), rawSk]);
+  }
   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" });
+    return nodeCrypto.createPrivateKey({ key: der, format: "der", type: kem.kind === "ec" ? "sec1" : "pkcs8" });
   } catch (e) {
-    throw _err("hpke/bad-key", "invalid " + kem.curve + " private key", e);
+    throw _err("hpke/bad-key", "invalid " + kem.name + " private key", e);
+  } finally {
+    guard.secret.zeroize(der, HpkeError, "hpke/bad-input", "the private key envelope");
   }
 }
+function _boundPublic(kem, privateKey, pkm) {
+  var derived = _exportPublic(kem, nodeCrypto.createPublicKey(privateKey));
+  if (pkm === undefined) return derived;
+  if (!_isBuffer(pkm) || !_bufferEquals(derived, pkm)) {
+    throw _err("hpke/bad-key", "pkm is not the " + kem.name + " public key derived from skm");
+  }
+  return derived;
+}
 function _dh(privateKey, publicKey) {
   try {
     return nodeCrypto.diffieHellman({ privateKey: privateKey, publicKey: publicKey });
@@ -164,12 +231,33 @@ function _extractAndExpand(kem, dh, kemContext) {
 function _kemId(kem) { for (var k in KEMS) if (KEMS[k] === kem) return Number(k); return 0; }
 
 function _ephemeral(kem, eph) {
-  if (eph) return { skE: _importPrivate(kem, eph.skm, eph.pkm), enc: _buf(eph.pkm) };
+  if (eph != null) {
+    if (typeof eph !== "object") throw _err("hpke/bad-input", "eph must be { skm, pkm } (a fixed ephemeral key pair), got " + guard.text.showValue(eph));
+    var skE = _importPrivate(kem, eph.skm);
+    return { skE: skE, enc: _boundPublic(kem, skE, eph.pkm) };
+  }
   var kp = _generate(kem);
   return { skE: kp.privateKey, enc: _exportPublic(kem, kp.publicKey) };
 }
 function _wipeDh(dh) { guard.secret.zeroize(dh, HpkeError, "hpke/bad-input", "the KEM shared secret"); }
+function _mlKemEncap(kem, pkR, eph) {
+  if (eph != null) {
+    throw _err("hpke/bad-input", "eph (a fixed ephemeral key pair) applies to a DHKEM suite; " + kem.name + " encapsulation takes its randomness from the runtime");
+  }
+  var r;
+  try { r = nodeCrypto.encapsulate(pkR); }
+  catch (e) { throw _err("hpke/bad-key", kem.name + " encapsulation failed", e); }
+  return { sharedSecret: r.sharedKey, enc: r.ciphertext };
+}
+function _mlKemDecap(kem, enc, skR) {
+  if (enc.length !== kem.Nenc) {
+    throw _err("hpke/bad-key", kem.name + " encapsulated key must be " + kem.Nenc + " bytes (FIPS 203 sec. 7.3 ciphertext check)");
+  }
+  try { return nodeCrypto.decapsulate(skR, enc); }
+  catch (e) { throw _err("hpke/bad-key", kem.name + " decapsulation failed", e); }
+}
 function _encap(kem, pkR, pkRm, eph) {
+  if (kem.kind === "mlkem") return _mlKemEncap(kem, pkR, eph);
   var e = _ephemeral(kem, eph);
   var dh = null;
   try {
@@ -178,6 +266,7 @@ function _encap(kem, pkR, pkRm, eph) {
   } finally { _wipeDh(dh); }
 }
 function _decap(kem, enc, skR, pkRm) {
+  if (kem.kind === "mlkem") return _mlKemDecap(kem, enc, skR);
   var pkE = _importPublic(kem, enc);
   var dh = null;
   try {
@@ -307,14 +396,32 @@ function _recipPublic(suite, pk) {
   }
 }
 function _recipPrivate(suite, sk) {
-  if (sk && sk.skm) return { key: _importPrivate(suite.kem, sk.skm, sk.pkm), pkm: sk.pkm };
-  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");
+  var kem = suite.kem;
+  if (sk && sk.skm != null) {
+    var key = _importPrivate(kem, sk.skm);
+    return { key: key, pkm: _boundPublic(kem, key, sk.pkm) };
+  }
+  if (_isBuffer(sk)) {
+    throw _err("hpke/bad-key", "a serialized " + kem.name + " private key must be provided as { skm" +
+      (kem.kind === "mlkem" ? " } holding the 64-byte seed" : ", pkm } (the raw scalar, and optionally its public key)") + ", not a bare buffer");
+  }
   try {
-    var pkm = _exportPublic(suite.kem, nodeCrypto.createPublicKey(sk));
+    if (sk.type !== "private") throw _err("hpke/bad-key", "the private key must be a private KeyObject or { skm, pkm }, got a " + guard.text.showValue(sk.type) + " KeyObject");
+    var pkm = _exportPublic(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);
+    throw _err("hpke/bad-key", "invalid private key (expected a node KeyObject or { skm, pkm })", e);
+  }
+}
+function _requireAuthCapable(kem) {
+  if (kem.kind === "mlkem") {
+    throw _err("hpke/auth-unsupported", kem.name + " defines no AuthEncap / AuthDecap (draft-ietf-hpke-pq sec. 7.2); use the psk mode or a signature");
+  }
+}
+function _refuseUnusedAuthKey(value, name, mode) {
+  if (value != null) {
+    throw _err("hpke/bad-input", name + " applies to the auth and auth-psk modes; mode " + mode + " would leave it unused, so the exchange it was meant to authenticate would not be");
   }
 }
 
@@ -332,7 +439,7 @@ var _SETUP_S_KEYS = _withCommon({
 var _SETUP_R_KEYS = _withCommon({
   senderPublicKey: 1,
 });
-function _mode(opts, keys, who) {
+function _options(opts, keys, who) {
   guard.identifier.assertKnownKeys(opts, keys, _err, "hpke/bad-input", function (k) {
     var other = (keys === _SETUP_S_KEYS ? _SETUP_R_KEYS : _SETUP_S_KEYS);
     return "unknown HPKE " + who + " option " + JSON.stringify(k) +
@@ -340,17 +447,21 @@ function _mode(opts, keys, who) {
         ? " -- that option belongs to the other end of the exchange, where it would authenticate or seed; here it would do nothing"
         : "") + " -- accepted: " + Object.keys(keys).sort().join(", ");
   });
-  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 " + guard.text.showValue(mode) + " (RFC 9180 sec. 5.1 defines base / psk / auth / auth-psk)");
+  var o = guard.identifier.snapshotOptions(opts, keys);
+  if (o.mode == null) o.mode = MODE_BASE;
+  if (o.mode !== MODE_BASE && o.mode !== MODE_PSK && o.mode !== MODE_AUTH && o.mode !== MODE_AUTH_PSK) {
+    throw _err("hpke/unknown-mode", "unsupported HPKE mode " + guard.text.showValue(o.mode) + " (RFC 9180 sec. 5.1 defines base / psk / auth / auth-psk)");
   }
-  return mode;
+  return o;
 }
 
 // @module @intro; a data registry, not a callable primitive).
 var suites = intrinsic.assign(intrinsic.create(null), {
-  KEM: intrinsic.assign(intrinsic.create(null), { DHKEM_P256_HKDF_SHA256: 0x0010, DHKEM_P521_HKDF_SHA512: 0x0012, DHKEM_X25519_HKDF_SHA256: 0x0020, DHKEM_X448_HKDF_SHA512: 0x0021 }),
-  KDF: intrinsic.assign(intrinsic.create(null), { HKDF_SHA256: 0x0001, HKDF_SHA512: 0x0003 }),
+  KEM: intrinsic.assign(intrinsic.create(null), {
+    DHKEM_P256_HKDF_SHA256: 0x0010, DHKEM_P521_HKDF_SHA512: 0x0012, DHKEM_X25519_HKDF_SHA256: 0x0020, DHKEM_X448_HKDF_SHA512: 0x0021,
+    ML_KEM_512: 0x0040, ML_KEM_768: 0x0041, ML_KEM_1024: 0x0042,
+  }),
+  KDF: intrinsic.assign(intrinsic.create(null), { HKDF_SHA256: 0x0001, HKDF_SHA384: 0x0002, HKDF_SHA512: 0x0003 }),
   AEAD: intrinsic.assign(intrinsic.create(null), { AES_128_GCM: 0x0001, AES_256_GCM: 0x0002, CHACHA20_POLY1305: 0x0003, EXPORT_ONLY: 0xFFFF }),
   MODE: intrinsic.assign(intrinsic.create(null), { BASE: MODE_BASE, PSK: MODE_PSK, AUTH: MODE_AUTH, AUTH_PSK: MODE_AUTH_PSK }),
 });
@@ -369,9 +480,13 @@ var suites = intrinsic.assign(intrinsic.create(null), {
  * (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.
+ * KeyObject or the serialized public key bytes (the uncompressed point, the raw
+ * Montgomery coordinate, or the ML-KEM encapsulation key). `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; an option that
+ * belongs to another mode, such as `senderKey` in base mode, is refused with
+ * `hpke/bad-input` rather than left unused. The auth modes exist for the DHKEM
+ * suites only: an ML-KEM suite throws `hpke/auth-unsupported`.
  *
  * @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 };
@@ -380,17 +495,18 @@ var suites = intrinsic.assign(intrinsic.create(null), {
  *   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, _SETUP_S_KEYS, "sender setup");
+  opts = _options(opts || {}, _SETUP_S_KEYS, "sender setup");
+  var mode = opts.mode;
   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");
+    _requireAuthCapable(kem);
     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 {
+    _refuseUnusedAuthKey(opts.senderKey, "senderKey", mode);
     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");
@@ -405,12 +521,14 @@ function _setupS(ids, pkR, opts) {
  * @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 }` holding
- * 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`.
+ * and the recipient KEM private key, recovering the same shared secret and key
+ * schedule. The private key is a node KeyObject, or `{ skm, pkm }` where `skm` is
+ * the raw private scalar of a DHKEM suite or the 64-byte seed of an ML-KEM suite;
+ * `pkm` is optional, and when given it must be the public key derived from `skm`
+ * or the call throws `hpke/bad-key`. 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 (DHKEM
+ * suites only). 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 };
@@ -421,16 +539,18 @@ function _setupS(ids, pkR, opts) {
  *   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, _SETUP_R_KEYS, "recipient setup");
+  opts = _options(opts || {}, _SETUP_R_KEYS, "recipient setup");
+  var mode = opts.mode;
   var r = _recipPrivate(suite, skR);
   var kem = suite.kem, ss;
   if (mode === MODE_AUTH || mode === MODE_AUTH_PSK) {
+    _requireAuthCapable(kem);
     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 {
+    _refuseUnusedAuthKey(opts.senderPublicKey, "senderPublicKey", mode);
     ss = _decap(kem, _buf(enc), r.key, r.pkm);
   }
   try { return _keySchedule(suite, mode, ss, _buf(opts.info), _buf(opts.psk), _buf(opts.pskId), "R"); }
@@ -451,9 +571,9 @@ function _setupR(ids, enc, skR, opts) {
  * `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"));
+ *   // requires: mlKemPkR -- the recipient's ML-KEM-768 encapsulation key (1184 bytes)
+ *   var s = pki.hpke.suites, ids = { kem: s.KEM.ML_KEM_768, kdf: s.KDF.HKDF_SHA256, aead: s.AEAD.AES_256_GCM };
+ *   var out = pki.hpke.seal(ids, mlKemPkR, {}, Buffer.from("aad"), Buffer.from("msg"));
  */
 function seal(ids, pkR, opts, aad, pt) {
   var s = null;
@@ -481,11 +601,11 @@ function seal(ids, pkR, opts, aad, pt) {
  * 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);
+ *   // requires: mlKemPkR -- the recipient's ML-KEM-768 encapsulation key (1184 bytes)
+ *   // requires: mlKemSkR -- { skm } holding the recipient's 64-byte ML-KEM-768 seed
+ *   var s = pki.hpke.suites, ids = { kem: s.KEM.ML_KEM_768, kdf: s.KDF.HKDF_SHA256, aead: s.AEAD.AES_256_GCM };
+ *   var o = pki.hpke.seal(ids, mlKemPkR, {}, Buffer.alloc(0), Buffer.from("m"));
+ *   var pt = pki.hpke.open(ids, o.enc, mlKemSkR, {}, Buffer.alloc(0), o.ct);
  */
 function open(ids, enc, skR, opts, aad, ct) {
   var ctx = _setupR(ids, enc, skR, opts);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.7.30",
+  "version": "0.7.31",
   "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:cccf2ff7-2673-4c48-b9bc-d452383b439d",
+  "serialNumber": "urn:uuid:12c7bd5e-a715-426d-b609-24c3b76f11be",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-09-12T06:10:23.138Z",
+    "timestamp": "2026-09-12T07:21:39.704Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.7.30",
+      "bom-ref": "@blamejs/pki@0.7.31",
       "type": "application",
       "name": "pki",
-      "version": "0.7.30",
+      "version": "0.7.31",
       "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.7.30",
+      "purl": "pkg:npm/%40blamejs/pki@0.7.31",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.7.30",
+      "ref": "@blamejs/pki@0.7.31",
       "dependsOn": []
     }
   ]