@blamejs/pki 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -4,7 +4,31 @@ 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.8 — 2026-07-05
+## v0.1.10 — 2026-07-05
+
+A CMS SignedData parser joins the pki.schema family; coverage-guided fuzzing now runs in CI.
+
+### Added
+
+- pki.schema.cms.parse — a CMS SignedData parser per RFC 5652 (§3 ContentInfo + §5 SignedData). It turns a DER Buffer or a 'CMS' PEM string into { version, digestAlgorithms, encapContentInfo, certificates, crls, signerInfos }. encapContentInfo.eContent is the raw content (or null when the signature is detached); each SignerInfo carries its raw signature and, when signed attributes are present, the on-wire signedAttrsBytes for external verification. The signer identifier is an issuerAndSerialNumber or a subjectKeyIdentifier, with the version-to-identifier rule (RFC 5652 §5.3) enforced, and a degenerate certificates-only SignedData (empty digest algorithms and signer infos) is accepted. A ContentInfo whose content type is not id-signedData throws cms/unsupported-content-type (a recognized PKCS#7 type) or cms/unknown-content-type; a malformed structure throws a typed CmsError (cms/*) and a leaf-level codec fault surfaces as asn1/*. pki.schema.cms.pemDecode / pemEncode handle the PEM envelope, and pki.schema.parse detect-and-routes a CMS message.
+- pki.asn1.read.octetStringImplicit and the pki.schema.engine.implicitOctetString(tag) leaf — read a context-tagged IMPLICIT OCTET STRING (the shape the CMS SignerIdentifier subjectKeyIdentifier [0] takes), the primitive-leaf sibling of implicitBitString.
+- Coverage-guided fuzzing in CI — a ClusterFuzzLite integration (.clusterfuzzlite/) plus pull-request and nightly-batch workflows run jazzer.js + libFuzzer against the pki.asn1.decode, pki.schema.x509.parse and pki.schema.cms.parse harnesses. A finding fails the run with the reproducer inline and uploads the crash input as an artifact. The integration is detectable by OpenSSF Scorecard's Fuzzing check.
+
+### Fixed
+
+- The OpenSSL interop runner counted a cross-check the oracle could not perform (for example, an OpenSSL predating ML-DSA) as a pass. Such a cross-check is now recorded as a skip and reported separately, so the interop pass count is not inflated by checks that never executed.
+
+## v0.1.9 — 2026-07-05
+
+A PKCS#8 private-key parser joins the pki.schema family.
+
+### Added
+
+- pki.schema.pkcs8.parse — a PKCS#8 PrivateKeyInfo / OneAsymmetricKey parser per RFC 5208 §5 and RFC 5958 §2. It turns a DER Buffer or a 'PRIVATE KEY' PEM string into { version, privateKeyAlgorithm, privateKey, attributes, publicKey }, where privateKey is the raw OCTET STRING content (the inner RSA/EC/curve key, decoded by the caller via privateKeyAlgorithm.oid) and publicKey is present only for a v2 key. The version must be v1 (0) or v2 (1), and a [1] public key is permitted only in a v2 key (both directions enforced). A malformed key throws a typed Pkcs8Error (pkcs8/*); a leaf-level codec fault surfaces as asn1/*. pki.schema.pkcs8.pemDecode / pemEncode handle the PEM envelope.
+- pki.schema.pkcs8.parseEncrypted — recognizes an EncryptedPrivateKeyInfo ('ENCRYPTED PRIVATE KEY') and surfaces its encryptionAlgorithm and raw encryptedData. Decryption (PBES2/PBKDF2 + a passphrase) is a separate concern and is not performed here. This is an explicit call — an EncryptedPrivateKeyInfo shares its SEQUENCE{SEQUENCE, OCTET STRING} shape with a PKCS#1 DigestInfo, so pki.schema.parse does not auto-route it (structure alone cannot classify it without a validated encryption-algorithm discriminator).
+- pki.asn1.read.enumerated's sibling pki.asn1.read.bitStringImplicit and the pki.schema.engine.implicitBitString(tag) leaf — read a context-tagged IMPLICIT BIT STRING (the shape a PKCS#8 OneAsymmetricKey public key [1] takes).
+
+## v0.1.8 — 2026-07-04
 
 A PKCS#10 certification-request parser joins the pki.schema family.
 

package/README.md

@@ -194,9 +194,11 @@ is callable today; nothing below is a stub.
 | `pki.schema.x509` | Parse DER / PEM certificates into structured, validated fields — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.crl` | Parse DER / PEM X.509 CRLs per RFC 5280 §5 — revoked serials with real-`Date` revocation times, named + partly-decoded extensions, fail-closed — `parse`, `pemDecode` |
 | `pki.schema.csr` | Parse DER / PEM PKCS#10 certification requests per RFC 2986 — subject DN, public key, requested attributes, signature, fail-closed — `parse`, `pemDecode`, `pemEncode` |
+| `pki.schema.pkcs8` | Parse DER / PEM PKCS#8 private keys per RFC 5208 / 5958 — algorithm, raw key bytes, attributes, optional public key, fail-closed; encrypted keys recognized (not decrypted) — `parse`, `parseEncrypted`, `pemDecode`, `pemEncode` |
+| `pki.schema.cms` | Parse DER / PEM CMS SignedData per RFC 5652 — encapsulated content, signer infos, raw signed-attribute bytes for external verification, certificates / CRLs kept raw, fail-closed; non-SignedData content types recognized (not decoded) — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.engine` | The declarative ASN.1 structure-schema engine every format parser composes — `walk` plus the schema combinators |
 | `pki.C` / `pki.constants` | Version-stable constants — functional scale helpers (`C.TIME.*`, `C.BYTES.*`), codec `LIMITS`, `version` |
-| `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError`, each carrying a stable `code` in `domain/reason` form |
+| `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError` / `Pkcs8Error` / `CmsError`, each carrying a stable `code` in `domain/reason` form |
 | `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>` |
 
 ### CLI
@@ -212,7 +214,7 @@ pki parse cert.pem                       # structured JSON summary of a certific
 
 Certificate build/sign/verify, certification-path
 validation, CMS (SignedData / EnvelopedData / EncryptedData / AuthenticatedData),
-OCSP, RFC 3161 timestamping, PKCS#8 / SPKI / PBES2 / PKCS#12, and the
+OCSP, RFC 3161 timestamping, PKCS#8 decryption (PBES2) / SPKI / PKCS#12, and the
 post-quantum certificate and CMS surface (ML-DSA / ML-KEM / SLH-DSA and hybrid
 composites) are on the roadmap and ride this same core. See
 [ROADMAP.md](ROADMAP.md) for the full plan and current status of each area, and

package/lib/asn1-der.js

@@ -318,9 +318,11 @@ function readEnumerated(node) {
   return _readIntegerLikeContent(node, "ENUMERATED", "readEnumerated");
 }
 
-function readBitString(node) {
-  _expectUniversal(node, TAGS.BIT_STRING, "readBitString");
-  _expectPrimitive(node, "readBitString");
+// The BIT STRING content decoder (the leading unused-bit octet + body, with the
+// DER zero-pad rule). Shared by the universal reader and the IMPLICIT
+// context-tagged reader — the caller asserts the tag first.
+function _readBitStringContent(node, who) {
+  _expectPrimitive(node, who);
   var c = node.content;
   if (c.length === 0) throw new Asn1Error("asn1/bad-bit-string", "BIT STRING must have >= 1 content octet");
   var unusedBits = c[0];
@@ -335,12 +337,43 @@ function readBitString(node) {
   return { unusedBits: unusedBits, bytes: c.subarray(1) };
 }
 
+function readBitString(node) {
+  _expectUniversal(node, TAGS.BIT_STRING, "readBitString");
+  return _readBitStringContent(node, "readBitString");
+}
+
+// Read a [tag] IMPLICIT BIT STRING — a context-class PRIMITIVE node whose content
+// is a bit-string body (identical content rules to a universal BIT STRING). The
+// IMPLICIT tag replaces the universal one, so there is no inner universal node.
+// Used for the PKCS#8 OneAsymmetricKey publicKey [1] (RFC 5958 §2).
+function readBitStringImplicit(node, tag) {
+  if (node.tagClass !== "context" || node.tagNumber !== tag) {
+    throw new Asn1Error("asn1/unexpected-tag", "readBitStringImplicit: expected context tag [" + tag +
+      "], got " + node.tagClass + "/" + node.tagNumber);
+  }
+  return _readBitStringContent(node, "readBitStringImplicit");
+}
+
 function readOctetString(node) {
   _expectUniversal(node, TAGS.OCTET_STRING, "readOctetString");
   _expectPrimitive(node, "readOctetString");
   return node.content;
 }
 
+// Read a [tag] IMPLICIT OCTET STRING — a context-class PRIMITIVE node whose
+// content is the octet-string body (the IMPLICIT tag replaces the universal one,
+// so there is no inner universal node). Primitive-only, like its universal
+// counterpart, so the BER constructed/streamed form is rejected. Used for the CMS
+// SignerIdentifier subjectKeyIdentifier [0] (RFC 5652 §5.3).
+function readOctetStringImplicit(node, tag) {
+  if (node.tagClass !== "context" || node.tagNumber !== tag) {
+    throw new Asn1Error("asn1/unexpected-tag", "readOctetStringImplicit: expected context tag [" + tag +
+      "], got " + node.tagClass + "/" + node.tagNumber);
+  }
+  _expectPrimitive(node, "readOctetStringImplicit");
+  return node.content;
+}
+
 function readNull(node) {
   _expectUniversal(node, TAGS.NULL, "readNull");
   _expectPrimitive(node, "readNull");
@@ -773,7 +806,9 @@ module.exports = {
     integer:      readInteger,
     enumerated:   readEnumerated,
     bitString:    readBitString,
+    bitStringImplicit: readBitStringImplicit,
     octetString:  readOctetString,
+    octetStringImplicit: readOctetStringImplicit,
     nullValue:    readNull,
     oid:          readOid,
     string:       readString,

package/lib/framework-error.js

@@ -133,6 +133,14 @@ var SchemaError = defineClass("SchemaError", { withCause: true });
 // (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).
+var Pkcs8Error = defineClass("Pkcs8Error", { withCause: true });
+
+// 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 });
+
 module.exports = {
   PkiError:         PkiError,
   defineClass:      defineClass,
@@ -144,4 +152,6 @@ module.exports = {
   CrlError:         CrlError,
   SchemaError:      SchemaError,
   CsrError:         CsrError,
+  Pkcs8Error:       Pkcs8Error,
+  CmsError:         CmsError,
 };

package/lib/oid.js

@@ -70,8 +70,19 @@ var FAMILIES = {
     rsaEncryption: 1, rsassaPss: 10, sha256WithRSAEncryption: 11,
     sha384WithRSAEncryption: 12, sha512WithRSAEncryption: 13 } },
 
-  // PKCS#9 attribute types.
-  pkcs9: { base: [1, 2, 840, 113549, 1, 9], of: { emailAddress: 1, challengePassword: 7, extensionRequest: 14 } },
+  // PKCS#7 / CMS content types (RFC 5652 §4, RFC 2315). id-signedData is the one
+  // this toolkit structurally decodes; the rest are recognized-and-deferred.
+  pkcs7: { base: [1, 2, 840, 113549, 1, 7], of: {
+    data: 1, signedData: 2, envelopedData: 3, signedAndEnvelopedData: 4,
+    digestedData: 5, encryptedData: 6 } },
+
+  // PKCS#9 attribute types — incl. the CMS signed-attribute OIDs (RFC 5652 §11).
+  pkcs9: { base: [1, 2, 840, 113549, 1, 9], of: {
+    emailAddress: 1, contentType: 3, messageDigest: 4, signingTime: 5,
+    challengePassword: 7, extensionRequest: 14 } },
+
+  // S/MIME content types on the PKCS#9 smime arc (RFC 5652, RFC 3161): id-ct.
+  smimeCt: { base: [1, 2, 840, 113549, 1, 9, 16, 1], of: { authData: 2, tSTInfo: 4 } },
 
   // ANSI X9.62 EC public key, named curve, and ECDSA signatures.
   ansiX962: { base: [1, 2, 840, 10045], of: {

package/lib/schema-all.js

@@ -12,7 +12,7 @@
  * @intro
  *   The schema family: a declarative ASN.1 structure-schema engine and the
  *   per-format parsers built on it. Every format (X.509 certificates, CRLs,
- *   PKCS#10 certification requests, and — as they land — CMS / PKCS#8) is a
+ *   PKCS#10 certification requests, PKCS#8 private keys, and CMS SignedData) is a
  *   member that COMPOSES the
  *   shared engine and the shared PKIX sub-schemas (AlgorithmIdentifier, Name,
  *   Extension), so a structural rule — bounds-checked positional reads,
@@ -35,6 +35,8 @@ var pkix = require("./schema-pkix");
 var x509 = require("./schema-x509");
 var crl = require("./schema-crl");
 var csr = require("./schema-csr");
+var pkcs8 = require("./schema-pkcs8");
+var cms = require("./schema-cms");
 var frameworkError = require("./framework-error");
 
 var SchemaError = frameworkError.SchemaError;
@@ -51,6 +53,31 @@ var ENTRY = { pemLabel: null, PemError: PemError, ErrorClass: SchemaError, prefi
 // logic. Order matters: the most specific detector wins, so a new member is
 // inserted ahead of any more-permissive one.
 var FORMATS = [
+  {
+    // CMS ContentInfo (RFC 5652 §3) — the only registered root that leads with an
+    // OBJECT IDENTIFIER child (a SEQUENCE of exactly 2: contentType OID + a
+    // context [0] EXPLICIT content wrapper). Disjoint from the INTEGER-first pkcs8
+    // and the tbs-SEQUENCE-first signed-envelope trio, so it detects unambiguously.
+    // A non-SignedData content type routes here and gets a precise
+    // cms/unsupported-content-type rather than schema/unknown-format.
+    name: "cms",
+    module: cms,
+    detect: cms.matches,
+    parse: function (input) { return cms.parse(input); },
+  },
+  {
+    // PKCS#8 PrivateKeyInfo / OneAsymmetricKey — SEQUENCE whose first child is an
+    // INTEGER (version) and third an OCTET STRING (privateKey); disjoint from the
+    // signed-envelope trio. (EncryptedPrivateKeyInfo is deliberately NOT
+    // auto-routed: its SEQUENCE{SEQUENCE, OCTET STRING} shape is ambiguous — a
+    // PKCS#1 DigestInfo is identical — so structural detection cannot classify it
+    // without a validated encryption-algorithm discriminator, which arrives with
+    // the PBES layer. It is reached explicitly via pki.schema.pkcs8.parseEncrypted.)
+    name: "pkcs8",
+    module: pkcs8,
+    detect: pkcs8.matches,
+    parse: function (input) { return pkcs8.parse(input); },
+  },
   {
     // CertificationRequest ::= SEQUENCE { certificationRequestInfo,
     // signatureAlgorithm, signature } — the same outer 3-element shape,
@@ -93,7 +120,7 @@ var FORMATS = [
  * The names of every registered format, in detection order.
  *
  * @example
- *   pki.schema.all();  // → ["csr", "crl", "x509"]
+ *   pki.schema.all();  // → ["cms", "pkcs8", "csr", "crl", "x509"]
  */
 function all() { return FORMATS.map(function (f) { return f.name; }); }
 
@@ -134,6 +161,8 @@ module.exports = {
   x509: { parse: x509.parse, pemDecode: x509.pemDecode, pemEncode: x509.pemEncode },
   crl:  { parse: crl.parse,  pemDecode: crl.pemDecode },
   csr:  { parse: csr.parse,  pemDecode: csr.pemDecode, pemEncode: csr.pemEncode },
+  pkcs8: { parse: pkcs8.parse, parseEncrypted: pkcs8.parseEncrypted, pemDecode: pkcs8.pemDecode, pemEncode: pkcs8.pemEncode },
+  cms:  { parse: cms.parse, pemDecode: cms.pemDecode, pemEncode: cms.pemEncode },
   all: all,
   parse: parse,
 };

package/lib/schema-cms.js

@@ -0,0 +1,375 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.schema.cms
+ * @nav        Schema
+ * @title      CMS
+ * @order      160
+ * @slug       cms
+ *
+ * @intro
+ *   CMS SignedData handling per RFC 5652 (§3 ContentInfo envelope, §5 SignedData).
+ *   `parse` turns a DER or PEM (`CMS`) message into a structured object: the
+ *   SignedData version, the digest algorithms, the encapsulated content, the
+ *   certificate / CRL sets, and the signer infos. It is an OID-dispatch envelope —
+ *   ContentInfo reads its `contentType` and structurally decodes only
+ *   `id-signedData`; the other PKCS#7 content types (EnvelopedData, EncryptedData,
+ *   …) are recognized and rejected with a precise `cms/unsupported-content-type`
+ *   rather than a generic unknown-format error.
+ *
+ *   CMS is a signed container: the bytes an external verifier must hash are
+ *   surfaced RAW and never re-serialized. `encapContentInfo.eContent` is the raw
+ *   content (or `null` for a detached signature); each SignerInfo's `signature` is
+ *   raw, and `signedAttrsBytes` is the on-wire `[0]` SignedAttributes TLV so a
+ *   verifier can re-tag it to the universal SET the signature is computed over
+ *   (§5.4). Embedded certificates and CRLs are surfaced as raw DER + their outer
+ *   tag, so an obsolete or unknown alternative never fails the parse. DER-only,
+ *   fail-closed.
+ *
+ * @card
+ *   Parse DER / PEM CMS SignedData (RFC 5652) into structured, validated fields —
+ *   encapsulated content, signer infos, raw signed-attribute bytes for external
+ *   verification, certificates/CRLs kept raw, 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 CmsError = frameworkError.CmsError;
+var PemError = frameworkError.PemError;
+
+// The cms error namespace the schema engine walks under.
+var NS = pkix.makeNS("cms", CmsError, oid);
+
+var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
+var ATTRIBUTE = pkix.attribute(NS);
+var NAME = pkix.name(NS);
+
+// CMSVersion ::= INTEGER — the SignedData version is {1,3,4,5} and the SignerInfo
+// version is {1,3} (RFC 5652 §5.1, §5.3). Wider accept maps than any other format.
+var SIGNED_DATA_VERSION = pkix.versionReader(NS, { "1": 1, "3": 3, "4": 4, "5": 5 });
+var SIGNER_VERSION = pkix.versionReader(NS, { "1": 1, "3": 3 });
+
+// id-signedData is the one content type this build structurally decodes; the rest
+// are recognized-and-deferred (a precise diagnostic, not a silent unknown-format).
+// OIDs resolve from the registry (pkcs7 / smimeCt families), never dotted literals.
+var OID_SIGNED_DATA = oid.byName("signedData");
+var OID_DATA = oid.byName("data");
+var DEFERRED = new Set([
+  oid.byName("data"), oid.byName("envelopedData"), oid.byName("signedAndEnvelopedData"),
+  oid.byName("digestedData"), oid.byName("encryptedData"), oid.byName("authData"),
+]);
+// The two mandatory signed-attribute types (RFC 5652 §5.3, §11.1/§11.2).
+var OID_CONTENT_TYPE = oid.byName("contentType");
+var OID_MESSAGE_DIGEST = oid.byName("messageDigest");
+
+// Enforce the SignedAttributes value constraints (RFC 5652 §5.3, §11) — if
+// signedAttrs is present it MUST contain exactly one content-type attribute and
+// exactly one message-digest attribute, each single-valued. The content-type value
+// == eContentType and messageDigest == the actual content hash are §5.6
+// VERIFICATION concerns (surfaced, checked by the verifier), not structural-parse
+// concerns.
+function _checkSignedAttrs(attrs) {
+  var ct = 0, md = 0, seen = Object.create(null);
+  for (var i = 0; i < attrs.length; i++) {
+    var a = attrs[i];
+    // RFC 5652 §5.3 — a signerInfo MUST NOT include multiple instances of the
+    // same signed-attribute type (specific codes for the two mandatory types).
+    if (seen[a.type]) {
+      if (a.type === OID_CONTENT_TYPE) throw NS.E("cms/duplicate-content-type", "signedAttrs must not repeat the content-type attribute");
+      if (a.type === OID_MESSAGE_DIGEST) throw NS.E("cms/duplicate-message-digest", "signedAttrs must not repeat the message-digest attribute");
+      throw NS.E("cms/duplicate-signed-attr", "signedAttrs must not include multiple instances of the same attribute type (" + a.type + ")");
+    }
+    seen[a.type] = true;
+    if (a.type === OID_CONTENT_TYPE) {
+      ct += 1;
+      if (a.values.length !== 1) throw NS.E("cms/bad-content-type-attr", "the content-type signed attribute must be single-valued");
+      // ContentType ::= OBJECT IDENTIFIER (RFC 5652 §11.1) — validate the value's
+      // full syntax (tag AND minimal base-128 OID content), not just the tag, so a
+      // truncated / non-minimal subidentifier is rejected here, not at verify time.
+      try { asn1.read.oid(asn1.decode(a.values[0])); }
+      catch (e) { throw NS.E("cms/bad-content-type-attr", "the content-type signed attribute value must be a valid OBJECT IDENTIFIER", e); }
+    } else if (a.type === OID_MESSAGE_DIGEST) {
+      md += 1;
+      if (a.values.length !== 1) throw NS.E("cms/bad-message-digest-attr", "the message-digest signed attribute must be single-valued");
+      // MessageDigest ::= OCTET STRING (RFC 5652 §11.2) — validate the full syntax.
+      try { asn1.read.octetString(asn1.decode(a.values[0])); }
+      catch (e) { throw NS.E("cms/bad-message-digest-attr", "the message-digest signed attribute value must be an OCTET STRING", e); }
+    }
+  }
+  // Duplicates are rejected in the loop (the seen-set); here only presence.
+  if (ct === 0) throw NS.E("cms/missing-content-type", "signedAttrs must contain a content-type attribute (RFC 5652 §11.1)");
+  if (md === 0) throw NS.E("cms/missing-message-digest", "signedAttrs must contain a message-digest attribute (RFC 5652 §11.2)");
+}
+
+// A CertificateChoices / RevocationInfoChoice element, surfaced RAW (its DER +
+// outer tag) rather than recursively parsed — the obsolete CHOICE alternatives
+// (extendedCertificate, attribute certs, otherRevocationInfo) never fail the
+// parse, and a caller re-parses a `certificate`/`CertificateList` element itself.
+function rawElement(item) {
+  return { bytes: item.node.bytes, tagClass: item.node.tagClass, tagNumber: item.node.tagNumber };
+}
+
+// RFC 5652 §5.1 — the exact SignedData CMSVersion, computed from the raw
+// CertificateChoices / RevocationInfoChoice outer tags (a certificate `other` is
+// [3], a v2AttrCert [2], a v1AttrCert [1]; a RevocationInfoChoice `other` is [1]),
+// the SignerInfo versions, and whether the content type is id-data.
+function _expectedSignedDataVersion(certificates, crls, signerInfos, eContentType) {
+  function ctx(el, n) { return el.tagClass === "context" && el.tagNumber === n; }
+  var otherCert = certificates.some(function (c) { return ctx(c, 3); });
+  var otherCrl = crls.some(function (c) { return ctx(c, 1); });
+  if (otherCert || otherCrl) return 5;
+  if (certificates.some(function (c) { return ctx(c, 2); })) return 4;   // v2AttrCert [2]
+  if (certificates.some(function (c) { return ctx(c, 1); }) ||           // v1AttrCert [1]
+      signerInfos.some(function (si) { return si.version === 3; }) ||
+      eContentType !== OID_DATA) return 3;
+  return 1;
+}
+
+// EncapsulatedContentInfo ::= SEQUENCE { eContentType OID,
+//   eContent [0] EXPLICIT OCTET STRING OPTIONAL } (RFC 5652 §5.2). Absent eContent
+// is a detached signature (surfaced as null); present is the raw content bytes.
+var ENCAP_CONTENT_INFO = schema.seq([
+  schema.field("eContentType", schema.oidLeaf()),
+  schema.optional("eContent", schema.octetString(), { tag: 0, explicit: true, emptyCode: "cms/bad-econtent" }),
+], {
+  assert: "sequence", arity: { min: 1, max: 2 }, code: "cms/bad-encap-content-info", what: "EncapsulatedContentInfo",
+  build: function (m) {
+    return {
+      eContentType: m.fields.eContentType.value,
+      eContent: m.fields.eContent.present ? m.fields.eContent.value : null,
+    };
+  },
+});
+
+// IssuerAndSerialNumber ::= SEQUENCE { issuer Name, serialNumber INTEGER }
+// (RFC 5652 §10.2.4). serialNumberHex preserves the DER sign padding.
+var ISSUER_AND_SERIAL = schema.seq([
+  schema.field("issuer", NAME),
+  schema.field("serialNumber", schema.integerLeaf()),
+], {
+  assert: "sequence", arity: { exact: 2 }, code: "cms/bad-issuer-and-serial", what: "IssuerAndSerialNumber",
+  build: function (m) {
+    return {
+      issuer: m.fields.issuer.value.result,
+      serialNumber: m.fields.serialNumber.value,
+      serialNumberHex: m.fields.serialNumber.node.content.toString("hex"),
+    };
+  },
+});
+
+// SignerIdentifier ::= CHOICE { issuerAndSerialNumber IssuerAndSerialNumber,
+//   subjectKeyIdentifier [0] IMPLICIT OCTET STRING } (RFC 5652 §5.3) — the arm is
+// disambiguated by tag (universal SEQUENCE vs context [0]).
+var SIGNER_IDENTIFIER = schema.choice([
+  { when: { tagClass: "universal", tagNumber: asn1.TAGS.SEQUENCE }, schema: ISSUER_AND_SERIAL },
+  { when: { tagClass: "context", tagNumber: 0 }, schema: schema.implicitOctetString(0) },
+], { code: "cms/bad-signer-identifier", what: "SignerIdentifier" });
+
+// SignerInfo ::= SEQUENCE { version, sid SignerIdentifier, digestAlgorithm,
+//   signedAttrs [0] IMPLICIT OPTIONAL, signatureAlgorithm, signature OCTET STRING,
+//   unsignedAttrs [1] IMPLICIT OPTIONAL } (RFC 5652 §5.3). signedAttrs/unsignedAttrs
+// are positional optionals (a required signatureAlgorithm sits between them, so
+// they cannot be a trailing block).
+var SIGNER_INFO = schema.seq([
+  schema.field("version", SIGNER_VERSION),
+  schema.field("sid", SIGNER_IDENTIFIER),
+  schema.field("digestAlgorithm", ALGORITHM_IDENTIFIER),
+  schema.optional("signedAttrs", schema.implicitSetOf(0, ATTRIBUTE, { min: 1, code: "cms/bad-signed-attrs", what: "signedAttrs" }), { tag: 0 }),
+  schema.field("signatureAlgorithm", ALGORITHM_IDENTIFIER),
+  schema.field("signature", schema.octetString()),
+  schema.optional("unsignedAttrs", schema.implicitSetOf(1, ATTRIBUTE, { min: 1, code: "cms/bad-unsigned-attrs", what: "unsignedAttrs" }), { tag: 1 }),
+], {
+  assert: "sequence", code: "cms/bad-signer-info", what: "SignerInfo",
+  build: function (m) {
+    var version = m.fields.version.value;
+    var sidNode = m.fields.sid.node;
+    var isSkid = sidNode.tagClass === "context" && sidNode.tagNumber === 0;
+    var sid;
+    if (isSkid) {
+      // RFC 5652 §5.3 — a subjectKeyIdentifier sid forces SignerInfo version 3.
+      if (version !== 3) throw NS.E("cms/bad-signer-version", "a subjectKeyIdentifier signer identifier requires SignerInfo version 3");
+      sid = { subjectKeyIdentifier: m.fields.sid.value };
+    } else {
+      // RFC 5652 §5.3 — an issuerAndSerialNumber sid forces SignerInfo version 1.
+      if (version !== 1) throw NS.E("cms/bad-signer-version", "an issuerAndSerialNumber signer identifier requires SignerInfo version 1");
+      sid = m.fields.sid.value.result;
+    }
+    var signedAttrs = null, signedAttrsBytes = null;
+    if (m.fields.signedAttrs.present) {
+      signedAttrs = m.fields.signedAttrs.value.items.map(function (it) { return it.value.result; });
+      _checkSignedAttrs(signedAttrs);
+      // The raw on-wire signedAttrs bytes (leading 0xA0) so a verifier can re-tag to
+      // a universal SET and reproduce the signed hash (RFC 5652 §5.4).
+      signedAttrsBytes = m.fields.signedAttrs.node.bytes;
+    }
+    return {
+      version: version,
+      sid: sid,
+      digestAlgorithm: m.fields.digestAlgorithm.value.result,
+      signedAttrs: signedAttrs,
+      signedAttrsBytes: signedAttrsBytes,
+      signatureAlgorithm: m.fields.signatureAlgorithm.value.result,
+      signature: m.fields.signature.value,
+      unsignedAttrs: m.fields.unsignedAttrs.present ? m.fields.unsignedAttrs.value.items.map(function (it) { return it.value.result; }) : null,
+    };
+  },
+});
+
+// SignedData ::= SEQUENCE { version CMSVersion, digestAlgorithms SET OF,
+//   encapContentInfo, certificates [0] IMPLICIT OPTIONAL, crls [1] IMPLICIT
+//   OPTIONAL, signerInfos SET OF } (RFC 5652 §5.1). digestAlgorithms and
+//   signerInfos are min:0 — a degenerate certs-only SignedData carries neither.
+var SIGNED_DATA = schema.seq([
+  schema.field("version", SIGNED_DATA_VERSION),
+  schema.field("digestAlgorithms", schema.setOf(ALGORITHM_IDENTIFIER, { min: 0, code: "cms/bad-digest-algorithms", what: "digestAlgorithms" })),
+  schema.field("encapContentInfo", ENCAP_CONTENT_INFO),
+  schema.optional("certificates", schema.implicitSetOf(0, schema.any(), { min: 1, code: "cms/bad-certificates", what: "certificates" }), { tag: 0 }),
+  schema.optional("crls", schema.implicitSetOf(1, schema.any(), { min: 1, code: "cms/bad-crls", what: "crls" }), { tag: 1 }),
+  schema.field("signerInfos", schema.setOf(SIGNER_INFO, { min: 0, code: "cms/bad-signer-infos", what: "signerInfos" })),
+], {
+  assert: "sequence", code: "cms/bad-signed-data", what: "SignedData",
+  build: function (m) {
+    var version = m.fields.version.value;
+    var encapContentInfo = m.fields.encapContentInfo.value.result;
+    var certificates = m.fields.certificates.present ? m.fields.certificates.value.items.map(rawElement) : [];
+    var crls = m.fields.crls.present ? m.fields.crls.value.items.map(rawElement) : [];
+    var signerInfos = m.fields.signerInfos.value.items.map(function (it) { return it.value.result; });
+
+    // RFC 5652 §5.3 — signedAttrs MAY be omitted only when the content type is
+    // id-data; any other eContentType requires each SignerInfo to carry signedAttrs
+    // (so the content-type + message-digest attributes bind the signature).
+    if (encapContentInfo.eContentType !== OID_DATA) {
+      for (var s = 0; s < signerInfos.length; s++) {
+        if (signerInfos[s].signedAttrs === null) throw NS.E("cms/missing-signed-attrs", "a SignerInfo must carry signedAttrs when the content type is not id-data (RFC 5652 §5.3)");
+      }
+    }
+
+    // RFC 5652 §5.3 — when signedAttrs are present, the content-type attribute's
+    // value MUST equal the eContentType (a cross-field consistency both parsed
+    // here; a mismatch is an internally-inconsistent SignedData).
+    for (var si = 0; si < signerInfos.length; si++) {
+      var sa = signerInfos[si].signedAttrs;
+      if (!sa) continue;
+      for (var ai = 0; ai < sa.length; ai++) {
+        if (sa[ai].type !== OID_CONTENT_TYPE) continue;
+        var ctv = asn1.read.oid(asn1.decode(sa[ai].values[0]));
+        if (ctv !== encapContentInfo.eContentType) throw NS.E("cms/content-type-mismatch", "the content-type signed attribute (" + ctv + ") must equal the eContentType (" + encapContentInfo.eContentType + ") (RFC 5652 §5.3)");
+      }
+    }
+
+    // RFC 5652 §5.1 — the SignedData CMSVersion is determined by its contents.
+    var expected = _expectedSignedDataVersion(certificates, crls, signerInfos, encapContentInfo.eContentType);
+    if (version !== expected) throw NS.E("cms/bad-version", "SignedData version " + version + " does not match its contents (RFC 5652 §5.1 requires v" + expected + ")");
+
+    return {
+      version: version,
+      digestAlgorithms: m.fields.digestAlgorithms.value.items.map(function (it) { return it.value.result; }),
+      encapContentInfo: encapContentInfo,
+      certificates: certificates,
+      crls: crls,
+      signerInfos: signerInfos,
+    };
+  },
+});
+
+// ContentInfo ::= SEQUENCE { contentType OID, content [0] EXPLICIT ANY DEFINED BY
+//   contentType } (RFC 5652 §3). The content is captured raw (explicit(0, any()))
+//   and re-dispatched by contentType inside the build: id-signedData walks
+//   SIGNED_DATA, the other PKCS#7 types are recognized-and-deferred, unknown OIDs
+//   are rejected.
+var CONTENT_INFO = schema.seq([
+  schema.field("contentType", schema.oidLeaf()),
+  schema.field("content", schema.explicit(0, schema.any(), { code: "cms/not-a-content-info" })),
+], {
+  assert: "sequence", arity: { exact: 2 }, code: "cms/not-a-content-info", what: "ContentInfo",
+  build: function (m, ctx) {
+    var ct = m.fields.contentType.value;
+    if (ct === OID_SIGNED_DATA) return schema.walk(SIGNED_DATA, m.fields.content.value, ctx).result;
+    if (DEFERRED.has(ct)) {
+      throw NS.E("cms/unsupported-content-type", (ctx.oid.name(ct) || ct) + " is recognized but not parsed by this build");
+    }
+    throw NS.E("cms/unknown-content-type", "unrecognized ContentInfo content type " + ct);
+  },
+});
+
+/**
+ * @primitive  pki.schema.cms.parse
+ * @signature  pki.schema.cms.parse(input) -> signedData
+ * @since      0.1.10
+ * @status     experimental
+ * @spec       RFC 5652
+ * @related    pki.schema.parse, pki.schema.x509.parse
+ *
+ * Parse a DER `Buffer` or a PEM (`CMS`) string into a structured CMS SignedData:
+ * `{ version, digestAlgorithms, encapContentInfo, certificates, crls,
+ * signerInfos }`. `encapContentInfo.eContent` is the raw content (or `null` when
+ * detached); each SignerInfo carries its raw `signature` and, when present, the
+ * on-wire `signedAttrsBytes` for external verification. A ContentInfo whose type
+ * is not `id-signedData` throws `cms/unsupported-content-type` (a recognized
+ * PKCS#7 type) or `cms/unknown-content-type`; a malformed structure throws a typed
+ * `CmsError` (`cms/*`) and a leaf-level codec fault surfaces as `asn1/*`.
+ *
+ * @example
+ *   var cms = pki.schema.cms.parse(der);
+ *   cms.signerInfos[0].sid.serialNumberHex;   // -> "0a1b..."
+ *   cms.encapContentInfo.eContent;            // -> Buffer | null (detached)
+ */
+var parse = pkix.makeParser({ pemLabel: "CMS", PemError: PemError, ErrorClass: CmsError, prefix: "cms", what: "CMS ContentInfo", topSchema: CONTENT_INFO, ns: NS });
+
+/**
+ * @primitive  pki.schema.cms.pemDecode
+ * @signature  pki.schema.cms.pemDecode(text, label?) -> Buffer
+ * @since      0.1.10
+ * @status     experimental
+ * @spec       RFC 7468, RFC 5652
+ * @related    pki.schema.cms.parse
+ *
+ * Extract the DER bytes from a PEM CMS block (default label `CMS`). Throws
+ * `PemError` on a missing / mismatched envelope or a non-base64 body.
+ *
+ * @example
+ *   var der = pki.schema.cms.pemDecode(pemText);
+ */
+function pemDecode(text, label) { return pkix.pemDecode(text, label || "CMS", PemError); }
+
+/**
+ * @primitive  pki.schema.cms.pemEncode
+ * @signature  pki.schema.cms.pemEncode(der, label?) -> string
+ * @since      0.1.10
+ * @status     experimental
+ * @spec       RFC 7468
+ * @related    pki.schema.cms.pemDecode
+ *
+ * Wrap DER bytes in a PEM CMS envelope (default label `CMS`).
+ *
+ * @example
+ *   var pem = pki.schema.cms.pemEncode(der);
+ */
+function pemEncode(der, label) { return pkix.pemEncode(der, label || "CMS", PemError); }
+
+// A CMS ContentInfo root is the only registered structure whose root leads with an
+// OBJECT IDENTIFIER child: a SEQUENCE of exactly 2 whose first child is an OID and
+// second a context [0] constructed wrapper. x509/crl/csr lead with a tbs SEQUENCE
+// and pkcs8 with an INTEGER, so the detectors are mutually exclusive regardless of
+// registry order.
+function matches(root) {
+  var TAGS = asn1.TAGS;
+  if (!root || root.tagClass !== "universal" || root.tagNumber !== TAGS.SEQUENCE) return false;
+  var k = root.children;
+  if (!k || k.length !== 2) return false;
+  if (!(k[0].tagClass === "universal" && k[0].tagNumber === TAGS.OBJECT_IDENTIFIER)) return false;
+  if (!(k[1].tagClass === "context" && k[1].tagNumber === 0 && k[1].children)) return false;
+  return true;
+}
+
+module.exports = {
+  parse: parse,
+  pemDecode: pemDecode,
+  pemEncode: pemEncode,
+  matches: matches,
+};

package/lib/schema-crl.js

@@ -46,7 +46,7 @@ var OID_INVALIDITY_DATE = oid.byName("invalidityDate");
 
 // The crl error namespace the schema engine walks under. Shared PKIX sub-schemas
 // are instantiated here under crl/* so a structural fault reports a crl code.
-var NS = { prefix: "crl", E: function (code, message, cause) { return new CrlError(code, message, cause); }, oid: oid };
+var NS = pkix.makeNS("crl", CrlError, oid);
 
 var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
 var NAME = pkix.name(NS);
@@ -56,12 +56,7 @@ var TIME = schema.time(NS);
 // CRL Version ::= INTEGER { v1(0), v2(1) } — a BARE INTEGER (not [0] EXPLICIT).
 // A CRL is at most v2; reject an explicit v1 (DER forbids the default) and any
 // value >= 2. Do NOT reuse the certificate readVersion (it maps 2 -> v3).
-var CRL_VERSION = schema.decode(function (n) {
-  var v = asn1.read.integer(n);
-  if (v === 1n) return 2;
-  if (v === 0n) throw NS.E("crl/bad-version", "DER forbids explicitly encoding the default version v1");
-  throw NS.E("crl/bad-version", "unsupported CRL version " + v.toString() + " (a CRL is at most v2)");
-});
+var CRL_VERSION = pkix.versionReader(NS, { "1": 2 });
 
 // The three cheap, high-value CRL extension values are decoded from their raw
 // extnValue octets (RFC 5280 §5.2/§5.3); GeneralNames-based extensions

package/lib/schema-csr.js

@@ -40,7 +40,7 @@ var PemError = frameworkError.PemError;
 
 // The csr error namespace the schema engine walks under. Shared PKIX sub-schemas
 // are instantiated here under csr/* so a structural fault reports a csr code.
-var NS = { prefix: "csr", E: function (code, message, cause) { return new CsrError(code, message, cause); }, oid: oid };
+var NS = pkix.makeNS("csr", CsrError, oid);
 
 var NAME = pkix.name(NS);
 var SPKI = pkix.spki(NS);
@@ -50,30 +50,12 @@ var SPKI = pkix.spki(NS);
 // readers, which reject 0 as the DER-forbidden default. Surface v1 as 1. A
 // cert-shaped [0] EXPLICIT wrapper at this position makes asn1.read.integer throw
 // asn1/* (fail-closed).
-var CSR_VERSION = schema.decode(function (n) {
-  var v = asn1.read.integer(n);
-  if (v === 0n) return 1;
-  throw NS.E("csr/bad-version", "unsupported CSR version " + v.toString() + " (PKCS#10 requires v1)");
-});
+var CSR_VERSION = pkix.versionReader(NS, { "0": 1 });
 
-// Attribute ::= SEQUENCE { type OBJECT IDENTIFIER, values SET OF AttributeValue }.
-// AttributeValue is ANY, kept as raw DER (node.bytes) — an unrecognized attribute
-// type never fails the parse. values is SET SIZE (1..MAX): an empty SET is
-// rejected. There is NO SET-OF uniqueness on attributes (unlike cert extensions).
-var ATTRIBUTE = schema.seq([
-  schema.field("type", schema.oidLeaf()),
-  schema.field("values", schema.setOf(schema.any(), { assert: "set", min: 1, code: "csr/bad-attribute-values", what: "attribute values" })),
-], {
-  assert: "sequence", arity: { exact: 2 }, code: "csr/bad-attribute", what: "Attribute",
-  build: function (m, ctx) {
-    var t = m.fields.type.value;
-    return {
-      type: t,
-      name: ctx.oid.name(t) || null,
-      values: m.fields.values.value.items.map(function (it) { return it.node.bytes; }),
-    };
-  },
-});
+// Attribute ::= SEQUENCE { type OID, values SET OF ANY } — the shared pkix factory
+// under the csr NS (values raw DER, SET SIZE(1..MAX), no uniqueness). The same
+// factory serves the PKCS#8 private-key attributes.
+var ATTRIBUTE = pkix.attribute(NS);
 
 // CertificationRequestInfo ::= SEQUENCE { version, subject Name,
 //   subjectPKInfo SubjectPublicKeyInfo, attributes [0] IMPLICIT SET OF Attribute }.

package/lib/schema-engine.js

@@ -97,6 +97,13 @@ function integerLeaf()    { return { kind: "leaf", read: asn1.read.integer }; }
 function boolean()        { return { kind: "leaf", read: asn1.read.boolean }; }
 function octetString()    { return { kind: "leaf", read: asn1.read.octetString }; }
 function bitString()      { return { kind: "leaf", read: function (n) { var b = asn1.read.bitString(n); return { unusedBits: b.unusedBits, bytes: b.bytes }; } }; }
+// A [tag] IMPLICIT BIT STRING leaf (context-class primitive) — the primitive-leaf
+// counterpart to implicitSetOf, for e.g. the PKCS#8 publicKey [1] (RFC 5958 §2).
+function implicitBitString(tag) { return { kind: "leaf", read: function (n) { var b = asn1.read.bitStringImplicit(n, tag); return { unusedBits: b.unusedBits, bytes: b.bytes }; } }; }
+// A [tag] IMPLICIT OCTET STRING leaf (context-class primitive) — the sibling of
+// implicitBitString, for e.g. the CMS SignerIdentifier subjectKeyIdentifier [0]
+// (RFC 5652 §5.3). Yields the raw content bytes.
+function implicitOctetString(tag) { return { kind: "leaf", read: function (n) { return asn1.read.octetStringImplicit(n, tag); } }; }
 function any()            { return { kind: "any" }; }
 function decode(fn)       { return { kind: "decode", fn: fn }; }
 
@@ -368,7 +375,8 @@ module.exports = {
   seqOf: seqOf, setOf: setOf, setOfUnique: setOfUnique, implicitSetOf: implicitSetOf, choice: choice,
   // leaves
   oidLeaf: oidLeaf, integerLeaf: integerLeaf, boolean: boolean, octetString: octetString,
-  bitString: bitString, any: any, decode: decode, time: time,
+  bitString: bitString, implicitBitString: implicitBitString, implicitOctetString: implicitOctetString,
+  any: any, decode: decode, time: time,
   // engine
   walk: walk,
 };

package/lib/schema-pkcs8.js

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.schema.pkcs8
+ * @nav        Schema
+ * @title      PKCS#8
+ * @order      140
+ * @slug       pkcs8
+ *
+ * @intro
+ *   PKCS#8 private-key handling per RFC 5208 §5 (PrivateKeyInfo) and RFC 5958 §2
+ *   (OneAsymmetricKey). `parse` turns a DER or PEM (`PRIVATE KEY`) key into a
+ *   structured object: version, the private-key algorithm identifier, the raw
+ *   private-key bytes, the optional attributes, and — for a v2 OneAsymmetricKey —
+ *   the optional public key. It composes the same schema engine and shared PKIX
+ *   sub-schemas (AlgorithmIdentifier, Attribute) the other parsers use.
+ *
+ *   A PKCS#8 key is a container, not a signed structure: it has no signature, no
+ *   distinguished name, and no to-be-signed region. The private-key OCTET STRING
+ *   content is kept raw — the algorithm-specific inner key (an RSAPrivateKey, an
+ *   ECPrivateKey, a CurvePrivateKey) is decoded by the caller using the surfaced
+ *   algorithm OID, so an unknown or future key type never fails the parse. An
+ *   `ENCRYPTED PRIVATE KEY` (EncryptedPrivateKeyInfo, RFC 5958 §3) is recognized
+ *   and surfaced with its encryption algorithm and raw ciphertext; decrypting it
+ *   needs a passphrase and is out of scope for structural parsing.
+ *
+ * @card
+ *   Parse DER / PEM PKCS#8 private keys (RFC 5208 / 5958) into structured,
+ *   validated fields — algorithm, raw key bytes, attributes, optional public key,
+ *   fail-closed. Encrypted keys are recognized, not decrypted.
+ */
+
+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 Pkcs8Error = frameworkError.Pkcs8Error;
+var PemError = frameworkError.PemError;
+
+// The pkcs8 error namespace the schema engine walks under.
+var NS = pkix.makeNS("pkcs8", Pkcs8Error, oid);
+
+var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
+var ATTRIBUTE = pkix.attribute(NS);
+
+// version ::= INTEGER { v1(0), v2(1) } — 0 and 1 are both LEGAL (the divergence
+// from every other reader; cert/CRL reject 0, CSR accepts only 0). Surface as the
+// RFC's vN number.
+var PKCS8_VERSION = pkix.versionReader(NS, { "0": 1, "1": 2 });
+
+// PrivateKeyInfo ::= SEQUENCE { version, privateKeyAlgorithm AlgorithmIdentifier,
+//   privateKey OCTET STRING, attributes [0] IMPLICIT SET OF Attribute OPTIONAL,
+//   publicKey [1] IMPLICIT BIT STRING OPTIONAL (v2 only) }. The two trailing
+// context fields are modeled with `trailing` so they must appear in ascending tag
+// order and an unknown trailing context tag is rejected (not bled into a field).
+var PRIVATE_KEY_INFO = schema.seq([
+  schema.field("version", PKCS8_VERSION),
+  schema.field("privateKeyAlgorithm", ALGORITHM_IDENTIFIER),
+  schema.field("privateKey", schema.octetString()),
+  schema.trailing([
+    { tag: 0, name: "attributes", schema: schema.implicitSetOf(0, ATTRIBUTE, { min: 0, code: "pkcs8/bad-attributes", what: "attributes" }) },
+    { tag: 1, name: "publicKey", schema: schema.implicitBitString(1) },
+  ], { minTag: 0, maxTag: 1, unexpectedCode: "pkcs8/not-a-private-key-info", orderCode: "pkcs8/bad-order" }),
+], {
+  assert: "sequence", arity: { min: 3 }, code: "pkcs8/not-a-private-key-info", what: "PrivateKeyInfo",
+  build: function (m) {
+    var version = m.fields.version.value;              // 1 (v1) | 2 (v2)
+    var hasPublicKey = m.fields.publicKey.present;
+    // RFC 5958 §2 — publicKey present <=> version is v2. Enforce both directions.
+    if (hasPublicKey && version !== 2) throw NS.E("pkcs8/bad-version", "a [1] publicKey is permitted only in a v2 OneAsymmetricKey");
+    if (!hasPublicKey && version === 2) throw NS.E("pkcs8/bad-version", "a v2 OneAsymmetricKey must carry a [1] publicKey");
+    return {
+      version: version,
+      privateKeyAlgorithm: m.fields.privateKeyAlgorithm.value.result,
+      privateKey: m.fields.privateKey.value,           // raw OCTET STRING content (the inner key DER)
+      attributes: m.fields.attributes.present ? m.fields.attributes.value.items.map(function (it) { return it.value.result; }) : [],
+      publicKey: hasPublicKey ? m.fields.publicKey.value : null,
+    };
+  },
+});
+
+// EncryptedPrivateKeyInfo ::= SEQUENCE { encryptionAlgorithm AlgorithmIdentifier,
+//   encryptedData OCTET STRING } (RFC 5958 §3). Recognized and surfaced; the raw
+// ciphertext is kept for a later decryption layer (PBES2/PBKDF2 + a passphrase).
+var ENCRYPTED_PRIVATE_KEY_INFO = schema.seq([
+  schema.field("encryptionAlgorithm", ALGORITHM_IDENTIFIER),
+  schema.field("encryptedData", schema.octetString()),
+], {
+  assert: "sequence", arity: { exact: 2 }, code: "pkcs8/not-an-encrypted-private-key-info", what: "EncryptedPrivateKeyInfo",
+  build: function (m) {
+    return {
+      encryptionAlgorithm: m.fields.encryptionAlgorithm.value.result,
+      encryptedData: m.fields.encryptedData.value,     // raw ciphertext
+    };
+  },
+});
+
+/**
+ * @primitive  pki.schema.pkcs8.parse
+ * @signature  pki.schema.pkcs8.parse(input) -> privateKey
+ * @since      0.1.9
+ * @status     experimental
+ * @spec       RFC 5208, RFC 5958
+ * @related    pki.schema.parse, pki.schema.x509.parse
+ *
+ * Parse a DER `Buffer` or a PEM (`PRIVATE KEY`) string into a structured PKCS#8
+ * key: `{ version, privateKeyAlgorithm, privateKey, attributes, publicKey }`. The
+ * `privateKey` is the raw OCTET STRING content (the algorithm-specific inner key,
+ * decoded by the caller using `privateKeyAlgorithm.oid`); `publicKey` is `null`
+ * for a v1 key. A malformed PrivateKeyInfo throws a typed `Pkcs8Error` (`pkcs8/*`)
+ * and a leaf-level codec fault surfaces as `asn1/*`.
+ *
+ * @example
+ *   var key = pki.schema.pkcs8.parse(der);
+ *   key.privateKeyAlgorithm.oid;   // -> "1.3.101.112" (Ed25519)
+ *   key.privateKey;                // -> Buffer (the inner key encoding)
+ */
+var parse = pkix.makeParser({ pemLabel: "PRIVATE KEY", PemError: PemError, ErrorClass: Pkcs8Error, prefix: "pkcs8", what: "private key", topSchema: PRIVATE_KEY_INFO, ns: NS });
+
+/**
+ * @primitive  pki.schema.pkcs8.parseEncrypted
+ * @signature  pki.schema.pkcs8.parseEncrypted(input) -> encrypted
+ * @since      0.1.9
+ * @status     experimental
+ * @spec       RFC 5958, RFC 5208
+ * @related    pki.schema.pkcs8.parse
+ *
+ * Parse a DER `Buffer` or a PEM (`ENCRYPTED PRIVATE KEY`) string into an
+ * EncryptedPrivateKeyInfo: `{ encryptionAlgorithm, encryptedData }`. The
+ * ciphertext is surfaced raw; decrypting it (PBES2/PBKDF2 + a passphrase) is a
+ * separate concern from structural validation.
+ *
+ * @example
+ *   var enc = pki.schema.pkcs8.parseEncrypted(der);
+ *   enc.encryptionAlgorithm.oid;   // -> "1.2.840.113549.1.5.13" (PBES2)
+ */
+var parseEncrypted = pkix.makeParser({ pemLabel: "ENCRYPTED PRIVATE KEY", PemError: PemError, ErrorClass: Pkcs8Error, prefix: "pkcs8", what: "encrypted private key", topSchema: ENCRYPTED_PRIVATE_KEY_INFO, ns: NS });
+
+/**
+ * @primitive  pki.schema.pkcs8.pemDecode
+ * @signature  pki.schema.pkcs8.pemDecode(text, label?) -> Buffer
+ * @since      0.1.9
+ * @status     experimental
+ * @spec       RFC 7468, RFC 5958
+ * @related    pki.schema.pkcs8.parse
+ *
+ * Extract the DER bytes from a PEM private-key block (default label `PRIVATE
+ * KEY`). Throws `PemError` on a missing / mismatched envelope or a non-base64
+ * body.
+ *
+ * @example
+ *   var der = pki.schema.pkcs8.pemDecode(pemText);
+ */
+function pemDecode(text, label) { return pkix.pemDecode(text, label || "PRIVATE KEY", PemError); }
+
+/**
+ * @primitive  pki.schema.pkcs8.pemEncode
+ * @signature  pki.schema.pkcs8.pemEncode(der, label?) -> string
+ * @since      0.1.9
+ * @status     experimental
+ * @spec       RFC 7468
+ * @related    pki.schema.pkcs8.pemDecode
+ *
+ * Wrap DER bytes in a PEM private-key envelope (default label `PRIVATE KEY`).
+ *
+ * @example
+ *   var pem = pki.schema.pkcs8.pemEncode(der);
+ */
+function pemEncode(der, label) { return pkix.pemEncode(der, label || "PRIVATE KEY", PemError); }
+
+// A PKCS#8 PrivateKeyInfo root is a SEQUENCE whose first child is a universal
+// INTEGER (version) and third child a universal OCTET STRING (privateKey) — a
+// shape the signed-envelope trio (whose children[0] is a SEQUENCE and children[2]
+// a BIT STRING) can never present, so the detectors are mutually exclusive
+// regardless of registry order. Trailing context fields are [0]/[1] in ascending
+// order.
+function matches(root) {
+  var TAGS = asn1.TAGS;
+  if (!root || root.tagClass !== "universal" || root.tagNumber !== TAGS.SEQUENCE) return false;
+  var k = root.children;
+  if (!k || k.length < 3 || k.length > 5) return false;
+  if (!(k[0].tagClass === "universal" && k[0].tagNumber === TAGS.INTEGER)) return false;
+  if (!(k[1].tagClass === "universal" && k[1].tagNumber === TAGS.SEQUENCE)) return false;
+  if (!(k[2].tagClass === "universal" && k[2].tagNumber === TAGS.OCTET_STRING)) return false;
+  var last = -1;
+  for (var i = 3; i < k.length; i++) {
+    if (k[i].tagClass !== "context" || k[i].tagNumber <= last || k[i].tagNumber > 1) return false;
+    last = k[i].tagNumber;
+  }
+  return true;
+}
+
+// NOTE: there is intentionally no `matchesEncrypted` detector. An
+// EncryptedPrivateKeyInfo is a SEQUENCE { SEQUENCE, OCTET STRING } — a shape it
+// shares with a PKCS#1 DigestInfo and other AlgorithmIdentifier-plus-octets
+// structures — so it cannot be classified from structure alone. The orchestrator
+// does not auto-route it; an operator who knows a key is encrypted (e.g. from an
+// 'ENCRYPTED PRIVATE KEY' PEM label) calls parseEncrypted directly. A structural
+// auto-route can return once a validated encryption-algorithm discriminator (the
+// PBES layer) exists.
+
+module.exports = {
+  parse: parse,
+  parseEncrypted: parseEncrypted,
+  pemDecode: pemDecode,
+  pemEncode: pemEncode,
+  matches: matches,
+};

package/lib/schema-pkix.js

@@ -105,6 +105,30 @@ var DN_SHORT = {
 };
 
 // AlgorithmIdentifier ::= SEQUENCE { algorithm OBJECT IDENTIFIER, parameters ANY OPTIONAL }
+// The error/OID namespace every format module walks its schema under:
+// { prefix, E:(code,message,cause)=>new ErrorClass(...), oid }. Factored so a
+// format declares it in one line instead of repeating the error-constructor
+// closure (a caller that never passes a cause is unaffected — withCause ignores
+// an undefined third arg).
+function makeNS(prefix, ErrorClass, oidModule) {
+  return { prefix: prefix, E: function (code, message, cause) { return new ErrorClass(code, message, cause); }, oid: oidModule };
+}
+
+// A bounded universal-INTEGER version reader. `accept` maps each legal wire value
+// (as a decimal string) to its surfaced version number; any other value is a
+// <prefix>/bad-version fault. The one genuine per-format divergence — the cert
+// rejects 0 and maps 1->2/2->3, a CRL accepts only 1->2, a CSR only 0->1, a PKCS#8
+// 0->1/1->2 — is expressed purely as the accept map (RFC 5280 §4.1.2.1 / §5.1.2.1,
+// RFC 2986 §4.1, RFC 5958 §2). read.integer is strict, so an ENUMERATED-tagged
+// version is rejected at the leaf (asn1/*).
+function versionReader(ns, accept) {
+  return schema.decode(function (n) {
+    var key = asn1.read.integer(n).toString();
+    if (Object.prototype.hasOwnProperty.call(accept, key)) return accept[key];
+    throw ns.E(ns.prefix + "/bad-version", "unsupported version " + key);
+  });
+}
+
 function algorithmIdentifier(ns) {
   return schema.seq([
     schema.field("algorithm", schema.oidLeaf()),
@@ -242,6 +266,28 @@ function spki(ns) {
   });
 }
 
+// Attribute ::= SEQUENCE { type OBJECT IDENTIFIER, values SET OF AttributeValue }.
+// AttributeValue is ANY, kept as raw DER (node.bytes) — an unrecognized attribute
+// type never fails the parse. values is SET SIZE (1..MAX): an empty SET is
+// rejected; there is NO SET-OF uniqueness. Shared by the CSR (requested
+// attributes, RFC 2986 §4.1) and PKCS#8 (private-key attributes, RFC 5958 §2).
+function attribute(ns) {
+  return schema.seq([
+    schema.field("type", schema.oidLeaf()),
+    schema.field("values", schema.setOf(schema.any(), { assert: "set", min: 1, code: ns.prefix + "/bad-attribute-values", what: "attribute values" })),
+  ], {
+    assert: "sequence", arity: { exact: 2 }, code: ns.prefix + "/bad-attribute", what: "Attribute",
+    build: function (m, ctx) {
+      var t = m.fields.type.value;
+      return {
+        type: t,
+        name: ctx.oid.name(t) || null,
+        values: m.fields.values.value.items.map(function (it) { return it.node.bytes; }),
+      };
+    },
+  });
+}
+
 // Certificate, CertificateList, and CertificationRequest share one outer shape:
 // SEQUENCE { toBeSigned SEQUENCE, signatureAlgorithm, signatureValue }. This
 // returns the first element (the to-be-signed info) when `root` is that
@@ -304,6 +350,8 @@ module.exports = {
   coerceToDer: coerceToDer,
   decodeRoot: decodeRoot,
   runParse: runParse,
+  makeNS: makeNS,
+  versionReader: versionReader,
   DN_SHORT: DN_SHORT,
   algorithmIdentifier: algorithmIdentifier,
   spki: spki,
@@ -314,6 +362,7 @@ module.exports = {
   attributeTypeAndValue: attributeTypeAndValue,
   relativeDistinguishedName: relativeDistinguishedName,
   name: name,
+  attribute: attribute,
   extension: extension,
   extensions: extensions,
 };

package/lib/schema-x509.js

@@ -80,7 +80,7 @@ function pemEncode(der, label) { return pkix.pemEncode(der, label, PemError); }
 // sub-schemas (AlgorithmIdentifier, Name, Extension) live in lib/pkix-schema.js
 // as ns-parameterized factories so crl.js / cms.js reuse them while emitting
 // their own crl/*, cms/* codes; here they are instantiated under this NS.
-var NS = { prefix: "x509", E: function (code, message) { return new CertificateError(code, message); }, oid: oid };
+var NS = pkix.makeNS("x509", CertificateError, oid);
 
 var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
 var NAME = pkix.name(NS);
@@ -103,15 +103,9 @@ var EXTENSIONS = pkix.extensions(NS);
 // Version ::= INTEGER { v1(0), v2(1), v3(2) }, [0] EXPLICIT DEFAULT v1. Read as a
 // BigInt so an out-of-range value can't coerce to a float; reject an explicitly-
 // encoded v1 (DER forbids encoding the DEFAULT).
-function readVersion(ns) {
-  return schema.decode(function (n) {
-    var v = asn1.read.integer(n);
-    if (v === 0n) throw ns.E(ns.prefix + "/bad-version", "DER forbids explicitly encoding the default version v1");
-    if (v === 1n) return 2;
-    if (v === 2n) return 3;
-    throw ns.E(ns.prefix + "/bad-version", "unsupported certificate version " + v.toString());
-  });
-}
+// version ::= INTEGER { v1(0), v2(1), v3(2) } inside a [0] EXPLICIT DEFAULT v1 —
+// DER forbids encoding the default, so 0 is rejected; 1->v2, 2->v3.
+var CERTIFICATE_VERSION = pkix.versionReader(NS, { "1": 2, "2": 3 });
 
 // TBSCertificate ::= SEQUENCE { version [0] EXPLICIT DEFAULT v1, serialNumber
 // INTEGER, signature AlgorithmIdentifier, issuer Name, validity Validity,
@@ -120,7 +114,7 @@ function readVersion(ns) {
 // EXPLICIT OPTIONAL }. The trailing fields are at-most-once, in increasing tag
 // order (the engine enforces it); only extensions are surfaced.
 var CERTIFICATE_TBS = schema.seq([
-  schema.optional("version", readVersion(NS), { tag: 0, explicit: true, emptyCode: "x509/bad-version", default: 1 }),
+  schema.optional("version", CERTIFICATE_VERSION, { tag: 0, explicit: true, emptyCode: "x509/bad-version", default: 1 }),
   schema.field("serialNumber", schema.integerLeaf()),
   schema.field("signature", ALGORITHM_IDENTIFIER),
   schema.field("issuer", NAME),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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:64eeff87-502c-43f1-a398-5fbe7fc7a614",
+  "serialNumber": "urn:uuid:e5089c51-5287-4fe7-bbfc-520b07cbb2f2",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-05T06:26:48.420Z",
+    "timestamp": "2026-07-05T18:32:46.745Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.8",
+      "bom-ref": "@blamejs/pki@0.1.10",
       "type": "application",
       "name": "pki",
-      "version": "0.1.8",
+      "version": "0.1.10",
       "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.8",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.10",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.8",
+      "ref": "@blamejs/pki@0.1.10",
       "dependsOn": []
     }
   ]