@blamejs/pki 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -4,6 +4,32 @@ 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.6 — 2026-07-04
+
+A declarative ASN.1 structure-schema engine; the X.509 parser is rebuilt on it.
+
+### Added
+
+- pki.asn1.schema — a declarative ASN.1 structure-schema engine. A schema is plain data built from combinators (seq / field / optional / explicit / trailing / seqOf / setOf / setOfUnique / choice, plus the value leaves oidLeaf / integerLeaf / boolean / octetString / bitString / any / decode / time); pki.asn1.schema.walk(schema, node, ctx) interprets it against a decoded DER node under an error namespace, enforcing the structural rules — shape assertion, bounds-checked positional reads, optional / context-tagged fields in strictly increasing tag order, SET-OF uniqueness, and fail-closed typed errors — in one place. This is the shared base the certificate parser is built on and the forthcoming CRL / CMS parsers compose, so a new format is declared as data rather than hand-written.
+
+### Changed
+
+- pki.x509.parse is now built on the schema engine: the Certificate, tbsCertificate, and every sub-structure (AlgorithmIdentifier, Name, Validity, SubjectPublicKeyInfo, Extensions) are declared as schemas and walked. Every valid certificate parses to the same result as before, and every malformed certificate is still rejected — the full existing test suite passes unchanged. The certificate's structural rules (positional bounds, the trailing-field grammar, extension uniqueness, the signature-algorithm agreement) now live in one auditable place instead of a hand-written decoder, and the format is structurally incapable of the positional-read and duplicate-field bug classes. The parser now validates the full certificate structure before applying cross-field checks, so a certificate carrying more than one defect at once may be rejected with a different (still fail-closed) error than a prior release reported.
+
+## v0.1.5 — 2026-07-04
+
+Container healthcheck honors WIKI_PORT; release-tooling supply-chain hardening.
+
+### Fixed
+
+- The example wiki container's HEALTHCHECK now probes the port from WIKI_PORT (defaulting to 3009) rather than a hardcoded 3009, so overriding WIKI_PORT at runtime no longer leaves the container reporting unhealthy while the server is serving on the configured port.
+
+### Security
+
+- The CI secret-scan gate now fetches the gitleaks binary over authenticated requests and verifies it against the checksums file published in the same release before executing it, so a corrupted or tampered download fails closed instead of running as the gate. Tracking the latest release keeps detection rules current.
+- The release-container workflow validates that the base image resolved to a well-formed sha256 digest before building against it, so a failed resolution can no longer silently produce an unpinned base — the scanned image is always the published one.
+- The workflow-security audit re-runs when its own configuration file changes, so an edit that would suppress a finding is itself audited.
+
 ## v0.1.4 — 2026-07-04
 
 The ASN.1 codec's universal-type metadata moves to a single descriptor registry.

package/index.js

@@ -25,6 +25,7 @@
 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");
