Files
mtusi2026lab6/openspec/specs/identification/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

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 нет