@blamejs/pki 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.

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
@@ -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/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,
+};

package/lib/{asn1-schema.js → schema-engine.js}

@@ -2,8 +2,8 @@
 // Copyright (c) blamejs contributors
 "use strict";
 /**
- * @module     pki.asn1.schema
- * @nav        ASN.1
+ * @module     pki.schema.engine
+ * @nav        Schema
  * @title      Schema engine
  * @order      60
  *
@@ -109,14 +109,20 @@ function time(ns) {
 function field(name, schema)          { return { fkind: "required", name: name, schema: schema }; }
 function optional(name, schema, opts) {
   opts = opts || {};
-  // How the optional field is recognized at its position. Default: a context
-  // [tag] (the certificate version [0] shape). `whenAny`: the next element
-  // whatever its tag — an OPTIONAL ANY like AlgorithmIdentifier.parameters. The
-  // recognizer lets _walkSeq CONSUME the element so a closed sequence can reject
-  // whatever is left over (without it, a trailing ANY looks unconsumed).
+  // How the optional field is recognized at its position:
+  //   - default:       a context [tag] (the certificate version [0] shape).
+  //   - whenUniversal: the next element iff its UNIVERSAL tag is in the set —
+  //     the CRL TBSCertList shape (bare INTEGER version, Time nextUpdate,
+  //     SEQUENCE revokedCertificates), disambiguated by tag, not a context [n].
+  //   - whenAny:       the next element whatever its tag — an OPTIONAL ANY like
+  //     AlgorithmIdentifier.parameters.
+  // The recognizer lets _walkSeq CONSUME the element so a closed sequence can
+  // reject whatever is left over (without it, a trailing ANY looks unconsumed).
   var match = opts.whenAny
     ? function () { return true; }
-    : function (n) { return n.tagClass === "context" && n.tagNumber === opts.tag; };
+    : opts.whenUniversal
+      ? function (n) { return n.tagClass === "universal" && opts.whenUniversal.indexOf(n.tagNumber) !== -1; }
+      : function (n) { return n.tagClass === "context" && n.tagNumber === opts.tag; };
   return { fkind: "optional", name: name, schema: schema, tag: opts.tag, match: match,
            explicit: !!opts.explicit, emptyCode: opts.emptyCode, hasDefault: ("default" in opts), def: opts.default };
 }
@@ -167,12 +173,12 @@ function setOfUnique(item, keyFn, opts) {
 // ---- the walk engine -------------------------------------------------
 
 /**
- * @primitive  pki.asn1.schema.walk
- * @signature  pki.asn1.schema.walk(schema, node, ctx) -> value
- * @since      0.1.6
+ * @primitive  pki.schema.engine.walk
+ * @signature  pki.schema.engine.walk(schema, node, ctx) -> value
+ * @since      0.1.7
  * @status     experimental
  * @spec       X.690, X.680
- * @related    pki.asn1.decode, pki.x509.parse
+ * @related    pki.asn1.decode, pki.schema.x509.parse
  *
  * Interpret a declarative schema against a decoded DER node, enforcing the
  * schema's structural rules (shape assertion, arity, optional / context-tagged
@@ -188,7 +194,7 @@ function setOfUnique(item, keyFn, opts) {
  * `octetString` / `bitString` / `any` / `decode` / `time`).
  *
  * @example
- *   var S = pki.asn1.schema;
+ *   var S = pki.schema.engine;
  *   var ALGID = S.seq([S.field("algorithm", S.oidLeaf())],
  *     { assert: "sequence", arity: { min: 1 }, code: "app/bad-alg" });
  *   S.walk(ALGID, pki.asn1.decode(der), { prefix: "app", E: MyError, oid: pki.oid });

package/lib/schema-pkix.js

@@ -0,0 +1,239 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal — no operator-facing namespace. The documented surface is the
+// parsers that compose these factories (pki.schema.x509, pki.schema.crl, …).
+//
+// Shared PKIX structure-schema factories (RFC 5280). Each is a namespace-
+// parameterized FACTORY: given an error namespace `ns` ({ prefix, E, oid }) it
+// returns an asn1-schema that walks the corresponding ASN.1 structure and emits
+// the caller's own <prefix>/* error codes. x509.js, crl.js, and future CMS/CSR
+// parsers compose these so AlgorithmIdentifier / Name / Extension are defined
+// once, not re-derived per format. This module is internal infrastructure — the
+// operator-facing surface is the parsers that consume it.
+
+var asn1 = require("./asn1-der");
+var constants = require("./constants");
+var schema = require("./schema-engine");
+
+var PEM_RE = /-----BEGIN ([A-Z0-9 ]+)-----([\s\S]*?)-----END \1-----/;
+
+// ---- shared parse-entry ----------------------------------------------
+// Input handling, PEM unwrapping (with the size cap), DER-decode wrapping, and
+// the walk are defined ONCE here so no format can diverge on a guard. Each
+// format supplies only its labels, error class, code prefix, and top schema.
+
+// pemDecode(text, label, PemError): `label` (when truthy) is enforced, else the
+// first block is taken. Applies the LIMITS.PEM_MAX_BYTES cap before scanning.
+function pemDecode(text, label, PemError) {
+  if (Buffer.isBuffer(text)) text = text.toString("latin1");
+  if (typeof text !== "string") throw new PemError("pem/bad-input", "pemDecode expects a string or Buffer");
+  if (text.length > constants.LIMITS.PEM_MAX_BYTES) throw new PemError("pem/too-large", "PEM input exceeds size cap");
+  var m = PEM_RE.exec(text);
+  if (!m) throw new PemError("pem/no-block", "no PEM block found");
+  if (label && m[1] !== label) throw new PemError("pem/label-mismatch", "expected " + JSON.stringify(label) + " block, got " + JSON.stringify(m[1]));
+  var b64 = m[2].replace(/[\r\n\t ]+/g, "");
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(b64)) throw new PemError("pem/bad-base64", "PEM body is not valid base64");
+  return Buffer.from(b64, "base64");
+}
+
+function pemEncode(der, label, PemError) {
+  if (typeof label !== "string" || label.length === 0) throw new PemError("pem/bad-label", "pemEncode requires a label");
+  var buf = Buffer.isBuffer(der) ? der : Buffer.from(der);
+  var b64 = buf.toString("base64").replace(/(.{64})/g, "$1\n").replace(/\n$/, "");
+  return "-----BEGIN " + label + "-----\n" + b64 + "\n-----END " + label + "-----\n";
+}
+
+// Coerce parse input to DER bytes. A PEM string OR a PEM Buffer (a .pem file
+// read with fs.readFileSync) is unwrapped with opts.pemLabel; a DER Buffer or
+// Uint8Array is taken as bytes. opts: { pemLabel, PemError, ErrorClass, prefix }.
+function coerceToDer(input, opts) {
+  if (typeof input === "string") return pemDecode(input, opts.pemLabel, opts.PemError);
+  if (input instanceof Uint8Array && !Buffer.isBuffer(input)) input = Buffer.from(input);
+  if (Buffer.isBuffer(input)) {
+    return _isPemArmor(input) ? pemDecode(input, opts.pemLabel, opts.PemError) : input;
+  }
+  throw new opts.ErrorClass(opts.prefix + "/bad-input", "parse expects a DER Buffer or a PEM string");
+}
+
+// Does a Buffer carry PEM armor (a .pem read with fs.readFileSync) rather than
+// raw DER? It does iff "-----BEGIN" appears and everything before it is TEXT
+// (UTF-8 BOM / whitespace / RFC 7468 explanatory preamble). DER is binary — its
+// leading tag+length bytes are non-printable — so a non-SEQUENCE DER (a bare
+// SET / INTEGER) is NOT misrouted here; it decodes and fails closed structurally.
+function _isPemArmor(buf) {
+  var head = buf.slice(0, 4096).toString("latin1");
+  var idx = head.indexOf("-----BEGIN");
+  if (idx === -1) return false;
+  for (var i = 0; i < idx; i++) {
+    var c = buf[i];
+    var textByte = (c >= 0x20 && c < 0x7f) || c === 0x09 || c === 0x0a || c === 0x0d ||
+      c === 0xef || c === 0xbb || c === 0xbf; // printable ASCII, tab/newlines, UTF-8 BOM
+    if (!textByte) return false;
+  }
+  return true;
+}
+
+// Decode the DER root, wrapping a codec fault in the caller's <prefix>/bad-der.
+function decodeRoot(der, opts) {
+  try { return asn1.decode(der); }
+  catch (e) { throw new opts.ErrorClass(opts.prefix + "/bad-der", (opts.what || "input") + " DER did not decode: " + ((e && e.message) || String(e)), e); }
+}
+
+// The shared parse entry: coerce -> decode -> walk the top schema. A format's
+// parse() is one call to this; the guard-parity bug class (a new format not
+// mirroring an existing format's input handling) is structurally impossible.
+function runParse(input, opts) {
+  return schema.walk(opts.topSchema, decodeRoot(coerceToDer(input, opts), opts), opts.ns).result;
+}
+
+// Distinguished-name attribute short labels (RFC 4514 §3 + common use).
+var DN_SHORT = {
+  commonName:             "CN",
+  countryName:            "C",
+  localityName:           "L",
+  stateOrProvinceName:    "ST",
+  streetAddress:          "STREET",
+  organizationName:       "O",
+  organizationalUnitName: "OU",
+  domainComponent:        "DC",
+  surname:                "SN",
+  givenName:              "GN",
+  serialNumber:           "SERIALNUMBER",
+  emailAddress:           "emailAddress",
+};
+
+// AlgorithmIdentifier ::= SEQUENCE { algorithm OBJECT IDENTIFIER, parameters ANY OPTIONAL }
+function algorithmIdentifier(ns) {
+  return schema.seq([
+    schema.field("algorithm", schema.oidLeaf()),
+    schema.optional("parameters", schema.any(), { whenAny: true }),
+  ], {
+    assert: "sequence", arity: { min: 1 }, code: ns.prefix + "/bad-algorithm-identifier", what: "AlgorithmIdentifier",
+    build: function (m, ctx) {
+      var dotted = m.fields.algorithm.value;
+      return { oid: dotted, name: ctx.oid.name(dotted) || null, parameters: m.fields.parameters.present ? m.fields.parameters.node.bytes : null };
+    },
+  });
+}
+
+// attrValueToString(ns): the AttributeValue decode-leaf. A malformed KNOWN
+// string type (invalid UTF-8, a non-IA5 byte, a PrintableString character
+// outside its set, ...) surfaces as an asn1/bad-* content error and must fail
+// closed — do NOT hex-encode it away, or the decoder's strict string validation
+// is silently bypassed on the DN path. A value that is simply not a decodable
+// primitive string is NOT malformed and stays representable: an ANY-typed
+// non-string tag (asn1/expected-string) or a constructed universal type such as
+// a SEQUENCE (asn1/expected-primitive) renders per RFC 4514 §2.4 as "#" plus the
+// hex of its FULL DER encoding (node.bytes), round-tripping intact.
+function attrValueToString(ns) {
+  return schema.decode(function (node) {
+    try { return asn1.read.string(node); }
+    catch (e) {
+      if (!e || (e.code !== "asn1/expected-string" && e.code !== "asn1/expected-primitive")) {
+        throw ns.E(ns.prefix + "/bad-atv", "malformed string in attribute value: " + ((e && e.message) || String(e)));
+      }
+      return "#" + node.bytes.toString("hex");
+    }
+  });
+}
+
+function _escapeDnValue(v) {
+  return v.replace(/([,+"\\<>;])/g, "\\$1");
+}
+
+// Name ::= RDNSequence ::= SEQUENCE OF RelativeDistinguishedName; RDN ::= SET OF
+// AttributeTypeAndValue ::= SEQUENCE { type OID, value ANY }. The atv asserts
+// bare-constructed (min 2) — matching the historical guard that never checked
+// the SEQUENCE tag — and repeated RDN attribute types stay legal (no uniqueness).
+function attributeTypeAndValue(ns) {
+  return schema.seq([
+    schema.field("type", schema.oidLeaf()),
+    schema.field("value", attrValueToString(ns)),
+  ], {
+    assert: "constructed", arity: { min: 2 }, code: ns.prefix + "/bad-atv", what: "AttributeTypeAndValue",
+    build: function (m, ctx) {
+      var typeOid = m.fields.type.value;
+      return { type: typeOid, name: ctx.oid.name(typeOid) || null, value: m.fields.value.value };
+    },
+  });
+}
+function relativeDistinguishedName(ns) {
+  // RelativeDistinguishedName ::= SET SIZE (1..MAX) — an empty SET {} is malformed.
+  return schema.setOf(attributeTypeAndValue(ns), { assert: "set", min: 1, code: ns.prefix + "/bad-rdn", what: "RelativeDistinguishedName" });
+}
+function name(ns) {
+  return schema.seqOf(relativeDistinguishedName(ns), {
+    assert: "sequence", code: ns.prefix + "/bad-name", what: "Name",
+    build: function (m) {
+      var rdns = [], parts = [];
+      m.items.forEach(function (rdnItem) {
+        var atvs = [], atvParts = [];
+        rdnItem.value.items.forEach(function (atvItem) {
+          var a = atvItem.value.result; // atvItem.value = the atv seq-match; .result = its build result
+          atvs.push(a);
+          var label = (a.name && DN_SHORT[a.name]) || a.name || a.type;
+          atvParts.push(label + "=" + _escapeDnValue(a.value));
+        });
+        rdns.push(atvs);
+        parts.push(atvParts.join("+"));
+      });
+      return { rdns: rdns, dn: parts.join(", ") };
+    },
+  });
+}
+
+// Extension ::= SEQUENCE { extnID OID, critical BOOLEAN DEFAULT FALSE,
+// extnValue OCTET STRING }. `critical` is a universal BOOLEAN present-by-count
+// (not context-tagged), so the per-extension decode handles the 2-vs-3-child
+// shape directly; the seqOf centralizes the SEQUENCE / SIZE(1..MAX) assertion
+// and the RFC 5280 §4.2 per-OID uniqueness.
+function extension(ns) {
+  return schema.decode(function (ext) {
+    // Extension ::= SEQUENCE { extnID, critical DEFAULT FALSE, extnValue } — a
+    // UNIVERSAL SEQUENCE of exactly 2 (critical omitted) or 3 children. A
+    // context-tagged item (e.g. [5]{OID, OCTET STRING}) or a wrong child count
+    // is malformed; assert the tag, don't just count children (fail closed).
+    if (!ext.children || ext.tagClass !== "universal" || ext.tagNumber !== asn1.TAGS.SEQUENCE ||
+        ext.children.length < 2 || ext.children.length > 3) {
+      throw ns.E(ns.prefix + "/bad-extension", "Extension must be a SEQUENCE of {extnID, critical?, extnValue}");
+    }
+    var extnID = asn1.read.oid(ext.children[0]);
+    var critical = false, valueNode;
+    if (ext.children.length === 3) {
+      critical = asn1.read.boolean(ext.children[1]);
+      // critical is BOOLEAN DEFAULT FALSE — DER omits the field when false, so an
+      // explicitly-encoded FALSE is a non-canonical form; reject it fail-closed.
+      if (critical === false) throw ns.E(ns.prefix + "/bad-extension", "an explicit critical FALSE must be omitted (BOOLEAN DEFAULT FALSE)");
+      valueNode = ext.children[2];
+    } else {
+      valueNode = ext.children[1];
+    }
+    return { oid: extnID, name: ns.oid.name(extnID) || null, critical: critical, value: asn1.read.octetString(valueNode) };
+  });
+}
+function extensions(ns) {
+  return schema.seqOf(extension(ns), {
+    assert: "sequence", min: 1, code: ns.prefix + "/bad-extensions", what: "Extensions",
+    unique: function (item) { return item.value.oid; }, dupCode: ns.prefix + "/duplicate-extension",
+    build: function (m) { return m.items.map(function (it) { return it.value; }); },
+  });
+}
+
+module.exports = {
+  pemDecode: pemDecode,
+  pemEncode: pemEncode,
+  coerceToDer: coerceToDer,
+  decodeRoot: decodeRoot,
+  runParse: runParse,
+  DN_SHORT: DN_SHORT,
+  algorithmIdentifier: algorithmIdentifier,
+  attrValueToString: attrValueToString,
+  attributeTypeAndValue: attributeTypeAndValue,
+  relativeDistinguishedName: relativeDistinguishedName,
+  name: name,
+  extension: extension,
+  extensions: extensions,
+};
+

package/lib/{x509.js → schema-x509.js}

@@ -2,8 +2,8 @@
 // Copyright (c) blamejs contributors
 "use strict";
 /**
- * @module     pki.x509
- * @nav        Certificates
+ * @module     pki.schema.x509
+ * @nav        Schema
  * @title      X.509
  * @order      100
  * @featured   true
@@ -29,42 +29,24 @@
  *   with named algorithms, extensions, and real-`Date` validity windows.
  */
 