@@ -35,7 +36,9 @@ module.exports = {
   C:         constants,
   constants: constants,
   errors:    errors,
-  asn1:      asn1,
+  // `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 }),
   oid:       oid,
   x509:      x509,
   // A ready W3C Crypto instance (globalThis.crypto shape) + the classes

package/lib/asn1-schema.js

@@ -0,0 +1,340 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.asn1.schema
+ * @nav        ASN.1
+ * @title      Schema engine
+ * @order      60
+ *
+ * @intro
+ *   L2 of the ASN.1 stack — a declarative structure-schema engine. A schema is
+ *   plain data (`{kind, ...}` descriptors built by the combinators here) and
+ *   `walk(schema, node, ctx)` interprets it against a decoded DER node. The
+ *   engine is where every cross-cutting structural rule lives ONCE: the shape
+ *   assertion (SEQUENCE / SET / bare-constructed), bounds-checked positional
+ *   reads, optional and context-tagged fields in strictly-increasing tag order,
+ *   SET-OF uniqueness, and fail-closed typed errors. A format module declares a
+ *   schema and calls `walk` under an error namespace `ctx = { E, prefix, oid }`;
+ *   it never hand-rolls `children[idx++]`, so the positional-read and
+ *   duplicate-field bug classes are structurally retired. This is the shared
+ *   base the certificate parser (and, later, CRL / CMS) composes.
+ *
+ * @card
+ *   Declarative ASN.1 structure schemas + one walk engine — the shared base the
+ *   certificate / CRL / CMS parsers compose instead of hand-writing.
+ */
+
+var asn1 = require("./asn1-der.js");
+
+var TAGS = asn1.TAGS;
+
+// ---- context ---------------------------------------------------------
+// A walk receives ctx = { E, prefix, oid } where E(code, message) constructs
+// (does not throw) the format's typed error, prefix names the error family
+// ("x509", "crl", ...) and oid is the OID registry (for name resolution in a
+// build fn). _fail throws so a schema node reads as a single expression.
+
+function _fail(ctx, code, message) {
+  throw ctx.E(code, message);
+}
+
+// ---- shape assertions ------------------------------------------------
+// A schema's `assert` mode is a real behaviour-preservation control: some
+// hand-written guards checked the universal SEQUENCE tag (algorithmIdentifier,
+// Name), others checked only that the node had children (Validity, SPKI, the
+// tbs body, an AttributeTypeAndValue). Collapsing them to one "is a SEQUENCE"
+// check would silently change behaviour on SET-wrapped input, so each is kept.
+
+function _assertShape(schema, node, ctx) {
+  var mode = schema.assert || "sequence";
+  if (mode === "sequence") {
+    if (node.tagClass !== "universal" || node.tagNumber !== TAGS.SEQUENCE || !node.children) {
+      _fail(ctx, schema.code, (schema.what || "value") + " must be a SEQUENCE");
+    }
+  } else if (mode === "set") {
+    if (node.tagClass !== "universal" || node.tagNumber !== TAGS.SET || !node.children) {
+      _fail(ctx, schema.code, (schema.what || "value") + " must be a SET");
+    }
+  } else if (mode === "constructed") {
+    // Bare constructed: the historical guards only required decoded children,
+    // never a specific universal tag.
+    if (!node.children) {
+      _fail(ctx, schema.code, (schema.what || "value") + " must be a constructed value");
+    }
+  } else {
+    _fail(ctx, schema.code, "unknown assert mode " + JSON.stringify(mode));
+  }
+  return node.children;
+}
+
+function _assertArity(schema, kids, ctx) {
+  var a = schema.arity;
+  if (!a) return;
+  if (a.exact != null && kids.length !== a.exact) {
+    _fail(ctx, schema.code, (schema.what || "value") + " must have exactly " + a.exact + " elements");
+  }
+  if (a.min != null && kids.length < a.min) {
+    _fail(ctx, schema.code, (schema.what || "value") + " must have at least " + a.min + " elements");
+  }
+}
+
+// ---- leaf / value combinators ---------------------------------------
+// Leaves read a primitive off a node via the L1 codec; the codec's own
+// asn1/* errors propagate unchanged (the frozen oracle expects those codes on
+// the OID / INTEGER / string reads). `decode(fn)` hands the whole node to fn,
+// which owns its try/catch and code mapping. `any()` yields the node itself.
+
+function oidLeaf()        { return { kind: "leaf", read: asn1.read.oid }; }
+function integerLeaf()    { return { kind: "leaf", read: asn1.read.integer }; }
+function boolean()        { return { kind: "leaf", read: asn1.read.boolean }; }
+function octetString()    { return { kind: "leaf", read: asn1.read.octetString }; }
+function bitString()      { return { kind: "leaf", read: function (n) { var b = asn1.read.bitString(n); return { unusedBits: b.unusedBits, bytes: b.bytes }; } }; }
+function any()            { return { kind: "any" }; }
+function decode(fn)       { return { kind: "decode", fn: fn }; }
+
+// time(ns): a UTCTime / GeneralizedTime value, asserting the tag before the
+// codec reads it (mirrors _parseValidityTime's x509/bad-time guard).
+function time(ns) {
+  return decode(function (n, ctx) {
+    if (n.tagClass !== "universal" || (n.tagNumber !== TAGS.UTC_TIME && n.tagNumber !== TAGS.GENERALIZED_TIME)) {
+      _fail(ctx, ns.prefix + "/bad-time", "time must be UTCTime or GeneralizedTime");
+    }
+    return asn1.read.time(n);
+  });
+}
+
+// ---- field descriptors (members of a seq) ---------------------------
+
+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).
+  var match = opts.whenAny
+    ? function () { return true; }
+    : 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 };
+}
+// trailing: the [minTag..maxTag] optional context fields, each at most once in
+// strictly-increasing tag order (the tbs issuerUniqueID[1]/subjectUniqueID[2]/
+// extensions[3] block). members: [{ tag, name, schema, explicit? }].
+function trailing(members, opts) {
+  opts = opts || {};
+  return { fkind: "trailing", members: members, minTag: opts.minTag, maxTag: opts.maxTag,
+           unexpectedCode: opts.unexpectedCode, orderCode: opts.orderCode };
+}
+
+// ---- structural combinators -----------------------------------------
+
+function seq(fields, opts) {
+  opts = opts || {};
+  return { kind: "seq", fields: fields, assert: opts.assert || "sequence", arity: opts.arity,
+           code: opts.code, what: opts.what, build: opts.build, checks: opts.checks || [] };
+}
+
+// A NON-optional EXPLICIT context wrapper (CMS ContentInfo; the tbs [3] uses it
+// inside `trailing`). Asserts context class + tag, constructed, >=1 child, then
+// walks the inner schema on children[0].
+function explicit(tag, schema, opts) {
+  opts = opts || {};
+  return { kind: "explicit", tag: tag, schema: schema, emptyCode: opts.emptyCode, code: opts.code, what: opts.what };
+}
+
+function choice(alts, opts) {
+  opts = opts || {};
+  return { kind: "choice", alts: alts, code: opts.code, what: opts.what };
+}
+
+function seqOf(item, opts) {
+  opts = opts || {};
+  return { kind: "repeat", item: item, assert: opts.assert || "sequence", code: opts.code, what: opts.what,
+           min: opts.min, unique: opts.unique, dupCode: opts.dupCode, build: opts.build };
+}
+function setOf(item, opts) {
+  opts = opts || {};
+  return { kind: "repeat", item: item, assert: opts.assert || "set", 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 || {}));
+}
+
+// ---- the walk engine -------------------------------------------------
+
+/**
+ * @primitive  pki.asn1.schema.walk
+ * @signature  pki.asn1.schema.walk(schema, node, ctx) -> value
+ * @since      0.1.6
+ * @status     experimental
+ * @spec       X.690, X.680
+ * @related    pki.asn1.decode, pki.x509.parse
+ *
+ * Interpret a declarative schema against a decoded DER node, enforcing the
+ * schema's structural rules (shape assertion, arity, optional / context-tagged
+ * fields in increasing tag order, SET-OF uniqueness) and returning the built
+ * value — or the match tree (`{ node, fields | items }`, with the build output
+ * on `.result`) for a structure with no build fn. `ctx = { E, prefix, oid }`
+ * supplies the typed-error constructor, the error-code family prefix, and the
+ * OID registry a build fn resolves names through.
+ *
+ * The schema is assembled from the combinators this module exports — structural
+ * (`seq` / `field` / `optional` / `explicit` / `trailing` / `seqOf` / `setOf` /
+ * `setOfUnique` / `choice`) and value (`oidLeaf` / `integerLeaf` / `boolean` /
+ * `octetString` / `bitString` / `any` / `decode` / `time`).
+ *
+ * @example
+ *   var S = pki.asn1.schema;
+ *   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 });
+ */
+function walk(schema, node, ctx) {
+  switch (schema.kind) {
+    case "leaf":   return schema.read(node);
+    case "any":    return node;
+    case "decode": return schema.fn(node, ctx);
+    case "seq":    return _walkSeq(schema, node, ctx);
+    case "explicit": return _walkExplicit(schema, node, ctx);
+    case "repeat": return _walkRepeat(schema, node, ctx);
+    case "choice": return _walkChoice(schema, node, ctx);
+    default: _fail(ctx, (ctx.prefix || "schema") + "/bad-schema", "unknown schema kind " + JSON.stringify(schema.kind));
+  }
+  return undefined;
+}
+
+// An EXPLICIT [tag] wrapper carries EXACTLY ONE inner value; 0 children is
+// empty and 2+ would silently drop all but the first (the same drop-extra
+// fail-open the seq guard closes). Assert exactly one, return it.
+function _explicitInner(node, tag, ctx, code) {
+  if (!node.children || node.children.length !== 1) {
+    _fail(ctx, code, "EXPLICIT [" + tag + "] must wrap exactly one value");
+  }
+  return node.children[0];
+}
+
+function _walkExplicit(schema, node, ctx) {
+  if (node.tagClass !== "context" || node.tagNumber !== schema.tag) {
+    _fail(ctx, schema.emptyCode || schema.code, "expected an EXPLICIT [" + schema.tag + "] wrapper");
+  }
+  return walk(schema.schema, _explicitInner(node, schema.tag, ctx, schema.emptyCode || schema.code), ctx);
+}
+
+function _walkChoice(schema, node, ctx) {
+  for (var i = 0; i < schema.alts.length; i++) {
+    var w = schema.alts[i].when;
+    if (node.tagClass === w.tagClass && node.tagNumber === w.tagNumber) {
+      return walk(schema.alts[i].schema, node, ctx);
+    }
+  }
+  _fail(ctx, schema.code, "no CHOICE alternative matched " + node.tagClass + "/" + node.tagNumber);
+  return undefined;
+}
+
+function _walkRepeat(schema, node, ctx) {
+  var kids = _assertShape(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)");
+  }
+  var items = [];
+  var seen = schema.unique ? new Set() : null;
+  for (var i = 0; i < kids.length; i++) {
+    // The item wrapper is the SAME shape unique() and build() see: { node,
+    // value: <walk result> }. keyFn reads off item.value just like build does.
+    var item = { node: kids[i], value: walk(schema.item, kids[i], ctx) };
+    if (seen) {
+      var key = schema.unique(item);
+      if (seen.has(key)) _fail(ctx, schema.dupCode || schema.code, "duplicate element " + key);
+      seen.add(key);
+    }
+    items.push(item);
+  }
+  var match = { kind: "repeat", node: node, items: items };
+  if (schema.build) match.result = schema.build(match, ctx);
+  return match;
+}
+
+function _walkSeq(schema, node, ctx) {
+  var kids = _assertShape(schema, node, ctx);
+  _assertArity(schema, kids, ctx);
+
+  var fields = {};
+  var idx = 0;
+  for (var f = 0; f < schema.fields.length; f++) {
+    var fld = schema.fields[f];
+    if (fld.fkind === "required") {
+      if (idx >= kids.length) _fail(ctx, schema.code, "missing required field " + JSON.stringify(fld.name));
+      var child = kids[idx++];
+      fields[fld.name] = { node: child, value: walk(fld.schema, child, ctx) };
+    } else if (fld.fkind === "optional") {
+      var next = idx < kids.length ? kids[idx] : null;
+      if (next && fld.match(next)) {
+        idx++;
+        var inner = next;
+        if (fld.explicit) {
+          inner = _explicitInner(next, fld.tag, ctx, fld.emptyCode || schema.code);
+        }
+        fields[fld.name] = { node: next, present: true, value: walk(fld.schema, inner, ctx) };
+      } else {
+        fields[fld.name] = { present: false, value: fld.hasDefault ? fld.def : undefined };
+      }
+    } else if (fld.fkind === "trailing") {
+      _consumeTrailing(fld, kids, idx, fields, ctx);
+      idx = kids.length;
+    }
+  }
+
+  // Every child must be consumed by a field. A leftover element (no trailing
+  // field ran to absorb it) is malformed — dropping it silently would let a
+  // closed sequence of optional fields accept a duplicate/extra element.
+  if (idx < kids.length) {
+    _fail(ctx, schema.code, (schema.what || "value") + " has an unexpected element after its last field");
+  }
+
+  var match = { kind: "seq", node: node, fields: fields };
+  for (var c = 0; c < schema.checks.length; c++) schema.checks[c](match, ctx);
+  if (schema.build) match.result = schema.build(match, ctx);
+  return match;
+}
+
+function _consumeTrailing(fld, kids, start, fields, ctx) {
+  var byTag = {};
+  for (var m = 0; m < fld.members.length; m++) byTag[fld.members[m].tag] = fld.members[m];
+  // The monotonic-order sentinel must start below the lowest accepted tag.
+  // Context tag numbers are non-negative, so -1 is below any member tag when
+  // minTag is absent — otherwise a trailing block whose first member is [0]
+  // would reject that field (0 <= last==0) as repeated/out-of-order.
+  var last = fld.minTag != null ? fld.minTag - 1 : -1;
+  for (var i = start; i < kids.length; i++) {
+    var t = kids[i];
+    if (t.tagClass !== "context" || (fld.minTag != null && t.tagNumber < fld.minTag) || (fld.maxTag != null && t.tagNumber > fld.maxTag) || !byTag[t.tagNumber]) {
+      _fail(ctx, fld.unexpectedCode, "unexpected trailing field [" + (t.tagClass === "context" ? t.tagNumber : t.tagClass) + "]");
+    }
+    if (t.tagNumber <= last) _fail(ctx, fld.orderCode, "trailing field [" + t.tagNumber + "] is repeated or out of order");
+    last = t.tagNumber;
+    var member = byTag[t.tagNumber];
+    var inner = t;
+    if (member.explicit) {
+      inner = _explicitInner(t, t.tagNumber, ctx, member.emptyCode);
+    }
+    fields[member.name] = { node: t, present: true, value: walk(member.schema, inner, ctx) };
+  }
+  for (var n = 0; n < fld.members.length; n++) {
+    if (!fields[fld.members[n].name]) fields[fld.members[n].name] = { present: false, value: undefined };
+  }
+}
+
+module.exports = {
+  // structural
+  seq: seq, field: field, optional: optional, explicit: explicit, trailing: trailing,
+  seqOf: seqOf, setOf: setOf, setOfUnique: setOfUnique, choice: choice,
+  // leaves
+  oidLeaf: oidLeaf, integerLeaf: integerLeaf, boolean: boolean, octetString: octetString,
+  bitString: bitString, any: any, decode: decode, time: time,
+  // engine
+  walk: walk,
+};

