Модуль Core (Аутентификация, Пользователи, KYC)

Обзор

Модуль Core является фундаментальным модулем платформы IWM, отвечающим за управление идентификацией, аутентификацию, авторизацию и верификацию KYC (Know Your Customer). Все остальные модули зависят от Core для идентификации пользователей и контроля доступа.

Зоны ответственности

• Регистрация пользователей и управление аккаунтами
• Аутентификация (email/пароль, OAuth провайдеры)
• Двухфакторная аутентификация (2FA)
• Управление сессиями (JWT токены)
• Процесс верификации KYC
• Ролевой контроль доступа (RBAC)
• Безопасность паролей и защита аккаунтов

---

Доменные сущности

User

Центральная сущность идентификации, представляющая пользователя платформы.

Поле	Тип	Описание
id	UUID	Первичный идентификатор
email	VARCHAR(255)	Уникальный email адрес
phone	VARCHAR(20)	Опциональный номер телефона (уникальный)
password_hash	VARCHAR(255)	Хэш пароля bcrypt
status	ENUM	Статус аккаунта
email_verified_at	TIMESTAMP	Время верификации email
phone_verified_at	TIMESTAMP	Время верификации телефона
last_login_at	TIMESTAMP	Последний успешный вход
created_at	TIMESTAMP	Время создания аккаунта
updated_at	TIMESTAMP	Время последнего изменения

UserProfile

Расширенная информация о пользователе для персонализации и соответствия требованиям.

Поле	Тип	Описание
id	UUID	Первичный идентификатор
user_id	UUID	Ссылка на User
first_name	VARCHAR(100)	Имя по документам
last_name	VARCHAR(100)	Фамилия по документам
middle_name	VARCHAR(100)	Отчество
date_of_birth	DATE	Дата рождения для KYC
avatar_url	VARCHAR(500)	URL изображения профиля
language	VARCHAR(10)	Код предпочитаемого языка
timezone	VARCHAR(50)	Часовой пояс пользователя

Session

Активные сессии пользователя для состояния аутентификации.

Поле	Тип	Описание
id	UUID	Идентификатор сессии
user_id	UUID	Ссылка на User
refresh_token_hash	VARCHAR(255)	Хэш refresh токена
device_fingerprint	VARCHAR(255)	Идентификация устройства
ip_address	INET	IP адрес клиента
user_agent	TEXT	Информация о браузере/клиенте
expires_at	TIMESTAMP	Время истечения сессии
revoked_at	TIMESTAMP	Время ручного отзыва

KycVerification

Состояние и данные процесса верификации KYC.

Поле	Тип	Описание
id	UUID	Идентификатор верификации
user_id	UUID	Ссылка на User
status	ENUM	Статус верификации
level	ENUM	Достигнутый уровень верификации
personal_info	JSONB	Зашифрованные персональные данные
submitted_at	TIMESTAMP	Время подачи
reviewed_at	TIMESTAMP	Время завершения проверки
reviewed_by	UUID	Администратор, проводивший проверку
rejection_reason	TEXT	Причина отклонения
expires_at	TIMESTAMP	Срок действия верификации

KycDocument

Документы, загруженные для верификации KYC.

Поле	Тип	Описание
id	UUID	Идентификатор документа
verification_id	UUID	Ссылка на KycVerification
document_type	ENUM	Тип документа
file_key	VARCHAR(500)	Ключ S3/хранилища
file_name	VARCHAR(255)	Исходное имя файла
mime_type	VARCHAR(100)	MIME тип файла
status	ENUM	Статус документа
ocr_data	JSONB	Извлеченные данные OCR
rejection_reason	TEXT	Причина отклонения

---

Жизненный цикл пользователя

Пользователи проходят через определенные состояния в течение своего жизненного цикла:

Определения статусов

Статус	Описание	Разрешенные действия
PENDING_VERIFICATION	Аккаунт создан, ожидает верификации email	Повторная отправка верификации, просмотр ограниченного контента
ACTIVE	Полностью верифицированный и рабочий аккаунт	Все функции платформы
SUSPENDED	Временно ограничен из-за нарушения правил	Только просмотр, подача апелляции
BANNED	Перманентно заблокирован на платформе	Нет доступных действий

---

Методы аутентификации

Аутентификация по Email/Паролю

Основной метод аутентификации с использованием email и пароля:

1. Регистрация: Пользователь указывает email и пароль
2. Хэширование пароля: bcrypt с фактором стоимости 12
3. Верификация Email: Уникальный токен отправляется на email
4. Вход: Проверка email + пароль
5. Создание сессии: Выдаются JWT access токен + refresh токен

OAuth провайдеры

Поддерживаемые провайдеры социального входа:

Провайдер	Тип	Идентификатор
Google	GOOGLE	provider_user_id от Google
Facebook	FACEBOOK	provider_user_id от Facebook
Apple	APPLE	provider_user_id от Apple ID
Telegram	TELEGRAM	provider_user_id от Telegram

Процесс OAuth:

1. Пользователь инициирует OAuth с провайдером
2. Провайдер перенаправляет с кодом авторизации
3. Бэкенд обменивает код на токены
4. Профиль пользователя получен от провайдера
5. Аккаунт связан или создан
6. Выдана сессия платформы

---

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

TOTP (Time-based One-Time Password)

Основной метод 2FA с использованием приложений-аутентификаторов:

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

• Алгоритм: SHA-1
• Количество цифр: 6
• Период: 30 секунд
• Секрет: 32 байта, кодировка base32

Резервный SMS

