image-platform/docs/imgproxy-contract.md

Контракт с imgproxy

imgproxy всегда внешний сервис для image-platform.

Env

IMGPROXY_UPSTREAM=http://external-imgproxy.internal:8080
IMGPROXY_SIGNING_ENABLED=false
IMGPROXY_KEY=
IMGPROXY_SALT=

Dev режим

В dev можно использовать unsigned /unsafe URL, если внешний imgproxy запущен без key/salt.

Пример path:

/unsafe/resize:fit:800:0:0/q:80/plain/https://storage.yandexcloud.net/shared1318/img/1.jpg

Prod режим

В prod нужно перейти на signed URLs и закрыть /unsafe.

Path для подписи строится без /unsafe:

/resize:fit:800:0:0/q:80/plain/https://storage.yandexcloud.net/shared1318/img/1.jpg

Signature:

HMAC-SHA256(binary_key, binary_salt + path_bytes)
base64url without padding

Node implementation reference:

import crypto from "node:crypto"

export function signImgproxyPath(keyHex: string, saltHex: string, path: string) {
  const key = Buffer.from(keyHex, "hex")
  const salt = Buffer.from(saltHex, "hex")
  const hmac = crypto.createHmac("sha256", key)

  hmac.update(Buffer.concat([salt, Buffer.from(path)]))

  return hmac.digest("base64url")
}

Final signed URL:

{IMGPROXY_UPSTREAM}/{signature}{path}

Security rules

• Не отдавать IMGPROXY_KEY и IMGPROXY_SALT в браузер.
• Source URL валидировать в Backend/worker для managed assets и в Gateway для remote source mode.
• Разрешать только http и https.
• Запрещать localhost, private IP, loopback, link-local.
• Source host должен быть разрешён mock allowlist SOURCE_ALLOWED_HOSTS; таблица allowed_image_hosts остаётся для будущего CRUD.
• Не давать клиенту произвольные imgproxy options без IMAGE_ALLOW_CUSTOM_TRANSFORMS=true.
• Использовать static presets/custom normalization и deterministic variantHash.