- carry the lab 3 solution over from mtusi2026lab3-safronov (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests, bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts, Dockerfile, compose, pyproject and uv lock - merge Makefile, .gitignore and .dockerignore (the lab 3 versions only add lines to the skeleton, which is the same in lab 4) and .env.example (lab 4 skeleton names listed in the header) - rename the compose project to mtusi-lab4 and the image to :lab4 so the stand does not reuse the lab 3 containers and volumes - update AGENTS.md for lab 4: current lab, origin commit, contract and test files of the new skeleton Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
8.7 KiB
sessions Specification
Purpose
Как пользователь получает и теряет право на запросы с лабы 2: вход по паролю через Basic с выдачей непрозрачного токена, хранение сессий, срок жизни и отзыв, сохранность действующих сессий после рестарта.
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