@blamejs/pki 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -4,6 +4,47 @@ 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
+
+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.
+
+### Added
+
+- pki.schema.crl.parse — an X.509 CRL (CertificateList) parser per RFC 5280 §5. It turns a DER Buffer or an 'X509 CRL' PEM string into a structured object: version, issuer distinguished name, thisUpdate / nextUpdate as real Dates, the ordered list of revoked certificates (serial number + hex + revocation date + entry extensions), and the CRL extensions — with the cRLNumber, reasonCode, and invalidityDate values decoded and the raw tbsCertList bytes returned for signature verification. It composes the same schema engine and shared PKIX sub-schemas (AlgorithmIdentifier, Name, Extension) as the certificate parser, so the CertificateList inherits the identical fail-closed structural rules (bounds-checked positional reads, the signature-algorithm agreement, non-empty issuer, extension uniqueness, the v2-only version rule).
+- pki.schema.parse — a detect-and-route entry point: hand it DER or PEM and it identifies which registered PKI format the bytes encode (certificate vs CRL) and routes to that member's parser. pki.schema.all() enumerates the registered formats.
+
+### Changed
+
+- The schema engine and the per-format parsers are reorganized under one pki.schema namespace. pki.x509.parse is now pki.schema.x509.parse (and .pemDecode / .pemEncode likewise), and the structure-schema engine pki.asn1.schema is now pki.schema.engine. pki.asn1 remains the strict DER codec (decode / encode / build / read / TAGS). This is a breaking rename with no compatibility shim; see MIGRATING. The schema engine also gained a universal-tag optional-field recognizer, which the CRL's bare version / nextUpdate / revokedCertificates fields require.
+
+### Migration
+
+- Replace pki.x509.parse(...) with pki.schema.x509.parse(...); pki.x509.pemDecode / pemEncode become pki.schema.x509.pemDecode / pemEncode.
+- Replace pki.asn1.schema (the structure-schema engine) with pki.schema.engine. pki.asn1 is unchanged for the DER codec (pki.asn1.decode / encode / build / read / TAGS).
+
 ## v0.1.6 — 2026-07-04
 
 A declarative ASN.1 structure-schema engine; the X.509 parser is rebuilt on it.

package/README.md

@@ -63,7 +63,7 @@ var pki = require("@blamejs/pki");
 
 ### Parse an X.509 certificate
 
-`pki.x509.parse` accepts a DER `Buffer` or a PEM string/Buffer and returns a
+`pki.schema.x509.parse` accepts a DER `Buffer` or a PEM string/Buffer and returns a
 fully-decoded, validated certificate — distinguished names rendered and
 structured, the validity window as real `Date`s, algorithms and extensions
 named through the OID registry, and the exact signed `tbsBytes` for a downstream
@@ -74,7 +74,7 @@ var pki = require("@blamejs/pki");
 var fs  = require("node:fs");
 
 var pem  = fs.readFileSync("cert.pem", "utf8");
-var cert = pki.x509.parse(pem);
+var cert = pki.schema.x509.parse(pem);
 
 cert.subject.dn;                    // "CN=example.com, O=Example Org, C=US"
 cert.issuer.dn;                     // "CN=example.com, O=Example Org, C=US"
@@ -94,7 +94,7 @@ Malformed bytes throw a typed error rather than returning a half-parsed object:
 
 ```js
 try {
-  pki.x509.parse(Buffer.from([0x30, 0x03, 0x02, 0x01, 0x00]));
+  pki.schema.x509.parse(Buffer.from([0x30, 0x03, 0x02, 0x01, 0x00]));
 } catch (e) {
   e.constructor.name;  // "CertificateError"
   e.code;              // e.g. "x509/not-a-certificate" — stable domain/reason string
@@ -104,8 +104,8 @@ try {
 ### Convert PEM ↔ DER
 
 ```js
