Fetch Metadata Request Headers

Fetch Metadata Request Headers
Fetch Metadata Request Headers
W3C Working Draft
1 April 2025
More details about this document
This version:
Latest published version:
Editor's Draft:
Previous Versions:
History:
Feedback:
public-webappsec@w3.org
with subject line “
[fetch-metadata]
… message topic …
” (
archives
GitHub
Editor:
Mike West
Google Inc.
Participate:
File an issue
open issues
Tests:
web-platform-tests fetch/sec-metadata/
World Wide Web Consortium
W3C
liability
trademark
and
permissive document license
rules apply.
Abstract
This document defines a set of Fetch metadata request headers that aim to provide servers with
enough information to make
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
This section describes the status of this document at the time 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/.
This document was published by the
Web Application Security Working Group
as a Working Draft using the
Recommendation
track
. This document is intended to become a W3C Recommendation.
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
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 the
Web Application Security Working Group
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
This document is governed by the
03 November 2023 W3C Process Document
1.
Introduction
Interesting web applications generally end up with a large number of web-exposed endpoints that
might reveal sensitive data about a user, or take action on a user’s behalf. Since users' browsers
can be easily convinced to make requests to those endpoints, and to include the users' ambient
credentials (cookies, privileged position on an intranet, etc), applications need to be very careful
about the way those endpoints work in order to avoid abuse.
Being careful turns out to be hard in some cases ("simple" CSRF), and practically impossible in
others (cross-site search, timing attacks, etc). The latter category includes timing attacks based
on the server-side processing necessary to generate certain responses, and length measurements (both
via web-facing timing attacks and passive network attackers).
It would be helpful if servers could make more intelligent decisions about whether or not to respond
to a given request based on the way that it’s made in order to mitigate the latter category. For
example, it seems pretty unlikely that a "Transfer all my money" endpoint on a bank’s server would
expect to be referenced from an
img
tag, and likewise unlikely that
evil.com
is going to be
making any legitimate requests whatsoever. Ideally, the server could reject these requests
a priori
rather than delivering them to the application backend.
Here, we describe a mechanims by which user agents can enable this kind of decision-making by
adding additional context to outgoing requests. By delivering metadata to a server in a set of
fetch metadata headers
, we enable applications to quickly reject requests based on testing a
set of preconditions. That work can even be lifted up above the application layer (to reverse
proxies, CDNs, etc) if desired.
1.1.
Examples
A request generated by a
picture
element would result in a request containing the following
HTTP request headers:
Sec-Fetch-Dest: image
Sec-Fetch-Mode: no-cors
Sec-Fetch-Site: cross-site
A top-level navigation from
to
caused by a user’s click
on an in-page link would result in a request containing the following HTTP request header:
Sec-Fetch-Dest: document
Sec-Fetch-Mode: navigate
Sec-Fetch-Site: same-origin
Sec-Fetch-User: ?1
2.
Fetch Metadata Headers
The following sections define several
fetch metadata headers
, each of which
exposes an interesting
request
attribute to a server.
2.1.
The
Sec-Fetch-Dest
HTTP Request Header
The
Sec-Fetch-Dest
HTTP request header exposes a
request
’s
destination
to a server. It is a
Structured Field
whose value MUST be a
token
[RFC9651]
Its ABNF is:
Sec-Fetch-Dest =
sf-token
Valid
Sec-Fetch-Dest
values include the set of valid
request
destinations
defined by
[Fetch]
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:
Sec-Fetch-Dest: empty

//

’s destination is "image"
Sec-Fetch-Dest: image

//
new Worker()
’s destination is "worker"
Sec-Fetch-Dest: worker

// Top-level navigations' destinations are "document"
Sec-Fetch-Dest: document

//
 navigations' destinations are "iframe" Sec-Fetch-Dest: iframe To set the Sec-Fetch-Dest header for a request Assert: ’s url is a potentially trustworthy URL Let header be a Structured Field whose value is a token If ’s destination is the empty string, set header ’s value to the string empty ". Otherwise, set header ’s value to ’s destination Note: We map Fetch’s empty string destination onto an explicit " empty token in order to simplify processing. Set a structured field value Sec-Fetch-Dest `/ header in ’s header list 2.2. The Sec-Fetch-Mode HTTP Request Header The Sec-Fetch-Mode HTTP request header exposes a request ’s mode to a server. It is a Structured Field whose value MUST be a token [RFC9651] Its ABNF is: Sec-Fetch-Mode = sf-token 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 request Assert: ’s url is a potentially trustworthy URL Let header be a Structured Field whose value is a token Set header ’s value to ’s mode Set a structured field value Sec-Fetch-Mode `/ header in ’s header list 2.3. The Sec-Fetch-Site HTTP Request Header The Sec-Fetch-Site HTTP request header exposes the relationship between a request initiator’s origin and its target’s origin. It is a Structured Field whose value is a token [RFC9651] Its ABNF is: Sec-Fetch-Site = sf-token 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 request Assert: ’s url is a potentially trustworthy URL Let header be a Structured Field whose value is a token Set header ’s value to same-origin If 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: See § 4.3 Directly User-Initiated Requests for more detail on this somewhat poorly-defined step. If header ’s value is not none , then for each url in ’s url list If url is same origin with ’s origin continue Set header ’s value to cross-site If ’s origin is not same site with url ’s origin , then break Set header ’s value to same-site Set a structured field value Sec-Fetch-Site `/ header in ’s header list 2.4. The Sec-Fetch-User HTTP Request Header The Sec-Fetch-User HTTP request header exposes whether or not a navigation request was triggered by user activation. It is a Structured Field whose value is a boolean [RFC9651] Its ABNF is: Sec-Fetch-User = sf-boolean 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 request Assert: ’s url is a potentially trustworthy URL If is not a navigation request , or if ’s user-activation is false , return. Let header be a Structured Field whose value is a token Set header ’s value to true Set a structured field value Sec-Fetch-User `/ header in ’s header list 3. Integration with Fetch and HTML To support Sec-Fetch-User request has a user-activation which is false, unless otherwise populated by HTML’s create navigation params by fetching algorithm. 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] To append the Fetch metadata headers for a request , given request If ’s url is not an potentially trustworthy URL , return. Set the Sec-Fetch-Dest header for Set the Sec-Fetch-Mode header for Set the Sec-Fetch-Site header for Set the Sec-Fetch-User header for 4. Security and Privacy Considerations 4.1. Redirects 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 For example, if requests , the initial request’s Sec-Fetch-Site value would be same-origin . If that response redirected to , that request’s Sec-Fetch-Site value would be same-site (as and have the same registrable domain). If that response redirected to , that request’s Sec-Fetch-Site value would be cross-site (as is not same-site with and ). If that response redirects all the way back to , the final request’s Sec-Fetch-Site value would still be cross-site (as the redirect chain includes , 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 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 as Sec-Fetch-Site: none , a post-redirect navigation to 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 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. 4.3. Directly User-Initiated Requests When setting the Sec-Fetch-Site header , user agents are asked to distinguish between navigation requests that are "explicitly caused by a user’s interaction". This somewhat poorly defined phrase is pulled from HTML, which suggests that "A user agent may provide various ways for the user to explicitly cause a browsing context to navigate, in addition to those defined in this specification." The goal is to distinguish between "webby" navigations that are controlled by a given (potentially malicious!) website (e.g. links, the window.location setter, form submissions, etc.), and those that are not (e.g. user interaction with a user agent’s address bar, bookmarks, etc). The former will be delivered with a Sec-Fetch-Site header whose value is same-origin same-site , or cross-site , as appropriate. The latter will be distinguished with a value of none , as no specific site is actually responsible for the request, and it makes sense to allow servers to treat them as trusted, as they somehow represent a user’s direct intent. Each user agent is likely to have a distinct set of interactions which might fall into one or the other category, and it will be hard to share an automated test suite for these cases. Still, it would be ideal to align on behavior for those which are likely to be common. Sme examples follow: Navigation from the address bar: In the general case, this kind of navigation should be treated as directly user-initiated, and include Sec-Fetch-Site: none . It may be reasonable for user agents to include heuristics around pasting values into the address bar (especially if the "copy" action can be traced to a specific origin), and to treat such navigations distinctly from those which the user types themselves. Navigation from user agent UI (bookmarks, new tab page, etc): A user’s interaction with links in user agent UI should be treated similarly to their input in the user agent’s address bar, including Sec-Fetch-Site: none to demarcate the navigation as user-initiated. Navigation from a link’s context menu (e.g. "Open in new window"): as the link’s target is controlled by the page on which the link is present, user agents should treat the navigation as site-controlled, and set the Sec-Fetch-Site header appropriately for the relationship between the site which controls the link and the site which is being opened. Ctrl-click on a link: the same arguments and conclusions apply here as apply to a link’s context menu, discussed directly above. Navigation through history (e.g. a user agent’s "back" button): Drag-and-drop: It seems reasonable to distinguish behavior here based upon the source of the dragged content. If content is dragged from a tab, the user agent should be able to ascertain its origin, and set Sec-Fetch-Site accordingly. If content is dragged from elsewhere (the user agent’s bookmark bar, another app entirely, etc), then Sec-Fetch-Site: none may be appropriate. 4.4. Extension-Initiated Requests Some user agents support extensions which are capable of making requests, and which can be empowered beyond regular web content in order to give users more control over their web experience. While these are somewhat outside the scope of the web platform, user agents are encouraged to carefully consider how these requests are to be represented to servers. In general, it would be ideal for user agents to satisfy two goals: Extensions without special privileges for a given site cannot cause requests that would bypass that site’s server-side Fetch Metadata logic. Developers can recognize extensions' requests so that they can be exempted from the server’s Fetch Metadata logic if it chooses to do so. This increases developers' ability to confidently deploy Fetch Metadata protections without undermining legitimate user interests. With these goals in mind, user agents are encouraged to implement the following behaviors: If an extension does not have permission to access to a given URL, its requests to that URL could contain a Sec-Fetch-Site header whose value is cross-site , just as a normal web request would. If the extension does have access to a given URL, the Sec-Fetch-Site value could be same-origin The Origin header could be included with outgoing requests from extension contexts, with an implementation-defined value that allows servers to distinguish extension-initiated requests from web-initiated requests. 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 [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 headers, each of which contains only a single token. This design should perform significantly better under HTTP’s current HPACK compression algorithms. Further discussion on the topic can be found on the review thread in w3ctag/design-reviews#280 6. IANA Considerations 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 Sec-Fetch-Dest Applicable protocol http Status standard Author/Change controller Me Specification document This specification (See § 2.1 The Sec-Fetch-Dest HTTP Request Header 6.2. Sec-Fetch-Mode Registration Header field name Sec-Fetch-Mode Applicable protocol http Status standard Author/Change controller Me Specification document This specification (See § 2.2 The Sec-Fetch-Mode HTTP Request Header 6.3. Sec-Fetch-Site Registration Header field name Sec-Fetch-Site Applicable protocol http Status standard Author/Change controller Me Specification document This specification (See § 2.3 The Sec-Fetch-Site HTTP Request Header 6.4. Sec-Fetch-User Registration Header field name Sec-Fetch-User Applicable protocol http Status standard Author/Change controller Me Specification document This specification (See § 2.4 The Sec-Fetch-User HTTP Request Header 7. Acknowledgements 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" 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: 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. Index Terms defined by this specification append the Fetch metadata headers for a request , in § 3 fetch metadata headers , in § 2 Sec-Fetch-Dest , in § 2.1 Sec-Fetch-Mode , in § 2.2 Sec-Fetch-Site , in § 2.3 Sec-Fetch-User , in § 2.4 set-dest , in § 2.1 set-mode , in § 2.2 set-site , in § 2.3 set-user , in § 2.4 Terms defined by reference [FETCH] defines the following terms: current URL destination forbidden response-header name header list mode navigation request origin request set a structured field value URL URL list user-activation [HTML] defines the following terms: create navigation params by fetching img picture same origin same site [INFRA] defines the following terms: break continue implementation-defined [RFC9651] defines the following terms: boolean sf-boolean sf-token structured field token [SECURE-CONTEXTS] defines the following terms: potentially trustworthy URL [URL] defines the following terms: origin References Normative References [FETCH] Anne van Kesteren. Fetch Standard . Living Standard. URL: [HTML] Anne van Kesteren; et al. HTML Standard . Living Standard. URL: [INFRA] Anne van Kesteren; Domenic Denicola. Infra Standard . Living Standard. URL: [RFC2119] S. Bradner. Key words for use in RFCs to Indicate Requirement Levels . March 1997. Best Current Practice. URL: [RFC3864] G. Klyne; M. Nottingham; J. Mogul. Registration Procedures for Message Header Fields . September 2004. Best Current Practice. URL: [RFC9651] M. Nottingham; P-H. Kamp. Structured Field Values for HTTP . September 2024. Proposed Standard. URL: [SECURE-CONTEXTS] Mike West. Secure Contexts . 10 November 2023. CRD. URL: [URL] Anne van Kesteren. URL Standard . Living Standard. URL: Informative References [MNOT-DESIGNING-HEADERS] Mark Nottingham. Designing Headers for HTTP Compression . URL: [RFC9110] R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. HTTP Semantics . June 2022. Internet Standard. URL: MDN Headers/Sec-Fetch-Dest In all current engines. Firefox 90+ Safari 16.4+ Chrome 80+ Opera Edge 80+ Edge (Legacy) IE None Firefox for Android iOS Safari Chrome for Android Android WebView Samsung Internet Opera Mobile None MDN Headers/Sec-Fetch-Mode In all current engines. Firefox 90+ Safari 16.4+ Chrome 76+ Opera Edge 79+ Edge (Legacy) IE None Firefox for Android iOS Safari Chrome for Android Android WebView Samsung Internet Opera Mobile MDN Headers/Sec-Fetch-Site In all current engines. Firefox 90+ Safari 16.4+ Chrome 76+ Opera Edge 79+ Edge (Legacy) IE None Firefox for Android iOS Safari Chrome for Android Android WebView Samsung Internet Opera Mobile MDN Headers/Sec-Fetch-User In all current engines. Firefox 90+ Safari 16.4+ Chrome 76+ Opera Edge 79+ Edge (Legacy) IE None Firefox for Android iOS Safari Chrome for Android Android WebView Samsung Internet Opera Mobile</div> </div> <div class="detail-actions"> <a href="/search?q=www.w3.org" class="btn">Same domain →</a> <a href="/search?q=Fetch%20Metadata%20Request%20Headers" class="btn btn-secondary">Similar titles →</a> </div> </article> </main> <footer class="site-footer"> <div class="container"> C U Cyber History — Public Interest Web Archive Preserving fading web memories. Discover history that once existed. </div> </footer> <script id="chat-i18n-en" type="application/json">{"button_label":"Need Help?","placeholder":"Ask us anything...","title":"CUCH Assistant","subtitle":"How can we help you?","send":"Send","close":"Close","folder":"/var/www/cu","greeting":"Hi! Welcome to CUCH.org. How can I help you today? Feel free to ask about our archive, search, or anything else!","error":"Sorry, our service is temporarily unavailable. Please try again later.","banner_text":"Need help? Ask our AI assistant!"}</script> <script src="/static/js/chat-widget.js"></script> </body> </html>