diff --git a/sites/website/src/docs/3.x/advanced/dom-policy-and-trusted-types.md b/sites/website/src/docs/3.x/advanced/dom-policy-and-trusted-types.md new file mode 100644 index 00000000000..77b7970bf7b --- /dev/null +++ b/sites/website/src/docs/3.x/advanced/dom-policy-and-trusted-types.md @@ -0,0 +1,179 @@ +--- +id: dom-policy-and-trusted-types +title: DOMPolicy and Trusted Types +layout: 3x +eleventyNavigation: + key: dom-policy-and-trusted-types3x + parent: advanced3x + title: DOMPolicy and Trusted Types +navigationOptions: + activeKey: dom-policy-and-trusted-types3x +description: Configure DOMPolicy and Trusted Types for FAST Element templates and DOM bindings. +keywords: + - DOMPolicy + - Trusted Types + - security + - XSS + - templates +--- + +# DOMPolicy and Trusted Types + +FAST Element renders templates by compiling HTML strings and updating DOM sinks such as text content, attributes, properties, token lists, and event listeners. A `DOMPolicy` is the security boundary FAST uses for those operations. + +Use a policy to: + +- integrate FAST template compilation with the browser's [Trusted Types](https://developer.mozilla.org/docs/Web/API/Trusted_Types_API) enforcement; +- block, wrap, or sanitize sensitive binding sinks before FAST writes to them; +- document which application code is allowed to render raw HTML. + +## Configure a policy at startup + +`DOM.setPolicy()` installs the default policy used by FAST's templating system. It can only be called once, so configure it from an application entry module before custom elements are defined, templates are compiled, or templates are rendered. + +```ts +import { DOM } from "@microsoft/fast-element/dom.js"; +import { DOMPolicy } from "@microsoft/fast-element/dom-policy.js"; + +function sanitizeHTML(value: string): string { + // Use your application's HTML sanitizer here. + return value; +} + +const trustedType = globalThis.trustedTypes?.createPolicy("app-fast-html", { + createHTML: sanitizeHTML, +}) ?? { createHTML: sanitizeHTML }; + +DOM.setPolicy(DOMPolicy.create({ trustedType })); +``` + +If your Content Security Policy uses a `trusted-types` directive, the policy name you create must be allowed by that directive. If you rely on FAST's built-in Trusted Types policy, allow the `fast-element` policy name. + +:::important +Application owners should configure the global policy. Reusable component libraries should not call `DOM.setPolicy()` because doing so would prevent the host application from installing its own policy. +::: + +## Create policies with `DOMPolicy.create()` + +`DOMPolicy.create()` creates an immutable policy with two responsibilities: + +| Responsibility | What FAST uses it for | +|---|---| +| `createHTML(value)` | Converts the HTML string passed to template compilation into trusted HTML before FAST assigns it to a `