@blamejs/pki 0.2.15 → 0.2.17

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.2.17 — 2026-07-14
+
+Post-quantum SLH-DSA joins CMS SignedData: pki.cms.sign and pki.cms.verify now sign and verify with all twelve FIPS 205 SLH-DSA parameter sets (RFC 9814), freely mixed with the classical and ML-DSA signers in one message.
+
+### Added
+
+- pki.cms.sign and pki.cms.verify sign and verify a CMS SignedData with the twelve pure FIPS 205 SLH-DSA parameter sets (id-slh-dsa-sha2-128s/f, -192s/f, -256s/f and the SHAKE equivalents), RFC 9814: pure mode, empty context, AlgorithmIdentifier parameters absent, over attached or detached content and single or multiple signers -- freely mixed with RSA, RSASSA-PSS, ECDSA, EdDSA, and ML-DSA signers in one message. The signer identifier is issuerAndSerialNumber or subjectKeyIdentifier, and the output is a DER Buffer or PEM.
+- The CMS message-digest algorithm for an SLH-DSA signer is fixed to the parameter set's paired digest (RFC 9814 section 4); signing emits it automatically and rejects a caller digest that contradicts the set, so the SignedData carries the conformant digest for the chosen parameter set.
+
+### Changed
+
+- CMS signature verification's one-shot signer-key agreement check (a single algorithm identifier naming both the key and the signature) now covers SLH-DSA alongside EdDSA and ML-DSA: an SLH-DSA SignerInfo whose signer certificate public-key parameter set disagrees with the signatureAlgorithm fails closed with a typed error.
+
+## v0.2.16 — 2026-07-13
+
+Post-quantum ML-DSA joins CMS SignedData: pki.cms.sign and pki.cms.verify now sign and verify with ML-DSA-44/65/87 (RFC 9882), freely mixed with the classical signers in one message.
+
+### Added
+
+- pki.cms.sign and pki.cms.verify sign and verify a CMS SignedData with the post-quantum ML-DSA-44, ML-DSA-65, and ML-DSA-87 (RFC 9882): pure mode, empty context, AlgorithmIdentifier parameters absent, over attached or detached content and single or multiple signers -- freely mixed with RSA, RSASSA-PSS, ECDSA, and EdDSA signers in one message. The signer identifier is issuerAndSerialNumber or subjectKeyIdentifier, and the output is a DER Buffer or PEM.
+- The CMS message-digest algorithm for an ML-DSA signer is held to the parameter set's security strength (RFC 9882 section 3.3): SHA-512 by default and SHAKE256 optional, with SHA-256 accepted only for ML-DSA-44. A below-strength digest is refused fail-closed on both signing and verification, so a weak message digest cannot cap the collision resistance of a strong ML-DSA signature.
+
+### Changed
+
+- CMS signature verification now requires a one-shot signer (EdDSA or ML-DSA, where a single algorithm identifier names both the key and the signature) to present a signer certificate whose public-key algorithm matches the SignerInfo signatureAlgorithm; a disagreement fails closed with a typed error rather than surfacing an opaque import failure.
+
 ## v0.2.15 — 2026-07-13
 
 CMS SignedData signing arrives as pki.cms.sign, and RFC 3161 timestamp token creation as pki.tsp.sign -- the producing sides of the CMS and timestamp verifiers, emitting exactly what pki.cms.verify and OpenSSL cms -verify accept.

package/README.md

@@ -221,7 +221,7 @@ is callable today; nothing below is a stub.
 | `pki.schema.smime` | Decode S/MIME ESS signed-attribute values (RFC 5035 / RFC 8551) — `parseSigningCertificate` / `parseSigningCertificateV2` bind a signature to its signing certificate (cert hash, hash algorithm, issuer `GeneralNames` + serial), `parseSmimeCapabilities` decodes the ordered capability list, and `decodeAttribute` OID-dispatches a CMS attribute (enforcing the single-value rule, recognize-and-defer for unknown types). A companion decoder for CMS signed attributes, not an auto-routed format, fail-closed — `parseSigningCertificate`, `parseSigningCertificateV2`, `parseSmimeCapabilities`, `decodeAttribute` |
 | `pki.schema.engine` | The declarative ASN.1 structure-schema engine every format parser composes — `walk` / `encode` / `embeddedDer` plus the schema combinators |
 | `pki.path` | RFC 5280 §6 certification-path validation — `validate` runs the §6.1 state machine (signature chaining across RSA, ECDSA, EdDSA, ML-DSA, SLH-DSA and hybrid composite ML-DSA signatures — a composite is accepted only when **both** its post-quantum and traditional components verify; validity windows, name chaining, basic constraints and path length, key usage, name constraints, the certificate-policy tree) over an ordered path and a trust anchor, returning a structured verdict with per-check reason codes, and enforces a `pki.trust` anchor's per-purpose distrust-after dates and delegator purposes via `checkPurpose`; `crlChecker` supplies CRL-based revocation — including partitioned/sharded CRLs, whose §6.3.3 Distribution Point ↔ IDP correspondence lets a corresponding full-reason shard establish non-revocation — and `ocspChecker` supplies OCSP-based revocation (RFC 6960 — CertID binding, responder authorization, signature, currency) over the same pluggable hook. Pure and re-entrant, fail-closed — `validate`, `crlChecker`, `ocspChecker` |
