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

116 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` нет