@blamejs/pki 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -4,7 +4,40 @@ 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.7 — 2026-07-05
+## 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.
+
+### Added
+
+- pki.schema.csr.parse — a PKCS#10 CertificationRequest parser per RFC 2986. It turns a DER Buffer or a 'CERTIFICATE REQUEST' PEM string into a structured object: version, subject distinguished name, subjectPublicKeyInfo, the requested attributes (each with its type OID, resolved name, and raw-DER values), and the signatureAlgorithm / signatureValue over the CertificationRequestInfo — with the raw certificationRequestInfoBytes returned for signature verification. It composes the shared schema engine and PKIX sub-schemas (AlgorithmIdentifier, Name, SubjectPublicKeyInfo), so a certification request inherits the identical fail-closed structural rules and a malformed request throws a typed CsrError (csr/*); a leaf-level codec fault surfaces as asn1/*. The version must be v1 (INTEGER 0), the [0] IMPLICIT attributes element is mandatory, and each attribute's values SET must be non-empty. pki.schema.parse now detects and routes certification requests, and pki.schema.all() lists it alongside crl and x509. pki.schema.csr.pemDecode / pemEncode handle the PEM envelope.
+- pki.asn1.read.enumerated — reads an ENUMERATED value from a decoded node (the same content rules as an INTEGER), the counterpart to the now-strict pki.asn1.read.integer.
+
+### Changed
+
+- C.TIME.ms is renamed to C.TIME.milliseconds, so every C.TIME duration helper now reads as a full word (milliseconds, seconds, minutes, hours, days, weeks). The behaviour is unchanged — it still returns an integer millisecond count.
+
+### Security
+
+- pki.asn1.read.integer now rejects an ENUMERATED-tagged node. INTEGER and ENUMERATED share DER content encoding, so an INTEGER-pinned field — a certificate or certification-request version, a serial number, or a cRLNumber — mis-encoded as ENUMERATED was previously decoded as though it were the INTEGER, a type confusion that let malformed DER parse where a conformant reader rejects it. read.integer is now strict on the tag, and ENUMERATED values are read with the new pki.asn1.read.enumerated. Certificate, CRL, and certification-request parsing reject these inputs fail-closed.
+- SubjectPublicKeyInfo is now required to be a universal SEQUENCE across the certificate and certification-request parsers — a context-tagged or SET-tagged constructed node carrying a well-formed algorithm and key is no longer accepted as an SPKI.
+- SET OF components are now required to be in ascending DER order (X.690 §11.6) wherever the schema declares a SET OF — a relative distinguished name, and a certification request's attributes and attribute values. A non-canonical, unsorted encoding is rejected fail-closed.
+
+### Migration
+
+- Replace C.TIME.ms(n) with C.TIME.milliseconds(n). The other C.TIME and C.BYTES helpers are unchanged.
+
+## v0.1.7 — 2026-07-04
 
 A unified pki.schema family: the structure-schema engine, the X.509 parser, a new CRL parser, and a detect-and-route orchestrator.
 

package/README.md

@@ -193,9 +193,11 @@ is callable today; nothing below is a stub.
 | `pki.schema` | The schema family — `parse` detects which PKI format DER / PEM encodes and routes to the right parser, `all` enumerates the registered formats, and the engine + per-format members are grouped here |
 | `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.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`, each carrying a stable `code` in `domain/reason` form |
+| `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError` / `Pkcs8Error`, each carrying a stable `code` in `domain/reason` form |
 | `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>` |
 
 ### CLI
@@ -209,9 +211,9 @@ pki parse cert.pem                       # structured JSON summary of a certific
 
 ### What's coming
 
