FF145 Relnote: Trusted Types early beta (#41518)

hamishwillee · bsmth · web-flow · commit 4db798b6db57 · 2025-11-03T10:02:53.000+11:00
* FF145 Relnote: Trusted Types early beta

* trusted-types-eval - add

* Add more items to trusted types sinks

* Add note about indirect injection

* Apply suggestions from code review

Co-authored-by: Brian Smith &lt;brian@smith.berlin&gt;

* Move the injection sink list

---------

Co-authored-by: Brian Smith &lt;brian@smith.berlin&gt;
diff --git a/files/en-us/mozilla/firefox/experimental_features/index.md b/files/en-us/mozilla/firefox/experimental_features/index.md
@@ -408,26 +408,20 @@ The {{domxref("CloseWatcher")}} interface allows developers to implement UI comp
 ### Trusted Types API
 
 The [Trusted Types API](/en-US/docs/Web/API/Trusted_Types_API) provides mechanisms to ensure that functions that can potentially be used as vectors for XSS attacks are only able to be called with data that has been validated or sanitized.
+The API is enabled in early beta releases ([Firefox bug 1992941](https://bugzil.la/1992941)).
 
-> [!NOTE]
-> At the time of writing not enough of the API has been implemented for it to be effectively testable.
-> This note will be removed once it is ready.
+This includes (non-exhaustively):
 
-This subset of the API has been implemented:
-
-- {{domxref("TrustedTypePolicyFactory")}}:
-  - {{domxref("TrustedTypePolicyFactory/getAttributeType", "getAttributeType()")}} and {{domxref("TrustedTypePolicyFactory/getPropertyType", "getPropertyType()")}} ([Firefox bug 1917783](https://bugzil.la/1917783), [Firefox bug 1917784](https://bugzil.la/1917784)).
-- The {{domxref("Document.write()", "write()")}} and {{domxref("Document.writeln()","writeln()")}} methods of the {{domxref("Document")}} interface now accept {{domxref("TrustedHTML")}} objects as parameters, in addition to strings. ([Firefox bug 1906301](https://bugzil.la/1906301)).
-- The {{domxref("HTMLScriptElement.text","text")}}, {{domxref("HTMLElement.innerText","innerText")}}, and {{domxref("Node.textContent","textContent")}} properties of the {{domxref("HTMLScriptElement")}} interface now accept {{domxref("TrustedScript")}} objects a value, while {{domxref("HTMLScriptElement.src", "src")}} accepts {{domxref("TrustedScriptURL")}} values. ([Firefox bug 1905706](https://bugzil.la/1905706)).
-- The {{domxref("Window.setInterval()")}} and {{domxref("Window.setTimeout()")}} methods can be called with a {{domxref("TrustedScript")}}. ([Firefox bug 1931290](https://bugzil.la/1931290)).
-- The global [`trustedTypes`](/en-US/docs/Web/API/Window/trustedTypes) property is available for accessing the Trusted Types API.
-- The properties {{domxref("Element.innerHTML")}} and {{domxref("ShadowRoot.innerHTML")}} can be called with [trusted types](/en-US/docs/Web/API/Trusted_Types_API).
+- Addition of the {{domxref("TrustedTypePolicyFactory")}}, {{domxref("TrustedTypePolicy")}}, {{domxref("TrustedHTML")}}, {{domxref("TrustedScript")}}, {{domxref("TrustedScriptURL")}} interfaces, and the `trustedTypes` property on {{domxref("Window/trustedTypes", "Window")}} and {{domxref("WorkerGlobalScope/trustedTypes", "WorkerGlobalScope")}}.
+- Updates to [injection sink interfaces](/en-US/docs/Web/API/Trusted_Types_API#injection_sink_interfaces), such as {{domxref("Element.innerHTML")}} and {{domxref("Document.write()", "document.write()")}}, to allow the `TrustedHTML`, `TrustedScript`, `TrustedScriptURL` to be passed as well as strings.
+- Support for the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for) and [`trusted-types`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/trusted-types) directives, and the [`'trusted-types-eval'`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#trusted-types-eval) keyword, of the {{HTTPHeader("Content-Security-Policy")}} HTTP header.
+  These can be used to enforce trusted types instead of strings, name the specific policies that are allowed, and to enable [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) and similar functions to be used when [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) are supported and enforced.
 
 | Release channel   | Version added | Enabled by default? |
 | ----------------- | ------------- | ------------------- |
-| Nightly           | 133           | No                  |
-| Developer Edition | 133           | No                  |
-| Beta              | 133           | No                  |
+| Nightly           | 145           | Yes                 |
+| Developer Edition | 145           | Yes                 |
+| Beta              | 145           | Yes                 |
 | Release           | 133           | No                  |
 
 - `dom.security.trusted_types.enabled`
diff --git a/files/en-us/mozilla/firefox/releases/145/index.md b/files/en-us/mozilla/firefox/releases/145/index.md
@@ -117,3 +117,14 @@ You can find more such features on the [Experimental features](/en-US/docs/Mozil
 
   The CSS `text-decoration-trim` property is supported but currently disabled by default.
   It allows you to specify {{cssxref("text-decoration")}} start and end offsets to shorten, lengthen, or shift the position of text decorations with respect to the text ([Firefox bug 1979915](https://bugzil.la/1979915)).
+
+- **Trusted Types API** for scripts (Nightly/Early Beta): `dom.security.trusted_types.enabled`
+
+  The [Trusted Types API](/en-US/docs/Web/API/Trusted_Types_API) is now enabled in early beta releases. ([Firefox bug 1976656](https://bugzil.la/1976656)).
+
+  The changes include:
+
+- Addition of the {{domxref("TrustedTypePolicyFactory")}}, {{domxref("TrustedTypePolicy")}}, {{domxref("TrustedHTML")}}, {{domxref("TrustedScript")}}, {{domxref("TrustedScriptURL")}} interfaces, and the `trustedTypes` property on {{domxref("Window/trustedTypes", "Window")}} and {{domxref("WorkerGlobalScope/trustedTypes", "WorkerGlobalScope")}}.
+  - Updates to [injection sink interfaces](/en-US/docs/Web/API/Trusted_Types_API##injection_sink_interfaces) APIs, such as {{domxref("Element.innerHTML")}} and {{domxref("Document.write()", "document.write()")}}, to allow the `TrustedHTML`, `TrustedScript`, `TrustedScriptURL` to be passed as well as strings.
+  - Support for the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for) and [`trusted-types`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/trusted-types) directives, and the [`'trusted-types-eval'`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#trusted-types-eval) keyword, of the {{HTTPHeader("Content-Security-Policy")}} HTTP header.
+    These can be used to enforce trusted types instead of strings, name the specific policies that are allowed, and to enable [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) and similar functions to be used when [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) are supported and enforced.
diff --git a/files/en-us/web/api/trusted_types_api/index.md b/files/en-us/web/api/trusted_types_api/index.md
@@ -12,7 +12,7 @@ The **Trusted Types API** gives web developers a way to ensure that input has be
 
 ## Concepts and usage
 
-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_.
+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_](#injection_sink_interfaces).
 
 The Trusted Types API distinguishes three sorts of injection sinks:
 
@@ -134,6 +134,50 @@ element.innerHTML = userInput;
 > [!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.
 
+### Injection sink interfaces
+
+This section provides an list of "direct" injection sink interfaces.
+
+Note that there are cases where untrusted strings may be "indirectly injected", such as when an untrusted string is added as the child node of a script element, and then the element is added to the document.
+These cases are evaluated the untrusted script is added to the document.
+
+#### TrustedHTML
+
+- {{domxref("Document.execCommand()")}} with a `commandName` of [`"insertHTML"`](/en-US/docs/Web/API/Document/execCommand#inserthtml)
+- {{domxref("Document.parseHTMLUnsafe_static()")}}
+- {{domxref("Document.write()")}}
+- {{domxref("Document.writeln()")}}
+- {{domxref("DOMParser.parseFromString()")}}
+- {{domxref("Element.innerHTML")}}
+- {{domxref("Element.insertAdjacentHTML")}}
+- {{domxref("Element.outerHTML")}}
+- {{domxref("Element.setHTMLUnsafe()")}}
+- {{domxref("HTMLIFrameElement.srcdoc")}}
+- {{domxref("Range.createContextualFragment()")}}
+- {{domxref("ShadowRoot.innerHTML")}}
+- {{domxref("ShadowRoot.setHTMLUnsafe()")}}
+
+#### TrustedScript
+
+- [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval)
+- [`Element.setAttribute()`](/en-US/docs/Web/API/Element/setAttribute#value) (`value` argument)
+- [`Element.setAttributeNS()`](/en-US/docs/Web/API/Element/setAttributeNS#value) (`value` argument)
+- [`Function()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/Function)
+- {{domxref("HTMLScriptElement.innerText")}}
+- {{domxref("HTMLScriptElement.textContent")}}
+- {{domxref("HTMLScriptElement.text")}}
+- [`window.setTimeout()`](/en-US/docs/Web/API/Window/setTimeout#code) and [`WorkerGlobalScope.setTimeout()`](/en-US/docs/Web/API/WorkerGlobalScope/setTimeout#code) (`code` argument)
+- [`window.setInterval()`](/en-US/docs/Web/API/Window/setInterval#code) and [`WorkerGlobalScope.setInterval()`](/en-US/docs/Web/API/WorkerGlobalScope/setInterval#code) (`code` argument)
+
+#### TrustedScriptURL
+
+- {{domxref("HTMLScriptElement.src")}}
+- {{domxref("ServiceWorkerContainer.register()")}}
+- {{domxref("SvgAnimatedString.baseVal")}}
+- {{domxref("WorkerGlobalScope.importScripts()")}}
+- `url` argument to [`Worker()` constructor](/en-US/docs/Web/API/Worker/Worker#url)
+- `url` argument to [`SharedWorker()` constructor](/en-US/docs/Web/API/SharedWorker/SharedWorker#url)
+
 ### 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).
@@ -201,6 +245,28 @@ Either way, the injection sink gets sanitized data, and because we could enforce
 - {{domxref("TrustedTypePolicyFactory")}}
   - : Creates policies and verifies that Trusted Type object instances were created via one of the policies.
 
+### Extensions to other interfaces
+
+- {{domxref("Window.trustedTypes")}}
+  - : Returns the {{domxref("TrustedTypePolicyFactory")}} object associated with the global object in the main thread.
+    This is the entry point for using the API in the Window thread.
+- {{domxref("WorkerGlobalScope.trustedTypes")}}.
+  - : Returns the {{domxref("TrustedTypePolicyFactory")}} object associated with the global object in a worker.
+
+### Extensions to HTTP
+
+#### `Content-Security-Policy` directives
+
+- {{CSP("require-trusted-types-for")}}
+  - : Enforces that [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) are passed to DOM XSS [injection sinks](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage).
+- {{CSP("trusted-types")}}
+  - : Used to specify an allowlist of [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) policy names.
+
+#### `Content-Security-Policy` keywords
+
+- [`trusted-types-eval`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#trusted-types-eval)
+  - : Allows [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) and similar functions to be used but only when [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) are supported and enforced.
+
 ## Examples
 
 In the below example we create a policy that will create {{domxref("TrustedHTML")}} objects using {{domxref("TrustedTypePolicyFactory.createPolicy()")}}. We can then use {{domxref("TrustedTypePolicy.createHTML()")}} to create a sanitized HTML string to be inserted into the document.
diff --git a/files/en-us/web/http/guides/csp/index.md b/files/en-us/web/http/guides/csp/index.md
@@ -329,7 +329,11 @@ Like inline JavaScript, if a CSP contains either a `default-src` or a `script-sr
   setTimeout("console.log('hello from setTimeout')", 1);
   ```
 
-The `unsafe-eval` keyword can be used to override this behavior, and as with `unsafe-inline`, and for the same reasons: **developers should avoid `unsafe-eval`**. Sometimes it can be difficult to remove usages of `eval()`: in these situations, the [Trusted Types API](/en-US/docs/Web/API/Trusted_Types_API) can make it safer, by ensuring that the input meets a defined policy.
+The `unsafe-eval` keyword can be used to override this behavior, and as with `unsafe-inline`, and for the same reasons: **developers should avoid `unsafe-eval`**.
+
+Sometimes it can be difficult to remove usages of `eval()` and the other methods: in these situations, the [Trusted Types API](/en-US/docs/Web/API/Trusted_Types_API) can make it safer, by ensuring that the input meets a defined policy.
+The `trusted-types-eval` keyword should be used to override the behavior in this case.
+Unlike `unsafe-inline` it only overrides the behavior in browser when trusted types are supported and enabled; which ensures that the methods will remain blocked on browsers that don't support trusted types.
 
 Unlike `unsafe-inline`, the `unsafe-eval` keyword does still work in a directive that contains nonce or hash expressions.
 
diff --git a/files/en-us/web/http/reference/headers/content-security-policy/index.md b/files/en-us/web/http/reference/headers/content-security-policy/index.md
@@ -159,10 +159,8 @@ Reporting directives control the destination URL for CSP violation reports in `C
   - : Used to specify an allowlist of [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) policies.
     Trusted Types allows applications to lock down DOM XSS injection sinks to only accept non-spoofable, typed values in place of strings.
 - {{CSP("upgrade-insecure-requests")}}
-  - : Instructs user agents to treat all of a site's insecure URLs (those served over
-    HTTP) as though they have been replaced with secure URLs (those served over HTTPS).
-    This directive is intended for websites with large numbers of insecure legacy URLs
-    that need to be rewritten.
+  - : Instructs user agents to treat all of a site's insecure URLs (those served over HTTP) as though they have been replaced with secure URLs (those served over HTTPS).
+    This directive is intended for websites with large numbers of insecure legacy URLs that need to be rewritten.
 
 ### Deprecated directives
 
@@ -272,14 +270,33 @@ Secure upgrades are allowed. For example:
 - If the document is served from `http://example.com`, then a CSP of `'self'` will also permit resources from `https://example.com`.
 - If the document is served from `ws://example.org`, then a CSP of `'self'` will also permit resources from `wss://example.org`.
 
+### 'trusted-types-eval'
+
+By default, if a CSP contains a `default-src` or a `script-src` directive, then JavaScript functions which evaluate their arguments as JavaScript are disabled.
+This includes [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval), the [`code`](/en-US/docs/Web/API/Window/setTimeout#code) argument to {{domxref("Window.setTimeout()", "setTimeout()")}}, or the {{jsxref("Function/Function()", "Function()")}} constructor.
+
+The `trusted-types-eval` keyword can be used to undo this protection, but only when [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) are enforced and passed to these functions instead of strings.
+This allows dynamic evaluation of strings as JavaScript, but only after inputs have been passed through a transformation function before it is injected, which has the chance to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input to remove potentially dangerous markup.
+
+The `trusted-types-eval` must be used instead of [`'unsafe-eval'`](#unsafe-eval) when using these methods with trusted types.
+This ensures that access to the methods is blocked on browsers that don't support trusted types.
+
+> [!NOTE]
+> Developers should avoid using `trusted-types-eval` or these methods unless absolutely necessary.
+> Trusted types ensure that the input passes through a transformation function — they don't ensure that the transformation makes the input safe (and this can be very hard to get right).
+
+See [`eval()` and similar APIs](/en-US/docs/Web/HTTP/Guides/CSP#eval_and_similar_apis) in the CSP guide for more usage information.
+
 ### 'unsafe-eval'
 
-By default, if a CSP contains a `default-src` or a `script-src` directive, then JavaScript functions which evaluate their arguments as JavaScript are disabled. This includes [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval), the [`code`](/en-US/docs/Web/API/Window/setTimeout#code) argument to {{domxref("Window.setTimeout()", "setTimeout()")}}, or the {{jsxref("Function/Function()", "Function()")}} constructor.
+By default, if a CSP contains a `default-src` or a `script-src` directive, then JavaScript functions which evaluate their arguments as JavaScript are disabled.
+This includes [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval), the [`code`](/en-US/docs/Web/API/Window/setTimeout#code) argument to {{domxref("Window.setTimeout()", "setTimeout()")}}, or the {{jsxref("Function/Function()", "Function()")}} constructor.
 
 The `unsafe-eval` keyword can be used to undo this protection, allowing dynamic evaluation of strings as JavaScript.
 
 > [!WARNING]
 > Developers should avoid `'unsafe-eval'`, because it defeats much of the purpose of having a CSP.
+> ['trusted-types-eval'](#trusted-types-eval) provides a "potentially" safer alternative if using these methods is necessary.
 
 See [`eval()` and similar APIs](/en-US/docs/Web/HTTP/Guides/CSP#eval_and_similar_apis) in the CSP guide for more usage information.
 
