@blamejs/pki 0.2.16 → 0.2.18

package/lib/path-validate.js

@@ -40,6 +40,9 @@ var crl = require("./schema-crl");
 var ocsp = require("./schema-ocsp");
 var guard = require("./guard-all");
 var constants = require("./constants");
+var validator = require("./validator-all");
+var compositeSig = require("./composite-sig");
+var edwardsPoint = require("./edwards-point");
 
 var PathError = errors.PathError;
 function E(code, message, cause) { return new PathError(code, message, cause); }
@@ -114,6 +117,10 @@ function _sig(name, verify, imp, params, ecdsa, sameKeyOid) {
   var entry = { verify: verify, imp: imp, params: params };
   if (ecdsa) entry.ecdsa = true;
   if (sameKeyOid) entry.sameKeyOid = true;
+  // EdDSA descriptors carry the Edwards curve id (6 = Ed25519, 7 = Ed448) so the verify path
+  // validates the issuer point through the shared gate without re-branching on the algorithm name.
+  if (verify.name === "Ed25519") entry.eddsa = 6;
+  else if (verify.name === "Ed448") entry.eddsa = 7;
   SIG_ALGS[oid.byName(name)] = entry;
 }
 // RSASSA-PKCS1-v1_5 -- parameters MUST be NULL.
@@ -151,13 +158,8 @@ HASH_BY_OID[oid.byName("sha256")] = "SHA-256";
 HASH_BY_OID[oid.byName("sha384")] = "SHA-384";
 HASH_BY_OID[oid.byName("sha512")] = "SHA-512";
 
-var CURVE_FIELD_BYTES = { "P-256": 32, "P-384": 48, "P-521": 66 };
-// Curve group orders n -- a valid ECDSA signature has r,s in [1, n-1].
-var CURVE_ORDER = {
-  "P-256": BigInt("0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551"),
-  "P-384": BigInt("0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFC7634D81F4372DDF581A0DB248B0A77AECEC196ACCC52973"),
-  "P-521": BigInt("0x01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFA51868783BF2F966B7FCC0148F709A5D03BB5C9B8899C47AEBB6FB71E91386409"),
-};
+// The order-aware ECDSA DER->P1363 converter + its CURVE_FIELD_BYTES / CURVE_ORDER tables now
+// live in validator-sig.js (validator.sig.ecdsaDerToP1363), shared with the composite engine.
 
 // The algorithm OID of an AlgorithmIdentifier SEQUENCE { algorithm OID,
 // parameters OPTIONAL }. STRICT: a universal SEQUENCE with the OID and AT MOST
@@ -187,6 +189,9 @@ function hashAlgOid(seq) {
 }
 // The hash OID inside an EXPLICIT [n] wrapper around a hash AlgorithmIdentifier.
 function explicitHashAlgOid(wrapper) {
+  // Coverage residual -- unreachable: the sole caller (resolveRsaPss) already
+  // asserts the EXPLICIT wrapper carries exactly one child before calling this, so
+  // this identical inner check cannot fire; it is a local defense-in-depth backstop.
   if (!wrapper.children || wrapper.children.length !== 1) throw E("path/unsupported-algorithm", "malformed EXPLICIT hash AlgorithmIdentifier");
   return hashAlgOid(wrapper.children[0]);
 }