-var constants = require("./constants");
 var asn1 = require("./asn1-der");
-var schema = require("./asn1-schema");
+var schema = require("./schema-engine");
 var oid = require("./oid");
 var frameworkError = require("./framework-error");
+var pkix = require("./schema-pkix");
 
 var CertificateError = frameworkError.CertificateError;
 var PemError = frameworkError.PemError;
 
-// Distinguished-name attribute short labels (RFC 4514 §3 + common use).
-var DN_SHORT = {
-  commonName:             "CN",
-  countryName:            "C",
-  localityName:           "L",
-  stateOrProvinceName:    "ST",
-  streetAddress:          "STREET",
-  organizationName:       "O",
-  organizationalUnitName: "OU",
-  domainComponent:        "DC",
-  surname:                "SN",
-  givenName:              "GN",
-  serialNumber:           "SERIALNUMBER",
-  emailAddress:           "emailAddress",
-};
-
 // ---- PEM -------------------------------------------------------------
 
-var PEM_RE = /-----BEGIN ([A-Z0-9 ]+)-----([\s\S]*?)-----END \1-----/;
-
 /**
- * @primitive  pki.x509.pemDecode
- * @signature  pki.x509.pemDecode(text, label?) -> Buffer
- * @since      0.1.0
+ * @primitive  pki.schema.x509.pemDecode
+ * @signature  pki.schema.x509.pemDecode(text, label?) -> Buffer
+ * @since      0.1.7
  * @status     stable
  * @spec       RFC 7468, RFC 5280
- * @related    pki.x509.pemEncode
+ * @related    pki.schema.x509.pemEncode
  *
  * Extract the DER bytes from a PEM block. With `label` given (e.g.
  * `"CERTIFICATE"`) the block type must match; without it, the first block
@@ -72,133 +54,36 @@ var PEM_RE = /-----BEGIN ([A-Z0-9 ]+)-----([\s\S]*?)-----END \1-----/;
  * non-base64 body.
  *
  * @example
- *   var der = pki.x509.pemDecode(pemText, "CERTIFICATE");
+ *   var der = pki.schema.x509.pemDecode(pemText, "CERTIFICATE");
  */
