@blamejs/pki 0.6.52 → 0.6.53

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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.6.53 — 2026-09-07
+
+A composite ML-KEM private key states its public half, so a holder can name the recipient it is.
+
+### Added
+
+- pki.key.publicFromPrivate derives the public key of a composite ML-KEM private key (draft-ietf-lamps-pq-composite-kem section 4.1). A composite private key is the ML-KEM seed followed by the traditional private key, and the public key is the ML-KEM encapsulation key followed by the traditional public key under the same OID. Each half states its own: the seed generates the encapsulation key, and the traditional half is read in the encoding its algorithm uses, an RSAPrivateKey, a SEC1 ECPrivateKey, or the raw scalar of an OKP curve. All twelve registered families are covered, and each derives byte-for-byte the public key the draft's own Appendix G test vectors publish for that key. opts.pem returns it armored, as it does for every other family.
+- The derived key is the one the rest of the toolkit takes. It is the recipient pki.cms.encrypt accepts for a composite KEM recipient, and pki.kem.encapsulate establishes a shared secret for it that the private key it came from decapsulates to the same value.
+
+### Changed
+
+- A composite ML-KEM private key reports why it cannot be read, rather than reporting that a public key could not be derived from it. An AlgorithmIdentifier carrying parameters is kem/bad-algorithm, since the draft requires them absent (section 5.3); a key no longer than the ML-KEM seed is kem/bad-key; and an OID no registered family claims is refused rather than guessed at. The private key material and the copy taken of it are wiped before the call returns, on the refusing paths as well as the deriving one.
+- Each component is held to what the composite OID names it must be. The RSA component's modulus must be the size that family states, and the EC component must be on the curve it states: a SEC1 ECPrivateKey carries its own curve, and exporting the point of one curve under an OID naming another would state a public key nothing can use. Decapsulation reaches the same conclusion by failing the agreement, and a derivation performs no operation that would notice, so it is checked.
+- Every copy of private key material the derivation allocates is cleared before it returns, on the refusing paths as well as the deriving one: the caller's snapshot, the key octets, and the ML-KEM seed re-encoded for the key engine to read. The EC component adds two more, the scalar taken out of the ECPrivateKey and the copy a width check rejects, and a decapsulation refused after its Diffie-Hellman has already run clears that agreement's secret before reporting the refusal.
+- The EC component's point is generated from its scalar rather than read from the key, in the derivation and in pki.kem.decapsulate alike. RFC 5915 section 3 gives an ECPrivateKey an optional public point, which may be written compressed, and the composite public key carries the uncompressed point at a fixed width. The combiner hashes that public key, so the two sides read one function for it: a key storing a compressed point now establishes the same shared secret whichever spelling of it a sender encapsulated to. Generating the point also means the answer is the one the scalar produces, so a point stored beside a scalar that does not produce it does not reach the result.
+
+### Fixed
+
+- The X25519 and X448 component of a composite ML-KEM key is imported through an encoding that is now cleared once the import has read it. That encoding holds the component's private scalar and is allocated inside the helper both pki.kem.decapsulate and the new derivation reach the curve through, so a decapsulation left a copy of it behind.
+
 ## v0.6.52 — 2026-09-07
 
 A CMP client can accept a key pair the CA generated for it, and refuses one from an authority that never claimed to be one.

package/lib/composite-kem.js

@@ -102,9 +102,16 @@ function _okpPubFromRaw(d, raw) {
   var spki = _b.sequence([_b.sequence([_b.oid(oid.byName(d.trad.curve))]), _b.bitString(raw, 0)]);
   return nodeCrypto.createPublicKey({ key: spki, format: "der", type: "spki" });
 }
