← All posts

Migrating to Trusted Types, from Report-Only to trusted-types-eval

CentralCSP Team

CentralCSP ·

Last update:

Trusted Types is the part of a Content Security Policy (CSP) that closes DOM-based cross-site scripting (XSS). With it enforced, the DOM sinks that turn a string into markup or code (innerHTML, document.write, eval, the Function constructor and a few dozen others) refuse a plain string. They accept only typed objects produced by policies you wrote, so an injected string never reaches a sink.

This guide is the migration, in the order you would run it on a real app: turn enforcement on in Report-Only, register policies, fix the sinks the reports surface (including the ones your framework owns), deal with the eval sink using 'trusted-types-eval' instead of 'unsafe-eval', then enforce. For the related inline-script and string-to-code problems, see why you should never use unsafe-inline in CSP and unsafe-eval and how to remove it. The directive references are require-trusted-types-for and trusted-types.

What Trusted Types protects against

DOM XSS happens when client-side code passes attacker-controlled text into a sink that parses it as HTML or runs it as script. A classic case is element.innerHTML = location.hash. Server-side defenses never see it, because the dangerous assignment happens in the browser, after the page loads, from data the server may never have touched.

Trusted Types changes the rule at the sink. MDN groups the sinks in three families: HTML sinks such as Element.innerHTML and document.write(), JavaScript sinks such as eval() and HTMLScriptElement.text, and script URL sinks such as HTMLScriptElement.src. Under enforcement each one accepts only a TrustedHTML, TrustedScript or TrustedScriptURL, and the only way to make one is to run a string through a registered policy function. That gives you one auditable place where every value crossing into a sink is checked, and it makes the unsafe pattern fail loudly instead of executing.

Step 1: turn enforcement on, in Report-Only

One directive switches Trusted Types on. require-trusted-types-for takes the single value 'script':

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

Enforced, that header makes every covered sink throw a TypeError when it receives a plain string, and emit a violation report. The directive has no fallback to default-src, so it only applies when you set it explicitly.

Switching it on directly on a live site breaks anything that writes a raw string to a sink, which on most apps is many places you do not know about yet. So start on the Content-Security-Policy-Report-Only header, which blocks nothing and reports every write that enforcement would have rejected:

Content-Security-Policy-Report-Only:
  require-trusted-types-for 'script';
  trusted-types myPolicy;
  report-to csp-endpoint
Reporting-Endpoints: csp-endpoint="https://<Endpoint-ID>.report.centralcsp.com"

Trusted Types violations do not introduce a new report type. They arrive as standard CSP violation reports at the same endpoint, with the same effectiveDirective, sample and sourceFile fields as any other blocked script; see the CSP violation report fields. Each report is one sink to fix.

Step 2: allowlist and register your policies

Enforcement on its own would block your own code too, because your code also writes to those sinks. The trusted-types directive names the policies the page may create. A policy is a small object with createHTML, createScript or createScriptURL functions that vet a string and return the typed value.

Content-Security-Policy: trusted-types myPolicy

The tokens worth knowing:

  • 'none' forbids creating any policy, the strictest setting, for when no code writes to a sink directly any more.
  • * allows any unique policy name, less strict but convenient during the migration.
  • 'allow-duplicates' permits registering the same name more than once, which some bundlers and micro-frontends need.
  • default is the reserved name of the default policy, covered below.

Then register the policy and route every sink write through it:

// The name must be listed in the trusted-types directive.
const policy = window.trustedTypes.createPolicy("myPolicy", {
  createHTML: (input) => {
    // Do the real sanitization here. Returning input untouched is not safe;
    // the policy is only as strong as the check inside it.
    return sanitize(input);
  },
});

element.innerHTML = userInput; // throws TypeError under enforcement
element.innerHTML = policy.createHTML(userInput); // accepted

The value is the chokepoint, not the assignment. Every string that becomes markup passes through createHTML, so you have one function to review, test and harden instead of auditing every innerHTML in the codebase.