-function pemDecode(text, label) {
-  if (Buffer.isBuffer(text)) text = text.toString("latin1");
-  if (typeof text !== "string") throw new PemError("pem/bad-input", "pemDecode expects a string or Buffer");
-  if (text.length > constants.LIMITS.PEM_MAX_BYTES) throw new PemError("pem/too-large", "PEM input exceeds size cap");
-  var m = PEM_RE.exec(text);
-  if (!m) throw new PemError("pem/no-block", "no PEM block found");
-  if (label && m[1] !== label) throw new PemError("pem/label-mismatch", "expected " + JSON.stringify(label) + " block, got " + JSON.stringify(m[1]));
-  var b64 = m[2].replace(/[\r\n\t ]+/g, "");
-  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(b64)) throw new PemError("pem/bad-base64", "PEM body is not valid base64");
-  return Buffer.from(b64, "base64");
-}
+function pemDecode(text, label) { return pkix.pemDecode(text, label, PemError); }
 
 /**
- * @primitive  pki.x509.pemEncode
- * @signature  pki.x509.pemEncode(der, label) -> string
- * @since      0.1.0
+ * @primitive  pki.schema.x509.pemEncode
+ * @signature  pki.schema.x509.pemEncode(der, label) -> string
+ * @since      0.1.7
  * @status     stable
  * @spec       RFC 7468, RFC 5280
- * @related    pki.x509.pemDecode
+ * @related    pki.schema.x509.pemDecode
  *
  * Wrap DER bytes in a PEM envelope with 64-column base64 lines.
  *
  * @example
- *   var pem = pki.x509.pemEncode(der, "CERTIFICATE");
+ *   var pem = pki.schema.x509.pemEncode(der, "CERTIFICATE");
  */
