From 628b5f2278d22c0a13b2ba8e33b57b5d2f284efe Mon Sep 17 00:00:00 2001 From: roman Date: Fri, 16 Oct 2026 12:58:30 +0300 Subject: [PATCH] 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 --- .claude/rules/api-contract.md | 17 +++++++++++ .../changes/strict-id-validation/tasks.md | 12 ++++---- src/api/routers/v1/chat.py | 6 ++-- src/api/routers/v1/message.py | 7 ++--- src/api/schemas/__init__.py | 3 +- src/api/schemas/chat.py | 4 +-- src/api/schemas/common.py | 29 +++++++++++++++++-- src/utils/constants.py | 7 +++++ src/utils/cursor.py | 24 ++++++++++++--- 9 files changed, 86 insertions(+), 23 deletions(-) diff --git a/.claude/rules/api-contract.md b/.claude/rules/api-contract.md index 1c388eb8..d55f28b3 100644 --- a/.claude/rules/api-contract.md +++ b/.claude/rules/api-contract.md @@ -120,6 +120,16 @@ FastAPI 0.141 из `uv.lock`: `limit=0` и нечисловой → 400. Битый `cursor` → 400. - `member_ids`: 1–100 элементов, без дубликатов, все пользователи существуют, вызывающий в списке. Иначе 400. +- UUID на входе — только запись 8-4-4-4-12 (`format: uuid`), цифры в + любом регистре (спек `api-conventions`, «UUID на входе»). `UUID` + pydantic шире контракта: принимает запись без дефисов, с `urn:uuid:` и + в `{…}` (проверено на pydantic 2.13). Поэтому всё, что UUID передаёт + клиент, — `chat_id` в пути и элементы `member_ids`, с лабы 4 и + `attachment_ids`, — объявляется типом `UuidIn` из + `src/api/schemas/common.py` (`BeforeValidator` с `UUID_PATTERN` и + `re.fullmatch`), а не голым `UUID`. Модели ответов — обычный `UUID`. + Не-строку `UuidIn` отдаёт валидатору `UUID`, и `[]`, `{}`, `123`, + `false` дают 400 по типу. ## Аутентификация и сессии (лаба 2) @@ -162,6 +172,13 @@ FastAPI 0.141 из `uv.lock`: или пользователя, битая base64 или JSON → 400. Последний элемент предыдущей страницы не повторяется. `limit` между страницами можно менять. +- Курсор принимается только в записи, которую выдал сервер: + `decode_cursor` после разбора собирает его заново (`encode_cursor`) и + сравнивает со входом. Изменённый курсор — `"i"` не строка, тот же id в + другой записи, `"v": true`, лишнее поле — 400, а не 500 и не страница + (спек `pagination`, «Изменённый курсор»). Значения курсора до + `UUID()` и `strptime` проверяются на тип: `UUID()` на не-строке роняет + `AttributeError`, а не `ValueError` (change `strict-id-validation`). - Семантику при конкурентных вставках и ограничения часов описать в `REPORT.md` (например: `created_at` монотонен внутри чата). - В Postgres порядок и курсор задаёт SQL: сравнение кортежей diff --git a/openspec/changes/strict-id-validation/tasks.md b/openspec/changes/strict-id-validation/tasks.md index 84579726..eee7d580 100644 --- a/openspec/changes/strict-id-validation/tasks.md +++ b/openspec/changes/strict-id-validation/tasks.md @@ -87,7 +87,7 @@ - [x] 2.5 `make lint`, затем commit тестов и синхронизированных спеков (после подтверждения; сообщение вроде `test: cover tampered cursors and UUID input forms`). Проверка: `git status` чист. -- [ ] 2.6 Красный прогон на этом commit: `make test_isolated`. Ожидание +- [x] 2.6 Красный прогон на этом commit: `make test_isolated`. Ожидание (решение 5): - красные: «Изменённый курсор» на обоих списках (500 у `"i"` не того типа, 200 у остальных подмен), «Другая запись UUID» (200 / 201); @@ -99,7 +99,7 @@ ## 3. Исправление (решения 1–2) -- [ ] 3.1 `UUID_PATTERN` (8-4-4-4-12, шестнадцатеричные цифры в любом +- [x] 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 @@ -107,12 +107,12 @@ - канон в обоих регистрах принимается; - запись без дефисов, `urn:uuid:`, `{…}`, пробел, `\n` в конце, `[]`, `{}`, `123`, `false`, `null` — ошибка валидации. -- [ ] 3.2 Тип UUID входа у `member_ids` (`src/api/schemas/chat.py`) и у +- [x] 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`): +- [x] 3.3 `decode_cursor` (`src/utils/cursor.py`): - `t` и `i` — строки; - `except` только `ValueError`; - обратная сборка через `encode_cursor` и сравнение со входом; @@ -121,10 +121,10 @@ Проверка: `uv run python -c` — на всех вариантах 2.1 и на `garbage`, `eyJ4IjoxfQ`, `!!!` только `CursorError`, другого исключения нет; на выданном курсоре — тот же ключ. -- [ ] 3.4 `make lint`, `make test_isolated` — все тесты зелёные, 4 теста +- [x] 3.4 `make lint`, `make test_isolated` — все тесты зелёные, 4 теста реплик пропущены с причиной «one API process». Вывод — в журнал этапа. -- [ ] 3.5 Правило `.claude/rules/api-contract.md`: +- [x] 3.5 Правило `.claude/rules/api-contract.md`: - «Валидация → 400»: pydantic принимает UUID шире `format: uuid`; вход с UUID (путь и тело) — только через тип UUID входа из `common.py`, ответы — `UUID`; diff --git a/src/api/routers/v1/chat.py b/src/api/routers/v1/chat.py index 45bc8f34..335c460f 100644 --- a/src/api/routers/v1/chat.py +++ b/src/api/routers/v1/chat.py @@ -1,9 +1,7 @@ -from uuid import UUID - from fastapi import APIRouter from src.api.dependencies import ChatServiceDep, CurrentUser, PageQueryDep -from src.api.schemas import Chat, ChatPage, CreateChat +from src.api.schemas import Chat, ChatPage, CreateChat, UuidIn router = APIRouter(prefix="/chats", tags=["chats"]) @@ -39,7 +37,7 @@ async def list_chats( @router.get("/{chat_id}", response_model=Chat) async def get_chat( user: CurrentUser, - chat_id: UUID, + chat_id: UuidIn, chats: ChatServiceDep, ) -> Chat: chat = await chats.get_chat_for_member(chat_id=chat_id, user_id=user.id) diff --git a/src/api/routers/v1/message.py b/src/api/routers/v1/message.py index 069235dd..4ebf3a44 100644 --- a/src/api/routers/v1/message.py +++ b/src/api/routers/v1/message.py @@ -1,10 +1,9 @@ from typing import Annotated -from uuid import UUID from fastapi import APIRouter, Header from src.api.dependencies import CurrentUser, MessageServiceDep, PageQueryDep -from src.api.schemas import CreateMessage, Message, MessagePage +from src.api.schemas import CreateMessage, Message, MessagePage, UuidIn from src.utils.constants import ( IDEMPOTENCY_KEY_HEADER, IDEMPOTENCY_KEY_MAX_LENGTH, @@ -31,7 +30,7 @@ IdempotencyKeyHeader = Annotated[ @router.post("", status_code=201, response_model=Message) async def send_message( user: CurrentUser, - chat_id: UUID, + chat_id: UuidIn, body: CreateMessage, idempotency_key: IdempotencyKeyHeader, messages: MessageServiceDep, @@ -49,7 +48,7 @@ async def send_message( @router.get("", response_model=MessagePage) async def list_messages( user: CurrentUser, - chat_id: UUID, + chat_id: UuidIn, page: PageQueryDep, messages: MessageServiceDep, ) -> MessagePage: diff --git a/src/api/schemas/__init__.py b/src/api/schemas/__init__.py index cec9a6e1..fe1a3616 100644 --- a/src/api/schemas/__init__.py +++ b/src/api/schemas/__init__.py @@ -1,5 +1,5 @@ from .chat import Chat, ChatPage, CreateChat -from .common import Error, ErrorBody, ErrorCode, Health +from .common import Error, ErrorBody, ErrorCode, Health, UuidIn from .message import CreateMessage, Message, MessagePage from .session import Session from .user import CreateUser, User @@ -18,4 +18,5 @@ __all__ = [ "MessagePage", "Session", "User", + "UuidIn", ] diff --git a/src/api/schemas/chat.py b/src/api/schemas/chat.py index 33f3f265..db34bcf6 100644 --- a/src/api/schemas/chat.py +++ b/src/api/schemas/chat.py @@ -2,7 +2,7 @@ from uuid import UUID from pydantic import BaseModel, ConfigDict, Field -from src.api.schemas.common import NonBlankStr, UtcDatetime +from src.api.schemas.common import NonBlankStr, UtcDatetime, UuidIn from src.utils.constants import ( CHAT_MEMBERS_MAX, CHAT_MEMBERS_MIN, @@ -20,7 +20,7 @@ class CreateChat(BaseModel): ) # только форма; повторы, существование и вызывающего в списке # проверяет ChatService.create_chat - member_ids: list[UUID] = Field( + member_ids: list[UuidIn] = Field( min_length=CHAT_MEMBERS_MIN, max_length=CHAT_MEMBERS_MAX, ) diff --git a/src/api/schemas/common.py b/src/api/schemas/common.py index 8cf3c5b7..050894a5 100644 --- a/src/api/schemas/common.py +++ b/src/api/schemas/common.py @@ -1,11 +1,20 @@ -"""Общие типы HTTP-моделей: строки, время, ошибки, health.""" +"""Общие типы HTTP-моделей: строки, UUID входа, время, ошибки, health.""" +import re from datetime import datetime from enum import StrEnum from typing import Annotated, Literal +from uuid import UUID -from pydantic import AfterValidator, BaseModel, PlainSerializer, StrictStr +from pydantic import ( + AfterValidator, + BaseModel, + BeforeValidator, + PlainSerializer, + StrictStr, +) +from src.utils.constants import UUID_PATTERN from src.utils.utc import to_rfc3339 @@ -16,9 +25,25 @@ def _reject_blank(value: str) -> str: return value +def _require_uuid_form(value: object) -> object: + """Строка UUID — только в записи 8-4-4-4-12; не-строку разбирает `UUID`. + + pydantic принимает и запись без дефисов, с `urn:uuid:` и в `{…}`, а + контракт — только `format: uuid`. Тип не-строки (массив, число, bool) + отвергает сам валидатор `UUID`. + """ + if isinstance(value, str) and not re.fullmatch(UUID_PATTERN, value): + raise ValueError("must be a UUID in 8-4-4-4-12 form") + return value + + # строгая строка: число не превращается в строку; пробелы не принимаются NonBlankStr = Annotated[StrictStr, AfterValidator(_reject_blank)] +# UUID, который передаёт клиент (путь и тело): запись контракта, цифры в +# любом регистре. Модели ответов — обычный `UUID` +UuidIn = Annotated[UUID, BeforeValidator(_require_uuid_form)] + # время в ответе: RFC 3339 UTC, всегда шесть знаков микросекунд и Z UtcDatetime = Annotated[ datetime, diff --git a/src/utils/constants.py b/src/utils/constants.py index 92d89d2a..620aa8b4 100644 --- a/src/utils/constants.py +++ b/src/utils/constants.py @@ -15,6 +15,13 @@ REQUEST_ID_HEADER = "X-Request-Id" INSTANCE_ID_HEADER = "X-Instance-Id" IDEMPOTENCY_KEY_HEADER = "Idempotency-Key" +# идентификатор на входе: запись 8-4-4-4-12 (`format: uuid` контракта), +# шестнадцатеричные цифры в любом регистре +UUID_PATTERN = ( + r"^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}" + r"-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" +) + # экземпляр API: значение X-Instance-Id безопасно для заголовка и журнала INSTANCE_ID_PATTERN = r"^[A-Za-z0-9._-]{1,64}$" diff --git a/src/utils/cursor.py b/src/utils/cursor.py index d1cd2a29..1150c4ba 100644 --- a/src/utils/cursor.py +++ b/src/utils/cursor.py @@ -4,6 +4,11 @@ `{"v": 1, "s": <область>, "t": , "i": }`. Область привязывает курсор к конкретному списку: курсор чужого чата или списка чатов другого пользователя не разбирается. + +Принимается только та запись, которую выдал сервер: после разбора курсор +собирается заново и сравнивается с полученной строкой. Так изменённый +клиентом курсор (`"v": true`, лишнее поле, id или время в другой записи) +— ошибка, а не страница. """ import base64 @@ -47,8 +52,9 @@ def encode_cursor(*, scope: str, created_at: datetime, item_id: UUID) -> str: def decode_cursor(cursor: str, *, scope: str) -> CursorKey: """Ключ последнего элемента предыдущей страницы. - Бросает `CursorError`, если курсор не разбирается, другой версии или - выдан для другой области. + Бросает `CursorError`, если курсор не разбирается, другой версии, + выдан для другой области или отличается от записи, которую выдал бы + `encode_cursor` для того же ключа. """ try: padded = cursor + "=" * (-len(cursor) % 4) @@ -63,7 +69,17 @@ def decode_cursor(cursor: str, *, scope: str) -> CursorKey: if payload.get("s") != scope: raise CursorError("cursor belongs to another list") + raw_time, raw_id = payload.get("t"), payload.get("i") + # не-строку UUID() не отвергает, а роняет AttributeError + if not isinstance(raw_time, str) or not isinstance(raw_id, str): + raise CursorError("malformed cursor") try: - return from_rfc3339(payload["t"]), UUID(payload["i"]) - except (KeyError, TypeError, ValueError) as e: + created_at = from_rfc3339(raw_time) + item_id = UUID(raw_id) + except ValueError as e: raise CursorError("malformed cursor") from e + + issued = encode_cursor(scope=scope, created_at=created_at, item_id=item_id) + if issued != cursor: + raise CursorError("cursor was changed") + return created_at, item_id