@blamejs/pki 0.2.19 → 0.2.21

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.2.21 — 2026-07-15
+
+ML-KEM public keys in X.509 certificates and PKCS#8 private keys (RFC 9935 / FIPS 203) become a first-class, fail-closed surface: certification-path validation enforces the keyEncipherment-only key usage, key import validates the private-key CHOICE and rejects an inconsistent key with a typed error, and pki.lint gains the RFC 9935 certificate rows.
+
+### Added
+
+- pki.path.validate enforces the RFC 9935 section 5 key-usage rule for ML-KEM (id-ml-kem-512/768/1024) certificates: a present keyUsage MUST assert keyEncipherment as the only bit. A leaf with digitalSignature, an ML-KEM key with keyCertSign / cRLSign / keyAgreement / dataEncipherment / nonRepudiation, or keyEncipherment set alongside any reserved bit, fails closed with the frozen code path/kem-key-usage -- for the target and every intermediate whose own subject key is ML-KEM. An absent keyUsage places no restriction (RFC 5280 section 4.2.1.3).
+- pki.lint gains an rfc9935 profile: lint/rfc9935/kem-key-usage (the section 5 keyEncipherment-only rule) and lint/rfc9935/kem-key-length (the SPKI encapsulation key must be exactly 800 / 1184 / 1568 octets for the id-ml-kem-512 / 768 / 1024 OID -- the OID is the sole authority for the parameter set, so an OCTET-STRING-wrapped or wrong-set key is flagged). Both run by default and are silent on a non-ML-KEM certificate.
+
+### Fixed
+
+- pki.webcrypto.subtle.importKey no longer surfaces a raw engine exception when handed a malformed or inconsistent key: a bad SPKI, a bad JWK, or an ML-KEM private key whose seed and expanded halves are inconsistent (FIPS 203 section 7.3) now fails closed with a typed webcrypto/data error. For an ML-KEM PKCS#8, the RFC 9935 section 6 private-key CHOICE is validated by its DER tag and exact size for the algorithm OID before the engine imports it -- the OpenSSL-legacy bare-seed, bare-expanded-key, and concatenated layouts the engine would otherwise accept are rejected, so a non-conformant private key cannot be imported under an ML-KEM name.
+- pki.webcrypto.subtle.importKey now fails closed on two further malformed-input classes: a JWK import whose key data is not an object (null, a primitive, or an array -- including the JSON null an unwrap over non-authenticating ciphertext can yield) returns a typed webcrypto/data error instead of a raw TypeError; and an SPKI or PKCS#8 import requested under a secret-key or key-derivation algorithm name (AES-GCM/CBC/CTR/KW, HMAC, HKDF, PBKDF2) is rejected as webcrypto/not-supported rather than importing a mislabeled key handle.
+
+## v0.2.20 — 2026-07-15
+
+A WebAuthn attestation object whose attestation statement is not a CBOR map is now rejected with a typed webauthn/bad-attestation-object at parse instead of surfacing an untyped error from a format verifier, and the strict CBOR codec gains pki.cbor.read.mapGet -- a keyed map lookup that asserts the map's major type inside the accessor.
+
+### Added
+
+- pki.cbor.read.mapGet(node, key) -- the keyed lookup over a decoded CBOR map (RFC 8949 major type 5). A text-string key matches text-string map keys; an integer key (a safe-integer number or a BigInt, as COSE labels are) matches integer map keys; matching never coerces across the two. It returns the value node, or null when the map has no such entry -- decode already enforced key uniqueness, so at most one entry can match. A non-map node throws cbor/unexpected-major, and a key that is neither a text string nor an integer throws a TypeError.
+
+### Changed
+
+- A WebAuthn attestation object whose attStmt is not a CBOR map is now classified as a malformed attestation object -- webauthn/bad-attestation-object, thrown at parse for every attestation format -- where it previously surfaced as a per-format webauthn/bad-att-stmt or an untyped error depending on the CBOR type carried.
+
+### Fixed
+
+- pki.webauthn.parseAttestationObject and pki.webauthn.verify no longer throw a raw TypeError when the attestation object's attStmt is a CBOR array: the attestation-statement field walk read the array's children as key/value pairs and dereferenced undefined. The attestation object's attStmt shape is now validated at parse (WebAuthn sec. 6.5.4), and the statement walk reads its pairs through pki.cbor.read.map, which asserts the major type -- malformed hostile bytes are a typed webauthn/* verdict, never an untyped crash.
+
 ## v0.2.19 — 2026-07-14
 
 The RFC 3161 Time-Stamp Protocol surface is complete: pki.tsp.request and pki.tsp.response build and parse the protocol's request and response messages, and pki.tsp.verify verifies a timestamp token end to end -- the CMS signature, the message imprint, the ESSCertID(V2) certificate binding, the critical timeStamping-only extendedKeyUsage, and full validation of the TSA certificate at the token's own genTime.

