# auth Specification

## Purpose

Регистрация и аутентификация пользователей по email и паролю с выдачей краткоживущих и долгоживущих JWT-токенов.

## Requirements

### Requirement: Регистрация пользователя
Пользователь SHALL регистрироваться, указав имя, пароль и хотя бы один из идентификаторов —
email или телефон. Пароль SHALL храниться в виде bcrypt-хэша. Телефон SHALL нормализоваться
к формату E.164 и быть уникальным; email SHALL приводиться к нижнему регистру и быть
уникальным.

#### Scenario: Успешная регистрация
- **WHEN** пользователь отправляет свободный email, имя и пароль
- **THEN** система создаёт учётную запись и возвращает access- и refresh-токены

#### Scenario: Регистрация по телефону
- **WHEN** пользователь отправляет свободный телефон в формате E.164, имя и пароль
- **THEN** система создаёт учётную запись и возвращает access- и refresh-токены

#### Scenario: Нет ни email, ни телефона
- **WHEN** пользователь не указывает ни email, ни телефон
- **THEN** система отклоняет регистрацию

#### Scenario: Повторный email
- **WHEN** пользователь регистрируется с уже занятым email или телефоном
- **THEN** система возвращает ошибку конфликта и не создаёт вторую запись

### Requirement: Вход по email или телефону
Пользователь SHALL входить по единому идентификатору — email или телефону в формате
E.164 — и паролю.

#### Scenario: Успешный вход
- **WHEN** пользователь вводит существующий email или телефон и верный пароль
- **THEN** система возвращает access- и refresh-токены

#### Scenario: Неверные учётные данные
- **WHEN** пользователь вводит несуществующий идентификатор или неверный пароль
- **THEN** система возвращает 401, не раскрывая, какое именно поле неверно

### Requirement: Обновление access-токена
Пользователь SHALL иметь возможность обменять refresh-токен на новую пару токенов. Access-токен живёт 15 минут, refresh-токен — 30 дней.

#### Scenario: Валидный refresh-токен
- **WHEN** пользователь предоставляет действующий refresh-токен
- **THEN** система выдаёт новый access-токен и ротирует refresh-токен

#### Scenario: Недействительный refresh-токен
- **WHEN** пользователь предоставляет истёкший или отозванный refresh-токен
- **THEN** система возвращает 401

### Requirement: Выход из системы
Пользователь SHALL иметь возможность выйти, отозвав refresh-токен.

#### Scenario: Выход
- **WHEN** пользователь вызывает logout с действующим refresh-токеном
- **THEN** система отзывает refresh-токен, и его дальнейшее использование отклоняется

### Requirement: Хранение пользовательских настроек интерфейса
Система SHALL хранить настройки отображения в профиле пользователя и SHALL возвращать их при
получении текущего пользователя. Настройки SHALL быть приватными для пользователя.
Отсутствие настроек SHALL трактоваться как значения по умолчанию.

#### Scenario: Получение настроек
- **WHEN** аутентифицированный пользователь запрашивает свой профиль
- **THEN** ответ содержит его настройки отображения (или пустой объект по умолчанию)

#### Scenario: Сохранение настроек
- **WHEN** пользователь сохраняет настройки отображения
- **THEN** система сохраняет их в профиле и возвращает сохранённое состояние

#### Scenario: Изоляция настроек
- **WHEN** другой пользователь запрашивает свой профиль
- **THEN** он не получает настройки первого пользователя

#### Scenario: Некорректные настройки
- **WHEN** пользователь присылает настройки недопустимой структуры или размера
- **THEN** система отклоняет запрос с ошибкой и не меняет сохранённые настройки