Files
mtusi2026lab3/openspec/specs/lab2-auth-sessions/spec.md
T

9.8 KiB
Raw Blame History

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".

В соответствии с разделом «Идентификация и сессии» contracts/README.md, NUL в Basic username SHALL приводить к тому же 401 unauthorized.

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, сессия не создаётся

Scenario: Username с NUL

  • WHEN в POST /api/v1/auth/sessions передан корректный Base64 от username с NUL и пароля
  • THEN ответ 401 с WWW-Authenticate: Basic realm="messenger", charset="UTF-8"; тело {"error":{"code":"unauthorized","message":...,"request_id":...}} совпадает с ошибкой неверного пароля, кроме request_id
  • AND ответ содержит непустые X-Instance-Id и X-Request-Id, совпадающий с error.request_id

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