Files
mtusi2026lab3/openspec/specs/identification/spec.md
T
ricoromaandClaude Opus 5.5 af4bca08c9 feat: carry lab 2 over and add X-Instance-Id and idempotency keys
- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec
  change instance-id-idempotency)
- rename the compose project to mtusi-lab3 and the image to :lab3
- add X-Instance-Id to every response and instance_id to every log
  record ([app] instance_id, hostname by default)
- require Idempotency-Key on POST messages: keys table in Postgres,
  key and message in one transaction, replay returns the same 201,
  another body gets 409, TTL from [idempotency] ttl_seconds
- send the key from student-tests, k6 scenarios and the skill driver;
  add idempotency, X-Instance-Id, key race and fault tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-08 19:42:36 +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` нет