VersolaVersola/docs
versola.kzGitHub
RUEN

Архитектура

Architecture Planes

Versola организована в три логических уровня, каждый из которых состоит из независимо разворачиваемых сервисов. Каждый сервис использует собственную БД без общих схем. Все межсервисные взаимодействия происходят через четко определенные HTTP API.

Control Plane

  • Компоненты: central + central-ui + central DB
  • Назначение: Конфигурация и управление платформой
  • Задачи: Администраторы управляют тенантами, клиентами, скоупами, ролями и разрешениями через административную панель. central — единственный источник истины для всей конфигурации.

Data Plane

  • Компоненты: auth + auth DB
  • Назначение: Аутентификация пользователей
  • Задачи: Обрабатывает OAuth 2.1/OIDC потоки, выпускает токены, управляет сессиями аутентификации, проверяет credentials и challenges, хранит пользователей и данные аутентификации. Синхронизирует конфигурацию клиентов и скоупов из central.

Traffic Plane

  • Компоненты: edge + edge DB
  • Назначение: Проксирование пользовательского трафика и авторизация
  • Задачи: Принимает запросы от браузеров/приложений, управляет сессиями браузера, вычисляет CEL-правила авторизации (роли и разрешения), проксирует запросы к upstream бэкендам с инъекцией auth заголовков. Синхронизирует конфигурацию и JWKS из central.

System Context

flowchart TB
    admin[["👤 Admin<br/><i>Manages platform</i>"]]
    user[["👤 End User<br/><i>Accesses apps</i>"]]

    versola["⚡ Versola<br/><b>Identity & Authorization Platform</b>"]

    upstream{{"🔌 Upstream<br/>Backend APIs"}}
    notifications{{"📧 Notification Channel<br/>Notifications"}}

    admin -->|Manage| versola
    user -->|Auth| versola
    versola -->|Proxy| upstream
    versola -->|Request Notification| notifications

    style admin fill:#a78bfa,stroke:#a78bfa,color:#fff
    style user fill:#34d399,stroke:#34d399,color:#fff
    style versola fill:#58a6ff,stroke:#e6edf3,color:#fff,stroke-width:3px
    style upstream fill:#6e7681,stroke:#e6edf3,color:#fff
    style notifications fill:#6e7681,stroke:#e6edf3,color:#fff

На уровне системного контекста Versola взаимодействует с тремя типами участников:

  • Администратор платформы — управляет тенантами, клиентами, ролями, разрешениями и пользователями через административную панель.
  • Конечный пользователь — аутентифицируется и получает доступ к защищённым ресурсам через браузер или приложение.
  • Внешние системы — SMS / Email провайдеры для доставки OTP и клиентские бэкенды, к которым edge проксирует трафик.

Container Diagram

flowchart TB
    admin[["👤 Admin"]]
    user[["👤 User"]]

    subgraph versola["⚡ Versola Platform"]
        ui["central-ui<br/><i>Lit/TS</i><br/>Dashboard"]
        central["central<br/><i>Scala/ZIO</i><br/>Config"]
        edge["edge<br/><i>Scala/ZIO</i><br/>Proxy"]

        db_central[("central DB")]
        db_edge[("edge DB")]

        auth["auth<br/><i>Scala/ZIO</i><br/>OAuth"]
        db_auth[("auth DB")]
    end

    upstream{{"🔌 Upstream<br/>APIs"}}
    notifications{{"📧 Notifications<br/>OTP"}}

    admin -->|Manage| ui
    user -->|Login| edge

    ui -->|API| central
    central -->|R/W| db_central
    edge -->|R/W| db_edge
    edge -->|SSO| auth
    auth -->|R/W| db_auth
    edge -.->|Sync| central
    auth -.->|Sync| central

    edge -->|Proxy| upstream
    auth -->|Request| notifications

    style admin fill:#a78bfa,stroke:#a78bfa,color:#fff
    style user fill:#34d399,stroke:#34d399,color:#fff
    style ui fill:#58a6ff,stroke:#e6edf3,color:#fff
    style central fill:#58a6ff,stroke:#e6edf3,color:#fff
    style edge fill:#58a6ff,stroke:#e6edf3,color:#fff
    style auth fill:#58a6ff,stroke:#e6edf3,color:#fff
    style db_central fill:#1f6feb,stroke:#e6edf3,color:#fff
    style db_edge fill:#1f6feb,stroke:#e6edf3,color:#fff
    style db_auth fill:#1f6feb,stroke:#e6edf3,color:#fff
    style upstream fill:#6e7681,stroke:#e6edf3,color:#fff
    style notifications fill:#6e7681,stroke:#e6edf3,color:#fff
    style versola fill:#161b22,stroke:#e6edf3,stroke-width:2px,color:#e6edf3