-Certificate build/sign/verify, CRLs, CSRs (PKCS#10), certification-path
+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

@@ -273,15 +273,15 @@ function readBoolean(node) {
   throw new Asn1Error("asn1/bad-boolean", "DER BOOLEAN must be 0x00 or 0xFF, got 0x" + v.toString(16));
 }
 
-function readInteger(node) {
-  if (node.tagClass === "universal" && node.tagNumber === TAGS.ENUMERATED) {
-    // ENUMERATED shares INTEGER's content encoding.
-  } else {
-    _expectUniversal(node, TAGS.INTEGER, "readInteger");
-  }
-  _expectPrimitive(node, "readInteger");
+// INTEGER and ENUMERATED share DER content encoding (a two's-complement big-endian
+// value) but are DISTINCT universal types. This decodes that shared content — the
+// caller asserts the tag first. `typeName` names the type in error messages; the
+// stable error codes stay the integer family (a caller switching on `code` treats
+// both alike since the encoding is identical).
+function _readIntegerLikeContent(node, typeName, who) {
+  _expectPrimitive(node, who);
   var c = node.content;
-  if (c.length === 0) throw new Asn1Error("asn1/bad-integer", "INTEGER must have at least 1 content octet");
+  if (c.length === 0) throw new Asn1Error("asn1/bad-integer", typeName + " must have at least 1 content octet");
   // Defense-in-depth: refuse an over-cap magnitude before touching BigInt.
   // A one-shot hex parse is linear, but the length still bounds worst-case
   // work — reject a hostile length prefix up front. The cap bounds the
@@ -290,20 +290,39 @@ function readInteger(node) {
   // modulus is 16384 magnitude bytes plus that sign pad).
   if (c.length > constants.LIMITS.DER_MAX_INTEGER_BYTES + 1) {
     throw new Asn1Error("asn1/integer-too-large",
-      "INTEGER content " + c.length + " bytes exceeds cap " + (constants.LIMITS.DER_MAX_INTEGER_BYTES + 1));
+      typeName + " content " + c.length + " bytes exceeds cap " + (constants.LIMITS.DER_MAX_INTEGER_BYTES + 1));
   }
   if (c.length > 1) {
-    if (c[0] === 0x00 && (c[1] & 0x80) === 0) throw new Asn1Error("asn1/non-minimal-integer", "non-minimal positive INTEGER");
-    if (c[0] === 0xff && (c[1] & 0x80) !== 0) throw new Asn1Error("asn1/non-minimal-integer", "non-minimal negative INTEGER");
+    if (c[0] === 0x00 && (c[1] & 0x80) === 0) throw new Asn1Error("asn1/non-minimal-integer", "non-minimal positive " + typeName);
+    if (c[0] === 0xff && (c[1] & 0x80) !== 0) throw new Asn1Error("asn1/non-minimal-integer", "non-minimal negative " + typeName);
   }
   var neg = (c[0] & 0x80) !== 0;
   var mag = c.length ? BigInt("0x" + Buffer.from(c).toString("hex")) : 0n;
   return neg ? mag - (1n << BigInt(c.length * 8)) : mag;
 }
 
-function readBitString(node) {
-  _expectUniversal(node, TAGS.BIT_STRING, "readBitString");
-  _expectPrimitive(node, "readBitString");
+// read.integer is STRICT on the tag: an ENUMERATED node (which shares INTEGER's
+// content encoding) is NOT accepted here. Coercing an ENUMERATED to an INTEGER is a
+// type confusion — an INTEGER-pinned field (a certificate/CSR version, a serial
+// number, a cRLNumber) encoded as ENUMERATED would slip past a lenient reader.
+// Read ENUMERATED values with read.enumerated.
+function readInteger(node) {
+  _expectUniversal(node, TAGS.INTEGER, "readInteger");
+  return _readIntegerLikeContent(node, "INTEGER", "readInteger");
+}
+
+// read.enumerated reads an ENUMERATED value; its content rules are identical to
+// INTEGER (non-empty, minimally encoded, magnitude within the cap).
+function readEnumerated(node) {
+  _expectUniversal(node, TAGS.ENUMERATED, "readEnumerated");
+  return _readIntegerLikeContent(node, "ENUMERATED", "readEnumerated");
+}
+
+// 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];
@@ -318,6 +337,23 @@ 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");
@@ -754,7 +790,9 @@ module.exports = {
   read: {
     boolean:      readBoolean,
     integer:      readInteger,
+    enumerated:   readEnumerated,
     bitString:    readBitString,
+    bitStringImplicit: readBitStringImplicit,
     octetString:  readOctetString,
     nullValue:    readNull,
     oid:          readOid,

package/lib/constants.js

@@ -64,7 +64,7 @@ var DAYS_PER_WEEK = 7;
  *   // -> 31536000000
  */
 var TIME = {
-  ms:      function (n) { return Math.round(_positive(n, "C.TIME.ms")); },
+  milliseconds: function (n) { return Math.round(_positive(n, "C.TIME.milliseconds")); },
   seconds: function (n) { return Math.round(_positive(n, "C.TIME.seconds") * MS_PER_SECOND); },
   minutes: function (n) { return Math.round(_positive(n, "C.TIME.minutes") * SECONDS_PER_MINUTE * MS_PER_SECOND); },
   hours:   function (n) { return Math.round(_positive(n, "C.TIME.hours") * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND); },

package/lib/framework-error.js

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

package/lib/oid.js

@@ -71,7 +71,7 @@ var FAMILIES = {
     sha384WithRSAEncryption: 12, sha512WithRSAEncryption: 13 } },
 
   // PKCS#9 attribute types.
-  pkcs9: { base: [1, 2, 840, 113549, 1, 9], of: { emailAddress: 1 } },
+  pkcs9: { base: [1, 2, 840, 113549, 1, 9], of: { emailAddress: 1, challengePassword: 7, extensionRequest: 14 } },
 
   // 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,8 @@
  * @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,
- *   and — as they land — CMS / CSR / PKCS#8) is a member that COMPOSES the
+ *   PKCS#10 certification requests, and — as they land — CMS / PKCS#8) 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,
  *   optional / tagged field ordering, SET-OF uniqueness, fail-closed typed
@@ -33,6 +34,8 @@ var engine = require("./schema-engine");
 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 frameworkError = require("./framework-error");
 
 var SchemaError = frameworkError.SchemaError;
@@ -49,11 +52,34 @@ 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 = [
+  {
+    // 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,
+    // distinguished by a CertificationRequestInfo of EXACTLY four children
+    // ending in the IMPLICIT [0] attributes element. Checked first because that
+    // detector is the most specific and mutually exclusive with the others.
+    name: "csr",
+    module: csr,
+    detect: csr.matches,
+    parse: function (input) { return csr.parse(input); },
+  },
   {
     // CertificateList ::= SEQUENCE { tbsCertList, signatureAlgorithm,
     // signatureValue } — the same outer shape as a certificate, distinguished
     // by its tbsCertList (a bare Time at the certificate's Validity position).
-    // Checked first because its detector is the specific one.
     name: "crl",
     module: crl,
     detect: crl.matches,
@@ -81,7 +107,7 @@ var FORMATS = [
  * The names of every registered format, in detection order.
  *
  * @example
- *   pki.schema.all();  // → ["crl", "x509"]
+ *   pki.schema.all();  // → ["pkcs8", "csr", "crl", "x509"]
  */
 function all() { return FORMATS.map(function (f) { return f.name; }); }
 
@@ -121,6 +147,8 @@ module.exports = {
   engine: engine,
   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 },
   all: all,
   parse: parse,
 };

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
@@ -74,11 +69,9 @@ function decodeExt(ext) {
       value = asn1.read.integer(asn1.decode(ext.value));
       if (value < 0n) throw new Error("cRLNumber must be non-negative (INTEGER 0..MAX)");
     } else if (ext.oid === OID_REASON_CODE) { // reasonCode ::= ENUMERATED (CRLReason)
-      var rn = asn1.decode(ext.value);
-      if (rn.tagClass !== "universal" || rn.tagNumber !== TAGS.ENUMERATED) {
-        throw new Error("reasonCode must be an ENUMERATED");
-      }
-      var reason = asn1.read.integer(rn);
+      // read.enumerated asserts the ENUMERATED tag (a bare INTEGER is rejected) —
+      // the codec owns the tag check, so this reader need not repeat it.
+      var reason = asn1.read.enumerated(asn1.decode(ext.value));
       if (CRL_REASONS.indexOf(reason) === -1) throw new Error("undefined CRLReason " + reason.toString());
       value = Number(reason);
     } else if (ext.oid === OID_INVALIDITY_DATE) { // invalidityDate ::= GeneralizedTime
@@ -153,17 +146,15 @@ var TBS_CERTLIST = schema.seq([
 });
 
 // CertificateList ::= SEQUENCE { tbsCertList, signatureAlgorithm, signatureValue }
-var CERTIFICATE_LIST = schema.seq([
-  schema.field("tbsCertList", TBS_CERTLIST),
-  schema.field("signatureAlgorithm", ALGORITHM_IDENTIFIER),
-  schema.field("signatureValue", schema.bitString()),
-], {
-  assert: "sequence", arity: { exact: 3 }, code: "crl/not-a-crl", what: "CertificateList",
-  build: function (m) {
-    var tbsMatch = m.fields.tbsCertList.value;
-    var tbs = tbsMatch.result;
+// — the shared SIGNED envelope. The CRL-specific invariants (outer==inner
+// signatureAlgorithm agreement, non-empty issuer, v2-only extensions) live in the
+// build; the envelope owns the SEQUENCE-of-3 shape and signature extraction.
+var CERTIFICATE_LIST = pkix.signedEnvelope(NS, TBS_CERTLIST, {
+  code: "crl/not-a-crl", what: "CertificateList",
+  build: function (e) {
+    var tbs = e.tbsMatch.result;
     // RFC 5280 §5.1.1.2 — the outer signatureAlgorithm MUST equal tbsCertList.signature.
-    if (!m.fields.signatureAlgorithm.node.bytes.equals(tbsMatch.fields.signature.node.bytes)) {
+    if (!e.outerSignatureAlgorithmBytes.equals(e.tbsMatch.fields.signature.node.bytes)) {
       throw NS.E("crl/bad-signature-algorithm", "signatureAlgorithm must match tbsCertList.signature (RFC 5280 §5.1.1.2)");
     }
     // RFC 5280 §5.1.2.3 — the issuer MUST be a non-empty distinguished name.
@@ -183,9 +174,9 @@ var CERTIFICATE_LIST = schema.seq([
       nextUpdate: tbs.nextUpdate,
       revokedCertificates: tbs.revokedCertificates,
       crlExtensions: tbs.crlExtensions,
-      tbsBytes: tbsMatch.node.bytes,
-      signatureAlgorithm: m.fields.signatureAlgorithm.value.result,
-      signatureValue: { unusedBits: m.fields.signatureValue.value.unusedBits, bytes: m.fields.signatureValue.value.bytes },
+      tbsBytes: e.tbsBytes,
+      signatureAlgorithm: e.signatureAlgorithm,
+      signatureValue: e.signatureValue,
     };
   },
 });
@@ -208,9 +199,7 @@ var CERTIFICATE_LIST = schema.seq([
  *   var crl = pki.schema.crl.parse(der);
  *   crl.revokedCertificates[0].serialNumberHex;  // → "0a3f…"
  */
-function parse(input) {
-  return pkix.runParse(input, { pemLabel: "X509 CRL", PemError: PemError, ErrorClass: CrlError, prefix: "crl", what: "CRL", topSchema: CERTIFICATE_LIST, ns: NS });
-}
+var parse = pkix.makeParser({ pemLabel: "X509 CRL", PemError: PemError, ErrorClass: CrlError, prefix: "crl", what: "CRL", topSchema: CERTIFICATE_LIST, ns: NS });
 
 /**
  * @primitive  pki.schema.crl.pemDecode
@@ -236,10 +225,8 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || "X509 CRL
 // version or an INTEGER serial FOLLOWED by an AlgorithmIdentifier and a Name,
 // then a Validity SEQUENCE, never a bare Time at that depth.
 function matches(root) {
-  if (!root || root.tagClass !== "universal" || root.tagNumber !== TAGS.SEQUENCE) return false;
-  if (!root.children || root.children.length !== 3) return false;
-  var tbs = root.children[0];
-  if (!tbs.children || tbs.tagNumber !== TAGS.SEQUENCE) return false;
+  var tbs = pkix.signedEnvelopeTbs(root);
+  if (!tbs) return false;
   // A certificate's tbs leads with [0] EXPLICIT version — a CRL never does.
   if (tbs.children[0] && tbs.children[0].tagClass === "context") return false;
   // Walk to the thisUpdate / validity position: skip an optional bare INTEGER

package/lib/schema-csr.js

@@ -0,0 +1,185 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.schema.csr
+ * @nav        Schema
+ * @title      CSR
+ * @order      130
+ * @slug       csr
+ *
+ * @intro
+ *   PKCS#10 certification request handling per RFC 2986. `parse` turns a DER or
+ *   PEM CSR into a structured object: version, subject distinguished name,
+ *   subject public-key info, the requested attributes (each with its raw values),
+ *   and the signature over the CertificationRequestInfo. It composes the same
+ *   schema engine and shared PKIX sub-schemas (AlgorithmIdentifier, Name,
+ *   SubjectPublicKeyInfo) the certificate parser uses, so the request inherits the
+ *   identical fail-closed structural rules, and the raw
+ *   `certificationRequestInfoBytes` are returned for signature checking.
+ *
+ *   A CSR is self-signed only in the sense that the requester proves possession of
+ *   the private key; unlike a certificate or CRL there is no inner signature
+ *   algorithm to agree with, the subject MAY be empty, and the attribute set has
+ *   no uniqueness constraint — the parser deliberately omits those three
+ *   certificate/CRL guards.
+ *
+ * @card
+ *   Parse DER / PEM PKCS#10 CSRs into structured, validated fields — subject DN,
+ *   public key, requested attributes, signature, 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 CsrError = frameworkError.CsrError;
+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 = pkix.makeNS("csr", CsrError, oid);
+
+var NAME = pkix.name(NS);
+var SPKI = pkix.spki(NS);
+
+// CertificationRequestInfo version ::= INTEGER { v1(0) } (RFC 2986 §4.1). A BARE
+// mandatory INTEGER whose ONLY legal value is 0 — the inverse of the cert/CRL
+// 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 = pkix.versionReader(NS, { "0": 1 });
+
+// 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 }.
+// attributes is a REQUIRED field (a CRI omitting [0] is a missing-required-field
+// fault, not silently accepted) modeled as an IMPLICIT [0] SET OF with min:0 (an
+// empty attributes SET is legal). subject MAY be empty — no non-empty-DN guard.
+var CERTIFICATION_REQUEST_INFO = schema.seq([
+  schema.field("version", CSR_VERSION),
+  schema.field("subject", NAME),
+  schema.field("subjectPKInfo", SPKI),
+  schema.field("attributes", schema.implicitSetOf(0, ATTRIBUTE, { min: 0, code: "csr/bad-attributes", what: "attributes" })),
+], {
+  assert: "sequence", code: "csr/bad-cri", what: "certificationRequestInfo",
+  build: function (m) {
+    return {
+      version: m.fields.version.value,
+      subject: m.fields.subject.value.result, // Name is a seqOf → field.value is the match; .result is the {rdns, dn} build
+      subjectPublicKeyInfo: m.fields.subjectPKInfo.value.result,
+      attributes: m.fields.attributes.value.items.map(function (it) { return it.value.result; }),
+    };
+  },
+});
+
+// CertificationRequest ::= SEQUENCE { certificationRequestInfo, signatureAlgorithm,
+//   signature BIT STRING } — the shared SIGNED envelope. DIVERGENCE from the
+// cert/CRL builders: OMIT the outer-vs-inner signatureAlgorithm agreement check
+// (the CRI has no inner signature AlgorithmIdentifier) and the non-empty-subject
+// guard (a CSR subject MAY be empty). The omission is structural — this build
+// simply never references the agreement bytes.
+var CERTIFICATION_REQUEST = pkix.signedEnvelope(NS, CERTIFICATION_REQUEST_INFO, {
+  code: "csr/not-a-certification-request", what: "CertificationRequest",
+  build: function (e) {
+    var cri = e.tbsMatch.result;
+    return {
+      version: cri.version,
+      subject: cri.subject,
+      subjectPublicKeyInfo: cri.subjectPublicKeyInfo,
+      attributes: cri.attributes,
+      certificationRequestInfoBytes: e.tbsBytes,
+      tbsBytes: e.tbsBytes,
+      signatureAlgorithm: e.signatureAlgorithm,
+      signatureValue: e.signatureValue,
+    };
+  },
+});
+
+/**
+ * @primitive  pki.schema.csr.parse
+ * @signature  pki.schema.csr.parse(input) -> csr
+ * @since      0.1.8
+ * @status     experimental
+ * @spec       RFC 2986
+ * @related    pki.schema.x509.parse, pki.schema.parse
+ *
+ * Parse a DER `Buffer` or a PEM (`CERTIFICATE REQUEST`) string into a structured
+ * PKCS#10 request: `{ version, subject, subjectPublicKeyInfo, attributes,
+ * certificationRequestInfoBytes, tbsBytes, signatureAlgorithm, signatureValue }`.
+ * Every field is validated on the way in; a malformed CertificationRequest /
+ * CertificationRequestInfo throws a typed `CsrError` (`csr/*`) and a leaf-level
+ * codec fault surfaces as `asn1/*`. Attribute values are returned as raw DER
+ * buffers so an unrecognized attribute type never fails the parse.
+ *
+ * @example
+ *   var csr = pki.schema.csr.parse(der);
+ *   csr.subject.dn;             // → "CN=req.example"
+ *   csr.attributes[0].type;     // → "1.2.840.113549.1.9.14"
+ */
+var parse = pkix.makeParser({ pemLabel: "CERTIFICATE REQUEST", PemError: PemError, ErrorClass: CsrError, prefix: "csr", what: "certification request", topSchema: CERTIFICATION_REQUEST, ns: NS });
+
+/**
+ * @primitive  pki.schema.csr.pemDecode
+ * @signature  pki.schema.csr.pemDecode(text, label?) -> Buffer
+ * @since      0.1.8
+ * @status     experimental
+ * @spec       RFC 7468, RFC 2986
+ * @related    pki.schema.csr.parse
+ *
+ * Extract the DER bytes from a PEM CSR block (default label `CERTIFICATE
+ * REQUEST`). Throws `PemError` on a missing / mismatched envelope or a non-base64
+ * body.
+ *
+ * @example
+ *   var der = pki.schema.csr.pemDecode(pemText);
+ */
+function pemDecode(text, label) { return pkix.pemDecode(text, label || "CERTIFICATE REQUEST", PemError); }
+
+/**
+ * @primitive  pki.schema.csr.pemEncode
+ * @signature  pki.schema.csr.pemEncode(der, label?) -> string
+ * @since      0.1.8
+ * @status     experimental
+ * @spec       RFC 7468
+ * @related    pki.schema.csr.pemDecode
+ *
+ * Wrap DER bytes in a PEM CSR envelope (default label `CERTIFICATE REQUEST`).
+ *
+ * @example
+ *   var pem = pki.schema.csr.pemEncode(der);
+ */
+function pemEncode(der, label) { return pkix.pemEncode(der, label || "CERTIFICATE REQUEST", PemError); }
+
+// A CertificationRequest shares the outer SEQUENCE-of-3 shape with a certificate
+// and a CRL; a CSR is distinguished by its CertificationRequestInfo — a SEQUENCE
+// of EXACTLY four children {version INTEGER, subject SEQUENCE, subjectPKInfo
+// SEQUENCE, attributes [0]}. The mandatory trailing context-[0] attributes
+// element is what a cert (whose tbs leads with [0] EXPLICIT version or an INTEGER
+// serial and never ends the leading run this way) and a CRL (whose tbs reaches a
+// bare Time at the validity position) never present, so the three detectors are
+// mutually exclusive.
+function matches(root) {
+  var TAGS = asn1.TAGS;
+  var cri = pkix.signedEnvelopeTbs(root);
+  if (!cri) return false;
+  var k = cri.children;
+  if (k.length !== 4) return false;
+  return k[0].tagClass === "universal" && k[0].tagNumber === TAGS.INTEGER &&
+    k[1].tagClass === "universal" && k[1].tagNumber === TAGS.SEQUENCE &&
+    k[2].tagClass === "universal" && k[2].tagNumber === TAGS.SEQUENCE &&
+    k[3].tagClass === "context" && k[3].tagNumber === 0;
+}
+
+module.exports = {
+  parse: parse,
+  pemDecode: pemDecode,
+  pemEncode: pemEncode,
+  matches: matches,
+};

package/lib/schema-engine.js

@@ -62,6 +62,13 @@ function _assertShape(schema, node, ctx) {
     if (!node.children) {
       _fail(ctx, schema.code, (schema.what || "value") + " must be a constructed value");
     }
+  } else if (mode === "implicit") {
+    // IMPLICIT [tag] SET/SEQUENCE OF: the context tag replaces the universal
+    // tag, so the node is a context-class constructed [tag] and its direct
+    // children are the items (no inner universal SET, no EXPLICIT unwrap).
+    if (node.tagClass !== "context" || node.tagNumber !== schema.implicitTag || !node.children) {
+      _fail(ctx, schema.code, (schema.what || "value") + " must be an IMPLICIT [" + schema.implicitTag + "] SET OF");
+    }
   } else {
     _fail(ctx, schema.code, "unknown assert mode " + JSON.stringify(mode));
   }
@@ -90,6 +97,9 @@ 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 }; } }; }
 function any()            { return { kind: "any" }; }
 function decode(fn)       { return { kind: "decode", fn: fn }; }
 
@@ -163,12 +173,20 @@ function seqOf(item, opts) {
 }
 function setOf(item, opts) {
   opts = opts || {};
-  return { kind: "repeat", item: item, assert: opts.assert || "set", code: opts.code, what: opts.what,
+  return { kind: "repeat", item: item, assert: opts.assert || "set", derSetOrder: true, code: opts.code, what: opts.what,
            min: opts.min, unique: opts.unique, dupCode: opts.dupCode, build: opts.build };
 }
 function setOfUnique(item, keyFn, opts) {
   return setOf(item, Object.assign({ unique: keyFn }, opts || {}));
 }
+// [tag] IMPLICIT SET OF item — the context tag REPLACES the universal SET tag,
+// so the node is a context-class constructed [tag] whose direct children are the
+// items (RFC 2986 §4.1 CSR attributes). No inner SET, no EXPLICIT unwrap.
+function implicitSetOf(tag, item, opts) {
+  opts = opts || {};
+  return { kind: "repeat", item: item, assert: "implicit", implicitTag: tag, derSetOrder: true, code: opts.code, what: opts.what,
+           min: opts.min, unique: opts.unique, dupCode: opts.dupCode, build: opts.build };
+}
 
 // ---- the walk engine -------------------------------------------------
 
@@ -246,6 +264,19 @@ function _walkRepeat(schema, node, ctx) {
   if (schema.min != null && kids.length < schema.min) {
     _fail(ctx, schema.code, (schema.what || "value") + " must contain at least " + schema.min + " element(s)");
   }
+  // DER (X.690 §11.6) — the components of a SET OF appear in ascending order, the
+  // encodings compared as octet strings. SEQUENCE OF is order-preserving and is
+  // exempt (no derSetOrder). Compare full TLV byte strings, the same canonical
+  // order build.set emits, so a decode round-trips a build. Equal-adjacent
+  // encodings are permitted here (semantic uniqueness is the `unique` option's
+  // job); only a descending pair is non-canonical.
+  if (schema.derSetOrder) {
+    for (var s = 1; s < kids.length; s++) {
+      if (Buffer.compare(kids[s - 1].bytes, kids[s].bytes) > 0) {
+        _fail(ctx, schema.code, (schema.what || "value") + " components must be in ascending DER order (X.690 §11.6)");
+      }
+    }
+  }
   var items = [];
   var seen = schema.unique ? new Set() : null;
   for (var i = 0; i < kids.length; i++) {
@@ -337,10 +368,10 @@ function _consumeTrailing(fld, kids, start, fields, ctx) {
 module.exports = {
   // structural
   seq: seq, field: field, optional: optional, explicit: explicit, trailing: trailing,
-  seqOf: seqOf, setOf: setOf, setOfUnique: setOfUnique, choice: choice,
+  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, 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()),
@@ -221,18 +245,124 @@ function extensions(ns) {
   });
 }
 
+// SubjectPublicKeyInfo ::= SEQUENCE { algorithm AlgorithmIdentifier,
+// subjectPublicKey BIT STRING } (RFC 5280 §4.1.2.7, RFC 2986 §4.1). Asserted as a
+// universal SEQUENCE — a context-tagged or SET-tagged constructed node carrying
+// two well-formed children is NOT a SubjectPublicKeyInfo. Shared by the
+// certificate and CSR parsers.
+function spki(ns) {
+  return schema.seq([
+    schema.field("algorithm", algorithmIdentifier(ns)),
+    schema.field("subjectPublicKey", schema.bitString()),
+  ], {
+    assert: "sequence", arity: { exact: 2 }, code: ns.prefix + "/bad-spki", what: "SubjectPublicKeyInfo",
+    build: function (m) {
+      return {
+        algorithm: m.fields.algorithm.value.result,
+        publicKey: { unusedBits: m.fields.subjectPublicKey.value.unusedBits, bytes: m.fields.subjectPublicKey.value.bytes },
+        bytes: m.node.bytes,
+      };
+    },
+  });
+}
+
+// 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
+// SEQUENCE-of-exactly-3 whose first child is itself a constructed universal
+// SEQUENCE, or null otherwise. Every format's `matches` detector shares this
+// preamble, so the signed-envelope shape is recognized in one place and the three
+// detectors cannot drift on it (the CRL detector historically omitted the
+// tbs-is-universal check this recovers).
+function signedEnvelopeTbs(root) {
+  if (!root || root.tagClass !== "universal" || root.tagNumber !== asn1.TAGS.SEQUENCE) return null;
+  if (!root.children || root.children.length !== 3) return null;
+  var tbs = root.children[0];
+  if (!tbs.children || tbs.tagClass !== "universal" || tbs.tagNumber !== asn1.TAGS.SEQUENCE) return null;
+  return tbs;
+}
+
+// Every format's `parse` is the shared runParse bound to that format's identity
+// (PEM label, error class, error-code prefix, top-level schema). This returns the
+// bound parser so a format declares its configuration once and never re-writes the
+// coerce -> decode -> walk wrapper. `opts`: { pemLabel, PemError, ErrorClass,
+// prefix, what, topSchema, ns }.
+function makeParser(opts) {
+  return function (input) { return runParse(input, opts); };
+}
+
+// The X.509 SIGNED{ToBeSigned} macro (RFC 5280 §4.1.1.3): the outer
+// SEQUENCE { toBeSigned, signatureAlgorithm AlgorithmIdentifier,
+// signatureValue BIT STRING } shared by Certificate, CertificateList and
+// CertificationRequest. `tbsSchema` parses the first element; the SEQUENCE-of-3
+// shape, the arity, the signature extraction and the raw tbs / outer-signature
+// bytes (for the cert/CRL outer==inner agreement check) are owned here once, and
+// each format's `opts.build(envelope, ctx)` shapes its own object from the
+// envelope. A CSR's build simply omits the agreement check — its CRI has no inner
+// signature AlgorithmIdentifier — so the omission is structural, not a copy that
+// forgot a guard.
+function signedEnvelope(ns, tbsSchema, opts) {
+  return schema.seq([
+    schema.field("toBeSigned", tbsSchema),
+    schema.field("signatureAlgorithm", algorithmIdentifier(ns)),
+    schema.field("signatureValue", schema.bitString()),
+  ], {
+    assert: "sequence", arity: { exact: 3 }, code: opts.code, what: opts.what,
+    build: function (m, ctx) {
+      var tbsMatch = m.fields.toBeSigned.value;
+      var sigBits = m.fields.signatureValue.value;
+      return opts.build({
+        tbsMatch: tbsMatch,                                    // raw seq-match: .fields.* / .result / .node
+        tbsBytes: tbsMatch.node.bytes,                         // the exact signed region
+        outerSignatureAlgorithmBytes: m.fields.signatureAlgorithm.node.bytes,
+        signatureAlgorithm: m.fields.signatureAlgorithm.value.result,
+        signatureValue: { unusedBits: sigBits.unusedBits, bytes: sigBits.bytes },
+      }, ctx);
+    },
+  });
+}
+
 module.exports = {
   pemDecode: pemDecode,
   pemEncode: pemEncode,
   coerceToDer: coerceToDer,
   decodeRoot: decodeRoot,
   runParse: runParse,
+  makeNS: makeNS,
+  versionReader: versionReader,
   DN_SHORT: DN_SHORT,
   algorithmIdentifier: algorithmIdentifier,
+  spki: spki,
+  makeParser: makeParser,
+  signedEnvelopeTbs: signedEnvelopeTbs,
+  signedEnvelope: signedEnvelope,
   attrValueToString: attrValueToString,
   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);
@@ -95,35 +95,17 @@ var VALIDITY = schema.seq([
   build: function (m) { return { notBefore: m.fields.notBefore.value, notAfter: m.fields.notAfter.value }; },
 });
 
-// SubjectPublicKeyInfo ::= SEQUENCE { algorithm AlgorithmIdentifier, subjectPublicKey BIT STRING }.
-var SPKI = schema.seq([
-  schema.field("algorithm", ALGORITHM_IDENTIFIER),
-  schema.field("subjectPublicKey", schema.bitString()),
-], {
-  assert: "constructed", arity: { exact: 2 }, code: "x509/bad-spki", what: "SubjectPublicKeyInfo",
-  build: function (m) {
-    return {
-      algorithm: m.fields.algorithm.value.result, // algorithm field = ALGORITHM_IDENTIFIER seq-match; .value = its build
-      publicKey: { unusedBits: m.fields.subjectPublicKey.value.unusedBits, bytes: m.fields.subjectPublicKey.value.bytes },
-      bytes: m.node.bytes,
-    };
-  },
-});
+// SubjectPublicKeyInfo — the shared pkix.spki factory under the x509 NS.
+var SPKI = pkix.spki(NS);
 
 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,
@@ -132,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),
@@ -151,17 +133,17 @@ var CERTIFICATE_TBS = schema.seq([
 // agreement, §4.1.2.4 non-empty issuer, §4.1.2.9 extensions-only-in-v3) after the
 // structural walk, then assembles the public parse result. Raw-byte accessors
 // (serialNumberHex, tbsBytes, sig-alg agreement) read off the match-tree nodes.
-var CERTIFICATE = schema.seq([
-  schema.field("tbsCertificate", CERTIFICATE_TBS),
-  schema.field("signatureAlgorithm", ALGORITHM_IDENTIFIER),
-  schema.field("signatureValue", schema.bitString()),
-], {
-  assert: "sequence", arity: { exact: 3 }, code: "x509/not-a-certificate", what: "Certificate",
-  build: function (m, ctx) {
-    var tbs = m.fields.tbsCertificate.value; // CERTIFICATE_TBS seq-match (no build)
+// Certificate ::= SEQUENCE { tbsCertificate, signatureAlgorithm, signatureValue }
+// — the shared SIGNED envelope. The certificate-specific invariants (outer==inner
+// signatureAlgorithm agreement, non-empty issuer, v3-only extensions) live in the
+// build; the envelope owns the SEQUENCE-of-3 shape and signature extraction.
+var CERTIFICATE = pkix.signedEnvelope(NS, CERTIFICATE_TBS, {
+  code: "x509/not-a-certificate", what: "Certificate",
+  build: function (e, ctx) {
+    var tbs = e.tbsMatch; // CERTIFICATE_TBS seq-match (no build)
 
     // RFC 5280 §4.1.1.2 — outer signatureAlgorithm MUST equal tbsCertificate.signature.
-    if (!m.fields.signatureAlgorithm.node.bytes.equals(tbs.fields.signature.node.bytes)) {
+    if (!e.outerSignatureAlgorithmBytes.equals(tbs.fields.signature.node.bytes)) {
       throw ctx.E("x509/bad-signature-algorithm", "signatureAlgorithm must match tbsCertificate.signature (RFC 5280 §4.1.1.2)");
     }
 
@@ -180,20 +162,19 @@ var CERTIFICATE = schema.seq([
     }
 
     var serialNode = tbs.fields.serialNumber.node;
-    var sigBits = m.fields.signatureValue.value; // { unusedBits, bytes }
     return {
       version:               version,
       serialNumber:          tbs.fields.serialNumber.value,
       serialNumberHex:       serialNode.content.toString("hex"),
-      signatureAlgorithm:    m.fields.signatureAlgorithm.value.result,
+      signatureAlgorithm:    e.signatureAlgorithm,
       tbsSignatureAlgorithm: tbs.fields.signature.value.result,
       issuer:                issuer,
       subject:               tbs.fields.subject.value.result,
       validity:              tbs.fields.validity.value.result,
       subjectPublicKeyInfo:  tbs.fields.subjectPublicKeyInfo.value.result,
       extensions:            hasExtensions ? extField.value.result : [],
-      tbsBytes:              tbs.node.bytes,
-      signatureValue:        { unusedBits: sigBits.unusedBits, bytes: sigBits.bytes },
+      tbsBytes:              e.tbsBytes,
+      signatureValue:        e.signatureValue,
     };
   },
 });
@@ -226,9 +207,7 @@ var CERTIFICATE = schema.seq([
  *   cert.validity.notAfter;          // Date
  *   cert.signatureAlgorithm.name;    // "sha256WithRSAEncryption"
  */
-function parse(input) {
-  return pkix.runParse(input, { pemLabel: "CERTIFICATE", PemError: PemError, ErrorClass: CertificateError, prefix: "x509", what: "certificate", topSchema: CERTIFICATE, ns: NS });
-}
+var parse = pkix.makeParser({ pemLabel: "CERTIFICATE", PemError: PemError, ErrorClass: CertificateError, prefix: "x509", what: "certificate", topSchema: CERTIFICATE, ns: NS });
 
 // matches(root): does the decoded DER look like a Certificate? A CSR and a CRL
 // share the outer SEQUENCE-of-3 envelope, so the discriminator is inside the
@@ -238,10 +217,8 @@ function parse(input) {
 // and a CRL leads with a bare Time; neither matches. Used by the orchestrator.
 function matches(root) {
   var TAGS = asn1.TAGS;
-  if (!root || root.tagClass !== "universal" || root.tagNumber !== TAGS.SEQUENCE) return false;
-  if (!root.children || root.children.length !== 3) return false;
-  var tbs = root.children[0];
-  if (!tbs.children || tbs.tagClass !== "universal" || tbs.tagNumber !== TAGS.SEQUENCE) return false;
+  var tbs = pkix.signedEnvelopeTbs(root);
+  if (!tbs) return false;
   var kids = tbs.children;
   var i = (kids[0] && kids[0].tagClass === "context" && kids[0].tagNumber === 0) ? 1 : 0; // optional [0] version
   var validity = kids[i + 3]; // serial(i), signature(i+1), issuer(i+2), validity(i+3)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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:a50e8ea1-a357-4e08-b473-56bcf5e2659f",
+  "serialNumber": "urn:uuid:3cf64a06-eef0-417c-a199-787130b9149a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-05T03:52:05.348Z",
+    "timestamp": "2026-07-05T08:37:25.927Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.7",
+      "bom-ref": "@blamejs/pki@0.1.9",
       "type": "application",
       "name": "pki",
-      "version": "0.1.7",
+      "version": "0.1.9",
       "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.7",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.9",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.7",
+      "ref": "@blamejs/pki@0.1.9",
       "dependsOn": []
     }
   ]