Файл без расширения не обязательно повреждён. Многие API отдают объект по ID или подписанной ссылке, где путь ничего не говорит о формате. Расширение нужно файловой системе и приложениям, но тип содержимого сначала определяют по метаданным и самому потоку.
Не дописывайте .jpg ко всему подряд. Серверный Content-Type может быть ошибочным, а исходное имя — пользовательским и недоверенным. Безопасная цепочка принимает несколько сигналов, разрешает только поддерживаемые форматы и отправляет противоречивые случаи в карантин.
Сигналы имеют разный вес
| Сигнал | Для чего годится | Чего не доказывает |
|---|---|---|
| Content-Type ответа | Предварительный выбор parser | Что тело действительно этого формата |
| Имя из metadata | Понятная подпись пользователю | Безопасность пути и реальный тип |
| Magic bytes | Отсев многих известных контейнеров | Полную корректность повреждённого файла |
| Успешный decoder/parser | Проверка структуры поддержанного формата | Отсутствие вредного содержимого внутри |
| IANA media type | Нормализованное имя типа | Разрешение бизнес-системы хранить его |
IANA ведёт реестр media types, а HTTP Content-Type описывает media type представления. Но для загружаемого недоверенного файла заголовок остаётся утверждением отправителя. Политика приложения решает, какие типы принимать и какими библиотеками их разбирать.
Сначала временный файл, потом постоянное имя
$declared = normalizeMediaType($response->header("Content-Type"));
$temp = streamToQuarantine($response->body(), maxBytes: 25_000_000);
$detected = detectFromSignature($temp);
$allowed = [
"image/jpeg" => "jpg",
"image/png" => "png",
"image/webp" => "webp",
"application/pdf" => "pdf",
];
if (!isset($allowed[$detected]) || !typesAgree($declared, $detected)) {
quarantine($temp, reason: "media_type_mismatch");
}
$final = safeObjectId() . "." . $allowed[$detected];
atomicMove($temp, $storageDir . "/" . $final);Временное имя генерируется приложением и не содержит исходный path. Ограничение размера применяется во время streaming, а не после загрузки в память. atomicMove выполняется только внутри подготовленного каталога хранения; конфликт имён решает уникальный object ID.
Allowlist связывает тип с одним каноническим суффиксом
Не превращайте произвольную строку после slash в расширение: media type может содержать параметры, нестандартные символы или просто не поддерживаться. Таблица приложения нормализует, например image/jpeg в jpg, хранится рядом с версией обработчика и проходит тесты при добавлении формата.
- Отделяйте media type от параметров вроде charset до сравнения.
- Не доверяйте Content-Disposition filename как пути на диске.
- Для SVG и HTML применяйте отдельную политику активного содержимого.
- Архивы и офисные контейнеры проверяйте специализированным parser и лимитами распаковки.
- Неизвестный тип сохраняйте только в закрытом карантине без публичного URL.
Расхождение не исправляют молча
Если сервер обещает image/jpeg, а сигнатура и decoder показывают PNG, это может быть обычная ошибка интеграции или подмена. Запишите оба media type, source object ID и hash, но не публикуйте объект. Автоматическое предпочтение одного сигнала скроет дефект поставщика и усложнит расследование.
Для форматов со сложной структурой одной короткой сигнатуры мало. После первичного определения вызовите библиотеку, которая действительно разбирает изображение, PDF или видео metadata под лимитами времени и памяти.
Имя для скачивания отделено от ключа хранения
Постоянный storage key лучше строить из внутреннего object ID, а оригинальное имя хранить отдельным очищенным полем. При отдаче пользователю безопасное display name можно поместить в Content-Disposition, не позволяя слешам, управляющим символам и зарезервированным именам стать частью пути.
Набор тестов включает неудобные случаи
- JPEG без имени и с корректным image/jpeg получает .jpg.
- PNG с ошибочным image/jpeg уходит в карантин.
- Тело HTML под видом изображения не становится публичным файлом.
- Файл сверх лимита прерывается во время чтения потока.
- Два объекта с одинаковым display name получают разные storage key.
- Неизвестный media type не порождает расширение из входной строки.
Лог фиксирует решение, а не содержимое
Для разбора нужны source object ID, declared и detected type, размер, hash, версия detector, конечный статус и причина карантина. Первые байты, приватная ссылка и оригинальный документ в общий лог не помещают. Такой журнал помогает увидеть системную ошибку API без утечки файлов.