# 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`.