Capability Delegation

window.onclick = () => {
  targetWindow.postMessage('a_message', {delegate: "payment"});
};

window.onmessage = () => {
  const payRequest = new PaymentRequest(...);
  const payResponse = await payRequest.show();
  ...
}

3. Initiating capability delegation

When a browsing context wants to delegate a capability to another browsing context, it posts a message to the second browsing context with an extra WindowPostMessageOptions called delegate specifying the capability. The value of this option MUST be a feature-identifier. The option MUST be ignored if the value does not correspond to any features supported by the user agent.

3.1. Monkey-patch to HTML spec

The WindowPostMessageOptions IDL definition will include an additional field as follows:

DOMString? delegate;

In the algorithm for window post message, the following step:

6. Let transfer be options["transfer"].

will be followed by two additional steps as follows:

7. Let delegate be options["delegate"].

8. If delegate is not null, then:

   1. If the user agent does not support delegating the feature indicated by delegate, then throw a "NotSupportedError" DOMException.

   2. If targetWindow’s associated Document is not allowed-to-use the feature indicated by delegate, then throw a a "NotAllowedError" DOMException.

   3. If targetOrigin is a single U+002A ASTERISK character (*), then throw a a "NotAllowedError" DOMException.

      The default value of targetOrigin is "/", restricting the message to same-origin targets. The additional requirement to use a string other than "*" means that cross-origin messages has to specify the specific origin for which they are intended.

   4. Let source be incumbentSettings’s global object.

   5. If source does not have transient activation, then throw a "NotAllowedError" DOMException.

   6. Consume user activation in source.

4. Tracking delegated capability

Capabilities delegated to a browsing context will be tracked using a map named Window.DELEGATED_CAPABILITY_TIMESTAMPS. Each time a capability is delegated to a Window, an entry will be added in DELEGATED_CAPABILITY_TIMESTAMPS with a key equal to the feature-identifier representing the capability, and a value equal to current DOMHighResTimeStamp. If the map already has an entry for the same key, the existing value will be updated to current DOMHighResTimeStamp.

4.1. Monkey-patch to HTML spec

Right before the algorithm for window post message, a new paragraph will be inserted, as follow:

For the purpose of tracking capabilities delegated to a browsing context, each Window has a map called DELEGATED_CAPABILITY_TIMESTAMPS from feature-identifier to DOMHighResTimeStamp. The map is initialized with an empty map.

In the algorithm for window post message, two additional sub-steps will be added to current Step 8. The first additional sub-step will be inserted after the following sub-step:

8. Queue a global task ...

   2. Let origin be the serialization of incumbentSettings’s origin.

as follows:

8. Queue a global task ... (unchanged)

   3. Let delegate be options["delegate"].

The second additional sub-step will be inserted after the following sub-step:

8. Queue a global task ...

   6. Let newPorts be a new frozen array consisting of ...

as follows:

8. Queue a global task ... (unchanged)

   7. Let newPorts be a new frozen array consisting of ... (unchanged except for numbering)

   8. If delegate is not null, AND the user agent supports delegating delegate, then set DELEGATED_CAPABILITY_TIMESTAMPS[delegate] to current high resolution time.

5. Defining delegated capability behavior

Any capability that defines a delegated behavior uses the corresponding entry in Window.DELEGATED_CAPABILITY_TIMESTAMPS in a manner appropriate for the capability. Below is the spec change needed for one particular capability.

5.1. Monkey-patch to Payment Request spec

In the algorithm for show(), the following steps will be replaced to implement the delegated behavior:

The two steps:

2. If the relevant global object of request does not have transient activation:

   1. Return a promise rejected with a "SecurityError" DOMException.

3. Consume user activation of the relevant global object.

will be replaced by the following three steps:

2. If the relevant global object of request does not have transient activation, AND the timestamp DELEGATED_CAPABILITY_TIMESTAMPS["payment"] in the relevant global object is either undefined or expired:

   1. Return a promise rejected with a "SecurityError" DOMException.

3. If the relevant global object of request does not have transient activation, then clear the map entry DELEGATED_CAPABILITY_TIMESTAMPS["payment"].

4. Otherwise, consume user activation of the relevant global object.

5.2. Monkey-patch to Fullscreen spec

In the algorithm for requestFullscreen(), the following changes will be done to implement the delegated behavior:

The last condition in Step 5:

5. If any of the following conditions are false, then set error to true: ...

   • This’s relevant global object has transient activation or the algorithm is triggered by a user generated orientation change.

will be replaced by:

5. If any of the following conditions are false, then set error to true: ... (unchanged)

   • This’s relevant global object has transient activation, or the timestamp DELEGATED_CAPABILITY_TIMESTAMPS["fullscreen"] in this’s relevant global object is neither undefined nor expired, or the algorithm is triggered by a user generated orientation change.

Right before the Step 10:

10. Let fullscreenElements be an ordered set initially consisting of this.

the following new step will be inserted:

10. If this’s relevant global object does not have transient activation, then clear the map entry DELEGATED_CAPABILITY_TIMESTAMPS["fullscreen"] in this’s relevant global object.

11. Let fullscreenElements be an ordered set initially consisting of this. (unchanged except for numbering)

5.3. Monkey-patch to [SCREEN-CAPTURE] spec

In the algorithm for getDisplayMedia(), the following changes will be done to implement the delegated behavior:

The condition in Step 3:

3. If the relevant global object of this does not have transient activation, return a promise rejected with a DOMException object whose name attribute has the value InvalidStateError.

will be replaced by:

3. If the relevant global object of this does not have transient activation AND the timestamp DELEGATED_CAPABILITY_TIMESTAMPS["display-capture"] in this’s relevant global object is either undefined or expired, return a promise rejected with a DOMException object whose name attribute has the value InvalidStateError.