@blamejs/pki 0.3.6 → 0.3.8

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.3.8 — 2026-07-18
+
+Human-readable inspection extends to CRLs, CSRs, and CMS messages, with a pki.schema.detectFormat companion.
+
+### Added
+
+- pki.inspect.crl / .csr / .cms render a certificate revocation list, a PKCS#10 certification request, and a CMS message as OpenSSL-familiar text reports (openssl crl -text / req -text / cms -cmsout -print), and pki.inspect.any detects the format of a DER/PEM input and routes it to the matching report. Each composes the certificate inspector's shipped field renderers, resolves every extension/attribute/algorithm/content-type OID through the registry (unknown -> dotted, undecodable value -> raw octets), and is best-effort: a malformed part hex-dumps rather than failing the report, and only entry-point coercion throws (inspect/bad-crl / inspect/bad-csr / inspect/bad-cms / inspect/unsupported-format). Cross-checked field-for-field against OpenSSL. RFC 5280 / RFC 2986 / RFC 5652.
+- pki.schema.detectFormat(input) returns the registered PKI format name a DER Buffer or PEM string encodes -- one of pki.schema.all() -- without parsing it, or null when it matches no registered format. The detection half of pki.schema.parse, over the same authoritative format ordering.
+
+## v0.3.7 — 2026-07-17
+
+Certification path building arrives as pki.path.build, and pki.lint gains seven RFC 5280 extension-criticality and CA-scope lints.
+
+### Added
+
+- pki.path.build(leaf, opts) discovers the ordered certification path from a leaf up to a trust anchor over an untrusted pool of candidate CA certificates, then validates it -- the discovering complement of pki.path.validate. Candidates are matched by RFC 5280 name chaining, prioritized by the RFC 4158 heuristics (subjectKeyIdentifier/authorityKeyIdentifier match, anchor-adjacent issuer, CA and keyCertSign, validity), and searched depth-first with backtracking; every accept flows through pki.path.validate, so a name or key-identifier match is only an ordering hint and building never weakens a path-validation check. The search is bounded (a chain-length cap, a total-work cap on candidate expansions, and an identity-tuple visited-set) so a cross-certificate cycle or Bridge-CA fan-out terminates deterministically; the trust store accepts anchor tuples or self-signed root certificates, opts.validate:false returns the ordered path unvalidated, and the verdict is cross-checked against openssl verify. AIA caIssuers fetching is offline-only (supply fetched issuers in opts.candidates). RFC 4158 / RFC 5280.
+- pki.lint.certificate flags seven RFC 5280 extension-criticality and CA-scope violations that parse but breach the certificate profile: basicConstraints (on a certificate-signing CA), nameConstraints, policyConstraints, and inhibitAnyPolicy must be marked critical (error); keyUsage should be critical (warn); nameConstraints must appear only in a CA certificate (error); and an end-entity certificate should carry a subjectKeyIdentifier (notice). The basicConstraints criticality rule applies only when the CA key validates certificate signatures (RFC 5280 4.2.1.9), so a CRL-signing-only CA carrying a non-critical basicConstraints is not falsely flagged.
+
 ## v0.3.6 — 2026-07-17
 
 pki.cmp.build gains the CA/responder side -- certificate, revocation, key-recovery, general, error, poll, and confirmation responses complete the RFC 9810 message surface.

package/README.md

@@ -221,7 +221,7 @@ is callable today; nothing below is a stub.
 | `pki.acme` | RFC 8555 / 8737 / 8738 / 9773 ACME message layer over `pki.jose` — resource-object validators (closed status enums, conditional-required fields, unknown fields ignored), the three §7.1.6 state machines, request builders (newAccount + EAB, newOrder + `replaces`, finalize with CSR identifier-set match and account-key-reuse rejection, challenge responses, deactivation, revokeCert in both key modes, the keyChange nested JWS, POST-as-GET), the http-01 / dns-01 / tls-alpn-01 challenge computations, the dns/ip identifier validators, and the ARI certID (serial sign-padding preserved). A message layer, not an HTTP client — transport-injectable, fail-closed — `validate`, `identify`, `assertTransition`, the builders, `keyAuthorization`, `http01`, `dns01`, `tlsAlpn01Extension`, `verifyTlsAlpn01`, `ariCertId` |
 | `pki.schema.smime` | Decode S/MIME ESS signed-attribute values (RFC 5035 / RFC 8551) — `parseSigningCertificate` / `parseSigningCertificateV2` bind a signature to its signing certificate (cert hash, hash algorithm, issuer `GeneralNames` + serial), `parseSmimeCapabilities` decodes the ordered capability list, and `decodeAttribute` OID-dispatches a CMS attribute (enforcing the single-value rule, recognize-and-defer for unknown types). A companion decoder for CMS signed attributes, not an auto-routed format, fail-closed — `parseSigningCertificate`, `parseSigningCertificateV2`, `parseSmimeCapabilities`, `decodeAttribute` |
 | `pki.schema.engine` | The declarative ASN.1 structure-schema engine every format parser composes — `walk` / `encode` / `embeddedDer` plus the schema combinators |
