@blamejs/pki 0.6.13 → 0.6.15

package/lib/shbs.js

@@ -30,30 +30,19 @@ var constants = require("./constants");
 var ShbsError = frameworkError.ShbsError;
 function _err(code, message, cause) { return new ShbsError(code, message, cause); }
 
-// ---- big-endian serialization (RFC 8554 sec. 3.1: network byte order) --------
 
 function u8(x) { return Buffer.from([x & 0xff]); }
 function u16(x) { return Buffer.from([(x >> 8) & 0xff, x & 0xff]); }
 function u32(x) { return Buffer.from([(x >>> 24) & 0xff, (x >>> 16) & 0xff, (x >>> 8) & 0xff, x & 0xff]); }
 
-// Domain separators (RFC 8554 sec. 7.1). All exceed 264 (the max Winternitz
-// digit index i) so a security-string D can never collide with a chain-hash i,
-// which occupies the same 2-byte offset (sec. 9.1).
-var D_PBLC = 0x8080;   // LM-OTS public-key finalize
-var D_MESG = 0x8181;   // message hash
-var D_LEAF = 0x8282;   // LMS leaf hash
-var D_INTR = 0x8383;   // LMS interior node hash
+var D_PBLC = 0x8080;
+var D_MESG = 0x8181;
+var D_LEAF = 0x8282;
+var D_INTR = 0x8383;
 
-// ---- typecode registry (IANA Leighton-Micali Signatures; NIST SP 800-208) ----
-// LMS   0x05..0x18 : {m, h, hashFamily}. LM-OTS 0x01..0x10 : {n, w, hashFamily}.
-// p and ls are DERIVED from (n, w) per RFC 8554 sec. 4.1 / Appendix B so the
-// table stays data, not a switch, and a wrong hardcoded p cannot creep in.
 
 function _ilog2(x) { var r = 0; while (x > 1) { x = Math.floor(x / 2); r += 1; } return r; }
 
