Skip to content

Commit 3a21ed3

Browse files
annevkannevk
committed
Provide an API for referrer and referrer policies (both at Fetch and fetch() level). Fixes #80.
1 parent c5dc814 commit 3a21ed3

File tree

2 files changed

+233
-40
lines changed

2 files changed

+233
-40
lines changed

‎Overview.html‎

Lines changed: 118 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
<p><a class="logo" href="https://whatwg.org/"><img alt="WHATWG" height="100" src="https://resources.whatwg.org/logo-fetch.svg" width="100"></a>
99
<h1 id="cors">Fetch</h1>
10-
<h2 class="no-num no-toc" id="living-standard-—-last-updated-15-july-2015">Living Standard — Last Updated 15 July 2015</h2>
10+
<h2 class="no-num no-toc" id="living-standard-—-last-updated-16-july-2015">Living Standard — Last Updated 16 July 2015</h2>
1111

1212
<dl>
1313
<dt>Participate:
@@ -53,7 +53,8 @@ <h2 class="no-num no-toc" id="table-of-contents">Table of Contents</h2>
5353
<li><a href="#requests"><span class="secno">3.1.4 </span>Requests</a></li>
5454
<li><a href="#responses"><span class="secno">3.1.5 </span>Responses</a></ul></li>
5555
<li><a href="#authentication-entries"><span class="secno">3.2 </span>Authentication entries</a></li>
56-
<li><a href="#fetch-registries"><span class="secno">3.3 </span>Fetch registries</a></ul></li>
56+
<li><a href="#fetch-registries"><span class="secno">3.3 </span>Fetch registries</a></li>
57+
<li><a href="#referrer-policies"><span class="secno">3.4 </span>Referrer policies</a></ul></li>
5758
<li><a href="#http-extensions"><span class="secno">4 </span>HTTP extensions</a>
5859
<ul class="toc">
5960
<li><a href="#origin-header"><span class="secno">4.1 </span>`<code title="">Origin</code>` header</a></li>
@@ -810,9 +811,18 @@ <h4 id="requests"><span class="secno">3.1.4 </span>Requests</h4>
810811
<dfn id="same-origin-data-url-flag">same-origin data-URL flag</dfn>. Unless stated otherwise it is unset.
811812

812813
<p>A <a href="#concept-request" title="concept-request">request</a> has an associated
813-
<dfn id="concept-request-referrer" title="concept-request-referrer">referrer</dfn>, which is <i title="">no referrer</i>,
814-
<i title="">client</i>, or a <a class="external" href="https://url.spec.whatwg.org/#concept-url" title="concept-url">URL</a>. Unless
815-
stated otherwise it is <i title="">client</i>.
814+
<dfn id="concept-request-referrer" title="concept-request-referrer">referrer</dfn>, which is "<code>no-referrer</code>",
815+
"<code>client</code>", or a <a class="external" href="https://url.spec.whatwg.org/#concept-url" title="concept-url">URL</a>.
816+
Unless stated otherwise it is "<code>client</code>".
817+
818+
<p>A <a href="#concept-request" title="concept-request">request</a> has an associated
819+
<dfn id="concept-request-referrer-policy" title="concept-request-referrer-policy">referrer policy</dfn>, which is a
820+
<a href="#concept-referrer-policy" title="concept-referrer-policy">referrer policy</a>. Unless stated otherwise it is
821+
the empty string.
822+
823+
<p class="note no-backref">This can be used to override a referrer policy associated with
824+
an <a class="external" href="https://html.spec.whatwg.org/multipage/webappapis.html#environment-settings-object">environment settings object</a>.
825+
<a href="#refsREFERRER">[REFERRER]</a>
816826

817827
<p>A <a href="#concept-request" title="concept-request">request</a> has an associated
818828
<dfn id="synchronous-flag">synchronous flag</dfn>. Unless stated otherwise it is unset.
@@ -1142,6 +1152,27 @@ <h3 id="fetch-registries"><span class="secno">3.3 </span>Fetch registries</h3>
11421152

11431153

11441154

