@blamejs/pki 0.6.13 → 0.6.15

package/lib/composite-kem.js

@@ -19,15 +19,6 @@
  * @spec draft-ietf-lamps-pq-composite-kem
  * @card Establish a shared secret with a hybrid post-quantum plus traditional KEM.
  */
-//
-// ML-KEM runs on the toolkit's hardened WebCrypto surface (the FIPS 203 ciphertext-length check +
-// shared-secret zeroization ride along); the traditional component uses node:crypto directly, as the
-// sibling KEM module lib/hpke.js does, promoting RSA-OAEP into a KEM (a fresh random secret encrypted,
-// draft sec. 2.1) and ECDH / X25519 / X448 into a KEM (an ephemeral public key as the ciphertext,
-// draft sec. 2.2). The public key is mlkemEK || tradPK (sec. 4.1) in the SPKI BIT STRING; the private
-// key is mlkemSeed || tradSK (sec. 4.2, a 64-byte ML-KEM seed) in the PKCS#8 privateKey OCTET STRING;
-// the ciphertext is mlkemCT || tradCT (sec. 4.3). The ML-KEM component is the fixed-length first half,
-// and the split point is its parameter-set length.
 
 var asn1 = require("./asn1-der");
 var oid = require("./oid");
@@ -43,12 +34,6 @@ var KemError = frameworkError.KemError;
 var PemError = frameworkError.PemError;
 function _err(code, message, cause) { return new KemError(code, message, cause); }
 
