12k
All articles

Bloquear DOM XSS en React con Trusted Types

Vea cómo React 19.3 habilita Trusted Types contra XSS en el DOM con una política DOMPurify, encabezados CSP y una implementación gradual en modo de informe.

OpenReplay Team
OpenReplay Team
Bloquear DOM XSS en React con Trusted Types

React 19.3 pasa los objetos de Trusted Types directamente al DOM. Esto permite que una aplicación React aplique require-trusted-types-for 'script' y haga pasar todo el marcado de dangerouslySetInnerHTML por una política basada en DOMPurify.

Hasta esta versión, esa configuración solía fallar. Sanitizabas el HTML de tu CMS, activabas la directiva CSP y React volvía a convertir en cadena tu valor cuidadosamente tipado.

Este artículo cubre el cambio en React, las cabeceras CSP, un módulo de política que también funciona en navegadores sin la API y un despliegue que empieza en modo report-only. Para los fundamentos de XSS, consulta cómo prevenir XSS en contenido generado por usuarios.

Puntos clave

  • Antes de React 19.3, React convertía los valores en cadenas con '' + value. Por eso, un objeto TrustedHTML pasado a dangerouslySetInnerHTML llegaba a innerHTML como una cadena normal, y un navegador con la política aplicada lo rechazaba.
  • Con require-trusted-types-for 'script', asignar una cadena simple a un sink de inyección como innerHTML lanza un TypeError.
  • Trusted Types no sanitiza nada. Obliga a que el HTML llegue al sink a través de una política escrita por ti, y es DOMPurify, dentro de esa política, quien hace la limpieza.
  • Despliega primero Content-Security-Policy-Report-Only, corrige cada sink reportado, añade los nombres de tus políticas a la lista de permitidos con trusted-types y, después, aplica la política.
  • Los navegadores sin Trusted Types no aplican ninguna restricción, así que el sanitizador de tu política tiene que ejecutarse en cada llamada.

¿Qué ha cambiado en React 19.3?

React 19.3 (publicado el 9 de septiembre de 2026) pasa los valores TrustedHTML, TrustedScript y TrustedScriptURL al DOM sin convertirlos. Así, el navegador puede comprobar que los ha generado una política de Trusted Types.

Las versiones anteriores convertían los valores en cadenas con '' + value antes de entregarlos a las APIs del DOM. En consecuencia, un objeto TrustedHTML pasado a dangerouslySetInnerHTML llegaba a innerHTML como una cadena normal, y un navegador con la política aplicada lo rechazaba. El anuncio de la versión usa innerHTML como sink de ejemplo. dangerouslySetInnerHTML, que escribe en innerHTML, ahora conserva el objeto de confianza. Esta misma versión también estabilizó las refs de Fragment.

¿Cómo bloquea Trusted Types el DOM XSS?

La API de Trusted Types cierra los sinks de inyección a las cadenas sin procesar. Una vez aplicada, sinks como innerHTML o el src de un script solo aceptan objetos tipados creados por una política con nombre.

Tipo de confianzaCategoría de sinkSink de ejemplo
TrustedHTMLAnálisis de HTMLElement.innerHTML
TrustedScriptTexto de scripteval()
TrustedScriptURLCarga de scriptsHTMLScriptElement.src

Trusted Types no limpia ningún marcado por sí mismo. Lo que garantiza es que todo valor que llega a un sink ha pasado por una función de política, y es en esa función donde DOMPurify hace el trabajo. Esto cambia el modelo de seguridad: la sanitización deja de depender de que cada desarrollador se acuerde de aplicarla en cada punto de llamada y pasa a ser algo que impone el navegador.

Configurar la cabecera Content-Security-Policy

Trusted Types se activa con la directiva CSP require-trusted-types-for 'script'. Empieza enviando esa directiva en Content-Security-Policy-Report-Only. En ese modo, el navegador reporta las infracciones, pero deja que el código se siga ejecutando.

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

Añade un endpoint de reporte con la directiva report-to para que el navegador envíe cada sink infractor a tu colector en lugar de limitarse a registrarlo en la consola. Cuando dejen de llegar reportes, cambia a la cabecera que aplica la política:

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

require-trusted-types-for hace que las asignaciones de cadenas a los sinks lancen una excepción. trusted-types enumera los nombres de política permitidos, y trustedTypes.createPolicy() lanza una excepción si lo llamas con un nombre que no figura en la lista. Envíalas como cabeceras de respuesta: los navegadores no admiten la cabecera report-only ni la directiva report-to en una etiqueta <meta>.

Crear una política que envuelva DOMPurify

En una aplicación React, crea la política de Trusted Types una sola vez, en el ámbito del módulo, e impórtala donde la necesites. createPolicy() lanza un TypeError ante un nombre duplicado, salvo que 'allow-duplicates' figure en la directiva trusted-types. Por eso, el cuerpo de un componente no es el lugar adecuado para crearla: React vuelve a renderizar los componentes y StrictMode los invoca dos veces.

// 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 devuelve una cadena sanitizada y el navegador la envuelve en un TrustedHTML. Pasar TRUSTED_TYPES_POLICY: null evita que DOMPurify cree su propia política interna dompurify, de modo que la lista de permitidos solo necesita app-html. No uses RETURN_TRUSTED_TYPE: true dentro de createHTML, porque el callback debe devolver una cadena simple.

