Файл без расширения не обязательно повреждён. Многие 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, не позволяя слешам, управляющим символам и зарезервированным именам стать частью пути.

Набор тестов включает неудобные случаи

  1. JPEG без имени и с корректным image/jpeg получает .jpg.
  2. PNG с ошибочным image/jpeg уходит в карантин.
  3. Тело HTML под видом изображения не становится публичным файлом.
  4. Файл сверх лимита прерывается во время чтения потока.
  5. Два объекта с одинаковым display name получают разные storage key.
  6. Неизвестный media type не порождает расширение из входной строки.

Лог фиксирует решение, а не содержимое

Для разбора нужны source object ID, declared и detected type, размер, hash, версия detector, конечный статус и причина карантина. Первые байты, приватная ссылка и оригинальный документ в общий лог не помещают. Такой журнал помогает увидеть системную ошибку API без утечки файлов.

Проверенные источники