@blamejs/pki

PKI in pure JavaScript, with its own ASN.1 codec and crypto engine.

X.509, ASN.1/DER, OID, CMS, OCSP, CRL, timestamping, enrollment, and the PKCS formats. The fail-closed DER codec and the post-quantum-first algorithm registry are in-tree and public, so strictness and algorithm coverage are decisions this toolkit makes rather than inherits, and neither is capped by what Web Crypto exposes. No runtime dependencies, no TypeScript, no build step.

pkijs.com · Roadmap · Security · Changelog

Most JavaScript PKI code gets its ASN.1 parser and its algorithm coverage from somewhere else: an external DER library with its own CVE history, or the Web Crypto API with its limits on streaming, opaque keys, and algorithm reach. @blamejs/pki owns those layers.

• Its own DER codec. Strict, canonical, and bounded. Malformed input is rejected in bounded time rather than walked into a stack overflow.
• An OID-named algorithm registry. Every algorithm, attribute, and extension is named through one two-way OID table (pki.oid). Adding a signature or KEM algorithm, post-quantum ones included, is a registry entry rather than a case in parse. Sign and verify resolve algorithms through the same table the parsers read.
• Fail-closed everywhere. Every parse, sign, and verify path throws on failure. No path returns zero, a default, or partial output in place of a verdict.
• Nothing in your package.json. The cryptography runs on Node's built-in node:crypto: the classical set plus post-quantum ML-DSA and SLH-DSA signatures via the platform OpenSSL 3.5, and ML-KEM key generation, encapsulation, and decapsulation. Nothing is vendored and nothing is installed, so there is no dependency tree for npm audit to report on.

npm i @blamejs/pki

Requires Node.js 24.19+ and runs on the shipped runtime, with no build step and no transpilation.

var pki = require("@blamejs/pki");

pki.schema.x509.parse accepts a DER Buffer or a PEM string or Buffer. It returns a fully decoded, validated certificate: distinguished names rendered and structured, the validity window as real Dates, algorithms and extensions named through the OID registry, and the exact signed tbsBytes for a downstream verifier.

var pki = require("@blamejs/pki");
var fs  = require("node:fs");

var pem  = fs.readFileSync("cert.pem", "utf8");
var cert = pki.schema.x509.parse(pem);

cert.subject.dn;                    // "CN=example.com, O=Example Org, C=US"
cert.issuer.dn;                     // "CN=example.com, O=Example Org, C=US"
cert.serialNumberHex;              // "7057e1ebeec2e5f7…"
cert.signatureAlgorithm.name;      // "sha256WithRSAEncryption"
cert.subjectPublicKeyInfo.algorithm.name;  // "rsaEncryption"
cert.validity.notAfter;            // Date — 2027-07-04T07:16:15.000Z

cert.extensions.forEach(function (ext) {
  ext.name;      // "subjectKeyIdentifier" (or null when the OID is unknown)
  ext.critical;  // boolean
  ext.value;     // Buffer — the raw extnValue OCTET STRING contents
});

Malformed bytes throw a typed error rather than returning a half-parsed object:

try {
  pki.schema.x509.parse(Buffer.from([0x30, 0x03, 0x02, 0x01, 0x00]));
} catch (e) {
  e.constructor.name;  // "CertificateError"
  e.code;              // e.g. "x509/not-a-certificate" — stable domain/reason string
}

var der = pki.schema.x509.pemDecode(pem, "CERTIFICATE");   // Buffer of DER bytes
var out = pki.schema.x509.pemEncode(der, "CERTIFICATE");   // 64-column PEM string

The codec under every structure is public. Decode returns a zero-copy node tree, and the builders emit canonical DER.

// Build a canonical-DER SEQUENCE, then decode it back.
var der = pki.asn1.build.sequence([
  pki.asn1.build.oid("2.5.4.3"),          // commonName
  pki.asn1.build.utf8("example.com"),
]);

var node = pki.asn1.decode(der);
node.tagNumber === pki.asn1.TAGS.SEQUENCE;   // true
node.children.length;                        // 2
pki.asn1.read.oid(node.children[0]);         // "2.5.4.3"
pki.asn1.read.string(node.children[1]);      // "example.com"

The decoder is strict by construction, so non-DER shapes are refused:

try {
  pki.asn1.decode(Buffer.from([0x30, 0x80, 0x00, 0x00]));  // indefinite length
} catch (e) {
  e.constructor.name;  // "Asn1Error"
  e.code;              // "asn1/indefinite-length"
}

Size and depth are bounded before a byte is walked. Override the caps per call:

pki.asn1.decode(der, { maxBytes: pki.C.BYTES.mib(4), maxDepth: 32 });

