![Jack J](https://web.dev/images/authors/jackjey.jpg) Jack J [GitHub](https://github.com/JackJey)
Applications deal with untrusted strings all the time, but safely rendering that content as part of an HTML document can be tricky. Without sufficient care, you may accidentally create opportunities for [cross-site scripting](https://www.google.com/about/appsecurity/learning/xss/) (XSS) that malicious attackers may exploit. To mitigate that risk, the new [Sanitizer API](https://wicg.github.io/sanitizer-api/) proposal aims to build a robust processor for arbitrary strings to be safely inserted into a page. // Expanded Safely !! $div.setHTML(`hello world`, new Sanitizer()) ## Escape user input When inserting user input, query strings, cookie contents, and more, into the DOM, the strings must be escaped properly. Particular attention should be paid to DOM manipulation with [`.innerHTML`](https://developer.mozilla.org/docs/Web/API/Element/innerHTML), where unescaped strings are a typical source of XSS. const user_input = `hello world` $div.innerHTML = user_input If you escape HTML special characters in the input string or expand it using [`.textContent`](https://developer.mozilla.org/docs/Web/API/Node/textContent), `alert(0)` isn't executed. However, since `` added by the user is also expanded as a string as it is, this method cannot be used in order to keep the text decoration in HTML. The best thing to do here is not *escaping* , but *sanitizing*. ## Sanitize user input Escaping refers to replacing special HTML characters with [HTML Entities](https://developer.mozilla.org/docs/Glossary/Entity). Sanitizing refers to removing semantically harmful parts (such as script execution) from HTML strings. ### Example In the previous example, `` causes the error handler to be executed, but if the `onerror` handler was removed, it would be possible to safely expand it in the DOM while leaving `` intact. // XSS 🧨 $div.innerHTML = `hello world` // Sanitized ⛑ $div.innerHTML = `hello world` To sanitize correctly, it is necessary to parse the input string as HTML, omit tags and attributes that are considered harmful, and keep the harmless ones. The [proposed Sanitizer API specification](https://wicg.github.io/sanitizer-api/) aims to provide such processing as a standard API for browsers. > [!NOTE] > **Note:** Internet Explorer had implemented `window.toStaticHTML()` for this purpose, but it was never standardized. ## Sanitizer API The [Sanitizer API](https://wicg.github.io/sanitizer-api/) is used in the following way: const $div = document.querySelector('div') const user_input = `hello world` $div.setHTML(user_input, { sanitizer: new Sanitizer() }) //
hello world
However, the `{ sanitizer: new Sanitizer() }` is the default argument. $div.setHTML(user_input) //
hello world
It's worth noting that `setHTML()` is defined on [`Element`](https://developer.mozilla.org/docs/Web/API/Element). Being a method of `Element`, the context to parse is self-explanatory (`
` in this case), the parsing is done once internally, and the result is directly expanded into the DOM. To get the result of sanitization as a string, you can use `.innerHTML` from the `setHTML()` results. const $div = document.createElement('div') $div.setHTML(user_input) $div.innerHTML // hello world ### Customize with configuration The Sanitizer API is configured by default to remove strings that would trigger script execution. However, you can also add your own customizations to the sanitization process with a configuration object. const config = { allowElements: [], blockElements: [], dropElements: [], allowAttributes: {}, dropAttributes: {}, allowCustomElements: true, allowComments: true }; // sanitized result is customized by configuration new Sanitizer(config) The following options specify how the sanitization result should treat the specified element. `allowElements`: Names of elements that the sanitizer should retain. `blockElements`: Names of elements the sanitizer should remove, while retaining their children. `dropElements`: Names of elements the sanitizer should remove, along with their children. const str = `hello world` $div.setHTML(str) //
hello world
$div.setHTML(str, { sanitizer: new Sanitizer({allowElements: [ "b" ]}) }) //
hello world
$div.setHTML(str, { sanitizer: new Sanitizer({blockElements: [ "b" ]}) }) //
hello world
$div.setHTML(str, { sanitizer: new Sanitizer({allowElements: []}) }) //
hello world
You can also control whether the sanitizer will allow or deny specified attributes with the following options: - `allowAttributes` - `dropAttributes` `allowAttributes` and `dropAttributes` properties expect **attribute match lists** ---objects whose keys are attribute names, and values are lists of target elements or the `*` wildcard. const str = `hello` $div.setHTML(str) //
hello
$div.setHTML(str, { sanitizer: new Sanitizer({allowAttributes: {"style": ["span"]}}) }) //
hello
$div.setHTML(str, { sanitizer: new Sanitizer({allowAttributes: {"style": ["p"]}}) }) //
hello
$div.setHTML(str, { sanitizer: new Sanitizer({allowAttributes: {"style": ["*"]}}) }) //
hello
$div.setHTML(str, { sanitizer: new Sanitizer({dropAttributes: {"id": ["span"]}}) }) //
hello
$div.setHTML(str, { sanitizer: new Sanitizer({allowAttributes: {}}) }) //
hello
`allowCustomElements` is the option to allow or deny custom elements. If they're allowed, other configurations for elements and attributes still apply. const str = `hello` $div.setHTML(str) //
const sanitizer = new Sanitizer({ allowCustomElements: true, allowElements: ["div", "custom-elem"] }) $div.setHTML(str, { sanitizer }) //
hello
> [!NOTE] > **Note:** The Sanitizer API is designed to be safe by default. This means that no matter how you set it up, it will never allow constructs that are known XXS targets. For example, `allowElements: ["script"]` won't actually allow `