El objeto de respaldo aplica la idea del tinyfill de MDN de forma adaptada a los módulos ES. Donde falta la API, createPolicy devuelve tu objeto de reglas sin cambios, así que htmlPolicy.createHTML() sigue ejecutando DOMPurify y devuelve una cadena. El flujo de código es el mismo en todas partes. Además, como el respaldo es local, el módulo se importa sin errores durante el renderizado en servidor, donde trustedTypes es undefined. DOMPurify necesita una implementación del DOM para sanitizar en el servidor; su README explica cómo configurarla.

DOMPurify también ofrece un atajo: llamar a DOMPurify.sanitize(dirty, { RETURN_TRUSTED_TYPE: true }) sin una política propia. Devuelve un TrustedHTML donde hay soporte, y basta con añadir dompurify a la lista de permitidos (trusted-types app-html dompurify).

Usar la política con dangerouslySetInnerHTML

Con React 19.3 o posterior, coloca la salida de la política en __html y React pasará el objeto TrustedHTML a innerHTML sin modificarlo.

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

En modo report-only, esa línea aparece como un reporte de infracción. Con la política aplicada, lanza una excepción.

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

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

Haz pasar toda la salida del CMS, de markdown y de texto enriquecido por RichText (o por una llamada directa a htmlPolicy.createHTML()). Si más adelante buscas __html: con grep, cada coincidencia debería estar junto a una llamada a la política.

Desplegar Trusted Types de forma segura

Un despliegue seguro de Trusted Types tiene cuatro fases: solo reportar, corregir cada sink reportado, añadir los nombres de tus políticas a la lista de permitidos y, por último, aplicar la política.

  1. Despliega Content-Security-Policy-Report-Only: require-trusted-types-for 'script' con un endpoint de reporte.
  2. Corrige cada sink reportado haciéndolo pasar por htmlPolicy, o sustitúyelo por un sink que no necesite valores de confianza, como textContent.
  3. Enumera en trusted-types cada nombre de política que creen tu código y tus dependencias.
  4. Cambia a la cabecera Content-Security-Policy que aplica la política.

Si hay código de terceros que sigue asignando cadenas y todavía no puedes corregirlo, una política llamada default puede servir de puente temporal. Con la política aplicada, el navegador le entrega cada cadena sin procesar que llega a un sink. MDN recomienda usarla solo durante la migración de código heredado.

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

La comprobación de soporte evita que el módulo lance excepciones en navegadores sin la API y durante el renderizado en servidor.

Añade default a trusted-types mientras exista esta política. Cuando dejen de aparecer sus advertencias, elimina tanto la política como la entrada de la lista de permitidos.

¿Qué ocurre en los navegadores sin Trusted Types?

Los navegadores sin Trusted Types no aplican ninguna restricción. En ellos, el sanitizador de tu política es lo único que se interpone entre el HTML no confiable y el DOM. MDN clasifica window.trustedTypes como Baseline 2026, disponible desde febrero de 2026, así que las versiones de navegador más antiguas presentes en tu tráfico no lo tendrán.

El respaldo definido en el ámbito del módulo se encarga de esto. Los navegadores sin soporte ignoran la cabecera, pero siguen ejecutando DOMPurify.sanitize() en cada llamada. Por eso la política debe sanitizar siempre y nunca devolver su entrada sin cambios.

Conclusión

React 19.3 elimina la conversión a cadena que antes rompía Trusted Types, de modo que dangerouslySetInnerHTML ya puede transportar HTML generado por una política cuyo uso impone el navegador. Despliega primero la cabecera report-only, haz que todas las asignaciones a __html pasen por una única política basada en DOMPurify y aplica la política cuando dejen de llegar reportes. Después, aplica la misma disciplina en el lado del servidor con estas buenas prácticas de seguridad para APIs.

Preguntas frecuentes

¿Qué ocurre si una política default de Trusted Types devuelve null o undefined?

El navegador lanza un TypeError en el sink y la asignación no se produce. Una política default que devuelve null o undefined no deja pasar el valor: falla de forma segura y bloquea la escritura en lugar de dejar pasar la cadena original. Una política default que devuelva null para cualquier entrada es, además, una forma útil de localizar las asignaciones de cadenas que queden pendientes durante la migración.

¿Es seguro usar un comodín o allow-duplicates en la directiva trusted-types?

Ninguna de las dos opciones es recomendable en producción. Un asterisco (*) como nombre de política permite cualquier nombre de política único, por lo que un script inyectado podría registrar su propia política y crear valores de confianza. La palabra clave 'allow-duplicates' permite crear varias políticas con el mismo nombre, de modo que un nombre deja de corresponder a una única política conocida. En su lugar, enumera el nombre exacto de cada política que creen tu código y tus dependencias.

¿Puedo seguir usando eval() con Trusted Types aplicado?

Sí. Añade la palabra clave 'trusted-types-eval' a tu CSP. Permite eval() y funciones similares solo en los navegadores que admiten y aplican Trusted Types. A diferencia de 'unsafe-eval', mantiene esas funciones bloqueadas en los navegadores sin soporte para Trusted Types. Con la política aplicada, el código que se pasa a eval() debe seguir siendo un TrustedScript, o una cadena sin procesar que una política default convierta en uno. De lo contrario, la llamada lanza una excepción.

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.