@blamejs/pki 0.6.51 → 0.6.53

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" });
@@ -340,6 +376,164 @@ async function publicFromPrivate(privateKey, opts) {
   return opts.pem ? pkix.pemEncode(spki, "PUBLIC KEY", PemError) : spki;
 }
 
+/**
+ * @internal Whether a private key and a SubjectPublicKeyInfo are the two halves of one key pair, for a
+ * caller deciding whether a private key it was handed goes with a certificate it was handed.
+ *
+ * Deriving the public key and comparing does NOT answer this. A key structure states its own public
+ * half and the key engine reads what it is told: RFC 5958 sec. 2 gives a OneAsymmetricKey an optional
+ * `publicKey`, an EC key's RFC 5915 `ECPrivateKey` carries its own public point, and an RSA private
+ * key carries the modulus and public exponent outright. A structure whose private components were
+ * replaced while its stored public ones were left alone therefore derives to exactly the public key
+ * that was planted in it, and the comparison accepts a private key that cannot use the certificate.
+ *
+ * So the pair is proven by USING it, on whichever operation the key type can perform: a signature the
+ * public half verifies, a Diffie-Hellman agreement that reaches the same secret from both sides, or a
+ * key encapsulation the private half decapsulates to the same secret. Each fails for a key that merely
+ * claims the public half.
+ *
+ * What a true answer means is exactly that: the private key WORKS with this public key, on the
+ * operation its type performs. It is not a statement that every field of the private structure is
+ * internally consistent, which no operation reveals. A component the algorithm ignores, such as a bit
+ * an X25519 scalar clamps away or an ML-KEM implicit-rejection secret, is not exercised by a
+ * correspondence that succeeds, and does not stop the key from being usable with the certificate.
+ * A caller needing structural consistency has a different question, and this is not it.
+ */
+var _PAIR_DIGEST = Object.assign(Object.create(null), { rsa: "sha256", ec: "sha256" });
+var _PAIR_AGREE = Object.assign(Object.create(null), { x25519: 1, x448: 1 });
+var _PAIR_KEM = Object.assign(Object.create(null),
+  { "ml-kem-512": 1, "ml-kem-768": 1, "ml-kem-1024": 1 });
+/** @internal RFC 4055 sec. 1.2: ONE RSA key pair may be identified either by `rsaEncryption` or by
+ * `id-RSASSA-PSS`, and a delivered private key and the certificate that certifies it need not have
+ * chosen the same one. The key engine reports those two encodings as different types, so comparing
+ * types alone would call a usable pair no pair at all. They name one algorithm and are exercised
+ * together, under PSS, which is the padding the restricted encoding permits. */
+var _PAIR_RSA = Object.assign(Object.create(null), { rsa: 1, "rsa-pss": 1 });
+var _PAIR_PROBE = Buffer.from("pki.js key pair correspondence", "utf8");
+
+function _sameKeyFamily(priv, pub) {
+  if (priv.asymmetricKeyType === pub.asymmetricKeyType) return true;
+  return !!(_PAIR_RSA[guard.text.keyOf(priv.asymmetricKeyType)] &&
+    _PAIR_RSA[guard.text.keyOf(pub.asymmetricKeyType)]);
+}
+
+/** @internal How to exercise a signing pair: the digest, and any padding the encoding requires. An
+ * `id-RSASSA-PSS` key may pin the hash and salt length it is usable with, and the engine refuses any
+ * other, so a pinned value from either half is what proves the pair. */
+function _pairSignOptions(priv, pub) {
+  var privPss = priv.asymmetricKeyType === "rsa-pss", pubPss = pub.asymmetricKeyType === "rsa-pss";
+  if (!privPss && !pubPss) {
+    return { digest: _PAIR_DIGEST[guard.text.keyOf(priv.asymmetricKeyType)] || null, options: null };
+  }
+  var privDetails = _pssRestrictionOf(priv, privPss);
+  var pubDetails = _pssRestrictionOf(pub, pubPss);
+  /** @internal A half that pins nothing constrains nothing, so only two halves that BOTH pin can
+   * disagree. Both encodings pinning incompatible parameters describes no operation this pair can
+   * perform together, which is not the same as being different keys: it is reported as unexercisable
+   * rather than as a false "not a pair". Where one pins and the other does not, the pinned half
+   * supplies the parameters below and the engine enforces it against its own key. */
+  if (_pssConflict(privDetails, pubDetails)) return null;
+  var digest = privDetails.hashAlgorithm || pubDetails.hashAlgorithm || "sha256";
+  /** @internal The engine derives MGF1 from the digest and takes no separate option for it, so a half
+   * that pins a mask generator other than its own hash names an operation this pair cannot perform
+   * together. That is the same "cannot be decided" verdict two conflicting halves get, not a false
+   * report that the halves are different keys. */
+  var mgf1 = privDetails.mgf1HashAlgorithm || pubDetails.mgf1HashAlgorithm;
+  if (mgf1 != null && mgf1 !== digest) return null;
+  var salt = _pssSalt(privDetails.saltLength, pubDetails.saltLength);
+  /** @internal Null-prototype, because the engine READS this object by name. A plain object would
+   * let an inherited `saltLength` reach the signature as a restriction neither half stated. */
+  var options = Object.create(null);
+  options.padding = nodeCrypto.constants.RSA_PKCS1_PSS_PADDING;
+  if (salt != null) options.saltLength = salt;
+  return { digest: digest, options: options };
+}
+
+var _PSS_PINS = ["hashAlgorithm", "mgf1HashAlgorithm", "saltLength"];
+
+/** @internal What a half pins, as a null-prototype record carrying only what the key itself states.
+ * A half pins nothing when it is not an id-RSASSA-PSS key at all, and equally when it is one whose
+ * parameters are absent, which RFC 4055 sec. 3.1 leaves optional. Reading either through a plain
+ * object would let an inherited `saltLength` or `hashAlgorithm` answer as a restriction the key never
+ * carried, and refuse a genuine pair. */
+function _pssRestrictionOf(key, isPss) {
+  var out = Object.create(null);
+  var details = isPss ? key.asymmetricKeyDetails : null;
+  if (details == null) return out;
+  for (var i = 0; i < _PSS_PINS.length; i++) {
+    var name = _PSS_PINS[i];
+    if (Object.prototype.hasOwnProperty.call(details, name) && details[name] != null) out[name] = details[name];
+  }
+  return out;
+}
+
+/** @internal Whether two halves state a restriction that cannot be satisfied at once. RFC 4055
+ * sec. 3.3 requires the signature's hash and mask generator to match the key's, so two halves naming
+ * different ones describe no shared operation. It treats the salt length differently: "The saltLength
+ * field in the signature parameters MUST be greater or equal to that in the key parameters field",
+ * and sec. 3.1 says the field "does not need to be fixed for a given RSA key pair". Two halves naming
+ * different salt lengths are therefore both satisfied by the larger, and do not conflict. A field
+ * only one half states constrains only that half, so it cannot disagree with anything. */
+function _pssConflict(a, b) {
+  if (a.hashAlgorithm != null && b.hashAlgorithm != null && a.hashAlgorithm !== b.hashAlgorithm) return true;
+  if (a.mgf1HashAlgorithm != null && b.mgf1HashAlgorithm != null && a.mgf1HashAlgorithm !== b.mgf1HashAlgorithm) return true;
+  return false;
+}
+
+/** @internal The smallest salt length both halves accept, which is the larger of the two floors. */
+function _pssSalt(a, b) {
+  if (a == null) return b;
+  if (b == null) return a;
+  return a > b ? a : b;
+}
+
+async function correspondsTo(privateKey, spkiDer) {
+  var privDer = await _toPrivateKeyDer(privateKey);
+  var priv, pub;
+  try { priv = nodeCrypto.createPrivateKey({ key: privDer, format: "der", type: "pkcs8" }); }
+  catch (e) { throw _err("key/bad-input", "the private key could not be read", e); }
+  try { pub = nodeCrypto.createPublicKey({ key: Buffer.from(spkiDer), format: "der", type: "spki" }); }
+  catch (e) { throw _err("key/bad-input", "the public key could not be read", e); }
+  if (!_sameKeyFamily(priv, pub)) return false;
+  var kind = guard.text.keyOf(priv.asymmetricKeyType);
+  try {
+    if (_PAIR_KEM[kind]) {
+      var sealed = nodeCrypto.encapsulate(pub);
+      return guard.crypto.constantTimeEqual(nodeCrypto.decapsulate(priv, sealed.ciphertext), sealed.sharedKey);
+    }
+    if (_PAIR_AGREE[kind]) {
+      var ephemeral = nodeCrypto.generateKeyPairSync(priv.asymmetricKeyType);
+      if (!guard.crypto.constantTimeEqual(
+        nodeCrypto.diffieHellman({ privateKey: priv, publicKey: ephemeral.publicKey }),
+        nodeCrypto.diffieHellman({ privateKey: ephemeral.privateKey, publicKey: pub }))) return false;
+      /** @internal The agreement proves the SCALAR, not the encoding it was handed. RFC 7748 masks the
+       * top bit of an X25519 u-coordinate before the ladder, so a public value differing from the real
+       * one only in a masked bit reaches the same secret from both sides. The certificate would then
+       * carry bytes this key does not produce, and its subjectKeyIdentifier and any pinning of it
+       * would name a key the holder does not have. These types store no public copy in the private
+       * structure for an attacker to plant, so what the scalar generates IS the canonical answer and
+       * comparing against it adds a bound the agreement alone does not give. */
+      return guard.crypto.constantTimeEqual(
+        nodeCrypto.createPublicKey(priv).export({ format: "der", type: "spki" }),
+        pub.export({ format: "der", type: "spki" }));
+    }
+    var how = _pairSignOptions(priv, pub);
+    if (how === null) {
+      throw _err("key/unsupported-algorithm", "the two halves pin incompatible RSASSA-PSS parameters, so no operation exercises them together and whether they are a pair cannot be decided");
+    }
+    var signKey = how.options ? Object.assign(Object.create(null), { key: priv }, how.options) : priv;
+    var verifyKey = how.options ? Object.assign(Object.create(null), { key: pub }, how.options) : pub;
+    return nodeCrypto.verify(how.digest, _PAIR_PROBE, verifyKey,
+      nodeCrypto.sign(how.digest, _PAIR_PROBE, signKey)) === true;
+  } catch (e) {
+    /** @internal The incompatible-parameters verdict is decided rather than caught, so it is passed
+     * through with the reason it was raised for. Rewrapping it would tell an operator the pair could
+     * not be exercised without saying that the two encodings pin conflicting parameters. */
+    if (e && e.code === "key/unsupported-algorithm" && e.isPkiError === true) throw e;
+    throw _err("key/unsupported-algorithm", "the key pair could not be exercised to decide whether its two halves correspond", e);
+  }
+}
+
 
 function _detectKeyInput(input) {
   var der = pkix.coerceToDer(input, { pemLabel: null, PemError: PemError, ErrorClass: KeyError, prefix: "key" });
@@ -397,4 +591,5 @@ module.exports = {
   import: import_,
   generate: generate,
   publicFromPrivate: publicFromPrivate,
+  correspondsTo: correspondsTo,   // @internal
 };

package/lib/oid.js

@@ -174,6 +174,8 @@ var FAMILIES = Object.assign(Object.create(null), {
     countersignature: 6, challengePassword: 7, extensionRequest: 14,
     smimeCapabilities: 15, friendlyName: 20, localKeyId: 21 } },
 
+  keyPackageContentTypes: { base: [2, 16, 840, 1, 101, 2, 1, 2, 78], of: { aKeyPackage: 5 } },
+
   pkcs9CertTypes: { base: [1, 2, 840, 113549, 1, 9, 22], of: { x509Certificate: 1, sdsiCertificate: 2 } },
   pkcs9CrlTypes:  { base: [1, 2, 840, 113549, 1, 9, 23], of: { x509CRL: 1 } },
 

package/lib/path-validate.js

@@ -486,8 +486,16 @@ function ipMatch(constraint, addr) {
   return true;
 }
 
+/** @internal The one place a constraint base meets a name, so the base's form is read here and
+ * nowhere else. A caller's base met `guard.name.constraintBaseRefusal` at the door; a base a
+ * certificate carries in its own nameConstraints extension met no door, and the same rule decides it
+ * here. Answering a base outside its tag's form with no match rather than no verdict would make an
+ * excluded subtree that covers nothing exclude nothing. */
 function nameMatchesConstraint(gnTag, gnValue, base) {
   if (base.tagNumber !== gnTag) return null;
+  if (gnTag === 1 || gnTag === 2 || gnTag === 6) {
+    if (guard.name.constraintBaseUnreadable(gnTag, base.value)) return "unsupported";
+  }
   switch (gnTag) {
     case 1: return emailMatch(base.value, gnValue);
     case 2: return hostConstraintMatch(base.value, gnValue);

package/lib/schema-cmp.js

@@ -359,7 +359,7 @@ var ENCRYPTED_KEY = schema.choice([
       if (ct === null || ct.length === 0) {
         throw ctx.E("cmp/bad-cert-response", "an EncryptedKey envelopedData must carry non-empty attached ciphertext -- its encryptedContent is the certificate/key payload (RFC 9810 sec. 5.2.2)");
       }
-      return { envelopedData: env };
+      return { envelopedData: env, bytes: asn1.sequenceTlv(n) };
     }) },
 ], { code: "cmp/bad-cert-response", what: "EncryptedKey" });
 

