Auth Flows

1. Guest flow

sequenceDiagram
    participant C as Client
    participant Auth as auth-service

    C->>Auth: POST /auth/guest {display_name}
    Auth->>Auth: Generate guest_id + signed token
    Auth-->>C: guest_token (TTL 24h)
    Note over C: Authorization: Guest 

FR: FR-009, FR-022

2. Email register + login

sequenceDiagram
    participant U as User
    participant Auth as auth-service

    U->>Auth: POST /auth/register {email, password}
    Auth-->>U: access_jwt + refresh_token
    U->>Auth: POST /auth/login {email, password}
    Auth-->>U: access_jwt + refresh_token

FR: FR-007, FR-021

3. Telegram Login (web)

sequenceDiagram
    participant W as web-app
    participant Auth as auth-service
    participant TG as Telegram

    W->>TG: Login Widget
    TG-->>W: user data + hash
    W->>Auth: POST /auth/telegram {id, hash, ...}
    Auth->>Auth: Verify HMAC with bot token
    Auth-->>W: JWT or link to existing user

FR: FR-008, FR-023

4. Telegram bot implicit auth

• message.from.id → telegram_id
• Bot calls POST /sessions/join with bot service token + telegram_id
• session-service links or creates Participant

FR: FR-024

5. Link Telegram to account

sequenceDiagram
    participant U as User
    participant Auth as auth-service

    U->>Auth: POST /auth/link-telegram (JWT + TG widget data)
    Auth->>Auth: Verify hash, set users.telegram_id
    Auth-->>U: 200 OK

6. Admin OTP flow

sequenceDiagram
    participant A as Admin
    participant Bot as telegram_bot
    participant Auth as auth-service
    participant W as admin_UI

    A->>Bot: /admin login
    Bot->>Auth: POST /auth/admin/otp/request
    Auth-->>Bot: OTP generated
    Bot->>A: DM with 6-digit code
    A->>W: /admin/login username + code
    W->>Auth: POST /auth/admin/otp/verify
    Auth-->>W: admin JWT

• Single admin user (Mihaham); OTP sent only to ADMIN_TELEGRAM_ID.
• See admin-auth.md for full spec.

FR: FR-057, FR-058

Token format

Refresh flow

POST /auth/refresh
Cookie: refresh_token=...
→ new access_jwt

Security requirements

• NFR-011, NFR-013, NFR-014, NFR-015