-// Accept a composite key as DER (any BufferSource, snapshotted at the door) or as a PEM block with the
-// given label. A PEM decode fault is re-typed into the module's own KemError so the verb's documented
-// "throws a typed KemError" contract holds for every input shape. PEM is detected with the shared armor
-// check (so leading text before "-----BEGIN" is tolerated as elsewhere in the toolkit), and the byte
-// source is snapshot-COPIED first: the async verbs read the key across await points, so it must not alias
-// a caller buffer that can change underneath them (guard.bytes.source, which coerceToDer uses, aliases).
 function _toDer(input, pemLabel, what) {
   if (typeof input === "string") return _pemToDer(input, pemLabel);
   var buf = guard.bytes.snapshotSource(input, KemError, "kem/bad-input", what);
@@ -60,17 +45,6 @@ function _pemToDer(text, label) {
   catch (e) { throw _err("kem/bad-key", "the PEM input is not a valid " + label + " block", e); }
 }
 
-// ---- registry (draft sec. 6) -------------------------------------------------
-//
-// One row per composite algorithm, keyed by the composite OID. `trad` is exactly one component shape,
-// each carrying `ctLen`, the exact byte length of its traditional ciphertext component (RSA-OAEP block,
-// EC uncompressed point, or raw OKP ephemeral key), so the composite ciphertext length is fixed and an
-// oversized attacker-controlled component is refused before any key is built:
-//   { kind: "rsa", bits, ctLen }        RSA-OAEP-KEM, OAEP SHA-256 / MGF1-SHA256 / empty label (sec. 6.1)
-//   { kind: "ec",  node, curve, ctLen } ECDH DHKEM, `node` the node namedCurve, `curve` the curve OID name
-//   { kind: "okp", curve, ctLen }       X25519 / X448 DHKEM, `curve` the registered OID name
-// `label` is stored as the AUTHORITATIVE per-row bytes (draft sec. 6): most are ASCII, but the
-// id-MLKEM768-X25519 label is the raw six bytes 5c2e2f2f5e5c and MUST NOT be derived from the name.
 var COMPOSITE_KEM = {};
 function _comp(name, mlkemBits, label, trad) {
   var mlOidName = "id-ml-kem-" + mlkemBits;
@@ -93,14 +67,9 @@ _comp("id-MLKEM1024-ECDH-brainpoolP384r1-SHA3-256", 1024, Buffer.from("MLKEM1024
 _comp("id-MLKEM1024-X448-SHA3-256", 1024, Buffer.from("MLKEM1024-X448", "ascii"), { kind: "okp", curve: "X448", ctLen: 56 });
 _comp("id-MLKEM1024-ECDH-P521-SHA3-256", 1024, Buffer.from("MLKEM1024-P521", "ascii"), { kind: "ec", node: "secp521r1", curve: "secp521r1", ctLen: 133 });
 
-var MLKEM_SEED = 64;   // d || z, both 32 bytes (draft sec. 4.2)
-var RSA_SS = 32;       // ss_len for RSA-OAEP-KEM (draft sec. 6.1)
+var MLKEM_SEED = 64;
+var RSA_SS = 32;
 
-// ---- ML-KEM component (toolkit WebCrypto) ------------------------------------
-//
-// The private key is the 64-byte seed; node reconstructs the decapsulation key from a PKCS#8 whose
-// privateKey OCTET STRING wraps the seed as a context-[0] primitive (the OpenSSL / draft seed form),
-// not from node's own { seed } keygen option, whose seed convention differs.
 function _mlkemSeedPkcs8(d, seed) {
   return _b.sequence([
     _b.integer(0n),
@@ -115,33 +84,17 @@ function _mlkemEncaps(d, mlkemEK) {
   return subtle.importKey("spki", _mlkemSpki(d, mlkemEK), { name: d.mlkemWc }, false, ["encapsulateBits"])
     .then(function (k) { return subtle.encapsulateBits({ name: d.mlkemWc }, k); })
     .then(function (r) { return { ss: Buffer.from(r.sharedKey), ct: Buffer.from(r.ciphertext) }; })
-    // a malformed ML-KEM public-key half surfaces from the engine as a WebCryptoError; re-type it into
-    // the module's own KemError so the verb's typed-error contract holds. The chain runs only the
-    // WebCrypto component operations, which never raise a KemError, so the re-type is unconditional.
     .catch(function (e) { throw _err("kem/bad-key", "the ML-KEM component public key is invalid", e); });
 }
 function _mlkemDecaps(d, seed, mlkemCT) {
   return subtle.importKey("pkcs8", _mlkemSeedPkcs8(d, seed), { name: d.mlkemWc }, false, ["decapsulateBits"])
     .then(function (k) { return subtle.decapsulateBits({ name: d.mlkemWc }, k, mlkemCT); })
     .then(function (ss) { return Buffer.from(ss); })
-    // Defensive re-type mirroring _mlkemEncaps. Verified-unreachable from the shipped decapsulate path:
-    // the caller-checked split always supplies a valid 64-byte ML-KEM seed (any 64 bytes are a valid
-    // key) and an exact-parameter-set-length ML-KEM ciphertext, and ML-KEM decapsulation is implicitly
-    // rejecting, so neither the import nor the decapsulation of the ML-KEM half can fail here. Kept for
-    // node's experimental ML-KEM surface and for symmetry with the reachable encapsulate catch.
     .catch(function (e) { throw _err("kem/bad-key", "the ML-KEM component private key is invalid", e); });
 }
 
-// ---- traditional component (node:crypto, like lib/hpke.js) -------------------
-//
-// The traditional public key encodings mixed into the combiner (draft sec. 4.1 / Appendix B): RSA is
-// the RSAPublicKey DER, EC is the uncompressed X9.62 point, X25519 / X448 is the raw curve point.
 function _ecPubFromPoint(d, point) {
-  // draft Appendix B: the EC component is the uncompressed X9.62 point (0x04 || X || Y). node would
-  // silently decompress a 0x02/0x03 point, so a compressed or hybrid form is refused here as non-canonical;
-  // createPublicKey then validates the length and that the point is on the curve.
   if (point.length < 1 || point[0] !== 0x04) throw _err("kem/bad-key", "the EC component point is not in uncompressed form");
-  // SubjectPublicKeyInfo { AlgorithmIdentifier { ecPublicKey, namedCurve }, BIT STRING point }.
   var spki = _b.sequence([_b.sequence([_b.oid(oid.byName("ecPublicKey")), _b.oid(oid.byName(d.trad.curve))]), _b.bitString(point, 0)]);
   return nodeCrypto.createPublicKey({ key: spki, format: "der", type: "spki" });
 }
@@ -153,8 +106,6 @@ function _okpPrivFromRaw(d, raw) {
   var p8 = _b.sequence([_b.integer(0n), _b.sequence([_b.oid(oid.byName(d.trad.curve))]), _b.octetString(_b.octetString(raw))]);
   return nodeCrypto.createPrivateKey({ key: p8, format: "der", type: "pkcs8" });
 }
-// The subjectPublicKey octets of a public KeyObject (the uncompressed EC point / raw OKP key), read
-// off the SPKI export rather than a JWK export, which node cannot produce for the brainpool curves.
 function _rawPubOf(keyObject) {
   var spki = keyObject.export({ format: "der", type: "spki" });
   return Buffer.from(asn1.read.bitString(asn1.decode(spki).children[1]).bytes);
@@ -165,8 +116,6 @@ function _tradEncaps(d, tradPK) {
   if (trad.kind === "rsa") {
     var pub;
     try {
-      // node's createPublicKey ignores trailing bytes after the RSAPublicKey; decode strictly first so a
-      // composite key carrying extra bytes after the RSA component is refused (draft sec. 4.1: exact encoding).
       asn1.decode(tradPK);
       pub = nodeCrypto.createPublicKey({ key: tradPK, format: "der", type: "pkcs1" });
     } catch (e) { return Promise.reject(_err("kem/bad-key", "the RSA component public key is not a valid RSAPublicKey", e)); }
@@ -175,18 +124,11 @@ function _tradEncaps(d, tradPK) {
     var ct;
     try { ct = Buffer.from(nodeCrypto.publicEncrypt({ key: pub, padding: nodeCrypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: "sha256" }, ss)); }
     catch (e) {
-      // the random secret is already allocated; wipe it before rejecting if the RSA public operation fails
-      // (draft sec. 3.5). On success it is returned and wiped by the combiner.
       guard.secret.zeroize(ss, KemError, "kem/bad-input", "the RSA-OAEP component secret");
       return Promise.reject(_err("kem/bad-key", "the RSA-OAEP component encryption failed", e));
     }
     return Promise.resolve({ ss: ss, ct: ct });
   }
-  // DHKEM: an ephemeral keypair, the shared secret is DH(ephemeral, recipient), the ciphertext is the
-  // ephemeral public key in the component's own encoding (draft sec. 2.2). The Diffie-Hellman is inside
-  // the try: a structurally valid but low-order recipient point (e.g. an all-zero X25519 key) imports
-  // cleanly but makes node's diffieHellman throw, which must surface as a typed fault rather than a raw
-  // OpenSSL error escaping the encapsulation.
   var dh, dhCt;
   try {
     var recip = trad.kind === "ec" ? _ecPubFromPoint(d, tradPK) : _okpPubFromRaw(d, tradPK);
@@ -202,36 +144,25 @@ function _tradDecaps(d, tradSK, tradCT) {
   if (trad.kind === "rsa") {
     var priv;
     try {
-      // node's createPrivateKey ignores trailing bytes after the RSAPrivateKey; decode strictly first so a
-      // composite key carrying extra bytes after the RSA component is refused (draft sec. 4.2: exact encoding).
       asn1.decode(tradSK);
       priv = nodeCrypto.createPrivateKey({ key: tradSK, format: "der", type: "pkcs1" });
     } catch (e) { return Promise.reject(_err("kem/bad-key", "the RSA component private key is not a valid RSAPrivateKey", e)); }
     if (priv.asymmetricKeyDetails.modulusLength !== trad.bits) return Promise.reject(_err("kem/bad-key", "the RSA component modulus is not " + trad.bits + " bits (draft sec. 6)"));
     var ss;
-    // OAEP-invalid ciphertext and valid-padding-wrong-length plaintext MUST fail identically: a distinct
-    // verdict for either is an RSA-OAEP padding-validity oracle (Manger). Both reject with the same code
-    // and message AND no cause (the OpenSSL error is dropped, since it too would tell the paths apart), so
-    // the caller cannot tell the failure reason apart. draft sec. 2.1 fixes the transported secret at 32
-    // bytes; a plaintext of any other length is wiped and rejected here with that same verdict (sec. 3.5).
     try { ss = Buffer.from(nodeCrypto.privateDecrypt({ key: priv, padding: nodeCrypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: "sha256" }, tradCT)); }
     catch (_e) { return Promise.reject(_err("kem/decapsulation-failed", "the RSA-OAEP component decryption failed")); }
     if (ss.length !== RSA_SS) {
       guard.secret.zeroize(ss, KemError, "kem/bad-input", "the RSA-OAEP component secret");
       return Promise.reject(_err("kem/decapsulation-failed", "the RSA-OAEP component decryption failed"));
     }
-    // The combiner input tradPK is the RSAPublicKey DER (n, e), draft sec. 4.1, taken from the key object.
     return Promise.resolve({ ss: ss, tradPK: Buffer.from(nodeCrypto.createPublicKey(priv).export({ format: "der", type: "pkcs1" })) });
   }
   var priv2, eph;
   try {
     if (trad.kind === "ec") {
-      // node's SEC1 reader ignores trailing bytes after the ECPrivateKey; decode strictly first so a
-      // composite key carrying extra bytes after the EC component is refused (draft sec. 4.2, exact encoding).
       asn1.decode(tradSK);
       priv2 = nodeCrypto.createPrivateKey({ key: tradSK, format: "der", type: "sec1" });
     } else {
-      // the OKP private key is a fixed-length raw scalar; node rejects any wrong length, trailing included.
       priv2 = _okpPrivFromRaw(d, tradSK);
     }
     eph = trad.kind === "ec" ? _ecPubFromPoint(d, tradCT) : _okpPubFromRaw(d, tradCT);
@@ -242,23 +173,15 @@ function _tradDecaps(d, tradSK, tradCT) {
   return Promise.resolve({ ss: dh, tradPK: _rawPubOf(nodeCrypto.createPublicKey(priv2)) });
 }
 
-// ---- combiner (draft sec. 3.4) -----------------------------------------------
 function _combine(d, mlkemSS, tradSS, tradCT, tradPK) {
   var preimage = Buffer.concat([mlkemSS, tradSS, tradCT, tradPK, d.label]);
   return subtle.digest("SHA3-256", preimage).then(function (h) {
     return Buffer.from(h);
   }).finally(function () {
-    // draft sec. 3.5: clear the intermediate key material on every path, whether the digest resolves or
-    // fails. Only the returned composite secret survives. tradCT / tradPK are public, but the preimage
-    // holds copies of both component shared secrets, and mlkemSS / tradSS are the component secrets.
     guard.secret.zeroizeAll([preimage, mlkemSS, tradSS], KemError, "kem/bad-input", "a KEM combiner secret");
   });
 }
 
-// Run the two component operations; if EITHER rejects, wipe the shared secret the OTHER already produced
-// before re-throwing, so a component failure leaves no key material readable (draft sec. 3.5 -- clear all
-// buffers and forward the error). On success the combiner wipes both component secrets. `secA` / `secB`
-// extract the secret Buffer from each component's result.
 async function _settleOrWipe(pA, pB, secA, secB) {
   var s = await Promise.allSettled([pA, pB]);
   if (s[0].status === "rejected" || s[1].status === "rejected") {
@@ -269,25 +192,18 @@ async function _settleOrWipe(pA, pB, secA, secB) {
   return [s[0].value, s[1].value];
 }
 
-// ---- descriptor resolution ---------------------------------------------------
 function _descriptor(algOid) {
   var d = COMPOSITE_KEM[algOid];
   if (!d) throw _err("kem/unsupported-algorithm", "not a composite ML-KEM algorithm: " + (oid.name(algOid) || algOid));
   return d;
 }
-// Resolve the composite descriptor from an algorithm OID, enforcing the draft sec. 5.3 parameters-absent
-// rule. Both verbs feed the same (oid, hasParams) here so the dispatch and the parameters rule live once,
-// whether the AlgorithmIdentifier was read from a hand-decoded SPKI or a schema-parsed OneAsymmetricKey.
 function _descriptorForAlg(algOid, hasParams) {
   if (hasParams) throw _err("kem/bad-algorithm", "a composite ML-KEM AlgorithmIdentifier MUST have absent parameters (draft sec. 5.3)");
   return _descriptor(algOid);
 }
-// A DER node is a universal SEQUENCE (SubjectPublicKeyInfo and AlgorithmIdentifier are both SEQUENCE, not
-// SET or any other constructed tag): a SET carrying the same children is not a canonical encoding.
 function _isSequence(node) {
   return !!node && node.tagClass === "universal" && node.tagNumber === asn1.TAGS.SEQUENCE && !!node.children;
 }
-// Resolve the composite descriptor from a raw AlgorithmIdentifier node (the SPKI encapsulation path).
 function _fromAlgId(algNode) {
   if (!_isSequence(algNode) || algNode.children.length < 1) throw _err("kem/bad-algorithm", "the AlgorithmIdentifier is malformed");
   var algOid;
@@ -296,7 +212,6 @@ function _fromAlgId(algNode) {
   return _descriptorForAlg(algOid, algNode.children.length > 1);
 }
 
-// ---- public verbs ------------------------------------------------------------
 
 /**
  * @primitive pki.kem.decapsulate
@@ -320,33 +235,23 @@ function _fromAlgId(algNode) {
  *   // requires: ciphertext -- the composite KEM ciphertext received from the sender
  *   var secret = await pki.kem.decapsulate(privatePkcs8Der, ciphertext);   // 32-byte Buffer
  */
-// async so any synchronous fault (an argument that is not a BufferSource, a malformed DER structure)
-// leaves as a rejected promise rather than a synchronous throw, keeping the Promise-returning contract.
 async function _decapsulate(privateKey, ciphertext) {
   var pkcs8 = _toDer(privateKey, "PRIVATE KEY", "the composite ML-KEM private key");
   var ct = guard.bytes.snapshotSource(ciphertext, KemError, "kem/bad-input", "the composite ML-KEM ciphertext");
   var d, sk;
   try {
     try {
-      // Compose the shared strict OneAsymmetricKey parser so the version, the algorithm, and the optional
-      // [0]/[1] trailing fields are all validated once, rather than reading fixed positions and trusting
-      // the rest. The privateKey octets are the raw composite mlkemSeed || tradSK (draft sec. 4.2).
       var info = schemaPkcs8.parse(pkcs8);
       var alg = info.privateKeyAlgorithm;
       d = _descriptorForAlg(alg.oid, alg.parameters !== null);
       sk = Buffer.from(info.privateKey);
     } catch (e) {
       if (e instanceof KemError) throw e;
-      // the shared parser rejects a present `parameters` at the envelope; re-map it to the module's own
-      // parameters-absent verdict so both verbs report draft sec. 5.3 the same way.
       if (e && e.code === "pkcs8/bad-algorithm-parameters") throw _err("kem/bad-algorithm", "a composite ML-KEM AlgorithmIdentifier MUST have absent parameters (draft sec. 5.3)", e);
       throw _err("kem/bad-key", "the composite ML-KEM private key is not a well-formed OneAsymmetricKey", e);
     }
     try {
       if (sk.length <= MLKEM_SEED) throw _err("kem/bad-key", "the composite private key is shorter than the ML-KEM seed");
-      // the composite ciphertext is a fixed length (the ML-KEM ciphertext plus the exact traditional
-      // component); reject any other length before building a key, so an attacker-controlled oversized
-      // traditional component cannot force an unbounded allocation (CWE-770).
       if (ct.length !== d.mlkemCt + d.trad.ctLen) throw _err("kem/bad-ciphertext", "the composite ciphertext is not the expected " + (d.mlkemCt + d.trad.ctLen) + " bytes for " + d.name);
       var seed = sk.subarray(0, MLKEM_SEED), tradSK = sk.subarray(MLKEM_SEED);
       var mlkemCT = ct.subarray(0, d.mlkemCt), tradCT = ct.subarray(d.mlkemCt);
@@ -354,12 +259,9 @@ async function _decapsulate(privateKey, ciphertext) {
         function (v) { return v; }, function (v) { return v.ss; });
       return await _combine(d, r[0], r[1].ss, tradCT, r[1].tradPK);
     } finally {
-      // the reconstructed private-key copy (ML-KEM seed || traditional private key) is wiped on every path,
-      // including the length-validation exits above.
       guard.secret.zeroize(sk, KemError, "kem/bad-input", "the composite private key material");
     }
   } finally {
-    // the snapshotted PKCS#8 copy still holds the private-key octets; wipe it on every path (draft sec. 3.5).
     guard.secret.zeroize(pkcs8, KemError, "kem/bad-input", "the composite private key DER");
   }
 }
@@ -405,8 +307,6 @@ async function _encapsulate(publicKey) {
   return { sharedSecret: ss, ciphertext: Buffer.concat([r[0].ct, r[1].ct]) };
 }
 
-// Only the two verbs are public: this module IS the pki.kem namespace, so the internal registry stays
-// unexported to keep it off the operator surface and immutable from outside.
 module.exports = {
   encapsulate: _encapsulate,
   decapsulate: _decapsulate,

package/lib/composite-sig.js

@@ -1,26 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The composite ML-DSA signature engine
-// (draft-ietf-lamps-pq-composite-sigs for the construction; draft-ietf-lamps-cms-composite-sigs
-// binds it to CMS), shared by certification-path validation (X.509 composite certificates,
-// lib/path-validate.js) and CMS (composite SignerInfo, lib/cms-verify.js / lib/cms-sign.js).
-//
-// A composite signature pairs a post-quantum ML-DSA with a traditional RSA / ECDSA / EdDSA so the
-// signature stays trustworthy if EITHER primitive is later broken. The public key is the raw
-// concatenation mldsaPK || tradPK (sec. 4.1) in the SPKI BIT STRING; the signature is
-// mldsaSig || tradSig (sec. 4.3). Verification (sec. 2) reconstructs
-//   M' = Prefix || Label || len(ctx) || ctx || PH(M),
-// verifies the ML-DSA component over M' with ctx = the composite Label, verifies the traditional
-// component over M' under its own hash, and accepts if and only if both pass. Every component must
-// verify; there is no AND-to-OR downgrade. The ML-DSA component is the fixed-length first half, and
-// the split point is its length.
-//
-// Error-parameterized like the guard / validator families: each consumer passes its own typed
-// error CONSTRUCTOR `E` and its domain codes (path validation passes PathError + path/*; CMS
-// passes CmsError + cms/*), so the shared engine keeps no domain of its own. compositeVerify keeps
-// the { ok, code, error } verdict shape; the codes are caller-supplied.
+// @internal
 
 var asn1 = require("./asn1-der");
 var oid = require("./oid");
@@ -30,10 +11,6 @@ var edwardsPoint = require("./edwards-point");
 var subtle = webcrypto.webcrypto.subtle;
 var _b = asn1.build;
 
-// A caught error's own code if it shares the caller's domain prefix (the fallback's namespace,
-// e.g. path/ or cms/), else the fallback. A foreign code (asn1/*) maps to the fallback so the
-// verdict stays in the caller's error namespace. Mirrors path-validate's original pathCode when
-// the fallback is a path/* code.
 function _codeOf(e, fallback) {
   var prefix = fallback.slice(0, fallback.indexOf("/") + 1);
   return (e && typeof e.code === "string" && e.code.indexOf(prefix) === 0) ? e.code : fallback;
@@ -46,17 +23,8 @@ var MLDSA_COMPONENT = {
   "ML-DSA-87": { pk: 2592, sig: 4627, oid: "id-ml-dsa-87" },
 };
 var EC_CURVE_OID = { "P-256": "prime256v1", "P-384": "secp384r1", "P-521": "secp521r1" };
-// The WebCrypto pre-hash name (ph) -> the CMS digest-algorithm name (the SignerInfo digestAlgorithm,
-// draft-ietf-lamps-cms-composite-sigs Table 1). The SINGLE source of truth for the CMS binding's
-// digest -- both the verify coherence gate and the sign digestAlgorithm read phCms, never a second
-// name map inlined at the CMS boundary.
 var PH_CMS = { "SHA-256": "sha256", "SHA-512": "sha512", "SHAKE256": "shake256" };
 var COMPOSITE_ALGS = {};
-// _comp(name, mldsa, ph, label, trad). `trad` is exactly one component shape:
-//   { ec, hash } | { eddsa } | { rsaPss, hash, salt } | { rsaPkcs1, hash } |
-//   { unsupported } for the arms Node's WebCrypto surface cannot verify (the two
-//   brainpool curves): registered and params-guarded, deferred at verify to the
-//   caller's unsupported-algorithm code instead of silently accepted.
 function _comp(name, mldsa, ph, label, trad) {
   var sz = MLDSA_COMPONENT[mldsa];
   COMPOSITE_ALGS[oid.byName(name)] = {
@@ -83,24 +51,16 @@ _comp("id-MLDSA87-RSA3072-PSS-SHA512", "ML-DSA-87", "SHA-512", "COMPSIG-MLDSA87-
 _comp("id-MLDSA87-RSA4096-PSS-SHA512", "ML-DSA-87", "SHA-512", "COMPSIG-MLDSA87-RSA4096-PSS-SHA512", { rsaPss: true, hash: "SHA-384", salt: 48, rsaBits: 4096 });
 _comp("id-MLDSA87-ECDSA-P521-SHA512", "ML-DSA-87", "SHA-512", "COMPSIG-MLDSA87-ECDSA-P521-SHA512", { ec: "P-521", hash: "SHA-512" });
 
-// Wrap a raw component public key in the SPKI its WebCrypto import expects, so each half is
-// verified through the same import and verify seam the classical path uses (no second parallel
-// verify path). tradPK for RSA is the RSAPublicKey DER; for EC the uncompressed point; for EdDSA
-// the raw public key.
 function _spkiFor(algNode, keyBytes) { return _b.sequence([algNode, _b.bitString(keyBytes, 0)]); }
 function _mldsaSpki(mldsaOid, raw) { return _spkiFor(_b.sequence([_b.oid(oid.byName(mldsaOid))]), raw); }
 function _ecSpki(curve, point) { return _spkiFor(_b.sequence([_b.oid(oid.byName("ecPublicKey")), _b.oid(oid.byName(EC_CURVE_OID[curve]))]), point); }
 function _edSpki(name, raw) { return _spkiFor(_b.sequence([_b.oid(oid.byName(name))]), raw); }
 function _rsaSpki(rsaPub) { return _spkiFor(_b.sequence([_b.oid(oid.byName("rsaEncryption")), _b.nullValue()]), rsaPub); }
 
-// The exact modulus bit length of an RSAPublicKey (SEQUENCE { modulus, exponent }).
 function _rsaModulusBits(rsaPubDer) {
   return asn1.read.integer(asn1.decode(rsaPubDer).children[0]).toString(2).length;
 }
 
-// M' = Prefix || Label || len(ctx) || ctx || PH(M) (draft sec. 2 / RFC 8410-style domain
-// separation). ctx is a single-octet-length-prefixed application context; X.509 path validation
-// and CMS both use the empty context. Shared by verify AND sign so the two cannot diverge.
 function compositeMprime(d, phBuf, ctx) {
   ctx = ctx || Buffer.alloc(0);
   return Buffer.concat([COMPOSITE_PREFIX, d.label, Buffer.from([ctx.length]), ctx, Buffer.from(phBuf)]);
@@ -108,22 +68,13 @@ function compositeMprime(d, phBuf, ctx) {
 
 function _verifyTradComponent(trad, tradPK, tradSig, mprime, E, badSig) {
   if (trad.ec) {
-    // draft sec. 5.1: the EC point MUST be the uncompressed X9.62 form (leading 0x04).
-    // A compressed / hybrid point is a non-conforming composite component encoding.
     if (tradPK.length < 1 || tradPK[0] !== 0x04) return Promise.resolve(false);
     return subtle.importKey("spki", _ecSpki(trad.ec, tradPK), { name: "ECDSA" }, false, ["verify"]).then(function (k) {
-      // The traditional ECDSA signature is DER Ecdsa-Sig-Value; convert to P1363 through the shared
-      // order-aware reader that also rejects r/s outside [1,n-1] (CVE-2022-21449).
       var p1363 = validator.sig.ecdsaDerToP1363(tradSig, trad.ec, E, badSig);
       return subtle.verify({ name: "ECDSA", hash: trad.hash }, k, p1363, mprime);
     });
   }
   if (trad.eddsa) {
-    // node/OpenSSL imports any Ed25519/Ed448 SPKI without validating the point, and a low-order
-    // (e.g. all-zeroes) key verifies a forged signature, collapsing the composite conjunction to
-    // ML-DSA alone. Reject a non-full-order point before verify, through the same shared
-    // edwards-point gate every other EdDSA verify path in the toolkit routes through, surfacing a
-    // coded fault (like the ECDSA order-bound belt) instead of a silent false.
     if (!edwardsPoint.validate(tradPK, trad.eddsa === "Ed25519" ? 6 : 7)) {
       throw new E(badSig, "the composite EdDSA component public key is not a valid, full-order Edwards point");
     }
@@ -131,10 +82,6 @@ function _verifyTradComponent(trad, tradPK, tradSig, mprime, E, badSig) {
       .then(function (k) { return subtle.verify({ name: trad.eddsa }, k, tradSig, mprime); });
   }
   if (trad.rsaPss || trad.rsaPkcs1) {
-    // The composite OID fixes the RSA modulus size: a downgraded or mismatched modulus under the
-    // declared OID (an id-MLDSA44-RSA2048-* whose component is really 1024-bit) is rejected before
-    // verify, so a weak RSA component cannot satisfy an arm that promises 2048/3072/4096 bits. A
-    // malformed RSAPublicKey rejects the same way.
     var bits;
     try { bits = _rsaModulusBits(tradPK); }
     catch (_e) { return Promise.resolve(false); }
@@ -146,14 +93,9 @@ function _verifyTradComponent(trad, tradPK, tradSig, mprime, E, badSig) {
     return subtle.importKey("spki", _rsaSpki(tradPK), { name: "RSASSA-PKCS1-v1_5", hash: trad.hash }, false, ["verify"])
       .then(function (k) { return subtle.verify({ name: "RSASSA-PKCS1-v1_5" }, k, tradSig, mprime); });
   }
-  // Coverage residual -- unreachable: compositeVerify returns early for a trad.unsupported arm, so
-  // _verifyTradComponent runs only for arms that set exactly one of ec/eddsa/rsaPss/rsaPkcs1.
   return Promise.resolve(false);
 }
 
-// Verify a composite signature: `spkiBytes` the issuer SPKI DER, `sigBytes` the raw signatureValue
-// (mldsaSig || tradSig), `message` the signed region. `E` the caller's error constructor;
-// `unsupported`/`badSig` its domain codes. Returns { ok, code?, error? } (a false is a verdict).
 function compositeVerify(spkiBytes, sigBytes, message, d, E, unsupported, badSig) {
   if (d.trad.unsupported) {
     return Promise.resolve({ ok: false, code: unsupported,
@@ -162,13 +104,9 @@ function compositeVerify(spkiBytes, sigBytes, message, d, E, unsupported, badSig
   var rawKey;
   try {
     var bs = asn1.read.bitString(asn1.decode(spkiBytes).children[1]);
-    // The composite subjectPublicKey is an octet-aligned concatenation (no unused bits); a non-zero
-    // unused-bit count is malformed.
     if (bs.unusedBits !== 0) throw new E(badSig, "composite subjectPublicKey has unused bits");
     rawKey = bs.bytes;
   } catch (e) { return Promise.resolve({ ok: false, code: _codeOf(e, badSig), error: e }); }
-  // The ML-DSA half is fixed-length and comes first; the traditional half is the remainder. Both must be
-  // non-empty for a well-formed composite.
   if (rawKey.length <= d.mldsaPk || sigBytes.length <= d.mldsaSig) {
     return Promise.resolve({ ok: false, code: badSig,
       error: new E(badSig, "composite key/signature shorter than the fixed ML-DSA component") });
@@ -184,27 +122,15 @@ function compositeVerify(spkiBytes, sigBytes, message, d, E, unsupported, badSig
   }).catch(function (e) { return { ok: false, code: _codeOf(e, badSig), error: e }; });
 }
 
-// Resolve the composite descriptor for a signatureAlgorithm, or null if the OID is not composite.
-// A composite OID MUST carry absent parameters (draft-ietf-lamps-pq-composite-sigs sec. 5.3); the
-// public-key algorithm OID equals the signature OID, so the caller enforces sameKeyOid.
 function resolveCompositeDescriptor(sigAlg, E, unsupported) {
   var comp = COMPOSITE_ALGS[sigAlg.oid];
   if (!comp) return null;
-  // Coverage residual -- unreachable through the shipped consumer: the only caller (path-validate)
-  // reaches here with a sigAlg from a parsed structure whose shared AlgorithmIdentifier decoder
-  // already rejects a composite OID carrying parameters (the _PARAMS_ABSENT gate), so `parameters`
-  // is always absent here. Kept as defense-in-depth. (CMS does its own inline params check.)
   if (sigAlg.parameters !== null && sigAlg.parameters !== undefined) {
     throw new E(unsupported, "composite signature algorithm parameters must be absent (draft-ietf-lamps-pq-composite-sigs sec. 5.3)");
   }
   return { composite: comp, sameKeyOid: true };
 }
 
-// Sign a composite signature over `message`: `keys` = { mldsa, trad } component private keys as
-// PKCS#8 DER (Node has no composite private-key type). Signs the ML-DSA half over M' with ctx =
-// the composite Label (the same domain-separated preimage compositeVerify reconstructs), signs the
-// traditional half over M', and returns mldsaSig || tradSig. The caller rejects an unsupported arm
-// before calling (d.trad.unsupported).
 function compositeSign(d, keys, message, ctx) {
   return subtle.digest({ name: d.ph }, message).then(function (phBuf) {
     var mprime = compositeMprime(d, phBuf, ctx);
@@ -218,8 +144,6 @@ function _signTradComponent(trad, pkcs8, mprime) {
   if (trad.ec) {
     return subtle.importKey("pkcs8", pkcs8, { name: "ECDSA", namedCurve: trad.ec }, false, ["sign"])
       .then(function (k) { return subtle.sign({ name: "ECDSA", hash: trad.hash }, k, mprime); })
-      // WebCrypto emits P1363 r||s; the composite trad-ECDSA signature is DER Ecdsa-Sig-Value, so
-      // re-encode through the shared canonical-DER gate (the inverse of the verify path's read).
       .then(function (raw) { var r = Buffer.from(raw); return validator.sig.rawToEcdsaDer(r, r.length / 2); });
   }
   if (trad.eddsa) {