Files
mtusi2026lab2/openspec/changes/session-auth/design.md
T
ricoromaandClaude Opus 5.5 7887e03ade fix: precompute dummy password hash at startup
- lifespan computes the dummy Argon2id hash: first unknown-user login
  takes as long as a wrong password
- evidence for session TTL from config.toml, default and environment
- REPORT.md: manual /docs check, TTL configuration row
- tasks.md: why checks ran on a separate dev database

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 19:16:18 +03:00

17 KiB
Raw Blame History

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 проверяется против фиктивного хэша, посчитанного один раз на процесс — в lifespan при старте. Время ответа тогда то же, что у неверного пароля, с первого запроса (auth.md); замер — в evidence. Ленивый расчёт при первом входе делал бы этот вход вдвое дольше (нашёл /opsx:verify).
  • Регистрация хэширует пароль до обращения к БД. Вход читает хэш, затем 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.