index.bs

<pre class='metadata'>
Title: Fetch Metadata Request Headers
Shortname: fetch-metadata
Level: None
Group: webappsec
Status: WD
TR: https://www.w3.org/TR/fetch-metadata/
ED: https://w3c.github.io/webappsec-fetch-metadata/
Previous Version: from biblio
Editor: Mike West 56384, Google Inc., mkwst@google.com
Abstract:
    This document defines a set of Fetch metadata request headers that aim to provide servers with
    enough information to make <i lang="la">a priori</i> 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.
Markup Shorthands: markdown yes
!Participate: <a href="https://github.com/w3c/webappsec-fetch-metadata/issues/new">File an issue</a> (<a href="https://github.com/w3c/webappsec-fetch-metadata/issues">open issues</a>)
!Tests: <a href=https://github.com/web-platform-tests/wpt/tree/master/fetch/sec-metadata>web-platform-tests fetch/sec-metadata/</a>
Version History: https://github.com/w3c/webappsec-fetch-metadata/commits/main/index.bs
</pre>
<pre class="biblio">
{
  "I-D.ietf-httpbis-header-structure": {
    "authors": [ "Mark Nottingham", "Poul-Henning Kamp" ],
    "href": "https://tools.ietf.org/html/draft-ietf-httpbis-header-structure",
    "title": "Structured Headers for HTTP",
    "status": "ID",
    "publisher": "IETF"
  },
  "mnot-designing-headers": {
    "authors": [ "Mark Nottingham" ],
    "href": "https://www.mnot.net/blog/2018/11/27/header_compression",
    "title": "Designing Headers for HTTP Compression"
  }
}
</pre>

<pre class="anchors">
urlPrefix: https://tools.ietf.org/html/draft-ietf-httpbis-header-structure; spec: I-D.ietf-httpbis-header-structure
    type: dfn
        text: structured header; url: #
    for: structured header
        type: dfn
            text: token; url: #section-3.7
            text: boolean; url: #section-3.9
    type: abstract-op
        text: serialize Structured Header; url: #section-4.1
urlPrefix: https://html.spec.whatwg.org/multipage/browsing-the-web.html;
    type: dfn
        text: create navigation params by fetching; url: #create-navigation-params-by-fetching
</pre>

<pre class="link-defaults">
spec:html; type:dfn; text:environment
spec:html; type:dfn; for:site; text:same site
spec:fetch; type:dfn; for:/; text:request
spec:fetch; type:dfn; text:main fetch
spec:url; type:dfn; for:/; text:url
</pre>

