OpenAI API: почему ключ должен оставаться только на сервере

Почему frontend не является безопасным местом для ключа

Код браузера принадлежит пользователю на время выполнения. Он может быть прочитан в исходниках, расширениях, сетевых логах, error-reporting, снимках экрана и собранном bundle. Обфускация, переменная с префиксом PUBLIC и «скрытый» endpoint не превращают секрет в защищённый. Если ключ нужен клиенту, его нужно считать скомпрометированным и планировать отзыв, а не надеяться, что строку никто не заметит.

Та же логика относится к мобильному приложению и desktop-клиенту: встроенный секрет можно извлечь из пакета или памяти. Не просите пользователя присылать свой ключ, cookie, upstream credential или скриншот заголовка для диагностики. У вашего продукта должен быть собственный аутентифицированный API, который принимает намерение пользователя, проверяет роль, tenant, лимит и допустимый capability, а затем уже формирует server-side запрос к gateway.

Постройте узкий backend-маршрут

Плохой прокси просто пересылает из браузера любой URL, model ID, headers и тело. Такой маршрут даёт клиенту возможность обходить вашу policy и превращает сервер в открытый туннель. Хороший маршрут принимает ограниченную команду, например summarize_ticket, и сам выбирает разрешённый alias, timeout, максимальный размер входа и схему ответа. Валидация происходит до чтения секрета и до сетевого вызова.

Свяжите запрос с аутентифицированным actor ID, project ID и environment на сервере. Клиентские поля можно использовать как подсказку, но не как источник прав. Для multi-tenant системы проверяйте принадлежность проекта, allowlist capability и локальную квоту. Не обещайте, что конкретный OpenAI-compatible endpoint всегда имеет одинаковую схему: перед обновлением интеграции сверяйте действующий каталог и документацию, а неизвестный alias обрабатывайте как контролируемый отказ.

Храните и выдавайте секрет по минимальному доступу

Ключ RussiaAPI должен жить в secrets manager либо в защищённой переменной окружения server-side процесса. Разделяйте development, staging и production: тестовый ключ не должен незаметно обслуживать production, а production-секрет — появляться в локальном .env.example. Процесс, который не вызывает gateway, не должен иметь доступ к переменной. Это уменьшает область ущерба при ошибке приложения или компрометации одного worker.

Не печатайте значение секрета при startup, в debug-логах, exception trace, аналитике или ответе API. Маскируйте Authorization и похожие поля до отправки события в наблюдаемость. Ротация должна быть процедурой: создайте новый управляемый секрет, переключите server-side потребителя, выполните безопасный smoke test с обезличенным запросом и отзовите старый по политике. Не публикуйте реальный ключ как «пример» и не включайте его в тестовые фикстуры.

Ограничьте злоупотребление без ложного контроля

Server-side ключ сам по себе не решает проблему злоупотребления. Добавьте аутентификацию вашего пользователя, rate limit по actor и tenant, ограничение размера входа, лимит параллельности и бюджетную policy. Ошибки 401, 403, 429 и timeout нормализуйте для клиента, но не возвращайте технические детали, которые раскрывают секреты, внутренние alias или чужие проекты. Для дорогих или побочных действий предусмотрите отдельное подтверждение.

Лимит должен иметь понятное последствие. Например, браузер получает local_rate_limited с request ID и временем повторной проверки, а сервер записывает только минимальные метаданные. Не подсказывайте способы обхода технических ограничений, правил платформ, законов или санкций. Если бизнесу нужна новая квота или capability, это решается владельцем проекта и действующими условиями, а не сменой IP, утечкой ключа или общим аккаунтом команды.

Журналируйте решение, а не пользовательский контент

Для расследования обычно достаточно времени, actor ID, project ID, capability, версии policy, локального request ID, результата валидации и агрегированной технической метрики. Полный prompt, ответ модели, вложение, ключ и Authorization header чаще создают новый риск, чем помогают. Если содержание действительно необходимо для поддержки, определите отдельное основание, минимальный объём, права доступа и срок удаления.

Связывайте клиентское сообщение об ошибке с локальным request ID, а не с чужим идентификатором провайдера, который может раскрывать лишний контекст. В dashboard показывайте агрегаты по проекту и environment: разрешённые вызовы, отказы policy, timeout и возраст очереди. Это помогает заметить проблему ключа или маршрута без того, чтобы инженеры искали персональные данные в логах. Доступ к журналу тоже должен быть ролью, а не ссылкой без срока.

Проверьте утечку и подготовьте отзыв заранее

Перед релизом ищите секреты в bundle, source maps, примерах документации, CI logs и публичных репозиториях. Добавьте тест, который убеждается: browser build не содержит имени или значения server-only переменной; endpoint отклоняет неизвестный capability; API не отражает Authorization. Проверьте, что оператор может отключить один проект или alias feature flag-ом, не останавливая всю систему.

Если секрет всё же оказался в клиенте, действуйте как при инциденте: ограничьте использование, замените и отзовите ключ согласно процедуре, проверьте минимальные логи и исправьте путь утечки. Не публикуйте расследование с реальными токенами и не пытайтесь «спасти» секрет сменой названия переменной. После исправления выполните серверный smoke test, проверьте доступы и обновите threat model. Такая дисциплина уменьшает риск, но не заменяет требования договора, закона и поставщика.

Server-side пример

Пример рассчитан на Node.js 18+ и защищённый server-side запуск. Он не содержит реального ключа и показывает только логику приложения; перед интеграцией подтвердите текущий маршрут, alias модели и схему payload.

const capabilities = { summarize_ticket: { alias: 'approved-text-alias', maxChars: 6000 } };

export function authorizeBrowserIntent({ actor, projectId, capability, text }) {
  const rule = capabilities[capability];
  if (!actor?.id || actor.projectId !== projectId) return { ok: false, reason: 'project_not_allowed' };
  if (!rule || typeof text !== 'string' || text.length > rule.maxChars) return { ok: false, reason: 'invalid_intent' };
  return { ok: true, alias: rule.alias };
}
// A server-only handler calls this before reading process.env.RUSSIAAPI_API_KEY.
// Never send that environment variable, Authorization header, or raw key to a browser.

Проверьте синтаксис командой node --check, добавьте собственную аутентификацию, лимиты и отрицательные тесты. Не добавляйте в журнал тело запроса, ответ целиком или авторизационные заголовки.

Граница ответственности

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