UnivexID Service¶

Назначение¶

UnivexID — центральный Identity-сервис платформы Univex: аутентификация, авторизация, управление сессиями, двухфакторная аутентификация, KYC, API-ключи, роли администраторов. Делегирует операции смежным сервисам (Ledger, P2P, Exchange Integration).

Транспорт: gRPC. Количество RPC: 95+, организованных по 17 доменам.
База данных: PostgreSQL (48 миграций). Дополнительно: Redis (кэш сессий/кодов), Temporal (асинхронные рабочие процессы).

Потоки аутентификации¶

Регистрация¶

Клиент → SignUp(email/phone, password)
       → SendEmailCode / SendPhoneCode (код подтверждения)
       → CompleteSignUp(code)
       → Создание аккаунта + сессии
       → Возврат токена

Вход¶

Клиент → SignIn(email/phone, password)
       → [Если включена 2FA: SendEmailCode / ConfirmGoogleCode / ConfirmPhoneCode]
       → CompleteSignIn(code)
       → Возврат сессии/токена

Вход через Telegram¶

Клиент → RegisterByTelegram(telegram_data)
       → Создание/поиск аккаунта по Telegram ID
       → Возврат сессии/токена

Ключевые перечисления¶

Role — роль сотрудника¶

enum Role {
    ROLE_UNSPECIFIED    = 0;
    CASHIER             = 1;  // Кассир
    OPERATOR            = 2;  // Оператор
    P2P_ARBITRATOR      = 3;  // P2P арбитр
    SUPPORT_STAFF       = 4;  // Сотрудник поддержки
    ADMINISTRATOR       = 5;  // Администратор
    OWNER               = 6;  // Владелец
}

AccountStatus — статус аккаунта¶

enum AccountStatus {
    ACCOUNT_STATUS_UNSPECIFIED = 0;
    ACCOUNT_STATUS_ACTIVE      = 1;
    ACCOUNT_STATUS_SUSPENDED   = 2;
    ACCOUNT_STATUS_BLOCKED     = 3;
}

AccountKYCStatus — статус KYC¶

enum AccountKYCStatus {
    KYC_STATUS_UNSPECIFIED  = 0;
    KYC_STATUS_NOT_STARTED  = 1;
    KYC_STATUS_PENDING      = 2;
    KYC_STATUS_APPROVED     = 3;
    KYC_STATUS_REJECTED     = 4;
}

Confirmation — тип подтверждения операции¶

enum Confirmation {
    CONFIRMATION_UNSPECIFIED = 0;
    EMAIL                    = 1;
    PHONE                    = 2;
    GOOGLE                   = 3;
    SET_PASSWORD             = 4;
    SET_PHONE                = 5;
    SET_EMAIL                = 6;
    ADMIN                    = 7;
}

BanType — тип блокировки¶

enum BanType {
    BAN_TYPE_UNSPECIFIED = 0;
    BAN_TYPE_TEMPORARY   = 1;
    BAN_TYPE_PERMANENT   = 2;
}

База данных¶

48 миграций PostgreSQL. Покрывают все домены сервиса:

Диапазон миграций	Домены
1–10	Аккаунты, сессии, пароли, контактные данные
11–20	2FA (TOTP/Google), коды подтверждения, API-ключи
21–30	Административные аккаунты, роли, действия
31–40	Уведомления, тиры, личные коды, верификация
41–48	Telegram, username, дополнительные индексы

RPC по доменам¶

1. Аутентификация¶

RPC	Описание
`SignIn`	Вход по email/телефону и паролю. Возвращает незавершённую сессию, требующую 2FA.
`CompleteSignIn`	Завершение входа после подтверждения (код email/phone/Google).
`SignUp`	Начало регистрации: создаёт незавершённый аккаунт, отправляет код.
`CompleteSignUp`	Завершение регистрации после подтверждения кода.

2. Коды подтверждения¶

RPC	Описание
`SendEmailCode`	Отправляет OTP-код на email (через Email-сервис).
`SendPhoneCode`	Отправляет OTP-код на телефон (через SMS Gate).
`ConfirmEmailCode`	Подтверждает OTP-код, полученный на email.
`ConfirmPhoneCode`	Подтверждает OTP-код, полученный по SMS.
`ConfirmGoogleCode`	Подтверждает TOTP-код из Google Authenticator.

3. Сессии¶

RPC	Описание
`TerminateSession`	Завершает конкретную сессию пользователя.
`TerminateSessions`	Завершает все сессии пользователя (кроме текущей, опционально).
`ListSessions`	Возвращает список активных сессий аккаунта.
`GetSession`	Возвращает данные конкретной сессии.
`RefreshSession`	Обновляет access-токен по refresh-токену.

4. Двухфакторная аутентификация (2FA)¶

RPC	Описание
`CreateGoogleAuthMethod`	Инициирует привязку Google Authenticator. Возвращает QR-код/секрет.
`CompleteCreateGoogleAuthMethod`	Завершает привязку Google Authenticator после подтверждения TOTP-кода.

5. Смена пароля¶

RPC	Описание
`ChangePassword`	Инициирует смену пароля (требует текущий пароль).
`CompleteChangePassword`	Завершает смену пароля после подтверждения кодом.
`ResetPassword`	Инициирует сброс пароля через email/телефон.
`CompleteResetPassword`	Завершает сброс пароля: устанавливает новый после подтверждения кода.

6. Смена email¶

RPC	Описание
`ChangeEmail`	Инициирует смену email: отправляет код на новый адрес.
`CompleteChangeEmail`	Завершает смену email после подтверждения кода.

7. Смена телефона¶

RPC	Описание
`ChangePhone`	Инициирует смену номера телефона.
`CompleteChangePhone`	Завершает смену телефона после подтверждения SMS-кода.

