From 0cef33335dc2883e89d879e64e46fb46a7a67bb4 Mon Sep 17 00:00:00 2001 From: roman Date: Thu, 1 Oct 2026 18:59:53 +0300 Subject: [PATCH] docs: add session-auth evidence and report - 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 --- REPORT.md | 166 ++++++++++++++++++++----- evidence/auth/expiry.md | 78 ++++++++++++ evidence/auth/passwords-and-tokens.md | 82 ++++++++++++ evidence/migrations/drop-lab1-data.md | 84 +++++++++++++ evidence/storage/test-persistence.md | 54 ++++++++ evidence/tests/test-isolated.md | 75 +++++++++++ openspec/changes/session-auth/tasks.md | 8 +- 7 files changed, 509 insertions(+), 38 deletions(-) create mode 100644 evidence/auth/expiry.md create mode 100644 evidence/auth/passwords-and-tokens.md create mode 100644 evidence/migrations/drop-lab1-data.md create mode 100644 evidence/storage/test-persistence.md create mode 100644 evidence/tests/test-isolated.md diff --git a/REPORT.md b/REPORT.md index 15bb747c..1c8907fe 100644 --- a/REPORT.md +++ b/REPORT.md @@ -6,10 +6,11 @@ - Использованные источники, библиотеки и помощь ИИ: раздел «Источники, библиотеки и использование ИИ» в конце отчёта Отчёт заполняется по мере работы. Готово: хранение в PostgreSQL (change -`postgres-storage`). Впереди: пароли, вход и сессии (`session-auth`), -кэш Redis/Valkey (`membership-cache`), проверки отказов уровня 4 -(`failure-checks`), EXPLAIN и стенд под Postgres (`bench-postgres`), -трек 2 (`track2-query-plans`, `track2-backup-restore`). +`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 @@ -17,7 +18,7 @@ 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 и остальное строго по `uv.lock`. Проверено на Docker +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+) для @@ -75,12 +76,41 @@ make validate PYTHON=.venv/bin/python # OpenAPI 3.1 (после uv sync --a make test_isolated # образ на временной базе: smoke + student-tests, уборка make student_test # собственные тесты против запущенного стенда (BASE_URL) make test # публичный smoke против запущенного стенда +make test-persistence ACTION_SCRIPT=scripts/restart.sh # данные и прежний токен после рестарта ``` -До change `session-auth` публичный smoke лабы 2 падает на регистрации с -`password`, а в `student-tests` падает `test_security_scheme_in_openapi` -(контракт lab2 не содержит схему `devUser`); остальные 79 тестов -проходят. +Ожидаемо: `make test` и `make test-persistence` — `PASS`, +`make test_isolated` — код 0 и `99 passed` (`evidence/tests/test-isolated.md`). + +### Сценарий защиты + +```sh +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 +``` + +Вручную вход и запрос выглядят так (пароль и токен — свои): + +```sh +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 ' # 200 +curl -s -X DELETE localhost:8080/api/v1/auth/sessions/current -H 'Authorization: Bearer ' # 204 +``` + +**Миграция `42bc3b9be38f` удаляет данные лабы 1.** У пользователей, +созданных до `session-auth`, нет пароля, войти они не смогут, а хэш +теперь обязателен. Поэтому при первом `make run_docker` или +`make run_dev` на старом volume миграция удаляет таких пользователей +вместе с чатами, участниками и сообщениями и пишет их число в журнал +`migrate` (`warning`). Данные стенда синтетические +(`evidence/migrations/drop-lab1-data.md`). ### Остановка и удаление данных @@ -97,15 +127,18 @@ make test # публичный smoke проти migrate (тот же образ, alembic upgrade head, до старта api) ``` -**Источник истины** — PostgreSQL. Пользователи, чаты, участники и -сообщения хранятся только в нём; память процесса, файлы и SQLite не -используются. Подтверждённая запись (201) зафиксирована commit до ответа. +**Источник истины** — PostgreSQL. Пользователи, чаты, участники, +сообщения и сессии хранятся только в нём; память процесса, файлы и SQLite +не используются. Подтверждённая запись (201, 204) зафиксирована commit до +ответа. -**Схема** (миграция `migrations/versions/…_added_messenger_tables.py`): +**Схема** (миграции `migrations/versions/…_added_messenger_tables.py` и +`…_added_sessions_and_password_hashes.py`): | Таблица | Ключи и ограничения | Индексы | |---|---|---| -| `users` | PK `id`; UNIQUE `username`; CHECK шаблона `username` и длины `display_name` | `uq_users_username` | +| `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 истории | @@ -121,7 +154,10 @@ keyset-ом по индексу без сортировки всех чатов | Операция | Шаги в одной транзакции | |---|---| -| регистрация | `INSERT … ON CONFLICT (username) DO NOTHING RETURNING`; конфликт → 409 | +| регистрация | хэш пароля (до БД) → `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` | @@ -149,8 +185,45 @@ keyset-ом по индексу без сортировки всех чатов ограничения asyncpg и SQLAlchemy ждали разморозки сервера (169 с в замере); подробности — design change `postgres-storage`, решение 6. -**Конфигурация.** Все значения — из `.env`, переключение консоль ↔ -docker без правки файлов. Консольный сервис читает `.env` с мостами +**Пароли и сессии.** + +- **Пароль** — 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`. + Разбор свой: FastAPI `HTTPBasic` декодирует 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`. @@ -160,16 +233,17 @@ docker без правки файлов. Консольный сервис чи | `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` | TODO, change `session-auth` | +| `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` | TODO, change `session-auth` (сессии в PostgreSQL) | +| `SESSION_STORE` | `postgres`: таблица `sessions`, без кэша — отзыв мгновенный | | `CACHE_URL_FILE` | TODO, change `membership-cache` | -**Что перенесено из лабы 1 и что изменено.** HTTP-контракт лабы 1 -(`X-User-Id`) пока сохранён: замену хранилища проверяют перенесённые -`student-tests` без правки тестов поведения. Хранилище `MemoryStore` +**Что перенесено из лабы 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). @@ -177,23 +251,29 @@ docker без правки файлов. Консольный сервис чи | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | `make test`, `make test_isolated` | TODO: до `session-auth` падает на регистрации с `password` | TODO | +| Публичный 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 | `scripts/restart.sh` | у API и Postgres новые `StartedAt` и `Up` с нуля в `docker compose ps`, прежний `X-User-Id` видит свои данные, порядок участников и истории тот же | `evidence/storage/restart.md`; `make test-persistence` — после `session-auth` | +| Данные и действующие сессии переживают рестарт 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, Bearer, срок жизни и отзыв сессии, KDF | — | TODO, change `session-auth` | 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` | механика проверена: база и контейнер убираются при любом исходе; зелёный прогон — после `session-auth` | `evidence/tests/test-isolated-mechanics.md` | +| Собственные тесты против контейнера | `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: гонка регистрации одного `username` | `test_same_username_at_once` | одна 201, девять 409 | TODO: вывод `make test_isolated` после `session-auth` | +| Уровень 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 и отказов | TODO | +| Остальные пункты уровня 4 | — | TODO: Redis/Valkey, EXPLAIN на ≥10 000, автоматические проверки expiry и недоступности БД и Redis (`failure-checks`) | TODO | | Трек 5 | — | TODO | TODO | ## Эксперименты и отказы @@ -210,6 +290,10 @@ docker без правки файлов. Консольный сервис чи | `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 удалены намеренно (синтетические) | ## Ограничения и следующие шаги @@ -226,7 +310,16 @@ docker без правки файлов. Консольный сервис чи реплик. - Прогоны `make student_test` и `make test` против рабочего стенда оставляют данные в рабочей базе; обычный прогон — `make test_isolated`. -- Не реализовано: вход и сессии, Redis/Valkey, автоматические проверки +- Истёкшие сессии остаются в таблице: их не читает ни один запрос, рост — + одна строка на вход. Чистка — фоновая задача с лабы 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. ## Источники, библиотеки и использование ИИ @@ -235,9 +328,14 @@ docker без правки файлов. Консольный сервис чи `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, uvicorn; в тестах — pytest и httpx. -- ИИ: Claude (Claude Code) помогал проектировать change - `postgres-storage` (OpenSpec), писать код, правила и отчёт, а также - проверял поведение на стенде. Решения и все правки просмотрены автором; - поведение подтверждено командами, выводы которых лежат в `evidence/`. + SQLAlchemy, asyncpg, alembic, argon2-cffi, uvicorn; в тестах — pytest и + httpx. +- ИИ: Claude (Claude Code) помогал проектировать changes + `postgres-storage` и `session-auth` (OpenSpec), писать код, правила и + отчёт, а также проверял поведение на стенде. Решения и все правки + просмотрены автором; поведение подтверждено командами, выводы которых + лежат в `evidence/`. diff --git a/evidence/auth/expiry.md b/evidence/auth/expiry.md new file mode 100644 index 00000000..27d0a384 --- /dev/null +++ b/evidence/auth/expiry.md @@ -0,0 +1,78 @@ +# Срок сессии и отказ БД при запросе с токеном + +| | | +|---|---| +| Спеки | `sessions` «Истёкший токен», «Срок не продлевается», «БД остановлена при запросе с токеном»; `service-configuration` «Короткий срок из окружения» | +| Change | `session-auth`, задача 7.1 | +| Дата | 2026-10-01 15:53 UTC | +| Commit | `ae4154e` | +| Хост | Docker Desktop 29.8.1, macOS arm64; ВМ Docker: 12 CPU, 7 GiB RAM; лимиты контейнерам не задавались | +| Клиент | разовый stdlib-скрипт; токены и пароли синтетические и в файл не попадают | + +Автоматическая проверка истечения и отказа БД требует особого стенда и +входит в change `failure-checks`. Здесь — ручной прогон тех же сценариев. + +## 1. Срок 2 с: `AUTH__SESSION_TTL_SECONDS=2` + +Стенд: сервис в console на `127.0.0.1:18080` +(`AUTH__SESSION_TTL_SECONDS=2 python3 .claude/skills/run-mtusi-messenger/driver.py +--port 18080 start`), Postgres из compose. Файлы конфигурации не +менялись: окружение важнее `.env` и `config.toml`. Запись «Created +session» в журнале сервиса — с `ttl_seconds: 2`. + +### Истёкший токен + +`expires_at` минус момент входа — 2,04 с. + +| Момент после входа | `GET /users/me` | `WWW-Authenticate` | +|---|---|---| +| сразу | 200 | — | +| через 3 с | 401 `unauthorized` | `Bearer realm="messenger"` | + +### Срок не продлевается: запросы каждые 0,5 с + +| Время после входа | Статус | +|---|---| +| 0,1 с | 200 | +| 0,6 с | 200 | +| 1,1 с | 200 | +| 1,6 с | 200 | +| 2,1 с | 401 | +| 2,6 с | 401 | +| 3,2 с | 401 | + +Срок по `expires_at` — 2,06 с после входа, первый 401 — через 2,1 с. +Частые успешные запросы срок не продлили. + +## 2. PostgreSQL остановлен, токен действующий + +Стенд: `make run_docker`, API на `127.0.0.1:8080`, срок по умолчанию +(3600 с). + +| Шаг | Запрос | Статус | `code` | +|---|---|---|---| +| БД работает | `GET /users/me` с токеном | 200 | — | +| `docker compose stop postgres` | `GET /users/me` с токеном | 503 | `unavailable` | +| | `POST /auth/sessions` | 503 | `unavailable` | +| `docker compose start postgres` | `GET /users/me` тем же токеном | 200 | — | + +У ответа 503 нет `WWW-Authenticate`: это не отказ в аутентификации, а +недоступность хранилища. + +Журнал API за время шага (`docker compose logs --no-log-prefix api`, +поля `level`, `event`, `error_type`): + +```json +{"level": "warning", "event": "Database is unavailable", "error_type": "gaierror"} +{"level": "warning", "event": "Database is unavailable", "error_type": "gaierror"} +``` + +## Вывод + +- Срок сессии фиксируется при входе. Окружение + `AUTH__SESSION_TTL_SECONDS` меняет его без правки файлов. +- После срока токен получает 401 с вызовом Bearer, и запросы срок не + продлевают. +- При остановленной БД запрос с действующим токеном получает 503, а не + 401 и не анонимный доступ. После возврата БД тот же токен снова + работает без рестарта API. diff --git a/evidence/auth/passwords-and-tokens.md b/evidence/auth/passwords-and-tokens.md new file mode 100644 index 00000000..c272f7f3 --- /dev/null +++ b/evidence/auth/passwords-and-tokens.md @@ -0,0 +1,82 @@ +# Пароли и токены: что хранится, что пишется в журнал, время входа + +| | | +|---|---| +| Спеки | `users` «Хэш в БД»; `sessions` «Токена нет в хранилище», «Неизвестный пользователь»; `service-logging` «Вход и выход» | +| Change | `session-auth`, задача 7.1 | +| Дата | 2026-10-01 15:52 UTC | +| Commit | `ae4154e` | +| Стенд | `make run_docker` (compose: postgres, migrate, api), API на `127.0.0.1:8080` | +| Хост | Docker Desktop 29.8.1, macOS arm64; ВМ Docker: 12 CPU, 7 GiB RAM; лимиты контейнерам не задавались | +| Клиент | разовый stdlib-скрипт: HTTP по контракту, `psql` и `pg_dump` в контейнере postgres, `docker compose logs`. Пароль P и токен T синтетические и в файл не попадают — только итоги проверок | + +## 1. Регистрация и вход + +| Запрос | Статус | Проверка | +|---|---|---| +| `POST /users` alice и bob с одинаковым паролем P | 201, 201 | поля `User`: `created_at`, `display_name`, `id`, `username`; пароля и хэша в ответе нет | +| `POST /auth/sessions` alice по Basic | 201 | токен T — 43 символа (`secrets.token_urlsafe(32)`, 256 бит), не содержит username и id | + +## 2. Что лежит в PostgreSQL + +```text +$ select username, left(password_hash, 31), length(password_hash) from users ... +alice_… $argon2id$v=19$m=65536,t=3,p=4$… 97 +bob_… $argon2id$v=19$m=65536,t=3,p=4$… 97 +``` + +Хэш — строка Argon2id (версия 19, m = 64 MiB, t = 3, p = 4) с солью и +результатом; параметры видны в самой строке. + +| Проверка | Результат | +|---|---| +| хэши одинакового пароля у alice и bob различаются (соль) | да | +| `token_hash` сессии alice — 32 байта | да | +| `token_hash` равен SHA-256 выданного токена | да | +| пароль P встречается в `pg_dump --data-only` | нет | +| токен T встречается в `pg_dump --data-only` | нет | + +## 3. Журнал API + +Сценарий: две регистрации, вход alice, вход с неверным паролем (401), +выход (204). Поиск по `docker compose logs --no-log-prefix api` за время +сценария: + +| В журнале | Встречается | +|---|---| +| пароль P | нет | +| токен T | нет | +| SHA-256 токена (hex) | нет | +| credentials Basic (base64) | нет | +| слово `Authorization` | нет | +| username alice | нет | + +Записи сервиса о сессиях (`module=session_service`; id сокращены, +`timestamp` и место вызова опущены): + +```json +{"level": "info", "event": "Created session", "user_id": "bc82f04f…", "session_id": "7c4d74c6…", "ttl_seconds": 3600} +{"level": "warning", "event": "Login failed"} +{"level": "info", "event": "Revoked session", "user_id": "bc82f04f…", "session_id": "7c4d74c6…", "already_revoked": false} +``` + +## 4. Время ответа на вход: неверный пароль и неизвестный username + +30 пар запросов поочерёдно; оба ответа — 401 с одинаковым телом и +`WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`. + +| Случай | Медиана | p90 | Мин | Макс | +|---|---|---|---|---| +| неверный пароль | 26,4 мс | 31,1 мс | 24,8 мс | 39,2 мс | +| неизвестный username | 26,0 мс | 29,8 мс | 25,1 мс | 58,5 мс | + +## Вывод + +- Пароль хранится только строкой Argon2id с солью, токен — только + SHA-256. По таблицам ни пароль, ни действующий токен не восстановить. +- В журнале нет пароля, токена, его хэша, credentials и username. Вход, + неудачный вход и выход записаны с `user_id` и `id` сессии там, где + они есть. +- Неизвестный username проверяется против фиктивного хэша, поэтому время + ответа то же, что у неверного пароля. Существование пользователя по + времени не определить; разница медиан — 0,4 мс. diff --git a/evidence/migrations/drop-lab1-data.md b/evidence/migrations/drop-lab1-data.md new file mode 100644 index 00000000..a72f3e94 --- /dev/null +++ b/evidence/migrations/drop-lab1-data.md @@ -0,0 +1,84 @@ +# Миграция `42bc3b9be38f`: очистка данных лабы 1 и обязательный хэш пароля + +| | | +|---|---| +| Спек | `db-migrations` «Миграция, удаляющая данные»: сценарии «Пользователи без пароля», «Пустая база» | +| Change | `session-auth`, решение 7 design и задача 7.1 | +| Дата | 2026-10-01 15:51 UTC | +| Commit | `ae4154e` | +| Стенд | рабочий стенд `make run_docker` (compose: postgres, migrate, api) с данными лабы 1 в volume `postgres_data` | +| Хост | Docker Desktop 29.8.1, macOS arm64; ВМ Docker: 12 CPU, 7 GiB RAM; лимиты контейнерам не задавались | + +У пользователей лабы 1 нет пароля: войти они не смогут, а хэш теперь +обязателен. Миграция удаляет их вместе с чатами, участниками и +сообщениями. Данные стенда синтетические — их создавали тесты и +сценарии evidence лабы 1 и `postgres-storage`. + +## До миграции + +| users | chats | chat_members | messages | alembic_version | +|---|---|---|---|---| +| 225 | 93 | 200 | 410 | `16c279725564` | + +Колонки `users`: `id, username, display_name, created_at`. Таблицы +`sessions` нет. + +## `make run_docker` с образом из `ae4154e` + +```text +$ make run_docker # exit 0 +Container mtusi-lab2-postgres-1 Running +Container mtusi-lab2-migrate-1 Recreated +Container mtusi-lab2-api-1 Recreated +Container mtusi-lab2-postgres-1 Healthy +Container mtusi-lab2-migrate-1 Started +Container mtusi-lab2-migrate-1 Exited +Container mtusi-lab2-api-1 Started +GET /health/ready -> 200 +``` + +Журнал `migrate` (`docker compose logs --no-log-prefix migrate`, поля +`level` и `event`): + +```json +{"level": "info", "event": "Running alembic"} +{"level": "info", "event": "Context impl PostgresqlImpl."} +{"level": "info", "event": "Will assume transactional DDL."} +{"level": "info", "event": "Running upgrade 16c279725564 -> 42bc3b9be38f, added sessions and password hashes"} +{"level": "warning", "event": "Deleted lab 1 data without passwords: 225 users with their chats and messages"} +{"level": "info", "event": "Finished alembic"} +``` + +`migrate` завершился с кодом 0 (`FinishedAt` 15:51:17.74) раньше старта +API (`StartedAt` 15:51:18.22). + +## После миграции + +| users | chats | chat_members | messages | alembic_version | +|---|---|---|---|---| +| 0 | 0 | 0 | 0 | `42bc3b9be38f` | + +Колонки `users`: `id, username, display_name, created_at, password_hash`; +`password_hash` — `NOT NULL`. Таблица `sessions` создана. + +## Повторный прогон + +```text +$ docker compose run --rm migrate # exit 0 +{"level": "info", "event": "Running alembic"} +{"level": "info", "event": "Context impl PostgresqlImpl."} +{"level": "info", "event": "Will assume transactional DDL."} +{"level": "info", "event": "Finished alembic"} +``` + +Строк `Running upgrade` и `Deleted ...` нет, счётчики те же: 0/0/0/0, +`42bc3b9be38f`. + +## Вывод + +- Миграция удалила данные лабы 1 без паролей и записала число + удалённых пользователей в журнал `migrate` с уровнем `warning`. +- После неё каждый пользователь обязан иметь хэш пароля. +- Повторный прогон ничего не удаляет и не меняет. +- Тот же сценарий на базе разработки с 3 засеянными пользователями, + `downgrade` и `alembic check` проверены при реализации (задача 2.2). diff --git a/evidence/storage/test-persistence.md b/evidence/storage/test-persistence.md new file mode 100644 index 00000000..8cc25933 --- /dev/null +++ b/evidence/storage/test-persistence.md @@ -0,0 +1,54 @@ +# `make test-persistence ACTION_SCRIPT=scripts/restart.sh`: данные и прежний токен после рестарта + +| | | +|---|---| +| Спеки | `container-run` «Публичная проверка сохранности», «Рестарт hook-ом»; `sessions` «Прежний токен после рестарта»; `data-storage` «Прежний пользователь после рестарта» | +| Change | `session-auth`, задача 7.1 | +| Дата | 2026-10-01 15:51 UTC | +| Commit | `ae4154e` | +| Стенд | `make run_docker` (compose: postgres, migrate, api), API на `127.0.0.1:8080` | +| Хост | Docker Desktop 29.8.1, macOS arm64; ВМ Docker: 12 CPU, 7 GiB RAM; лимиты контейнерам не задавались | + +Публичная проверка skeleton (`tests/resilience.py`, `tests/README.md`): +- создаёт пользователей с паролем, входит, создаёт чат и сообщение и + держит токен только в памяти процесса; +- запускает hook и ждёт готовности; +- проверяет те же данные **прежним токеном**, без повторного входа. + +## Запуск + +```text +$ make test-persistence ACTION_SCRIPT=scripts/restart.sh # exit 0, 4,9 с +python3 tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://localhost:8080" +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. +``` + +## Что действительно перезапускалось + +Проверка сама об этом не судит («Hook scope needs operator evidence»), +поэтому — `docker inspect` и `docker compose ps` до и после: + +| Контейнер | `StartedAt` до | `StartedAt` после | Перезапущен | +|---|---|---|---| +| `mtusi-lab2-api-1` | 2026-10-01T15:51:18.217149927Z | 2026-10-01T15:51:46.585300051Z | да | +| `mtusi-lab2-postgres-1` | 2026-10-01T15:47:56.156435375Z | 2026-10-01T15:51:43.730010675Z | да | + +```text +$ docker compose ps -a # до +mtusi-lab2-api-1 Up 24 seconds (healthy) +mtusi-lab2-migrate-1 Exited (0) 25 seconds ago +mtusi-lab2-postgres-1 Up 3 minutes (healthy) +$ docker compose ps -a # после +mtusi-lab2-api-1 Up 1 second (healthy) +mtusi-lab2-migrate-1 Exited (0) 1 second ago +mtusi-lab2-postgres-1 Up 4 seconds (healthy) +``` + +## Вывод + +- Hook перезапустил API и Postgres (новый `StartedAt` у обоих), volume + `postgres_data` сохранён. +- После рестарта прежний токен прочитал те же подтверждённые данные: + сессии хранятся в PostgreSQL и рестарт их не теряет. +- `migrate` прошёл заново как зависимость `start api`, это no-op. diff --git a/evidence/tests/test-isolated.md b/evidence/tests/test-isolated.md new file mode 100644 index 00000000..a02412a9 --- /dev/null +++ b/evidence/tests/test-isolated.md @@ -0,0 +1,75 @@ +# `make test_isolated`: публичный smoke и весь набор против образа + +| | | +|---|---| +| Спеки | `student-tests` «Прогон на временной базе» — сценарий «Успешный прогон»; «Результат прогона сохраняется»; `container-run` «Штатный запуск» (`make student_test` проходит) | +| Change | `session-auth`, задача 7.1 | +| Дата | 2026-10-01 15:54 UTC | +| Commit | `ae4154e` | +| Стенд | рабочий `make run_docker` запущен; образ собран из рабочего дерева, тестовый контейнер `mtusi-lab2-test-api` на `127.0.0.1:18088`, временная база `test_messenger` в том же Postgres | +| Хост | Docker Desktop 29.8.1, macOS arm64; ВМ Docker: 12 CPU, 7 GiB RAM; лимиты контейнерам не задавались | + +Механика временной базы и уборка при любом исходе — +`evidence/tests/test-isolated-mechanics.md`. Здесь — первый зелёный +прогон: до `session-auth` smoke лабы 2 падал на регистрации с паролем. + +## Прогон + +```text +$ make test_isolated # exit 0 +[test_isolated] database=test_messenger container=mtusi-lab2-test-api base_url=http://127.0.0.1:18088 +[test_isolated] build image +[test_isolated] create database test_messenger +[test_isolated] migrations +[test_isolated] start api container +[test_isolated] ready +[test_isolated] make test +PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. +[test_isolated] make student_test +coverage: 96 scenarios in 9 specs, 81 tested, 15 excluded +============================== 99 passed in 8.66s ============================== +[test_isolated] cleanup +[test_isolated] results: {'test': 0, 'student_test': 0} +``` + +Строки `PASSED` по модулям: + +| Модуль | Прошло | +|---|---| +| `test_api_conventions.py` | 11 | +| `test_chats.py` | 10 | +| `test_contract.py` | 8 | +| `test_coverage.py` | 7 | +| `test_data_storage.py` | 2 | +| `test_health.py` | 4 | +| `test_identification.py` | 10 | +| `test_messages.py` | 5 | +| `test_pagination.py` | 12 | +| `test_race.py` | 2 | +| `test_rubric.py` | 7 | +| `test_sessions.py` | 10 | +| `test_users.py` | 11 | +| **всего** | **99** | + +Гонки уровня «4» (вывод тестов с `-rP`): + +```text +race: 10 clients x 10 messages, statuses {201: 100}, max in flight 10; history: 100 messages, 100 unique ids, 4 pages by 30 +username race: 10 clients, statuses {409: 9, 201: 1}, max in flight 10 +``` + +## После прогона + +| Проверка | Результат | +|---|---| +| база `test_messenger` в `pg_database` | нет | +| контейнер `mtusi-lab2-test-api` в `docker ps -a` | нет | + +## Вывод + +- Образ из рабочего дерева в связке compose проходит публичный smoke + лабы 2 и все 99 собственных тестов, включая вход, Bearer, logout и + неверный пароль. +- Каждый сценарий HTTP-спеков покрыт тестом или исключением с причиной + и ссылкой на evidence: 81 тестом и 15 исключениями из 96. +- Временная база и контейнер убраны, рабочий стенд не затронут. diff --git a/openspec/changes/session-auth/tasks.md b/openspec/changes/session-auth/tasks.md index 175a8601..e6dbd3f2 100644 --- a/openspec/changes/session-auth/tasks.md +++ b/openspec/changes/session-auth/tasks.md @@ -108,7 +108,7 @@ ## 6. Инструменты и документы -- [ ] 6.1 Скилл `run-mtusi-messenger`: `driver.py` регистрирует с +- [x] 6.1 Скилл `run-mtusi-messenger`: `driver.py` регистрирует с паролем, входит и ходит с Bearer, `req --token` вместо `--user`; `SKILL.md` без `X-User-Id` и известных падений. Проверка: `python3 .claude/skills/run-mtusi-messenger/driver.py all` — `FAILED: none`, @@ -127,11 +127,11 @@ ## 7. Evidence и отчёт -- [ ] 7.1 Evidence по таблице решения 9 с закоммиченного кода. Проверка: +- [x] 7.1 Evidence по таблице решения 9 с закоммиченного кода. Проверка: в каждом файле дата, commit, стенд; паролей, токенов и `Authorization` в файлах нет; `drop-lab1-data.md` снят на рабочей базе до её очистки. -- [ ] 7.2 `REPORT.md`: Argon2id и его параметры, сессии и их хранение, +- [x] 7.2 `REPORT.md`: Argon2id и его параметры, сессии и их хранение, `SESSION_TTL_SECONDS` и `SESSION_STORE=postgres` в таблице соответствия, сценарий защиты (миграции → вход → сообщение → `make test-persistence` → logout), строки доказательств уровня «3» и @@ -139,6 +139,6 @@ предупреждение об очистке данных лабы 1, удаление закрытых TODO. Проверка: у каждой строки таблицы доказательств есть команда, наблюдение и файл. -- [ ] 7.3 `make lint`, `make check`, `openspec validate session-auth +- [x] 7.3 `make lint`, `make check`, `openspec validate session-auth --strict`, `graphify update .`; показать изменения и после подтверждения пользователя закоммитить evidence и отчёт.