Skip to content

Commit 78741b7

Browse files
clellanddomenic
clelland
authored and
domenic
committed
Integrate Feature Policy concepts into HTML
This commit introduces the feature policy for Document objects, adds the 'allow' attribute to iframe elements, and reframes 'allowfullscreen', 'allowpaymentrequest' and 'allowusermedia' in terms of feature policy. Document allow* flags are removed, as they are no longer referenced. The 'allowed to use' algorithm is also updated to call into the feature policy 'Is feature enabled' algorithm, and rewritten to take a policy- controlled feature as an argument rather than an attribute, so that other specs can also use it to control other features. Tests: - web-platform-tests/wpt#10966 - web-platform-tests/wpt@3cc0d89 - web-platform-tests/wpt@9a00e4a - web-platform-tests/wpt#4625
1 parent 4539076 commit 78741b7

File tree

1 file changed

+142
-120
lines changed

1 file changed

+142
-120
lines changed

‎source

Lines changed: 142 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -4007,6 +4007,22 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
40074007
</ul>
40084008
</dd>
40094009

4010+
<dt>Feature Policy</dt>
4011+
4012+
<dd>
4013+
<p>The following terms are defined in <cite>Feature Policy</cite>: <ref spec="FEATUREPOLICY"></p>
4014+
4015+
<ul class="brief">
4016+
<li><dfn data-x="concept-feature-policy" data-x-href="https://wicg.github.io/feature-policy/#feature-policy">feature policy</dfn></li>
4017+
<li><dfn data-x="concept-container-policy" data-x-href="https://wicg.github.io/feature-policy/#container-policy">container policy</dfn></li>
4018+
<li><dfn data-x="concept-serialized-feature-policy" data-x-href="https://wicg.github.io/feature-policy/#serialized-feature-policy">serialized feature policy</dfn></li>
4019+
<li>The <dfn data-x-href="https://wicg.github.io/feature-policy/#initialize-for-document">Initialize document’s feature policy</dfn> algorithm</li>
4020+
<li>The <dfn data-x-href="https://wicg.github.io/feature-policy/#initialize-from-response">Initialize document’s feature policy from response</dfn> algorithm</li>
4021+
<li>The <dfn data-x="is-feature-enabled" data-x-href="https://wicg.github.io/feature-policy/#is-feature-enabled">Is feature enabled by policy for origin</dfn> algorithm</li>
4022+
<li>The <dfn data-x="process-feature-policy-attributes" data-x-href="https://wicg.github.io/feature-policy/#process-feature-policy-attributes">Process feature policy attributes</dfn> algorithm</li>
4023+
</ul>
4024+
</dd>
4025+
40104026

40114027
<dt>Payment Request API</dt>
40124028

