- passwords and tokens: Argon2id hashes, no secrets in db and logs
- session expiry and database outage with a valid token
- make test-persistence and make test_isolated on ae4154e
- migration drops lab 1 data without passwords
- REPORT.md: sessions, defense scenario, evidence rows
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
32 KiB
Отчёт — лабораторная 2
- Автор, группа: Сафронов Роман Николаевич, БВТ2301
- Целевая оценка 5; выбранный трек 5: 2 (план запроса и восстановление)
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: раздел «Источники, библиотеки и использование ИИ» в конце отчёта
Отчёт заполняется по мере работы. Готово: хранение в PostgreSQL (change
postgres-storage), пароли, вход по Basic и Bearer-сессии
(session-auth). Впереди: кэш Redis/Valkey (membership-cache),
автоматические проверки отказов уровня 4 (failure-checks), EXPLAIN и
стенд под Postgres (bench-postgres), трек 2 (track2-query-plans,
track2-backup-restore).
Запуск из чистого clone
Версии. Образ API: python:3.12.14-slim-trixie и uv 0.12.17,
Postgres: postgres:18.6-trixie; все закреплены тегом и digest индекса
(amd64 + arm64) в Dockerfile и docker-compose.yml. Приложение:
Python 3.12, FastAPI 0.141.1, SQLAlchemy 2.1.1 (async), asyncpg 0.31.0,
alembic 1.20.0, argon2-cffi 25.1.0 и остальное строго по uv.lock. Проверено на Docker
Desktop 29.8.1 (VM linux/arm64), Compose v5.5.1, macOS на Apple M3 Pro.
Нужно на машине: Docker с BuildKit, make, python3 (3.9+) для
публичных проверок и make test_isolated, свободные порты
127.0.0.1:8080 (API) и 127.0.0.1:5433 (Postgres). uv на хосте нужен
только для запуска сервиса без контейнера (make run_dev).
Подготовка и секреты. make env_setup создаёт .env из
.env.example и config.toml из config_example.toml; существующие
файлы не трогает. В шаблоне пароль Postgres пустой, в новый .env
подставляется случайный (openssl rand -hex 16), так что общего пароля
стенда в git нет. Отдельно запускать env_setup не нужно: его вызывают
make run_docker, make run_dev и make test_isolated. Пароль задаётся
Postgres только при создании volume: после смены POSTGRES_PASSWORD
нужен make wipe_data.
git clone <fork> && cd <каталог clone>
git checkout solution/bvt2301-safronov
Способ 1. Всё в compose: make run_docker
make run_docker
# make env_setup (только недостающие .env и config.toml)
# DOCKER_BUILDKIT=1 docker compose build
# docker compose up -d postgres -> migrate (alembic upgrade head) -> api
Порядок задают depends_on: migrate стартует после healthcheck
Postgres (pg_isready по TCP), API — после того, как migrate
завершился с кодом 0. Готовность — GET http://127.0.0.1:8080/health/ready
→ 200 (несколько секунд после команды). Журнал API — make logs,
миграций — docker compose logs migrate.
Способ 2. Сервис на хосте: make run_dev
make run_dev
# docker compose up -d --wait postgres
# uv run alembic upgrade head -> 127.0.0.1:5433
# APP__RUN_MODE=console uv run python -m src
Сервис слушает 127.0.0.1:8080 с reload по src/, Postgres — тот же
контейнер и тот же volume, что у способа 1. Переключение между способами
не требует правки файлов (раздел «Конфигурация»).
Проверки
make check # структура skeleton
make validate PYTHON=.venv/bin/python # OpenAPI 3.1 (после uv sync --all-extras)
make test_isolated # образ на временной базе: smoke + student-tests, уборка
make student_test # собственные тесты против запущенного стенда (BASE_URL)
make test # публичный smoke против запущенного стенда
make test-persistence ACTION_SCRIPT=scripts/restart.sh # данные и прежний токен после рестарта
Ожидаемо: make test и make test-persistence — PASS,
make test_isolated — код 0 и 99 passed (evidence/tests/test-isolated.md).
Сценарий защиты
echo yes | make wipe_data && make run_docker # миграции на пустом volume
# регистрация, вход, сообщение — тем же сценарием, что в tests/smoke.py:
make test # PASS
make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт API и Postgres, тот же токен
# logout и повтор прежним токеном: test_logout, test_logout_twice в make test_isolated
# короткий срок сессии — отдельным экземпляром в консоли:
AUTH__SESSION_TTL_SECONDS=2 python3 .claude/skills/run-mtusi-messenger/driver.py --port 18080 start
Вручную вход и запрос выглядят так (пароль и токен — свои):
curl -s -X POST localhost:8080/api/v1/users -H 'Content-Type: application/json' \
-d '{"username":"alice_demo","display_name":"Алиса","password":"<пароль 12–128>"}'
curl -s -X POST localhost:8080/api/v1/auth/sessions -u 'alice_demo:<пароль>' # 201 Session
curl -s localhost:8080/api/v1/users/me -H 'Authorization: Bearer <token>' # 200
curl -s -X DELETE localhost:8080/api/v1/auth/sessions/current -H 'Authorization: Bearer <token>' # 204
Миграция 42bc3b9be38f удаляет данные лабы 1. У пользователей,
созданных до session-auth, нет пароля, войти они не смогут, а хэш
теперь обязателен. Поэтому при первом make run_docker или
make run_dev на старом volume миграция удаляет таких пользователей
вместе с чатами, участниками и сообщениями и пишет их число в журнал
migrate (warning). Данные стенда синтетические
(evidence/migrations/drop-lab1-data.md).
Остановка и удаление данных
make stop— остановить контейнеры;make down— удалить контейнеры, volumepostgres_dataс данными остаётся;make wipe_data— удалить контейнеры и volume, только после вводаyes; следующийmake run_dockerподнимает пустую базу со схемой.
Архитектура и решения
клиент --HTTP--> api (FastAPI, 1 процесс) --asyncpg, пул--> postgres (volume postgres_data)
^
migrate (тот же образ, alembic upgrade head, до старта api)
Источник истины — PostgreSQL. Пользователи, чаты, участники, сообщения и сессии хранятся только в нём; память процесса, файлы и SQLite не используются. Подтверждённая запись (201, 204) зафиксирована commit до ответа.
Схема (миграции migrations/versions/…_added_messenger_tables.py и
…_added_sessions_and_password_hashes.py):
| Таблица | Ключи и ограничения | Индексы |
|---|---|---|
users |
PK id; UNIQUE username; CHECK шаблона username и длины display_name; password_hash NOT NULL, CHECK LIKE '$argon2id$%' — открытый пароль или быстрый хэш не запишется |
uq_users_username |
sessions |
PK id; FK user_id → users; UNIQUE token_hash (SHA-256 токена, bytea, CHECK 32 байта); CHECK expires_at > created_at |
uq_sessions_token_hash — проверка токена |
chats |
PK id; CHECK длины title |
— |
chat_members |
PK (chat_id, user_id); FK на chats и users; UNIQUE (chat_id, position); position хранит порядок member_ids |
(user_id, created_at, chat_id) — keyset списка чатов |
messages |
PK id; составной FK (chat_id, sender_id) → chat_members: отправитель обязан быть участником; CHECK длины text |
(chat_id, created_at, id) — keyset истории |
id и created_at назначает сервис (uuid4(), utcnow()), а не БД.
chat_members.created_at — копия времени чата, по ней список чатов идёт
keyset-ом по индексу без сортировки всех чатов пользователя. CHECK
дублируют контракт: первым отвечает API (400), сработавший CHECK —
дефект валидации.
Транзакционные границы. Одна AsyncSession на запрос, commit делает
сервис, изоляция READ COMMITTED:
| Операция | Шаги в одной транзакции |
|---|---|
| регистрация | хэш пароля (до БД) → INSERT … ON CONFLICT (username) DO NOTHING RETURNING; конфликт → 409 |
| вход | транзакция 1: SELECT учётных данных → commit (соединение возвращается в пул); проверка пароля вне БД; транзакция 2: INSERT sessions → commit |
| запрос с токеном | один SELECT sessions JOIN users WHERE token_hash = … AND expires_at > now |
| выход | DELETE FROM sessions WHERE id = … → commit |
| создание чата | проверка существования участников → INSERT chats → INSERT chat_members (одна вставка) → commit; ошибка до commit — откат, не остаётся ни чата, ни участников |
| сообщение | проверка членства → INSERT messages → commit |
| чтения | один SELECT |
Явные блокировки не нужны: пользователи и участники не меняются и не
удаляются, гонку регистрации закрывает уникальный индекс (тест
test_same_username_at_once: из 10 одновременных регистраций одна 201,
девять 409).
Пагинация. Курсор — ключ (created_at, id) последнего элемента;
запрос — сравнение кортежей по индексу, без OFFSET. Повторов при обходе
нет. Сообщение, которое закоммитилось позже, но с created_at меньше уже
пройденного курсора, текущий обход пропустит, а новый обход с начала
увидит. Время ставит один процесс API с часами хоста; при нескольких
репликах лабы 3 часы общие (один Docker-host).
Недоступность БД. Критичная зависимость /health/ready — PostgreSQL
(SELECT 1 с таймаутом 2 с). Ошибки соединения и таймауты на
бизнес-запросе дают 503 unavailable без деталей, причина пишется в
журнал (warning), после возврата Postgres запросы обслуживаются без
рестарта API. Таймауты: подключение 3 с, ожидание соединения пула 5 с,
серверный statement_timeout 5 с, срок всей работы запроса с БД 6 с;
пул 10 + 5 соединений. При замёрзшем сервере ответ приходит через 6 + 2 с:
2 с — ограниченное мягкое закрытие прерванного соединения. Без этого
ограничения asyncpg и SQLAlchemy ждали разморозки сервера (169 с в
замере); подробности — design change postgres-storage, решение 6.
Пароли и сессии.
- Пароль — Argon2id (argon2-cffi), профиль RFC 9106 low-memory назван в коде явно: t = 3, m = 64 MiB, p = 4, соль 16 байт, хэш 32 байта. Около 30 мс на хэш или проверку. Пароль хэшируется целиком как UTF-8, без обрезки: 128 кириллических символов (256 байт) сравниваются полностью, поэтому не bcrypt (72 байта). Lab7 требует Argon2id.
- KDF не в event loop: в потоке через
anyio.to_thread.run_syncсо своим лимитом[auth] kdf_concurrency= 4. Пик памяти 4 × 64 MiB, а не 40 × 64 MiB при общем пуле потоков anyio. Пока считается пароль, соединение БД отпущено. - Неизвестный username проверяется против фиктивного хэша: время
ответа то же, что у неверного пароля (26,0 и 26,4 мс в медиане,
evidence/auth/passwords-and-tokens.md). Ответ одинаковый: 401 сWWW-Authenticate: Basic realm="messenger", charset="UTF-8". - Вход — только
Authorization: BasicнаPOST /auth/sessions. Разбор свой: FastAPIHTTPBasicдекодирует ASCII и на пароле не из ASCII сам отвечает 401 мимо формата контракта. Схема объявлена черезHTTPBase, base64 строго, UTF-8, первое двоеточие. Username не по шаблону и пароль вне 12–128 отсекаются до БД и KDF тем же 401. Ответа 400 у входа нет: любой сбой Basic — 401. - Токен —
secrets.token_urlsafe(32): 256 бит, 43 символа, ничего не кодирует. В БД — только его SHA-256: быстрого хэша достаточно, перебирать 256 бит нечего. - Сессия — строка
sessionsсexpires_at, фиксированным при входе. Срок не продлевают ни запросы, ни рестарт. Каждый запрос — одинSELECTпоtoken_hash, поэтому отзыв мгновенный:DELETEстроки, кэша нет. Истёкший, отозванный или неизвестный токен, Basic на бизнес-ручке — 401 сWWW-Authenticate: Bearer realm="messenger".X-User-Idигнорируется. - Недоступность Postgres при запросе с токеном — 503
unavailable, не 401 и не анонимный доступ (evidence/auth/expiry.md). - Журнал не содержит паролей, токенов, их хэшей,
Authorizationи username. Вход, неудачный вход и выход пишутся сuser_idиidсессии. Параметры SQL в ошибках драйвера скрыты (hide_parameters).
Конфигурация. Адреса, порты и учётные данные — из .env, пул,
таймауты и срок сессии — из config.toml. Переключение консоль ↔ docker
— без правки файлов. Консольный сервис читает .env с мостами
DATABASE__*; в контейнер .env не попадает, адрес и порт Postgres
приходят из environment compose. В compose нет литералов адреса и
порта Postgres, литерал — только адрес публикации 127.0.0.1.
Переменная skeleton (.env.example) |
В этом проекте |
|---|---|
APP_HOST |
режим APP__RUN_MODE: console — 127.0.0.1, docker — 0.0.0.0 |
APP_PORT |
APP__PORT (внутри), APP_OUT_PORT (публикация на 127.0.0.1) |
APP_ENV |
не используется: окружение одно — учебный стенд |
SESSION_TTL_SECONDS |
[auth] session_ttl_seconds в config.toml, по умолчанию 3600; разовая подмена — окружением AUTH__SESSION_TTL_SECONDS (так короткий срок 2 с для проверки истечения). Мостом из .env не заводится: его читает только приложение, а окружение мост по исходному имени не перекрывает |
DATABASE_URL_FILE |
не используется: URL собирает приложение из [database], пароль — мостом из POSTGRES_PASSWORD |
SESSION_STORE |
postgres: таблица sessions, без кэша — отзыв мгновенный |
CACHE_URL_FILE |
TODO, change membership-cache |
Что перенесено из лабы 1 и что изменено. Хранилище MemoryStore
заменено PostgreSQL, repo и сервисы переписаны на AsyncSession, цель
make run_no_compose удалена: API без Postgres не обслуживает запросы.
Переход API 1 → 2 (COURSE.md): X-User-Id заменён Bearer-сессией,
регистрация требует пароль, student-tests идентифицируются токеном.
Данные лабы 1 без паролей удаляет миграция (см. «Сценарий защиты»).
Согласования с преподавателем из лабы 1 действуют: FastAPI с его
расхождениями и конфиг через config.toml (AGENTS.md).
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | make test_isolated (внутри — make test против образа) |
PASS: lab2 public API scenario |
evidence/tests/test-isolated.md |
PostgreSQL содержит пользователей, чаты, участников и сообщения; PK/FK, уникальный username |
\d в psql, alembic check после миграций |
4 таблицы, ограничения и индексы по таблице выше; модели совпадают со схемой | evidence/migrations/from-zero-and-rerun.md, migrations/versions/ |
| Миграции с нуля и повторно без дублирования | make wipe_data, make run_docker, docker compose run --rm migrate |
migrate завершился с кодом 0 до старта API; повтор — no-op, число строк не изменилось |
evidence/migrations/from-zero-and-rerun.md |
| API не стартует при ошибке миграции | migrate с несуществующей базой через override-файл compose |
up — код 1, migrate Exited (1), api создан, но не запущен; ошибка в журнале migrate |
evidence/migrations/migration-error.md |
| Запуск из чистого clone: консоль, затем docker | git clone, make env_setup, make run_dev, make run_docker, make down + make run_docker |
консоль с нуля: Postgres, миграции и ready 200 одной командой; docker видит данные из консоли без правки файлов; после make down данные на месте |
evidence/storage/fresh-clone.md |
| Данные и действующие сессии переживают рестарт API и хранилищ без удаления volumes | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS: прежний токен читает те же данные; у API и Postgres новые StartedAt |
evidence/storage/test-persistence.md; порядок участников и истории — evidence/storage/restart.md (снят до session-auth, с X-User-Id) |
| Миграция к паролям на старой базе | make run_docker на volume с данными лабы 1, затем docker compose run --rm migrate |
warning «Deleted lab 1 data without passwords: 225 users…», password_hash NOT NULL, таблица sessions; повтор — no-op |
evidence/migrations/drop-lab1-data.md |
| Составная операция создания чата атомарна | код ChatService.create_chat: один commit |
автоматическая проверка отката — change failure-checks |
TODO |
Basic только на POST /auth/sessions, остальное — Bearer; X-User-Id не даёт доступ |
smoke и test_identification.py, test_sessions.py в make test_isolated |
Basic на /users/me — 401 с вызовом Bearer; только X-User-Id — 401; Bearer alice с X-User-Id eve — alice; битый Basic — 401 с вызовом Basic |
evidence/tests/test-isolated.md |
| Срок жизни сессии | сервис с AUTH__SESSION_TTL_SECONDS=2 |
200 сразу, 401 через 2,1 с; запросы каждые 0,5 с срок не продлевают | evidence/auth/expiry.md |
| Отзыв сессии | DELETE /auth/sessions/current: test_logout, test_logout_twice, test_other_session_survives_logout |
204 без тела, дальше этот токен — 401 везде; вторая сессия работает | evidence/tests/test-isolated.md |
| Пароли — password KDF | psql, pg_dump --data-only, журнал API |
$argon2id$v=19$m=65536,t=3,p=4$…, у одинаковых паролей разные хэши; пароля и токена нет ни в БД, ни в журнале; в sessions — SHA-256 токена |
evidence/auth/passwords-and-tokens.md |
| Secrets и volumes не в git | .gitignore, make env_setup |
.env, config.toml игнорируются; пароль Postgres генерируется локально |
.gitignore |
| Собственные тесты против контейнера | make test_isolated |
код 0: smoke PASS, 99 passed; 96 сценариев спеков: 81 тестом, 15 исключениями; база и контейнер убираются при любом исходе |
evidence/tests/test-isolated.md, evidence/tests/test-isolated-mechanics.md |
Конфигурация из .env, без литералов адреса и порта Postgres в compose |
POSTGRES_PORT и POSTGRES_OUT_PORT изменены в .env, make run_docker, make run_dev |
оба способа запуска подключились к новому порту, compose не правился | evidence/storage/postgres-port.md |
| Уровень 4: ограниченный пул и таймауты | пул из одного соединения, Postgres на паузе | второй запрос — 503 через 1 с (pool_timeout), первый — 503 через 6 + 2 с |
evidence/storage/pool-timeout.md |
| Уровень 4: таймаут запроса и логи без содержимого сообщений | messages под ACCESS EXCLUSIVE, POST сообщения |
503 через 5 с по statement_timeout; в журнале SQL и причина, параметры скрыты (hide_parameters), текста сообщения нет; до исправления он там был |
evidence/storage/statement-timeout.md |
| Уровень 4: недоступность БД | docker compose stop и pause postgres |
503 unavailable без деталей, /health/live 200, после возврата — без рестарта API |
evidence/storage/db-unavailable.md |
| Уровень 4: недоступность БД при запросе с токеном | docker compose stop postgres, GET /users/me и вход |
503 unavailable, не 401 и не анонимный доступ; после start тот же токен — 200 |
evidence/auth/expiry.md |
| Уровень 4: автоматические проверки logout и неверного пароля | test_logout, test_wrong_password (test_rubric.py) в make test_isolated |
выход — 204, повтор — 401 Bearer; неверный пароль — 401 Basic без токена | evidence/tests/test-isolated.md |
Уровень 4: гонка регистрации одного username |
test_same_username_at_once в make test_isolated |
10 клиентов, в полёте одновременно 10: одна 201, девять 409 | evidence/tests/test-isolated.md |
| Уровень 4: параметризованные запросы | код repo | SQLAlchemy Core/ORM с параметрами, SQL из строк нет | src/core/repos/ |
| Остальные пункты уровня 4 | — | TODO: Redis/Valkey, EXPLAIN на ≥10 000, автоматические проверки expiry и недоступности БД и Redis (failure-checks) |
TODO |
| Трек 5 | — | TODO | TODO |
Эксперименты и отказы
Стенд: Docker Desktop 29.8.1 на macOS (Apple M3 Pro), ВМ Docker 12 CPU и
7 GiB RAM, лимиты контейнерам не задавались; таймауты — по умолчанию из
config_example.toml.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
docker compose stop postgres |
503 вместо 500, ready 503, live 200 | 503 через 0,01 с; ready 503, live 200 | после start — сразу, без рестарта API; подтверждённые данные на месте |
docker compose pause postgres (сервер завис) |
503 не позже срока запроса и закрытия соединения (6 + 2 с) | 503 через 8,0 с, ready 503 через 2 с | после unpause — сразу |
| пул исчерпан (1 соединение, сервер завис) | ожидание не дольше pool_timeout |
503 через 1,0 с | после unpause — сразу |
messages под ACCESS EXCLUSIVE 8 с |
503 по statement_timeout, в журнале нет параметров SQL |
503 через 5,0 с, параметры скрыты | после снятия блокировки — сразу |
migrate завершился ошибкой |
API не стартует | api в состоянии Created, up — код 1 |
make run_docker с верной базой — сразу |
scripts/restart.sh (API и Postgres) |
данные и порядок на месте | hook 3,5 с, готовность через 1 с после него | потерь нет |
make test-persistence с тем же hook |
прежний токен работает | PASS, вся проверка 4,9 с |
сессии и данные на месте |
срок сессии 2 с (AUTH__SESSION_TTL_SECONDS=2) |
401 после срока, запросы не продлевают | первый 401 через 2,1 с при запросах каждые 0,5 с | — |
| Postgres остановлен, токен действующий | 503, не 401 | 503 unavailable на /users/me и на вход |
после start тот же токен — 200 |
| миграция к паролям на базе лабы 1 | данные без паролей удалены, это видно в журнале | warning с числом 225, password_hash NOT NULL |
данные лабы 1 удалены намеренно (синтетические) |
Ограничения и следующие шаги
- Сервер, замёрзший при открытом соединении, держит запрос 8 с, а не 6: 2 с уходят на ограниченное закрытие соединения.
- Время сообщений ставит процесс API: порядок истории зависит от часов хоста; конкурентные вставки могут быть пропущены текущим обходом (раздел «Пагинация»).
- Срок запроса может истечь на самом
commit. Тогда сервер мог уже зафиксировать запись, а клиент получит 503: это не частичная запись, но исход для клиента неизвестен, и повтор создаст дубль. Безопасный повтор появится сIdempotency-Keyв лабе 3. - Один Docker-host: потерю хоста стенд не переживает, Postgres без реплик.
- Прогоны
make student_testиmake testпротив рабочего стенда оставляют данные в рабочей базе; обычный прогон —make test_isolated. - Истёкшие сессии остаются в таблице: их не читает ни один запрос, рост — одна строка на вход. Чистка — фоновая задача с лабы 5.
- Вход ограничен лимитом KDF (4 хэша одновременно), но частота входа не ограничена (429 не реализован). Очередь из сотен входов дольше 6 с дала бы 503 с записью «Database is unavailable», хотя БД в порядке.
- Защита от перебора имён по времени касается только входа: регистрация
по контракту отвечает 409 на занятый
username. - Swagger UI кодирует Basic через
btoa: войти из/docsможно только с паролем из ASCII. API принимает любой UTF-8, это проверяют тесты. - Не реализовано: Redis/Valkey, автоматические проверки истечения и отказов, EXPLAIN и трек 2 — следующие changes.
Источники, библиотеки и использование ИИ
- Документация: PostgreSQL 18 (транзакции,
statement_timeout,pg_isready), SQLAlchemy 2.1 (asyncio, пул, обработка разрывов), alembic (async-шаблонenv.py), asyncpg (параметры подключения,connection_class), Docker Compose (depends_on,--wait, сети). - Документация по аутентификации: RFC 7617 (Basic), RFC 9106 (Argon2) и
argon2-cffi (профили параметров), anyio (
to_thread.run_sync,CapacityLimiter), FastAPI security (HTTPBase,HTTPBearer). - Библиотеки: FastAPI, pydantic, pydantic-settings, structlog, SQLAlchemy, asyncpg, alembic, argon2-cffi, uvicorn; в тестах — pytest и httpx.
- ИИ: Claude (Claude Code) помогал проектировать changes
postgres-storageиsession-auth(OpenSpec), писать код, правила и отчёт, а также проверял поведение на стенде. Решения и все правки просмотрены автором; поведение подтверждено командами, выводы которых лежат вevidence/.