-| `pki.cms` | RFC 5652 §5 CMS SignedData signing + signature verification — `sign(content, signers, opts)` produces a SignedData (attached or detached, one or many signers, RSA / RSASSA-PSS / ECDSA / EdDSA); it builds the signed attributes (content-type, message-digest, signing-time) as canonical DER, signs the exact §5.4 preimage, and emits a DER `Buffer` or PEM. `verify(input, opts)` parses a SignedData over the strict `pki.schema.cms` codec, locates each SignerInfo's signer certificate by its issuerAndSerialNumber or subjectKeyIdentifier, and checks the signature over the exact §5.4 preimage: when signed attributes are present it confirms the message-digest attribute equals the content digest and verifies over the DER re-encoding of the SignedAttributes (the on-wire `[0]` tag replaced by a universal SET OF), otherwise directly over the content. It returns a per-signer verdict with the matched signer certificate; it does not chain that certificate to a trust anchor — that is the caller's step through `pki.path.validate`. Fail-closed with typed `cms/*` errors — `sign`, `verify` |
+| `pki.cms` | RFC 5652 §5 CMS SignedData signing + signature verification — `sign(content, signers, opts)` produces a SignedData (attached or detached, one or many signers, RSA / RSASSA-PSS / ECDSA / EdDSA and the post-quantum ML-DSA-44/65/87 (RFC 9882) and SLH-DSA (all twelve FIPS 205 sets, RFC 9814)); it builds the signed attributes (content-type, message-digest, signing-time) as canonical DER, signs the exact §5.4 preimage, and emits a DER `Buffer` or PEM. `verify(input, opts)` parses a SignedData over the strict `pki.schema.cms` codec, locates each SignerInfo's signer certificate by its issuerAndSerialNumber or subjectKeyIdentifier, and checks the signature over the exact §5.4 preimage: when signed attributes are present it confirms the message-digest attribute equals the content digest and verifies over the DER re-encoding of the SignedAttributes (the on-wire `[0]` tag replaced by a universal SET OF), otherwise directly over the content. It returns a per-signer verdict with the matched signer certificate; it does not chain that certificate to a trust anchor — that is the caller's step through `pki.path.validate`. Fail-closed with typed `cms/*` errors — `sign`, `verify` |
 | `pki.tsp` | RFC 3161 timestamp token creation — `sign(messageImprint, tsa, opts)` produces a TimeStampToken: a CMS SignedData (over `pki.cms.sign`) whose content is a `TSTInfo` carrying the timestamped message imprint, the TSA policy, a serial number, and `genTime` (with optional accuracy / nonce / ordering), plus the RFC 3161 §2.4.2 signing-certificate attribute binding the token to the TSA certificate. The producing side of `pki.schema.tsp.parseToken`; SHA-2 imprints, and any `pki.cms.sign` TSA key — `sign` |
 | `pki.ct` | RFC 6962 Certificate Transparency SCTs — `parseSctList` decodes the `SignedCertificateTimestampList` a certificate or OCSP response carries in the SCT extension (a TLS-presentation-language payload inside the §3.3 double DER wrap) into per-SCT log id, exact `timestamp` (BigInt), named signature algorithm, and raw signature; `reconstructSignedData` rebuilds the exact `digitally-signed` preimage; `verifySct` verifies an SCT signature against a log's public key by reconstructing the signed data, routing an ECDSA signature through the strict DER-conformance gate, and verifying through the crypto engine — resolving true or false, and throwing a typed error on a structural fault. Structure decoded, crypto fail-closed — `parseSctList`, `reconstructSignedData`, `verifySct` |
 | `pki.merkle` | RFC 6962 / RFC 9162 Merkle-tree proof verification — `leafHash` / `nodeHash` / `emptyRootHash` build the domain-separated (0x00 leaf / 0x01 node) SHA-256 tree hashes; `verifyInclusion` folds an audit proof back to a root and `verifyConsistency` reconstructs both the old and new root (the append-only guarantee), each constant-time-compared to a trusted checkpoint root. Fail-closed on bad geometry, sync hashing, transport-free — `leafHash`, `nodeHash`, `emptyRootHash`, `verifyInclusion`, `verifyConsistency` |

package/lib/asn1-der.js

@@ -109,6 +109,7 @@ function _className(bits) {
     case CLASS_APPLICATION: return "application";
     case CLASS_CONTEXT:     return "context";
     case CLASS_PRIVATE:     return "private";
+    // Coverage residual -- tagClassBits is (first & 0xc0), always one of the 4 enumerated class values; the default arm is unreachable defensive code.
     default:                return "universal";
   }
 }
@@ -394,6 +395,7 @@ function _readIntegerLikeContent(node, typeName, who) {
     if (c[0] === 0xff && (c[1] & 0x80) !== 0) throw new Asn1Error("asn1/non-minimal-integer", "non-minimal negative " + typeName);
   }
   var neg = (c[0] & 0x80) !== 0;
+  // Coverage residual -- the c.length===0 guard above throws, so c.length is always >=1 here; the 0n alternate is unreachable.
   var mag = c.length ? BigInt("0x" + Buffer.from(c).toString("hex")) : 0n;
   return neg ? mag - (1n << BigInt(c.length * 8)) : mag;
 }