Резервный метод 2FA через SMS:

1. Пользователь запрашивает SMS резервный код
2. Система отправляет 6-значный код на верифицированный телефон
3. Код действителен 5 минут
4. Максимум 3 попытки на один код

---

Управление сессиями

Архитектура токенов

Платформа использует систему двойных токенов:

Access Token (JWT)

Claim	Описание
sub	ID пользователя (UUID)
email	Email пользователя
roles	Массив кодов ролей
iat	Время выдачи
exp	Время истечения

Параллельные сессии

• Пользователи могут иметь несколько активных сессий
• Каждое устройство/браузер создает отдельную сессию
• Сессии отслеживаются по отпечатку устройства
• Пользователь может просматривать и отзывать отдельные сессии
• Безопасность: Подозрительная активность запускает проверку сессий

Отзыв сессий

Сессии могут быть отозваны:

• Вручную пользователем (выход, настройки безопасности)
• Автоматически при смене пароля
• Автоматически при инциденте безопасности
• Действием администратора

---

Процесс KYC

Уровни верификации

Уровень	Требования	Разблокированные функции
NONE	Без верификации	Только просмотр, ограниченные действия
BASIC	Email + телефон верифицированы	Базовые покупки, ограниченные инвестиции
STANDARD	Документ удостоверения личности верифицирован	Полный доступ к платформе
ENHANCED	Подтверждение адреса + селфи	Транзакции высокой стоимости

Поток статусов KYC

Типы документов

Тип	Требуется для	Описание
PASSPORT	STANDARD	Государственный паспорт
ID_CARD	STANDARD	Национальное удостоверение личности
DRIVER_LICENSE	STANDARD	Водительское удостоверение с фото
UTILITY_BILL	ENHANCED	Подтверждение адреса (недавнее)
BANK_STATEMENT	ENHANCED	Финансовое подтверждение адреса
SELFIE	ENHANCED	Живое селфи с документом

---

Функции безопасности

Безопасность паролей

• Хэширование: bcrypt с фактором стоимости 12
• Требования: Минимум 8 символов, разный регистр, цифры
• История: Последние 5 паролей нельзя использовать повторно
• Истечение: Опциональная принудительная ротация (настраивается)

Защита от перебора

Пороговые значения:

• 5 неудачных попыток: задержка 5 минут
• 10 неудачных попыток: блокировка 15 минут
• 20 неудачных попыток: аккаунт заблокирован, требуется верификация email

Ограничение запросов

Эндпоинт	Лимит	Окно
POST /auth/login	10 запросов	1 минута
POST /auth/register	5 запросов	1 минута
POST /auth/forgot-password	3 запроса	5 минут
POST /auth/verify-2fa	5 запросов	1 минута

---

Публикуемые события

Модуль Core публикует следующие доменные события для межмодульной коммуникации:

Событие	Триггер	Payload
UserRegistered	Регистрация нового пользователя	userId, email, referralCode
UserVerified	Завершение верификации email	userId, email
UserStatusChanged	Изменение статуса аккаунта	userId, fromStatus, toStatus, reason
UserProfileUpdated	Изменение информации профиля	userId, changedFields
UserLoggedIn	Успешный вход	userId, ipAddress, userAgent
UserLoggedOut	Выход пользователя	userId, sessionId
SessionRevoked	Ручной отзыв сессии	userId, sessionId, reason
TwoFactorEnabled	Активация 2FA	userId, method
TwoFactorDisabled	Деактивация 2FA	userId, method
KycStatusChanged	Переход статуса KYC	userId, fromStatus, toStatus, level
KycDocumentUploaded	Загружен документ для KYC	userId, verificationId, documentType
KycApproved	Верификация KYC одобрена	userId, level, approvedBy
KycRejected	Верификация KYC отклонена	userId, reason, rejectedBy
PasswordChanged	Пользователь сменил пароль	userId, changedAt
PasswordResetRequested	Инициирован сброс пароля	userId, email

---

Бизнес-правила и инварианты

Правила пользователей

1. Email должен быть уникальным среди всех пользователей
2. Номер телефона, если указан, должен быть уникальным
3. Пользователь не может быть удален, если у него есть активные заказы или инвестиции
4. Переходы статусов должны следовать определенной машине состояний
5. Только пользователи со статусом ACTIVE могут совершать транзакции

Правила сессий

1. Время жизни access токена: 15 минут (не настраивается)
2. Время жизни refresh токена: 7 дней
3. Максимум параллельных сессий на пользователя: 10
4. Сессия должна быть отозвана при смене пароля
5. Неактивные сессии автоматически истекают после истечения refresh токена

Правила KYC

1. Верификация KYC истекает через 1 год (для уровня ENHANCED)
2. Пользователь не может подать новую KYC, пока предыдущая находится UNDER_REVIEW
3. Отклоненная KYC позволяет повторную подачу через 24 часа
4. Уровень ENHANCED требует сначала уровень STANDARD
5. Данные KYC должны быть зашифрованы при хранении

---

Точки интеграции

Предоставляет другим модулям

Интерфейс	Потребители	Назначение
IUserLookupService	MLM, Commerce, Investment	Получение данных профиля пользователя
IKycStatusService	Investment, MLM	Проверка статуса верификации KYC
IAuthenticationService	Все модули	Валидация токенов, получение текущего пользователя
IRoleService	Admin	Проверка прав пользователя

Потребляет от других модулей

Модуль Core является фундаментальным и не потребляет сервисы от других бизнес-модулей.

---

Связанные документы

• Core Schema
• Module Architecture
• API Structure