Bring the Claude Code settings, the lint hook, the opsx commands and skills, the architecture notes, the lab 1 and lab 2 specs and the archived lab 1 and lab 2 changes into the lab 3 skeleton, so lab 3 continues the same spec history instead of starting from scratch. Rewrite AGENTS.md and the openspec context and rules for lab 3: HAProxy in front of several stateless API replicas, X-Instance-Id on every response, a mandatory Idempotency-Key for messages shared by all replicas through PostgreSQL, explicit stop-one and restart hooks, Out of scope moved to labs 4-7 plus Swarm and HA storage, and rules on retry policy, timeout chains and replica-local state. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
124 lines
9.1 KiB
Markdown
124 lines
9.1 KiB
Markdown
# lab2-auth-sessions Specification
|
||
|
||
## Purpose
|
||
Определяет, как пользователь доказывает знание пароля, получает непрозрачную сессию с абсолютным сроком жизни, предъявляет её на защищённых endpoint и отзывает её. Заменяет учебную идентификацию `X-User-Id` лабы 1.
|
||
## Requirements
|
||
### Requirement: Пароль хранится только как password KDF
|
||
|
||
Сервис SHALL хранить пароль пользователя только в виде хеша библиотечного password KDF Argon2id с солью. Пароль, его хеш и сессионные данные SHALL NOT входить в объект `User` и SHALL NOT попадать в журнал. Пароль SHALL содержать от 12 до 128 Unicode code points и SHALL NOT состоять только из пробельных символов.
|
||
|
||
#### Scenario: В хранилище нет открытого пароля
|
||
|
||
- **WHEN** пользователь зарегистрирован с паролем
|
||
- **THEN** запись пользователя в БД содержит строку, начинающуюся с `$argon2id$`, и не содержит пароля
|
||
|
||
#### Scenario: Пароль вне допустимой длины
|
||
|
||
- **WHEN** `POST /api/v1/users` содержит `password` короче 12 или длиннее 128 code points
|
||
- **THEN** ответ `400` с кодом `invalid_request`, пользователь не создаётся
|
||
|
||
#### Scenario: Пароль из одних пробелов
|
||
|
||
- **WHEN** `password` состоит только из пробельных символов
|
||
- **THEN** ответ `400` с кодом `invalid_request`
|
||
|
||
#### Scenario: Ответ регистрации без пароля
|
||
|
||
- **WHEN** пользователь успешно зарегистрирован
|
||
- **THEN** тело `201` содержит ровно `id`, `username`, `display_name`, `created_at`
|
||
|
||
### Requirement: Вход по Basic выдаёт сессию
|
||
|
||
Сервис SHALL принимать `POST /api/v1/auth/sessions` только с заголовком `Authorization: Basic <base64(username:password)>` и без тела. Декодирование base64 SHALL быть строгим, разделителем SHALL служить первое двоеточие, пароль SHALL декодироваться как UTF-8. При верных учётных данных ответ SHALL быть `201` с телом `{"token","token_type":"Bearer","expires_at","user"}`, где `token` — непрозрачная случайная строка не короче 32 символов с энтропией не менее 256 бит, `expires_at` — RFC 3339 UTC с `Z`, а `user` совпадает с ответом регистрации. Неверный пароль, неизвестный `username`, отсутствующий и испорченный заголовок SHALL давать одинаковый `401` с кодом `unauthorized` и заголовком `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`.
|
||
|
||
#### Scenario: Успешный вход
|
||
|
||
- **WHEN** зарегистрированный пользователь отправляет верные `username:password` в `Basic`
|
||
- **THEN** ответ `201`, тело соответствует схеме `Session`, `token_type` равен `Bearer`
|
||
- **AND** `user` побайтно равен телу ответа его регистрации, `expires_at` в будущем
|
||
|
||
#### Scenario: Неверный пароль и неизвестный пользователь неразличимы
|
||
|
||
- **WHEN** приходит `Basic` с неверным паролем существующего пользователя или с несуществующим `username`
|
||
- **THEN** оба ответа — `401` с кодом `unauthorized` и `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`
|
||
- **AND** тела ответов различаются только `request_id`
|
||
|
||
#### Scenario: Испорченный заголовок Basic
|
||
|
||
- **WHEN** заголовок отсутствует, содержит другую схему, невалидный base64 или строку без двоеточия
|
||
- **THEN** ответ `401` с тем же заголовком `WWW-Authenticate: Basic ...`
|
||
|
||
#### Scenario: Двоеточие в пароле
|
||
|
||
- **WHEN** пароль пользователя содержит двоеточие и он входит по `Basic`
|
||
- **THEN** ответ `201`: разделителем служит первое двоеточие
|
||
|
||
#### Scenario: Тело запроса при входе
|
||
|
||
- **WHEN** запрос с верным `Basic` содержит тело
|
||
- **THEN** ответ `400` с кодом `invalid_request`, сессия не создаётся
|
||
|
||
### Requirement: Защищённые endpoint принимают только Bearer
|
||
|
||
Все `/api/v1/*`, кроме `POST /api/v1/users` и `POST /api/v1/auth/sessions`, SHALL требовать `Authorization: Bearer <token>`; схема сравнивается без учёта регистра. Отсутствующий, неизвестный, истёкший и отозванный токен, а также `Basic` на этих endpoint SHALL давать `401` с кодом `unauthorized` и `WWW-Authenticate: Bearer realm="messenger"`. Заголовок `X-User-Id` SHALL игнорироваться: он не даёт доступа и не меняет владельца сессии. Аутентификация SHALL выполняться раньше проверки доступа к ресурсу и раньше валидации пути, параметров и тела.
|
||
|
||
#### Scenario: Только X-User-Id
|
||
|
||
- **WHEN** `GET /api/v1/users/me` приходит с `X-User-Id` существующего пользователя и без `Authorization`
|
||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||
|
||
#### Scenario: X-User-Id не подменяет владельца
|
||
|
||
- **WHEN** `GET /api/v1/users/me` приходит с `Bearer` пользователя alice и `X-User-Id` пользователя eve
|
||
- **THEN** ответ `200` с пользователем alice
|
||
|
||
#### Scenario: Basic на бизнес-endpoint
|
||
|
||
- **WHEN** `GET /api/v1/users/me` приходит с верным `Basic`
|
||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||
|
||
#### Scenario: Неизвестный токен
|
||
|
||
- **WHEN** запрос несёт `Bearer` со случайной строкой
|
||
- **THEN** ответ `401` с кодом `unauthorized`
|
||
|
||
#### Scenario: Аутентификация раньше валидации
|
||
|
||
- **WHEN** `POST /api/v1/chats/not-a-uuid/messages` приходит без `Authorization` и с испорченным JSON
|
||
- **THEN** ответ `401`, а не `400`
|
||
|
||
### Requirement: Абсолютный срок жизни сессии
|
||
|
||
Срок жизни сессии SHALL задаваться `SESSION_TTL_SECONDS` (по умолчанию 3600) от момента входа и SHALL NOT продлеваться ни использованием, ни рестартом сервиса. После `expires_at` токен SHALL давать `401`.
|
||
|
||
#### Scenario: Срок назначен при входе
|
||
|
||
- **WHEN** пользователь вошёл
|
||
- **THEN** `expires_at` равен моменту входа плюс `SESSION_TTL_SECONDS` секунд
|
||
|
||
#### Scenario: Истёкший токен
|
||
|
||
- **WHEN** сервис запущен с `SESSION_TTL_SECONDS=2` и токен предъявлен через 3 секунды после входа
|
||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||
|
||
### Requirement: Отзыв текущей сессии
|
||
|
||
`DELETE /api/v1/auth/sessions/current` SHALL отзывать предъявленный токен и отвечать `204` без тела. После отзыва этот токен SHALL давать `401`, в том числе на повторный `DELETE`. Остальные сессии того же пользователя SHALL оставаться действительными.
|
||
|
||
#### Scenario: Выход
|
||
|
||
- **WHEN** пользователь отправляет `DELETE /api/v1/auth/sessions/current` со своим токеном
|
||
- **THEN** ответ `204` с пустым телом и непустым `X-Request-Id`
|
||
- **AND** следующий `GET /api/v1/users/me` с этим токеном получает `401`
|
||
|
||
#### Scenario: Повторный выход
|
||
|
||
- **WHEN** `DELETE /api/v1/auth/sessions/current` повторяется с уже отозванным токеном
|
||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||
|
||
#### Scenario: Другая сессия не затронута
|
||
|
||
- **WHEN** пользователь вошёл дважды и отозвал первую сессию
|
||
- **THEN** второй токен продолжает получать `200`
|
||
|