The default policy, for code you cannot edit

A policy registered with the name "default" runs automatically on any plain string passed to a sink. That is how you retrofit Trusted Types onto third-party or legacy code you cannot change. MDN recommends using it only while you move legacy code to explicit Trusted Types, and notes that if the default policy returns null or undefined, the sink throws a TypeError. Keep its checks strict: a permissive default policy widens the surface back out.

Step 3: let your framework create the typed values

Most apps do not call sinks directly; a framework does it for them. The migration work is then about allowlisting the policies the framework registers.

Angular

Angular has built-in Trusted Types support. Its sanitization runs through policies named angular for the framework and angular#bundler for the build output:

Content-Security-Policy:
  require-trusted-types-for 'script';
  trusted-types angular angular#bundler

Depending on your build, Angular may also register angular#unsafe-bypass, angular#unsafe-jit or angular#unsafe-upgrade, so read the Report-Only reports and allowlist the ones your build actually uses. If your own code calls sinks outside Angular's APIs, register an extra policy and add its name.

React with DOMPurify

React escapes text by default, but dangerouslySetInnerHTML writes straight to the DOM, so it is the sink to guard. DOMPurify can return a Trusted Types value directly with the RETURN_TRUSTED_TYPE option:

import DOMPurify from "dompurify";

// DOMPurify creates a Trusted Types policy named "dompurify" internally.
const clean = DOMPurify.sanitize(dirtyHtml, { RETURN_TRUSTED_TYPE: true });

<div dangerouslySetInnerHTML={{ __html: clean }} />;
Content-Security-Policy:
  require-trusted-types-for 'script';
  trusted-types dompurify myPolicy

The same pattern works for any framework with a raw-HTML sink: sanitize with DOMPurify in RETURN_TRUSTED_TYPE mode, pass the typed result to the sink, and allowlist dompurify.

Step 4: handle eval with trusted-types-eval

The eval family is usually the last group of reports standing. When a policy sets script-src (or falls back to default-src), the browser already blocks the functions that turn strings into code:

  • eval()
  • new Function() and the Function constructor
  • the string form of setTimeout() and setInterval()

The traditional way back in is 'unsafe-eval', which re-enables string compilation for every string, with or without Trusted Types. 'trusted-types-eval' is the safer replacement. It is a script-src keyword (not a value of require-trusted-types-for or trusted-types), and MDN describes it as allowing eval() and similar functions "only when Trusted Types are supported and enforced", with a TrustedScript passed instead of a string.

The practical difference shows on browsers that do not support Trusted Types. With 'unsafe-eval', they run any string you hand to eval(). With 'trusted-types-eval', nothing lets eval through, so the sink stays blocked. That is why MDN says 'trusted-types-eval' must be used instead of 'unsafe-eval' when you use these methods with Trusted Types.

Swap the keyword in the policy you are migrating:

Content-Security-Policy:
-  script-src 'self' 'unsafe-eval';
+  script-src 'self' 'trusted-types-eval';
  require-trusted-types-for 'script';
  trusted-types myPolicy

Then give your policy a createScript and compile through it:

const policy = window.trustedTypes.createPolicy("myPolicy", {
  createScript: (input) => {
    // Validate or transform input here. Returning it as-is is not safe.
    return input;
  },
});

eval('a = "hello"'); // throws EvalError: plain strings stay blocked
eval(policy.createScript('a = "hello"')); // runs

Two things to keep clear. 'trusted-types-eval' does not enable Trusted Types on its own; enforcement still comes from require-trusted-types-for. And a "default" policy with a createScript function runs on every plain string handed to an eval sink, which re-permits plain-string eval() across the page. Use that deliberately, because it moves you back toward 'unsafe-eval' behavior.

Should you keep eval at all?

