- 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>
116 lines
5.8 KiB
Markdown
116 lines
5.8 KiB
Markdown
# 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` нет
|