# Client Hints Infrastructure

## Draft Community Group Report, 1 January 1970

This version:
  https://wicg.github.io/client-hints-infrastructure
Editor:
  Yoav Weiss (Google) yoav@yoav.ws

Copyright © 1970 the Contributors to the Client Hints Infrastructure Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

## Abstract

Specification of the Client Hints infrastructure and its integration with Fetch and HTML

## Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

## 1. Introduction

Client Hints is collection of HTTP and user-agent features that enables privacy-preserving, proactive content negotiation with an explicit third-party delegation mechanism:

- Proactive content negotiation at the HTTP layer enables servers to request delivery of specific hints, in order to enable optimized and automated selection of resources based on a user’s device, conditions and preferences, and lets clients decide which hint requests they want to grant, with per-hint and per-origin granularity.

- Integration of said mechanism with web concepts, defined in this document, enables browsers to benefit from content adaptation, and have it play nicely with current web restrictions (e.g. same-origin policy).

- The opt-in nature of the mechanism enables browsers to advertise requested hint data (e.g. user agent and device characteristics) selectively to secure-transport origins, instead of appending such data on every outgoing request.

- Origin opt-in applies to same-origin assets only and delivery to third-party origins is subject to explicit first party delegation via Feature Policy, enabling tight control over which third party origins can access requested hint data.

The goal of Client Hints is to reduce passive fingerprinting on the web while enabling scalable and privacy preserving content adaptation between client and server, via a standardized set of content negotiation primitives at the HTTP and user agent levels.

## 2. Infrastructure definition

The specification of the Client Hints infrastructure is divided between the following specifications and proposals:

- IETF [CLIENT-HINTS]

  - Provides the motivation for Client Hints.

  - Defines the fundamental Client Hints infrastructure:

    - The `Accept-CH` response header, which servers may use to advertise support for certain Client Hints.

  - Provides both general guidelines, and formal requirements, about Client Hints’ impact on caching, security, and privacy.

  - Does not define any actual, particular hints – or say anything about how Client Hints works in web contexts.

- Client Hints infrastructure - this document

  - Defines how web clients should process the `Accept-CH` headers sent by servers.

  - Defines the environment settings object state related to `Accept-CH`, which stores information about which servers should get which hints.

  - Defines how, and when, web clients should actually go about sending hints, based on the state of their environment settings object.

    - More specifically, it integrates the HTML web concepts with Fetch’s algorithms to make sure that opted-in hints are added to requests for same-origin or delegated-to cross-origin requests. It also makes sure hints are removed from not delegated-to cross-origin requests after redirections.

  - Integrates those concepts with the [HTML] and [FETCH] specifications, by patching various concepts there.

- W3C Feature Policy specification (relevant section)

  - In order to perform third party Client Hint delegation, Feature Policy has been extended to control features within fetch requests (rather than just Documents).

## 3. Environment settings object processing

### 3.1. Client hints set

A client hints set is a set of client hints tokens.

### 3.2. Accept-CH cache

An Accept-CH cache is owned by the user agent and is an ordered map, keyed on origin (an origin), with a value of client hints set (a client hints set).

The Accept-CH cache can effectively act as an alternative cookie store, since sites can use each of the hints as a bit set on the client, and that information will be communicated to them on every request. As such, a user agent MUST evict that cache whenever the user clears their cookies or when session cookies expire.

To add a new Accept-CH cache entry to the Accept-CH cache, given an origin origin and a client hints set client hints set, set Accept-CH cache[origin] to client hints set.

To retrieve the client hints set given an origin:

1. Let clientHintsSet be an empty ordered set.

2. Let originMatchingEntries be the entries in the Accept-CH cache whose origin is same origin with origin.

3. For each entry in originMatchingEntries, for each token in its client hints set, append the token to clientHintsSet.

4. Return clientHintsSet.

### 3.3. Initialize Client Hints set

When asked to initialize the Client Hints set with settingsObject and response as inputs, run the following steps:

1. Let clientHintsSet be the result of running retrieve the client hints set with settingsObject’s origin.