-var der = pki.x509.pemDecode(pem, "CERTIFICATE");   // Buffer of DER bytes
-var out = pki.x509.pemEncode(der, "CERTIFICATE");   // 64-column PEM string
+var der = pki.schema.x509.pemDecode(pem, "CERTIFICATE");   // Buffer of DER bytes
+var out = pki.schema.x509.pemEncode(der, "CERTIFICATE");   // 64-column PEM string
 ```
 
 ### Decode and build ASN.1 / DER directly
@@ -180,7 +180,7 @@ var ok  = await subtle.verify({ name: "ML-DSA-65" }, kp.publicKey, sig, data); /
 // same call shape, and every key it exports is OpenSSL/NSS-interoperable.
 ```
 
-## What ships today (v0.1.0)
+## What ships today
 
 The core codec and certificate-reading surface are here and stable. Everything
 is callable today; nothing below is a stub.
@@ -190,9 +190,13 @@ is callable today; nothing below is a stub.
 | `pki.asn1` | Strict, bounded DER codec — `decode` (zero-copy node tree), `encode`, `build.*` canonical-DER value builders, `read.*` typed readers, `TAGS`, OID-content encode/decode |
 | `pki.oid` | Two-way OID ↔ name registry — `name`, `byName`, `register`, `toArcs`/`fromArcs`, `toDER`/`fromDER`; seeded with RFC 5280 + NIST PQC arcs |
 | `pki.webcrypto` | A W3C WebCrypto (`SubtleCrypto`) engine over `node:crypto` — `sign`/`verify`/`encrypt`/`decrypt`/`deriveBits`/`digest`/`generateKey`/`importKey`/`exportKey` across RSA, ECDSA, ECDH, Ed25519/Ed448, AES, HMAC, HKDF, PBKDF2, SHA — **and** post-quantum ML-DSA-44/65/87 and SLH-DSA signatures, plus ML-KEM-512/768/1024 key generation (KEM encapsulation on the roadmap). Zero-dependency, OpenSSL-interoperable |
-| `pki.x509` | Parse DER / PEM certificates into structured, validated fields — `parse`, `pemDecode`, `pemEncode` |
+| `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.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`, each carrying a stable `code` in `domain/reason` form |
+| `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError`, each carrying a stable `code` in `domain/reason` form |
 | `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>` |
 
 ### CLI
