@blamejs/pki 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -4,6 +4,36 @@ 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
+
+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.
+
+### Added
+
+- pki.asn1.schema — a declarative ASN.1 structure-schema engine. A schema is plain data built from combinators (seq / field / optional / explicit / trailing / seqOf / setOf / setOfUnique / choice, plus the value leaves oidLeaf / integerLeaf / boolean / octetString / bitString / any / decode / time); pki.asn1.schema.walk(schema, node, ctx) interprets it against a decoded DER node under an error namespace, enforcing the structural rules — shape assertion, bounds-checked positional reads, optional / context-tagged fields in strictly increasing tag order, SET-OF uniqueness, and fail-closed typed errors — in one place. This is the shared base the certificate parser is built on and the forthcoming CRL / CMS parsers compose, so a new format is declared as data rather than hand-written.
+
+### Changed
+
+- pki.x509.parse is now built on the schema engine: the Certificate, tbsCertificate, and every sub-structure (AlgorithmIdentifier, Name, Validity, SubjectPublicKeyInfo, Extensions) are declared as schemas and walked. Every valid certificate parses to the same result as before, and every malformed certificate is still rejected — the full existing test suite passes unchanged. The certificate's structural rules (positional bounds, the trailing-field grammar, extension uniqueness, the signature-algorithm agreement) now live in one auditable place instead of a hand-written decoder, and the format is structurally incapable of the positional-read and duplicate-field bug classes. The parser now validates the full certificate structure before applying cross-field checks, so a certificate carrying more than one defect at once may be rejected with a different (still fail-closed) error than a prior release reported.
+
 ## v0.1.5 — 2026-07-04
 
 Container healthcheck honors WIKI_PORT; release-tooling supply-chain hardening.

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,12 @@ 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.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`, each carrying a stable `code` in `domain/reason` form |
 | `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>` |
 
 ### CLI

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
@@ -27,7 +28,7 @@ var errors    = require("./lib/framework-error");
 var asn1      = require("./lib/asn1-der");
 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,
@@ -35,9 +36,12 @@ module.exports = {
   C:         constants,
   constants: constants,
   errors:    errors,
+  // `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/framework-error.js

@@ -121,6 +121,14 @@ 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 });
+
 module.exports = {
   PkiError:         PkiError,
   defineClass:      defineClass,
@@ -129,4 +137,6 @@ module.exports = {
   OidError:         OidError,
   PemError:         PemError,
   CertificateError: CertificateError,
+  CrlError:         CrlError,
+  SchemaError:      SchemaError,
 };

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 } },

package/lib/schema-all.js

