Files
mtusi2026lab5/openspec/specs/identification/spec.md
T
ricoromaandClaude Opus 5.5 04f859282d chore: port lab 4 solution into the lab 5 skeleton
Source: mtusi2026lab4-safronov, solution/bvt2301-safronov, 2546deb.
Contracts, public tests and evidence of lab 4 are not carried over.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 03:09:12 +03:00

5.8 KiB
Raw Blame History

identification Specification

Purpose

Как сервис определяет текущего пользователя запроса с лабы 2: по Bearer-токену действующей сессии (capability sessions), с ответом 401 и вызовом Bearer при отказе и порядком проверок «аутентификация → доступ к ресурсу». Заголовок X-User-Id лабы 1 доступа больше не даёт.

Requirements

Requirement: Защищённые эндпоинты требуют Bearer

Все эндпоинты, кроме POST /api/v1/users, POST /api/v1/auth/sessions и health, SHALL требовать заголовок Authorization: Bearer <token> с токеном действующей сессии (capability sessions). Владелец сессии SHALL считаться текущим пользователем запроса.

Scenario: Действующий токен

  • WHEN пользователь вызывает GET /api/v1/users/me со своим токеном
  • THEN ответ 200 с этим пользователем

Requirement: Отказ в аутентификации — 401

Сервис SHALL отвечать 401 с code unauthorized и заголовком WWW-Authenticate: Bearer realm="messenger", когда на защищённом эндпоинте нет заголовка Authorization, схема не Bearer (в том числе верный Basic), токен пустой, неизвестен, истёк или отозван. Эти случаи MUST давать одинаковый ответ и MUST NOT давать 400 или 403.

Scenario: Нет заголовка

  • WHEN клиент вызывает GET /api/v1/users/me без Authorization
  • THEN ответ 401 с code unauthorized и WWW-Authenticate схемы Bearer

Scenario: Неизвестный токен

  • WHEN клиент вызывает GET /api/v1/users/me с Bearer-токеном, которого сервис не выдавал
  • THEN ответ 401 с WWW-Authenticate схемы Bearer

Scenario: Basic на бизнес-эндпоинте

  • WHEN клиент вызывает GET /api/v1/users/me с верными username и паролем в Authorization: Basic
  • THEN ответ 401 с WWW-Authenticate схемы Bearer

Requirement: X-User-Id не даёт доступа

Заголовок X-User-Id SHALL игнорироваться: он MUST NOT давать доступ без Bearer-токена и MUST NOT менять текущего пользователя при действующем токене.

Scenario: Только X-User-Id

  • WHEN клиент вызывает GET /api/v1/users/me только с X-User-Id существующего пользователя
  • THEN ответ 401

Scenario: X-User-Id не меняет владельца

  • WHEN клиент вызывает GET /api/v1/users/me с токеном alice и X-User-Id eve
  • THEN ответ 200 с пользователем alice

Requirement: Идентификация раньше доступа и валидации

Аутентификация SHALL проверяться раньше доступа к конкретному ресурсу и раньше проверки пути, query и полей тела. Исключение, согласованное с преподавателем 2026-09-26: тело, которое не разбирается как JSON, отклоняется с 400 до аутентификации.

Scenario: Чужой чат без заголовка

  • WHEN клиент без Bearer-токена запрашивает существующий чат
  • THEN ответ 401, а не 404

Scenario: Невалидное поле без заголовка

  • WHEN клиент без Bearer-токена отправляет сообщение с {"text": ""}
  • THEN ответ 401, а не 400

Scenario: Битый JSON без заголовка

  • WHEN клиент без Bearer-токена отправляет тело {bad
  • THEN ответ 400 с code invalid_request

Requirement: Схема идентификации в документации API

Документация, которую отдаёт сервис (/openapi.json и /docs), SHALL объявлять схемы безопасности bearerAuth и basicAuth так же, как contracts/openapi.json, и MUST NOT объявлять devUser. Защищённые операции SHALL ссылаться на bearerAuth, POST /api/v1/auth/sessions — на basicAuth, а POST /api/v1/users и health MUST NOT ссылаться ни на одну схему. Объявление схем MUST NOT менять ответы: без заголовка по-прежнему 401 в формате контракта, а не ошибка FastAPI.

Scenario: Кнопка Authorize в Swagger

  • WHEN разработчик открывает /docs
  • THEN кнопка Authorize предлагает Basic для входа и Bearer для остальных запросов, и введённый токен уходит заголовком Authorization: Bearer в защищённые запросы

Scenario: Схема в openapi.json

  • WHEN клиент запрашивает /openapi.json
  • THEN components.securitySchemes.bearerAuth и basicAuth совпадают с контрактом, devUser нет, у GET /api/v1/users/me security равно [{"bearerAuth": []}], у POST /api/v1/auth/sessions — [{"basicAuth": []}], а у POST /api/v1/users security нет