1155+
<h3 id="referrer-policies"><span class="secno">3.4 </span>Referrer policies</h3>
1156+
1157+
<p>A <dfn id="concept-referrer-policy" title="concept-referrer-policy">referrer policy</dfn> is the empty string,
1158+
"<code>no-referrer</code>", "<code>no-referrer-when-downgrade</code>",
1159+
"<code>origin-only</code>", "<code>origin-when-cross-origin</code>", or
1160+
"<code>unsafe-url</code>".
1161+
1162+
<pre class="idl">enum <dfn id="referrerpolicy">ReferrerPolicy</dfn> {
1163+
"",
1164+
"no-referrer",
1165+
"no-referrer-when-downgrade",
1166+
"origin-only",
1167+
"origin-when-cross-origin",
1168+
"unsafe-url"
1169+
};</pre>
1170+
1171+
<p class="note">The details of referrer policies are discussed in Referrer Policy.
1172+
<a href="#refsREFERRER">[REFERRER]</a>
1173+
1174+
1175+
11451176
<h2 id="http-extensions"><span class="secno">4 </span>HTTP extensions</h2>
11461177

11471178
<h3 id="origin-header"><span class="secno">4.1 </span>`<code title="">Origin</code>` header</h3>
@@ -1520,15 +1551,15 @@ <h3 id="main-fetch"><span class="secno">5.1 </span>Main fetch</h3>
15201551

15211552
<li>
15221553
<p>If <var title="">request</var>'s <a href="#concept-request-referrer" title="concept-request-referrer">referrer</a>
1523-
is not <i title="">no referrer</i>, set <var title="">request</var>'s
1554+
is not "<code>no-referrer</code>", set <var title="">request</var>'s
15241555
<a href="#concept-request-referrer" title="concept-request-referrer">referrer</a> to the result of invoking
15251556
<a href="https://w3c.github.io/webappsec/specs/referrer-policy/#determine-requests-referrer">determine <var title="">request</var>'s referrer</a>.
15261557
<a href="#refsREFERRER">[REFERRER]</a>
15271558

15281559
<p class="note no-backref">As stated in <cite>Referrer Policy</cite>, user agents can
15291560
provide the end user with options to override <var title="">request</var>'s
1530-
<a href="#concept-request-referrer" title="concept-request-referrer">referrer</a> to <i title="">no referrer</i> or have
1531-
it expose less sensitive information.
1561+
<a href="#concept-request-referrer" title="concept-request-referrer">referrer</a> to "<code>no-referrer</code>" or
1562+
have it expose less sensitive information.
15321563

15331564
<li><p>If <var title="">request</var>'s
15341565
<a href="#concept-request-current-url" title="concept-request-current-url">current url</a> contains a Known HSTS Host,
@@ -1649,7 +1680,7 @@ <h3 id="main-fetch"><span class="secno">5.1 </span>Main fetch</h3>
16491680
<a href="https://w3c.github.io/webappsec/specs/mixedcontent/#should-block-response">should <var>internalResponse</var> to <var>request</var> be blocked as mixed content</a>,
16501681
<span class="XXX">should <var>internalResponse</var> to <var title="">request</var> be blocked as content security</span>,
16511682
or
1652-
<span>should <var>internalResponse</var> to <var><a href="#request">request</a></var> be blocked due to nosniff</span>
1683+
<a href="#should-response-to-request-be-blocked-due-to-nosniff?" title="should response to request be blocked due to nosniff">should <var>internalResponse</var> to <var>request</var> be blocked due to nosniff</a>
16531684
returns <b title="">blocked</b>, set <var title="">response</var> to a
16541685
<a href="#concept-network-error" title="concept-network-error">network error</a>.
16551686
<a href="#refsMIX">[MIX]</a>
@@ -1738,7 +1769,8 @@ <h3 id="basic-fetch"><span class="secno">5.2 </span>Basic fetch</h3>
17381769
<dd>
17391770
<p>If <var title="">request</var>'s
17401771
<a href="#concept-request-current-url" title="concept-request-current-url">current url</a>'s
1741-
<a class="external" href="https://url.spec.whatwg.org/#concept-url-scheme-data" title="concept-url-scheme-data">scheme data</a> is
1772+
<a class="external" href="https://url.spec.whatwg.org/#non_relative-flag">non-relative flag</a> is set and
1773+
<a class="external" href="https://url.spec.whatwg.org/#concept-url-path" title="concept-url-path">path</a> contains a single string
17421774
"<code title="">blank</code>", return a <a href="#concept-response" title="concept-response">response</a> whose
17431775
<a href="#concept-response-header-list" title="concept-response-header-list">header list</a> consist of a single
17441776
<a href="#concept-header" title="concept-header">header</a> whose
@@ -1753,7 +1785,8 @@ <h3 id="basic-fetch"><span class="secno">5.2 </span>Basic fetch</h3>
17531785

