Capability Delegation

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

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

// sw.js (Service Worker):
self.addEventListener('notificationclick', (event) => {
  event.waitUntil((async () => {
    const clients = await self.clients.matchAll({type: 'window'});
    const client = clients.find(c => c.visibilityState === 'visible') || clients[0];
    if (client) {
      await client.focus();
      client.postMessage(
        {action: 'preview_email', emailId: event.notification.data.emailId},
        {delegate: 'popup'}
      );
    }
  })());
});

// main.js (Client Window):
navigator.serviceWorker.addEventListener('message', (event) => {
  if (event.data.action === 'preview_email') {
    window.open(
      '/preview?id=' + event.data.emailId,
      'preview_win',
      'width=600,height=500'
    );
  }
});

3. Initiating capability delegation

When a browsing context or service worker wants to delegate a capability to another browsing context, it posts a message with an extra option called delegate specifying the capability. For a browsing context, the message is sent using WindowPostMessageOptions, and the value of this option MUST be a feature-identifier. For a service worker, the message is sent to a same-origin WindowClient using ClientPostMessageOptions, and the value of this option MUST be "popup". The option MUST be ignored or rejected if the value does not correspond to any capability supported for delegation 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 delegate is not a feature-identifier, or the user agent does not support delegating the feature indicated by delegate via Window.postMessage(), 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.

3.2. Monkey-patch to Notifications spec

Each NotificationEvent has an associated active transient capability token for "popup", which is initially unset.

In the algorithm for fire a service worker notification event, the following step will be added after Step 2:

2. Initialize event’s type attribute to e.

3. If e is "notificationclick", then:

   1. Set event’s active transient capability token for "popup".

   2. The token expires and is unset when event is no longer active (i.e., after its synchronous dispatch completes and upon the settlement of all promises passed to event.waitUntil()), or when 5 seconds have elapsed from the creation of event, whichever occurs first.

When an active transient capability token is consumed by an algorithm (such as in Client.postMessage()), it is unset.

3.3. Monkey-patch to Service Workers spec

The ClientPostMessageOptions dictionary will be added to the Service Workers specification, replacing the StructuredSerializeOptions parameter in Client.postMessage():

dictionary ClientPostMessageOptions : StructuredSerializeOptions {
  DOMString? delegate;
};

partial interface Client {
  undefined postMessage(any message, optional ClientPostMessageOptions options = {});
};

In the algorithm for Client.postMessage(), before serializing message, the following steps will be added to validate and transfer the capability:

1. Let client be this Client object.

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

3. If delegate is not null, then:

   1. If delegate is not "popup", or the user agent does not support delegating delegate, then throw a "NotSupportedError" DOMException.

   2. If client is not a WindowClient, then throw a "NotSupportedError" DOMException.

   3. If the current execution context is not associated with an active NotificationEvent that has an active transient capability token for delegate, then throw a "NotAllowedError" DOMException.

   4. Consume the active transient capability token for delegate from the NotificationEvent.

4. In the task queued on the destination client’s responsible event loop to dispatch the message event, immediately before firing the message event (after deserialization succeeds):

   1. If delegate is not null, set DELEGATED_CAPABILITY_TIMESTAMPS[delegate] on the target Window to current high resolution time.

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 capability identifier (either a feature-identifier or "popup"), 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 or DOMString 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 delegate is a feature-identifier supported for delegation by the user agent, 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 are the spec changes needed for capabilities that define delegated behavior.

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.

5.4. Monkey-patch to HTML spec for window open

In Step 5 of the algorithm for the rules for choosing a navigable (invoked by the window open steps when chosen is null and a new top-level traversable is being requested), the following changes will be made to implement the delegated behavior for "popup":

1. Popup Allowed Check: In the first condition of Step 5 (evaluating whether the user agent’s popup blocker blocks creating a new top-level traversable), allow creation (do not block) if currentNavigable’s active window (the relevant global object) has transient activation, OR if the timestamp DELEGATED_CAPABILITY_TIMESTAMPS["popup"] in currentNavigable’s active window is present and not expired (where an entry for "popup" is considered expired if the current high resolution time minus the timestamp is greater than 1 second, i.e., 1000 milliseconds). Subsequent sandboxing flag checks in Step 5 remain unchanged.

2. Unified Consumption: In the branch of Step 5 that creates a new top-level traversable:

   1. If currentNavigable’s active window has transient activation, then consume user activation of currentNavigable’s active window.

   2. Clear the map entry DELEGATED_CAPABILITY_TIMESTAMPS["popup"] in currentNavigable’s active window.