Bring the Claude Code settings, the lint hook, the opsx commands and
skills, the architecture notes, the lab 1 to lab 5 specs and the
archived lab 1 to lab 5 changes into the lab 6 skeleton, so lab 6
continues the same spec history instead of starting from scratch. The
files come from the lab 5 solution commit 64d5c67.
Rewrite AGENTS.md and the openspec context and rules for lab 6: the
business API stays at contract 1.6.0, API, relay and worker start the
OpenTelemetry SDK in every process after fork and export OTLP over HTTP
to a separate Collector, Prometheus, Loki and Tempo store metrics, logs
and traces on volumes, Grafana only reads them through provisioning
kept in Git, telemetry never blocks a request and never feeds
/health/ready, metric labels stay low-cardinality and message bodies
and secrets never leave the process. Out of scope moves to lab 7,
track 2 and clustered telemetry backends.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
9.1 KiB
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