+/** @internal The encoding is this helper's own allocation and holds the traditional private scalar, so
+ * it is cleared here. A caller's own cleanup cannot reach a buffer it never sees, and both the
+ * derivation and the decapsulation reach the curve through this one function. */
 function _okpPrivFromRaw(d, raw) {
   var p8 = _b.sequence([_b.integer(0n), _b.sequence([_b.oid(oid.byName(d.trad.curve))]), _b.octetString(_b.octetString(raw))]);
-  return nodeCrypto.createPrivateKey({ key: p8, format: "der", type: "pkcs8" });
+  try {
+    return nodeCrypto.createPrivateKey({ key: p8, format: "der", type: "pkcs8" });
+  } finally {
+    guard.secret.zeroize(p8, KemError, "kem/bad-input", "the " + d.trad.curve + " component key encoding");
+  }
 }
 function _rawPubOf(keyObject) {
   var spki = keyObject.export({ format: "der", type: "spki" });
@@ -170,7 +177,20 @@ function _tradDecaps(d, tradSK, tradCT) {
   var dh;
   try { dh = Buffer.from(nodeCrypto.diffieHellman({ privateKey: priv2, publicKey: eph })); }
   catch (e) { return Promise.reject(_err("kem/decapsulation-failed", "the " + trad.curve + " Diffie-Hellman failed", e)); }
-  return Promise.resolve({ ss: dh, tradPK: _rawPubOf(nodeCrypto.createPublicKey(priv2)) });
+  /** @internal The same canonical point the derivation states, read from the one function that spells
+   * it. The combiner hashes these bytes, so a stored spelling here and a generated one there would
+   * reach different secrets from the two sides of one key. */
+  var tradPK;
+  try {
+    tradPK = trad.kind === "ec" ? _ecPointOf(d, tradSK) : _rawPubOf(nodeCrypto.createPublicKey(priv2));
+  } catch (e) {
+    /** @internal The agreement already produced a secret, and this rejection happens after it, so the
+     * secret is wiped here: the caller's settle-or-wipe covers a value it was handed, and a rejected
+     * promise hands it nothing. */
+    guard.secret.zeroize(dh, KemError, "kem/bad-input", "the " + trad.curve + " component secret");
+    return Promise.reject(e);
+  }
+  return Promise.resolve({ ss: dh, tradPK: tradPK });
 }
 
 function _combine(d, mlkemSS, tradSS, tradCT, tradPK) {
@@ -309,8 +329,152 @@ async function _encapsulate(publicKey) {
 
 function _isCompositeKem(algOid) { return COMPOSITE_KEM[algOid] != null; }
 
+/** @internal The EC component's public point, generated from its scalar. RFC 5915 sec. 3 gives an
+ * ECPrivateKey an optional public point which may be written compressed, and the key engine keeps
+ * whatever encoding it was handed. The composite concatenation carries the uncompressed point at a
+ * fixed width (draft sec. 4.1), and the combiner hashes those bytes, so BOTH the derivation and the
+ * decapsulation read this one function: a point spelled two ways would agree on the secret nowhere. */
+function _ecPointOf(d, tradSK) {
+  /** @internal The scalar is a fresh copy of private key material, so it is wiped here rather than
+   * left for the caller's own copies to cover: those wipe the PKCS#8 and the key octets, and this
+   * buffer is neither. */
+  var scalar = _ecScalarOf(d, tradSK);
+  var point;
+  try {
+    var ecdh = nodeCrypto.createECDH(d.trad.node);
+    ecdh.setPrivateKey(scalar);
+    point = ecdh.getPublicKey(null, "uncompressed");
+  } catch (e) {
+    if (e instanceof KemError) throw e;
+    throw _err("kem/bad-key", "the EC component scalar does not generate a point on " + d.trad.node, e);
+  } finally {
+    guard.secret.zeroize(scalar, KemError, "kem/bad-input", "the EC component scalar");
+  }
+  if (point.length !== d.trad.ctLen) throw _err("kem/bad-key", "the EC component point is not the expected " + d.trad.ctLen + " bytes for " + d.name);
+  return point;
+}
+
+/** @internal The private scalar of a SEC1 ECPrivateKey (RFC 5915 sec. 3), left-padded to the field
+ * width the curve uses. The structure states the scalar as an OCTET STRING in its second field, and
+ * the point generation below is positional, so a short one is padded rather than shifted. */
+function _ecScalarOf(d, tradSK) {
+  var width = (d.trad.ctLen - 1) / 2;
+  var raw;
+  try {
+    var node = asn1.decode(tradSK);
+    raw = Buffer.from(asn1.read.octetString(node.children[1]));
+  } catch (e) { throw _err("kem/bad-key", "the EC component private key is not a well-formed ECPrivateKey", e); }
+  /** @internal `raw` holds private key material. It is handed on only when it IS the returned buffer,
+   * which the caller then wipes; on every other exit, the padded one and the refusal alike, this is
+   * the last reference and the copy is cleared here. */
+  var handedOn = false;
+  try {
+    if (raw.length === 0 || raw.length > width) throw _err("kem/bad-key", "the EC component scalar is not a " + d.trad.node + " field element");
+    if (raw.length === width) { handedOn = true; return raw; }
+    var out = Buffer.alloc(width);
+    raw.copy(out, width - raw.length);
+    return out;
+  } finally {
+    if (!handedOn) guard.secret.zeroize(raw, KemError, "kem/bad-input", "the EC component scalar copy");
+  }
+}
+
+/** @internal The traditional component's public half, derived from its private half by the same route
+ * `_tradDecaps` takes to report `tradPK`. Each kind states its private key in its own encoding: an
+ * RSAPrivateKey, a SEC1 ECPrivateKey, or the raw scalar an OKP curve carries. */
+function _tradPubOf(d, tradSK) {
+  var trad = d.trad;
+  if (trad.kind === "rsa") {
+    var rp;
+    try {
+      asn1.decode(tradSK);
+      rp = nodeCrypto.createPrivateKey({ key: tradSK, format: "der", type: "pkcs1" });
+    } catch (e) { throw _err("kem/bad-key", "the RSA component private key is not a valid RSAPrivateKey", e); }
+    if (rp.asymmetricKeyDetails.modulusLength !== trad.bits) {
+      throw _err("kem/bad-key", "the RSA component modulus is not " + trad.bits + " bits (draft sec. 6)");
+    }
+    return Buffer.from(nodeCrypto.createPublicKey(rp).export({ format: "der", type: "pkcs1" }));
+  }
+  var priv;
+  try {
+    if (trad.kind === "ec") {
+      asn1.decode(tradSK);
+      priv = nodeCrypto.createPrivateKey({ key: tradSK, format: "der", type: "sec1" });
+    } else {
+      priv = _okpPrivFromRaw(d, tradSK);
+    }
+  } catch (e) { throw _err("kem/bad-key", "the " + trad.curve + " key material is invalid", e); }
+  /** @internal A SEC1 ECPrivateKey names its own curve, and the composite OID names the curve the
+   * component must be on. Exporting the point of one curve under an OID that names another states a
+   * public key nothing can use, so the two are held to each other here. Decapsulation reaches the same
+   * conclusion by failing the agreement; a derivation performs no operation that would notice. */
+  if (trad.kind === "ec") {
+    var named = priv.asymmetricKeyDetails && priv.asymmetricKeyDetails.namedCurve;
+    if (named !== trad.node) {
+      throw _err("kem/bad-key", "the EC component is on " + guard.text.showValue(named) + ", and " + d.name + " names " + trad.node);
+    }
+    /** @internal Recomputed from the scalar rather than exported. RFC 5915 gives an ECPrivateKey an
+     * optional public point, the key engine keeps whatever encoding it was handed, and a compressed
+     * point is neither the width nor the form the composite concatenation carries (draft sec. 4.1).
+     * Generating the point from the scalar answers with the key this component actually holds, so a
+     * point stored beside it cannot stand in for one it does not generate. */
+    return _ecPointOf(d, tradSK);
+  }
+  return _rawPubOf(nodeCrypto.createPublicKey(priv));
+}
+
+/** @internal The composite `SubjectPublicKeyInfo` for a composite ML-KEM private key. The runtime key
+ * decoder does not know a composite OID, so a caller deriving one cannot go through it; the key is
+ * split the way `_decapsulate` splits it (draft sec. 4.1: `seed || tradSK`) and each half states its
+ * own public key, concatenated under the same OID as `mlkemEK || tradPK` (sec. 5.1). The ML-KEM half
+ * is recovered by importing the seed and reading the public key it generates, so a stored public copy
+ * could not answer in its place. The private material is wiped on every path. */
+async function _publicFromPrivate(privateKey) {
+  var pkcs8 = _toDer(privateKey, "PRIVATE KEY", "the composite ML-KEM private key");
+  /** @internal Every buffer this derivation allocates that holds private key material is registered
+   * here and cleared once, on every exit. A copy added later is covered by registering it rather than
+   * by a further nested block, which is how the ML-KEM seed encoding came to outlive two of them. */
+  var secrets = [];
+  guard.list.append(secrets, pkcs8);
+  var d;
+  try {
+    var sk;
+    try {
+      var info = schemaPkcs8.parse(pkcs8);
+      var alg = info.privateKeyAlgorithm;
+      d = _descriptorForAlg(alg.oid, alg.parameters !== null);
+      sk = Buffer.from(info.privateKey);
+      guard.list.append(secrets, sk);
+    } catch (e) {
+      if (e instanceof KemError) throw e;
+      if (e && e.code === "pkcs8/bad-algorithm-parameters") throw _err("kem/bad-algorithm", "a composite ML-KEM AlgorithmIdentifier MUST have absent parameters (draft sec. 5.3)", e);
+      throw _err("kem/bad-key", "the composite ML-KEM private key is not a well-formed OneAsymmetricKey", e);
+    }
+    if (sk.length <= MLKEM_SEED) throw _err("kem/bad-key", "the composite private key is shorter than the ML-KEM seed");
+    var seed = sk.subarray(0, MLKEM_SEED), tradSK = sk.subarray(MLKEM_SEED);
+    var ek;
+    try {
+      /** @internal The seed re-encoded as a OneAsymmetricKey the key engine reads, which is a second
+       * copy of the seed and is registered as one. */
+      var seedPkcs8 = _mlkemSeedPkcs8(d, seed);
+      guard.list.append(secrets, seedPkcs8);
+      var mlPriv = nodeCrypto.createPrivateKey({ key: seedPkcs8, format: "der", type: "pkcs8" });
+      ek = _rawPubOf(nodeCrypto.createPublicKey(mlPriv));
+    } catch (e) {
+      if (e instanceof KemError) throw e;
+      throw _err("kem/bad-key", "the ML-KEM component private key is invalid", e);
+    }
+    if (ek.length !== d.mlkemEk) throw _err("kem/bad-key", "the ML-KEM component public key is not the expected " + d.mlkemEk + " bytes for " + d.name);
+    var composite = Buffer.concat([ek, _tradPubOf(d, tradSK)]);
+    return _b.sequence([_b.sequence([_b.oid(oid.byName(d.name))]), _b.bitString(composite, 0)]);
+  } finally {
+    guard.secret.zeroizeAll(secrets, KemError, "kem/bad-input", "the composite private key material");
+  }
+}
+
 module.exports = {
   encapsulate: _encapsulate,
   decapsulate: _decapsulate,
   isCompositeKem: _isCompositeKem,
+  publicFromPrivate: _publicFromPrivate,
 };

package/lib/key.js

@@ -26,6 +26,7 @@ var pbes2 = require("./pbes2");
 var pkcs8 = require("./schema-pkcs8");
 var pkix = require("./schema-pkix");
 var webcrypto = require("./webcrypto");
+var compositeKem = require("./composite-kem");
 var frameworkError = require("./framework-error");
 var guard = require("./guard-all");
 
@@ -311,7 +312,7 @@ async function generate(algorithm, opts) {
  * @signature pki.key.publicFromPrivate(privateKey, opts?) -> Promise<Buffer|string>
  * @since 0.3.10
  * @status stable
- * @spec RFC 5280 sec. 4.1.2.7, RFC 8410 sec. 3
+ * @spec RFC 5280 sec. 4.1.2.7, RFC 8410 sec. 3, draft-ietf-lamps-pq-composite-kem sec. 4.1
  * @related pki.key.export, pki.key.import
  *
  * Derive the SubjectPublicKeyInfo (SPKI) public key from a PKCS#8 private key (DER `Buffer`, `PRIVATE KEY`
@@ -319,6 +320,13 @@ async function generate(algorithm, opts) {
  * the algorithm from the key structure, so no `AlgorithmIdentifier` is re-encoded: Ed25519 stays
  * parameters-absent, RSA keeps its NULL, EC keeps its namedCurve.
  *
+ * A composite ML-KEM key is derived from its two components instead, since the node key engine does not
+ * read a composite algorithm. The private key is `seed || tradSK` and the public key is
+ * `mlkemEK || tradPK` under the same OID: the seed states the ML-KEM encapsulation key it generates, the
+ * traditional half states its own public key, and the two are concatenated. An AlgorithmIdentifier
+ * carrying parameters, a key no longer than the ML-KEM seed, and an unregistered composite OID are each
+ * refused with a typed `KemError`.
+ *
  * @opts
  *   - `pem` (boolean) -- return a `PUBLIC KEY` PEM string instead of DER.
  * @example
@@ -327,12 +335,40 @@ async function generate(algorithm, opts) {
  */
 var _PUBLIC_FROM_PRIVATE_OPTS = Object.assign(Object.create(null), { pem: 1 });
 
+/** @internal The composite ML-KEM OID a private key names, or null when it names anything else. Read
+ * from the AlgorithmIdentifier alone: a key that is not well formed enough to state one is left to the
+ * decoder below, which reports it. */
+function _compositeKemOidOf(der) {
+  var algOid;
+  try {
+    /** @internal The AlgorithmIdentifier OID only, read without the strict OneAsymmetricKey rules. A
+     * composite key that breaks one of those rules is still a composite key, and the module that owns
+     * the algorithm is the one that should say so: parsing strictly here would send a composite key
+     * carrying parameters to the runtime decoder, which reports that it cannot read the key rather
+     * than that the parameters are not allowed (draft sec. 5.3). */
+    var node = asn1.decode(der);
+    if (!node.children || node.children.length < 3) return null;
+    var alg = node.children[1];
+    if (!alg.children || alg.children.length < 1) return null;
+    algOid = asn1.read.oid(alg.children[0]);
+  } catch (_e) { return null; }
+  return typeof algOid === "string" && compositeKem.isCompositeKem(algOid) ? algOid : null;
+}
+
 async function publicFromPrivate(privateKey, opts) {
   opts = guard.identifier.optionsObject(opts, _err, "key/bad-input", "pki.key.publicFromPrivate options");
   guard.identifier.assertKnownKeys(opts, _PUBLIC_FROM_PRIVATE_OPTS, _err, "key/bad-input",
     "pki.key.publicFromPrivate has an unknown option: ");
   var der = await _toPrivateKeyDer(privateKey);
   var spki;
+  /** @internal A composite ML-KEM key is a toolkit-defined algorithm the runtime decoder cannot read,
+   * so it is routed before the decoder rather than after it fails. Its own module owns the split and
+   * the wipe, and reports its own typed reasons. */
+  var compositeOid = _compositeKemOidOf(der);
+  if (compositeOid !== null) {
+    spki = await compositeKem.publicFromPrivate(der);
+    return opts.pem ? pkix.pemEncode(spki, "PUBLIC KEY", PemError) : spki;
+  }
   try {
     var priv = nodeCrypto.createPrivateKey({ key: der, format: "der", type: "pkcs8" });
     spki = nodeCrypto.createPublicKey(priv).export({ format: "der", type: "spki" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.6.52",
+  "version": "0.6.53",
   "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:5de9cc32-97b6-4f34-a868-7ad628091d11",
+  "serialNumber": "urn:uuid:258eb315-4dba-4e0f-8600-313c47a1a144",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-09-07T15:01:14.383Z",
+    "timestamp": "2026-09-07T16:58:48.291Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.6.52",
+      "bom-ref": "@blamejs/pki@0.6.53",
       "type": "application",
       "name": "pki",
-      "version": "0.6.52",
+      "version": "0.6.53",
       "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.6.52",
+      "purl": "pkg:npm/%40blamejs/pki@0.6.53",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.6.52",
+      "ref": "@blamejs/pki@0.6.53",
       "dependsOn": []
     }
   ]