SuavePlan/suaveplan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
suaveplan/packages/security-stack/security/x509/README.md
admin 9b28db724f Initial Commit
2026-05-27 23:47:53 +01:00

29 KiB
Raw Permalink Blame History

@suaveplan/x509 - RFC 5280 X.509 v3 certificate parser and certification-path validator. Universal: pure TypeScript over Uint8Array/DataView; signature verify delegated to @suaveplan/crypto-rsa and @suaveplan/crypto-curve.

Summary

RFC 5280 X.509 v3 certificate parser and certification-path validator. Universal (zero browser, Node, or React deps). Pure TypeScript over Uint8Array / DataView; signature verify delegated to @suaveplan/crypto-rsa (RSA-PKCS1v1.5, RSA-PSS) and @suaveplan/crypto-curve (ECDSA-P{256,384,521}, Ed25519).

Documentation tree

  • fixtures — (no submodules)
  • decoder — Implements decodeAsn1(bytes, mode) covering every ASN.1 production used by RFC 5280 Appendix A: primitive scalars (`I…
  • encoder — Implements encodeAsn1(node) producing canonical DER bytes per X.690 paragraph 10 for any Asn1Node the decoder accep…
  • oid — Encodes and decodes ASN.1 OBJECT IDENTIFIER bodies per X.690 paragraph 8.19. OIDs in X.509 identify algorithms, extensi…
  • strings — Decodes and encodes the typed ASN.1 string types used inside X.509 Names and SubjectAltName entries: UTF8String, `Pri…
  • time — Decodes and encodes the two time formats RFC 5280 paragraph 4.1.2.5 permits inside a certificate's Validity field: `U…
  • name — Decodes RFC 5280 paragraph 4.1.2.4 Name (RDNSequence) structures into a typed shape carrying both the raw DER bytes…
  • parse — Implements parseCertificate(bytes) decoding a DER- or PEM-encoded Certificate into a typed X509Certificate value…
  • errors — (no submodules)
  • authority-key-id — Decodes the authority-key-id extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • basic-constraints — Decodes the basic-constraints extension into BasicConstraints { cA: boolean; pathLenConstraint?: number }. During pat…
  • crl-distribution-points — Decodes the crl-distribution-points extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is…
  • extended-key-usage — Decodes the extended-key-usage extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is capt…
  • key-usage — Decodes the key-usage extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured from…
  • name-constraints — Decodes the name-constraints extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • registry — Decodes the registry extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured from…
  • subject-alt-name — Decodes the subject-alt-name extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • subject-key-id — Decodes the subject-key-id extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured…
  • chains-to — The helpers/chains-to module exposes a pre-filtering / display helper around the parsed certificate data. It is indep…
  • has-name-match — The helpers/has-name-match module exposes a pre-filtering / display helper around the parsed certificate data. It is…
  • is-issuer-of — The helpers/is-issuer-of module exposes a pre-filtering / display helper around the parsed certificate data. It is in…
  • observability — (no submodules)
  • pem — (no submodules)
    • pem — (no submodules)
  • schemas — (no submodules)
  • alg-map — The signature/alg-map module is part of the certificate signature-verify pipeline. Together with the rest of the `sig…
  • decode-ecdsa-sig — The signature/decode-ecdsa-sig module is part of the certificate signature-verify pipeline. Together with the rest of…
  • verify — The signature/verify module is part of the certificate signature-verify pipeline. Together with the rest of the `sign…
  • trust-anchor — validate/trust-anchor is the core of the certificate path-validation pipeline. validateChain walks the certificate…
  • validate-chain — validate/validate-chain is the core of the certificate path-validation pipeline. validateChain walks the certificat…
- [build-certs](./src/__fixtures__/build-certs.md) — _(no submodules)_- [decoder](./src/asn1/decoder.md) — Implements `decodeAsn1(bytes, mode)` covering every ASN.1 production used by RFC 5280 Appendix A: primitive scalars (`I…
  • encoder — Implements encodeAsn1(node) producing canonical DER bytes per X.690 paragraph 10 for any Asn1Node the decoder accep…
  • oid — Encodes and decodes ASN.1 OBJECT IDENTIFIER bodies per X.690 paragraph 8.19. OIDs in X.509 identify algorithms, extensi…
  • strings — Decodes and encodes the typed ASN.1 string types used inside X.509 Names and SubjectAltName entries: UTF8String, `Pri…
  • time — Decodes and encodes the two time formats RFC 5280 paragraph 4.1.2.5 permits inside a certificate's Validity field: `U…
  • name — Decodes RFC 5280 paragraph 4.1.2.4 Name (RDNSequence) structures into a typed shape carrying both the raw DER bytes…
  • parse — Implements parseCertificate(bytes) decoding a DER- or PEM-encoded Certificate into a typed X509Certificate value…
  • errors — (no submodules)- error-codes — (no submodules)- authority-key-id — Decodes the authority-key-id extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • basic-constraints — Decodes the basic-constraints extension into BasicConstraints { cA: boolean; pathLenConstraint?: number }. During pat…
  • crl-distribution-points — Decodes the crl-distribution-points extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is…
  • extended-key-usage — Decodes the extended-key-usage extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is capt…
  • key-usage — Decodes the key-usage extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured from…
  • name-constraints — Decodes the name-constraints extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • registry — Decodes the registry extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured from…
  • subject-alt-name — Decodes the subject-alt-name extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • subject-key-id — Decodes the subject-key-id extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured…
  • chains-to — The helpers/chains-to module exposes a pre-filtering / display helper around the parsed certificate data. It is indep…
  • has-name-match — The helpers/has-name-match module exposes a pre-filtering / display helper around the parsed certificate data. It is…
  • is-issuer-of — The helpers/is-issuer-of module exposes a pre-filtering / display helper around the parsed certificate data. It is in…
  • observability — (no submodules)- metrics — (no submodules)- pem — (no submodules)- pem — (no submodules)- schemas — (no submodules)- schemas — (no submodules)- alg-map — The signature/alg-map module is part of the certificate signature-verify pipeline. Together with the rest of the `sig…
  • decode-ecdsa-sig — The signature/decode-ecdsa-sig module is part of the certificate signature-verify pipeline. Together with the rest of…
  • verify — The signature/verify module is part of the certificate signature-verify pipeline. Together with the rest of the `sign…
  • trust-anchor — validate/trust-anchor is the core of the certificate path-validation pipeline. validateChain walks the certificate…
  • validate-chain — validate/validate-chain is the core of the certificate path-validation pipeline. validateChain walks the certificat…
  • build-certs — (no submodules)- decoder — Implements decodeAsn1(bytes, mode) covering every ASN.1 production used by RFC 5280 Appendix A: primitive scalars (`I…
  • encoder — Implements encodeAsn1(node) producing canonical DER bytes per X.690 paragraph 10 for any Asn1Node the decoder accep…
  • oid — Encodes and decodes ASN.1 OBJECT IDENTIFIER bodies per X.690 paragraph 8.19. OIDs in X.509 identify algorithms, extensi…
  • strings — Decodes and encodes the typed ASN.1 string types used inside X.509 Names and SubjectAltName entries: UTF8String, `Pri…
  • time — Decodes and encodes the two time formats RFC 5280 paragraph 4.1.2.5 permits inside a certificate's Validity field: `U…
  • name — Decodes RFC 5280 paragraph 4.1.2.4 Name (RDNSequence) structures into a typed shape carrying both the raw DER bytes…
  • parse — Implements parseCertificate(bytes) decoding a DER- or PEM-encoded Certificate into a typed X509Certificate value…
  • errors — (no submodules)- error-codes — (no submodules)- authority-key-id — Decodes the authority-key-id extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • basic-constraints — Decodes the basic-constraints extension into BasicConstraints { cA: boolean; pathLenConstraint?: number }. During pat…
  • crl-distribution-points — Decodes the crl-distribution-points extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is…
  • extended-key-usage — Decodes the extended-key-usage extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is capt…
  • key-usage — Decodes the key-usage extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured from…
  • name-constraints — Decodes the name-constraints extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • registry — Decodes the registry extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured from…
  • subject-alt-name — Decodes the subject-alt-name extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • subject-key-id — Decodes the subject-key-id extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured…
  • chains-to — The helpers/chains-to module exposes a pre-filtering / display helper around the parsed certificate data. It is indep…
  • has-name-match — The helpers/has-name-match module exposes a pre-filtering / display helper around the parsed certificate data. It is…
  • is-issuer-of — The helpers/is-issuer-of module exposes a pre-filtering / display helper around the parsed certificate data. It is in…
  • observability — (no submodules)- metrics — (no submodules)- pem — (no submodules)- pem — (no submodules)- schemas — (no submodules)- schemas — (no submodules)- alg-map — The signature/alg-map module is part of the certificate signature-verify pipeline. Together with the rest of the `sig…
  • decode-ecdsa-sig — The signature/decode-ecdsa-sig module is part of the certificate signature-verify pipeline. Together with the rest of…
  • verify — The signature/verify module is part of the certificate signature-verify pipeline. Together with the rest of the `sign…
  • trust-anchor — validate/trust-anchor is the core of the certificate path-validation pipeline. validateChain walks the certificate…
  • validate-chain — validate/validate-chain is the core of the certificate path-validation pipeline. validateChain walks the certificat…
  • build-certs — (no submodules)- decoder — Implements decodeAsn1(bytes, mode) covering every ASN.1 production used by RFC 5280 Appendix A: primitive scalars (`I…
  • encoder — Implements encodeAsn1(node) producing canonical DER bytes per X.690 paragraph 10 for any Asn1Node the decoder accep…
  • oid — Encodes and decodes ASN.1 OBJECT IDENTIFIER bodies per X.690 paragraph 8.19. OIDs in X.509 identify algorithms, extensi…
  • strings — Decodes and encodes the typed ASN.1 string types used inside X.509 Names and SubjectAltName entries: UTF8String, `Pri…
  • time — Decodes and encodes the two time formats RFC 5280 paragraph 4.1.2.5 permits inside a certificate's Validity field: `U…
  • name — Decodes RFC 5280 paragraph 4.1.2.4 Name (RDNSequence) structures into a typed shape carrying both the raw DER bytes…
  • parse — Implements parseCertificate(bytes) decoding a DER- or PEM-encoded Certificate into a typed X509Certificate value…
  • errors — (no submodules)- error-codes — (no submodules)- authority-key-id — Decodes the authority-key-id extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • basic-constraints — Decodes the basic-constraints extension into BasicConstraints { cA: boolean; pathLenConstraint?: number }. During pat…
  • crl-distribution-points — Decodes the crl-distribution-points extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is…
  • extended-key-usage — Decodes the extended-key-usage extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is capt…
  • key-usage — Decodes the key-usage extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured from…
  • name-constraints — Decodes the name-constraints extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • registry — Decodes the registry extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured from…
  • subject-alt-name — Decodes the subject-alt-name extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • subject-key-id — Decodes the subject-key-id extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured…
  • chains-to — The helpers/chains-to module exposes a pre-filtering / display helper around the parsed certificate data. It is indep…
  • has-name-match — The helpers/has-name-match module exposes a pre-filtering / display helper around the parsed certificate data. It is…
  • is-issuer-of — The helpers/is-issuer-of module exposes a pre-filtering / display helper around the parsed certificate data. It is in…
  • observability — (no submodules)- metrics — (no submodules)- pem — (no submodules)- pem — (no submodules)- schemas — (no submodules)- schemas — (no submodules)- alg-map — The signature/alg-map module is part of the certificate signature-verify pipeline. Together with the rest of the `sig…
  • decode-ecdsa-sig — The signature/decode-ecdsa-sig module is part of the certificate signature-verify pipeline. Together with the rest of…
  • verify — The signature/verify module is part of the certificate signature-verify pipeline. Together with the rest of the `sign…
  • trust-anchor — validate/trust-anchor is the core of the certificate path-validation pipeline. validateChain walks the certificate…
  • validate-chain — validate/validate-chain is the core of the certificate path-validation pipeline. validateChain walks the certificat…
  • build-certs — (no submodules)- decoder — Implements decodeAsn1(bytes, mode) covering every ASN.1 production used by RFC 5280 Appendix A: primitive scalars (`I…
  • encoder — Implements encodeAsn1(node) producing canonical DER bytes per X.690 paragraph 10 for any Asn1Node the decoder accep…
  • oid — Encodes and decodes ASN.1 OBJECT IDENTIFIER bodies per X.690 paragraph 8.19. OIDs in X.509 identify algorithms, extensi…
  • strings — Decodes and encodes the typed ASN.1 string types used inside X.509 Names and SubjectAltName entries: UTF8String, `Pri…
  • time — Decodes and encodes the two time formats RFC 5280 paragraph 4.1.2.5 permits inside a certificate's Validity field: `U…
  • name — Decodes RFC 5280 paragraph 4.1.2.4 Name (RDNSequence) structures into a typed shape carrying both the raw DER bytes…
  • parse — Implements parseCertificate(bytes) decoding a DER- or PEM-encoded Certificate into a typed X509Certificate value…
  • errors — (no submodules) - error-codes — (no submodules)- authority-key-id — Decodes the authority-key-id extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • basic-constraints — Decodes the basic-constraints extension into BasicConstraints { cA: boolean; pathLenConstraint?: number }. During pat…
  • crl-distribution-points — Decodes the crl-distribution-points extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is…
  • extended-key-usage — Decodes the extended-key-usage extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is capt…
  • key-usage — Decodes the key-usage extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured from…
  • name-constraints — Decodes the name-constraints extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • registry — Decodes the registry extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured from…
  • subject-alt-name — Decodes the subject-alt-name extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captur…
  • subject-key-id — Decodes the subject-key-id extension per RFC 5280 paragraph 4.2. Every public field in the resulting type is captured…
  • chains-to — The helpers/chains-to module exposes a pre-filtering / display helper around the parsed certificate data. It is indep…
  • has-name-match — The helpers/has-name-match module exposes a pre-filtering / display helper around the parsed certificate data. It is…
  • is-issuer-of — The helpers/is-issuer-of module exposes a pre-filtering / display helper around the parsed certificate data. It is in…
  • observability — (no submodules) - metrics — (no submodules)- pem — (no submodules) - pem — (no submodules)- schemas — (no submodules) - schemas — (no submodules)- alg-map — The signature/alg-map module is part of the certificate signature-verify pipeline. Together with the rest of the `sig…
  • decode-ecdsa-sig — The signature/decode-ecdsa-sig module is part of the certificate signature-verify pipeline. Together with the rest of…
  • verify — The signature/verify module is part of the certificate signature-verify pipeline. Together with the rest of the `sign…
  • trust-anchor — validate/trust-anchor is the core of the certificate path-validation pipeline. validateChain walks the certificate…
  • validate-chain — validate/validate-chain is the core of the certificate path-validation pipeline. validateChain walks the certificat…

Install

bun add @suaveplan/x509

Quick start

import { parseCertificate, validateChain, TrustAnchorStore } from "@suaveplan/x509";

const leaf = parseCertificate(leafDerBytes);
const intermediate = parseCertificate(intermediateDerBytes);
const root = parseCertificate(rootDerBytes);

const result = await validateChain({
    leaf,
    intermediates: [intermediate],
    trustAnchors: [root],
});

console.log(result.trustedPath.length); // 3

Modules

Module Purpose
asn1/decoder TLV decoder for the X.509 ASN.1 subset
asn1/encoder Canonical DER encoder (round-trip with decoder)
asn1/oid OBJECT IDENTIFIER encode / decode
asn1/strings Typed-string decoders (UTF8 / Printable / IA5 / BMP / Universal / Teletex)
asn1/time UTCTime and GeneralizedTime codec
pem/pem RFC 7468 PEM framing
certificate/parse RFC 5280 §4.1 Certificate parser
certificate/name Name codec + canonical comparison
extensions/basic-constraints RFC 5280 §4.2.1.9
extensions/key-usage RFC 5280 §4.2.1.3
extensions/extended-key-usage RFC 5280 §4.2.1.12
extensions/subject-alt-name RFC 5280 §4.2.1.6 + §4.2.2.6
extensions/name-constraints RFC 5280 §4.2.1.10
extensions/authority-key-id RFC 5280 §4.2.1.1
extensions/subject-key-id RFC 5280 §4.2.1.2
extensions/crl-distribution-points RFC 5280 §4.2.1.13 (parse only)
extensions/registry OID-keyed dispatch table
signature/alg-map Signature-algorithm OID lookup
signature/verify Signature verify dispatch
signature/decode-ecdsa-sig ECDSA-Sig-Value DER decoder
validate/validate-chain RFC 5280 §6.1 path-validation algorithm
validate/trust-anchor SKI-indexed trust-anchor store
helpers/has-name-match RFC 6125 host-name match
helpers/chains-to SKI/AKI chaining heuristic
helpers/is-issuer-of Canonical name equality
errors/error-codes Typed error registry
observability/metrics OpenTelemetry surface
schemas/schemas Zod boundary schemas

Out of scope

  • OCSP — interface only (OcspResponderLike); implementation in follow-up @suaveplan/x509-ocsp.
  • CRL fetching — distribution-point parsing only; implementation in follow-up @suaveplan/x509-crl.
  • Certificate issuance / signing — follow-up @suaveplan/x509-ca.
  • Policy mapping / policy constraints — decoded as RawExtension; critical occurrence triggers CRITICAL_EXTENSION_UNRECOGNIZED per RFC 5280 §6.1.4(f).
  • PKCS#12 / PKCS#11 / smartcard — not in scope.
Reference in New Issue View Git Blame Copy Permalink