package/lib/x509.js

@@ -31,14 +31,13 @@
 
 var constants = require("./constants");
 var asn1 = require("./asn1-der");
+var schema = require("./asn1-schema");
 var oid = require("./oid");
 var frameworkError = require("./framework-error");
 
 var CertificateError = frameworkError.CertificateError;
 var PemError = frameworkError.PemError;
 
-var TAGS = asn1.TAGS;
-
 // Distinguished-name attribute short labels (RFC 4514 §3 + common use).
 var DN_SHORT = {
   commonName:             "CN",
@@ -109,126 +108,236 @@ function pemEncode(der, label) {
 
 // ---- helpers ---------------------------------------------------------
 
-function _algId(node) {
-  if (node.tagClass !== "universal" || node.tagNumber !== TAGS.SEQUENCE || !node.children.length) {
-    throw new CertificateError("x509/bad-algorithm-identifier", "AlgorithmIdentifier must be a non-empty SEQUENCE");
-  }
-  var dotted = asn1.read.oid(node.children[0]);
-  return {
-    oid: dotted,
-    name: oid.name(dotted) || null,
-    parameters: node.children.length > 1 ? node.children[1].bytes : null,
-  };
+// 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).
+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; }
 
-function _attrValueToString(node) {
-  try { return asn1.read.string(node); }
-  catch (e) {
-    // A malformed KNOWN string type (invalid UTF-8, a non-IA5 byte, a
-    // PrintableString character outside its set, ...) is a malformed
-    // certificate and must fail closed — do NOT hex-encode it away, or the
-    // decoder's strict string validation is silently bypassed on the DN path.
-    // Those surface as asn1/bad-* content errors; raise a CertificateError so
-    // parse fails closed on the documented x509/* contract.
-    //
-    // A value that simply is not a decodable primitive string is NOT malformed
-    // and must stay representable: an ANY-typed non-string tag
-    // (asn1/expected-string) or a constructed universal type such as a SEQUENCE
-    // (asn1/expected-primitive). Per RFC 4514 §2.4 it is rendered as "#" plus
-    // the hex of its FULL DER encoding (tag + length + content — node.bytes),
-    // so a constructed value round-trips intact rather than being dropped or
-    // rejecting the whole certificate.
-    if (!e || (e.code !== "asn1/expected-string" && e.code !== "asn1/expected-primitive")) {
-      throw new CertificateError("x509/bad-atv", "malformed string in attribute value: " + ((e && e.message) || String(e)));
+// 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");
     }
-    return "#" + node.bytes.toString("hex");
-  }
+  });
 }
 
 function _escapeDnValue(v) {
   return v.replace(/([,+"\\<>;])/g, "\\$1");
 }
 
-function _parseName(node) {
-  if (node.tagClass !== "universal" || node.tagNumber !== TAGS.SEQUENCE) {
-    throw new CertificateError("x509/bad-name", "Name must be an RDNSequence (SEQUENCE)");
-  }
-  var rdns = [];
-  var parts = [];
-  for (var i = 0; i < node.children.length; i++) {
-    var rdn = node.children[i];
-    if (rdn.tagClass !== "universal" || rdn.tagNumber !== TAGS.SET) {
-      throw new CertificateError("x509/bad-rdn", "RelativeDistinguishedName must be a SET");
-    }
-    var atvs = [];
-    var atvParts = [];
-    for (var j = 0; j < rdn.children.length; j++) {
-      var atv = rdn.children[j];
-      if (!atv.children || atv.children.length < 2) {
-        throw new CertificateError("x509/bad-atv", "AttributeTypeAndValue must be a SEQUENCE of {type, value}");
-      }
-      var typeOid = asn1.read.oid(atv.children[0]);
-      var typeName = oid.name(typeOid);
-      var value = _attrValueToString(atv.children[1]);
-      atvs.push({ type: typeOid, name: typeName || null, value: value });
-      var label = (typeName && DN_SHORT[typeName]) || typeName || typeOid;
-      atvParts.push(label + "=" + _escapeDnValue(value));
-    }
-    rdns.push(atvs);
-    parts.push(atvParts.join("+"));
-  }
-  return { rdns: rdns, dn: parts.join(", ") };
+// 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 _parseValidityTime(node) {
-  if (node.tagClass !== "universal" || (node.tagNumber !== TAGS.UTC_TIME && node.tagNumber !== TAGS.GENERALIZED_TIME)) {
-    throw new CertificateError("x509/bad-time", "Validity time must be UTCTime or GeneralizedTime");
-  }
-  return asn1.read.time(node);
+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 _parseExtensions(seqNode) {
-  // RFC 5280 §4.1.2.9 — Extensions ::= SEQUENCE SIZE (1..MAX) OF Extension.
-  // The wrapped value must be a SEQUENCE (not a primitive, which would read
-  // seqNode.children as null and throw a raw TypeError) and must carry at
-  // least one extension.
-  if (seqNode.tagClass !== "universal" || seqNode.tagNumber !== TAGS.SEQUENCE || !seqNode.children) {
-    throw new CertificateError("x509/bad-extensions", "extensions [3] must wrap a SEQUENCE");
-  }
-  if (seqNode.children.length === 0) {
-    throw new CertificateError("x509/bad-extensions", "extensions SEQUENCE must contain at least one extension");
-  }
-  var out = [];
-  var seen = new Set();
-  for (var i = 0; i < seqNode.children.length; i++) {
-    var ext = seqNode.children[i];
+function _parseName(node) { return schema.walk(NAME, node, NS).result; }
+
+// Validity ::= SEQUENCE { notBefore Time, notAfter Time }. The historical guard
+// checked only children.length===2 (not the SEQUENCE tag) -> assert "constructed".
+var VALIDITY = schema.seq([
+  schema.field("notBefore", schema.time(NS)),
+  schema.field("notAfter", schema.time(NS)),
+], {
+  assert: "constructed", arity: { exact: 2 }, code: "x509/bad-validity", what: "Validity",
+  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,
+    };
+  },
+});
+
+// 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 new CertificateError("x509/bad-extension", "Extension must be a SEQUENCE");
+      throw ns.E(ns.prefix + "/bad-extension", "Extension must be a SEQUENCE");
     }
     var extnID = asn1.read.oid(ext.children[0]);
-    // RFC 5280 §4.2 — a certificate MUST NOT include more than one
-    // instance of a particular extension.
-    if (seen.has(extnID)) {
-      throw new CertificateError("x509/duplicate-extension", "certificate repeats extension " + extnID);
+    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; }
+
+// 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-
+// encoded v1 (DER forbids encoding the DEFAULT).
+function readVersion(ns) {
+  return schema.decode(function (n) {
+    var v = asn1.read.integer(n);
+    if (v === 0n) throw ns.E(ns.prefix + "/bad-version", "DER forbids explicitly encoding the default version v1");
+    if (v === 1n) return 2;
+    if (v === 2n) return 3;
+    throw ns.E(ns.prefix + "/bad-version", "unsupported certificate version " + v.toString());
+  });
+}
+
+// TBSCertificate ::= SEQUENCE { version [0] EXPLICIT DEFAULT v1, serialNumber
+// INTEGER, signature AlgorithmIdentifier, issuer Name, validity Validity,
+// subject Name, subjectPublicKeyInfo SubjectPublicKeyInfo, issuerUniqueID [1]
+// IMPLICIT OPTIONAL, subjectUniqueID [2] IMPLICIT OPTIONAL, extensions [3]
+// EXPLICIT OPTIONAL }. The trailing fields are at-most-once, in increasing tag
+// order (the engine enforces it); only extensions are surfaced.
+var CERTIFICATE_TBS = schema.seq([
+  schema.optional("version", readVersion(NS), { tag: 0, explicit: true, emptyCode: "x509/bad-version", default: 1 }),
+  schema.field("serialNumber", schema.integerLeaf()),
+  schema.field("signature", ALGORITHM_IDENTIFIER),
+  schema.field("issuer", NAME),
+  schema.field("validity", VALIDITY),
+  schema.field("subject", NAME),
+  schema.field("subjectPublicKeyInfo", SPKI),
+  schema.trailing([
+    { tag: 1, name: "issuerUniqueID", schema: schema.any() },
+    { tag: 2, name: "subjectUniqueID", schema: schema.any() },
+    { tag: 3, name: "extensions", schema: EXTENSIONS, explicit: true, emptyCode: "x509/bad-extensions" },
+  ], { minTag: 1, maxTag: 3, unexpectedCode: "x509/bad-tbs", orderCode: "x509/bad-tbs" }),
+], { assert: "constructed", code: "x509/bad-tbs", what: "tbsCertificate" });
+
+// Certificate ::= SEQUENCE { tbsCertificate, signatureAlgorithm, signatureValue
+// BIT STRING }. The build runs the RFC 5280 cross-field checks (§4.1.1.2 sig-alg
+// 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)
+
+    // RFC 5280 §4.1.1.2 — outer signatureAlgorithm MUST equal tbsCertificate.signature.
+    if (!m.fields.signatureAlgorithm.node.bytes.equals(tbs.fields.signature.node.bytes)) {
+      throw ctx.E("x509/bad-signature-algorithm", "signatureAlgorithm must match tbsCertificate.signature (RFC 5280 §4.1.1.2)");
     }
-    seen.add(extnID);
-    var critical = false;
-    var valueNode;
-    if (ext.children.length === 3) {
-      critical = asn1.read.boolean(ext.children[1]);
-      valueNode = ext.children[2];
-    } else {
-      valueNode = ext.children[1];
+
+    var version = tbs.fields.version.value; // 1 (default) | 2 | 3
+    var issuer = tbs.fields.issuer.value.result;
+    // RFC 5280 §4.1.2.4 — issuer MUST be non-empty (an empty subject is permitted, §4.1.2.6).
+    if (!issuer.rdns.length) {
+      throw ctx.E("x509/bad-issuer", "issuer must be a non-empty distinguished name");
     }
-    out.push({
-      oid:      extnID,
-      name:     oid.name(extnID) || null,
-      critical: critical,
-      value:    asn1.read.octetString(valueNode),
-    });
-  }
-  return out;
-}
+
+    var extField = tbs.fields.extensions;
+    var hasExtensions = !!(extField && extField.present);
+    // RFC 5280 §4.1.2.9 — extensions appear only in a v3 certificate.
+    if (hasExtensions && version !== 3) {
+      throw ctx.E("x509/bad-version", "extensions are only permitted in a v3 certificate");
+    }
+
+    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,
+      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 },
+    };
+  },
+});
 
 // ---- parse -----------------------------------------------------------
 
