Skip to content

Miscellaneous spec cleanup (no normative changes) #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Jun 23, 2017
Merged

Miscellaneous spec cleanup (no normative changes) #44

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
05ed5d6
Link to promise spec.
mgiuca Jun 21, 2017
786a14a
Explicitly resolve promise with undefined.
mgiuca Jun 21, 2017
2cc5c61
Make the share method steps a MUST.
mgiuca Jun 21, 2017
85d5186
Added normative requirement to not reveal the targets to the website.
mgiuca Jun 21, 2017
9e8d108
Rewrite some non-normative text to remove MUST and MUST NOT language.
mgiuca Jun 21, 2017
61b6b8d
Revert "Make the share method steps a MUST."
mgiuca Jun 22, 2017
a94067a
Link resolve and reject to promises spec.
mgiuca Jun 22, 2017
9395223
Rewrite to avoid using RFC2119 keywords in non-normative text.
mgiuca Jun 22, 2017
2cbfd0e
Explain that additional private browsing restrictions are not mandated.
mgiuca Jun 22, 2017
b658e25
Be more specific about getting the base URL.
mgiuca Jun 22, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 79 additions & 65 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,9 +102,9 @@ <h3>
The above statement is designed to permit feature detection. If
<a for="Navigator"><code>share</code></a> is present, there is a
reasonable expectation that it will work and present the user with at
least one <a>share target</a>. Clients should be able to use the
presence or absence of this method to determine whether to show UI
that triggers its use.
least one <a>share target</a>. Clients can use the presence or
absence of this method to determine whether to show UI that triggers
its use.
</div>
<section>
<h4>
Expand All @@ -115,18 +115,24 @@ <h4>
<var>data</var>, run the following steps:
</p>
<ol>
<li>Let <var>p</var> be a newly created promise.
<li>Let <var>p</var> be <a data-cite=
"!promises-guide#a-new-promise">a new promise</a>.
</li>
<li>If <var>data</var>'s <a for="ShareData">url</a> member is
<a data-cite="!WEBIDL#dfn-present">present</a>:
<ol>
<li>Let <var>base</var> be the <b>this</b> value's
<a data-cite="!HTML#relevant-settings-object">relevant
settings object</a>'s <a data-cite="!HTML#api-base-url">API
base URL</a>.
</li>
<li>Let <var>url</var> be the result of running the
<a data-cite="!URL#concept-url-parser">URL parser</a> on <var>
data</var>'s <a for="ShareData">url</a>, with the document's
<a data-cite="!HTML#document-base-url">base URL</a>, and no
<var>encoding override</var>.
data</var>'s <a for="ShareData">url</a>, with
<var>base</var>, and no <var>encoding override</var>.
</li>
<li>If <var>url</var> is failure, reject <var>p</var> with
<li>If <var>url</var> is failure, <a data-cite=
"!promises-guide#reject-promise">reject</a> <var>p</var> with
<a data-cite=
"!WEBIDL#exceptiondef-typeerror"><code>TypeError</code></a>,
and abort these steps.
Expand All @@ -140,52 +146,63 @@ <h4>
</li>
<li>If the method call was not <a data-cite=
"!HTML#triggered-by-user-activation">triggered by user
activation</a>, reject <var>p</var> with <a data-cite=
activation</a>, <a data-cite=
"!promises-guide#reject-promise">reject</a> <var>p</var> with
<a data-cite=
"!WEBIDL#securityerror"><code>SecurityError</code></a>, and abort
these steps.
</li>
<li>
<a data-cite="!HTML#in-parallel">In parallel</a>:
<ol>
<li>If there are no <a>share targets</a> available, reject
<var>p</var> with <a data-cite=
"!WEBIDL#aborterror"><code>AbortError</code></a>, and abort
these steps.
<li>If there are no <a>share targets</a> available,
<a data-cite="!promises-guide#reject-promise">reject</a> <var>
p</var> with <a data-cite=
"!WEBIDL#aborterror"><code>AbortError</code></a>, and abort
these steps.
</li>
<li>Present the user with a choice of one or more <a>share
targets</a>, 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.
</li>
<li>If the user chose to cancel the share operation, reject
<var>p</var> with <a data-cite=
"!WEBIDL#aborterror"><code>AbortError</code></a>, and abort
these steps.
<li>If the user chose to cancel the share operation,
<a data-cite="!promises-guide#reject-promise">reject</a> <var>
p</var> with <a data-cite=
"!WEBIDL#aborterror"><code>AbortError</code></a>, and abort
these steps.
</li>
<li>Activate the chosen <a>share target</a>, <a>convert
<var>data</var> to a format suitable for ingestion into the
target</a>, and transmit the converted data to the target. If
an error occurs starting the target or transmitting the data,
reject <var>p</var> with <a data-cite=
"!WEBIDL#aborterror"><code>AbortError</code></a>, and abort
these steps.
<a data-cite="!promises-guide#reject-promise">reject</a> <var>
p</var> with <a data-cite=
"!WEBIDL#aborterror"><code>AbortError</code></a>, and abort
these steps.
</li>
<li>Once the data has been successfully transmitted to the
target, resolve <var>p</var>.
target, <a data-cite=
"!promises-guide#resolve-promise">resolve</a> <var>p</var> with
<b>undefined</b>.
</li>
</ol>
</li>
<li>Return <var>p</var>.
</li>
</ol>
<p>
The user agent MUST NOT allow the website to learn which share
targets are available, or the identity of the chosen target.
</p>
<div class="note">
<a for="Navigator"><code>share</code></a> always shows some form of
UI, to give the user a choice of application and get their approval
to invoke and send data to a potentially native application (which
carries a security risk). For this reason, user agents MUST still
show UI even if there is only a single share target, and MUST NOT
perform any kind of "always use this target" to bypass the UI in
subsequent share operations.
carries a security risk). For this reason, user agents are
prohibited from showing any kind of "always use this target in the
future" option, or bypassing the UI if there is only a single share
target.
</div>
</section>
</section>
Expand Down Expand Up @@ -222,13 +239,13 @@ <h3>
These fields are <a data-cite=
"!WEBIDL#idl-USVString"><code>USVString</code></a> (as opposed to
<a data-cite="!WEBIDL#idl-DOMString"><code>DOMString</code></a>)
because they must not contain invalid <a data-cite=
because they are not allowed to contain invalid <a data-cite=
"rfc2781#section-2">UTF-16</a> surrogates. This means the user agent
is free to re-encode them in any Unicode encoding (e.g.,
<a data-cite="rfc3629#section-3">UTF-8</a>).
</div>
<div class="note">
The <a for="ShareData">url</a> field may contain a <a data-cite=
The <a for="ShareData">url</a> field can contain a <a data-cite=
"!URL#relative-url-with-fragment-string">relative URL</a>. In this
case, it will be automatically resolved relative to the current page
location, just like a <a data-cite=
Expand All @@ -249,7 +266,7 @@ <h2>
user agent.
</p>
<p>
A share target may not be directly able to accept a <a>ShareData</a>
A share target might not be directly able to accept a <a>ShareData</a>
(due to not having been written with this API in mind). However, it
MUST have the ability to receive data that matches some or all of the
concepts exposed in <a>ShareData</a>. To <dfn>convert data to a format
Expand All @@ -259,18 +276,17 @@ <h2>
payload is at the discretion of the share target.
</p>
<p>
Each share target may be made conditionally available depending on the
Each share target MAY be made conditionally available depending on the
<a>ShareData</a> payload delivered to the <a for="Navigator">share</a>
method.
</p>
<div class="note">
Once a share target has been given the payload, the share is considered
successful. If the target considers the data unacceptable or an error
occurs, the target should either recover gracefully, or show an error
message to the end-user, because the sender is not going to know that
an error occurred. In other words, the <a for="Navigator">share</a>
method is "fire and forget"; it does not wait for the target to approve
or reject the payload.
occurs, it can either recover gracefully, or show an error message to
the end-user; it cannot rely on the sender to handle errors. In other
words, the <a for="Navigator">share</a> method is "fire and forget"; it
does not wait for the target to approve or reject the payload.
</div>
<section class="informative">
<h3>
Expand Down Expand Up @@ -301,16 +317,16 @@ <h3>
<p>
In some cases, the host operating system will provide a sharing or
intent system similar to Web Share. In these cases, the user agent
may simply forward the share data to the operating system and not
can simply forward the share data to the operating system and not
talk directly to native applications.
</p>
<p>
Mapping the <a>ShareData</a> to the share target (or operating
system)'s native format can be tricky as some platforms will not have
an equivalent set of fields. For example, if the target has a "text"
field but not a "URL" field, it may be necessary to concatenate both
the <a for="ShareData">text</a> and <a for="ShareData">url</a> fields
of <a>ShareData</a> and pass the result in the "text" field of the
field but not a "URL" field, one solution is to concatenate both the
<a for="ShareData">text</a> and <a for="ShareData">url</a> fields of
<a>ShareData</a> and pass the result in the "text" field of the
target.
</p>
</section>
Expand All @@ -319,33 +335,30 @@ <h3>
<h2>
Security and privacy considerations
</h2>
<p>
Implementations should observe the following security and privacy
advice.
</p>
<p>
Web Share enables data to be sent from websites to native applications.
While this ability is not unique to Web Share, it does come with a
number of potential security issues that may vary in severity
number of potential security issues that can vary in severity
(depending on the underlying platform).
</p>
<ul>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The introduction still contains "should", and seems out of place since this is supposed to be now re-stating requirements expressed elsewhere.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done. I've grepped the whole document for all reserved words in RFC 2119 and rewritten the sentences around them (or, in one case, upgraded "may" to "MAY").

