12k
All articles

Bloqueando DOM XSS no React com Trusted Types

Veja como o React 19.3 habilita Trusted Types contra XSS no DOM com uma política DOMPurify, cabeçalhos CSP e implantação segura em modo de relatório.

OpenReplay Team
OpenReplay Team
Bloqueando DOM XSS no React com Trusted Types

O React 19.3 passa objetos Trusted Types diretamente para o DOM. Com isso, uma aplicação React agora pode exigir require-trusted-types-for 'script' e enviar todo o markup de dangerouslySetInnerHTML por meio de uma policy baseada no DOMPurify.

Até esta versão, essa configuração costumava não funcionar. Você sanitizava o HTML vindo do CMS, ativava a diretiva de CSP, e o React convertia de volta para string o valor que você havia tipado com tanto cuidado.

Este artigo aborda a mudança no React, os headers de CSP, um módulo de policy que também funciona em navegadores sem a API e um rollout que começa no modo report-only. Para os fundamentos de XSS, veja preventing XSS in user-generated content.

Principais pontos

  • Antes do React 19.3, o React convertia valores em strings com '' + value. Assim, um objeto TrustedHTML passado para dangerouslySetInnerHTML chegava ao innerHTML como uma string comum, e um navegador com a enforcement ativa o rejeitava.
  • Com require-trusted-types-for 'script', atribuir uma string comum a um injection sink como innerHTML lança um TypeError.
  • Trusted Types não sanitiza nada. A API garante que o HTML chegue ao sink por meio de uma policy escrita por você, e o DOMPurify dentro dessa policy faz a limpeza.
  • Publique primeiro o Content-Security-Policy-Report-Only, corrija cada sink reportado, inclua os nomes das suas policies na allowlist com trusted-types e só então ative a enforcement.
  • Navegadores sem Trusted Types não aplicam nenhuma restrição, então o sanitizador dentro da sua policy precisa ser executado em todas as chamadas.

O que mudou no React 19.3?

O React 19.3 (lançado em 9 de setembro de 2026) passa valores TrustedHTML, TrustedScript e TrustedScriptURL para o DOM sem convertê-los. Assim, o navegador pode verificar se eles foram produzidos por uma policy de Trusted Types.

As versões anteriores convertiam os valores em string com '' + value antes de entregá-los às APIs do DOM. Por isso, um objeto TrustedHTML passado para dangerouslySetInnerHTML chegava ao innerHTML como uma string comum, e um navegador com a enforcement ativa o recusava. O post de lançamento usa innerHTML como exemplo de sink. Como dangerouslySetInnerHTML escreve em innerHTML, ele agora preserva o objeto trusted. A mesma versão também tornou estáveis as Fragment refs.

Como os Trusted Types bloqueiam DOM XSS?

A Trusted Types API fecha os injection sinks para strings brutas. Com a enforcement ativa, sinks como innerHTML ou o src de um script aceitam apenas objetos tipados criados por uma policy nomeada.

Trusted typeCategoria de sinkExemplo de sink
TrustedHTMLParsing de HTMLElement.innerHTML
TrustedScriptTexto de scripteval()
TrustedScriptURLCarregamento de scriptHTMLScriptElement.src

Trusted Types não limpa nenhum markup por conta própria. A garantia é que todo valor que chega a um sink passou por uma função de policy, e é nessa função que o DOMPurify faz o trabalho. Isso muda o modelo de segurança. A sanitização deixa de ser algo que cada desenvolvedor precisa lembrar em cada ponto de chamada e passa a ser algo que o navegador impõe.

Configurando o header Content-Security-Policy

Trusted Types é ativado com a diretiva de CSP require-trusted-types-for 'script'. Comece enviando essa diretiva no Content-Security-Policy-Report-Only. Nesse modo, o navegador reporta as violações, mas continua permitindo a execução do código.

Content-Security-Policy-Report-Only: require-trusted-types-for 'script'

Adicione um endpoint de relatórios usando a diretiva report-to. Assim, o navegador envia cada sink em violação para o seu coletor, em vez de apenas registrá-lo no console. Quando os relatórios pararem de chegar, mude para o header com enforcement:

Content-Security-Policy: require-trusted-types-for 'script'; trusted-types app-html

require-trusted-types-for faz com que atribuições de strings a sinks lancem um erro. trusted-types lista os nomes de policies permitidos, e trustedTypes.createPolicy() lança um erro se você chamá-lo com um nome que não esteja na lista. Envie essas diretivas como headers de resposta. Os navegadores não oferecem suporte ao header report-only nem à diretiva report-to em uma tag <meta>.

Criando uma policy que encapsula o DOMPurify

Em uma aplicação React, crie a policy de Trusted Types uma única vez, no escopo do módulo, e importe-a onde precisar. O createPolicy() lança um TypeError para nomes duplicados, a menos que 'allow-duplicates' esteja na diretiva trusted-types. Por isso, o corpo de um componente é o lugar errado para essa chamada: o React renderiza componentes novamente, e o StrictMode os invoca duas vezes.

// 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 }),
});

O createHTML retorna uma string sanitizada, e o navegador a encapsula em um TrustedHTML. Passar TRUSTED_TYPES_POLICY: null impede que o DOMPurify crie sua própria policy interna dompurify, então a allowlist só precisa de app-html. Não use RETURN_TRUSTED_TYPE: true dentro de createHTML, porque o callback precisa retornar uma string comum.

