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. `limit=0` и нечисловой → 400. Битый `cursor` → 400.
- `member_ids`: 1–100 элементов, без дубликатов, все пользователи - `member_ids`: 1–100 элементов, без дубликатов, все пользователи
существуют, вызывающий в списке. Иначе 400. существуют, вызывающий в списке. Иначе 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) ## Аутентификация и сессии (лаба 2)
@@ -162,6 +172,13 @@ FastAPI 0.141 из `uv.lock`:
или пользователя, битая base64 или JSON → 400. Последний элемент или пользователя, битая base64 или JSON → 400. Последний элемент
предыдущей страницы не повторяется. `limit` между страницами можно предыдущей страницы не повторяется. `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` монотонен внутри чата). `REPORT.md` (например: `created_at` монотонен внутри чата).
- В Postgres порядок и курсор задаёт SQL: сравнение кортежей - В Postgres порядок и курсор задаёт SQL: сравнение кортежей
@@ -87,7 +87,7 @@
- [x] 2.5 `make lint`, затем commit тестов и синхронизированных спеков - [x] 2.5 `make lint`, затем commit тестов и синхронизированных спеков
(после подтверждения; сообщение вроде `test: cover tampered cursors (после подтверждения; сообщение вроде `test: cover tampered cursors
and UUID input forms`). Проверка: `git status` чист. and UUID input forms`). Проверка: `git status` чист.
- [ ] 2.6 Красный прогон на этом commit: `make test_isolated`. Ожидание - [x] 2.6 Красный прогон на этом commit: `make test_isolated`. Ожидание
(решение 5): (решение 5):
- красные: «Изменённый курсор» на обоих списках (500 у `"i"` не того - красные: «Изменённый курсор» на обоих списках (500 у `"i"` не того
типа, 200 у остальных подмен), «Другая запись UUID» (200 / 201); типа, 200 у остальных подмен), «Другая запись UUID» (200 / 201);
@@ -99,7 +99,7 @@
## 3. Исправление (решения 1–2) ## 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` — регистре) в `src/utils/constants.py`. В `src/api/schemas/common.py` —
тип UUID входа: `Annotated[UUID, BeforeValidator(...)]` с тип UUID входа: `Annotated[UUID, BeforeValidator(...)]` с
`re.fullmatch`; не-строку пропускает дальше. Проверка: `uv run python `re.fullmatch`; не-строку пропускает дальше. Проверка: `uv run python
@@ -107,12 +107,12 @@
- канон в обоих регистрах принимается; - канон в обоих регистрах принимается;
- запись без дефисов, `urn:uuid:`, `{…}`, пробел, `\n` в конце, - запись без дефисов, `urn:uuid:`, `{…}`, пробел, `\n` в конце,
`[]`, `{}`, `123`, `false`, `null` — ошибка валидации. `[]`, `{}`, `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`). `chat_id` трёх ручек (`src/api/routers/v1/chat.py`, `message.py`).
Модели ответов не меняются. Проверка: `make run_dev`, в Модели ответов не меняются. Проверка: `make run_dev`, в
`/openapi.json` у `chat_id` по-прежнему `{"type": "string", `/openapi.json` у `chat_id` по-прежнему `{"type": "string",
"format": "uuid"}`. "format": "uuid"}`.
- [ ] 3.3 `decode_cursor` (`src/utils/cursor.py`): - [x] 3.3 `decode_cursor` (`src/utils/cursor.py`):
- `t` и `i` — строки; - `t` и `i` — строки;
- `except` только `ValueError`; - `except` только `ValueError`;
- обратная сборка через `encode_cursor` и сравнение со входом; - обратная сборка через `encode_cursor` и сравнение со входом;
@@ -121,10 +121,10 @@
Проверка: `uv run python -c` — на всех вариантах 2.1 и на Проверка: `uv run python -c` — на всех вариантах 2.1 и на
`garbage`, `eyJ4IjoxfQ`, `!!!` только `CursorError`, другого `garbage`, `eyJ4IjoxfQ`, `!!!` только `CursorError`, другого
исключения нет; на выданном курсоре — тот же ключ. исключения нет; на выданном курсоре — тот же ключ.
- [ ] 3.4 `make lint`, `make test_isolated` — все тесты зелёные, 4 теста - [x] 3.4 `make lint`, `make test_isolated` — все тесты зелёные, 4 теста
реплик пропущены с причиной «one API process». Вывод — в журнал реплик пропущены с причиной «one API process». Вывод — в журнал
этапа. этапа.
- [ ] 3.5 Правило `.claude/rules/api-contract.md`: - [x] 3.5 Правило `.claude/rules/api-contract.md`:
- «Валидация → 400»: pydantic принимает UUID шире `format: uuid`; - «Валидация → 400»: pydantic принимает UUID шире `format: uuid`;
вход с UUID (путь и тело) — только через тип UUID входа из вход с UUID (путь и тело) — только через тип UUID входа из
`common.py`, ответы — `UUID`; `common.py`, ответы — `UUID`;
+2 -4
View File
@@ -1,9 +1,7 @@
from uuid import UUID
from fastapi import APIRouter from fastapi import APIRouter
from src.api.dependencies import ChatServiceDep, CurrentUser, PageQueryDep 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"]) router = APIRouter(prefix="/chats", tags=["chats"])
@@ -39,7 +37,7 @@ async def list_chats(
@router.get("/{chat_id}", response_model=Chat) @router.get("/{chat_id}", response_model=Chat)
async def get_chat( async def get_chat(
user: CurrentUser, user: CurrentUser,
chat_id: UUID, chat_id: UuidIn,
chats: ChatServiceDep, chats: ChatServiceDep,
) -> Chat: ) -> Chat:
chat = await chats.get_chat_for_member(chat_id=chat_id, user_id=user.id) 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 typing import Annotated
from uuid import UUID
from fastapi import APIRouter, Header from fastapi import APIRouter, Header
from src.api.dependencies import CurrentUser, MessageServiceDep, PageQueryDep 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 ( from src.utils.constants import (
IDEMPOTENCY_KEY_HEADER, IDEMPOTENCY_KEY_HEADER,
IDEMPOTENCY_KEY_MAX_LENGTH, IDEMPOTENCY_KEY_MAX_LENGTH,
@@ -31,7 +30,7 @@ IdempotencyKeyHeader = Annotated[
@router.post("", status_code=201, response_model=Message) @router.post("", status_code=201, response_model=Message)
async def send_message( async def send_message(
user: CurrentUser, user: CurrentUser,
chat_id: UUID, chat_id: UuidIn,
body: CreateMessage, body: CreateMessage,
idempotency_key: IdempotencyKeyHeader, idempotency_key: IdempotencyKeyHeader,
messages: MessageServiceDep, messages: MessageServiceDep,
@@ -49,7 +48,7 @@ async def send_message(
@router.get("", response_model=MessagePage) @router.get("", response_model=MessagePage)
async def list_messages( async def list_messages(
user: CurrentUser, user: CurrentUser,
chat_id: UUID, chat_id: UuidIn,
page: PageQueryDep, page: PageQueryDep,
messages: MessageServiceDep, messages: MessageServiceDep,
) -> MessagePage: ) -> MessagePage:
+2 -1
View File
@@ -1,5 +1,5 @@
from .chat import Chat, ChatPage, CreateChat 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 .message import CreateMessage, Message, MessagePage
from .session import Session from .session import Session
from .user import CreateUser, User from .user import CreateUser, User
@@ -18,4 +18,5 @@ __all__ = [
"MessagePage", "MessagePage",
"Session", "Session",
"User", "User",
"UuidIn",
] ]
+2 -2
View File
@@ -2,7 +2,7 @@ from uuid import UUID
from pydantic import BaseModel, ConfigDict, Field 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 ( from src.utils.constants import (
CHAT_MEMBERS_MAX, CHAT_MEMBERS_MAX,
CHAT_MEMBERS_MIN, CHAT_MEMBERS_MIN,
@@ -20,7 +20,7 @@ class CreateChat(BaseModel):
) )
# только форма; повторы, существование и вызывающего в списке # только форма; повторы, существование и вызывающего в списке
# проверяет ChatService.create_chat # проверяет ChatService.create_chat
member_ids: list[UUID] = Field( member_ids: list[UuidIn] = Field(
min_length=CHAT_MEMBERS_MIN, min_length=CHAT_MEMBERS_MIN,
max_length=CHAT_MEMBERS_MAX, 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 datetime import datetime
from enum import StrEnum from enum import StrEnum
from typing import Annotated, Literal 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 from src.utils.utc import to_rfc3339
@@ -16,9 +25,25 @@ def _reject_blank(value: str) -> str:
return value 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)] NonBlankStr = Annotated[StrictStr, AfterValidator(_reject_blank)]
# UUID, который передаёт клиент (путь и тело): запись контракта, цифры в
# любом регистре. Модели ответов — обычный `UUID`
UuidIn = Annotated[UUID, BeforeValidator(_require_uuid_form)]
# время в ответе: RFC 3339 UTC, всегда шесть знаков микросекунд и Z # время в ответе: RFC 3339 UTC, всегда шесть знаков микросекунд и Z
UtcDatetime = Annotated[ UtcDatetime = Annotated[
datetime, datetime,
+7
View File
@@ -15,6 +15,13 @@ REQUEST_ID_HEADER = "X-Request-Id"
INSTANCE_ID_HEADER = "X-Instance-Id" INSTANCE_ID_HEADER = "X-Instance-Id"
IDEMPOTENCY_KEY_HEADER = "Idempotency-Key" 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 безопасно для заголовка и журнала # экземпляр API: значение X-Instance-Id безопасно для заголовка и журнала
INSTANCE_ID_PATTERN = r"^[A-Za-z0-9._-]{1,64}$" 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": 1, "s": <область>, "t": <created_at>, "i": <id>}`. Область
привязывает курсор к конкретному списку: курсор чужого чата или списка привязывает курсор к конкретному списку: курсор чужого чата или списка
чатов другого пользователя не разбирается. чатов другого пользователя не разбирается.
Принимается только та запись, которую выдал сервер: после разбора курсор
собирается заново и сравнивается с полученной строкой. Так изменённый
клиентом курсор (`"v": true`, лишнее поле, id или время в другой записи)
— ошибка, а не страница.
""" """
import base64 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: def decode_cursor(cursor: str, *, scope: str) -> CursorKey:
"""Ключ последнего элемента предыдущей страницы. """Ключ последнего элемента предыдущей страницы.
Бросает `CursorError`, если курсор не разбирается, другой версии или Бросает `CursorError`, если курсор не разбирается, другой версии,
выдан для другой области. выдан для другой области или отличается от записи, которую выдал бы
`encode_cursor` для того же ключа.
""" """
try: try:
padded = cursor + "=" * (-len(cursor) % 4) padded = cursor + "=" * (-len(cursor) % 4)
@@ -63,7 +69,17 @@ def decode_cursor(cursor: str, *, scope: str) -> CursorKey:
if payload.get("s") != scope: if payload.get("s") != scope:
raise CursorError("cursor belongs to another list") 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: try:
return from_rfc3339(payload["t"]), UUID(payload["i"]) created_at = from_rfc3339(raw_time)
except (KeyError, TypeError, ValueError) as e: item_id = UUID(raw_id)
except ValueError as e:
raise CursorError("malformed cursor") from 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