Files
mtusi2026lab2/openspec/specs/lab2-auth-sessions/spec.md
T
ArtyomandClaude Opus 5.5 0ec2f9dae3 Carry over the agent context and openspec history from lab 2
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>
2026-10-28 11:23:53 +03:00

124 lines
9.1 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.
# 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`