'trusted-types-eval' is safer than 'unsafe-eval', but the safest policy has neither. MDN's own note is that Trusted Types make sure input passes through a transformation function, not that the transformation makes it safe. A reasonable order of preference:

  1. Remove the eval. Replace dynamic string compilation with JSON.parse, a lookup table or ordinary code wherever you can.
  2. Allow the specific scripts you trust with a nonce or a hash in script-src, rather than opening eval.
  3. If you genuinely need eval for now, use 'trusted-types-eval' with require-trusted-types-for 'script' and a strict policy, as a temporary step while you remove the dependency.

Step 5: enforce, and keep the reports on

When Report-Only is quiet, meaning every remaining report is noise or something you are happy to block, move the same directives to the enforcing Content-Security-Policy header and keep report-to on it:

Content-Security-Policy:
  script-src 'self' 'trusted-types-eval';
  require-trusted-types-for 'script';
  trusted-types myPolicy dompurify;
  report-to csp-endpoint

Enforced reports matter as much as the Report-Only ones: a new dependency that writes a raw string to innerHTML shows up as a violation instead of a silent breakage. CentralCSP ingests those reports and groups them by page and sink, so you can see which parts of the app still write raw strings or rely on eval before and after you enforce. You can check a draft policy for eval keywords and other weak spots with the free CSP evaluator before you ship it.

Browser support today

Trusted Types is Baseline 2026: MDN marks it as working across the latest browsers since February 2026. Chromium has shipped it for years; Firefox and Safari are the recent additions, so older versions of those browsers still ignore it.

The behavior degrades safely. A browser that does not enforce Trusted Types ignores the directives and runs the page as before, so shipping them does not break older clients; you only miss the protection there. MDN also documents a one-line "tinyfill" (trustedTypes = { createPolicy: (n, rules) => rules } when trustedTypes is undefined) so the same policy code runs everywhere, and notes that once your code has been tested on a supporting browser with require-trusted-types-for, the tinyfill gives the same protection in browsers that lack the API.

'trusted-types-eval' is newer than the Trusted Types directives. Browser compatibility data lists it in Chrome 145, Firefox 148 and Safari 26, so the current version of every engine understands it. A browser that does not recognize the keyword leaves eval blocked, which is the failure mode you want.

Frequently asked questions

How do I enable Trusted Types?

Add require-trusted-types-for 'script' to your CSP to turn enforcement on, and a trusted-types directive listing the policy names your code creates. Route every sink write through one of those policies, and start on the Content-Security-Policy-Report-Only header so you see every sink before you block one.

What does require-trusted-types-for do?

It makes the browser enforce Trusted Types at script-related DOM sinks such as innerHTML, document.write and eval. Its only value is 'script'. With it set, those sinks reject a plain string and accept only typed objects produced by your registered policies.

What is the difference between unsafe-eval and trusted-types-eval?

'unsafe-eval' allows eval() and Function() for any string, on every browser. 'trusted-types-eval' allows them only when Trusted Types are enforced and the argument is a TrustedScript from one of your policies; on browsers without Trusted Types, eval stays blocked.

What is the default Trusted Types policy?

A policy registered with the reserved name "default". The browser runs it on any plain string passed to a sink, which retrofits Trusted Types onto code you cannot change. Use it during the migration and keep its checks strict.

Can I use Trusted Types with React?

Yes. Guard dangerouslySetInnerHTML by sanitizing with DOMPurify in RETURN_TRUSTED_TYPE mode, which returns a TrustedHTML the sink accepts, and allowlist the dompurify policy name.

The takeaway

Migrating to Trusted Types is two directives and one habit: require-trusted-types-for 'script' turns enforcement on, trusted-types allowlists the policies that may create typed values, and every sink write goes through a policy you can audit. Run it in Report-Only, fix the sinks the reports surface, let Angular or DOMPurify handle the framework sinks, replace 'unsafe-eval' with 'trusted-types-eval' for the eval you cannot remove yet, then enforce with reporting still on.

Sources