package/lib/schema-pkix.js

@@ -539,6 +539,44 @@ function keyUsageOf(ns, cert, E, code, label) {
   return null;
 }
 
+/** @internal The extendedKeyUsage purposes a certificate asserts, or null when it carries no such
+ * extension. A malformed extension throws through the caller's ErrorClass; it never reads as an
+ * empty set. */
+var _EKU_DECODER = new _WeakMapI();
+function extKeyUsageOf(ns, cert, E, code, label) {
+  var exts = (cert && cert.extensions) || [];
+  var want = ns.oid.byName("extKeyUsage");
+  for (var i = 0; i < exts.length; i++) {
+    if (exts[i].oid !== want || exts[i].value == null) continue;
+    var dec = _weakGet(_EKU_DECODER, ns);
+    if (!dec) { dec = certExtensionDecoders(ns).byOid[want]; _weakSet(_EKU_DECODER, ns, dec); }
+    try { return dec(exts[i].value); }
+    catch (e) { throw E(code, "the " + label + " extendedKeyUsage extension is malformed", e); }
+  }
+  return null;
+}
+
+/**
+ * @internal Whether a certificate ASSERTS a key purpose, for a rule that requires the assertion to be
+ * present. RFC 5280 sec. 4.2.1.12 constrains a certificate only when the extension is there, so an
+ * absent extendedKeyUsage permits every purpose and satisfies `pki.path.validate`'s `requiredEku`. A
+ * profile that reads the purpose as an authorization statement (RFC 6960's id-kp-OCSPSigning
+ * responder, RFC 9483 sec. 4.1.6's id-kp-cmKGA key generation authority) needs the opposite reading:
+ * the certificate must say so. This returns false for an absent, empty, malformed, or
+ * differently-purposed extension, and true only when the named purpose is listed.
+ *
+ * @enforced-by behavioral -- an absent extension answering an authorization question has no
+ * rename-proof code shape; each consumer's RED conformance vector drives the shipped verb on a
+ * certificate with no extendedKeyUsage and asserts the refusal.
+ */
+function assertsPurpose(ns, cert, purposeOid) {
+  var purposes;
+  try { purposes = extKeyUsageOf(ns, cert, ns.E, ns.prefix + "/bad-extension-value", "certificate"); }
+  catch (_e) { return false; }
+  if (!purposes) return false;
+  return guard.list.contains(purposes, purposeOid);
+}
+
 function issuingDistributionPoint(code) {
   return schema.seq([
     schema.trailing([
@@ -676,7 +714,7 @@ function certExtensionDecoders(ns) {
     for (var z = 0; z < bs.bytes.length; z++) { if (bs.bytes[z] !== 0) { anyBit = true; break; } }
     if (!anyBit) throw ns.E(C, "KeyUsage must assert at least one bit (RFC 5280 sec. 4.2.1.3)");
     schema.assertMinimalNamedBits(bs.unusedBits, bs.bytes, function (m) { throw ns.E(C, m); });
-    // allow:registry-table-inherits-object-prototype -- the decoded KeyUsage record, whose keys are the fixed KU_BITS names the schema declares rather than anything the certificate supplies
+    // allow:registry-table-inherits-object-prototype -- the decoded KeyUsage record, whose keys are the fixed KU_BITS names the schema declares; the certificate supplies none of them
     var out = {};
     _forEach(KU_BITS, function (nm, bit) {
       var byte = bit >> 3, mask = 0x80 >> (bit & 7);
@@ -822,7 +860,7 @@ function certExtensionDecoders(ns) {
   function authorityKeyIdentifier(buf) {
     var C = ns.prefix + "/bad-extension-value";
     var kids = seqChildren(buf, C, "AuthorityKeyIdentifier");
-    // allow:registry-table-inherits-object-prototype -- the decoded AuthorityKeyIdentifier record, read by the three field names the schema declares rather than by anything the certificate supplies
+    // allow:registry-table-inherits-object-prototype -- the decoded AuthorityKeyIdentifier record, read by the three field names the schema declares; the certificate supplies none of them
     var out = { keyIdentifier: null, authorityCertIssuer: null, authorityCertSerialNumber: null };
     var lastTag = -1;
     _forEach(kids, function (k) {
@@ -869,7 +907,7 @@ function certExtensionDecoders(ns) {
       if (dp.tagClass !== "universal" || dp.tagNumber !== _T.SEQUENCE || !dp.children) {
         throw ns.E(C, "DistributionPoint must be a SEQUENCE { distributionPoint?, reasons?, cRLIssuer? }");
       }
-      // allow:registry-table-inherits-object-prototype -- the decoded DistributionPoint record, read by the three field names the schema declares rather than by anything the certificate supplies
+      // allow:registry-table-inherits-object-prototype -- the decoded DistributionPoint record, read by the three field names the schema declares; the certificate supplies none of them
       var out = { distributionPoint: null, reasons: null, cRLIssuer: null };
       var lastTag = -1;
       _forEach(dp.children, function (f) {
@@ -1247,6 +1285,8 @@ module.exports = {
   distributionPointName: distributionPointName,
   issuingDistributionPoint: issuingDistributionPoint,
   keyUsageOf: keyUsageOf,
+  extKeyUsageOf: extKeyUsageOf,
+  assertsPurpose: assertsPurpose,
   generalizedTime: generalizedTime,
   utf8Text: utf8Text,
   rawNonEmptySequence: rawNonEmptySequence,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.6.51",
+  "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:d9015ac6-f8a1-409f-9e1f-5ae1fc7491a1",
+  "serialNumber": "urn:uuid:258eb315-4dba-4e0f-8600-313c47a1a144",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-09-07T06:27:34.397Z",
+    "timestamp": "2026-09-07T16:58:48.291Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.6.51",
+      "bom-ref": "@blamejs/pki@0.6.53",
       "type": "application",
       "name": "pki",
-      "version": "0.6.51",
+      "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.51",
+      "purl": "pkg:npm/%40blamejs/pki@0.6.53",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.6.51",
+      "ref": "@blamejs/pki@0.6.53",
       "dependsOn": []
     }
   ]