Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adds TrustedTypePolicyFactory #3192

Merged
merged 20 commits into from
Apr 6, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
ee183ca
Adds TrustedTypePolicyFactory
rachelandrew Mar 16, 2021
c18ef87
Update files/en-us/web/api/trustedtypepolicyfactory/createpolicy/inde…
rachelandrew Mar 17, 2021
711fe2d
Update files/en-us/web/api/trustedtypepolicyfactory/createpolicy/inde…
rachelandrew Mar 17, 2021
f58fa13
Update files/en-us/web/api/trustedtypepolicyfactory/isscript/index.html
rachelandrew Mar 17, 2021
257c7df
Update files/en-us/web/api/trustedtypepolicyfactory/isscript/index.html
rachelandrew Mar 17, 2021
cb6b2ac
Update files/en-us/web/api/trustedtypepolicyfactory/isscripturl/index…
rachelandrew Mar 17, 2021
da4bd4c
Update files/en-us/web/api/trustedtypepolicyfactory/isscripturl/index…
rachelandrew Mar 17, 2021
4314369
Update files/en-us/web/api/trustedtypepolicyfactory/isscripturl/index…
rachelandrew Mar 17, 2021
08ea1b0
Update files/en-us/web/api/trustedtypepolicyfactory/emptyscript/index…
rachelandrew Mar 17, 2021
7c5aadb
Update files/en-us/web/api/trustedtypepolicyfactory/getattributetype/…
rachelandrew Mar 17, 2021
d635d3e
Update files/en-us/web/api/trustedtypepolicyfactory/getpropertytype/i…
rachelandrew Mar 17, 2021
5676729
Update files/en-us/web/api/trustedtypepolicyfactory/index.html
rachelandrew Mar 17, 2021
054cc24
Update files/en-us/web/api/trustedtypepolicyfactory/ishtml/index.html
rachelandrew Mar 17, 2021
cfcbdee
Update files/en-us/web/api/trustedtypepolicyfactory/ishtml/index.html
rachelandrew Mar 17, 2021
3e1e04d
Update files/en-us/web/api/trustedtypepolicyfactory/ishtml/index.html
rachelandrew Mar 17, 2021
fb8a0bd
Update files/en-us/web/api/trustedtypepolicyfactory/isscript/index.html
rachelandrew Mar 17, 2021
7916109
Update files/en-us/web/api/trustedtypepolicyfactory/createpolicy/inde…
rachelandrew Mar 23, 2021
2aef5bf
edits from PR review
rachelandrew Mar 23, 2021
83726d4
adding a line about emptyScript and emptyHTML
rachelandrew Apr 1, 2021
8b32253
Adding note re default policy
rachelandrew Apr 6, 2021
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 107 additions & 0 deletions files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
---
title: TrustedTypePolicyFactory.createPolicy()
slug: Web/API/TrustedTypePolicyFactory/createPolicy
tags:
- API
- Method
- Reference
- createPolicy
- TrustedTypePolicyFactory
---
<div>{{DefaultAPISidebar("Trusted Types API")}}</div>

<p class="summary">The <strong><code>createPolicy()</code></strong> method of the {{domxref("TrustedTypePolicyFactory")}} interface creates a {{domxref("TrustedTypePolicy")}} object that implements the rules passed as <code>policyOptions</code>.</p>

<h3 id="Default_policy">The default policy</h3>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hate to throw this back at you again, but this needs to have information that aspects of the default policy are non-normative and specific to Chrome. This kind of thing is not unprecedented on MDN. If a normative approach emerges in the future, Chrome will likely be the first to implement it, giving us the chance to update this.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't really understand what you want me to do here or where this non-normative information is from that you want me to include. I've searched the spec, for all instances of defaultPolicy, and I seem to have documented this according to the spec.

I also looked at the open issues on the spec: https://github.com/w3c/webappsec-trusted-types/issues

I did note in my original comment on this that I didn't understand your non-normative comment: #3192 (comment)

What aspect are you suggesting is specific to Chrome? Given that only Chromium has implemented I can't test it to find out what other UAs are doing to try and work this out myself.

If you can let me know where you have this Chromium specific info from I'll fold it in :)

