# vapor/jwt-kit architecture

> Architecture diagram of the GitHub repository vapor/jwt-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vapor/jwt-kit
- Repository: https://github.com/vapor/jwt-kit

## Overview

##### Project type and purpose
- This is an open-source Swift package (“jwt-kit”) providing JSON Web Token (JWT) signing, verification, and key management.
- It’s a library/module, not a full-stack app. Its main goal is to offer a modular, cryptography-driven API conforming to RFC-7519/7518/8037.

##### File structure
- Top-level directories:
- Sources/JWTKit: core source modules, organized by feature (Claims, ECDSA, EdDSA, HMAC, JWK, None, RSA, Utilities, Vendor, X5C)
- Tests/JWTKitTests: unit tests per algorithm and payload type
- Benchmarks: performance tests for signing, verifying, token lifecycle
- Snippets: example code for JWK/JWTKit usage
- scripts: helper scripts (certificate/token generation)
- .github/workflows: CI pipelines (test, benchmark, api-docs)
- Configuration/build: Package.swift (SwiftPM), .swift-format, .spi.yml

##### Pulling insights from the README
- Core components: JWTKeyCollection actor, JWTSigner protocols, JWTParser/JWTSerializer
- Extensible algorithm plugins: HMAC, RSA/RSAPSS, ECDSA, EdDSA, “none”
- Standard claims package and custom parsing/serialization support
- Integration point: Vapor’s jwt package wraps this for frameworks

- Interface Layer
– JWTKeyCollection (actor)
– JWTSigner protocols & Implementations
– JWTParser / JWTSerializer
- Algorithm Plugins
– HMACSigner (HS256/384/512)
– RSASigner / PSSSigner (RS256/384/512, PS256/384/512)
– ECDSASigner (ES256/384/512)
– EdDSASigner (Ed25519)
– UnsecuredNoneSigner
- Claims Library
– Standard claims (Expiration, Issuer, Audience, etc.)
– Custom claims, multi-value, epoch, locale
- Key Representations
– JWK / JWKS loader
– PEM/Certificate loaders (Insecure.RSA, ES…PublicKey)
- Utilities & Vendor
– Base64URL, CryptoSigner abstraction, JSONCoders
- Support & QA
– Tests suite
– Benchmarks
– Example Snippets
- External Tools / Consumers
– Vapor/jwt integration
– Command-line scripts

1. Consumer code → calls JWTKeyCollection.sign/verify
2. JWTKeyCollection delegates to selected JWTSigner
3. JWTSigner uses Utilities (CryptoSigner, Base64URL) → produces token bytes
4. Parser/Serializer handle header/payload encoding and decoding
5. Claims.verify(using:) invoked inside verify workflow
6. Key loaders (JWK/JWKS/PEM) populate JWTKeyCollection
7. CI pipeline triggers Tests and Benchmarks

c. Architectural patterns and principles:
- Strategy pattern: pluggable JWTSigner implementations
- Actor model: JWTKeyCollection is an async-safe actor for key management
- Layered separation: parsing, signing, claims verification, key loading
- Protocol-oriented modularity: JWTParser/JWTSerializer protocols, JWTPayload protocol
- Extensibility points: algorithm modules, custom parser/serializer injection

