Блокировка DOM XSS в React с помощью Trusted Types
Узнайте, как React 19.3 включает Trusted Types для защиты от DOM XSS с политикой DOMPurify, заголовками CSP и безопасным запуском в режиме отчётов.
React 19.3 передаёт объекты Trusted Types напрямую в DOM. Теперь React-приложение может включить require-trusted-types-for 'script' и пропускать всю разметку из dangerouslySetInnerHTML через политику на базе DOMPurify.
До этого релиза такая конфигурация, как правило, не работала. Вы санитизировали HTML из CMS и включали директиву CSP, но React всё равно превращал аккуратно типизированное значение обратно в строку.
В статье разбираются изменение в React, заголовки CSP, модуль политики, который работает и в браузерах без поддержки API, а также поэтапное внедрение, начиная с режима report-only. Основы XSS описаны в статье о предотвращении XSS в пользовательском контенте.
Ключевые выводы
- До React 19.3 React приводил значения к строке через
'' + value. Поэтому объект TrustedHTML, переданный вdangerouslySetInnerHTML, попадал вinnerHTMLкак обычная строка, и браузер в режиме принудительного применения его отклонял. - При
require-trusted-types-for 'script'присваивание обычной строки опасному приёмнику (injection sink), напримерinnerHTML, выбрасывает TypeError. - Trusted Types сам ничего не санитизирует. Он гарантирует, что HTML попадает в приёмник только через написанную вами политику, а очисткой внутри этой политики занимается DOMPurify.
- Сначала разверните
Content-Security-Policy-Report-Onlyи исправьте все приёмники из отчётов. Затем внесите имена политик в разрешённый список черезtrusted-typesи только после этого включайте принудительный режим. - Браузеры без Trusted Types ничего не проверяют, поэтому санитайзер внутри политики должен выполняться при каждом вызове.
Что изменилось в React 19.3?
React 19.3 (выпущен 9 сентября 2026 г.) передаёт значения TrustedHTML, TrustedScript и TrustedScriptURL в DOM без приведения типов. Благодаря этому браузер может проверить, что их создала политика Trusted Types.
Предыдущие версии превращали значения в строку через '' + value перед передачей в DOM API. Поэтому объект TrustedHTML, переданный в dangerouslySetInnerHTML, доходил до innerHTML как обычная строка, и браузер в режиме принудительного применения его отклонял. В анонсе релиза в качестве примера приёмника приводится innerHTML. Свойство dangerouslySetInnerHTML, которое записывает именно в innerHTML, теперь сохраняет доверенный объект. В этом же релизе стабильными стали refs для Fragment.
Как Trusted Types блокирует DOM XSS?
Trusted Types API закрывает опасные приёмники для «сырых» строк. После включения принудительного режима такие приёмники, как innerHTML или src у скрипта, принимают только типизированные объекты, созданные именованной политикой.
| Доверенный тип | Категория приёмника | Пример приёмника |
|---|---|---|
TrustedHTML | Парсинг HTML | Element.innerHTML |
TrustedScript | Текст скрипта | eval() |
TrustedScriptURL | Загрузка скрипта | HTMLScriptElement.src |
Trusted Types сам не очищает разметку. Он гарантирует, что каждое значение, попавшее в приёмник, прошло через функцию политики, и именно в этой функции работает DOMPurify. Это меняет модель безопасности: санитизация перестаёт зависеть от того, вспомнит ли разработчик о ней в каждом месте вызова, и становится правилом, которое обеспечивает браузер.
Настройка заголовка Content-Security-Policy
Trusted Types включается директивой CSP require-trusted-types-for 'script'. Начните с отправки этой директивы в заголовке Content-Security-Policy-Report-Only. В этом режиме браузер сообщает о нарушениях, но не мешает выполнению кода.
Content-Security-Policy-Report-Only: require-trusted-types-for 'script'
Добавьте эндпоинт для отчётов с помощью директивы report-to. Тогда браузер будет отправлять каждый нарушающий приёмник в ваш сборщик, а не только выводить его в консоль. Когда отчёты перестанут приходить, переключитесь на заголовок с принудительным применением:
Content-Security-Policy: require-trusted-types-for 'script'; trusted-types app-html
Директива require-trusted-types-for заставляет присваивание строк приёмникам выбрасывать исключение. Директива trusted-types перечисляет разрешённые имена политик: trustedTypes.createPolicy() выбросит исключение, если вызвать его с именем не из списка. Отправляйте обе директивы в заголовках ответа: браузеры не поддерживают заголовок report-only и директиву report-to в теге <meta>.
Создание политики-обёртки над DOMPurify
В React-приложении создавайте политику Trusted Types один раз на уровне модуля и импортируйте её там, где она нужна. createPolicy() выбрасывает TypeError при повторном имени, если в директиве trusted-types нет 'allow-duplicates'. Поэтому тело компонента для этого не подходит: React повторно рендерит компоненты, а StrictMode вызывает их дважды.
// trusted-html.js
import DOMPurify from 'dompurify';
const factory = globalThis.trustedTypes ?? {
createPolicy: (name, rules) => rules,
};
export const htmlPolicy = factory.createPolicy('app-html', {
createHTML: (dirty) =>
DOMPurify.sanitize(dirty, { TRUSTED_TYPES_POLICY: null }),
});
createHTML возвращает санитизированную строку, а браузер оборачивает её в TrustedHTML. Параметр TRUSTED_TYPES_POLICY: null не даёт DOMPurify создать собственную внутреннюю политику dompurify, поэтому в разрешённом списке достаточно app-html. Не указывайте RETURN_TRUSTED_TYPE: true внутри createHTML: колбэк должен возвращать обычную строку.
Резервный объект — это идея tinyfill из MDN, адаптированная для ES-модулей. Если API недоступен, createPolicy возвращает объект правил без изменений, и htmlPolicy.createHTML() всё так же вызывает DOMPurify и возвращает строку. Путь выполнения кода везде одинаков. Поскольку резервный объект локальный, модуль без ошибок импортируется и при серверном рендеринге, где trustedTypes не определён. Для санитизации на сервере DOMPurify нужна реализация DOM; как её настроить, описано в README библиотеки.
У DOMPurify есть и более короткий путь: вызвать DOMPurify.sanitize(dirty, { RETURN_TRUSTED_TYPE: true }) без собственной политики. Там, где API поддерживается, функция вернёт TrustedHTML, а в разрешённый список нужно будет добавить dompurify (trusted-types app-html dompurify).
Использование политики с dangerouslySetInnerHTML
В React 19.3 и новее передайте результат политики в __html, и React отдаст объект TrustedHTML в innerHTML без изменений.
// Before: under enforcement, the raw string throws a TypeError
<div dangerouslySetInnerHTML={{ __html: html }} />
В режиме report-only эта строка попадёт в отчёт о нарушении. В принудительном режиме она выбросит исключение.
import { htmlPolicy } from './trusted-html';
export function RichText({ html }) {
return <div dangerouslySetInnerHTML={{ __html: htmlPolicy.createHTML(html) }} />;
}
Пропускайте весь вывод из CMS, Markdown и rich-text-редакторов через RichText (или прямой вызов htmlPolicy.createHTML()). Если потом выполнить grep по __html:, рядом с каждым совпадением должен стоять вызов политики.
Безопасное внедрение Trusted Types
Безопасное внедрение Trusted Types состоит из четырёх этапов: режим report-only, исправление всех приёмников из отчётов, внесение имён политик в разрешённый список и включение принудительного режима.
- Разверните
Content-Security-Policy-Report-Only: require-trusted-types-for 'script'с эндпоинтом для отчётов. - Исправьте каждый приёмник из отчётов: пропустите значение через
htmlPolicyили замените приёмник на тот, которому не нужны доверенные значения, напримерtextContent. - Перечислите в
trusted-typesвсе имена политик, которые создают ваш код и зависимости. - Переключитесь на заголовок
Content-Security-Policyс принудительным применением.
Если сторонний код продолжает присваивать строки и исправить его пока нельзя, временным мостом может послужить политика с именем default. В принудительном режиме браузер передаёт ей каждую «сырую» строку, дошедшую до приёмника. MDN рекомендует использовать её только на время миграции устаревшего кода.
// TEMPORARY: remove before you finish the migration.
import DOMPurify from 'dompurify';
if (globalThis.trustedTypes) {
globalThis.trustedTypes.createPolicy('default', {
createHTML(value) {
console.warn('Untyped HTML reached a sink');
return DOMPurify.sanitize(value, { TRUSTED_TYPES_POLICY: null });
},
});
}
Проверка наличия API не даёт модулю выбросить исключение в браузерах без поддержки Trusted Types и при серверном рендеринге.
Пока эта политика существует, добавьте default в trusted-types. Когда её предупреждения перестанут появляться, удалите и саму политику, и запись в разрешённом списке.
Что происходит в браузерах без Trusted Types?
Браузеры без Trusted Types ничего не проверяют. В них санитайзер внутри вашей политики — единственный барьер между недоверенным HTML и DOM. MDN отмечает window.trustedTypes как Baseline 2026 (newly available с февраля 2026 г.), поэтому у части вашей аудитории со старыми версиями браузеров этого API не будет.
Эту ситуацию обрабатывает резервный объект на уровне модуля. Браузеры без поддержки игнорируют заголовок, но всё равно выполняют DOMPurify.sanitize() при каждом вызове. Поэтому политика должна санитизировать всегда и никогда не возвращать входные данные без изменений.
Заключение
React 19.3 убирает приведение к строке, из-за которого раньше ломался Trusted Types. Теперь dangerouslySetInnerHTML может передавать созданный политикой HTML, а браузер обеспечивает соблюдение правил. Сначала разверните заголовок report-only, переведите все присваивания __html на одну политику на базе DOMPurify и включите принудительный режим, когда отчёты перестанут приходить. Затем примените тот же подход на стороне сервера, опираясь на эти рекомендации по безопасности API.
Часто задаваемые вопросы
Что произойдёт, если политика Trusted Types по умолчанию вернёт null или undefined?
Браузер выбросит TypeError на приёмнике, и присваивание не выполнится. Политика по умолчанию, возвращающая null или undefined, не пропускает значение дальше. Она работает по принципу fail-closed и блокирует запись, а не пропускает исходную строку. Политика по умолчанию, которая возвращает null для любого входного значения, также помогает найти оставшиеся присваивания строк во время миграции.
Безопасно ли использовать wildcard или allow-duplicates в директиве trusted-types?
Ни то, ни другое не подходит для продакшена. Звёздочка (*) в качестве имени политики разрешает любое уникальное имя, поэтому внедрённый скрипт сможет зарегистрировать собственную политику и создавать доверенные значения. Ключевое слово 'allow-duplicates' позволяет коду создавать несколько политик с одинаковым именем, и одно имя перестаёт однозначно соответствовать одной известной политике. Вместо этого перечислите точные имена всех политик, которые создают ваш код и зависимости.
Можно ли использовать eval() при включённом принудительном режиме Trusted Types?
Да. Добавьте в CSP ключевое слово 'trusted-types-eval'. Оно разрешает eval() и аналогичные функции только в браузерах, которые поддерживают Trusted Types и применяют его. В отличие от 'unsafe-eval', в браузерах без поддержки Trusted Types эти функции остаются заблокированными. При включённом принудительном режиме код, передаваемый в eval(), по-прежнему должен быть TrustedScript или «сырой» строкой, которую политика по умолчанию преобразует в TrustedScript. Иначе вызов выбросит исключение.
Gain Debugging Superpowers
Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.
Star on GitHub12k