@blamejs/pki 0.2.22 → 0.2.24

package/lib/ct.js

@@ -38,11 +38,13 @@
  *   bounded TLS-struct decode, fail-closed.
  */
 
+var nodeCrypto = require("crypto");
 var asn1 = require("./asn1-der.js");
 var constants = require("./constants.js");
 var frameworkError = require("./framework-error.js");
 var guard = require("./guard-all.js");
 var ByteReader = require("./byte-reader.js");
+var ByteWriter = require("./byte-writer.js");
 var oid = require("./oid.js");
 var webcrypto = require("./webcrypto.js");
 var validator = require("./validator-all.js");
@@ -136,15 +138,15 @@ function _parseSct(r, sctLen) {
 
 /**
  * @primitive  pki.ct.parseSctList
- * @signature  pki.ct.parseSctList(extValue) -> { scts, unknownScts }
+ * @signature  pki.ct.parseSctList(extValue) -> { scts, unknownScts, all }
  * @since      0.1.20
  * @status     experimental
  * @spec       RFC 6962, RFC 5246, RFC 8446
- * @related    pki.ct.reconstructSignedData, pki.schema.x509.parse
+ * @related    pki.ct.reconstructSignedData, pki.ct.encodeSctList, pki.schema.x509.parse
  *
  * Parse the value of an RFC 6962 SCT-list extension (the raw `extnValue`
  * content an `x509.parse` / OCSP extension already surfaces) into
- * `{ scts, unknownScts }`. Each entry of `scts` is a fully decoded v1 SCT:
+ * `{ scts, unknownScts, all }`. Each entry of `scts` is a fully decoded v1 SCT:
  * `version` (0), `logId` (32-byte Buffer) + `logIdHex`, `timestamp` (BigInt,
  * exact) + `timestampMs` (Number or `null` above 2^53) + `timestampDate`,
  * `extensions` (raw Buffer), `hashAlg` / `sigAlg` (1-byte code points) + a named
@@ -152,7 +154,10 @@ function _parseSct(r, sctLen) {
  * SerializedSCT body). A SerializedSCT whose version this parser does not define
  * is preserved OPAQUE in `unknownScts` as `{ version, rawSct }` rather than
  * failing the list -- RFC 6962 sec. 3.3 frames each SerializedSCT with its own length
- * so unknown versions are skippable (forward compatibility).
+ * so unknown versions are skippable (forward compatibility). `all` lists every
+ * SerializedSCT (known and unknown) in the exact wire order, so
+ * `encodeSctList(all)` reproduces the list byte-identically even when the two
+ * kinds are interleaved.
  *
  * The extension value is a DER `OCTET STRING` wrapping the TLS-encoded list
  * (RFC 6962 sec. 3.3 double wrap); everything below that peel is TLS presentation
@@ -186,7 +191,7 @@ function parseSctList(extValue) {
   if (listLen < 1) {
     throw new CtError("ct/empty-list", "an SCT list must contain at least one SCT (RFC 6962 sec. 3.3)");
   }
-  var scts = [], unknownScts = [];
+  var scts = [], unknownScts = [], all = [];
   // The shared item counter bounds the TOTAL element count (known + preserved-
   // unknown) before it can drive unbounded per-element work (RFC 6962 sec. 3.3).
   var sctCount = guard.limits.counter(C.LIMITS.SCT_MAX_COUNT, _ctErr, "ct/too-many-scts", "SCT");
@@ -203,10 +208,12 @@ function parseSctList(extValue) {
     }
     sctCount.tick();
     var one = _parseSct(outer.subReader(sctLen, "ct/list-trailing-bytes"), sctLen);
-    if (one.unknown) unknownScts.push({ version: one.version, rawSct: one.rawSct });
-    else scts.push(one);
+    if (one.unknown) { var u = { version: one.version, rawSct: one.rawSct }; unknownScts.push(u); all.push(u); }
+    else { scts.push(one); all.push(one); }
   }
-  return { scts: scts, unknownScts: unknownScts };
+  // `all` preserves the exact wire order across known + unknown entries, so encodeSctList(all)
+  // reproduces the list byte-identically even when the two kinds were interleaved.
+  return { scts: scts, unknownScts: unknownScts, all: all };
 }
 
 function _u24Bytes(n) {
@@ -409,10 +416,188 @@ async function verifySct(entry, sct, logPublicKey) {
   }
 }
 
+// The TLS-vector WRITER bound to the ct/* fault domain -- the encode twin of TlsReader,
+// over the shared ByteWriter engine primitive (see lib/byte-writer.js).
+function TlsWriter() { return new ByteWriter(CtError, "ct/bad-input"); }
+
+// Encode one SerializedSCT body. A v1 SCT is rebuilt from its fields in the exact _parseSct
+// order (so it round-trips byte-identically); an opaque non-v1 entry re-emits its rawSct
+// verbatim (RFC 6962 sec. 3.3 forward-compat symmetry -- encode preserves what parse preserved).
+function _encodeSctBody(sct) {
+  if (!sct || typeof sct !== "object") throw new CtError("ct/bad-input", "each SCT must be an object");
+  if (sct.version !== 0) {
+    // The SerializedSCT version is a single byte (RFC 6962 sec. 3.2), so a declared version must be a
+    // 0..255 integer -- reject a non-byte value rather than masking it (a masked 263 would spoof v7).
+    if (typeof sct.version !== "number" || !Number.isInteger(sct.version) || sct.version < 0 || sct.version > 255) {
+      throw new CtError("ct/bad-input", "an SCT version must be a byte in 0..255 (RFC 6962 sec. 3.2)");
+    }
+    // An opaque entry re-emits its rawSct verbatim, but the SerializedSCT's on-wire version is
+    // rawSct[0] -- refuse a rawSct whose leading byte disagrees with the declared version, so encode
+    // never emits a list whose framing our own parser would reject or re-classify (RFC 6962 sec. 3.3).
+    var raw = _toBuffer(sct.rawSct, "sct.rawSct");
+    if (raw.length < 1 || raw[0] !== sct.version) {
+      throw new CtError("ct/bad-input", "an opaque SCT's rawSct[0] must equal its declared version (RFC 6962 sec. 3.3)");
+    }
+    return raw;
+  }
+  var w = new TlsWriter();
+  w.u8(0, "ct/bad-input");                                                            // Version -- v1(0)
+  var logId = _toBuffer(sct.logId, "sct.logId");
+  if (logId.length !== LOGID_BYTES) throw new CtError("ct/bad-input", "an SCT logId must be exactly " + LOGID_BYTES + " bytes (RFC 6962 sec. 3.2)");
+  w.bytes(logId);
+  w.u64(guard.range.uint64(sct.timestamp, _ctErr, "ct/bad-input", "sct.timestamp"), "ct/bad-input");   // uint64 timestamp
+  w.vector(2, 0, 0xffff, _toBuffer(sct.extensions, "sct.extensions"), "ct/bad-input");  // CtExtensions<0..2^16-1>
+  w.u8(sct.hashAlg, "ct/bad-input");                                                   // digitally-signed hash
+  w.u8(sct.sigAlg, "ct/bad-input");                                                    // digitally-signed signature
+  w.vector(2, 0, 0xffff, _toBuffer(sct.signature, "sct.signature"), "ct/bad-input");   // signature<0..2^16-1>
+  return w.build();
+}
+
+/**
+ * @primitive  pki.ct.encodeSctList
+ * @signature  pki.ct.encodeSctList(scts) -> Buffer
+ * @since      0.2.24
+ * @status     experimental
+ * @spec       RFC 6962, RFC 5246
+ * @related    pki.ct.parseSctList, pki.ct.signSct
+ *
+ * Build the value of an RFC 6962 SCT-list extension from an array of SCTs -- the exact
+ * inverse of `parseSctList`, such that `parseSctList(encodeSctList(list.all))` round-trips to
+ * identical bytes. Each element is either a decoded v1 SCT (the shape `parseSctList().scts[]`
+ * or `signSct` returns: `version` 0, 32-byte `logId`, `timestamp` BigInt, raw `extensions`,
+ * `hashAlg` / `sigAlg` code points, raw `signature`) -- rebuilt from its fields in the RFC
+ * 6962 sec. 3.2 field order -- or an opaque non-v1 entry (`{ version, rawSct }`) whose
+ * `rawSct` is re-emitted verbatim (forward compatibility, sec. 3.3). Pass `parseSctList().all`
+ * (not `.scts`) to preserve the exact wire order and every unknown-version entry.
+ *
+ * Returns the DER `OCTET STRING`-wrapped TLS `SignedCertificateTimestampList` (the same
+ * `extnValue` content `parseSctList` consumes). The list must be non-empty and stays within
+ * the parser's `SCT_MAX_COUNT` element cap and the RFC 6962 sec. 3.3 65535-byte list-body cap so
+ * encode cannot emit what parse would reject. Throws a typed `CtError` (`ct/empty-list`,
+ * `ct/bad-input`, `ct/too-large`, `ct/too-many-scts`) on malformed input.
+ *
+ * @example
+ *   var list = pki.ct.parseSctList(sctExtValue);
+ *   var reEncoded = pki.ct.encodeSctList(list.all);   // byte-identical to sctExtValue
+ */
+function encodeSctList(scts) {
+  if (!Array.isArray(scts)) throw new CtError("ct/bad-input", "encodeSctList expects an array of SCTs");
+  if (scts.length < 1) throw new CtError("ct/empty-list", "an SCT list must contain at least one SCT (RFC 6962 sec. 3.3)");
+  var sctCount = guard.limits.counter(C.LIMITS.SCT_MAX_COUNT, _ctErr, "ct/too-many-scts", "SCT");
+  var elements = [], total = 0;
+  for (var i = 0; i < scts.length; i++) {
+    sctCount.tick();
+    var ew = new TlsWriter();
+    ew.vector(2, 1, 0xffff, _encodeSctBody(scts[i]), "ct/bad-input");   // SerializedSCT<1..2^16-1>
+    var el = ew.build();
+    total += el.length;
+    // Enforce the sct_list<1..2^16-1> body cap INCREMENTALLY, so an over-long list fails at the first
+    // element that crosses the bound instead of accumulating the whole (potentially large) set first.
+    if (total > 0xffff) throw new CtError("ct/too-large", "the SCT list body exceeds the 65535-byte maximum (RFC 6962 sec. 3.3)");
+    elements.push(el);
+  }
+  var lw = new TlsWriter();
+  lw.vector(2, 1, 0xffff, Buffer.concat(elements, total), "ct/too-large");   // sct_list<1..2^16-1>
+  return asn1.build.octetString(lw.build());                                 // RFC 6962 sec. 3.3 DER OCTET STRING wrap
+}
+
+// A CT log private key -> its PKCS#8 DER (for WebCrypto sign) + the SPKI DER (for the LogID +
+// the sec. 2.1.4 algorithm profile). Accepts a PKCS#8 DER Buffer, a PEM string, a node
+// KeyObject, or a { key, format, type } input.
+function _logKeyMaterial(logKey) {
+  // Every key operation runs inside the guard: a duck-typed impostor (an object carrying an
+  // asymmetricKeyType but not a real KeyObject) fails at export/createPublicKey and surfaces the
+  // typed ct/bad-input, never a raw TypeError. The private-key check keeps its own CtError.
+  try {
+    var keyObj;
+    if (logKey && typeof logKey === "object" && logKey.asymmetricKeyType) keyObj = logKey;
+    else if (Buffer.isBuffer(logKey)) keyObj = nodeCrypto.createPrivateKey({ key: logKey, format: "der", type: "pkcs8" });
+    else keyObj = nodeCrypto.createPrivateKey(logKey);
+    if (keyObj.type !== "private") throw new CtError("ct/bad-input", "signSct requires the CT log PRIVATE key");
+    return { pkcs8: keyObj.export({ type: "pkcs8", format: "der" }), spki: nodeCrypto.createPublicKey(keyObj).export({ type: "spki", format: "der" }) };
+  } catch (e) {
+    if (e instanceof CtError) throw e;
+    throw new CtError("ct/bad-input", "the CT log private key could not be loaded", e);
+  }
+}
+
+/**
+ * @primitive  pki.ct.signSct
+ * @signature  pki.ct.signSct(entry, logKey, opts?) -> Promise<sct>
+ * @since      0.2.24
+ * @status     experimental
+ * @spec       RFC 6962
+ * @related    pki.ct.verifySct, pki.ct.reconstructSignedData, pki.ct.encodeSctList
+ *
+ * Perform a Certificate Transparency log's signing step (RFC 6962 sec. 3.2): rebuild the exact
+ * `digitally-signed` preimage over `entry` (via `reconstructSignedData`, the SAME builder the
+ * verifier hashes), sign it with the log's private key, and return a fully-formed v1 SCT that
+ * `verifySct` accepts against the log's public key. `entry` is the log entry the SCT covers
+ * (`{ entryType: 0, leafCert }` or `{ entryType: 1, tbsCertificate, issuerKeyHash }`, as for
+ * `reconstructSignedData`); `logKey` is the log's private key (PKCS#8 DER `Buffer`, PEM string,
+ * or a node `KeyObject`).
+ *
+ * The log-key profile is RFC 6962 sec. 2.1.4: ECDSA NIST P-256 (`sigAlg` 3) or RSA >= 2048
+ * (`sigAlg` 1), SHA-256 only -- an unsupported key fails closed `ct/unsupported-algorithm`. The
+ * `logId` is derived as SHA-256 of the log SPKI (sec. 3.4); a supplied `opts.logId` must match.
+ * The returned SCT is the parseSctList/verifySct shape and composes with `encodeSctList`.
+ *
+ * @opts timestamp   ms since the epoch (finite non-negative integer/BigInt). Default `Date.now()`.
+ * @opts extensions  raw `CtExtensions` bytes (opaque<0..2^16-1>). Default empty.
+ * @opts logId       assert the derived LogID equals this 32-byte value (fail closed on mismatch).
+ * @example
+ *   var sct = await pki.ct.signSct({ entryType: 0, leafCert: der }, signerKeyPkcs8);
+ *   var ext = pki.ct.encodeSctList([sct]);
+ */
+async function signSct(entry, logKey, opts) {
+  opts = opts || {};
+  var mat = _logKeyMaterial(logKey);
+  var alg = _spkiAlg(mat.spki);
+  var hashAlg = 4, sigAlg, imp, sign, ecdsaDer = false, coordLen;
+  if (alg.algOid === oid.byName("ecPublicKey")) {
+    var ec = CT_EC_CURVE[alg.curveOid];
+    if (!ec) throw new CtError("ct/unsupported-algorithm", "unsupported SCT log EC curve (RFC 6962 sec. 2.1.4 mandates NIST P-256)");
+    sigAlg = 3; imp = { name: "ECDSA", namedCurve: ec.curve }; sign = { name: "ECDSA", hash: "SHA-256" }; ecdsaDer = true; coordLen = ec.coordLen;
+  } else if (alg.algOid === oid.byName("rsaEncryption")) {
+    if (!(alg.rsaBits >= 2048)) throw new CtError("ct/unsupported-algorithm", "the SCT log RSA key is below the RFC 6962 sec. 2.1.4 minimum of 2048 bits");
+    sigAlg = 1; imp = { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }; sign = { name: "RSASSA-PKCS1-v1_5" };
+  } else {
+    throw new CtError("ct/unsupported-algorithm", "unsupported SCT log key algorithm (RFC 6962 sec. 2.1.4 supports ecdsa P-256 / rsa)");
+  }
+  var timestamp;
+  if (opts.timestamp == null) timestamp = BigInt(Date.now());
+  else if (typeof opts.timestamp === "bigint") timestamp = opts.timestamp;
+  else if (typeof opts.timestamp === "number" && Number.isSafeInteger(opts.timestamp) && opts.timestamp >= 0) timestamp = BigInt(opts.timestamp);
+  else throw new CtError("ct/bad-input", "timestamp must be a finite non-negative integer or BigInt (RFC 6962 sec. 3.2)");
+  var extensions = opts.extensions == null ? Buffer.alloc(0) : _toBuffer(opts.extensions, "opts.extensions");
+  var logId = Buffer.from(await subtle.digest("SHA-256", mat.spki));
+  if (opts.logId != null && !_toBuffer(opts.logId, "opts.logId").equals(logId)) {
+    throw new CtError("ct/bad-input", "opts.logId does not match SHA-256 of the log key (RFC 6962 sec. 3.4)");
+  }
+  // Reuse the ONE preimage builder the verifier uses -- sign and verify cannot diverge.
+  var preimage = reconstructSignedData(entry, { version: 0, timestamp: timestamp, extensions: extensions });
+  var priv = await subtle.importKey("pkcs8", mat.pkcs8, imp, false, ["sign"]);
+  var sigRaw = Buffer.from(await subtle.sign(sign, priv, preimage));
+  var signature = ecdsaDer ? validator.sig.rawToEcdsaDer(sigRaw, coordLen) : sigRaw;
+  return {
+    version: 0,
+    logId: logId, logIdHex: logId.toString("hex"),
+    timestamp: timestamp,
+    extensions: extensions,
+    hashAlg: hashAlg, sigAlg: sigAlg,
+    // The `|| null` fallbacks mirror parseSctList's shape; unreachable here since signSct only ever
+    // emits the in-map sha256(4) + ecdsa(3)/rsa(1) code points (coverage residual).
+    signatureAlgorithm: { hash: hashAlg, hashName: HASH_ALGORITHMS[hashAlg] || null, signature: sigAlg, signatureName: SIGNATURE_ALGORITHMS[sigAlg] || null },
+    signature: signature,
+  };
+}
+
 module.exports = {
   parseSctList: parseSctList,
   reconstructSignedData: reconstructSignedData,
   verifySct: verifySct,
+  encodeSctList: encodeSctList,
+  signSct: signSct,
   HASH_ALGORITHMS: HASH_ALGORITHMS,
   SIGNATURE_ALGORITHMS: SIGNATURE_ALGORITHMS,
 };

package/lib/oid.js

@@ -147,7 +147,7 @@ var FAMILIES = {
 
   // PKCS#1 RSA public-key + RSASSA signature algorithms.
   rsa: { base: [1, 2, 840, 113549, 1, 1], of: {
-    rsaEncryption: 1, rsaesOaep: 7, mgf1: 8, rsassaPss: 10,
+    rsaEncryption: 1, rsaesOaep: 7, mgf1: 8, pSpecified: 9, rsassaPss: 10,
     sha256WithRSAEncryption: 11,
     sha384WithRSAEncryption: 12, sha512WithRSAEncryption: 13 } },
 
@@ -215,9 +215,26 @@ var FAMILIES = {
   // CEK-HKDF content-encryption wrapper (RFC 9709) a KEMRecipientInfo names, plus
   // the RSA-KEM SPKI algorithm (RFC 9690). Parameters are absent for the HKDFs.
   smimeAlg: { base: [1, 2, 840, 113549, 1, 9, 16, 3], of: {
+    "id-alg-PWRI-KEK": 9,
     "id-rsa-kem": 14, "id-alg-hss-lms-hashsig": 17,
+    // RFC 8418 X25519/X448 key-agreement schemes (HKDF-based).
+    "dhSinglePass-stdDH-hkdf-sha256-scheme": 19, "dhSinglePass-stdDH-hkdf-sha384-scheme": 20,
+    "dhSinglePass-stdDH-hkdf-sha512-scheme": 21,
     hkdfWithSha256: 28, hkdfWithSha384: 29, hkdfWithSha512: 30, cekHkdfSha256: 31 } },
 
+  // RFC 5753 ephemeral-static ECDH key-agreement schemes -- the keyEncryptionAlgorithm OID of a
+  // kari, whose PARAMETER is the KeyWrapAlgorithm (so these are NOT params-absent). The X9.63 KDF
+  // variants: stdDH (SECG arc 1.3.132.1.11) + cofactorDH (1.3.132.1.14) for SHA-224/256/384/512,
+  // and the SHA-1 KDF pair on the ANSI-X9.63 arc (the OpenSSL default).
+  secgStdDH: { base: [1, 3, 132, 1, 11], of: {
+    "dhSinglePass-stdDH-sha224kdf-scheme": 0, "dhSinglePass-stdDH-sha256kdf-scheme": 1,
+    "dhSinglePass-stdDH-sha384kdf-scheme": 2, "dhSinglePass-stdDH-sha512kdf-scheme": 3 } },
+  secgCofactorDH: { base: [1, 3, 132, 1, 14], of: {
+    "dhSinglePass-cofactorDH-sha224kdf-scheme": 0, "dhSinglePass-cofactorDH-sha256kdf-scheme": 1,
+    "dhSinglePass-cofactorDH-sha384kdf-scheme": 2, "dhSinglePass-cofactorDH-sha512kdf-scheme": 3 } },
+  x963Schemes: { base: [1, 3, 133, 16, 840, 63, 0], of: {
+    "dhSinglePass-stdDH-sha1kdf-scheme": 2, "dhSinglePass-cofactorDH-sha1kdf-scheme": 3 } },
+
   // PKIX algorithms arc -- the stateful hash-based signature algorithm
   // identifiers (RFC 9802 sec. 4). HSS/LMS additionally has the SMIME
   // id-alg-hss-lms-hashsig OID above (RFC 9708 / RFC 9802 share it).

package/lib/schema-cms.js

@@ -1203,4 +1203,13 @@ module.exports = {
   walkSignedData: walkSignedData,
   walkEncryptedData: walkEncryptedData,
   assertAttachedCiphertext: assertAttachedCiphertext,
+  // The structure's own algorithm tables, exported (like the walk* helpers) as the single source
+  // of truth the crypto layer (cms-encrypt / cms-decrypt) shares -- so the wrap<->KEK-length, the
+  // ML-KEM ciphertext-length, and the AEAD-mode/ICV-length rules the parser enforces cannot drift
+  // from what the producer/consumer emit and accept.
+  WRAP_KEK_LENGTHS: WRAP_KEK_LENGTHS,
+  KEM_CT_LENGTHS: KEM_CT_LENGTHS,
+  AEAD_ALGS: AEAD_ALGS,
+  AEAD_GCM_ICVLENS: AEAD_GCM_ICVLENS,
+  AEAD_CCM_ICVLENS: AEAD_CCM_ICVLENS,
 };

package/lib/webcrypto.js

@@ -22,9 +22,9 @@
  *   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, 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).
+ *   FIPS 203 ML-KEM key generation, encoding, certificate/PKCS#8 import,
+ *   and encapsulation/decapsulation (encapsulateBits / decapsulateBits over
+ *   Node's crypto.encapsulate/decapsulate) are all available.
  *   Because it is OpenSSL-backed, every key and signature it emits is
  *   interoperable with OpenSSL, NSS, and other PKI implementations.
  *
@@ -83,6 +83,7 @@ function _normalizeAlg(algorithm, who) {
 // backwards compatibility with legacy certificates and signatures.
 var HASH_NODE = {
   "SHA-1":   "sha1",
+  "SHA-224": "sha224",
   "SHA-256": "sha256",
   "SHA-384": "sha384",
   "SHA-512": "sha512",
@@ -130,9 +131,8 @@ 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. 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.
+// same shape as ML-DSA / EdDSA. ML-KEM covers key-generation / encoding /
+// import plus encapsulateBits / decapsulateBits over Node's KEM primitive.
 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"
@@ -147,13 +147,13 @@ var SIGN_VERIFY_NAMES = {};
   .concat(Object.keys(ML_DSA_NODE), Object.keys(SLH_DSA_NODE))
   .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 };
+var DERIVE_NAMES = { "ECDH": true, "X25519": true, "X448": true, "HKDF": true, "PBKDF2": true, "X963KDF": 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 };
+var SECRET_KEY_NAMES = { "AES-GCM": true, "AES-CBC": true, "AES-CTR": true, "AES-KW": true, "HMAC": true, "HKDF": true, "PBKDF2": true, "X963KDF": true };
 
 // ---- CryptoKey -------------------------------------------------------
 
@@ -533,9 +533,29 @@ function _deriveBitsRaw(alg, key, length) {
     var out = nodeCrypto.pbkdf2Sync(_secretBytes(key), _toBuf(alg.salt, "PBKDF2 salt"), alg.iterations, length / 8, _hashNode(alg.hash, "PBKDF2"));
     return _toArrayBuffer(out);
   }
+  if (name === "X963KDF") {
+    // ANSI-X9.63 / SEC1 sec. 3.6.1 single-step KDF: K = H(Z || INT32(counter) || SharedInfo)
+    // concatenated over counter = 1, 2, ... The RFC 5753 kari KEK derivation; the base key holds
+    // the ECDH shared secret Z, alg.info holds the DER ECC-CMS-SharedInfo.
+    _requireDeriveLength(length, "X963KDF");
+    return _toArrayBuffer(_x963Kdf(_hashNode(alg.hash, "X963KDF"), _secretBytes(key), _toBuf(alg.info || Buffer.alloc(0), "X963KDF SharedInfo"), length / 8));
+  }
   throw new WebCryptoError("webcrypto/not-supported", "deriveBits: unsupported algorithm " + JSON.stringify(name));
 }
 
+// The X9.63 single-step KDF counter loop. Bounded by the 2^32 counter range; every input is a
+// public/agreed value, so a plain (non-constant-time) hash concat is correct.
+function _x963Kdf(hashNode, z, sharedInfo, lenBytes) {
+  var blocks = [], counter = 1, got = 0;
+  while (got < lenBytes) {
+    if (counter > 0xffffffff) throw new WebCryptoError("webcrypto/operation", "X963KDF: requested output exceeds the counter range");
+    var ctr = Buffer.alloc(4); ctr.writeUInt32BE(counter, 0);
+    var h = nodeCrypto.createHash(hashNode).update(z).update(ctr).update(sharedInfo).digest();
+    blocks.push(h); got += h.length; counter += 1;
+  }
+  return Buffer.concat(blocks).subarray(0, lenBytes);
+}
+
 SubtleCrypto.prototype.deriveBits = async function deriveBits(algorithm, key, length) {
   var alg = _normalizeAlg(algorithm, "deriveBits");
   _requireUsage(key, "deriveBits");
@@ -579,6 +599,41 @@ SubtleCrypto.prototype.deriveKey = async function deriveKey(algorithm, baseKey,
   return this.importKey("raw", raw, dk, extractable, keyUsages);
 };
 
+// ML-KEM (FIPS 203) key encapsulation over Node's crypto.encapsulate/decapsulate.
+// encapsulateBits takes the recipient's PUBLIC (encapsulation) key and returns a fresh
+// { sharedKey, ciphertext }; decapsulateBits takes the PRIVATE (decapsulation) key + a
+// ciphertext and recovers the shared key. ML-KEM's Fujisaki-Okamoto transform gives IMPLICIT
+// rejection: a tampered but correctly-sized ciphertext decapsulates to a pseudo-random shared
+// key rather than failing, so decapsulateBits only throws (typed) on a malformed / wrong-length
+// ciphertext -- the "wrong key" case is indistinguishable by design, which the CMS uniform
+// decrypt-failure verdict relies on. The usage split (encapsulateBits -> public, decapsulateBits
+// -> private) already lives in the generateKey usage filters; the explicit type check hardens a
+// key imported with custom usages.
+SubtleCrypto.prototype.encapsulateBits = async function encapsulateBits(algorithm, encapsulationKey) {
+  var alg = _normalizeAlg(algorithm, "encapsulateBits");
+  _requireUsage(encapsulationKey, "encapsulateBits");
+  if (!ML_KEM_NODE[alg.name]) throw new WebCryptoError("webcrypto/not-supported", "encapsulateBits: unsupported algorithm " + JSON.stringify(alg.name));
+  _requireAlgMatch(alg, encapsulationKey, "encapsulateBits");
+  if (encapsulationKey.type !== "public") throw new WebCryptoError("webcrypto/invalid-access", "encapsulateBits requires a public (encapsulation) key, got " + JSON.stringify(encapsulationKey.type));
+  var r;
+  try { r = nodeCrypto.encapsulate(encapsulationKey._handle); }
+  catch (e) { throw new WebCryptoError("webcrypto/operation", "encapsulateBits: ML-KEM encapsulation failed", e); }
+  return { sharedKey: _toArrayBuffer(Buffer.from(r.sharedKey)), ciphertext: _toArrayBuffer(Buffer.from(r.ciphertext)) };
+};
+
+SubtleCrypto.prototype.decapsulateBits = async function decapsulateBits(algorithm, decapsulationKey, ciphertext) {
+  var alg = _normalizeAlg(algorithm, "decapsulateBits");
+  _requireUsage(decapsulationKey, "decapsulateBits");
+  if (!ML_KEM_NODE[alg.name]) throw new WebCryptoError("webcrypto/not-supported", "decapsulateBits: unsupported algorithm " + JSON.stringify(alg.name));
+  _requireAlgMatch(alg, decapsulationKey, "decapsulateBits");
+  if (decapsulationKey.type !== "private") throw new WebCryptoError("webcrypto/invalid-access", "decapsulateBits requires a private (decapsulation) key, got " + JSON.stringify(decapsulationKey.type));
+  var ct = _toBuf(ciphertext, "decapsulateBits ciphertext");
+  var ss;
+  try { ss = nodeCrypto.decapsulate(decapsulationKey._handle, ct); }
+  catch (e) { throw new WebCryptoError("webcrypto/operation", "decapsulateBits: ML-KEM decapsulation failed (malformed or wrong-length ciphertext)", e); }
+  return _toArrayBuffer(Buffer.from(ss));
+};
+
 SubtleCrypto.prototype.wrapKey = async function wrapKey(format, key, wrappingKey, wrapAlgorithm) {
   var exported = await this.exportKey(format, key);
   var bytes = (format === "jwk") ? Buffer.from(JSON.stringify(exported)) : Buffer.from(exported);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "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:54db6dce-3101-401d-be5e-baa7f068783f",
+  "serialNumber": "urn:uuid:778bbc49-b521-4695-b1a1-915cda8b8012",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-16T03:51:39.360Z",
+    "timestamp": "2026-07-16T09:47:36.237Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.22",
+      "bom-ref": "@blamejs/pki@0.2.24",
       "type": "application",
       "name": "pki",
-      "version": "0.2.22",
+      "version": "0.2.24",
       "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.22",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.24",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.22",
+      "ref": "@blamejs/pki@0.2.24",
       "dependsOn": []
     }
   ]