d. Key technologies and frameworks:
- Swift 6+ and SwiftPM
- SwiftCrypto for cryptographic primitives
- DocC for generating API docs (Docs.docc)
- GitHub Actions for CI (test, benchmark, docs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Public API
    subgraph "Public API"
        KCollection["JWTKeyCollection"]:::publicAPI
        SignerProtocol["JWTSigner Protocol"]:::publicAPI
        Parser["JWTParser"]:::publicAPI
        Serializer["JWTSerializer"]:::publicAPI
    end

    %% Algorithm Plugins
    subgraph "Algorithm Plugins"
        HMAC["HMACSigner"]:::plugins
        RSA["RSASigner/PSSSigner"]:::plugins
        ECDSA["ECDSASigner"]:::plugins
        EdDSA["EdDSASigner"]:::plugins
        None["UnsecuredNoneSigner"]:::plugins
    end

    %% Claims Library
    subgraph "Claims Library"
        Claims["Standard & Custom Claims"]:::claims
    end

    %% Key Representations
    subgraph "Key Representations"
        JWK["JWK/JWKS Loader"]:::keyrepr
        PEM["PEM/Certificate Loader"]:::keyrepr
        X5C["X5C Verifier"]:::keyrepr
    end

    %% Utilities & Vendor
    subgraph "Utilities & Vendor"
        Utils["Utilities & Vendor"]:::utils
    end

    %% Support & QA
    subgraph "Support & QA"
        Tests["Test Suite"]:::support
        Bench["Benchmarks"]:::support
        Snip["Example Snippets"]:::support
        CI["CI Pipelines"]:::support
    end

    %% External Consumers
    subgraph "External Consumers"
        Vapor["Vapor/jwt Integration"]:::external
        CLI["Command-line Scripts"]:::external
    end

    %% Relationships
    Vapor -->|"uses"| KCollection
    CLI -->|"uses"| KCollection

    KCollection -->|"delegates to"| SignerProtocol
    KCollection -->|"populates via"| JWK
    KCollection -->|"populates via"| PEM
    KCollection -->|"populates via"| X5C

    SignerProtocol -->|"implements"| HMAC
    SignerProtocol -->|"implements"| RSA
    SignerProtocol -->|"implements"| ECDSA
    SignerProtocol -->|"implements"| EdDSA
    SignerProtocol -->|"implements"| None

    HMAC -->|"uses"| Utils
    RSA -->|"uses"| Utils
    ECDSA -->|"uses"| Utils
    EdDSA -->|"uses"| Utils
    None -->|"uses"| Utils

    Parser -->|"decodes token"| KCollection
    Parser -->|"verifies claims via"| Claims
    Serializer -->|"encodes payload"| SignerProtocol

    %% Support flows
    CI --> Tests
    CI --> Bench
    CI --> Snip

    %% Click Events
    click KCollection "https://github.com/vapor/jwt-kit/blob/main/Sources/JWTKit/JWTKeyCollection.swift"
    click SignerProtocol "https://github.com/vapor/jwt-kit/blob/main/Sources/JWTKit/JWTSigner.swift"
    click Parser "https://github.com/vapor/jwt-kit/blob/main/Sources/JWTKit/JWTParser.swift"
    click Serializer "https://github.com/vapor/jwt-kit/blob/main/Sources/JWTKit/JWTSerializer.swift"
    click Claims "https://github.com/vapor/jwt-kit/tree/main/Sources/JWTKit/Claims/"
    click HMAC "https://github.com/vapor/jwt-kit/blob/main/Sources/JWTKit/HMAC/HMACSigner.swift"
    click RSA "https://github.com/vapor/jwt-kit/blob/main/Sources/JWTKit/RSA/RSASigner.swift"
    click ECDSA "https://github.com/vapor/jwt-kit/blob/main/Sources/JWTKit/ECDSA/ECDSASigner.swift"
    click EdDSA "https://github.com/vapor/jwt-kit/blob/main/Sources/JWTKit/EdDSA/EdDSASigner.swift"
    click None "https://github.com/vapor/jwt-kit/blob/main/Sources/JWTKit/None/UnsecuredNoneSigner.swift"
    click JWK "https://github.com/vapor/jwt-kit/tree/main/Sources/JWTKit/JWK/"
    click PEM "https://github.com/vapor/jwt-kit/blob/main/Sources/JWTKit/Insecure/Insecure.swift"
    click Utils "https://github.com/vapor/jwt-kit/tree/main/Sources/JWTKit/Utilities/"
    click X5C "https://github.com/vapor/jwt-kit/tree/main/Sources/JWTKit/X5C/"
    click Tests "https://github.com/vapor/jwt-kit/tree/main/Tests/JWTKitTests/"
    click Bench "https://github.com/vapor/jwt-kit/tree/main/Benchmarks/"
    click Snip "https://github.com/vapor/jwt-kit/tree/main/Snippets/"
    click CI "https://github.com/vapor/jwt-kit/tree/main/.github/workflows/"

    %% Styles
    classDef publicAPI fill:#B3DDF2,stroke:#333,stroke-width:1px
    classDef plugins fill:#A8D5BA,stroke:#333,stroke-width:1px
    classDef claims fill:#F9E79F,stroke:#333,stroke-width:1px
    classDef keyrepr fill:#D5D8DC,stroke:#333,stroke-width:1px
    classDef utils fill:#E5E7E9,stroke:#333,stroke-width:1px
    classDef support fill:#F5CBA7,stroke:#333,stroke-width:1px
    classDef external fill:#D6EAF8,stroke:#333,stroke-width:1px
```
