@blamejs/pki 0.1.21 → 0.1.22

package/CHANGELOG.md

@@ -4,6 +4,18 @@ 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.

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.

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

@@ -370,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" });
 
@@ -495,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 };
@@ -838,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.21",
+  "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:bcaea9d8-cd0d-4a9f-8ac3-72b3efecc8be",
+  "serialNumber": "urn:uuid:38c53855-3eaa-4d1a-8c48-b03540881d8a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-09T15:12:46.820Z",
+    "timestamp": "2026-07-09T18:46:47.249Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.21",
+      "bom-ref": "@blamejs/pki@0.1.22",
       "type": "application",
       "name": "pki",
-      "version": "0.1.21",
+      "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.21",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.22",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.21",
+      "ref": "@blamejs/pki@0.1.22",
       "dependsOn": []
     }
   ]