# vapor/auth architecture

> Architecture diagram of the GitHub repository vapor/auth, 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/auth
- Repository: https://github.com/vapor/auth

## Overview

##### Project type and purpose
- This is a Swift package named “Auth” that provides authentication middleware and protocols for Vapor 3 applications. It is not a standalone server or end-user app but a library module you plug into your Vapor web service to handle user authentication via multiple strategies (Basic, Bearer, Header, Password, Token, Session-persisted).

##### File structure
- Top-level
- Package.swift – SwiftPM manifest
- README.md, CONTRIBUTING.md, circle.yml
- Sources/Authentication – root of the library
- Tests/AuthenticationTests – unit tests
- Sources/Authentication subdirectories
- Core protocols and types:
– Authenticatable.swift
– AuthenticationProvider.swift
– AuthenticationCache.swift
– Exports.swift
- Strategy modules:
– Basic/BasicAuthenticatable.swift, BasicAuthenticationMiddleware.swift
– Bearer/BearerAuthenticatable.swift, BearerAuthenticationMiddleware.swift
– Header/HeaderAuthenticatableMiddleware.swift, HeaderValueAuthenticatable.swift
– Password/PasswordAuthenticatable.swift, PasswordVerifier.swift
– Token/TokenAuthenticatable.swift, TokenAuthenticationMiddleware.swift
– Persist/AuthenticationSessionsMiddleware.swift, RedirectMiddleware.swift, SessionAuthenticatable.swift
- Utilities: AuthenticationError.swift, GuardMiddleware.swift

##### Essential architectural elements
- Detail each strategy’s position in the pipeline
- How the AuthenticationCache intersects with multiple strategies
- Registration step (AuthenticationProvider) at boot time
- Do not over-fragment: group similar strategies visually but call out each for clarity

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Consumer Vapor Application"
        Request["HTTP Request"]:::external
        AppRoutes["Route Handlers"]:::external
    end

    subgraph "Auth Package Internals"
        subgraph "Provider & Pipeline"
            Provider["AuthenticationProvider"]:::core
            MiddlewareChain["Middleware Chain"]:::core
            Guard["GuardMiddleware"]:::core
            Cache["AuthenticationCache"]:::core
        end
        Exports["Exports"]:::core

        subgraph "Protocols"
            ProtAuth["Authenticatable"]:::protocol
            ProtSession["SessionAuthenticatable"]:::protocol
            ProtToken["TokenAuthenticatable"]:::protocol
            ProtHeader["HeaderValueAuthenticatable"]:::protocol
            ProtPassword["PasswordAuthenticatable"]:::protocol
        end

        subgraph "Strategies"
            BasicMid["BasicAuthenticationMiddleware"]:::strategy
            BasicProt["BasicAuthenticatable"]:::protocol
            BearerMid["BearerAuthenticationMiddleware"]:::strategy
            BearerProt["BearerAuthenticatable"]:::protocol
            HeaderMid["HeaderAuthenticatableMiddleware"]:::strategy
            HeaderValProt["HeaderValueAuthenticatable"]:::protocol
            PassVerifier["PasswordVerifier"]:::strategy
            PasswordProt["PasswordAuthenticatable"]:::protocol
            TokenMid["TokenAuthenticationMiddleware"]:::strategy
            TokenProt2["TokenAuthenticatable"]:::protocol
            SessionMid["AuthenticationSessionsMiddleware"]:::strategy
            Redirect["RedirectMiddleware"]:::strategy
            SessionProt2["SessionAuthenticatable"]:::protocol
        end
    end

    subgraph "External Services"
        SessionStore["Session Store"]:::external
        Database["Database/Token Store"]:::external
        OAuthProvider["OAuth/OpenID Provider"]:::external
    end

    Request --> Provider
    Provider --> MiddlewareChain
    MiddlewareChain --> Guard
    Guard --> BasicMid
    Guard --> BearerMid
    Guard --> HeaderMid
    Guard --> PassVerifier
    Guard --> TokenMid
    Guard --> SessionMid
    MiddlewareChain --> Cache
    MiddlewareChain --> AppRoutes

    BasicMid --> BasicProt
    BearerMid --> BearerProt
    HeaderMid --> HeaderValProt
    PassVerifier --> PasswordProt
    PassVerifier --> Database
    TokenMid --> TokenProt2
    TokenMid --> Database
    SessionMid --> SessionProt2
    SessionMid --> SessionStore
    SessionMid --> Redirect

    click Provider "https://github.com/vapor/auth/blob/master/Sources/Authentication/AuthenticationProvider.swift"
    click Cache "https://github.com/vapor/auth/blob/master/Sources/Authentication/AuthenticationCache.swift"
    click Exports "https://github.com/vapor/auth/blob/master/Sources/Authentication/Exports.swift"
    click ProtAuth "https://github.com/vapor/auth/blob/master/Sources/Authentication/Authenticatable.swift"
    click BasicMid "https://github.com/vapor/auth/blob/master/Sources/Authentication/Basic/BasicAuthenticationMiddleware.swift"
    click BasicProt "https://github.com/vapor/auth/blob/master/Sources/Authentication/Basic/BasicAuthenticatable.swift"
    click BearerMid "https://github.com/vapor/auth/blob/master/Sources/Authentication/Bearer/BearerAuthenticationMiddleware.swift"
    click BearerProt "https://github.com/vapor/auth/blob/master/Sources/Authentication/Bearer/BearerAuthenticatable.swift"
    click HeaderMid "https://github.com/vapor/auth/blob/master/Sources/Authentication/Header/HeaderAuthenticatableMiddleware.swift"
    click HeaderValProt "https://github.com/vapor/auth/blob/master/Sources/Authentication/Header/HeaderValueAuthenticatable.swift"
    click PassVerifier "https://github.com/vapor/auth/blob/master/Sources/Authentication/Password/PasswordVerifier.swift"
    click PasswordProt "https://github.com/vapor/auth/blob/master/Sources/Authentication/Password/PasswordAuthenticatable.swift"
    click TokenMid "https://github.com/vapor/auth/blob/master/Sources/Authentication/Token/TokenAuthenticationMiddleware.swift"
    click TokenProt2 "https://github.com/vapor/auth/blob/master/Sources/Authentication/Token/TokenAuthenticatable.swift"
    click SessionMid "https://github.com/vapor/auth/blob/master/Sources/Authentication/Persist/AuthenticationSessionsMiddleware.swift"
    click Redirect "https://github.com/vapor/auth/blob/master/Sources/Authentication/Persist/RedirectMiddleware.swift"
    click SessionProt2 "https://github.com/vapor/auth/blob/master/Sources/Authentication/Persist/SessionAuthenticatable.swift"
    click ExError "https://github.com/vapor/auth/blob/master/Sources/Authentication/Utilities/AuthenticationError.swift"
    click Guard "https://github.com/vapor/auth/blob/master/Sources/Authentication/Utilities/GuardMiddleware.swift"
    click Manifest "https://github.com/vapor/auth/blob/master/Package.swift"
    click Root "https://github.com/vapor/auth/tree/master/Sources/Authentication"
    click Tests "https://github.com/vapor/auth/tree/master/Tests/AuthenticationTests"

    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef strategy fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef protocol fill:#D3D3D3,stroke:#333,stroke-width:1px
```