Copy link
Collaborator

@jpmedley jpmedley Apr 2, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://w3c.github.io/webappsec-trusted-types/dist/spec/#default-policy-hdr

  • Somewhere say that the default is currently set in Chrome by creating a policy with the name "default". If another browser implements this differently, they'll have a logical place to document it. If Chrome's current behavior is ratified, we'll be able to remove the word 'Chrome' from the description.
  • Include a disclaimer that this isn't settled in the spec and may change in the future.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done in latest commit, though I think that really the same could be said about pretty much any feature only implemented in one engine! Hence my general bemusement.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand your concern. This is a judgement call based on experience with very new APIs. We'll discuss this in our 1:1 this week. Thank you for trusting me.


<p>In Chrome a policy with a name of "default" creates a special policy that will be used if a string (rather than a Trusted Type object) is passed to an injection sink. This can be used in a transitional phase while moving from an application that inserted strings into injection sinks.</p>

<div class="notecard note">
<h4>Note</h4>
<p>The above behavior is not yet settled in the specification and may change in future.</p>
</div>

<div class="notecard warning">
<h4>Note</h4>
<p>A lax default policy could defeat the purpose of using Trusted Types, and therefore should be defined with strict rules to ensure it cannot be used to run dangerous code.</p>
</div>

<h2 id="Syntax">Syntax</h2>

<pre class="syntaxbox">var <var>policy</var> = <var>TrustedTypePolicyFactory</var>.createPolicy(<var>policyName</var>,<var>policyOptions</var>);</pre>

<h3 id="Parameters">Parameters</h3>

<dl>
<dt><code>policyName</code></dt>
<dd>A {{domxref("DOMString")}} with the name of the policy.</dd>
<dt><code>policyOptions</code>{{optional_inline}}</dt>
<dd>User-defined functions for converting strings into trusted values.
<dl>
<dt><code>CreateHTML(<var>input</var>[,<var>args</var>])</code></dt>
<dd>A callback function in the form of a {{domxref("DOMString", "string")}} that contains code to run when creating a {{domxref("TrustedHTML")}} object.</dd>
<dt><code>CreateScript(<var>input</var>[,<var>args</var>])</code></dt>
<dd>A callback function in the form of a {{domxref("DOMString", "string")}} that contains code to run when creating a {{domxref("TrustedScript")}} object.</dd>
<dt><code>CreateScriptURL(<var>input</var>[,<var>args</var>])</code></dt>
<dd>A callback function in the form of a {{domxref("DOMString", "string")}} that contains code to run when creating a {{domxref("TrustedScriptURL")}} object.</dd>
</dl>
</dd>
</dl>

<h3 id="Returns">Return value</h3>

<p>A {{domxref("TrustedTypePolicy")}} object.</p>

<h3 id="Exceptions">Exceptions</h3>

<dl>
<dt>{{jsxref("TypeError")}}</dt>
<dd>Thrown if policy names are restricted by the <a href="/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types">Content Security Policy <code>trusted-types</code> directive</a> and this name is not on the allowlist.</dd>
<dt>{{jsxref("TypeError")}}</dt>
<dd>Thrown if the name is a duplicate and the <a href="/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types">Content Security Policy trusted-types directive</a> is not using <code>allow-duplicates</code>.</dd>
</dl>

<h2 id="Examples">Examples</h2>

<p>The below code creates a policy with the name <code>"myEscapePolicy"</code> with a function defined for <code>createHTML()</code> which sanitizes HTML.</p>

<pre class="brush: js">const escapeHTMLPolicy = trustedTypes.createPolicy("myEscapePolicy", {
createHTML: (string) =&gt; string.replace(/\&gt;/g, "&lt;")
});</pre>

<h3>Creating a default policy</h3>

<p>On a site where Trusted Types are enforced via a Content Security Policy with the <code><a href="/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/require-trusted-types-for">require-trusted-types-for</a></code> directive set to <code>script</code>, any injection script that accepts a script expects a Trusted Type object. In the case that a string is inserted instead, the following default policy will be used.</p>

