Конфигурация frontend-приложений¶
Требования этого документа применяются к конфигурации frontend-приложений
профилей CSR, SSR, SSG и edge по frontend/rendering-profiles.md. Браузер
является недоверенной средой, поэтому любое значение, попадающее в поставляемый
bundle, считается публичным; server-only и edge-only конфигурация не становится
клиентской конфигурацией. Уровни обязательности определены в корневом
README.md.
FE-CONF-001. Разделение build-time и runtime конфигурации¶
Уровень: MUST
Применяется к: конфигурации приложения
Каждый параметр конфигурации должен быть отнесён к одному из источников:
- build-time значение, неизменное для всех окружений и зафиксированное в репозитории;
- runtime значение, внедряемое во время выполнения в согласии с
DEV-BUILD-004, включая значения, отличающие окружения.
Значение, зависящее от окружения или экземпляра, не должно требовать пересборки артефакта. Состав build-time параметров должен быть документирован.
Обоснование¶
Явное разделение поддерживает единый артефакт для всех окружений и делает источник каждого значения однозначным.
Проверка¶
- review состава build-time и runtime параметров;
- проверка запуска одного артефакта с конфигурацией разных окружений;
- проверка отсутствия per-env пересборки.
Исключения¶
Build-time feature flag для управляемого набора сборок по DEV-BUILD-004 допускается
как явно задокументированное исключение.
FE-CONF-002. Отсутствие секретов в клиентском bundle¶
Уровень: MUST
Применяется к: browser bundle, HTML и передаваемым клиенту данным
Запрещено встраивать в browser bundle, HTML или hydration state секреты,
приватные API-ключи, пароли, токены доступа, приватные ключи и иные учётные
данные. Любое значение, попавшее в клиентский результат, должно считаться
публичным и доступным конечному пользователю. Secret input SSR-, SSG- и
edge-части также регулируется SEC-SCRT-001, SEC-SCRT-002 и SEC-SCRT-005 и
не должен
встраиваться в server или edge bundle.
Допускаются только значения, которые по своей природе являются публичными и предназначены для клиента: публичный идентификатор OAuth-клиента, publishable key SDK наблюдаемости и идентификаторы, не дающие сами по себе доступа к защищённым ресурсам.
Обоснование¶
Браузер и клиентский результат находятся вне доверенного периметра; извлечь встроенное значение невозможно предотвратить. Встроенный secret server bundle также становится частью распространяемого артефакта.
Проверка¶
- static analysis и secret scanning browser, server и edge bundles и HTML;
- review всех build-time и runtime параметров на статус секрета;
- тест доступа к ресурсу только с публичным значением из bundle.
Исключения¶
Не допускаются.
FE-CONF-003. Типизация и проверка конфигурации¶
Уровень: MUST
Применяется к: итоговой конфигурации приложения
Каждый параметр конфигурации должен иметь объявленный тип, источник и допустимые значения. Build-time параметры должны проверяться при сборке, а runtime — при загрузке приложения до начала значимой работы.
Приложение должно различать отсутствующее, пустое и некорректное значение и не должно молча подставлять значение по умолчанию вместо явно переданного некорректного.
Обоснование¶
Fail-fast предотвращает запуск приложения с неверно истолкованной конфигурацией.
Проверка¶
- unit-тест схемы конфигурации;
- негативные тесты отсутствующего, пустого и некорректного значения;
- проверка поведения при ошибке конфигурации.
Исключения¶
Неизвестные ключи допускаются только в явно объявленном расширяемом разделе.
FE-CONF-004. Runtime конфигурация из доверенного источника¶
Уровень: MUST
Применяется к: runtime параметрам, загружаемым приложением
Если приложение загружает runtime конфигурацию, она должна поступать из
объявленного доверенного источника, проверяться по FE-CONF-003 и обрабатываться
как недоверенный ввод. Конечная точка конфигурации не должна позволять
переопределить защищённые параметры таким образом, чтобы обойти серверную
авторизацию.
Обоснование¶
Browser-среда и промежуточные proxy контролируются вызывающей стороной, поэтому источник и валидность конфигурации должны быть явными.
Проверка¶
- contract-тест источника и схемы runtime конфигурации;
- security-тест подмены конфигурации и переопределения защищённых параметров;
- проверка обработки некорректного ответа.
Исключения¶
Не допускаются для проверки недоверенного ввода.
FE-CONF-005. Отсутствие секретов и отладочного вывода в production¶
Уровень: MUST
Применяется к: диагностическому выводу в браузере
В production-сборке приложение не должно выводить в консоль браузера секреты,
токены, заголовки авторизации, персональные данные и полный дамп состояния, а
также отладочные сообщения уровня DEBUG и ниже. Подробное логирование
допускается только в непроизводственной сборке.
Обоснование¶
Консоль браузера и расширения доступны широкой стороне, а подробный вывод раскрывает внутреннее устройство и данные пользователя.
Проверка¶
- review конфигурации логирования в production-сборке;
- тест отсутствия секретов и персональных данных в консоли;
- проверка удаления или отключения debug-вывода в production.
Исключения¶
Ограниченный диагностический вывод, необходимый пользователю для сообщения об ошибке, допускается без раскрытия секретов и персональных данных.