Files
mtusi2026lab4/openspec/specs/identification/spec.md
T
ricoromaandClaude Opus 5.5 5d5d8f9d2a chore: carry lab 3 over
- carry the lab 3 solution over from mtusi2026lab3-safronov
  (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests,
  bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts,
  Dockerfile, compose, pyproject and uv lock
- merge Makefile, .gitignore and .dockerignore (the lab 3 versions only
  add lines to the skeleton, which is the same in lab 4) and
  .env.example (lab 4 skeleton names listed in the header)
- rename the compose project to mtusi-lab4 and the image to :lab4 so
  the stand does not reuse the lab 3 containers and volumes
- update AGENTS.md for lab 4: current lab, origin commit, contract and
  test files of the new skeleton

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 17:32:33 +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 нет