@blamejs/pki 0.1.20 → 0.1.22

package/CHANGELOG.md

@@ -4,6 +4,33 @@ 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.1.22 — 2026-07-09
+
+An RFC 5035 / RFC 8551 S/MIME ESS signed-attribute decoder joins the schema family.
+
+### Added
+
+- pki.schema.smime.parseSigningCertificate(der) / parseSigningCertificateV2(der) — decode the RFC 5035 ESS SigningCertificate (v1) and SigningCertificateV2 (v2) signed-attribute values into { certs, policies }. Each certs entry is { certHash, hashAlgorithm, issuerSerial } in wire order: certHash raw; hashAlgorithm the implied SHA-1 for v1, or the decoded algorithm (or the id-sha256 default, flagged defaulted) for v2; issuerSerial (or null) the issuer GeneralNames (each CHOICE arm validated, surfaced raw) plus serialNumber as a BigInt and serialNumberHex. certs is non-empty and order-preserving; a v2 hashAlgorithm encoded byte-equal to its DEFAULT is rejected smime/non-canonical-default (X.690 §11.5). Malformed input fails closed with a typed smime/* (or leaf asn1/*) code.
+- pki.schema.smime.parseSmimeCapabilities(der) — decode an RFC 8551 SMIMECapabilities value into { capabilities }, an ordered list (preference order preserved, never sorted) of { capabilityID, name, parameters } with parameters the raw ANY-DEFINED-BY bytes.
+- pki.schema.smime.decodeAttribute(attr) — an OID-dispatch convenience over the three decoders for a CMS-shaped { type, values } attribute (the shape cms.parse surfaces on signerInfos[i].signedAttrs). It enforces the single-AttributeValue rule (a values length other than one is rejected smime/multi-valued-attribute), routes on the attribute OID, and recognize-and-defers an unknown type as smime/unsupported-attribute carrying the type, registry name, and raw values.
+- The error taxonomy gains SmimeError, carrying a stable smime/* code.
+- The OID registry gains the smimeCapabilities attribute identifier and the RFC 2634 ESS attribute names (receiptRequest through contentReference), so a CMS signed attribute of one of those types resolves to a name in an unsupported-attribute diagnostic.
+
+## v0.1.21 — 2026-07-09
+
+SLH-DSA signatures verify in certification-path validation, and the post-quantum / EdDSA parameters-absent rule is enforced across every format.
+
+### Added
+
+- SLH-DSA signature verification in pki.path.validate — all twelve FIPS 205 parameter sets (id-slh-dsa-sha2-{128,192,256}{s,f} and the SHAKE sets). A certificate or CRL signed with SLH-DSA now verifies by importing the issuer's SLH-DSA public key and checking the one-shot signature over the raw signed region; the same rows serve both the certificate signature check and the CRL revocation checker. ML-DSA and the classical RSA / ECDSA / EdDSA set were already wired.
+- pki.oid.paramsMustBeAbsent(oid) — a predicate that reports whether an AlgorithmIdentifier bearing the given OID must encode its parameters field as absent (the ML-DSA and SLH-DSA families and the RFC 8410 Edwards / Montgomery curves). It is the single source the shared AlgorithmIdentifier decoder consults.
+- The OID registry now names the twelve pre-hash HashSLH-DSA identifiers (id-hash-slh-dsa-*, RFC 9909 §3), so a certificate or CRL that carries a HashSLH-DSA algorithm resolves to a name and is covered by the parameters-absent rule.
+
+### Fixed
+
+- The shared AlgorithmIdentifier decoder now rejects a present parameters field on the algorithms whose parameters MUST be absent — ML-DSA, SLH-DSA, Ed25519, Ed448, X25519, and X448 (RFC 9909 §3, RFC 9814 §4, RFC 9881 §2, RFC 8410 §3) — failing closed with a <format>/bad-algorithm-parameters code. Previously a stray explicit NULL or arbitrary bytes in that field were surfaced raw. The rule is enforced once in the shared decoder, so every format that names an algorithm inherits it; a conforming identifier, which omits the field, is unaffected.
+- Certification-path validation now enforces issuer-key / signature-algorithm consistency for the one-shot families whose public-key OID equals the signature OID — EdDSA, ML-DSA, and SLH-DSA — rejecting a mismatch with a path/algorithm-mismatch reason (RFC 9814 §4). Because the underlying WebCrypto import binds a public key of a different type to the requested algorithm name and verifies with the real key, a certificate or CRL signed by one key type but labelling its signatureAlgorithm as another one-shot type could otherwise validate; the check closes that algorithm-confusion path for both the certificate signature and the CRL revocation checker.
+
 ## v0.1.20 — 2026-07-09
 
 An RFC 6962 Certificate Transparency SCT-list parser joins the toolkit.

package/README.md

@@ -202,6 +202,7 @@ is callable today; nothing below is a stub.
 | `pki.schema.crmf` | Parse DER / PEM RFC 4211 certificate request messages (CertReqMessages — the CMP / EST enrollment body) — the requested-certificate template (subject, public key, validity, extensions), proof-of-possession, and registration controls, with the raw `CertRequest` region a POP verifier hashes; names dual-accepted (IMPLICIT and EXPLICIT), fail-closed — `parse`, `pemDecode` |
 | `pki.schema.pkcs12` | Parse DER / BER / PEM RFC 7292 PKCS#12 (PFX) stores — key bags via the PKCS#8 parser, shrouded keys (algorithm surfaced, ciphertext opaque), cert / CRL / secret bags raw and byte-exact, encrypted and enveloped safes structurally via CMS, `friendlyName` / `localKeyId` decoded, and the exact MAC byte range (`macedBytes`) plus RFC 9579 PBMAC1 recognition for external verification; BER accepted exactly where §4.1 requires it, fail-closed — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.cmp` | Parse DER / PEM RFC 9810 Certificate Management Protocol messages (PKIMessage) — the header (version, sender / recipient incl. the anonymous NULL-DN, nonces, transaction id, general info), the 27-arm body (certificate requests via the CRMF parser, an encrypted certificate's EnvelopedData via CMS, response / revocation / confirmation / error / support / polling arms structural, the rest raw), and the exact `headerBytes` / `bodyBytes` slices an external verifier reconstructs the protected part from; the CMP-before-OCSP dispatch order is enforced, fail-closed — `parse`, `pemDecode`, `pemEncode` |
+| `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, 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; `crlChecker` supplies CRL-based revocation. Pure and re-entrant, fail-closed — `validate`, `crlChecker` |
 | `pki.ct` | Parse RFC 6962 Certificate Transparency SCT lists — `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 for external verification. Structure decoded, crypto surfaced raw, bounded decode, fail-closed — `parseSctList`, `reconstructSignedData` |

package/lib/framework-error.js

@@ -179,6 +179,14 @@ var CmpError = defineClass("CmpError", { withCause: true });
 // `.cause`.
 var PathError = defineClass("PathError", { withCause: true });
 
+// SmimeError — a byte sequence that is not a well-formed RFC 5035 ESS
+// signing-certificate attribute (SigningCertificate / SigningCertificateV2 /
+// ESSCertID(v2) / IssuerSerial) or RFC 8551 SMIMECapabilities, or a CMS
+// attribute violating a §2.5 coherence rule (single-AttributeValue, certs
+// non-empty, non-canonical DEFAULT hashAlgorithm). Carries the underlying leaf
+// fault (e.g. the inner asn1/* decode error) as `.cause`.
+var SmimeError = defineClass("SmimeError", { withCause: true });
+
 // CtError — a byte sequence that is not a well-formed RFC 6962 Certificate
 // Transparency SCT list: a malformed inner DER OCTET-STRING wrap, or a TLS
 // presentation-language framing violation (a lying vector length, a field read
@@ -209,4 +217,5 @@ module.exports = {
   CmpError:         CmpError,
   PathError:        PathError,
   CtError:          CtError,
+  SmimeError:       SmimeError,
 };

package/lib/oid.js

@@ -141,7 +141,8 @@ var FAMILIES = {
   // and the PKCS#12 bag attributes friendlyName / localKeyId (RFC 7292 §4.2).
   pkcs9: { base: [1, 2, 840, 113549, 1, 9], of: {
     emailAddress: 1, contentType: 3, messageDigest: 4, signingTime: 5,
-    challengePassword: 7, extensionRequest: 14, friendlyName: 20, localKeyId: 21 } },
+    challengePassword: 7, extensionRequest: 14, smimeCapabilities: 15,
+    friendlyName: 20, localKeyId: 21 } },
 
   // PKCS#9 CertBag / CRLBag value discriminators (RFC 7292 §4.2.3-§4.2.4).
   pkcs9CertTypes: { base: [1, 2, 840, 113549, 1, 9, 22], of: { x509Certificate: 1, sdsiCertificate: 2 } },
@@ -188,7 +189,11 @@ var FAMILIES = {
   // S/MIME authenticated attributes (id-aa, RFC 2634 / RFC 5035 / RFC 5816). The ESS
   // signing-certificate attributes bind a CMS / TSP SignerInfo to its signing cert;
   // signingCertificateV2 (ESSCertIDv2) carries a non-SHA-1 cert hash (RFC 5816 §2.2.1).
+  // The RFC 2634 originals (receiptRequest .. contentReference) are name-only: they
+  // resolve to a name so an unsupported-attribute diagnostic is legible, not decoded.
   smimeAa: { base: [1, 2, 840, 113549, 1, 9, 16, 2], of: {
+    receiptRequest: 1, eSSSecurityLabel: 2, mlExpansionHistory: 3, contentHints: 4,
+    msgSigDigest: 5, contentIdentifier: 7, equivalentLabels: 9, contentReference: 10,
     signingCertificate: 12, timeStampToken: 14, signingCertificateV2: 47 } },
 
   // ANSI X9.62 EC public key, named curve, and ECDSA signatures.
@@ -217,9 +222,10 @@ var FAMILIES = {
     sha256: 1, sha384: 2, sha512: 3, "sha3-256": 8, "sha3-512": 10, 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. The 12 Pure SLH-DSA parameter sets are
-  // assigned sequentially (RFC 9909 §3): the SHA-2 sets .20-.25, then the SHAKE
-  // sets .26-.31.
+  // signature arc 2.16.840.1.101.3.4.3. RFC 9909 §3 assigns the 12 Pure SLH-DSA
+  // sets .20-.31 (SHA-2 .20-.25, SHAKE .26-.31) and the 12 pre-hash HashSLH-DSA
+  // sets .35-.46, each pairing a parameter set with its message-digest hash. The
+  // parameters MUST be absent for every one of them (enforced via paramsMustBeAbsent).
   nistSig: { base: [2, 16, 840, 1, 101, 3, 4, 3], of: {
     "id-ml-dsa-44": 17, "id-ml-dsa-65": 18, "id-ml-dsa-87": 19,
     "id-slh-dsa-sha2-128s": 20, "id-slh-dsa-sha2-128f": 21,
@@ -227,7 +233,13 @@ var FAMILIES = {
     "id-slh-dsa-sha2-256s": 24, "id-slh-dsa-sha2-256f": 25,
     "id-slh-dsa-shake-128s": 26, "id-slh-dsa-shake-128f": 27,
     "id-slh-dsa-shake-192s": 28, "id-slh-dsa-shake-192f": 29,
-    "id-slh-dsa-shake-256s": 30, "id-slh-dsa-shake-256f": 31 } },
+    "id-slh-dsa-shake-256s": 30, "id-slh-dsa-shake-256f": 31,
+    "id-hash-slh-dsa-sha2-128s-with-sha256": 35, "id-hash-slh-dsa-sha2-128f-with-sha256": 36,
+    "id-hash-slh-dsa-sha2-192s-with-sha512": 37, "id-hash-slh-dsa-sha2-192f-with-sha512": 38,
+    "id-hash-slh-dsa-sha2-256s-with-sha512": 39, "id-hash-slh-dsa-sha2-256f-with-sha512": 40,
+    "id-hash-slh-dsa-shake-128s-with-shake128": 41, "id-hash-slh-dsa-shake-128f-with-shake128": 42,
+    "id-hash-slh-dsa-shake-192s-with-shake256": 43, "id-hash-slh-dsa-shake-192f-with-shake256": 44,
+    "id-hash-slh-dsa-shake-256s-with-shake256": 45, "id-hash-slh-dsa-shake-256f-with-shake256": 46 } },
 
   // NIST KEM — FIPS 203 ML-KEM (arc 2.16.840.1.101.3.4.4).
   nistKem: { base: [2, 16, 840, 1, 101, 3, 4, 4], of: {
@@ -402,10 +414,58 @@ function fromDER(input) {
   return asn1.read.oid(node);
 }
 
+// Algorithm identifiers whose `parameters` field MUST be absent — no explicit
+// NULL, no bytes. The FIPS 204 ML-DSA and FIPS 205 SLH-DSA signature families
+// and the RFC 8410 Edwards / Montgomery curves each carry this MUST: RFC 9909 §3
+// (SLH-DSA in X.509), RFC 9814 §4 (SLH-DSA in CMS), RFC 9881 §2 (ML-DSA in X.509),
+// RFC 8410 §3 (Ed25519 / Ed448 / X25519 / X448). Built by NAME through the same
+// registry every caller uses, so a typo fails closed at load rather than silently
+// dropping a member. One set drives the single shared AlgorithmIdentifier reject
+// (schema-pkix), so every format consumer inherits the rule with no per-format code.
+var _PARAMS_ABSENT = new Set();
+[
+  "id-ml-dsa-44", "id-ml-dsa-65", "id-ml-dsa-87",
+  "id-slh-dsa-sha2-128s", "id-slh-dsa-sha2-128f", "id-slh-dsa-sha2-192s",
+  "id-slh-dsa-sha2-192f", "id-slh-dsa-sha2-256s", "id-slh-dsa-sha2-256f",
+  "id-slh-dsa-shake-128s", "id-slh-dsa-shake-128f", "id-slh-dsa-shake-192s",
+  "id-slh-dsa-shake-192f", "id-slh-dsa-shake-256s", "id-slh-dsa-shake-256f",
+  // Pre-hash HashSLH-DSA sets (RFC 9909 §3) — parameters MUST be absent too.
+  "id-hash-slh-dsa-sha2-128s-with-sha256", "id-hash-slh-dsa-sha2-128f-with-sha256",
+  "id-hash-slh-dsa-sha2-192s-with-sha512", "id-hash-slh-dsa-sha2-192f-with-sha512",
+  "id-hash-slh-dsa-sha2-256s-with-sha512", "id-hash-slh-dsa-sha2-256f-with-sha512",
+  "id-hash-slh-dsa-shake-128s-with-shake128", "id-hash-slh-dsa-shake-128f-with-shake128",
+  "id-hash-slh-dsa-shake-192s-with-shake256", "id-hash-slh-dsa-shake-192f-with-shake256",
+  "id-hash-slh-dsa-shake-256s-with-shake256", "id-hash-slh-dsa-shake-256f-with-shake256",
+  "Ed25519", "Ed448", "X25519", "X448",
+].forEach(function (nm) { _PARAMS_ABSENT.add(byName(nm)); });
+
+/**
+ * @primitive  pki.oid.paramsMustBeAbsent
+ * @signature  pki.oid.paramsMustBeAbsent(dotted) -> boolean
+ * @since      0.1.21
+ * @status     experimental
+ * @spec       RFC 9909, RFC 9814, RFC 9881, RFC 8410
+ * @related    pki.oid.name, pki.oid.byName
+ *
+ * True when an AlgorithmIdentifier bearing this OID MUST encode its `parameters`
+ * field as ABSENT (not an explicit NULL, not any bytes): the FIPS 204 ML-DSA and
+ * FIPS 205 SLH-DSA signature families and the RFC 8410 Edwards / Montgomery
+ * curves. The shared AlgorithmIdentifier decoder consults this and fails closed
+ * on a present-parameters violation, so every format inherits the rule.
+ *
+ * @example
+ *   pki.oid.paramsMustBeAbsent(pki.oid.byName("id-slh-dsa-sha2-128s")); // -> true
+ *   pki.oid.paramsMustBeAbsent(pki.oid.byName("rsaEncryption"));        // -> false
+ */
+function paramsMustBeAbsent(dotted) {
+  return _PARAMS_ABSENT.has(dotted);
+}
+
 module.exports = {
   name:           name,
   byName:         byName,
   has:            has,
+  paramsMustBeAbsent: paramsMustBeAbsent,
   register:       register,
   registerFamily: registerFamily,
   all:            all,

package/lib/path-validate.js

@@ -86,9 +86,16 @@ var SIG_ALGS = {};
 // NULL must be present — RSASSA-PKCS1-v1_5, RFC 4055 §5) or "absent" (parameters
 // must be omitted — ECDSA/EdDSA/ML-DSA, RFC 5758/8410). A cert deviating from
 // its algorithm's required shape is malformed and rejected before verify.
-function _sig(name, verify, imp, params, ecdsa) {
+// `sameKeyOid` marks the one-shot families whose PUBLIC-KEY algorithm OID is the
+// SAME as the signature algorithm OID — EdDSA, ML-DSA, SLH-DSA. For these, Node's
+// WebCrypto imports an SPKI of ANOTHER type under the requested name and verifies
+// with the real key (it does NOT reject a mismatched SPKI the way it does for
+// RSA/ECDSA), so the issuer-key <-> signature-algorithm consistency (RFC 9814 §4)
+// must be checked structurally: the SPKI OID must equal the signature OID.
+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;
   SIG_ALGS[oid.byName(name)] = entry;
 }
 // RSASSA-PKCS1-v1_5 — parameters MUST be NULL.
@@ -99,13 +106,22 @@ _sig("sha512WithRSAEncryption", { name: "RSASSA-PKCS1-v1_5", hash: "SHA-512" },
 _sig("ecdsaWithSHA256", { name: "ECDSA", hash: "SHA-256" }, { name: "ECDSA" }, "absent", true);
 _sig("ecdsaWithSHA384", { name: "ECDSA", hash: "SHA-384" }, { name: "ECDSA" }, "absent", true);
 _sig("ecdsaWithSHA512", { name: "ECDSA", hash: "SHA-512" }, { name: "ECDSA" }, "absent", true);
-// EdDSA (one-shot, no hash parameter) — params absent.
-_sig("Ed25519", { name: "Ed25519" }, { name: "Ed25519" }, "absent");
-_sig("Ed448", { name: "Ed448" }, { name: "Ed448" }, "absent");
-// ML-DSA (FIPS 204) — params absent.
-_sig("id-ml-dsa-44", { name: "ML-DSA-44" }, { name: "ML-DSA-44" }, "absent");
-_sig("id-ml-dsa-65", { name: "ML-DSA-65" }, { name: "ML-DSA-65" }, "absent");
-_sig("id-ml-dsa-87", { name: "ML-DSA-87" }, { name: "ML-DSA-87" }, "absent");
+// EdDSA (one-shot, no hash parameter) — params absent; key OID == sig OID.
+_sig("Ed25519", { name: "Ed25519" }, { name: "Ed25519" }, "absent", false, true);
+_sig("Ed448", { name: "Ed448" }, { name: "Ed448" }, "absent", false, true);
+// ML-DSA (FIPS 204) — params absent; key OID == sig OID.
+_sig("id-ml-dsa-44", { name: "ML-DSA-44" }, { name: "ML-DSA-44" }, "absent", false, true);
+_sig("id-ml-dsa-65", { name: "ML-DSA-65" }, { name: "ML-DSA-65" }, "absent", false, true);
+_sig("id-ml-dsa-87", { name: "ML-DSA-87" }, { name: "ML-DSA-87" }, "absent", false, true);
+// SLH-DSA (FIPS 205) — params absent; key OID == sig OID. The twelve pure sets;
+// the RFC 9909 §3 OID name maps to the WebCrypto set name by id-slh-dsa-<set> ->
+// SLH-DSA-<SET> (the webcrypto SLH_DSA_NODE keys). One-shot verify like ML-DSA.
+["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 (set) {
+  var wc = "SLH-DSA-" + set.toUpperCase();
+  _sig("id-slh-dsa-" + set, { name: wc }, { name: wc }, "absent", false, true);
+});
 
 // RSASSA-PSS resolves its hash + salt from the AlgorithmIdentifier parameters.
 var OID_RSA_PSS = oid.byName("rsassaPss");
@@ -238,6 +254,24 @@ function resolveDescriptor(sigAlg) {
   return d;
 }
 
+// RFC 9814 §4 issuer-key <-> signature-algorithm consistency (algorithm-confusion
+// defense). For the one-shot families whose public key shares the signature OID
+// (EdDSA, ML-DSA, SLH-DSA), Node's WebCrypto imports an SPKI of a DIFFERENT type
+// under the requested name and verifies with the real key — so an Ed25519-signed
+// certificate labelled SLH-DSA would otherwise validate. Enforce structurally:
+// the issuer SPKI's algorithm OID MUST equal the signature algorithm OID. (For
+// RSA/ECDSA — different key vs signature OIDs — WebCrypto's import already rejects
+// a mismatched key type, so `sameKeyOid` is not set and this is a no-op.)
+function assertKeyMatchesSigAlg(spkiBytes, sigOid, d) {
+  if (!d || !d.sameKeyOid) return;
+  var keyOid;
+  try { keyOid = asn1.read.oid(asn1.decode(spkiBytes).children[0].children[0]); }
+  catch (e) { throw E("path/algorithm-mismatch", "cannot read the issuer public-key algorithm identifier", e); }
+  if (keyOid !== sigOid) {
+    throw E("path/algorithm-mismatch", "issuer public-key algorithm " + keyOid + " does not match the signature algorithm " + sigOid + " (RFC 9814 §4 - algorithm confusion)");
+  }
+}
+
 // 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) {
@@ -270,8 +304,10 @@ function ecdsaDerToP1363(der, curve) {
 // Verify cert.signatureValue over cert.tbsBytes with the working public key.
 function builtinVerify(state, cert) {
   var d;
-  try { d = resolveDescriptor(cert.signatureAlgorithm); }
-  catch (e) { return Promise.resolve({ ok: false, code: pathCode(e, "path/unsupported-algorithm"), error: e }); }
+  try {
+    d = resolveDescriptor(cert.signatureAlgorithm);
+    assertKeyMatchesSigAlg(state.workingPublicKey, cert.signatureAlgorithm.oid, d);
+  } catch (e) { return Promise.resolve({ ok: false, code: pathCode(e, "path/unsupported-algorithm"), error: e }); }
   // The signature is an octet-aligned BIT STRING (no unused bits) for every
   // supported algorithm; a non-zero unused-bit count is malformed.
   if (cert.signatureValue.unusedBits !== 0) return Promise.resolve({ ok: false, code: "path/bad-signature" });
@@ -1387,8 +1423,10 @@ function crlEntryReason(entry) {
 
 function verifyCrlSignature(theCrl, issuer) {
   var d;
-  try { d = resolveDescriptor(theCrl.signatureAlgorithm); }
-  catch (_e) { return Promise.resolve(false); }
+  try {
+    d = resolveDescriptor(theCrl.signatureAlgorithm);
+    assertKeyMatchesSigAlg(issuer.workingPublicKey, theCrl.signatureAlgorithm.oid, d);
+  } catch (_e) { return Promise.resolve(false); }
   if (theCrl.signatureValue.unusedBits !== 0) return Promise.resolve(false);   // non-octet-aligned signature
   var key;
   return subtle.importKey("spki", issuer.workingPublicKey, d.imp, false, ["verify"]).then(function (k) {

package/lib/schema-all.js

@@ -43,6 +43,11 @@ var tsp = require("./schema-tsp");
 var crmf = require("./schema-crmf");
 var cmp = require("./schema-cmp");
 var attrcert = require("./schema-attrcert");
+// smime is a COMPANION decoder for CMS signed-attribute values, NOT a top-level
+// format — it has no self-describing DER root (an ESS attribute value is a bare
+// SEQUENCE) so it is deliberately absent from FORMATS / the detect-and-route
+// `parse`; it is reached only by explicit OID dispatch on a CMS attribute.
+var smime = require("./schema-smime");
 var frameworkError = require("./framework-error");
 
 var SchemaError = frameworkError.SchemaError;
@@ -277,6 +282,7 @@ module.exports = {
   crmf: { parse: crmf.parse, pemDecode: crmf.pemDecode },
   cmp: { parse: cmp.parse, pemDecode: cmp.pemDecode, pemEncode: cmp.pemEncode },
   attrcert: { parse: attrcert.parse, pemDecode: attrcert.pemDecode },
+  smime: { parseSigningCertificate: smime.parseSigningCertificate, parseSigningCertificateV2: smime.parseSigningCertificateV2, parseSmimeCapabilities: smime.parseSmimeCapabilities, decodeAttribute: smime.decodeAttribute },
   all: all,
   parse: parse,
 };

package/lib/schema-pkix.js

@@ -156,6 +156,15 @@ function algorithmIdentifier(ns, opts) {
     arity: { min: 1 }, code: ns.prefix + "/bad-algorithm-identifier", what: "AlgorithmIdentifier",
     build: function (m, ctx) {
       var dotted = m.fields.algorithm.value;
+      // RFC 9909 §3 / RFC 9814 §4 / RFC 9881 §2 / RFC 8410 §3: for the PQC
+      // signature families (ML-DSA, SLH-DSA) and the Edwards/Montgomery curves,
+      // the `parameters` field MUST be absent — no explicit NULL, no bytes.
+      // Enforced ONCE here so every consumer of the shared AlgorithmIdentifier
+      // inherits the rule; the guard-parity bug class is structurally impossible.
+      if (m.fields.parameters.present && ctx.oid.paramsMustBeAbsent(dotted)) {
+        throw ctx.E(ctx.prefix + "/bad-algorithm-parameters",
+          "the " + (ctx.oid.name(dotted) || dotted) + " AlgorithmIdentifier parameters field MUST be absent (RFC 9909 §3 / RFC 9814 §4 / RFC 9881 §2 / RFC 8410 §3)");
+      }
       return { oid: dotted, name: ctx.oid.name(dotted) || null, parameters: m.fields.parameters.present ? m.fields.parameters.node.bytes : null };
     },
   });
@@ -361,6 +370,28 @@ function generalNames(ns, opts) {
 // `decodeExt` pattern (asn1.decode → read.* / schema.walk, wrapped). Returns
 // { byOid } keyed by dotted OID so a consumer dispatches by ext.oid.
 var _T = asn1.TAGS;
+
+// assertPolicyQualifiers(qNode, fail) — RFC 5280 §4.2.1.4: a PolicyInformation's
+// policyQualifiers is a non-empty SEQUENCE OF PolicyQualifierInfo, each a SEQUENCE
+// { policyQualifierId OID, qualifier } of EXACTLY two members led by an OID. The
+// structure is validated fail-closed; the qualifier body stays opaque (surfaced
+// raw by the caller). `fail(msg)` throws the caller's typed code. Shared by the
+// certificatePolicies extension decoder and the RFC 5035 ESS SigningCertificate
+// policies field so the same PolicyInformation shape cannot drift between them.
+// `fail(msg, cause?)` throws the caller's typed code, carrying the underlying
+// leaf fault as the error cause when one is available.
+function assertPolicyQualifiers(qNode, fail) {
+  if (qNode.tagClass !== "universal" || qNode.tagNumber !== _T.SEQUENCE || !qNode.children || !qNode.children.length) {
+    fail("policyQualifiers must be a non-empty SEQUENCE (RFC 5280 §4.2.1.4)");
+  }
+  qNode.children.forEach(function (pq) {
+    if (pq.tagClass !== "universal" || pq.tagNumber !== _T.SEQUENCE || !pq.children || pq.children.length !== 2) {
+      fail("policyQualifiers element must be a PolicyQualifierInfo SEQUENCE { policyQualifierId, qualifier } (RFC 5280 §4.2.1.4)");
+    }
+    try { asn1.read.oid(pq.children[0]); } catch (e) { fail("PolicyQualifierInfo must lead with a policyQualifierId OID", e); }
+  });
+}
+
 function certExtensionDecoders(ns) {
   var GN_SUBTREE = generalName(ns, { decodeValue: true, subtreeBase: true, code: ns.prefix + "/bad-name-constraints" });
 
@@ -486,20 +517,9 @@ function certExtensionDecoders(ns) {
       var qualifiers = null;
       if (pi.children.length > 1) {
         var q = pi.children[1];
-        if (q.tagClass !== "universal" || q.tagNumber !== _T.SEQUENCE || !q.children || !q.children.length) {
-          throw ns.E(C, "PolicyInformation policyQualifiers must be a non-empty SEQUENCE (RFC 5280 §4.2.1.4)");
-        }
-        // Each element is a PolicyQualifierInfo ::= SEQUENCE { policyQualifierId
-        // OID, qualifier ANY DEFINED BY policyQualifierId } — EXACTLY two members
-        // (qualifier is not OPTIONAL). A SEQUENCE missing the qualifier or
-        // carrying trailing extra fields is malformed; the qualifier body itself
-        // stays opaque.
-        q.children.forEach(function (pq) {
-          if (pq.tagClass !== "universal" || pq.tagNumber !== _T.SEQUENCE || !pq.children || pq.children.length !== 2) {
-            throw ns.E(C, "policyQualifiers element must be a PolicyQualifierInfo SEQUENCE { policyQualifierId, qualifier } (RFC 5280 §4.2.1.4)");
-          }
-          try { asn1.read.oid(pq.children[0]); } catch (e) { throw ns.E(C, "PolicyQualifierInfo must lead with a policyQualifierId OID", e); }
-        });
+        // PolicyQualifierInfo structure validated by the shared assertion; the
+        // qualifier body stays opaque (surfaced raw).
+        assertPolicyQualifiers(q, function (msg, cause) { throw ns.E(C, msg, cause); });
         qualifiers = q.bytes;
       }
       return { policyIdentifier: pid, qualifiersBytes: qualifiers };
@@ -829,6 +849,7 @@ module.exports = {
   makeParser: makeParser,
   signedEnvelopeTbs: signedEnvelopeTbs,
   rootSequenceChildren: rootSequenceChildren,
+  assertPolicyQualifiers: assertPolicyQualifiers,
   signedEnvelope: signedEnvelope,
   attrValueToString: attrValueToString,
   attributeTypeAndValue: attributeTypeAndValue,

package/lib/schema-smime.js

@@ -0,0 +1,363 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.schema.smime
+ * @nav        Schema
+ * @title      S/MIME (ESS)
+ * @order      180
+ * @slug       smime
+ *
+ * @intro
+ *   S/MIME Enhanced Security Services signed-attribute values per RFC 5035 (ESS)
+ *   and RFC 8551 (S/MIME 4.0). These are the DER-decoded VALUES of CMS signed
+ *   attributes — they ride inside a `SignerInfo.signedAttrs`, so this is a
+ *   companion decoder a CMS consumer invokes by attribute OID, NOT a top-level
+ *   format the schema orchestrator auto-routes.
+ *
+ *   `parseSigningCertificate` / `parseSigningCertificateV2` decode the ESS
+ *   signing-certificate attributes that bind a signature to the exact certificate
+ *   that made it: each surfaces its list of `ESSCertID`(v2) — the certificate hash
+ *   (raw), the hash algorithm (decoded for v2, or the implied SHA-1 for v1), and
+ *   the optional `issuerSerial` (issuer `GeneralNames` validated + surfaced raw,
+ *   serial as a BigInt + hex) — plus the optional certificate policies.
+ *   `parseSmimeCapabilities` decodes the ordered `SMIMECapabilities` list (each a
+ *   capability OID + raw parameters). `decodeAttribute` takes a CMS-shaped
+ *   `{ type, values }` attribute, enforces the single-`AttributeValue` rule
+ *   (RFC 8551 §2.5.2), routes on the attribute OID, and recognize-and-defers an
+ *   unknown attribute type with its raw values intact.
+ *
+ *   Structure is decoded; verification is the consumer's — the parser surfaces
+ *   `certHash` + `hashAlgorithm` + `issuerSerial` so a verifier recomputes the
+ *   certificate hash (compose `webcrypto`) and matches the issuer/serial against
+ *   the actual signing certificate; it never recomputes a hash or trusts a cert.
+ *   Whether an attribute is correctly placed in `signedAttrs` (vs `unsignedAttrs`)
+ *   is the CMS consumer's knowledge. DER-only, fail-closed.
+ *
+ * @card
+ *   Decode RFC 5035 ESS SigningCertificate / SigningCertificateV2 and RFC 8551
+ *   SMIMECapabilities signed-attribute values — cert-hash binding, validated
+ *   issuer GeneralNames, ordered capability list, OID-dispatched, fail-closed.
+ */
+
+var asn1 = require("./asn1-der");
+var schema = require("./schema-engine");
+var pkix = require("./schema-pkix");
+var oid = require("./oid");
+var frameworkError = require("./framework-error");
+
+var SmimeError = frameworkError.SmimeError;
+var PemError = frameworkError.PemError;
+
+var NS = pkix.makeNS("smime", SmimeError, oid);
+var TAGS = asn1.TAGS;
+
+var ALGID = pkix.algorithmIdentifier(NS);
+
+// Registry constants — never a dotted literal in a format module.
+var OID_SHA1 = oid.byName("sha1");
+var OID_SHA256 = oid.byName("sha256");
+var OID_SIGNING_CERTIFICATE = oid.byName("signingCertificate");
+var OID_SIGNING_CERTIFICATE_V2 = oid.byName("signingCertificateV2");
+var OID_SMIME_CAPABILITIES = oid.byName("smimeCapabilities");
+
+// IssuerSerial ::= SEQUENCE { issuer GeneralNames, serialNumber CertificateSerialNumber }
+// (RFC 5035 App A). A bare universal SEQUENCE of exactly two fields — distinct
+// from the RFC 5755 attribute-certificate IssuerSerial (three fields, reached
+// IMPLICIT-tagged), so declared per-format. `issuer` composes the shared
+// GeneralNames factory (every CHOICE arm validated + surfaced raw, SIZE 1..MAX)
+// and is surfaced unchanged here: the RFC 5035 §5 directoryName narrowing applies
+// only to a non-attribute (public-key) certificate reference, and an ESSCertID
+// entry may reference an attribute certificate whose issuer is a full GeneralNames.
+// The FIRST cert is known to be the signing public-key cert (RFC 5035 §3), so the
+// directoryName rule is enforced there — in the SigningCertificate build — not here.
+var GENERAL_NAME_DIRECTORY = 4;
+var ISSUER_SERIAL = schema.seq([
+  schema.field("issuer", pkix.generalNames(NS, { code: "smime/bad-general-names" })),
+  schema.field("serialNumber", schema.integerLeaf()),
+], {
+  assert: "sequence", arity: { exact: 2 }, code: "smime/bad-issuer-serial", what: "IssuerSerial",
+  build: function (m) {
+    return {
+      issuer: m.fields.issuer.value.result,
+      serialNumber: m.fields.serialNumber.value,
+      serialNumberHex: m.fields.serialNumber.node.content.toString("hex"),
+    };
+  },
+});
+
+// RFC 5035 §5: the signing certificate (certs[0], the public-key cert that made
+// the signature per §3) MUST identify its issuer as exactly one directoryName [4].
+// Additional certs[1..] may reference attribute certificates, whose issuer is a
+// GeneralNames — left unconstrained (a verifier-tier profile concern). `fail`
+// throws the caller's code.
+function assertSignerIssuerIsDirectoryName(certs, fail) {
+  if (!certs.length || !certs[0].issuerSerial) return;
+  var names = certs[0].issuerSerial.issuer.names;
+  if (names.length !== 1 || names[0].tagClass !== "context" || names[0].tagNumber !== GENERAL_NAME_DIRECTORY) {
+    fail("the signing certificate's IssuerSerial issuer MUST be exactly one directoryName [4] GeneralName (RFC 5035 §5)");
+  }
+}
+
+// PolicyInformation ::= SEQUENCE { policyIdentifier CertPolicyId,
+//   policyQualifiers SEQUENCE OF PolicyQualifierInfo OPTIONAL } (RFC 5280 §4.2.1.4).
+// Decode the policy OID (+ registry name); surface policyQualifiers raw.
+var POLICY_INFORMATION = schema.seq([
+  schema.field("policyIdentifier", schema.oidLeaf()),
+  schema.optional("policyQualifiers", schema.any(), { whenUniversal: [TAGS.SEQUENCE] }),
+], {
+  assert: "sequence", code: "smime/bad-policy-information", what: "PolicyInformation",
+  build: function (m, ctx) {
+    var qualifiers = null;
+    if (m.fields.policyQualifiers.present) {
+      // The qualifier body stays raw (per the ESS scope), but the RFC 5280
+      // §4.2.1.4 structure is validated fail-closed by the shared assertion — the
+      // same PolicyInformation shape the certificatePolicies decoder enforces.
+      var q = m.fields.policyQualifiers.node;
+      pkix.assertPolicyQualifiers(q, function (msg, cause) { throw ctx.E("smime/bad-policy-information", msg, cause); });
+      qualifiers = q.bytes;
+    }
+    return {
+      policyIdentifier: m.fields.policyIdentifier.value,
+      name: ctx.oid.name(m.fields.policyIdentifier.value) || null,
+      policyQualifiers: qualifiers,
+    };
+  },
+});
+// policies SEQUENCE OF PolicyInformation OPTIONAL — order-preserving; the ASN.1
+// module carries no SIZE bound, so an explicitly present but empty list is legal.
+var POLICIES = schema.seqOf(POLICY_INFORMATION, {
+  assert: "sequence", min: 0, code: "smime/bad-policies", what: "policies",
+  build: function (m) { return m.items.map(function (it) { return it.value.result; }); },
+});
+
+// ESSCertID ::= SEQUENCE { certHash Hash, issuerSerial IssuerSerial OPTIONAL }
+// (RFC 5035 §5.4.2). Hash ::= OCTET STRING — for v1 it is the SHA-1 hash of the
+// whole certificate with NO algorithm field, so the hash algorithm is SYNTHESIZED
+// as the implied SHA-1 to make v1 shape-compatible with v2 for a verifier.
+var ESS_CERT_ID = schema.seq([
+  schema.field("certHash", schema.octetString()),
+  schema.optional("issuerSerial", ISSUER_SERIAL, { whenUniversal: [TAGS.SEQUENCE] }),
+], {
+  assert: "sequence", code: "smime/bad-ess-cert-id", what: "ESSCertID",
+  build: function (m) {
+    return {
+      certHash: m.fields.certHash.value,
+      hashAlgorithm: { oid: OID_SHA1, name: "sha1", parameters: null, implied: true },
+      issuerSerial: m.fields.issuerSerial.present ? m.fields.issuerSerial.value.result : null,
+    };
+  },
+});
+
+// ESSCertIDv2 ::= SEQUENCE { hashAlgorithm AlgorithmIdentifier DEFAULT
+//   {algorithm id-sha256}, certHash Hash, issuerSerial IssuerSerial OPTIONAL }
+// (RFC 5035 §5.4.1 / §4). The mandatory certHash OCTET STRING pivots between the
+// two optional SEQUENCEs, so a leading SEQUENCE is hashAlgorithm and a leading
+// OCTET STRING means hashAlgorithm defaulted.
+var ESS_CERT_ID_V2 = schema.seq([
+  schema.optional("hashAlgorithm", ALGID, { whenUniversal: [TAGS.SEQUENCE] }),
+  schema.field("certHash", schema.octetString()),
+  schema.optional("issuerSerial", ISSUER_SERIAL, { whenUniversal: [TAGS.SEQUENCE] }),
+], {
+  assert: "sequence", code: "smime/bad-ess-cert-id-v2", what: "ESSCertIDv2",
+  build: function (m, ctx) {
+    var hashAlgorithm;
+    if (m.fields.hashAlgorithm.present) {
+      var alg = m.fields.hashAlgorithm.value.result;
+      // X.690 §11.5: a DEFAULT value MUST be omitted in DER. The default is
+      // {algorithm id-sha256, parameters ABSENT}; an explicit encoding byte-equal
+      // to it is a non-canonical DEFAULT and is rejected fail-closed (the
+      // structured-value analogue of the primitive-DEFAULT rejection the toolkit
+      // already enforces). A present hashAlgorithm carrying a redundant NULL
+      // parameters is NOT byte-equal to the params-absent default and decodes.
+      if (alg.oid === OID_SHA256 && alg.parameters === null) {
+        throw ctx.E("smime/non-canonical-default",
+          "ESSCertIDv2 hashAlgorithm equal to the DEFAULT {algorithm id-sha256} MUST be omitted (X.690 §11.5)");
+      }
+      hashAlgorithm = { oid: alg.oid, name: alg.name, parameters: alg.parameters, defaulted: false };
+    } else {
+      hashAlgorithm = { oid: OID_SHA256, name: "sha256", parameters: null, defaulted: true };
+    }
+    return {
+      certHash: m.fields.certHash.value,
+      hashAlgorithm: hashAlgorithm,
+      issuerSerial: m.fields.issuerSerial.present ? m.fields.issuerSerial.value.result : null,
+    };
+  },
+});
+
+// SigningCertificate ::= SEQUENCE { certs SEQUENCE OF ESSCertID,
+//   policies SEQUENCE OF PolicyInformation OPTIONAL } (RFC 5035 §5.4.2). certs is
+// order-preserving — RFC 5035 §3 makes the FIRST element the signing certificate
+// — and non-empty (an empty certs cannot name a signing cert).
+function signingCertificateSchema(essCertId, code, what) {
+  return schema.seq([
+    schema.field("certs", schema.seqOf(essCertId, { assert: "sequence", min: 1, code: "smime/bad-certs", what: "certs" })),
+    schema.optional("policies", POLICIES, { whenUniversal: [TAGS.SEQUENCE] }),
+  ], {
+    assert: "sequence", code: code, what: what,
+    build: function (m, ctx) {
+      var certs = m.fields.certs.value.items.map(function (it) { return it.value.result; });
+      assertSignerIssuerIsDirectoryName(certs, function (msg) { throw ctx.E("smime/bad-issuer-serial", msg); });
+      return {
+        certs: certs,
+        policies: m.fields.policies.present ? m.fields.policies.value.result : null,
+      };
+    },
+  });
+}
+var SIGNING_CERTIFICATE = signingCertificateSchema(ESS_CERT_ID, "smime/bad-signing-certificate", "SigningCertificate");
+var SIGNING_CERTIFICATE_V2 = signingCertificateSchema(ESS_CERT_ID_V2, "smime/bad-signing-certificate-v2", "SigningCertificateV2");
+
+// SMIMECapability ::= SEQUENCE { capabilityID OBJECT IDENTIFIER,
+//   parameters ANY DEFINED BY capabilityID OPTIONAL } (RFC 8551 §2.5.2). Distinct
+// domain from AlgorithmIdentifier though isomorphic — surfaced as capabilityID +
+// raw parameters (the ANY-DEFINED-BY interpretation is a negotiation concern).
+var SMIME_CAPABILITY = schema.seq([
+  schema.field("capabilityID", schema.oidLeaf()),
+  schema.optional("parameters", schema.any(), { whenAny: true }),
+], {
+  assert: "sequence", code: "smime/bad-capability", what: "SMIMECapability",
+  build: function (m, ctx) {
+    return {
+      capabilityID: m.fields.capabilityID.value,
+      name: ctx.oid.name(m.fields.capabilityID.value) || null,
+      parameters: m.fields.parameters.present ? m.fields.parameters.node.bytes : null,
+    };
+  },
+});
+// SMIMECapabilities ::= SEQUENCE OF SMIMECapability — ordered by preference
+// (RFC 8551 §2.5.2), never sorted; an empty list is legal.
+var SMIME_CAPABILITIES = schema.seqOf(SMIME_CAPABILITY, {
+  assert: "sequence", min: 0, code: "smime/bad-capabilities", what: "SMIMECapabilities",
+  build: function (m) { return { capabilities: m.items.map(function (it) { return it.value.result; }) }; },
+});
+
+/**
+ * @primitive  pki.schema.smime.parseSigningCertificate
+ * @signature  pki.schema.smime.parseSigningCertificate(der) -> { certs, policies }
+ * @since      0.1.22
+ * @status     experimental
+ * @spec       RFC 5035, RFC 2634
+ * @related    pki.schema.smime.parseSigningCertificateV2, pki.schema.smime.decodeAttribute
+ *
+ * Decode an ESS v1 `SigningCertificate` attribute value (RFC 5035 §5.4.2) — the
+ * raw `AttributeValue` a CMS consumer plucks off `SignerInfo.signedAttrs`. Returns
+ * `{ certs, policies }`: each `certs` entry is `{ certHash, hashAlgorithm,
+ * issuerSerial }` in wire order (the first is the signing certificate), where
+ * `hashAlgorithm` is the implied SHA-1 (v1 carries no algorithm field) and
+ * `issuerSerial` (or `null`) surfaces the issuer `GeneralNames` + serial. Throws a
+ * typed `smime/*` (or leaf `asn1/*`) error on malformed input.
+ *
+ * @example
+ *   var b = pki.asn1.build;
+ *   var essCertId = b.sequence([b.octetString(Buffer.alloc(20, 1))]);   // SHA-1 hash, no issuerSerial
+ *   var av = b.sequence([b.sequence([essCertId])]);                     // SigningCertificate { certs }
+ *   var sc = pki.schema.smime.parseSigningCertificate(av);
+ *   sc.certs[0].hashAlgorithm.name;    // "sha1" (implied)
+ */
+var parseSigningCertificate = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorClass: SmimeError, prefix: "smime", what: "SigningCertificate", topSchema: SIGNING_CERTIFICATE, ns: NS });
+
+/**
+ * @primitive  pki.schema.smime.parseSigningCertificateV2
+ * @signature  pki.schema.smime.parseSigningCertificateV2(der) -> { certs, policies }
+ * @since      0.1.22
+ * @status     experimental
+ * @spec       RFC 5035, RFC 5816
+ * @related    pki.schema.smime.parseSigningCertificate, pki.schema.smime.decodeAttribute
+ *
+ * Decode an ESS v2 `SigningCertificateV2` attribute value (RFC 5035 §5.4.1).
+ * Identical shape to v1 but each `certs` entry carries a real `hashAlgorithm`:
+ * decoded when present, or the RFC 5035 §4 default `id-sha256` (with
+ * `defaulted: true`) when omitted. An explicit `hashAlgorithm` byte-equal to that
+ * default is a non-canonical DER encoding and is rejected `smime/non-canonical-default`
+ * (X.690 §11.5). Throws a typed `smime/*` error on malformed input.
+ *
+ * @example
+ *   var b = pki.asn1.build;
+ *   var essCertId = b.sequence([b.octetString(Buffer.alloc(32, 2))]);   // hashAlgorithm defaulted
+ *   var av = b.sequence([b.sequence([essCertId])]);
+ *   var sc = pki.schema.smime.parseSigningCertificateV2(av);
+ *   sc.certs[0].hashAlgorithm.defaulted;   // true (SHA-256 default)
+ */
+var parseSigningCertificateV2 = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorClass: SmimeError, prefix: "smime", what: "SigningCertificateV2", topSchema: SIGNING_CERTIFICATE_V2, ns: NS });
+
+/**
+ * @primitive  pki.schema.smime.parseSmimeCapabilities
+ * @signature  pki.schema.smime.parseSmimeCapabilities(der) -> { capabilities }
+ * @since      0.1.22
+ * @status     experimental
+ * @spec       RFC 8551
+ * @related    pki.schema.smime.decodeAttribute
+ *
+ * Decode an `SMIMECapabilities` attribute value (RFC 8551 §2.5.2) into
+ * `{ capabilities }` — an ORDERED list (preference order, never sorted), each
+ * `{ capabilityID, name, parameters }` with `parameters` the raw
+ * `ANY DEFINED BY capabilityID` bytes (or `null`). Throws a typed `smime/*` error
+ * on malformed input.
+ *
+ * @example
+ *   var b = pki.asn1.build;
+ *   var cap = b.sequence([b.oid(pki.oid.byName("aes256-CBC"))]);
+ *   var caps = pki.schema.smime.parseSmimeCapabilities(b.sequence([cap]));
+ *   caps.capabilities[0].name;    // "aes256-CBC"
+ */
+var parseSmimeCapabilities = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorClass: SmimeError, prefix: "smime", what: "SMIMECapabilities", topSchema: SMIME_CAPABILITIES, ns: NS });
+
+/**
+ * @primitive  pki.schema.smime.decodeAttribute
+ * @signature  pki.schema.smime.decodeAttribute(attr) -> { kind, ... }
+ * @since      0.1.22
+ * @status     experimental
+ * @spec       RFC 8551, RFC 5035
+ * @related    pki.schema.smime.parseSigningCertificate, pki.schema.cms.parse
+ *
+ * OID-dispatch convenience over the three value decoders for a CMS-shaped
+ * `{ type, values }` attribute (the shape `cms.parse` surfaces on
+ * `signerInfos[i].signedAttrs`). Enforces the single-`AttributeValue` rule
+ * (RFC 8551 §2.5.2 / §2.5) — a `values` length other than 1 is rejected
+ * `smime/multi-valued-attribute` — then routes on `attr.type`:
+ * `signingCertificate` / `signingCertificateV2` / `smimeCapabilities` decode to
+ * `{ kind, ...result }`; any other type is recognize-and-deferred
+ * `smime/unsupported-attribute` (its `type`, registry `name`, and raw `values`
+ * carried on the error so a caller keeps the bytes).
+ *
+ * @example
+ *   var b = pki.asn1.build;
+ *   var essCertId = b.sequence([b.octetString(Buffer.alloc(32, 2))]);   // ESSCertIDv2, hashAlgorithm defaulted
+ *   var av = b.sequence([b.sequence([essCertId])]);                     // SigningCertificateV2 { certs: [ ESSCertIDv2 ] }
+ *   var got = pki.schema.smime.decodeAttribute({ type: pki.oid.byName("signingCertificateV2"), values: [av] });
+ *   got.kind;    // "signingCertificateV2"
+ */
+function decodeAttribute(attr) {
+  if (!attr || typeof attr !== "object" || typeof attr.type !== "string" || !Array.isArray(attr.values)) {
+    throw new SmimeError("smime/bad-input", "decodeAttribute expects a CMS attribute { type, values }");
+  }
+  // Route on the attribute OID FIRST. The single-AttributeValue MUST (RFC 8551
+  // §2.5.2) is specific to the ESS / SMIMECapabilities attributes, so it is
+  // enforced only inside the known-type branch; an unknown / custom attribute
+  // recognize-and-defers with its raw values intact regardless of value count
+  // (its own cardinality rules are not this decoder's to enforce).
+  if (attr.type === OID_SIGNING_CERTIFICATE || attr.type === OID_SIGNING_CERTIFICATE_V2 || attr.type === OID_SMIME_CAPABILITIES) {
+    if (attr.values.length !== 1) {
+      throw new SmimeError("smime/multi-valued-attribute",
+        "an ESS / SMIMECapabilities attribute MUST carry exactly one AttributeValue, got " + attr.values.length + " (RFC 8551 §2.5.2)");
+    }
+    var value = attr.values[0];
+    if (attr.type === OID_SIGNING_CERTIFICATE) { var v1 = parseSigningCertificate(value); return { kind: "signingCertificate", certs: v1.certs, policies: v1.policies }; }
+    if (attr.type === OID_SIGNING_CERTIFICATE_V2) { var v2 = parseSigningCertificateV2(value); return { kind: "signingCertificateV2", certs: v2.certs, policies: v2.policies }; }
+    return { kind: "smimeCapabilities", capabilities: parseSmimeCapabilities(value).capabilities };
+  }
+  var e = new SmimeError("smime/unsupported-attribute", "unsupported S/MIME attribute type " + attr.type + (oid.name(attr.type) ? " (" + oid.name(attr.type) + ")" : ""));
+  e.type = attr.type;
+  e.name = oid.name(attr.type) || null;
+  e.values = attr.values;
+  throw e;
+}
+
+module.exports = {
+  parseSigningCertificate: parseSigningCertificate,
+  parseSigningCertificateV2: parseSigningCertificateV2,
+  parseSmimeCapabilities: parseSmimeCapabilities,
+  decodeAttribute: decodeAttribute,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "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:f23ca197-835e-4ec8-8d04-486fb3d9deac",
+  "serialNumber": "urn:uuid:38c53855-3eaa-4d1a-8c48-b03540881d8a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-09T14:17:20.162Z",
+    "timestamp": "2026-07-09T18:46:47.249Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.20",
+      "bom-ref": "@blamejs/pki@0.1.22",
       "type": "application",
       "name": "pki",
-      "version": "0.1.20",
+      "version": "0.1.22",
       "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.1.20",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.22",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.20",
+      "ref": "@blamejs/pki@0.1.22",
       "dependsOn": []
     }
   ]