@blamejs/pki 0.3.7 → 0.3.8

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.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.

package/README.md

@@ -237,7 +237,7 @@ 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 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` |

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/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.7",
+  "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:dc01f613-ee62-4b7d-b2d5-42e3bb2f5560",
+  "serialNumber": "urn:uuid:7df7ec92-2c30-46ba-acd2-036a52d58ca2",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-18T01:11:02.665Z",
+    "timestamp": "2026-07-18T08:43:20.402Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.3.7",
+      "bom-ref": "@blamejs/pki@0.3.8",
       "type": "application",
       "name": "pki",
-      "version": "0.3.7",
+      "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.7",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.8",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.3.7",
+      "ref": "@blamejs/pki@0.3.8",
       "dependsOn": []
     }
   ]