2. For each hint in clientHintsSet, append hint to settingsObject’s client hints set.

3. If the result of executing Is an environment settings object contextually secure? on settingsObject is `"Not Secure"`, abort these steps.

4. Let browsingContext be settingsObject’s responsible browsing context.

5. If the top-level browsing context does not equal browsingContext, abort these steps.

6. If response’s `Accept-CH` header is present, parse the header field value according to the `Accept-CH` header parsing rules, as a field-name. Add each parsed client hints token to settingsObject’s client hints set.

7. Add a new Accept-CH cache entry with response’s origin and settingsObject’s client hints set as inputs.

Note, the above algorithm:

- Initializes client hints set on the environment settings object based on its origin.

- If we are in a secure context and the navigation is a top-level navigation, it parses `Accept-CH` and adds the results to the environment setting object’s client hints set as well as the Accept-CH cache.

### 3.4. Accept-CH state (`http-equiv="accept-ch"`)

Note: This pragma appends client hints tokens to the environment settings object's client hints set.

1. If the `meta` element is not a child of a `head` element, then return.

2. If the `meta` element has no `content` attribute, or if that attribute’s value is the empty string, then return.

3. Let settingsObject be the `meta` element’s relevant settings object.

4. If the result of executing Is an environment settings object contextually secure? on settingsObject is `"Not Secure"`, then return.

5. Let browsingContext be settingsObject’s responsible browsing context.

6. If the top-level browsing context does not equal browsingContext, abort these steps.

7. Let acceptCHValue be the `meta` element’s `content` attribute’s value.

8. Parse acceptCHValue according to the Accept-CH header parsing rules, as a field-name. Append each parsed client hints token to settingsObject’s client hints set.

9. Add a new Accept-CH cache entry with settingsObject’s origin, and settingsObject’s client hints set.

## 4. Integration with HTML

This specification integrates with the [HTML] specification by patching the algorithms below:

### 4.1. Document object initialization

At Create and initialize a Document object, after step 11, starting with "Initialize a Document’s CSP list", call initialize the Client Hints set with document’s relevant settings object and response as inputs.

### 4.2. Worker initialization

At set up a worker environment settings object, after step 6, add the following step:

1. Set settingsObject’s client hints set to be a clone of outside settings’ client hints set.

### 4.3. http-equiv attributes

This section is non-normative.

In the table on attributes, add "accept-ch" in the line which attribute is "http-equiv".

### 4.4. Pragma directives

For the table in pragma directives, add a line with a "State" value of Accept-CH and a "Keyword" value of accept-ch.

### 4.5. Extending environment settings object

An environment settings object has a client hints set: a client hints set, initially the empty set, used for fetches performed using the environment settings object as a request client.

## 5. Request processing

When asked to append client hints to request with request as input, run the following steps:

If request is a navigation request, a user agent should, for each header name (hintName) in the registry’s low entropy hint table, if request’s header list does not contain hintName, then append hintName/the corresponding value to request’s header list.

Define registry’s low entropy table

If request’s client is not null, then for each client hints token hintName of request’s client’s client hints set:

1. Let value be the return value of running find client hint value, given hintName as input.

2. If request is a subresource request and the result of running Should request be allowed to use feature?, given request and hintName’s associated policy-controlled feature, returns `false`, then skip the next steps and continue to the next hintName. [FEATURE-POLICY] [CLIENT-HINTS]

3. Set hintName to "Sec-" concatenated with hintName.

   We need to figure out if we really want a `Sec-` prefix, and if so also exempt it from CORS.

4. If request’s header list does not contain hintName, a user agent should append hintName/value to request’s header list.

When asked to remove client hints from redirect if needed with request as input, run the following steps:

1. If request’s client is null, then abort these steps.
2. Let clientHintsSet be request’s client’s client hints set.

3. For each hintName of clientHintsSet:

   1. Set hintName to "Sec-" concatenated with hintName.

   2. If request’s header list contains hintName and if the result of running Should request be allowed to use feature?, given request and hintName’s associated policy-controlled feature, returns `false`, then remove hintName from header list. [FEATURE-POLICY] [CLIENT-HINTS]

