@blamejs/pki 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -4,7 +4,17 @@ 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.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,10 @@ 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.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`, each carrying a stable `code` in `domain/reason` form |
 | `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>` |
 
 ### CLI
@@ -212,7 +213,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,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");
@@ -773,6 +792,7 @@ module.exports = {
     integer:      readInteger,
     enumerated:   readEnumerated,
     bitString:    readBitString,
+    bitStringImplicit: readBitStringImplicit,
     octetString:  readOctetString,
     nullValue:    readNull,
     oid:          readOid,

package/lib/framework-error.js

@@ -133,6 +133,10 @@ 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 });
+
 module.exports = {
   PkiError:         PkiError,
   defineClass:      defineClass,
@@ -144,4 +148,5 @@ module.exports = {
   CrlError:         CrlError,
   SchemaError:      SchemaError,
   CsrError:         CsrError,
+  Pkcs8Error:       Pkcs8Error,
 };

package/lib/schema-all.js

@@ -35,6 +35,7 @@ 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;
@@ -51,6 +52,19 @@ 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,
@@ -93,7 +107,7 @@ var FORMATS = [
  * The names of every registered format, in detection order.
  *
  * @example
- *   pki.schema.all();  // → ["csr", "crl", "x509"]
+ *   pki.schema.all();  // → ["pkcs8", "csr", "crl", "x509"]
  */
 function all() { return FORMATS.map(function (f) { return f.name; }); }
 
@@ -134,6 +148,7 @@ 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 },
   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

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,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 }; }
 
@@ -368,7 +371,7 @@ 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, 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.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:64eeff87-502c-43f1-a398-5fbe7fc7a614",
+  "serialNumber": "urn:uuid:3cf64a06-eef0-417c-a199-787130b9149a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-05T06:26:48.420Z",
+    "timestamp": "2026-07-05T08:37:25.927Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.8",
+      "bom-ref": "@blamejs/pki@0.1.9",
       "type": "application",
       "name": "pki",
-      "version": "0.1.8",
+      "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.8",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.9",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.8",
+      "ref": "@blamejs/pki@0.1.9",
       "dependsOn": []
     }
   ]