Перейти к основному содержимому

Безопасное подключение к провайдерам

  • Дата: 3 августа 2026 года
  • Статус: принято для gpt2giga 0.3
  • Ответственные направления: профили и адаптеры провайдеров, интеграция
  • Ревизия: gpt2giga.provider-security.v1

Контекст​

Универсальный шлюз работает с несколькими сетевыми адресами и наборами учётных данных. Если разрешить запросу менять адрес, заголовки, DNS-результат или правила повторных попыток, обычное поле совместимости может привести к незапланированному переключению провайдера или SSRF.

Решение​

Настройки берутся только из профиля​

Тип провайдера, схема, хост, порт, базовый путь, политика TLS, ссылка на учётные данные и фактическая модель задаются неизменяемым профилем. Тело и заголовки публичного запроса не могут их переопределить.

Поля base_url, url, provider, api_key, token, authorization, настройки TLS и прокси, произвольные заголовки и внутренние идентификаторы моделей отклоняются до сетевого вызова. Адаптер сам формирует обязательные заголовки провайдера и пропускает только заранее разрешённые короткие идентификаторы трассировки. В первой версии схемы нет произвольной карты заголовков.

Адрес и DNS​

  • Для рабочих профилей обязателен https.
  • http разрешён только для явно отмеченного локального профиля разработки и не может вести за пределы loopback-интерфейса.
  • URL с userinfo, фрагментом, неоднозначным портом, неподдерживаемой схемой или неканоническим хостом не проходит проверку.
  • Частные и служебные адреса, а также категории link-local, multicast, unspecified и loopback запрещены. Исключение — точное правило локальной разработки.
  • После DNS-разрешения создаётся одноразовое сетевое разрешение. Оно связано со схемой, хостом, портом, набором IP-адресов, HTTP-методом, размером и хешем тела, назначением запроса, предельным размером ответа и сроком действия.
  • Фактический адрес соединения сверяется с разрешением. SDK, в котором такую проверку нельзя выполнить, нельзя делать публично настраиваемым до перехода на общий контролируемый транспорт.
  • HTTP-редиректы отключены. Вместо перехода по новому адресу шлюз возвращает destination_mismatch.

TLS и учётные данные​

Проверка TLS всегда включена. Профиль может сослаться на заранее проверенную политику TLS, но запрос не может отключить проверку сертификата или передать свой сертификат.

В профиле хранится только имя переменной окружения или SecretRef. При запуске шлюз проверяет наличие учётных данных для включённых профилей и возвращает credential_unavailable, если их нет.

Значение секрета доступно только при создании клиента адаптера или конкретного запроса. Оно исключается из repr, ошибок, логов, трассировок, метрик, диагностических ответов, манифестов, тестовых данных и постоянного хранилища. Передавать учётные данные провайдера в каждом запросе нельзя. Прежний режим с pass-token остаётся только за пределами режима профилей провайдеров.

Повторные попытки и отмена​

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

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

Что можно записывать в диагностику​

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

Миграция и откат​

  • Переменные GIGACHAT_* используются только встроенным нативным маршрутом GigaChat, когда файл профилей не указан.
  • Поля транспорта и провайдера из запроса, которые раньше игнорировались или передавались дальше, в режиме профилей теперь приводят к явному отказу.
  • После удаления файла конфигурации следующий запуск вернётся к нативному маршруту GigaChat. Версия 0.2.x не использует файлы профилей и ссылки на политики.