micro509

micro509

A zero-dependency TypeScript PKI toolkit for certificates, verification, revocation, and PKCS workflows.

Zero dependencies. Tree-shakeable subpath entrypoints. Pure WebCrypto. Runs everywhere: Node, Bun, Deno, browsers, Cloudflare Workers.

Prerelease — API may change before 1.0.

Install

npm install micro509

Why micro509

JavaScript PKI libraries usually force a bad tradeoff: heavyweight standards toolkits, legacy crypto kitchen sinks, or narrow parsing utilities.

micro509 is the practical middle: a modern, WebCrypto-native PKI toolkit with zero runtime dependencies and typed APIs for the workflows most applications actually need.

It gives you one library for certificate and CSR creation, chain verification, service-identity matching, CRLs, OCSP, PKCS#7 SignedData, PFX/PKCS#12, PEM handling, and key import/export.

And when verification fails, you get typed results your code can act on: a typed error code for every failure mode, the failing certificate index, and structured failure details instead of false.

if (!result.ok) {
  // result.error.code: 'signature_invalid' | 'certificate_expired' | 'name_constraints_violated' | ...
  // result.error.index: which certificate in the chain failed
  // result.error.details: { expected, actual } for identity mismatches
}

Beyond verification, micro509 covers PKI surface that's hard to find in a single zero-dependency JS package:

• OCSP — build requests, parse and validate responses, verify responder authorization
• PFX / PKCS#12 — create and parse password-protected key+cert bundles
• PKCS#7 / CMS — sign content, parse and verify SignedData, extract cert bags
• CRLs — create, parse, verify, and check revocation status
• Encrypted keys — PBES2 PKCS#8, legacy OpenSSL encrypted PEM, PKCS#1, SEC1
• Key import/export — PKCS#8, SPKI, JWK, PKCS#1, SEC1 with generation for RSA, ECDSA, Ed25519
• Service identity — wildcard DNS, IPv6 normalization, URI-ID, SRV-ID, explicit CN opt-in

Narrow defaults, explicit escape hatches — dangerous operations like CN fallback or self-signed leaf acceptance require opt-in. All with no any, no type assertions, no non-null assertions, and no runtime DI frameworks that break edge runtimes.

Quick start

Create a self-signed certificate:

import { createSelfSignedCertificate } from 'micro509';

const { certificate, keyPair } = await createSelfSignedCertificate({
  subject: {
    commonName: 'example.com',
    organization: 'Acme',
    country: 'US',
  },
  validity: { days: 30 },
  extensions: {
    keyUsage: ['digitalSignature', 'keyEncipherment'],
    subjectAltNames: [
      { type: 'dns', value: 'example.com' },
      { type: 'dns', value: 'www.example.com' },
    ],
  },
});

console.log(certificate.pem);
console.log(await keyPair.exportPkcs8Pem());

Create a CSR:

import { createCertificateSigningRequest, generateKeyPair } from 'micro509';

const keyPair = await generateKeyPair({ kind: 'ed25519' });
const csr = await createCertificateSigningRequest({
  subject: { commonName: 'csr.example' },
  publicKey: keyPair.publicKey,
  signerPrivateKey: keyPair.privateKey,
  extensions: {
    subjectAltNames: [{ type: 'dns', value: 'csr.example' }],
  },
});

console.log(csr.pem);

Parse a certificate:

import { parseCertificatePem, unwrap } from 'micro509';

// Using certificate from previous example
const parsed = unwrap(parseCertificatePem(certificate.pem));
console.log(parsed.subject.values.commonName);
console.log(parsed.extendedKeyUsage);
console.log(parsed.authorityInfoAccess);

parseCertificatePem returns a typed Result — check result.ok, or unwrap() to throw on malformed input.

Verify a chain:

import { verifyCertificateChain } from 'micro509';

// Assuming you have a self-signed certificate used as both leaf and root; no intermediates
const result = await verifyCertificateChain({
  leaf: certificate.pem,
  intermediates: [],
  roots: [certificate.pem], // Using self-signed cert as root for demo
  purpose: 'serverAuth',
  serviceIdentity: { type: 'dns', value: 'example.com' },
});

if (result.ok) {
  console.log(result.value.chain.length);
} else {
  console.log(result.error.code);
}

Runtime support

Runtime	Status	Notes
Node	supported	modern Node with WebCrypto globals (tested on 24+)
Bun	supported	Bun 1.3+
Deno	supported	requires WebCrypto and web text/base64 globals
Browser	supported	modern browsers only
Worker	supported	same WebCrypto and text/base64 globals required

The core stays ESM-only and side-effect-free.

Algorithm support

Area	Shipped support
Certificate and CSR signatures	RSA PKCS#1 v1.5, RSA-PSS, ECDSA P-256 / P-384 / P-521, Ed25519
RSA key APIs	scheme: 'pkcs1-v1_5'
ECDSA key APIs	P-256, P-384, P-521
Encrypted PKCS#8 and PFX	PBES2 with AES-CBC plus PBKDF2 HMAC-SHA1/HMAC-SHA256
Encrypted traditional PEM	AES-128-CBC, AES-192-CBC, AES-256-CBC for RSA and EC private keys

micro509 focuses on algorithms that are broadly interoperable in modern X.509 and WebCrypto-backed runtimes.
It intentionally excludes niche, blockchain-specific, or key-agreement-only primitives from the core API unless they are needed for a PKI workflow the library explicitly supports.

Standards status

Area	Status
RFC 5280 path validation	complete
RFC 6960 OCSP	complete
RFC 6125 service identity	complete
RFC 9618 policy validation	complete

See docs/PKIX-SCOPE.md for the detailed scope boundary and the API reference for the public module surface.

Imports

Use the root package for most applications:

import { createCertificate, parseCertificatePem, verifyCertificateChain } from 'micro509';

Use domain entrypoints when you want exhaustive advanced types or a narrower workflow surface:

import { parseCertificatePem } from 'micro509/x509';
import { verifyCertificateChain, matchServiceIdentity } from 'micro509/verify';
import { createOcspRequest, checkCertificateRevocation } from 'micro509/revocation';
import { createPfx } from 'micro509/pkcs';
import { generateKeyPair } from 'micro509/keys';
import { pemDecode, pemEncode } from 'micro509/pem';
import type { Micro509Error } from 'micro509/result';

The full stable subpath list lives in the API reference.

More docs

• API reference: micro509.kjanat.dev/api
• Standards scope: docs/PKIX-SCOPE.md
• PKITS harness: test/pkits.test.ts
• Differential harness: test/differential.test.ts
• Contributing: CONTRIBUTING.md

License

MIT