Компонент Технологии Назначение
central-ui Lit / TypeScript Административная панель
central Scala 3 / ZIO Источник истины* тенанты, клиенты, скоупы, роли, разрешения
auth Scala 3 / ZIO OAuth 2.1 / OIDC сервер авторизации. Выпускает токены, ведёт аутентификационные потоки
edge Scala 3 / ZIO Клиентский прокси сессий. Управляет сессиями браузера, проксирует запросы
central DB БД Тенанты, клиенты, скоупы, роли, разрешения, JWKS, индекс пользователей
auth DB БД Сессии, коды авторизации, refresh-токены, пользователи, passkey
edge DB БД Edge-сессии, refresh-токены, состояние входа

Web OAuth Login & Proxy Flow

Этот поток используется для браузерных приложений, где edge выступает в роли прокси сессий.

Краткое описание потока:

  1. Браузер → edge GET /login/:presetId
  2. edge перенаправляет в auth /authorize (PKCE + state)
  3. auth ведёт пользователя через цепочку проверок (пароль / OTP / passkey)
  4. auth перенаправляет обратно на edge /complete?code=…
  5. edge обменивает код на токены через POST /token
  6. edge сохраняет refresh-токен в БД, устанавливает cookie EDGE_SESSION (JWT)
  7. При каждом запросе edge валидирует JWT, вычисляет CEL-правила и проксирует запрос с инъекцией заголовка Authorization
sequenceDiagram
    autonumber
    participant B as Browser
    participant E as edge
    participant A as auth
    participant U as Upstream

    B->>E: GET /login/:presetId
    E-->>B: 302 → auth /authorize (PKCE, state)

    note over B,A: Challenge flow (password / OTP / passkey)

    A-->>B: 302 → edge /complete?code=…&state=…
    B->>E: GET /complete?code=…
    E->>A: POST /token (code + PKCE verifier)
    A-->>E: access_token + refresh_token
    E->>E: Store refresh token in DB
    E-->>B: 302 → app  +  Set-Cookie: EDGE_SESSION (JWT)

    note over B,E: Session active — every request carries the cookie

    B->>E: GET /resources/api/v1/data
    E->>E: Validate JWT, evaluate CEL rules
    E->>U: Forward + inject Authorization header (Basic / Bearer)
    U-->>E: 200 OK
    E-->>B: 200 OK (upstream Set-Cookie stripped)

Mobile OAuth Flow

Этот поток используется для нативных мобильных приложений. Ключевое отличие: мобильное приложение получает authorization code через deep link (custom URI scheme) и обменивает его напрямую с auth для получения токенов. Приложение безопасно хранит токены (Keychain/Keystore) и включает access token в заголовок Authorization при отправке запросов через edge. Прокси edge валидирует токен и применяет CEL-правила авторизации перед проксированием к upstream API.

sequenceDiagram
    autonumber
    participant M as Mobile App
    participant A as auth
    participant E as edge
    participant U as Upstream

    M->>A: GET /authorize (PKCE, state, redirect_uri=app-scheme://)

    note over M,A: Challenge flow (password / OTP / passkey)

    A-->>M: 302 → app-scheme://callback?code=…&state=…
    M->>M: Extract code from deep link
    M->>A: POST /token (code + PKCE verifier)
    A-->>M: access_token + refresh_token
    M->>M: Store tokens securely (Keychain / Keystore)

    note over M,E: Session active — app sends requests with access_token

    M->>E: GET /resources/api/v1/data + Authorization: Bearer {access_token}
    E->>E: Validate JWT, evaluate CEL rules
    E->>U: Forward + inject Authorization header (Basic / Bearer)
    U-->>E: 200 OK
    E-->>M: 200 OK

    note over M,A: Token refresh when access token expires

    M->>A: POST /token (grant_type=refresh_token)
    A-->>M: new access_token + refresh_token