8. Username¶

RPC	Описание
`ChangeUsername`	Изменяет имя пользователя (никнейм).

9. Управление аккаунтами¶

RPC	Описание
`GetAccount`	Возвращает данные текущего аккаунта.
`GetAccountByCredentials`	Возвращает аккаунт по email/телефону (для внутреннего использования).
`FindAccounts`	Поиск аккаунтов по частичному совпадению (для сотрудников).
`ListAccounts`	Постраничный список аккаунтов с фильтрацией (для сотрудников).
`BanAccount`	Блокирует аккаунт (временно или постоянно).
`UnbanAccount`	Снимает блокировку с аккаунта.
`ListAccountBanEvents`	Возвращает историю блокировок/разблокировок аккаунта.
`GenerateNewPersonalCode`	Генерирует новый личный реферальный код для аккаунта.
`GetMyPersonalCode`	Возвращает текущий личный код аккаунта.

10. Торговые уровни (Tiers)¶

RPC	Описание
`ListTiers`	Возвращает список доступных торговых уровней.
`SetTier`	Устанавливает торговый уровень для аккаунта.

11. Верификация (KYC)¶

RPC	Описание
`StartVerification`	Запускает KYC-верификацию через Sumsub Integration. Возвращает токен для виджета.

12. API-ключи¶

RPC	Описание
`CreateApiKey`	Создаёт новый API-ключ для аккаунта.
`ListApiKeys`	Возвращает список API-ключей аккаунта.
`DeleteApiKey`	Удаляет API-ключ по идентификатору.

13. Административные аккаунты¶

RPC	Описание
`SignInAdmin`	Вход администратора по учётным данным.
`GetAdminProfile`	Возвращает профиль текущего администратора.
`GetAdminSession`	Возвращает данные активной административной сессии.
`RevokeAdminSession`	Отзывает административную сессию.
`CreateAdmin`	Создаёт новый административный аккаунт.
`ListAdmins`	Возвращает список администраторов.
`DeleteAdmin`	Удаляет административный аккаунт.
`ConfirmOperationByAdmin`	Подтверждает чувствительную операцию администратором.
`ListAdminNotifications`	Возвращает список уведомлений администратора.
`ReadAdminNotification`	Отмечает уведомление как прочитанное.
`CreateAction`	Создаёт запись об административном действии (audit log).
`ListActions`	Возвращает лог административных действий.

14. Роли¶

RPC	Описание
`CreateRole`	Создаёт новую роль в системе RBAC.

15. Telegram¶

RPC	Описание
`RegisterByTelegram`	Регистрирует/аутентифицирует пользователя через Telegram (Telegram Login Widget).

Делегированные операции¶

UnivexID выступает агрегатором и делегирует операции смежным сервисам. Клиент обращается к UnivexID, который самостоятельно вызывает нужный downstream-сервис:

Домен	Downstream-сервис	Примеры операций
Балансы	Exchange Integration	`GetBalances`, `GetAccountDetails`
Фиатные операции	Ledger	`CreateFiatOperation`, `ListFiatOperations`, `ProcessFiatBid`
Блокчейн	Exchange Integration	`GetDepositAddress`, `WithdrawToBlockchain`, `ListTopUps`
Торговля / ордера	Exchange Integration	`ListOrders`, `ListTickers`
Переводы	Ledger	`StartTransfer`, `GetTransferStatus`, `ListTransfers`
Замороженные активы	Ledger	`FreezeMoney`, `UnfreezeMoney`, `ListFrozenAssets`
Горячие кошельки	Exchange Integration	`ListHotWallets`, `TransferAssets`
Адресная книга	Ledger / внутренний	`ListAddressBook`, `AddAddress`, `DeleteAddress`
Фиатные кассы	Ledger	`ListFiatPlaces`
Funded Codes	Ledger	`CreateFundedCode`, `RedeemFundedCode`, `ListFundedCodes`
Уведомления	внутренний	`ListNotifications`, `ReadNotification`

Модель авторизации¶

Доступ к RPC определяется ролью аккаунта:

Роль	Уровень доступа
Обычный пользователь	Свои данные, торговля, переводы, блокчейн-операции, P2P
`CASHIER`	Фиатные операции (приём/выдача наличных)
`OPERATOR`	Ручные балансовые операции
`P2P_ARBITRATOR`	Разрешение P2P-споров
`SUPPORT_STAFF`	Просмотр данных аккаунтов, помощь пользователям
`ADMINISTRATOR`	Управление аккаунтами, KYC, блокировки, тиры
`OWNER`	Полный доступ, управление администраторами и ролями

Конфигурация¶

Параметр	Описание
`DATABASE_URL`	DSN для подключения к PostgreSQL
`REDIS_URL`	Адрес Redis
`GRPC_PORT`	Порт gRPC-сервера
`TEMPORAL_HOST`	Адрес Temporal-сервера
`TEMPORAL_NAMESPACE`	Namespace в Temporal
`EXCHANGE_INTEGRATION_GRPC_ADDR`	Адрес Exchange Integration gRPC
`LEDGER_GRPC_ADDR`	Адрес Ledger gRPC
`P2P_GRPC_ADDR`	Адрес P2P gRPC
`EMAIL_GRPC_ADDR`	Адрес Email gRPC
`SMS_GRPC_ADDR`	Адрес SMS Gate gRPC
`SUMSUB_GRPC_ADDR`	Адрес Sumsub Integration gRPC
`JWT_SECRET`	Секрет для подписи JWT-токенов
`ACCESS_TOKEN_TTL`	Время жизни access-токена
`REFRESH_TOKEN_TTL`	Время жизни refresh-токена