@blamejs/pki 0.2.20 → 0.2.22

package/lib/webcrypto.js

@@ -22,10 +22,11 @@
  *   still runs on -- RSASSA-PKCS1-v1_5, RSA-PSS, RSA-OAEP, ECDSA, ECDH,
  *   Ed25519 / Ed448, AES-GCM / CBC / KW, HMAC, HKDF, PBKDF2, and the SHA
  *   family (including legacy SHA-1 for old certificates and signatures).
- *   FIPS 203 ML-KEM key generation and encoding are available; KEM
- *   encapsulation follows once Node exposes it. Because it is
- *   OpenSSL-backed, every key and signature it emits is interoperable
- *   with OpenSSL, NSS, and other PKI implementations.
+ *   FIPS 203 ML-KEM key generation, encoding, and certificate/PKCS#8
+ *   import are available; KEM encapsulation/decapsulation is deferred to
+ *   the CMS KEM-decrypt surface by decision (the Node primitive exists).
+ *   Because it is OpenSSL-backed, every key and signature it emits is
+ *   interoperable with OpenSSL, NSS, and other PKI implementations.
  *
  * @card
  *   A zero-dep, PQC-first W3C WebCrypto (`SubtleCrypto`) engine over
@@ -37,6 +38,8 @@ var nodeCrypto = require("node:crypto");
 var frameworkError = require("./framework-error");
 var guard = require("./guard-all");
 var constants = require("./constants");
+var asn1 = require("./asn1-der");
+var oid = require("./oid");
 
 // Single-owner error class -- co-located with its module (framework-error
 // stays the cross-module home; this is webcrypto-private). withCause: a
