# ory/fosite architecture

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

## Overview

##### Project type and purpose
- This is a Go-based, security-first OAuth2 & OpenID Connect framework (library), not a complete application or service.
- It provides composable handlers for every OAuth2 and OpenID Connect flow (authorize code, implicit, hybrid, device code, PKCE, JWT bearer, pushed auth, refresh, revoke, introspect, etc.).
- It’s intended to be embedded into your own HTTP server or an OAuth2 service (e.g., ORY Hydra).

##### File structure
- Top-level packages:
- compose – convenience functions to wire together config, storage, crypto, and handlers
- handler – flow-specific handlers (oauth2/, openid/, par, pkce, rfc8628, verifiable)
- token – token strategies (HMAC, JWT)
- internal – core implementations, storage interfaces, strategies, helpers
- Core API entrypoints:
- Fosite public API (fosite.go, client.go, handler.go)
- HTTP handler glue (access_request_handler.go, authorize_request_handler.go, token handlers, introspection handlers, revoke handlers)
- Configuration & build: config.go, Makefile, go.mod, CI/CD workflows, tests & examples.

##### Key insights from the README
- The public API revolves around a provider object created via compose.ComposeAllEnabled(...)
- The provider exposes methods: NewAuthorizeRequest, NewAuthorizeResponse, NewAccessRequest, NewAccessResponse, IntrospectToken, Write…Error/Response.
- You supply: HTTP server endpoints → call Fosite → Fosite calls registered flow handlers → Fosite calls storage interfaces → Fosite generates tokens.