<p>The policy logs a message to the console to remind the developer to refactor this part of the application to use a Trusted Type object. It also appends details of the use of the default policy, type, and injection sink to the returned value.</p>

<pre class="brush: js">trustedTypes.createPolicy('default', {
createScriptURL: (s, type, sink) => {
console.log("Please refactor.");
return s + '?default-policy-used&type=' + encodeURIComponent(type) +
'&sink=' + encodeURIComponent(sink);
}
});</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-trustedtypepolicyfactory-createpolicy','TrustedTypePolicyFactory.createPolicy()')}}</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.TrustedTypePolicyFactory.createPolicy")}}</p>
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
title: TrustedTypePolicyFactory.defaultPolicy
slug: Web/API/TrustedTypePolicyFactory/defaultPolicy
tags:
- API
- Property
- Reference
- defaultPolicy
- TrustedTypePolicyFactory
---
<div>{{DefaultAPISidebar("Trusted Types API")}}</div>

<p class="summary">The <strong><code>defaultPolicy</code></strong> read-only property of the {{domxref("TrustedTypePolicyFactory")}} interface returns the default {{domxref("TrustedTypePolicy")}} or null if this is empty.</p>
jpmedley marked this conversation as resolved.
Show resolved Hide resolved

<div class="notecard note">
<h4>Note</h4>
<p>Information about the creation and use of default policies can be found in the <code><a href="/en-US/docs/Web/API/TrustedTypePolicyFactory/createPolicy#default_policy">createPolicy()</a></code> documentation.</p>
</div>

<h2 id="Syntax">Syntax</h2>

<pre class="syntaxbox">var <var>defaultPolicy</var> = <var>TrustedTypePolicyFactory</var>.defaultPolicy;</pre>

<h3>Value</h3>
<p>A {{domxref("TrustedTypePolicy")}} or null.</p>

<h2 id="Examples">Examples</h2>

<p>The first line below returns null as no default policy has been created. Once a default policy is created, calling <code>defaultPolicy</code> returns that policy object.</p>

<pre class="brush: js">console.log(trustedTypes.defaultPolicy); // null
const dp = trustedTypes.createPolicy('default', {});
console.log(trustedTypes.defaultPolicy); // a TrustedTypePolicy 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','#dom-trustedtypepolicyfactory-defaultpolicy','TrustedTypePolicyFactory.defaultPolicy')}}</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.TrustedTypePolicyFactory.defaultPolicy")}}</p>
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
---
title: TrustedTypePolicyFactory.emptyHTML
slug: Web/API/TrustedTypePolicyFactory/emptyHTML
tags:
- API
- Property
- Reference
- emptyHTML
- TrustedTypePolicyFactory
---
<div>{{DefaultAPISidebar("Trusted Types API")}}</div>

<p class="summary">The <strong><code>emptyHTML</code></strong> read-only property of the {{domxref("TrustedTypePolicyFactory")}} interface returns a {{domxref("TrustedHTML")}} object containing an empty string.</p>
rachelandrew marked this conversation as resolved.
Show resolved Hide resolved

<p>This object can be used when the application requires an empty string to be inserted into an injection sink.</p>

<h2 id="Syntax">Syntax</h2>

<pre class="syntaxbox">var <var>emptyHTML</var> = <var>TrustedTypePolicyFactory</var>.emptyHTML;</pre>

<h3>Value</h3>
<p>A {{domxref("TrustedHTML")}} object.</p>

<h2 id="Examples">Examples</h2>

<p>In the below example an empty string is to be inserted into the element. Therefore there is no need to create a policy, and the <code>emptyHTML</code> property can be used to insert the empty element when a Trusted Types object is expected.</p>

<pre class="brush: js">el.innerHTML = trustedTypes.emptyHTML;</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-trustedtypepolicyfactory-emptyhtml','TrustedTypePolicyFactory.emptyHTML')}}</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.TrustedTypePolicyFactory.emptyHTML")}}</p>
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
---
title: TrustedTypePolicyFactory.emptyScript
slug: Web/API/TrustedTypePolicyFactory/emptyScript
tags:
- API
- Property
- Reference
- emptyScript
- TrustedTypePolicyFactory
---
<div>{{DefaultAPISidebar("Trusted Types API")}}</div>