@@ -734,6 +736,7 @@ function readTime(node, opts) {
   var d = new Date(0);
   d.setUTCFullYear(year, month - 1, day);
   d.setUTCHours(hour, min, sec, ms);
+  // Coverage residual -- regex-validated fields are finite integers and Date rolls over (never NaN); out-of-range is caught by the component round-trip check below.
   if (isNaN(d.getTime())) throw new Asn1Error("asn1/bad-time", "unparseable time " + JSON.stringify(s));
   // Date/setUTC* silently roll over out-of-range fields (Feb 30 -> Mar 2,
   // month 13 -> next Jan, hour 25 -> +1 day). Reject unless every component
@@ -767,6 +770,7 @@ function encodeLength(n) {
 // `children` (not `content`), so the content is those children's DER concatenated;
 // the identifier becomes the SEQUENCE tag and the length is canonical DER.
 function sequenceTlv(node) {
+  // Coverage residual -- a decoded node with content==null is always constructed with a children array; the || [] guards a non-decoder-built node and is unreachable via decode.
   var content = node.content != null ? node.content : Buffer.concat((node.children || []).map(function (c) { return c.bytes; }));
   return Buffer.concat([Buffer.from([TAGS.SEQUENCE | CONSTRUCTED_BIT]), encodeLength(content.length), content]);
 }

package/lib/cms-sign.js

@@ -32,8 +32,8 @@ function O(name) { return oid.byName(name); }
 // A digest-algorithm name -> the WebCrypto hash (sign path). SHAKE256 has no WebCrypto hash, so
 // the message digest is always computed with node:crypto (below), uniform across the family.
 var HASH = { sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
-var NODE_DIGEST = { sha256: "sha256", sha384: "sha384", sha512: "sha512", shake256: "shake256" };
-var SHAKE_OUT = { shake256: 64 };   // RFC 8419 sec. 2.3 -- Ed448 uses SHAKE256 with 512-bit output
+var NODE_DIGEST = { sha256: "sha256", sha384: "sha384", sha512: "sha512", shake128: "shake128", shake256: "shake256" };
+var SHAKE_OUT = { shake128: 32, shake256: 64 };   // SHAKE output lengths: SHAKE128 256-bit (RFC 9814 sec. 4), SHAKE256 512-bit (RFC 8419 sec. 2.3 / RFC 9814)
 var PSS_SALT = { "SHA-256": 32, "SHA-384": 48, "SHA-512": 64 };
 var ECDSA_ALG = { sha256: "ecdsaWithSHA256", sha384: "ecdsaWithSHA384", sha512: "ecdsaWithSHA512" };
 var HASH_NAME_BY_OID = {};
@@ -44,6 +44,31 @@ var EC_BY_CURVE_OID = {};
 EC_BY_CURVE_OID[O("prime256v1")] = { curve: "P-256", coordLen: 32 };
 EC_BY_CURVE_OID[O("secp384r1")] = { curve: "P-384", coordLen: 48 };
 EC_BY_CURVE_OID[O("secp521r1")] = { curve: "P-521", coordLen: 66 };
+// ML-DSA (RFC 9882): the signer cert SPKI algorithm OID -> its WebCrypto name. Registry-keyed
+// (Hard rule #2, no dotted-decimal literal). The same OID identifies both the key and the signature.
+var MLDSA_BY_OID = {};
+MLDSA_BY_OID[O("id-ml-dsa-44")] = "ML-DSA-44";
+MLDSA_BY_OID[O("id-ml-dsa-65")] = "ML-DSA-65";
+MLDSA_BY_OID[O("id-ml-dsa-87")] = "ML-DSA-87";
+// The message-digest algorithms suitable for each ML-DSA parameter set (RFC 9882 sec. 3.3 /
+// Table 1): a digest MUST offer at least the parameter set's collision strength (lambda) and at
+// least 2*lambda bits of output. SHA-512 is suitable for all sets; SHAKE256 (512-bit output) too.
+// Below-strength digests downgrade the signature to the weaker of the two (the whichever-is-lower
+// rule), so they are refused fail-closed on sign and verify -- the RFC's "verifiers MAY reject".
+var MLDSA_SUITABLE_DIGEST = {
+  "ML-DSA-44": { sha256: 1, sha384: 1, sha512: 1, shake256: 1 },
+  "ML-DSA-65": { sha384: 1, sha512: 1, shake256: 1 },
+  "ML-DSA-87": { sha512: 1, shake256: 1 },
+};
+// SLH-DSA (RFC 9814): the twelve pure FIPS 205 sets. The signer cert SPKI algorithm OID -> its
+// WebCrypto set name ("SLH-DSA-"+SET, mirroring webcrypto's SLH_DSA_NODE / path-validate) + the
+// RFC 9814 sec. 4 pinned message digest for that set. The sig and key share one OID; the digest is
+// FIXED per set (no caller choice, unlike ML-DSA's suitable-set). Registry-keyed (Hard rule #2).
+var SLHDSA_BY_OID = {};
+[["sha2-128s", "sha256"], ["sha2-128f", "sha256"], ["sha2-192s", "sha512"], ["sha2-192f", "sha512"],
+ ["sha2-256s", "sha512"], ["sha2-256f", "sha512"], ["shake-128s", "shake128"], ["shake-128f", "shake128"],
+ ["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] }; });
 
 var OID_DATA = O("data");
 var OID_SIGNED_DATA = O("signedData");
@@ -98,7 +123,7 @@ function _digest(digestName, content) {
 // Resolve the sign scheme from the signer certificate's public-key algorithm + per-signer opts:
 // the digest, the digestAlgorithm and signatureAlgorithm AlgorithmIdentifiers (with the exact
 // parameter shape cms.verify requires), and the WebCrypto import + sign algorithms.
-function _scheme(cert, so) {
+function _scheme(cert, so, noSignedAttrs) {
   var alg = cert.subjectPublicKeyInfo.algorithm;
   var keyOid = alg.oid;
   if (keyOid === O("rsaEncryption") || keyOid === O("rsassaPss")) {
@@ -131,6 +156,34 @@ function _scheme(cert, so) {
     if (!NODE_DIGEST[dd]) throw _err("cms/unsupported-algorithm", "unsupported " + name + " digest algorithm " + JSON.stringify(dd));
     return { digest: dd, digestAlgId: _algId(dd, "absent"), sigAlgId: _algId(name, "absent"), imp: { name: name }, sign: { name: name }, ecdsaDer: false };
   }
+  if (MLDSA_BY_OID[keyOid]) {
+    // ML-DSA (RFC 9882): a one-shot post-quantum signature, pure mode, empty context. The signature
+    // covers the same sec. 5.4 preimage as every other scheme; digestAlgorithm names the message-
+    // digest algorithm (SHA-512 by default -- the sec. 3.3 MUST / interop default), which must be
+    // suitable for the parameter set (Q1 -- enforced on sign, refusing a below-strength digest).
+    var mlName = MLDSA_BY_OID[keyOid];
+    // RFC 9882 sec. 3.3: without signed attributes the digestAlgorithm has no meaning, but the
+    // signer MUST still emit SHA-512 to avoid an interoperability failure -- so force it (ignoring
+    // any caller digestAlgorithm) rather than carry a value a strict peer would reject. With signed
+    // attributes the digest must be suitable for the parameter set (Q1 -- enforced on sign).
+    var md;
+    if (noSignedAttrs) {
+      md = "sha512";
+    } else {
+      md = so.digestAlgorithm || "sha512";
+      if (!NODE_DIGEST[md]) throw _err("cms/unsupported-algorithm", "unsupported ML-DSA message digest " + JSON.stringify(md));
+      if (!MLDSA_SUITABLE_DIGEST[mlName][md]) throw _err("cms/unsupported-algorithm", "the " + md + " message digest is below the security strength of " + mlName + " (RFC 9882 sec. 3.3)");
+    }
+    return { digest: md, digestAlgId: _algId(md, "absent"), sigAlgId: _algId(oid.name(keyOid), "absent"), imp: { name: mlName }, sign: { name: mlName }, ecdsaDer: false };
+  }
+  if (SLHDSA_BY_OID[keyOid]) {
+    // SLH-DSA (RFC 9814): a one-shot post-quantum signature, pure mode, empty context. The message
+    // digest is FIXED per parameter set (sec. 4) -- emit it, and reject a contradicting caller
+    // digestAlgorithm fail-closed rather than carry a non-conformant digest.
+    var slh = SLHDSA_BY_OID[keyOid];
+    if (so.digestAlgorithm && so.digestAlgorithm !== slh.digest) throw _err("cms/bad-input", "SLH-DSA " + slh.wc + " requires the " + slh.digest + " message digest (RFC 9814 sec. 4); digestAlgorithm " + JSON.stringify(so.digestAlgorithm) + " conflicts");
+    return { digest: slh.digest, digestAlgId: _algId(slh.digest, "absent"), sigAlgId: _algId(oid.name(keyOid), "absent"), imp: { name: slh.wc }, sign: { name: slh.wc }, ecdsaDer: false };
+  }
   throw _err("cms/unsupported-algorithm", "unsupported signer key algorithm " + keyOid);
 }
 
@@ -182,7 +235,7 @@ function _buildSignerInfo(signer, content, eContentType, opts) {
   var so = signer || {};
   var certDer = _normCertDer(so.cert);
   var cert = x509.parse(certDer);
-  var scheme = _scheme(cert, so);
+  var scheme = _scheme(cert, so, opts.signedAttributes === false);
   var useSki = opts.sid === "ski";
   var sid = useSki
     ? b.contextPrimitive(0, _skiValue(cert))                                       // [0] IMPLICIT SubjectKeyIdentifier
@@ -321,4 +374,7 @@ function _toBuf(v, what) {
 //   * `_assertKeyMatchesScheme`'s `!ka.hash` guard -- an `imp.hash` is set only for an RSA
 //     scheme, which requires `ka.name` to already equal the RSA name (else the earlier name
 //     check throws); an RSA CryptoKey always carries a `hash`, so `!ka.hash` never fires.
-module.exports = { sign: sign };
+// MLDSA_SUITABLE_DIGEST is shared with cms-verify (which requires this module) so the per-
+// parameter-set digest-strength policy has ONE home -- a digest accepted on sign is exactly the
+// set accepted on verify, and neither side can drift from the other (RFC 9882 sec. 3.3).
+module.exports = { sign: sign, MLDSA_SUITABLE_DIGEST: MLDSA_SUITABLE_DIGEST, SLHDSA_BY_OID: SLHDSA_BY_OID };

package/lib/cms-verify.js

@@ -13,10 +13,14 @@
  *   confirms the message-digest attribute equals the digest of the content and verifies the
  *   signature over the DER re-encoding of the SignedAttributes (the on-wire `[0]` tag replaced
  *   by a universal SET OF); otherwise it verifies directly over the content. Attached and
- *   detached content, single and multiple signers, and RSA / RSASSA-PSS / ECDSA / EdDSA are
- *   covered. It reports a per-signer verdict; it does NOT chain the signer certificate to a
- *   trust anchor -- that is the caller's step through `pki.path.validate`.
+ *   detached content, single and multiple signers, and RSA / RSASSA-PSS / ECDSA / EdDSA and the
+ *   post-quantum ML-DSA (ML-DSA-44/65/87, RFC 9882) plus SLH-DSA (the twelve FIPS 205 sets, RFC 9814)
+ *   are covered. It reports a per-signer verdict;
+ *   it does NOT chain the signer certificate to a trust anchor -- that is the caller's step through
+ *   `pki.path.validate`.
  * @spec RFC 5652
+ * @spec RFC 9882
+ * @spec RFC 9814
  * @card Verify a CMS SignedData signature (S/MIME, timestamps, code signing).
  */
 
@@ -29,6 +33,8 @@ var webcrypto = require("./webcrypto");
 var subtle = webcrypto.webcrypto.subtle;
 var edwardsPoint = require("./edwards-point");
 var cmsSign = require("./cms-sign");
+var MLDSA_SUITABLE_DIGEST = cmsSign.MLDSA_SUITABLE_DIGEST;   // shared sign/verify digest-strength policy (RFC 9882 sec. 3.3)
+var SLHDSA_BY_OID = cmsSign.SLHDSA_BY_OID;                   // shared SLH-DSA set -> { wc, digest } (RFC 9814 sec. 4 pinned digest)
 var validator = require("./validator-all");
 var guard = require("./guard-all");
 var frameworkError = require("./framework-error");
@@ -43,7 +49,7 @@ var OID_CONTENT_TYPE = oid.byName("contentType");
 var DIGEST_HASH = { sha1: "SHA-1", sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
 // SHAKE256 (RFC 8419 sec. 2.3, the Ed448 message digest) has no WebCrypto hash, so it is computed
 // with node:crypto; its 512-bit (64-byte) output length is fixed by the profile.
-var SHAKE_OUT = { shake256: 64 };
+var SHAKE_OUT = { shake128: 32, shake256: 64 };   // SHAKE128 256-bit (RFC 9814 sec. 4), SHAKE256 512-bit
 // Is `name` a message-digest algorithm this verifier supports (SHA-2 family or SHAKE256)?
 function _supportedDigest(name) { return !!(DIGEST_HASH[name] || SHAKE_OUT[name]); }
 // The digest of `content` under the named algorithm, resolved to a Buffer.
@@ -61,8 +67,14 @@ var SIG_SCHEME = {
   rsaEncryption: { kind: "rsa", params: "null" },
   rsassaPss: { kind: "rsapss" },
   ecPublicKey: { kind: "ec", params: "absent" },
-  Ed25519: { kind: "eddsa", name: "Ed25519", params: "absent" },
-  Ed448: { kind: "eddsa", name: "Ed448", params: "absent" },
+  // One-shot families (EdDSA, ML-DSA): the same OID identifies the key and the signature, so the
+  // signer cert SPKI algorithm OID MUST equal the signatureAlgorithm OID -- `sameKeyOid` enables
+  // that agreement check (RFC 8410 / RFC 9882; enforced in _verifyAgainstCandidates).
+  Ed25519: { kind: "eddsa", name: "Ed25519", params: "absent", sameKeyOid: true },
+  Ed448: { kind: "eddsa", name: "Ed448", params: "absent", sameKeyOid: true },
+  "id-ml-dsa-44": { kind: "mldsa", name: "ML-DSA-44", params: "absent", sameKeyOid: true },
+  "id-ml-dsa-65": { kind: "mldsa", name: "ML-DSA-65", params: "absent", sameKeyOid: true },
+  "id-ml-dsa-87": { kind: "mldsa", name: "ML-DSA-87", params: "absent", sameKeyOid: true },
   sha1WithRSAEncryption: { kind: "rsa", hash: "SHA-1", params: "null" },
   sha256WithRSAEncryption: { kind: "rsa", hash: "SHA-256", params: "null" },
   sha384WithRSAEncryption: { kind: "rsa", hash: "SHA-384", params: "null" },
@@ -72,6 +84,12 @@ var SIG_SCHEME = {
   ecdsaWithSHA384: { kind: "ec", hash: "SHA-384", params: "absent" },
   ecdsaWithSHA512: { kind: "ec", hash: "SHA-512", params: "absent" },
 };
+// SLH-DSA (RFC 9814): the twelve pure FIPS 205 sets, seeded like webcrypto's SLH_DSA_NODE. Each is
+// a one-shot family (kind "slhdsa"), params absent, sig-OID == key-OID (sameKeyOid). The WebCrypto
+// name is "SLH-DSA-"+SET, matching path-validate's transform (drift rule sec. 5 -- one name map).
+["sha2-128s", "sha2-128f", "sha2-192s", "sha2-192f", "sha2-256s", "sha2-256f",
+ "shake-128s", "shake-128f", "shake-192s", "shake-192f", "shake-256s", "shake-256f"
+].forEach(function (s) { SIG_SCHEME["id-slh-dsa-" + s] = { kind: "slhdsa", name: "SLH-DSA-" + s.toUpperCase(), params: "absent", sameKeyOid: true, digest: SLHDSA_BY_OID[oid.byName("id-slh-dsa-" + s)].digest }; });
 // The signatureAlgorithm parameters match the algorithm's fixed shape (RFC 5754). A DER NULL
 // is exactly `05 00`; "absent" is the parameters field omitted entirely.
 function _isDerNull(p) { return Buffer.isBuffer(p) && p.length === 2 && p[0] === 0x05 && p[1] === 0x00; }
@@ -111,7 +129,7 @@ function _findSignerCerts(sid, parsedCerts) {
 // through to the next -- so a colliding certificate cannot make a valid signature read invalid.
 // When no candidate verifies, a plain false is a code-less verdict; the last structural fault's
 // code is surfaced if one occurred (so the diagnostic is not lost).
-function _verifyAgainstCandidates(scheme, sigHash, sigBytes, signedBytes, sid, candidates, pssSalt) {
+function _verifyAgainstCandidates(scheme, sigHash, sigBytes, signedBytes, sid, candidates, pssSalt, expectedKeyOid) {
   var lastErr = null;
   function attempt(idx) {
     if (idx >= candidates.length) {
@@ -119,6 +137,13 @@ function _verifyAgainstCandidates(scheme, sigHash, sigBytes, signedBytes, sid, c
         : { ok: false, sid: sid, cert: candidates[0].der };
     }
     var c = candidates[idx];
+    // One-shot family (EdDSA/ML-DSA): the signer cert public-key algorithm OID MUST equal the
+    // SignerInfo signatureAlgorithm OID. A candidate whose SPKI disagrees is skipped with a precise
+    // verdict, rather than a foreign webcrypto/data throw from importing under the wrong name.
+    if (expectedKeyOid && c.cert.subjectPublicKeyInfo.algorithm.oid !== expectedKeyOid) {
+      lastErr = _err("cms/unsupported-algorithm", "the signer certificate public-key algorithm does not match the SignerInfo signatureAlgorithm");
+      return attempt(idx + 1);
+    }
     return Promise.resolve()
       .then(function () { return _verifySignature(scheme, sigHash, sigBytes, c.cert.subjectPublicKeyInfo.bytes, signedBytes, _certCurveOid(c.cert), pssSalt); })
       .then(function (ok) { return ok === true ? { ok: true, sid: sid, cert: c.der } : attempt(idx + 1); },
@@ -225,6 +250,14 @@ function _verifySignature(scheme, hashName, sigBytes, spki, signedBytes, curveOi
     return subtle.importKey("spki", spki, { name: "ECDSA", namedCurve: ec.curve }, false, ["verify"])
       .then(function (k) { return subtle.verify({ name: "ECDSA", hash: hashName }, k, raw, signedBytes); });
   }
+  if (scheme.kind === "mldsa" || scheme.kind === "slhdsa") {
+    // ML-DSA (RFC 9882) / SLH-DSA (RFC 9814): a one-shot post-quantum verify, pure mode, empty
+    // context -- no external signature hash and no Edwards-point validation (FIPS 204 sec. 5.3 /
+    // FIPS 205 sec. 10.3; node structurally validates the SPKI on import). The signature is raw and
+    // fixed-length (not ECDSA-DER).
+    return subtle.importKey("spki", spki, { name: scheme.name }, false, ["verify"])
+      .then(function (k) { return subtle.verify({ name: scheme.name }, k, sigBytes, signedBytes); });
+  }
   // EdDSA -- the WebCrypto name follows the signing key's SPKI OID (Ed25519 / Ed448). node/
   // OpenSSL imports any Ed25519/Ed448 SPKI without validating the point, and a low-order (e.g.
   // all-zeroes) key verifies a forged signature -- so reject a non-full-order point first.
@@ -288,15 +321,36 @@ function _verifyOne(si, content, eContentType, parsedCerts) {
   if (scheme.params && !_algParamsOk(scheme.params, si.signatureAlgorithm.parameters)) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "the " + si.signatureAlgorithm.name + " signature algorithm parameters must be " + (scheme.params === "null" ? "DER NULL (RFC 4055)" : "absent (RFC 5758/8410)") });
   // The digestAlgorithm parameters, when present, MUST be a DER NULL (RFC 5754 sec. 2 accepts
   // absent OR NULL; a present non-NULL is malformed and, being outside the signed preimage,
-  // must fail closed like the signatureAlgorithm parameters above).
+  // must fail closed like the signatureAlgorithm parameters above). EXCEPT for an ML-DSA
+  // SignerInfo WITHOUT signed attributes: RFC 9882 sec. 3.3 says the whole digestAlgorithm field
+  // has no meaning there and MUST be ignored, so neither its parameters nor its name may reject.
   var dp = si.digestAlgorithm.parameters;
-  if (dp !== null && dp !== undefined && !_isDerNull(dp)) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "the " + si.digestAlgorithm.name + " digest algorithm parameters must be absent or DER NULL (RFC 5754 sec. 2)" });
+  var mldsaNoAttrs = scheme.kind === "mldsa" && !si.signedAttrsBytes;
+  if (!mldsaNoAttrs && dp !== null && dp !== undefined && !_isDerNull(dp)) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "the " + si.digestAlgorithm.name + " digest algorithm parameters must be absent or DER NULL (RFC 5754 sec. 2)" });
+  // A SHAKE digest algorithm identifier (id-shake128 / id-shake256) carries NO parameters at all --
+  // not even a DER NULL (RFC 8702 sec. 3.1) -- so for a one-shot PQC SignerInfo (ML-DSA per RFC 9882,
+  // SLH-DSA per RFC 9814 sec. 4, both citing RFC 8702) with signed attributes a present SHAKE
+  // parameter fails closed. The SHA-2 digests (id-sha256/384/512) follow RFC 5754, which requires a
+  // verifier to accept absent OR NULL (the generic rule above); the RFCs' omit-on-encode rule binds
+  // the signer, not the verifier, so a SHA-2 NULL is not tightened here.
+  if ((scheme.kind === "mldsa" || scheme.kind === "slhdsa") && si.signedAttrsBytes && (si.digestAlgorithm.name === "shake128" || si.digestAlgorithm.name === "shake256") && dp !== null && dp !== undefined) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "a SHAKE digestAlgorithm carries no parameters (RFC 8702 sec. 3.1)" });
   var sigHash = pss ? pss.hash : (scheme.hash || digestHash);
   // The signature hash is required for every non-EdDSA scheme (EdDSA hashes internally);
   // the content digest is required whenever signed attributes are present, for every scheme
   // (the message-digest attribute is computed under digestAlgorithm). Either gap is a
   // fail-closed unsupported-algorithm verdict, never a foreign-domain throw from the digest.
-  if ((scheme.kind !== "eddsa" && !sigHash) || (si.signedAttrsBytes && !_supportedDigest(si.digestAlgorithm.name))) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "unsupported digest algorithm " + JSON.stringify(si.digestAlgorithm.name) });
+  if ((scheme.kind !== "eddsa" && scheme.kind !== "mldsa" && scheme.kind !== "slhdsa" && !sigHash) || (si.signedAttrsBytes && !_supportedDigest(si.digestAlgorithm.name))) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "unsupported digest algorithm " + JSON.stringify(si.digestAlgorithm.name) });
+  // ML-DSA (RFC 9882 sec. 3.3): with signed attributes present, the message-digest algorithm MUST
+  // meet the parameter set's security strength -- a below-strength digest is the weaker link and is
+  // rejected fail-closed (the RFC's "verifiers MAY reject", taken by the strict-verifier posture).
+  // With signed attributes absent the digestAlgorithm has no meaning (sec. 3.3) and is not checked.
+  if (scheme.kind === "mldsa" && si.signedAttrsBytes && !MLDSA_SUITABLE_DIGEST[scheme.name][si.digestAlgorithm.name]) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "the " + si.digestAlgorithm.name + " message digest is below the security strength of " + scheme.name + " (RFC 9882 sec. 3.3)" });
+  // RFC 9814 sec. 4: an SLH-DSA SignerInfo's message-digest algorithm is the one paired with the
+  // parameter set (the sec. 4 list, always at least twice the tree-hash size); the signer emits it
+  // and this strict verifier requires it, so a digest that does not match the set's paired hash fails
+  // closed -- otherwise a signer could compute the message-digest attribute under a weaker hash the
+  // set does not pair. Gated on signed attributes (absent -> the digest is not consulted, sec. 4).
+  if (scheme.kind === "slhdsa" && si.signedAttrsBytes && si.digestAlgorithm.name !== scheme.digest) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "SLH-DSA " + scheme.name + " requires the " + scheme.digest + " message digest (RFC 9814 sec. 4)" });
   var signers = _findSignerCerts(si.sid, parsedCerts);
   if (!signers.length) return Promise.resolve({ ok: false, code: "cms/signer-cert-not-found", sid: si.sid, message: "no certificate matches this SignerInfo's signer identifier" });
   var sigBytes = _toBuf(si.signature, "the SignerInfo signature");
@@ -337,7 +391,7 @@ function _verifyOne(si, content, eContentType, parsedCerts) {
     });
   }).then(function (signedBytes) {
     if (signedBytes && signedBytes.mismatch) return { ok: false, code: signedBytes.mismatch.code, sid: si.sid, cert: signers[0].der, message: signedBytes.mismatch.message };
-    return _verifyAgainstCandidates(scheme, sigHash, sigBytes, signedBytes, si.sid, signers, pss ? pss.saltLength : 0);
+    return _verifyAgainstCandidates(scheme, sigHash, sigBytes, signedBytes, si.sid, signers, pss ? pss.saltLength : 0, scheme.sameKeyOid ? oid.byName(si.signatureAlgorithm.name) : null);
   });
 }
 