@@ -274,134 +383,7 @@ function parse(input) {
   } catch (e) {
     throw new CertificateError("x509/bad-der", "certificate DER did not decode: " + e.message, e);
   }
-  if (root.tagClass !== "universal" || root.tagNumber !== TAGS.SEQUENCE || !root.children || root.children.length !== 3) {
-    throw new CertificateError("x509/not-a-certificate", "Certificate must be a SEQUENCE of {tbsCertificate, signatureAlgorithm, signature}");
-  }
-
-  var tbs = root.children[0];
-  var outerSigAlg = root.children[1];
-  var sigValueNode = root.children[2];
-  if (!tbs.children || !tbs.children.length) {
-    throw new CertificateError("x509/bad-tbs", "tbsCertificate is empty");
-  }
-
-  var idx = 0;
-  var version;
-  var first = tbs.children[0];
-  if (first.tagClass === "context" && first.tagNumber === 0) {
-    if (!first.children || !first.children.length) throw new CertificateError("x509/bad-version", "version [0] must wrap an INTEGER");
-    // RFC 5280 §4.1.2.1 — version is INTEGER { v1(0), v2(1), v3(2) }; read
-    // it as a BigInt so an out-of-range value can't be coerced to a float,
-    // and reject an explicitly-encoded v1 (DER forbids encoding the DEFAULT).
-    var versionValue = asn1.read.integer(first.children[0]);
-    if (versionValue === 0n) {
-      throw new CertificateError("x509/bad-version", "DER forbids explicitly encoding the default version v1");
-    } else if (versionValue === 1n) {
-      version = 2;
-    } else if (versionValue === 2n) {
-      version = 3;
-    } else {
-      throw new CertificateError("x509/bad-version", "unsupported certificate version " + versionValue.toString());
-    }
-    idx = 1;
-  } else {
-    version = 1;
-  }
-
-  // Six positional fields follow any [0] version; a shorter tbs would read
-  // `undefined` and throw a raw TypeError on the first property access.
-  if (tbs.children.length < idx + 6) {
-    throw new CertificateError("x509/bad-tbs", "tbsCertificate is too short");
-  }
-
-  var serialNode = tbs.children[idx++];
-  var serialNumber = asn1.read.integer(serialNode);
-  var innerSigAlg = tbs.children[idx++];
-  var issuer = _parseName(tbs.children[idx++]);
-  var validityNode = tbs.children[idx++];
-  var subject = _parseName(tbs.children[idx++]);
-  var spkiNode = tbs.children[idx++];
-
-  // RFC 5280 §4.1.1.2 — the outer signatureAlgorithm MUST contain the same
-  // AlgorithmIdentifier (OID and parameters) as tbsCertificate.signature. A
-  // mismatch is a signature-algorithm-substitution vector, so compare the full
-  // DER of both fields rather than surfacing two disagreeing algorithms.
-  if (!outerSigAlg.bytes.equals(innerSigAlg.bytes)) {
-    throw new CertificateError("x509/bad-signature-algorithm", "signatureAlgorithm must match tbsCertificate.signature (RFC 5280 §4.1.1.2)");
-  }
-
-  // RFC 5280 §4.1.2.4 — the issuer field MUST contain a non-empty distinguished
-  // name. (An empty subject is permitted when a subjectAltName carries the
-  // identity — §4.1.2.6 — so only the issuer is required non-empty here.)
-  if (!issuer.rdns.length) {
-    throw new CertificateError("x509/bad-issuer", "issuer must be a non-empty distinguished name");
-  }
-
-  if (!validityNode.children || validityNode.children.length !== 2) {
-    throw new CertificateError("x509/bad-validity", "Validity must be a SEQUENCE of {notBefore, notAfter}");
-  }
-  var validity = {
-    notBefore: _parseValidityTime(validityNode.children[0]),
-    notAfter:  _parseValidityTime(validityNode.children[1]),
-  };
-
-  if (!spkiNode.children || spkiNode.children.length !== 2) {
-    throw new CertificateError("x509/bad-spki", "SubjectPublicKeyInfo must be a SEQUENCE of {algorithm, subjectPublicKey}");
-  }
-  var spkiBits = asn1.read.bitString(spkiNode.children[1]);
-  var subjectPublicKeyInfo = {
-    algorithm: _algId(spkiNode.children[0]),
-    publicKey: { unusedBits: spkiBits.unusedBits, bytes: spkiBits.bytes },
-    bytes:     spkiNode.bytes,
-  };
-
-  // Remaining tbs children: optional issuerUniqueID [1], subjectUniqueID
-  // [2], and extensions [3] EXPLICIT. Only extensions are surfaced. RFC 5280
-  // §4.1 fixes these as the trailing fields, each at most once and in strictly
-  // increasing tag order; a repeated or out-of-order tag (or an unknown /
-  // non-context field) is malformed. Without the monotonic guard a second [3]
-  // silently overwrites the first, hiding its extensions and splitting
-  // duplicate extension OIDs across two wrappers past the per-sequence check.
-  var extensions = [];
-  var hasExtensions = false;
-  var lastTrailingTag = 0;
-  for (; idx < tbs.children.length; idx++) {
-    var t = tbs.children[idx];
-    if (t.tagClass !== "context" || t.tagNumber < 1 || t.tagNumber > 3) {
-      throw new CertificateError("x509/bad-tbs", "unexpected field after subjectPublicKeyInfo; tbsCertificate allows only issuerUniqueID [1], subjectUniqueID [2], extensions [3]");
-    }
-    if (t.tagNumber <= lastTrailingTag) {
-      throw new CertificateError("x509/bad-tbs", "tbsCertificate trailing field [" + t.tagNumber + "] is repeated or out of order");
-    }
-    lastTrailingTag = t.tagNumber;
-    if (t.tagNumber === 3) {
-      hasExtensions = true;
-      if (!t.children || !t.children.length) throw new CertificateError("x509/bad-extensions", "extensions [3] must wrap a SEQUENCE");
-      extensions = _parseExtensions(t.children[0]);
-    }
-  }
-
-  // RFC 5280 §4.1.2.9 — the extensions field appears only in a v3 cert.
-  if (hasExtensions && version !== 3) {
-    throw new CertificateError("x509/bad-version", "extensions are only permitted in a v3 certificate");
-  }
-
-  var sigBits = asn1.read.bitString(sigValueNode);
-
-  return {
-    version:            version,
-    serialNumber:       serialNumber,
-    serialNumberHex:    serialNode.content.toString("hex"),
-    signatureAlgorithm: _algId(outerSigAlg),
-    tbsSignatureAlgorithm: _algId(innerSigAlg),
-    issuer:             issuer,
-    subject:            subject,
-    validity:           validity,
-    subjectPublicKeyInfo: subjectPublicKeyInfo,
-    extensions:         extensions,
-    tbsBytes:           tbs.bytes,
-    signatureValue:     { unusedBits: sigBits.unusedBits, bytes: sigBits.bytes },
-  };
+  return schema.walk(CERTIFICATE, root, NS).result;
 }
 
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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:d25ccb6d-af2d-4b1f-b300-f756dc788762",
+  "serialNumber": "urn:uuid:8ff5f15e-e999-4db6-bf14-09273902a9c2",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-04T19:57:57.512Z",
+    "timestamp": "2026-07-04T22:46:29.855Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.4",
+      "bom-ref": "@blamejs/pki@0.1.6",
       "type": "application",
       "name": "pki",
-      "version": "0.1.4",
+      "version": "0.1.6",
       "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.4",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.6",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.4",
+      "ref": "@blamejs/pki@0.1.6",
       "dependsOn": []
     }
   ]