- 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>
106 lines
7.1 KiB
Markdown
106 lines
7.1 KiB
Markdown
# Proposal
|
||
|
||
## Why
|
||
|
||
Переход API 1 → 2 (`COURSE.md`): регистрация требует `password`, вход
|
||
идёт по Basic, бизнес-запросы — по Bearer-сессии, а `X-User-Id` доступа
|
||
больше не даёт. Сейчас любой клиент выдаёт себя за другого заголовком.
|
||
Поэтому не проходят ни публичный smoke лабы 2, ни `make
|
||
test-persistence`, ни зелёный `make test_isolated` — это обязательный
|
||
минимум «3» (`README.md`). Хранилище уже в PostgreSQL (`postgres-storage`),
|
||
теперь можно строить на нём сессии.
|
||
|
||
## What Changes
|
||
|
||
- **BREAKING (API):** `POST /api/v1/users` требует `password` (12–128
|
||
code points, не только из пробелов). Пароль хэшируется Argon2id и
|
||
никогда не возвращается.
|
||
- Новый `POST /api/v1/auth/sessions`: вход по `Authorization: Basic`,
|
||
без тела. Ответ — 201 `Session`: непрозрачный токен (256 бит),
|
||
`token_type`, `expires_at`, `user`. Неверный пароль, неизвестный
|
||
пользователь и битый Basic дают одинаковый 401 с
|
||
`WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`.
|
||
- Новый `DELETE /api/v1/auth/sessions/current`: отзыв текущей сессии,
|
||
204. Дальше этот токен получает 401.
|
||
- **BREAKING (API):** защищённые эндпоинты принимают только
|
||
`Authorization: Bearer <token>`. Нет токена, он неизвестен, истёк или
|
||
отозван, пришёл Basic — 401 с `WWW-Authenticate: Bearer
|
||
realm="messenger"`. `X-User-Id` игнорируется везде.
|
||
- Сессии хранятся в PostgreSQL: SHA-256 токена, срок `expires_at`,
|
||
фиксированный при входе. Срок задаёт `[auth] session_ttl_seconds` в
|
||
`config.toml` (по умолчанию 3600), разовая подмена — окружением
|
||
`AUTH__SESSION_TTL_SECONDS`; контрактное имя `SESSION_TTL_SECONDS`
|
||
сопоставлено в `REPORT.md`. Действующие сессии переживают рестарт,
|
||
рестарт срок не продлевает. Отзыв мгновенный: каждый запрос проверяет
|
||
сессию в БД.
|
||
- **BREAKING (данные):** миграция удаляет пользователей, чаты, участников
|
||
и сообщения лабы 1 — у них нет пароля, войти они не смогут — и делает
|
||
хэш пароля обязательным. Число удалённых пользователей пишется в журнал
|
||
миграции. Данные стенда синтетические.
|
||
- `/openapi.json` и `/docs` объявляют схемы `bearerAuth` и `basicAuth`
|
||
из контракта вместо `devUser`.
|
||
- `student-tests` идентифицируются Bearer-токеном. Добавлены проверки
|
||
входа, неверного пароля, logout, отказа Basic и `X-User-Id` на
|
||
бизнес-ручках.
|
||
- Становятся зелёными публичный smoke, `make test-persistence
|
||
ACTION_SCRIPT=scripts/restart.sh` и `make test_isolated`. Их выводы и
|
||
ручная проверка истечения сессии при TTL 2 с сохраняются в
|
||
`evidence/`.
|
||
|
||
Вне этого change: Redis/Valkey (`membership-cache`), автоматическая
|
||
проверка истечения на особом стенде с коротким TTL и проверки отказов
|
||
(`failure-checks`), перевод `bench/` на Bearer (`bench-postgres`),
|
||
ограничение частоты входа (429), чистка истёкших сессий.
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `sessions`: вход по Basic, токен и его хранение, срок жизни, отзыв,
|
||
сохранность сессий после рестарта.
|
||
|
||
### Modified Capabilities
|
||
|
||
- `identification`: Bearer вместо `X-User-Id` на защищённых эндпоинтах,
|
||
401 с вызовом `Bearer`, `X-User-Id` игнорируется, схемы `bearerAuth` и
|
||
`basicAuth` в документации API.
|
||
- `users`: регистрация с паролем, хэш пароля через KDF, `User` без
|
||
пароля, текущий пользователь по токену.
|
||
- `health`: health не требует аутентификации и игнорирует
|
||
`Authorization` и `X-User-Id`.
|
||
- `data-storage`: сценарии с `X-User-Id` переходят на токен, сессии тоже
|
||
хранятся в PostgreSQL и переживают рестарт.
|
||
- `container-run`: рестарт hook-ом проверяется прежним токеном,
|
||
`make test-persistence` проходит.
|
||
- `service-configuration`: срок сессии — параметр `config.toml` с
|
||
разовой подменой окружением, одинаково в консоли и docker.
|
||
- `service-logging`: в журнале нет паролей, токенов, их хэшей и
|
||
заголовка `Authorization`; `user_id` берётся из сессии.
|
||
- `student-tests`: обязательные проверки лабы 2 — неверный пароль и
|
||
logout.
|
||
- `db-migrations`: миграция, которая удаляет данные, обязана сообщать об
|
||
этом в журнале.
|
||
|
||
## Impact
|
||
|
||
- Код: `src/core/services/session.py`, `src/core/repos/session.py`,
|
||
`src/api/routers/v1/session.py`, `src/api/schemas/session.py`, модель
|
||
`src/infra/db/models/session.py`, хэширование пароля в
|
||
`src/infra/`; правки `user` во всех слоях, `src/api/dependencies.py`
|
||
(Bearer вместо `X-User-Id`), `src/api/errors.py` (`WWW-Authenticate`),
|
||
`src/core/exceptions/`, `src/config/settings.py` (`[auth]`),
|
||
`src/utils/constants.py`.
|
||
- Миграция: `password_hash` в `users`, таблица `sessions`, очистка
|
||
данных лабы 1.
|
||
- Зависимости: `argon2-cffi`; `uv.lock`.
|
||
- Конфигурация: `config_example.toml` (секция `[auth]`); `.env.example`
|
||
и `docker-compose.yml` не меняются.
|
||
- Тесты: `student-tests/api_client.py` (токен в `Actor`, регистрация с
|
||
паролем и входом), новый `test_sessions.py`, переписанный
|
||
`test_identification.py`, тела регистрации в `test_users.py`,
|
||
`test_race.py`, `test_rubric.py`, `spec_coverage.py`.
|
||
- Инструменты и документы: скилл `run-mtusi-messenger` (вход и Bearer в
|
||
`driver.py`), `AGENTS.md` («Переходное состояние»), `.claude/rules/`
|
||
(`auth.md` — выбранные решения), `REPORT.md` (KDF, сессии,
|
||
доказательства уровня «3»), `evidence/`.
|