Adds TrustedHTML, TrustedScript, TrustedScriptURL (#2978)

* Adds TrustedHTML, TrustedScript, TrustedScriptURL * Update files/en-us/web/api/trustedhtml/index.html Co-authored-by: Joe Medley <[email protected]> * Update files/en-us/web/api/trustedhtml/index.html Co-authored-by: Joe Medley <[email protected]> * fixes * fixes from PR review Co-authored-by: Joe Medley <[email protected]>
mdn · Mar 22, 2021 · 592cdbf · 592cdbf
1 parent 5f17459
commit 592cdbf
Show file tree

Hide file tree

Showing 9 changed files with 510 additions and 0 deletions.
diff --git a/files/en-us/web/api/trustedhtml/index.html b/files/en-us/web/api/trustedhtml/index.html
@@ -0,0 +1,70 @@
+---
+title: TrustedHTML
+slug: Web/API/TrustedHTML
+tags:
+  - API
+  - Interface
+  - Reference
+  - TrustedHTML
+---
+<div>{{DefaultAPISidebar("Trusted Types API")}}</div>
+
+<p class="summary">The <strong><code>TrustedHTML</code></strong> interface of the {{domxref('Trusted Types API')}} represents a string that a developer can insert into an <a href="/en-US/docs/Web/API/Trusted_Types_API#injection_sinks">injection sink</a> that will render it as HTML. These objects are created via {{domxref("TrustedTypePolicy.createHTML", "TrustedTypePolicy.createHTML()")}} and therefore have no constructor.</p>
+
+<p>The value of a <strong>TrustedHTML</strong> object is set when the object is created and cannot be changed by JavaScript as there is no setter exposed.</p>
+
+<h2 id="Methods">Methods</h2>
+
+<dl>
+  <dt>{{domxref("TrustedHTML.toJSON()")}}</dt>
+  <dd>Returns a JSON representation of the stored data.</dd>
+  <dt>{{domxref("TrustedHTML.toString()")}}</dt>
+  <dd>A {{domxref("DOMString","string")}} containing the sanitized HTML.</dd>
+</dl>
+
+<h2 id="Examples">Examples</h2>
+
+<p>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.</p>
+
+<p>The sanitized value can then be used with {{domxref("Element.innerHTML")}} to ensure that no new HTML elements can be injected.</p>
+
+<pre class="brush: html">&lt;div id="myDiv"&gt;&lt;/div&gt;</pre>
+
+<pre class="brush: js">const escapeHTMLPolicy = trustedTypes.createPolicy("myEscapePolicy", {
+  createHTML: (string) =&gt; string.replace(/\&gt;/g, "&lt;")
+});
+
+let el = document.getElementById("myDiv");
+const escaped = escapeHTMLPolicy.createHTML("&lt;img src=x onerror=alert(1)&gt;");
+console.log(escaped instanceof TrustedHTML); // true
+el.innerHTML = escaped;
+</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+<table class="standard-table">
+  <tbody>
+   <tr>
+    <th scope="col">Specification</th>
+    <th scope="col">Status</th>
+    <th scope="col">Comment</th>
+   </tr>
+   <tr>
+    <td>{{SpecName('Trusted Types','#trusted-html','TrustedHTML')}}</td>
+    <td>{{Spec2('Trusted Types')}}</td>
+    <td>Initial definition.</td>
+   </tr>
+  </tbody>
+ </table>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<div class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>
+
+<p>{{Compat("api.TrustedHTML")}}</p>
+
+<h2 id="See_also">See also</h2>
+
+<ul>
+  <li><a href="https://web.dev/trusted-types/">Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types</a></li>
+</ul>
diff --git a/files/en-us/web/api/trustedhtml/tojson/index.html b/files/en-us/web/api/trustedhtml/tojson/index.html
@@ -0,0 +1,56 @@
+---
+title: TrustedHTML.toJSON()
+slug: Web/API/TrustedHTML/toJSON
+tags:
+  - API
+  - Method
+  - Reference
+  - toJSON
+  - TrustedHTML
+---
+<div>{{DefaultAPISidebar("Trusted Types API")}}</div>
+
+<p class="summary">The <strong><code>toJSON()</code></strong> method of the {{domxref("TrustedHTML")}} interface returns a JSON representation of the stored data.</p>
+
+<h2 id="Syntax">Syntax</h2>
+
+<pre class="syntaxbox">var <var>json</var> = <var>TrustedHTML</var>.toJSON();</pre>
+
+<h3 id="Returns">Return value</h3>
+
+<p>A {{domxref("DOMString","string")}} containing a JSON representation of the stored data.</p>
+
+<h2 id="Examples">Examples</h2>
+
+<p>The constant <code>escaped</code> is an object created via the Trusted Types policy escapeHTMLPolicy. The <code>toString()</code> method returns a string to safely insert into a document.</p>
+
+<pre class="brush: js">const escapeHTMLPolicy = trustedTypes.createPolicy("myEscapePolicy", {
+  createHTML: (string) =&gt; string.replace(/\&gt;/g, "&lt;")
+});
+
+const escaped = escapeHTMLPolicy.createHTML("&lt;img src=x onerror=alert(1)&gt;");
+console.log(escaped.toJSON());
+</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+<table class="standard-table">
+  <tbody>
+   <tr>
+    <th scope="col">Specification</th>
+    <th scope="col">Status</th>
+    <th scope="col">Comment</th>
+   </tr>
+   <tr>
+    <td>{{SpecName('Trusted Types','#dom-trustedhtml-tojson','TrustedHTML.toJSON()')}}</td>
+    <td>{{Spec2('Trusted Types')}}</td>
+    <td>Initial definition.</td>
+   </tr>
+  </tbody>
+ </table>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<div class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>
+
+<p>{{Compat("api.TrustedHTML.toJSON")}}</p>
diff --git a/files/en-us/web/api/trustedhtml/tostring/index.html b/files/en-us/web/api/trustedhtml/tostring/index.html
@@ -0,0 +1,56 @@
+---
+title: TrustedHTML.toString()
+slug: Web/API/TrustedHTML/toString
+tags:
+  - API
+  - Method
+  - Reference
+  - toString
+  - TrustedHTML
+---
+<div>{{DefaultAPISidebar("Trusted Types API")}}</div>
+
+<p class="summary">The <strong><code>toString()</code></strong> method of the {{domxref("TrustedHTML")}} interface returns a string which may safely inserted into an injection sink.</p>
+
+<h2 id="Syntax">Syntax</h2>
+
+<pre class="syntaxbox">var <var>str</var> = <var>TrustedHTML</var>.toString();</pre>
+
+<h3 id="Returns">Return value</h3>
+
+<p>A {{domxref("DOMString","string")}} containing the sanitized HTML.</p>
+
+<h2 id="Examples">Examples</h2>
+
+<p>The constant <code>escaped</code> is an object created via the Trusted Types policy escapeHTMLPolicy. The <code>toString()</code> method returns a string to safely insert into a document.</p>
+
+<pre class="brush: js">const escapeHTMLPolicy = trustedTypes.createPolicy("myEscapePolicy", {
+  createHTML: (string) =&gt; string.replace(/\&gt;/g, "&lt;")
+});
+
+const escaped = escapeHTMLPolicy.createHTML("&lt;img src=x onerror=alert(1)&gt;");
+console.log(escaped.toString());
+</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+<table class="standard-table">
+  <tbody>
+   <tr>
+    <th scope="col">Specification</th>
+    <th scope="col">Status</th>
+    <th scope="col">Comment</th>
+   </tr>
+   <tr>
+    <td>{{SpecName('Trusted Types','#trustedhtml-stringification-behavior','TrustedHTML.toString()')}}</td>
+    <td>{{Spec2('Trusted Types')}}</td>
+    <td>Initial definition.</td>
+   </tr>
+  </tbody>
+ </table>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<div class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>
+
+<p>{{Compat("api.TrustedHTML.toString")}}</p>
diff --git a/files/en-us/web/api/trustedscript/index.html b/files/en-us/web/api/trustedscript/index.html
@@ -0,0 +1,60 @@
+---
+title: TrustedScript
+slug: Web/API/TrustedScript
+tags:
+  - API
+  - Interface
+  - Reference
+  - TrustedScript
+---
+<div>{{DefaultAPISidebar("Trusted Types API")}}</div>
+
+<p class="summary">The <strong><code>TrustedScript</code></strong> interface of the {{domxref('Trusted Types API')}} represents a string with an uncompiled script body that a developer can insert into an <a href="/en-US/docs/Web/API/Trusted_Types_API#injection_sinks">injection sink</a> that might execute the script. These objects are created via {{domxref("TrustedTypePolicy.createScript","TrustedTypePolicy.createScript()")}} and therefore have no constructor.</p>
+
+<p>The value of a <strong>TrustedScript</strong> object is set when the object is created and cannot be changed by JavaScript as there is no setter exposed.</p>
+
+<h2 id="Methods">Methods</h2>
+
+<dl>
+  <dt>{{domxref("TrustedScript.toJSON()")}}</dt>
+  <dd>Returns a JSON representation of the stored data.</dd>
+  <dt>{{domxref("TrustedScript.toString()")}}</dt>
+  <dd>A {{domxref("DOMString","string")}} containing the sanitized script.</dd>
+</dl>
+
+<h2 id="Examples">Examples</h2>
+
+<p>The constant <code>sanitized</code> is an object created via a Trusted Types policy.</p>
+
+<pre class="brush: js">const sanitized = scriptPolicy.createScript("eval('2 + 2')");
+console.log(sanitized;) /* a TrustedScript object */
+</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+<table class="standard-table">
+  <tbody>
+   <tr>
+    <th scope="col">Specification</th>
+    <th scope="col">Status</th>
+    <th scope="col">Comment</th>
+   </tr>
+   <tr>
+    <td>{{SpecName('Trusted Types','#trusted-script','TrustedScript')}}</td>
+    <td>{{Spec2('Trusted Types')}}</td>
+    <td>Initial definition.</td>
+   </tr>
+  </tbody>
+ </table>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<div class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>
+
+<p>{{Compat("api.TrustedScript")}}</p>
+
+<h2 id="See_also">See also</h2>
+
+<ul>
+  <li><a href="https://web.dev/trusted-types/">Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types</a></li>
+</ul>
diff --git a/files/en-us/web/api/trustedscript/tojson/index.html b/files/en-us/web/api/trustedscript/tojson/index.html
@@ -0,0 +1,52 @@
+---
+title: TrustedScript.toJSON()
+slug: Web/API/TrustedScript/toJSON
+tags:
+  - API
+  - Method
+  - Reference
+  - toJSON
+  - TrustedScript
+---
+<div>{{DefaultAPISidebar("Trusted Types API")}}</div>
+
+<p class="summary">The <strong><code>toJSON()</code></strong> method of the {{domxref("TrustedScript")}} interface returns a JSON representation of the stored data.</p>
+
+<h2 id="Syntax">Syntax</h2>
+
+<pre class="syntaxbox">var <var>json</var> = <var>TrustedScript</var>.toJSON();</pre>
+
+<h3 id="Returns">Return value</h3>
+
+<p>A {{domxref("DOMString","string")}} containing a JSON representation of the stored data.</p>
+
+<h2 id="Examples">Examples</h2>
+
+<p>The constant <code>sanitized</code> is an object created via a Trusted Types policy. The <code>toString()</code> method returns a string to safely execute as a script.</p>
+
+<pre class="brush: js">const sanitized = scriptPolicy.createScript("eval('2 + 2')");
+  console.log(sanitized.toJSON());
+</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+<table class="standard-table">
+  <tbody>
+   <tr>
+    <th scope="col">Specification</th>
+    <th scope="col">Status</th>
+    <th scope="col">Comment</th>
+   </tr>
+   <tr>
+    <td>{{SpecName('Trusted Types','#dom-trustedscript-tojson','TrustedScript.toJSON()')}}</td>
+    <td>{{Spec2('Trusted Types')}}</td>
+    <td>Initial definition.</td>
+   </tr>
+  </tbody>
+ </table>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<div class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>
+
+<p>{{Compat("api.TrustedScript.toJSON")}}</p>
diff --git a/files/en-us/web/api/trustedscript/tostring/index.html b/files/en-us/web/api/trustedscript/tostring/index.html
@@ -0,0 +1,52 @@
+---
+title: TrustedScript.toString()
+slug: Web/API/TrustedScript/toString
+tags:
+  - API
+  - Method
+  - Reference
+  - toString
+  - TrustedScript
+---
+<div>{{DefaultAPISidebar("Trusted Types API")}}</div>
+
+<p class="summary">The <strong><code>toString()</code></strong> method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into an <a href="/en-US/docs/Web/API/Trusted_Types_API#injection_sinks">injection sink</a>.</p>
+
+<h2 id="Syntax">Syntax</h2>
+
+<pre class="syntaxbox">var <var>str</var> = <var>TrustedScript</var>.toString();</pre>
+
+<h3 id="Returns">Return value</h3>
+
+<p>A {{domxref("DOMString","string")}} containing the sanitized script.</p>
+
+<h2 id="Examples">Examples</h2>
+
+<p>The constant <code>sanitized</code> is an object created via a Trusted Types policy. The <code>toString()</code> method returns a string to safely execute as a script.</p>
+
+<pre class="brush: js">const sanitized = scriptPolicy.createScript("eval('2 + 2')");
+console.log(sanitized.toString());
+</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+<table class="standard-table">
+  <tbody>
+   <tr>
+    <th scope="col">Specification</th>
+    <th scope="col">Status</th>
+    <th scope="col">Comment</th>
+   </tr>
+   <tr>
+    <td>{{SpecName('Trusted Types','#trustedscript-stringification-behavior','TrustedScript.toString()')}}</td>
+    <td>{{Spec2('Trusted Types')}}</td>
+    <td>Initial definition.</td>
+   </tr>
+  </tbody>
+ </table>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<div class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>
+
+<p>{{Compat("api.TrustedScript.toString")}}</p>