@@ -258,16 +263,11 @@ function isDerNull(p) { return p && p.length === 2 && p[0] === 0x05 && p[1] ===
 
 function resolveDescriptor(sigAlg) {
   if (sigAlg.oid === OID_RSA_PSS) return resolveRsaPss(sigAlg.parameters);
-  var comp = COMPOSITE_ALGS[sigAlg.oid];
-  if (comp) {
-    // draft-ietf-lamps-pq-composite-sigs sec. 5.3: parameters MUST be absent.
-    if (sigAlg.parameters !== null && sigAlg.parameters !== undefined) {
-      throw E("path/unsupported-algorithm", "composite signature algorithm parameters must be absent (draft-ietf-lamps-pq-composite-sigs sec. 5.3)");
-    }
-    // The composite public-key algorithm OID equals the signature OID; enforce
-    // the RFC 9814-style key<->signature consistency structurally (sameKeyOid).
-    return { composite: comp, sameKeyOid: true };
-  }
+  // Composite ML-DSA: the OID-keyed registry + the parameters-absent check
+  // (draft-ietf-lamps-pq-composite-sigs sec. 5.3) live in composite-sig.js, shared with
+  // CMS. sameKeyOid enforces the RFC 9814 sec. 4 key<->signature OID consistency.
+  var comp = compositeSig.resolveCompositeDescriptor(sigAlg, PathError, "path/unsupported-algorithm");
+  if (comp) return comp;
   var d = SIG_ALGS[sigAlg.oid];
   if (!d) throw E("path/unsupported-algorithm", "no verify descriptor for signature algorithm " + (sigAlg.name || sigAlg.oid));
   // The signatureAlgorithm's parameters MUST match the algorithm's fixed shape:
@@ -297,169 +297,15 @@ function assertKeyMatchesSigAlg(spkiBytes, sigOid, d) {
   }
 }
 
-// DER Ecdsa-Sig-Value SEQUENCE { r, s } -> fixed-width r||s (P1363), rejecting
-// r or s outside [1, n-1] (CVE-2022-21449 "Psychic Signatures").
-function ecdsaDerToP1363(der, curve) {
-  var width = CURVE_FIELD_BYTES[curve];
-  var order = CURVE_ORDER[curve];
-  if (!width || !order) throw E("path/bad-signature", "unsupported ECDSA curve " + curve);
-  var n;
-  try { n = asn1.decode(der); }
-  catch (e) { throw E("path/bad-signature", "ECDSA signature is not a DER SEQUENCE(r,s)", e); }
-  if (n.tagClass !== "universal" || n.tagNumber !== asn1.TAGS.SEQUENCE || !n.children || n.children.length !== 2) {
-    throw E("path/bad-signature", "ECDSA signature must be a SEQUENCE of exactly two INTEGERs");
-  }
-  var r = asn1.read.integer(n.children[0]);
-  var s = asn1.read.integer(n.children[1]);
-  if (r < 1n || s < 1n || r >= order || s >= order) {
-    throw E("path/bad-signature", "ECDSA signature component out of range [1, n-1] (CVE-2022-21449)");
-  }
-  function pad(v) {
-    var hex = v.toString(16);
-    if (hex.length % 2) hex = "0" + hex;
-    var buf = Buffer.from(hex, "hex");
-    if (buf.length > width) throw E("path/bad-signature", "ECDSA signature component wider than the curve field");
-    var out = Buffer.alloc(width);
-    buf.copy(out, width - buf.length);
-    return out;
-  }
-  return Buffer.concat([pad(r), pad(s)]);
-}
+// ecdsaDerToP1363 relocated to validator-sig.js; the composite trad-ECDSA and classical ECDSA
+// paths call validator.sig.ecdsaDerToP1363(sig, curve, PathError, "path/bad-signature").
 
 // ---- composite ML-DSA signatures (draft-ietf-lamps-pq-composite-sigs) -------
-// A composite signature pairs a post-quantum ML-DSA with a traditional RSA /
-// ECDSA / EdDSA. 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) in the signatureValue BIT STRING. Both are surfaced RAW by the
-// x509 parser (no sub-walk). Verification (sec. 2): reconstruct
-//   M' = Prefix || Label || len(ctx) || ctx || PH(M),
-// verify the ML-DSA component over M' with ctx = the composite Label, verify the
-// traditional component over M' under its own hash, and accept IFF BOTH pass
-// (THREAT-MODEL: all components must verify -- never an AND-to-OR downgrade). The
-// ML-DSA component is the fixed-length FIRST half; the split point is its length.
-var COMPOSITE_PREFIX = Buffer.from("CompositeAlgorithmSignatures2025", "ascii");
-var MLDSA_COMPONENT = {
-  "ML-DSA-44": { pk: 1312, sig: 2420, oid: "id-ml-dsa-44" },
-  "ML-DSA-65": { pk: 1952, sig: 3309, oid: "id-ml-dsa-65" },
-  "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" };
-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 (brainpool
-//   curves; the SHAKE256/64 pre-hash) -- registered + params-guarded, deferred at
-//   verify to path/unsupported-algorithm rather than silently accepted.
-function _comp(name, mldsa, ph, label, trad) {
-  var sz = MLDSA_COMPONENT[mldsa];
-  COMPOSITE_ALGS[oid.byName(name)] = {
-    name: name, mldsa: mldsa, mldsaPk: sz.pk, mldsaSig: sz.sig, mldsaOid: sz.oid,
-    ph: ph, label: Buffer.from(label, "ascii"), trad: trad,
-  };
-}
-_comp("id-MLDSA44-RSA2048-PSS-SHA256", "ML-DSA-44", "SHA-256", "COMPSIG-MLDSA44-RSA2048-PSS-SHA256", { rsaPss: true, hash: "SHA-256", salt: 32, rsaBits: 2048 });
-_comp("id-MLDSA44-RSA2048-PKCS15-SHA256", "ML-DSA-44", "SHA-256", "COMPSIG-MLDSA44-RSA2048-PKCS15-SHA256", { rsaPkcs1: true, hash: "SHA-256", rsaBits: 2048 });
-_comp("id-MLDSA44-Ed25519-SHA512", "ML-DSA-44", "SHA-512", "COMPSIG-MLDSA44-Ed25519-SHA512", { eddsa: "Ed25519" });
-_comp("id-MLDSA44-ECDSA-P256-SHA256", "ML-DSA-44", "SHA-256", "COMPSIG-MLDSA44-ECDSA-P256-SHA256", { ec: "P-256", hash: "SHA-256" });
-_comp("id-MLDSA65-RSA3072-PSS-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-RSA3072-PSS-SHA512", { rsaPss: true, hash: "SHA-256", salt: 32, rsaBits: 3072 });
-_comp("id-MLDSA65-RSA3072-PKCS15-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-RSA3072-PKCS15-SHA512", { rsaPkcs1: true, hash: "SHA-256", rsaBits: 3072 });
-_comp("id-MLDSA65-RSA4096-PSS-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-RSA4096-PSS-SHA512", { rsaPss: true, hash: "SHA-384", salt: 48, rsaBits: 4096 });
-_comp("id-MLDSA65-RSA4096-PKCS15-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-RSA4096-PKCS15-SHA512", { rsaPkcs1: true, hash: "SHA-384", rsaBits: 4096 });
-_comp("id-MLDSA65-ECDSA-P256-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-ECDSA-P256-SHA512", { ec: "P-256", hash: "SHA-256" });
-_comp("id-MLDSA65-ECDSA-P384-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-ECDSA-P384-SHA512", { ec: "P-384", hash: "SHA-384" });
-_comp("id-MLDSA65-ECDSA-brainpoolP256r1-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-ECDSA-BP256-SHA512", { unsupported: "brainpoolP256r1 is not in the WebCrypto ECDSA curve set" });
-_comp("id-MLDSA65-Ed25519-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-Ed25519-SHA512", { eddsa: "Ed25519" });
-_comp("id-MLDSA87-ECDSA-P384-SHA512", "ML-DSA-87", "SHA-512", "COMPSIG-MLDSA87-ECDSA-P384-SHA512", { ec: "P-384", hash: "SHA-384" });
-_comp("id-MLDSA87-ECDSA-brainpoolP384r1-SHA512", "ML-DSA-87", "SHA-512", "COMPSIG-MLDSA87-ECDSA-BP384-SHA512", { unsupported: "brainpoolP384r1 is not in the WebCrypto ECDSA curve set" });
-_comp("id-MLDSA87-Ed448-SHAKE256", "ML-DSA-87", "SHAKE256", "COMPSIG-MLDSA87-Ed448-SHAKE256", { unsupported: "the SHAKE256/64 pre-hash is not in the WebCrypto digest set" });
-_comp("id-MLDSA87-RSA3072-PSS-SHA512", "ML-DSA-87", "SHA-512", "COMPSIG-MLDSA87-RSA3072-PSS-SHA512", { rsaPss: true, hash: "SHA-256", salt: 32, rsaBits: 3072 });
-_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" });
-
-var _b = asn1.build;
-// Wrap a raw component public key in the SPKI its WebCrypto import expects, so
-// each half is verified through the SAME import + 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;
-}
-
-function _verifyTradComponent(trad, tradPK, tradSig, mprime) {
-  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 reader that also rejects r/s outside [1,n-1] (CVE-2022-21449).
-      var p1363 = ecdsaDerToP1363(tradSig, trad.ec);
-      return subtle.verify({ name: "ECDSA", hash: trad.hash }, k, p1363, mprime);
-    });
-  }
-  if (trad.eddsa) {
-    return subtle.importKey("spki", _edSpki(trad.eddsa, tradPK), { name: trad.eddsa }, false, ["verify"])
-      .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); }
-    if (bits !== trad.rsaBits) return Promise.resolve(false);
-    if (trad.rsaPss) {
-      return subtle.importKey("spki", _rsaSpki(tradPK), { name: "RSA-PSS", hash: trad.hash }, false, ["verify"])
-        .then(function (k) { return subtle.verify({ name: "RSA-PSS", saltLength: trad.salt }, k, tradSig, mprime); });
-    }
-    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); });
-  }
-  return Promise.resolve(false);
-}
-
-// Verify a composite signature: `spkiBytes` the issuer SPKI DER, `sigBytes` the
-// raw signatureValue (mldsaSig || tradSig), `message` the signed region (tbsBytes).
-function compositeVerify(spkiBytes, sigBytes, message, d) {
-  if (d.trad.unsupported) {
-    return Promise.resolve({ ok: false, code: "path/unsupported-algorithm",
-      error: E("path/unsupported-algorithm", "composite " + d.name + ": " + d.trad.unsupported) });
-  }
-  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 E("path/bad-signature", "composite subjectPublicKey has unused bits");
-    rawKey = bs.bytes;
-  } catch (e) { return Promise.resolve({ ok: false, code: pathCode(e, "path/bad-signature"), error: e }); }
-  // The ML-DSA half is fixed-length and 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: "path/bad-signature",
-      error: E("path/bad-signature", "composite key/signature shorter than the fixed ML-DSA component") });
-  }
-  var mldsaPK = rawKey.subarray(0, d.mldsaPk), tradPK = rawKey.subarray(d.mldsaPk);
-  var mldsaSig = sigBytes.subarray(0, d.mldsaSig), tradSig = sigBytes.subarray(d.mldsaSig);
-  return subtle.digest({ name: d.ph }, message).then(function (phBuf) {
-    // M' = Prefix || Label || len(ctx)=0 || ctx="" || PH(M). In X.509 path
-    // validation the application context is empty (a caller ctx is out of scope).
-    var mprime = Buffer.concat([COMPOSITE_PREFIX, d.label, Buffer.from([0]), Buffer.from(phBuf)]);
-    var mldsaP = subtle.importKey("spki", _mldsaSpki(d.mldsaOid, mldsaPK), { name: d.mldsa }, false, ["verify"])
-      .then(function (mk) { return subtle.verify({ name: d.mldsa, context: d.label }, mk, mldsaSig, mprime); });
-    var tradP = _verifyTradComponent(d.trad, tradPK, tradSig, mprime);
-    return Promise.all([mldsaP, tradP]).then(function (r) { return { ok: r[0] === true && r[1] === true }; });
-  }).catch(function (e) { return { ok: false, code: pathCode(e, "path/bad-signature"), error: e }; });
-}
+// The composite verify/sign engine + the COMPOSITE_ALGS OID-keyed registry live in
+// composite-sig.js (shared with CMS composite SignerInfo). Path validation composes it:
+// resolveDescriptor (above) delegates to compositeSig.resolveCompositeDescriptor, the
+// certificate + OCSP verify paths to compositeSig.compositeVerify, and
+// compositeKeyUsageCheck (below) enforces the sec. 5.2 signature-only keyUsage restriction.
 
 // draft-ietf-lamps-pq-composite-sigs sec. 5.2: a certificate whose SubjectPublicKeyInfo
 // carries a composite ML-DSA OID, IF it has a keyUsage extension, MUST assert at least
