- 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>
17 KiB
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)— профиль назван явно, а не взят умолчанием библиотеки; asynchash_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.
HTTPBasicFastAPI не годится: декодирует 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.exampleskeleton называет эти имена логическими и просит сопоставить их с реальными в отчёте. Ни одна публичная проверка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:
SELECT count(*) FROM users; если больше нуля —TRUNCATE users, chats CASCADE(уходят иchat_members,messages) иwarningв журналmigrateс числом удалённых пользователей. Логгер — stdliblogging.getLogger("alembic..."): его уже форматируетsrc/infra/logger.py, а ревизия не импортируетsrc(migrations.md).password_hash text NOT NULLсCHECK, таблицаsessionsс ограничениями из решения 1.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.