<li>User agents MUST NOT allow the website to learn which apps are
installed, or which app was chosen from
<a><code>navigator.share</code></a>. This information could be used for
fingerprinting, as well as leaking details about the user's device.
<li>There is a requirement to not allow the website to learn which apps
are installed, or which app was chosen from
<a><code>navigator.share</code></a>, because this information could be
used for fingerprinting, as well as leaking details about the user's
device.
</li>
<li>Implementors should carefully consider what information is revealed
in the error message when <a><code>navigator.share</code></a> is
rejected. Even distinguishing between the case where no targets are
available and user cancellation may reveal information about which apps
are installed on the user's device.
<li>Implementors will want to carefully consider what information is
revealed in the error message when <a><code>navigator.share</code></a>
is rejected. Even distinguishing between the case where no targets are
available and user cancellation could reveal information about which
apps are installed on the user's device.
</li>
<li>On every call to <a><code>navigator.share</code></a>, the user MUST
be presented with a dialog asking them to select a target application
(even if there is only one possible target). This surface serves as a
security confirmation, ensuring that websites cannot silently send data
to native applications.
<li>There is a requirement that <a><code>navigator.share</code></a>
presents the user with a dialog asking them to select a target
application (even if there is only one possible target). This surface
serves as a security confirmation, ensuring that websites cannot
silently send data to native applications.
</li>
<li>Due to the capabilities of the API surface,
<a><code>navigator.share</code></a> is <a data-cite=
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's an errant "may leak private data" below that ideally would be "might". The same bullet also contains a "should" which I am not sure what to do with.

Similarly, "may be used" should be "can be used", and "should be aware" should be, e.g., "will want to be aware"

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

"will want to be aware" sounds very watery, but I can't think of anything better that doesn't involve these words.

Expand All @@ -354,16 +367,17 @@ <h2>
</li>
<li>Use of <a><code>navigator.share</code></a> from a <a href=
"https://en.wikipedia.org/wiki/Privacy_mode">private browsing mode</a>
may leak private data to a third-party application that does not
respect the user's privacy setting. User agents should consider
presenting additional warnings or disabling the feature entirely when
in a private browsing mode.
might leak private data to a third-party application that does not
respect the user's privacy setting. User agents could present
additional warnings or disable the feature entirely when in a private
browsing mode, but this is not mandated as the chooser UI could be
considered sufficient warning.
</li>
<li>The data passed to <a><code>navigator.share</code></a> may be used
to exploit buffer overflow or other remote code execution
<li>The data passed to <a><code>navigator.share</code></a> might be
used to exploit buffer overflow or other remote code execution
vulnerabilities in native applications that receive shares. There is no
general way to guard against this, but implementors should be aware
that it is a possibility.
general way to guard against this, but implementors will want to be
aware that it is a possibility.
</li>
</ul>
</section>
Expand Down