Files
mtusi2026lab2/openspec/changes/session-auth/specs/sessions/spec.md
T
ricoromaandClaude Opus 5.5 ae4154eaf5 feat: add password login and bearer sessions
- Argon2id password hashes, KDF in a thread with its own limit
- POST /auth/sessions with Basic, DELETE /auth/sessions/current
- Bearer sessions in PostgreSQL, X-User-Id ignored
- migration drops lab 1 data without passwords
- student-tests on tokens, sessions spec and synced specs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 18:50:42 +03:00

159 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Spec Delta
## Purpose
Как пользователь получает и теряет право на запросы с лабы 2: вход по
паролю через Basic с выдачей непрозрачного токена, хранение сессий,
срок жизни и отзыв, сохранность действующих сессий после рестарта.
## ADDED Requirements
### Requirement: Вход по Basic
`POST /api/v1/auth/sessions` SHALL принимать только заголовок
`Authorization: Basic <base64(username:password)>`; тело запроса 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