Files
mtusi2026lab4/openspec/changes/archive/2026-10-01-session-auth/proposal.md
T
ricoromaandClaude Opus 5.5 5d5d8f9d2a chore: carry lab 3 over
- carry the lab 3 solution over from mtusi2026lab3-safronov
  (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests,
  bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts,
  Dockerfile, compose, pyproject and uv lock
- merge Makefile, .gitignore and .dockerignore (the lab 3 versions only
  add lines to the skeleton, which is the same in lab 4) and
  .env.example (lab 4 skeleton names listed in the header)
- rename the compose project to mtusi-lab4 and the image to :lab4 so
  the stand does not reuse the lab 3 containers and volumes
- update AGENTS.md for lab 4: current lab, origin commit, contract and
  test files of the new skeleton

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 17:32:33 +03:00

7.1 KiB
Raw Blame History

Proposal

Why

Переход API 1 → 2 (COURSE.md): регистрация требует password, вход идёт по Basic, бизнес-запросы — по Bearer-сессии, а X-User-Id доступа больше не даёт. Сейчас любой клиент выдаёт себя за другого заголовком. Поэтому не проходят ни публичный smoke лабы 2, ни make test-persistence, ни зелёный make test_isolated — это обязательный минимум «3» (README.md). Хранилище уже в PostgreSQL (postgres-storage), теперь можно строить на нём сессии.

What Changes

  • BREAKING (API): POST /api/v1/users требует password (12–128 code points, не только из пробелов). Пароль хэшируется Argon2id и никогда не возвращается.
  • Новый POST /api/v1/auth/sessions: вход по Authorization: Basic, без тела. Ответ — 201 Session: непрозрачный токен (256 бит), token_type, expires_at, user. Неверный пароль, неизвестный пользователь и битый Basic дают одинаковый 401 с WWW-Authenticate: Basic realm="messenger", charset="UTF-8".
  • Новый DELETE /api/v1/auth/sessions/current: отзыв текущей сессии, 204. Дальше этот токен получает 401.
  • BREAKING (API): защищённые эндпоинты принимают только Authorization: Bearer <token>. Нет токена, он неизвестен, истёк или отозван, пришёл Basic — 401 с WWW-Authenticate: Bearer realm="messenger". X-User-Id игнорируется везде.
  • Сессии хранятся в PostgreSQL: SHA-256 токена, срок expires_at, фиксированный при входе. Срок задаёт [auth] session_ttl_seconds в config.toml (по умолчанию 3600), разовая подмена — окружением AUTH__SESSION_TTL_SECONDS; контрактное имя SESSION_TTL_SECONDS сопоставлено в REPORT.md. Действующие сессии переживают рестарт, рестарт срок не продлевает. Отзыв мгновенный: каждый запрос проверяет сессию в БД.
  • BREAKING (данные): миграция удаляет пользователей, чаты, участников и сообщения лабы 1 — у них нет пароля, войти они не смогут — и делает хэш пароля обязательным. Число удалённых пользователей пишется в журнал миграции. Данные стенда синтетические.
  • /openapi.json и /docs объявляют схемы bearerAuth и basicAuth из контракта вместо devUser.
  • student-tests идентифицируются Bearer-токеном. Добавлены проверки входа, неверного пароля, logout, отказа Basic и X-User-Id на бизнес-ручках.
  • Становятся зелёными публичный smoke, make test-persistence ACTION_SCRIPT=scripts/restart.sh и make test_isolated. Их выводы и ручная проверка истечения сессии при TTL 2 с сохраняются в evidence/.

Вне этого change: Redis/Valkey (membership-cache), автоматическая проверка истечения на особом стенде с коротким TTL и проверки отказов (failure-checks), перевод bench/ на Bearer (bench-postgres), ограничение частоты входа (429), чистка истёкших сессий.

Capabilities

New Capabilities

  • sessions: вход по Basic, токен и его хранение, срок жизни, отзыв, сохранность сессий после рестарта.

Modified Capabilities

  • identification: Bearer вместо X-User-Id на защищённых эндпоинтах, 401 с вызовом Bearer, X-User-Id игнорируется, схемы bearerAuth и basicAuth в документации API.
  • users: регистрация с паролем, хэш пароля через KDF, User без пароля, текущий пользователь по токену.
  • health: health не требует аутентификации и игнорирует Authorization и X-User-Id.
  • data-storage: сценарии с X-User-Id переходят на токен, сессии тоже хранятся в PostgreSQL и переживают рестарт.
  • container-run: рестарт hook-ом проверяется прежним токеном, make test-persistence проходит.
  • service-configuration: срок сессии — параметр config.toml с разовой подменой окружением, одинаково в консоли и docker.
  • service-logging: в журнале нет паролей, токенов, их хэшей и заголовка Authorization; user_id берётся из сессии.
  • student-tests: обязательные проверки лабы 2 — неверный пароль и logout.
  • db-migrations: миграция, которая удаляет данные, обязана сообщать об этом в журнале.

Impact

  • Код: src/core/services/session.py, src/core/repos/session.py, src/api/routers/v1/session.py, src/api/schemas/session.py, модель src/infra/db/models/session.py, хэширование пароля в src/infra/; правки user во всех слоях, src/api/dependencies.py (Bearer вместо X-User-Id), src/api/errors.py (WWW-Authenticate), src/core/exceptions/, src/config/settings.py ([auth]), src/utils/constants.py.
  • Миграция: password_hash в users, таблица sessions, очистка данных лабы 1.
  • Зависимости: argon2-cffi; uv.lock.
  • Конфигурация: config_example.toml (секция [auth]); .env.example и docker-compose.yml не меняются.
  • Тесты: student-tests/api_client.py (токен в Actor, регистрация с паролем и входом), новый test_sessions.py, переписанный test_identification.py, тела регистрации в test_users.py, test_race.py, test_rubric.py, spec_coverage.py.
  • Инструменты и документы: скилл run-mtusi-messenger (вход и Bearer в driver.py), AGENTS.md («Переходное состояние»), .claude/rules/ (auth.md — выбранные решения), REPORT.md (KDF, сессии, доказательства уровня «3»), evidence/.