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 listed steps listed below while taking into consideration the following security implications.

Web Share enables data to be sent from websites to a share target, which can be a native applications. While this ability is not unique to Web Share, it does come with a number of potential security risks that can vary in severity (depending on the underlying platform).

The data passed to share() might be used to exploit buffer overflow or other remote code execution vulnerabilities in the share target that receive shares. There is no general way to guard against this, but implementors will want to be aware that it is a possibility (particularly when sharing files).

Share targets that dereference a shared URL and forward that information on might inadvertently forward information that might be otherwise confidential. This can lead to unexpected information leakage if shares reference content that is only accessible by that application, the host on which it runs, or its network location.

Malicious sites might exploit share targets that leak information by providing URLs that ultimately resolve to local resources, including, but not limited to, "file:" URLs or local services that might otherwise be inaccessible. Even though this API limits shared URLS to a restricted set of sharable schemes, use of redirects to other URLs or tweaks to DNS records for hosts in those URLs might be used to cause applications to acquire content.

To avoid being used in these attacks, share targets can consume the URL, retrieve the content, and process that information without sharing it. For instance, a photo editing application might retrieve an image that is "shared" with it. A share target can also share the URL without fetching any of the referenced content.

Share targets that fetch content for the purposes of offering a preview or for sharing content risk information leakage. Content that is previewed and authorized by a user might be safe to forward, however it is not always possible for a person to identify when information should be confidential, so forwarding any content presents a risk. In particular, the title might be used by an attacker to trick a user into misinterpreting the nature of the content.

As with any user of DOMException, implementors need to carefully consider what information is revealed in the error message when share() is rejected. Even distinguishing between the case where no share targets are available and user cancellation could reveal information about which share targets are installed on the user's device.

1. Let global be this's relevant global object.
2. Let document be global's associated Document.
3. If document is not fully active, return a promise rejected with an "InvalidStateError" DOMException.
4. If document is not allowed to use "web-share", return a promise rejected with a "NotAllowedError" DOMException.
5. If this.[[sharePromise]] is not null, return a promise rejected with an "InvalidStateError" DOMException.
6. If global does not have transient activation, return a promise rejected with a "NotAllowedError" DOMException.
7. Consume user activation of global.
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, queue a global task on the user interaction task source using global to:
       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 more share targets and the ability abort the operation. This UI surface serves as a security confirmation, ensuring that websites cannot silently send data to native applications. The user agent SHOULD show intermediary UI through which the user can verify the shared content (if the OS-level UI does not provide this functionality).
    3. Wait for the user's choice.
    4. If the user chose to abort the share operation, queue a global task on the user interaction task source using global to:
       1. Reject this.[[sharePromise]] with an "AbortError" DOMException,
       2. Set this.[[sharePromise]] to null.
       3. Abort these steps.
    5. Activate the chosen share target, convert data to a format suitable for ingestion into the target, and transmit the converted data to the target.
    6. If an error occurs starting the target or transmitting the data, queue a global task on the user interaction task source using global to:
       1. Reject this.[[sharePromise]] with an "DataError" DOMException.
       2. Set this.[[sharePromise]] to null.
       3. Abort these steps.
    7. 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), queue a global task on the user interaction task source using global to:
       Note
       1. Resolve this.[[sharePromise]] with undefined.
       2. Set this.[[sharePromise]] to null.

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

1. Let document be the this'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.

A sharable scheme is any of the following URL schemes:

• http
• https
• Any safelisted scheme that the user agent supports for the purpose of sharing.

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 (i.e., the user agent determines a file is malicious in some way, because of its contents, size, or other characteristic), 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 the url's scheme is a local scheme, or file, or javascript, or ws, or wss, return false.
   4. If url's scheme is not a sharable scheme, return false.
5. Return true.