# lcobucci/jwt architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source PHP library (lcobucci/jwt) that implements JSON Web Token (JWT) and JSON Web Signature (JWS) per RFC 7519/7515.
- Its public API lets consuming code build, sign, encode, parse, and validate JWTs.

##### File structure
- No “frontend/backend” – this is a library.
- src/ holds all core components, organized by responsibility:
- Builder, Encoder, Decoder, Parser, JwtFacade – the high-level public interface
- Encoding/… – formatters and encoders that transform the token DTO into a JWS compact representation
- Signer/… – a strategy hierarchy for signing algorithms (HMAC, RSA, ECDSA, EdDSA, Blake2b) plus key-management abstractions
- Token/… – token data structures, DTO builders and parsers
- Validation/… – a Constraint→Validator subsystem that checks claims and signature integrity
- Configuration – central factory for wiring encoders, decoders, signers and validation rules
- tests/ and docs/ confirm modular design; mkdocs.yml suggests readthedocs for external docs

##### Key insights from README
- Project exposes a simple façade for JWT handling
- Supports multiple signing algorithms, pluggable formatters and validators
- Extensible by supplying custom constraints or encoders

##### Main components
a. Public API Layer (JwtFacade / Builder / Configuration)
b. Core Token Representation (Token DTOs, Claims)
c. Encoding & Crypto
- Encoding Chain: ChainedFormatter → JOSE encoder → base64 polyfill → timestamp formatters
- Signer Strategy: HMAC, RSA, ECDSA, EdDSA, Blake2b + Key abstractions (InMemory, File)
d. Parsing & Decoding (Parser, Decoder)
e. Validation Layer (Validator + Constraint objects)
f. External Interfaces (User code consumption, HTTP/transports)

##### Relationships & interactions
- User code calls JwtFacade (or Builder + Encoder + Signer) to produce a serialized JWT string
- Serialized JWT travels over HTTP or messaging layer
- Consumer code feeds the JWT to Parser → Decoder → reconstruct Token DTO
- Validator runs a set of Constraint objects on the Token DTO (including signature verification via Signer)
- Configuration object wires together the correct Encoder, Decoder, Signer, and Validator