@@ -347,6 +401,8 @@ function _verifyOne(si, content, eContentType, parsedCerts) {
  * @since      0.2.14
  * @status     experimental
  * @spec       RFC 5652
+ * @spec       RFC 9882
+ * @spec       RFC 9814
  * @defends    cms-signature-forgery (CWE-347)
  * @related    pki.schema.cms.parse, pki.path.validate
  *
@@ -354,7 +410,9 @@ function _verifyOne(si, content, eContentType, parsedCerts) {
  * `Buffer`, or a parsed `pki.schema.cms` object. Returns `{ valid, signers }` where each
  * `signers[i]` is `{ ok, sid, cert }` (`cert` the matched signer certificate DER) or carries
  * a `code` on a structural failure; `valid` is true when there is at least one signer and
- * every signer verified.
+ * every signer verified. RSA (PKCS#1 v1.5 and RSASSA-PSS), ECDSA, EdDSA, and the post-quantum
+ * ML-DSA (ML-DSA-44/65/87, RFC 9882) and SLH-DSA (the twelve FIPS 205 sets, RFC 9814) -- pure mode,
+ * empty context -- signatures are recognized.
  *
  * @opts  content  The detached content (a `Buffer`) when the SignedData carries no
  *                 encapsulated eContent. Required for a detached signature.
@@ -419,6 +477,8 @@ function _addCert(out, der) {
  * @since      0.2.15
  * @status     experimental
  * @spec       RFC 5652
+ * @spec       RFC 9882
+ * @spec       RFC 9814
  * @related    pki.cms.verify, pki.schema.cms.parse
  *
  * Produce a CMS SignedData (RFC 5652 sec. 5) over `content` (a `Buffer`) -- the structure
@@ -429,7 +489,9 @@ function _addCert(out, der) {
  * signature covers the RFC 5652 sec. 5.4 preimage: with signed attributes (the default) the
  * message-digest attribute is bound to the content digest and the signature is over the
  * canonical DER SET OF SignedAttributes; otherwise over the content directly. RSA (PKCS#1 v1.5
- * and, with `pss`, RSASSA-PSS), ECDSA (P-256/384/521), Ed25519, and Ed448 are covered.
+ * and, with `pss`, RSASSA-PSS), ECDSA (P-256/384/521), Ed25519, Ed448, and the post-quantum ML-DSA
+ * (ML-DSA-44/65/87, RFC 9882) and SLH-DSA (the twelve FIPS 205 sets, RFC 9814 -- the message digest
+ * pinned per parameter set) are covered.
  *
  * @opts  detached          Omit the encapsulated content (a detached signature; the verifier
  *                          supplies the content). Default false.

package/lib/inspect.js

@@ -63,6 +63,12 @@ function _hexColon(buf, opts) {
   return lines.join("\n");
 }
 
+// Coverage residual -- two _hexColon default arms are unreachable through the public API:
+//   * `opts = opts || {}` -- all call sites pass an explicit opts object literal, so the
+//     `|| {}` default never fires.
+//   * `" ".repeat(opts.indent || 0)` -- every wrap-mode caller passes a positive indent
+//     (pad.length + 8 >= 8, or inner.length == 16), so `opts.indent` is never falsy.
+
 // Control-byte neutralization for a GeneralName string value routes through the
 // guard family (the guard-shape-reinlined detector protects the shape).
 // @guard-via guard\.name\.escape
@@ -217,6 +223,28 @@ function _gnRaw(buf) {
   } catch (_e) { return _hexColon(buf, {}); }
 }
 
+// Coverage residual -- the GeneralName render fallbacks are unreachable because the strict
+// generalName decoder and each caller already narrow the shape (the _gnRaw catch above is
+// separately documented):
+//   * _ipString `if (!Buffer.isBuffer(buf)) return "";` -- every caller passes a Buffer (the
+//     recursion slices a Buffer, _gn guards Buffer.isBuffer(g.value), _gnRaw passes
+//     asn1.decode(...).content).
+//   * _ipString trailing `return _hexColon(buf, {});` -- generalName enforces iPAddress to
+//     4/16 octets (8/32 for a name-constraints subtree base), so length is only ever 4/8/16/32.
+//   * _gn `if (!g || typeof g !== "object") return "";` -- every _gn call maps a decoder-produced
+//     GeneralName object; the decoders never emit a null element.
+//   * _gn directoryName `: ((g.value && g.value.dn) || "")` -- a decoded directoryName [4] always
+//     carries a Name with an rdns array, so the rdns arm is always taken.
+//   * _gn otherName `: "<unsupported>"` -- a decoded GeneralName always carries its raw bytes TLV.
+//   * _gn `|| ("tag" + t)` -- GeneralName CHOICE tags are 0..8, all mapped in NAMES.GENERAL_NAME;
+//     generalName rejects a tag outside 0..8.
+//   * _gn `? _hexColon(g.value, {})` -- iPAddress [7] is the only choice whose decoded value is a
+//     Buffer, handled at the t === 7 branch before this ternary; other tags' value is string or null.
+//   * _gn trailing `: ""` -- a decoded GeneralName always carries a bytes Buffer, so the
+//     Buffer.isBuffer(g.bytes) arm is always taken.
+//   * _gnRaw `if (!Buffer.isBuffer(buf)) return "";` -- the sole caller (the CRL-DP fullName loop)
+//     guards Buffer.isBuffer(nm) before calling _gnRaw.
+
 // Shared value renderers reused by more than one extension key.
 function _renderAltName(decoded, inner) {
   return inner + (decoded.names || []).map(_gn).join(", ");
@@ -254,6 +282,18 @@ function _renderCrlDp(decoded, inner) {
   return dpLines.join("\n");
 }
 
+// Coverage residual -- the shared alt-name / CRL-DP render fallbacks are unreachable because the
+// strict decoders already narrow the shape:
+//   * _renderAltName `(decoded.names || [])` -- the subjectAltName/issuerAltName decoder always
+//     yields a names array.
+//   * _renderCrlDp `(decoded || [])` -- the cRLDistributionPoints/freshestCRL decoder always
+//     yields an array.
+//   * _renderCrlDp `: _gn(nm)` -- distributionPointName surfaces fullName entries as raw
+//     GeneralName Buffers, so Buffer.isBuffer(nm) is always true.
+//   * _renderCrlDp `if (!wrote) ... "(distribution point)"` -- crlDistributionPoints throws unless
+//     a distributionPoint (always fullName/rdn) or cRLIssuer (sets wrote) is present, so !wrote
+//     never holds.
+
 // Declarative extension-value renderer registry: extension name -> (decoded, inner) ->
 // text. Data-driven dispatch (the schema family's "registry, not switch" shape) so a
 // new extension is a row rather than another hand-coded branch, and the set an
@@ -365,6 +405,35 @@ var EXT_RENDERERS = {
   },
 };
 
+// Coverage residual -- the EXT_RENDERERS entry fallbacks are unreachable because each shared
+// decoder (and asn1.read.oid) already narrows the shape before the renderer runs:
+//   * extKeyUsage `catch (_e) { /* unregistered EKU OID */ }` and certificatePolicies
+//     `catch (_e) { /* unregistered qualifier */ }` -- oid.name returns undefined (never throws)
+//     for a well-formed unregistered OID; it throws only on a non-dotted argument, and both OIDs
+//     come from asn1.read.oid (always a valid dotted OID).
+//   * certificatePolicies `(asn1.decode(p.qualifiersBytes).children || [])` -- asn1.decode of the
+//     assertPolicyQualifiers-validated qualifiers SEQUENCE always yields a children array.
+//   * certificatePolicies `: Buffer.alloc(0)` -- assertPolicyQualifiers requires every
+//     PolicyQualifierInfo to be a 2-child SEQUENCE, so pqi.children[1] is always a present node
+//     carrying a bytes Buffer.
+//   * certificatePolicies outer `catch (_e) { ... _hexColon(p.qualifiersBytes, {}) ... }` --
+//     certificatePolicies already validated qualifiersBytes as a SEQUENCE of 2-child PQIs each
+//     leading with a valid OID, so the re-decode + asn1.read.oid cannot throw.
+//   * policyConstraints `: inner + "(empty)"` -- policyConstraints rejects an empty SEQUENCE
+//     (>= 1 context field), so requireExplicitPolicy or inhibitPolicyMapping is non-null;
+//     pc.length is never 0.
+//   * SCT `(decoded.scts || [])` / `(decoded.unknownScts || [])` -- ct.parseSctList always returns
+//     both arrays.
+//   * SCT `: 0` -- every scts entry is a decoded v1 SCT with numeric version 0 (unknown-version
+//     SCTs go to unknownScts and are not iterated here).
+//   * SCT `: inner + "(empty SCT list)"` -- ct.parseSctList rejects an empty list and routes every
+//     SerializedSCT into scts/unknownScts, so at least one line is always emitted.
+//   * subjectKeyIdentifier `: (decoded.bytes || Buffer.alloc(0))` -- the subjectKeyIdentifier
+//     decoder returns the KeyIdentifier as a Buffer, so Buffer.isBuffer(decoded) is always true.
+//   * authorityKeyIdentifier `: BigInt(decoded.authorityCertSerialNumber)` -- the AKI decoder reads
+//     authorityCertSerialNumber via asn1.read.integerImplicit (a bigint), so typeof === "bigint"
+//     is always true.
+
 function _renderExtValue(ext, decoded, inner) {
   var fn = EXT_RENDERERS[ext.name];
   return fn ? fn(decoded, inner) : null;   // no registered renderer -> caller hex-dumps
@@ -476,6 +545,8 @@ function certificate(input) {
   L.push("        Subject: " + _dnString(c.subject));
   L.push("        Subject Public Key Info:");
   L.push(_keyBlock(c.subjectPublicKeyInfo, "            "));
+  // Coverage residual -- `c.extensions || []` is unreachable: both input paths guarantee an array
+  // (x509.parse yields one; the pre-parsed fast path requires Array.isArray(extensions) in _looksParsed).
   if ((c.extensions || []).length) {
     L.push("        X509v3 extensions:");
     c.extensions.forEach(function (ext) { L.push(_extension(ext, "            ")); });

package/lib/oid.js

@@ -284,7 +284,7 @@ var FAMILIES = {
 
   // NIST hash functions (SHA-2, SHA-3, SHAKE).
   nistHash: { base: [2, 16, 840, 1, 101, 3, 4, 2], of: {
-    sha256: 1, sha384: 2, sha512: 3, "sha3-256": 8, "sha3-512": 10, shake256: 12 } },
+    sha256: 1, sha384: 2, sha512: 3, "sha3-256": 8, "sha3-512": 10, shake128: 11, shake256: 12 } },
 
   // NIST signature algorithms -- FIPS 204 ML-DSA + FIPS 205 SLH-DSA share the
   // signature arc 2.16.840.1.101.3.4.3. RFC 9909 sec. 3 assigns the 12 Pure SLH-DSA

package/lib/path-validate.js

@@ -187,6 +187,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]);
 }
@@ -261,6 +264,10 @@ function resolveDescriptor(sigAlg) {
   var comp = COMPOSITE_ALGS[sigAlg.oid];
   if (comp) {
     // draft-ietf-lamps-pq-composite-sigs sec. 5.3: parameters MUST be absent.
+    // Coverage residual -- unreachable: every sigAlg reaching resolveDescriptor is a
+    // field of a parsed x509/CRL/OCSP structure, and the shared AlgorithmIdentifier
+    // decoder (schema-pkix) rejects a composite OID carrying parameters at parse time
+    // (oid.paramsMustBeAbsent), so `parameters` is always absent here. Defense in depth.
     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)");
     }
@@ -302,6 +309,9 @@ function assertKeyMatchesSigAlg(spkiBytes, sigOid, d) {
 function ecdsaDerToP1363(der, curve) {
   var width = CURVE_FIELD_BYTES[curve];
   var order = CURVE_ORDER[curve];
+  // Coverage residual -- unreachable: `curve` is a WebCrypto-imported ECDSA
+  // namedCurve (P-256/384/521) or a composite trad.ec from the same set; all three
+  // are present in the width/order tables, so no import yields an untabulated curve.
   if (!width || !order) throw E("path/bad-signature", "unsupported ECDSA curve " + curve);
   var n;
   try { n = asn1.decode(der); }
@@ -318,6 +328,8 @@ function ecdsaDerToP1363(der, curve) {
     var hex = v.toString(16);
     if (hex.length % 2) hex = "0" + hex;
     var buf = Buffer.from(hex, "hex");
+    // Coverage residual -- unreachable: the preceding [1, order-1] range gate bounds
+    // r and s below the curve order, which fits within `width` bytes.
     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);
@@ -424,6 +436,9 @@ function _verifyTradComponent(trad, tradPK, 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); });
   }
+  // 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; this final fallthrough is a backstop.
   return Promise.resolve(false);
 }
 
@@ -714,6 +729,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 +826,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 +1155,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) {
@@ -1773,6 +1797,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 +1919,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
@@ -1963,6 +1991,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]);
@@ -2149,6 +2180,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "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:edfce9fb-f69d-4264-b69d-27177c001bc9",
+  "serialNumber": "urn:uuid:e4cc4e90-fbb7-4869-9baf-d6ce16b67d7f",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-14T00:56:05.894Z",
+    "timestamp": "2026-07-14T04:28:56.898Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.15",
+      "bom-ref": "@blamejs/pki@0.2.17",
       "type": "application",
       "name": "pki",
-      "version": "0.2.15",
+      "version": "0.2.17",
       "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.15",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.17",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.15",
+      "ref": "@blamejs/pki@0.2.17",
       "dependsOn": []
     }
   ]