New HTML setters

files/en-us/glossary/sanitize/index.md

@@ -0,0 +1,19 @@
+---
+title: sanitize
+slug: Glossary/Sanitize
+page-type: glossary-definition
+sidebar: glossarysidebar
+---
+
+Sanitization is the process of removing unsafe features from a string of HTML: for example, {{htmlelement("script")}} tags or inline event handlers.
+
+Since sanitization, like output encoding, is difficult to get right, it is often advised to do this through reputable third-party libraries like [DOMPurify](https://github.com/cure53/DOMPurify).
+
+The [HTML Sanitizer API](/en-US/docs/Web/API/HTML_Sanitizer_API) is a web platform API that provides a number of methods for removing unwanted HTML entities from HTML input before it is injected into the DOM. These come in XSS-safe versions (for example, {{domxref("Element.setHTML()")}}) that enforce removal of all unsafe elements and attributes, and potentially unsafe versions (for example, {{domxref("Element.setHTMLUnsafe()")}}) that give developers full control over the HTML entities that are allowed.
+
+## See also
+
+- [XSS sanitization](/en-US/docs/Web/Security/Attacks/XSS#sanitization)
+- [HTML Sanitizer API](/en-US/docs/Web/API/HTML_Sanitizer_API)
+- Related glossary terms:
+  - {{Glossary("Cross-site scripting")}}

files/en-us/web/api/characterdata/afterhtml/index.md

@@ -0,0 +1,151 @@
+---
+title: "CharacterData: afterHTML() method"
+short-title: afterHTML()
+slug: Web/API/CharacterData/afterHTML
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.CharacterData.afterHTML
+---
+
+{{APIRef("DOM")}}
+
+The **`afterHTML()`** method of the {{domxref("CharacterData")}} interface provides an XSS-safe method to parse and sanitize a string of HTML and insert it in the children list of the `CharacterData`'s parent, just after the `CharacterData`. Nothing happens if the node has no parent or the parent is a {{HTMLElement("script")}} element (and similar for SVG {{SVGElement("script")}} elements).
+
+The method removes any elements and attributes that are considered XSS-unsafe, even if the caller passes a [sanitizer](#sanitizer) option which allows them. For more information see the [HTML Sanitizer API](/en-US/docs/Web/API/HTML_Sanitizer_API).
+
+Notably, the following elements are always removed: {{HTMLElement("script")}}, {{HTMLElement("frame")}}, {{HTMLElement("iframe")}}, {{HTMLElement("embed")}}, {{HTMLElement("object")}}, {{HTMLElement("base")}}, {{SVGElement("use")}}, as well event handler content attributes (for example, `onclick`, `onload`, `onerror` and so forth). See [default sanitizer configuration](/en-US/docs/Web/API/HTML_Sanitizer_API/Default_sanitizer_configuration) for more information.
+
+## Syntax
+
+```js-nolint
+afterHTML(input)
+afterHTML(input, options)
+```
+
+### Parameters
+
+- `input` {{experimental_inline}}
+  - : A string defining HTML to be sanitized and inserted.
+- `options` {{optional_inline}} {{experimental_inline}}
+  - : An options object with the following optional parameters:
+    - `sanitizer` {{optional_inline}} {{experimental_inline}}
+      - : A {{domxref("Sanitizer")}} or {{domxref("SanitizerConfig")}} object which defines what elements of the input will be allowed or removed, or the string `"default"` for the default configuration.
+        The method will remove any XSS-unsafe elements and attributes, even if allowed by the sanitizer.
+        If not specified, the [default sanitizer configuration](/en-US/docs/Web/API/HTML_Sanitizer_API/Default_sanitizer_configuration) is used.
+
+        Note that if you're using the same configuration multiple times, it's expected to be more efficient to use a `Sanitizer` and modify it when you need to.
+
+### Return value
+
+None (`undefined`).
+
+### Exceptions
+
+- {{jsxref("TypeError")}} {{experimental_inline}}
+  - : This is thrown if `options.sanitizer` is passed a:
+    - {{domxref("SanitizerConfig")}} that isn't [valid](/en-US/docs/Web/API/SanitizerConfig#valid_configuration).
+      For example, a configuration that includes both "allowed" and "removed" configuration settings.
+    - string that does not have the value `"default"`.
+    - value that is not a {{domxref("Sanitizer")}}, {{domxref("SanitizerConfig")}}, or string.
+
+- `HierarchyRequestError` {{DOMxRef("DOMException")}}
+  - : Thrown when the parent element is a {{domxref("Document")}}, an {{HTMLElement("html")}} element, a {{HTMLElement("template")}} element, or a hostless {{domxref("DocumentFragment")}}.
+
+## Description
+
+`afterHTML()` drops any elements in the HTML input string that are invalid in the context of the node's parent element (or the shadow host, if the parent is a shadow root), such as a {{htmlelement("col")}} element outside of a {{htmlelement("table")}}.
+
+It then removes any HTML elements and attributes that aren't allowed by the sanitizer configuration, and further removes any XSS-unsafe elements or attributes — whether or not they are allowed by the sanitizer. For more information see the [HTML Sanitizer API](/en-US/docs/Web/API/HTML_Sanitizer_API).
+
+If no sanitizer is specified in the `options.sanitizer` parameter, `afterHTML()` is used with the [default sanitizer configuration](/en-US/docs/Web/API/HTML_Sanitizer_API/Default_sanitizer_configuration).
+This configuration is suitable for the majority of use cases as it prevents XSS attacks, as well as other attacks like clickjacking or spoofing.
+
+A custom {{domxref("Sanitizer")}} or {{domxref("SanitizerConfig")}} can be specified to choose which elements, attributes, and comments are allowed or removed.
+Note that even if unsafe options are allowed by the sanitizer, they will still be removed when using this method (it removes the same elements as a sanitizer on which {{domxref('Sanitizer.removeUnsafe()')}} has been called).
+
+`afterHTML()` can be used instead of {{domxref("Element.setHTML")}} when HTML needs to be inserted after a text or comment node.
+
+It should also be used instead of {{domxref("CharacterData.afterHTMLUnsafe()")}}, unless there is a specific need to allow unsafe elements and attributes.
+
+Note that since this method always sanitizes input strings of XSS-unsafe entities, it is not secured or validated using the [Trusted Types API](/en-US/docs/Web/API/Trusted_Types_API).
+
+### Related HTML setter APIs
+
+This is part of a series of APIs to set HTML in {{domxref("CharacterData")}}:
+
+| Action                                 | API                                                             | Unsafe API                                                                  |
+| -------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Replace the entire node with this HTML | {{domxref("CharacterData.replaceWithHTML", "replaceWithHTML")}} | {{domxref("CharacterData.replaceWithHTMLUnsafe", "replaceWithHTMLUnsafe")}} |
+| Add the HTML before the element        | {{domxref("CharacterData.beforeHTML", "beforeHTML")}}           | {{domxref("CharacterData.beforeHTMLUnsafe", "beforeHTMLUnsafe")}}           |
+| Add the HTML after the element         | {{domxref("CharacterData.afterHTML", "afterHTML")}}             | {{domxref("CharacterData.afterHTMLUnsafe", "afterHTMLUnsafe")}}             |
+
+Each API type takes the same arguments but allows for ease of inserting the required HTML in the appropriate place and with or without the default sanitizer applied. The unsafe variants allows scripts to be run using the `runScripts` options.
+
+Similar methods, and more, exist on {{domxref("Element")}} (for example {{domxref("Element.afterHTML")}}).
+
+## Examples
+
+> [!NOTE]
+> The [`setHTML()`](/docs/Web/API/Element/setHTML#examples) page includes additional examples, including a live example, which are similar to how `afterHTML()` can be used.
+
+These examples shows some of the ways you can use `afterHTML()` to sanitize and inject a string of HTML.
+
+### Basic usage with default sanitizer
+
+Using the default sanitizer:
+
+```js
+const unsanitizedString = "<p><i>abc</i><script>alert(1)<" + "/script> def</p>";
+const myText = document.getElementById("myText").firstChild;
+
+myText.afterHTML(unsanitizedString);
+// Result is that the following is added after the current text:
+// <p><i>abc</i> def</p>
+```
+
+### Using a custom sanitizer
+
+Using a custom `Sanitizer`, that allows only the {{htmlelement("div")}}, {{htmlelement("p")}}, {{htmlelement("button")}}, and {{htmlelement("script")}} elements. Note that {{htmlelement("script")}} is XSS-unsafe, so it will be removed anyway:
+
+```js
+const unsanitizedString = "<p><i>abc</i><script>alert(1)<" + "/script> def</p>";
+const myText = document.getElementById("myText").firstChild;
+
+const mySanitizer = new Sanitizer({
+  elements: ["div", "p", "button", "script"],
+});
+myText.afterHTML(unsanitizedString, { sanitizer: mySanitizer });
+// Result is that the following is added after the current text:
+// <p> def</p>
+```
+
+### Using a custom sanitizer with `removeElements`
+
+Using a custom `SanitizerConfig`, that removes only the {{htmlelement("div")}}, {{htmlelement("p")}}, {{htmlelement("button")}}, and {{htmlelement("script")}} elements, as well as other XSS-unsafe elements and attributes that are always removed by this method.
+
+```js
+const unsanitizedString = "<p><i>abc</i><script>alert(1)<" + "/script> def</p>";
+const myText = document.getElementById("myText").firstChild;
+
+myText.afterHTML(unsanitizedString, {
+  sanitizer: { removeElements: ["i", "script"] },
+});
+// Result is that the following is added after the current text:
+// <p> def</p>
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("CharacterData.afterHTMLUnsafe()")}}
+- {{domxref("Element.afterHTML()")}} and {{domxref("Element.afterHTMLUnsafe()")}}
+- {{domxref("Document.parseHTML_static", "Document.parseHTML()")}} and {{domxref("Document.parseHTMLUnsafe_static", "Document.parseHTMLUnsafe()")}}
+- [HTML Sanitizer API](/en-US/docs/Web/API/HTML_Sanitizer_API)