10 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".
В соответствии с разделом «Идентификация и сессии» contracts/README.md, NUL в Basic username и не-ASCII символы в закодированной части Basic 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
Scenario: Не-ASCII в закодированной части Basic
- WHEN
POST /api/v1/auth/sessionsполучаетAuthorizationс не-ASCII байтами послеBasic, в том числе0xff - 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