Introduction {#intro}
=====================

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
<i lang="la">a priori</i> 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.

Examples {#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 `https://example.com` to `https://example.com/` 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
```

Fetch Metadata Headers {#framework}
===================================

The following sections define several <dfn export>fetch metadata headers</dfn>, each of which
exposes an interesting [=request=] attribute to a server.

The `Sec-Fetch-Dest` HTTP Request Header {#sec-fetch-dest-header}
-----------------------------------------------------------------

The <dfn http-header export>`Sec-Fetch-Dest`</dfn> HTTP request header exposes a [=request=]'s
[=request/destination=] to a server. It is a [=Structured Header=] whose value MUST be a
[=structured header/token=]. [[!I-D.ietf-httpbis-header-structure]] Its ABNF is:

```
Sec-Fetch-Dest = sh-token
```

Valid `Sec-Fetch-Dest` values include the set of valid [=request=] [=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.

<pre class="example">
// `fetch()`'s destination is the empty string:
Sec-Fetch-Dest: empty

// `<img>`'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

// `<iframe>` navigations' destinations are "iframe"
Sec-Fetch-Dest: iframe
</pre>

<div algorithm="set `Sec-Fetch-Dest`">
To <dfn abstract-op lt="set-dest">set the `Sec-Fetch-Dest` header</dfn> for a [=request=] |r|:

<ol class="algorithm">
    1.  Assert: |r|'s [=request/url=] is a [=potentially trustworthy URL=].

    2.  Let |header| be a [=Structured Header=] whose value is a [=structured header/token=].

    3.  If |r|'s [=request/destination=] is the empty string, set |header|'s value to the string
        "`empty`". Otherwise, set |header|'s value to |r|'s [=request/destination=].

        Note: We map Fetch's empty string [=request/destination=] onto an explicit "`empty`"
        [=structured header/token=] in order to simplify processing.

    4.  [=header list/Set a structured field value=]
        &#96;<a http-header>`Sec-Fetch-Dest`</a>&#96;/|header| in |r|'s [=request/header list=].
</div>



The `Sec-Fetch-Mode` HTTP Request Header {#sec-fetch-mode-header}
-----------------------------------------------------------------

The <dfn http-header export>`Sec-Fetch-Mode`</dfn> HTTP request header exposes a [=request=]'s
[=request/mode=] to a server. It is a [=Structured Header=] whose value is a
[=structured header/token=]. [[!I-D.ietf-httpbis-header-structure]] Its ABNF is:

```
Sec-Fetch-Mode = sh-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.

<div algorithm="set `Sec-Fetch-Mode`">
To <dfn abstract-op lt="set-mode">set the `Sec-Fetch-Mode` header</dfn> for a [=request=] |r|:

<ol class="algorithm">
    1.  Assert: |r|'s [=request/url=] is a [=potentially trustworthy URL=].

    2.  Let |header| be a [=Structured Header=] whose value is a [=structured header/token=].

    3.  Set |header|'s value to |r|'s [=request/mode=].

    4.  [=header list/Set a structured field value=]
        &#96;<a http-header>`Sec-Fetch-Mode`</a>&#96;/|header| in |r|'s [=request/header list=].
</ol>
</div>


The `Sec-Fetch-Site` HTTP Request Header {#sec-fetch-site-header}
-----------------------------------------------------------------

The <dfn http-header export>`Sec-Fetch-Site`</dfn> HTTP request header exposes the relationship
between a [=request=] initiator's origin and its target's origin. It is a [=Structured Header=]
whose value is a [=structured header/token=]. [[!I-D.ietf-httpbis-header-structure]] Its ABNF is:

```
Sec-Fetch-Site = sh-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.

<div algorithm="set `Sec-Fetch-Site`">
To <dfn abstract-op lt="set-site">set the `Sec-Fetch-Site` header</dfn> for a [=request=] |r|:

<ol class="algorithm">
    1.  Assert: |r|'s [=request/url=] is a [=potentially trustworthy URL=].

    2.  Let |header| be a [=Structured Header=] whose value is a [=structured header/token=].

    3.  Set |header|'s value to `same-origin`.

    4.  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: See [[#directly-user-initiated]] for more detail on this somewhat poorly-defined step.

    5.  If |header|'s value is not `none`, then for each |url| in |r|'s [=request/url list=]:

        1.  If |url| is [=same origin=] with |r|'s [=request/origin=], [=iteration/continue=].

        2.  Set |header|'s value to `cross-site`.

        3.  If |r|'s [=request/origin=] is not [=same site=] with |url|'s [=url/origin=], then [=iteration/break=].

        4.  Set |header|'s value to `same-site`.

    6.  [=header list/Set a structured field value=]
        &#96;<a http-header>`Sec-Fetch-Site`</a>&#96;/|header| in |r|'s [=request/header list=].
</ol>
</div>


The `Sec-Fetch-User` HTTP Request Header {#sec-fetch-user-header}
-----------------------------------------------------------------

The <dfn http-header export>`Sec-Fetch-User`</dfn> HTTP request header exposes whether or not a
[=navigation request=] was triggered by user activation. It is a [=Structured Header=] whose
value is a [=structured header/boolean=]. [[!I-D.ietf-httpbis-header-structure]] Its ABNF is:

```
Sec-Fetch-User = sh-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.

<div algorithm="set `Sec-Fetch-User`">
To <dfn abstract-op lt="set-user">set the `Sec-Fetch-User` header</dfn> for a [=request=] |r|:

<ol class="algorithm">
    1.  Assert: |r|'s [=request/url=] is a [=potentially trustworthy URL=].

    2.  If |r| is not a [=navigation request=], or if |r|'s [=request/user-activation=] is
        `false`, return.

    3.  Let |header| be a [=Structured Header=] whose value is a [=structured header/token=].

    4.  Set |header|'s value to `true`.

    5.  [=header list/Set a structured field value=]
        &#96;<a http-header>`Sec-Fetch-User`</a>&#96;/|header| in |r|'s [=request/header list=].
</ol>
</div>


Integration with Fetch and HTML {#fetch-integration}
===========================================

To support `Sec-Fetch-User`, [=request=] has a [=request/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]].

<div algorithm="append fetch metadata headers">
To <dfn abstract-op export>append the Fetch metadata headers for a request</dfn>, given [=request=] |r|:

<ol class="algorithm">
    1.  If |r|'s [=request/url=] is not an [=potentially trustworthy URL=], return.

    2.  <a abstract-op lt='set-dest'>Set the `Sec-Fetch-Dest` header</a> for |r|.

    3.  <a abstract-op lt='set-mode'>Set the `Sec-Fetch-Mode` header</a> for |r|.

    4.  <a abstract-op lt='set-site'>Set the `Sec-Fetch-Site` header</a> for |r|.

    5.  <a abstract-op lt='set-user'>Set the `Sec-Fetch-User` header</a> for |r|.
</ol>
</div>


Security and Privacy Considerations {#sec-priv-considerations}
==============================================================

Redirects {#redirects}
----------------------

The user agent will send a <a http-header>`Sec-Fetch-Site`</a> 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 <a abstract-op lt='set-site'>set the `Sec-Fetch-Site` header</a> walks the [=request=]'s entire
[=request/url list=], and will send `cross-site` if any URL in the list is cross-site to the
request's [=request/current url=], `same-site` only if all URLs in the list are same-site with the
request's [=request/current url=], and `same-origin` only if all URLs in the list are same-origin
with the request's [=request/current url=].

For example, if `https://example.com/` requests `https://example.com/redirect`, the initial
request's `Sec-Fetch-Site` value would be `same-origin`. If that response redirected to
`https://subdomain.example.com/redirect`, that request's `Sec-Fetch-Site` value would be
`same-site` (as `https://subdomain.example.com/` and `https://example.com/` have the same
registrable domain). If that response redirected to `https://example.net/redirect`, that
request's `Sec-Fetch-Site` value would be `cross-site` (as `https://example.net/` is not
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
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`.

The `Sec-` Prefix {#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.

Directly User-Initiated Requests {#directly-user-initiated}
-----------------------------------------------------------

When <a abstract-op lt='set-site'>setting the `Sec-Fetch-Site` header</a>, 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](https://html.spec.whatwg.org/multipage/browsing-the-web.html#navigating-across-documents)
"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.

Extension-Initiated Requests {#extension-initiated}
---------------------------------------------------

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:

1.  Extensions without special privileges for a given site cannot cause requests that would bypass
    that site's server-side Fetch Metadata logic.

2.  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:

1.  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`.

2.  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.

Deployment Considerations {#deployment-considerations}
======================================================

Vary {#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`.

Header Bloat {#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](https://github.com/w3ctag/design-reviews/issues/280).

IANA Considerations {#iana}
===========================

The permanent message header field registry should be updated with the following registrations for
[=Fetch metadata headers=]: [[!RFC3864]]

`Sec-Fetch-Dest` Registration {#sec-fetc-dest-reg}
-----------------------------

:   Header field name
::  Sec-Fetch-Dest
:   Applicable protocol
::  http
:   Status
::  standard
:   Author/Change controller
::  Me
:   Specification document
::  This specification (See [[#sec-fetch-dest-header]])

`Sec-Fetch-Mode` Registration {#sec-fetch-mode-reg}
-----------------------------

:   Header field name
::  Sec-Fetch-Mode
:   Applicable protocol
::  http
:   Status
::  standard
:   Author/Change controller
::  Me
:   Specification document
::  This specification (See [[#sec-fetch-mode-header]])

`Sec-Fetch-Site` Registration {#sec-fetch-site-reg}
-----------------------------

:   Header field name
::  Sec-Fetch-Site
:   Applicable protocol
::  http
:   Status
::  standard
:   Author/Change controller
::  Me
:   Specification document
::  This specification (See [[#sec-fetch-site-header]])

`Sec-Fetch-User` Registration {#sec-fetch-user-reg}
-----------------------------

:   Header field name
::  Sec-Fetch-User
:   Applicable protocol
::  http
:   Status
::  standard
:   Author/Change controller
::  Me
:   Specification document
::  This specification (See [[#sec-fetch-user-header]])

Acknowledgements {#acks}
========================

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.