Propose non-ASCII Basic rejection as an openspec change

This commit is contained in:
Artyom
2026-11-06 02:17:03 +03:00
parent d60e29221a
commit f7bfd1d473
5 changed files with 107 additions and 0 deletions
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-06
@@ -0,0 +1,22 @@
## Context
См. `proposal.md`. HTTP-заголовки преобразуются из байтов через Latin-1; `b64decode` принимает строку только из ASCII. Context7 `/python/cpython` подтверждает это ограничение; существующий Python 3.14.5 воспроизводит ValueError на `Basic \xff` до VerifyCredentials.
## Goals / Non-Goals
Получать стандартный отказ до проверки credentials. Сохранить строгий Base64, UTF-8 пароля, первое двоеточие как разделитель и прежнюю проверку username. Схема заголовка остаётся регистронезависимой.
## Decisions
1. HTTP-граница identity проверяет `encoded.isascii()` вместе со схемой. Явная проверка выражает ограничение входа и не требует расширять перехват исключений на весь ValueError. Она выполняется до `strip`, чтобы парсер не принимал не-ASCII пробел как часть Base64. Общая нормализация HTTP-заголовков не меняется.
2. Guard и RequestPipeline сохраняют существующий путь `401 unauthorized` с Basic challenge, телом ошибки и обоими X-заголовками. Проверки используют байтовые заголовки и подставной VerifyCredentials, подтверждая отсутствие его вызова. Полный HTTP-тест сравнивает ответ с неверным паролем и передаётся финальному агенту.
3. Новых портов и зависимостей между зонами нет. UserDirectory, IdentityUnitOfWork, PostgreSQL-адаптеры, Valkey и сборка DI прежние. shared, SQL, миграции и инфраструктура не требуют изменений.
## Risks / Trade-offs
- Offline ASGI-вызов не проверяет HAProxy/Uvicorn и реальную БД → отдельный обязательный прогон через LB и интеграционные тесты перечисляются в evidence.
- Проверка ASCII могла бы ошибочно запретить Unicode-пароль → существующая регрессия UTF-8 пароля остаётся в unit-наборе; ограничивается только Base64-представление.
## Migration Plan
Замена кода без миграции данных. Прежние измерения сохраняют свой SHA, динамические результаты новой версии не заявляются. Откат коммита возвращает прежний дефект.
@@ -0,0 +1,27 @@
## Why
Ревью snapshot `d60e29221a553c62ee5dc27615c17fdaa6d27895` выявило необработанный ValueError при `Authorization: Basic` с не-ASCII байтами. Offline-вызовы парсера и guard подтвердили исключение вместо контрактного одинакового `401`.
## What Changes
- Проверять ASCII закодированной части Basic перед декодированием Base64.
- Добавить регрессии для не-ASCII заголовков, стандартного отказа и отсутствия вызова VerifyCredentials.
- Подготовить HTTP-регрессию для финального агента и сохранить offline-доказательства отдельно от нагрузочных результатов.
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `lab2-auth-sessions`: не-ASCII в закодированной части Basic получает одинаковый `401 unauthorized` с Basic challenge.
## Impact
Уровень «3»: сохранение минимума lab2 из `README.md`, раздел «Идентификация и сессии» `contracts/README.md`, строка «Негативные случаи и заголовки, гонки, миграции» в `REPORT.md`. Затронуты только HTTP-граница identity, собственные тесты, OpenSpec и evidence. Динамические проверки выполняет финальный агент; этот этап использует существующее окружение и offline-проверки.
## Non-goals
Возможности лаб 4–7 из Out of scope в `openspec/config.yaml`, изменение SQLAlchemy/Alembic, инфраструктуры, зависимостей, нормативных файлов, итогового отчёта и публикация.
@@ -0,0 +1,46 @@
## MODIFIED Requirements
### Requirement: Вход по Basic выдаёт сессию
Сервис SHALL принимать `POST /api/v1/auth/sessions` только с заголовком `Authorization: Basic <base64(username:password)>` и без тела. Декодирование base64 SHALL быть строгим, разделителем SHALL служить первое двоеточие, пароль SHALL декодироваться как UTF-8. При верных учётных данных ответ SHALL быть `201` с телом `{"token","token_type":"Bearer","expires_at","user"}`, где `token` — непрозрачная случайная строка не короче 32 символов с энтропией не менее 256 бит, `expires_at` — RFC 3339 UTC с `Z`, а `user` совпадает с ответом регистрации. Неверный пароль, неизвестный `username`, отсутствующий и испорченный заголовок SHALL давать одинаковый `401` с кодом `unauthorized` и заголовком `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`.
В соответствии с разделом «Идентификация и сессии» `contracts/README.md`, NUL в Basic username и не-ASCII символы в закодированной части Basic SHALL приводить к тому же `401 unauthorized`.
#### Scenario: Успешный вход
- **WHEN** зарегистрированный пользователь отправляет верные `username:password` в `Basic`
- **THEN** ответ `201`, тело соответствует схеме `Session`, `token_type` равен `Bearer`
- **AND** `user` побайтно равен телу ответа его регистрации, `expires_at` в будущем
#### Scenario: Неверный пароль и неизвестный пользователь неразличимы
- **WHEN** приходит `Basic` с неверным паролем существующего пользователя или с несуществующим `username`
- **THEN** оба ответа — `401` с кодом `unauthorized` и `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`
- **AND** тела ответов различаются только `request_id`
#### Scenario: Испорченный заголовок Basic
- **WHEN** заголовок отсутствует, содержит другую схему, невалидный base64 или строку без двоеточия
- **THEN** ответ `401` с тем же заголовком `WWW-Authenticate: Basic ...`
#### Scenario: Двоеточие в пароле
- **WHEN** пароль пользователя содержит двоеточие и он входит по `Basic`
- **THEN** ответ `201`: разделителем служит первое двоеточие
#### Scenario: Тело запроса при входе
- **WHEN** запрос с верным `Basic` содержит тело
- **THEN** ответ `400` с кодом `invalid_request`, сессия не создаётся
#### Scenario: Username с NUL
- **WHEN** в `POST /api/v1/auth/sessions` передан корректный Base64 от username с NUL и пароля
- **THEN** ответ `401` с `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`; тело `{"error":{"code":"unauthorized","message":...,"request_id":...}}` совпадает с ошибкой неверного пароля, кроме `request_id`
- **AND** ответ содержит непустые `X-Instance-Id` и `X-Request-Id`, совпадающий с `error.request_id`
#### Scenario: Не-ASCII в закодированной части Basic
- **WHEN** `POST /api/v1/auth/sessions` получает `Authorization` с не-ASCII байтами после `Basic `, в том числе `0xff`
- **THEN** ответ `401` с `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`; тело `{"error":{"code":"unauthorized","message":...,"request_id":...}}` совпадает с ошибкой неверного пароля, кроме `request_id`
- **AND** ответ содержит непустой `X-Instance-Id` и `X-Request-Id`, совпадающий с `error.request_id`; сессия не создаётся
@@ -0,0 +1,10 @@
## 1. Identity — минимум уровня «3»
- [ ] 1.1 Добавить offline-регрессии не-ASCII Basic для парсера и ASGI-конвейера; сохранить ожидаемые падения старого кода.
- [ ] 1.2 Отклонять не-ASCII до декодирования Base64; проверить стандартный 401, заголовки, тело и отсутствие вызова VerifyCredentials через unit-тесты.
## 2. Проверки и передача
- [ ] 2.1 Добавить HTTP-регрессию одинакового 401 с неверным паролем и отсутствия новой сессии; собрать её через pytest --collect-only без Docker.
- [ ] 2.2 Выполнить offline unit-тесты, make check, make validate, make lint и OpenSpec strict; сохранить evidence с SHA и командами.
- [ ] 2.3 Перечислить обязательные динамические проверки финального агента в evidence, синхронизировать спецификацию и архивировать change.