@blamejs/pki 0.2.9 → 0.2.10

package/CHANGELOG.md

@@ -4,6 +4,15 @@ 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.2.10 — 2026-07-13
+
+Certificate linting arrives as pki.lint -- graded, advisory conformance findings against the RFC 5280 profile and a representative CA/Browser Forum TLS Baseline Requirements subset.
+
+### Added
+
+- pki.lint.certificate(input, opts) lints a certificate against the RFC 5280 profile and a representative CA/Browser Forum TLS BR subset, returning a report of graded advisory findings (id, severity, source, spec citation, message). The data path never throws -- malformed input becomes a fatal lint/unparseable finding rather than an exception -- so a corpus lints without per-file error handling; only config-time misuse raises a typed LintError.
+- pki.lint.rules(profile) and pki.lint.profiles() enumerate the rule registry and the available profiles (rfc5280, cabf-tls) so findings are traceable to a stable id and a spec clause.
+
 ## v0.2.9 — 2026-07-13
 
 Certification-path validation verifies composite ML-DSA signatures, accepting a certificate only when both its post-quantum and traditional components verify.

package/README.md

@@ -229,8 +229,9 @@ is callable today; nothing below is a stub.
 | `pki.sigstore` | Offline verifier for a Sigstore bundle — the exact artifact `npm publish --provenance` produces and the registry serves. `verifyBundle` composes five fail-closed legs against caller-pinned trust (Fulcio CA roots + Rekor log keys, never trusted from the bundle): the DSSE signature over its PAE preimage under the Fulcio leaf key; the ephemeral Fulcio certificate chain, validated as of the Rekor log time; the RFC 9162 inclusion proof folded to a Rekor-signed tree root; the log entry bound to this exact signature; and the in-toto SLSA subject digest the caller confirms against the published artifact. Zero runtime deps — reuses the X.509 parser, RFC 5280 path validator, and Merkle verifier; the net-new codecs are the DSSE PAE byte-builder and a fail-closed JSON reader. `pae`, `parseBundle`, `verifyBundle` |
 | `pki.inspect` | Human-readable certificate inspection — the pure-JS equivalent of `openssl x509 -text`. `certificate(pem \| der \| parsed)` renders a familiar OpenSSL-style report: version, serial, signature algorithm, issuer/subject distinguished names, validity, public-key details (curve or modulus size + the raw point/modulus), every decoded extension with its critical flag, and the signature. Built over the strict parser and the two-way OID registry, so it names extension and algorithm OIDs an OpenSSL build shows only as raw bytes. No OpenSSL dependency; the format is stable and OpenSSL-familiar rather than pinned to one OpenSSL version; a malformed extension falls back to a hex dump rather than throwing — `certificate` |
 | `pki.webauthn` | WebAuthn / passkey attestation verification — offline trust evaluation of a W3C WebAuthn (Level 3) attestation. `parseAttestationObject(bytes)` decodes the CBOR attestation object + authenticatorData + COSE credential key over the strict `pki.cbor` codec; `verify(attestationObject, clientDataHash, opts)` checks the attestation-statement signature and each format's structural bindings for **packed / tpm / android-key / apple / fido-u2f / none** — the x5c leaf key, the apple nonce, the tpm `certInfo` Name/`extraData` over the `pubArea`, the android `KeyDescription`, the fido-u2f `verificationData` — binding the credential public key to each attestation (via the signed authenticatorData for packed/fido-u2f, or a cert/`pubArea`-key equality check for android-key/apple/tpm) and enforcing each leaf's certificate requirements. The credential-key check covers the full WebAuthn COSE algorithm set — ES256/384/512, RS256/384/512, PS256, EdDSA (Ed25519), and the RFC 9864 fully-specified identifiers **ESP256/384/512, Ed25519, and Ed448** — validating the public-key point on its curve, rejecting the compressed EC point form, and enforcing a minimally-encoded DER ECDSA signature. A verifier, not a ceremony client; fail-closed with typed `webauthn/*` errors. Chaining the returned trust path to a pinned root (and aaguid→root via FIDO MDS) is the caller's step through `pki.path.validate` — `parseAttestationObject`, `verify` |