An OID names every algorithm, attribute type, and extension. The registry is a two-way map, seeded with the RFC 5280 set, the classical algorithm set, and the NIST post-quantum arcs (ML-DSA, ML-KEM, SLH-DSA).

pki.oid.name("1.2.840.113549.1.1.11");  // "sha256WithRSAEncryption"
pki.oid.byName("sha256");               // "2.16.840.1.101.3.4.2.1"
pki.oid.toArcs("2.5.4.3");              // [2, 5, 4, 3]

// Extend it with your own arc:
pki.oid.register("1.3.6.1.4.1.99999.1", "acmeCorpExtension");

pki.webcrypto is a standard W3C WebCrypto (SubtleCrypto) engine over node:crypto. The post-quantum suite lives in the same API as RSA, ECDSA, and EdDSA: pick the algorithm, and the rest is identical.

var subtle = pki.webcrypto.subtle;
var data   = Buffer.from("sign me");

// FIPS 204 ML-DSA-65 — a post-quantum signature.
var kp  = await subtle.generateKey({ name: "ML-DSA-65" }, true, ["sign", "verify"]);
var sig = await subtle.sign({ name: "ML-DSA-65" }, kp.privateKey, data);
var ok  = await subtle.verify({ name: "ML-DSA-65" }, kp.publicKey, sig, data); // true

// The classical set — ECDSA, RSA-PSS, Ed25519, AES-GCM, ECDH, HKDF, … — is the
// same call shape, and every key it exports is OpenSSL/NSS-interoperable.

Everything below is callable now; nothing is a stub. The core codec and the certificate-reading surface are stable under the deprecation policy; the rest carries a per-primitive @status on its wiki page, and LTS-CALENDAR.md explains what experimental excludes. The table is an index — the per-function reference, generated from the source comment blocks, is at pkijs.com.

pki version                              # the installed @blamejs/pki version
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
pki sign msg.txt --cert signer.pem --key signer-key.pem --out msg.p7s   # CMS SignedData (pki.cms.sign)
pki sign msg.txt --cert signer.pem --key signer-key.pem --detached --pem # detached, PEM to stdout

inspect, lint, convert, verify, and sign are thin front-ends over pki.inspect, pki.lint, the per-format PEM codecs, pki.path.validate, and pki.cms.sign. The CLI does nothing the library API cannot. lint exits non-zero when any error or fatal finding is present, verify exits non-zero when the path does not validate, and sign reads a PKCS#8 DER or PEM private key and its certificate and writes a DER (or --pem) SignedData to --out or stdout.

SCEP enrollment, and additional NIST-on-ramp PQC signatures as the OID registry admits them, are on the roadmap and ride this same core. ROADMAP.md carries the full plan and the current status of each area; CHANGELOG.md carries what has landed.

Every PKI format is a thin, declarative schema over one shared engine. A parser declares the ASN.1 structure as data and hands it to walk; it never advances a child cursor, re-checks a tag, or re-rolls PEM handling by hand. Each structural rule is therefore written once in the engine — bounds-checked positional reads, optional and context-tagged field ordering, SET-OF ascending order and uniqueness, arity, and fail-closed typed errors — and no new format can reintroduce the bug class it prevents. Adding a format is a schema declaration plus a documentation comment block.

┌─ Detect + route ─────────────────────────────────────────────────────────┐
│ pki.schema.parse — inspect the DER root, route to the matching sibling   │
└──────────────────────────────────────────────────────────────────────────┘
                                     │
 ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
 │  x509  │ │  crl   │ │  csr   │ │ pkcs8  │
 └────────┘ └────────┘ └────────┘ └────────┘
 ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
 │  cms   │ │  ocsp  │ │  tsp   │ │  crmf  │
 └────────┘ └────────┘ └────────┘ └────────┘
 ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
 │ pkcs12 │ │  cmp   │ │ smime  │ │attrcert│
 └────────┘ └────────┘ └────────┘ └────────┘
                                     │  routed DER format parsers (siblings)
┌─ Protocols · trust · supply chain  (reached by explicit call) ───────────┐
│ pki.path RFC 5280 · pki.trust anchors · pki.ct SCTs · pki.hpke RFC 9180  │
│ pki.shbs HSS/LMS · pki.merkle RFC 9162 · pki.sigstore npm provenance     │
│ pki.jose · pki.acme · pki.est — compose the layers below directly.       │
└──────────────────────────────────────────────────────────────────────────┘
                                     │  every module composes ↓
┌─ Shared structure ───────────────────────────────────────────────────────┐
│ pki.schema.engine — walk + combinators (positional reads, tag order,     │
│ SET-OF uniqueness, typed errors) · the PKIX sub-schemas · and the        │
│ guard family (guard-*) — one fail-closed choke point per CVE class.      │
└──────────────────────────────────────────────────────────────────────────┘
                                     │  built on ↓
