diff --git a/index.html b/index.html index 7befdac..b10a062 100644 --- a/index.html +++ b/index.html @@ -4,15 +4,14 @@ Client Hints Infrastructure - + - + - - + - + - + - + - - + - +a.self-link::before { content: "¶"; } +.heading > a.self-link::before { content: "§"; } +dfn > a.self-link::before { content: "#"; } +

Client Hints Infrastructure

-

Draft Community Group Report,

+

Draft Community Group Report,

This version: @@ -476,7 +534,7 @@

Client Hints Infrastructure

-

Copyright © 2023 the Contributors to the Client Hints Infrastructure Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). +

Copyright © 2024 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.

@@ -535,7 +593,6 @@

Table of Contents

Conformance
  1. Document conventions -
  2. Conformant Algorithms
  • Index @@ -593,15 +650,8 @@

    2

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

      -
    • -

      The Critical-CH response header, which servers may use to request a reload -to include critical Client Hints missing in the initial load.

      -
    +

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

    @@ -628,16 +678,19 @@

    2 hints are removed from not delegated-to cross-origin requests after redirections.

    +
  • +

    Defines the Critical-CH response header, which servers may use to request a restart + to include critical Client Hints missing in the initial load.

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

    + by patching various concepts there.

  • W3C Permissions Policy specification

  • Client Hints Reliability

    @@ -650,13 +703,15 @@

    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), +

    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.

    -

    Note: A site can clear the browser’s Accept-CH cache for its origin by sending an empty Accept-CH header in a response. This sets the origin’s client hints set to an empty set.

    +cache whenever the user clears their cookies or when session cookies expire. +A user agent also MUST clear the Accept-CH according to the rules of the Clear-Site-Data Header.

    +

    A site can clear the browser’s Accept-CH cache for its origin by sending an empty Accept-CH header in a response. This sets the origin’s client hints set to an empty set.

    +

    There MAY be multiple Accept-CH headers per-response and sf-lists can be split across lines as long as each line contains at least one token.

    Note: As the cache can only be modified by the top-level frame, it is considered to be partitioned.

    When asked to update the client hints set from cache given a settingsObject:

      @@ -687,13 +742,15 @@

      Accept-CH cache that means only subsiquent loads of that origin will include the hints. If it’s critical that every load (including the first) has the requested Client Hints, -then the server can set a Critical-CH header to request a reload. The Critical-CH header itself does not modify the Accept-CH cache.

      -

      A reload will only occur when a hint in the Accept-CH header is both not in the Accept-CH cache and in the Critical-CH header. If hints listed in -the Critical-CH header are already in the Accept-CH cache no reload is +then the server can set a Critical-CH header to request a restart. The Critical-CH header itself does not modify the Accept-CH cache.

      +

      A restart will only occur when a hint in the Accept-CH header is both not in the Accept-CH cache and in the Critical-CH header. If hints listed in +the Critical-CH header are already in the Accept-CH cache no restart is needed as they were sent. If hints listed in the Critical-CH header are not -in the Accept-CH header a reload would not result in the hints being included +in the Accept-CH header a restart would not result in the hints being included anyway.

      -

      When asked if the user agent should reload page for critical client hints given a settingsObject and response:

      +

      The restart retries the entire navigation (including any prior redirects).

      +

      There MAY be multiple Critical-CH headers per-response and sf-lists can be split across lines as long as each line contains at least one token.

      +

      When asked if the user agent should restart loading the page for critical client hints given a settingsObject and response:

      1. If settingsObject is a non-secure context, abort these steps.
      2. Let browsingContext be settingsObject’s global object's browsing context. @@ -720,11 +777,12 @@

        3.4. Delegate-CH

        +

        There MAY be multiple Delegate-CH tags per-document and this algorithm is run once for each in the order of the appearance of the tags.

        Note: This metadata appends client hints tokens to the environment settings object's client hints set. It does not add those hints to the Accept-CH cache.

        1. Let metaElement be the meta element.
        2. If any link, style, or script elements have begun to execute, then return. -
        3. If metaElement has no name attribute, or if that attribute’s value is not delegate-ch, then return. +
        4. If metaElement has no http-equiv attribute, or if that attribute’s value is not delegate-ch, then return.
        5. If metaElement has no content attribute, or if that attribute’s value is the empty string, then return.
        6. Let settingsObject be metaElement’s relevant settings object.
        7. If settingsObject is a non-secure context, abort these steps. @@ -752,30 +810,45 @@

          Accept-CH cache, but will be retrieved and merged when update the client hints set from cache is run. The full processing model is defined in Client Hints Reliability.

          +

          There MUST be only one ACCEPT_CH frames per-connection. Additional frames will be ignored.

          4. Integration with HTML

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

          Add a new field to navigable:

            -
          • A has reloaded for Critical-CH boolean, initially false. +
          • A Critical-CH restart time DOMHighResTimeStamp, initially 0. + This records the time the navigation was restarted to ensure required Client Hint + headers will be sent.

          At populating a session history entry, in step 6 after substep 7 insert the following:

            -
          1. Let shouldReloadForCriticalClientHints be false. +
          2. Let shouldRestartForCriticalClientHints be false.
          3. - If navigable’s has reloaded for Critical-CH is false: + If navigable’s Critical-CH restart time is 0:
              -
            1. Let shouldReloadForCriticalClientHints be the result of running should reload page for critical client hints with the relevant settings object and response. +
            2. Let shouldRestartForCriticalClientHints be the result of running should restart page for critical client hints with the relevant settings object and response.
          4. Run create or override the cached client hints set with the relevant settings object and response as inputs.
          5. - If shouldReloadForCriticalClientHints then: + If shouldRestartForCriticalClientHints then: +
              +
            1. Set navigable’s Critical-CH restart time to the current high resolution time. +
            2. Restart the initial navigation (before any redirects). +
            +
          6. + If navigable’s Critical-CH restart time is not 0:
              -
            1. Set navigable’s has reloaded for Critical-CH to true. -
            2. reload navigable. +
            3. Set navigationParams’s Critical-CH restart time to be navigable’s Critical-CH restart time.
          +

          Clarify how "Restart the initial navigation (before any redirects)" integrates with the HTML spec. [Issue #154]

          +

          At navigation params, append the following:

          +
          +
          Critical-CH restart time +
          a DOMHighResTimeStamp used for creating the navigation timing entry for the new Document. + This records the time the navigation was restarted to ensure required Client Hint headers will be sent. +

          4.3. Service Worker initialization

          At set up a worker environment settings object, after step 6, add the following step: @@ -799,7 +872,12 @@

          navigation request for a "document" destination and if the result of running Permissions Policy § 9.10 Should request be allowed to use feature? given request and hintName’s associated feature in § 7.2 Policy-controlled features returns false, then continue to next hintName. +
        8. + If request is not a navigation request for a "document" destination: +
            +
          1. Let requestPermitsHint be the result of running Permissions Policy § 9.13 Should request be allowed to use feature? given request and hintName’s associated feature in § 7.2 Policy-controlled features. +
          2. If requestPermitsHint is false, then continue to next hintName. +
        9. If the user agent decides, in an implementation-defined way (see § 8 Security and Privacy considerations), to omit this hint then continue.
        10. Let value be the result of running find client hint value with hintName.
        11. If the user agent decides, in an implementation-defined way (see § 8 Security and Privacy considerations), to modify value then do so. @@ -980,20 +1058,6 @@

          , 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

          @@ -1031,420 +1095,130 @@

          client hints token, in § 7.1
        12. create or override the cached client hints set, in § 3.2 +
        13. Critical-CH restart time, in § 4.1
        14. Delegate-CH, in § 3.4
        15. field-name, in § 9
        16. find client hint value, in § 7.4 -
        17. has reloaded for Critical-CH, in § 4.1
        18. high-entropy client hint, in § 7.3
        19. low entropy hint table, in § 7.3
        20. low-entropy hint table, in § 7.3
        21. origin, in § 3.2
        22. policy-controlled client hints features, in § 7.2
        23. remove client hints from redirect if needed, in § 5 -
        24. should reload page for critical client hints, in § 3.3 +
        25. should restart loading the page for critical client hints, in § 3.3
        26. update the client hints set from cache, in § 3.2 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

          Terms defined by reference

            +
          • + [CLEAR-SITE-DATA] defines the following terms: +
              +
            • clear-site-data header +
          • [FETCH] defines the following terms:
              -
            • append -
            • client -
            • contains -
            • destination -
            • fetch -
            • forbidden request-header -
            • header list -
            • http-network-or-cache fetch -
            • http-redirect fetch -
            • name -
            • navigation request -
            • non-subresource request -
            • request -
            • value +
            • append +
            • client +
            • contains +
            • destination +
            • fetch +
            • forbidden request-header +
            • header list +
            • http-network-or-cache fetch +
            • http-redirect fetch +
            • name +
            • navigation request +
            • non-subresource request +
            • request +
            • value +
            +
          • + [HR-TIME-3] defines the following terms: +
              +
            • DOMHighResTimeStamp +
            • current high resolution time
          • [HTML] defines the following terms:
              -
            • browsing context -
            • content -
            • environment settings object -
            • global object -
            • link -
            • meta -
            • name -
            • navigable -
            • non-secure context -
            • origin -
            • permissions policy -
            • populating a session history entry -
            • relevant settings object -
            • reload -
            • same origin -
            • script -
            • set up a worker environment settings object -
            • standard metadata names -
            • style -
            • top-level browsing context +
            • browsing context +
            • content +
            • environment settings object +
            • global object +
            • http-equiv +
            • link +
            • meta +
            • navigable +
            • non-secure context +
            • origin +
            • permissions policy +
            • populating a session history entry +
            • relevant settings object +
            • same origin +
            • script +
            • set up a worker environment settings object +
            • standard metadata names +
            • style +
            • top-level browsing context
          • [INFRA] defines the following terms:
              -
            • append -
            • byte-lowercase -
            • clone -
            • for each -
            • implementation-defined -
            • key -
            • ordered map -
            • ordered set -
            • set -
            • set (for map) -
            • user agent +
            • append +
            • byte-lowercase +
            • clone +
            • for each +
            • implementation-defined +
            • key +
            • ordered map +
            • ordered set +
            • set +
            • set (for map) +
            • user agent +
            +
          • + [NAVIGATION-TIMING-2] defines the following terms: +
              +
            • create the navigation timing entry
          • [PERMISSIONS-POLICY-1] defines the following terms:
              -
            • default allowlist -
            • policy-controlled feature +
            • default allowlist +
            • policy-controlled feature
          • [SERVICE-WORKERS] defines the following terms:
              -
            • ServiceWorkerGlobalScope +
            • ServiceWorkerGlobalScope +
            +
          • + [STRUCTURED-FIELDS] defines the following terms: +
              +
            • sf-lists
          • [URL] defines the following terms:
              -
            • origin +
            • origin

          References

          Normative References

          +
          [CLEAR-SITE-DATA] +
          Mike West. Clear Site Data. URL: https://w3c.github.io/webappsec-clear-site-data/
          [FETCH]
          Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/ +
          [HR-TIME-3] +
          Yoav Weiss. High Resolution Time. URL: https://w3c.github.io/hr-time/
          [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/ +
          [NAVIGATION-TIMING-2] +
          Yoav Weiss; Noam Rosenthal. Navigation Timing Level 2. URL: https://w3c.github.io/navigation-timing/
          [PERMISSIONS-POLICY-1]
          Ian Clelland. Permissions Policy. URL: https://w3c.github.io/webappsec-permissions-policy/
          [RFC2119] @@ -1466,173 +1240,580 @@

          Issues Index

          Clarify detection of link, style, or script element execution. [Issue #110] ↵
          +
          Clarify how "Restart the initial navigation (before any redirects)" integrates with the HTML spec. [Issue #154] ↵
          Should we tie low-entropy-ness to allowlists, generally? ↵
          Links for image features are broken, need to actually define that and link to them. ↵
          - - - - - - - - - - - - - - - - - + + + \ No newline at end of file