Files
mtusi2026lab4/openspec/specs/sessions/spec.md
T
ricoromaandClaude Opus 5.5 5d5d8f9d2a chore: carry lab 3 over
- 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>
2026-10-20 17:32:33 +03:00

8.7 KiB
Raw Blame History

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