- Argon2id password hashes, KDF in a thread with its own limit - POST /auth/sessions with Basic, DELETE /auth/sessions/current - Bearer sessions in PostgreSQL, X-User-Id ignored - migration drops lab 1 data without passwords - student-tests on tokens, sessions spec and synced specs Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
128 lines
6.4 KiB
Markdown
128 lines
6.4 KiB
Markdown
# Spec Delta
|
||
|
||
## ADDED 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
|
||
|
||
## MODIFIED Requirements
|
||
|
||
### 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` нет
|
||
|
||
## REMOVED Requirements
|
||
|
||
### Requirement: Защищённые эндпоинты требуют X-User-Id
|
||
|
||
**Reason**: переход API 1 → 2 (`COURSE.md`): `X-User-Id` заменяется
|
||
Bearer-сессией.
|
||
**Migration**: требование «Защищённые эндпоинты требуют Bearer»;
|
||
сценарий «Корректный заголовок» переходит в «Действующий токен».
|
||
|
||
### Requirement: Отказ в идентификации — 401
|
||
|
||
**Reason**: заголовка `X-User-Id` больше нет; отказ теперь касается
|
||
Bearer-токена и несёт `WWW-Authenticate`.
|
||
**Migration**: требование «Отказ в аутентификации — 401»; сценарии «Не
|
||
UUID» и «Неизвестный пользователь» переходят в «Неизвестный токен», «Нет
|
||
заголовка» остаётся с проверкой `WWW-Authenticate`.
|