- 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>
250 lines
17 KiB
Markdown
250 lines
17 KiB
Markdown
# 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`.
|