@@ -127,8 +130,9 @@ var ML_KEM_NODE = { "ML-KEM-512": "ml-kem-512", "ML-KEM-768": "ml-kem-768", "ML-
 
 // FIPS 205 SLH-DSA -- stateless hash-based signatures. All twelve
 // parameter sets Node exposes; signing is one-shot (null algorithm), the
-// same shape as ML-DSA / EdDSA. KEM encapsulation for ML-KEM is not yet
-// in Node's API, so ML-KEM here is key-generation / encoding only.
+// same shape as ML-DSA / EdDSA. ML-KEM here is key-generation / encoding /
+// import; encapsulation/decapsulation (which Node now exposes) is deferred
+// to the CMS KEM-decrypt surface, not blocked by the engine.
 var SLH_DSA_NODE = {};
 ["sha2-128s", "sha2-128f", "sha2-192s", "sha2-192f", "sha2-256s", "sha2-256f",
  "shake-128s", "shake-128f", "shake-192s", "shake-192f", "shake-256s", "shake-256f"
@@ -144,6 +148,12 @@ var SIGN_VERIFY_NAMES = {};
   .forEach(function (n) { SIGN_VERIFY_NAMES[n] = true; });
 var ENCRYPT_DECRYPT_NAMES = { "RSA-OAEP": true, "AES-GCM": true, "AES-CBC": true, "AES-CTR": true };
 var DERIVE_NAMES = { "ECDH": true, "X25519": true, "X448": true, "HKDF": true, "PBKDF2": true };
+// The secret-key / KDF algorithms whose key material is raw octets (imported via "raw" or a
+// JWK "oct"), NEVER an SPKI / PKCS#8 asymmetric-key structure. importKey("spki"|"pkcs8", ...)
+// under one of these names is unsupported (W3C: NotSupportedError) -- and, without this gate, it
+// would mint a mislabeled CryptoKey wrapping an asymmetric handle AND dodge the algorithm-keyed
+// pkcs8 pre-validation (e.g. the RFC 9935 ML-KEM CHOICE guard).
+var SECRET_KEY_NAMES = { "AES-GCM": true, "AES-CBC": true, "AES-CTR": true, "AES-KW": true, "HMAC": true, "HKDF": true, "PBKDF2": true };
 
 // ---- CryptoKey -------------------------------------------------------
 
@@ -654,14 +664,97 @@ function _assertAesImportLen(name, byteLen) {
   }
 }
 
+// Run a node:crypto key-import call, mapping a raw engine error (a malformed DER, an
+// inconsistent key) to a typed webcrypto/data DataError -- importKey over hostile bytes
+// must never leak a bare OpenSSL/Node exception through the public API.
+function _nodeKey(fn, who) {
+  try { return fn(); }
+  catch (e) {
+    // Coverage residual -- every current thunk calls node:crypto (which throws a node error),
+    // never a WebCryptoError, so this already-typed passthrough is defensive depth for a future
+    // thunk that pre-validates and throws typed; it prevents double-wrapping a typed error.
+    if (e instanceof WebCryptoError) throw e;
+    throw new WebCryptoError("webcrypto/data", who + ": the key material is malformed or internally inconsistent", e);
+  }
+}
+
+// RFC 9935 sec. 6 ML-KEM-*-PrivateKey CHOICE: the inner sizes, keyed by the OID -- the OID is
+// the SOLE authority for the parameter set (never a length heuristic). ek = 384k+32, dk = the
+// FIPS 203 decapsulation key length.
+var ML_KEM_INNER = {};
+ML_KEM_INNER[oid.byName("id-ml-kem-512")] = { ek: 800, dk: 1632 };
+ML_KEM_INNER[oid.byName("id-ml-kem-768")] = { ek: 1184, dk: 2400 };
+ML_KEM_INNER[oid.byName("id-ml-kem-1024")] = { ek: 1568, dk: 3168 };
+
+function _isOctet(node, size) {
+  return node && node.tagClass === "universal" && node.tagNumber === asn1.TAGS.OCTET_STRING &&
+    !node.constructed && node.content && node.content.length === size;
+}
+// Validate the RFC 9935 sec. 6 inner CHOICE structurally, dispatching on the DER tag (0x80 seed
+// [0] / 0x04 expandedKey / 0x30 both) -- NEVER on the length of the enclosing OCTET STRING. A
+// bare seed, a bare dk, an oqskeypair dk||ek, a constructed [0], or a wrong-size arm is rejected
+// fail-closed (guards never guess a plausible layout). The seed/expandedKey CRYPTOGRAPHIC
+// consistency (sec. 8 / FIPS 203 sec. 7.3) is enforced by the engine on import (a mismatch is a
+// raw node error _nodeKey maps to webcrypto/data).
+function _validateMlKemInner(innerBytes, sizes) {
+  var node;
+  try { node = asn1.decode(innerBytes); }
+  catch (e) { throw new WebCryptoError("webcrypto/data", "an ML-KEM private key must be the RFC 9935 sec. 6 seed/expandedKey/both CHOICE, not a bare key", e); }
+  if (node.tagClass === "context" && node.tagNumber === 0 && !node.constructed) {
+    if (!node.content || node.content.length !== 64) throw new WebCryptoError("webcrypto/data", "an ML-KEM seed must be exactly 64 octets (RFC 9935 sec. 6)");
+    return;
+  }
+  if (_isOctet(node, sizes.dk)) return;
+  if (node.tagClass === "universal" && node.tagNumber === asn1.TAGS.OCTET_STRING && !node.constructed) {
+    throw new WebCryptoError("webcrypto/data", "an ML-KEM expandedKey must be exactly " + sizes.dk + " octets for this parameter set (RFC 9935 sec. 6)");
+  }
+  if (node.tagClass === "universal" && node.tagNumber === asn1.TAGS.SEQUENCE) {
+    // Coverage residual -- a decoded universal SEQUENCE always carries a children array, so the
+    // `|| []` fallback is defensive (asn1.decode never yields a childless constructed node).
+    var kids = node.children || [];
+    if (kids.length !== 2 || !_isOctet(kids[0], 64) || !_isOctet(kids[1], sizes.dk)) {
+      throw new WebCryptoError("webcrypto/data", "an ML-KEM both-arm must be SEQUENCE { seed OCTET STRING(64), expandedKey OCTET STRING(" + sizes.dk + ") } (RFC 9935 sec. 6)");
+    }
+    return;
+  }
+  throw new WebCryptoError("webcrypto/data", "an ML-KEM private key must be the seed, expandedKey, or both CHOICE (RFC 9935 sec. 6)");
+}
+
+// PKCS#8 inner-key pre-validation, keyed by the privateKeyAlgorithm OID (a registry row, not a
+// switch). The parse surfaces the inner key as opaque octets by design; the fail-closed
+// per-algorithm structural check lives here, at the one import boundary. Only ML-KEM needs it
+// today: the engine ACCEPTS the OpenSSL-legacy bare-seed layout RFC 9935 sec. 6 forbids.
+var PKCS8_INNER_VALIDATORS = {};
+Object.keys(ML_KEM_INNER).forEach(function (o) { PKCS8_INNER_VALIDATORS[o] = function (inner) { _validateMlKemInner(inner, ML_KEM_INNER[o]); }; });
+
+function _preValidatePkcs8(p8, name) {
+  if (!ML_KEM_NODE[name]) return;   // only the ML-KEM CHOICE carries the bare-seed hazard
+  var algOid, innerBytes;
+  try {
+    var root = asn1.decode(p8);
+    algOid = asn1.read.oid(root.children[1].children[0]);
+    innerBytes = asn1.read.octetString(root.children[2]);
+  } catch (e) { throw new WebCryptoError("webcrypto/data", "importKey pkcs8: the ML-KEM PKCS#8 envelope is not well-formed", e); }
+  var validate = PKCS8_INNER_VALIDATORS[algOid];
+  if (!validate) throw new WebCryptoError("webcrypto/data", "importKey pkcs8: " + name + " does not match the key's algorithm OID");
+  validate(innerBytes);
+}
+
 SubtleCrypto.prototype.importKey = async function importKey(format, keyData, algorithm, extractable, keyUsages) {
   var alg = _normalizeAlg(algorithm, "importKey");
   var usages = keyUsages || [];
   var name = alg.name;
 
+  // spki / pkcs8 carry an asymmetric key; a secret-key / KDF name has no such structure. Reject
+  // it up front (W3C NotSupportedError) so it can neither mint a mislabeled key nor bypass the
+  // per-algorithm pkcs8 pre-validation below.
+  if ((format === "spki" || format === "pkcs8") && SECRET_KEY_NAMES[name]) {
+    throw new WebCryptoError("webcrypto/not-supported", "importKey: " + name + " does not support the " + format + " key format");
+  }
+
   if (format === "raw") {
     // Symmetric raw material, or a raw public key for EC/OKP.
-    if (name === "AES-GCM" || name === "AES-CBC" || name === "AES-CTR" || name === "AES-KW" || name === "HMAC" || name === "HKDF" || name === "PBKDF2") {
+    if (SECRET_KEY_NAMES[name]) {
       var raw = _toBuf(keyData, "importKey raw");
       _assertAesImportLen(name, raw.length);
       var secret = nodeCrypto.createSecretKey(raw);
@@ -673,15 +766,24 @@ SubtleCrypto.prototype.importKey = async function importKey(format, keyData, alg
   }
 
   if (format === "spki") {
-    var pub = nodeCrypto.createPublicKey({ key: _toBuf(keyData, "importKey spki"), format: "der", type: "spki" });
+    var spkiBuf = _toBuf(keyData, "importKey spki");
+    var pub = _nodeKey(function () { return nodeCrypto.createPublicKey({ key: spkiBuf, format: "der", type: "spki" }); }, "importKey spki");
     return new CryptoKey("public", true, _algFromImport(name, alg, pub), usages, pub);
   }
   if (format === "pkcs8") {
-    var priv = nodeCrypto.createPrivateKey({ key: _toBuf(keyData, "importKey pkcs8"), format: "der", type: "pkcs8" });
+    var p8Buf = _toBuf(keyData, "importKey pkcs8");
+    _preValidatePkcs8(p8Buf, name);
+    var priv = _nodeKey(function () { return nodeCrypto.createPrivateKey({ key: p8Buf, format: "der", type: "pkcs8" }); }, "importKey pkcs8");
     return new CryptoKey("private", extractable, _algFromImport(name, alg, priv), usages, priv);
   }
   if (format === "jwk") {
     var jwk = keyData;
+    // A JWK is a JSON object; null / undefined / an array / a primitive (incl. the JSON token
+    // `null` from an unwrapKey over non-authenticating ciphertext) fails closed as a typed
+    // DataError, never a raw property-access TypeError.
+    if (jwk === null || typeof jwk !== "object" || Array.isArray(jwk)) {
+      throw new WebCryptoError("webcrypto/data", "importKey jwk: keyData must be a JsonWebKey object");
+    }
     if (jwk.kty === "oct") {
       var kbuf = _b64urlToBuf(jwk.k, "JWK oct key material");
       _assertAesImportLen(name, kbuf.length);
@@ -690,7 +792,7 @@ SubtleCrypto.prototype.importKey = async function importKey(format, keyData, alg
       return new CryptoKey("secret", extractable, a2, usages, s2);
     }
     var isPrivate = Object.prototype.hasOwnProperty.call(jwk, "d");
-    var ko = isPrivate ? nodeCrypto.createPrivateKey({ key: jwk, format: "jwk" }) : nodeCrypto.createPublicKey({ key: jwk, format: "jwk" });
+    var ko = _nodeKey(function () { return isPrivate ? nodeCrypto.createPrivateKey({ key: jwk, format: "jwk" }) : nodeCrypto.createPublicKey({ key: jwk, format: "jwk" }); }, "importKey jwk");
     return new CryptoKey(isPrivate ? "private" : "public", isPrivate ? extractable : true, _algFromImport(name, alg, ko), usages, ko);
   }
   throw new WebCryptoError("webcrypto/not-supported", "importKey: unsupported format " + JSON.stringify(format));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "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:2c42308d-4c79-437b-8bf2-36089abf8898",
+  "serialNumber": "urn:uuid:54db6dce-3101-401d-be5e-baa7f068783f",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-15T22:55:37.673Z",
+    "timestamp": "2026-07-16T03:51:39.360Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.20",
+      "bom-ref": "@blamejs/pki@0.2.22",
       "type": "application",
       "name": "pki",
-      "version": "0.2.20",
+      "version": "0.2.22",
       "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.20",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.22",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.20",
+      "ref": "@blamejs/pki@0.2.22",
       "dependsOn": []
     }
   ]