Web Share API

This API adds the following internal slot to the Navigator interface.

Promise? [[sharePromise]]

The this.[[sharePromise]] is a promise that represents a user's current intent to share some data with a share target. It is initialized to null.

When the share() method is called with argument data, run the following steps:

1. Let document be the current settings object's relevant global object's associated Document.
2. If document is not fully active, return a promise rejected with an "InvalidStateError" DOMException.
3. If document is not allowed to use "web-share", return a promise rejected with a "NotAllowedError" DOMException.
4. If this.[[sharePromise]] is not null, return a promise rejected with an "InvalidStateError" DOMException.
5. Let window be relevant global object of this.
6. If window does not have transient activation, return a promise rejected with a "NotAllowedError" DOMException.
7. Consume user activation of window.
8. Let base be this's relevant settings object's API base URL.
9. If validate share data with data and base returns false, then return a promise rejected with a TypeError.
10. If data's url member is present:
    1. Let url be the result of running the URL parser on data's url with base.
    2. Assert: url is URL.
    3. Set data to a copy of data, with its url member set to the result of running the URL serializer on url.
11. If a file type is being blocked due to security considerations, return a promise rejected with a "NotAllowedError" DOMException.
12. Set this.[[sharePromise]] to be a new promise.
13. Return this.[[sharePromise]] and in parallel:
    1. If there are no share targets available:
       1. Reject this.[[sharePromise]] with an "AbortError" DOMException.
       2. Set this.[[sharePromise]] to null.
       3. Abort these steps.
    2. Present the user with a choice of one or more share targets, selected at the user agent's discretion. The user MUST be given the option to cancel rather than choosing any of the share targets. Wait for the user's choice.
    3. If the user chose to cancel the share operation:
       1. Reject this.[[sharePromise]] with an "AbortError" DOMException,
       2. Set this.[[sharePromise]] to null.
       3. Abort these steps.
    4. Activate the chosen share target, convert data to a format suitable for ingestion into the target, and transmit the converted data to the target.
    5. If an error occurs starting the target or transmitting the data:
       1. Reject this.[[sharePromise]] with an "DataError" DOMException.
       2. Set this.[[sharePromise]] to null.
       3. Abort these steps.
    6. Once the data has either been successfully transmitted to the share target, or successfully transmitted to the OS (if the transmission to the share target cannot be confirmed), resolve this.[[sharePromise]] with undefined.
    7. Set this.[[sharePromise]] to null.

The user agent MUST NOT allow the website to learn which share targets are available, or the identity of the chosen target.

When the canShare() method is called with argument ShareData data, run the following steps:

1. Let document be the current settings object's relevant global object's associated Document.
2. If document is not fully active, return false.
3. If document is not allowed to use "web-share", return false.
4. Return the result of validate share data with data and this's relevant settings object's API base URL.

To validate share data with data and base, run the following steps:

1. If none of data's members title, text, or url or files are present, return false.
2. Let titleTextOrUrl be true if any of title, or text, or url is present.
3. If data's files member is present:
   1. If titleTextOrUrl is false and data's files member is empty, return false.
      Note

      This causes a { files: [] } dictionary to be treated as an empty dictionary. However, passing a dictionary like {text: "text", files: []} is fine, as files is just ignored.

   2. If the implementation does not support file sharing, return false.
   3. If the user agent believes sharing any of the files in files would result in a potentially hostile share, return false.
4. If data's url member is present:
   1. Let url be the result of running the URL parser on data's url member, with base, and no encoding override.
   2. If url is failure, return false.

   3. If url is a URL the user agent deems potentially hostile (e.g., "file:") or wouldn't make sense to outside the scope of the document (e.g., "blob:"), return false.

      Issue 178: Limiting to http/https is limiting

      #173 was a bit of a learning experience. The fix for that in #174 limits URLs to http or https. That was the most conservative reaction to that issue.

      This means that a number of URI schemes with no known exposure to this vulnerability can no longer be shared. From standard protocols mailto, sip[s], and tel are all examples of schemes that do not invoke actions and should be safe to share. (Why you might use those rather than share a vCard resource is not relevant; these seem valid to me.) Then there are the quasi-standard things like: ipfs, magnet. And a whole bunch of proprietary schemes: acrobat, zoommtg, steam, microsoft-edge (ok, maybe we don't want that...), and so forth.

      Now that the dust has settled, it might be worth examining principles a little closer to determine whether a looser set of constraints can be made to work. @dveditz suggested that we block URLs if we might not permit both navigation or redirection. I think that is a reasonable starting point here. We don't allow navigation or redirects to file:// and so sharing that seems to be primarily a means of circumventing that policy.

      We can't expect that share targets will respect the same policies that a browser does in case it follows an HTTP URL that redirects to file:///, but we are explicitly accepting that risk already by allowing use of HTTP schemes.

5. Return true.