-function pemEncode(der, label) {
-  if (typeof label !== "string" || label.length === 0) throw new PemError("pem/bad-label", "pemEncode requires a label");
-  var buf = Buffer.isBuffer(der) ? der : Buffer.from(der);
-  var b64 = buf.toString("base64").replace(/(.{64})/g, "$1\n").replace(/\n$/, "");
-  return "-----BEGIN " + label + "-----\n" + b64 + "\n-----END " + label + "-----\n";
-}
+function pemEncode(der, label) { return pkix.pemEncode(der, label, PemError); }
 
 // ---- helpers ---------------------------------------------------------
 
 // The x509 error namespace the schema engine walks under: prefix names the
 // error family and E constructs the typed CertificateError. The shared PKIX
-// sub-schemas below are ns-parameterized FACTORIES so crl.js / cms.js can later
-// reuse them while emitting their own crl/*, cms/* codes (hoist to a shared
-// lib/pkix-schema.js when that second consumer lands).
+// 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 };
 
-// AlgorithmIdentifier ::= SEQUENCE { algorithm OBJECT IDENTIFIER, parameters ANY OPTIONAL }
-function algorithmIdentifier(ns) {
-  return schema.seq([
-    schema.field("algorithm", schema.oidLeaf()),
-    schema.optional("parameters", schema.any(), { whenAny: true }),
-  ], {
-    assert: "sequence", arity: { min: 1 }, code: ns.prefix + "/bad-algorithm-identifier", what: "AlgorithmIdentifier",
-    build: function (m, ctx) {
-      var dotted = m.fields.algorithm.value;
-      return { oid: dotted, name: ctx.oid.name(dotted) || null, parameters: m.fields.parameters.present ? m.fields.parameters.node.bytes : null };
-    },
-  });
-}
-var ALGORITHM_IDENTIFIER = algorithmIdentifier(NS);
-
-function _algId(node) { return schema.walk(ALGORITHM_IDENTIFIER, node, NS).result; }
-
-// attrValueToString(ns): the AttributeValue decode-leaf. A malformed KNOWN
-// string type (invalid UTF-8, a non-IA5 byte, a PrintableString character
-// outside its set, ...) surfaces as an asn1/bad-* content error and must fail
-// the certificate closed — do NOT hex-encode it away, or the decoder's strict
-// string validation is silently bypassed on the DN path. A value that is simply
-// not a decodable primitive string is NOT malformed and stays representable: an
-// ANY-typed non-string tag (asn1/expected-string) or a constructed universal
-// type such as a SEQUENCE (asn1/expected-primitive) renders per RFC 4514 §2.4 as
-// "#" plus the hex of its FULL DER encoding (node.bytes), round-tripping intact.
-function attrValueToString(ns) {
-  return schema.decode(function (node) {
-    try { return asn1.read.string(node); }
-    catch (e) {
-      if (!e || (e.code !== "asn1/expected-string" && e.code !== "asn1/expected-primitive")) {
-        throw ns.E(ns.prefix + "/bad-atv", "malformed string in attribute value: " + ((e && e.message) || String(e)));
-      }
-      return "#" + node.bytes.toString("hex");
-    }
-  });
-}
-
-function _escapeDnValue(v) {
-  return v.replace(/([,+"\\<>;])/g, "\\$1");
-}
-
-// Name ::= RDNSequence ::= SEQUENCE OF RelativeDistinguishedName; RDN ::= SET OF
-// AttributeTypeAndValue ::= SEQUENCE { type OID, value ANY }. The atv asserts
-// bare-constructed (min 2) — matching the historical guard that never checked
-// the SEQUENCE tag — and repeated RDN attribute types stay legal (no uniqueness).
-function attributeTypeAndValue(ns) {
-  return schema.seq([
-    schema.field("type", schema.oidLeaf()),
-    schema.field("value", attrValueToString(ns)),
-  ], {
-    assert: "constructed", arity: { min: 2 }, code: ns.prefix + "/bad-atv", what: "AttributeTypeAndValue",
-    build: function (m, ctx) {
-      var typeOid = m.fields.type.value;
-      return { type: typeOid, name: ctx.oid.name(typeOid) || null, value: m.fields.value.value };
-    },
-  });
-}
-function relativeDistinguishedName(ns) {
-  return schema.setOf(attributeTypeAndValue(ns), { assert: "set", code: ns.prefix + "/bad-rdn", what: "RelativeDistinguishedName" });
-}
-function name(ns) {
-  return schema.seqOf(relativeDistinguishedName(ns), {
-    assert: "sequence", code: ns.prefix + "/bad-name", what: "Name",
-    build: function (m) {
-      var rdns = [], parts = [];
-      m.items.forEach(function (rdnItem) {
-        var atvs = [], atvParts = [];
-        rdnItem.value.items.forEach(function (atvItem) {
-          var a = atvItem.value.result; // atvItem.value = the atv seq-match; .value = its build result
-          atvs.push(a);
-          var label = (a.name && DN_SHORT[a.name]) || a.name || a.type;
-          atvParts.push(label + "=" + _escapeDnValue(a.value));
-        });
-        rdns.push(atvs);
-        parts.push(atvParts.join("+"));
-      });
-      return { rdns: rdns, dn: parts.join(", ") };
-    },
-  });
-}
-var NAME = name(NS);
-
-function _parseName(node) { return schema.walk(NAME, node, NS).result; }
+var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
+var NAME = pkix.name(NS);
 
 // Validity ::= SEQUENCE { notBefore Time, notAfter Time }. The historical guard
 // checked only children.length===2 (not the SEQUENCE tag) -> assert "constructed".
@@ -225,33 +110,7 @@ var SPKI = schema.seq([
   },
 });
 
-// Extension ::= SEQUENCE { extnID OID, critical BOOLEAN DEFAULT FALSE,
-// extnValue OCTET STRING }. `critical` is a universal BOOLEAN present-by-count
-// (not context-tagged), so the per-extension decode handles the 2-vs-3-child
-// shape directly; the seqOf centralizes the SEQUENCE / SIZE(1..MAX) assertion
-// and the RFC 5280 §4.2 per-OID uniqueness.
-function extension(ns) {
-  return schema.decode(function (ext) {
-    if (!ext.children || ext.children.length < 2) {
-      throw ns.E(ns.prefix + "/bad-extension", "Extension must be a SEQUENCE");
-    }
-    var extnID = asn1.read.oid(ext.children[0]);
-    var critical = false, valueNode;
-    if (ext.children.length === 3) { critical = asn1.read.boolean(ext.children[1]); valueNode = ext.children[2]; }
-    else { valueNode = ext.children[1]; }
-    return { oid: extnID, name: ns.oid.name(extnID) || null, critical: critical, value: asn1.read.octetString(valueNode) };
-  });
-}
-function extensions(ns) {
-  return schema.seqOf(extension(ns), {
-    assert: "sequence", min: 1, code: ns.prefix + "/bad-extensions", what: "Extensions",
-    unique: function (item) { return item.value.oid; }, dupCode: ns.prefix + "/duplicate-extension",
-    build: function (m) { return m.items.map(function (it) { return it.value; }); },
-  });
-}
-var EXTENSIONS = extensions(NS);
-
-function _parseExtensions(seqNode) { return schema.walk(EXTENSIONS, seqNode, NS).result; }
+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-
@@ -342,9 +201,9 @@ var CERTIFICATE = schema.seq([
 // ---- parse -----------------------------------------------------------
 
 /**
- * @primitive  pki.x509.parse
- * @signature  pki.x509.parse(input) -> certificate
- * @since      0.1.0
+ * @primitive  pki.schema.x509.parse
+ * @signature  pki.schema.x509.parse(input) -> certificate
+ * @since      0.1.7
  * @status     stable
  * @spec       RFC 5280, X.509
  * @defends    malformed-certificate-parse (CWE-20)
@@ -362,32 +221,40 @@ var CERTIFICATE = schema.seq([
  * certificate and `Asn1Error` when the underlying DER is malformed.
  *
  * @example
- *   var cert = pki.x509.parse(pemString);
+ *   var cert = pki.schema.x509.parse(pemString);
  *   cert.subject.dn;                 // "CN=example.com, O=Example"
  *   cert.validity.notAfter;          // Date
  *   cert.signatureAlgorithm.name;    // "sha256WithRSAEncryption"
  */
 function parse(input) {
-  var der;
-  if (typeof input === "string" || (Buffer.isBuffer(input) && input.length >= 5 && input.toString("latin1", 0, 5) === "-----")) {
-    der = pemDecode(input, "CERTIFICATE");
-  } else if (Buffer.isBuffer(input) || input instanceof Uint8Array) {
-    der = Buffer.isBuffer(input) ? input : Buffer.from(input);
-  } else {
-    throw new CertificateError("x509/bad-input", "parse expects a DER Buffer or a PEM string");
-  }
+  return pkix.runParse(input, { pemLabel: "CERTIFICATE", PemError: PemError, ErrorClass: CertificateError, prefix: "x509", what: "certificate", topSchema: CERTIFICATE, ns: NS });
+}
 
-  var root;
-  try {
-    root = asn1.decode(der);
-  } catch (e) {
-    throw new CertificateError("x509/bad-der", "certificate DER did not decode: " + e.message, e);
-  }
-  return schema.walk(CERTIFICATE, root, NS).result;
+// 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
+// tbs: a certificate has a Validity — a SEQUENCE of exactly two Time values — at
+// position [serial, signature, issuer, VALIDITY] after the optional [0] version.
+// A CSR's certificationRequestInfo has subjectPublicKeyInfo there (no Validity),
+// 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 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)
+  return !!validity && validity.tagClass === "universal" && validity.tagNumber === TAGS.SEQUENCE &&
+    !!validity.children && validity.children.length === 2 &&
+    validity.children.every(function (t) {
+      return t.tagClass === "universal" && (t.tagNumber === TAGS.UTC_TIME || t.tagNumber === TAGS.GENERALIZED_TIME);
+    });
 }
 
 module.exports = {
   parse:     parse,
   pemDecode: pemDecode,
   pemEncode: pemEncode,
+  matches:   matches,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "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:8ff5f15e-e999-4db6-bf14-09273902a9c2",
+  "serialNumber": "urn:uuid:a50e8ea1-a357-4e08-b473-56bcf5e2659f",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-04T22:46:29.855Z",
+    "timestamp": "2026-07-05T03:52:05.348Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.6",
+      "bom-ref": "@blamejs/pki@0.1.7",
       "type": "application",
       "name": "pki",
-      "version": "0.1.6",
+      "version": "0.1.7",
       "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.6",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.7",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.6",
+      "ref": "@blamejs/pki@0.1.7",
       "dependsOn": []
     }
   ]