@blamejs/pki 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -4,7 +4,30 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## v0.1.7 — 2026-07-05
+## v0.1.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.
 

package/README.md

@@ -193,9 +193,10 @@ is callable today; nothing below is a stub.
 | `pki.schema` | The schema family — `parse` detects which PKI format DER / PEM encodes and routes to the right parser, `all` enumerates the registered formats, and the engine + per-format members are grouped here |
 | `pki.schema.x509` | Parse DER / PEM certificates into structured, validated fields — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.crl` | Parse DER / PEM X.509 CRLs per RFC 5280 §5 — revoked serials with real-`Date` revocation times, named + partly-decoded extensions, fail-closed — `parse`, `pemDecode` |
+| `pki.schema.csr` | Parse DER / PEM PKCS#10 certification requests per RFC 2986 — subject DN, public key, requested attributes, signature, fail-closed — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.engine` | The declarative ASN.1 structure-schema engine every format parser composes — `walk` plus the schema combinators |
 | `pki.C` / `pki.constants` | Version-stable constants — functional scale helpers (`C.TIME.*`, `C.BYTES.*`), codec `LIMITS`, `version` |
-| `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError`, each carrying a stable `code` in `domain/reason` form |
+| `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError`, each carrying a stable `code` in `domain/reason` form |
 | `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>` |
 
 ### CLI
@@ -209,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/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

@@ -129,6 +129,10 @@ var CrlError = defineClass("CrlError", { withCause: true });
 // no registered format / does not decode). (code, message) shape like the rest.
 var SchemaError = defineClass("SchemaError", { withCause: true });
 
+// CsrError — a byte sequence that is not a well-formed PKCS#10 CertificationRequest
+// (RFC 2986).
+var CsrError = defineClass("CsrError", { withCause: true });
+
 module.exports = {
   PkiError:         PkiError,
   defineClass:      defineClass,
@@ -139,4 +143,5 @@ module.exports = {
   CertificateError: CertificateError,
   CrlError:         CrlError,
   SchemaError:      SchemaError,
+  CsrError:         CsrError,
 };

package/lib/oid.js

@@ -71,7 +71,7 @@ var FAMILIES = {
     sha384WithRSAEncryption: 12, sha512WithRSAEncryption: 13 } },
 
   // PKCS#9 attribute types.
