@blamejs/pki 0.2.10 → 0.2.11

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.2.11 — 2026-07-13
+
+The pki command-line tool gains inspect, lint, convert, and verify -- front-ends over the certificate inspector, the linter, the PEM codecs, and RFC 5280 path validation.
+
+### Added
+
+- pki inspect <cert> renders a certificate as an openssl x509 -text style report (composes pki.inspect.certificate).
+- pki lint <cert> [--profile <name>] [--severity <floor>] [--json] lints a certificate against the RFC 5280 and CABF TLS profiles, exiting non-zero when an error or fatal finding is present (composes pki.lint.certificate).
+- pki convert <file> --to der|pem [--label <label>] transcodes between DER and PEM with auto-detected input encoding and byte-exact round-tripping.
+- pki verify <cert>... --anchor <cert> [--time <ISO>] validates an ordered certification path against a trust anchor per RFC 5280 section 6.1 (composes pki.path.validate), exiting non-zero and naming the failing check on rejection.
+
 ## v0.2.10 — 2026-07-13
 
 Certificate linting arrives as pki.lint -- graded, advisory conformance findings against the RFC 5280 profile and a representative CA/Browser Forum TLS Baseline Requirements subset.

package/README.md

@@ -232,7 +232,7 @@ is callable today; nothing below is a stub.
 | `pki.lint` | Certificate linting — the zlint / pkilint of JavaScript. `certificate(pem \| der \| parsed, opts)` walks a parsed certificate and emits graded, advisory findings — each with a stable id, a severity (`fatal` > `error` > `warn` > `notice`), a source, a spec-clause citation, and a message — against the RFC 5280 profile plus a representative CA/Browser Forum TLS BR subset (serial sign/size, validity ordering + the the SC081v3 reducing validity schedule, keyCertSign coherence, unknown critical extensions, empty-subject SAN, SKI/AKI presence, SAN required + CN-in-SAN, dNSName syntax, serverAuth EKU, weak keys). Unlike every other entry the DATA path never throws: hostile bytes return a `fatal` `lint/unparseable` finding (with the strict parser's code) so a whole directory lints without a try/catch; only config-time misuse throws a typed `LintError`. `certificate`, `rules`, `profiles` |
 | `pki.C` / `pki.constants` | Version-stable constants — functional scale helpers (`C.TIME.*`, `C.BYTES.*`), codec `LIMITS`, `version` |
 | `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError` / `Pkcs8Error` / `CmsError` / `OcspError` / `TspError` / `AttrCertError` / `CrmfError` / `Pkcs12Error` / `CmpError` / `PathError` / `CtError` / `JoseError` / `AcmeError` / `WebauthnError` / `LintError`, each carrying a stable `code` in `domain/reason` form |
-| `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>` |
+| `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>` |
 
 ### CLI
 
@@ -241,8 +241,18 @@ pki version                              # @blamejs/pki v0.1.0
 pki oid 1.2.840.113549.1.1.11           # sha256WithRSAEncryption
 pki oid sha256                           # 2.16.840.1.101.3.4.2.1
 pki parse cert.pem                       # structured JSON summary of a certificate
+pki inspect cert.pem                     # openssl x509 -text style report (pki.inspect)
+pki lint cert.pem                        # graded conformance findings; exit 1 on an error
+pki lint cert.pem --json --profile cabf-tls
+pki convert cert.pem --to der > cert.der # transcode between PEM and DER (round-trips)
+pki verify leaf.pem --anchor root.pem --time 2026-01-01T00:00:00Z   # RFC 5280 path validation
 ```
 
+`inspect`/`lint`/`convert`/`verify` are thin front-ends over `pki.inspect`, `pki.lint`, the
+per-format PEM codecs, and `pki.path.validate` — the CLI never does anything the library
+API can't. `lint` exits non-zero when any `error`/`fatal` finding is present; `verify` exits
+non-zero when the path does not validate.
+
 ### What's coming
 
 Certificate build/sign/verify, CMS AuthenticatedData /

package/bin/pki.js

@@ -5,14 +5,21 @@
 /**
  * pki — command-line front-end for @blamejs/pki.
  *
- *   pki version
- *   pki oid <dotted|name>          resolve an OID <-> name
- *   pki parse <cert.pem|cert.der>  parse an X.509 certificate and print
- *                                  its fields as JSON
+ *   pki version                          print the package version
+ *   pki oid <dotted|name>                resolve an OID <-> name
+ *   pki parse <cert>                      parse an X.509 certificate to JSON
+ *   pki inspect <cert>                    render a certificate as text (openssl x509 -text style)
+ *   pki lint <cert> [--profile P]         lint a certificate; exit non-zero on an error finding
+ *              [--severity S] [--json]
+ *   pki convert <file> --to der|pem       transcode a DER/PEM file between the two encodings
+ *              [--label LABEL]
+ *   pki verify <cert>... --anchor <cert>  validate an ordered certification path (anchor->target)
+ *              [--time ISO]
  *
- * The CLI is a thin operator convenience over the library surface; it
- * validates its arguments (entry-point tier — bad input exits non-zero
- * with a message) and never does anything the public API can't.
+ * The CLI is a thin operator convenience over the library surface: it validates its
+ * arguments (entry-point tier — bad input exits non-zero with a message) and never does
+ * anything the public API cannot. inspect / lint / convert / verify compose pki.inspect,
+ * pki.lint, the per-format PEM codecs, and pki.path.validate respectively.
  */
 
 var fs  = require("node:fs");
@@ -23,6 +30,65 @@ function fail(msg) {
   process.exit(1);
 }
 
+// Minimal flag parser: `--flag value` for value-taking flags, `--flag` for booleans, the
+// rest are positionals in `_`. A value-taking flag whose value is absent or is itself another
+// flag is a usage error (never silently coerced to `true`, which would make e.g. `--time`
+// parse as `new Date(true)` = a real 1970 timestamp). No clustering, no `=value`.
+var VALUE_FLAGS = { to: 1, profile: 1, severity: 1, label: 1, anchor: 1, time: 1 };
+function parseArgs(argv) {
+  var out = { _: [] };
+  for (var i = 0; i < argv.length; i++) {
+    var a = argv[i];
+    if (a.indexOf("--") === 0) {
+      var key = a.slice(2);
+      if (VALUE_FLAGS[key]) {
+        if (i + 1 >= argv.length || argv[i + 1].indexOf("--") === 0) fail("--" + key + " requires a value");
+        out[key] = argv[++i];
+      } else { out[key] = true; }
+    } else { out._.push(a); }
+  }
+  return out;
+}
+
+function readFileBytes(file) {
+  try { return fs.readFileSync(file); } catch (e) { return fail("cannot read " + file + ": " + e.message); }
+}
+
+// For the library entry points (parse / inspect / lint / verify) that accept EITHER a DER
+// Buffer or a PEM string and own the decode + error handling: hand a Buffer when the bytes
+// are a well-formed DER structure, otherwise the text so the library pemDecodes it (and
+// applies its own canonical-base64 policy). This defers ALL error handling to the library,
+// which is what preserves the linter's never-throw survey -- malformed bytes become a fatal
+// lint/unparseable finding rather than a CLI hard-fail. DER-first is unambiguous (a PEM file
+// is ASCII text and never decodes as one DER TLV).
+function readForLib(file) {
+  var bytes = readFileBytes(file);
+  try { pki.asn1.decode(bytes); return bytes; }
+  catch (_derErr) { return bytes.toString("latin1"); }   // not DER -- let the library pemDecode / report it
+}
+
+// For `convert`, which transcodes RAW bytes and bypasses the library parse: extract DER
+// explicitly (a well-formed DER file as-is, or a canonical PEM body), failing on anything
+// else. Returns { der, label } where `label` is the PEM armor when the input was PEM.
+function readDer(file) {
+  var bytes = readFileBytes(file);
+  try { pki.asn1.decode(bytes); return { der: bytes, label: null }; }
+  catch (_derErr) { /* not a single well-formed DER structure -- try PEM */ }
+  // Match the library's PEM grammar exactly (an uppercase A-Z0-9 label, and ONLY CR/LF/TAB/
+  // space ignored in the body -- not every JS whitespace), so convert is not a looser
+  // validation path than the codecs it composes.
+  var m = /-----BEGIN ([A-Z0-9 ]+)-----([\s\S]*?)-----END \1-----/.exec(bytes.toString("latin1"));
+  if (!m) return fail(file + ": input is neither a well-formed DER structure nor a PEM block");
+  var b64 = m[2].replace(/[\r\n\t ]+/g, "");
+  // Enforce CANONICAL base64 (RFC 4648 sec. 3.5), matching the library's fail-closed PEM
+  // policy: Node's decoder silently drops invalid characters and tolerates non-canonical
+  // trailing pad bits. Gate alphabet/length, then require that re-encoding reproduces the body.
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(b64) || b64.length % 4 !== 0) return fail(file + ": malformed PEM base64");
+  var der = Buffer.from(b64, "base64");
+  if (der.toString("base64") !== b64) return fail(file + ": non-canonical PEM base64");
+  return { der: der, label: m[1] };
+}
+
 function cmdVersion() {
   process.stdout.write("@blamejs/pki v" + pki.version + "\n");
 }
@@ -41,10 +107,8 @@ function cmdOid(arg) {
 
 function cmdParse(file) {
   if (!file) fail("usage: pki parse <cert.pem|cert.der>");
-  var bytes;
-  try { bytes = fs.readFileSync(file); } catch (e) { return fail("cannot read " + file + ": " + e.message); }
   var cert;
-  try { cert = pki.schema.x509.parse(bytes); } catch (e) { return fail(e.code + ": " + e.message); }
+  try { cert = pki.schema.x509.parse(readForLib(file)); } catch (e) { return fail(e.code + ": " + e.message); }
   var view = {
     version:            cert.version,
     serialNumber:       cert.serialNumberHex,
@@ -59,19 +123,101 @@ function cmdParse(file) {
   process.stdout.write(JSON.stringify(view, null, 2) + "\n");
 }
 
+// pki inspect <cert> -- the human-readable certificate render (pki.inspect.certificate),
+// the pure-JS equivalent of `openssl x509 -text`.
+function cmdInspect(file) {
+  if (!file) fail("usage: pki inspect <cert.pem|cert.der>");
+  try { process.stdout.write(pki.inspect.certificate(readForLib(file))); }
+  catch (e) { return fail(e.code + ": " + e.message); }
+}
+
+function pad(s, n) { while (s.length < n) s += " "; return s; }
+
+// pki lint <cert> -- lint against pki.lint's profiles. Prints one line per finding and
+// exits non-zero when any error/fatal finding is present (0 when the worst is advisory).
+function cmdLint(args) {
+  var file = args._[0];
+  if (!file) fail("usage: pki lint <cert> [--profile <name>] [--severity <floor>] [--json]");
+  var report;
+  // Config-time misuse (unknown profile / bad severity) throws a typed LintError; the data
+  // path never throws (malformed bytes become a fatal lint/unparseable finding).
+  try { report = pki.lint.certificate(readForLib(file), { profile: args.profile, severity: args.severity }); }
+  catch (e) { return fail(e.code + ": " + e.message); }
+  if (args.json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  } else {
+    report.findings.forEach(function (f) {
+      process.stdout.write(pad(f.severity.toUpperCase(), 7) + " " + f.id + " -- " + f.message + "\n");
+    });
+    process.stdout.write("\n" + (report.findings.length || "no") + " finding(s); worst: " + (report.worst || "pass") + "\n");
+  }
+  // Set the exit CODE and let Node drain — process.exit() can truncate a buffered stdout
+  // write to a pipe before it flushes.
+  process.exitCode = (report.counts.error || report.counts.fatal) ? 1 : 0;
+}
+
+// pki convert <file> --to der|pem -- transcode between DER and PEM. The input encoding is
+// auto-detected; the bytes must be well-formed DER (we never wrap/emit garbage).
+function cmdConvert(args) {
+  var file = args._[0], to = args.to;
+  if (!file) fail("usage: pki convert <file> --to der|pem [--label LABEL]");
+  if (to !== "der" && to !== "pem") fail("convert: --to must be 'der' or 'pem'");
+  var input = readDer(file);
+  try { pki.asn1.decode(input.der); } catch (e) { return fail("input is not well-formed DER: " + (e.code || e.message)); }
+  if (to === "der") { process.stdout.write(input.der); return; }
+  var label = args.label || input.label || "CERTIFICATE";
+  // The armor label must be re-readable by the library's PEM grammar (uppercase A-Z0-9 words,
+  // single spaces) -- reject a lowercase/invalid label rather than emit an unparseable file.
+  if (!/^[A-Z0-9]+( [A-Z0-9]+)*$/.test(label)) return fail("convert: --label must be an uppercase A-Z0-9 label with single spaces (RFC 7468)");
+  var b64 = input.der.toString("base64").replace(/(.{1,64})/g, "$1\n");
+  process.stdout.write("-----BEGIN " + label + "-----\n" + b64 + "-----END " + label + "-----\n");
+}
+
+// pki verify <cert>... --anchor <cert> -- validate an ordered certification path
+// (anchor->target) against a trust anchor via pki.path.validate (RFC 5280 sec. 6.1).
+function cmdVerify(args) {
+  var certFiles = args._, anchorFile = args.anchor;
+  if (!certFiles.length || !anchorFile) fail("usage: pki verify <cert>... --anchor <anchor-cert> [--time ISO]");
+  var certs, anchor;
+  try { certs = certFiles.map(function (f) { return pki.schema.x509.parse(readForLib(f)); }); }
+  catch (e) { return fail("cannot parse a path certificate: " + (e.code || e.message)); }
+  try { anchor = pki.schema.x509.parse(readForLib(anchorFile)); }
+  catch (e2) { return fail("cannot parse the anchor certificate: " + (e2.code || e2.message)); }
+  var time = args.time ? new Date(args.time) : new Date();
+  if (isNaN(time.getTime())) fail("verify: --time must be an ISO-8601 date");
+  var spki = anchor.subjectPublicKeyInfo;
+  return pki.path.validate(certs, {
+    time: time,
+    trustAnchor: { name: anchor.subject, publicKey: spki.bytes, algorithm: spki.algorithm.oid, parameters: spki.algorithm.parameters },
+  }).then(function (res) {
+    process.stdout.write(res.valid ? "valid\n" : "invalid\n");
+    if (!res.valid) {
+      (res.results || []).forEach(function (r, i) {
+        (r.checks || []).forEach(function (c) { if (c.ok === false) process.stdout.write("  cert[" + i + "] " + c.code + "\n"); });
+      });
+    }
+    process.exitCode = res.valid ? 0 : 1;   // let Node flush stdout before it exits
+  }, function (e) { return fail(e.code + ": " + e.message); });
+}
+
+var USAGE = "usage: pki <version|oid|parse|inspect|lint|convert|verify> [args]\n";
+
 function main(argv) {
   var cmd = argv[0];
   switch (cmd) {
     case "version": case "--version": case "-v": return cmdVersion();
     case "oid":     return cmdOid(argv[1]);
     case "parse":   return cmdParse(argv[1]);
+    case "inspect": return cmdInspect(argv[1]);
+    case "lint":    return cmdLint(parseArgs(argv.slice(1)));
+    case "convert": return cmdConvert(parseArgs(argv.slice(1)));
+    case "verify":  return cmdVerify(parseArgs(argv.slice(1)));
     case undefined: case "help": case "--help": case "-h":
-      process.stdout.write("usage: pki <version|oid|parse> [args]\n");
+      process.stdout.write(USAGE);
       return;
     default:
       return fail("unknown command: " + cmd);
   }
 }
 
-main(process.argv.slice(2));
-
+Promise.resolve(main(process.argv.slice(2))).catch(function (e) { fail(e && (e.stack || e.message) || String(e)); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "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:63ae20ee-b75f-4b87-9846-27c435f26822",
+  "serialNumber": "urn:uuid:a5150e4c-cfd7-4241-8d30-2a5f74cea49e",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-13T16:00:51.631Z",
+    "timestamp": "2026-07-13T17:30:07.505Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.10",
+      "bom-ref": "@blamejs/pki@0.2.11",
       "type": "application",
       "name": "pki",
-      "version": "0.2.10",
+      "version": "0.2.11",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.2.10",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.11",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.10",
+      "ref": "@blamejs/pki@0.2.11",
       "dependsOn": []
     }
   ]