@blamejs/pki 0.1.6 → 0.1.8

package/lib/schema-pkix.js

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

package/lib/schema-x509.js

@@ -0,0 +1,243 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.schema.x509
+ * @nav        Schema
+ * @title      X.509
+ * @order      100
+ * @featured   true
+ * @slug       x509
+ *
+ * @intro
+ *   X.509 certificate handling per RFC 5280. The seed surface is
+ *   `parse` — turn a DER or PEM certificate into a structured,
+ *   fully-decoded object: version, serial, signature algorithm, issuer
+ *   and subject distinguished names, validity window (as real `Date`s),
+ *   subject public-key info, and the extension list. The parser composes
+ *   the strict DER codec and the OID registry, so every field is
+ *   validated on the way in and every algorithm / attribute / extension
+ *   is named where the registry knows it.
+ *
+ *   The raw `tbsCertificate` bytes are returned alongside the parsed
+ *   fields so a signature-verification layer can hash exactly the bytes
+ *   that were signed rather than re-encoding and hoping for round-trip
+ *   fidelity.
+ *
+ * @card
+ *   Parse DER / PEM X.509 certificates into structured, validated fields
+ *   with named algorithms, extensions, and real-`Date` validity windows.
+ */
+
+var asn1 = require("./asn1-der");
+var schema = require("./schema-engine");
+var oid = require("./oid");
+var frameworkError = require("./framework-error");
+var pkix = require("./schema-pkix");
+
+var CertificateError = frameworkError.CertificateError;
+var PemError = frameworkError.PemError;
+
+// ---- PEM -------------------------------------------------------------
+
+/**
+ * @primitive  pki.schema.x509.pemDecode
+ * @signature  pki.schema.x509.pemDecode(text, label?) -> Buffer
+ * @since      0.1.7
+ * @status     stable
+ * @spec       RFC 7468, RFC 5280
+ * @related    pki.schema.x509.pemEncode
+ *
+ * Extract the DER bytes from a PEM block. With `label` given (e.g.
+ * `"CERTIFICATE"`) the block type must match; without it, the first block
+ * is taken. Throws `PemError` on a missing / mismatched envelope or a
+ * non-base64 body.
+ *
+ * @example
+ *   var der = pki.schema.x509.pemDecode(pemText, "CERTIFICATE");
+ */
+function pemDecode(text, label) { return pkix.pemDecode(text, label, PemError); }
+
+/**
+ * @primitive  pki.schema.x509.pemEncode
+ * @signature  pki.schema.x509.pemEncode(der, label) -> string
+ * @since      0.1.7
+ * @status     stable
+ * @spec       RFC 7468, RFC 5280
+ * @related    pki.schema.x509.pemDecode
+ *
+ * Wrap DER bytes in a PEM envelope with 64-column base64 lines.
+ *
+ * @example
+ *   var pem = pki.schema.x509.pemEncode(der, "CERTIFICATE");
+ */
+function pemEncode(der, label) { return pkix.pemEncode(der, label, PemError); }
+
+// ---- helpers ---------------------------------------------------------
+
+// The x509 error namespace the schema engine walks under: prefix names the
+// error family and E constructs the typed CertificateError. The shared PKIX
+// sub-schemas (AlgorithmIdentifier, Name, Extension) live in lib/pkix-schema.js
+// as ns-parameterized factories so crl.js / cms.js reuse them while emitting
+// their own crl/*, cms/* codes; here they are instantiated under this NS.
+var NS = { prefix: "x509", E: function (code, message) { return new CertificateError(code, message); }, oid: oid };
+
+var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
+var NAME = pkix.name(NS);
+
+// Validity ::= SEQUENCE { notBefore Time, notAfter Time }. The historical guard
+// checked only children.length===2 (not the SEQUENCE tag) -> assert "constructed".
+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 — the shared pkix.spki factory under the x509 NS.
+var SPKI = pkix.spki(NS);
+
+var EXTENSIONS = pkix.extensions(NS);
+
+// Version ::= INTEGER { v1(0), v2(1), v3(2) }, [0] EXPLICIT DEFAULT v1. Read as a
+// BigInt so an out-of-range value can't coerce to a float; reject an explicitly-
+// 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.
+// 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 (!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)");
+    }
+
+    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");
+    }
+
+    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;
+    return {
+      version:               version,
+      serialNumber:          tbs.fields.serialNumber.value,
+      serialNumberHex:       serialNode.content.toString("hex"),
+      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:              e.tbsBytes,
+      signatureValue:        e.signatureValue,
+    };
+  },
+});
+
+// ---- parse -----------------------------------------------------------
+
+/**
+ * @primitive  pki.schema.x509.parse
+ * @signature  pki.schema.x509.parse(input) -> certificate
+ * @since      0.1.7
+ * @status     stable
+ * @spec       RFC 5280, X.509
+ * @defends    malformed-certificate-parse (CWE-20)
+ * @related    pki.asn1.decode, pki.oid.name
+ *
+ * Parse a DER `Buffer` or a PEM string/Buffer into a structured
+ * certificate: `{ version, serialNumber, serialNumberHex,
+ * signatureAlgorithm, issuer, subject, validity, subjectPublicKeyInfo,
+ * extensions, tbsBytes, signatureValue }`. Distinguished names come back
+ * both as a rendered `dn` string and as structured `rdns`; the validity
+ * window is real `Date`s; `tbsBytes` is the exact signed byte range for a
+ * downstream verifier.
+ *
+ * Throws `CertificateError` when the bytes are not a well-formed
+ * certificate and `Asn1Error` when the underlying DER is malformed.
+ *
+ * @example
+ *   var cert = pki.schema.x509.parse(pemString);
+ *   cert.subject.dn;                 // "CN=example.com, O=Example"
+ *   cert.validity.notAfter;          // Date
+ *   cert.signatureAlgorithm.name;    // "sha256WithRSAEncryption"
+ */
+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
+// tbs: a certificate has a Validity — a SEQUENCE of exactly two Time values — at
+// position [serial, signature, issuer, VALIDITY] after the optional [0] version.
+// A CSR's certificationRequestInfo has subjectPublicKeyInfo there (no Validity),
+// and a CRL leads with a bare Time; neither matches. Used by the orchestrator.
+function matches(root) {
+  var TAGS = asn1.TAGS;
+  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)
+  return !!validity && validity.tagClass === "universal" && validity.tagNumber === TAGS.SEQUENCE &&
+    !!validity.children && validity.children.length === 2 &&
+    validity.children.every(function (t) {
+      return t.tagClass === "universal" && (t.tagNumber === TAGS.UTC_TIME || t.tagNumber === TAGS.GENERALIZED_TIME);
+    });
+}
+
+module.exports = {
+  parse:     parse,
+  pemDecode: pemDecode,
+  pemEncode: pemEncode,
+  matches:   matches,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.1.6",
+  "version": "0.1.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:8ff5f15e-e999-4db6-bf14-09273902a9c2",
+  "serialNumber": "urn:uuid:64eeff87-502c-43f1-a398-5fbe7fc7a614",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-04T22:46:29.855Z",
+    "timestamp": "2026-07-05T06:26:48.420Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.6",
+      "bom-ref": "@blamejs/pki@0.1.8",
       "type": "application",
       "name": "pki",
-      "version": "0.1.6",
+      "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.6",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.8",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.6",
+      "ref": "@blamejs/pki@0.1.8",
       "dependsOn": []
     }
   ]