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>
This commit is contained in:
2026-10-16 12:58:30 +03:00
co-authored by Claude Opus 5.5
parent c5d5a1ab25
commit 628b5f2278
9 changed files with 86 additions and 23 deletions
+17
View File
@@ -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: сравнение кортежей
@@ -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`;
+2 -4
View File
@@ -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)
+3 -4
View File
@@ -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:
+2 -1
View File
@@ -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",
]
+2 -2
View File
@@ -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,
)
+27 -2
View File
@@ -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,
+7
View File
@@ -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}$"
+20 -4
View File
@@ -4,6 +4,11 @@
`{"v": 1, "s": <область>, "t": <created_at>, "i": <id>}`. Область
привязывает курсор к конкретному списку: курсор чужого чата или списка
чатов другого пользователя не разбирается.
Принимается только та запись, которую выдал сервер: после разбора курсор
собирается заново и сравнивается с полученной строкой. Так изменённый
клиентом курсор (`"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