Skip to content

Commit

Permalink
Clarify consumption of user activation at the initiation step.
Browse files Browse the repository at this point in the history
  • Loading branch information
@mustaqahmed
mustaqahmed committed Jan 10, 2022
1 parent 07fa929 commit d66f573
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 23 deletions.
26 changes: 18 additions & 8 deletions spec.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,13 +68,23 @@ capability delegation in future.

## Transient availability ## {#transient-availability}

Both the steps mentioned above are time-constrained in nature. The initiation
step is [[html#user-activation-gated-apis|activation consuming]], so the step is
allowed only after a recent user activation. After successful completion of
this step, the delegated API becomes available for use for a few seconds (to be
precise, the same limit as [activation
expiry](https://html.spec.whatwg.org/multipage/interaction.html#activation-expiry)
unless the limit is defined otherwise by the specification of the delegated API.
Both the steps mentioned above are time-constrained in nature:

1. The initiation step is [[html#user-activation-gated-apis|activation
consuming]], so the step is allowed only after a recent user activation.
Moreover, the consumption of user activation here guarantees that the
delegation mechanism can't be used more than once per user activation. This
prevents malicous uses of capability delegation, like repeated delegation
attempts to multiple frames to effectively bypass the user activation
restriction for the delegated API.

2. After a successful completion of the initiation step, the delegated API
becomes available for use in the target [=browsing context=] for a few
seconds only. The exact time limit here depends on how a delegated API
defines the delegated behavior in its own specification. For an API that
does not define its own time limit, the default limit will be the same as
[user activation
expiry](https://html.spec.whatwg.org/multipage/interaction.html#activation-expiry).


# Examples # {#examples}
Expand Down Expand Up @@ -145,7 +155,7 @@ will be followed by two additional steps as follows:

8. If <var>delegate</var> is not null, then:

1. If <var>targetOrigin</var> is a single U+002A ASTERISK character (*), then throw a
1. If <var ignore=''>targetOrigin</var> is a single U+002A ASTERISK character (*), then throw a
a "NotAllowedError" DOMException.

2. If <var>targetWindow</var> has [transient
Expand Down
43 changes: 28 additions & 15 deletions spec.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
<link href="https://www.w3.org/StyleSheets/TR/2016/cg-draft" rel="stylesheet">
<meta content="Bikeshed version 5c7bc9381, updated Wed May 12 18:18:08 2021 -0700" name="generator">
<link href="https://wicg.github.io/capability-delegation/spec.html" rel="canonical">
<meta content="3e5f77738c8bb0a153e937b3ac50ae12b3e35975" name="document-revision">
<meta content="07fa929fd39e840394f8be1d849078d944c18aaf" name="document-revision">
<style>/* style-autolinks */

.css.css, .property.property, .descriptor.descriptor {
Expand Down Expand Up @@ -563,7 +563,7 @@
<div class="head">
<p data-fill-with="logo"><a class="logo" href="https://www.w3.org/"> <img alt="W3C" height="48" src="https://www.w3.org/StyleSheets/TR/2016/logos/W3C" width="72"> </a> </p>
<h1 class="p-name no-ref" id="title">Capability Delegation</h1>
<h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span class="content">Draft Community Group Report, <time class="dt-updated" datetime="2022-01-07">7 January 2022</time></span></h2>
<h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span class="content">Draft Community Group Report, <time class="dt-updated" datetime="2022-01-10">10 January 2022</time></span></h2>
<div data-fill-with="spec-metadata">
<dl>
<dt>This version:
Expand Down Expand Up @@ -683,12 +683,24 @@ <h3 class="heading settled" data-level="1.2" id="initiate-vs-use"><span class="s
serve as a guide for similar changes in any other APIs that would utilize
capability delegation in future.</p>
<h3 class="heading settled" data-level="1.3" id="transient-availability"><span class="secno">1.3. </span><span class="content">Transient availability</span><a class="self-link" href="#transient-availability"></a></h3>
<p>Both the steps mentioned above are time-constrained in nature. The initiation
step is <a href="https://html.spec.whatwg.org/multipage/interaction.html#user-activation-gated-apis">activation consuming</a>, so the step is
allowed only after a recent user activation. After successful completion of
this step, the delegated API becomes available for use for a few seconds (to be
precise, the same limit as <a href="https://html.spec.whatwg.org/multipage/interaction.html#activation-expiry">activation
expiry</a> unless the limit is defined otherwise by the specification of the delegated API.</p>
<p>Both the steps mentioned above are time-constrained in nature:</p>
<ol>
<li data-md>
<p>The initiation step is <a href="https://html.spec.whatwg.org/multipage/interaction.html#user-activation-gated-apis">activation
consuming</a>, so the step is allowed only after a recent user activation.
Moreover, the consumption of user activation here guarantees that the
delegation mechanism can’t be used more than once per user activation. This
prevents malicous uses of capability delegation, like repeated delegation
attempts to multiple frames to effectively bypass the user activation
restriction for the delegated API.</p>
<li data-md>
<p>After a successful completion of the initiation step, the delegated API
becomes available for use in the target <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#browsing-context" id="ref-for-browsing-context⑥">browsing context</a> for a few
seconds only. The exact time limit here depends on how a delegated API
defines the delegated behavior in its own specification. For an API that
does not define its own time limit, the default limit will be the same as <a href="https://html.spec.whatwg.org/multipage/interaction.html#activation-expiry">user activation
expiry</a>.</p>
</ol>
<h2 class="heading settled" data-level="2" id="examples"><span class="secno">2. </span><span class="content">Examples</span><a class="self-link" href="#examples"></a></h2>
<div class="example" id="example-payment-request">
<a class="self-link" href="#example-payment-request"></a> When a site wants to delegate the capability to call <a data-link-type="biblio" href="#biblio-payment-request">[payment-request]</a> <code class="idl"><a data-link-type="idl" href="https://www.w3.org/TR/payment-request/#dom-paymentrequest-show" id="ref-for-dom-paymentrequest-show">show()</a></code> from a subframe after a mouse click, it will <a href="https://html.spec.whatwg.org/multipage/web-messaging.html#posting-messages">post a message</a> to the subframe with an additional
Expand All @@ -708,8 +720,8 @@ <h2 class="heading settled" data-level="2" id="examples"><span class="secno">2.
</div>
</section>
<h2 class="heading settled" data-level="3" id="initiating-delegation"><span class="secno">3. </span><span class="content">Initiating capability delegation</span><a class="self-link" href="#initiating-delegation"></a></h2>
<p>When a <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#browsing-context" id="ref-for-browsing-context⑥">browsing context</a> wants to delegate a capability to another <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#browsing-context" id="ref-for-browsing-context⑦">browsing
context</a>, it posts a message to the second <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#browsing-context" id="ref-for-browsing-context⑧">browsing context</a> with an extra <code class="idl"><a data-link-type="idl" href="https://html.spec.whatwg.org/multipage/window-object.html#windowpostmessageoptions" id="ref-for-windowpostmessageoptions">WindowPostMessageOptions</a></code> called <code>delegate</code> specifying the capability. The
<p>When a <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#browsing-context" id="ref-for-browsing-context⑦">browsing context</a> wants to delegate a capability to another <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#browsing-context" id="ref-for-browsing-context⑧">browsing
context</a>, it posts a message to the second <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#browsing-context" id="ref-for-browsing-context⑨">browsing context</a> with an extra <code class="idl"><a data-link-type="idl" href="https://html.spec.whatwg.org/multipage/window-object.html#windowpostmessageoptions" id="ref-for-windowpostmessageoptions">WindowPostMessageOptions</a></code> called <code>delegate</code> specifying the capability. The
value of this option MUST be a <a href="https://www.w3.org/TR/permissions-policy/#ascii-serialization">feature-identifier</a>. The option MUST
be ignored if the value does not correspond to any <a href="https://w3c.github.io/webappsec-permissions-policy/#supported-features">features supported by the
user
Expand Down Expand Up @@ -748,7 +760,7 @@ <h3 class="heading settled" data-level="3.1" id="monkey-patch-to-html-initiating
</ol>
</ol>
<h2 class="heading settled" data-level="4" id="tracking-delegation"><span class="secno">4. </span><span class="content">Tracking delegated capability</span><a class="self-link" href="#tracking-delegation"></a></h2>
<p>Capabilities delegated to a <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#browsing-context" id="ref-for-browsing-context⑨">browsing context</a> will be tracked using a map
<p>Capabilities delegated to a <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#browsing-context" id="ref-for-browsing-context①⓪">browsing context</a> will be tracked using a map
named <code class="idl"><a data-link-type="idl" href="https://html.spec.whatwg.org/multipage/window-object.html#window" id="ref-for-window">Window</a></code>.<a data-link-type="dfn" href="#delegated_capability_timestamps" id="ref-for-delegated_capability_timestamps">DELEGATED_CAPABILITY_TIMESTAMPS</a>. Each time a capability is
delegated to a <code class="idl"><a data-link-type="idl" href="https://html.spec.whatwg.org/multipage/window-object.html#window" id="ref-for-window①">Window</a></code>, an entry will be added in <a data-link-type="dfn" href="#delegated_capability_timestamps" id="ref-for-delegated_capability_timestamps①">DELEGATED_CAPABILITY_TIMESTAMPS</a> with a key equal to the <a href="https://www.w3.org/TR/permissions-policy/#ascii-serialization">feature-identifier</a> representing the
capability, and a value equal to current <code class="idl"><a data-link-type="idl" href="https://www.w3.org/TR/hr-time-2/#dom-domhighrestimestamp" id="ref-for-dom-domhighrestimestamp">DOMHighResTimeStamp</a></code>. If the map
Expand All @@ -759,7 +771,7 @@ <h3 class="heading settled" data-level="4.1" id="monkey-patch-to-html-tracking-d
message</a>,
a new paragraph will be inserted, as follow:</p>
<blockquote>
<p>For the purpose of tracking capabilities delegated to a <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#browsing-context" id="ref-for-browsing-context①⓪">browsing context</a>,
<p>For the purpose of tracking capabilities delegated to a <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/browsers.html#browsing-context" id="ref-for-browsing-context①①">browsing context</a>,
each <code class="idl"><a data-link-type="idl" href="https://html.spec.whatwg.org/multipage/window-object.html#window" id="ref-for-window②">Window</a></code> has a <a data-link-type="dfn" href="https://infra.spec.whatwg.org/#ordered-map" id="ref-for-ordered-map">map</a> called <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="delegated_capability_timestamps">DELEGATED_CAPABILITY_TIMESTAMPS</dfn> from <a href="https://www.w3.org/TR/permissions-policy/#ascii-serialization">feature-identifier</a> to <code class="idl"><a data-link-type="idl" href="https://www.w3.org/TR/hr-time-2/#dom-domhighrestimestamp" id="ref-for-dom-domhighrestimestamp②">DOMHighResTimeStamp</a></code>. The map is initialized with an empty map.</p>
</blockquote>
<p>In the algorithm for <a href="https://html.spec.whatwg.org/multipage/web-messaging.html#window-post-message-steps">window post
Expand Down Expand Up @@ -936,9 +948,10 @@ <h3 class="no-num no-ref heading settled" id="index-defined-here"><span class="c
<li><a href="#ref-for-browsing-context">1. Introduction</a> <a href="#ref-for-browsing-context①">(2)</a>
<li><a href="#ref-for-browsing-context②">1.1. What is capability delegation?</a>
<li><a href="#ref-for-browsing-context③">1.2. Initiating a delegation vs using a capability</a> <a href="#ref-for-browsing-context④">(2)</a> <a href="#ref-for-browsing-context⑤">(3)</a>
<li><a href="#ref-for-browsing-context⑥">3. Initiating capability delegation</a> <a href="#ref-for-browsing-context⑦">(2)</a> <a href="#ref-for-browsing-context⑧">(3)</a>
<li><a href="#ref-for-browsing-context⑨">4. Tracking delegated capability</a>
<li><a href="#ref-for-browsing-context①⓪">4.1. Monkey-patch to HTML spec</a>
<li><a href="#ref-for-browsing-context⑥">1.3. Transient availability</a>
<li><a href="#ref-for-browsing-context⑦">3. Initiating capability delegation</a> <a href="#ref-for-browsing-context⑧">(2)</a> <a href="#ref-for-browsing-context⑨">(3)</a>
<li><a href="#ref-for-browsing-context①⓪">4. Tracking delegated capability</a>
<li><a href="#ref-for-browsing-context①①">4.1. Monkey-patch to HTML spec</a>
</ul>
</aside>
<aside class="dfn-panel" data-for="term-for-dom-open">
Expand Down

0 comments on commit d66f573

Please sign in to comment.