17541786
<p id="unicorn">Otherwise, if <var title="">request</var>'s
17551787
<a href="#concept-request-current-url" title="concept-request-current-url">current url</a>'s
1756-
<a class="external" href="https://url.spec.whatwg.org/#concept-url-scheme-data" title="concept-url-scheme-data">scheme data</a> is
1788+
<a class="external" href="https://url.spec.whatwg.org/#non_relative-flag">non-relative flag</a> is set and
1789+
<a class="external" href="https://url.spec.whatwg.org/#concept-url-path" title="concept-url-path">path</a> contains a single string
17571790
"<code title="">unicorn</code>", return a <a href="#concept-response" title="concept-response">response</a>
17581791
whose <a href="#concept-response-header-list" title="concept-response-header-list">header list</a> consist of a single
17591792
<a href="#concept-header" title="concept-header">header</a> whose
@@ -2247,7 +2280,7 @@ <h3 id="http-network-or-cache-fetch"><span class="secno">5.4 </span>HTTP-network
22472280

22482281
<li><p><a href="#concept-header-list-append" title="concept-header-list-append">Append</a>
22492282
`<code title="">Referer</code>`/empty byte sequence, if <var title="">HTTPRequest</var>'s
2250-
<a href="#concept-request-referrer" title="concept-request-referrer">referrer</a> is <i title="">no referrer</i>, and
2283+
<a href="#concept-request-referrer" title="concept-request-referrer">referrer</a> is "<code>no-referrer</code>", and
22512284
`<code title="">Referer</code>`/<var title="">HTTPRequest</var>'s
22522285
<a href="#concept-request-referrer" title="concept-request-referrer">referrer</a>,
22532286
<a class="external" href="https://url.spec.whatwg.org/#concept-url-serializer" title="concept-url-serializer">serialized</a> and
@@ -2585,9 +2618,12 @@ <h3 id="cors-preflight-fetch"><span class="secno">5.6 </span>CORS-preflight fetc
25852618
<a href="#concept-request-context-frame-type" title="concept-request-context-frame-type">context-frame type</a>,
25862619
<a href="#concept-request-origin" title="concept-request-origin">origin</a> is <var title="">request</var>'s
25872620
<a href="#concept-request-origin" title="concept-request-origin">origin</a>,
2588-
<a href="#force-origin-header-flag">force-<code>Origin</code>-header flag</a> is set, and
2621+
<a href="#force-origin-header-flag">force-<code>Origin</code>-header flag</a> is set,
25892622
<a href="#concept-request-referrer" title="concept-request-referrer">referrer</a> is <var title="">request</var>'s
2590-
<a href="#concept-request-referrer" title="concept-request-referrer">referrer</a>.
2623+
<a href="#concept-request-referrer" title="concept-request-referrer">referrer</a>, and
2624+
<a href="#concept-request-referrer-policy" title="concept-request-referrer-policy">referrer policy</a> is
2625+
<var title="">request</var>'s
2626+
<a href="#concept-request-referrer-policy" title="concept-request-referrer-policy">referrer policy</a>.
25912627

25922628
<li><p><a href="#concept-header-list-set" title="concept-header-list-set">Set</a>
25932629
`<code title="http-access-control-request-method"><a href="#http-access-control-request-method">Access-Control-Request-Method</a></code>` to
@@ -3345,8 +3381,9 @@ <h3 id="request-class"><span class="secno">6.3 </span>Request class</h3>
33453381
[SameObject] readonly attribute <a href="#headers">Headers</a> <a href="#dom-request-headers" title="dom-Request-headers">headers</a>;
33463382

33473383
readonly attribute <a href="#requestcontext">RequestContext</a> <a href="#dom-request-context" title="dom-Request-context">context</a>;<!--
3348-
readonly attribute DOMString <span title=dom-Request-origin>origin</span>;-->
3349-
readonly attribute DOMString <a href="#dom-request-referrer" title="dom-Request-referrer">referrer</a>;<!--
3384+
readonly attribute USVString <span title=dom-Request-origin>origin</span>;-->
3385+
readonly attribute USVString <a href="#dom-request-referrer" title="dom-Request-referrer">referrer</a>;
3386+
readonly attribute <a href="#referrerpolicy">ReferrerPolicy</a> <a href="#dom-request-referrerpolicy" title="dom-Request-referrerPolicy">referrerPolicy</a>;<!--
33503387
readonly attribute boolean <span title=dom-Request-handles401>handles401</span>;
33513388
readonly attribute boolean <span title=dom-Request-isSynchronous>isSynchronous</span>;-->
33523389
readonly attribute <a href="#requestmode">RequestMode</a> <a href="#dom-request-mode" title="dom-Request-mode">mode</a>;
@@ -3359,10 +3396,15 @@ <h3 id="request-class"><span class="secno">6.3 </span>Request class</h3>
33593396
};
33603397
<a href="#request">Request</a> implements <a href="#body">Body</a>;
33613398