package/README.md

@@ -199,9 +199,9 @@ is callable today; nothing below is a stub.
 | Namespace | What it does |
 |---|---|
 | `pki.asn1` | Strict, bounded DER codec — `decode` (zero-copy node tree), `encode`, `build.*` canonical-DER value builders, `read.*` typed readers, `TAGS`, OID-content encode/decode |
-| `pki.cbor` | Strict, bounded RFC 8949 deterministic CBOR codec — `decode` (zero-copy node tree) + `read.*` typed leaf readers, fail-closed on every non-canonical shape (indefinite length, non-minimal argument, unsorted / duplicate map keys, non-shortest float, trailing bytes) |
+| `pki.cbor` | Strict, bounded RFC 8949 deterministic CBOR codec — `decode` (zero-copy node tree) + `read.*` typed leaf readers incl. the keyed map lookup `read.mapGet` (text or COSE-label integer key, the map's major type asserted in the accessor), fail-closed on every non-canonical shape (indefinite length, non-minimal argument, unsorted / duplicate map keys, non-shortest float, trailing bytes) |
 | `pki.oid` | Two-way OID ↔ name registry — `name`, `byName`, `register`, `toArcs`/`fromArcs`, `toDER`/`fromDER`; seeded with RFC 5280 + NIST PQC arcs |
-| `pki.webcrypto` | A W3C WebCrypto (`SubtleCrypto`) engine over `node:crypto` — `sign`/`verify`/`encrypt`/`decrypt`/`deriveBits`/`digest`/`generateKey`/`importKey`/`exportKey` across RSA, ECDSA, ECDH, Ed25519/Ed448, AES, HMAC, HKDF, PBKDF2, SHA — **and** post-quantum ML-DSA-44/65/87 and SLH-DSA signatures, plus ML-KEM-512/768/1024 key generation (KEM encapsulation on the roadmap). Zero-dependency, OpenSSL-interoperable |
+| `pki.webcrypto` | A W3C WebCrypto (`SubtleCrypto`) engine over `node:crypto` — `sign`/`verify`/`encrypt`/`decrypt`/`deriveBits`/`digest`/`generateKey`/`importKey`/`exportKey` across RSA, ECDSA, ECDH, Ed25519/Ed448, AES, HMAC, HKDF, PBKDF2, SHA — **and** post-quantum ML-DSA-44/65/87 and SLH-DSA signatures, plus ML-KEM-512/768/1024 key generation and certificate/PKCS#8 import — the RFC 9935 seed / expandedKey / both private-key CHOICE is validated fail-closed, so an OpenSSL-legacy bare-seed or an internally inconsistent key is rejected with a typed error (KEM encapsulation lands with CMS KEM-decrypt). Zero-dependency, OpenSSL-interoperable |
 | `pki.schema` | The schema family — `parse` detects which PKI format DER / PEM encodes and routes to the right parser, `all` enumerates the registered formats, and the engine + per-format members are grouped here |
 | `pki.schema.x509` | Parse DER / PEM certificates into structured, validated fields — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.crl` | Parse DER / PEM X.509 CRLs per RFC 5280 §5 — revoked serials with real-`Date` revocation times, named + partly-decoded extensions, fail-closed — `parse`, `pemDecode`, `pemEncode` |

package/lib/cbor-det.js

@@ -415,6 +415,52 @@ function readMap(node) {
   return node.children;
 }
 
+/**
+ * @primitive  pki.cbor.read.mapGet
+ * @signature  pki.cbor.read.mapGet(node, key) -> valueNode | null
+ * @since      0.2.20
+ * @status     experimental
+ * @spec       RFC 8949 sec. 3.1 (major type 5)
+ *
+ * The value node of the map entry whose key equals `key` -- a text string
+ * (matched against text-string keys) or an integer (a safe-integer number or a
+ * BigInt, matched against integer keys, as COSE labels are) -- or null when the
+ * map has no such entry. Key matching never coerces across types: a text key
+ * only matches a text-string key node, an integer key only an integer key node.
+ * At most one entry can match -- decode already enforced key uniqueness. This is
+ * the single keyed-lookup home over a decoded map: a consumer composes it (or
+ * `read.map`) rather than walking `children` as pairs, so a lookup can never
+ * pair-index a non-map's children (single nodes, whose pair index reads
+ * undefined). Throws `cbor/unexpected-major` when `node` is not a map -- a
+ * lookup on a non-map is malformed input, never an absent-entry verdict -- and
+ * a TypeError for a key that is neither a text string nor an integer.
+ *
+ * @example
+ *   pki.cbor.read.mapGet(node, "fmt"); // -> valueNode | null
+ *   pki.cbor.read.mapGet(node, 3);     // a COSE alg label -> valueNode | null
+ */
+function readMapGet(node, key) {
+  _expectMajor(node, 5, "read.mapGet");
+  var wantText = typeof key === "string";
+  if (!wantText) {
+    if (typeof key === "number") {
+      if (!Number.isSafeInteger(key)) throw new TypeError("read.mapGet: a numeric key must be a safe integer");
+      key = BigInt(key);
+    } else if (typeof key !== "bigint") {
+      throw new TypeError("read.mapGet: key must be a text string or an integer");
+    }
+  }
+  for (var i = 0; i < node.children.length; i++) {
+    var k = node.children[i][0];
+    if (wantText) {
+      if (k.majorType === 3 && readTextString(k) === key) return node.children[i][1];
+    } else if ((k.majorType === 0 || k.majorType === 1) && readInt(k) === key) {
+      return node.children[i][1];
+    }
+  }
+  return null;
+}
+
 /**
  * @primitive  pki.cbor.read.boolean
  * @signature  pki.cbor.read.boolean(node) -> false
@@ -550,6 +596,8 @@ function readTime(node) {
   }
   var ns = Number(secs);
   var d = new Date(ns < 0 ? -constants.TIME.seconds(-ns) : constants.TIME.seconds(ns));
+  // Coverage residual -- the epoch-window bound above already rejects any value the
+  // Date constructor cannot represent, so this backstop is defense-in-depth.
   if (isNaN(d.getTime())) throw new CborError("cbor/bad-time", "epoch time out of range");
   return d;
 }
@@ -586,6 +634,7 @@ module.exports = {
     textString:     readTextString,
     array:          readArray,
     map:            readMap,
+    mapGet:         readMapGet,
     boolean:        readBoolean,
     nullValue:      readNull,
     undefinedValue: readUndefined,

package/lib/lint.js

@@ -25,6 +25,7 @@
 
 var frameworkError = require("./framework-error");
 var asn1 = require("./asn1-der");
+var guard = require("./guard-all");
 var oid = require("./oid");
 var x509 = require("./schema-x509");
 var pkix = require("./schema-pkix");
@@ -458,11 +459,51 @@ var CABF_TLS_RULES = [
   },
 ];
 
+// RFC 9935 -- ML-KEM public keys in X.509 certificates. The OID is the sole authority for the
+// parameter set; the SPKI BIT STRING is the raw ek, exactly 384k+32 octets for that OID.
+var ML_KEM_EK_LEN = {};
+["id-ml-kem-512", "id-ml-kem-768", "id-ml-kem-1024"].forEach(function (n, i) { ML_KEM_EK_LEN[n] = [800, 1184, 1568][i]; });
+function _isMlKem(cert) {
+  var spki = cert.subjectPublicKeyInfo;
+  return !!(spki && spki.algorithm && ML_KEM_EK_LEN[spki.algorithm.name] !== undefined);
+}
+var RFC9935_RULES = [
+  {
+    id: "lint/rfc9935/kem-key-usage", severity: "error", source: "rfc9935", citation: "RFC 9935 5",
+    message: "an ML-KEM certificate's keyUsage, if present, must assert keyEncipherment as the only key usage set",
+    appliesTo: _isMlKem,
+    check: function (cert, ctx) {
+      var ku = ctx.decode("keyUsage");
+      if (!ku || !ku.value) return null;   // absent keyUsage is unconstrained (RFC 5280 4.2.1.3)
+      var v = ku.value;
+      var others = v.digitalSignature || v.nonRepudiation || v.dataEncipherment || v.keyAgreement ||
+        v.keyCertSign || v.cRLSign || v.encipherOnly || v.decipherOnly || v.reservedBitsSet === true;
+      return (v.keyEncipherment && !others) ? null : true;
+    },
+  },
+  {
+    id: "lint/rfc9935/kem-key-length", severity: "error", source: "rfc9935", citation: "RFC 9935 4 / FIPS 203",
+    message: "an ML-KEM subjectPublicKey must be the raw encapsulation key at its exact FIPS 203 size for the OID, in a byte-aligned BIT STRING",
+    appliesTo: _isMlKem,
+    check: function (cert) {
+      var spki = cert.subjectPublicKeyInfo;
+      var want = ML_KEM_EK_LEN[spki.algorithm.name];
+      var pub = spki.publicKey;   // a parsed SPKI always surfaces the BIT STRING as { bytes, unusedBits }
+      // The ek is a raw byte string carried in the BIT STRING: it must be the exact size AND
+      // byte-aligned. A right-length but non-octet-aligned BIT STRING (unusedBits != 0) is not the
+      // raw ek (RFC 9935 sec. 4); route the alignment test through the shared guard primitive.
+      return (guard.crypto.isOctetAligned(pub) && pub.bytes.length === want) ? null
+        : { context: { expected: want, got: pub.bytes.length, unusedBits: pub.unusedBits } };
+    },
+  },
+];
+
 var PROFILES = {
   "rfc5280": RFC5280_RULES,
+  "rfc9935": RFC9935_RULES,
   "cabf-tls": CABF_TLS_RULES,
 };
-var ALL_RULES = RFC5280_RULES.concat(CABF_TLS_RULES);
+var ALL_RULES = RFC5280_RULES.concat(RFC9935_RULES).concat(CABF_TLS_RULES);
 
 function _selectRules(profile) {
   if (profile == null || profile === "all" || profile === "default") return ALL_RULES;
@@ -557,7 +598,7 @@ function rules(profile) {
  *
  * List the known lint-profile names.
  * @example
- *   pki.lint.profiles();   // -> ["rfc5280", "cabf-tls"]
+ *   pki.lint.profiles();   // -> ["rfc5280", "rfc9935", "cabf-tls"]
  */
 function profiles() { return Object.keys(PROFILES); }
 

package/lib/oid.js

@@ -553,7 +553,7 @@ var _PARAMS_ABSENT = new Set();
   "id-hash-slh-dsa-shake-192s-with-shake256", "id-hash-slh-dsa-shake-192f-with-shake256",
   "id-hash-slh-dsa-shake-256s-with-shake256", "id-hash-slh-dsa-shake-256f-with-shake256",
   "Ed25519", "Ed448", "X25519", "X448",
-  // FIPS 203 ML-KEM (RFC 9936 sec. 3: PARAMS ARE absent).
+  // FIPS 203 ML-KEM (RFC 9935 sec. 3 certificates + RFC 9936 sec. 3 CMS: PARAMS ARE absent).
   "id-ml-kem-512", "id-ml-kem-768", "id-ml-kem-1024",
   // HKDF key-derivation identifiers (RFC 8619 sec. 2: when any of these appear
   // within AlgorithmIdentifier, the parameters component SHALL be absent).

package/lib/path-validate.js

@@ -331,6 +331,32 @@ function compositeKeyUsageCheck(cert) {
   return { ok: true };
 }
 
+// The ML-KEM SubjectPublicKeyInfo OIDs (RFC 9935 / FIPS 203). A certificate carrying one of
+// these keys is a KEM key-establishment certificate: it can neither sign nor agree.
+var ML_KEM_OIDS = {};
+["id-ml-kem-512", "id-ml-kem-768", "id-ml-kem-1024"].forEach(function (n) { ML_KEM_OIDS[oid.byName(n)] = true; });
+
+// RFC 9935 sec. 5: a certificate whose SubjectPublicKeyInfo carries an id-ml-kem-* OID, IF it
+// has a keyUsage extension, MUST assert keyEncipherment as the ONLY key usage set -- an ML-KEM
+// key is a key-establishment-only key (it cannot sign or agree, so no other bit is legitimate,
+// and an unnamed/reserved bit set alongside keyEncipherment is equally forbidden). The caller
+// invokes this only for an ML-KEM-keyed certificate; an absent keyUsage places no restriction
+// (RFC 5280 sec. 4.2.1.3). This also makes an ML-KEM "CA" (keyCertSign) an explicit reject.
+function kemKeyUsageCheck(cert) {
+  var ku;
+  try { ku = decodeExt(cert, OID.keyUsage); }
+  catch (e) { return { ok: false, code: "path/kem-key-usage", error: e }; }
+  if (!ku) return { ok: true };
+  var v = ku.value;
+  var others = v.digitalSignature || v.nonRepudiation || v.dataEncipherment || v.keyAgreement ||
+    v.keyCertSign || v.cRLSign || v.encipherOnly || v.decipherOnly || (v.reservedBitsSet === true);
+  if (!v.keyEncipherment || others) {
+    return { ok: false, code: "path/kem-key-usage",
+      error: E("path/kem-key-usage", "an ML-KEM key's keyUsage must assert keyEncipherment as the only bit (RFC 9935 sec. 5)") };
+  }
+  return { ok: true };
+}
+
 // Import a descriptor's verification key, validating an EdDSA point FIRST: node/OpenSSL import a
 // low-order (e.g. identity or all-zeroes) Ed25519/Ed448 SPKI without complaint and such a key
 // verifies a forged signature. This is the ONE seam both the certificate path and the revocation
@@ -1215,6 +1241,14 @@ async function validate(path, opts) {
       if (!cku.ok) failed = true;
     }
 
+    // RFC 9935 sec. 5: an ML-KEM-keyed certificate's keyUsage must be keyEncipherment-only.
+    // Runs for the target AND every intermediate whose own subject key is ML-KEM.
+    if (ML_KEM_OIDS[cert.subjectPublicKeyInfo.algorithm.oid]) {
+      var kku = kemKeyUsageCheck(cert);
+      checks.push({ name: "kemKeyUsage", ok: kku.ok, code: kku.ok ? undefined : kku.code });
+      if (!kku.ok) failed = true;
+    }
+
     // 6.1.3(a)(2) validity window.
     var t = opts.time;
     var vOk = true, vCode;

package/lib/schema-pkix.js

@@ -660,6 +660,14 @@ function certExtensionDecoders(ns) {
       var byte = bit >> 3, mask = 0x80 >> (bit & 7);
       out[nm] = byte < bs.bytes.length && (bs.bytes[byte] & mask) !== 0;
     });
+    // Any bit beyond the 9 named positions is a reserved/unknown usage. RFC 5280 tolerates it,
+    // but a "MUST be the ONLY bit" rule (e.g. RFC 9935 sec. 5 ML-KEM keyEncipherment-only) needs
+    // to see it -- so surface it rather than silently drop bits >= 9.
+    var reserved = false;
+    for (var bit2 = KU_BITS.length; bit2 < bs.bytes.length * 8 && !reserved; bit2++) {
+      if ((bs.bytes[bit2 >> 3] & (0x80 >> (bit2 & 7))) !== 0) reserved = true;
+    }
+    out.reservedBitsSet = reserved;
     return out;
   }
 

package/lib/validator-cose.js

@@ -64,19 +64,6 @@ var ALG_PROFILE = {
   "-257": { kty: 3 }, "-258": { kty: 3 }, "-259": { kty: 3 }, "-37": { kty: 3 }, "-65535": { kty: 3 },
 };
 
-// The value node of an integer-labelled COSE_Key parameter (labels are ints), or null.
-function _mapGetInt(node, key) {
-  // Coverage residual -- credentialKey validates node is a majorType-5 map (before any
-  // _mapGetInt call), and cbor-det always gives a map a (truthy) children array, so this
-  // guard cannot fire.
-  if (!node || node.majorType !== 5 || !node.children) return null;
-  for (var i = 0; i < node.children.length; i++) {
-    var k = node.children[i][0];
-    if ((k.majorType === 0 || k.majorType === 1) && cbor.read.int(k) === BigInt(key)) return node.children[i][1];
-  }
-  return null;
-}
-
 // credentialKey(node, E, code) -> the decoded + validated credential public key
 // { kty, alg, crv?, x?, y?, n?, e? }, or throws new E(code, ...). The complete COSE_Key
 // conformance gate for a WebAuthn credential key; a format module MUST route a credential
@@ -90,9 +77,9 @@ function credentialKey(node, E, code) {
   if (!node || node.majorType !== 5) throw bad("a COSE_Key must be a CBOR map (RFC 9052 sec. 7)");
   // Every parameter read maps a wrong-type cbor/* fault to the caller's domain -- a
   // wrong-typed COSE label (x as an integer, kty as a string) is bad input, not a leak.
-  function ib(label) { var n = _mapGetInt(node, label); if (!n) return null; try { return cbor.read.byteString(n); } catch (e) { throw bad("COSE_Key parameter " + label + " must be a byte string", e); } }
-  function ii(label) { var n = _mapGetInt(node, label); if (!n) return null; try { return cbor.read.int(n); } catch (e) { throw bad("COSE_Key parameter " + label + " must be an integer", e); } }
-  var ktyN = _mapGetInt(node, 1), algN = _mapGetInt(node, 3);
+  function ib(label) { var n = cbor.read.mapGet(node, label); if (!n) return null; try { return cbor.read.byteString(n); } catch (e) { throw bad("COSE_Key parameter " + label + " must be a byte string", e); } }
+  function ii(label) { var n = cbor.read.mapGet(node, label); if (!n) return null; try { return cbor.read.int(n); } catch (e) { throw bad("COSE_Key parameter " + label + " must be an integer", e); } }
+  var ktyN = cbor.read.mapGet(node, 1), algN = cbor.read.mapGet(node, 3);
   if (!ktyN) throw bad("a COSE_Key is missing the kty (label 1) parameter");
   if (!algN) throw bad("a COSE_Key is missing the alg (label 3) parameter");
   var kty, algv;
@@ -103,7 +90,7 @@ function credentialKey(node, E, code) {
     key.crv = ii(-1) != null ? Number(ii(-1)) : null;
     // WebAuthn EC2 credential keys MUST use the uncompressed point form: y (-3) is the full
     // y-coordinate byte string, never a CBOR bool sign bit (WebAuthn sec. alg identifier).
-    var yNode = _mapGetInt(node, -3);
+    var yNode = cbor.read.mapGet(node, -3);
     if (yNode && yNode.majorType === 7) throw bad("an EC2 credential key must use the uncompressed point form (a compressed y sign-bit is not permitted for WebAuthn)");
     key.x = ib(-2); key.y = ib(-3);
     if (key.crv == null || !key.x || !key.y) throw bad("an EC2 COSE_Key must carry crv (-1), x (-2), and y (-3)");

package/lib/webauthn.js

@@ -75,20 +75,6 @@ function _coseAlgHash(alg, E) {
   return h;
 }
 
-// ---- CBOR map access over the strict pki.cbor node tree ----------------------
-
-// A decoded CBOR map is a node whose `children` is an array of [keyNode, valNode].
-// Look a text-keyed entry up, or null. The strict codec already rejected a
-// duplicate map key, so at most one match exists.
-function _mapGet(node, key) {
-  if (!node || node.majorType !== 5 || !node.children) return null;
-  for (var i = 0; i < node.children.length; i++) {
-    var k = node.children[i][0];
-    if (k.majorType === 3 && cbor.read.textString(k) === key) return node.children[i][1];
-  }
-  return null;
-}
-
 // ---- authenticatorData bounded reader (WebAuthn sec. 6.1) --------------------
 
 // authData = rpIdHash[32] || flags[1] || signCount[4 BE] || (AT? attestedCredentialData) || (ED? extensions CBOR).
@@ -333,11 +319,16 @@ function parseAttestationObject(bytes) {
   var root;
   try { root = cbor.decode(bytes); } catch (e) { throw _err("webauthn/bad-attestation-object", "the attestation object is not well-formed CBOR", e); }
   if (root.majorType !== 5) throw _err("webauthn/bad-attestation-object", "the attestation object must be a CBOR map { fmt, attStmt, authData }");
-  var fmtN = _mapGet(root, "fmt"), attStmtN = _mapGet(root, "attStmt"), authDataN = _mapGet(root, "authData");
+  var fmtN = cbor.read.mapGet(root, "fmt"), attStmtN = cbor.read.mapGet(root, "attStmt"), authDataN = cbor.read.mapGet(root, "authData");
   // The attestation object is EXACTLY { fmt, attStmt, authData } -- no more, no fewer
   // (WebAuthn 6.5.4); an extra top-level key is a non-canonical envelope, rejected.
   if (root.children.length !== 3 || !fmtN || !attStmtN || !authDataN) throw _err("webauthn/bad-attestation-object", "the attestation object must be exactly { fmt, attStmt, authData }");
   if (fmtN.majorType !== 3) throw _err("webauthn/bad-attestation-object", "attestation object 'fmt' must be a text string");
+  // attStmt is the attestation statement, a CBOR map keyed by field name (WebAuthn 6.5.4);
+  // a non-map attStmt is a malformed attestation OBJECT, rejected here rather than deferred
+  // to a format verifier -- a non-map value (e.g. a CBOR array, whose children are single
+  // nodes, not { key, value } pairs) must never reach the per-field statement walk.
+  if (attStmtN.majorType !== 5) throw _err("webauthn/bad-attestation-object", "attestation object 'attStmt' must be a CBOR map");
   if (authDataN.majorType !== 2) throw _err("webauthn/bad-attestation-object", "attestation object 'authData' must be a byte string");
   var authDataBytes = cbor.read.byteString(authDataN);
   return {
@@ -351,7 +342,7 @@ function parseAttestationObject(bytes) {
 // ---- attestation-format verifiers -------------------------------------------
 
 function _reqAttr(map, key) {
-  var n = _mapGet(map, key);
+  var n = cbor.read.mapGet(map, key);
   if (!n) throw _err("webauthn/bad-att-stmt", "the attestation statement is missing the '" + key + "' field");
   return n;
 }
@@ -370,7 +361,11 @@ function _sigOf(attStmt) { return _attRead(attStmt, "sig", cbor.read.byteString,
 // non-canonical statement, rejected before any field is trusted (WebAuthn sec. 8.*).
 function _requireAttShape(attStmt, allowed, required) {
   var have = {};
-  if (attStmt && attStmt.children) attStmt.children.forEach(function (kv) {
+  // attStmt is the attestation-statement map (parseAttestationObject established it is a CBOR
+  // map). cbor.read.map asserts the major type and yields the { key, value } pairs -- never a
+  // raw .children walk, whose entries are single nodes (not pairs) for a non-map, so a pair
+  // index would read undefined and throw a raw TypeError instead of failing closed.
+  cbor.read.map(attStmt).forEach(function (kv) {
     // attStmt keys are text strings; a non-text key is a malformed statement,
     // rejected (not silently skipped, which would evade the unexpected-field check).
     if (kv[0].majorType !== 3) throw _err("webauthn/bad-att-stmt", "the attestation statement has a non-text-string field key");
@@ -380,7 +375,7 @@ function _requireAttShape(attStmt, allowed, required) {
   required.forEach(function (k) { if (!have[k]) throw _err("webauthn/bad-att-stmt", "the attestation statement is missing the '" + k + "' field"); });
 }
 function _readX5c(attStmt) {
-  var x5cN = _mapGet(attStmt, "x5c");
+  var x5cN = cbor.read.mapGet(attStmt, "x5c");
   if (!x5cN || x5cN.majorType !== 4 || !x5cN.children || !x5cN.children.length) throw _err("webauthn/bad-att-stmt", "x5c must be a non-empty array of certificates");
   return x5cN.children.map(function (c) {
     var der;
@@ -401,7 +396,7 @@ function _checkAaguidExt(cert, aaguid) { validator.attcert.aaguidExt(cert, aagui
 var VERIFIERS = {
   // packed (WebAuthn 8.2): the x5c arm (Basic/AttCA) or self-attestation.
   packed: function (att, clientDataHash) {
-    var isX5c = !!_mapGet(att.attStmt, "x5c");
+    var isX5c = !!cbor.read.mapGet(att.attStmt, "x5c");
     _requireAttShape(att.attStmt, isX5c ? ["alg", "sig", "x5c"] : ["alg", "sig"], isX5c ? ["alg", "sig", "x5c"] : ["alg", "sig"]);
     var alg = _algOf(att.attStmt), sig = _sigOf(att.attStmt);
     var message = Buffer.concat([att.authDataBytes, clientDataHash]);
@@ -483,7 +478,7 @@ var VERIFIERS = {
   // bind pubArea to the credential key, and verify sig over certInfo with the AIK.
   tpm: function (att, clientDataHash) {
     _requireAttShape(att.attStmt, ["ver", "alg", "sig", "certInfo", "pubArea", "x5c"], ["ver", "alg", "sig", "certInfo", "pubArea", "x5c"]);
-    var verN = _mapGet(att.attStmt, "ver");
+    var verN = cbor.read.mapGet(att.attStmt, "ver");
     if (!verN || verN.majorType !== 3 || cbor.read.textString(verN) !== "2.0") throw _err("webauthn/bad-att-stmt", "tpm attestation 'ver' MUST be \"2.0\" (WebAuthn 8.3)");
     var alg = _algOf(att.attStmt), sig = _sigOf(att.attStmt);
     var pubAreaBytes = _attRead(att.attStmt, "pubArea", cbor.read.byteString, "a byte string");
@@ -526,9 +521,9 @@ var VERIFIERS = {
   // an empty map; there is no statement to verify, so the result carries no trust
   // path. The credential public key still binds via authenticatorData (AT flag).
   none: function (att) {
-    // attStmt MUST BE an empty CBOR map -- reject a missing, non-map, or non-empty
-    // attStmt, not only a non-empty map (WebAuthn 8.7).
-    if (!att.attStmt || att.attStmt.majorType !== 5 || (att.attStmt.children && att.attStmt.children.length !== 0)) {
+    // parseAttestationObject has already established attStmt is a CBOR map; the none format
+    // additionally requires it be EMPTY -- there is no statement to verify (WebAuthn 8.7).
+    if (att.attStmt.children.length !== 0) {
       throw _err("webauthn/bad-att-stmt", "the none attestation statement MUST be an empty map (WebAuthn 8.7)");
     }
     return Promise.resolve(_result("none", "None", [], att));

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.19",
+  "version": "0.2.21",
   "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:d6e0649c-f4db-4241-8784-6f3c9d3d663f",
+  "serialNumber": "urn:uuid:77add14d-d236-4f91-aec8-607349cb6aa8",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-14T16:14:40.970Z",
+    "timestamp": "2026-07-16T01:35:31.295Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.19",
+      "bom-ref": "@blamejs/pki@0.2.21",
       "type": "application",
       "name": "pki",
-      "version": "0.2.19",
+      "version": "0.2.21",
       "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.19",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.21",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.19",
+      "ref": "@blamejs/pki@0.2.21",
       "dependsOn": []
     }
   ]