@blamejs/pki 0.1.6 → 0.1.8

package/lib/schema-crl.js

@@ -0,0 +1,251 @@
+// 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)
+      // 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
+      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 }
+// — 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 (!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.
+    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: e.tbsBytes,
+      signatureAlgorithm: e.signatureAlgorithm,
+      signatureValue: e.signatureValue,
+    };
+  },
+});
+
+/**
+ * @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…"
+ */
+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
+ * @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) {
+  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
+  // 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/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/{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
  *
@@ -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));
   }
@@ -109,14 +116,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 };
 }
@@ -157,22 +170,30 @@ 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 -------------------------------------------------
 
 /**
- * @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 +209,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 });
@@ -240,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++) {
@@ -331,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,