@blamejs/pki 0.1.21 → 0.1.23

package/lib/ct.js

@@ -14,26 +14,26 @@
  *   OCSP response) carries in the SCT extension into its individual signed
  *   certificate timestamps.
  *
- *   The SCT payload is encoded in the TLS presentation language (RFC 8446 §3 /
- *   RFC 5246 §4 conventions) — positional, tag-less, fixed-width big-endian
- *   integers and length-prefixed opaque vectors — NOT ASN.1/DER. So this module
+ *   The SCT payload is encoded in the TLS presentation language (RFC 8446 sec. 3 /
+ *   RFC 5246 sec. 4 conventions) -- positional, tag-less, fixed-width big-endian
+ *   integers and length-prefixed opaque vectors -- NOT ASN.1/DER. So this module
  *   owns a bounded big-endian TLS-struct reader rather than composing the DER
- *   schema engine; the only ASN.1 surface is the §3.3 double wrap (the
+ *   schema engine; the only ASN.1 surface is the sec. 3.3 double wrap (the
  *   extension value is a DER OCTET STRING whose content is another DER OCTET
- *   STRING whose content is the TLS list — the certificate/OCSP layer peels the
+ *   STRING whose content is the TLS list -- the certificate/OCSP layer peels the
  *   outer, this module peels the inner).
  *
  *   Structure is decoded, crypto is surfaced RAW: each SCT surfaces its `logId`
- *   (32 raw bytes — SHA-256 of the log's SPKI, never recomputed), the exact
+ *   (32 raw bytes -- SHA-256 of the log's SPKI, never recomputed), the exact
  *   `timestamp` as a BigInt, the raw `extensions`, the named-but-not-interpreted
  *   `hashAlg`/`sigAlg` code points, and the raw `signature`. The parser NEVER
- *   verifies a signature, recomputes a LogID, or trusts a log — a verifier
+ *   verifies a signature, recomputes a LogID, or trusts a log -- a verifier
  *   composes `webcrypto` over `reconstructSignedData(...)`, the exact
  *   `digitally-signed` preimage. DER-only carrier, fail-closed.
  *
  * @card
  *   Parse RFC 6962 Certificate Transparency SCT lists from a certificate or OCSP
- *   extension — per-SCT logId / timestamp (BigInt) / algorithm / raw signature,
+ *   extension -- per-SCT logId / timestamp (BigInt) / algorithm / raw signature,
  *   the signed-preimage reconstruction surfaced for external verification,
  *   bounded TLS-struct decode, fail-closed.
  */
@@ -45,8 +45,8 @@ var frameworkError = require("./framework-error.js");
 var CtError = frameworkError.CtError;
 var C = constants;
 
-// RFC 5246 §7.4.1.4.1 code points — 1-byte, NOT OIDs. Surfaced named; an
-// unknown code surfaces as its numeric byte with a null name (never rejected —
+// RFC 5246 sec. 7.4.1.4.1 code points -- 1-byte, NOT OIDs. Surfaced named; an
+// unknown code surfaces as its numeric byte with a null name (never rejected --
 // off-profile-pair rejection is a verifier-tier log-conformance concern).
 var HASH_ALGORITHMS = {
   0: "none", 1: "md5", 2: "sha1", 3: "sha224", 4: "sha256", 5: "sha384", 6: "sha512",
@@ -59,7 +59,7 @@ var SCT_MIN_BODY = 47;
 var LOGID_BYTES = 32;
 var MAX_SAFE = 9007199254740991n;   // 2^53 - 1; above this a Number loses precision
 
-// ---- TlsReader — the one net-new primitive (an ENCODING layer, not a schema
+// ---- TlsReader -- the one net-new primitive (an ENCODING layer, not a schema
 // combinator): a bounded big-endian TLS-vector cursor with a hard [pos, end).
 // A lying inner length can overrun only the current sub-reader's `end`, never
 // the parent buffer, so bounds-before-slice is structural.
@@ -81,7 +81,7 @@ TlsReader.prototype.fixed = function (n, code) {
   this._need(n, code);
   var s = this.buf.subarray(this.pos, this.pos + n); this.pos += n; return s;
 };
-// opaque<min..max> — a length-prefixed vector (lenWidth-byte big-endian prefix).
+// opaque<min..max> -- a length-prefixed vector (lenWidth-byte big-endian prefix).
 // The length prefix itself is a plain read (a truncation there is ct/truncated);
 // only a LYING length whose body overruns the bound carries the field's own code.
 TlsReader.prototype.vector = function (lenWidth, min, max, code) {
@@ -98,16 +98,16 @@ TlsReader.prototype.subReader = function (len, code) {
 TlsReader.prototype.remaining = function () { return this.end - this.pos; };
 TlsReader.prototype.atEnd = function () { return this.pos === this.end; };
 
-// Peel the RFC 6962 §3.3 inner DER OCTET STRING (the certificate/OCSP layer
+// Peel the RFC 6962 sec. 3.3 inner DER OCTET STRING (the certificate/OCSP layer
 // already peeled the outer extnValue OCTET STRING). Rides the strict codec, so
 // an indefinite length / constructed OCTET STRING / trailing bytes / single
 // wrap all fail closed here; the asn1/* fault attaches as `.cause`.
 function _peelInner(extValue) {
   var node;
   try { node = asn1.decode(extValue); }
-  catch (e) { throw new CtError("ct/bad-der", "the SCT-list extension value is not valid DER (RFC 6962 §3.3)", e); }
+  catch (e) { throw new CtError("ct/bad-der", "the SCT-list extension value is not valid DER (RFC 6962 sec. 3.3)", e); }
   try { return asn1.read.octetString(node); }
-  catch (e) { throw new CtError("ct/bad-der", "the SCT-list extension value must be a DER OCTET STRING wrapping the TLS list (RFC 6962 §3.3)", e); }
+  catch (e) { throw new CtError("ct/bad-der", "the SCT-list extension value must be a DER OCTET STRING wrapping the TLS list (RFC 6962 sec. 3.3)", e); }
 }
 
 function _toBuffer(v, field) {
@@ -119,9 +119,9 @@ function _toBuffer(v, field) {
 // Parse one SerializedSCT body inside a sub-reader bounded to the element (so a
 // lying extensions/signature length overruns the element, never the list). A
 // version this parser does not define is preserved OPAQUE, not rejected: RFC 6962
-// §3.3 gives every SerializedSCT its own length prefix precisely so a client "can
+// sec. 3.3 gives every SerializedSCT its own length prefix precisely so a client "can
 // still parse old SCTs while skipping over new SCTs whose versions they don't
-// understand" — so an unknown version yields { unknown, version, rawSct } and the
+// understand" -- so an unknown version yields { unknown, version, rawSct } and the
 // v1-specific field decode (and the 47-byte floor) is skipped.
 function _parseSct(r, sctLen) {
   var bodyStart = r.pos;
@@ -130,7 +130,7 @@ function _parseSct(r, sctLen) {
     return { unknown: true, version: version, rawSct: r.buf.subarray(bodyStart, r.end) };
   }
   if (sctLen < SCT_MIN_BODY) {
-    throw new CtError("ct/sct-too-short", "a v1 SCT body is at least " + SCT_MIN_BODY + " bytes, got " + sctLen + " (RFC 6962 §3.2)");
+    throw new CtError("ct/sct-too-short", "a v1 SCT body is at least " + SCT_MIN_BODY + " bytes, got " + sctLen + " (RFC 6962 sec. 3.2)");
   }
   var logId = r.fixed(LOGID_BYTES);
   var timestamp = r.u64();
@@ -139,7 +139,7 @@ function _parseSct(r, sctLen) {
   var sigAlg = r.u8();
   var signature = r.vector(2, 0, null, "ct/sig-overrun");
   if (!r.atEnd()) {
-    throw new CtError("ct/sct-trailing-bytes", (r.end - r.pos) + " byte(s) left in a SerializedSCT after the signature (RFC 6962 §3.3)");
+    throw new CtError("ct/sct-trailing-bytes", (r.end - r.pos) + " byte(s) left in a SerializedSCT after the signature (RFC 6962 sec. 3.3)");
   }
   var timestampMs = timestamp <= MAX_SAFE ? Number(timestamp) : null;
   return {
@@ -176,13 +176,13 @@ function _parseSct(r, sctLen) {
  * `signatureAlgorithm`, the raw `signature` Buffer, and `rawSct` (the full
  * SerializedSCT body). A SerializedSCT whose version this parser does not define
  * is preserved OPAQUE in `unknownScts` as `{ version, rawSct }` rather than
- * failing the list — RFC 6962 §3.3 frames each SerializedSCT with its own length
+ * failing the list -- RFC 6962 sec. 3.3 frames each SerializedSCT with its own length
  * so unknown versions are skippable (forward compatibility).
  *
  * The extension value is a DER `OCTET STRING` wrapping the TLS-encoded list
- * (RFC 6962 §3.3 double wrap); everything below that peel is TLS presentation
+ * (RFC 6962 sec. 3.3 double wrap); everything below that peel is TLS presentation
  * language, decoded with a bounded cursor. Structure is decoded, crypto is
- * surfaced RAW — the signature is never verified and the LogID never recomputed.
+ * surfaced RAW -- the signature is never verified and the LogID never recomputed.
  *
  * Throws `CtError` with a stable `ct/*` code on any malformed input (a bad inner
  * DER wrap is `ct/bad-der` with the `asn1/*` fault as `.cause`), never a raw
@@ -209,22 +209,22 @@ function parseSctList(extValue) {
   var outer = new TlsReader(blob, 0, blob.length);
   var listLen = outer.u16("ct/bad-list");
   if (listLen + 2 !== blob.length) {
-    throw new CtError("ct/bad-list", "the SCT list declared length " + listLen + " does not match the " + (blob.length - 2) + " byte(s) present (RFC 6962 §3.3)");
+    throw new CtError("ct/bad-list", "the SCT list declared length " + listLen + " does not match the " + (blob.length - 2) + " byte(s) present (RFC 6962 sec. 3.3)");
   }
   if (listLen < 1) {
-    throw new CtError("ct/empty-list", "an SCT list must contain at least one SCT (RFC 6962 §3.3)");
+    throw new CtError("ct/empty-list", "an SCT list must contain at least one SCT (RFC 6962 sec. 3.3)");
   }
   var scts = [], unknownScts = [];
   while (!outer.atEnd()) {
     if (outer.remaining() < 2) {
-      throw new CtError("ct/list-trailing-bytes", "a dangling partial element after the last complete SCT (RFC 6962 §3.3)");
+      throw new CtError("ct/list-trailing-bytes", "a dangling partial element after the last complete SCT (RFC 6962 sec. 3.3)");
     }
     var sctLen = outer.u16("ct/list-trailing-bytes");
     if (sctLen < 1) {
-      throw new CtError("ct/sct-empty", "a SerializedSCT must be non-empty (RFC 6962 §3.3)");
+      throw new CtError("ct/sct-empty", "a SerializedSCT must be non-empty (RFC 6962 sec. 3.3)");
     }
     if (outer.remaining() < sctLen) {
-      throw new CtError("ct/list-trailing-bytes", "a SerializedSCT length " + sctLen + " overruns the list (RFC 6962 §3.3)");
+      throw new CtError("ct/list-trailing-bytes", "a SerializedSCT length " + sctLen + " overruns the list (RFC 6962 sec. 3.3)");
     }
     var one = _parseSct(outer.subReader(sctLen, "ct/list-trailing-bytes"), sctLen);
     if (one.unknown) unknownScts.push({ version: one.version, rawSct: one.rawSct });
@@ -240,7 +240,7 @@ function parseSctList(extValue) {
 
 function _u24Bytes(n) {
   if (n < 1 || n > 0xffffff) {
-    throw new CtError("ct/bad-tbs-length", "a certificate / TBSCertificate length must be in 1..2^24-1, got " + n + " (RFC 6962 §3.1)");
+    throw new CtError("ct/bad-tbs-length", "a certificate / TBSCertificate length must be in 1..2^24-1, got " + n + " (RFC 6962 sec. 3.1)");
   }
   return Buffer.from([(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff]);
 }
@@ -254,20 +254,22 @@ function _u24Bytes(n) {
  * @related    pki.ct.parseSctList
  *
  * Rebuild the exact `digitally-signed` preimage bytes an external verifier
- * hashes to check an SCT's signature (RFC 6962 §3.2), for a parsed `sct`.
+ * hashes to check an SCT's signature (RFC 6962 sec. 3.2), for a parsed `sct`.
  * `entry` selects the log-entry arm:
- *   - `{ entryType: 0, leafCert: <DER Buffer> }` — an SCT delivered over TLS /
+ *   - `{ entryType: 0, leafCert: <DER Buffer> }` -- an SCT delivered over TLS /
  *     OCSP, signed over `x509_entry(0)` with the leaf certificate.
- *   - `{ entryType: 1, tbsCertificate: <DER Buffer>, issuerKeyHash: <32B> }` —
+ *   - `{ entryType: 1, tbsCertificate: <DER Buffer>, issuerKeyHash: <32B> }` --
  *     an SCT EMBEDDED in a certificate, signed over `precert_entry(1)` with the
  *     issuer key hash + the precertificate TBS (the TBS with only the SCT
  *     extension removed). `issuerKeyHash` is SHA-256 of the issuer's SPKI DER.
  *
  * The preimage reuses the parsed SCT's raw `extensions` byte-for-byte and
- * re-emits the fixed-width scalars canonically. This never verifies anything —
+ * re-emits the fixed-width scalars canonically. This never verifies anything --
  * a verifier hashes the returned bytes and checks the signature with the log's
  * public key (compose `webcrypto`). Throws `CtError` (`ct/bad-entry-type`,
- * `ct/bad-issuer-key-hash`, `ct/bad-tbs-length`) on a malformed entry.
+ * `ct/bad-issuer-key-hash`, `ct/bad-tbs-length`) on a malformed entry, and
+ * `ct/bad-input` / `ct/bad-extensions` on an `sct` whose timestamp or
+ * extensions exceed their RFC 6962 3.2 wire ranges (uint64 / opaque<0..2^16-1>).
  *
  * @example
  *   var sct = pki.ct.parseSctList(sctExtValue).scts[0];
@@ -278,17 +280,23 @@ function reconstructSignedData(entry, sct) {
   entry = entry || {};
   var entryType = entry.entryType;
   if (entryType !== 0 && entryType !== 1) {
-    throw new CtError("ct/bad-entry-type", "entryType must be x509_entry(0) or precert_entry(1), got " + entryType + " (RFC 6962 §3.1)");
+    throw new CtError("ct/bad-entry-type", "entryType must be x509_entry(0) or precert_entry(1), got " + entryType + " (RFC 6962 sec. 3.1)");
   }
-  // A fully decoded v1 SCT (from parseSctList().scts[]) — not an opaque
+  // A fully decoded v1 SCT (from parseSctList().scts[]) -- not an opaque
   // unknownScts entry, whose body layout is undefined and cannot be signed over.
   if (!sct || typeof sct.timestamp !== "bigint" || sct.version !== 0) {
     throw new CtError("ct/bad-input", "reconstructSignedData expects a decoded v1 SCT from parseSctList().scts[]");
   }
+  // RFC 6962 3.2: the timestamp is a uint64. A hand-built value outside
+  // 0..2^64-1 cannot fill the fixed 8-byte field -- refused typed here rather
+  // than escaping as a raw RangeError from the Buffer write.
+  if (sct.timestamp < 0n || sct.timestamp > 0xffffffffffffffffn) {
+    throw new CtError("ct/bad-input", "sct.timestamp must be a uint64 (0..2^64-1), got " + sct.timestamp.toString() + " (RFC 6962 3.2)");
+  }
   var parts = [];
-  parts.push(Buffer.from([sct.version & 0xff]));                          // Version — v1(0)
-  parts.push(Buffer.from([0]));                                          // SignatureType — certificate_timestamp(0)
-  var ts = Buffer.alloc(8); ts.writeBigUInt64BE(BigInt(sct.timestamp)); parts.push(ts);   // uint64 timestamp
+  parts.push(Buffer.from([sct.version & 0xff]));                          // Version -- v1(0)
+  parts.push(Buffer.from([0]));                                          // SignatureType -- certificate_timestamp(0)
+  var ts = Buffer.alloc(8); ts.writeBigUInt64BE(sct.timestamp); parts.push(ts);   // uint64 timestamp
   parts.push(Buffer.from([(entryType >> 8) & 0xff, entryType & 0xff]));  // LogEntryType (2 bytes BE)
   if (entryType === 0) {
     var cert = _toBuffer(entry.leafCert, "leafCert");
@@ -296,13 +304,20 @@ function reconstructSignedData(entry, sct) {
   } else {
     var ikh = _toBuffer(entry.issuerKeyHash, "issuerKeyHash");
     if (ikh.length !== 32) {
-      throw new CtError("ct/bad-issuer-key-hash", "issuer_key_hash must be exactly 32 bytes (SHA-256 of the issuer SPKI), got " + ikh.length + " (RFC 6962 §3.2)");
+      throw new CtError("ct/bad-issuer-key-hash", "issuer_key_hash must be exactly 32 bytes (SHA-256 of the issuer SPKI), got " + ikh.length + " (RFC 6962 sec. 3.2)");
     }
     var tbs = _toBuffer(entry.tbsCertificate, "tbsCertificate");
     parts.push(ikh);
     parts.push(_u24Bytes(tbs.length)); parts.push(tbs);                  // PreCert.tbs_certificate<1..2^24-1>
   }
   var ext = _toBuffer(sct.extensions, "sct.extensions");                 // reuse the parsed raw bytes, never re-encode
+  // RFC 6962 3.2: CtExtensions is opaque<0..2^16-1>. A longer value is
+  // unrepresentable -- its 2-byte prefix would silently truncate mod 65536,
+  // an internally inconsistent preimage -- so it is refused, matching the
+  // range check the u24 certificate lengths get.
+  if (ext.length > 0xffff) {
+    throw new CtError("ct/bad-extensions", "CtExtensions must be 0..65535 bytes, got " + ext.length + " (RFC 6962 3.2)");
+  }
   parts.push(Buffer.from([(ext.length >> 8) & 0xff, ext.length & 0xff])); parts.push(ext);   // CtExtensions
   return Buffer.concat(parts);
 }

package/lib/framework-error.js

@@ -16,10 +16,10 @@
  *   `{ name, code, message, permanent, isPkiError: true }`.
  *
  *   `code` is a stable, greppable `domain/reason` string
- *   (`asn1/indefinite-length`, `x509/not-a-certificate`) — safe to switch
+ *   (`asn1/indefinite-length`, `x509/not-a-certificate`) -- safe to switch
  *   on and safe to log. Because every failure here is a deterministic
  *   verdict on the bytes in hand (a malformed length, an unknown OID
- *   shape, a truncated certificate), errors are `permanent: true` — the
+ *   shape, a truncated certificate), errors are `permanent: true` -- the
  *   same input will never parse on retry.
  *
  * @card
@@ -27,6 +27,10 @@
  *   classes the toolkit throws.
  */
 
+// The frozen shape of every error code: a `domain/reason` string of
+// lowercase alphanumerics and dashes.
+var CODE_SHAPE = /^[a-z0-9-]+\/[a-z0-9-]+$/;
+
 /**
  * @primitive  pki.errors.PkiError
  * @signature  new PkiError(message, code)
@@ -36,6 +40,11 @@
  *
  * Base class every toolkit error extends. Provides the unified
  * `instanceof` check plus the `{ name, code, isPkiError }` shape.
+ * A supplied `code` must be a `domain/reason` string (lowercase
+ * alphanumerics and dashes) -- the construction throws a `TypeError`
+ * otherwise, which catches an argument-order swap with the
+ * `defineClass` subclasses' `(code, message)` convention at the call
+ * site instead of shipping prose into a code-switching consumer.
  *
  * @example
  *   try { pki.asn1.decode(bytes); }
@@ -47,7 +56,14 @@ class PkiError extends Error {
   constructor(message, code) {
     super(message);
     this.name = "PkiError";
-    this.code = code || "pki/invalid";
+    var c = code || "pki/invalid";
+    if (typeof c !== "string" || !CODE_SHAPE.test(c)) {
+      throw new TypeError(
+        "PkiError code must be a domain/reason string, got " + String(c) +
+        " (PkiError takes (message, code); defineClass subclasses take (code, message))"
+      );
+    }
+    this.code = c;
     this.isPkiError = true;
     this.permanent = true;
   }
@@ -60,13 +76,16 @@ class PkiError extends Error {
  * @status     stable
  * @spec       internal (design: error-class factory)
  *
- * Factory that produces a `PkiError` subclass with the standard shape —
+ * Factory that produces a `PkiError` subclass with the standard shape --
  * eliminating the per-domain boilerplate. The returned constructor takes
  * `(code, message)`, stamps `name`, sets an `is<Name>` flag, and exposes
  * a `.factory` static for the common `var _err = XxxError.factory` shape.
+ * The `code` must be a `domain/reason` string (the base-class contract);
+ * without `withCause`, a third constructor argument throws a `TypeError`
+ * rather than silently discarding a cause the caller meant to thread.
  *
  * @opts
- *   withCause:  boolean,  // default: false — constructor becomes (code, message, cause)
+ *   withCause:  boolean,  // default: false -- constructor becomes (code, message, cause)
  *
  * @example
  *   var MyError = pki.errors.defineClass("MyError");
@@ -85,7 +104,11 @@ function defineClass(name, opts) {
       super(message, code);
       this.name = name;
       this[flagKey] = true;
-      if (withCause && arg3 !== undefined) this.cause = arg3;
+      if (withCause) {
+        if (arg3 !== undefined) this.cause = arg3;
+      } else if (arg3 !== undefined) {
+        throw new TypeError(name + " takes (code, message); to thread a cause, define the class with { withCause: true }");
+      }
     }
   };
   Object.defineProperty(GeneratedError, "name", { value: name, configurable: true });
@@ -97,93 +120,101 @@ function defineClass(name, opts) {
 
 // ---- Per-domain error classes ----
 
-// ConstantsError — a bad scale argument to C.TIME.* / C.BYTES.* (an
+// ConstantsError -- a bad scale argument to C.TIME.* / C.BYTES.* (an
 // authoring bug caught at config time).
 var ConstantsError = defineClass("ConstantsError");
 
-// Asn1Error — malformed / non-canonical DER: truncated TLV, indefinite
+// Asn1Error -- malformed / non-canonical DER: truncated TLV, indefinite
 // length, non-minimal length or integer, leftover trailing bytes, depth
 // or size cap exceeded. DER is a canonical encoding, so anything the
 // decoder rejects is permanently invalid.
 var Asn1Error = defineClass("Asn1Error");
 
-// OidError — a malformed object-identifier: fewer than two arcs, a first
+// OidError -- a malformed object-identifier: fewer than two arcs, a first
 // arc outside 0..2, a second arc >= 40 under arcs 0/1, or a non-minimal
 // base-128 sub-identifier.
 var OidError = defineClass("OidError");
 
-// PemError — a malformed PEM envelope: missing / mismatched BEGIN/END
+// PemError -- a malformed PEM envelope: missing / mismatched BEGIN/END
 // markers, a bad label, or non-base64 body.
 var PemError = defineClass("PemError");
 
-// CertificateError — a byte sequence that is not a well-formed X.509
+// CertificateError -- a byte sequence that is not a well-formed X.509
 // certificate (wrong outer structure, unparseable field, unsupported
 // version).
 var CertificateError = defineClass("CertificateError", { withCause: true });
 
-// CrlError — a byte sequence that is not a well-formed X.509 CRL
-// (CertificateList / TBSCertList — RFC 5280 §5).
+// CrlError -- a byte sequence that is not a well-formed X.509 CRL
+// (CertificateList / TBSCertList -- RFC 5280 sec. 5).
 var CrlError = defineClass("CrlError", { withCause: true });
 
-// SchemaError — the schema-family orchestrator's own errors (input that matches
+// SchemaError -- the schema-family orchestrator's own errors (input that matches
 // no registered format / does not decode). (code, message) shape like the rest.
 var SchemaError = defineClass("SchemaError", { withCause: true });
 
-// CsrError — a byte sequence that is not a well-formed PKCS#10 CertificationRequest
+// CsrError -- a byte sequence that is not a well-formed PKCS#10 CertificationRequest
 // (RFC 2986).
 var CsrError = defineClass("CsrError", { withCause: true });
 
-// Pkcs8Error — a byte sequence that is not a well-formed PKCS#8 PrivateKeyInfo /
-// OneAsymmetricKey or EncryptedPrivateKeyInfo (RFC 5208 §5, RFC 5958 §2/§3).
+// Pkcs8Error -- a byte sequence that is not a well-formed PKCS#8 PrivateKeyInfo /
+// OneAsymmetricKey or EncryptedPrivateKeyInfo (RFC 5208 sec. 5, RFC 5958 sec. 2/sec. 3).
 var Pkcs8Error = defineClass("Pkcs8Error", { withCause: true });
 
-// CmsError — a byte sequence that is not a well-formed CMS ContentInfo /
+// CmsError -- a byte sequence that is not a well-formed CMS ContentInfo /
 // SignedData (RFC 5652). Carries the underlying leaf fault as `.cause`.
 var CmsError = defineClass("CmsError", { withCause: true });
 
-// OcspError — a byte sequence that is not a well-formed OCSP request or response
-// (OCSPRequest / OCSPResponse — RFC 6960 §4). Carries the leaf fault as `.cause`.
+// OcspError -- a byte sequence that is not a well-formed OCSP request or response
+// (OCSPRequest / OCSPResponse -- RFC 6960 sec. 4). Carries the leaf fault as `.cause`.
 var OcspError = defineClass("OcspError", { withCause: true });
 
-// TspError — a byte sequence that is not a well-formed RFC 3161 timestamp token,
+// TspError -- a byte sequence that is not a well-formed RFC 3161 timestamp token,
 // TSTInfo, or TimeStampResp. Carries the underlying leaf fault as `.cause`.
 var TspError = defineClass("TspError", { withCause: true });
 
-// AttrCertError — a byte sequence that is not a well-formed X.509 Attribute
-// Certificate (AttributeCertificate / AttributeCertificateInfo — RFC 5755 §4),
+// AttrCertError -- a byte sequence that is not a well-formed X.509 Attribute
+// Certificate (AttributeCertificate / AttributeCertificateInfo -- RFC 5755 sec. 4),
 // or a recognized-and-deferred legacy AttributeCertificateV1. Carries the
 // underlying leaf fault as `.cause`.
 var AttrCertError = defineClass("AttrCertError", { withCause: true });
 
-// CrmfError — a byte sequence that is not a well-formed RFC 4211 CertReqMessages
+// CrmfError -- a byte sequence that is not a well-formed RFC 4211 CertReqMessages
 // / CertReqMsg / CertRequest / CertTemplate. Carries the underlying leaf fault as
 // `.cause`.
 var CrmfError = defineClass("CrmfError", { withCause: true });
 
-// Pkcs12Error — a byte sequence that is not a well-formed RFC 7292 PFX
-// (AuthenticatedSafe / SafeContents / SafeBag), or a PFX violating a §4
+// Pkcs12Error -- a byte sequence that is not a well-formed RFC 7292 PFX
+// (AuthenticatedSafe / SafeContents / SafeBag), or a PFX violating a sec. 4
 // coherence rule (version, integrity mode, bag dispatch, MacData). Carries
 // the underlying leaf fault as `.cause`.
 var Pkcs12Error = defineClass("Pkcs12Error", { withCause: true });
 
-// CmpError — a byte sequence that is not a well-formed RFC 9810 PKIMessage
-// (PKIHeader / PKIBody / protection / extraCerts), or one violating a §5
-// coherence rule (protection⇔protectionAlg, certConf-hashAlg⇔pvno). Carries
+// CmpError -- a byte sequence that is not a well-formed RFC 9810 PKIMessage
+// (PKIHeader / PKIBody / protection / extraCerts), or one violating a sec. 5
+// coherence rule (protection<=>protectionAlg, certConf-hashAlg<=>pvno). Carries
 // the underlying leaf fault as `.cause`.
 var CmpError = defineClass("CmpError", { withCause: true });
 
-// PathError — a certification path that fails RFC 5280 §6 validation, or a
+// PathError -- a certification path that fails RFC 5280 sec. 6 validation, or a
 // malformed input handed to the validator (an extension value that does not
 // decode, an empty path, an unsupported signature algorithm). Carries the
 // per-check reason in `.code` (`path/*`) and the underlying leaf fault as
 // `.cause`.
 var PathError = defineClass("PathError", { withCause: true });
 
-// CtError — a byte sequence that is not a well-formed RFC 6962 Certificate
+// 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 sec. 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
 // past its bound, a truncated element). An SCT whose version this parser does
-// not define is NOT an error — RFC 6962 §3.3 makes unknown versions skippable,
+// not define is NOT an error -- RFC 6962 sec. 3.3 makes unknown versions skippable,
 // so they are preserved opaque. Carries the underlying leaf fault (e.g. the
 // inner `asn1/*` decode error) as `.cause`.
 var CtError = defineClass("CtError", { withCause: true });
@@ -209,4 +240,5 @@ module.exports = {
   CmpError:         CmpError,
   PathError:        PathError,
   CtError:          CtError,
+  SmimeError:       SmimeError,
 };