Files
mtusi2026lab2/openspec/changes/session-auth/design.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

250 lines
17 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.
# Design
## Context
Мотивация — `proposal.md`, раздел Why. Требования — `specs/`. Как
реализовывать пароль, Basic, токен и `get_current_user`, уже записано в
`.claude/rules/auth.md`; здесь — решения, которые правило оставляет
change, и проверки на текущих версиях.
Сейчас `get_current_user` читает `X-User-Id` через `APIKeyHeader`
(`devUser`), `UserService.identify` ищет пользователя по UUID, а 401 даёт
`Unidentified` без `WWW-Authenticate`. Хранилище — PostgreSQL
(`postgres-storage`): одна `AsyncSession` на запрос, commit в сервисе,
ошибки БД → 503 в `get_db_session` с общим сроком запроса 6 с. В
explore перед `postgres-storage` решено: сессии — PostgreSQL без кэша,
отзыв мгновенный, Redis/Valkey — кэш состава чатов (`membership-cache`).
Проверено на версиях этого change:
- FastAPI 0.141.1: `HTTPBase(scheme="basic", ...)` с `auto_error=False`
отдаёт `scheme` и `credentials` как есть, не проверяя схему и не
декодируя base64; `HTTPBearer(auto_error=False)` на чужую схему
отдаёт `None`.
- argon2-cffi 25.1.0: `PasswordHasher()` — профиль
`RFC_9106_LOW_MEMORY` (Argon2id, t=3, m=64 MiB, p=4, соль 16 байт).
Хэш — 97 символов `$argon2id$v=19$m=65536,t=3,p=4$...`, хэширование и
проверка — около 30 мс на M3 Pro. Пароль из 128 кириллических
символов (256 байт) сравнивается целиком.
- pydantic-settings (python-dotenv) подставляет `${VAR}` в мосте `.env`
сначала из самого файла: при `SESSION_TTL_SECONDS=3600` в `.env` и
`SESSION_TTL_SECONDS=2` в окружении мост
`AUTH__SESSION_TTL_SECONDS=${SESSION_TTL_SECONDS}` даёт 3600.
## Goals / Non-Goals
**Goals:**
- Публичный smoke лабы 2, `make test-persistence
ACTION_SCRIPT=scripts/restart.sh` и `make test_isolated` проходят
целиком; `student-tests` — все, включая переписанный
`test_security_scheme_in_openapi`.
- Один запрос с токеном — один `SELECT` в PostgreSQL: проверка сессии и
загрузка пользователя вместе.
- Время входа не выдаёт, существует ли username.
**Non-Goals:**
- Автоматические тесты истечения (TTL 2 с) и недоступности БД — особый
стенд, механизм выбирает `failure-checks` (`student-tests.md`). Здесь
поведение реализуется и проверяется вручную с записью в `evidence/`.
- Чистка истёкших сессий, `check_needs_rehash`, ограничение частоты
входа, «выйти со всех устройств».
- `bench/` на Bearer — `bench-postgres`.
## Decisions
### 1. Таблица `sessions` и отзыв удалением
```
users sessions
id uuid PK <----+ id uuid PK
username text UQ +---- user_id uuid FK -> users, NOT NULL
display_name text token_hash bytea UQ, CHECK octet_length = 32
password_hash text NOT NULL created_at timestamptz
CHECK LIKE '$argon2id$%' expires_at timestamptz, CHECK > created_at
created_at timestamptz
```
- `token_hash` — SHA-256 токена (32 байта, `bytea`), поиск — по
уникальному индексу. Токен у клиента, в БД его нет (`auth.md`).
- Отзыв — `DELETE ... WHERE id = :session_id`. Отзыв мгновенный, следы
в журнале (`info` с `id` сессии). Истёкшие строки остаются: их не
читает ни один запрос, рост таблицы — по числу входов.
- `CHECK password_hash LIKE '$argon2id$%'` — защита в глубину: открытый
пароль или быстрый хэш не запишется даже при ошибке в сервисе.
- Индекса по `sessions.user_id` нет: ни один запрос не ищет сессии по
пользователю, а пользователи не удаляются.
*Альтернатива:* `revoked_at` вместо удаления. Отвергнута: проверка
сессии получила бы ещё одно условие, а историю отзывов никто не читает —
она есть в журнале.
### 2. Проверка токена — один запрос с часами приложения
`SELECT sessions.id, users.* FROM sessions JOIN users ON ... WHERE
token_hash = :hash AND expires_at > :now`. `now` передаёт сервис
(`utcnow()`): `created_at` и `expires_at` тоже ставит приложение, и срок
сравнивается по одним часам. Нет строки — `Unauthenticated` (401
Bearer). Ошибка БД уходит в `get_db_session` и даёт 503, а не 401:
недоступность хранилища не делает токен недействительным (спек
`sessions`).
### 3. Пароль: Argon2id в потоке с ограничением
- `src/infra/password.py`: `PasswordHasher.from_parameters(
profiles.RFC_9106_LOW_MEMORY)` — профиль назван явно, а не взят
умолчанием библиотеки; async `hash_password`, `verify_password`.
- KDF — `anyio.to_thread.run_sync(..., limiter=...)` с отдельным
`CapacityLimiter` на `[auth] kdf_concurrency` (по умолчанию 4). Без
него вход шёл бы через общий пул потоков anyio на 40: 40 × 64 MiB =
2,5 GiB памяти, ВМ Docker — 7 GiB. С лимитом пик — 256 MiB, остальные
ждут в очереди.
- Неизвестный username проверяется против фиктивного хэша,
посчитанного один раз при первом входе. Время ответа тогда то же, что
у неверного пароля (`auth.md`); замер — в evidence.
- Регистрация хэширует пароль до обращения к БД. Вход читает хэш, затем
`commit()` — сессия БД возвращает соединение в пул, — проверяет пароль
и вставляет сессию новой транзакцией. Соединение пула не держится
30 мс KDF и время ожидания лимита. Между чтением и вставкой ничего не
может измениться: пароли и пользователи не меняются и не удаляются.
*Альтернативы:* bcrypt — режет пароль на 72 байтах, а пароль до 128
code points в UTF-8 занимает до 512 байт; scrypt — допустим, но lab7
требует Argon2id. `asyncio.to_thread` без лимита — память выше.
### 4. Разбор Basic — в слое API
- Зависимость входа: `HTTPBase(scheme="basic", scheme_name="basicAuth",
auto_error=False)` объявляет схему в `/openapi.json` и отдаёт сырые
credentials. Свой разбор (`auth.md`): схема `basic` без учёта регистра
→ `b64decode(..., validate=True)` → UTF-8 → `partition(":")`. Любой
сбой — `InvalidCredentials`.
- До БД отсекаются значения, которые не могут быть верными: username не
по шаблону, пароль вне 12–128 code points. Это тот же 401, без KDF и
без запроса к БД. Существования пользователя такой ответ не выдаёт, а
пароль в мегабайт не доходит до KDF.
- `HTTPBasic` FastAPI не годится: декодирует ASCII и на пароле не из
ASCII сам отвечает 401 мимо формата контракта (`api-contract.md`).
### 5. Bearer, текущая сессия и ошибки
- `get_current_session`: `HTTPBearer(scheme_name="bearerAuth",
auto_error=False)` → токен или `None` → `SessionService.authenticate`
→ `CurrentSessionDTO(id, user)`. `get_current_user` берёт `user` из
неё; `current_user_id` ставится после успеха. `X-User-Id` не читает
никто, константа и `APIKeyHeader` удаляются.
- Исключения: `InvalidCredentials` (вход) и `Unauthenticated` (Bearer)
вместо `Unidentified`. Таблица `errors.py` получает к статусу и `code`
ещё и заголовки: `WWW-Authenticate: Basic realm="messenger",
charset="UTF-8"` и `Bearer realm="messenger"`. Сообщения одинаковые
для всех причин внутри каждого исключения.
- `DELETE /auth/sessions/current` зависит от `get_current_session` и
удаляет её по `id`. Два одновременных выхода одним токеном оба
получат 204: проверка прошла у обоих, второй `DELETE` удалит 0 строк.
### 6. Настройки
- `[auth] session_ttl_seconds: int > 0`, по умолчанию 3600;
`[auth] kdf_concurrency: int > 0`, по умолчанию 4. Оба — в
`config_example.toml`: их читает только приложение (`settings.md`,
«Что где хранится»). В `.env` и compose срока нет.
- Короткий срок для проверки истечения — `AUTH__SESSION_TTL_SECONDS=2`
в окружении: в консоли перед `make run_dev` или `uv run`, у
контейнера — `-e` при `docker compose run`, как `run_isolated.py`
подменяет `DATABASE__NAME`. Окружение важнее `.env` и `config.toml`.
Для рабочего стенда в docker — правка смонтированного `config.toml` и
`docker compose restart api`.
- Контрактное имя `SESSION_TTL_SECONDS` — строкой в таблице
соответствия `REPORT.md`, как `APP_HOST` и `DATABASE_URL_FILE`: шапка
`.env.example` skeleton называет эти имена логическими и просит
сопоставить их с реальными в отчёте. Ни одна публичная проверка
`SESSION_TTL_SECONDS` не читает.
*Альтернатива:* `SESSION_TTL_SECONDS` в `.env` и мост
`AUTH__SESSION_TTL_SECONDS=${SESSION_TTL_SECONDS:-3600}` в `.env` и в
`x-app-env` compose. Отвергнута: значение по умолчанию в трёх местах
ради одного имени, а в консоли `SESSION_TTL_SECONDS=2` из окружения мост
не перекрывает (Context), так что контрактное имя работало бы только
правкой `.env`.
### 7. Миграция: очистка лабы 1, затем обязательный хэш
Одна ревизия поверх `16c279725564`:
1. `SELECT count(*) FROM users`; если больше нуля — `TRUNCATE users,
chats CASCADE` (уходят и `chat_members`, `messages`) и `warning` в
журнал `migrate` с числом удалённых пользователей. Логгер — stdlib
`logging.getLogger("alembic...")`: его уже форматирует
`src/infra/logger.py`, а ревизия не импортирует `src`
(`migrations.md`).
2. `password_hash text NOT NULL` с `CHECK`, таблица `sessions` с
ограничениями из решения 1.
3. `downgrade` — удалить `sessions` и колонку; удалённые данные не
возвращаются.
Решение пользователя (вопрос при `/opsx:propose`): у пользователей
лабы 1 нет пароля, войти они не смогут, данные синтетические. Повторный
прогон — no-op: alembic не применяет ревизию дважды.
*Альтернативы:* nullable-колонка и отказ во входе без хэша — в схеме
навсегда `NULL` и ветка в коде входа; `NOT NULL` с отказом миграции на
непустой базе — ручной `make wipe_data` у оператора.
### 8. `student-tests`
- `Actor` хранит `user`, пароль и токен; `headers()` →
`Authorization: Bearer`. `Api.register` регистрирует с паролем и
сразу входит; `Api.login` — отдельный вход; `Actor.unregistered()` —
случайный токен, которого нет на сервере.
- Тела регистрации в тестах `users`, гонок и рубрики — с паролем через
один хелпер: без него `test_duplicate_username` получил бы 400 вместо
409.
- `test_identification.py` переписывается по дельте спека;
`test_sessions.py` — новый. Сценарии, которые не проверить по HTTP на
обычном стенде (истечение, рестарт, недоступность БД, содержимое
таблиц), — исключения в `spec_coverage.py` со ссылкой на evidence и
`failure-checks`.
### 9. Evidence
Снимается с закоммиченного кода (`bench.md`, «Измеренное состояние —
commit»):
| Файл | Что |
|---|---|
| `evidence/tests/test-isolated.md` | `make test_isolated`: smoke и весь набор против образа, код 0 |
| `evidence/storage/test-persistence.md` | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `StartedAt` до и после |
| `evidence/auth/passwords-and-tokens.md` | `psql`: хэш Argon2id, токена нет в БД, `token_hash` 32 байта; журнал без пароля, токена и `Authorization`; время входа — неверный пароль и неизвестный username |
| `evidence/auth/expiry.md` | сервис с `AUTH__SESSION_TTL_SECONDS=2`: токен работает, через 3 с — 401, запросы срок не продлевают; отказ БД при запросе с токеном — 503 |
| `evidence/migrations/drop-lab1-data.md` | миграция на рабочей базе с данными лабы 1: число удалённых в журнале, повтор — no-op |
## Risks / Trade-offs
- [Миграция необратимо удаляет данные лабы 1] → Решение пользователя;
данные синтетические; удаление видно в журнале и в `REPORT.md`
(спек `db-migrations`).
- [Очередь KDF за лимитом съедает срок запроса 6 с, и вход получает 503
с записью «Database is unavailable»] → При 4 потоках и 30 мс на хэш
это больше 700 входов одновременно: для учебного стенда недостижимо.
Лимит и срок — настройки.
- [Истёкшие сессии копятся] → Их не читают; таблица растёт на одну
строку за вход. Чистка — фоновая задача с лабы 5.
- [Вход держит две транзакции] → Если БД упадёт между ними, клиент
получит 503 и повторит вход; сессия либо создана целиком, либо нет.
- [Каждый запрос с токеном — `SELECT` в PostgreSQL] → Так отзыв
мгновенный без инвалидации кэша (решение explore). Цену покажет
`bench-postgres`; кэш сессий в `membership-cache` не входит.
- [Swagger UI кодирует Basic через `btoa`, пароль не из ASCII из `/docs`
не войдёт] → Ограничение браузерного UI, не API; проверка — по HTTP в
тестах.
## Migration Plan
Порядок: зависимость и настройки → миграция и модели → infra пароля →
repo и сервисы → API (зависимости, роутер, ошибки) → `student-tests` →
скилл, правила, `AGENTS.md` → commit → evidence → `REPORT.md`. Рабочий
стенд после `make run_docker` проходит миграцию с очисткой. Откат:
`git revert` коммитов change, `alembic downgrade 16c279725564` (данные
лабы 1 не вернутся) или `make wipe_data`.