🔐 Passwordless Authentication

flowchart TD
    User[User / Client]
    Choose[Select Auth Method]
    User --> Choose

    subgraph MagicLink[Magic Link Flow]
        direction TB
        MLRequest[POST /request/magic]
        CreateToken[Generate one-time token]
        EnqueueEmail[Enqueue email job]
        EmailWorker[Email worker picks job]
        SendEmail[Send via SMTP]
        ClickLink[User clicks link]
        VerifyToken[Validate and mark used]
        IssueJWT_ML[Issue JWTs]
    end

    subgraph TOTP[TOTP Flow]
        direction TB
        TOTPEnroll[POST /totp/enroll]
        StoreTOTP[Store TOTP secret]
        TOTPVerify[POST /totp/verify]
        ValidateTOTP[Validate code]
        IssueJWT_TOTP[Issue JWTs]
    end

    subgraph WebAuthn[WebAuthn Flow]
        direction TB
        WebRegOptions[POST /webauthn/register/options]
        CompleteReg[POST /webauthn/register/complete]
        SaveCred[Persist credential]
        WebLoginOptions[POST /webauthn/login/options]
        CompleteLogin[POST /webauthn/login/complete]
        IssueJWT_Web[Issue JWTs]
    end

    subgraph Tokens[Token Management]
        direction TB
        RefreshReq[POST /token/refresh]
        ValidateRefresh[Validate refresh token]
        IssueNewJWT[Issue new JWTs]
    end

    subgraph DB[SQLite Database]
        direction TB
        Users[Users Table]
        MagicTokens[Magic Link Tokens]
        TOTPSecrets[TOTP Secrets]
        WebCreds[WebAuthn Credentials]
        RefreshTokens[Refresh Tokens]
        EmailQueue[Email Queue]
    end

    Choose --> MLRequest
    MLRequest --> CreateToken --> EnqueueEmail
    EnqueueEmail --> EmailQueue
    EmailQueue --> EmailWorker --> SendEmail
    SendEmail --> ClickLink --> VerifyToken --> IssueJWT_ML --> User

    Choose --> TOTPEnroll --> StoreTOTP
    StoreTOTP --> TOTPSecrets
    TOTPVerify --> ValidateTOTP --> IssueJWT_TOTP --> User

    Choose --> WebRegOptions --> CompleteReg --> SaveCred
    SaveCred --> WebCreds
    WebLoginOptions --> CompleteLogin --> IssueJWT_Web --> User

    User --> RefreshReq --> ValidateRefresh
    ValidateRefresh --> RefreshTokens
    ValidateRefresh --> IssueNewJWT --> User
                

classDiagram
    class AuthServer {
        +Config config
        +start()
        +shutdown()
    }

    class MagicLinkService {
        +request_link(email)
        +verify(token)
        +generate_token()
    }

    class TOTPService {
        +enroll(email)
        +verify(email, code)
        +generate_secret()
    }

    class WebAuthnService {
        +begin_registration(email)
        +complete_registration(pending_id, resp)
        +begin_login(email)
        +complete_login(pending_id, resp)
    }

    class JWTService {
        +create_access(user_id)
        +create_refresh(user_id)
        +verify(token)
        +revoke_refresh(token)
    }

    class EmailQueueWorker {
        +enqueue(to, subject, text, html)
        +process_due()
        +retry_failed()
    }

    class SMTPProvider {
        +send(to, subject, body)
        +configure(host, port, username, password)
    }

    class SQLiteDB {
        +execute(query)
        +query(query)
        +transaction()
    }

    class User {
        -String id
        -String email
        -String totp_secret
        -credentials
    }

    class MagicLinkToken {
        -String token
        -DateTime expires_at
        -bool used
        -String user_id
    }

    class RefreshToken {
        -String token
        -DateTime expires_at
        -bool revoked
        -String user_id
    }

    AuthServer --> MagicLinkService
    AuthServer --> TOTPService
    AuthServer --> WebAuthnService
    AuthServer --> JWTService
    AuthServer --> SQLiteDB

    MagicLinkService --> SQLiteDB
    MagicLinkService --> EmailQueueWorker
    EmailQueueWorker --> SMTPProvider
    EmailQueueWorker --> SQLiteDB

    TOTPService --> SQLiteDB
    WebAuthnService --> SQLiteDB
    JWTService --> SQLiteDB

    SQLiteDB --> User
    SQLiteDB --> MagicLinkToken
    SQLiteDB --> RefreshToken
                

sequenceDiagram
    participant U as User
    participant C as Client App
    participant S as Auth Server
    participant DB as Database
    participant SMTP as SMTP Server

    Note over U,SMTP: Magic Link Authentication Flow

    U->>C: Enter email
    C->>S: POST /request/magic
    S->>DB: Create magic token
    S->>DB: Enqueue email
    S-->>C: 200 OK silent

    loop Email Worker
        S->>DB: Fetch pending emails
        S->>SMTP: Send magic link
        SMTP-->>U: Email delivered
    end

    U->>C: Click magic link
    C->>S: GET /verify/magic
    S->>DB: Validate token
    S->>DB: Mark token as used
    S->>DB: Store refresh token
    S-->>C: Return tokens
    C->>C: Store tokens

    Note over U,SMTP: Subsequent Requests

    C->>S: API request with access token
    S->>S: Verify JWT
    S-->>C: Protected resource

    Note over U,SMTP: Token Refresh

    C->>S: POST /token/refresh
    S->>DB: Validate refresh token
    S->>DB: Create new refresh token
    S-->>C: Return new tokens