Files
mtusi2026lab3/openspec/changes/strict-id-validation/tasks.md
T
ricoromaandClaude Opus 5.5 628b5f2278 fix: reject tampered cursors and non-canonical UUIDs
decode_cursor checked only for KeyError, TypeError and ValueError, so a
server-issued cursor whose item id was replaced with [], {}, 123 or
false crashed UUID() with AttributeError and answered 500. It now checks
the types of "t" and "i" before parsing and accepts only the exact
string the server would issue for the parsed key: re-encoding must give
the received cursor, so v=true, an extra field or the id in another
notation is a 400 instead of a page.

pydantic's UUID also accepts ids without hyphens, with the urn:uuid:
prefix and in braces, wider than the contract's format: uuid. chat_id in
the path of the three chat endpoints and member_ids elements now use
UuidIn, which requires the 8-4-4-4-12 form in any case. Response models
and the OpenAPI schema are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 12:58:30 +03:00

12 KiB
Raw Blame History

Tasks

Как строить — design.md (дальше «решение N»). Что должно получиться — дельты specs/api-conventions, specs/pagination, specs/chats.

Правила.

  • Правила слоёв. Перед первым файлом слоя — Read его правила и одного файла из каталога, чтобы правило подгрузилось:

    Что правим Правила
    student-tests/ student-tests.md, api-contract.md
    src/api/schemas/ dto.md, api-contract.md
    src/api/routers/ api-layer.md, api-contract.md
    src/utils/ api-contract.md (пагинация), service-layer.md (курсор)
  • Только Edit и Write. Файлы меняются только ими. Перед правкой — Read файла. Для проверок uv run python -c … запускать можно.

  • Коммиты — только после подтверждения пользователя: показать изменения, предложить сообщение (английский, conventional style, последняя строка Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>), ждать ок. Push, checkout, reset, stash — нельзя.

  • Упавший тест или прогон — сначала разбор и названная причина, потом правка (AGENTS.md). Тест не ослабляется под ответ.

  • Прогоны по одному. make test_isolated и make failure_checks не запускать параллельно друг с другом и с другой сессией (student-tests.md).

1. Подготовка

  • 1.1 Прочитать правила из таблицы и по одному файлу каждого слоя: student-tests/test_pagination.py, src/api/schemas/common.py, src/api/routers/v1/chat.py, src/utils/cursor.py. Проверка: правила слоёв подгрузились.
  • 1.2 openspec validate strict-id-validation --strict — без ошибок.

2. Тесты на текущем коде (решения 4 и 5)

  • 2.1 test_pagination.py, сценарий pagination «Изменённый курсор»:

    • хелпер подмены одного поля выданного курсора; кодирует так же, как сервер (компактный JSON, base64url без =);
    • в хелпере — утверждение, что без изменений он возвращает ту же строку;
    • фикстура на оба списка: история (два сообщения, limit=1) и список чатов (два чата, limit=1);
    • варианты:
      • "i" = [], {}, 123, false;
      • тот же id без дефисов и в верхнем регистре;
      • "v": true;
      • лишнее поле;
    • контроль: перекодированный без изменений курсор даёт 200.

    Проверка: uv run pytest student-tests/test_pagination.py --collect-only -q показывает тест для обоих списков.

  • 2.2 test_chats.py, сценарии chats:

    • «Участник в верхнем регистре» — 201, member_ids в нижнем регистре равен [alice.id, bob.id], Боб видит чат;
    • «Повтор участника в другом регистре» — 400, чат не создан;
    • «member_ids не массив» — {}, 123, false, строка с id Алисы → 400, чат не создан (listed_titles).

    Проверка: тесты собираются, маркеры дословно совпадают со сценариями дельты.

  • 2.3 test_api_conventions.py, сценарии api-conventions:

    • «UUID другого типа в теле» — member_ids = [alice.id, X], где X — [], {}, 123, false; 400, чат не создан;
    • «Не UUID в пути» — chat_id = 123, false, [], {} (через urllib.parse.quote(…, safe="")) у GET чата, GET истории и POST сообщения с ключом; 400;
    • «Другая запись UUID»:
      • id своего чата без дефисов, с urn:uuid: и в {…} на тех же трёх ручках — 400, история не изменилась;
      • id Боба в тех же записях в member_ids — 400, чат не создан;
    • «UUID в верхнем регистре в пути» — ответы трёх ручек равны ответам на нижний регистр, id и chat_id в нижнем регистре.

    Проверка: тесты собираются.

  • 2.4 Синхронизировать дельты в основные спеки (/opsx:sync): сверка покрытия читает только openspec/specs/, и без этого маркеры новых сценариев — ссылка на неизвестный сценарий. Проверка:

    • openspec validate --specs без ошибок;
    • в основных спеках есть новые сценарии.
  • 2.5 make lint, затем commit тестов и синхронизированных спеков (после подтверждения; сообщение вроде test: cover tampered cursors and UUID input forms). Проверка: git status чист.

  • 2.6 Красный прогон на этом commit: make test_isolated. Ожидание (решение 5):

    • красные: «Изменённый курсор» на обоих списках (500 у "i" не того типа, 200 у остальных подмен), «Другая запись UUID» (200 / 201);
    • зелёные — все остальные новые тесты и test_coverage.py.

    Расхождение с ожиданием — разбор (AGENTS.md). Если красный тест типов — это дефект, чинить в разделе 3. Вывод с commit, числом тестов и причинами падений — в журнал этапа для 5.1.

