Repository: mdn/content
Pull request #37917: Expand trusted types guidance
Author: login: wbamberg
Labels: name: Content:WebAPI
description: Web API docs
name: size/m
description: [PR only] 51-500 LoC changed
Created: 2025-02-02T07:49:46Z | Merged: 2025-03-10T22:50:18Z

I had thought to defer updates to the trusted types docs until it ships cross-browser, but given conversations like https://github.com/w3c-cg/swag/pull/9#discussion_r1931309886 and our general desire to talk about this API, I thought it was worth expanding on things a little now.

We should think of this PR as a stop-gap though: I still think we should revisit these docs, write a proper guide, and refresh all the API pages, when the API ships in Firefox or Safari.

This PR expands the [Trusted Types API overview page](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) in two ways:
- explain better about enforcement using a CSP
- explain about polyfills, since people can get the benefit of this API cross-browser now

I also updated the rest of the section to be clearer about what the API actually does and how it connects with XSS - I thought things like "lock down the insecure parts of the DOM API" weren't very meaningful.

I hope I understood the bit about polyfills!

@aaronshim, @lukewarlow 


Diff:
diff --git a/files/en-us/web/api/trusted_types_api/index.md b/files/en-us/web/api/trusted_types_api/index.md
index b81cb4594d74338..9b70d972e888434 100644
--- a/files/en-us/web/api/trusted_types_api/index.md
+++ b/files/en-us/web/api/trusted_types_api/index.md
@@ -8,30 +8,185 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a user-specified transformation function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks. Most commonly the transformation function [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+The Trusted Types API distinguishes three sorts of injection sinks:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
+- **HTML sinks**: APIs that interpret their input as HTML, such as {{domxref("Element.innerHTML")}} or {{domxref("Document.write()", "document.write()")}}. These APIs could execute JavaScript if it is embedded in the HTML, for example in {{htmlelement("script")}} tags or event handler attributes.
+- **JavaScript sinks**: APIs that interpret their input as JavaScript, such as {{jsxref("Global_Objects/eval", "eval()")}} or {{domxref("HTMLScriptElement.text")}}.
+- **JavaScript URL sinks**: APIs that interpret their input as the URL of a script, such as {{domxref("HTMLScriptElement.src")}}.
 
-### Injection Sinks
+One of the main defenses against DOM-based XSS attacks is to ensure that input is made safe before being passed to an injection sink.
 
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
+In the Trusted Types API, a developer defines a _policy object_, which contains methods that transform input bound for an injection sink so as to make it safe. The policy can define different methods for the different types of sink:
 
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
-- Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
-- Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
-- Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
+- For HTML sinks, the transformation function typically [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input, for example by using a library like [DOMPurify](https://github.com/cure53/DOMPurify).
+- For JavaScript and JavaScript URL sinks, the policy may turn off the sinks entirely or allow certain predefined inputs (for example, specific URLs).
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+The Trusted Types API will then ensure that input is passed through the appropriate transformation function before being passed into the sink.
 
-### Trusted Type Policies
+That is, the API enables you to define your policy in one place and then be assured that any data passed to an injection sink has been passed through the policy.
 
-A policy is a factory for Trusted Types. Web developers can specify a set of policies used for the creation of typed objects which form the trusted codebase for valid Trusted Type objects.
+> [!NOTE]
+>
+> The Trusted Types API does _not_ itself supply a policy or any transformation functions: the developer defines their own policy, which contains the transformations that they wish to apply.
+
+The API has two main parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The `trustedTypes` global property, available in both {{domxref("Window.trustedTypes", "Window")}} and {{domxref("WorkerGlobalScope.trustedTypes", "Worker")}} contexts, is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a transformation function.
+- Trusted type objects represent data that has been through the policy, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to the different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL to a script.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a transformation function.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+In order to enforce that a trusted type must always be passed, you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP).
+With this directive set, passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting.
+
+### The default policy
+
+In the Trusted Types API, you can define a _default policy_. This helps you find any places in your code where you're still passing strings into injection sinks, so you can rewrite the code to create and pass trusted types instead.
+
+If you create a policy named `"default"`, and your CSP enforces the use of trusted types, then any string argument passed into injection sinks will be automatically passed to this policy. For example, suppose we create a policy like this:
+
+```js
+trustedTypes.createPolicy("default", {
+  createHTML: (value) => {
+    console.log("Please refactor this code");
+    return sanitize(value);
+  },
+});
+```
+
+With this policy, if your code assigns a string to `innerHTML`, the browser will call the policy's `createHTML()` method and assign its result to the sink:
+
+```js
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput;
+// Logs "Please refactor this code"
+// Assigns the result of sanitize(userInput)
+```
+
+If the default policy returned `null` or `undefined`, then the browser will throw a `TypeError` when assigning the result to the sink:
+
+```js
+trustedTypes.createPolicy("default", {
+  createHTML: (value) => {
+    console.log("Please refactor this code");
+    return null;
+  },
+});
+
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput;
+// Logs "Please refactor this code"
+// Throws a TypeError
+```
+
+> [!NOTE]
+> It's recommended that you use the default policy only while you are transitioning from legacy code that passes input directly to injection sinks, to code that uses trusted types explicitly.
+
+### Cross-browser support for trusted types
+
+The Trusted Types API is not yet available in all modern browsers, but it is usable everywhere today thanks to [compatibility aids created by the W3C](https://github.com/w3c/trusted-types/tree/main?tab=readme-ov-file#polyfill).
+
+- The [_full_ polyfill](https://github.com/w3c/trusted-types/blob/main/src/polyfill/full.js) defines the JavaScript API, attempts to infer the CSP from the current document, and enforces the use of trusted types based on the inferred CSP.
+- The [_API only_ polyfill](https://github.com/w3c/trusted-types/blob/main/src/polyfill/api_only.js) defines only the JavaScript API, and does not include the ability to enforce the use of trusted types using a CSP.
+
+As well as these two polyfills, the W3C provides what it calls a _tinyfill_, which we'll explain in more detail below.
+
+Note that as long as you have tested your code on a supporting browser with CSP enforcement enabled, then you don't need to use the _full polyfill_ above on other browsers — you can get the same benefits using the _API only polyfill_ or the _tinyfill_.
+
+This is because the enforcement forces you to refactor your code to ensure that all data is passed through the Trusted Types API (and therefore has been through a sanitization function) before being passed to an injection sink.
+If you then run the refactored code in a different browser without enforcement, it will still go through the same code paths, and give you the same protection.
+
+#### Trusted Types tinyfill
+
+In this section we'll look at how the trusted types tinyfill can protect a website, even though it doesn't add support for trusted types at all.
+
+The trusted types tinyfill is just this:
+
+```js
+if (typeof trustedTypes == "undefined")
+  trustedTypes = { createPolicy: (n, rules) => rules };
+```
+
+It provides an implementation of `trustedTypes.createPolicy()` which just returns the [`policyOptions`](/en-US/docs/Web/API/TrustedTypePolicyFactory/createPolicy#policyoptions) object it was passed. The `policyOptions` object defines sanitization functions for data, and these functions are expected to return strings.
+
+With this tinyfill in place, suppose we create a policy:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+In browsers that support trusted types, this will return a `TrustedTypePolicy` which will create a `TrustedHTML` object when we call `policy.createHTML()`. The `TrustedHTML` object can then be passed to an injection sink, and we can enforce that the sink received a trusted type, rather than a string.
+
+In browsers that don't support trusted types, this code will return an object with a `createHTML()` function that sanitizes its input and returns it as a string. The sanitized string can then be passed to an injection sink.
+
+```js
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+// In supporting browsers, trustedHTML is a TrustedHTML object.
+// In non-supporting browsers, trustedHTML is a string.
+
+element.innerHTML = trustedHTML;
+// In supporting browsers, this will throw if trustedHTML
+// is not a TrustedHTML object.
+```
+
+Either way, the injection sink gets sanitized data, and because we could enforce the use of the policy in the supporting browser, we know that this code path goes through the sanitization function in the non-supporting browser, too.
 
 ## Interfaces
 
diff --git a/files/en-us/web/api/trustedhtml/index.md b/files/en-us/web/api/trustedhtml/index.md
index cd6cf14f6aa32ce..57915c3ba12f0e3 100644
--- a/files/en-us/web/api/trustedhtml/index.md
+++ b/files/en-us/web/api/trustedhtml/index.md
@@ -7,7 +7,7 @@ browser-compat: api.TrustedHTML
 
 {{APIRef("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **`TrustedHTML`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks) that will render it as HTML. These objects are created via {{domxref("TrustedTypePolicy.createHTML()")}} and therefore have no constructor.
+The **`TrustedHTML`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage) that will render it as HTML. These objects are created via {{domxref("TrustedTypePolicy.createHTML()")}} and therefore have no constructor.
 
 The value of a `TrustedHTML` object is set when the object is created and cannot be changed by JavaScript as there is no setter exposed.
 
diff --git a/files/en-us/web/api/trustedscript/index.md b/files/en-us/web/api/trustedscript/index.md
index aa347c85fcc5506..019a1b6199bb96c 100644
--- a/files/en-us/web/api/trustedscript/index.md
+++ b/files/en-us/web/api/trustedscript/index.md
@@ -7,7 +7,7 @@ browser-compat: api.TrustedScript
 
 {{APIRef("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **`TrustedScript`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string with an uncompiled script body that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks) that might execute the script. These objects are created via {{domxref("TrustedTypePolicy.createScript","TrustedTypePolicy.createScript()")}} and therefore have no constructor.
+The **`TrustedScript`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string with an uncompiled script body that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage) that might execute the script. These objects are created via {{domxref("TrustedTypePolicy.createScript","TrustedTypePolicy.createScript()")}} and therefore have no constructor.
 
 The value of a **TrustedScript** object is set when the object is created and cannot be changed by JavaScript as there is no setter exposed.
 
diff --git a/files/en-us/web/api/trustedscript/tostring/index.md b/files/en-us/web/api/trustedscript/tostring/index.md
index 1da6cd48b420679..6362aceb73f451f 100644
--- a/files/en-us/web/api/trustedscript/tostring/index.md
+++ b/files/en-us/web/api/trustedscript/tostring/index.md
@@ -8,7 +8,7 @@ browser-compat: api.TrustedScript.toString
 
 {{APIRef("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks).
+The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may be safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage).
 
 ## Syntax
 
diff --git a/files/en-us/web/api/trustedscripturl/index.md b/files/en-us/web/api/trustedscripturl/index.md
index d22ec4629e05c97..6d321edda8c7f16 100644
--- a/files/en-us/web/api/trustedscripturl/index.md
+++ b/files/en-us/web/api/trustedscripturl/index.md
@@ -7,7 +7,7 @@ browser-compat: api.TrustedScriptURL
 
 {{APIRef("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **`TrustedScriptURL`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks) that will parse it as a URL of an external script. These objects are created via {{domxref("TrustedTypePolicy.createScriptURL","TrustedTypePolicy.createScriptURL()")}} and therefore have no constructor.
+The **`TrustedScriptURL`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage) that will parse it as a URL of an external script. These objects are created via {{domxref("TrustedTypePolicy.createScriptURL","TrustedTypePolicy.createScriptURL()")}} and therefore have no constructor.
 
 The value of a `TrustedScriptURL` object is set when the object is created and cannot be changed by JavaScript as there is no setter exposed.
 
diff --git a/files/en-us/web/api/trustedscripturl/tostring/index.md b/files/en-us/web/api/trustedscripturl/tostring/index.md
index c8ba90514d9cf9d..c6b2ecd1b02c49a 100644
--- a/files/en-us/web/api/trustedscripturl/tostring/index.md
+++ b/files/en-us/web/api/trustedscripturl/tostring/index.md
@@ -8,7 +8,7 @@ browser-compat: api.TrustedScriptURL.toString
 
 {{APIRef("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **`toString()`** method of the {{domxref("TrustedScriptURL")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks).
+The **`toString()`** method of the {{domxref("TrustedScriptURL")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage).
 
 ## Syntax
 
diff --git a/files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.md b/files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.md
index dbd72ec80cb4272..631fb38cf6e2a51 100644
--- a/files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.md
+++ b/files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.md
@@ -10,16 +10,6 @@ browser-compat: api.TrustedTypePolicyFactory.createPolicy
 
 The **`createPolicy()`** method of the {{domxref("TrustedTypePolicyFactory")}} interface creates a {{domxref("TrustedTypePolicy")}} object that implements the rules passed as `policyOptions`.
 
-### The default policy
-
-In Chrome a policy with a name of "default" creates a special policy that will be used if a string (rather than a Trusted Type object) is passed to an injection sink. This can be used in a transitional phase while moving from an application that inserted strings into injection sinks.
-
-> [!NOTE]
-> The above behavior is not yet settled in the specification and may change in future.
-
-> [!WARNING]
-> A lax default policy could defeat the purpose of using Trusted Types, and therefore should be defined with strict rules to ensure it cannot be used to run dangerous code.
-
 ## Syntax
 
 ```js-nolint
@@ -54,6 +44,8 @@ A {{domxref("TrustedTypePolicy")}} object.
 
 ## Examples
 
+### Creating a policy for HTML sinks
+
 The below code creates a policy with the name `"myEscapePolicy"` with a function defined for `createHTML()` which sanitizes HTML.
 
 ```js
@@ -64,9 +56,9 @@ const escapeHTMLPolicy = trustedTypes.createPolicy("myEscapePolicy", {
 
 ### Creating a default policy
 
-On a site where Trusted Types are enforced via a Content Security Policy with the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/require-trusted-types-for) directive set to `script`, any injection script that accepts a script expects a Trusted Type object. In the case that a string is inserted instead, the following default policy will be used.
+On a site where Trusted Types are enforced via a Content Security Policy with the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/require-trusted-types-for) directive set to `script`, any injection script that accepts a script expects a Trusted Type object. In the case that a string is inserted instead, a [default policy](/en-US/docs/Web/API/Trusted_Types_API#the_default_policy) will be used.
 
-The policy logs a message to the console to remind the developer to refactor this part of the application to use a Trusted Type object. It also appends details of the use of the default policy, type, and injection sink to the returned value.
+The default policy logs a message to the console to remind the developer to refactor this part of the application to use a Trusted Type object. It also appends details of the use of the default policy, type, and injection sink to the returned value.
 
 ```js
 trustedTypes.createPolicy("default", {
diff --git a/files/en-us/web/api/trustedtypepolicyfactory/defaultpolicy/index.md b/files/en-us/web/api/trustedtypepolicyfactory/defaultpolicy/index.md
index 85a4c1d09da9dcc..5d2a08217d7b8fa 100644
--- a/files/en-us/web/api/trustedtypepolicyfactory/defaultpolicy/index.md
+++ b/files/en-us/web/api/trustedtypepolicyfactory/defaultpolicy/index.md
@@ -10,8 +10,7 @@ browser-compat: api.TrustedTypePolicyFactory.defaultPolicy
 
 The **`defaultPolicy`** read-only property of the {{domxref("TrustedTypePolicyFactory")}} interface returns the default {{domxref("TrustedTypePolicy")}} or null if this is empty.
 
-> [!NOTE]
-> Information about the creation and use of default policies can be found in the [`createPolicy()`](/en-US/docs/Web/API/TrustedTypePolicyFactory/createPolicy#the_default_policy) documentation.
+See [The default policy](/en-US/docs/Web/API/Trusted_Types_API#the_default_policy) for more details.
 
 ## Value
 


Reviews:
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T00:57:31Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T01:01:45Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T01:01:59Z
user: login: lukewarlow
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-02-03T01:21:03Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T01:27:32Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T01:32:22Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T01:34:29Z
user: login: hamishwillee
body: Yes, much better. Just a few comments.
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T01:47:49Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T01:54:27Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T02:18:59Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T22:21:42Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T22:23:11Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T22:23:34Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T22:27:39Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T22:30:03Z
user: login: github-actions[bot]
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-02-03T22:38:56Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T22:51:02Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T22:55:40Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T23:28:44Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-03T23:31:02Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-04T00:18:50Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-04T07:28:25Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-05T20:42:14Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-07T01:05:52Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-07T01:41:29Z
user: login: hamishwillee
body: Much better IMO. Added a suggestion. I'm approving rather than merging, because not clear to me if @lukewarlow has more review to do.
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-02-07T01:42:34Z
user: login: aaronshim
body: Thanks so much for putting this together! 😄 
state: COMMENTED
author_association: NONE
submitted_at: 2025-02-17T18:48:36Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-18T17:43:06Z
user: login: aaronshim
state: COMMENTED
author_association: NONE
submitted_at: 2025-02-18T20:44:47Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-02-24T00:35:16Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-05T05:13:31Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-05T05:16:56Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-05T05:17:28Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-06T02:26:02Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-07T00:04:25Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-07T00:15:46Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-07T00:16:12Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-07T00:17:42Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-07T00:22:49Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-07T17:23:13Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-07T17:46:31Z
user: login: wbamberg
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-07T17:46:38Z
user: login: hamishwillee
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-10T22:41:55Z
user: login: hamishwillee
body: @wbamberg I've given this another quick scan. I think it reads well - certainly it is a really solid improvement on what is there. 

I would like to see it merge sooner rather than later. Approving so that you can do so at will.
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-03-10T22:45:03Z

Review comments:
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: This "Concepts and usage" section is now linked from all of the various trusted type interfaces as "injection syncs". For instance, in trusted HTML it says 

> The TrustedHTML interface of the [Trusted Types API](https://pr37917.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Trusted_Types_API) represents a string that a developer can insert into an [injection sink](https://pr37917.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage) that will render it as HTML.

But in TrustedHtml there is no listing of what interfaces this might be used with - and if you navigate here, just this single example of `Element.innerHTML`.

This is perhaps intentional - you don't want to have a list that can't be maintained as exhaustive? I think in this case it would be useful to either list the problematic interfaces in TrustedHtml and friends, or here have a larger subset of what they are used for. You can still say "such as" even for an incomplete list. FWIW I think page is good, and would have it in the interfaces as per https://github.com/mdn/content/pull/37917/files#r1938643809

FYI I'm looking at documenting `Document.write()` and `Document.writeln()` and when I was looking at this page, knowing this was an affected case of HTML insertion was useful.
created_at: 2025-02-03T00:57:30Z
author_association: COLLABORATOR
diff_hunk: @@ -8,7 +8,7 @@ browser-compat: api.TrustedScript.toString
 
 {{APIRef("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks).
+The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage).
path: files/en-us/web/api/trustedscript/tostring/index.md
user: login: hamishwillee
body: As per https://github.com/mdn/content/pull/37917/files#r1938642352 I'm concerned that we don't list more specifically the places this would used - either here or in concepts and usage. 

```suggestion
The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into a [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage) that accepts JavaScript, such as X, Y , Z.
```

If you don't do as "such as" here, then still consider at least indicating the type of injection sink "that accepts JavaScript".
created_at: 2025-02-03T01:01:44Z
author_association: COLLABORATOR
diff_hunk: @@ -8,7 +8,7 @@ browser-compat: api.TrustedScript.toString
 
 {{APIRef("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks).
+The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage).
path: files/en-us/web/api/trustedscript/tostring/index.md
user: login: hamishwillee
body: Ditto for other cases.
created_at: 2025-02-03T01:01:59Z
author_association: COLLABORATOR
diff_hunk: @@ -8,7 +8,7 @@ browser-compat: api.TrustedScript.toString
 
 {{APIRef("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks).
+The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage).
path: files/en-us/web/api/trustedscript/tostring/index.md
user: login: lukewarlow
body: Also this should read "may safely be inserted"
created_at: 2025-02-03T01:21:03Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: This is all true. Another goal is to centralise that sanitization code in one place, the defintition of the trusted types, making it easier to audit. Would be good to capture that too.
created_at: 2025-02-03T01:27:32Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+However, if you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP), then passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+Instead, you must always pass a trusted type.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: This is mostly to my taste - a bit more active about what you do

````suggestion
In order to enforce that a trusted type must always be passed, you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP).
With this directive set, passing strings into injection sinks will result in a `TypeError` exception:

```js example-bad
const userInput = "I might be XSS";
const element = document.querySelector("#container");

element.innerHTML = userInput; // Throws a TypeError
```

````
created_at: 2025-02-03T01:32:22Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+However, if you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP), then passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+Instead, you must always pass a trusted type.
+
+Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting.
+
+### The Trusted Types polyfills
+
+The Trusted Types API is not yet available in all modern browsers, but it is usable everywhere today thanks to [polyfills created by the W3C](https://github.com/w3c/trusted-types?tab=readme-ov-file#polyfill).
+
+There are two polyfills:
+
+- The _API only_ polyfill defines only the JavaScript API, and does not include the ability to enforce the use of trusted types using a CSP.
+- The _full_ polyfill defines the JavaScript API, attempts to infer the CSP from the current document, and enforces the use of trusted types based on the inferred CSP.
+
+Note that as long as you have tested your code, with trusted types enforced, in a browser that fully supports their enforcement using a CSP, you can still benefit from trusted types in other browsers even without enforcing their use in those other browsers.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: This sentence is hard to parse - it took me some time to "get" this, and consequently the following two paragraphs.

I get it now. 
- If you test your code with the types enforced you will make sure that all sinks use the trusted types API and that only the allowed-named policies can be set by your users. 
- At that point enforcement is unnecessary, because everything has been checked.

But, I'm not sure these three paras belongs here - they have nothing to do with polyfills, other than you will need a polyfil to use the API in some browsers.
created_at: 2025-02-03T01:34:29Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+However, if you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP), then passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+Instead, you must always pass a trusted type.
+
+Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting.
+
+### The Trusted Types polyfills
+
+The Trusted Types API is not yet available in all modern browsers, but it is usable everywhere today thanks to [polyfills created by the W3C](https://github.com/w3c/trusted-types?tab=readme-ov-file#polyfill).
+
+There are two polyfills:
+
+- The _API only_ polyfill defines only the JavaScript API, and does not include the ability to enforce the use of trusted types using a CSP.
+- The _full_ polyfill defines the JavaScript API, attempts to infer the CSP from the current document, and enforces the use of trusted types based on the inferred CSP.
+
+Note that as long as you have tested your code, with trusted types enforced, in a browser that fully supports their enforcement using a CSP, you can still benefit from trusted types in other browsers even without enforcing their use in those other browsers.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: wbamberg
body: > they have nothing to do with polyfills

They do though, because they mean you don't need the full polyfill (with CSP enforcement). You can (AFAICT) get away with the tinyfill, and this is why.
created_at: 2025-02-03T01:54:27Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+However, if you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP), then passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+Instead, you must always pass a trusted type.
+
+Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting.
+
+### The Trusted Types polyfills
+
+The Trusted Types API is not yet available in all modern browsers, but it is usable everywhere today thanks to [polyfills created by the W3C](https://github.com/w3c/trusted-types?tab=readme-ov-file#polyfill).
+
+There are two polyfills:
+
+- The _API only_ polyfill defines only the JavaScript API, and does not include the ability to enforce the use of trusted types using a CSP.
+- The _full_ polyfill defines the JavaScript API, attempts to infer the CSP from the current document, and enforces the use of trusted types based on the inferred CSP.
+
+Note that as long as you have tested your code, with trusted types enforced, in a browser that fully supports their enforcement using a CSP, you can still benefit from trusted types in other browsers even without enforcing their use in those other browsers.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: wbamberg
body: But I do agree that the sentence is hard and would accept suggestions!
created_at: 2025-02-03T02:18:58Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: wbamberg
body: I've made two changes here from what was there before:
- removed the "injection sinks" heading
- removed a couple of the examples, specifically `outerHTML` and `document.write()`.

So pretty minor change. I haven't changed it from an exhaustive to a non-exhaustive list, it was never exhaustive. I don't want the "injection sinks" heading there, or a very long list, because I think it breaks the flow of the document.

But I do agree that it is a bit weird having the "injection sinks" link in pages like https://developer.mozilla.org/en-US/docs/Web/API/TrustedScript/toString go to "concepts and usage". To address that I might suggest having an "Injection sinks" H3 heading at the end of "concepts and usage", which looks quite a bit like the existing one at https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API#injection_sinks.

Separately, yes it would be good to have an exhaustive list! But I can't find one in the [specification](https://w3c.github.io/trusted-types/dist/spec/). Also I think that's out of the intended scope of this PR.
created_at: 2025-02-03T22:21:42Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+However, if you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP), then passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+Instead, you must always pass a trusted type.
+
+Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting.
+
+### The Trusted Types polyfills
+
+The Trusted Types API is not yet available in all modern browsers, but it is usable everywhere today thanks to [polyfills created by the W3C](https://github.com/w3c/trusted-types?tab=readme-ov-file#polyfill).
+
+There are two polyfills:
+
+- The _API only_ polyfill defines only the JavaScript API, and does not include the ability to enforce the use of trusted types using a CSP.
+- The _full_ polyfill defines the JavaScript API, attempts to infer the CSP from the current document, and enforces the use of trusted types based on the inferred CSP.
+
+Note that as long as you have tested your code, with trusted types enforced, in a browser that fully supports their enforcement using a CSP, you can still benefit from trusted types in other browsers even without enforcing their use in those other browsers.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: > > they have nothing to do with polyfills
> 
> They do though, because they mean you don't need the full polyfill (with CSP enforcement). You can (AFAICT) get away with the tinyfill, and this is why.

Ah, there is no way to draw that conclusion from this text.

When you say "The _API only_ polyfill defines only the" - is that the tinyfill? ALso not clear.

In any case, I stand by my point that you don't need to have these three paras in here to make that point that "enforcement only has to be tested in one browser".

Upshot, structural issues to connect the dots about what you want to show.

created_at: 2025-02-03T22:23:10Z
author_association: COLLABORATOR
diff_hunk: @@ -8,7 +8,7 @@ browser-compat: api.TrustedScript.toString
 
 {{APIRef("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks).
+The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage).
path: files/en-us/web/api/trustedscript/tostring/index.md
user: login: wbamberg
body: Sorry I think this is out of scope for this PR. I don't really want to go through all the TT reference pages at this point. Let's do that when it ships cross-browser.
created_at: 2025-02-03T22:23:33Z
author_association: COLLABORATOR
diff_hunk: @@ -8,7 +8,7 @@ browser-compat: api.TrustedScript.toString
 
 {{APIRef("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks).
+The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage).
path: files/en-us/web/api/trustedscript/tostring/index.md
user: login: hamishwillee
body: @wbamberg You can reasonably avoid the changes I suggested, but the problem Luke is highlighting is a typo.

```suggestion
The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may be safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage).
```
created_at: 2025-02-03T22:27:39Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: I think even a non-exhaustive list would be useful. But appreciate you have a clear understanding of what you want to achieve. 

No worse that what was here before so OK as an edit.
created_at: 2025-02-03T22:30:03Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+In order to enforce that a trusted type must always be passed, you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP).
+With this directive set, passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+
path: files/en-us/web/api/trusted_types_api/index.md
user: login: github-actions[bot]
body: **[mdn-linter]** <sub>reported by [reviewdog](https://github.com/reviewdog/reviewdog) :dog:</sub><br>
```suggestion
```

<!-- __reviewdog__:Cg9lZDFhODliMTJmM2UzYzQSCm1kbi1saW50ZXI= -->

created_at: 2025-02-03T22:38:56Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: wbamberg
body: I do think BTW that in pages like https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML we should talk about trusted types. It's unclear to me how someone can really use this API effectively without knowing exactly which APIs are governed by it. But again I don't want to do this now, because it turns into "rewrite everything".
created_at: 2025-02-03T22:51:02Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+However, if you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP), then passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+Instead, you must always pass a trusted type.
+
+Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting.
+
+### The Trusted Types polyfills
+
+The Trusted Types API is not yet available in all modern browsers, but it is usable everywhere today thanks to [polyfills created by the W3C](https://github.com/w3c/trusted-types?tab=readme-ov-file#polyfill).
+
+There are two polyfills:
+
+- The _API only_ polyfill defines only the JavaScript API, and does not include the ability to enforce the use of trusted types using a CSP.
+- The _full_ polyfill defines the JavaScript API, attempts to infer the CSP from the current document, and enforces the use of trusted types based on the inferred CSP.
+
+Note that as long as you have tested your code, with trusted types enforced, in a browser that fully supports their enforcement using a CSP, you can still benefit from trusted types in other browsers even without enforcing their use in those other browsers.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: wbamberg
body: > When you say "The API only polyfill defines only the" - is that the tinyfill? ALso not clear.

No, the tinyfill is different, because it's not a polyfill for the API - i.e. it doesn't produce actual trusted types, it just produces strings. I could add an H4 heading "Tinyfill" before "The W3C also offers the following ["tinyfill"](https://github.com/w3c/trusted-types?tab=readme-ov-file#tinyfill):" if that helps make it clear that it's a different thing.

Otherwise it is tricky because the repo calls it a tinyfill not a polyfill, so I can't amend "There are two polyfills:" to "There are three polyfills:", and saying "There are two polyfills and one tinyfill:" sounds stupid.
created_at: 2025-02-03T22:55:40Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: Yes, I plan to do that as part of https://github.com/mdn/content/issues/37518 - discovered it had not been done yesterday.
created_at: 2025-02-03T23:28:44Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: Note, at this point, covering the APIs in that PR (write, writeln from Document, the setInterval/Time, Element.innerHTML, ShadowRoot.innerHTML. 
There are others that may also be affected, such as outerHTML, but I'm constraining myself in order to meet a specific FF release now overdue (i.e. what I have tested works in FF).
created_at: 2025-02-03T23:31:02Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+However, if you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP), then passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+Instead, you must always pass a trusted type.
+
+Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting.
+
+### The Trusted Types polyfills
+
+The Trusted Types API is not yet available in all modern browsers, but it is usable everywhere today thanks to [polyfills created by the W3C](https://github.com/w3c/trusted-types?tab=readme-ov-file#polyfill).
+
+There are two polyfills:
+
+- The _API only_ polyfill defines only the JavaScript API, and does not include the ability to enforce the use of trusted types using a CSP.
+- The _full_ polyfill defines the JavaScript API, attempts to infer the CSP from the current document, and enforces the use of trusted types based on the inferred CSP.
+
+Note that as long as you have tested your code, with trusted types enforced, in a browser that fully supports their enforcement using a CSP, you can still benefit from trusted types in other browsers even without enforcing their use in those other browsers.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: Perhaps pull the tinyfill into its own heading then, with whatever is relevant to its behaviour and not everything else?That makes it easier to cover the above distinctions.
created_at: 2025-02-04T00:18:50Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,123 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: There is one other thing it would be good to mention here, and that is default policy, which I would pull out of the `createPolicy` docs. 

At least for the Document.write() method, the spec says that IFF CSP is enforced then any strings passed to injection sink (or at least write()) will be offered to the default policy, and only if that default policy doesn't exist is there a TypeError. The idea is that you log this default policy, and eventually end up with everything migrated. 

IF you don't do it, then I'll have a go after this merges.
created_at: 2025-02-04T07:28:24Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,124 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+However, if you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP), then passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+Instead, you must always pass a trusted type.
+
+Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting.
+
+### The Trusted Types polyfills
+
+The Trusted Types API is not yet available in all modern browsers, but it is usable everywhere today thanks to [polyfills created by the W3C](https://github.com/w3c/trusted-types?tab=readme-ov-file#polyfill).
+
+There are two polyfills:
+
+- The _API only_ polyfill defines only the JavaScript API, and does not include the ability to enforce the use of trusted types using a CSP.
+- The _full_ polyfill defines the JavaScript API, attempts to infer the CSP from the current document, and enforces the use of trusted types based on the inferred CSP.
+
+Note that as long as you have tested your code, with trusted types enforced, in a browser that fully supports their enforcement using a CSP, you can still benefit from trusted types in other browsers even without enforcing their use in those other browsers.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: wbamberg
body: OK so based on this and our conversation I have had a bit of a go at this. Hope it is clearer.

-> https://github.com/mdn/content/pull/37917/commits/36206602ed293307b197f2c87a679ccbf16ec09b
created_at: 2025-02-05T20:42:14Z
author_association: COLLABORATOR
diff_hunk: @@ -21,7 +21,9 @@ Examples of injection sinks include:
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to centralize the sanitization code and to ensure that any data passed to an injection sink has been passed through the sanitization code.
+
+The API is really in two parts:
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: ```suggestion
The API has two main parts:
```
created_at: 2025-02-07T01:05:51Z
author_association: COLLABORATOR
diff_hunk: @@ -75,29 +77,33 @@ element.innerHTML = userInput; // Throws a TypeError
 
 Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting.
 
-### The Trusted Types polyfills
+### Cross-browser support for trusted types
 
-The Trusted Types API is not yet available in all modern browsers, but it is usable everywhere today thanks to [polyfills created by the W3C](https://github.com/w3c/trusted-types?tab=readme-ov-file#polyfill).
+The Trusted Types API is not yet available in all modern browsers, but it is usable everywhere today thanks to [compatibility aids created by the W3C](https://github.com/w3c/trusted-types/tree/main?tab=readme-ov-file#polyfill).
 
-There are two polyfills:
+- The [_full_ polyfill](https://github.com/w3c/trusted-types/blob/main/src/polyfill/full.js) defines the JavaScript API, attempts to infer the CSP from the current document, and enforces the use of trusted types based on the inferred CSP.
+- The [_API only_ polyfill](https://github.com/w3c/trusted-types/blob/main/src/polyfill/api_only.js) defines only the JavaScript API, and does not include the ability to enforce the use of trusted types using a CSP.
 
-- The _API only_ polyfill defines only the JavaScript API, and does not include the ability to enforce the use of trusted types using a CSP.
-- The _full_ polyfill defines the JavaScript API, attempts to infer the CSP from the current document, and enforces the use of trusted types based on the inferred CSP.
+As well as these two polyfills, the W3C provides what it calls a _tinyfill_, which we'll explain in more detail below.
 
-Note that as long as you have tested your code, with trusted types enforced, in a browser that fully supports their enforcement using a CSP, you can still benefit from trusted types in other browsers even without enforcing their use in those other browsers.
+Note that as long as you have tested your code, with trusted types enforced, in one browser, then you don't necessarily need to enforce trusted types in a different browser. This means that if you have tested your website in a browser that fully supports trusted types, you can then use just the API polyfill or the tinyfill in other browsers - you don't need to use the full polyfill.
 
 This is because, if you have enforced the use of trusted types in a browser, then you must refactor your code to ensure that all data is passed through the Trusted Types API (and therefore has been through a sanitization function) before being passed to an injection sink.
 
 If you then run the refactored code in a different browser without enforcement, it will still go through the same code paths, and give you the same protection.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: @wbamberg Problem fixed but I find this section a little repetitive/laborious. A very small refactor addresses this IMO.

```suggestion
Note that as long as you have tested your code on a supporting browser with CSP enforcement enabled, then you don't need to use the _full polyfill_ above on other browsers — you can get the same benefits using the _API only polyfill_ or the _tinyfill_.

This is because the enforcement forces you to refactor your code to ensure that all data is passed through the Trusted Types API (and therefore has been through a sanitization function) before being passed to an injection sink.
If you then run the refactored code in a different browser without enforcement, it will still go through the same code paths, and give you the same protection.
```
created_at: 2025-02-07T01:41:29Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,128 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: aaronshim
body: Technically, as a nit, it doesn't guarantee that the input has been sanitized (a common technique is using a passthrough policy that just returns the input)-- just that it's passed through a user-specified transformation explicitly. I think the most straightforward/common usage is that folks do indeed plop in a sanitization in the policy, but there is technically no control to force that the transformation specified in the policy is necessarily a sanitization (or unfortunately, "correct" from a security point of view-- TT is unopinionated in that way, for the better or worse)!
created_at: 2025-02-17T13:43:05Z
author_association: NONE
diff_hunk: @@ -8,30 +8,128 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to centralize the sanitization code and to ensure that any data passed to an injection sink has been passed through the sanitization code.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: aaronshim
body: A nuance here is that sanitization only works for HTML that is being passed in to the DOM sink-- and is something we can only realistically add for the `createHTML` piece of the policy. For `createScript` and `createScriptURL`, there isn't much you can do in the sanitization space, so common strategies are primitive checks (like making sure that the URLs for `createScriptURL` is from a trusted origin, if that is consistent with your threat model) or turning off `createScript` / `createScriptURL` altogether or doing a passthrough for `createScriptURL` and relying on other security features (CSP, integrity hashes, etc).
created_at: 2025-02-17T18:35:03Z
author_association: NONE
diff_hunk: @@ -8,30 +8,128 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to centralize the sanitization code and to ensure that any data passed to an injection sink has been passed through the sanitization code.
+
+The API has two main parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: aaronshim
body: nit: Is https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/trustedTypes also worth mentioning?
created_at: 2025-02-17T18:37:05Z
author_association: NONE
diff_hunk: @@ -8,30 +8,128 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to centralize the sanitization code and to ensure that any data passed to an injection sink has been passed through the sanitization code.
+
+The API has two main parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: aaronshim
body: nit: See comment previous about the nuance of "sanitization" vs. "user-supplied transformation"-- most of the times it should be sanitization (for `createHTML`) but it's not always the case.
created_at: 2025-02-17T18:38:00Z
author_association: NONE
diff_hunk: @@ -8,30 +8,128 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to centralize the sanitization code and to ensure that any data passed to an injection sink has been passed through the sanitization code.
+
+The API has two main parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
path: files/en-us/web/api/trusted_types_api/index.md
user: login: aaronshim
body: data that has been explicitly passed through a developer-provided transformation to create a trust boundary, rather than "sanitized"?
created_at: 2025-02-17T18:38:58Z
author_association: NONE
diff_hunk: @@ -8,30 +8,128 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to centralize the sanitization code and to ensure that any data passed to an injection sink has been passed through the sanitization code.
+
+The API has two main parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: aaronshim
body: parse the data as a URL-- for the purposes of executing it as a script later?
created_at: 2025-02-17T18:39:19Z
author_association: NONE
diff_hunk: @@ -8,30 +8,128 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to centralize the sanitization code and to ensure that any data passed to an injection sink has been passed through the sanitization code.
+
+The API has two main parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
path: files/en-us/web/api/trusted_types_api/index.md
user: login: aaronshim
body: nit: Would it be better to style `userInput` as something that is definitely HTML markup and not just plaintext? Otherwise the "simple fix" would be `element.textContent = userInput`.
created_at: 2025-02-17T18:41:20Z
author_association: NONE
diff_hunk: @@ -8,30 +8,123 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
path: files/en-us/web/api/trusted_types_api/index.md
user: login: aaronshim
body: I think the default policy has a couple other uses in the way we've used them in production-- such as allowlisting a series of known constants, for example. Also important to note is that if we return `null` or `undefined` from the [default policy](https://www.w3.org/TR/trusted-types/#default-policy-hdr), we will not end up transforming the string into a `TrustedHTML`/`TrustedScript`/`TrustedScriptURL`, so we will end up blocking the potential XSS execution and with the `TypeError`.

This is useful, as @hamishwillee mentioned, for using the default policy as a logging/observability mechanism of everything that will end up in a DOM sink without going through another policy first.
created_at: 2025-02-17T18:48:16Z
author_association: NONE
diff_hunk: @@ -8,30 +8,128 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: wbamberg
body: I think this is a bit tricky, because in the intro paragraph saying "ensure that input has been passed through a user-specified transformation function" rather than "ensure that input has been passed through a sanitization function" is IMO quite unhelpfully abstract: as a reader I read this and go "what does that mean, and why would I want to do that?" The whole point of the API AIUI is to sanitize input, so saying that early on seems helpful.

Also the current text doesn't say that the API ensures input is sanitized, it says it enables developers to ensure input is sanitized, which seems true to me.

It is true, and important, that the API doesn't ensure that sanitization happens, but maybe it's better to state the main (happy) path first, and then to qualify it. We do already have that qualification, more or less, in https://pr37917.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Trusted_Types_API#the_trusted_types_javascript_api:

> Note that the Trusted Types API does not itself include a sanitization function: you supply your own function when you define the TrustedTypePolicy that you will use.

Would it be enough to:
- move this paragraph up a bit (not I think to the very start, but maybe to the end of the "concepts and usage" preamble)
- be a bit clearer/more emphatic that the API offers no guarantee that the function supplied is correct or even a sanitization function at all

?



created_at: 2025-02-18T17:43:06Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,128 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: aaronshim
body: I think it's certainly worth a shot, thank you for your ideas!
created_at: 2025-02-18T20:44:47Z
author_association: NONE
diff_hunk: @@ -8,30 +8,128 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: > The whole point of the API AIUI is to sanitize input, so saying that early on seems helpful.

FWIW the point of the API is to force all data going to a sink to be _considered for sanitization_, and make finding all the sinks easier. There are plenty of cases where you might not want or be able to do much sanitizing, such as scripts  - as per @aaronshim comment in https://github.com/mdn/content/pull/37917#discussion_r1958668942

I think your points and proposed solution are good though.

created_at: 2025-02-24T00:35:16Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,128 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to centralize the sanitization code and to ensure that any data passed to an injection sink has been passed through the sanitization code.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: wbamberg
body: I've thought quite a bit about this and some related comments you have here and have changed things in https://github.com/mdn/content/pull/37917/commits/aae1d358c84187352f4f48722ab1e93e50cbb320. 

I had been vaguely uneasy about "sanitization" language outside the context of HTML but hadn't really considered it explicitly till I read this comment. In https://github.com/mdn/content/pull/37917/commits/aae1d358c84187352f4f48722ab1e93e50cbb320 I've tried to talk about the different kinds of sinks that might want different kinds of transformation, and that only one of them is really a sanitization function.
created_at: 2025-03-05T05:13:31Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,128 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to centralize the sanitization code and to ensure that any data passed to an injection sink has been passed through the sanitization code.
+
+The API has two main parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: wbamberg
body: -> https://github.com/mdn/content/pull/37917/commits/248627224fe4c33cfcd0480416b99566a9ba8cf8
created_at: 2025-03-05T05:16:56Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,128 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to centralize the sanitization code and to ensure that any data passed to an injection sink has been passed through the sanitization code.
+
+The API has two main parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
path: files/en-us/web/api/trusted_types_api/index.md
user: login: wbamberg
body: Also in https://github.com/mdn/content/pull/37917/commits/aae1d358c84187352f4f48722ab1e93e50cbb320.
created_at: 2025-03-05T05:17:27Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,123 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
path: files/en-us/web/api/trusted_types_api/index.md
user: login: wbamberg
body: I've added something on the default policy in https://github.com/mdn/content/pull/37917/commits/c76c3db477f7dc0bd01b155576c6712d4e143a24. I didn't keep the warning about making sure the default policy isn't too lax, because I don't really understand why this applies to the default policy and not to any other policy. I'm probably missing something though.

I also did not talk about:

> I think the default policy has a couple other uses in the way we've used them in production-- such as allowlisting a series of known constants, for example

...because as I read it, using the default policy for anything other than transitioning to using trusted types fully is discouraged (see the first note under https://www.w3.org/TR/trusted-types/#default-policy-hdr).
created_at: 2025-03-06T02:26:02Z
author_association: COLLABORATOR
diff_hunk: @@ -10,16 +10,6 @@ browser-compat: api.TrustedTypePolicyFactory.createPolicy
 
 The **`createPolicy()`** method of the {{domxref("TrustedTypePolicyFactory")}} interface creates a {{domxref("TrustedTypePolicy")}} object that implements the rules passed as `policyOptions`.
 
-### The default policy
path: files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.md
user: login: hamishwillee
body: In the `##` Examples below please create a heading for the first example, and in the second example link to your new default policy topic - i.e. explaining what a default policy is.
created_at: 2025-03-07T00:04:25Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,182 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a user-specified transformation function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks. Most commonly the transformation function [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+The Trusted Types API distinguishes three sorts of injection sinks:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
+- **HTML sinks**: APIs that interpret their input as HTML, such as {{domxref("Element.innerHTML")}} or {{domxref("Document.write()", "document.write()")}}. These APIs could execute JavaScript if it is embedded in the HTML, for example in {{htmlelement("script")}} tags or event handler attributes.
+- **JavaScript sinks**: APIs that interpret their input as JavaScript, such as {{jsxref("Global_Objects/eval", "eval()")}} or {{domxref("HTMLScriptElement.text")}}.
+- **JavaScript URL sinks**: APIs that interpret their input as the URL of a script, such as {{domxref("HTMLScriptElement.src")}}.
 
-### Injection Sinks
+One of the main defenses against DOM-based XSS attacks is to ensure that input is made safe before being passed to an injection sink.
 
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
+In the Trusted Types API, a developer defines a _policy object_, which contains methods that transform input bound for an injection sink so as to make it safe. The policy can define different methods for the different types of sink:
 
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
-- Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
-- Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
-- Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
+- For HTML sinks, the transformation function typically [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input, for example by using a library like [DOMPurify](https://github.com/cure53/DOMPurify).
+- For JavaScript and JavaScript URL sinks, the policy may turn off the sinks entirely or allow certain predefined inputs (for example, specific URLs).
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+The Trusted Types API will then ensure that input is passed through the appropriate transformation function before being passed into the sink.
 
-### Trusted Type Policies
+That is, the API enables you to define your policy in one place and then be assured that any data passed to an injection sink has been passed through the policy.
 
-A policy is a factory for Trusted Types. Web developers can specify a set of policies used for the creation of typed objects which form the trusted codebase for valid Trusted Type objects.
+> [!NOTE]
+>
+> The Trusted Types API does _not_ itself supply a policy or any transformation functions: the developer defines their own policy, which contains the transformations that they wish to apply.
+
+The API has two main parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The `trustedTypes` global property, available in both {{domxref("Window.trustedTypes", "Window")}} and {{domxref("WorkerGlobalScope.trustedTypes", "Worker")}} contexts, is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a transformation function.
+- Trusted type objects represent data that has been through the policy, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to the different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL to a script.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a transformation function.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+In order to enforce that a trusted type must always be passed, you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP).
+With this directive set, passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting.
+
+### The default policy
+
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: @wbamberg This is a matter of taste, but I prefer to introduce the concept and its use before showing how it is used - in particular because this is on the migration path. So consider removing the last comment in this section and replacing it with something like (with appropriate changes to the first sentence that follows):

> A default policy can be used to help you find any places in your code where you're still using strings in your injection sinks, so you can rewrite the code to create and pass trusted types instead.
> Note that you should only use the default policy only to transition from legacy code!


created_at: 2025-03-07T00:15:46Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,182 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a user-specified transformation function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks. Most commonly the transformation function [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+The Trusted Types API distinguishes three sorts of injection sinks:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
+- **HTML sinks**: APIs that interpret their input as HTML, such as {{domxref("Element.innerHTML")}} or {{domxref("Document.write()", "document.write()")}}. These APIs could execute JavaScript if it is embedded in the HTML, for example in {{htmlelement("script")}} tags or event handler attributes.
+- **JavaScript sinks**: APIs that interpret their input as JavaScript, such as {{jsxref("Global_Objects/eval", "eval()")}} or {{domxref("HTMLScriptElement.text")}}.
+- **JavaScript URL sinks**: APIs that interpret their input as the URL of a script, such as {{domxref("HTMLScriptElement.src")}}.
 
-### Injection Sinks
+One of the main defenses against DOM-based XSS attacks is to ensure that input is made safe before being passed to an injection sink.
 
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
+In the Trusted Types API, a developer defines a _policy object_, which contains methods that transform input bound for an injection sink so as to make it safe. The policy can define different methods for the different types of sink:
 
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
-- Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
-- Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
-- Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
+- For HTML sinks, the transformation function typically [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input, for example by using a library like [DOMPurify](https://github.com/cure53/DOMPurify).
+- For JavaScript and JavaScript URL sinks, the policy may turn off the sinks entirely or allow certain predefined inputs (for example, specific URLs).
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+The Trusted Types API will then ensure that input is passed through the appropriate transformation function before being passed into the sink.
 
-### Trusted Type Policies
+That is, the API enables you to define your policy in one place and then be assured that any data passed to an injection sink has been passed through the policy.
 
-A policy is a factory for Trusted Types. Web developers can specify a set of policies used for the creation of typed objects which form the trusted codebase for valid Trusted Type objects.
+> [!NOTE]
+>
+> The Trusted Types API does _not_ itself supply a policy or any transformation functions: the developer defines their own policy, which contains the transformations that they wish to apply.
+
+The API has two main parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The `trustedTypes` global property, available in both {{domxref("Window.trustedTypes", "Window")}} and {{domxref("WorkerGlobalScope.trustedTypes", "Worker")}} contexts, is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a transformation function.
+- Trusted type objects represent data that has been through the policy, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to the different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL to a script.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a transformation function.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+In order to enforce that a trusted type must always be passed, you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP).
+With this directive set, passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting.
+
+### The default policy
+
+If you create a policy named `"default"`, and your CSP enforces the use of trusted types, then any string argument passed into injection sinks will be automatically passed to this policy. For example, suppose we create a policy like this:
+
+```js
+trustedTypes.createPolicy("default", {
+  createHTML: (value) => {
+    console.log("Please refactor this code");
+    return sanitize(value);
+  },
+});
+```
+
+With this policy, if your code assigns a string to `innerHTML`, the browser will call the policy's `createHTML()` method and assign its result to the sink:
+
+```js
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput;
+// Logs "Please refactor this code"
+// Assigns the result of sanitize(userInput)
+```
+
+If the default policy returned `null` or `undefined`, then the browser will throw a `TypeError` when assigning the result to the sink:
+
+```js
+trustedTypes.createPolicy("default", {
+  createHTML: (value) => {
+    console.log("Please refactor this code");
+    return null;
+  },
+});
+
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput;
+// Logs "Please refactor this code"
+// Throws a TypeError
+```
+
+It's recommended that you use the default policy only to transition from legacy code that passes input directly to injection sinks. That is, it helps you discover the places in your code where you're using injection sinks directly, so you can rerwite the code to create and pass trusted types instead.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: If you choose not to do https://github.com/mdn/content/pull/37917/files#r1984217780 then typo

```suggestion
It's recommended that you use the default policy only to transition from legacy code that passes input directly to injection sinks. That is, it helps you discover the places in your code where you're using injection sinks directly, so you can rewrite the code to create and pass trusted types instead.
```
created_at: 2025-03-07T00:16:12Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,123 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to ensure that any data passed to an injection sink has been passed through a sanitization function. It is really in two parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The {{domxref("Window.trustedTypes", "trustedTypes")}} global property is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a sanitization function.
+- Trusted type objects represent data that has been sanitized, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a sanitization function.
+
+Note that the Trusted Types API does _not_ itself include a sanitization function: you supply your own function when you define the `TrustedTypePolicy` that you will use.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "I might be XSS";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: I've added a suggestion, but this is good.

FWIW I read the use of the default policy in the same way as you do.
created_at: 2025-03-07T00:17:41Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,128 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a [sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization) function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+Examples of injection sinks include:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
-
-### Injection Sinks
-
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
-
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
+- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}.
 - Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
 - Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
 - Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+One of the main defenses against DOM-based XSS attacks is to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) data before passing it to an injection sink. The Trusted Types API enables a developer to centralize the sanitization code and to ensure that any data passed to an injection sink has been passed through the sanitization code.
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: I thought it was OK before, but the changes are much better/more precise.

Let's see what @aaronshim says - this reads well, but I don't know how to assess the truth of things like "For JavaScript and JavaScript URL sinks, the policy may turn off the sinks entirely or allow certain predefined inputs (for example, specific URLs)."
created_at: 2025-03-07T00:22:49Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,182 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a user-specified transformation function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks. Most commonly the transformation function [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+The Trusted Types API distinguishes three sorts of injection sinks:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
+- **HTML sinks**: APIs that interpret their input as HTML, such as {{domxref("Element.innerHTML")}} or {{domxref("Document.write()", "document.write()")}}. These APIs could execute JavaScript if it is embedded in the HTML, for example in {{htmlelement("script")}} tags or event handler attributes.
+- **JavaScript sinks**: APIs that interpret their input as JavaScript, such as {{jsxref("Global_Objects/eval", "eval()")}} or {{domxref("HTMLScriptElement.text")}}.
+- **JavaScript URL sinks**: APIs that interpret their input as the URL of a script, such as {{domxref("HTMLScriptElement.src")}}.
 
-### Injection Sinks
+One of the main defenses against DOM-based XSS attacks is to ensure that input is made safe before being passed to an injection sink.
 
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
+In the Trusted Types API, a developer defines a _policy object_, which contains methods that transform input bound for an injection sink so as to make it safe. The policy can define different methods for the different types of sink:
 
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
-- Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
-- Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
-- Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
+- For HTML sinks, the transformation function typically [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input, for example by using a library like [DOMPurify](https://github.com/cure53/DOMPurify).
+- For JavaScript and JavaScript URL sinks, the policy may turn off the sinks entirely or allow certain predefined inputs (for example, specific URLs).
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+The Trusted Types API will then ensure that input is passed through the appropriate transformation function before being passed into the sink.
 
-### Trusted Type Policies
+That is, the API enables you to define your policy in one place and then be assured that any data passed to an injection sink has been passed through the policy.
 
-A policy is a factory for Trusted Types. Web developers can specify a set of policies used for the creation of typed objects which form the trusted codebase for valid Trusted Type objects.
+> [!NOTE]
+>
+> The Trusted Types API does _not_ itself supply a policy or any transformation functions: the developer defines their own policy, which contains the transformations that they wish to apply.
+
+The API has two main parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The `trustedTypes` global property, available in both {{domxref("Window.trustedTypes", "Window")}} and {{domxref("WorkerGlobalScope.trustedTypes", "Worker")}} contexts, is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a transformation function.
+- Trusted type objects represent data that has been through the policy, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to the different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL to a script.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a transformation function.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+In order to enforce that a trusted type must always be passed, you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP).
+With this directive set, passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting.
+
+### The default policy
+
path: files/en-us/web/api/trusted_types_api/index.md
user: login: wbamberg
body: >  I prefer to introduce the concept and its use before showing how it is used

Yeah, I agree this is a good principle!
created_at: 2025-03-07T17:23:13Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,182 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a user-specified transformation function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks. Most commonly the transformation function [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+The Trusted Types API distinguishes three sorts of injection sinks:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
+- **HTML sinks**: APIs that interpret their input as HTML, such as {{domxref("Element.innerHTML")}} or {{domxref("Document.write()", "document.write()")}}. These APIs could execute JavaScript if it is embedded in the HTML, for example in {{htmlelement("script")}} tags or event handler attributes.
+- **JavaScript sinks**: APIs that interpret their input as JavaScript, such as {{jsxref("Global_Objects/eval", "eval()")}} or {{domxref("HTMLScriptElement.text")}}.
+- **JavaScript URL sinks**: APIs that interpret their input as the URL of a script, such as {{domxref("HTMLScriptElement.src")}}.
 
-### Injection Sinks
+One of the main defenses against DOM-based XSS attacks is to ensure that input is made safe before being passed to an injection sink.
 
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
+In the Trusted Types API, a developer defines a _policy object_, which contains methods that transform input bound for an injection sink so as to make it safe. The policy can define different methods for the different types of sink:
 
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
-- Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
-- Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
-- Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
+- For HTML sinks, the transformation function typically [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input, for example by using a library like [DOMPurify](https://github.com/cure53/DOMPurify).
+- For JavaScript and JavaScript URL sinks, the policy may turn off the sinks entirely or allow certain predefined inputs (for example, specific URLs).
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+The Trusted Types API will then ensure that input is passed through the appropriate transformation function before being passed into the sink.
 
-### Trusted Type Policies
+That is, the API enables you to define your policy in one place and then be assured that any data passed to an injection sink has been passed through the policy.
 
-A policy is a factory for Trusted Types. Web developers can specify a set of policies used for the creation of typed objects which form the trusted codebase for valid Trusted Type objects.
+> [!NOTE]
+>
+> The Trusted Types API does _not_ itself supply a policy or any transformation functions: the developer defines their own policy, which contains the transformations that they wish to apply.
+
+The API has two main parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The `trustedTypes` global property, available in both {{domxref("Window.trustedTypes", "Window")}} and {{domxref("WorkerGlobalScope.trustedTypes", "Worker")}} contexts, is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a transformation function.
+- Trusted type objects represent data that has been through the policy, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to the different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL to a script.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a transformation function.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+In order to enforce that a trusted type must always be passed, you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP).
+With this directive set, passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting.
+
+### The default policy
+
path: files/en-us/web/api/trusted_types_api/index.md
user: login: wbamberg
body: -> https://github.com/mdn/content/pull/37917/commits/acff35ba89bb6a1abbfdbd7dd809bb4b93ab8f27
created_at: 2025-03-07T17:46:31Z
author_association: COLLABORATOR
diff_hunk: @@ -10,16 +10,6 @@ browser-compat: api.TrustedTypePolicyFactory.createPolicy
 
 The **`createPolicy()`** method of the {{domxref("TrustedTypePolicyFactory")}} interface creates a {{domxref("TrustedTypePolicy")}} object that implements the rules passed as `policyOptions`.
 
-### The default policy
path: files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.md
user: login: wbamberg
body: -> https://github.com/mdn/content/pull/37917/commits/acff35ba89bb6a1abbfdbd7dd809bb4b93ab8f27
created_at: 2025-03-07T17:46:38Z
author_association: COLLABORATOR
diff_hunk: @@ -8,30 +8,182 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/
 
 {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}}
 
-The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks.
+The **Trusted Types API** gives web developers a way to ensure that input has been passed through a user-specified transformation function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks. Most commonly the transformation function [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input.
 
-## Concepts and Usage
+## Concepts and usage
 
-Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions.
+Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_.
 
-The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function.
+The Trusted Types API distinguishes three sorts of injection sinks:
 
-Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives.
+- **HTML sinks**: APIs that interpret their input as HTML, such as {{domxref("Element.innerHTML")}} or {{domxref("Document.write()", "document.write()")}}. These APIs could execute JavaScript if it is embedded in the HTML, for example in {{htmlelement("script")}} tags or event handler attributes.
+- **JavaScript sinks**: APIs that interpret their input as JavaScript, such as {{jsxref("Global_Objects/eval", "eval()")}} or {{domxref("HTMLScriptElement.text")}}.
+- **JavaScript URL sinks**: APIs that interpret their input as the URL of a script, such as {{domxref("HTMLScriptElement.src")}}.
 
-### Injection Sinks
+One of the main defenses against DOM-based XSS attacks is to ensure that input is made safe before being passed to an injection sink.
 
-The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include:
+In the Trusted Types API, a developer defines a _policy object_, which contains methods that transform input bound for an injection sink so as to make it safe. The policy can define different methods for the different types of sink:
 
-- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}.
-- Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}.
-- Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}.
-- Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute.
+- For HTML sinks, the transformation function typically [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input, for example by using a library like [DOMPurify](https://github.com/cure53/DOMPurify).
+- For JavaScript and JavaScript URL sinks, the policy may turn off the sinks entirely or allow certain predefined inputs (for example, specific URLs).
 
-Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy.
+The Trusted Types API will then ensure that input is passed through the appropriate transformation function before being passed into the sink.
 
-### Trusted Type Policies
+That is, the API enables you to define your policy in one place and then be assured that any data passed to an injection sink has been passed through the policy.
 
-A policy is a factory for Trusted Types. Web developers can specify a set of policies used for the creation of typed objects which form the trusted codebase for valid Trusted Type objects.
+> [!NOTE]
+>
+> The Trusted Types API does _not_ itself supply a policy or any transformation functions: the developer defines their own policy, which contains the transformations that they wish to apply.
+
+The API has two main parts:
+
+- A JavaScript API enables a developer to sanitize data before passing it to an injection sink.
+- Two [CSP](/en-US/docs/Web/HTTP/CSP) directives enforce and control the usage of the JavaScript API.
+
+### The Trusted Types JavaScript API
+
+In the Trusted Types API:
+
+- The `trustedTypes` global property, available in both {{domxref("Window.trustedTypes", "Window")}} and {{domxref("WorkerGlobalScope.trustedTypes", "Worker")}} contexts, is used to create {{domxref("TrustedTypePolicy")}} objects.
+- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a transformation function.
+- Trusted type objects represent data that has been through the policy, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to the different sort of injection sink:
+  - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML.
+  - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript.
+  - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL to a script.
+
+With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a transformation function.
+
+For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library:
+
+```js
+const policy = trustedTypes.createPolicy("my-policy", {
+  createHTML: (input) => DOMPurify.sanitize(input),
+});
+```
+
+Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink:
+
+```js
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+const trustedHTML = policy.createHTML(userInput);
+element.innerHTML = trustedHTML;
+```
+
+### Using a CSP to enforce trusted types
+
+The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`.
+
+In order to enforce that a trusted type must always be passed, you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/CSP).
+With this directive set, passing strings into injection sinks will result in a `TypeError` exception:
+
+```js example-bad
+const userInput = "<p>I might be XSS</p>";
+const element = document.querySelector("#container");
+
+element.innerHTML = userInput; // Throws a TypeError
+```
+
+Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting.
+
+### The default policy
+
path: files/en-us/web/api/trusted_types_api/index.md
user: login: hamishwillee
body: Looks good
created_at: 2025-03-10T22:41:55Z
author_association: COLLABORATOR

PR comments:
user: login: github-actions[bot]
created_at: 2025-02-02T07:51:02Z
body: <!-- build_hash: de9215eacdadf38fcc2c2bd6581f0807 date: 2025-03-07 17:47:25.935300 -->

<details><summary><b>Preview URLs</b> (8 pages)</summary>

- [`/en-US/docs/Web/API/TrustedHTML`](https://pr37917.review.mdn.allizom.net/en-US/docs/Web/API/TrustedHTML)
- [`/en-US/docs/Web/API/TrustedScript/toString`](https://pr37917.review.mdn.allizom.net/en-US/docs/Web/API/TrustedScript/toString)
- [`/en-US/docs/Web/API/TrustedScriptURL/toString`](https://pr37917.review.mdn.allizom.net/en-US/docs/Web/API/TrustedScriptURL/toString)
- [`/en-US/docs/Web/API/TrustedScriptURL`](https://pr37917.review.mdn.allizom.net/en-US/docs/Web/API/TrustedScriptURL)
- [`/en-US/docs/Web/API/TrustedScript`](https://pr37917.review.mdn.allizom.net/en-US/docs/Web/API/TrustedScript)
- [`/en-US/docs/Web/API/TrustedTypePolicyFactory/createPolicy`](https://pr37917.review.mdn.allizom.net/en-US/docs/Web/API/TrustedTypePolicyFactory/createPolicy)
- [`/en-US/docs/Web/API/TrustedTypePolicyFactory/defaultPolicy`](https://pr37917.review.mdn.allizom.net/en-US/docs/Web/API/TrustedTypePolicyFactory/defaultPolicy)
- [`/en-US/docs/Web/API/Trusted_Types_API`](https://pr37917.review.mdn.allizom.net/en-US/docs/Web/API/Trusted_Types_API)

</details>


<details><summary><b>External URLs</b> (5)</summary>

URL: [`/en-US/docs/Web/API/Trusted_Types_API`](https://pr37917.review.mdn.allizom.net/en-US/docs/Web/API/Trusted_Types_API)
Title: `Trusted Types API`

  - [https://github.com/cure53/DOMPurify](<https://redirect.github.com/cure53/DOMPurify>) (2 times) (Note! This may be a new URL 👀)
  - [https://github.com/w3c/trusted-types](<https://redirect.github.com/w3c/trusted-types>) (1 time) (Note! This may be a new URL 👀)
  - [https://github.com/w3c/trusted-types/blob/main/src/polyfill/api_only.js](<https://redirect.github.com/w3c/trusted-types/blob/main/src/polyfill/api_only.js>) (1 time) (Note! This may be a new URL 👀)
  - [https://github.com/w3c/trusted-types/blob/main/src/polyfill/full.js](<https://redirect.github.com/w3c/trusted-types/blob/main/src/polyfill/full.js>) (1 time) (Note! This may be a new URL 👀)
  - [https://github.com/w3c/trusted-types/tree/main?tab=readme-ov-file](<https://redirect.github.com/w3c/trusted-types/tree/main?tab=readme-ov-file>) (1 time) (Note! This may be a new URL 👀)

</details>

*(comment last updated: 2025-03-07 17:47:26)*
author_association: CONTRIBUTOR
user: login: lukewarlow
created_at: 2025-02-02T17:42:14Z
body: I will try to review this change during this week.

The polyfill specifically might need some updates to match it with latest spec changes I'm not sure of its current state.
author_association: CONTRIBUTOR
user: login: hamishwillee
created_at: 2025-03-07T00:24:42Z
body: Changes look really good structurally. Note though that I didn't do a very thorough look - I'd rather do one last pass when @aaronshim has confirmed that he is happy with the technical changes.
author_association: COLLABORATOR
user: login: wbamberg
created_at: 2025-03-10T22:50:14Z
body: Thanks Hamish! I'm going to merge this then, and we can take further improvements/corrections as follow-ups.


author_association: COLLABORATOR
user: login: wbamberg
created_at: 2025-03-10T22:55:57Z
body: FWIW I think we are getting close to the point where "concepts and usage" is long enough to split out into a separate guide page.
author_association: COLLABORATOR
user: login: hamishwillee
created_at: 2025-03-10T23:09:54Z
body: > FWIW I think we are getting close to the point where "concepts and usage" is long enough to split out into a separate guide page.

Probably. I've like the clarity you can get with a succinct outline in the API overview . That said, I'm much better at criticizing guide than writing it, so might be a bit of fear about having to reimagine the content into a more full guide.
author_association: COLLABORATOR