@@ -206,7 +210,7 @@ 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
 post-quantum certificate and CMS surface (ML-DSA / ML-KEM / SLH-DSA and hybrid

package/bin/pki.js

@@ -44,7 +44,7 @@ function cmdParse(file) {
   var bytes;
   try { bytes = fs.readFileSync(file); } catch (e) { return fail("cannot read " + file + ": " + e.message); }
   var cert;
-  try { cert = pki.x509.parse(bytes); } catch (e) { return fail(e.code + ": " + e.message); }
+  try { cert = pki.schema.x509.parse(bytes); } catch (e) { return fail(e.code + ": " + e.message); }
   var view = {
     version:            cert.version,
     serialNumber:       cert.serialNumberHex,
@@ -74,3 +74,4 @@ function main(argv) {
 }
 
 main(process.argv.slice(2));
+

package/index.js

@@ -13,7 +13,8 @@
  *                  (PkiError taxonomy), asn1 (strict DER codec), oid
  *                  (OID ↔ name registry), webcrypto (W3C SubtleCrypto
  *                  engine over node:crypto — PQC-first, classical-capable)
- *   Certificates:  x509 (parse DER / PEM certificates)
+ *   Schema:        schema (the structure-schema engine + per-format parsers:
+ *                  schema.engine, schema.x509, schema.parse detect-and-route)
  *
  * The surface grows per ROADMAP.md — CMS, OCSP, CRL, CSR, PKCS#8/#12,
  * timestamping, path validation, and the post-quantum algorithm set are
@@ -25,10 +26,9 @@
 var constants = require("./lib/constants");
 var errors    = require("./lib/framework-error");
 var asn1      = require("./lib/asn1-der");
-var asn1Schema = require("./lib/asn1-schema");
 var oid       = require("./lib/oid");
 var webcrypto = require("./lib/webcrypto");
-var x509      = require("./lib/x509");
+var schema    = require("./lib/schema-all");
 
 module.exports = {
   version:   constants.version,
@@ -36,11 +36,12 @@ module.exports = {
   C:         constants,
   constants: constants,
   errors:    errors,
-  // `asn1.schema` (L2) is the declarative structure-schema engine, exposed on
-  // the asn1 namespace alongside the codec (decode/encode/build/read/TAGS).
-  asn1:      Object.assign({}, asn1, { schema: asn1Schema }),
+  // `asn1` is the strict DER codec (decode/encode/build/read/TAGS).
+  asn1:      asn1,
   oid:       oid,
-  x509:      x509,
+  // `schema` is the family: the L2 structure-schema engine (schema.engine) and
+  // the per-format parsers (schema.x509, …) with detect-and-route schema.parse.
+  schema:    schema,
   // A ready W3C Crypto instance (globalThis.crypto shape) + the classes
   // for constructing more. PQC-first, classical-capable, zero-dep.
   webcrypto: webcrypto.webcrypto,

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,17 +290,34 @@ 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;
 }
 
+// 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");
+}
+
 function readBitString(node) {
   _expectUniversal(node, TAGS.BIT_STRING, "readBitString");
   _expectPrimitive(node, "readBitString");
@@ -754,6 +771,7 @@ module.exports = {
   read: {
     boolean:      readBoolean,
     integer:      readInteger,
+    enumerated:   readEnumerated,
     bitString:    readBitString,
     octetString:  readOctetString,
     nullValue:    readNull,

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

@@ -121,6 +121,18 @@ var PemError = defineClass("PemError");
 // version).
 var CertificateError = defineClass("CertificateError", { withCause: true });
 
+// CrlError — a byte sequence that is not a well-formed X.509 CRL
+// (CertificateList / TBSCertList — RFC 5280 §5).
+var CrlError = defineClass("CrlError", { withCause: true });
+
+// SchemaError — the schema-family orchestrator's own errors (input that matches
+// no registered format / does not decode). (code, message) shape like the rest.
+var SchemaError = defineClass("SchemaError", { withCause: true });
+
+// CsrError — a byte sequence that is not a well-formed PKCS#10 CertificationRequest
+// (RFC 2986).
+var CsrError = defineClass("CsrError", { withCause: true });
+
 module.exports = {
   PkiError:         PkiError,
   defineClass:      defineClass,
@@ -129,4 +141,7 @@ module.exports = {
   OidError:         OidError,
   PemError:         PemError,
   CertificateError: CertificateError,
+  CrlError:         CrlError,
+  SchemaError:      SchemaError,
+  CsrError:         CsrError,
 };

package/lib/oid.js

@@ -54,8 +54,13 @@ var FAMILIES = {
   // RFC 5280 certificate extensions.
   certExtension: { base: [2, 5, 29], of: {
     subjectKeyIdentifier: 14, keyUsage: 15, subjectAltName: 17, issuerAltName: 18,
-    basicConstraints: 19, nameConstraints: 30, cRLDistributionPoints: 31,
-    certificatePolicies: 32, authorityKeyIdentifier: 35, extKeyUsage: 37 } },
+    basicConstraints: 19,
+    // CRL + CRL-entry extensions (RFC 5280 §5.2, §5.3)
+    cRLNumber: 20, reasonCode: 21, invalidityDate: 24, deltaCRLIndicator: 27,
+    issuingDistributionPoint: 28, certificateIssuer: 29,
+    nameConstraints: 30, cRLDistributionPoints: 31,
+    certificatePolicies: 32, authorityKeyIdentifier: 35, extKeyUsage: 37,
+    freshestCRL: 46 } },
 
   // PKIX private extensions (authorityInfoAccess et al).
   pkixAccess: { base: [1, 3, 6, 1, 5, 5, 7, 1], of: { authorityInfoAccess: 1 } },
@@ -66,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

@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.schema
+ * @nav        Schema
+ * @title      Schema
+ * @order      10
+ * @featured   true
+ * @slug       schema
+ *
+ * @intro
+ *   The schema family: a declarative ASN.1 structure-schema engine and the
+ *   per-format parsers built on it. Every format (X.509 certificates, CRLs,
+ *   PKCS#10 certification requests, and — as they land — CMS / PKCS#8) is a
+ *   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
+ *   errors — is defined once in the engine and no format can reintroduce the
+ *   class of bug it prevents.
+ *
+ *   `parse` is the orchestrator: hand it DER (or PEM) and it detects which
+ *   format the bytes encode and routes to that member's parser. Each member is
+ *   also reachable directly (`pki.schema.x509.parse`, `pki.schema.crl.parse`),
+ *   and `all()` enumerates the registered formats.
+ *
+ * @card
+ *   One declarative schema engine; every PKI format (X.509, CRL, …) is a
+ *   member composed on it. Detect-and-parse DER, or call a format directly.
+ */
+
+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 frameworkError = require("./framework-error");
+
+var SchemaError = frameworkError.SchemaError;
+var PemError = frameworkError.PemError;
+
+// The shared parse-entry opts for the orchestrator: label-agnostic PEM unwrap
+// (any block type routes), the schema/* error family. Detection needs DER, so
+// the coerced DER is what gets routed to the matched format.
+var ENTRY = { pemLabel: null, PemError: PemError, ErrorClass: SchemaError, prefix: "schema", what: "input" };
+
+// REGISTRY — each format is declarative data: a name, a `detect(root)` that
+// recognizes the decoded DER root as this format's outer structure, and the
+// member's own `parse`. Adding a format is a table entry, not new dispatch
+// logic. Order matters: the most specific detector wins, so a new member is
+// inserted ahead of any more-permissive one.
+var FORMATS = [
+  {
+    // 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).
+    name: "crl",
+    module: crl,
+    detect: crl.matches,
+    parse: function (input) { return crl.parse(input); },
+  },
+  {
+    name: "x509",
+    module: x509,
+    // Certificate — identified by a Validity (SEQUENCE of two Times) inside the
+    // tbs, so a CSR / other 3-element signed envelope is NOT misclassified as a
+    // certificate (it falls through to schema/unknown-format).
+    detect: x509.matches,
+    parse: function (input) { return x509.parse(input); },
+  },
+];
+
+/**
+ * @primitive  pki.schema.all
+ * @signature  pki.schema.all() -> string[]
+ * @since      0.1.7
+ * @status     experimental
+ * @spec       RFC 5280
+ * @related    pki.schema.parse
+ *
+ * The names of every registered format, in detection order.
+ *
+ * @example
+ *   pki.schema.all();  // → ["csr", "crl", "x509"]
+ */
+function all() { return FORMATS.map(function (f) { return f.name; }); }
+
+/**
+ * @primitive  pki.schema.parse
+ * @signature  pki.schema.parse(input) -> parsed
+ * @since      0.1.7
+ * @status     experimental
+ * @spec       RFC 5280
+ * @related    pki.schema.x509, pki.schema.all
+ *
+ * Detect which PKI format `input` (a DER `Buffer` or a PEM string) encodes and
+ * route to that format's parser, returning the same structured object the
+ * format's own `parse` returns. Throws `SchemaError("schema/unknown-format")` when
+ * the bytes match no registered format; the underlying decode / structural
+ * errors of the matched format propagate unchanged.
+ *
+ * @example
+ *   var parsed = pki.schema.parse(der);  // cert → the pki.schema.x509 shape
+ */
+function parse(input) {
+  // Coerce + decode via the shared parse-entry, then route the COERCED DER (a
+  // PEM string/Buffer is already unwrapped, so the matched format parses DER
+  // directly and never re-treats the armor as DER).
+  var der = pkix.coerceToDer(input, ENTRY);
+  var root = pkix.decodeRoot(der, ENTRY);
+  for (var i = 0; i < FORMATS.length; i++) {
+    if (FORMATS[i].detect(root)) return FORMATS[i].parse(der);
+  }
+  throw new SchemaError("schema/unknown-format", "input does not match any registered PKI format (" + all().join(", ") + ")");
+}
+
+// Curated public surface: each format exposes only its operator primitives. The
+// `matches` detector is internal dispatch infrastructure (used by FORMATS above),
+// not an operator API, so it is NOT re-exported here.
+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 },
+  all: all,
+  parse: parse,
+};