## 6. Integration with Fetch

This specification integrates with the [FETCH] specification by patching the algorithms below:

In Fetching, after step 1.6, run append client hints to request with request as input.

In HTTP-redirect fetch, after step 7, run remove client hints from redirect if needed with request as input.

## 7. Feature Registry

Note: This section contains feature-specific definitions. New features that rely on the Client Hints infrastructure need to add their respective definitions to this registry. User Agents can implement some of those features without implementing others.

### 7.1. Client hints token

A client hints token is a byte-lowercase representation of one of `Save-Data`, `DPR`, `Width`, `Viewport-Width`, `Device-Memory`, `RTT`, `Downlink`, `ECT`, `Arch`, `Model`, `Platform`, `UA` or `Mobile`.

### 7.2. Policy-controlled features

This document defines the following policy-controlled features:

- `ch-save-data` which has a default allowlist of `'*'`

- `ch-dpr` which has a default allowlist of `'self'`

- `ch-width` which has a default allowlist of `'self'`

- `ch-viewport-width` which has a default allowlist of `'self'`

- `ch-device-memory` which has a default allowlist of `'self'`

- `ch-rtt` which has a default allowlist of `'self'`

- `ch-downlink` which has a default allowlist of `'self'`

- `ch-ect` which has a default allowlist of `'self'`

- `ch-arch` which has a default allowlist of `'self'`

- `ch-model` which has a default allowlist of `'self'`

- `ch-platform` which has a default allowlist of `'self'`

- `ch-ua` which has a default allowlist of `'self'`

- `ch-mobile` which has a default allowlist of `'self'`

Should Save-data really have an allowlist of *? If so, is it because it’s somehow "low entropy" and should we tie low-entropy-ness to allowlists, generally?

### 7.3. Low entropy hint table

The low entropy hint table below defines hints that are only exposing low amounts of entropy.

Name | Value
--- | ---
`Save-Data` | a suitable Save-Data value

### 7.4. Find client hint value

When asked to find client hint value, given hint as input, switch on hint and return the result:

`Save-Data`
  a suitable Save-Data value
`DPR`
  a suitable DPR value
`Viewport-Width`
  a suitable Viewport-Width value
`Width`
  a suitable Width value
`Device-Memory`
  a suitable Device-Memory value
`RTT`
  a suitable RTT value
`Downlink`
  a suitable Downlink value
`ECT`
  a suitable ECT value
`Arch`
  a suitable Arch value
`Model`
  a suitable Model value
`Platform`
  a suitable Platform value
`UA`
  a suitable UA value
`Mobile`
  a suitable Mobile value

Links for image features are broken, need to actually define that and link to them.

## 8. Security and Privacy considerations

See [CLIENT-HINTS].

## 9. Terms

The following terms are defined in the HTTP specifications: field-name

## Conformance

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.

## Index

### Terms defined by this specification

- accept-ch, in §4.4
- Accept-CH cache, in §3.2
- Accept-CH state, in §3.4
- add a new Accept-CH cache entry, in §3.2
- append client hints to request, in §5
- ch-arch, in §7.2
- ch-device-memory, in §7.2
- ch-downlink, in §7.2
- ch-dpr, in §7.2
- ch-ect, in §7.2
- ch-mobile, in §7.2
- ch-model, in §7.2
- ch-platform, in §7.2
- ch-rtt, in §7.2
- ch-save-data, in §7.2
- ch-ua, in §7.2
- ch-viewport-width, in §7.2
- ch-width, in §7.2
- client hints set
  - definition of, in §3.1
  - dfn for accept-ch-cache, in §3.2
  - dfn for environment settings object, in §4.5
- client hints token, in §7.1
- field-name, in §9
- find client hint value, in §7.4
- initialize the Client Hints set, in §3.3
- low entropy hint table, in §7.3
- origin, in §3.2
- remove client hints from redirect if needed, in §5
- retrieve the client hints set, in §3.2

https://wicg.github.io/feature-policy/#default-allowlist Referenced in:

- 7.2. Policy-controlled features (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13)

https://wicg.github.io/feature-policy/#policy-controlled-feature Referenced in:

- 7.2. Policy-controlled features

https://fetch.spec.whatwg.org/#concept-header-list-append Referenced in:

- 5. Request processing (2)

https://fetch.spec.whatwg.org/#concept-request-client Referenced in:

- 4.5. Extending environment settings object
- 5. Request processing (2) (3)

https://fetch.spec.whatwg.org/#header-list-contains Referenced in:

- 5. Request processing (2) (3)

https://fetch.spec.whatwg.org/#header-list-contains Referenced in:

- 5. Request processing (2) (3)

https://fetch.spec.whatwg.org/#concept-fetch Referenced in:

- 4.5. Extending environment settings object
- 6. Integration with Fetch

https://fetch.spec.whatwg.org/#concept-header Referenced in:

- 5. Request processing

https://fetch.spec.whatwg.org/#concept-request-header-list Referenced in:

- 5. Request processing (2) (3) (4) (5) (6)

https://fetch.spec.whatwg.org/#concept-http-redirect-fetch Referenced in:

- 6. Integration with Fetch

https://fetch.spec.whatwg.org/#concept-header-name Referenced in:

- 5. Request processing
- 7.3. Low entropy hint table

https://fetch.spec.whatwg.org/#navigation-request Referenced in:

- 5. Request processing

https://fetch.spec.whatwg.org/#concept-request-request Referenced in:

- 4.5. Extending environment settings object

https://fetch.spec.whatwg.org/#subresource-request Referenced in:

- 5. Request processing

https://fetch.spec.whatwg.org/#concept-header-value Referenced in:

- 7.3. Low entropy hint table

https://html.spec.whatwg.org/multipage/semantics.html#attr-meta-content Referenced in:

- 3.4. Accept-CH state (http-equiv="accept-ch") (2)

https://html.spec.whatwg.org/multipage/webappapis.html#environment-settings-object Referenced in:

- 3.4. Accept-CH state (http-equiv="accept-ch")
- 4.5. Extending environment settings object (2)

https://html.spec.whatwg.org/multipage/semantics.html#the-head-element Referenced in:

- 3.4. Accept-CH state (http-equiv="accept-ch")

https://html.spec.whatwg.org/multipage/semantics.html#meta Referenced in:

- 3.4. Accept-CH state (http-equiv="accept-ch") (2) (3) (4)

https://html.spec.whatwg.org/multipage/webappapis.html#concept-settings-object-origin Referenced in:

- 3.3. Initialize Client Hints set

https://html.spec.whatwg.org/multipage/webappapis.html#relevant-settings-object Referenced in:

- 3.4. Accept-CH state (http-equiv="accept-ch")
- 4.1. Document object initialization

https://html.spec.whatwg.org/multipage/webappapis.html#responsible-browsing-context Referenced in:

- 3.3. Initialize Client Hints set
- 3.4. Accept-CH state (http-equiv="accept-ch")

https://html.spec.whatwg.org/multipage/origin.html#same-origin Referenced in:

- 3.2. Accept-CH cache

https://html.spec.whatwg.org/multipage/browsers.html#top-level-browsing-context Referenced in:

- 3.3. Initialize Client Hints set
- 3.4. Accept-CH state (http-equiv="accept-ch")

https://infra.spec.whatwg.org/#set-append Referenced in:

- 3.2. Accept-CH cache
- 3.3. Initialize Client Hints set
- 3.4. Accept-CH state (http-equiv="accept-ch")

https://infra.spec.whatwg.org/#byte-lowercase Referenced in:

- 7.1. Client hints token

https://infra.spec.whatwg.org/#list-clone Referenced in:

- 4.2. Worker initialization

https://infra.spec.whatwg.org/#list-iterate Referenced in:

- 5. Request processing (2)

https://infra.spec.whatwg.org/#map-key Referenced in:

- 3.2. Accept-CH cache

https://infra.spec.whatwg.org/#ordered-map Referenced in:

