x509

@peculiar/x509 is a TypeScript/JavaScript library, built on top of @peculiar/asn1-schema and its family of sibling ASN.1 packages, that makes working with X.509 certificates, PKCS#10 certificate signing requests, and certificate revocation lists (CRLs) approachable without hand-rolling ASN.1 parsing. It exposes typed wrapper classes for reading existing certificates (subject, issuer, validity dates, extensions, public key) as well as generator classes for creating self-signed certificates, CSRs, and CRLs, plus a chain-builder for validating certificate chains and exporters for PKCS#7 bundles.

Because it delegates all cryptographic operations to the standard WebCrypto API through a pluggable CryptoProvider, the same code runs unmodified in browsers and in Node.js (paired with a WebCrypto-compatible implementation such as @peculiar/webcrypto). Signature verification and algorithm handling are extensible via a dependency-injection-based formatter registry, and the library ships explicit support for post-quantum signature algorithms (ML-DSA, SLH-DSA) alongside classic RSA and EC schemes, making it a practical building block for PKI tooling, certificate-issuance services, and crypto-facing Node/browser applications.

What You Get

• Typed X509Certificate, X509Crl, and Pkcs10CertificateRequest classes that lazily parse ASN.1 fields (subject, issuer, validity, extensions, public key) into ergonomic JS getters
• Generator classes (X509CertificateGenerator, Pkcs10CertificateRequestGenerator, X509CrlGenerator) for creating self-signed certificates, CSRs, and CRLs with WebCrypto key pairs
• An X509ChainBuilder for constructing and validating certificate chains from a pool of candidate certificates
• A registry-based extension/attribute system (BasicConstraints, KeyUsage, SubjectAltName, AuthorityKeyIdentifier, and more) that decodes known X.509/PKCS#9 extensions by OID automatically
• Built-in support for classic RSA/EC/Ed algorithms as well as post-quantum ML-DSA and SLH-DSA signature schemes
• PEM/DER/Base64 conversion helpers and PKCS#7 certificate-list export, plus dual CJS/ESM/UMD browser builds

Common Use Cases

• Issuing and validating self-signed certificates for internal services or development environments
• Generating PKCS#10 certificate signing requests to submit to an internal or external CA
• Parsing and inspecting X.509 certificates (subject, issuer, validity window, extensions) inside a Node.js backend or browser app
• Building and verifying certificate chains for mutual-TLS or client-certificate authentication flows
• Implementing custom PKI tooling that needs post-quantum-ready signature algorithm support

Under The Hood

Architecture The library is organized around ASN.1 wrapper classes built on the shared PemData base class (pem_data.ts): X509Certificate, X509Crl, and Pkcs10CertificateRequest each wrap a raw ASN.1 schema object (from @peculiar/asn1-x509 and sibling packages) and lazily parse fields such as subject, issuer, extensions, and public key into typed JS wrapper objects on first access, caching the result in private class fields (#tbs, #serialNumber, etc.). Extension and attribute polymorphism is handled through ExtensionFactory/AttributeFactory registries (extension_factory.ts, attribute_factory.ts), populated at module load via top-level registration calls in index.ts — a plugin-registry pattern that lets a generic decode step dispatch to a concrete class like BasicConstraintsExtension purely by OID lookup instead of a large switch statement. Cryptographic operations are decoupled from any one runtime through CryptoProvider (provider.ts), a singleton map of named WebCrypto-compatible implementations, and through tsyringe-based dependency injection for pluggable signature formatters (AsnDefaultSignatureFormatter, AsnEcSignatureFormatter) selected by a DI token, so verifying an EC-signed certificate routes through different signature logic than RSA without the core certificate classes needing to know about it. Generator classes are kept as separate builder objects from the read-side wrapper classes, cleanly separating certificate creation from certificate parsing.

Tech Stack Written in TypeScript targeting Node >=20 and browsers, the library depends on a family of sibling @peculiar/asn1-* packages (asn1-schema, asn1-x509, asn1-cms, asn1-csr, asn1-ecc, asn1-rsa, asn1-pkcs9, asn1-x509-post-quantum) for ASN.1 DER encoding/decoding, pvtsutils for buffer conversions, and tsyringe (a reflect-metadata-based DI container) for its formatter/algorithm registries — which is why consumers must import a Reflect polyfill (reflect-metadata, core-js, or @abraham/reflection) before using the library, a wrinkle called out prominently in the README. The build pipeline uses Rollup (with rollup-plugin-typescript2, rollup-plugin-dts, and Terser) to produce CJS, ESM, and UMD browser bundles plus a rolled-up .d.ts; tests run on Vitest with v8 coverage reported to Coveralls; linting and formatting use the Oxc toolchain (oxlint/oxfmt) rather than ESLint/Prettier; and a separate Docusaurus site under website/ hosts the documentation.

Code Quality The test/ directory contains a broad set of Vitest suites covering algorithms, extensions, attributes, names, PEM parsing, public keys, CRL/CSR generation, and dedicated regression tests tied to specific reported GitHub issues. Core classes use TypeScript throughout with explicit interfaces, extensive JSDoc documentation on public members, and true encapsulation via private class fields rather than underscore-prefixed convention. Error handling favors explicit thrown Error/TypeError over silent failures. CI (GitHub Actions on Node 24) runs format-checking, linting, coverage-instrumented tests, a full build, and npm pack on every push and pull request, giving reasonable confidence that regressions are caught before publish.

API Design The public API favors static factory methods (X509CertificateGenerator.createSelfSigned, Pkcs10CertificateRequestGenerator.create) that accept plain option objects mirroring WebCrypto’s own algorithm-parameter shape, so anyone already comfortable with SubtleCrypto has little new vocabulary to learn. Parsed certificates expose self-explanatory typed getters (.subject, .notBefore, .extensions) instead of requiring manual ASN.1 traversal, and PEM/DER/Base64 round-tripping is handled uniformly through the shared PemData base class. The one notable friction point is the mandatory Reflect-metadata polyfill import, an internal DI implementation detail that leaks into every consumer’s entry point — documented clearly, but still an extra setup step compared to lower-level ASN.1/PKI libraries that avoid a DI container altogether.