innerHTML, its content alone decides whether text appears there or someone else's code runs. This is DOM-based cross-site scripting, DOM XSS for short, and it happens in the browser, often without the server ever seeing the malicious value. Trusted Types target exactly this point: with the directive require-trusted-types-for 'script' in the Content Security Policy, dangerous DOM interfaces stop accepting plain strings and only take values that have first passed through a policy you wrote. Since February 2026 the feature has been Baseline, meaning it is available in the current versions of all major browsers (MDN). This post shows how the lock works, why the rollout starts with report-only, how to read the violation reports by directive and when to switch to enforcement.DOM XSS: when a string turns into a program
In DOM XSS, a value from a source an attacker can influence flows into a browser interface that evaluates it as HTML, as script or as a script URL. Typical sources are the part of the address after the hash sign, query parameters, messages between windows via postMessage or fields from a JSON response. The evaluating interfaces are called sinks: innerHTML, outerHTML, insertAdjacentHTML, document.write, eval, setTimeout with a string as code or the src property of a script element. Because the part after the hash sign is not sent to the server at all, web server logs and server-side filters usually do not see such an attack.
Cross-site scripting as a whole remains the most dangerous weakness class in publicly reported vulnerabilities. In the 2025 CWE Top 25 analysis, CWE-79, the category for cross-site scripting, keeps its spot at the top of the list, as in the previous year (MITRE). The basis is 39,080 CVE records for vulnerabilities published between June 1, 2024 and June 1, 2025 (MITRE). The number of records mapped to CWE-79 grew by more than 3,000 (MITRE). The ranking combines the frequency and the average severity of the records. It covers every kind of cross-site scripting in software products, not only DOM XSS and not only websites.
A figure from Google from 2023 shows how large the share of the DOM variant can be. Before Trusted Types were adopted, more than half of the XSS reports to the company's vulnerability reward program were DOM XSS (Google). For all XSS reports combined, the program paid out $360,000 in 2018 (Google), and $95,000 in 2022 (Google). For Alphabet applications migrated to Trusted Types, Google reported zero XSS at that point (Google). These are statements by a single company about its own services, made in a proposal to the browser vendors. They show the direction, but they are not an independent survey.
The CWE list counts CVE records for software of every kind and weights them by frequency and severity; it does not measure how many websites are affected. For your website, this yields no percentage, but it does yield an order of work: first know where your code writes strings into sinks, then decide when the lock should take effect.
Why a CSP alone rarely stops DOM XSS
A Content Security Policy decides which code may run: from which sources scripts load, whether inline scripts and event handlers are allowed, whether eval is available. A strict policy without 'unsafe-inline' would indeed stop an injected onerror handler. In practice, policies are rarely that strict. The share of websites examined by the HTTP Archive that use a Content Security Policy rose from 18.5 to 21.9 percent in 2025 (HTTP Archive Web Almanac 2025). Among the CSP headers recorded that set script sources via script-src or default-src, 92 percent contain 'unsafe-inline' (HTTP Archive Web Almanac 2025), and 'unsafe-eval' appears in 77 percent (HTTP Archive Web Almanac 2025).
It is not quite as bad as the number sounds: if the same source list names a nonce or a hash, the browser ignores 'unsafe-inline', and the same applies next to 'strict-dynamic'. Nonces, however, appear only on approximately 20 percent, and 'strict-dynamic' only on approximately 10 percent (HTTP Archive Web Almanac 2025). Many of these policies therefore still allow injected inline handlers, and those handlers are the classic route by which a string written via innerHTML becomes a program.
Even a strict, nonce-based policy like the one described in configuring Content Security Policy correctly leaves a gap for DOM XSS. With 'strict-dynamic', any script that an already trusted script loads may run. If your own code sets script.src to an address derived from manipulable input, the CSP allows it. And a page whose HTML is rewritten via innerHTML can display falsified forms, links and text even when no script runs at all. Trusted Types therefore do not start with the code but with the value: they require every string to pass a check you define before it reaches the sink.
How Trusted Types work
Trusted Types consist of two parts: a JavaScript interface for creating policies, and two CSP directives that enforce and control their use. A policy is a named object with transformation functions, such as createHTML for HTML, createScript for script text and createScriptURL for script URLs. Whatever these functions return, the browser wraps in a dedicated type that only policies can create. Once the lock is active, sinks accept only these types. A plain string throws a TypeError, and the value does not reach the sink.
| Type | Used for | Example sinks |
|---|---|---|
| TrustedHTML | values parsed as HTML | innerHTML, outerHTML, insertAdjacentHTML, document.write, document.writeln, srcdoc of an iframe |
| TrustedScript | values executed as JavaScript | eval, new Function, setTimeout and setInterval with code as a string, text of a script element |
| TrustedScriptURL | addresses scripts are loaded from | src of a script element, Worker and SharedWorker, importScripts, registering a service worker |
The directive require-trusted-types-for 'script' turns on the lock for all three groups; the specification currently knows no value other than 'script'. The second directive, trusted-types, defines which policy names a page may create. If it contains only 'none', no policy may be created. A name that is already in use can be created a second time only with the keyword 'allow-duplicates'. Here is what this looks like in code, using a comment field whose content comes from an API:
// A named policy that only returns sanitized HTML
const policy = window.trustedTypes?.createPolicy('comment-html', {
createHTML: (input) => sanitizeHtml(input)
});
const target = document.querySelector('#comment');
const raw = await (await fetch('/api/comment/latest')).text();
// With the lock active, this line throws a TypeError:
// target.innerHTML = raw;
// Through the policy the value arrives, because it passed createHTML:
target.innerHTML = policy ? policy.createHTML(raw) : sanitizeHtml(raw);
// Plain text needs neither HTML nor a policy:
target.textContent = raw;It matters what Trusted Types do not do. The interface brings no sanitizer of its own; the developer writes the transformation. The lock ensures that a value passed through your function, not that this function works correctly. The gain lies in reviewability: instead of every place in the code where a string might flow into a sink, you only review the few policies.
A policy that returns its input unchanged satisfies the lock on paper and protects nothing. The specification explicitly warns that a lax default policy without checks defeats all the benefits of Trusted Types. Keep policies as narrow as possible, give them descriptive names and use the trusted-types directive to allow exactly those names.
In all current browsers since February 2026
Chromium browsers have supported Trusted Types for years; the other engines only followed in 2025 and 2026. With Safari 26.0, web developers can also use the interface on Apple devices (WebKit). Firefox 148 was released on February 24, 2026 (MDN) and has supported the Trusted Types API since then (MDN). Since then, MDN lists the directive require-trusted-types-for as Baseline 2026, meaning available in the current versions of all major browsers (MDN).
| Browser | Version with Trusted Types | Released on (web-features) |
|---|---|---|
| Chrome | 83 | 2020-05-19 |
| Edge | 83 | 2020-05-21 |
| Safari and Safari on iOS | 26 | 2025-09-15 |
| Firefox | 148 | 2026-02-24 |
The web-features project, on which the Baseline labels are based, expects the status “widely available” on August 24, 2028 (web-features). Until then, people with older browsers will keep visiting your website, for example on devices without current updates. There the trustedTypes object is missing, both directives are ignored, and there is neither a lock nor a report. Your code therefore has to work in both worlds: create policies only when window.trustedTypes exists, and without Trusted Types fall back to a safe way of writing rather than passing the string straight into the sink after all.
Firefox 148 also brought the HTML Sanitizer API with setHTML() (MDN). It sanitizes HTML on insertion and fits the idea behind Trusted Types: where a component has to display user HTML and setHTML() is available, the detour through a policy of your own falls away.
How widely Trusted Types are actually used on the web is hard to read. In the Web Almanac 2025, a single, identical Trusted Types header with a report path belonging to Android appears on more than 12 percent of mobile pages; the authors have no direct explanation for it (HTTP Archive Web Almanac 2025). In 2023, Google stated that about 60 percent of pages rendered by Chrome worldwide use Trusted Types, likely through embedded libraries of the company (Google), while around 14 percent of the traffic enforces the lock via CSP (Google). Both values say more about embedded services of large providers than about the policy of a typical company website.
Step 1: set report-only without blocking anything
The safe entry point is the observation variant of CSP. With the header Content-Security-Policy-Report-Only, the browser evaluates the directives but blocks nothing: every string that flows into a sink is still processed, and the browser sends a report to the address you specify. This is exactly the path the specification describes for adoption: monitor violations through the report-only header, refactor the code step by step and only then switch. Reports are generated by real page views, so they only cover pages and paths that visitors actually use.
Reporting-Endpoints: xictraq="https://api.xictraq.com/api/csp-report/<TOKEN>"
Content-Security-Policy: script-src 'nonce-{RANDOM}' 'strict-dynamic'; object-src 'none'; base-uri 'self'; report-uri https://api.xictraq.com/api/csp-report/<TOKEN>; report-to xictraq
Content-Security-Policy-Report-Only: require-trusted-types-for 'script'; trusted-types comment-html module-loader; report-uri https://api.xictraq.com/api/csp-report/<TOKEN>; report-to xictraqYour existing, enforced CSP stays unchanged. Both headers apply side by side: the first keeps blocking what it blocked before, the second only reports. If you do not send a CSP at all yet, you can start with a report-only header for Trusted Types alone; how the other headers fit together is covered in the post on HTTP security headers. The matching report-uri for your website and an example with the two headers that belong together, Reporting-Endpoints and Content-Security-Policy, are shown in the “CSP violation reports” panel in XICTRAQ®, described in the security header handbook.
The default policy is a special case. If you create a policy named default during monitoring, the browser calls it for every string that flows into a sink without a type. If it returns nothing, a violation occurs; in report-only mode the browser still uses the original value. This lets you log in the browser which places are affected without changing how the page behaves.
Once this post is published, Black Friday is just under a week away. A sale week with extra landing pages, campaign scripts and more visitors is a good period to collect reports, because rarely used pages and paths get visited too. It is the wrong time to switch to enforcement: an overlooked sink in a promotional widget would disable a feature in the middle of peak business. How to set alerts for the peak week is described in the post on adaptive response time alerts.
Step 2: read the reports by directive
A Trusted Types violation arrives as an ordinary CSP report, via report-uri in the classic format or via report-to in the Reporting API format. Two cases can be told apart by directive and blocked source. If a string flows into a sink, the report names the directive require-trusted-types-for and, as the blocked source, the catch-all value trusted-types-sink. In the sample, the browser writes the name of the sink and the first 40 characters of the value (W3C Trusted Types). If, on the other hand, creating a policy fails because its name is not allowed or already taken, the directive is trusted-types, the blocked source is trusted-types-policy, and the sample contains the first 40 characters of the policy name (W3C Trusted Types).
{
"csp-report": {
"document-uri": "https://www.shop.example.invalid/product/wool-coat",
"violated-directive": "require-trusted-types-for",
"effective-directive": "require-trusted-types-for",
"disposition": "report",
"blocked-uri": "trusted-types-sink",
"source-file": "https://www.shop.example.invalid/js/reviews.js",
"line-number": 118,
"script-sample": "Element innerHTML|<img src=x onerror=alert(1)>"
}
}In the “CSP violation reports” panel, XICTRAQ® groups incoming reports by directive, blocked source and page path and counts how often each group was reported. For Trusted Types this means: all sink violations on one page carry the same directive and the same catch-all value and therefore end up in one row with a counter, even if several places in the code are behind it. The row tells you on which page strings still flow into sinks and how often. Which sink and which line of code are affected, you then clarify in the browser: the securitypolicyviolation event delivers every violation with source file, line and sample, and static analysis tools for the source code find many occurrences before the code ever runs.
A string flowed into a sink without a type. The sample in the browser's report names the sink, such as Element innerHTML, and the beginning of the value; the row in the panel does not show it.
A script tried to create a policy whose name the trusted-types directive does not allow or that is already taken.
Classic CSP violations: a source the policy does not allow. They belong to your existing CSP, not to the Trusted Types rollout.
Where the violation occurred and how often. A high counter on a page with a lot of traffic is more urgent than a single case on a rarely visited subpage.
Sort the rows by who owns the code. Violations from your own code, you refactor. Violations from embedded scripts, such as a chat window, a consent banner or an A/B testing tool that writes variants into the page via innerHTML, you clarify with the respective vendor or replace the script. Why test variants in particular deserve attention in sale week is covered in the post on A/B tests in Black Week; the risks embedded scripts bring in general are described in the post on third-party scripts.
Step 3: fix violations and keep policies small
For every violation there are four options, in a fixed order from the cleanest to the last resort:
- Rewrite the code. Often the place does not need HTML at all. Text belongs in
textContent, new elements are created withcreateElementandappendChild. This removes the sink and with it the violation. - Use a library that produces Trusted Types. Some sanitization and template libraries return ready-made TrustedHTML values.
- Write your own named policy. For places that genuinely need HTML or a script URL, such as a preview field or a loader for modules from a fixed list. The policy checks narrowly: fixed addresses instead of patterns, sanitized HTML instead of passed-through input.
- Use the default policy as a transition. It catches every string that flows into a sink without a type, including from third-party code you cannot change right away. MDN recommends it only for the period in which legacy code is being refactored.
// Before: HTML assembled from a string
list.innerHTML += '<li>' + product.name + '</li>';
// After: no HTML sink, no violation
const item = document.createElement('li');
item.textContent = product.name;
list.appendChild(item);
// Script URLs only from a fixed list
const loader = trustedTypes.createPolicy('module-loader', {
createScriptURL: (url) => {
const allowed = ['/js/map.js', '/js/configurator.js'];
if (allowed.includes(url)) return url;
throw new TypeError('Script URL not allowed: ' + url);
}
});
script.src = loader.createScriptURL('/js/map.js');The trusted-types directive keeps your set of policies manageable. It lists the allowed names, for example trusted-types comment-html module-loader. If a script tries to create a policy with a different name, a violation occurs, and in enforcement mode the call fails. Especially with embedded scripts, this prevents third-party code from building its own policy that passes everything through unchanged.
Once the lock is active, according to web.dev only the code inside one of your policies can open a DOM XSS hole. Instead of every place where a string might flow into a sink, you review a handful of functions with descriptive names on every update. Subresource Integrity follows the same principle for embedded files: anchor trust in a small, reviewable place.
Step 4: enforce and keep monitoring
When for a few days no more violations come from your own code, only isolated cases traced back to browser extensions, make the switch: the directives move from the report-only header into the enforced Content-Security-Policy. From then on, a string in a sink throws a TypeError, and the affected part of the page stops working. Keep report-uri and report-to in place. The panel continues to accept reports in enforcement mode, so a new violation after an update shows up as a row instead of only surfacing as a silent malfunction. If something goes wrong, the way back is short: the two directives move back into the report-only header.
The XICTRAQ® security scan checks the Content-Security-Policy of your websites on a fixed schedule, as a header and as a meta tag, and evaluates it the way a browser applies it: whether 'unsafe-inline' in the effective script list actually takes effect or is neutralized by a nonce or 'strict-dynamic', and whether 'unsafe-eval' is allowed. A report-only header on its own earns no points in the security score because it enforces nothing; its directives do feed into the CSP analysis, as the handbook describes. If the score drops below the minimum you set in the notification settings, XICTRAQ® alerts you through the configured alert channels. Which headers a single page is currently sending is shown by the free security score check.
XICTRAQ® has no dedicated Trusted Types check. The two directives are not scored separately, the CSP wizard does not write them into the generated headers, and the panel shows grouped reports rather than a list of individual sinks. Whether a policy sanitizes properly cannot be measured from the outside; that remains a matter of code review.
Where Trusted Types reach their limits
- Server-side XSS. If the server assembles HTML from unchecked input, the malicious code arrives with the document, not through a sink. Context-aware escaping in the templates and a nonce-based CSP help here.
- Indirect sinks. MDN lists ways in which strings reach the DOM indirectly without any type check taking effect. The lock covers the direct interfaces, not every conceivable shortcut.
- Bugs in the policy. If a policy sanitizes incompletely, the hole remains, just in a known place. Trusted Types enforce processing but do not define which rules are safe.
- Deliberately malicious code. The specification sees Trusted Types as protection against developer mistakes, not as a defense against first-party code that actively tries to bypass the rules.
- Browser extensions. Extensions that inject scripts into pages can trigger reports during the report-only run that have nothing to do with your code. Sort out such isolated cases when reading the reports.
Trusted Types are therefore one building block among others. The cross-origin headers from the post on COOP, COEP and CORP separate windows and resources of foreign origin, the Permissions-Policy locks browser features such as camera and location, and the script integrity check reports from the Business plan upward when an embedded script changes.
Monitor Trusted Types now, enforce after sale week
The effort to get started is one additional header. If you set require-trusted-types-for 'script' in report-only mode now, you collect reports during the Black Friday week from exactly the pages and paths that otherwise get few visits, and afterwards decide calmly which sinks to refactor. The switch follows once nothing is reported from your own code anymore, and not on the day a sale starts.
The panel of the security scan groups the reports by directive and page, and the counters show where refactoring pays off most. After the switch, every change only needs a few policies to pass review, not every line that writes HTML into the page.
This article is based on: MDN Web Docs, “Content-Security-Policy: require-trusted-types-for directive”, “Trusted Types API” and “Firefox 148 release notes for developers”; W3C, “Trusted Types”, Working Draft of the Web Application Security Working Group dated October 7, 2026; web.dev, “Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types”; WebKit, “WebKit Features in Safari 26.0”; web-features explorer, entry “Trusted types”; HTTP Archive, Web Almanac 2025, Security chapter; MITRE, “2025 CWE Top 25 Most Dangerous Software Weaknesses” with methodology and analysis; Google, “Trusted Types” proposal for Interop 2024 from September 2023. Product details: XICTRAQ® handbook, security headers.
What are Trusted Types, in short?
innerHTML or eval accept only values that have first passed through a policy you define. The lock is turned on with the CSP directive require-trusted-types-for 'script'; a plain string then typically throws a TypeError.Doesn't a Content Security Policy already protect against XSS?
'unsafe-inline' stops many attacks. But it governs which code may run, not which values flow into sinks. In practice, many policies allow inline scripts, and with 'strict-dynamic' loaded code may run. Trusted Types typically complement the CSP at exactly this point; they do not replace it.Can the directive break my website?
Content-Security-Policy-Report-Only header. In this variant the browser blocks nothing and only reports what it would block.Which browsers support Trusted Types?
Does XICTRAQ® show Trusted Types violations?
report-uri from the “CSP violation reports” panel to your header, violations appear there grouped by directive, blocked source and page path; for Trusted Types usually as a require-trusted-types-for row with the catch-all value trusted-types-sink. XICTRAQ® does not offer a dedicated Trusted Types check with a list of individual sinks.When does a default policy make sense?
textContent.