+| `pki.lint` | Certificate linting — the zlint / pkilint of JavaScript. `certificate(pem \| der \| parsed, opts)` walks a parsed certificate and emits graded, advisory findings — each with a stable id, a severity (`fatal` > `error` > `warn` > `notice`), a source, a spec-clause citation, and a message — against the RFC 5280 profile plus a representative CA/Browser Forum TLS BR subset (serial sign/size, validity ordering + the the SC081v3 reducing validity schedule, keyCertSign coherence, unknown critical extensions, empty-subject SAN, SKI/AKI presence, SAN required + CN-in-SAN, dNSName syntax, serverAuth EKU, weak keys). Unlike every other entry the DATA path never throws: hostile bytes return a `fatal` `lint/unparseable` finding (with the strict parser's code) so a whole directory lints without a try/catch; only config-time misuse throws a typed `LintError`. `certificate`, `rules`, `profiles` |
 | `pki.C` / `pki.constants` | Version-stable constants — functional scale helpers (`C.TIME.*`, `C.BYTES.*`), codec `LIMITS`, `version` |
-| `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError` / `Pkcs8Error` / `CmsError` / `OcspError` / `TspError` / `AttrCertError` / `CrmfError` / `Pkcs12Error` / `CmpError` / `PathError` / `CtError` / `JoseError` / `AcmeError` / `WebauthnError`, each carrying a stable `code` in `domain/reason` form |
+| `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError` / `Pkcs8Error` / `CmsError` / `OcspError` / `TspError` / `AttrCertError` / `CrmfError` / `Pkcs12Error` / `CmpError` / `PathError` / `CtError` / `JoseError` / `AcmeError` / `WebauthnError` / `LintError`, each carrying a stable `code` in `domain/reason` form |
 | `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>` |
 
 ### CLI

package/index.js

@@ -45,6 +45,7 @@ var jose       = require("./lib/jose");
 var acme       = require("./lib/acme");
 var trust      = require("./lib/trust");
 var inspect    = require("./lib/inspect");
+var lint       = require("./lib/lint");
 var webauthn   = require("./lib/webauthn");
 
 module.exports = {
@@ -117,6 +118,7 @@ module.exports = {
   // OID registry, naming extension/algorithm OIDs OpenSSL shows only as raw bytes.
   // Pure, no OpenSSL dependency; best-effort (a bad extension falls back to hex).
   inspect:   inspect,
+  lint:      lint,
   // `webauthn` verifies a W3C WebAuthn / passkey attestation -- pki.webauthn.verify
   // checks the attestation-statement signature + each format's structural bindings
   // (packed / tpm / android-key / apple / fido-u2f / none) and surfaces the x5c chain

package/lib/framework-error.js

@@ -303,6 +303,13 @@ var InspectError = defineClass("InspectError", { withCause: true });
 // its bounded layout, an attestation-statement signature that does not verify, or a
 // trust path that does not reach the caller's anchor. Fail-closed, typed reason.
 var WebauthnError = defineClass("WebauthnError", { withCause: true });
+// LintError -- CONFIG-time misuse of the certificate linter (pki.lint) ONLY: an
+// unknown profile name, an out-of-range severity threshold, or an input that is
+// neither a parsed structure, DER Buffer, nor PEM string. This is the lint engine's
+// SOLE throw path: unlike every other toolkit entry, the lint DATA path never throws
+// on malformed input -- a linter surveys a corpus that includes malformed members,
+// so hostile bytes surface a `fatal` finding (lint/unparseable) and return a report.
+var LintError = defineClass("LintError", { withCause: true });
 
 module.exports = {
   PkiError:         PkiError,
@@ -331,6 +338,7 @@ module.exports = {
   SigstoreError:    SigstoreError,
   InspectError:     InspectError,
   WebauthnError:    WebauthnError,
+  LintError:        LintError,
   MerkleError:      MerkleError,
   SmimeError:       SmimeError,
   CsrattrsError:    CsrattrsError,

package/lib/lint.js

@@ -0,0 +1,567 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module pki.lint
+ * @nav        Tooling
+ * @title      Lint
+ * @intro The certificate LINTING engine -- the zlint / pkilint of JavaScript. It walks an
+ *   ALREADY-PARSED certificate (from `pki.schema.x509.parse`, whose extension values it
+ *   decodes with the shared RFC 5280 decoders) and emits graded, advisory FINDINGS: each
+ *   with a stable id, a severity (`fatal` > `error` > `warn` > `notice` > `pass`), a source,
+ *   a spec-clause citation, and a human message. It ships the RFC 5280 certificate profile
+ *   plus a representative CA/Browser Forum TLS Baseline Requirements subset.
+ *
+ *   Unlike every other toolkit entry, the lint DATA path NEVER throws. A linter surveys a
+ *   corpus that includes malformed members, so `pki.lint.certificate(hostileBytes)` returns
+ *   a report whose worst finding is a `fatal` id `lint/unparseable` (carrying the inner
+ *   `PkiError.code`) rather than raising. The SOLE throw path is CONFIG-time misuse -- an
+ *   unknown profile, an out-of-range severity threshold, or a wrong-type input -- which
+ *   raises a typed `LintError`. This deliberate inversion of the toolkit's fail-closed-throw
+ *   posture is what lets an operator lint a whole directory without a try/catch per file.
+ * @spec RFC 5280, CA/Browser Forum TLS Baseline Requirements
+ * @card Lint a certificate against RFC 5280 + CABF TLS BR, in pure JS.
+ */
+
+var net = require("net");
+var frameworkError = require("./framework-error");
+var asn1 = require("./asn1-der");
+var oid = require("./oid");
+var x509 = require("./schema-x509");
+var pkix = require("./schema-pkix");
+var C = require("./constants");
+
+var MS_PER_DAY = C.TIME.days(1);
+
+var LintError = frameworkError.LintError;
+function _cfg(code, message, cause) { return new LintError(code, message, cause); }
+
+// Strict-parse pre-emption: this toolkit's parser is strict-DER, so several RFC 5280
+// profile violations a lenient linter (zlint/pkilint) would report as a SPECIFIC finding
+// are instead rejected fail-closed at PARSE and surface here as a single `fatal`
+// lint/unparseable whose context.code names the exact structural violation -- e.g. a
+// duplicate extension OID (x509/duplicate-extension), a pathLenConstraint without cA
+// (bad-basic-constraints), an explicit cA=FALSE, or a signatureAlgorithm/tbs mismatch.
+// The registry therefore ships no dedicated rule for a violation the parser already
+// rejects (a dead rule that could never fire); the specific reason is preserved in the
+// unparseable finding's context.
+//
+// The shared RFC 5280 extension decoders, composed exactly as path-validate / inspect
+// compose them -- the linter owns no second decoder table.
+var NS = pkix.makeNS("lint", LintError, oid);
+var EXT_DECODERS = pkix.certExtensionDecoders(NS).byOid;
+
+// Coverage note: the rules and helpers below carry defensive guards -- `|| []` / `|| ""`
+// on fields the strict parser ALWAYS sets (extensions, serialNumberHex, subject.rdns), and
+// `!Buffer.isBuffer` / `instanceof Date` / minimal-encoding checks against malformed-but-
+// parsed shapes the strict parser never produces. These are fail-safe belts, not reachable
+// paths; they stay verified-unreachable (documented) rather than removed, since the lint
+// data path must never throw even on an unexpected upstream shape.
+
+// ---- the advisory result surface (the Do-FIRST: graded findings, not a throw) ----
+
+// Severity ordering (zlint's LintStatus). NA (not applicable) and NE (not effective --
+// outside a rule's date window) are rule OUTCOMES, tracked in counts, not severities.
+var SEVERITY = { fatal: 5, error: 4, warn: 3, notice: 2, pass: 1 };
+var VALID_SEVERITY = Object.keys(SEVERITY);
+
+function _worst(findings) {
+  var w = null, wv = 0;
+  findings.forEach(function (f) { var v = SEVERITY[f.severity] || 0; if (v > wv) { wv = v; w = f.severity; } });
+  return w;
+}
+
+// A profile groups rules by source; a rule is `{ id, severity, source, citation,
+// appliesTo?, effectiveDate?, check }`. `check(cert, ctx)` returns null (pass) or a detail
+// / array of details, each becoming one finding under the rule. A detail carries only an
+// optional `context` object; the human message is the rule's.
+function _finding(rule, detail) {
+  var f = { id: rule.id, severity: rule.severity, source: rule.source, citation: rule.citation, message: rule.message };
+  if (detail && detail.context) f.context = detail.context;
+  return f;
+}
+
+// ---- ingestion: bytes/PEM/parsed -> parsed, or a fatal lint/unparseable finding ----
+
+function _looksParsed(o) {
+  return o && typeof o === "object" && !Buffer.isBuffer(o) &&
+    Buffer.isBuffer(o.tbsBytes) && o.validity && o.subjectPublicKeyInfo && Array.isArray(o.extensions);
+}
+
+// Returns { cert } on success, or { fatal: <Finding> } when hostile bytes do not parse
+// (the never-throw data path). Throws LintError ONLY on a wrong-TYPE input (config misuse).
+function _ingest(input) {
+  if (_looksParsed(input)) return { cert: input };
+  var der;
+  if (Buffer.isBuffer(input)) der = input;
+  else if (typeof input === "string") {
+    try { der = x509.pemDecode(input, "CERTIFICATE"); }
+    catch (e) { return { fatal: { id: "lint/unparseable", severity: "fatal", source: "engine", citation: "pki.lint", message: "input is not a decodable PEM/DER certificate", context: { code: e.code } } }; }
+  } else {
+    throw _cfg("lint/bad-input", "pki.lint input must be a parsed certificate, a DER Buffer, or a PEM string");
+  }
+  try { return { cert: x509.parse(der) }; }
+  catch (e) { return { fatal: { id: "lint/unparseable", severity: "fatal", source: "engine", citation: "RFC 5280", message: "input is not a well-formed X.509 certificate", context: { code: e.code } } }; }
+}
+
+// ---- per-cert context the rules read ----
+
+function _findRaw(cert, name) {
+  var dotted = oid.byName(name);
+  var list = cert.extensions || [];
+  for (var i = 0; i < list.length; i++) { if (list[i].oid === dotted) return list[i]; }
+  return null;
+}
+// Decode a known extension to { critical, value }, or null when absent OR undecodable.
+// The undecodable case is surfaced by the dedicated `extension-undecodable` rule; every
+// other rule treats an undecodable extension as "not usable" and simply does not fire.
+// allow:swallow-unverified the decode fault is reported by the extension-undecodable rule
+function _decodeOrNull(cert, name) {
+  var ext = _findRaw(cert, name);
+  if (!ext) return null;
+  var dec = EXT_DECODERS[oid.byName(name)];
+  if (!dec) return null;
+  try { return { critical: ext.critical, value: dec(ext.value) }; }
+  catch (_e) { return null; }
+}
+
+function _hasEku(cert, ekuName) {
+  var d = _decodeOrNull(cert, "extKeyUsage");
+  return !!(d && Array.isArray(d.value) && d.value.indexOf(oid.byName(ekuName)) !== -1);
+}
+
+function _makeCtx(cert, profile) {
+  var explicitTls = profile === "cabf-tls";
+  // A CA certificate is not a TLS server (leaf) certificate even when it carries a
+  // serverAuth EKU, so the default profile must NOT apply the CABF leaf rules (SAN
+  // required, CN-in-SAN, validity ceiling, ...) to it. An explicit cabf-tls selection
+  // still lints whatever the caller hands it as a server cert.
+  var bc = _decodeOrNull(cert, "basicConstraints");
+  var isCa = !!(bc && bc.value && bc.value.cA === true);
+  return {
+    profile: profile,
+    explicitTlsProfile: explicitTls,
+    isTlsServerCert: explicitTls || (_hasEku(cert, "serverAuth") && !isCa),
+    decode: function (name) { return _decodeOrNull(cert, name); },
+    raw: function (name) { return _findRaw(cert, name); },
+  };
+}
+
+// ---- the runner ----
+
+// A date-gated rule is effective for a cert only when the cert's notBefore is at or after
+// the rule's effectiveDate; a cert issued before it reports NE (not effective, never fires).
+// This encodes a scheduled requirement (the CABF validity-day ceiling) against issuance date.
+function _effective(rule, cert) {
+  if (!rule.effectiveDate) return true;
+  var nb = cert.validity && cert.validity.notBefore;
+  return (nb instanceof Date) && nb.getTime() >= rule.effectiveDate.getTime();
+}
+
+function _runLints(rules, cert, ctx) {
+  var findings = [], counts = { fatal: 0, error: 0, warn: 0, notice: 0, pass: 0, na: 0, ne: 0 }, ran = [];
+  rules.forEach(function (rule) {
+    if (rule.appliesTo && !rule.appliesTo(cert, ctx)) { counts.na++; return; }
+    if (!_effective(rule, cert)) { counts.ne++; return; }
+    ran.push(rule.id);
+    var res = rule.check(cert, ctx);
+    if (res == null || res === false) { counts.pass++; return; }
+    var details = Array.isArray(res) ? res : [res];
+    details.forEach(function (d) {
+      var f = _finding(rule, d === true ? null : d);
+      findings.push(f);
+      counts[f.severity] = (counts[f.severity] || 0) + 1;
+    });
+  });
+  return { findings: findings, counts: counts, ran: ran };
+}
+
+// ---- rule registry ----
+
+function _serialOctets(cert) {
+  var hex = cert.serialNumberHex || "";
+  if (hex.length % 2) hex = "0" + hex;
+  var buf = Buffer.from(hex, "hex");
+  // Strip a single DER positive-sign 00 (present only when the value's high bit is set);
+  // the octet COUNT the profile bounds is the value's, not the encoding's leading pad.
+  if (buf.length > 1 && buf[0] === 0x00 && (buf[1] & 0x80)) buf = buf.subarray(1);
+  return buf.length;
+}
+
+// dNSName syntax (a representative CABF check): no whitespace, no leading/trailing dot,
+// no empty label, and no underscore (forbidden in a dNSName). IDN must already be an
+// A-label (we do not transcode). Returns a reason string, or null when well-formed.
+function _dnsNameProblem(s) {
+  if (typeof s !== "string" || !s.length) return "empty";
+  if (s.length > 253) return "exceeds 253 octets";
+  if (/\s/.test(s)) return "whitespace";
+  if (s.charAt(0) === "." || s.charAt(s.length - 1) === ".") return "leading/trailing dot";
+  if (s.indexOf("_") !== -1) return "underscore forbidden in dNSName";
+  var labels = s.split(".");
+  for (var i = 0; i < labels.length; i++) {
+    var label = labels[i];
+    if (label.length === 0) return "empty label";
+    if (label.length > 63) return "label exceeds 63 octets";
+    // A leftmost "*" wildcard label is permitted only when at least one more label follows
+    // (a bare "*" is not a domain name).
+    if (i === 0 && label === "*") {
+      if (labels.length < 2) return "bare wildcard";
+      continue;
+    }
+    // RFC 1034 preferred name syntax: an LDH label that neither begins nor ends with a
+    // hyphen. Rejects "-bad" / "bad-" and any non-letter/digit/hyphen character.
+    if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/i.test(label)) return "invalid label syntax";
+  }
+  return null;
+}
+
+// A genuine IPv4 or IPv6 literal (validated by net.isIP, which rejects an out-of-range
+// dotted quad like 999.999.999.999 or a colon-bearing non-address like "api:443") -- a CN
+// validated against an iPAddress SAN rather than a dNSName.
+function _looksLikeIp(s) { return typeof s === "string" && net.isIP(s) !== 0; }
+
+function _sanDnsNames(ctx) {
+  var d = ctx.decode("subjectAltName");
+  if (!d || !d.value || !Array.isArray(d.value.names)) return [];
+  return d.value.names.filter(function (n) { return n && n.tagNumber === 2; }).map(function (n) { return n.value; });
+}
+// The subject CN string values (an RDN attribute of type commonName), if any.
+function _subjectCNs(cert) {
+  var out = [];
+  ((cert.subject && cert.subject.rdns) || []).forEach(function (rdn) {
+    rdn.forEach(function (a) { if (a.type === oid.byName("commonName") && typeof a.value === "string") out.push(a.value); });
+  });
+  return out;
+}
+
+// An extension is "recognized" (RFC 5280 4.2: a consumer MUST reject a critical extension
+// it does NOT recognize / cannot process) when the toolkit has a DECODER for it -- the
+// shared certExtensionDecoders table IS the set of extensions this toolkit processes. This
+// is registry-driven (no curated list to omit a legitimately-critical extension such as
+// policyMappings, which the table decodes) and correctly scoped to EXTENSION OIDs: an
+// algorithm / EKU-purpose OID the name registry happens to resolve is NOT in the decoder
+// table, so a critical extension carrying such an OID is still flagged.
+function _isUnknownExtension(extOid) { return !EXT_DECODERS[extOid]; }
+
+// RSA-modulus / EC-curve helpers for the weak-key lint. Each returns null when the key
+// material cannot be read as expected (a malformed RSA modulus, or EC parameters that are
+// absent / explicit / not a named-curve OID); the weak-key rule treats null as fail-closed
+// (a key it cannot confirm meets the minimum is flagged, not silently passed).
+function _rsaModulusBits(spki) {
+  try {
+    var pk = spki.publicKey && (spki.publicKey.bytes || spki.publicKey);
+    if (!Buffer.isBuffer(pk)) return null;
+    var seq = asn1.decode(pk);
+    // RSAPublicKey ::= SEQUENCE { modulus INTEGER, publicExponent INTEGER } -- exactly two
+    // INTEGERs, and the modulus MUST be positive. A negative/zero modulus (a high-bit key
+    // mis-encoded without a sign pad) or a missing exponent is malformed, not a real key.
+    if (!seq.children || seq.children.length !== 2) return null;
+    var mod = asn1.read.integer(seq.children[0]);
+    asn1.read.integer(seq.children[1]);   // the exponent must be a valid INTEGER
+    if (mod <= 0n) return null;
+    return mod.toString(2).length;
+  } catch (_e) { return null; }   // a modulus that will not decode cannot be sized
+}
+// Every RSA-family SPKI (rsaEncryption, RSASSA-PSS, RSAES-OAEP) carries an RSAPublicKey
+// SEQUENCE, so all are weighed by modulus size; matching only "rsaEncryption" would let an
+// RSA-PSS or RSAES-OAEP key skip the check.
+var RSA_KEY_ALGS = { rsaEncryption: 1, rsassaPss: 1, rsaesOaep: 1 };
+var APPROVED_EC_CURVES = ["prime256v1", "secp384r1", "secp521r1"]; // P-256 / P-384 / P-521
+function _ecCurveName(spki) {
+  try {
+    var params = spki.algorithm && spki.algorithm.parameters;
+    if (!Buffer.isBuffer(params)) return null;
+    return oid.name(asn1.read.oid(asn1.decode(params)));   // named-curve OID, or throw on explicit params
+  } catch (_e) { return null; }   // explicit / invalid EC parameters are not an approved named curve
+}
+
+var RFC5280_RULES = [
+  {
+    id: "lint/rfc5280/serial-not-positive", severity: "error", source: "rfc5280", citation: "RFC 5280 4.1.2.2",
+    message: "the certificate serialNumber must be a positive integer",
+    check: function (cert) { return cert.serialNumber <= 0n ? true : null; },
+  },
+  {
+    id: "lint/rfc5280/serial-too-long", severity: "error", source: "rfc5280", citation: "RFC 5280 4.1.2.2",
+    message: "the certificate serialNumber must not exceed 20 octets",
+    // Counts the VALUE magnitude (a single DER sign-pad 0x00 stripped), not the encoded
+    // length: a 20-byte random serial whose high bit is set encodes as 21 octets but is a
+    // conformant 20-octet value, so this avoids false-positiving on the common CA serial.
+    check: function (cert) { return _serialOctets(cert) > 20 ? { context: { octets: _serialOctets(cert) } } : null; },
+  },
+  {
+    id: "lint/rfc5280/validity-inverted", severity: "error", source: "rfc5280", citation: "RFC 5280 4.1.2.5",
+    message: "the certificate notBefore must not be later than notAfter",
+    check: function (cert) {
+      var v = cert.validity;
+      return (v.notBefore instanceof Date && v.notAfter instanceof Date && v.notBefore.getTime() > v.notAfter.getTime()) ? true : null;
+    },
+  },
+  {
+    id: "lint/rfc5280/ca-without-keycertsign", severity: "error", source: "rfc5280", citation: "RFC 5280 4.2.1.3 / 4.2.1.9",
+    message: "a CA certificate (basicConstraints cA=TRUE) must assert the keyCertSign key usage",
+    appliesTo: function (cert, ctx) { var bc = ctx.decode("basicConstraints"); return !!(bc && bc.value && bc.value.cA === true); },
+    check: function (cert, ctx) { var ku = ctx.decode("keyUsage"); return (ku && ku.value && ku.value.keyCertSign === true) ? null : true; },
+  },
+  {
+    id: "lint/rfc5280/keycertsign-without-ca", severity: "error", source: "rfc5280", citation: "RFC 5280 4.2.1.3",
+    message: "a certificate asserting the keyCertSign key usage must also assert basicConstraints cA=TRUE",
+    // The inverse coherence check: keyCertSign asserted -> cA MUST be TRUE. Fires when a
+    // cert claims certificate-signing usage but omits basicConstraints or is not a CA.
+    appliesTo: function (cert, ctx) { var ku = ctx.decode("keyUsage"); return !!(ku && ku.value && ku.value.keyCertSign === true); },
+    check: function (cert, ctx) { var bc = ctx.decode("basicConstraints"); return (bc && bc.value && bc.value.cA === true) ? null : true; },
+  },
+  {
+    id: "lint/rfc5280/unknown-critical-extension", severity: "error", source: "rfc5280", citation: "RFC 5280 4.2",
+    message: "a critical extension is not recognized by the profile -- a conforming consumer must reject it",
+    check: function (cert) {
+      var out = [];
+      (cert.extensions || []).forEach(function (e) {
+        if (e.critical === true && _isUnknownExtension(e.oid)) out.push({ context: { oid: e.oid, name: e.name || null } });
+      });
+      return out.length ? out : null;
+    },
+  },
+  {
+    id: "lint/rfc5280/empty-subject-san-not-critical", severity: "error", source: "rfc5280", citation: "RFC 5280 4.1.2.6",
+    message: "a certificate with an empty subject must carry a subjectAltName marked critical",
+    appliesTo: function (cert) { return !((cert.subject && cert.subject.rdns) || []).length; },
+    check: function (cert, ctx) { var san = ctx.decode("subjectAltName"); return (san && san.critical === true) ? null : true; },
+  },
+  {
+    id: "lint/rfc5280/extension-undecodable", severity: "error", source: "rfc5280", citation: "RFC 5280 4.2",
+    message: "a recognized extension's value does not decode under its RFC 5280 syntax",
+    check: function (cert) {
+      var out = [];
+      (cert.extensions || []).forEach(function (e) {
+        var dec = EXT_DECODERS[e.oid];
+        if (!dec) return;
+        try { dec(e.value); }
+        catch (err) {
+          out.push({ context: { oid: e.oid, name: e.name || null, code: err.code } });
+        }
+      });
+      return out.length ? out : null;
+    },
+  },
+  {
+    id: "lint/rfc5280/ski-missing", severity: "notice", source: "rfc5280", citation: "RFC 5280 4.2.1.2",
+    message: "a CA certificate should carry a subjectKeyIdentifier extension",
+    appliesTo: function (cert, ctx) { var bc = ctx.decode("basicConstraints"); return !!(bc && bc.value && bc.value.cA === true); },
+    check: function (cert, ctx) { return ctx.raw("subjectKeyIdentifier") ? null : true; },
+  },
+  {
+    id: "lint/rfc5280/aki-missing", severity: "notice", source: "rfc5280", citation: "RFC 5280 4.2.1.1",
+    message: "a non-self-issued certificate should carry an authorityKeyIdentifier extension",
+    appliesTo: function (cert) { return !!(cert.issuer && cert.subject && cert.issuer.dn !== cert.subject.dn); },
+    check: function (cert, ctx) { return ctx.raw("authorityKeyIdentifier") ? null : true; },
+  },
+];
+
+function _isTls(cert, ctx) { return ctx.isTlsServerCert; }
+
+// The CABF TLS BR maximum validity period (in days) by certificate issuance date --
+// the SC22 398-day ceiling (2020-09-01) reduced on the SC081v3 schedule: 200 days from
+// 2026-03-15, 100 days from 2027-03-15, 47 days from 2029-03-15. Newest-first so the first
+// entry whose `from` is at or before the cert's notBefore gives the applicable ceiling.
+var VALIDITY_SCHEDULE = [
+  { from: new Date("2029-03-15T00:00:00Z"), maxDays: 47 },
+  { from: new Date("2027-03-15T00:00:00Z"), maxDays: 100 },
+  { from: new Date("2026-03-15T00:00:00Z"), maxDays: 200 },
+  { from: new Date("2020-09-01T00:00:00Z"), maxDays: 398 },
+];
+var VALIDITY_SCHEDULE_START = VALIDITY_SCHEDULE[VALIDITY_SCHEDULE.length - 1].from;
+function _validityCeilingDays(notBefore) {
+  for (var i = 0; i < VALIDITY_SCHEDULE.length; i++) {
+    if (notBefore.getTime() >= VALIDITY_SCHEDULE[i].from.getTime()) return VALIDITY_SCHEDULE[i].maxDays;
+  }
+  // Unreachable: the rule's effectiveDate (VALIDITY_SCHEDULE_START) reports NE for any cert
+  // whose notBefore predates the schedule, so the loop always matches the last entry.
+  return VALIDITY_SCHEDULE[VALIDITY_SCHEDULE.length - 1].maxDays;
+}
+
+var CABF_TLS_RULES = [
+  {
+    id: "lint/cabf-tls/san-missing", severity: "error", source: "cabf-tls", citation: "CABF TLS BR 7.1.4.2.1",
+    message: "a TLS server certificate must include a usable subjectAltName extension",
+    appliesTo: _isTls,
+    // A SAN that is absent -- OR present but undecodable / carrying no names -- is not a
+    // usable subjectAltName, so all three cases are treated as missing for the TLS profile.
+    check: function (cert, ctx) { var san = ctx.decode("subjectAltName"); return (san && san.value && san.value.names && san.value.names.length) ? null : true; },
+  },
+  {
+    id: "lint/cabf-tls/cn-not-in-san", severity: "error", source: "cabf-tls", citation: "CABF TLS BR 7.1.4.2.2",
+    message: "a subject commonName value must also appear as a subjectAltName dNSName",
+    appliesTo: _isTls,
+    check: function (cert, ctx) {
+      // dNSNames are case-insensitive (RFC 4343), so match case-folded.
+      var sans = _sanDnsNames(ctx).map(function (s) { return typeof s === "string" ? s.toLowerCase() : s; }), out = [];
+      _subjectCNs(cert).forEach(function (cn) {
+        // A commonName MUST match a dNSName OR an iPAddress SAN (CABF 7.1.4.2.2). This
+        // subset checks dNSName values only, so an IP-literal CN (validated against the
+        // iPAddress SAN this subset does not yet render) is skipped, not false-flagged.
+        if (_looksLikeIp(cn)) return;
+        if (sans.indexOf(cn.toLowerCase()) === -1) out.push({ context: { cn: cn } });
+      });
+      return out.length ? out : null;
+    },
+  },
+  {
+    id: "lint/cabf-tls/dnsname-bad-syntax", severity: "error", source: "cabf-tls", citation: "CABF TLS BR 7.1.4.2.1",
+    message: "a subjectAltName dNSName is not well-formed",
+    appliesTo: _isTls,
+    check: function (cert, ctx) {
+      var out = [];
+      _sanDnsNames(ctx).forEach(function (name) { var p = _dnsNameProblem(name); if (p) out.push({ context: { dnsName: name, problem: p } }); });
+      return out.length ? out : null;
+    },
+  },
+  {
+    id: "lint/cabf-tls/eku-missing-serverauth", severity: "error", source: "cabf-tls", citation: "CABF TLS BR 7.1.2.7.6",
+    message: "a TLS server certificate's extKeyUsage must include id-kp-serverAuth",
+    // Only meaningful when the caller EXPLICITLY lints against the TLS profile; under the
+    // default profile a cert is recognized as TLS BY its serverAuth EKU, so the check is
+    // vacuous and reports NA rather than firing on every non-TLS certificate.
+    appliesTo: function (cert, ctx) { return ctx.explicitTlsProfile; },
+    check: function (cert, ctx) { return _hasEku(cert, "serverAuth") ? null : true; },
+  },
+  {
+    id: "lint/cabf-tls/weak-key", severity: "error", source: "cabf-tls", citation: "CABF TLS BR 6.1.5",
+    message: "the subject public key is below the CABF TLS BR minimum (RSA < 2048 bits, or a non-approved EC curve)",
+    appliesTo: _isTls,
+    check: function (cert) {
+      var spki = cert.subjectPublicKeyInfo, name = spki && spki.algorithm && spki.algorithm.name;
+      // Fail closed: a key whose size/curve cannot be confirmed to meet the minimum is
+      // flagged, not passed. RSA below 2048 bits (or an unreadable modulus), or an EC key
+      // NOT on an approved named curve (including absent / explicit / invalid parameters,
+      // which resolve to a null curve) is a finding -- CABF permits only P-256/384/521.
+      if (RSA_KEY_ALGS[name]) { var bits = _rsaModulusBits(spki); return (bits === null || bits < 2048) ? { context: { rsaBits: bits } } : null; }
+      if (name === "ecPublicKey") { var curve = _ecCurveName(spki); return APPROVED_EC_CURVES.indexOf(curve) === -1 ? { context: { curve: curve } } : null; }
+      // Any other key type (e.g. EdDSA) is out of this rule's RSA-size / EC-curve scope --
+      // key-TYPE approval for TLS is a separate concern, so weak-key does not fire here.
+      return null;
+    },
+  },
+  {
+    id: "lint/cabf-tls/validity-too-long", severity: "error", source: "cabf-tls", citation: "CABF TLS BR 6.3.2 (Ballots SC22 + SC081v3)",
+    message: "a TLS server certificate validity period exceeds the CABF maximum for its issuance date",
+    appliesTo: _isTls,
+    effectiveDate: VALIDITY_SCHEDULE_START,
+    check: function (cert) {
+      var v = cert.validity;
+      if (!(v.notBefore instanceof Date) || !(v.notAfter instanceof Date)) return null;
+      var maxDays = _validityCeilingDays(v.notBefore);
+      var days = (v.notAfter.getTime() - v.notBefore.getTime()) / MS_PER_DAY;
+      return days > maxDays ? { context: { days: Math.round(days), maxDays: maxDays } } : null;
+    },
+  },
+];
+
+var PROFILES = {
+  "rfc5280": RFC5280_RULES,
+  "cabf-tls": CABF_TLS_RULES,
+};
+var ALL_RULES = RFC5280_RULES.concat(CABF_TLS_RULES);
+
+function _selectRules(profile) {
+  if (profile == null || profile === "all" || profile === "default") return ALL_RULES;
+  if (!PROFILES[profile]) throw _cfg("lint/unknown-profile", "unknown lint profile \"" + profile + "\" (known: " + Object.keys(PROFILES).join(", ") + ")");
+  // An explicit cabf-tls run still needs the always-on rfc5280 structural rules? No: the
+  // caller asked for ONE profile. Return exactly that profile's rules.
+  return PROFILES[profile];
+}
+
+// Filter the emitted findings to the threshold floor (default `notice`). The threshold
+// is validated at the certificate() entry, so it is a known severity here; `counts` and
+// `worst` are computed before this filter and stay complete.
+function _applyThreshold(report, severity) {
+  var floor = SEVERITY[severity == null ? "notice" : severity];
+  return report.findings.filter(function (f) { return (SEVERITY[f.severity] || 0) >= floor; });
+}
+
+// ---- public surface ----
+
+/**
+ * @primitive  pki.lint.certificate
+ * @signature  pki.lint.certificate(input, opts?) -> LintReport
+ * @since      0.2.10
+ * @status     experimental
+ * @spec       RFC 5280, CA/Browser Forum TLS BR
+ * @related    pki.schema.x509.parse, pki.inspect.certificate, pki.path.validate
+ *
+ * Lint a certificate against the RFC 5280 profile plus a representative CABF TLS BR
+ * subset. `input` is a PEM string, a DER `Buffer`, or an already-parsed
+ * `pki.schema.x509` object. Returns a `LintReport`
+ * `{ findings: [{id, severity, source, citation, message, context?}], counts, worst, ran }`.
+ *
+ * The DATA path never throws: hostile bytes produce a single `fatal` finding
+ * `lint/unparseable` rather than raising. The ONLY throw path is config-time misuse
+ * (`opts.profile` unknown, `opts.severity` out of range, or a wrong-type input) -- a
+ * typed `LintError`.
+ *
+ * @opts  profile   One of `pki.lint.profiles()` (default runs every profile). Selecting
+ *                  `"cabf-tls"` lints the input AS a TLS server certificate.
+ * @opts  severity  Suppress findings below this floor (default `"notice"`). `counts` and
+ *                  `worst` always reflect the complete, unfiltered result.
+ * @example
+ *   var report = pki.lint.certificate(pemString);
+ *   report.worst;                              // "notice" | "error" | ...
+ *   report.findings.map(function (f) { return f.id; });
+ */
+function certificate(input, opts) {
+  opts = opts || {};
+  if (typeof opts !== "object") throw _cfg("lint/bad-input", "pki.lint options must be an object");
+  // Validate BOTH config options up front so a config error fails fast, before any work.
+  if (opts.severity != null && VALID_SEVERITY.indexOf(opts.severity) === -1) {
+    throw _cfg("lint/bad-severity", "unknown severity threshold \"" + opts.severity + "\" (known: " + VALID_SEVERITY.join(", ") + ")");
+  }
+  var rules = _selectRules(opts.profile);
+  var ingested = _ingest(input);
+  var report;
+  if (ingested.fatal) {
+    report = { findings: [ingested.fatal], counts: { fatal: 1, error: 0, warn: 0, notice: 0, pass: 0, na: 0, ne: 0 }, ran: [] };
+  } else {
+    var ctx = _makeCtx(ingested.cert, opts.profile);
+    report = _runLints(rules, ingested.cert, ctx);
+  }
+  report.worst = _worst(report.findings);
+  report.findings = _applyThreshold(report, opts.severity);
+  return report;
+}
+
+/**
+ * @primitive  pki.lint.rules
+ * @signature  pki.lint.rules(profile?) -> [{id, severity, source, citation}]
+ * @since      0.2.10
+ * @status     experimental
+ * @spec       RFC 5280, CA/Browser Forum TLS BR
+ *
+ * Enumerate the rule registry (all rules, or one profile's). Each entry exposes its
+ * stable `id`, `severity`, `source`, and spec-clause `citation` for documentation and
+ * corpus tooling.
+ * @example
+ *   pki.lint.rules("rfc5280").length;   // -> a positive count
+ */
+function rules(profile) {
+  var set = profile == null ? ALL_RULES : (PROFILES[profile] || (function () { throw _cfg("lint/unknown-profile", "unknown lint profile \"" + profile + "\""); })());
+  return set.map(function (r) { return { id: r.id, severity: r.severity, source: r.source, citation: r.citation }; });
+}
+
+/**
+ * @primitive  pki.lint.profiles
+ * @signature  pki.lint.profiles() -> [string]
+ * @since      0.2.10
+ * @status     experimental
+ * @spec       RFC 5280, CA/Browser Forum TLS BR
+ *
+ * List the known lint-profile names.
+ * @example
+ *   pki.lint.profiles();   // -> ["rfc5280", "cabf-tls"]
+ */
+function profiles() { return Object.keys(PROFILES); }
+
+module.exports = {
+  certificate: certificate,
+  rules: rules,
+  profiles: profiles,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "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:a09496c1-2301-420c-a786-1cb883b3f77c",
+  "serialNumber": "urn:uuid:63ae20ee-b75f-4b87-9846-27c435f26822",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-13T10:49:09.267Z",
+    "timestamp": "2026-07-13T16:00:51.631Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.9",
+      "bom-ref": "@blamejs/pki@0.2.10",
       "type": "application",
       "name": "pki",
-      "version": "0.2.9",
+      "version": "0.2.10",
       "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.2.9",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.10",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.9",
+      "ref": "@blamejs/pki@0.2.10",
       "dependsOn": []
     }
   ]