3. Исправление (решения 1–2)

  • 3.1 UUID_PATTERN (8-4-4-4-12, шестнадцатеричные цифры в любом регистре) в src/utils/constants.py. В src/api/schemas/common.py — тип UUID входа: Annotated[UUID, BeforeValidator(...)] с re.fullmatch; не-строку пропускает дальше. Проверка: uv run python -c с TypeAdapter:

    • канон в обоих регистрах принимается;
    • запись без дефисов, urn:uuid:, {…}, пробел, \n в конце, [], {}, 123, false, null — ошибка валидации.
  • 3.2 Тип UUID входа у member_ids (src/api/schemas/chat.py) и у chat_id трёх ручек (src/api/routers/v1/chat.py, message.py). Модели ответов не меняются. Проверка: make run_dev, в /openapi.json у chat_id по-прежнему {"type": "string", "format": "uuid"}.

  • 3.3 decode_cursor (src/utils/cursor.py):

    • t и i — строки;
    • except только ValueError;
    • обратная сборка через encode_cursor и сравнение со входом;
    • докстринг модуля и функции — под новое правило.

    Проверка: uv run python -c — на всех вариантах 2.1 и на garbage, eyJ4IjoxfQ, !!! только CursorError, другого исключения нет; на выданном курсоре — тот же ключ.

  • 3.4 make lint, make test_isolated — все тесты зелёные, 4 теста реплик пропущены с причиной «one API process». Вывод — в журнал этапа.

  • 3.5 Правило .claude/rules/api-contract.md:

    • «Валидация → 400»: pydantic принимает UUID шире format: uuid; вход с UUID (путь и тело) — только через тип UUID входа из common.py, ответы — UUID;
    • «Пагинация (keyset)»: курсор принимается только в записи сервера (обратная сборка).

    Проверка: названные в правиле файлы и тип существуют.

  • 3.6 Commit исправления и правила (после подтверждения; сообщение вроде fix: reject tampered cursors and non-canonical UUIDs). Проверка: git status чист.

4. Стенд и регрессия (решение 6)

  • 4.1 make replicas, затем make rolling_update. Проверка: make lb_stats — оба слота UP на новом образе, make instances — instances: 2.
  • 4.2 make test и make student_test через LB. Проверка:
    • PASS и все тесты прошли, включая тесты реплик;
    • в журнале реплик за время прогона нет ответов 500 (make logs, access-лог, поле статуса).
  • 4.3 make failure_checks. Проверка: все проверки отказов прошли, сводка журнала PostgreSQL стенда без признаков аварии, стенд отказов удалён.
  • 4.4 Чистый clone во временном проекте compose на нестандартных портах, по процедуре evidence/replicas/clean-clone-ports.md: git clone commit 3.6, make run_docker, make test, make student_test через LB клона, затем down -v клона. Проверка: всё код 0, рабочий стенд mtusi-lab3 не тронут.
  • 4.5 Спросить пользователя о полной проверке из чистого clone на портах по умолчанию (evidence/tests/clean-clone-final.md): она удаляет рабочий стенд с volume. Без согласия — не делать и записать в 5.1, что не делалась.

5. Документы

  • 5.1 evidence/tests/strict-id-validation-checks.md:

    • красный прогон 2.6 и зелёный 3.4 — commit, число тестов, причины падений;
    • 4.1–4.4 и решение по 4.5.

    Только обезличенные выводы, без токенов и паролей (evidence/README.md).

  • 5.2 REPORT.md:

    • строка в таблице доказательств: строгий вход с UUID и курсор, red → green, ссылка на 5.1;
    • расхождение с прежним поведением: запись UUID без дефисов, urn:uuid: и {…} → 400;
    • число тестов там, где отчёт говорит о текущем коде.

    Проверка: Read раздела после правки; числа совпадают с 4.2 и 3.4.

  • 5.3 AGENTS.md:

    • абзац о состоянии лабы: change strict-id-validation;
    • карта кода: тип UUID входа в common.py, обратная сборка в cursor.py.

    Проверка: Read абзаца и карты.

  • 5.4 graphify update . — граф собран без ошибок.

  • 5.5 Commit документов (после подтверждения; сообщение вроде docs: record strict-id-validation checks). Проверка: git status чист.

6. Завершение

  • 6.1 /opsx:verify strict-id-validation. Найденное исправить новым commit с повтором затронутых проверок.
  • 6.2 /opsx:archive strict-id-validation после ок пользователя. Проверка: change в openspec/changes/archive/, активных changes нет.