- 3.2. Accept-CH cache

https://infra.spec.whatwg.org/#ordered-set Referenced in:

- 3.1. Client hints set
- 3.2. Accept-CH cache

https://infra.spec.whatwg.org/#map-set Referenced in:

- 3.2. Accept-CH cache

https://w3c.github.io/webappsec-secure-contexts/#settings-object Referenced in:

- 3.3. Initialize Client Hints set
- 3.4. Accept-CH state (http-equiv="accept-ch")

### Terms defined by reference

- [FEATURE-POLICY] defines the following terms:
  - default allowlist
  - policy-controlled feature
- [FETCH] defines the following terms:
  - append
  - client
  - contains
  - does not contain
  - fetch
  - header
  - header list
  - http-redirect fetch
  - name
  - navigation request
  - request
  - subresource request
  - value
- [HTML] defines the following terms:
  - content
  - environment settings object
  - head
  - meta
  - origin (for environment settings object)
  - relevant settings object
  - responsible browsing context
  - same origin
  - top-level browsing context
- [INFRA] defines the following terms:
  - append
  - byte-lowercase
  - clone
  - for each
  - key
  - ordered map
  - ordered set
  - set (for map)
- [secure-contexts] defines the following terms:
  - Is an environment settings object contextually secure?

## References

### Normative References

[CLIENT-HINTS]
  Ilya Grigorik; Yoav Weiss. Client Hints. URL: https://httpwg.org/http-extensions/client-hints.html
[FEATURE-POLICY]
  Ian Clelland. Feature Policy. URL: https://wicg.github.io/feature-policy/
[FETCH]
  Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
  Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
  Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
  S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[SECURE-CONTEXTS]
  Mike West. Secure Contexts. 15 September 2016. CR. URL: https://www.w3.org/TR/secure-contexts/

## Issues Index

Define registry’s low entropy table ↵
We need to figure out if we really want a `Sec-` prefix, and if so also exempt it from CORS. ↵
Should Save-data really have an allowlist of *? If so, is it because it’s somehow "low entropy" and should we tie low-entropy-ness to allowlists, generally? ↵
Links for image features are broken, need to actually define that and link to them. ↵
#client-hints-set Referenced in:

- 3.2. Accept-CH cache (2)
- 4.5. Extending environment settings object

#accept-ch-cache Referenced in:

- 3.2. Accept-CH cache (2) (3)

#accept-ch-cache-origin Referenced in:

- 3.2. Accept-CH cache (2)

#accept-ch-cache-client-hints-set Referenced in:

- 3.2. Accept-CH cache

#add-a-new-accept-ch-cache-entry Referenced in:

- 3.3. Initialize Client Hints set
- 3.4. Accept-CH state (http-equiv="accept-ch")

#retrieve-the-client-hints-set Referenced in:

- 3.3. Initialize Client Hints set

#abstract-opdef-initialize-the-client-hints-set Referenced in:

- 4.1. Document object initialization

#accept-ch-state Referenced in:

- 4.4. Pragma directives

#accept-ch Referenced in:

- 3.4. Accept-CH state (http-equiv="accept-ch")

#environment-settings-object-client-hints-set Referenced in:

- 3.3. Initialize Client Hints set (2) (3)
- 3.4. Accept-CH state (http-equiv="accept-ch") (2) (3)
- 4.2. Worker initialization (2)
- 5. Request processing (2)

#abstract-opdef-append-client-hints-to-request Referenced in:

- 6. Integration with Fetch

#abstract-opdef-remove-client-hints-from-redirect-if-needed Referenced in:

- 6. Integration with Fetch

#client-hints-token Referenced in:

- 3.1. Client hints set
- 3.3. Initialize Client Hints set
- 3.4. Accept-CH state (http-equiv="accept-ch") (2)
- 5. Request processing

#low-entropy-hint-table Referenced in:

- 5. Request processing

#find-client-hint-value Referenced in:

- 5. Request processing

#field-name Referenced in:

- 3.3. Initialize Client Hints set
- 3.4. Accept-CH state (http-equiv="accept-ch")