O objeto de fallback aplica a ideia do tinyfill do MDN em um formato adequado a ES modules. Onde a API não existe, createPolicy retorna o seu objeto de regras sem alterações. Assim, htmlPolicy.createHTML() continua executando o DOMPurify e devolvendo uma string. O fluxo de código é o mesmo em todos os ambientes. Como o fallback é local, o módulo também pode ser importado sem erros durante a renderização no servidor, onde trustedTypes é undefined. O DOMPurify precisa de uma implementação de DOM para sanitizar no servidor, e o README dele explica essa configuração.

O DOMPurify também oferece um atalho: chamar DOMPurify.sanitize(dirty, { RETURN_TRUSTED_TYPE: true }) sem uma policy própria. Ele retorna TrustedHTML onde houver suporte, e você adiciona dompurify à allowlist (trusted-types app-html dompurify).

Usando a policy com dangerouslySetInnerHTML

A partir do React 19.3, coloque a saída da policy em __html, e o React passará o objeto TrustedHTML para o innerHTML sem alterações.

// Before: under enforcement, the raw string throws a TypeError
<div dangerouslySetInnerHTML={{ __html: html }} />

No modo report-only, essa linha aparece como um relatório de violação. No modo com enforcement, ela lança um erro.

import { htmlPolicy } from './trusted-html';

export function RichText({ html }) {
  return <div dangerouslySetInnerHTML={{ __html: htmlPolicy.createHTML(html) }} />;
}

Direcione toda a saída de CMS, markdown e rich text pelo RichText (ou por uma chamada direta a htmlPolicy.createHTML()). Se depois você fizer um grep por __html:, toda ocorrência deve estar acompanhada de uma chamada à policy.

Fazendo o rollout de Trusted Types com segurança

Um rollout seguro de Trusted Types tem quatro etapas: apenas reportar, corrigir cada sink reportado, incluir os nomes das policies na allowlist e, por fim, ativar a enforcement.

  1. Faça o deploy de Content-Security-Policy-Report-Only: require-trusted-types-for 'script' com um endpoint de relatórios.
  2. Corrija cada sink reportado direcionando-o pelo htmlPolicy ou substitua-o por um sink que não exija valores trusted, como textContent.
  3. Liste em trusted-types todos os nomes de policies criados pelo seu código e pelas suas dependências.
  4. Mude para o header Content-Security-Policy com enforcement.

Se um código de terceiros continuar atribuindo strings que você ainda não consegue corrigir, uma policy chamada default pode servir como ponte temporária. Com a enforcement ativa, o navegador entrega a ela toda string bruta que chega a um sink, e o MDN recomenda usá-la apenas durante a migração de código legado.

// 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 });
    },
  });
}

A verificação de suporte impede que o módulo lance erros em navegadores sem a API e durante a renderização no servidor.

Adicione default a trusted-types enquanto essa policy existir. Quando os avisos dela pararem de aparecer, remova tanto a policy quanto a entrada na allowlist.

O que acontece em navegadores sem Trusted Types?

Navegadores sem Trusted Types não aplicam nenhuma restrição. Neles, o sanitizador dentro da sua policy é a única barreira entre o HTML não confiável e o DOM. O MDN classifica window.trustedTypes como Baseline 2026, disponível recentemente desde fevereiro de 2026. Portanto, as versões mais antigas de navegadores presentes no seu tráfego não terão suporte.

O fallback no escopo do módulo cuida disso. Navegadores sem suporte ignoram o header e continuam executando DOMPurify.sanitize() em todas as chamadas. Por esse motivo, a policy deve sempre sanitizar e nunca retornar a entrada sem alterações.

Conclusão

O React 19.3 remove a conversão para string que antes quebrava os Trusted Types. Assim, dangerouslySetInnerHTML agora pode transportar HTML gerado por policies, com enforcement feito pelo navegador. Publique primeiro o header report-only, mova todas as atribuições de __html para uma única policy baseada no DOMPurify e ative a enforcement quando os relatórios pararem. Depois, aplique a mesma disciplina no lado do servidor com estas boas práticas de segurança de APIs.

Perguntas frequentes

O que acontece se uma default policy de Trusted Types retornar null ou undefined?

O navegador lança um TypeError no sink, e a atribuição não acontece. Uma default policy que retorna null ou undefined não deixa o valor passar. Ela falha de forma segura e bloqueia a escrita, em vez de liberar a string original. Uma default policy que retorna null para qualquer entrada também é uma forma útil de encontrar atribuições de strings remanescentes durante a migração.

É seguro usar um curinga ou allow-duplicates na diretiva trusted-types?

Nenhuma das duas opções é adequada para produção. Um asterisco (*) como nome de policy permite qualquer nome único de policy, então um script injetado poderia registrar a própria policy e criar valores trusted. A palavra-chave 'allow-duplicates' permite que o código crie várias policies com o mesmo nome, de modo que um nome deixa de corresponder a uma única policy conhecida. Em vez disso, liste o nome exato de cada policy criada pelo seu código e pelas suas dependências.

Ainda posso usar eval() com Trusted Types em enforcement?

Sim. Adicione a palavra-chave 'trusted-types-eval' à sua CSP. Ela permite eval() e funções semelhantes apenas em navegadores que oferecem suporte a Trusted Types e aplicam a enforcement. Diferentemente de 'unsafe-eval', ela mantém essas funções bloqueadas em navegadores sem suporte a Trusted Types. Com a enforcement ativa, o código passado para eval() ainda precisa ser um TrustedScript ou uma string bruta que uma default policy converta em um. Caso contrário, a chamada lança um erro.

DevTools for the frontend

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

We use cookies to improve your experience. By using our site, you accept cookies.