# 61131/nginx-http-auth-totp architecture

> Architecture diagram of the GitHub repository 61131/nginx-http-auth-totp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/61131/nginx-http-auth-totp
- Repository: https://github.com/61131/nginx-http-auth-totp

## Overview

##### Main Components

a. External Components:
- Client (Browser/API Client)
- Nginx Web Server
- TOTP Generator (Client-side authenticator app)

b. Internal Module Components:
- TOTP Authentication Module
- Configuration Handler
- TOTP Validator
- Cookie Manager
- User/Secret Store

##### Key Relationships to Highlight

Layer 1 (Client Interaction):
- Client making HTTP requests to Nginx
- TOTP generator (like Google Authenticator) interaction with the user

Layer 2 (Nginx Integration):
- How the module integrates with Nginx's request processing pipeline
- HTTP Basic Authentication flow

Layer 3 (Module Internals):
- TOTP validation logic
- Cookie-based session management
- User/secret file interaction

##### Specific Elements

Use the following visual elements:
- Diamonds for decision points
- Authentication requests
- TOTP validation
- Cookie management
- Configuration reading

##### Key Processes to Illustrate

a. Authentication Flow:
##### Session cookie creation and management

b. Configuration Flow:

##### Important Details to Note

- Configurable parameters:
- Time step (default 30s)
- TOTP length (1-8 digits)
- Skew window
- Cookie settings
- Realm configuration

##### Notes Section

A notes section highlighting:
- RFC compliance (4226, 6238, 7235)
- Security considerations
- Time synchronization requirements
- Cookie-based session handling

Remember to emphasize the integration points with Nginx and how the module hooks into the standard HTTP authentication flow. This will help developers understand both the module's operation and its place within the larger Nginx ecosystem.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Define styles
    classDef external fill:#b3d1ff,stroke:#333
    classDef core fill:#90EE90,stroke:#333
    classDef security fill:#ffb3b3,stroke:#333
    classDef storage fill:#fff2b3,stroke:#333

    %% Client Layer
    subgraph ClientLayer["Client Layer"]
        Client["Client Browser/API"]:::external
        TOTPGen["TOTP Generator\n(Authenticator App)"]:::external
    end

    %% Nginx Layer
    subgraph NginxLayer["Nginx Layer"]
        Nginx["Nginx Web Server"]:::external
        AuthModule["TOTP Authentication Module"]:::core
        ConfigHandler["Configuration Handler"]:::core
    end

    %% Module Layer
    subgraph ModuleLayer["Module Components"]
        TOTPValidator["TOTP Validator"]:::security
        CookieManager["Cookie Manager"]:::security
        UserStore["User/Secret Store"]:::storage
    end

    %% Relationships
    Client -->|1. HTTP Request| Nginx
    TOTPGen -->|2. Generates TOTP| Client
    Nginx -->|3. Auth Request| AuthModule
    AuthModule -->|4. Load Config| ConfigHandler
    ConfigHandler -->|5. Read Users| UserStore
    AuthModule -->|6. Validate TOTP| TOTPValidator
    TOTPValidator -->|7. Check Time Window| TOTPValidator
    AuthModule -->|8. Session Management| CookieManager
    CookieManager -->|9. Set Cookie| Client

    %% Notes
    subgraph Notes["Important Notes"]
        RFC["RFC Compliance:<br/>4226, 6238, 7235"]
        Security["Security:<br/>- Time sync required<br/>- Cookie-based sessions"]
        Config["Configuration:<br/>- Time step: 30s<br/>- TOTP length: 1-8<br/>- Skew window"]
    end

    %% Legend
    subgraph Legend["Legend"]
        L1["External Components"]:::external
        L2["Core Components"]:::core
        L3["Security Components"]:::security
        L4["Storage Components"]:::storage
    end

    %% Click events
    click AuthModule "https://github.com/61131/nginx-http-auth-totp/blob/main/ngx_http_auth_totp.c"
    click ConfigHandler "https://github.com/61131/nginx-http-auth-totp/blob/main/ngx_http_auth_totp.h"
    click TOTPValidator "https://github.com/61131/nginx-http-auth-totp/tree/main/config"
```