<p class="summary">The <strong><code>emptyScript</code></strong> read-only property of the {{domxref("TrustedTypePolicyFactory")}} interface returns a {{domxref("TrustedScript")}} object containing an empty string.</p>

<p>This object can be used when the application requires an empty string to be inserted into an injection sink which is expecting a <code>TrustedScript</code> object.</p>

<h2 id="Syntax">Syntax</h2>

<pre class="syntaxbox">var <var>emptyScript</var> = <var>TrustedTypePolicyFactory</var>.emptyScript;</pre>

<h3>Value</h3>
<p>A {{domxref("TrustedScript")}} object.</p>

<h2 id="Examples">Examples</h2>

<p>The <a href="https://w3c.github.io/webappsec-trusted-types/dist/spec/#dom-trustedtypepolicyfactory-emptyscript">specification</a> explains that the <code>emptyScript</code> object can be used to detect support for dynamic code compilation.</p>
jpmedley marked this conversation as resolved.
Show resolved Hide resolved

<p>Native Trusted Types implementations can support <code>eval(TrustedScript)</code>, therefore in the below example a native implementation will return false for <code>eval(trustedTypes.emptyScript)</code>. A polyfill will return a truthy object.</p>

<pre class="brush: js">const supportsTS = !eval(trustedTypes.emptyScript);
eval(supportsTS ? myTrustedScriptObj : myTrustedScriptObj.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','#dom-trustedtypepolicyfactory-emptyscript','TrustedTypePolicyFactory.emptyScript')}}</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.TrustedTypePolicyFactory.emptyScript")}}</p>
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
---
title: TrustedTypePolicyFactory.getAttributeType()
slug: Web/API/TrustedTypePolicyFactory/getAttributeType
tags:
- API
- Method
- Reference
- getAttributeType
- TrustedTypePolicyFactory
---
<div>{{DefaultAPISidebar("Trusted Types API")}}</div>

<p class="summary">The <strong><code>getAttributeType()</code></strong> method of the {{domxref("TrustedTypePolicyFactory")}} interface allows web developers to check if a Trusted Type is required for an element, and if so which Trusted Type is used.</p>

<h2 id="Syntax">Syntax</h2>

<pre class="syntaxbox">var <var>attributeType</var> = <var>TrustedTypePolicyFactory</var>.getAttributeType(<var>tagName</var>,<var>attribute</var>[,<var>elementNs</var>,<var>attrNs</var>]);</pre>

<h3 id="Parameters">Parameters</h3>

<dl>
<dt><code>tagName</code></dt>
<dd>A {{domxref("DOMString","string")}} containing the name of an HTML tag.</dd>
<dt><code>attribute</code></dt>
<dd>A {{domxref("DOMString","string")}} containing an attribute.</dd>
jpmedley marked this conversation as resolved.
Show resolved Hide resolved
<dt><code>elementNs</code>{{optional_inline}}</dt>
<dd>A {{domxref("DOMString","string")}} containing a namespace, if empty defaults to the HTML namespace.</dd>
<dt><code>attrNs</code>{{optional_inline}}</dt>
<dd>A {{domxref("DOMString","string")}} containing a namespace, if empty defaults to null.</dd>
</dl>

<h3 id="Returns">Return value</h3>

<p>A {{domxref("DOMString","string")}} with one of:</p>
<ul>
<li><code>"TrustedHTML"</code></li>
<li><code>"TrustedScript"</code></li>
<li><code>"TrustedScriptURL"</code></li>
</ul>

<p>Or, null.</p>

<h2 id="Examples">Examples</h2>

<p>In this example, passing the {{htmlelement("script")}} element and {{htmlattrxref("src")}} attribute to <code>getAttributeType</code> returns "TrustedScriptURL".</p>

<pre class="brush: js">console.log(trustedTypes.getAttributeType('script', 'src')); // "TrustedScriptURL"</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-trustedtypepolicyfactory-getattributetype','TrustedTypePolicyFactory.getAttributeType()')}}</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.TrustedTypePolicyFactory.getAttributeType")}}</p>
Loading