3362-
dictionary <dfn id="requestinit">RequestInit</dfn> {
3399+
<!--
3400+
Careful: defaults can only be set in prose, otherwise the Request() constructor
3401+
algorithm breaks down.
3402+
-->dictionary <dfn id="requestinit">RequestInit</dfn> {
33633403
ByteString method;
33643404
<a href="#headersinit">HeadersInit</a> headers;
33653405
<a href="#bodyinit">BodyInit</a> body;
3406+
USVString referrer;
3407+
<a href="#referrerpolicy">ReferrerPolicy</a> referrerPolicy;
33663408
<a href="#requestmode">RequestMode</a> mode;
33673409
<a href="#requestcredentials">RequestCredentials</a> credentials;
33683410
<a href="#requestcache">RequestCache</a> cache;
@@ -3458,6 +3500,11 @@ <h3 id="request-class"><span class="secno">6.3 </span>Request class</h3>
34583500
<a href="#concept-request-origin" title="concept-request-origin">origin</a> is <var title="">origin</var>,
34593501
<a href="#force-origin-header-flag">force-<code>Origin</code>-header flag</a> is set,
34603502
<a href="#same-origin-data-url-flag">same-origin data-URL flag</a> is set,
3503+
<a href="#concept-request-referrer" title="concept-request-referrer">referrer</a> is <var title="">request</var>'s
3504+
<a href="#concept-request-referrer" title="concept-request-referrer">referrer</a>,
3505+
<a href="#concept-request-referrer-policy" title="concept-request-referrer-policy">referrer policy</a> is
3506+
<var title="">request</var>'s
3507+
<a href="#concept-request-referrer-policy" title="concept-request-referrer-policy">referrer policy</a>,
34613508
<a href="#concept-request-context" title="concept-request-context">context</a> is the empty string,
34623509
<a href="#concept-request-mode" title="concept-request-mode">mode</a> is <var title="">request</var>'s
34633510
<a href="#concept-request-mode" title="concept-request-mode">mode</a>,
@@ -3479,14 +3526,17 @@ <h3 id="request-class"><span class="secno">6.3 </span>Request class</h3>
34793526

34803527
<li><p>Let <var title="">fallbackRedirect</var> be null.
34813528

3529+
<li><p>Let <var>baseURL</var> be
3530+
<a class="external" href="https://html.spec.whatwg.org/multipage/webappapis.html#entry-settings-object">entry settings object</a>'s
3531+
<a class="external" href="https://html.spec.whatwg.org/multipage/webappapis.html#api-base-url">API base URL</a>.
3532+
34823533
<li>
34833534
<p>If <var title="">input</var> is a string, run these substeps:
34843535

34853536
<ol>
34863537
<li><p>Let <var title="">parsedURL</var> be the result of
34873538
<a class="external" href="https://url.spec.whatwg.org/#concept-url-parser" title="concept-url-parser">parsing</a>
3488-
<var title="">input</var> with <a class="external" href="https://html.spec.whatwg.org/multipage/webappapis.html#entry-settings-object">entry settings object</a>'s
3489-
<a class="external" href="https://html.spec.whatwg.org/multipage/webappapis.html#api-base-url">API base URL</a>.
3539+
<var title="">input</var> with <var>baseURL</var>.
34903540

34913541
<li><p>If <var title="">parsedURL</var> is failure,
34923542
<a class="external" href="https://heycam.github.io/webidl/#dfn-throw">throw</a> a <code title="">TypeError</code>.
@@ -3510,6 +3560,49 @@ <h3 id="request-class"><span class="secno">6.3 </span>Request class</h3>
35103560
<li><p>Set <var title="">fallbackRedirect</var> to "<code title="">follow</code>".
35113561
</ol>
35123562

3563+
<li><p>If any of <var title="">init</var>'s members are present, set
3564+
<var title="">request</var>'s <a href="#concept-request-referrer" title="concept-request-referrer">referrer</a> to
3565+
"<code>client</code>", and <var title="">request</var>'s
3566+
<a href="#concept-request-referrer-policy" title="concept-request-referrer-policy">referrer policy</a> to the empty string.
3567+
3568+
<li>
3569+
<p>If <var title="">init</var>'s <code>referrer</code> member is present, run these
3570+
substeps:
3571+
3572+
<ol>
3573+
<li><p>Let <var title="">referrer</var> be <var title="">init</var>'s <code>referrer</code>
3574+
member.
3575+
3576+
<li><p>If <var title="">referrer</var> is the empty string, set <var title="">request</var>'s
3577+
<a href="#concept-request-referrer" title="concept-request-referrer">referrer</a> to "<code>no-referrer</code>" and
3578+
terminate these substeps.
3579+
3580+
<li><p>Let <var>parsedReferrer</var> be the result of
3581+
<a class="external" href="https://url.spec.whatwg.org/#concept-url-parser" title="concept-url-parser">parsing</a>
3582+
<var title="">referrer</var> with <var>baseURL</var>.
3583+
3584+
<li><p>If <var>parsedReferrer</var>'s
3585+
<a class="external" href="https://url.spec.whatwg.org/#non_relative-flag">non-relative flag</a> is set,
3586+
<a class="external" href="https://url.spec.whatwg.org/#concept-url-scheme" title="concept-url-scheme">scheme</a> is
3587+
"<code>about</code>", and
3588+
<a class="external" href="https://url.spec.whatwg.org/#concept-url-path" title="concept-url-path">path</a> contains a single string
3589+
"<code>client</code>", set <var title="">request</var>'s
3590+
<a href="#concept-request-referrer" title="concept-request-referrer">referrer</a> to "<code>client</code>" and
3591+
terminate these substeps.
3592+
3593+
<li><p>If <var>parsedReferrer</var>'s
3594+
<a class="external" href="https://url.spec.whatwg.org/#concept-url-origin" title="concept-url-origin">origin</a> is not
3595+
<a class="external" href="https://html.spec.whatwg.org/multipage/browsers.html#same-origin">same origin</a> with <var title="">origin</var>,
3596+
<a class="external" href="https://heycam.github.io/webidl/#dfn-throw">throw</a> a <code title="">TypeError</code>.
3597+
3598+
<li><p>Set <var title="">request</var>'s
3599+
<a href="#concept-request-referrer" title="concept-request-referrer">referrer</a> to <var>parsedReferrer</var>.
3600+
</ol>
3601+
3602+
<li><p>If <var title="">init</var>'s <code><a href="#referrerpolicy">referrerPolicy</a></code> member is present, set
3603+
<var title="">request</var>'s
3604+
<a href="#concept-request-referrer-policy" title="concept-request-referrer-policy">referrer policy</a> to it.
3605+
35133606
<li><p>Let <var title="">mode</var> be <var title="">init</var>'s <code title="">mode</code>
35143607
member if it is present, and <var title="">fallbackMode</var> otherwise.
35153608

@@ -3653,13 +3746,17 @@ <h3 id="request-class"><span class="secno">6.3 </span>Request class</h3>
36533746

36543747
<p>The <dfn id="dom-request-referrer" title="dom-Request-referrer"><code>referrer</code></dfn> attribute's getter must
36553748
return the empty string if <a href="#concept-request-request" title="concept-Request-request">request</a>'s
3656-
<a href="#concept-request-referrer" title="concept-Request-referrer">referrer</a> is <i title="">no referrer</i>,
3749+
<a href="#concept-request-referrer" title="concept-Request-referrer">referrer</a> is "<code>no-referrer</code>",
36573750
"<code title="">about:client</code>" if <a href="#concept-request-request" title="concept-Request-request">request</a>'s
3658-
<a href="#concept-request-referrer" title="concept-Request-referrer">referrer</a> is <i title="">client</i> and
3751+
<a href="#concept-request-referrer" title="concept-Request-referrer">referrer</a> is "<code>client</code>", and
36593752
<a href="#concept-request-request" title="concept-Request-request">request</a>'s
36603753
<a href="#concept-request-referrer" title="concept-Request-referrer">referrer</a>,
36613754
<a class="external" href="https://url.spec.whatwg.org/#concept-url-serializer" title="concept-url-serializer">serialized</a>, otherwise.
36623755

3756+
<p>The <dfn id="dom-request-referrerpolicy" title="dom-Request-referrerPolicy"><code>referrerPolicy</code></dfn> attribute's
3757+
getter must return <a href="#concept-request-request" title="concept-Request-request">request</a>'s
3758+
<a href="#concept-request-referrer-policy" title="concept-Request-referrer-policy">referrer policy</a>.
3759+
36633760
<p>The <dfn id="dom-request-mode" title="dom-Request-mode"><code>mode</code></dfn> attribute's getter must
36643761
return the value corresponding to the first matching statement, switching on
36653762
<a href="#concept-request-request" title="concept-Request-request">request</a>'s

0 commit comments

Comments
 (0)