# sessions Specification ## Purpose Как пользователь получает и теряет право на запросы с лабы 2: вход по паролю через Basic с выдачей непрозрачного токена, хранение сессий, срок жизни и отзыв, сохранность действующих сессий после рестарта. ## Requirements ### Requirement: Вход по Basic `POST /api/v1/auth/sessions` SHALL принимать только заголовок `Authorization: Basic `; тело запроса MUST NOT читаться и не влияет на ответ. Схема `Basic` распознаётся без учёта регистра, credentials декодируются как UTF-8, username и пароль делятся по первому двоеточию: двоеточие в пароле допустимо. При верной паре сервис SHALL создать новую сессию и ответить 201 с объектом `Session`: `token`, `token_type` `Bearer`, `expires_at` в RFC 3339 UTC с `Z` и `user` — тот же объект `User`, что при регистрации. #### Scenario: Успешный вход - **WHEN** зарегистрированный пользователь входит со своими username и паролем - **THEN** ответ 201 `Session`, `token_type` равен `Bearer`, `user` совпадает с ответом на регистрацию, `expires_at` в будущем #### Scenario: Двоеточие и не-ASCII в пароле - **WHEN** пароль содержит `:` и кириллицу, и пользователь входит с ним - **THEN** ответ 201 #### Scenario: Несколько сессий - **WHEN** пользователь входит дважды - **THEN** токены разные, и оба принимаются защищёнными эндпоинтами ### Requirement: Токен непрозрачный Токен SHALL быть случайным значением не короче 32 символов с энтропией не менее 256 бит. Токен MUST NOT содержать и кодировать `username`, `id` пользователя или срок. Сервис MUST NOT хранить токен в открытом виде: по данным хранилища нельзя восстановить действующий токен. #### Scenario: Токен не выводится из данных пользователя - **WHEN** пользователь получил токен - **THEN** токен не содержит его `username` и `id`, а у двух входов одного пользователя токены не совпадают #### Scenario: Токена нет в хранилище - **WHEN** выдан токен T - **THEN** ни одна строка таблиц PostgreSQL не содержит T ### Requirement: Отказ во входе Неверный пароль, неизвестный username, отсутствие заголовка, другая схема вместо `Basic`, битый base64, credentials не в UTF-8 и credentials без двоеточия SHALL давать одинаковый ответ 401 с `code` `unauthorized`, одинаковым `message` и заголовком `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`. Сессия при этом MUST NOT создаваться. Время ответа для неизвестного username MUST NOT заметно отличаться от ответа на неверный пароль: проверка пароля выполняется в обоих случаях. #### Scenario: Неверный пароль - **WHEN** пользователь входит со своим username и чужим паролем - **THEN** ответ 401 с `WWW-Authenticate` схемы `Basic` #### Scenario: Неизвестный пользователь - **WHEN** вход выполняется с username, которого нет - **THEN** ответ совпадает с ответом на неверный пароль: тот же статус, `code`, `message` и `WWW-Authenticate` #### Scenario: Битый Basic - **WHEN** заголовок `Authorization` равен `Basic !!!`, `Basic` с base64 без двоеточия или `Bearer <токен>` - **THEN** ответ 401 с `WWW-Authenticate` схемы `Basic` ### Requirement: Срок жизни сессии Срок сессии SHALL фиксироваться при входе: `expires_at` равен моменту входа плюс настроенный срок жизни (контрактное имя `SESSION_TTL_SECONDS`, capability `service-configuration`). Использование токена и рестарт сервиса MUST NOT продлевать срок. После `expires_at` токен SHALL получать 401 с `WWW-Authenticate: Bearer realm="messenger"`. #### Scenario: Истёкший токен - **WHEN** срок жизни сессии равен 2 с, пользователь вошёл и через 3 с запрашивает `GET /api/v1/users/me` - **THEN** ответ 401 с `WWW-Authenticate` схемы `Bearer` #### Scenario: Срок не продлевается - **WHEN** срок жизни сессии равен 2 с, и пользователь каждые 0,5 с успешно запрашивает `GET /api/v1/users/me` - **THEN** запрос через 3 с после входа получает 401 ### Requirement: Отзыв текущей сессии `DELETE /api/v1/auth/sessions/current` с действующим Bearer-токеном SHALL отзывать сессию этого токена и отвечать 204 без тела. Отзыв SHALL действовать сразу: следующий запрос с этим токеном к любому защищённому эндпоинту получает 401. Другие сессии того же пользователя MUST NOT затрагиваться. Без действующего токена эндпоинт SHALL отвечать 401 с `WWW-Authenticate: Bearer realm="messenger"`. #### Scenario: Выход - **WHEN** пользователь вызывает `DELETE /api/v1/auth/sessions/current` своим токеном, затем `GET /api/v1/users/me` тем же токеном - **THEN** первый ответ 204 без тела, второй — 401 #### Scenario: Повторный выход - **WHEN** пользователь второй раз вызывает `DELETE /api/v1/auth/sessions/current` отозванным токеном - **THEN** ответ 401 с `WWW-Authenticate` схемы `Bearer` #### Scenario: Другая сессия остаётся - **WHEN** пользователь вошёл дважды и отозвал первую сессию - **THEN** второй токен по-прежнему получает 200 ### Requirement: Сессии переживают рестарт Сессии SHALL храниться в PostgreSQL. После перезапуска API и PostgreSQL с сохранённым volume действующий токен SHALL работать до своего `expires_at`, а отозванный — оставаться отозванным. #### Scenario: Прежний токен после рестарта - **WHEN** пользователь вошёл, отправил сообщение, затем выполнен `scripts/restart.sh` - **THEN** тот же токен без повторного входа получает 200 и видит своё сообщение ### Requirement: Недоступность хранилища сессий Если PostgreSQL недоступен, вход и запрос с токеном SHALL получать 503 `unavailable`. Запрос MUST NOT обрабатываться как анонимный или как запрос от последнего известного владельца токена, и сервис MUST NOT отвечать 401 вместо 503: недоступность хранилища не означает, что токен недействителен. #### Scenario: БД остановлена при запросе с токеном - **WHEN** PostgreSQL остановлен, и клиент с действующим токеном запрашивает `GET /api/v1/users/me` - **THEN** ответ 503 `unavailable`, а после возврата PostgreSQL тот же токен получает 200