a priori decisions about whether or not to service
a request based on the way it was made, and the context in which it will be used.
-
Status of this document
+
Status of this document
This section describes the status of this document at the time of
- its publication. Other documents may supersede this document. A list of
+ its publication. A list of
current W3C publications and the latest revision of this technical report
can be found in the W3C technical reports
index at https://www.w3.org/TR/.
The (archived) public mailing list public-webappsec@w3.org (see instructions)
is preferred for discussion of this specification.
When sending e-mail,
please put the text “fetch-metadata” in the subject,
preferably like this:
“[fetch-metadata] …summary of comment…”
-
Publication as a Working Draft does not imply endorsement by the W3C
- Membership. This is a draft document and may be updated, replaced or
+
Publication as a Working Draft does not imply endorsement by W3C and its Members. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite this
document as other than work in progress.
This document was produced by a group operating under
the W3C Patent Policy.
W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group;
that page also includes instructions for disclosing a patent.
An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
In order to support forward-compatibility with as-yet-unknown request types, servers SHOULD ignore
this header if it contains an invalid value.
-
// fetch()'s destination is the empty string:
+
// fetch()’s destination is the empty string:
Sec-Fetch-Dest: empty
-// <img>'s destination is "image"
+// <img>’s destination is "image"
Sec-Fetch-Dest: image
-// new Worker()'s destination is "worker"
+// new Worker()’s destination is "worker"
Sec-Fetch-Dest: worker
// Top-level navigations' destinations are "document"
@@ -474,50 +944,35 @@
<iframe> navigations' destinations are "iframe"
Sec-Fetch-Dest: iframe
-
- To set the Sec-Fetch-Dest header for a requestr:
+
+ To set the Sec-Fetch-Dest header for a requestr:
Valid Sec-Fetch-Mode values include "cors", "navigate", "no-cors", "same-origin",
and "websocket". In order to support forward-compatibility with as-yet-unknown request types,
servers SHOULD ignore this header if it contains an invalid value.
-
- To set the Sec-Fetch-Mode header for a requestr:
+
+ To set the Sec-Fetch-Mode header for a requestr:
Valid Sec-Fetch-Site values include "cross-site", "same-origin", "same-site", and "none".
In order to support forward-compatibility with as-yet-unknown request types, servers SHOULD ignore
this header if it contains an invalid value.
-
- To set the Sec-Fetch-Site header for a requestr:
+
+ To set the Sec-Fetch-Site header for a requestr:
If r is a navigation request that was explicitly caused by a user’s interaction with
the user agent (by typing an address into the user agent directly, for example, or by
clicking a bookmark, etc.), then set header’s value to none.
Note: The header is delivered only for navigation requests, and only when its value is true.
+
Note: The header is delivered only for navigation requests, and only when its value is true.
It might be reasonable to expand the headers' scope in the future to include subresource requests
generally if we can spell out some use cases that would be improved by exposing that information
(and if we can agree on ways to define that status for all the subresource request types we’d be
interested in), but for the moment, navigation requests have clear use cases, and seem
straightforward to define interoperably.
-
- To set the Sec-Fetch-User header for a requestr:
+
+ To set the Sec-Fetch-User header for a requestr:
Fetch Metadata headers are appended to outgoing requests from within Fetch’s "HTTP-network-or-cache"
-algorithm, using the following steps. Consult that specification for integration details [FETCH].
+algorithm, using the following steps. Consult that specification for integration details [FETCH].
- To append the Fetch metadata headers for a request, given requestr:
+ To append the Fetch metadata headers for a request, given requestr:
The user agent will send a Sec-Fetch-Site header along with each request in a
redirect chain. The header’s value will shift in the presence of cross-origin or cross-site
redirection in order to mitigate confusion.
The algorithm to set the Sec-Fetch-Site header walks the request's entire url list, and will send cross-site if any URL in the list is cross-site to the
request’s current url, same-site only if all URLs in the list are same-site with the
request’s current url, and same-origin only if all URLs in the list are same-origin
with the request’s current url.
@@ -654,11 +1079,11 @@
same-site with https://example.com/ and https://subdomain.example.com/). If that response
redirects all the way back to https://example.com/, the final request’s Sec-Fetch-Site value would still be cross-site (as the redirect chain includes https://example.net/, which is
still not same-site with the other URLs.
-
Note: For the special case of Sec-Fetch-Site: None, it seems reasonable to maintain that value
+
Note: For the special case of Sec-Fetch-Site: None, it seems reasonable to maintain that value
through redirects in order to support the common case of copy/pasting shortlinks into the address
bar. That is, if a user agent chooses to treat an address-bar navigation to https://sho.rt/link as Sec-Fetch-Site: none, a post-redirect navigation to https://target.com/long/path/goes/here should likewise assert Sec-Fetch-Site: none.
4.2. The Sec- Prefix
-
Each of the headers defined in this document is prefixed with Sec-, which makes them all forbidden header names, and therefore unmodifiable from JavaScript. This will prevent
+
Each of the headers defined in this document is prefixed with Sec-, which makes them all forbidden response-header names, and therefore unmodifiable from JavaScript. This will prevent
malicious websites from convincing user agents to send forged metadata along with requests,
which should give sites a bit more confidence in their ability to respond reasonably to
the advertised information.
@@ -731,15 +1156,15 @@
5. Deployment Considerations
5.1. Vary
-
If a given endpoint’s response depends upon the values the client delivers in a Fetch metadata header, developers should be careful to include an appropriate Vary header [RFC7231], in order to ensure that caches handle the response appropriately. For example, Vary: Accept-Encoding, Sec-Fetch-Site.
+
If a given endpoint’s response depends upon the values the client delivers in a Fetch metadata header, developers should be careful to include an appropriate Vary header [RFC9110], in order to ensure that caches handle the response appropriately. For example, Vary: Accept-Encoding, Sec-Fetch-Site.
5.2. Header Bloat
An earlier version of this document defined a single Sec-Metadata header, whose contents were
-a dictionary. Subsequent discussion (as well as Mark Nottingham’s excellent [mnot-designing-headers]) shifted the design away from a single dictionary to a series of simple
+a dictionary. Subsequent discussion (as well as Mark Nottingham’s excellent [mnot-designing-headers]) shifted the design away from a single dictionary to a series of simple
headers, each of which contains only a single token. This design should perform significantly better
under HTTP’s current HPACK compression algorithms.
The permanent message header field registry should be updated with the following registrations for Fetch metadata headers: [RFC3864]
+
The permanent message header field registry should be updated with the following registrations for Fetch metadata headers: [RFC3864]
6.1. Sec-Fetch-Dest Registration
Header field name
@@ -816,513 +1241,889 @@
7. Thanks to Anne van Kesteren, Artur Janc, Dan Veditz, Łukasz Anforowicz, Mark Nottingham, and
Roberto Clapis, who all provided substantial support in the design of this mechanism.
-
Conformance
-
Document conventions
-
Conformance requirements are expressed with a combination of
- descriptive assertions and RFC 2119 terminology. The key words “MUST”,
- “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”,
- “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this
- document are to be interpreted as described in RFC 2119.
- However, for readability, these words do not appear in all uppercase
- letters in this specification.
-
All of the text of this specification is normative except sections
- explicitly marked as non-normative, examples, and notes. [RFC2119]
-
Examples in this specification are introduced with the words “for example”
- or are set apart from the normative text with class="example",
+
+
Conformance
+
Document conventions
+
Conformance requirements are expressed
+ with a combination of descriptive assertions
+ and RFC 2119 terminology.
+ The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”
+ in the normative parts of this document
+ are to be interpreted as described in RFC 2119.
+ However, for readability,
+ these words do not appear in all uppercase letters in this specification.
+
All of the text of this specification is normative
+ except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
+
Examples in this specification are introduced with the words “for example”
+ or are set apart from the normative text
+ with class="example",
+ like this:
+
+
+
This is an example of an informative example.
+
+
Informative notes begin with the word “Note”
+ and are set apart from the normative text
+ with class="note",
like this:
-
-
-
This is an example of an informative example.
+
Note, this is an informative note.
+
+
Conformant Algorithms
+
Requirements phrased in the imperative as part of algorithms
+ (such as "strip any leading space characters"
+ or "return false and abort these steps")
+ are to be interpreted with the meaning of the key word
+ ("must", "should", "may", etc)
+ used in introducing the algorithm.
+
Conformance requirements phrased as algorithms or specific steps
+ can be implemented in any manner,
+ so long as the end result is equivalent.
+ In particular, the algorithms defined in this specification
+ are intended to be easy to understand
+ and are not intended to be performant.
+ Implementers are encouraged to optimize.
+
-
Informative notes begin with the word “Note” and are set apart from the
- normative text with class="note", like this:
-
Note, this is an informative note.
-
Conformant Algorithms
-
Requirements phrased in the imperative as part of algorithms (such as
- "strip any leading space characters" or "return false and abort these
- steps") are to be interpreted with the meaning of the key word ("must",
- "should", "may", etc) used in introducing the algorithm.
-
Conformance requirements phrased as algorithms or specific steps can be
- implemented in any manner, so long as the end result is equivalent. In
- particular, the algorithms defined in this specification are intended to
- be easy to understand and are not intended to be performant. Implementers
- are encouraged to optimize.