# 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 ` с токеном действующей сессии (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` нет