feat: add password login and bearer sessions
- 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>
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-01
|
||||
@@ -0,0 +1,249 @@
|
||||
# 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`.
|
||||
@@ -0,0 +1,105 @@
|
||||
# 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/`.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Данные переживают рестарт стенда
|
||||
|
||||
Данные PostgreSQL SHALL храниться в именованном volume. Скрипт
|
||||
`scripts/restart.sh` SHALL перезапускать API и все используемые
|
||||
хранилища, сохраняя volume, схему и данные: без удаления volume,
|
||||
очистки и повторного наполнения. Скрипт SHALL быть исполняемым,
|
||||
завершаться с кодом 0 только после перезапуска, укладываться в 90 с и
|
||||
MUST NOT печатать секреты. Публичная проверка `make test-persistence
|
||||
ACTION_SCRIPT=scripts/restart.sh` SHALL проходить.
|
||||
|
||||
#### Scenario: Рестарт hook-ом
|
||||
|
||||
- **WHEN** пользователь вошёл, отправил сообщение, затем выполнен
|
||||
`scripts/restart.sh`
|
||||
- **THEN** контейнеры API и Postgres перезапущены (новое время старта в
|
||||
`docker inspect`), а после готовности запрос с прежним токеном
|
||||
получает 200 и видит своё сообщение
|
||||
|
||||
#### Scenario: Публичная проверка сохранности
|
||||
|
||||
- **WHEN** на запущенном стенде выполняется `make test-persistence
|
||||
ACTION_SCRIPT=scripts/restart.sh`
|
||||
- **THEN** команда завершается с кодом 0 и печатает `PASS`
|
||||
@@ -0,0 +1,31 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Хранение в PostgreSQL
|
||||
|
||||
Пользователи, чаты, участники чатов, сообщения и сессии SHALL храниться
|
||||
в PostgreSQL, он — источник истины. Сервис MUST NOT хранить эти данные
|
||||
в памяти процесса, файлах или SQLite. Подтверждённая запись (ответ 201
|
||||
или 204) SHALL быть зафиксирована в БД до ответа и видна следующему
|
||||
запросу.
|
||||
|
||||
#### Scenario: Созданное видно сразу
|
||||
|
||||
- **WHEN** клиент зарегистрировался и следующим запросом входит с теми
|
||||
же username и паролем
|
||||
- **THEN** вход успешен, и `GET /api/v1/users/me` с выданным токеном
|
||||
возвращает этого пользователя
|
||||
|
||||
### Requirement: Данные переживают рестарт
|
||||
|
||||
После перезапуска сервиса и PostgreSQL с сохранённым volume все ранее
|
||||
подтверждённые пользователи, чаты, участники и сообщения SHALL быть
|
||||
доступны в прежнем виде.
|
||||
|
||||
#### Scenario: Прежний пользователь после рестарта
|
||||
|
||||
- **WHEN** стенд перезапущен `scripts/restart.sh`, и клиент использует
|
||||
токен, полученный до рестарта
|
||||
- **THEN** ответ 200, а история чата этого пользователя содержит те же
|
||||
сообщения в том же порядке
|
||||
@@ -0,0 +1,23 @@
|
||||
# Spec Delta
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Миграция, удаляющая данные
|
||||
|
||||
Миграция MUST NOT удалять данные, которые можно привести к новой схеме.
|
||||
Миграция, которая удаляет данные, SHALL записывать в журнал сервиса миграций,
|
||||
сколько строк удалено, а её повторный запуск MUST NOT ничего удалять.
|
||||
Об удалении SHALL предупреждать `REPORT.md`.
|
||||
|
||||
#### Scenario: Пользователи без пароля
|
||||
|
||||
- **WHEN** миграция, которая делает хэш пароля обязательным, применяется
|
||||
к базе с пользователями лабы 1
|
||||
- **THEN** пользователи, их чаты, участники и сообщения удалены, в
|
||||
журнале `migrate` есть число удалённых пользователей, а схема требует
|
||||
хэш пароля у каждого пользователя
|
||||
|
||||
#### Scenario: Пустая база
|
||||
|
||||
- **WHEN** та же миграция применяется к пустой базе или повторно
|
||||
- **THEN** ничего не удаляется, и команда завершается с кодом 0
|
||||
@@ -0,0 +1,21 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Health вне версии API и без идентификации
|
||||
|
||||
Эндпоинты health SHALL находиться вне префикса `/api/v1`, MUST NOT
|
||||
требовать аутентификации и SHALL игнорировать заголовки
|
||||
`Authorization` и `X-User-Id`.
|
||||
|
||||
#### Scenario: Неизвестный X-User-Id
|
||||
|
||||
- **WHEN** клиент запрашивает health с `X-User-Id` несуществующего
|
||||
пользователя
|
||||
- **THEN** ответ 200, а не 401
|
||||
|
||||
#### Scenario: Неизвестный токен
|
||||
|
||||
- **WHEN** клиент запрашивает health с Bearer-токеном, которого сервис
|
||||
не выдавал
|
||||
- **THEN** ответ 200, а не 401
|
||||
@@ -0,0 +1,127 @@
|
||||
# Spec Delta
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Защищённые эндпоинты требуют Bearer
|
||||
|
||||
Все эндпоинты, кроме `POST /api/v1/users`, `POST /api/v1/auth/sessions`
|
||||
и health, SHALL требовать заголовок `Authorization: Bearer <token>` с
|
||||
токеном действующей сессии (capability `sessions`). Владелец сессии
|
||||
SHALL считаться текущим пользователем запроса.
|
||||
|
||||
#### Scenario: Действующий токен
|
||||
|
||||
- **WHEN** пользователь вызывает `GET /api/v1/users/me` со своим токеном
|
||||
- **THEN** ответ 200 с этим пользователем
|
||||
|
||||
### Requirement: Отказ в аутентификации — 401
|
||||
|
||||
Сервис SHALL отвечать 401 с `code` `unauthorized` и заголовком
|
||||
`WWW-Authenticate: Bearer realm="messenger"`, когда на защищённом
|
||||
эндпоинте нет заголовка `Authorization`, схема не `Bearer` (в том числе
|
||||
верный `Basic`), токен пустой, неизвестен, истёк или отозван. Эти случаи
|
||||
MUST давать одинаковый ответ и MUST NOT давать 400 или 403.
|
||||
|
||||
#### Scenario: Нет заголовка
|
||||
|
||||
- **WHEN** клиент вызывает `GET /api/v1/users/me` без `Authorization`
|
||||
- **THEN** ответ 401 с `code` `unauthorized` и `WWW-Authenticate` схемы
|
||||
`Bearer`
|
||||
|
||||
#### Scenario: Неизвестный токен
|
||||
|
||||
- **WHEN** клиент вызывает `GET /api/v1/users/me` с Bearer-токеном,
|
||||
которого сервис не выдавал
|
||||
- **THEN** ответ 401 с `WWW-Authenticate` схемы `Bearer`
|
||||
|
||||
#### Scenario: Basic на бизнес-эндпоинте
|
||||
|
||||
- **WHEN** клиент вызывает `GET /api/v1/users/me` с верными username и
|
||||
паролем в `Authorization: Basic`
|
||||
- **THEN** ответ 401 с `WWW-Authenticate` схемы `Bearer`
|
||||
|
||||
### Requirement: X-User-Id не даёт доступа
|
||||
|
||||
Заголовок `X-User-Id` SHALL игнорироваться: он MUST NOT давать доступ
|
||||
без Bearer-токена и MUST NOT менять текущего пользователя при
|
||||
действующем токене.
|
||||
|
||||
#### Scenario: Только X-User-Id
|
||||
|
||||
- **WHEN** клиент вызывает `GET /api/v1/users/me` только с `X-User-Id`
|
||||
существующего пользователя
|
||||
- **THEN** ответ 401
|
||||
|
||||
#### Scenario: X-User-Id не меняет владельца
|
||||
|
||||
- **WHEN** клиент вызывает `GET /api/v1/users/me` с токеном alice и
|
||||
`X-User-Id` eve
|
||||
- **THEN** ответ 200 с пользователем alice
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Идентификация раньше доступа и валидации
|
||||
|
||||
Аутентификация SHALL проверяться раньше доступа к конкретному ресурсу и
|
||||
раньше проверки пути, query и полей тела. Исключение, согласованное с
|
||||
преподавателем 2026-09-26: тело, которое не разбирается как JSON,
|
||||
отклоняется с 400 до аутентификации.
|
||||
|
||||
#### Scenario: Чужой чат без заголовка
|
||||
|
||||
- **WHEN** клиент без Bearer-токена запрашивает существующий чат
|
||||
- **THEN** ответ 401, а не 404
|
||||
|
||||
#### Scenario: Невалидное поле без заголовка
|
||||
|
||||
- **WHEN** клиент без Bearer-токена отправляет сообщение с
|
||||
`{"text": ""}`
|
||||
- **THEN** ответ 401, а не 400
|
||||
|
||||
#### Scenario: Битый JSON без заголовка
|
||||
|
||||
- **WHEN** клиент без Bearer-токена отправляет тело `{bad`
|
||||
- **THEN** ответ 400 с `code` `invalid_request`
|
||||
|
||||
### Requirement: Схема идентификации в документации API
|
||||
|
||||
Документация, которую отдаёт сервис (`/openapi.json` и `/docs`), SHALL
|
||||
объявлять схемы безопасности `bearerAuth` и `basicAuth` так же, как
|
||||
`contracts/openapi.json`, и MUST NOT объявлять `devUser`. Защищённые
|
||||
операции SHALL ссылаться на `bearerAuth`, `POST /api/v1/auth/sessions` —
|
||||
на `basicAuth`, а `POST /api/v1/users` и health MUST NOT ссылаться ни на
|
||||
одну схему. Объявление схем MUST NOT менять ответы: без заголовка
|
||||
по-прежнему 401 в формате контракта, а не ошибка FastAPI.
|
||||
|
||||
#### Scenario: Кнопка Authorize в Swagger
|
||||
|
||||
- **WHEN** разработчик открывает `/docs`
|
||||
- **THEN** кнопка Authorize предлагает Basic для входа и Bearer для
|
||||
остальных запросов, и введённый токен уходит заголовком
|
||||
`Authorization: Bearer` в защищённые запросы
|
||||
|
||||
#### Scenario: Схема в openapi.json
|
||||
|
||||
- **WHEN** клиент запрашивает `/openapi.json`
|
||||
- **THEN** `components.securitySchemes.bearerAuth` и `basicAuth`
|
||||
совпадают с контрактом, `devUser` нет, у `GET /api/v1/users/me`
|
||||
`security` равно `[{"bearerAuth": []}]`, у
|
||||
`POST /api/v1/auth/sessions` — `[{"basicAuth": []}]`, а у
|
||||
`POST /api/v1/users` `security` нет
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Защищённые эндпоинты требуют X-User-Id
|
||||
|
||||
**Reason**: переход API 1 → 2 (`COURSE.md`): `X-User-Id` заменяется
|
||||
Bearer-сессией.
|
||||
**Migration**: требование «Защищённые эндпоинты требуют Bearer»;
|
||||
сценарий «Корректный заголовок» переходит в «Действующий токен».
|
||||
|
||||
### Requirement: Отказ в идентификации — 401
|
||||
|
||||
**Reason**: заголовка `X-User-Id` больше нет; отказ теперь касается
|
||||
Bearer-токена и несёт `WWW-Authenticate`.
|
||||
**Migration**: требование «Отказ в аутентификации — 401»; сценарии «Не
|
||||
UUID» и «Неизвестный пользователь» переходят в «Неизвестный токен», «Нет
|
||||
заголовка» остаётся с проверкой `WWW-Authenticate`.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Spec Delta
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Срок жизни сессии
|
||||
|
||||
Срок жизни сессии SHALL задаваться параметром приложения
|
||||
`[auth] session_ttl_seconds` в `config.toml` и одинаково действовать в
|
||||
консоли и в docker. Без параметра срок SHALL быть 3600 с. Разовая
|
||||
подмена SHALL работать через окружение `AUTH__SESSION_TTL_SECONDS` без
|
||||
правки файлов. Значение SHALL быть целым положительным числом секунд,
|
||||
иначе сервис MUST NOT стартовать (требование «Некорректное значение
|
||||
останавливает запуск»). Соответствие контрактному имени
|
||||
`SESSION_TTL_SECONDS` SHALL быть описано в `REPORT.md`.
|
||||
|
||||
#### Scenario: Срок из config.toml
|
||||
|
||||
- **WHEN** в `config.toml` задано `[auth] session_ttl_seconds = 600`, и
|
||||
сервис запущен через `make run_dev` или `make run_docker`
|
||||
- **THEN** `expires_at` новой сессии на 600 с позже момента входа
|
||||
|
||||
#### Scenario: Срок по умолчанию
|
||||
|
||||
- **WHEN** параметр в `config.toml` не задан
|
||||
- **THEN** `expires_at` новой сессии на 3600 с позже момента входа
|
||||
|
||||
#### Scenario: Короткий срок из окружения
|
||||
|
||||
- **WHEN** сервис запущен с `AUTH__SESSION_TTL_SECONDS=2` в окружении,
|
||||
а файлы не менялись
|
||||
- **THEN** `expires_at` новой сессии на 2 с позже момента входа
|
||||
|
||||
#### Scenario: Срок не число
|
||||
|
||||
- **WHEN** сервис запускается с `AUTH__SESSION_TTL_SECONDS=abc` или
|
||||
`0`
|
||||
- **THEN** сервис не стартует, в журнале — ошибка проверки настроек
|
||||
@@ -0,0 +1,26 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Без содержимого сообщений и личных данных
|
||||
|
||||
Записи MUST NOT содержать текст сообщений, `display_name`, названия
|
||||
чатов, значения `username`, тела запросов и ответов. Записи MUST NOT
|
||||
содержать пароли, токены сессий, их хэши, значение заголовка
|
||||
`Authorization` и параметры SQL-запросов. Для сообщений допускаются
|
||||
идентификаторы и длина текста, для сессий — `id` сессии и `user_id`.
|
||||
|
||||
#### Scenario: Отправка сообщения
|
||||
|
||||
- **WHEN** участник отправляет сообщение с текстом T
|
||||
- **THEN** ни одна запись журнала не содержит T, а запись о создании
|
||||
сообщения содержит его `id`, `chat_id` и длину текста
|
||||
|
||||
#### Scenario: Вход и выход
|
||||
|
||||
- **WHEN** пользователь регистрируется с паролем P, входит, получает
|
||||
токен T и выходит, а затем кто-то пытается войти с неверным паролем
|
||||
- **THEN** ни одна запись журнала не содержит P, T, хэш T и значение
|
||||
`Authorization`; записи о создании и отзыве сессии содержат `user_id`
|
||||
и `id` сессии, а неудачный вход записан с уровнем `warning` без
|
||||
username и пароля
|
||||
@@ -0,0 +1,158 @@
|
||||
# Spec Delta
|
||||
|
||||
## Purpose
|
||||
|
||||
Как пользователь получает и теряет право на запросы с лабы 2: вход по
|
||||
паролю через Basic с выдачей непрозрачного токена, хранение сессий,
|
||||
срок жизни и отзыв, сохранность действующих сессий после рестарта.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Вход по Basic
|
||||
|
||||
`POST /api/v1/auth/sessions` SHALL принимать только заголовок
|
||||
`Authorization: Basic <base64(username:password)>`; тело запроса MUST
|
||||
NOT читаться и не влияет на ответ. Схема `Basic` распознаётся без учёта
|
||||
регистра, credentials декодируются как UTF-8, username и пароль делятся
|
||||
по первому двоеточию: двоеточие в пароле допустимо. При верной паре
|
||||
сервис SHALL создать новую сессию и ответить 201 с объектом `Session`:
|
||||
`token`, `token_type` `Bearer`, `expires_at` в RFC 3339 UTC с `Z` и
|
||||
`user` — тот же объект `User`, что при регистрации.
|
||||
|
||||
#### Scenario: Успешный вход
|
||||
|
||||
- **WHEN** зарегистрированный пользователь входит со своими username и
|
||||
паролем
|
||||
- **THEN** ответ 201 `Session`, `token_type` равен `Bearer`, `user`
|
||||
совпадает с ответом на регистрацию, `expires_at` в будущем
|
||||
|
||||
#### Scenario: Двоеточие и не-ASCII в пароле
|
||||
|
||||
- **WHEN** пароль содержит `:` и кириллицу, и пользователь входит с ним
|
||||
- **THEN** ответ 201
|
||||
|
||||
#### Scenario: Несколько сессий
|
||||
|
||||
- **WHEN** пользователь входит дважды
|
||||
- **THEN** токены разные, и оба принимаются защищёнными эндпоинтами
|
||||
|
||||
### Requirement: Токен непрозрачный
|
||||
|
||||
Токен SHALL быть случайным значением не короче 32 символов с энтропией
|
||||
не менее 256 бит. Токен MUST NOT содержать и кодировать `username`,
|
||||
`id` пользователя или срок. Сервис MUST NOT хранить токен в открытом
|
||||
виде: по данным хранилища нельзя восстановить действующий токен.
|
||||
|
||||
#### Scenario: Токен не выводится из данных пользователя
|
||||
|
||||
- **WHEN** пользователь получил токен
|
||||
- **THEN** токен не содержит его `username` и `id`, а у двух входов
|
||||
одного пользователя токены не совпадают
|
||||
|
||||
#### Scenario: Токена нет в хранилище
|
||||
|
||||
- **WHEN** выдан токен T
|
||||
- **THEN** ни одна строка таблиц PostgreSQL не содержит T
|
||||
|
||||
### Requirement: Отказ во входе
|
||||
|
||||
Неверный пароль, неизвестный username, отсутствие заголовка, другая
|
||||
схема вместо `Basic`, битый base64, credentials не в UTF-8 и
|
||||
credentials без двоеточия SHALL давать одинаковый ответ 401 с `code`
|
||||
`unauthorized`, одинаковым `message` и заголовком
|
||||
`WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`. Сессия при
|
||||
этом MUST NOT создаваться. Время ответа для неизвестного username MUST
|
||||
NOT заметно отличаться от ответа на неверный пароль: проверка пароля
|
||||
выполняется в обоих случаях.
|
||||
|
||||
#### Scenario: Неверный пароль
|
||||
|
||||
- **WHEN** пользователь входит со своим username и чужим паролем
|
||||
- **THEN** ответ 401 с `WWW-Authenticate` схемы `Basic`
|
||||
|
||||
#### Scenario: Неизвестный пользователь
|
||||
|
||||
- **WHEN** вход выполняется с username, которого нет
|
||||
- **THEN** ответ совпадает с ответом на неверный пароль: тот же статус,
|
||||
`code`, `message` и `WWW-Authenticate`
|
||||
|
||||
#### Scenario: Битый Basic
|
||||
|
||||
- **WHEN** заголовок `Authorization` равен `Basic !!!`, `Basic` с
|
||||
base64 без двоеточия или `Bearer <токен>`
|
||||
- **THEN** ответ 401 с `WWW-Authenticate` схемы `Basic`
|
||||
|
||||
### Requirement: Срок жизни сессии
|
||||
|
||||
Срок сессии SHALL фиксироваться при входе: `expires_at` равен моменту
|
||||
входа плюс настроенный срок жизни (контрактное имя
|
||||
`SESSION_TTL_SECONDS`, capability `service-configuration`).
|
||||
Использование токена и рестарт сервиса MUST NOT продлевать срок. После
|
||||
`expires_at` токен SHALL получать 401 с `WWW-Authenticate: Bearer
|
||||
realm="messenger"`.
|
||||
|
||||
#### Scenario: Истёкший токен
|
||||
|
||||
- **WHEN** срок жизни сессии равен 2 с, пользователь вошёл и через 3 с
|
||||
запрашивает `GET /api/v1/users/me`
|
||||
- **THEN** ответ 401 с `WWW-Authenticate` схемы `Bearer`
|
||||
|
||||
#### Scenario: Срок не продлевается
|
||||
|
||||
- **WHEN** срок жизни сессии равен 2 с, и пользователь каждые 0,5 с
|
||||
успешно запрашивает `GET /api/v1/users/me`
|
||||
- **THEN** запрос через 3 с после входа получает 401
|
||||
|
||||
### Requirement: Отзыв текущей сессии
|
||||
|
||||
`DELETE /api/v1/auth/sessions/current` с действующим Bearer-токеном
|
||||
SHALL отзывать сессию этого токена и отвечать 204 без тела. Отзыв SHALL
|
||||
действовать сразу: следующий запрос с этим токеном к любому защищённому
|
||||
эндпоинту получает 401. Другие сессии того же пользователя MUST NOT
|
||||
затрагиваться. Без действующего токена эндпоинт SHALL отвечать 401 с
|
||||
`WWW-Authenticate: Bearer realm="messenger"`.
|
||||
|
||||
#### Scenario: Выход
|
||||
|
||||
- **WHEN** пользователь вызывает `DELETE /api/v1/auth/sessions/current`
|
||||
своим токеном, затем `GET /api/v1/users/me` тем же токеном
|
||||
- **THEN** первый ответ 204 без тела, второй — 401
|
||||
|
||||
#### Scenario: Повторный выход
|
||||
|
||||
- **WHEN** пользователь второй раз вызывает
|
||||
`DELETE /api/v1/auth/sessions/current` отозванным токеном
|
||||
- **THEN** ответ 401 с `WWW-Authenticate` схемы `Bearer`
|
||||
|
||||
#### Scenario: Другая сессия остаётся
|
||||
|
||||
- **WHEN** пользователь вошёл дважды и отозвал первую сессию
|
||||
- **THEN** второй токен по-прежнему получает 200
|
||||
|
||||
### Requirement: Сессии переживают рестарт
|
||||
|
||||
Сессии SHALL храниться в PostgreSQL. После перезапуска API и PostgreSQL
|
||||
с сохранённым volume действующий токен SHALL работать до своего
|
||||
`expires_at`, а отозванный — оставаться отозванным.
|
||||
|
||||
#### Scenario: Прежний токен после рестарта
|
||||
|
||||
- **WHEN** пользователь вошёл, отправил сообщение, затем выполнен
|
||||
`scripts/restart.sh`
|
||||
- **THEN** тот же токен без повторного входа получает 200 и видит своё
|
||||
сообщение
|
||||
|
||||
### Requirement: Недоступность хранилища сессий
|
||||
|
||||
Если PostgreSQL недоступен, вход и запрос с токеном SHALL получать 503
|
||||
`unavailable`. Запрос MUST NOT обрабатываться как анонимный или как
|
||||
запрос от последнего известного владельца токена, и сервис MUST NOT
|
||||
отвечать 401 вместо 503: недоступность хранилища не означает, что токен
|
||||
недействителен.
|
||||
|
||||
#### Scenario: БД остановлена при запросе с токеном
|
||||
|
||||
- **WHEN** PostgreSQL остановлен, и клиент с действующим токеном
|
||||
запрашивает `GET /api/v1/users/me`
|
||||
- **THEN** ответ 503 `unavailable`, а после возврата PostgreSQL тот же
|
||||
токен получает 200
|
||||
@@ -0,0 +1,53 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Обязательные сценарии рубрики
|
||||
|
||||
Набор SHALL содержать отдельные тесты для сценариев уровня «4»:
|
||||
неверный JSON, чужой чат, пустое сообщение, дубликат `username`, обход
|
||||
нескольких страниц истории, а с лабы 2 — неверный пароль и logout.
|
||||
|
||||
#### Scenario: Неверный JSON
|
||||
|
||||
- **WHEN** тест отправляет тело `{bad` в эндпоинт, ожидающий JSON
|
||||
- **THEN** проверяется ответ 400 с `code` `invalid_request`
|
||||
|
||||
#### Scenario: Чужой чат
|
||||
|
||||
- **WHEN** пользователь, не состоящий в чате, читает чат, читает
|
||||
историю и пишет в чат
|
||||
- **THEN** проверяется, что все три запроса получают 404 `not_found`
|
||||
|
||||
#### Scenario: Пустое сообщение
|
||||
|
||||
- **WHEN** участник отправляет сообщение с `text` пустым и из пробелов
|
||||
- **THEN** проверяется ответ 400 `invalid_request`, и сообщение не
|
||||
появляется в истории
|
||||
|
||||
#### Scenario: Дубликат username
|
||||
|
||||
- **WHEN** регистрируется `username`, который уже занят
|
||||
- **THEN** проверяется ответ 409 `conflict`
|
||||
|
||||
#### Scenario: Обход нескольких страниц
|
||||
|
||||
- **WHEN** история содержит больше сообщений, чем помещается на одну
|
||||
страницу, и тест обходит её по `next_cursor`, в том числе меняя
|
||||
`limit` между страницами
|
||||
- **THEN** проверяется, что каждое сообщение встречается ровно один раз
|
||||
в порядке `(created_at, id)`, а последняя страница имеет
|
||||
`next_cursor` null
|
||||
|
||||
#### Scenario: Неверный пароль в рубрике
|
||||
|
||||
- **WHEN** зарегистрированный пользователь входит с неверным паролем
|
||||
- **THEN** проверяется ответ 401 с `WWW-Authenticate` схемы `Basic`, и
|
||||
выданного токена в ответе нет
|
||||
|
||||
#### Scenario: Logout в рубрике
|
||||
|
||||
- **WHEN** пользователь выходит, а затем повторяет запрос прежним
|
||||
токеном
|
||||
- **THEN** проверяется ответ 204 на выход и 401 с `WWW-Authenticate`
|
||||
схемы `Bearer` на повтор
|
||||
@@ -0,0 +1,74 @@
|
||||
# Spec Delta
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Формат пароля
|
||||
|
||||
`password` SHALL содержать от 12 до 128 Unicode code points и MUST NOT
|
||||
состоять только из пробельных символов. Допустимы любые символы
|
||||
Unicode, в том числе `:`. Значение SHALL использоваться без изменений:
|
||||
без обрезки, нормализации и усечения по байтам. Иначе сервис SHALL
|
||||
отвечать 400 `invalid_request`.
|
||||
|
||||
#### Scenario: Нет пароля
|
||||
|
||||
- **WHEN** тело регистрации не содержит `password`
|
||||
- **THEN** ответ 400
|
||||
|
||||
#### Scenario: Граница длины пароля
|
||||
|
||||
- **WHEN** `password` из 11 code points, затем из 12, из 128 и из 129
|
||||
- **THEN** первый и последний запросы дают 400, остальные — 201
|
||||
|
||||
#### Scenario: Пароль из пробелов
|
||||
|
||||
- **WHEN** `password` из 12 пробелов
|
||||
- **THEN** ответ 400
|
||||
|
||||
#### Scenario: Длинный пароль в UTF-8 целиком
|
||||
|
||||
- **WHEN** пользователь зарегистрировался с паролем из 128 кириллических
|
||||
символов, затем входит с паролем, где изменён только последний символ
|
||||
- **THEN** вход отклонён 401: пароль сравнивается целиком, а не по
|
||||
первым байтам
|
||||
|
||||
### Requirement: Пароль хранится только хэшем
|
||||
|
||||
Сервис SHALL хранить пароль только как результат библиотечного password
|
||||
KDF с солью. Пароль MUST NOT храниться в открытом виде или как быстрый
|
||||
хэш (SHA-256 и подобные) и MUST NOT попадать в ответы API и журнал.
|
||||
|
||||
#### Scenario: Хэш в БД
|
||||
|
||||
- **WHEN** пользователь зарегистрирован с паролем P
|
||||
- **THEN** в его строке в PostgreSQL нет P, а хранимое значение — строка
|
||||
KDF с параметрами и солью; у двух пользователей с одинаковым паролем
|
||||
хранимые значения разные
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Регистрация пользователя
|
||||
|
||||
`POST /api/v1/users` SHALL быть публичным и принимать тело
|
||||
`{"username": ..., "display_name": ..., "password": ...}`. При успехе
|
||||
сервис SHALL отвечать 201 с объектом `User`: `id`, `username`,
|
||||
`display_name`, `created_at`, без других полей: пароля и его хэша в
|
||||
ответе нет. `id` и `created_at` назначает сервер.
|
||||
|
||||
#### Scenario: Успешная регистрация
|
||||
|
||||
- **WHEN** клиент отправляет `{"username": "alice", "display_name":
|
||||
"Алиса", "password": ...}` с допустимым паролем
|
||||
- **THEN** ответ 201, `username` и `display_name` совпадают с
|
||||
отправленными, `id` — новый UUID, полей кроме четырёх полей `User` нет
|
||||
|
||||
### Requirement: Текущий пользователь
|
||||
|
||||
`GET /api/v1/users/me` SHALL возвращать 200 с объектом `User` владельца
|
||||
сессии, чей токен передан (capability `identification`).
|
||||
|
||||
#### Scenario: Совпадает с регистрацией
|
||||
|
||||
- **WHEN** пользователь запрашивает `GET /api/v1/users/me` со своим
|
||||
токеном
|
||||
- **THEN** тело ответа равно телу ответа на его регистрацию
|
||||
@@ -0,0 +1,144 @@
|
||||
# Tasks
|
||||
|
||||
Как строить — `design.md` (дальше «решение N»), что должно получиться —
|
||||
дельты в `specs/`. Перед первым файлом слоя прочитать его правило:
|
||||
`auth.md`, `migrations.md`, `infra.md`, `repo-layer.md`,
|
||||
`service-layer.md`, `dto.md`, `api-layer.md`, `api-contract.md`,
|
||||
`settings.md`, `student-tests.md`. Evidence снимается с закоммиченного
|
||||
кода, коммит — только после подтверждения пользователя (`bench.md`,
|
||||
«Измеренное состояние — commit»).
|
||||
|
||||
## 1. Зависимость и настройки
|
||||
|
||||
- [x] 1.1 `uv add argon2-cffi` в основную группу. Проверка:
|
||||
`uv lock --check` проходит, `uv run python -c "import argon2;
|
||||
print(argon2.profiles.RFC_9106_LOW_MEMORY)"` печатает t=3,
|
||||
m=65536, p=4.
|
||||
- [x] 1.2 Секция `Auth` в `src/config/settings.py`:
|
||||
`session_ttl_seconds` и `kdf_concurrency` (решение 6), оба в
|
||||
`config_example.toml` и рабочем `config.toml`; `.env.example` и
|
||||
compose не трогаются. Проверка: `uv run python -c "from src.config
|
||||
import settings; print(settings.auth.session_ttl_seconds)"` — 3600 без
|
||||
строки в `config.toml`, 600 при `session_ttl_seconds = 600` в нём, 2
|
||||
при `AUTH__SESSION_TTL_SECONDS=2` в окружении поверх файла;
|
||||
`AUTH__SESSION_TTL_SECONDS=abc` и `0` — ошибка проверки настроек.
|
||||
|
||||
## 2. Схема
|
||||
|
||||
- [x] 2.1 Модель `Session` (`src/infra/db/models/session.py`),
|
||||
`password_hash` в `User` с `CHECK` (решение 1). Проверка:
|
||||
`Base.metadata.sorted_tables` — пять таблиц, у ограничений есть
|
||||
имена.
|
||||
- [x] 2.2 Ревизия по решению 7: очистка лабы 1 с `warning` и числом
|
||||
пользователей, колонка, таблица; `downgrade` зеркалит `upgrade`.
|
||||
Проверка: на базе с данными лабы 1 `make upgrade` пишет число
|
||||
удалённых пользователей, повторный `make upgrade` ничего не пишет и не
|
||||
удаляет; `alembic downgrade 16c279725564` и снова `upgrade head`
|
||||
проходят; `alembic check` — «No new upgrade operations detected».
|
||||
|
||||
## 3. Пароль, repo и сервисы
|
||||
|
||||
- [x] 3.1 `src/infra/password.py` (решение 3): профиль явно,
|
||||
`CapacityLimiter`, фиктивный хэш. Проверка: разовым скриптом верный
|
||||
пароль проходит, изменённый в последнем из 128 кириллических символов
|
||||
— нет; 20 одновременных хэшей при `kdf_concurrency=4` идут не больше
|
||||
чем по 4.
|
||||
- [x] 3.2 DTO (`dto.md`): `UserFullDTO` без хэша, отдельный DTO
|
||||
учётных данных для входа, `SessionDTO`, `CurrentSessionDTO`. Repo
|
||||
`user`: вставка с хэшем, учётные данные по username. Repo `session`:
|
||||
вставка, проверка токена одним `SELECT` с `JOIN` (решение 2),
|
||||
удаление по `id`. Проверка: `make lint`; `EXPLAIN` проверки токена
|
||||
идёт по уникальному индексу `token_hash`.
|
||||
- [x] 3.3 `UserService.register` с паролем (хэш до БД), без
|
||||
`identify`; `SessionService`: `login` (две транзакции, решение 3),
|
||||
`authenticate`, `revoke`; исключения `InvalidCredentials` и
|
||||
`Unauthenticated` вместо `Unidentified`; логи по спеку
|
||||
`service-logging`. Проверка: `grep -rn "Unidentified\|X-User-Id\|
|
||||
USER_ID_HEADER" src` пусто, `make lint` чистый.
|
||||
|
||||
## 4. API
|
||||
|
||||
- [x] 4.1 `dependencies.py` (решения 4, 5): разбор Basic с ранним
|
||||
отсевом, `get_current_session` на `HTTPBearer`, `get_current_user` из
|
||||
неё; `errors.py` — `WWW-Authenticate` по типу исключения. Проверка: на
|
||||
`make run_dev` `GET /api/v1/users/me` без заголовка, с Basic и с
|
||||
неизвестным Bearer — 401 с `Bearer realm="messenger"`.
|
||||
- [x] 4.2 `CreateUser` с `password` (12–128, не только пробелы,
|
||||
`StrictStr`); роутер `session.py`: `POST /auth/sessions` 201 `Session`,
|
||||
`DELETE /auth/sessions/current` 204. Проверка: `make test` против
|
||||
`make run_dev` — `PASS`.
|
||||
- [x] 4.3 Документация API: `/openapi.json` объявляет `bearerAuth` и
|
||||
`basicAuth` как контракт, без `devUser` (спек `identification`).
|
||||
Проверка: `security` у `GET /api/v1/users/me`,
|
||||
`POST /api/v1/auth/sessions` и `POST /api/v1/users` — как в сценарии
|
||||
«Схема в openapi.json»; в `/docs` вход и запрос через Authorize
|
||||
работают с паролем из ASCII.
|
||||
|
||||
## 5. Собственные тесты
|
||||
|
||||
- [x] 5.1 `api_client.py` (решение 8): токен в `Actor`, `register` с
|
||||
паролем и входом, `login`, `unregistered()` со случайным токеном, хелпер
|
||||
тела регистрации; тела регистрации в `test_users.py`, `test_race.py`,
|
||||
`test_rubric.py` — через него. Проверка: `make student_test` против
|
||||
`make run_dev` — тесты поведения лабы 1 проходят без правки
|
||||
ожиданий.
|
||||
- [x] 5.2 `test_identification.py` по дельте `identification`,
|
||||
`test_sessions.py` по `sessions`, тесты сценариев `users` («Нет
|
||||
пароля», «Граница длины пароля», «Пароль из пробелов», «Длинный
|
||||
пароль в UTF-8 целиком»), `health` («Неизвестный токен») и рубрики
|
||||
`student-tests` («Неверный пароль в рубрике», «Logout в рубрике»).
|
||||
Проверка: против `make run_dev` все проходят. Тесты отказов (401)
|
||||
проверены на ложную зелень: временная поломка в
|
||||
`SessionService.authenticate` (принять любой токен) роняет их, после
|
||||
отката правки они снова зелёные.
|
||||
- [x] 5.3 `/opsx:sync` и в том же шаге `spec_coverage.py`: `sessions` —
|
||||
в список отслеживаемых capability; исключения для сценариев, которые
|
||||
не проверить на обычном стенде: «Истёкший токен», «Срок не
|
||||
продлевается», «Прежний токен после рестарта», «БД остановлена при
|
||||
запросе с токеном», «Токена нет в хранилище» (`sessions`), «Хэш в БД»
|
||||
(`users`) — со ссылкой на evidence и `failure-checks`; текст
|
||||
исключения «Прежний пользователь после рестарта» — про токен;
|
||||
«Кнопка Authorize в Swagger» — про `bearerAuth` и `basicAuth` вместо
|
||||
`devUser`. Спеки `service-configuration`, `container-run` и
|
||||
`db-migrations` проверяются evidence, в сверку не входят. Purpose
|
||||
основного спека `identification` переписать руками: в нём «с лабы 2
|
||||
её заменяет Bearer». Проверка: `make student_test` — все тесты
|
||||
прошли, в том числе `test_coverage.py`; `openspec validate --specs`
|
||||
без ошибок.
|
||||
|
||||
## 6. Инструменты и документы
|
||||
|
||||
- [ ] 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`,
|
||||
smoke `PASS`, student — все прошли.
|
||||
- [x] 6.2 `auth.md` — выбранные решения (сессии в PostgreSQL, отзыв
|
||||
удалением, лимит KDF, `HTTPBase` для `basicAuth`); `AGENTS.md` —
|
||||
«Переходное состояние» без пунктов про `X-User-Id`, `devUser`,
|
||||
`identification`/`users` и закрытых сценариев `session-auth`, карта
|
||||
кода (`session.py` во всех слоях, `infra/password.py`). Проверка:
|
||||
`grep -rn "X-User-Id" AGENTS.md .claude` — только история лабы 1 и
|
||||
правило, что он игнорируется.
|
||||
- [x] 6.3 Финальная проверка кода: `make lint`, `make check`,
|
||||
`openspec validate session-auth --strict`, `make test_isolated` —
|
||||
код 0. Затем показать изменения, предложить сообщение и после
|
||||
подтверждения пользователя закоммитить.
|
||||
|
||||
## 7. Evidence и отчёт
|
||||
|
||||
- [ ] 7.1 Evidence по таблице решения 9 с закоммиченного кода. Проверка:
|
||||
в каждом файле дата, commit, стенд; паролей, токенов и
|
||||
`Authorization` в файлах нет; `drop-lab1-data.md` снят на рабочей
|
||||
базе до её очистки.
|
||||
- [ ] 7.2 `REPORT.md`: Argon2id и его параметры, сессии и их хранение,
|
||||
`SESSION_TTL_SECONDS` и `SESSION_STORE=postgres` в таблице
|
||||
соответствия, сценарий защиты (миграции → вход → сообщение →
|
||||
`make test-persistence` → logout), строки доказательств уровня «3» и
|
||||
logout/неверного пароля уровня «4» со ссылками на evidence,
|
||||
предупреждение об очистке данных лабы 1, удаление закрытых TODO.
|
||||
Проверка: у каждой строки таблицы доказательств есть команда,
|
||||
наблюдение и файл.
|
||||
- [ ] 7.3 `make lint`, `make check`, `openspec validate session-auth
|
||||
--strict`, `graphify update .`; показать изменения и после
|
||||
подтверждения пользователя закоммитить evidence и отчёт.
|
||||
Reference in New Issue
Block a user