@@ -0,0 +1,126 @@
+// 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,
+ *   and — as they land — CMS / CSR / 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 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 = [
+  {
+    // 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,
+    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();  // → ["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 },
+  all: all,
+  parse: parse,
+};

package/lib/schema-crl.js

@@ -0,0 +1,259 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.schema.crl
+ * @nav        Schema
+ * @title      CRL
+ * @order      120
+ * @slug       crl
+ *
+ * @intro
+ *   X.509 Certificate Revocation List handling per RFC 5280 §5. `parse` turns a
+ *   DER or PEM CRL into a structured, fully-decoded object: version, issuer
+ *   distinguished name, this/next update as real `Date`s, the ordered list of
+ *   revoked certificates (serial + revocation date + entry extensions), and the
+ *   CRL extensions. It composes the same schema engine and shared PKIX
+ *   sub-schemas (AlgorithmIdentifier, Name, Extension) the certificate parser
+ *   uses, so the CertificateList inherits the identical fail-closed structural
+ *   rules, and the raw `tbsCertList` bytes are returned for signature checking.
+ *
+ * @card
+ *   Parse DER / PEM X.509 CRLs into structured, validated fields — revoked
+ *   serials with real-`Date` revocation times, named extensions, 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 CrlError = frameworkError.CrlError;
+var PemError = frameworkError.PemError;
+var TAGS = asn1.TAGS;
+
+
+// CRLReason ::= ENUMERATED (RFC 5280 §5.3.1) — value 7 is unused/reserved.
+var CRL_REASONS = [0n, 1n, 2n, 3n, 4n, 5n, 6n, 8n, 9n, 10n];
+
+// Extension-value decoding is keyed off the STABLE dotted OID (resolved once at
+// load from the canonical name), not the mutable display name — a caller's
+// pki.oid.register() display override must not change parse behaviour.
+var OID_CRL_NUMBER = oid.byName("cRLNumber");
+var OID_REASON_CODE = oid.byName("reasonCode");
+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 ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
+var NAME = pkix.name(NS);
+var EXTENSIONS = pkix.extensions(NS);
+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)");
+});
+
+// The three cheap, high-value CRL extension values are decoded from their raw
+// extnValue octets (RFC 5280 §5.2/§5.3); GeneralNames-based extensions
+// (issuingDistributionPoint, certificateIssuer, authorityKeyIdentifier, …) stay
+// raw with their bytes reachable. A malformed decoded value fails closed.
+function decodeExt(ext) {
+  var value = ext.value;
+  try {
+    if (ext.oid === OID_CRL_NUMBER) {         // cRLNumber ::= INTEGER (0..MAX)
+      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);
+      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
+      var n = asn1.decode(ext.value);
+      if (n.tagClass !== "universal" || n.tagNumber !== TAGS.GENERALIZED_TIME) {
+        throw new Error("invalidityDate must be a GeneralizedTime");
+      }
+      value = asn1.read.time(n);
+    }
+  } catch (e) {
+    throw NS.E("crl/bad-extension-value", "malformed " + (ext.name || ext.oid) + " extension value: " + ((e && e.message) || String(e)), e);
+  }
+  return { oid: ext.oid, name: ext.name, critical: ext.critical, value: value };
+}
+
+// RevokedCertificate ::= SEQUENCE { userCertificate CertificateSerialNumber,
+//   revocationDate Time, crlEntryExtensions Extensions OPTIONAL }
+var REVOKED_ENTRY = schema.seq([
+  schema.field("userCertificate", schema.integerLeaf()),
+  schema.field("revocationDate", TIME),
+  schema.optional("crlEntryExtensions", EXTENSIONS, { whenUniversal: [TAGS.SEQUENCE] }),
+], {
+  assert: "sequence", arity: { min: 2 }, code: "crl/bad-revoked-entry", what: "RevokedCertificate",
+  build: function (m) {
+    return {
+      serialNumber: m.fields.userCertificate.value,
+      // Raw INTEGER content bytes (not a reserialized BigInt) so the hex matches
+      // the X.509 parser's serialNumberHex and preserves DER sign padding
+      // (a positive 0x80 serial encodes as content 00 80).
+      serialNumberHex: m.fields.userCertificate.node.content.toString("hex"),
+      revocationDate: m.fields.revocationDate.value,
+      crlEntryExtensions: m.fields.crlEntryExtensions.present ? m.fields.crlEntryExtensions.value.result.map(decodeExt) : [],
+    };
+  },
+});
+
+var REVOKED_LIST = schema.seqOf(REVOKED_ENTRY, {
+  assert: "sequence", min: 1, code: "crl/bad-revoked-certificates", what: "revokedCertificates",
+  build: function (m) { return m.items.map(function (it) { return it.value.result; }); },
+});
+
+// TBSCertList ::= SEQUENCE { version Version OPTIONAL, signature AlgorithmIdentifier,
+//   issuer Name, thisUpdate Time, nextUpdate Time OPTIONAL,
+//   revokedCertificates SEQUENCE OF SEQUENCE {...} OPTIONAL,
+//   crlExtensions [0] EXPLICIT Extensions OPTIONAL }.
+// The three OPTIONAL universal-tagged fields (version=INTEGER, nextUpdate=Time,
+// revokedCertificates=SEQUENCE) are disambiguated by their universal tag;
+// crlExtensions is modeled as a trailing [0]..[0] so a stray non-[0] trailing
+// context tag is REJECTED (crl/bad-tbs), not silently ignored.
+var TBS_CERTLIST = schema.seq([
+  schema.optional("version", CRL_VERSION, { whenUniversal: [TAGS.INTEGER] }),
+  schema.field("signature", ALGORITHM_IDENTIFIER),
+  schema.field("issuer", NAME),
+  schema.field("thisUpdate", TIME),
+  schema.optional("nextUpdate", TIME, { whenUniversal: [TAGS.UTC_TIME, TAGS.GENERALIZED_TIME] }),
+  schema.optional("revokedCertificates", REVOKED_LIST, { whenUniversal: [TAGS.SEQUENCE] }),
+  schema.trailing([{ tag: 0, name: "crlExtensions", schema: EXTENSIONS, explicit: true, emptyCode: "crl/bad-extensions" }],
+    { minTag: 0, maxTag: 0, unexpectedCode: "crl/bad-tbs", orderCode: "crl/bad-tbs" }),
+], {
+  assert: "sequence", code: "crl/bad-tbs", what: "tbsCertList",
+  build: function (m) {
+    return {
+      version: m.fields.version.present ? m.fields.version.value : 1,
+      issuer: m.fields.issuer.value.result, // Name is a seqOf → field.value is the match; .result is the {rdns, dn} build
+      thisUpdate: m.fields.thisUpdate.value,
+      nextUpdate: m.fields.nextUpdate.present ? m.fields.nextUpdate.value : null,
+      revokedCertificates: m.fields.revokedCertificates.present ? m.fields.revokedCertificates.value.result : [],
+      crlExtensions: m.fields.crlExtensions.present ? m.fields.crlExtensions.value.result.map(decodeExt) : [],
+      crlExtensionsPresent: m.fields.crlExtensions.present,
+    };
+  },
+});
+
+// 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;
+    // 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)) {
+      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.
+    if (!tbs.issuer.rdns.length) {
+      throw NS.E("crl/bad-issuer", "issuer must be a non-empty distinguished name");
+    }
+    // RFC 5280 §5.1.2.1 — crlExtensions / crlEntryExtensions appear only in a v2 CRL.
+    var hasExtensions = tbs.crlExtensionsPresent ||
+      tbs.revokedCertificates.some(function (r) { return r.crlEntryExtensions.length > 0; });
+    if (hasExtensions && tbs.version !== 2) {
+      throw NS.E("crl/bad-version", "crlExtensions / crlEntryExtensions are only permitted in a v2 CRL");
+    }
+    return {
+      version: tbs.version,
+      issuer: tbs.issuer,
+      thisUpdate: tbs.thisUpdate,
+      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 },
+    };
+  },
+});
+
+/**
+ * @primitive  pki.schema.crl.parse
+ * @signature  pki.schema.crl.parse(input) -> crl
+ * @since      0.1.7
+ * @status     experimental
+ * @spec       RFC 5280
+ * @related    pki.schema.x509.parse, pki.schema.parse
+ *
+ * Parse a DER `Buffer` or a PEM (`X509 CRL`) string into a structured CRL:
+ * `{ version, issuer, thisUpdate, nextUpdate, revokedCertificates,
+ * crlExtensions, tbsBytes, signatureAlgorithm, signatureValue }`. Every field is
+ * validated on the way in; a malformed CertificateList / TBSCertList throws a
+ * typed `CrlError` (`crl/*`) and a leaf-level codec fault surfaces as `asn1/*`.
+ *
+ * @example
+ *   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 });
+}
+
+/**
+ * @primitive  pki.schema.crl.pemDecode
+ * @signature  pki.schema.crl.pemDecode(text, label?) -> Buffer
+ * @since      0.1.7
+ * @status     experimental
+ * @spec       RFC 7468, RFC 5280
+ * @related    pki.schema.crl.parse
+ *
+ * Extract the DER bytes from a PEM CRL block (default label `X509 CRL`). Throws
+ * `PemError` on a missing / mismatched envelope or a non-base64 body.
+ *
+ * @example
+ *   var der = pki.schema.crl.pemDecode(pemText);
+ */
+function pemDecode(text, label) { return pkix.pemDecode(text, label || "X509 CRL", PemError); }
+
+// Certificate and CertificateList share the outer SEQUENCE-of-3 shape; a CRL is
+// distinguished by its tbsCertList — the first tbs element is a bare INTEGER
+// (version) or an AlgorithmIdentifier (signature) SEQUENCE, and crucially the
+// field at the certificate's Validity position is a bare Time (thisUpdate). The
+// orchestrator uses `matches` to route; a cert's tbs leads with a [0] EXPLICIT
+// 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;
+  // 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
+  // version, then signature (SEQUENCE) + issuer (SEQUENCE); the next element is
+  // thisUpdate (Time) for a CRL, Validity (SEQUENCE) for a certificate.
+  var i = 0;
+  if (tbs.children[i] && tbs.children[i].tagClass === "universal" && tbs.children[i].tagNumber === TAGS.INTEGER) i++;
+  i += 2; // signature + issuer
+  var pos = tbs.children[i];
+  return !!pos && pos.tagClass === "universal" && (pos.tagNumber === TAGS.UTC_TIME || pos.tagNumber === TAGS.GENERALIZED_TIME);
+}
+
+module.exports = {
+  parse: parse,
+  pemDecode: pemDecode,
+  matches: matches,
+};