Files
mtusi2026lab2/openspec/changes/session-auth/proposal.md
T
ricoromaandClaude Opus 5.5 ae4154eaf5 feat: add password login and bearer sessions
- 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>
2026-10-01 18:50:42 +03:00

106 lines
7.1 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.
# 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/`.