@small-web/x509

Constructs the X.509 certificates and certification requests used by Auto Encrypt and Auto Encrypt Localhost, in 100% JavaScript with no dependencies.

This module fills in the gaps in node:crypto (specifically, crypto.X509Certificate) that we need for those two projects.

Scope

• Certificates (RFC 5280): Handles self-signed root certificate authority and server certificate creation (with basicConstraints, keyUsage, subjectKeyIdentifier, authorityKeyIdentifier, extendedKeyUsage and subjectAlternativeName).

• Certification requests (RFC 2986 / PKCS#10): Subject alternative names for domains and IPv4/IPv6 addresses, encoded per RFC 8555 § 7.4.

• Authority Key Identifier reader: Reads the Authority Key Identifier field using the Object Identifier (OID). Node does not expose this identifier and it is required per RFC 9773 § 4.1 for the ACME renewal information CertID.

Everything else we need – key generation, PEM keys, signing, and reading a certificate’s subject, issuer, serial number, alternative names and validity – is provided by node:crypto and should be used from there.

This is not a general-purpose module and it will likely have little use beyond its use in the two above-mentioned modules. If we had a monorepo, it would be in there and not published separately.

API

• createCertificate(): Issues self-signed authority certificates and server certificates.

• certificationRequest(): Builds a PKCS#10 request (RFC 2986) for an ACME order as per RFC 8555 § 7.4.

• extensionValue(): Read an extension value out of a certificate without needing a general ASN.1 decoder.

• authorityKeyIdentifier(): Returns the certificate’s Authority Key Identifier.

• serialNumber(): Returns a certificate’s byte-encoded serial number, without the tag and length. This serial number can then be base64url-encoded as per RFC 9773 § 4.1 into an ARI certificate identifier.

• subjectName(): Returns a certificate’s subject in its original encoding, including the header.

• pem(), absent and OID: Encodings and identifiers used by Auto Encrypt and Auto Encrypt Localhost.

Regression testing

Prior to this module, we were using @panva/asn1.js and an inlined RFC 5280 decoder. The former is now a dev dependency and the latter a test helper that we use in regression testing to ensure the refactor did not introduce any behaviour changes.

Specifically:

• Certification requests are asserted to be byte-identical with the encoding Auto Encrypt used previously.

• The Authority Key Identifier reader tested against the old RFC 5280 decoder on all roots in the system trust store.

• Key identifiers are compared against the SHA-1 hash derived by the RFC 5280 decoder.

Certificates are also inspected with crypto.X509Certificate and used for real TLS handshakes.

Licence

AGPL version 3.0.

Copyright ⓒ 2026-present Aral Balkan, Small Technology Foundation.