# jipok/jauth architecture

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

- Interactive diagram: https://gitdiagram.com/jipok/jauth
- Repository: https://github.com/jipok/jauth

## Overview

##### Project type and purpose
- Jauth is a single‐binary Go application that acts as an SSL/TLS reverse proxy with built-in user authorization (via SSH public keys or Telegram SSO). It protects self-hosted services by intercepting incoming HTTP/HTTPS connections, authenticating users, and forwarding traffic to backend targets.

##### File structure
- Top-level Go files (main.go, auth-handler.go, ssl-proxy.go, ssh-server.go, etc.) implement the core logic.
- config/ and config/dsl.go parse a TOML DSL for domains, certificate settings, SSH/Telegram users, whitelist rules.
- www/ holds static HTML pages (login, whitelist error, 502 fallback).
- Scripts (compact.sh, github-key-import.sh) automate key management or build steps.
- go.mod/go.sum define dependencies (net/http, crypto/tls, golang.org/x/crypto/ssh, autocert).

##### Key README insights
- On startup, Jauth loads a config (jauth.toml by default), then:
- Generates or acquires certificates (self-signed or via Let’s Encrypt autocert)
- Listens on port 80 (HTTP) to redirect to HTTPS, and port 443 (HTTPS) for protected resources
- Listens on port 2222 (SSH) to perform public-key authentication and mint session tokens
- Stores session tokens in jauth-tokens.txt, passes authenticated usernames via a Remote-User HTTP header
- For each request, enforces per-domain whitelist rules, then reverse-proxies to the configured target.

##### Detail
- Listeners, the cert-management pathway, both auth methods, the token lifecycle, and backend proxying.
- Per-domain rules: UserSuffix, Whitelist, NoAuth override
- Where drop-privileges and filtering (spam suppression) modules sit in the startup sequence

## Diagram (Mermaid)

```mermaid
graph TB
    %% Subgraph: Startup
    subgraph "Startup Sequence"
        direction TB
        CLI["CLI & Config Loader"]:::config
        CertMgr["Certificate Manager"]:::network
        DropPriv["Drop-Privileges & Sandbox Init"]:::utils
        Logger["Logging Subsystem"]:::utils
    end

    %% Subgraph: Configuration Loader
    subgraph "Config"
        direction TB
        ConfigDSL["DSL Parser (config/dsl.go)"]:::config
    end

    %% Subgraph: Listeners
    subgraph "Listeners"
        direction TB
        HTTPRedirect["HTTP→HTTPS Redirector (80)"]:::network
        HTTPSServer["HTTPS Server w/ TLS (443)"]:::network
        SSHServer["SSH Server (2222)"]:::network
    end

    %% Subgraph: Authentication & Proxy
    subgraph "Auth & Proxy"
        direction TB
        AuthHandler["Authentication Handler"]:::auth
        ReverseProxy["Reverse Proxy Engine"]:::network
    end

    %% Subgraph: Token Storage
    subgraph "Session Store"
        direction TB
        Tokens["Session/Token Store"]:::storage
    end

    %% Subgraph: Utils & Scripts
    subgraph "Utilities"
        direction TB
        Utils["Utility Functions"]:::utils
        Scripts["Helper Scripts"]:::utils
    end

    %% External Services
    ACME["Let’s Encrypt ACME API"]:::external
    Telegram["Telegram Bot"]:::external

    %% Flows
    CLI -->|loads config| ConfigDSL
    CLI -->|initializes| Logger
    CLI -->|initializes| CertMgr
    CLI -->|initializes| DropPriv

    CertMgr -->|requests certs| ACME
    CertMgr -->|serves certs to| HTTPSServer

    HTTPRedirect -->|redirects to| HTTPSServer

    HTTPSServer -->|forwards requests| AuthHandler
    AuthHandler -->|serves login pages| WWWIndex
    AuthHandler -->|serves whitelist error| WWWWhitelist
    AuthHandler -->|serves fallback| WWW502
    AuthHandler -->|on auth success| ReverseProxy

    SSHServer -->|validates public key| KeysStore
    SSHServer -->|issues token| Tokens
    Telegram -->|widget callback| AuthHandler
    AuthHandler -->|issues token| Tokens

    ReverseProxy -->|routes to backend| TargetBackend

    %% Nodes for static pages and keys store
    WWWIndex["www/index.html"]:::auth
    WWWWhitelist["www/NotInWhitelist.html"]:::auth
    WWW502["www/502.html"]:::auth
    KeysStore["AuthorizedKeys"]:::storage
    TargetBackend["Target Backends\n(e.g., 127.0.0.1:8080)"]:::network

    %% Utilities scripts
    Scripts --> compact["compact.sh"]:::utils
    Scripts --> importKey["github-key-import.sh"]:::utils
    Scripts --> wgetKeys["github-wget-keys.sh"]:::utils

    %% Click events for component mapping
    click CLI "https://github.com/jipok/jauth/blob/master/main.go"
    click CLI "https://github.com/jipok/jauth/blob/master/config.go"
    click ConfigDSL "https://github.com/jipok/jauth/blob/master/config/dsl.go"
    click CertMgr "https://github.com/jipok/jauth/blob/master/ssl-proxy.go"
    click CertMgr "https://github.com/jipok/jauth/blob/master/utils.go"
    click HTTPRedirect "https://github.com/jipok/jauth/blob/master/ssl-proxy.go"
    click HTTPSServer "https://github.com/jipok/jauth/blob/master/ssl-proxy.go"
    click AuthHandler "https://github.com/jipok/jauth/blob/master/auth-handler.go"
    click WWWIndex "https://github.com/jipok/jauth/blob/master/www/index.html"
    click WWWWhitelist "https://github.com/jipok/jauth/blob/master/www/NotInWhitelist.html"
    click WWW502 "https://github.com/jipok/jauth/blob/master/www/502.html"
    click SSHServer "https://github.com/jipok/jauth/blob/master/ssh-server.go"
    click Tokens "https://github.com/jipok/jauth/blob/master/tokens.go"
    click DropPriv "https://github.com/jipok/jauth/blob/master/drop-privileges.go"
    click Logger "https://github.com/jipok/jauth/blob/master/logger.go"
    click Utils "https://github.com/jipok/jauth/blob/master/utils.go"
    click compact "https://github.com/jipok/jauth/blob/master/compact.sh"
    click importKey "https://github.com/jipok/jauth/blob/master/github-key-import.sh"
    click wgetKeys "https://github.com/jipok/jauth/blob/master/github-wget-keys.sh"

    %% Styles
    classDef network fill:#D0E6FF,stroke:#0366d6,color:#034c8c
    classDef auth fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10
    classDef config fill:#FFEFD5,stroke:#D2691E,color:#8B4513
    classDef storage fill:#FFD1DC,stroke:#D00000,color:#900
    classDef utils fill:#EEEEEE,stroke:#999,color:#333
    classDef external fill:#FFFACD,stroke:#DAA520,color:#8B7500
```
