Propose bounded PNG validation as an openspec change

This commit is contained in:
Artyom
2026-11-06 12:49:16 +03:00
parent 8bc2da2c09
commit f0521fa1e0
5 changed files with 97 additions and 0 deletions
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-06
@@ -0,0 +1,26 @@
## Context
Причина и воспроизведение — `proposal.md`. Вызов `ImageInspector.inspect` предшествует intent → COMMIT → PUT → ready → COMMIT. Адаптер `PillowImageInspector` собирается в `attachments/entrypoints/ioc.py`; изменения остаются внутри инфраструктуры этой зоны.
## Goals / Non-Goals
**Goals:** отвергать недекодируемый основной PNG-поток до записи, сохранив ограниченную память и поддержку Adam7.
**Non-Goals:** рендеринг, варианты изображений и обработка кадров анимации; изменение SQLAlchemy/Alembic, границ зон, настроек конкурентности или хранилищ.
## Decisions
1. Сохранить Pillow для определения типа, размеров и проверки структуры/CRC. Context7 `/python-pillow/pillow/13.0.0` подтверждает: `verify` не декодирует пиксели. JPEG уже проверяется через `draft` и `load`.
2. После CRC проверять PNG через stdlib zlib: IDAT составляет один поток, включая Adler-32 и признак завершения. Ограничить и входные порции, и выдачу распаковщика 64 KiB; не собирать распакованный поток или строку целиком. Проверять точную длину проходов и байты фильтров 0–4, включая все семь проходов Adam7, малые размеры и глубины 1/2/4/8/16. Любой набор остальных байтов восстанавливается обратимыми PNG-фильтрами, поэтому пиксельный буфер для проверки не нужен. Источник: [PNG, разделы 7–11](https://www.w3.org/TR/png-3/).
3. Полный `Image.load()` для PNG отвергнут: 40 MP потребуют до 160 MB пиксельного буфера на проверку. Собственный ограниченный разбор добавляет код, зато сохраняет O(64 KiB) дополнительной памяти независимо от ширины строки. Число распакованных байтов ограничено IHDR; превышение немедленно отвергается. Новых зависимостей нет.
4. Существующие проверки размера тела и пикселей выполняются первыми. Проверка идёт в существующем потоке под `image_check_concurrency`, тело ограничено `max_upload_bytes`, одновременные загрузки — `upload_concurrency`. Исключения разбора отображаются существующим `UnsupportedImage` в `415`; записей PostgreSQL/S3 до проверки нет.
## Risks / Trade-offs
- Собственный учёт PNG-строк → регрессии всех цветовых типов/глубин, Adam7, границ блоков и чанков; корректные небольшие файлы сверяются с независимым `Pillow.load()`.
- Дополнительная распаковка меняет CPU и память upload → финальный агент повторяет затронутые негативные и upload-memory серии, включая сжатый PNG на 40 MP. Этот этап выполняет только offline-тесты; значения cgroup и HTTP-нагрузки не выводятся из unit-тестов.
- Сохранённые upload-замеры относятся к прежнему коду. Reconciler и текстовый путь не изменяются; их пригодные измерения не требуют повтора из-за этого исправления.
## Migration Plan
Миграция данных не нужна. Финальный этап пересобирает API, проверяет отклонение повреждённого PNG через LB, положительные загрузки/скачивание и расход памяти. Прежние evidence сохраняются с исходными SHA. Откат к старому инспектору вернёт major и не считается допустимым завершением исправления.
@@ -0,0 +1,28 @@
## Why
Ревью snapshot `8bc2da2c094afc7e5f5e97c7beb5f278e76253fd` обнаружило major: PNG с корректными CRC, но недекодируемым IDAT получает `201`. Воспроизведение на Pillow 13.0.0 подтверждает, что `Image.verify()` пропускает такой поток. Нарушен обязательный `415` для повреждённого файла уровня «3» и негативный suite уровня «4» из `README.md`.
## What Changes
- Проверять сжатый поток PNG и структуру его строк с ограниченной памятью до создания намерения и PUT.
- Сохранить поддержку корректных PNG, включая Adam7, пределы 10 MiB / 40 MP, JPEG и исходные байты.
- Добавить offline-регрессии и сценарий для финального прогона через LB.
- Передать отчётному и финальному агентам evidence исправления и перечень затронутых проверок.
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `lab4-attachments`: явно проверить недекодируемый поток пикселей при целых чанках.
## Impact
Адаптер `ImageInspector` зоны `attachments`, собственные тесты, OpenSpec и `evidence/png-validation-fix/`. Новых зависимостей, изменений SQL, миграций или контракта нет. Материал предназначен для строки «Лимиты и негативные тесты файлов» будущего `REPORT.md`; окончательный отчёт выполняет другой этап.
## Non-goals
Все пункты Out of scope из `openspec/config.yaml`; исправление известного minor с Unicode-суррогатами. Docker, нагрузка, публикации и изменение нормативных файлов запрещены текущему этапу. Динамические доказательства здесь не объявляются проверенными.
@@ -0,0 +1,30 @@
## MODIFIED Requirements
### Requirement: Тип определяется по содержимому
Сервис SHALL принимать только `Content-Type` `image/png` и `image/jpeg` (параметры заголовка и регистр не важны) и SHALL проверять, что сигнатура и структура файла соответствуют заявленному типу, а файл читается без ошибок. Иной или отсутствующий `Content-Type`, несовпадение заявленного типа и содержимого, пустое тело, обрезанный или повреждённый файл, GIF, WebP и текст SHALL давать `415` с кодом `unsupported_media_type`.
#### Scenario: Подмена MIME
- **WHEN** JPEG, GIF или текст отправлены с `Content-Type: image/png`
- **THEN** ответ `415` с кодом `unsupported_media_type`
#### Scenario: Обрезанное изображение
- **WHEN** отправлена первая половина корректного PNG или JPEG с верным `Content-Type`
- **THEN** ответ `415`
#### Scenario: Неподдерживаемый Content-Type
- **WHEN** корректный PNG отправлен с `Content-Type: application/octet-stream` или без `Content-Type`
- **THEN** ответ `415`
#### Scenario: Повреждённый поток пикселей при корректных CRC
- **WHEN** участник отправляет PNG с корректными CRC и IEND, но ошибочным zlib-потоком IDAT, его контрольной суммой, числом байтов строк или кодом фильтра
- **THEN** `POST /api/v1/chats/{chat_id}/attachments` отвечает `415` с кодом `unsupported_media_type`, `X-Request-Id` и `X-Instance-Id`; строка вложения и объект не создаются
#### Scenario: Корректные варианты PNG
- **WHEN** участник загружает корректный PNG в пределах лимитов, в том числе Adam7, с разрешёнными глубиной цвета и фильтрами, а IDAT разделён на несколько чанков
- **THEN** ответ `201 ready`, скачивание другим участником возвращает исходные байты
@@ -0,0 +1,11 @@
## 1. Исправление уровня «3»
- [ ] 1.1 Добавить регрессию PNG с корректными CRC и битым IDAT, зафиксировать исходный отказ теста offline.
- [ ] 1.2 Дополнить адаптер ImageInspector ограниченной проверкой потока PNG до записи в хранилища.
- [ ] 1.3 Проверить offline повреждённые потоки, фильтры, длины строк и корректные варианты PNG/JPEG; подтвердить отсутствие записей в handler и `415` через ASGI с подменёнными портами.
## 2. Ограничения уровня «4» и передача evidence
- [ ] 2.1 Проверить ограниченность распаковки, предел пикселей до неё и добавить регрессию через LB для финального этапа, не запуская Docker.
- [ ] 2.2 Выполнить make check, make validate, make lint и относящиеся offline-тесты; сохранить команды, результаты и перечень обязательных динамических проверок в evidence.
- [ ] 2.3 Синхронизировать спецификацию, архивировать change и выполнить строгую OpenSpec-валидацию.