-  pkcs9: { base: [1, 2, 840, 113549, 1, 9], of: { emailAddress: 1 } },
+  pkcs9: { base: [1, 2, 840, 113549, 1, 9], of: { emailAddress: 1, challengePassword: 7, extensionRequest: 14 } },
 
   // ANSI X9.62 EC public key, named curve, and ECDSA signatures.
   ansiX962: { base: [1, 2, 840, 10045], of: {

package/lib/schema-all.js

@@ -12,7 +12,8 @@
  * @intro
  *   The schema family: a declarative ASN.1 structure-schema engine and the
  *   per-format parsers built on it. Every format (X.509 certificates, CRLs,
- *   and — as they land — CMS / CSR / PKCS#8) is a member that COMPOSES the
+ *   PKCS#10 certification requests, and — as they land — CMS / PKCS#8) is a
+ *   member that COMPOSES the
  *   shared engine and the shared PKIX sub-schemas (AlgorithmIdentifier, Name,
  *   Extension), so a structural rule — bounds-checked positional reads,
  *   optional / tagged field ordering, SET-OF uniqueness, fail-closed typed
@@ -33,6 +34,7 @@ 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;
@@ -49,11 +51,21 @@ var ENTRY = { pemLabel: null, PemError: PemError, ErrorClass: SchemaError, prefi
 // logic. Order matters: the most specific detector wins, so a new member is
 // inserted ahead of any more-permissive one.
 var FORMATS = [
+  {
+    // CertificationRequest ::= SEQUENCE { certificationRequestInfo,
+    // signatureAlgorithm, signature } — the same outer 3-element shape,
+    // distinguished by a CertificationRequestInfo of EXACTLY four children
+    // ending in the IMPLICIT [0] attributes element. Checked first because that
+    // detector is the most specific and mutually exclusive with the others.
+    name: "csr",
+    module: csr,
+    detect: csr.matches,
+    parse: function (input) { return csr.parse(input); },
+  },
   {
     // CertificateList ::= SEQUENCE { tbsCertList, signatureAlgorithm,
     // signatureValue } — the same outer shape as a certificate, distinguished
     // by its tbsCertList (a bare Time at the certificate's Validity position).
-    // Checked first because its detector is the specific one.
     name: "crl",
     module: crl,
     detect: crl.matches,
@@ -81,7 +93,7 @@ var FORMATS = [
  * The names of every registered format, in detection order.
  *
  * @example
- *   pki.schema.all();  // → ["crl", "x509"]
+ *   pki.schema.all();  // → ["csr", "crl", "x509"]
  */
 function all() { return FORMATS.map(function (f) { return f.name; }); }
 
@@ -121,6 +133,7 @@ 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,
 };

package/lib/schema-crl.js

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

package/lib/schema-csr.js

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

package/lib/schema-engine.js

@@ -62,6 +62,13 @@ function _assertShape(schema, node, ctx) {
     if (!node.children) {
       _fail(ctx, schema.code, (schema.what || "value") + " must be a constructed value");
     }
+  } else if (mode === "implicit") {
+    // IMPLICIT [tag] SET/SEQUENCE OF: the context tag replaces the universal
+    // tag, so the node is a context-class constructed [tag] and its direct
+    // children are the items (no inner universal SET, no EXPLICIT unwrap).
+    if (node.tagClass !== "context" || node.tagNumber !== schema.implicitTag || !node.children) {
+      _fail(ctx, schema.code, (schema.what || "value") + " must be an IMPLICIT [" + schema.implicitTag + "] SET OF");
+    }
   } else {
     _fail(ctx, schema.code, "unknown assert mode " + JSON.stringify(mode));
   }
@@ -163,12 +170,20 @@ function seqOf(item, opts) {
 }
 function setOf(item, opts) {
   opts = opts || {};
-  return { kind: "repeat", item: item, assert: opts.assert || "set", code: opts.code, what: opts.what,
+  return { kind: "repeat", item: item, assert: opts.assert || "set", derSetOrder: true, code: opts.code, what: opts.what,
            min: opts.min, unique: opts.unique, dupCode: opts.dupCode, build: opts.build };
 }
 function setOfUnique(item, keyFn, opts) {
   return setOf(item, Object.assign({ unique: keyFn }, opts || {}));
 }
+// [tag] IMPLICIT SET OF item — the context tag REPLACES the universal SET tag,
+// so the node is a context-class constructed [tag] whose direct children are the
+// items (RFC 2986 §4.1 CSR attributes). No inner SET, no EXPLICIT unwrap.
+function implicitSetOf(tag, item, opts) {
+  opts = opts || {};
+  return { kind: "repeat", item: item, assert: "implicit", implicitTag: tag, derSetOrder: true, code: opts.code, what: opts.what,
+           min: opts.min, unique: opts.unique, dupCode: opts.dupCode, build: opts.build };
+}
 
 // ---- the walk engine -------------------------------------------------
 
@@ -246,6 +261,19 @@ function _walkRepeat(schema, node, ctx) {
   if (schema.min != null && kids.length < schema.min) {
     _fail(ctx, schema.code, (schema.what || "value") + " must contain at least " + schema.min + " element(s)");
   }
+  // DER (X.690 §11.6) — the components of a SET OF appear in ascending order, the
+  // encodings compared as octet strings. SEQUENCE OF is order-preserving and is
+  // exempt (no derSetOrder). Compare full TLV byte strings, the same canonical
+  // order build.set emits, so a decode round-trips a build. Equal-adjacent
+  // encodings are permitted here (semantic uniqueness is the `unique` option's
+  // job); only a descending pair is non-canonical.
+  if (schema.derSetOrder) {
+    for (var s = 1; s < kids.length; s++) {
+      if (Buffer.compare(kids[s - 1].bytes, kids[s].bytes) > 0) {
+        _fail(ctx, schema.code, (schema.what || "value") + " components must be in ascending DER order (X.690 §11.6)");
+      }
+    }
+  }
   var items = [];
   var seen = schema.unique ? new Set() : null;
   for (var i = 0; i < kids.length; i++) {
@@ -337,7 +365,7 @@ function _consumeTrailing(fld, kids, start, fields, ctx) {
 module.exports = {
   // structural
   seq: seq, field: field, optional: optional, explicit: explicit, trailing: trailing,
-  seqOf: seqOf, setOf: setOf, setOfUnique: setOfUnique, choice: choice,
+  seqOf: seqOf, setOf: setOf, setOfUnique: setOfUnique, implicitSetOf: implicitSetOf, choice: choice,
   // leaves
   oidLeaf: oidLeaf, integerLeaf: integerLeaf, boolean: boolean, octetString: octetString,
   bitString: bitString, any: any, decode: decode, time: time,

package/lib/schema-pkix.js

@@ -221,6 +221,83 @@ function extensions(ns) {
   });
 }
 
+// SubjectPublicKeyInfo ::= SEQUENCE { algorithm AlgorithmIdentifier,
+// subjectPublicKey BIT STRING } (RFC 5280 §4.1.2.7, RFC 2986 §4.1). Asserted as a
+// universal SEQUENCE — a context-tagged or SET-tagged constructed node carrying
+// two well-formed children is NOT a SubjectPublicKeyInfo. Shared by the
+// certificate and CSR parsers.
+function spki(ns) {
+  return schema.seq([
+    schema.field("algorithm", algorithmIdentifier(ns)),
+    schema.field("subjectPublicKey", schema.bitString()),
+  ], {
+    assert: "sequence", arity: { exact: 2 }, code: ns.prefix + "/bad-spki", what: "SubjectPublicKeyInfo",
+    build: function (m) {
+      return {
+        algorithm: m.fields.algorithm.value.result,
+        publicKey: { unusedBits: m.fields.subjectPublicKey.value.unusedBits, bytes: m.fields.subjectPublicKey.value.bytes },
+        bytes: m.node.bytes,
+      };
+    },
+  });
+}
+
+// Certificate, CertificateList, and CertificationRequest share one outer shape:
+// SEQUENCE { toBeSigned SEQUENCE, signatureAlgorithm, signatureValue }. This
+// returns the first element (the to-be-signed info) when `root` is that
+// SEQUENCE-of-exactly-3 whose first child is itself a constructed universal
+// SEQUENCE, or null otherwise. Every format's `matches` detector shares this
+// preamble, so the signed-envelope shape is recognized in one place and the three
+// detectors cannot drift on it (the CRL detector historically omitted the
+// tbs-is-universal check this recovers).
+function signedEnvelopeTbs(root) {
+  if (!root || root.tagClass !== "universal" || root.tagNumber !== asn1.TAGS.SEQUENCE) return null;
+  if (!root.children || root.children.length !== 3) return null;
+  var tbs = root.children[0];
+  if (!tbs.children || tbs.tagClass !== "universal" || tbs.tagNumber !== asn1.TAGS.SEQUENCE) return null;
+  return tbs;
+}
+
+// Every format's `parse` is the shared runParse bound to that format's identity
+// (PEM label, error class, error-code prefix, top-level schema). This returns the
+// bound parser so a format declares its configuration once and never re-writes the
+// coerce -> decode -> walk wrapper. `opts`: { pemLabel, PemError, ErrorClass,
+// prefix, what, topSchema, ns }.
+function makeParser(opts) {
+  return function (input) { return runParse(input, opts); };
+}
+
+// The X.509 SIGNED{ToBeSigned} macro (RFC 5280 §4.1.1.3): the outer
+// SEQUENCE { toBeSigned, signatureAlgorithm AlgorithmIdentifier,
+// signatureValue BIT STRING } shared by Certificate, CertificateList and
+// CertificationRequest. `tbsSchema` parses the first element; the SEQUENCE-of-3
+// shape, the arity, the signature extraction and the raw tbs / outer-signature
+// bytes (for the cert/CRL outer==inner agreement check) are owned here once, and
+// each format's `opts.build(envelope, ctx)` shapes its own object from the
+// envelope. A CSR's build simply omits the agreement check — its CRI has no inner
+// signature AlgorithmIdentifier — so the omission is structural, not a copy that
+// forgot a guard.
+function signedEnvelope(ns, tbsSchema, opts) {
+  return schema.seq([
+    schema.field("toBeSigned", tbsSchema),
+    schema.field("signatureAlgorithm", algorithmIdentifier(ns)),
+    schema.field("signatureValue", schema.bitString()),
+  ], {
+    assert: "sequence", arity: { exact: 3 }, code: opts.code, what: opts.what,
+    build: function (m, ctx) {
+      var tbsMatch = m.fields.toBeSigned.value;
+      var sigBits = m.fields.signatureValue.value;
+      return opts.build({
+        tbsMatch: tbsMatch,                                    // raw seq-match: .fields.* / .result / .node
+        tbsBytes: tbsMatch.node.bytes,                         // the exact signed region
+        outerSignatureAlgorithmBytes: m.fields.signatureAlgorithm.node.bytes,
+        signatureAlgorithm: m.fields.signatureAlgorithm.value.result,
+        signatureValue: { unusedBits: sigBits.unusedBits, bytes: sigBits.bytes },
+      }, ctx);
+    },
+  });
+}
+
 module.exports = {
   pemDecode: pemDecode,
   pemEncode: pemEncode,
@@ -229,6 +306,10 @@ module.exports = {
   runParse: runParse,
   DN_SHORT: DN_SHORT,
   algorithmIdentifier: algorithmIdentifier,
+  spki: spki,
+  makeParser: makeParser,
+  signedEnvelopeTbs: signedEnvelopeTbs,
+  signedEnvelope: signedEnvelope,
   attrValueToString: attrValueToString,
   attributeTypeAndValue: attributeTypeAndValue,
   relativeDistinguishedName: relativeDistinguishedName,

package/lib/schema-x509.js

@@ -95,20 +95,8 @@ var VALIDITY = schema.seq([
   build: function (m) { return { notBefore: m.fields.notBefore.value, notAfter: m.fields.notAfter.value }; },
 });
 
-// SubjectPublicKeyInfo ::= SEQUENCE { algorithm AlgorithmIdentifier, subjectPublicKey BIT STRING }.
-var SPKI = schema.seq([
-  schema.field("algorithm", ALGORITHM_IDENTIFIER),
-  schema.field("subjectPublicKey", schema.bitString()),
-], {
-  assert: "constructed", arity: { exact: 2 }, code: "x509/bad-spki", what: "SubjectPublicKeyInfo",
-  build: function (m) {
-    return {
-      algorithm: m.fields.algorithm.value.result, // algorithm field = ALGORITHM_IDENTIFIER seq-match; .value = its build
-      publicKey: { unusedBits: m.fields.subjectPublicKey.value.unusedBits, bytes: m.fields.subjectPublicKey.value.bytes },
-      bytes: m.node.bytes,
-    };
-  },
-});
+// SubjectPublicKeyInfo — the shared pkix.spki factory under the x509 NS.
+var SPKI = pkix.spki(NS);
 
 var EXTENSIONS = pkix.extensions(NS);
 
@@ -151,17 +139,17 @@ var CERTIFICATE_TBS = schema.seq([
 // agreement, §4.1.2.4 non-empty issuer, §4.1.2.9 extensions-only-in-v3) after the
 // structural walk, then assembles the public parse result. Raw-byte accessors
 // (serialNumberHex, tbsBytes, sig-alg agreement) read off the match-tree nodes.
-var CERTIFICATE = schema.seq([
-  schema.field("tbsCertificate", CERTIFICATE_TBS),
-  schema.field("signatureAlgorithm", ALGORITHM_IDENTIFIER),
-  schema.field("signatureValue", schema.bitString()),
-], {
-  assert: "sequence", arity: { exact: 3 }, code: "x509/not-a-certificate", what: "Certificate",
-  build: function (m, ctx) {
-    var tbs = m.fields.tbsCertificate.value; // CERTIFICATE_TBS seq-match (no build)
+// Certificate ::= SEQUENCE { tbsCertificate, signatureAlgorithm, signatureValue }
+// — the shared SIGNED envelope. The certificate-specific invariants (outer==inner
+// signatureAlgorithm agreement, non-empty issuer, v3-only extensions) live in the
+// build; the envelope owns the SEQUENCE-of-3 shape and signature extraction.
+var CERTIFICATE = pkix.signedEnvelope(NS, CERTIFICATE_TBS, {
+  code: "x509/not-a-certificate", what: "Certificate",
+  build: function (e, ctx) {
+    var tbs = e.tbsMatch; // CERTIFICATE_TBS seq-match (no build)
 
     // RFC 5280 §4.1.1.2 — outer signatureAlgorithm MUST equal tbsCertificate.signature.
-    if (!m.fields.signatureAlgorithm.node.bytes.equals(tbs.fields.signature.node.bytes)) {
+    if (!e.outerSignatureAlgorithmBytes.equals(tbs.fields.signature.node.bytes)) {
       throw ctx.E("x509/bad-signature-algorithm", "signatureAlgorithm must match tbsCertificate.signature (RFC 5280 §4.1.1.2)");
     }
 
@@ -180,20 +168,19 @@ var CERTIFICATE = schema.seq([
     }
 
     var serialNode = tbs.fields.serialNumber.node;
-    var sigBits = m.fields.signatureValue.value; // { unusedBits, bytes }
     return {
       version:               version,
       serialNumber:          tbs.fields.serialNumber.value,
       serialNumberHex:       serialNode.content.toString("hex"),
-      signatureAlgorithm:    m.fields.signatureAlgorithm.value.result,
+      signatureAlgorithm:    e.signatureAlgorithm,
       tbsSignatureAlgorithm: tbs.fields.signature.value.result,
       issuer:                issuer,
       subject:               tbs.fields.subject.value.result,
       validity:              tbs.fields.validity.value.result,
       subjectPublicKeyInfo:  tbs.fields.subjectPublicKeyInfo.value.result,
       extensions:            hasExtensions ? extField.value.result : [],
-      tbsBytes:              tbs.node.bytes,
-      signatureValue:        { unusedBits: sigBits.unusedBits, bytes: sigBits.bytes },
+      tbsBytes:              e.tbsBytes,
+      signatureValue:        e.signatureValue,
     };
   },
 });
@@ -226,9 +213,7 @@ var CERTIFICATE = schema.seq([
  *   cert.validity.notAfter;          // Date
  *   cert.signatureAlgorithm.name;    // "sha256WithRSAEncryption"
  */
-function parse(input) {
-  return pkix.runParse(input, { pemLabel: "CERTIFICATE", PemError: PemError, ErrorClass: CertificateError, prefix: "x509", what: "certificate", topSchema: CERTIFICATE, ns: NS });
-}
+var parse = pkix.makeParser({ pemLabel: "CERTIFICATE", PemError: PemError, ErrorClass: CertificateError, prefix: "x509", what: "certificate", topSchema: CERTIFICATE, ns: NS });
 
 // matches(root): does the decoded DER look like a Certificate? A CSR and a CRL
 // share the outer SEQUENCE-of-3 envelope, so the discriminator is inside the
@@ -238,10 +223,8 @@ function parse(input) {
 // and a CRL leads with a bare Time; neither matches. Used by the orchestrator.
 function matches(root) {
   var TAGS = asn1.TAGS;
-  if (!root || root.tagClass !== "universal" || root.tagNumber !== TAGS.SEQUENCE) return false;
-  if (!root.children || root.children.length !== 3) return false;
-  var tbs = root.children[0];
-  if (!tbs.children || tbs.tagClass !== "universal" || tbs.tagNumber !== TAGS.SEQUENCE) return false;
+  var tbs = pkix.signedEnvelopeTbs(root);
+  if (!tbs) return false;
   var kids = tbs.children;
   var i = (kids[0] && kids[0].tagClass === "context" && kids[0].tagNumber === 0) ? 1 : 0; // optional [0] version
   var validity = kids[i + 3]; // serial(i), signature(i+1), issuer(i+2), validity(i+3)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:a50e8ea1-a357-4e08-b473-56bcf5e2659f",
+  "serialNumber": "urn:uuid:64eeff87-502c-43f1-a398-5fbe7fc7a614",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-05T03:52:05.348Z",
+    "timestamp": "2026-07-05T06:26:48.420Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.7",
+      "bom-ref": "@blamejs/pki@0.1.8",
       "type": "application",
       "name": "pki",
-      "version": "0.1.7",
+      "version": "0.1.8",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.1.7",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.8",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.7",
+      "ref": "@blamejs/pki@0.1.8",
       "dependsOn": []
     }
   ]