Backend / REST API

API: Аутентификация

Эндпоинты регистрации, входа, управления сессиями, TOTP, QR-авторизации и валидации токенов Media SFU. Префикс: /auth. Файл: srv/app/api/endpoints/auth.py

Обзор эндпоинтов

МетодПутьAuthОписание
POST/auth/login—Вход по логину/паролю (JSON)
POST/auth/login-oauth—Вход через OAuth2 form-data
POST/auth/registerAdmin onlyСоздание нового пользователя
POST/auth/refresh—Обновление access токена
POST/auth/logoutBearerЗавершение текущей сессии
POST/auth/setup-accountBearerНастройка аккаунта + E2EE ключей
POST/auth/totp/enableBearerГенерация TOTP секрета (начало активации)
POST/auth/totp/verifyBearerПодтверждение TOTP кода (финализация)
POST/auth/totp/disableBearerОтключение двухфакторной аутентификации
GET/auth/sessionsBearerСписок активных сессий устройств
DELETE/auth/sessions/clear-othersBearerЗавершить все сессии кроме текущей
DELETE/auth/sessions/{session_id}BearerЗавершить конкретную сессию
POST/auth/update-fcmBearerОбновить FCM токен для push уведомлений
POST/auth/qr/approveBearerАвторизовать новое устройство через QR-код
POST/api/v1/internal/verify-tokenInternal RPCВерификация токена звонка (UDP Relay SFU)
POST/api/v1/internal/verify-token-onlyInternal RPCБыстрая валидация токена сессии (QUIC SFU)

Авторизация и токены

API использует два типа JWT токенов:

ТипСрок действияНазначение
access_token30 минутАвторизация запросов через заголовок Authorization: Bearer {token}
refresh_token30 днейПолучение нового access_token через POST /auth/refresh

Оба токена содержат в payload: sub (user_id), session_id (ID записи в таблице sessions), exp (время истечения).

JWT Payload
{
  "sub": "123",          // user_id
  "session_id": 45,      // ID сессии в БД
  "exp": 1750000000      // unix timestamp истечения
}

POST /auth/login

Основной метод входа. При успехе создаёт запись Session, отправляет системное уведомление о новом входе.

Request Body (JSON)
{
  "username": "alice",       // Обязательно
  "password": "secret123",   // Обязательно
  "totp_code": "123456"      // Требуется если включена 2FA
}
Response 200 OK
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user_id": 123
}

POST /auth/setup-account

Сохраняет публичный X25519 и зашифрованный приватный ключ при инициализации аккаунта (вызывается на экране AccountSetupScreen). Если пользователь выбирает сброс ключей при входе, то при вызове этого метода бэкенд автоматически удаляет все его сообщения у всех его собеседников, и его аккаунт пропадает из списков активных диалогов у других пользователей (путем отправки WebSocket оповещения chat_deleted).

Request Body (JSON)
{
  "first_name": "Иван",
  "last_name": "Иванов",
  "public_key": "Base64PublicKey...",
  "encrypted_private_key": "Base64EncryptedPrivateKey..."
}

Внутренние RPC эндпоинты Media SFU (Порт 8587)

Эти эндпоинты доступны только для локального взаимодействия с Go Media SFU сервером (localhost / 127.0.0.1) и используются для неблокирующей верификации входящих медиа-сессий звонков:

POST /api/v1/internal/verify-token (UDP Relay)

Используется классическим UDP Relay сервером (:4000) при получении первичного пакета авторизации 0x01. Проверяет валидность JWT токена, совпадение room_id и user_id, и генерирует уникальный migration_token для защиты от подделки IP.

Request Body & Response (JSON)
// Запрос от Go-сервера:
{ "token": "JWT...", "room_id": 12345, "user_id": 2 }

// Ответ бэкенда (200 OK):
{ "status": "ok", "migration_token": 3819283741 }

POST /api/v1/internal/verify-token-only (QUIC SFU)

Легковесный RPC эндпоинт для высокоскоростного QUIC SFU сервера (:4001). Валидирует JWT токен и возвращает подтверждённый user_id без привязки к фиксированному сокету (так как QUIC поддерживает бесшовную миграцию соединений на уровне протокола).

Request Body & Response (JSON)
// Запрос от Go QUIC-сервера:
{ "token": "JWT..." }

// Ответ бэкенда (200 OK):
{ "valid": true, "user_id": 2 }