@@ -485,6 +331,19 @@ function compositeKeyUsageCheck(cert) {
   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
+// (CRL / OCSP-response) path import through, so neither can skip the point gate -- a low-order
+// issuer / responder key fails the caller closed (a rejected promise the caller maps to a bad
+// verdict), never verifying a forged chain or a forged revocation.
+function _importVerifyKey(spkiBytes, d) {
+  try {
+    if (d.eddsa) edwardsPoint.validateSpki(spkiBytes, d.eddsa, PathError, "path/bad-signature");
+  } catch (e) { return Promise.reject(e); }
+  return subtle.importKey("spki", spkiBytes, d.imp, false, ["verify"]);
+}
+
 // Verify cert.signatureValue over cert.tbsBytes with the working public key.
 function builtinVerify(state, cert) {
   var d;
@@ -498,12 +357,12 @@ function builtinVerify(state, cert) {
   // A composite signature verifies its ML-DSA and traditional halves and accepts
   // IFF both pass -- delegated to the composite combinator (which reuses this
   // file's ECDSA range-check + the same import/verify seam).
-  if (d.composite) return compositeVerify(state.workingPublicKey, cert.signatureValue.bytes, cert.tbsBytes, d.composite);
+  if (d.composite) return compositeSig.compositeVerify(state.workingPublicKey, cert.signatureValue.bytes, cert.tbsBytes, d.composite, PathError, "path/unsupported-algorithm", "path/bad-signature");
   var key;
-  return subtle.importKey("spki", state.workingPublicKey, d.imp, false, ["verify"]).then(function (k) {
+  return _importVerifyKey(state.workingPublicKey, d).then(function (k) {
     key = k;
     var sig = cert.signatureValue.bytes;
-    if (d.ecdsa) sig = ecdsaDerToP1363(sig, key.algorithm.namedCurve);
+    if (d.ecdsa) sig = validator.sig.ecdsaDerToP1363(sig, key.algorithm.namedCurve, PathError, "path/bad-signature");
     return subtle.verify(d.verify, key, sig, cert.tbsBytes);
   }).then(function (ok) {
     return { ok: ok === true };
@@ -714,6 +573,9 @@ function certNameForms(cert) {
     // constraint check fails such a form closed (name-constraint-unsupported).
     san.value.names.forEach(function (nm) {
       if (nm.tagNumber === 1) hasRfc822San = true;   // an rfc822Name SAN carries the email identity
+      // Coverage residual -- the `undefined -> null` arm is unreachable: the SAN
+      // decoder (schema-pkix altName, decodeValue:true) routes through generalName,
+      // which already maps an undecoded value to null, so nm.value is never undefined.
       forms.push({ tag: nm.tagNumber, value: nm.value === undefined ? null : nm.value });
     });
   }
@@ -808,6 +670,8 @@ function treeWithoutParent(node) {
 }
 function leavesAt(tree, depth) {
   var out = [];
+  // Coverage residual -- unreachable: every call site guards state.validPolicyTree
+  // truthy before calling leavesAt; the null-tree early return is a backstop.
   if (!tree) return out;   // a pruned-empty tree has no nodes
   (function walk(node) {
     if (node.depth === depth) { out.push(node); return; }
@@ -1135,6 +999,10 @@ function applyPolicyMappings(state, mappings, i) {
     // extension may have already emptied the tree -- stop if it is gone.
     var mappedSet = {};
     mappings.forEach(function (m) { mappedSet[m.issuerDomainPolicy] = true; });
+    // Coverage residual -- unreachable today: applyPolicyMappings is invoked once per
+    // certificate under an `if (state.validPolicyTree)` guard and does not null the
+    // tree before this point. Retained as a cheap correctness backstop for a future
+    // per-mapping-batch refactor; do not remove.
     if (!state.validPolicyTree) return;
     leavesAt(state.validPolicyTree, depth).forEach(function (node) {
       if (mappedSet[node.validPolicy] && node.parent) {
@@ -1341,7 +1209,7 @@ async function validate(path, opts) {
     // draft-ietf-lamps-pq-composite-sigs sec. 5.2: a composite-keyed certificate's
     // keyUsage must be signature-only (no dual-usage). Runs for the target AND every
     // intermediate whose own subject key is composite.
-    if (COMPOSITE_ALGS[cert.subjectPublicKeyInfo.algorithm.oid]) {
+    if (compositeSig.COMPOSITE_ALGS[cert.subjectPublicKeyInfo.algorithm.oid]) {
       var cku = compositeKeyUsageCheck(cert);
       checks.push({ name: "compositeKeyUsage", ok: cku.ok, code: cku.ok ? undefined : cku.code });
       if (!cku.ok) failed = true;
@@ -1773,6 +1641,8 @@ function crlChecker(crls) {
         // process (anything but reasonCode) makes the CRL unusable for ANY
         // certificate, not just the entry that carries it.
         for (var ry = 0; ry < theCrl.revokedCertificates.length && !unhandledCritical; ry++) {
+          // Coverage residual -- the `|| []` fallback is unreachable: schema-crl sets
+          // crlEntryExtensions to [] when absent, so it is always an array.
           var ees = theCrl.revokedCertificates[ry].crlEntryExtensions || [];
           for (var ex = 0; ex < ees.length; ex++) {
             // Key on the stable OID only -- a display name is registry-dependent
@@ -1893,6 +1763,8 @@ function crlChecker(crls) {
 // number), or null when absent.
 var OID_REASON_CODE = oid.byName("reasonCode");
 function crlEntryReason(entry) {
+  // Coverage residual -- the `|| []` fallback is unreachable: schema-crl guarantees
+  // crlEntryExtensions is an array (empty when absent).
   var exts = entry.crlEntryExtensions || [];
   for (var i = 0; i < exts.length; i++) {
     if (exts[i].oid === OID_REASON_CODE) return exts[i].value;   // stable OID, not the display name
@@ -1918,10 +1790,10 @@ function _verifyWithSpki(sigAlg, rawSig, spkiBytes, tbsBytes) {
   // A composite-signed CRL / OCSP response verifies through the same combinator
   // (both halves must pass) that the certificate path uses -- one composite verify,
   // never a second parallel one.
-  if (d.composite) return compositeVerify(spkiBytes, rawSig, tbsBytes, d.composite).then(function (r) { return r.ok === true; });
-  return subtle.importKey("spki", spkiBytes, d.imp, false, ["verify"]).then(function (key) {
+  if (d.composite) return compositeSig.compositeVerify(spkiBytes, rawSig, tbsBytes, d.composite, PathError, "path/unsupported-algorithm", "path/bad-signature").then(function (r) { return r.ok === true; });
+  return _importVerifyKey(spkiBytes, d).then(function (key) {
     var sig = rawSig;
-    if (d.ecdsa) sig = ecdsaDerToP1363(sig, key.algorithm.namedCurve);
+    if (d.ecdsa) sig = validator.sig.ecdsaDerToP1363(sig, key.algorithm.namedCurve, PathError, "path/bad-signature");
     return subtle.verify(d.verify, key, sig, tbsBytes);
   }).then(function (ok) { return ok === true; }, function () { return false; });
 }
@@ -1963,6 +1835,9 @@ function ocspResponderSpki(rc, issuer) {
   var keyAlg = rc.subjectPublicKeyInfo.algorithm;
   if (!isNullOrAbsentParams(keyAlg.parameters)) return rc.subjectPublicKeyInfo.bytes;
   var issuerOid, issuerParams;
+  // Coverage residual -- the catch is unreachable: this function runs only after the
+  // delegate's signature verified under issuer.workingPublicKey, so that SPKI already
+  // imported and decodes cleanly here. (The children[1] ? : null false side IS covered.)
   try {
     var alg = asn1.decode(issuer.workingPublicKey).children[0];
     issuerOid = asn1.read.oid(alg.children[0]);
@@ -2082,7 +1957,7 @@ async function ocspAuthorizeResponder(basicResponse, cert, issuer, issuerKeyBits
     // A composite-keyed delegate is an out-of-path signer cert and gets the same
     // composite keyUsage gate the path certificates do (draft sec. 5.2): a dual-usage
     // composite responder key (a forbidden encryption bit set) is not authorized.
-    if (COMPOSITE_ALGS[rc.subjectPublicKeyInfo.algorithm.oid] && !compositeKeyUsageCheck(rc).ok) continue;
+    if (compositeSig.COMPOSITE_ALGS[rc.subjectPublicKeyInfo.algorithm.oid] && !compositeKeyUsageCheck(rc).ok) continue;
     return ocspResponderSpki(rc, issuer);
   }
   return null;
@@ -2149,6 +2024,9 @@ function ocspChecker(responses) {
         var resp = parsed[k];
         if (resp.responseStatus.code !== 0) continue;   // non-successful -> conveys no status
         var br = resp.basicResponse;
+        // Coverage residual -- unreachable for a parsed response: schema-ocsp enforces
+        // the successful-status <-> responseBytes biconditional, so a code-0 response
+        // always carries a basicResponse. Backstop for a hand-built object.
         if (!br) continue;
         var signerSpki = await ocspAuthorizeResponder(br, cert, issuer, issuerKeyBits, time);
         if (!signerSpki) continue;                       // unauthorized responder

package/lib/schema-cms.js

@@ -146,6 +146,9 @@ function _checkAttrPlacement(attrs, place) {
   for (var i = 0; i < attrs.length; i++) {
     var row = ATTR_FORBIDDEN_IN[attrs[i].type];
     if (row && row[place]) {
+      // Coverage residual -- reached only when the OID is a registry entry (the guard above
+      // guarantees it), so oid.name() never returns undefined and this fallback is a
+      // defensive belt, not selectable through the public parse path.
       throw NS.E("cms/misplaced-attr", "the " + (oid.name(attrs[i].type) || attrs[i].type) +
         " attribute must not be " + ATTR_PLACE_LABELS[place] + " (RFC 5652 sec. 11)");
     }
@@ -250,6 +253,10 @@ function _validateAeadParams(alg, macLen) {
   // sec. 3.1/sec. 3.2: the parameters field MUST be present and carry the Parameters SEQUENCE.
   if (alg.parameters === null) throw NS.E("cms/bad-aead-params", "an AES-" + K + " content-encryption algorithm MUST carry its parameters (RFC 5084 sec. 3." + (kind === "gcm" ? "2" : "1") + ")");
   var node;
+  // Coverage residual -- alg.parameters is an AlgorithmIdentifier child already fully
+  // validated by the eager-recursive asn1.decode during the enclosing SEQUENCE parse;
+  // re-decoding the same TLV cannot fault, so this catch is an unreachable fail-closed
+  // belt (malformed parameters are rejected as asn1/* before _validateAeadParams runs).
   try { node = asn1.decode(alg.parameters); }
   catch (e) { throw NS.E("cms/bad-aead-params", "malformed AES-" + K + " parameters", e); }
   if (node.tagClass !== "universal" || node.tagNumber !== T.SEQUENCE || !node.children || node.children.length < 1 || node.children.length > 2) {
@@ -739,12 +746,18 @@ var KEM_RECIPIENT_INFO = schema.seq([
     // recognized AES key-wrap pins the exact KEK size (registry, not switch).
     var wrapLen = WRAP_KEK_LENGTHS[wrap.oid];
     if (wrapLen !== undefined && kekLength !== wrapLen) {
+      // Coverage residual -- reached only when the OID is a registry entry (the guard above
+      // guarantees it), so oid.name() never returns undefined and this fallback is a
+      // defensive belt, not selectable through the public parse path.
       throw NS.E("cms/kek-length-mismatch", "kekLength " + kekLength + " does not match the " + (oid.name(wrap.oid) || wrap.oid) + " KEK size " + wrapLen + " (RFC 9629 sec. 3)");
     }
     // FIPS 203 -- a recognized ML-KEM kem produces a fixed-size ciphertext; any
     // other kemct length can never decapsulate.
     var ctLen = KEM_CT_LENGTHS[kem.oid];
     if (ctLen !== undefined && kemct.length !== ctLen) {
+      // Coverage residual -- reached only when the OID is a registry entry (the guard above
+      // guarantees it), so oid.name() never returns undefined and this fallback is a
+      // defensive belt, not selectable through the public parse path.
       throw NS.E("cms/bad-kem-ciphertext", "the " + (oid.name(kem.oid) || kem.oid) + " kemct must be exactly " + ctLen + " octets (FIPS 203)");
     }
     return {
@@ -1049,6 +1062,9 @@ var CONTENT_INFO = schema.seq([
     else if (ct === OID_AUTH_ENVELOPED_DATA) inner = AUTH_ENVELOPED_DATA;
     if (inner === null) {
       if (DEFERRED.has(ct)) {
+        // Coverage residual -- reached only when the OID is a registry entry (the guard above
+        // guarantees it), so oid.name() never returns undefined and this fallback is a
+        // defensive belt, not selectable through the public parse path.
         throw NS.E("cms/unsupported-content-type", (ctx.oid.name(ct) || ct) + " is recognized but not parsed by this build");
       }
       throw NS.E("cms/unknown-content-type", "unrecognized ContentInfo content type " + ct);
@@ -1058,6 +1074,9 @@ var CONTENT_INFO = schema.seq([
     // a consumer branches on contentTypeName instead of duck-typing the shape.
     var result = schema.walk(inner, m.fields.content.value, ctx).result;
     result.contentType = ct;
+    // Coverage residual -- reached only when the OID is a registry entry (the guard above
+    // guarantees it), so oid.name() never returns undefined and this fallback is a
+    // defensive belt, not selectable through the public parse path.
     result.contentTypeName = ctx.oid.name(ct) || null;
     return result;
   },

package/lib/sigstore.js

@@ -205,6 +205,7 @@ function _sha256(buf) { return nodeCrypto.createHash("sha256").update(buf).diges
 // A validFor bound is an epoch-ms number, a Date, or an ISO-8601 string (the form
 // a Sigstore trusted_root carries). Returns null for absent/unparseable.
 function _toMs(x) {
+  // Coverage residual -- _inWindow gates every _toMs call behind a != null check; the null guard is dead defensive code.
   if (x == null) return null;
   if (typeof x === "number") return Number.isFinite(x) ? x : null;
   if (x instanceof Date) { var d = x.getTime(); return isNaN(d) ? null : d; }
@@ -418,6 +419,7 @@ async function _verifyChain(leaf, chainDers, fulcioRoots, timeMs) {
       if (res.valid) return;
       lastErr = _err("sigstore/chain-invalid", "the Fulcio certificate chain is not valid as of the log time");
     } catch (e) {
+      // Coverage residual -- pathValidate.validate is fail-safe (builtinVerify never throws; every decodeExt wrapped), so no raw throw escapes for a well-formed path; the catch is a defensive re-type.
       lastErr = _err("sigstore/chain-invalid", "the Fulcio certificate chain failed validation: " + e.message, e);
     }
   }
@@ -439,6 +441,7 @@ function _identity(leaf) {
   // malformed certificate and fails closed with a named reason (never a silent
   // drop that would hide an identity claim a caller policy relies on).
   try {
+    // Coverage residual -- x509.parse always surfaces extensions as an array.
     (leaf.extensions || []).forEach(function (ext) {
       if (ext.oid === SAN_OID) { out.san = _sanValue(ext); return; }
       if (ext.oid.indexOf(FULCIO_PREFIX) === 0) {
@@ -458,6 +461,7 @@ var GN_TYPE = { 1: "rfc822Name", 2: "dNSName", 6: "uri" };
 function _sanValue(ext) {
   var seq = asn1.decode(ext.value);
   var names = [];
+  // Coverage residual -- path.validate's GeneralName gate (context-only, SEQUENCE SAN, strict otherName [0]) rejects the shapes that would trigger these fallbacks before _identity; asn1.decode guarantees a children array on any constructed node.
   for (var i = 0; i < (seq.children || []).length; i++) {
     var n = seq.children[i];
     if (n.tagClass !== "context") continue;
@@ -470,6 +474,7 @@ function _sanValue(ext) {
       // machine identities here (type-id .1.7, value a UTF8String).
       var inner = (n.children[1].children || [])[0] || n.children[1];
       var v;
+      // Coverage residual -- asn1.decode gives every node a (truthy) Buffer content, so the || [] fallback is unreachable; the catch itself runs for a non-string otherName inner value.
       try { v = asn1.read.string(inner); } catch (_e) { v = Buffer.from(inner.content || []).toString("utf8"); }
       val = { type: "otherName", oid: asn1.read.oid(n.children[0]), value: v };
     }
@@ -482,6 +487,7 @@ function _sanValue(ext) {
   return names[0] || null;
 }
 function _fulcioExtValue(ext, leafArc) {
+  // Coverage residual -- ext.value is read.octetString output, always a Buffer.
   if (!Buffer.isBuffer(ext.value)) throw _err("sigstore/bad-certificate", "Fulcio extension " + ext.oid + " has no value");
   // The raw-vs-DER split by member (Fulcio oid-info): .1-.6 legacy are raw UTF-8
   // strings; .8+ are DER UTF8String -- the arc is open-ended past .22. An

package/lib/validator-cose.js

@@ -66,6 +66,9 @@ var ALG_PROFILE = {
 
 // 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];
@@ -146,6 +149,9 @@ function toSpki(key, E, code) {
   function bad(msg) { return new E(code, msg); }
   if (key.kty === 2 && key.x && key.y) {
     var curveOid = EC2_CRV_OID[key.crv];
+    // Coverage residual -- toSpki only receives a credentialKey-validated key; EC2 crv is
+    // already gated to {1,2,3} by EC2_CRV_LEN, the exact EC2_CRV_OID keyset, so curveOid is
+    // always defined.
     if (!curveOid) throw bad("unsupported EC2 curve " + key.crv);
     var b = asn1.build;
     return b.sequence([
@@ -164,6 +170,8 @@ function toSpki(key, E, code) {
     var eb = asn1.build;
     return eb.sequence([eb.sequence([eb.oid(oid.byName(OKP_CRV[key.crv].oid))]), eb.bitString(key.x)]);
   }
+  // Coverage residual -- a credentialKey-validated key always matches one of the three forms
+  // above; this fallthrough is defensive depth.
   throw bad("cannot build an SPKI for this COSE key type");
 }
 

package/lib/validator-sig.js

@@ -71,4 +71,51 @@ function rawToEcdsaDer(raw, coordLen) {
   return asn1.build.sequence([asn1.build.integer(r), asn1.build.integer(s)]);
 }
 
-module.exports = { ecdsaSigToRaw: ecdsaSigToRaw, rawToEcdsaDer: rawToEcdsaDer };
+// The curve group orders n -- a valid ECDSA signature has r, s in [1, n-1].
+var CURVE_FIELD_BYTES = { "P-256": 32, "P-384": 48, "P-521": 66 };
+var CURVE_ORDER = {
+  "P-256": BigInt("0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551"),
+  "P-384": BigInt("0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFC7634D81F4372DDF581A0DB248B0A77AECEC196ACCC52973"),
+  "P-521": BigInt("0x01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFA51868783BF2F966B7FCC0148F709A5D03BB5C9B8899C47AEBB6FB71E91386409"),
+};
+
+// ecdsaDerToP1363(der, curve, E, code) -> the DER ECDSA-Sig-Value converted to raw r||s (P1363),
+// each coordinate left-padded to the curve field width, rejecting r or s outside [1, n-1] against
+// the curve ORDER (CVE-2022-21449 "Psychic Signatures" -- the r/s = 0 case AND the >= n upper
+// bound). `curve` is a WebCrypto namedCurve (P-256/384/521). This is the ORDER-AWARE gate a
+// verifier that knows the curve order MUST use; it is STRICTER than ecdsaSigToRaw above, which
+// bounds r/s only by the field SIZE (>= 1, <= coordLen bytes) and does not know the order. A
+// signature whose r or s is >= n is rejected here but passes ecdsaSigToRaw -- do not conflate them.
+// @enforced-by behavioral -- the RED conformance vectors (r/s = 0, r/s >= n, non-minimal, over-size)
+// and the composite-signature + path-validation KATs are the guard.
+function ecdsaDerToP1363(der, curve, E, code) {
+  var width = CURVE_FIELD_BYTES[curve];
+  var order = CURVE_ORDER[curve];
+  if (!width || !order) throw new E(code, "unsupported ECDSA curve " + curve);
+  var n;
+  try { n = asn1.decode(der); }
+  catch (e) { throw new E(code, "ECDSA signature is not a DER SEQUENCE(r,s)", e); }
+  if (n.tagClass !== "universal" || n.tagNumber !== asn1.TAGS.SEQUENCE || !n.children || n.children.length !== 2) {
+    throw new E(code, "ECDSA signature must be a SEQUENCE of exactly two INTEGERs");
+  }
+  var r = asn1.read.integer(n.children[0]);
+  var s = asn1.read.integer(n.children[1]);
+  if (r < 1n || s < 1n || r >= order || s >= order) {
+    throw new E(code, "ECDSA signature component out of range [1, n-1] (CVE-2022-21449)");
+  }
+  function pad(v) {
+    var hex = v.toString(16);
+    if (hex.length % 2) hex = "0" + hex;
+    var buf = Buffer.from(hex, "hex");
+    // Coverage residual -- unreachable: a component needing more than `width` bytes is >=
+    // 2^(8*width) > n (the curve order n < 2^(8*width) for P-256/384/521), so it is already
+    // rejected by the r/s >= order check above; this width guard is a defense-in-depth backstop.
+    if (buf.length > width) throw new E(code, "ECDSA signature component wider than the curve field");
+    var out = Buffer.alloc(width);
+    buf.copy(out, width - buf.length);
+    return out;
+  }
+  return Buffer.concat([pad(r), pad(s)]);
+}
+
+module.exports = { ecdsaSigToRaw: ecdsaSigToRaw, rawToEcdsaDer: rawToEcdsaDer, ecdsaDerToP1363: ecdsaDerToP1363 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "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:171a9606-6760-469e-abba-719538a2f2ab",
+  "serialNumber": "urn:uuid:bec63d3e-7332-4a32-bcc8-ac8614e7402a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-14T02:42:50.555Z",
+    "timestamp": "2026-07-14T07:20:40.274Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.16",
+      "bom-ref": "@blamejs/pki@0.2.18",
       "type": "application",
       "name": "pki",
-      "version": "0.2.16",
+      "version": "0.2.18",
       "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.16",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.18",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.16",
+      "ref": "@blamejs/pki@0.2.18",
       "dependsOn": []
     }
   ]