API gateway: проверка исходящих headers без утечки секретов

Опишите контракт вашего приложения, а не предполагаемый контракт провайдера

Сначала выпишите, какие заголовки обязан формировать именно ваш backend. Обычно это тип содержимого, безопасный локальный request ID и server-side авторизация, полученная из защищённого окружения. Поля, которые не нужны вашему сценарию, не должны появляться «на всякий случай». Названия, допустимые значения и поведение внешнего endpoint сверяйте с текущей документацией выбранного маршрута; статья не заменяет её и не делает вывод о поддержке OpenAI-совместимости.

Разделите заголовки на три группы: разрешённые для передачи, разрешённые только в локальной диагностике и запрещённые. В запрещённую группу попадут browser cookie, внутренние токены, отладочные дампы, клиентские IP-адреса без основания и любые чужие credentials. Такой список легче ревьюить, чем длинную конфигурацию SDK. Если поле не описано и не нужно для доказуемой функции, безопаснее удалить его до сетевого вызова и зафиксировать решение в коде.

Держите ключ и сбор headers только на сервере

Браузер не должен получать общий ключ gateway или подставлять Authorization напрямую. Клиент вызывает ваш аутентифицированный backend, а тот читает секрет из server-side хранилища и формирует минимальный набор headers. Разделяйте staging и production: для каждого окружения нужны свой endpoint-конфиг, собственный секрет и ограниченный доступ. Не вставляйте ключ в исходный код, пример, URL, screenshot или переменную, которую отправляет клиент.

Особенно опасны универсальные middleware, которые пересылают все входящие headers дальше. Они способны передать cookie, служебный токен или случайный отладочный признак в внешний маршрут. Используйте новую объектную структуру, собранную из allowlist, вместо копирования request.headers. Это также упрощает аудит: код показывает, какие данные разрешены, а изменение нового поля проходит отдельное review. Ключи поставщиков и upstream credentials не нужны ни читателю статьи, ни вашему frontend.

Проверьте отправку на синтетическом staging-сценарии

Для проверки подготовьте безопасный запрос без реального пользовательского текста, персональных данных и бизнес-действия. Тест должен подтвердить только наблюдаемое: backend создал разрешённый набор, не добавил запрещённые поля, получил ожидаемый класс ответа или понятный отказ. Не делайте вывод о постоянной доступности, скорости, лимите или цене по одному прогону. Запишите дату, версию SDK, версию адаптера и маршрут — так последующее изменение можно сопоставить с результатом.

В диагностический журнал сохраняйте не весь объект headers, а итог allowlist-полей в redacted-виде: например, факт наличия авторизации без значения, локальный request ID и класс исхода. Сканер логов полезно настроить на поиск строк Authorization, Bearer, cookie и похожих секретов. Если тест нашёл запрещённый фрагмент, остановите выпуск адаптера и исправьте код; не пытайтесь скрыть проблему маскировкой на экране после того, как секрет уже ушёл в лог.

Отделите техническую корреляцию от идентификации пользователя

Для разбора инцидента достаточно случайного локального request ID или trace ID, который не содержит prompt, email, tenant name или ключ. Связь с пользователем храните внутри своей системы доступа и выдавайте операторам только при необходимости. Передавать личные данные в технический header ради удобства поиска — плохая замена наблюдаемости. Если внешний контракт документирует корреляционное поле, всё равно оценивайте его как внешнюю передачу данных и сверяйте с политикой проекта.

Не используйте заголовок как канал для неограниченной отладочной информации. Длинный JSON, полный prompt или сериализованный контекст ломают границы данных, увеличивают риск утечки и могут по-разному обрабатываться промежуточными системами. Внутренний диагностический объект должен оставаться минимальным: версия адаптера, случайный идентификатор, длительность, локальная категория ошибки. Для воспроизведения проблемы лучше подготовить отдельный синтетический пример.

Сделайте проверку частью релиза и rollback

Добавьте в CI тест, который вызывает функцию сборки headers и сравнивает результат с allowlist. Проверьте отсутствие секретов в сериализованном логе, отсутствие входящих cookie и корректное поведение при пустой конфигурации. Такой unit-тест не требует сети и не доказывает контракт провайдера, но ловит опасную регрессию в вашем коде. Отдельный staging smoke test выполняйте после обновления SDK, middleware, base URL или маршрута.

Если на staging появился неизвестный формат ответа или обнаружилось поле, которое нельзя объяснить, не расширяйте allowlist автоматически. Остановите rollout, сохраните безопасную диагностику и вернитесь к последней проверенной конфигурации приложения. Feature flag и ручной rollback должны находиться в вашем контуре; они не означают, что gateway гарантирует автоматическое переключение. Такая процедура снижает риск передачи лишних данных при изменении интеграции.

Пример безопасной server-side проверки

Пример ниже иллюстрирует только логику приложения. Он не делает сетевой вызов, не содержит реальных ключей и не доказывает поддержку конкретного endpoint. Проверьте актуальный договор и API-контракт перед подключением рабочего маршрута.

export function buildOutboundHeaders(config, localRequestId) {
  if (!config.apiKey || !localRequestId) throw new Error('missing_server_config');
  return {
    'content-type': 'application/json',
    authorization: 'Bearer ' + config.apiKey,
    'x-client-request-id': localRequestId
  };
}

// Construct a new allowlisted object. Do not forward req.headers,
// cookies, browser tokens, prompt text, or a real key to logs.

Граница ответственности и данных

Это инженерный шаблон для вашего приложения, а не гарантия возможностей внешнего API. Не помещайте в браузер, тикет, статью или обычный журнал API-ключи, заголовок Authorization, cookie, ключи поставщиков, полный prompt или персональные данные. Условия обработки данных, права на контент и применимые требования проверяются по политике вашей организации, договору и с ответственным специалистом.

Контроль перед выпуском

Перед release проверьте синтетический сценарий, запреты на секреты и персональные данные в логах, роли и tenant boundary, понятное сообщение для пользователя и ручную ветку для неизвестного результата. Сохраните дату, версию адаптера и результат теста. При обновлении SDK, модели, schema или маршрута повторите проверку; не переносите выводы старого теста на новый контракт.

Для выбора маршрута откройте RussiaAPI и сверяйте действующие условия в каталоге. Используйте только ключ своего аккаунта на сервере. RussiaAPI не является официальным представителем упомянутых поставщиков; доступность моделей, функций, цены, лимиты и правила обработки данных требуют отдельного подтверждения.

Полезные материалы

OWASP: Secrets Management Cheat Sheet · OWASP: Logging Cheat Sheet

FAQ

Можно ли переслать все входящие headers через proxy?

Нет. Копирование request.headers способно передать cookie, пользовательский токен, IP-данные или отладочные поля, которые не относятся к внешнему вызову. Собирайте новый объект из явно разрешённых значений и проверяйте его на staging.

Нужно ли логировать Authorization для диагностики?

Нет. Логу достаточно сообщить, что server-side конфигурация была найдена, вместе с локальным request ID и категорией результата. Значение ключа, Bearer-строка, cookie и полный объект headers не нужны для обычного разбора ошибки.

Подтверждает ли пример поддержку конкретного header?

Нет. Пример показывает application-side allowlist. Доступность, имя и семантика конкретного поля зависят от актуального API-контракта, выбранного маршрута и вашего теста; их нужно проверять перед выпуском.

Следующий шаг

Продолжите с материалами: OpenAI-compatible API: окружения и CI · Ротация API-ключа без утечки · Request ID и корреляция очереди. Затем проверьте текущие условия и безопасно протестируйте интеграцию на staging перед production-трафиком.