Files
mtusi2026lab6/openspec/specs/sessions/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e.
Contracts, public tests and evidence of lab 5 are not carried over.
The compose project, image and CI prefix are renamed to lab6; the first
broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the
OpenSpec changes of lab 6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 04:46:56 +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