@@ -9212,6 +9228,10 @@ partial interface <dfn id="document" data-lt="">Document</dfn> {
92129228
containing all of the <span>Content Security Policy</span> objects active for the document. The
92139229
list is empty unless otherwise specified.</p>
92149230

9231+
<p>The <code>Document</code> has a <dfn data-x="concept-document-feature-policy" data-export=""
9232+
data-dfn-for="Document">feature policy</dfn>, which is a <span
9233+
data-x="concept-feature-policy">feature policy</span>, which is initially empty.</p>
9234+
92159235
<p>The <code>Document</code> has a <dfn data-dfn-for="Document"
92169236
data-x="concept-document-module-map">module map</dfn>, which is a <span>module map</span>,
92179237
initially empty.</p>
@@ -29438,6 +29458,7 @@ href="?audio">audio&lt;/a> test instead.)&lt;/p></pre>
2943829458
<dd><code data-x="attr-iframe-srcdoc">srcdoc</code></dd>
2943929459
<dd><code data-x="attr-iframe-name">name</code></dd>
2944029460
<dd><code data-x="attr-iframe-sandbox">sandbox</code></dd>
29461+
<dd><code data-x="attr-iframe-allow">allow</code></dd>
2944129462
<dd><code data-x="attr-iframe-allowfullscreen">allowfullscreen</code></dd>
2944229463
<dd><code data-x="attr-iframe-allowpaymentrequest">allowpaymentrequest</code></dd>
2944329464
<dd><code data-x="attr-iframe-allowusermedia">allowusermedia</code></dd>
@@ -29453,6 +29474,7 @@ interface <dfn>HTMLIFrameElement</dfn> : <span>HTMLElement</span> {
2945329474
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-iframe-srcdoc">srcdoc</span>;
2945429475
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-iframe-name">name</span>;
2945529476
[SameObject, PutForwards=<span data-x="dom-DOMTokenList-value">value</span>] readonly attribute <span>DOMTokenList</span> <span data-x="dom-iframe-sandbox">sandbox</span>;
29477+
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-iframe-allow">allow</span>;
2945629478
[<span>CEReactions</span>] attribute boolean <span data-x="dom-iframe-allowFullscreen">allowFullscreen</span>;
2945729479
[<span>CEReactions</span>] attribute boolean <span data-x="dom-iframe-allowPaymentRequest">allowPaymentRequest</span>;
2945829480
[<span>CEReactions</span>] attribute boolean <span data-x="dom-iframe-allowUserMedia">allowUserMedia</span>;
@@ -29959,13 +29981,30 @@ interface <dfn>HTMLIFrameElement</dfn> : <span>HTMLElement</span> {
2995929981
</div>
2996029982

2996129983

29962-
<hr> <!-- ALLOW FULLSCREEN / USER MEDIA -->
29984+
<hr> <!-- FEATURE POLICY ATTRIBUTES: ALLOW; ALLOW FULLSCREEN / PAYMENT REQUEST / USER MEDIA -->
29985+
29986+
<p>The <dfn><code data-x="attr-iframe-allow">allow</code></dfn> attribute, when specified,
29987+
determines the <span data-x="concept-container-policy">container policy</span> that will be used
29988+
when the <span data-x="concept-document-feature-policy">feature policy</span> for a
29989+
<span>Document</span> in the <code>iframe</code>'s <span>nested browsing context</span> is
29990+
initialized. Its value must be a <span data-x="concept-serialized-feature-policy">serialized
29991+
feature policy</span>. <ref spec="FEATUREPOLICY">
29992+
29993+
<div class="example">
29994+
<p>In this example, an <code>iframe</code> is used to embed a map from an online navigation
29995+
service. The <code data-x="attr-iframe-allow">allow</code> attribute is used to enable the
29996+
Geolocation API within the nested context.</p>
29997+
29998+
<pre>&lt;iframe src="https://maps.example.com/" allow="geolocation">&lt;/iframe></pre>
29999+
</div>
2996330000

2996430001
<p>The <dfn><code data-x="attr-iframe-allowfullscreen">allowfullscreen</code></dfn> attribute is a
2996530002
<span>boolean attribute</span>. When specified, it indicates that <code>Document</code> objects in
29966-
the <code>iframe</code> element's <span>browsing context</span> are to be allowed to use <code
29967-
data-x="dom-element-requestFullscreen">requestFullscreen()</code> (if it's not blocked for other
29968-
reasons, e.g. there is another ancestor <code>iframe</code> without this attribute set).</p>
30003+
the <code>iframe</code> element's <span>browsing context</span> will be initialized with a
30004+
<span data-x="concept-document-feature-policy">feature policy</span> which allows the <code
30005+
data-x="">fullscreen</code> feature to be used from any <span>origin</span>. This is enforced by
30006+
the <span data-x="process-feature-policy-attributes">Process feature policy attributes</span>
30007+
algorithm. <ref spec="FEATUREPOLICY">
2996930008

2997030009
<div class="example">
2997130010

@@ -29987,18 +30026,32 @@ interface <dfn>HTMLIFrameElement</dfn> : <span>HTMLElement</span> {
2998730026
<p>The <dfn><code data-x="attr-iframe-allowpaymentrequest">allowpaymentrequest</code></dfn>
2998830027
attribute is a <span>boolean attribute</span>. When specified, it indicates that
2998930028
<code>Document</code> objects in the <code>iframe</code> element's <span>browsing context</span>
29990-
are to be allowed to use the <code>PaymentRequest</code> interface to make payment requests.</p>
30029+
will be initialized with a <span data-x="concept-document-feature-policy">feature policy</span>
30030+
which allows the <code data-x="">payment</code> feature to be used to make payment requests from
30031+
any <span>origin</span>. This is enforced by the <span
30032+
data-x="process-feature-policy-attributes">Process feature policy attributes</span> algorithm.
30033+
<ref spec="FEATUREPOLICY">
2999130034

2999230035
<p>The <dfn><code data-x="attr-iframe-allowusermedia">allowusermedia</code></dfn> attribute is a
2999330036
<span>boolean attribute</span>. When specified, it indicates that <code>Document</code> objects in
29994-
the <code>iframe</code> element's <span>browsing context</span> are to be allowed to use <code
29995-
data-x="dom-MediaDevices-getUserMedia">getUserMedia()</code> (if it's not blocked for other
29996-
reasons, e.g. there is another ancestor <code>iframe</code> without this attribute set).</p>
30037+
the <code>iframe</code> element's <span>browsing context</span> will be initialized with a <span
30038+
data-x="concept-document-feature-policy">feature policy</span> which allows the
30039+
<code data-x="">camera</code> and <code data-x="">microphone</code> features to be used to call
30040+
<code data-x="dom-MediaDevices-getUserMedia">getUserMedia()</code> from any <span>origin</span>.
30041+
This is enforced by the <span data-x="process-feature-policy-attributes">Process feature policy
30042+
attributes</span> algorithm. <ref spec="FEATUREPOLICY">
30043+
30044+
<p class="note">None of these attributes, <code data-x="attr-iframe-allow">allow</code>,
30045+
<code data-x="attr-iframe-allowfullscreen">allowfullscreen</code>, <code
30046+
data-x="attr-iframe-allowpaymentrequest">allowpaymentrequest</code> or <code
30047+
data-x="attr-iframe-allowusermedia">allowusermedia</code>, can grant access to a feature in a
30048+
<span>nested browsing context</span> if the <code>iframe</code> element's <span>node
30049+
document</span> is not already allowed to use that feature.</p>
2999730050

2999830051
<div w-nodev>
2999930052
<p id="fullscreen-logic">To determine whether a <code>Document</code> object <var>document</var>
30000-
is <dfn data-export="">allowed to use</dfn> the feature indicated by attribute name
30001-
<var>allowattribute</var>, run these steps:</p>
30053+
is <dfn data-export="">allowed to use</dfn> the policy-controlled-feature <var>feature</var>,
30054+
run these steps:</p>
3000230055

3000330056
<ol>
3000430057
<li><p>If <var>document</var> has no <span data-x="concept-document-bc">browsing context</span>,
@@ -30007,117 +30060,24 @@ interface <dfn>HTMLIFrameElement</dfn> : <span>HTMLElement</span> {
3000730060
<li><p>If <var>document</var>'s <span data-x="concept-document-bc">browsing context</span>'s
3000830061
<span>active document</span> is not <var>document</var>, then return false.</p></li>
3000930062

30010-
<li><p>If <var>document</var>'s <span data-x="concept-document-bc">browsing context</span> is a
30011-
<span>top-level browsing context</span>, then return true.</p></li>
30012-
30013-
<li>
30014-
<p>If <var>allowattribute</var> is <code
30015-
data-x="attr-iframe-allowfullscreen">allowfullscreen</code>, then:</p>
30016-
30017-
<ol>
30018-
<li><p>If <var>document</var>'s <span data-x="concept-document-bc">browsing context</span> has
30019-
a <span>browsing context container</span> that is an <code>iframe</code> element with an
30020-
<var>allowattribute</var> attribute specified, and whose <span>node document</span> is
30021-
<span>allowed to use</span> the feature indicated by <var>allowattribute</var>, then return
30022-
true.</p></li>
30023-
</ol>
30024-
30025-
<p class="big-issue">This step is legacy behavior for the <code
30026-
data-x="attr-iframe-allowfullscreen">allowfullscreen</code> attribute that should not be used
30027-
for new features. If possible this will be removed, see <a
30028-
href="https://github.com/whatwg/html/issues/2143#issuecomment-265514585">issue 2143</a>.</p>
30029-
</li>
30030-
30031-
<li>
30032-
<p>Otherwise:</p>
30033-
30034-
<ol>
30035-
<li><p>If <var>document</var> has the <var><var>allowattribute</var> flag</var> set, and
30036-
<var>document</var>'s <span data-x="concept-document-bc">browsing context</span> has a
30037-
<span>browsing context container</span> that is an <code>iframe</code> element whose
30038-
<span>node document</span> is <span>allowed to use</span> the feature indicated by
30039-
<var>allowattribute</var>, then return true.</p></li>
30040-
</ol>
30041-
</li>
30063+
<li><p>If the result of running <span data-x="is-feature-enabled">Is feature enabled in document
30064+
for origin</span> on <var>feature</var>, <var>document</var>, and <var>document</var>'s
30065+
<span>origin</span> is "<code data-x="">Enabled</code>", then return true.</p></li>
3004230066

3004330067
<li><p>Return false.</p></li>
3004430068
</ol>
30069+
</div>
3004530070

30046-
<p>To <dfn>set the allow* flags</dfn> for a <code>Document</code> <var>document</var> means to
30047-
run these steps:</p>
30048-
30049-
<ol>
30050-
<li>
30051-
<p>If <var>document</var>'s <span data-x="concept-document-bc">browsing context</span> has a
30052-
<span>browsing context container</span> whose <span>node document</span>'s <span>origin</span>
30053-
is <span>same origin-domain</span> with <var>document</var>'s <span>origin</span>, then set the
30054-
<var>allowpaymentrequest flag</var> and the <var>allowusermedia flag</var> on
30055-
<var>document</var>, and return.</p>
30056-
30057-
<p class="note">If <code data-x="dom-document-domain">document.domain</code> has been used for
30058-
the <span>browsing context container</span>'s <span>node document</span>, then its
30059-
<span>origin</span> cannot be <span>same origin-domain</span> with <var>document</var>'s
30060-
<span>origin</span>, because these steps run when <var>document</var> is initialized so it
30061-
cannot itself yet have used <code data-x="dom-document-domain">document.domain</code>. Note
30062-
that this is less permissive compared to doing a <span>same origin</span> check instead.</p>
30063-
30064-
<div class="example">
30065-
<p>In this example, the child document is not allowed to use <code>PaymentRequest</code>,
30066-
despite being <span>same origin-domain</span> at the time the child document tries to use it.
30067-
At the time the child document is initialized, only the parent document has set <code
30068-
data-x="dom-document-domain">document.domain</code>, and the child document has not.</p>
30069-
30070-
<pre>&lt;!-- https://foo.example.com/a.html -->
30071-
&lt;!doctype html>
30072-
&lt;script>
30073-
document.domain = 'example.com';
30074-
&lt;/script>
30075-
&lt;iframe src=b.html>&lt;/iframe></pre>
30076-
30077-
<pre>&lt;!-- https://bar.example.com/b.html -->
30078-
&lt;!doctype html>
30079-
&lt;script>
30080-
document.domain = 'example.com'; // This happens after the document is initialized
30081-
new PaymentRequest(&hellip;); // Not allowed to use
30082-
&lt;/script></pre>
30083-
</div>
30084-
30085-
<div class="example">
30086-
<p>In this example, the child document <em>is</em> allowed to use <code>PaymentRequest</code>,
30087-
despite not being <span>same origin-domain</span> at the time the child document tries to use
30088-
it. At the time the child document is initialized, none of the documents have set <code
30089-
data-x="dom-document-domain">document.domain</code> yet so <span>same origin-domain</span>
30090-
falls back to a normal <span>same origin</span> check.</p>
30091-
30092-
<pre>&lt;!-- https://example.com/a.html -->
30093-
&lt;!doctype html>
30094-
&lt;iframe src=b.html>&lt;/iframe>
30095-
&lt;!-- The child document is now initialized, before the script below is run. -->
30096-
&lt;script>
30097-
document.domain = 'example.com';
30098-
&lt;/script></pre>
30099-
30100-
<pre>&lt;!-- https://example.com/b.html -->
30101-
&lt;!doctype html>
30102-
&lt;script>
30103-
new PaymentRequest(&hellip;); // Allowed to use
30104-
&lt;/script></pre>
30105-
</div>
30106-
</li>
30107-
30108-
<li><p>If <var>document</var>'s <span data-x="concept-document-bc">browsing context</span> has a
30109-
<span>browsing context container</span> that is an <code>iframe</code> element, let
30110-
<var>iframe</var> be that element. Otherwise, return.</p></li>
30111-
30112-
<li><p>If <var>iframe</var> has an <code
30113-
data-x="attr-iframe-allowpaymentrequest">allowpaymentrequest</code> attribute specified, then
30114-
set the <var>allowpaymentrequest flag</var> on <var>document</var>.</p></li>
30071+
<p class="warning">Because they only influence the <span
30072+
data-x="concept-document-feature-policy">feature policy</span> of the <span>nested browsing
30073+
context</span>'s <span>active document</span>, the <code data-x="attr-iframe-allow">allow</code>,
30074+
<code data-x="attr-iframe-allowfullscreen">allowfullscreen</code>, <code
30075+
data-x="attr-iframe-allowpaymentrequest">allowpaymentrequest</code> and <code
30076+
data-x="attr-iframe-allowusermedia">allowusermedia</code> attributes only take effect when the
30077+
<span>nested browsing context</span> of the <code>iframe</code> is <span
30078+
data-x="navigate">navigated</span>. Adding or removing them has no effect on an already-loaded
30079+
document.</p>
3011530080

30116-
<li><p>If <var>iframe</var> has an <code
30117-
data-x="attr-iframe-allowusermedia">allowusermedia</code> attribute specified, then set the
30118-
<var>allowusermedia flag</var> on <var>document</var>.</p></li>
30119-
</ol>
30120-
</div>
3012130081

3012230082
<hr> <!-- DIM ATTRIBUTES -->
3012330083

@@ -30151,8 +30111,9 @@ interface <dfn>HTMLIFrameElement</dfn> : <span>HTMLElement</span> {
3015130111

3015230112
<p>The IDL attributes <dfn><code data-x="dom-iframe-src">src</code></dfn>, <dfn><code
3015330113
data-x="dom-iframe-srcdoc">srcdoc</code></dfn>, <dfn><code
30154-
data-x="dom-iframe-name">name</code></dfn>,and <dfn><code
30155-
data-x="dom-iframe-sandbox">sandbox</code></dfn> must <span>reflect</span> the respective content
30114+
data-x="dom-iframe-name">name</code></dfn>, <dfn><code
30115+
data-x="dom-iframe-sandbox">sandbox</code></dfn>, and <dfn><code
30116+
data-x="dom-iframe-allow">allow</code></dfn> must <span>reflect</span> the respective content
3015630117
attributes of the same name.</p>
3015730118

3015830119
<p>The <span data-x="concept-supported-tokens">supported tokens</span> for <code
@@ -77001,7 +76962,8 @@ dictionary <dfn>DragEventInit</dfn> : <span>MouseEventInit</span> {
7700176962

7700276963
<li><p><span>Implement the sandboxing</span> for <var>document</var>.</p></li>
7700376964

77004-
<li><p><span>Set the allow* flags</span> for <var>document</var>.</p></li>
76965+
<li><p>Execute the <span>Initialize document’s Feature Policy</span> algorithm on
76966+
<var>document</var>. <ref spec="FEATUREPOLICY"></p></li>
7700576967

7700676968
<li><p>Add <var>document</var> to <var>browsingContext</var>'s <span>session
7700776969
history</span>.</p></li>
@@ -82370,7 +82332,64 @@ interface <dfn>Location</dfn> { // but see also <a href="#the-location-interface
8237082332

8237182333
<li><p><span>Implement the sandboxing</span> for the <code>Document</code>.</p></li>
8237282334

82373-
<li><p><span>Set the allow* flags</span> for the <code>Document</code>.</p></li>
82335+
<li>
82336+
<p>Execute the <span>Initialize document’s Feature Policy from response</span>
82337+
algorithm on the <code>Document</code> object and the <span
82338+
data-x="concept-response">response</span> used to generate the document. <ref
82339+
spec="FEATUREPOLICY"></p>
82340+
82341+
<p class="note">The <span>Initialize document’s Feature Policy from response</span> algorithm
82342+
makes use of the <code>Document</code>'s <span>origin</span>. If <code
82343+
data-x="dom-document-domain">document.domain</code> has been used for the <span>browsing
82344+
context container</span>'s <span>node document</span>, then its <span>origin</span> cannot be
82345+
<span>same origin-domain</span> with <var>document</var>'s <span>origin</span>, because these
82346+
steps run when <var>document</var> is initialized, so it cannot itself yet have used <code
82347+
data-x="dom-document-domain">document.domain</code>. Note that this means that Feature Policy
82348+
checks are less permissive compared to doing a <span>same origin</span> check instead.</p>
82349+
82350+
<div class="example">
82351+
<p>In this example, the child document is not allowed to use <code>PaymentRequest</code>,
82352+
despite being <span>same origin-domain</span> at the time the child document tries to use
82353+
it. At the time the child document is initialized, only the parent document has set <code
82354+
data-x="dom-document-domain">document.domain</code>, and the child document has not.</p>
82355+
82356+
<pre>&lt;!-- https://foo.example.com/a.html -->
82357+
&lt;!doctype html>
82358+
&lt;script>
82359+
document.domain = 'example.com';
82360+
&lt;/script>
82361+
&lt;iframe src=b.html>&lt;/iframe></pre>
82362+
82363+
<pre>&lt;!-- https://bar.example.com/b.html -->
82364+
&lt;!doctype html>
82365+
&lt;script>
82366+
document.domain = 'example.com'; // This happens after the document is initialized
82367+
new PaymentRequest(&hellip;); // Not allowed to use
82368+
&lt;/script></pre>
82369+
</div>
82370+
82371+
<div class="example">
82372+
<p>In this example, the child document <em>is</em> allowed to use
82373+
<code>PaymentRequest</code>, despite not being <span>same origin-domain</span> at the time
82374+
the child document tries to use it. At the time the child document is initialized, none of
82375+
the documents have set <code data-x="dom-document-domain">document.domain</code> yet so
82376+
<span>same origin-domain</span> falls back to a normal <span>same origin</span> check.</p>
82377+
82378+
<pre>&lt;!-- https://example.com/a.html -->
82379+
&lt;!doctype html>
82380+
&lt;iframe src=b.html>&lt;/iframe>
82381+
&lt;!-- The child document is now initialized, before the script below is run. -->
82382+
&lt;script>
82383+
document.domain = 'example.com';
82384+
&lt;/script></pre>
82385+
82386+
<pre>&lt;!-- https://example.com/b.html -->
82387+
&lt;!doctype html>
82388+
&lt;script>
82389+
new PaymentRequest(&hellip;); // Allowed to use
82390+
&lt;/script></pre>
82391+
</div>
82392+
</li>
8237482393

8237582394
<li>
8237682395
<p>If <var>response</var> has a `<code data-x="http-refresh">Refresh</code>` header, then:</p>
@@ -120140,6 +120159,9 @@ INSERT INTERFACES HERE
120140120159
<dt id="refsEXIF">[EXIF]</dt>
120141120160
<dd>(Non-normative) <cite><a href="https://www.jeita.or.jp/cgi-bin/standard_e/list.cgi?cateid=1&subcateid=4">Exchangeable image file format</a></cite>. JEITA.</dd>
120142120161

120162+
<dt id="refsFEATUREPOLICY">[FEATUREPOLICY]</dt>
120163+
<dd><cite><a href="https://wicg.github.io/feature-policy/">Feature Policy</a></cite>, I. Clelland, WICG.</dd>
120164+
120143120165
<dt id="refsFETCH">[FETCH]</dt>
120144120166
<dd><cite><a href="https://fetch.spec.whatwg.org/">Fetch</a></cite>, A. van Kesteren. WHATWG.</dd>
120145120167

0 commit comments

Comments
 (0)