a. Main components:
- Your HTTP Server (external)
- Fosite Provider (compose layer + config + crypto keys)
- OAuth2 & OIDC Handlers (handler/* packages)
- Token Strategies (token/hmac, token/jwt)
- Storage (your implementation or storage/memory)
- Internal core (internal/*: strategies, storage interfaces, request/response models)
b. Interactions:
1. HTTP Server invokes Provider.NewAuthorizeRequest(ctx, req)
2. Provider dispatches to the relevant AuthorizeCode/Implicit/Device/… handler
3. Handler validates client, scopes, redirect URIs, state → calls Storage interfaces to persist codes/tokens
4. On success, Provider.NewAuthorizeResponse bundles tokens/authorization codes via Token Strategies
5. HTTP Server writes response (redirect or JSON) using Provider.WriteAuthorizeResponse
6. Token endpoint flow similarly goes: NewAccessRequest → Token handlers → Storage → Token Strategies → WriteAccessResponse
7. Introspection → Provider.IntrospectToken → Introspector Strategy → Storage check → return active/inactive
c. Architectural patterns & design principles:
- Dependency injection via compose package
- Strategy pattern for token generation and validation (HMAC vs JWT)
- Handler pipeline for each grant type (chain of responsibility)
- Storage abstraction (interfaces in internal/, reference impl in storage/)
- Separation of API (public methods) vs implementation (internal/)
d. Key technologies & libraries:
- Go modules
- Standard library net/http for endpoints
- Crypto (RSA, HMAC) for JWT signing and token strategies
- Config-driven architecture (fosite.Config)
- Testing: extensive unit and integration tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef external fill:#f9f,stroke:#333
    classDef publicapi fill:#ccf,stroke:#333
    classDef compose fill:#cfc,stroke:#333
    classDef handler fill:#fcf,stroke:#333
    classDef storage fill:#ffc,stroke:#333
    classDef token fill:#cff,stroke:#333
    classDef internal fill:#eee,stroke:#333

    HTTP["Your HTTP Server"]:::external

    subgraph "Public API"
        Provider["Fosite Provider\n(NewAuthorizeRequest,NewAccessRequest,IntrospectToken,Write…Response)"]:::publicapi
        Config["fosite.Config"]:::publicapi
    end

    subgraph "Compose Layer"
        Compose["compose.ComposeAllEnabled(...)"]:::compose
    end

    subgraph "Handler Layer"
        subgraph "OAuth2 Flows"
            OAuth2["handler/oauth2/*"]:::handler
        end
        subgraph "OpenID Connect Flows"
            OIDC["handler/openid/*"]:::handler
        end
        subgraph "PAR"
            PAR["handler/par/*"]:::handler
        end
        subgraph "PKCE"
            PKCE["handler/pkce/*"]:::handler
        end
        subgraph "JWT Bearer (RFC7523)"
            RFC7523["handler/rfc7523/*"]:::handler
        end
        subgraph "Device Code (RFC8628)"
            RFC8628["handler/rfc8628/*"]:::handler
        end
        subgraph "Verifiable Credentials"
            VC["handler/verifiable/*"]:::handler
        end
    end

    subgraph "Storage"
        RefStorage["storage/* (memory,transactional)"]:::storage
        ExtStorage["Your Storage Implementation"]:::external
    end

    subgraph "Token Strategies"
        HMAC["token/hmac/*"]:::token
        JWT["token/jwt/*"]:::token
    end

    Internal["internal/*"]:::internal

    HTTP -->|"calls NewAuthorizeRequest"| Provider
    Provider -->|uses| Config
    Provider -->|wired by| Compose

    Compose -->|"registers handlers & strategies"| OAuth2
    Compose -->|"registers handlers & strategies"| OIDC
    Compose -->|"registers handlers & strategies"| PAR
    Compose -->|"registers handlers & strategies"| PKCE
    Compose -->|"registers handlers & strategies"| RFC7523
    Compose -->|"registers handlers & strategies"| RFC8628
    Compose -->|"registers handlers & strategies"| VC

    Provider -->|"dispatches to"| OAuth2
    Provider -->|"dispatches to"| OIDC
    Provider -->|"dispatches to"| PAR
    Provider -->|"dispatches to"| PKCE
    Provider -->|"dispatches to"| RFC7523
    Provider -->|"dispatches to"| RFC8628
    Provider -->|"dispatches to"| VC

    OAuth2 -->|"calls core"| Internal
    OIDC -->|"calls core"| Internal
    PAR -->|"calls core"| Internal
    PKCE -->|"calls core"| Internal
    RFC7523 -->|"calls core"| Internal
    RFC8628 -->|"calls core"| Internal
    VC -->|"calls core"| Internal

    Internal -->|"uses"| RefStorage
    ExtStorage -->|"implements"| Internal
    Internal -->|"uses"| HMAC
    Internal -->|"uses"| JWT

    HTTP -->|"writes response via Write*"| Provider

    class HTTP,ExtStorage external
    class Provider,Config publicapi
    class Compose compose
    class OAuth2,OIDC,PAR,PKCE,RFC7523,RFC8628,VC handler
    class RefStorage storage
    class HMAC,JWT token
    class Internal internal

    click Compose "https://github.com/ory/fosite/tree/master/compose/"
    click Provider "https://github.com/ory/fosite/blob/master/fosite.go"
    click Config "https://github.com/ory/fosite/blob/master/config.go"
    click OAuth2 "https://github.com/ory/fosite/tree/master/handler/oauth2/"
    click OIDC "https://github.com/ory/fosite/tree/master/handler/openid/"
    click PAR "https://github.com/ory/fosite/tree/master/handler/par/"
    click PKCE "https://github.com/ory/fosite/tree/master/handler/pkce/"
    click RFC7523 "https://github.com/ory/fosite/tree/master/handler/rfc7523/"
    click RFC8628 "https://github.com/ory/fosite/tree/master/handler/rfc8628/"
    click VC "https://github.com/ory/fosite/tree/master/handler/verifiable/"
    click RefStorage "https://github.com/ory/fosite/tree/master/storage/"
    click HMAC "https://github.com/ory/fosite/tree/master/token/hmac/"
    click JWT "https://github.com/ory/fosite/tree/master/token/jwt/"
    click Internal "https://github.com/ory/fosite/tree/master/internal/"
```