-| `pki.path` | RFC 5280 §6 certification-path validation — `validate` runs the §6.1 state machine (signature chaining across RSA, ECDSA, EdDSA, ML-DSA, SLH-DSA and hybrid composite ML-DSA signatures — a composite is accepted only when **both** its post-quantum and traditional components verify; validity windows, name chaining, basic constraints and path length, key usage, name constraints, the certificate-policy tree) over an ordered path and a trust anchor, returning a structured verdict with per-check reason codes, and enforces a `pki.trust` anchor's per-purpose distrust-after dates and delegator purposes via `checkPurpose`; `crlChecker` supplies CRL-based revocation — including partitioned/sharded CRLs, whose §6.3.3 Distribution Point ↔ IDP correspondence lets a corresponding full-reason shard establish non-revocation — and `ocspChecker` supplies OCSP-based revocation (RFC 6960 — CertID binding, responder authorization, signature, currency) over the same pluggable hook. Pure and re-entrant, fail-closed — `validate`, `crlChecker`, `ocspChecker` |
+| `pki.path` | RFC 5280 §6 certification-path validation — `validate` runs the §6.1 state machine (signature chaining across RSA, ECDSA, EdDSA, ML-DSA, SLH-DSA and hybrid composite ML-DSA signatures — a composite is accepted only when **both** its post-quantum and traditional components verify; validity windows, name chaining, basic constraints and path length, key usage, name constraints, the certificate-policy tree) over an ordered path and a trust anchor, returning a structured verdict with per-check reason codes, and enforces a `pki.trust` anchor's per-purpose distrust-after dates and delegator purposes via `checkPurpose`; `crlChecker` supplies CRL-based revocation — including partitioned/sharded CRLs, whose §6.3.3 Distribution Point ↔ IDP correspondence lets a corresponding full-reason shard establish non-revocation — and `ocspChecker` supplies OCSP-based revocation (RFC 6960 — CertID binding, responder authorization, signature, currency) over the same pluggable hook. `build(leaf, opts)` is the discovering complement (RFC 4158): from a leaf, an untrusted pool of candidate CA certificates, and a trust store, it finds the ordered leaf→anchor path `validate` accepts — name chaining plus the RFC 4158 §3.5 sort hints (AKI/SKI match, anchor-adjacent issuer, CA + keyCertSign, validity), a depth-first search with backtracking so the first path `validate` accepts wins, and a bounded search (chain-length cap, candidate-expansion cap, identity-tuple visited-set) so a cross-certificate cycle or Bridge-CA fan-out terminates deterministically; every accept flows through `validate` and its verdict is cross-checked against `openssl verify`. Pure and re-entrant, fail-closed — `validate`, `build`, `crlChecker`, `ocspChecker` |
 | `pki.x509` | X.509 certificate issuance (RFC 5280 §4) — `sign(spec, issuer, opts)` builds and signs a certificate: a `spec` of subject (a common-name string, an array of RDNs, or raw Name DER), the public key being certified, the validity window, an optional serial, and an optional `extensions` object; an `issuer` that is a key alone (self-signed — issuer equals subject, signed with that key) or a name + public key + key, or an issuing certificate + key (CA-signed). The signature algorithm is resolved from the signing key through the shared registry, so RSA (PKCS#1 v1.5 / PSS via `opts.pss`), ECDSA P-256/384/521, Ed25519, Ed448, ML-DSA-44/65/87, the twelve SLH-DSA sets, and the composite arms all issue without a per-algorithm branch. It encodes basic constraints, key usage, extended key usage, subject and authority key identifiers (the SKI auto-derived by SHA-1 of the subject key), subject alternative names, and certificate policies from the spec — any other extension supplied as pre-encoded DER — derives the version from the field set, and enforces the serial bounds, the UTCTime/GeneralizedTime cutover, the DER default omissions, and the CA cross-field rules; a violation throws a typed `CertificateError`. Returns DER, or a PEM `CERTIFICATE` with `opts.pem`; every arm is independently verified by OpenSSL. Parsing stays at `pki.schema.x509.parse` — `sign` |
 | `pki.csr` | PKCS#10 certification-request issuance (RFC 2986 / RFC 2985) — `sign(spec, key, opts)` builds and signs a `CertificationRequest`: a `spec` of subject (a common-name string, an array of RDNs, or raw Name DER; may be empty), the public key being certified, an optional `extensionRequest` (requested v3 extensions — subject alternative names, key usage, extended key usage, basic constraints, certificate policies, subject key identifier, or an array of pre-encoded Extension DER — that a CA copies into the issued certificate), and an optional `challengePassword`. `key` (or `{ key }`) is the subject's own private key: the request is self-signed to prove possession of the private half of `subjectPublicKey`, and that proof is verified before the request is returned (what `openssl req -verify` checks). The signature algorithm is resolved from the subject key, so RSA (PKCS#1 v1.5 / PSS via `opts.pss`), ECDSA, EdDSA, ML-DSA, SLH-DSA, and the composite arms all sign without a per-algorithm branch. Returns DER, or a PEM `CERTIFICATE REQUEST` with `opts.pem`; malformed input throws a typed `CsrError`. Parsing stays at `pki.schema.csr.parse` — `sign` |
 | `pki.attrcert` | RFC 5755 attribute-certificate issuance — `sign(spec, issuer, opts)` builds and signs an `AttributeCertificate` as an Attribute Authority: a `spec` of `holder` (exactly one of an entity name, a `baseCertificateID` public-key-certificate reference, a `fromCertificate` binding derived from a certificate, or an object digest), the validity window (GeneralizedTime), an optional serial (positive, ≤ 20 octets; randomly generated when omitted), the `attributes` (the privilege syntaxes — role, clearance, group, chargingIdentity, accessIdentity, authenticationInfo — or pre-encoded Attribute DER), and optional `extensions` (auditIdentity, targetInformation, noRevAvail, aaControls, acProxying, authorityKeyIdentifier, or pre-encoded Extension DER, each with its RFC 5755 criticality). An attribute certificate is never self-signed — the `issuer` is the signing AA, supplied as `{ cert, key }` or `{ name, publicKey, key }`. The signature algorithm is resolved from the AA key, so RSA (PKCS#1 v1.5 / PSS via `opts.pss`), ECDSA, EdDSA, ML-DSA, SLH-DSA, and the composite arms all sign without a per-algorithm branch, and the signature is verified under the AA public key before the certificate is returned. Returns DER, or a PEM `ATTRIBUTE CERTIFICATE` with `opts.pem`; malformed input throws a typed `AttrCertError`. Parsing stays at `pki.schema.attrcert.parse` — `sign` |
@@ -237,9 +237,9 @@ is callable today; nothing below is a stub.
 | `pki.shbs` | Stateful hash-based signature **verification** — HSS/LMS (RFC 8554), carried in X.509 by RFC 9802 and CMS by RFC 9708, profiled by NIST SP 800-208 (CNSA 2.0 firmware signing). `verify` checks an HSS signature (every level must pass) and `verifyLms` a single-tree LMS, over the raw public-key / signature blobs the parsers already surface. Pure public-input SHA-256 / SHAKE256 hashing, a data-driven typecode registry, bounds-before-slice reads; a malformed blob throws a typed `ShbsError`, a well-formed-but-wrong signature returns `false`. **Verify only by design** — stateful signing needs atomic one-time-key state that belongs in an HSM — `verify`, `verifyLms` |
 | `pki.hpke` | Hybrid Public Key Encryption (RFC 9180) — the encrypt-to-a-public-key primitive behind TLS ECH, MLS, and OHTTP. `setupS`/`setupR` establish a sender/recipient context (KEM encapsulation + HKDF key schedule); the context's `seal`/`open` AEAD-encrypt with a sequence-counter nonce and `export` derives further secrets; `seal`/`open` are single-shot wrappers. DHKEM (P-256, P-521, X25519, X448) × HKDF-SHA256/SHA512 × AES-GCM/ChaCha20Poly1305/export-only × all four modes, proven against the RFC 9180 Appendix A vectors. DHKEM(P-384) and HKDF-SHA384 are RFC-registered but Appendix A ships no vector for them, so they fail closed until an authoritative KAT exists. Pure composition over `node:crypto`; ML-KEM / X-Wing are a registry data-row extension pending stable drafts — `suites`, `setupS`, `setupR`, `seal`, `open` |
 | `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.inspect` | Human-readable inspection — the pure-JS equivalent of `openssl x509/crl/req/cms -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. `crl` / `csr` / `cms` render the non-certificate formats the same way — a CRL like `openssl crl -text` (issuer, Last/Next Update, CRL extensions, each revoked entry with its serial, revocation date, and named reason), a CSR like `openssl req -text` (subject, key, requested extensions and attributes), and a CMS message like `openssl cms -cmsout -print` (a SignedData's content type, digest algorithms, embedded certificates, and each SignerInfo with its signer identifier, algorithms, attributes, and signature; a non-SignedData ContentInfo gets a stable summary) — and `any(input)` detects the format and routes to the right report. Built over the strict parsers and the two-way OID registry, reusing one set of field renderers, so it names extension/algorithm OIDs an OpenSSL build shows only as raw bytes and never drifts. No OpenSSL dependency; the format is stable and OpenSSL-familiar rather than pinned to one OpenSSL version; a malformed part falls back to a hex dump rather than throwing — `certificate`, `crl`, `csr`, `cms`, `any` |
 | `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.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 SC081v3 reducing validity schedule, keyCertSign coherence, extension criticality — basicConstraints/nameConstraints/policyConstraints/inhibitAnyPolicy must be critical and keyUsage should be, nameConstraints CA-scope, unknown critical extensions, empty-subject SAN, SKI/AKI presence including the end-entity subjectKeyIdentifier, 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` / `LintError`, each carrying a stable `code` in `domain/reason` form |
 | `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>`, `pki inspect <cert>`, `pki lint <cert>`, `pki convert <file> --to der\|pem`, `pki verify <cert>... --anchor <cert>`, `pki sign <file> --cert <c> --key <k>` |

package/lib/constants.js

@@ -204,6 +204,17 @@ var LIMITS = {
   // chain's tree holds a handful of nodes; the operator may override via
   // opts.maxPolicyNodes.
   PATH_MAX_POLICY_NODES: 4096,
+  // Certification-path BUILDING bounds (pki.path.build). The pool of candidate
+  // issuers is untrusted, so a cross-certificate cycle or Bridge-CA fan-out can
+  // grow the number and length of candidate paths without bound (RFC 4158 sec.
+  // 8.1). PATH_BUILD_MAX_DEPTH caps the chain length explored from the leaf --
+  // well under PATH_MAX_CERTS so a built path clears the validator's own bound
+  // on hand-off; a real hierarchy is a handful of hops. PATH_BUILD_MAX_CANDIDATES
+  // is the total-work ceiling: the builder ticks it once per candidate-issuer
+  // expansion, so a hostile mesh terminates deterministically. Both are operator
+  // overridable (opts.maxDepth / opts.maxCandidatesConsidered).
+  PATH_BUILD_MAX_DEPTH: 20,
+  PATH_BUILD_MAX_CANDIDATES: 1000,
   // PKCS#12 container ceilings. A PFX carries lists at three altitudes
   // (ContentInfos per AuthenticatedSafe, SafeBags per SafeContents,
   // attributes per bag) and can chain fresh DER blobs inside OCTET STRINGs,

package/lib/inspect.js

@@ -27,6 +27,10 @@ var constants = require("./constants");
 var asn1 = require("./asn1-der");
 var oid = require("./oid");
 var x509 = require("./schema-x509");
+var crl = require("./schema-crl");
+var csr = require("./schema-csr");
+var cms = require("./schema-cms");
+var schemaAll = require("./schema-all");
 var pkix = require("./schema-pkix");
 var guard = require("./guard-all");
 
@@ -590,8 +594,395 @@ function certificate(input) {
   return L.join("\n") + "\n";
 }
 
+// ---- CRL / CSR / CMS coercion (the _parse model, per format) -----------------
+
+// Each fast-path completeness check mirrors _looksParsed: a bare/partial object
+// with only the marker field is NOT a parsed result, so it throws the documented
+// typed inspect/bad-input rather than dereferencing a missing field.
+function _looksParsedCrl(o) {
+  return typeof o.version === "number" && o.issuer && typeof o.issuer === "object" &&
+    o.thisUpdate != null && Array.isArray(o.revokedCertificates) && Array.isArray(o.crlExtensions) &&
+    o.signatureAlgorithm && typeof o.signatureAlgorithm === "object";
+}
+function _looksParsedCsr(o) {
+  return typeof o.version === "number" && o.subject && typeof o.subject === "object" &&
+    o.subjectPublicKeyInfo && typeof o.subjectPublicKeyInfo === "object" &&
+    Array.isArray(o.attributes) && o.signatureAlgorithm && typeof o.signatureAlgorithm === "object";
+}
+function _looksParsedCms(o) {
+  if (typeof o.contentType !== "string" || typeof o.contentTypeName !== "string" || typeof o.version !== "number") return false;
+  // A real parse result is one of the six dispatched content types AND carries that type's
+  // required structural fields (_CMS_SHAPE). An unrecognized contentType, or a recognized one
+  // missing its fields, is not a parse result: fail closed as inspect/bad-input, not a partial render.
+  var shape = _CMS_SHAPE[o.contentType];
+  return shape ? shape(o) : false;
+}
+// The shared inspect coercion boundary, composed by every direct inspector AND any():
+// pemLabel:null unwraps a PEM string OR a PEM-armored Buffer (a .pem read with
+// fs.readFileSync) under ANY block label -- so an aliased label (PKCS7 for CMS,
+// CRL for an X509 CRL) routes like any() instead of hitting a canonical-label
+// mismatch -- while a raw DER Buffer / Uint8Array passes through the detached-store guard.
+var _INSPECT_ENTRY = { pemLabel: null, PemError: InspectError, ErrorClass: InspectError, prefix: "inspect" };
+// A parameterized _parse clone: marker field, fast-path completeness check, then
+// the shared label-agnostic coercion to DER, then parse(der) inside try.
+function _coerce(input, spec) {
+  if (input && typeof input === "object" && !Buffer.isBuffer(input) && !(input instanceof Uint8Array) && input[spec.marker] !== undefined) {
+    if (!spec.looksParsed(input)) throw _err("inspect/bad-input", "input has a " + spec.marker + " property but is not a complete " + spec.parsedName + " result");
+    return input;
+  }
+  var der;
+  // Compose the ONE coercion every format parser + any() use, so a PEM string and a
+  // PEM-armored Buffer unwrap under any label (not just the format's canonical one)
+  // and a detached-store Buffer fails closed here, not divergently per inspector.
+  try { der = pkix.coerceToDer(input, _INSPECT_ENTRY); }
+  catch (e) { throw _err("inspect/bad-input", "input must be a parsed " + spec.what + ", a DER Buffer, or a PEM block", e); }
+  try { return spec.parse(der); }
+  catch (e) { throw _err(spec.badCode, "input is not a well-formed " + spec.what, e); }
+}
+function _parseCrl(input) { return _coerce(input, { marker: "thisUpdate", looksParsed: _looksParsedCrl, parsedName: "pki.schema.crl.parse", parse: crl.parse, badCode: "inspect/bad-crl", what: "X.509 CRL" }); }
+function _parseCsr(input) { return _coerce(input, { marker: "certificationRequestInfoBytes", looksParsed: _looksParsedCsr, parsedName: "pki.schema.csr.parse", parse: csr.parse, badCode: "inspect/bad-csr", what: "PKCS#10 certification request" }); }
+function _parseCms(input) { return _coerce(input, { marker: "contentType", looksParsed: _looksParsedCms, parsedName: "pki.schema.cms.parse", parse: cms.parse, badCode: "inspect/bad-cms", what: "CMS message" }); }
+
+// ---- shared attribute-value renderer (CSR attributes + CMS signed/unsigned) ---
+
+// Attribute/extension dispatch keys on the STABLE OID, never the display name a
+// pki.oid.register() override can change (the schema stores the overridden name).
+var OID_EXTENSION_REQUEST = oid.byName("extensionRequest");
+var OID_CONTENT_TYPE = oid.byName("contentType");
+var OID_MESSAGE_DIGEST = oid.byName("messageDigest");
+var OID_SIGNING_TIME = oid.byName("signingTime");
+
+// Decode the known content-binding attribute types for display; anything else, or
+// a decode failure, falls back to printable-or-hex. Never throws once parsed.
+// Keyed on the attribute's OID (stable), not its display name (register-mutable).
+function _attrValue(typeOid, rawDer, inner) {
+  try {
+    if (typeOid === OID_CONTENT_TYPE) { var ct = asn1.read.oid(asn1.decode(rawDer)); return inner + (oid.name(ct) || ct); }
+    if (typeOid === OID_MESSAGE_DIGEST) return _hexColon(asn1.read.octetString(asn1.decode(rawDer)), { wrap: 16, indent: inner.length });
+    if (typeOid === OID_SIGNING_TIME) return inner + _date(asn1.read.time(asn1.decode(rawDer)));
+  } catch (_e) { /* fall through to the raw fallback */ }
+  return _fallback(rawDer, inner);
+}
+
+// ---- CRL report --------------------------------------------------------------
+
+// The CRL decoder PRE-DECODES three extension values to a JS type (not the raw
+// Buffer the shared _extension consumes): cRLNumber -> BigInt, reasonCode ->
+// Number, invalidityDate -> Date. Dispatch on the STABLE OID exactly as the decoder
+// does (schema-crl decodeExt), NOT the display name -- pki.oid.register() can override
+// a built-in name, which would skip these branches and hand _extension a non-Buffer
+// value (rendering "(empty)" for the CRL number or reason). deltaCRLIndicator is a
+// raw-Buffer extension the decoder does NOT pre-decode, but its value is a bare INTEGER
+// (BaseCRLNumber) the operator needs in decimal to relate a delta CRL to its base -- so
+// decode it here for display (best-effort: a malformed value falls through to hex).
+// Delegate every other raw-value extension (AKI / IDP / freshestCRL / certificateIssuer)
+// to the shared _extension verbatim.
+var OID_CRL_NUMBER = oid.byName("cRLNumber");
+var OID_REASON_CODE = oid.byName("reasonCode");
+var OID_INVALIDITY_DATE = oid.byName("invalidityDate");
+var OID_DELTA_CRL_INDICATOR = oid.byName("deltaCRLIndicator");
+function _crlExtension(ext, pad) {
+  var label = EXT_LABEL[ext.name] || ext.name || ext.oid;
+  var header = pad + label + ":" + (ext.critical ? " critical" : "");
+  var inner = pad + "    ";
+  if (ext.oid === OID_CRL_NUMBER && typeof ext.value === "bigint") return header + "\n" + inner + String(ext.value);
+  if (ext.oid === OID_REASON_CODE && typeof ext.value === "number") return header + "\n" + inner + (NAMES.CRL_REASON[ext.value] || String(ext.value));
+  if (ext.oid === OID_INVALIDITY_DATE && ext.value instanceof Date) return header + "\n" + inner + _date(ext.value);
+  if (ext.oid === OID_DELTA_CRL_INDICATOR && Buffer.isBuffer(ext.value)) {
+    try { return header + "\n" + inner + "BaseCRLNumber: " + String(asn1.read.integer(asn1.decode(ext.value))); }
+    catch (_e) { /* malformed BaseCRLNumber -> fall through to the shared _extension (hex) */ }
+  }
+  return _extension(ext, pad);
+}
+
+/**
+ * @primitive pki.inspect.crl
+ * @signature pki.inspect.crl(input) -> string
+ * @since 0.3.8
+ * @status experimental
+ * @spec RFC 5280
+ * @related pki.schema.crl.parse, pki.inspect.certificate
+ *
+ * Render a certificate revocation list as an `openssl crl -text`-familiar text
+ * report: issuer, Last/Next Update, the CRL extensions, each revoked entry (serial,
+ * revocation date, entry extensions), and the signature. `input` is a PEM string, a
+ * DER Buffer, or a `pki.schema.crl.parse` result; a non-CRL throws
+ * `inspect/bad-crl`, a wrong-type input `inspect/bad-input`. A malformed individual
+ * extension renders as hex rather than failing the report.
+ *
+ * @example
+ *   pki.inspect.crl(crlDer).split("\n")[0]; // "Certificate Revocation List (CRL):"
+ */
+function crlReport(input) {
+  var c = _parseCrl(input);
+  var L = ["Certificate Revocation List (CRL):"];
+  L.push("        Version " + c.version + " (0x" + (c.version - 1).toString(16) + ")");
+  L.push("    Signature Algorithm: " + _algName(c.signatureAlgorithm));
+  L.push("        Issuer: " + _dnString(c.issuer));
+  L.push("        Last Update: " + _date(c.thisUpdate));
+  L.push("        Next Update: " + (c.nextUpdate ? _date(c.nextUpdate) : "NONE"));
+  if (c.crlExtensions.length) {
+    L.push("        CRL extensions:");
+    c.crlExtensions.forEach(function (ext) { L.push(_crlExtension(ext, "            ")); });
+  }
+  if (c.revokedCertificates.length) {
+    L.push("Revoked Certificates:");
+    c.revokedCertificates.forEach(function (e) {
+      L.push("    " + _serial(e, 8));
+      L.push("        Revocation Date: " + _date(e.revocationDate));
+      if ((e.crlEntryExtensions || []).length) {
+        L.push("        CRL entry extensions:");
+        e.crlEntryExtensions.forEach(function (ext) { L.push(_crlExtension(ext, "            ")); });
+      }
+    });
+  } else {
+    L.push("No Revoked Certificates.");
+  }
+  L.push("    Signature Algorithm: " + _algName(c.signatureAlgorithm));
+  var sig = c.signatureValue && (c.signatureValue.bytes || c.signatureValue);
+  if (Buffer.isBuffer(sig)) { L.push("    Signature Value:"); L.push(_hexColon(sig, { wrap: 16, indent: 8 })); }
+  return L.join("\n") + "\n";
+}
+
+// ---- CSR report --------------------------------------------------------------
+
+function _attribute(attr, pad) {
+  var inner = pad + "    ";
+  // extensionRequest carries decoded RFC 5280 extensions (the cert-extension shape)
+  // -> render each through the shared _extension, identically to a certificate's.
+  if (attr.type === OID_EXTENSION_REQUEST && Array.isArray(attr.extensions)) {
+    var lines = [pad + "Requested Extensions:"];
+    attr.extensions.forEach(function (ext) { lines.push(_extension(ext, inner)); });
+    return lines.join("\n");
+  }
+  var header = pad + (attr.name || oid.name(attr.type) || attr.type) + ":";
+  var vals = (attr.values || []).map(function (v) { return _attrValue(attr.type, v, inner); });
+  return vals.length ? header + "\n" + vals.join("\n") : header;
+}
+
+/**
+ * @primitive pki.inspect.csr
+ * @signature pki.inspect.csr(input) -> string
+ * @since 0.3.8
+ * @status experimental
+ * @spec RFC 2986
+ * @related pki.schema.csr.parse, pki.inspect.certificate
+ *
+ * Render a PKCS#10 certification request as an `openssl req -text`-familiar text
+ * report: subject, the subject public key, the requested extensions and other
+ * attributes, and the signature. `input` is a PEM string, a DER Buffer, or a
+ * `pki.schema.csr.parse` result; a non-CSR throws `inspect/bad-csr`, a wrong-type
+ * input `inspect/bad-input`. Best-effort like `certificate`.
+ *
+ * @example
+ *   pki.inspect.csr(csrDer).split("\n")[0]; // "Certificate Request:"
+ */
+function csrReport(input) {
+  var c = _parseCsr(input);
+  var L = ["Certificate Request:", "    Data:"];
+  L.push("        Version: " + c.version + " (0x" + (c.version - 1).toString(16) + ")");
+  L.push("        Subject: " + _dnString(c.subject));
+  L.push("        Subject Public Key Info:");
+  L.push(_keyBlock(c.subjectPublicKeyInfo, "            "));
+  L.push("        Attributes:");
+  if (c.attributes.length) c.attributes.forEach(function (attr) { L.push(_attribute(attr, "            ")); });
+  else L.push("            (none)");
+  L.push("    Signature Algorithm: " + _algName(c.signatureAlgorithm));
+  var sig = c.signatureValue && (c.signatureValue.bytes || c.signatureValue);
+  if (Buffer.isBuffer(sig)) { L.push("    Signature Value:"); L.push(_hexColon(sig, { wrap: 16, indent: 8 })); }
+  return L.join("\n") + "\n";
+}
+
+// ---- CMS report --------------------------------------------------------------
+
+// Dispatch on the STABLE contentType OID, never the display name: pki.oid.register()
+// lets an application override the built-in "signedData" name, and dispatching on the
+// mutable name would then misroute a valid SignedData to the generic summary.
+var OID_SIGNED_DATA = oid.byName("signedData");
+// pki.schema.cms.parse dispatches ONLY these six RFC 5652 content types (every other
+// OID throws cms/unsupported- or cms/unknown-content-type -- it never yields an object).
+// Each maps to a predicate over the REQUIRED (non-OPTIONAL) fields of its top-level
+// SEQUENCE, so the parsed-object fast path in _looksParsedCms accepts a genuine parse
+// result but a partial/hand-built object (the type OID + name + version, none of the
+// structural fields) fails closed as inspect/bad-input -- the documented boundary.
+function _isObj(x) { return !!x && typeof x === "object"; }
+var _CMS_SHAPE = {};
+_CMS_SHAPE[OID_SIGNED_DATA] = function (o) { return Array.isArray(o.digestAlgorithms) && _isObj(o.encapContentInfo) && Array.isArray(o.signerInfos); };            // sec. 5.1
+_CMS_SHAPE[oid.byName("envelopedData")] = function (o) { return Array.isArray(o.recipientInfos) && _isObj(o.encryptedContentInfo); };                                // sec. 6.1
+_CMS_SHAPE[oid.byName("encryptedData")] = function (o) { return _isObj(o.encryptedContentInfo); };                                                                  // sec. 8
+_CMS_SHAPE[oid.byName("authData")] = function (o) { return Array.isArray(o.recipientInfos) && _isObj(o.macAlgorithm) && _isObj(o.encapContentInfo) && Buffer.isBuffer(o.mac); }; // sec. 9.1
+_CMS_SHAPE[oid.byName("authEnvelopedData")] = function (o) { return Array.isArray(o.recipientInfos) && _isObj(o.encryptedContentInfo) && Buffer.isBuffer(o.mac); };                // RFC 5083 (build surfaces encryptedContentInfo)
+_CMS_SHAPE[oid.byName("compressedData")] = function (o) { return _isObj(o.compressionAlgorithm) && _isObj(o.encapContentInfo); };                                   // RFC 3274
+
+// Coverage residuals in the report assemblers -- verified-hard-to-reach, not gaps:
+//   * The `x.bytes || x` / `oid.name(o) || o` / `a.name || oid.name || a.type` fallbacks are
+//     belts for shapes the strict parsers never produce (a parsed CSR always carries
+//     signatureValue.bytes; a decoded algorithm always names its OID) -- they mirror
+//     certificate()'s own defensive fallbacks.
+//   * The embedded-CRL delegation and the CONTEXT-tagged embedded-element summary need a CMS
+//     carrying a crls element or an attribute-certificate CHOICE alternative, and the
+//     AuthenticatedData macAlgorithm / countersignature-unsignedAttrs arms need CMS shapes the
+//     toolkit's own producers (cms.sign / encrypt / compress) do not emit; every such arm is
+//     driven best-effort (never throws) and its structural sibling (embedded Certificate,
+//     envelopedData recipientInfo, CompressedData compressionAlgorithm, signed attributes) is
+//     covered.
+
+// An embedded certificate/CRL element {bytes,tagClass,tagNumber}: a UNIVERSAL
+// SEQUENCE is a real Certificate/CertificateList -> delegate to the full sub-report
+// (guarded; a one-line summary on any failure); a CONTEXT-tagged CHOICE alternative
+// (attribute certificate / other) renders a one-line tag+size summary, never parsed.
+function _cmsEmbedded(kind, el, pad) {
+  if (el.tagClass === "universal") {
+    try {
+      var sub = (kind === "CRL") ? crlReport(el.bytes) : certificate(el.bytes);
+      return pad + kind + ":\n" + sub.replace(/\n$/, "").split("\n").map(function (l) { return pad + "    " + l; }).join("\n");
+    } catch (_e) { /* fall through to the summary */ }
+  }
+  return pad + kind + " [" + el.tagClass + " " + el.tagNumber + "] (" + el.bytes.length + " bytes)";
+}
+
+function _signerInfoAttrs(title, attrs, pad) {
+  var lines = [pad + title + ":"];
+  var inner = pad + "    ";
+  attrs.forEach(function (a) {
+    var vals = (a.values || []).map(function (v) { return _attrValue(a.type, v, inner + "    "); });
+    lines.push(inner + (a.name || oid.name(a.type) || a.type) + ":");
+    vals.forEach(function (v) { lines.push(v); });
+  });
+  return lines.join("\n");
+}
+
+function _signerInfo(si, pad) {
+  var inner = pad + "    ";
+  var L = [pad + "SignerInfo:", inner + "Version: " + si.version];
+  if (si.sid && si.sid.serialNumberHex !== undefined) {
+    L.push(inner + "Issuer: " + _dnString(si.sid.issuer));
+    L.push(inner + _serial(si.sid, pad.length + 8));
+  } else if (si.sid && Buffer.isBuffer(si.sid.subjectKeyIdentifier)) {
+    L.push(inner + "Subject Key Identifier: " + _hexColon(si.sid.subjectKeyIdentifier, {}));
+  }
+  L.push(inner + "Digest Algorithm: " + _algName(si.digestAlgorithm));
+  if (si.signedAttrs && si.signedAttrs.length) L.push(_signerInfoAttrs("Signed Attributes", si.signedAttrs, inner));
+  L.push(inner + "Signature Algorithm: " + _algName(si.signatureAlgorithm));
+  if (si.unsignedAttrs && si.unsignedAttrs.length) L.push(_signerInfoAttrs("Unsigned Attributes", si.unsignedAttrs, inner));
+  if (Buffer.isBuffer(si.signature)) { L.push(inner + "Signature Value:"); L.push(_hexColon(si.signature, { wrap: 16, indent: pad.length + 8 })); }
+  return L.join("\n");
+}
+
+/**
+ * @primitive pki.inspect.cms
+ * @signature pki.inspect.cms(input) -> string
+ * @since 0.3.8
+ * @status experimental
+ * @spec RFC 5652
+ * @related pki.schema.cms.parse, pki.inspect.certificate
+ *
+ * Render a CMS message as an `openssl cms -cmsout -print`-familiar text report. A
+ * SignedData shows the content type, digest algorithms, encapsulated content,
+ * embedded certificates/CRLs, and each SignerInfo (signer identifier, algorithms,
+ * signed/unsigned attributes, signature); a non-SignedData ContentInfo renders a
+ * stable top-field summary. `input` is a PEM string, a DER Buffer, or a
+ * `pki.schema.cms.parse` result; a non-CMS throws `inspect/bad-cms`. Best-effort.
+ *
+ * @example
+ *   pki.inspect.cms(cmsDer).split("\n")[0]; // "CMS ContentInfo:"
+ */
+// A ContentInfo whose content type pki.schema.cms.parse does not dispatch (id-data,
+// digestedData, ...) is a VALID CMS the parser defers, not a malformed message -- render an
+// outer-only summary (the named content type) rather than failing the report.
+function _cmsOuterSummary(input) {
+  var ct = null;
+  try {
+    var der = pkix.coerceToDer(input, _INSPECT_ENTRY);
+    ct = asn1.read.oid(asn1.decode(der).children[0]);
+  } catch (_e) { /* best-effort: name unknown */ }
+  return "CMS ContentInfo:\n    Content Type: " + (ct ? (oid.name(ct) || ct) + " (" + ct + ")" : "unknown") +
+    "\n    (content type not further parsed; outer ContentInfo only)\n";
+}
+
+function cmsReport(input) {
+  var m;
+  try { m = _parseCms(input); }
+  catch (e) {
+    // A ContentInfo whose contentType the parser does not dispatch is a valid CMS, not a malformed
+    // message: a known-but-deferred type (cms/unsupported-content-type, e.g. id-data) or a private/
+    // unregistered OID (cms/unknown-content-type). Either renders the outer-only summary.
+    var cc = e && e.cause && e.cause.code;
+    if (e && e.code === "inspect/bad-cms" && (cc === "cms/unsupported-content-type" || cc === "cms/unknown-content-type")) return _cmsOuterSummary(input);
+    throw e;
+  }
+  var L = ["CMS ContentInfo:"];
+  L.push("    Content Type: " + (m.contentTypeName || oid.name(m.contentType) || m.contentType) + " (" + m.contentType + ")");
+  if (m.contentType === OID_SIGNED_DATA) {
+    L.push("    SignedData:");
+    L.push("        Version: " + m.version);
+    L.push("        Digest Algorithms:");
+    (m.digestAlgorithms || []).forEach(function (a) { L.push("            " + _algName(a)); });
+    if (m.encapContentInfo) {
+      L.push("        Encapsulated Content Info:");
+      L.push("            Content Type: " + (oid.name(m.encapContentInfo.eContentType) || m.encapContentInfo.eContentType) + " (" + m.encapContentInfo.eContentType + ")");
+      L.push("            " + (m.encapContentInfo.eContent == null ? "<no content (detached)>" : (m.encapContentInfo.eContent.length + " content byte(s)")));
+    }
+    (m.certificates || []).forEach(function (el) { L.push(_cmsEmbedded("Certificate", el, "        ")); });
+    (m.crls || []).forEach(function (el) { L.push(_cmsEmbedded("CRL", el, "        ")); });
+    (m.signerInfos || []).forEach(function (si) { L.push(_signerInfo(si, "        ")); });
+  } else {
+    // Non-SignedData: a stable top-field summary (no plaintext to show); never throws.
+    L.push("    " + (m.contentTypeName || "content") + ":");
+    if (m.version != null) L.push("        Version: " + m.version);
+    (m.recipientInfos || []).forEach(function (ri) { L.push("        RecipientInfo: " + (ri.type || "?") + (ri.ridType ? " (" + ri.ridType + ")" : "")); });
+    if (m.encryptedContentInfo) {
+      L.push("        Content Type: " + (oid.name(m.encryptedContentInfo.contentType) || m.encryptedContentInfo.contentType));
+      if (m.encryptedContentInfo.contentEncryptionAlgorithm) L.push("        Content Encryption Algorithm: " + _algName(m.encryptedContentInfo.contentEncryptionAlgorithm));
+    }
+    if (m.macAlgorithm) L.push("        MAC Algorithm: " + _algName(m.macAlgorithm));
+    if (m.compressionAlgorithm) L.push("        Compression Algorithm: " + _algName(m.compressionAlgorithm));
+  }
+  return L.join("\n") + "\n";
+}
+
+// ---- unified detect-and-dispatch ---------------------------------------------
+
+var _INSPECT_BY_FORMAT = { x509: certificate, crl: crlReport, csr: csrReport, cms: cmsReport };
+
+/**
+ * @primitive pki.inspect.any
+ * @signature pki.inspect.any(input) -> string
+ * @since 0.3.8
+ * @status experimental
+ * @spec RFC 5280
+ * @related pki.schema.detectFormat, pki.inspect.certificate
+ *
+ * Detect which PKI format `input` (a PEM string or DER Buffer) encodes and render
+ * it with the matching report -- the inspect analogue of `pki.schema.parse`. Routes
+ * a certificate / CRL / CSR / CMS to `certificate` / `crl` / `csr` / `cms`; a
+ * detected but out-of-scope format (OCSP, TSP, PKCS#8/#12, CRMF, CMP, ...) throws
+ * `inspect/unsupported-format` naming it, and an unrecognized input
+ * `inspect/bad-input`.
+ *
+ * @example
+ *   pki.inspect.any(der);  // routes to the right report by detected format
+ */
+function any(input) {
+  // Unwrap to DER ONCE (any PEM label), detect from the DER, then route the DER Buffer -- the
+  // renderer parses a Buffer directly and never re-applies its own strict PEM label.
+  var der, fmt;
+  try {
+    der = pkix.coerceToDer(input, _INSPECT_ENTRY);
+    fmt = schemaAll.detectFormat(der);   // decodes the root -- a non-DER Buffer throws here, not at coerce
+  } catch (e) { throw _err("inspect/bad-input", "input is not a decodable DER Buffer or PEM string", e); }
+  if (fmt === null) throw _err("inspect/bad-input", "input does not match any registered PKI format");
+  var render = _INSPECT_BY_FORMAT[fmt];
+  if (!render) throw _err("inspect/unsupported-format", "inspect does not support the detected format \"" + fmt + "\" (supported: certificate, crl, csr, cms)");
+  return render(der);
+}
+
 module.exports = {
   certificate: certificate,
+  crl: crlReport,
+  csr: csrReport,
+  cms: cmsReport,
+  any: any,
   // The extension names certificate() renders to their decoded values (vs the raw
   // hex fallback). The inspect test asserts this covers every extension the shared
   // decoders decode, so a newly-decodable extension cannot silently hex-dump.

package/lib/lint.js

@@ -297,6 +297,18 @@ function _ecCurveName(spki) {
   } catch (_e) { return null; }   // explicit / invalid EC parameters are not an approved named curve
 }
 
+// RFC 5280 marks several extensions MUST (error) or SHOULD (warn) be critical. The shape is
+// uniform: applies when the extension is present, fires when its raw `critical` flag is not
+// true. The rule reads `ctx.raw(name).critical` WITHOUT decoding the value -- criticality is
+// a structural property of the extension, independent of its contents.
+function _criticalityRule(name, id, severity, citation, message) {
+  return {
+    id: id, severity: severity, source: "rfc5280", citation: citation, message: message,
+    appliesTo: function (cert, ctx) { return !!ctx.raw(name); },
+    check: function (cert, ctx) { var e = ctx.raw(name); return (e && e.critical !== true) ? true : null; },
+  };
+}
+
 var RFC5280_RULES = [
   {
     id: "lint/rfc5280/serial-not-positive", severity: "error", source: "rfc5280", citation: "RFC 5280 4.1.2.2",
@@ -379,6 +391,51 @@ var RFC5280_RULES = [
     appliesTo: function (cert) { return !!(cert.issuer && cert.subject && cert.issuer.dn !== cert.subject.dn); },
     check: function (cert, ctx) { return ctx.raw("authorityKeyIdentifier") ? null : true; },
   },
+  {
+    // 4.2.1.9: MUST mark basicConstraints critical "in all CA certificates that contain
+    // public keys used to validate digital signatures on certificates" (keyCertSign). A CA
+    // key used exclusively for other purposes (CRL signing, key management) MAY carry a
+    // non-critical basicConstraints, so the rule applies only when keyCertSign is asserted
+    // (or keyUsage is absent) -- gating on cA alone would false-positive on a CRL-signing CA.
+    id: "lint/rfc5280/basic-constraints-not-critical", severity: "error", source: "rfc5280", citation: "RFC 5280 4.2.1.9",
+    message: "a CA certificate that validates certificate signatures must mark basicConstraints critical",
+    appliesTo: function (cert, ctx) {
+      var bc = ctx.decode("basicConstraints");
+      if (!(bc && bc.value && bc.value.cA === true)) return false;
+      var ku = ctx.decode("keyUsage");
+      return !ku || !ku.value || ku.value.keyCertSign === true;
+    },
+    check: function (cert, ctx) { var e = ctx.raw("basicConstraints"); return (e && e.critical !== true) ? true : null; },
+  },
+  _criticalityRule("nameConstraints", "lint/rfc5280/name-constraints-not-critical", "error",
+    "RFC 5280 4.2.1.10", "the nameConstraints extension must be marked critical"),
+  {
+    // 4.2.1.10: "The name constraints extension ... MUST be used only in a CA certificate."
+    id: "lint/rfc5280/name-constraints-not-ca", severity: "error", source: "rfc5280", citation: "RFC 5280 4.2.1.10",
+    message: "the nameConstraints extension must appear only in a CA certificate",
+    appliesTo: function (cert, ctx) { return !!ctx.raw("nameConstraints"); },
+    check: function (cert, ctx) { var bc = ctx.decode("basicConstraints"); return (bc && bc.value && bc.value.cA === true) ? null : true; },
+  },
+  _criticalityRule("policyConstraints", "lint/rfc5280/policy-constraints-not-critical", "error",
+    "RFC 5280 4.2.1.11", "the policyConstraints extension must be marked critical"),
+  _criticalityRule("inhibitAnyPolicy", "lint/rfc5280/inhibit-any-policy-not-critical", "error",
+    "RFC 5280 4.2.1.14", "the inhibitAnyPolicy extension must be marked critical"),
+  // 4.2.1.3: "When present, conforming CAs SHOULD mark this extension as critical." The
+  // recommendation directs the ISSUING CA whenever it includes keyUsage -- in ANY certificate,
+  // including an end-entity leaf -- and does NOT restrict it to certificates whose subject is
+  // itself a CA. So the rule is present-gated (matching zlint's w_ext_key_usage_not_critical),
+  // not CA-subject-gated; a SHOULD, hence warn.
+  _criticalityRule("keyUsage", "lint/rfc5280/key-usage-not-critical", "warn",
+    "RFC 5280 4.2.1.3", "the keyUsage extension should be marked critical"),
+  {
+    // 4.2.1.2: the SKI "SHOULD be included in all end entity certificates" (a SHOULD -> notice).
+    // The CA case is the separate ski-missing rule; this rule gates on the non-CA (leaf) path so
+    // the two are mutually exclusive and every certificate is covered by exactly one.
+    id: "lint/rfc5280/ski-missing-ee", severity: "notice", source: "rfc5280", citation: "RFC 5280 4.2.1.2",
+    message: "an end-entity 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; },
+  },
 ];
 
 function _isTls(cert, ctx) { return ctx.isTlsServerCert; }

package/lib/path-validate.js

@@ -75,6 +75,8 @@ var OID = {
   extKeyUsage: oid.byName("extKeyUsage"),
   anyExtendedKeyUsage: oid.byName("anyExtendedKeyUsage"),
   cRLDistributionPoints: oid.byName("cRLDistributionPoints"),
+  subjectKeyIdentifier: oid.byName("subjectKeyIdentifier"),
+  authorityKeyIdentifier: oid.byName("authorityKeyIdentifier"),
 };
 
 // The set of extension OIDs the validator PROCESSES -- an unrecognized critical
@@ -2024,8 +2026,300 @@ function verifyOcspResponse(parsedResponse, cert, issuerCert, time, opts) {
   });
 }
 
+// ---- certification path BUILDING (pki.path.build, RFC 4158) ----------------
+
+// A soft extension decode for the RFC 4158 sec. 3.5 SORT hints (AKI/SKI/
+// basicConstraints/keyUsage): a present-but-undecodable extension on an
+// UNTRUSTED pool candidate degrades to "no hint", never a hard fail -- the sort
+// weight is advisory, the branch is still tried, and validate is the authority.
+function softDecode(cert, extOid) {
+  try { return decodeExt(cert, extOid); }
+  catch (_e) { return null; }
+}
+
+// dnEqual that fails a control-byte DN (CVE-2009-2408) closed to "not a match"
+// rather than rejecting the whole build -- one malformed pool cert must not
+// poison a buildable path (parity with selfIssued's swallow). The hard
+// name-chaining gate remains validate's own dnEqual over the chosen path.
+function nameMatchSoft(rdnsA, rdnsB) {
+  try { return dnEqual(rdnsA, rdnsB); }
+  catch (_e) { return false; }
+}
+
+// A parsed extension entry the search's findExt dereferences by .oid and, for
+// the subjectAltName, by .value (a Buffer in the identity key).
+function _isExtensionEntry(e) { return !!e && typeof e.oid === "string" && Buffer.isBuffer(e.value); }
+
+// The complete parsed-certificate shape build produces AND hands to validate --
+// every top-level field this module dereferences (grep-verified), each with the
+// type the code assumes. A claimed-parsed object satisfying this cannot throw a
+// raw TypeError anywhere in the search or the validate hand-off.
+function _isParsedCert(o) {
+  return Buffer.isBuffer(o.tbsBytes) &&
+    typeof o.serialNumberHex === "string" &&
+    !!o.signatureAlgorithm && typeof o.signatureAlgorithm.oid === "string" &&
+    !!o.signatureValue && Buffer.isBuffer(o.signatureValue.bytes) &&
+    !!o.validity && o.validity.notBefore instanceof Date && o.validity.notAfter instanceof Date &&
+    !!o.issuer && Array.isArray(o.issuer.rdns) &&
+    !!o.subject && Array.isArray(o.subject.rdns) && Buffer.isBuffer(o.subject.bytes) &&
+    !!o.subjectPublicKeyInfo && Buffer.isBuffer(o.subjectPublicKeyInfo.bytes) &&
+    !!o.subjectPublicKeyInfo.algorithm && typeof o.subjectPublicKeyInfo.algorithm.oid === "string" &&
+    !!o.subjectPublicKeyInfo.publicKey && Buffer.isBuffer(o.subjectPublicKeyInfo.publicKey.bytes) &&
+    typeof o.subjectPublicKeyInfo.publicKey.unusedBits === "number" &&
+    Array.isArray(o.extensions) && o.extensions.every(_isExtensionEntry);
+}
+
+function coerceCert(input) {
+  // An already-parsed certificate is passed through; a DER Buffer / PEM string is
+  // parsed (and its typed error normalized by the caller). A claimed-parsed object
+  // (a truthy tbsBytes) must carry the COMPLETE parsed-certificate shape build and
+  // the validate hand-off dereference -- a bare { tbsBytes } object, or any partial
+  // shape, fails closed here as a typed PathError rather than a raw TypeError deeper
+  // in the walk or inside validate.
+  if (input && typeof input === "object" && !Buffer.isBuffer(input) && input.tbsBytes !== undefined) {
+    if (!_isParsedCert(input)) throw E("path/bad-input", "build: an input has tbsBytes but is not a well-formed parsed certificate");
+    return input;
+  }
+  return x509.parse(input);
+}
+
+// A trust-store entry is either a ready anchor tuple { name, publicKey,
+// algorithm, parameters? } or a self-signed root certificate reduced to that
+// tuple. The algorithm is the SPKI KEY-algorithm OID (the sec. 6.1.4(f)
+// parameter-inheritance value), mirroring trust.js _mkAnchor -- NOT the
+// signature OID. The anchor is an input to validate, never one of the path certs.
+function toAnchor(entry) {
+  if (entry && typeof entry === "object" && !Buffer.isBuffer(entry) && entry.name && entry.publicKey && entry.algorithm) {
+    // A ready anchor tuple: validate the shape build + validate consume -- name.rdns
+    // (name matching), publicKey bytes and the algorithm OID (the sec. 6.1.4 key
+    // hand-off). trustAnchors is a caller option, so a malformed tuple is a config
+    // error and fails closed at entry, not a downstream no-path / soft verdict.
+    if (!Array.isArray(entry.name.rdns) || !Buffer.isBuffer(entry.publicKey) || typeof entry.algorithm !== "string") {
+      throw E("path/bad-input", "build: a trustAnchor tuple must be { name: { rdns: [...] }, publicKey: Buffer, algorithm: OID string }");
+    }
+    return entry;
+  }
+  var cert;
+  try { cert = coerceCert(entry); }
+  catch (e) { throw E("path/bad-input", "build: a trustAnchor entry must be a { name, publicKey, algorithm } tuple or a certificate", e); }
+  var spki = cert.subjectPublicKeyInfo;
+  return { name: cert.subject, publicKey: spki.bytes, algorithm: spki.algorithm.oid, parameters: spki.algorithm.parameters, subjectDer: cert.subject.bytes };
+}
+
+// RFC 4158 sec. 2.4.2 loop key: the (subject DN + subjectAltName + subject
+// public key) tuple, NOT the DN alone. DN-alone keying wrongly prunes a
+// legitimate distinct cross-cert (cross-certs share a DN) and misses a same-key
+// loop; the key differentiates a rollover (same DN, new key) from a true repeat.
+function identityKey(cert) {
+  var san = findExt(cert, OID.subjectAltName);
+  return cert.subject.bytes.toString("hex") + "|" + (san ? san.value.toString("hex") : "") + "|" +
+    cert.subjectPublicKeyInfo.bytes.toString("hex");
+}
+
+function childAkiKeyId(cert) {
+  var d = softDecode(cert, OID.authorityKeyIdentifier);
+  return (d && d.value && d.value.keyIdentifier) ? d.value.keyIdentifier : null;
+}
+
+// RFC 4158 sec. 3.5 candidate prioritization -- a SORT weight, never a gate.
+// Higher = tried first (fewer validate calls to reach a valid path). Every term
+// is a hint: a KID match, an anchor-adjacent issuer, CA + keyCertSign presence,
+// and validity at the check time all raise priority, but a lower-scoring
+// candidate is STILL attempted, and validate makes every accept decision.
+function scoreCandidate(cand, childAki, anchors, time) {
+  var score = 0;
+  if (childAki) {
+    var d = softDecode(cand, OID.subjectKeyIdentifier);
+    if (d && Buffer.isBuffer(d.value) && d.value.equals(childAki)) score += 1000;   // sec. 3.5.12 KID match: heaviest
+  }
+  for (var i = 0; i < anchors.length; i++) {
+    if (nameMatchSoft(cand.issuer.rdns, anchors[i].name.rdns)) { score += 100; break; }   // sec. 3.5.15/.16 anchor-adjacent
+  }
+  var bc = softDecode(cand, OID.basicConstraints);
+  if (bc && bc.value && bc.value.cA === true) score += 10;                          // sec. 3.5.1 basicConstraints cA
+  var ku = softDecode(cand, OID.keyUsage);
+  if (ku && ku.value && ku.value.keyCertSign === true) score += 10;                 // sec. 3.5.3 keyUsage keyCertSign
+  var v = cand.validity;
+  // allow:nan-date-comparison-unguarded -- cand.validity dates are codec-parsed (asn1 readTime rejects a NaN instant) and time is guard.time.assertValid'd at entry; the validity term is a fail-safe sort hint regardless.
+  if (v && v.notBefore instanceof Date && v.notAfter instanceof Date &&
+    v.notBefore.getTime() <= time.getTime() && time.getTime() <= v.notAfter.getTime()) score += 5;   // sec. 3.5.4 validity
+  return score;
+}
+
+/**
+ * @primitive  pki.path.build
+ * @signature  pki.path.build(leaf, opts) -> Promise<{ valid, path, trustAnchor, result, candidatesConsidered }>
+ * @since       0.3.7
+ * @status      experimental
+ * @spec        RFC 4158, RFC 5280
+ * @related     pki.path.validate, pki.schema.x509.parse, pki.trust.parseCertdata
+ *
+ * Discover the ordered certification path from a leaf certificate up to a trust anchor, over an
+ * untrusted pool of candidate CA certificates, then validate it. `build` is the discovering
+ * complement of `validate`: `validate` takes an already-ordered path and a trust anchor and runs
+ * the 6.1 state machine; `build` takes a leaf, an unordered pool of candidate issuers, and a
+ * trust store, and searches for the ordered leaf->anchor path `validate` accepts.
+ *
+ * Candidate issuers are matched by RFC 5280 7.1 name chaining, prioritized by the RFC 4158 3.5
+ * heuristics (a subjectKeyIdentifier/authorityKeyIdentifier match, an anchor-adjacent issuer,
+ * CA + keyCertSign, validity at the check time -- all hints, never filters), and searched
+ * depth-first with backtracking: the first ordered path that `pki.path.validate` accepts wins. A
+ * name or key-identifier match is only an ordering hint; every accept flows through `validate`,
+ * so `build` never weakens or duplicates a 6.1 check. The search over the untrusted pool is
+ * bounded -- a depth cap on chain length, a total-work cap on candidate expansions, and a
+ * visited-set keyed on the (subject, subjectAltName, public key) tuple -- so a cross-certificate
+ * cycle or Bridge-CA fan-out terminates deterministically rather than growing without bound.
+ *
+ * `leaf` is a DER `Buffer`, a PEM string, or an already-parsed `pki.schema.x509` object. Returns
+ * `{ valid, path, trustAnchor, result, candidatesConsidered }`, where `path` is the ordered array
+ * `validate` consumes (anchor-proximal first, leaf last, the anchor excluded). Fail-closed: bad
+ * options throw `path/bad-input`; no chain to any anchor throws `path/no-path`; chains that
+ * assemble but none validate return `{ valid:false }` with the best failing `validate` result;
+ * the search bound throws `path/build-limit`. AIA caIssuers fetching is out of scope -- `build` is
+ * offline (zero network); supply fetched issuers in `opts.candidates`.
+ *
+ * @opts  candidates             The untrusted candidate CA pool (array of DER/PEM/parsed certs; alias `intermediates`).
+ * @opts  trustAnchors           The trust store (non-empty array of `{ name, publicKey, algorithm }` tuples or self-signed root certificates).
+ * @opts  time                   The check date (`Date`, required); forwarded to every internal `validate` call.
+ * @opts  maxDepth               Chain-length depth cap (default `C.LIMITS.PATH_BUILD_MAX_DEPTH`).
+ * @opts  maxCandidatesConsidered  Total-work cap on candidate expansions (default `C.LIMITS.PATH_BUILD_MAX_CANDIDATES`).
+ * @opts  validate               `false` returns the ordered path without validating (pure-builder mode; default `true`).
+ * @opts  (validate options)     Every `pki.path.validate` option (`requiredEku`, `revocationChecker`, `checkPurpose`, the initial policy inputs, ...) is forwarded unchanged.
+ * @example
+ *   var result = await pki.path.build(pemString, {
+ *     candidates: [],              // untrusted intermediates (the openssl -untrusted set)
+ *     trustAnchors: [pemString],   // a self-signed root, or a { name, publicKey, algorithm } tuple
+ *     time: new Date(),
+ *   });
+ *   result.valid;                  // true when a path to a trust anchor was found and validated
+ */
+async function build(leaf, opts) {
+  opts = opts || {};
+  if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw E("path/bad-input", "build: opts must be an object");
+  var leafCert;
+  try { leafCert = coerceCert(leaf); }
+  catch (e) { throw E("path/bad-input", "build: the leaf certificate did not parse", e); }
+
+  var poolInput = opts.candidates !== undefined ? opts.candidates : opts.intermediates;
+  if (poolInput === undefined) poolInput = [];
+  if (!Array.isArray(poolInput)) throw E("path/bad-input", "build: opts.candidates must be an array of certificates");
+  // A pool larger than the absolute ceiling is rejected at entry (bounds the
+  // parse work on an untrusted bundle) -- distinct from the per-search tick
+  // budget below, which an operator may set lower to cap the DFS.
+  var poolCeiling = constants.LIMITS.PATH_BUILD_MAX_CANDIDATES;
+  if (poolInput.length > poolCeiling) throw E("path/bad-input", "build: the candidate pool has " + poolInput.length + " certificates, exceeding the " + poolCeiling + " ceiling");
+  var pool;
+  try { pool = poolInput.map(coerceCert); }
+  catch (e) { throw E("path/bad-input", "build: a candidate certificate did not parse", e); }
+
+  if (!Array.isArray(opts.trustAnchors) || opts.trustAnchors.length === 0) throw E("path/bad-input", "build: opts.trustAnchors must be a non-empty array of anchor tuples or root certificates");
+  var anchors = opts.trustAnchors.map(toAnchor);
+
+  guard.time.assertValid(opts.time, E, "path/bad-input", "build: opts.time (the validity-window check date, forwarded to validate)");
+  // The chain-length bound is tied to the EFFECTIVE maxPathCerts the interleaved
+  // validate uses: a built path holds hop + 1 certificates (the leaf plus each
+  // intermediate), so capping hops at maxPathCerts - 1 keeps every path validate
+  // sees within its own per-path ceiling -- otherwise a maxDepth of maxPathCerts
+  // would assemble a maxPathCerts + 1 path that validate rejects with
+  // path/bad-input. The same cap value is computed the way validate computes it
+  // (opts.maxPathCerts forwarded), and the explicit-stack search below carries no
+  // native-recursion stack risk regardless of the depth.
+  var effectiveMaxCerts = guard.limits.cap(opts.maxPathCerts, "build: opts.maxPathCerts", constants.LIMITS.PATH_MAX_CERTS, { E: E, code: "path/bad-input", min: 1 });
+  // depthCeiling is 0 when maxPathCerts is 1: the only path within the limit is a
+  // single leaf directly under an anchor (a zero-hop search). maxDepth's minimum
+  // is therefore 0, not 1 -- a zero-hop search is legitimate and a maxPathCerts of
+  // 1 must not throw before the anchor is even checked.
+  var depthCeiling = effectiveMaxCerts - 1;
+  var maxDepth = guard.limits.cap(opts.maxDepth, "build: opts.maxDepth", Math.min(constants.LIMITS.PATH_BUILD_MAX_DEPTH, depthCeiling), { E: E, code: "path/bad-input", min: 0, max: depthCeiling });
+  var maxConsidered = guard.limits.cap(opts.maxCandidatesConsidered, "build: opts.maxCandidatesConsidered", poolCeiling, { E: E, code: "path/bad-input", min: 1 });
+  var doValidate = opts.validate !== false;
+
+  // The build-specific options are consumed here; every remaining validate
+  // option is forwarded unchanged to the interleaved validate call. Object.keys
+  // enumerates only own enumerable properties, so no prototype-pollution belt.
+  var BUILD_ONLY_OPT = { candidates: 1, intermediates: 1, trustAnchors: 1, maxDepth: 1, maxCandidatesConsidered: 1, validate: 1 };
+  var forwarded = {};
+  Object.keys(opts).forEach(function (k) { if (!BUILD_ONLY_OPT[k]) forwarded[k] = opts[k]; });
+  function validateOpts(anchor) {
+    var vo = {};
+    Object.keys(forwarded).forEach(function (f) { vo[f] = forwarded[f]; });
+    vo.trustAnchor = anchor;
+    return vo;
+  }
+
+  // The DoS terminator: tick() once per candidate-issuer expansion so a hostile
+  // mesh cannot fan the search without bound (RFC 4158 8.1). A breach throws
+  // path/build-limit. candidatesConsidered mirrors the tick count for the caller.
+  var counter = guard.limits.counter(maxConsidered, E, "path/build-limit", "build: candidate-issuer expansion");
+  var considered = 0;
+  var anyChainAssembled = false;
+  var bestFail = null;
+  var success = null;
+
+  // A bounded, EXPLICIT-stack forward DFS from the leaf toward an anchor -- no
+  // native recursion, so an operator-raised maxDepth cannot overflow the stack
+  // over an untrusted graph. Each frame is a candidate chain [top, ...toward the
+  // leaf] (leaf last) plus the identity keys already on it; a frame is expanded
+  // by prepending a name-chaining issuer. Highest-priority candidates are pushed
+  // LAST so they are popped (explored) FIRST -- depth-first in priority order.
+  // Caps are enforced before every expansion; a candidate whose (subject, SAN,
+  // public key) tuple is already on the chain is a loop and is pruned.
+  var stack = [{ chain: [leafCert], hop: 0, keys: new Set([identityKey(leafCert)]) }];
+  while (stack.length && !success) {
+    var frame = stack.pop();
+    var current = frame.chain[0];
+
+    // Terminate: is `current` issued by a configured anchor? An anchor-adjacent
+    // cert completes a candidate path; validate is the authority on acceptance.
+    // A found path breaks out here and the enclosing while exits on !success.
+    for (var ai = 0; ai < anchors.length; ai++) {
+      if (!nameMatchSoft(current.issuer.rdns, anchors[ai].name.rdns)) continue;
+      if (!doValidate) { success = { path: frame.chain.slice(), trustAnchor: anchors[ai] }; break; }
+      anyChainAssembled = true;
+      var res = await validate(frame.chain, validateOpts(anchors[ai]));
+      if (res.valid) { success = { valid: true, path: frame.chain.slice(), trustAnchor: anchors[ai], result: res }; break; }
+      if (!bestFail) bestFail = { path: frame.chain.slice(), trustAnchor: anchors[ai], result: res };
+    }
+    if (success || frame.hop >= maxDepth) continue;   // depth cap: this branch is exhausted
+
+    var childAki = childAkiKeyId(current);
+    var scored = [];
+    for (var pi = 0; pi < pool.length; pi++) {
+      if (nameMatchSoft(pool[pi].subject.rdns, current.issuer.rdns)) {
+        scored.push({ cand: pool[pi], score: scoreCandidate(pool[pi], childAki, anchors, opts.time) });
+      }
+    }
+    // Ascending sort -> push lowest priority first so the highest is on top.
+    scored.sort(function (a, bb) { return a.score - bb.score; });
+    for (var ci = 0; ci < scored.length; ci++) {
+      counter.tick();          // breadth / total-work cap -> throws path/build-limit
+      considered += 1;
+      var cand = scored[ci].cand;
+      var candKey = identityKey(cand);
+      if (frame.keys.has(candKey)) continue;   // the (subject,SAN,key) tuple is already on this branch -> a loop, prune
+      var childKeys = new Set(frame.keys);
+      childKeys.add(candKey);
+      stack.push({ chain: [cand].concat(frame.chain), hop: frame.hop + 1, keys: childKeys });
+    }
+  }
+
+  if (success) {
+    if (doValidate) return { valid: true, path: success.path, trustAnchor: success.trustAnchor, result: success.result, candidatesConsidered: considered };
+    return { path: success.path, trustAnchor: success.trustAnchor, candidatesConsidered: considered };
+  }
+  if (anyChainAssembled) {
+    // Chains reached an anchor but none validated -> the soft verdict carrying
+    // the best failing validate result (parity with validate; never a throw).
+    return { valid: false, path: bestFail.path, trustAnchor: bestFail.trustAnchor, result: bestFail.result, candidatesConsidered: considered };
+  }
+  // No chain to any configured anchor could even be assembled -- a permanent
+  // structural verdict (name/key chaining dead-ended before the trust store).
+  throw E("path/no-path", "build: no certification path from the leaf to any configured trust anchor could be assembled");
+}
+
 module.exports = {
   validate: validate,
+  build: build,
   crlChecker: crlChecker,
   ocspChecker: ocspChecker,
   verifyOcspResponse: verifyOcspResponse,

package/lib/schema-all.js

@@ -290,6 +290,34 @@ function parse(input) {
   throw new SchemaError("schema/unknown-format", "input does not match any registered PKI format (" + all().join(", ") + ")");
 }
 
+/**
+ * @primitive  pki.schema.detectFormat
+ * @signature  pki.schema.detectFormat(input) -> string | null
+ * @since       0.3.8
+ * @status      experimental
+ * @spec        RFC 5280
+ * @related     pki.schema.parse, pki.schema.all
+ *
+ * Detect which registered PKI format `input` (a DER `Buffer` or PEM string)
+ * encodes and return its name -- one of `pki.schema.all()` -- WITHOUT parsing it,
+ * or `null` when the decoded bytes match no registered format. This is the
+ * detection half of `pki.schema.parse`, running the same authoritative `FORMATS`
+ * ordering, exposed for a caller (e.g. `pki.inspect.any`) that needs the format
+ * name rather than the parsed result. Input that does not decode as DER throws the
+ * same coercion / decode error `parse` throws.
+ *
+ * @example
+ *   pki.schema.detectFormat(der);  // "x509" | "crl" | "csr" | "cms" | ... | null
+ */
+function detectFormat(input) {
+  var der = pkix.coerceToDer(input, ENTRY);
+  var root = pkix.decodeRoot(der, ENTRY);
+  for (var i = 0; i < FORMATS.length; i++) {
+    if (FORMATS[i].detect(root)) return FORMATS[i].name;
+  }
+  return null;
+}
+
 // Curated public surface: each format exposes only its operator primitives. The
 // `matches` detector is internal dispatch infrastructure (used by FORMATS above),
 // not an operator API, so it is NOT re-exported here.
@@ -313,4 +341,5 @@ module.exports = {
   smime: { parseSigningCertificate: smime.parseSigningCertificate, parseSigningCertificateV2: smime.parseSigningCertificateV2, parseSmimeCapabilities: smime.parseSmimeCapabilities, decodeAttribute: smime.decodeAttribute },
   all: all,
   parse: parse,
+  detectFormat: detectFormat,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.3.6",
+  "version": "0.3.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:552d3506-7a4d-4927-bd2e-3faadaa00c02",
+  "serialNumber": "urn:uuid:7df7ec92-2c30-46ba-acd2-036a52d58ca2",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-17T19:50:12.519Z",
+    "timestamp": "2026-07-18T08:43:20.402Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.3.6",
+      "bom-ref": "@blamejs/pki@0.3.8",
       "type": "application",
       "name": "pki",
-      "version": "0.3.6",
+      "version": "0.3.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.3.6",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.8",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.3.6",
+      "ref": "@blamejs/pki@0.3.8",
       "dependsOn": []
     }
   ]