-// RFC 8554 Appendix B: u = ceil(8n/w) hash digits; v = the checksum digit count;
-// p = u + v total Winternitz digits; ls = the left-shift aligning the checksum's
-// significant bits into the digit positions coef reads.
 function _deriveWinternitz(n, w) {
   var u = Math.ceil((8 * n) / w);
   var v = Math.ceil((_ilog2((Math.pow(2, w) - 1) * u) + 1) / w);
@@ -63,16 +52,12 @@ function _deriveWinternitz(n, w) {
 var LMS_SETS = {};
 var LMOTS_SETS = {};
 (function seed() {
-  var heights = [5, 10, 15, 20, 25];   // H5..H25 in typecode order
-  var ws = [1, 2, 4, 8];               // W1..W8 in typecode order
-  // LMS families in IANA order: SHA-256/M32 (0x05), SHA-256/M24 (0x0A),
-  // SHAKE/M32 (0x0F), SHAKE/M24 (0x14).
+  var heights = [5, 10, 15, 20, 25];
+  var ws = [1, 2, 4, 8];
   [{ base: 0x05, m: 32, f: "sha256" }, { base: 0x0A, m: 24, f: "sha256" },
    { base: 0x0F, m: 32, f: "shake256" }, { base: 0x14, m: 24, f: "shake256" }].forEach(function (fam) {
     heights.forEach(function (h, i) { LMS_SETS[fam.base + i] = { code: fam.base + i, m: fam.m, h: h, hashFamily: fam.f }; });
   });
-  // LM-OTS families: SHA-256/N32 (0x01), SHA-256/N24 (0x05), SHAKE/N32 (0x09),
-  // SHAKE/N24 (0x0D).
   [{ base: 0x01, n: 32, f: "sha256" }, { base: 0x05, n: 24, f: "sha256" },
    { base: 0x09, n: 32, f: "shake256" }, { base: 0x0D, n: 24, f: "shake256" }].forEach(function (fam) {
     ws.forEach(function (w, i) {
@@ -93,8 +78,6 @@ function _lmotsSet(code) {
   return s;
 }
 
-// hashFamily + output length -> the n-byte hash of the concatenated inputs.
-// SHA-256 truncated to n (n=24 is SHA-256/192); SHAKE256 with an n-byte output.
 function _hash(family, n, parts) {
   var h;
   if (family === "shake256") h = nodeCrypto.createHash("shake256", { outputLength: n });
@@ -104,9 +87,6 @@ function _hash(family, n, parts) {
   return (family === "shake256" || n === 32) ? d : d.subarray(0, n);
 }
 
-// ---- bounded big-endian reader (bounds-before-slice; the ct.js TlsReader model
-// for a non-DER positional wire, kept shbs-local because shbs needs u32 typecodes
-// and fixed-n reads, not CT's length-prefixed vector helpers) ----------------
 
 function Reader(buf, code, label) { this.buf = buf; this.pos = 0; this.code = code; this.label = label; }
 Reader.prototype._need = function (k) {
@@ -119,10 +99,7 @@ Reader.prototype.take = function (k) { this._need(k); var b = this.buf.subarray(
 Reader.prototype.remaining = function () { return this.buf.length - this.pos; };
 Reader.prototype.atEnd = function () { return this.pos === this.buf.length; };
 
-// ---- Winternitz digit + checksum (RFC 8554 sec. 3.1.3 / sec. 4.4) ------------
 
-// coef(S, i, w): the i-th w-bit digit of S, big-endian WITHIN each byte (digit 0
-// is the high-order w bits of byte 0). RFC 8554 sec. 3.1.3.
 function _coef(S, i, w) {
   var idx = Math.floor((i * w) / 8);
   if (idx >= S.length) throw _err("shbs/bad-signature", "Winternitz coefficient index out of range");
@@ -130,9 +107,6 @@ function _coef(S, i, w) {
   return ((1 << w) - 1) & (S[idx] >> shift);
 }
 
-// Cksm(Q) per RFC 8554 sec. 4.4: sum over the u message digits of (2^w-1 - digit),
-// left-shifted by ls, as a 2-byte big-endian value. Computed over Q ALONE; the
-// coefficient index space in the chain walk spans Q || Cksm(Q).
 function _cksm(Q, set) {
   var w = set.w, sum = 0, u = Math.ceil((8 * set.n) / w);
   for (var i = 0; i < u; i++) sum += ((1 << w) - 1) - _coef(Q, i, w);
@@ -140,9 +114,6 @@ function _cksm(Q, set) {
   return u16(sum);
 }
 
-// ---- LM-OTS public-key candidate Kc (RFC 8554 Algorithm 4b) ------------------
-// I, q identify the LMS leaf; otsSet is resolved from the PUBLIC KEY's otstype
-// (the authority); C + y[] come from the signature. Returns the n-byte Kc.
 
 function _lmotsKc(otsSet, I, q, C, y, message) {
   var n = otsSet.n, w = otsSet.w, p = otsSet.p, f = otsSet.hashFamily;
@@ -153,21 +124,14 @@ function _lmotsKc(otsSet, I, q, C, y, message) {
   for (var i = 0; i < p; i++) {
     var a = _coef(Qc, i, w);
     var tmp = y[i];
-    // Chain to 2^w - 1 total applications; the bound is EXCLUSIVE (last j = 2^w-2),
-    // matching key generation (RFC 8554 sec. 4.5 vs Algorithm 4b step 3).
     for (var j = a; j < (1 << w) - 1; j++) tmp = _hash(f, n, [I, qb, u16(i), u8(j), tmp]);
     z.push(tmp);
   }
   return _hash(f, n, z);
 }
 
-// ---- LMS verification core (RFC 8554 Algorithm 6 / 6a) -----------------------
-// pubBytes = lmstype(4) || otstype(4) || I(16) || T[1](m); sigBytes an LMS
-// signature. Returns true iff the recomputed Merkle root equals T[1]. Throws
-// ShbsError on any structural fault; a well-formed-but-wrong signature -> false.
 
 function _lmsVerify(pubBytes, message, sigBytes) {
-  // -- public key (the authority for both typecodes; RFC 8554 Algorithm 6) --
   if (pubBytes.length < 8) throw _err("shbs/bad-public-key", "LMS public key is shorter than 8 bytes");
   var pr = new Reader(pubBytes, "shbs/bad-public-key", "LMS public key");
   var lmsSet = _lmsSet(pr.u32());
@@ -177,81 +141,46 @@ function _lmsVerify(pubBytes, message, sigBytes) {
   var I = pr.take(16);
   var T1 = pr.take(m);
 
-  // -- signature (RFC 8554 Algorithm 6a). q first, then the LM-OTS signature,
-  //    then the LMS typecode (after the LM-OTS sig), then the auth path. --
   if (sigBytes.length < 8) throw _err("shbs/bad-signature", "LMS signature is shorter than 8 bytes");
   var sr = new Reader(sigBytes, "shbs/bad-signature", "LMS signature");
   var q = sr.u32();
   var otsSigType = sr.u32();
-  // The public key -- never the attacker-controlled signature -- is the authority
-  // (downgrade defense): a signature whose OTS typecode does not equal the one the
-  // public key commits to cannot verify against it. RFC 8554 Algorithm 6a checks
-  // the typecode (step 2c, and 2g for the LMS type below) before the length (steps
-  // 2d / 2i), and returns INVALID, a verification failure (false) and not a
-  // structural error. So a mismatch is `false` at this point even for a blob too
-  // short to be a complete signature: the mismatch is decidable once q + typecode
-  // are read (the bounded reader already threw if those 8 bytes are absent). A
-  // matching typecode with a truncated body still throws below (bounds-before-
-  // slice). Re-sizing the body by the signature's own mismatched typecode, so as to
-  // "fully validate before returning false", would violate this order and reject
-  // a legitimate typecode-mutation test vector as malformed instead of INVALID.
   if (otsSigType !== otsSet.code) return false;
   var n = otsSet.n, p = otsSet.p;
   var C = sr.take(n);
   var y = [];
   for (var yi = 0; yi < p; yi++) y.push(sr.take(n));
   var sigLmsType = sr.u32();
-  if (sigLmsType !== lmsSet.code) return false;   // RFC 8554 Algorithm 6a step 2g -> INVALID
+  if (sigLmsType !== lmsSet.code) return false;
   var path = [];
   for (var pi = 0; pi < h; pi++) path.push(sr.take(m));
   if (!sr.atEnd()) throw _err("shbs/bad-signature", "LMS signature has " + sr.remaining() + " trailing byte(s)");
-  // RFC 8554 Algorithm 6a step 2i: a leaf index q >= 2^h is INVALID, a
-  // verification failure (false) and not a structural error. Checked here, after
-  // the exact-length validation above (a truncated or trailing blob already threw
-  // typed), against the registry height and never the blob. 2^h fits Number (h<=25).
   if (q >= Math.pow(2, h)) return false;
 
-  // -- recompute the LM-OTS public-key candidate, then fold the Merkle path --
   var Kc = _lmotsKc(otsSet, I, q, C, y, message);
   var nodeNum = Math.pow(2, h) + q;
   var tmp = _hash(lmsSet.hashFamily, m, [I, u32(nodeNum), u16(D_LEAF), Kc]);
   for (var i2 = 0; nodeNum > 1; i2++) {
     var parent = Math.floor(nodeNum / 2);
     if (nodeNum % 2 === 1) {
-      // odd node_num: the current node is a RIGHT child, sibling on the LEFT.
       tmp = _hash(lmsSet.hashFamily, m, [I, u32(parent), u16(D_INTR), path[i2], tmp]);
     } else {
       tmp = _hash(lmsSet.hashFamily, m, [I, u32(parent), u16(D_INTR), tmp, path[i2]]);
     }
     nodeNum = parent;
   }
-  // The root comparison is over PUBLIC values (T1 is in the public key, tmp is
-  // derived from public inputs -- no secret, hence the module's "no side-channel
-  // surface" note), so constant time is not strictly required. It routes through
-  // the shared crypto guard anyway, for one length-checked comparison primitive
-  // across the hash-tree verifiers (pki.merkle folds its root the same way).
   return guard.crypto.constantTimeEqual(tmp, T1);
 }
 
-// Consume exactly one LMS public key from a reader (an HSS inner key), returning
-// its raw bytes; sized off the LMS typecode it leads with.
 function _consumeLmsPublicKey(r) {
   var start = r.pos;
-  var code = r.u32();       // lmstype
-  r.u32();                  // otstype (validated when the key is verified)
+  var code = r.u32();
+  r.u32();
   var m = _lmsSet(code).m;
-  r.take(16 + m);           // I || T[1]
+  r.take(16 + m);
   return r.buf.subarray(start, r.pos);
 }
 
-// The exact byte length (12 + n*(p+1) + m*h) of an LMS signature verified under
-// `keyBytes` -- the AUTHORITATIVE public key for its level. The concatenated HSS
-// blob is split by the public key's typecodes, never the attacker-controlled
-// signature's own: so a typecode-mutated signature is sliced to the length the
-// key expects and then _lmsVerify returns false (a verification failure, RFC 8554
-// Algorithm 6a 2c/2g), consistent with verifyLms, instead of throwing on a
-// mis-sized slice. Bounds-guarded (no direct read that could escape as a raw
-// RangeError on a truncated inner key).
 function _lmsSigLen(keyBytes) {
   if (keyBytes.length < 8) throw _err("shbs/bad-public-key", "LMS public key is shorter than 8 bytes");
   var lmsSet = _lmsSet(keyBytes.readUInt32BE(0));
@@ -259,41 +188,28 @@ function _lmsSigLen(keyBytes) {
   return 12 + otsSet.n * (otsSet.p + 1) + lmsSet.m * lmsSet.h;
 }
 
-// ---- HSS verification (RFC 8554 sec. 6.3) ------------------------------------
 
 function _hssVerify(pubBytes, message, sigBytes) {
   if (pubBytes.length < 4) throw _err("shbs/bad-public-key", "HSS public key is shorter than 4 bytes");
   var pr = new Reader(pubBytes, "shbs/bad-public-key", "HSS public key");
   var L = pr.u32();
   if (L < 1 || L > constants.LIMITS.HSS_MAX_LEVELS) throw _err("shbs/bad-public-key", "HSS level count L=" + L + " is outside 1.." + constants.LIMITS.HSS_MAX_LEVELS);
-  var topKey = pr.buf.subarray(pr.pos);   // the top-level LMS public key -- its
-  // structure (including an under-length blob) is validated by _lmsVerify below
-  // (the < 8 and exact-24+m checks), so no direct read here that would bypass the
-  // bounded reader and escape as a raw RangeError on a truncated key.
+  var topKey = pr.buf.subarray(pr.pos);
 
   var sr = new Reader(sigBytes, "shbs/bad-signature", "HSS signature");
   var Nspk = sr.u32();
-  // The level-count gate, checked before parsing any component (RFC 8554 sec. 6.3).
   if (Nspk + 1 !== L) throw _err("shbs/bad-signature", "HSS Nspk+1 (" + (Nspk + 1) + ") does not equal the public-key level count L (" + L + ")");
 
   var key = topKey;
   for (var i = 0; i < Nspk; i++) {
-    // Slice this level's LMS signature by the AUTHORITATIVE key's length (so a
-    // typecode mismatch is a false verdict via _lmsVerify, not a mis-sized throw).
     var sig = sr.take(_lmsSigLen(key));
     var nextKey = _consumeLmsPublicKey(sr);
-    // Each level signs the SERIALIZED next-level LMS public key; that recovered
-    // key becomes the verification key for the level below (chain of trust).
     if (!_lmsVerify(key, nextKey, sig)) return false;
     key = nextKey;
   }
-  // The final signature is the remainder; _lmsVerify parses it, applies the
-  // public-key-authoritative typecode check (mismatch -> false), and rejects a
-  // trailing / truncated remainder (bounds-before-slice + its own atEnd check).
   return _lmsVerify(key, message, sr.buf.subarray(sr.pos));
 }
 
-// ---- public surface ----------------------------------------------------------
 
 function _asBytes(x, label) { return guard.bytes.source(x, ShbsError, "shbs/bad-input", label); }
 

package/lib/sign-scheme.js

@@ -1,20 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) blamejs contributors
 "use strict";
-//
-// @internal -- no operator-facing namespace. The signature-scheme resolver + signer shared by
-// every producer that signs a raw preimage with a certificate's key: pki.cms.sign (SignerInfo),
-// pki.ocsp.sign (BasicOCSPResponse), and future X.509 / CRL issuance. It owns the single key ->
-// { signatureAlgorithm, WebCrypto import/sign params } dispatch across the whole algorithm set
-// (RSA-PKCS1 / RSA-PSS / ECDSA P-256/384/521 / Ed25519 / Ed448 / ML-DSA / SLH-DSA / composite
-// ML-DSA), so a new signer surface inherits the full registry, PQC included, instead of
-// re-deriving a partial, drifting copy (Hard rule #2: registry not switch; and no second signer).
-//
-// Error-parameterized like the guard / validator families: the caller passes its typed error
-// factory `E(kind, message, cause)` where kind is "bad-input" | "unsupported-algorithm", so every
-// domain keeps its own code (cms/bad-input vs ocsp/bad-input). The digest choice (a CMS
-// digestAlgorithm concern) is surfaced as `scheme.digest`; the caller that has a digestAlgorithm
-// field (CMS) builds it, the caller that signs raw bytes (OCSP) ignores it.
+// @internal
 
 var asn1 = require("./asn1-der");
 var oid = require("./oid");
@@ -28,10 +15,6 @@ var compositeSig = require("./composite-sig");
 var b = asn1.build;
 function O(name) { return oid.byName(name); }
 
-// Captured at load. This module decides which algorithm a signature runs under and whether the
-// caller's key matches the certificate it claims, so an operation read at call time is one the
-// caller answers: a replaced case fold reports two different algorithm names equal, and a replaced
-// `Buffer.isBuffer` admits a key that is not bytes.
 var _BigInt = intrinsic.BigInt;
 var _String = intrinsic.String;
 var _filter = intrinsic.filter;
@@ -39,19 +22,12 @@ var _stringify = intrinsic.stringify;
 var _toUpperCase = intrinsic.toUpperCase;
 var _isBuffer = intrinsic.isBuffer;
 var _bufferFrom = intrinsic.bufferFrom;
-// Asks the value's internal slot rather than `instanceof`, which reads the `Uint8Array` global at
-// call time and answers about whichever constructor is bound then. It also settles the two cases
-// `instanceof` gets wrong on their own terms: a real typed array from another realm is one, and an
-// object merely built on the prototype is not.
 var _isU8 = intrinsic.types.isUint8Array;
 
 var HASH = { sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
 var NODE_DIGEST = { sha256: "sha256", sha384: "sha384", sha512: "sha512", shake128: "shake128", shake256: "shake256" };
 var PSS_SALT = { "SHA-256": 32, "SHA-384": 48, "SHA-512": 64 };
 var ECDSA_ALG = { sha256: "ecdsaWithSHA256", sha384: "ecdsaWithSHA384", sha512: "ecdsaWithSHA512" };
-// RSA-PKCS1 signatures fold the digest into a combined signature OID when there is no separate
-// digestAlgorithm field to carry it (X.509 / CRL / OCSP; RFC 5280 sec. 4.1.1.2, RFC 6960). CMS
-// SignerInfo has that field, so it signs under the bare rsaEncryption key OID instead.
 var RSA_PKCS1_SIG = { sha256: "sha256WithRSAEncryption", sha384: "sha384WithRSAEncryption", sha512: "sha512WithRSAEncryption" };
 var HASH_NAME_BY_OID = {};
 HASH_NAME_BY_OID[O("sha256")] = "sha256";
@@ -70,14 +46,7 @@ var MLDSA_SUITABLE_DIGEST = {
   "ML-DSA-65": { sha384: 1, sha512: 1, shake256: 1 },
   "ML-DSA-87": { sha512: 1, shake256: 1 },
 };
-// mldsaDigestSuitable(mlName, md) -- is `md` listed as meeting `mlName`'s security strength?
-// Both levels are asked for their OWN entries. The gate rejects on a falsy lookup, so a digest name
-// planted on Object.prototype answers for every name the row omits and a below-strength digest
-// passes the RFC 9882 sec. 3.3 check. This is the single home for that question: the signer and the
-// verifier both ask it, and a copy at either would let the two drift.
 // @enforced-by behavioral -- an own-property table read has no rename-proof shape distinct from a
-//   legitimate one; the RED vectors (a below-strength digest still refused with its name planted on
-//   Object.prototype, on both the sign and verify paths) are the guard.
 function mldsaDigestSuitable(mlName, md) {
   if (!intrinsic.hasOwn(MLDSA_SUITABLE_DIGEST, mlName)) return false;
   var row = MLDSA_SUITABLE_DIGEST[mlName];
@@ -90,29 +59,13 @@ var SLHDSA_BY_OID = {};
  ["shake-192s", "shake256"], ["shake-192f", "shake256"], ["shake-256s", "shake256"], ["shake-256f", "shake256"]
 ].forEach(function (r) { SLHDSA_BY_OID[O("id-slh-dsa-" + r[0])] = { wc: "SLH-DSA-" + r[0].toUpperCase(), digest: r[1] }; });
 
-// An AlgorithmIdentifier { OID } (absent parameters) or { OID, NULL }.
 function _algId(name, shape) { return shape === "null" ? b.sequence([b.oid(O(name)), b.nullValue()]) : b.sequence([b.oid(O(name))]); }
-// The RSASSA-PSS AlgorithmIdentifier: explicit SHA-2 hash, MGF1 keyed to it, hash-length salt,
-// default trailerField omitted (RFC 4055).
 function _pssAlgId(digestName) {
   var hashAlg = b.sequence([b.oid(O(digestName)), b.nullValue()]);
   var mgf = b.sequence([b.oid(O("mgf1")), hashAlg]);
   var params = b.sequence([b.explicit(0, hashAlg), b.explicit(1, mgf), b.explicit(2, b.integer(_BigInt(PSS_SALT[HASH[digestName]])))]);
   return b.sequence([b.oid(O("rsassaPss")), params]);
 }
-// The hash an id-RSASSA-PSS SPKI restricts its key to, or null when it restricts none.
-//
-// RFC 4055 sec. 3.1 draws the line at whether the parameters are THERE: "if present, the parameters
-// field MUST contain RSASSA-PSS-params", and "if RSASSA-PSS-params is present, the certificate user
-// MUST perform those operations using the one-way hash function ... identified in the ...
-// parameters". Absent parameters therefore restrict nothing, and null says so.
-//
-// PRESENT parameters are a restriction even where they look empty. `hashAlgorithm` is
-// `[0] HashAlgorithm DEFAULT sha1Identifier`, so a params SEQUENCE that omits it names SHA-1 --
-// it does not decline to name anything. Reading the omission as "no restriction" is the fail-open
-// that matters here: it turns a key its own certificate confines to SHA-1 into one that will verify
-// a SHA-512 signature. And parameters that are present but unreadable are a restriction this code
-// cannot honor, which is not the same as no restriction either, so they are refused.
 function _pssHashFromSpki(cert, E) {
   var params = cert.subjectPublicKeyInfo.algorithm.parameters;
   if (params == null) return null;
@@ -123,8 +76,6 @@ function _pssHashFromSpki(cert, E) {
     throw E("unsupported-algorithm", "the id-RSASSA-PSS key parameters are not an RSASSA-PSS-params SEQUENCE (RFC 4055 sec. 3.1)");
   }
   var hashField = _filter(node.children, function (c) { return c.tagClass === "context" && c.tagNumber === 0; })[0];
-  // DEFAULT sha1Identifier -- an omitted hashAlgorithm names SHA-1, which this toolkit does not
-  // sign or verify with, so it is reported as the pin it is and refused by the caller's own table.
   if (!hashField) return "sha1";
   if (!hashField.children || !hashField.children[0] || !hashField.children[0].children) {
     throw E("unsupported-algorithm", "the id-RSASSA-PSS key parameters carry a malformed hashAlgorithm");
@@ -139,28 +90,14 @@ function _pssHashFromSpki(cert, E) {
   return name;
 }
 
-// @internal -- the WebCrypto hash name an id-RSASSA-PSS SPKI pins, or null when it pins none.
-// Verifiers need the same restriction the signer above honors: a key whose certificate says
-// SHA-256 must not be handed a SHA-512 signature to check, and reading the pin in two places is
-// how the two directions come to disagree. Throws through the caller's E on a hash this toolkit
-// does not implement, so an unreadable restriction is never treated as no restriction.
+// @internal
 function pssSpkiPinnedHash(cert, E) {
   var d = _pssHashFromSpki(cert, E);
   if (!d) return null;
-  // A pin this toolkit has no WebCrypto hash for (SHA-1, which RSASSA-PSS-params names by DEFAULT)
-  // is still a pin. Returning undefined here would hand the caller a falsy value it reads as
-  // "unrestricted", which is the same fail-open the DEFAULT reading above exists to close, one
-  // layer up.
   if (!HASH[d]) throw E("unsupported-algorithm", "the id-RSASSA-PSS key is restricted to " + d + ", which this toolkit does not verify with");
   return HASH[d];
 }
 
-// resolveSignScheme(cert, so, noSignedAttrs, E) -> the signature scheme from the signer cert's
-// public-key algorithm + per-signer opts (so.digestAlgorithm / so.pss / so.combinedRsaSig, the
-// last folds the digest into a combined RSA signature OID for a caller with no digestAlgorithm
-// field). Returns
-// { composite?, digest, digestAlgId, sigAlgId, imp?, sign?, ecdsaDer?, coordLen? }. `digest`/
-// `digestAlgId` matter only to a caller with a CMS digestAlgorithm field; OCSP ignores them.
 function resolveSignScheme(cert, so, noSignedAttrs, E) {
   so = so || {};
   var alg = cert.subjectPublicKeyInfo.algorithm;
@@ -217,14 +154,9 @@ function resolveSignScheme(cert, so, noSignedAttrs, E) {
   throw E("unsupported-algorithm", "unsupported signer key algorithm " + keyOid);
 }
 
-// A CryptoKey's algorithm must match the resolved scheme (name / hash / curve).
 function _assertKeyMatchesScheme(key, imp, E) {
   var ka = key.algorithm || {};
-  // WebCrypto algorithm names are ASCII-case-insensitive (RSASSA-PKCS1-v1_5 and RSASSA-PKCS1-V1_5 are one
-  // algorithm), so compare case-folded; a genuine mismatch (e.g. RSASSA-PKCS1-v1_5 vs ECDSA) still fails.
   if (_toUpperCase(_String(ka.name)) !== _toUpperCase(_String(imp.name))) {
-    // A WebCrypto RSA-PSS CryptoKey is bound to PSS and cannot produce the default RSASSA-PKCS1-v1_5
-    // signature (which a raw PKCS#8 RSA key can), so name the fix rather than only the mismatch.
     var hint = (_toUpperCase(_String(ka.name)) === "RSA-PSS" && _toUpperCase(_String(imp.name)) === "RSASSA-PKCS1-V1_5")
       ? "; this CryptoKey is bound to RSASSA-PSS -- pass opts.pss to sign with RSASSA-PSS" : "";
     throw E("bad-input", "the signer CryptoKey algorithm (" + ka.name + ") does not match the certificate's key algorithm (" + imp.name + ")" + hint);
@@ -233,9 +165,6 @@ function _assertKeyMatchesScheme(key, imp, E) {
   if (imp.namedCurve && ka.namedCurve !== imp.namedCurve) throw E("bad-input", "the signer CryptoKey curve (" + ka.namedCurve + ") does not match the certificate curve (" + imp.namedCurve + ")");
 }
 function _normPkcs8(k, label, E) {
-  // A caller's own Buffer is borrowed, not copied, the same rule _importKey states below. Every
-  // other form is copied, and neither copy is duplicated further, so a private key never gains a
-  // plaintext duplicate this module cannot account for.
   if (_isBuffer(k)) return guard.bytes.view(k, E, "bad-input", label);
   if (_isU8(k)) return guard.bytes.snapshot(k, E, "bad-input", label);
   if (typeof k === "string") { try { return pkcs8.pemDecode(k); } catch (e) { throw E("bad-input", label + " PEM could not be decoded", e); } }
@@ -248,27 +177,13 @@ function _normCompositeKeys(key, comp, E) {
   return { mldsa: _normPkcs8(key.mldsa, "the composite ML-DSA component key", E), trad: _normPkcs8(key.trad, "the composite traditional component key", E) };
 }
 function _importKey(key, imp, E) {
-  // A WebCrypto CryptoKey is detected structurally (a `.type` string + an `.algorithm` object, and not
-  // a byte view), never by instanceof (cross-realm / a second installed copy) or util.types.isCryptoKey
-  // (false for this engine's own keys). The gate is broader than webcrypto.isCryptoKeyLike on purpose:
-  // an incomplete CryptoKey-shaped object (e.g. one missing its `usages`) still routes here so adoptKey
-  // reports the specific reason (usages / not-exportable) rather than the generic byte-form message. It
-  // signs, so it must be a PRIVATE key: a public or secret CryptoKey cannot produce a signature and is
-  // refused precisely.
   if (key && typeof key === "object" && !_isBuffer(key) && !_isU8(key) && typeof key.type === "string" && key.algorithm != null) {
     if (key.type !== "private") {
       throw E("bad-input", "the signing key is a WebCrypto CryptoKey of type " + _stringify(key.type) + "; a signing key must be a private key (type \"private\")");
     }
     _assertKeyMatchesScheme(key, imp, E);
-    // A CryptoKey created outside this engine signs here too -- it is re-imported through this engine,
-    // because it carries none of the key material this engine signs with. One whose material this
-    // process cannot reach is refused with that as the reason.
     return webcrypto.adoptKey(key, imp, ["sign"], E, "bad-input");
   }
-  // A Uint8Array is copied here and a PEM string is decoded here, so both leave a second copy of a
-  // private key that nothing else can reach, wiped once the engine has imported it, which is the
-  // only thing that reads it. A caller's own Buffer is passed through untouched: they hold a live
-  // reference and will use it again, so clearing it would destroy their key.
   var der, owned = false;
   if (_isBuffer(key)) der = guard.bytes.view(key, E, "bad-input", "the signer private key");
   else if (_isU8(key)) { der = guard.bytes.snapshot(key, E, "bad-input", "the signer private key"); owned = true; }
@@ -277,13 +192,10 @@ function _importKey(key, imp, E) {
     catch (e) { throw E("bad-input", "the signer PEM private key could not be decoded", e); }
     owned = true;
   } else if (intrinsic.types.isKeyObject(key)) {
-    // A node:crypto KeyObject carries a `.type` but not the WebCrypto surface (algorithm / usages), so
-    // it fails the CryptoKey gate above and would otherwise land on the generic message -- name it precisely.
     throw E("bad-input", "the signing key is a node:crypto KeyObject, not a WebCrypto CryptoKey; pass a CryptoKey (e.g. from pki.key.generate) or export it to a PKCS#8 DER Buffer or PEM string");
   } else throw E("bad-input", "a signer key must be a WebCrypto CryptoKey, a PKCS#8 DER Buffer, or a PKCS#8 PEM string");
   var imported = subtle.importKey("pkcs8", der, imp, false, ["sign"]);
   if (!owned) return imported;
-  // Wiped on the reject path too: a malformed key is not a way to leave the copy in memory.
   return imported.then(function (k) {
     guard.secret.zeroize(der, E, "bad-input", "the signer private-key copy");
     return k;
@@ -293,9 +205,6 @@ function _importKey(key, imp, E) {
   });
 }
 
-// signOverTbs(scheme, key, signedBytes, E) -> Promise<Buffer> the raw signature over signedBytes.
-// The classical path imports the key + signs (re-encoding ECDSA to canonical DER); the composite
-// path signs both component keys and returns mldsaSig || tradSig (composite-sig.js owns it).
 function signOverTbs(scheme, key, signedBytes, E) {
   if (scheme.composite) {
     return compositeSig.compositeSign(scheme.composite, _normCompositeKeys(key, scheme.composite, E), signedBytes).then(function (sig) { return _bufferFrom(sig); });
@@ -309,10 +218,6 @@ function signOverTbs(scheme, key, signedBytes, E) {
   });
 }
 
-// MLDSA_SUITABLE_DIGEST + SLHDSA_BY_OID are the RFC 9882 sec. 3.3 / RFC 9814 sec. 4 per-parameter-
-// set digest policy, exported so the VERIFY side (cms-verify) shares the EXACT same table this
-// resolver signs under -- a digest accepted on sign is precisely the set accepted on verify, with
-// no drift between the two.
 module.exports = {
   resolveSignScheme: resolveSignScheme,
   pssSpkiPinnedHash: pssSpkiPinnedHash,