Choosing a library and a surface

Choose pkinative for strict, dependency-free PKI in any JavaScript runtime — certificates, paths and revocation, CMS and timestamps, PKCS#8 and PKCS#12 — with every refusal explained by a stable code. Choose another tool for what it will never do, listed below.

What pkinative does #

• Reads DER (and BER on request), PEM and OIDs; every field and standard extension of an RFC 5280 certificate, with profile concerns as diagnostics; PKCS#10 certification requests, with the extensions they ask for; CRLs, OCSP responses, CMS SignedData, RFC 3161 timestamp tokens, PKCS#8 keys and PKCS#12 files under PBES2.
• Builds certificates, certification requests, OCSP requests, CMS SignedData attached or detached, and timestamp requests — signed through Web Crypto by a key you hold, or by an ExternalSigner for a key in an HSM or a remote service; RSA PKCS#1 v1.5 and PSS, ECDSA on P-256, P-384 and P-521, Ed25519, and Ed448 where the host has it.
• Judges: RFC 5280 §6 path building and validation with name constraints and the policy tree, revocation by CRL (delta lists and scoping included) or OCSP, RFC 6125 host names, extended key usage, CMS signatures and timestamps, and a certification request's proof of possession. The one-call reports — verifyCertificateChain, verifySignedData, verifyTimeStampToken, verifyCertificationRequest, openPkcs12 — return every reason at once and never throw for a problem with the input.
• Proves it: scored against x509-limbo, NIST PKITS and its S/MIME messages, clause by clause against the pinned text of RFC 5280, and against OpenSSL and Windows in both directions — the conformance guide carries the current figures and every reviewed deviation.
• Runs one build on every runtime with Web Crypto, with zero runtime dependencies: tested in CI on Node.js 22 on Linux, Windows and macOS and on Node.js 24 on Linux, with a Deno, a Bun and a headless Chromium smoke test, and on Node.js 26 (Current) in an advisory run until its LTS date; other Web Crypto runtimes, such as Cloudflare Workers, are expected to work and are not tested in CI.

Verifying a signature is not validating a chain: verifyCertificateSignature says the issuer's key signed these bytes, and nothing about expiry, trust, revocation, or whether that issuer was entitled to sign. verifyCertificateChain is the call that answers those.

docs/data/surfaces.json lists each capability with the library exports, CLI commands and MCP tools that provide it and the version that brought it.

What it does not do, by design #

Each of these is a recorded decision, not a gap on a roadmap: the decision records say why, and what holds the line.

The alternatives, by the facts #

Read from the npm registry on 2026-09-19 (docs/data/comparison-2026-09-19.json):

node-forge and jsrsasign implement RSA and elliptic curves in JavaScript; pkinative will not, and leaves that arithmetic to Web Crypto. asn1js, pkijs and @peculiar/x509 are typed and modern, and bring their dependency trees with them.

When pkinative is the right choice #

• You read certificates from untrusted sources — uploads, network peers, logs — and want the parser to refuse ambiguous encodings and bound its resources.
• You ship to browsers or edge runtimes and count every dependency and every kilobyte: reading a certificate ships about 87 KB minified, describing a key file about 45 KB, and each subsystem's cost is a budget npm run verify:bundle checks.
• You build tools that must display every field of a certificate, including the ones other parsers skip.
• You drive a library from an AI agent and want machine-readable codes, diagnostics and an API manifest.
• You need a verdict you can act on: every refusal a reason code with its clause, several at once, and the one that would have been thrown kept in errorCode.

Choosing your surface #

pkinative reaches you three ways, and all three run the same engine: a verdict, a refusal code or an artefact does not depend on the surface that produced it. Pick the one that matches where your bytes live and who drives the call.

The CLI and the MCP server are thin wrappers: neither adds a PKI decision of its own, both pin pkinative ^1.0.0, both carry the engine's PKI_* codes verbatim, and both reach every runtime export of pkinative 1.0.0. What they add is the boundary the engine deliberately lacks — files and exit codes for the CLI, a sandbox and an MCP protocol surface for the server — and the errors guide shows how one failure looks on each.

Every capability docs/data/surfaces.json lists, by surface:

What each surface adds around the engine, and what it leaves out — an em-dash means the surface does not offer it:

Honest notes #

• No surface generates or exports a key, and none fetches. Web Crypto's generateKey and exportKey are refused in every version (ADR 0001), and the engine opens no socket (ADR 0006): keys come from your HSM, KMS or openssl genpkey, and CRLs, OCSP responses and timestamps are evidence you carry in. The CLI and the MCP server build the OCSP and timestamp requests; neither sends them.
• Only the CLI and the MCP sandbox write files. The engine returns bytes. The CLI writes where you point it, exclusively unless --overwrite; the MCP server writes only under PKINATIVE_MCP_OUTPUT_DIR, never overwrites, and never writes, lists or serves a key-bearing file.
• A key in an HSM or a remote service reaches the library only. Both satellites sign with a PKCS#8 or PKCS#12 file, imported as a non-extractable Web Crypto key; an ExternalSigner is a library call.
• A satellite adds no PKI decision. A PKI_*, PKI_REASON_* or PKI_DIAG_* code means the same on every surface. A CLI E_* class groups the codes for exit codes and scripts; an MCP wrapper code names only the boundary the server owns — validation, the sandbox, caps, secrets, output.
• The table is the complete story for these capabilities, not a sample: where a cell is an em-dash, the surface lacks the capability rather than hiding it under another name.

You can switch later #

All three surfaces call the same engine, so what one writes the others read: a certificate create_certificate writes into the sandbox verifies under pkinative chain verify and parses with parseCertificate, and a verdict carries the same reason codes wherever it was reached. cert create --spec and the spec input of create_certificate take the same JSON, so a certificate description moves between the CLI and the MCP server unchanged — but each surface keeps its own defaults: for a self-signed certificate cert create adds an authorityKeyIdentifier and create_certificate does not, so the same spec gives different bytes. Compare verdicts across surfaces, not hashes. Starting on the "wrong" surface costs a call-site migration, not a re-authoring.

The CLI guide and the MCP guide document every command and tool; CLI use cases and MCP use cases put them to work.