Intent to Ship: Document-Policy header

144 views
Skip to first unread message

Ian Clelland

unread,
Jul 24, 2020, 10:44:11 AM7/24/20
to blink-dev
icle...@google.com https://github.com/w3c/webappsec-permissions-policy/blob/master/document-policy-explainer.md https://w3c.github.io/webappsec-permissions-policy/document-policy.html https://github.com/w3ctag/design-reviews/issues/408 Document Policy is a general-purpose configuration mechanism for the web platform. It can be used to change the behaviour of features on a per-document basis, allowing things like: - Restricting the use of poorly-performing images - Disabling slow synchronous JS APIs - Configuring frame, image, or script loading styles - Restricting overall document sizes or network usage - Restricting patterns which cause page re-layout Note that this intent is just for the HTTP header which can be used to set a policy on a document, and does not include any controlled features -- they will have their own intents and Chrome Platform Status entries. However, we expect that the "force-load-at-top" policy will ship in conjunction with this, as the opt-out mechanism for the scroll-to-text-fragment feature.

The full Document Policy API also includes a negotiation mechanism, by which documents can request policies to be enforced on subframes. Required policies, and restrictions on subframes are not part of this intent, and will be covered by a separate launch. The full API is represented on Chrome Platform Status at https://www.chromestatus.com/feature/5645593894453248. https://groups.google.com/a/chromium.org/g/blink-dev/c/Biu2XfAls5A/m/tJFlkdE0AgAJ
If other engines do not implement the Document-Policy header, then the features which are configured with it will not be modifiable on those platforms. The risk here can be taken on a feature-by-feature basis. For the initial set of considered features, the risk is minimized by one of two factors: 1. Features may be performance optimizations only (image compression or dimension policies, font-display policy) where the goal is to guide sites to design which is fast on all browsers, regardless of support, and for which a non-supporting browser will simply not enforce the performance measures. 2. Features controlled may be Chromium-only, such as scroll-to-text-fragment. The web platform is not significantly impacted by lack of Document-Policy header support for scroll-to-text-fragment, for instance, on browsers which do not support that feature at all anyway. Gecko: Neutral (https://mozilla.github.io/standards-positions/#document-policy) Mozilla's official position on this is "non-harmful", though they have been involved in the design and direction of this API since its inception and split from Feature Policy. WebKit: No signal Web developers: No signals As a meta-feature, Document Policy is intended to be used in conjunction with a variety of features. However, in most cases, the goal is to improve performance, aligning as much as possible with the goals and metrics of the Web Core Vitals project. It does not limit Chrome's ability to maintain performance. Document-Policy can be taken advantage of immediately by interested developers, just by configuring their servers to set appropriate headers. Outreach and documentation can help to let developers know that these new controls are available, but no more than any other feature. The primary security risks associated with Document Policy are around policy negotiation in subframes, which this intent does not cover. We do not believe that there are significant security risks around allowing a site to set its own policy through this header.
We are considering a devtools extension, similar to https://chrome.google.com/webstore/detail/feature-policy-tester-dev/pchamnkhkeokbpahnocjaeednpbpacop, to allow developers to set and test policies locally. Policy negotiation (not covered by this intent) may benefit from deeper devtools integration. Yes Yes There are tests under https://wpt.fyi/results/document-policy around header parsing and behavior, including reporting, and we are creating tests for the behavior of individual policies. Most of those tests have been previously written as the features were part of a Feature Policy origin trial, and are being migrated to use the new Document Policy header. https://bugs.chromium.org/p/chromium/issues/detail?id=993790 https://www.chromestatus.com/feature/5756689661820928
This intent message was generated by Chrome Platform Status.

Yoav Weiss

unread,
Jul 28, 2020, 9:03:56 AM7/28/20
to Ian Clelland, blink-dev
On Fri, Jul 24, 2020 at 4:44 PM Ian Clelland <icle...@chromium.org> wrote:
icle...@google.com https://github.com/w3c/webappsec-permissions-policy/blob/master/document-policy-explainer.md https://w3c.github.io/webappsec-permissions-policy/document-policy.html https://github.com/w3ctag/design-reviews/issues/408 Document Policy is a general-purpose configuration mechanism for the web platform. It can be used to change the behaviour of features on a per-document basis, allowing things like: - Restricting the use of poorly-performing images - Disabling slow synchronous JS APIs - Configuring frame, image, or script loading styles - Restricting overall document sizes or network usage - Restricting patterns which cause page re-layout Note that this intent is just for the HTTP header which can be used to set a policy on a document, and does not include any controlled features -- they will have their own intents and Chrome Platform Status entries. However, we expect that the "force-load-at-top" policy will ship in conjunction with this, as the opt-out mechanism for the scroll-to-text-fragment feature.

The full Document Policy API also includes a negotiation mechanism, by which documents can request policies to be enforced on subframes. Required policies, and restrictions on subframes are not part of this intent, and will be covered by a separate launch. The full API is represented on Chrome Platform Status at https://www.chromestatus.com/feature/5645593894453248. https://groups.google.com/a/chromium.org/g/blink-dev/c/Biu2XfAls5A/m/tJFlkdE0AgAJ
If other engines do not implement the Document-Policy header, then the features which are configured with it will not be modifiable on those platforms. The risk here can be taken on a feature-by-feature basis. For the initial set of considered features, the risk is minimized by one of two factors: 1. Features may be performance optimizations only (image compression or dimension policies, font-display policy) where the goal is to guide sites to design which is fast on all browsers, regardless of support, and for which a non-supporting browser will simply not enforce the performance measures. 2. Features controlled may be Chromium-only, such as scroll-to-text-fragment. The web platform is not significantly impacted by lack of Document-Policy header support for scroll-to-text-fragment, for instance, on browsers which do not support that feature at all anyway. Gecko: Neutral (https://mozilla.github.io/standards-positions/#document-policy) Mozilla's official position on this is "non-harmful", though they have been involved in the design and direction of this API since its inception and split from Feature Policy. WebKit: No signal

Could you ask for a signal

Web developers: No signals As a meta-feature, Document Policy is intended to be used in conjunction with a variety of features. However, in most cases, the goal is to improve performance, aligning as much as possible with the goals and metrics of the Web Core Vitals project. It does not limit Chrome's ability to maintain performance. Document-Policy can be taken advantage of immediately by interested developers, just by configuring their servers to set appropriate headers. Outreach and documentation can help to let developers know that these new controls are available, but no more than any other feature. The primary security risks associated with Document Policy are around policy negotiation in subframes, which this intent does not cover. We do not believe that there are significant security risks around allowing a site to set its own policy through this header.
We are considering a devtools extension, similar to https://chrome.google.com/webstore/detail/feature-policy-tester-dev/pchamnkhkeokbpahnocjaeednpbpacop, to allow developers to set and test policies locally. Policy negotiation (not covered by this intent) may benefit from deeper devtools integration. Yes Yes There are tests under https://wpt.fyi/results/document-policy around header parsing and behavior, including reporting, and we are creating tests for the behavior of individual policies. Most of those tests have been previously written as the features were part of a Feature Policy origin trial, and are being migrated to use the new Document Policy header. https://bugs.chromium.org/p/chromium/issues/detail?id=993790 https://www.chromestatus.com/feature/5756689661820928
This intent message was generated by Chrome Platform Status.

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAK_TSXK9_xvbnmk1jXuR2jVER248OMhR6uKaHLNV-1kPMAGSXg%40mail.gmail.com.

Ian Clelland

unread,
Jul 28, 2020, 9:56:18 AM7/28/20
to Yoav Weiss, blink-dev
On Tue, Jul 28, 2020 at 9:03 AM Yoav Weiss <yo...@yoav.ws> wrote:
On Fri, Jul 24, 2020 at 4:44 PM Ian Clelland <icle...@chromium.org> wrote:
Gecko: Neutral (https://mozilla.github.io/standards-positions/#document-policy) Mozilla's official position on this is "non-harmful", though they have been involved in the design and direction of this API since its inception and split from Feature Policy. WebKit: No signal

Could you ask for a signal

Done, thanks -- I can link to the discussion when it shows up in the archive.

Thomas Steiner

unread,
Jul 28, 2020, 10:15:34 AM7/28/20
to Ian Clelland, Yoav Weiss, blink-dev

Mike West

unread,
Jul 30, 2020, 2:28:01 PM7/30/20
to blink-dev, Thomas Steiner, yo...@yoav.ws, blink-dev, Ian Clelland
LGTM1. I've seen reasonable engagement from our colleagues at Mozilla, and I'm happy that this approach has mitigated some of the concerns they raised about the Feature Policy model. I think there still might be some disagreements to come when we start talking about individual policies, but I think the framework at large provides a good model for changing the behavior of a given document, and the inheritance mechanism will allow more nuanced policy options than Feature Policy allowed, given its opt-in nature. This direction seems like a good one, and I'm happy to see it ship.

I note that the TAG review isn't complete, but I believe you've addressed concerns raised in the thread thus far, and they haven't responded to your invitation to review your updates since mid-April. I don't think we need to block on further feedback.

-mike

Chris Harrelson

unread,
Jul 30, 2020, 2:49:49 PM7/30/20
to Mike West, blink-dev, Thomas Steiner, yo...@yoav.ws, Ian Clelland
LGTM2

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.

Yoav Weiss

unread,
Jul 30, 2020, 3:33:10 PM7/30/20
to Chris Harrelson, Mike West, blink-dev, Thomas Steiner, Ian Clelland
LGTM3

Ian Clelland

unread,
Jul 30, 2020, 4:40:43 PM7/30/20
to Yoav Weiss, Chris Harrelson, Mike West, blink-dev, Thomas Steiner
Thanks, everyone!
Reply all
Reply to author
Forward
0 new messages