- 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>
159 lines
8.7 KiB
Markdown
159 lines
8.7 KiB
Markdown
# 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
|