##### Architectural patterns & design principles
- Facade (JwtFacade) simplifies public API
- Builder pattern for token assembly
- Strategy pattern for pluggable signing algorithms and formatters
- Dependency Injection via Configuration for extensibility
- Single Responsibility: separate packages for encoding, signing, parsing, validation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Consumer
    Consumer["Consumer Code"]:::external

    %% Public API Layer
    subgraph "Public API Layer"
        JwtFacade["JwtFacade"]:::publicAPI
        Builder["Builder"]:::publicAPI
        Configuration["Configuration"]:::publicAPI
    end

    %% Token Model
    subgraph "Core Token Representation"
        Token["Token DTO"]:::token
        UnencryptedToken["UnencryptedToken"]:::token
        TokenBuilder["Token Builder"]:::token
        TokenParserDTO["Token Parser"]:::token
        DataSet["Token DataSet"]:::token
        SignatureModel["Token Signature model"]:::token
        RegisteredClaims["Registered Claims"]:::token
        InvalidStructure["InvalidTokenStructure"]:::token
        UnsupportedHeader["UnsupportedHeaderFound"]:::token
        RegisteredClaimGiven["RegisteredClaimGiven"]:::token
        ClaimsFormatter["ClaimsFormatter"]:::token
    end

    %% Encoding & Crypto
    subgraph "Encoding & Crypto"
        EncoderFacade["Encoder"]:::crypto
        subgraph "Formatter Chain"
            ChainedFormatter["ChainedFormatter"]:::crypto
            JoseEncoder["JoseEncoder"]:::crypto
            UnixDates["UnixTimestampDates"]:::crypto
            MicrosecDates["MicrosecondBasedDateConversion"]:::crypto
            UnifyAud["UnifyAudience"]:::crypto
        end
        SodiumBase64["SodiumBase64Polyfill"]:::crypto
        SignerInterface["Signer"]:::crypto
        subgraph "Signer Strategy"
            HMAC["HMAC"]:::crypto
            RSA["RSA"]:::crypto
            ECDSA["ECDSA"]:::crypto
            EdDSA["EdDSA"]:::crypto
            Blake2b["Blake2b"]:::crypto
            OpenSSL["OpenSSL adapter"]:::crypto
        end
        subgraph "Key Abstractions"
            KeyInterface["Key interface"]:::crypto
            InMemoryKey["InMemory Key"]:::crypto
            FileKey["File key loader"]:::crypto
        end
    end

    %% Parsing & Decoding
    subgraph "Parsing & Decoding"
        Parser["Parser"]:::crypto
        Decoder["Decoder"]:::crypto
    end

    %% Validation Layer
    subgraph "Validation Layer"
        ValidatorFacade["Validator"]:::validation
        CoreValidator["Core Validator"]:::validation
        ConstraintInterface["Constraint interface"]:::validation
        subgraph "Built-in Constraints"
            HasClaim["HasClaim"]:::validation
            IssuedBy["IssuedBy"]:::validation
            SignedWithRule["SignedWith adapter"]:::validation
            ValidAtRule["ValidAt adapter"]:::validation
        end
        NoConstraints["NoConstraintsGiven"]:::validation
        RequiredViolated["RequiredConstraintsViolated"]:::validation
        ConstraintViolation["ConstraintViolation"]:::validation
    end

    %% Data Flow
    Consumer -->|"calls"| JwtFacade
    JwtFacade -->|"builds token"| Builder
    Builder -->|"produces Token DTO"| TokenBuilder
    TokenBuilder --> Token
    JwtFacade -->|"uses"| Configuration

    Token -->|"formats claims"| ClaimsFormatter
    ClaimsFormatter --> EncoderFacade
    EncoderFacade --> ChainedFormatter
    ChainedFormatter --> JoseEncoder
    JoseEncoder --> UnixDates
    UnixDates --> MicrosecDates
    MicrosecDates --> UnifyAud
    UnifyAud --> SodiumBase64
    SodiumBase64 --> SignerInterface
    SignerInterface --> HMAC
    SignerInterface --> RSA
    SignerInterface --> ECDSA
    SignerInterface --> EdDSA
    SignerInterface --> Blake2b
    SignerInterface --> OpenSSL
    SignerInterface --> KeyInterface
    KeyInterface --> InMemoryKey
    KeyInterface --> FileKey

    EncoderFacade -->|"JWT string"| Consumer

    Consumer -->|"passes JWT"| Parser
    Parser --> Decoder
    Decoder --> TokenParserDTO
    TokenParserDTO --> DataSet
    TokenParserDTO --> SignatureModel
    TokenParserDTO --> RegisteredClaims
    TokenParserDTO --> InvalidStructure
    TokenParserDTO --> UnsupportedHeader
    TokenParserDTO --> RegisteredClaimGiven

    DataSet --> ValidatorFacade
    SignatureModel --> ValidatorFacade
    ValidatorFacade --> CoreValidator
    CoreValidator --> ConstraintInterface
    ConstraintInterface --> HasClaim
    ConstraintInterface --> IssuedBy
    ConstraintInterface --> SignedWithRule
    ConstraintInterface --> ValidAtRule
    CoreValidator --> NoConstraints
    CoreValidator --> RequiredViolated
    CoreValidator --> ConstraintViolation
    CoreValidator --> ValidatorFacade
    ValidatorFacade -->|"validated Token DTO"| Consumer

    %% Click Events
    click JwtFacade "https://github.com/lcobucci/jwt/blob/6.0.x/src/JwtFacade.php"
    click Builder "https://github.com/lcobucci/jwt/blob/6.0.x/src/Builder.php"
    click Configuration "https://github.com/lcobucci/jwt/blob/6.0.x/src/Configuration.php"
    click Token "https://github.com/lcobucci/jwt/blob/6.0.x/src/Token.php"
    click UnencryptedToken "https://github.com/lcobucci/jwt/blob/6.0.x/src/UnencryptedToken.php"
    click TokenBuilder "https://github.com/lcobucci/jwt/blob/6.0.x/src/Token/Builder.php"
    click TokenParserDTO "https://github.com/lcobucci/jwt/blob/6.0.x/src/Token/Parser.php"
    click DataSet "https://github.com/lcobucci/jwt/blob/6.0.x/src/Token/DataSet.php"
    click SignatureModel "https://github.com/lcobucci/jwt/blob/6.0.x/src/Token/Signature.php"
    click RegisteredClaims "https://github.com/lcobucci/jwt/blob/6.0.x/src/Token/RegisteredClaims.php"
    click InvalidStructure "https://github.com/lcobucci/jwt/blob/6.0.x/src/Token/InvalidTokenStructure.php"
    click UnsupportedHeader "https://github.com/lcobucci/jwt/blob/6.0.x/src/Token/UnsupportedHeaderFound.php"
    click RegisteredClaimGiven "https://github.com/lcobucci/jwt/blob/6.0.x/src/Token/RegisteredClaimGiven.php"
    click ClaimsFormatter "https://github.com/lcobucci/jwt/blob/6.0.x/src/ClaimsFormatter.php"
    click EncoderFacade "https://github.com/lcobucci/jwt/blob/6.0.x/src/Encoder.php"
    click Decoder "https://github.com/lcobucci/jwt/blob/6.0.x/src/Decoder.php"
    click ChainedFormatter "https://github.com/lcobucci/jwt/blob/6.0.x/src/Encoding/ChainedFormatter.php"
    click JoseEncoder "https://github.com/lcobucci/jwt/blob/6.0.x/src/Encoding/JoseEncoder.php"
    click UnixDates "https://github.com/lcobucci/jwt/blob/6.0.x/src/Encoding/UnixTimestampDates.php"
    click MicrosecDates "https://github.com/lcobucci/jwt/blob/6.0.x/src/Encoding/MicrosecondBasedDateConversion.php"
    click UnifyAud "https://github.com/lcobucci/jwt/blob/6.0.x/src/Encoding/UnifyAudience.php"
    click SodiumBase64 "https://github.com/lcobucci/jwt/blob/6.0.x/src/SodiumBase64Polyfill.php"
    click SignerInterface "https://github.com/lcobucci/jwt/blob/6.0.x/src/Signer.php"
    click HMAC "https://github.com/lcobucci/jwt/blob/6.0.x/src/Signer/Hmac.php"
    click RSA "https://github.com/lcobucci/jwt/blob/6.0.x/src/Signer/Rsa.php"
    click ECDSA "https://github.com/lcobucci/jwt/blob/6.0.x/src/Signer/Ecdsa.php"
    click EdDSA "https://github.com/lcobucci/jwt/blob/6.0.x/src/Signer/Eddsa.php"
    click Blake2b "https://github.com/lcobucci/jwt/blob/6.0.x/src/Signer/Blake2b.php"
    click OpenSSL "https://github.com/lcobucci/jwt/blob/6.0.x/src/Signer/OpenSSL.php"
    click KeyInterface "https://github.com/lcobucci/jwt/blob/6.0.x/src/Signer/Key.php"
    click InMemoryKey "https://github.com/lcobucci/jwt/blob/6.0.x/src/Signer/Key/InMemory.php"
    click FileKey "https://github.com/lcobucci/jwt/blob/6.0.x/src/Signer/Key/FileCouldNotBeRead.php"
    click Parser "https://github.com/lcobucci/jwt/blob/6.0.x/src/Parser.php"
    click ValidatorFacade "https://github.com/lcobucci/jwt/blob/6.0.x/src/Validator.php"
    click CoreValidator "https://github.com/lcobucci/jwt/blob/6.0.x/src/Validation/Validator.php"
    click ConstraintInterface "https://github.com/lcobucci/jwt/blob/6.0.x/src/Validation/Constraint.php"
    click NoConstraints "https://github.com/lcobucci/jwt/blob/6.0.x/src/Validation/NoConstraintsGiven.php"
    click RequiredViolated "https://github.com/lcobucci/jwt/blob/6.0.x/src/Validation/RequiredConstraintsViolated.php"
    click ConstraintViolation "https://github.com/lcobucci/jwt/blob/6.0.x/src/Validation/ConstraintViolation.php"
    click SignedWithRule "https://github.com/lcobucci/jwt/blob/6.0.x/src/Validation/SignedWith.php"
    click ValidAtRule "https://github.com/lcobucci/jwt/blob/6.0.x/src/Validation/ValidAt.php"

    %% Styles
    classDef publicAPI fill:#b6e3b6,stroke:#333,stroke-width:1px
    classDef token fill:#c6dbef,stroke:#333,stroke-width:1px
    classDef crypto fill:#fdd0a2,stroke:#333,stroke-width:1px
    classDef validation fill:#d4b9da,stroke:#333,stroke-width:1px
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
```