┌─ Foundation ─────────────────────────────────────────────────────────────┐
│ pki.asn1 — strict bounded DER codec · pki.cbor — deterministic CBOR ·    │
│ pki.oid — two-way PQC-seeded registry · pki.errors — PkiError taxonomy   │
│ · pki.C — version-stable LIMITS + scale constants.                       │
└──────────────────────────────────────────────────────────────────────────┘

┌─ Crypto ─────────────────────────────────────────────────────────────────┐
│ pki.webcrypto ─▶ node:crypto — a W3C SubtleCrypto engine: the            │
│ classical set + post-quantum ML-DSA / SLH-DSA + ML-KEM key generation.   │
└──────────────────────────────────────────────────────────────────────────┘

Foundation. The strict, bounded DER codec (pki.asn1), the two-way OID registry (pki.oid), the PkiError taxonomy (pki.errors), and the version-stable constants (pki.C). These have no PKI knowledge; they are the bytes-and-names layer everything else stands on.

Shared structure. The declarative schema engine (pki.schema.engine) and the PKIX sub-schemas it is fed: AlgorithmIdentifier, Name, Extension, the bounded version reader, and the single coerce-decode-walk parse entry that every format's parse is bound to. Input coercion, the PEM size cap, and the DER-decode wrapping live here once, so a format cannot diverge on a guard.

Format parsers. x509, crl, csr, pkcs8, cms, ocsp, tsp, attrcert, crmf, pkcs12, cmp, smime, and csrattrs are siblings. Each is a schema declaration composed from the shared pieces, emitting its own typed domain/reason error codes. pki.schema.parse inspects a decoded root and routes to the first sibling whose detector accepts. Where two detectors overlap, order in the registry is load-bearing and the more specific one sits first, so a new format is inserted ahead of any more permissive detector.

Protocols, trust, and supply chain. Above the format parsers sit the domain modules reached by explicit call rather than DER routing: pki.path (RFC 5280 path validation), pki.trust (trust anchors), pki.ct (Certificate Transparency SCTs), pki.hpke (RFC 9180), pki.shbs (HSS/LMS stateful hash signatures), pki.merkle (RFC 9162 transparency proofs), pki.sigstore (offline npm-provenance verification), pki.webauthn (WebAuthn and passkey verification), pki.cms (RFC 5652 SignedData signing and verification), pki.tsp (RFC 3161 timestamping), and the jose, acme, and est enrollment surfaces. Each composes the shared structure, foundation, and crypto layers directly. Alongside the schema engine, the fail-closed guard family (guard-*) centralizes each CVE-class defense — detached-buffer re-view, resource caps, constant-time compares, canonical-DN comparison — as one choke point a format cannot re-inline.

Crypto. pki.webcrypto is a W3C SubtleCrypto engine over node:crypto, carrying the classical suite plus post-quantum ML-DSA and SLH-DSA signatures and ML-KEM key generation. Sign and verify resolve algorithms through the same OID registry the parsers read, so the signing surface and the parsing surface share one algorithm vocabulary.

• Zero npm runtime dependencies, nothing vendored. The cryptography runs on Node's built-in node:crypto, and the toolkit vendors no third-party code. A platform built-in ships zero bytes and stays OpenSSL-interoperable by construction. No dependency tree, transitive or vendored, exists to compromise or keep current.
• Fail-closed DER. The decoder rejects every non-canonical shape — indefinite length, non-minimal length or tag encodings, trailing bytes, over-long or over-deep input — with a typed Asn1Error before it walks the structure. Size and depth caps are enforced up front, so adversarial input costs bounded work rather than a stack overflow.
• Fail-closed verification. Every verify path throws on failure. A default that accepts on error is treated as a bug.
• PQC-first crypto. Post-quantum ML-DSA and SLH-DSA signatures run in the WebCrypto engine (pki.webcrypto) alongside the classical set, and ML-KEM key generation, encapsulation, and decapsulation carry the CMS KEM recipient arm. Every algorithm is named in the OID registry (pki.oid), sign and verify resolve through that registry, and no default is classical-only where a post-quantum option exists.
• Signed releases. Release tags are annotated and SSH-signed, and published tarballs carry provenance and an SBOM. See SECURITY.md → Verifying release authenticity.

Report a vulnerability privately — see SECURITY.md. For usage questions and support channels, see SUPPORT.md.

The primitive-by-primitive reference lives at pkijs.com, generated from the source comment blocks so it cannot drift from the shipped API.

Apache-2.0. Third-party attribution, currently none since the toolkit vendors nothing, is tracked in NOTICE.