Feature Policy: Document Policies

[clelland]

こんにちはTAG!

I'm requesting a TAG review of:

• Name: Document Policies
• Specification URL: https://wicg.github.io/document-policy/
• Explainer (containing user needs and example code)¹: https://github.com/wicg/document-policy/blob/main/document-policy-explainer.md
• GitHub issues (if you prefer feedback filed there): https://github.com/WICG/document-policy/issues
• Tests: https://wpt.fyi/results/document-policy
• Primary contacts (and their relationship to the specification): @clelland (author)

Further details:

• Relevant time constraints or deadlines: [please provide]
• I have read and filled out the Self-Review Questionnaire on Security and Privacy. The assessment is here.
• I have reviewed the TAG's API Design Principles
• The group where the work on this specification is: W3C WebAppSec

You should also know that the initial Feature Policy spec, which was reviewed previously (#159) by TAG, can be simplified with the adoption of Document Policies. The goal is to constrain it to just those features which are best served by the "allowed at top-level, delegate to cross-origin frames" model, and focus it tightly on that use case.

You should also also know that this explainer is the result of discussions which were also previously noted by TAG in #341.

This request has been updated (2020-12-08) to reflect the new repository which was opened in WICG for Document Policy, as a result of w3c/webappsec-permissions-policy#411.

We'd prefer the TAG provide feedback as (please select one):

• open issues in our GitHub repo for each point of feedback
• open a single issue in our GitHub repo for the entire review
• leave review feedback as a comment in this issue and @-notify [github usernames]

[clelland]

Friendly ping to TAG :) Is there any update on this since the TPAC f2f?

[torgo]

Sorry we haven't made enough progress here. We'll try to wrap things up in in 2 weeks.

[kenchris]

How does Document-Policy, Require-Document-Policy and Sec-Required-Policy relate to eachother and to the attribute "policy" (used for iframe etc, I assume that is mapped to Document-Policy).

I think the explainer should make this clear early on

[torgo]

Hi @clelland apologies this is taking so long. One poinf of feedback I have is that the explainer could be a bit clearer on the user need. Also: is there anything further on the spec itself?

A bit of elaboration on the detail in the explainer. For example, example one talks about performance guardrails. What is a guardrail? The example talks about "documents" and resources, but can we state this example in terms of (for example) "a commercial web site embeds ads from different 3rd parties and wants to ensure an overall good performance for the user so makes use of this feature policy to... xyz" - basically making it more clear what we aare talking about.

[kenchris]

Some things are not very clear in the explainer, like "associated flag, requires-acknowledgement".

What is an associated flag? I guess it is not a header as it is lower-case, also probably not an attribute either, so I guess this is part of the value, like "image-compression;bpp=4 requires-acknowledgement" also I believe the US spelling of "acknowledgment" is without the latter e

[clelland]

Thanks for taking a look -- I'll see if I can update the explainer. Some of the more formal bits can probably be removed now, since they're covered in the actual spec text.

To answer the questions here in advance of that:

1. There are three headers and an attribute, which work together like this:

• Document-Policy: Response header which sets the policy for the document it is delivered with.
• Require-Document-Policy: Response header which sets a minimum policy for any embedded content.
• <iframe policy>: attribute which sets a minimum policy for any content loaded into that frame.
• Sec-Required-Document-Policy: Request header, which details the minimum policy required for the document being requested.

Essentially, if there is a minimum policy required (in most cases there won't be, unless Require-Document-Policy or <iframe policy> has been used) then it is advertised to the server with the Sec-Required-Document-Policy header. If the document in the response doesn't meet that requirement, then it will not be loaded.

2. The spec has been updated since I filed this request (I'll update the issue with the link there) There are still a couple of sections needing to be fleshed out, but the algorithms and structures are all there, I believe.

3. "Guardrails" is an informal term we've been using to talk about controls that make it easier for developers to succeed, to create performant sites, either by removing poorly-performing APIs, or letting them know through reporting when they're doing something that is likely to be slow. I'll see if I can rewrite that, either to explain it or to use clearer terms.

4. The 'requires-acknowledgment' flag is part of definition the feature itself, and not something that is up to a developer to control. We would define that flag for a feature based on whether or not it is safe to impose the policy on a subframe without requiring the subframe to explicitly set it in its own Document-Policy header.

   As a couple of examples:

   • If we define a document policy feature to disable document.write, that could have unintended consequences on pages which aren't aware that it could be disabled, potentially introducing security bugs on a previously-safe page. So that policy would require acknowledgment. You could set it on your own document, but you can't impose it on another one without its consent.
   • If we define a policy that requires images to have declared sizes, to improve layout speed, that would likely not cause any drastic consequences to a page that wasn't aware of the policy (other than maybe making it look worse). We could probably safely impose that policy without needing the embedded page to acknowledge it explicitly.
   • Also, iframe sandboxing already defines a number of similar features that can be disabled, that don't require acknowledgment, and this has generally been okay. If we want to use Document Policy to explain sandboxing, then those features should be implemented in a way that doesn't require acknowledgment.

[kenchris]

I think it would be nice if the spec was a bit clearer on what are request and response headers - like you could group them in different sections.

Also as Require-Document-Policy is about content couldn't we make that clearer in the name, like Content-Policy or Document-Content-Policy. Then if <iframe policy> became <iframe content-policy> - then the relation would also be clearer

[kenchris]

I think the specification could use more examples, for instance I have trouble understanding parts like the requires-acknowlegment:

When explicit acknowledgment of a required policy is not required, similar to iframe sandbox, this means that behaviors of existing features may be changed in published web sites, by embedding them in another document with an appropriate required policy.

[atanassov]

Consider adding an example with deeper (more than one level) nesting in the section on Deeper Nesting. It was unclear if the Sec-Required-Document-Policy would be carried through deeply nested iframes in the case of no policy attribute being set.

Perhaps the example of your last section can be introduced earlier?

[clelland]

Also as Require-Document-Policy is about content couldn't we make that clearer in the name, like Content-Policy or Document-Content-Policy. Then if <iframe policy> became <iframe content-policy> - then the relation would also be clearer

@kenchris are you suggesting renaming the overall spec from "Document Policy" or just the headers / iframe attribute?

(I'm not super attached to the name, if we can find a better one. It's pretty generic as-is)

[clelland]

I've rewritten big parts of the explainer, hopefully to provide clearer explanations, as suggested above. The spec is also in a better place, and should be the final word on any algorithm questions and other speccy things.

[kenchris]

For self sandboxing, reporting seems to be a big deal - it is supported by the spec but not mentioned at all in the explainer. I think it should be. I could see an admin setting a document policy for a whole web site, with separate teams (maybe in other countries) creating the actual content that now might be blocked due to such a policy, thus reporting is quite important

[kenchris]

Are other browser vendors interested in this and has it gotten a more wide review?

[torgo]

Hi @clelland - could you briefly let us know what the latest status is on this and how the TAG can best provide value here?

[clelland]

Hi @torgo,

Regarding the spec and explainer:

• As mentioned in previous comments, the spec and explainer have both been updated since March, to incorporate the comments from TAG. (I should still address the comments in Feature Policy: Document Policies #408 (comment) specifically).
• The requires-acknowledgment bits have been removed
• The special "no-" syntax has been replaced with standard structured-field boolean False syntax.

Regarding implementation status:

• Chrome has shipped support for just the Document-Policy header, to provide an document-level opt-out mechanism for Scroll-to-text-fragment.
• Chrome is considering using Document Policy to provide a similar opt-out for use of sync-xhr and document-domain, hopefully as a path to eventual deprecation of those features.

Regarding interest:

• There has been discussion in the security community about using Document Policy as a means of lowering usage of security-negative features on the web platform, by making them opt-in. (See https://cloud.arturjanc.com/secweb-2020.pdf)
• There is interest, but not interest, from Mozilla, on both Document Policy and its use for sync-xhr. See MSP, XHR and comments here.

For TAG:
Despite Chrome shipping the initial header, there are still some outstanding issues that I would love TAG feedback on. Roughly in order of importance:

• We've deliberately not shipped the negotiation mechanism; I'm a bit concerned that "policy" is a very generic term to use for the attribute, and would like confirmation that it's a good choice before ossifying it.
• I'm pretty convinced that the mechanism, based on CSP-embedded-enforcement, is sound, but it would be good to get TAG's opinion on that as well.
• There is an open question as to whether a JS API would be a good idea for introspecting the active policy.
• There are also questions about how an enum type should work with required policies; I haven't written those down yet, but essentially, it seems easy for a single document to specify its configuration as a single value from an enumerated set of tokens. It is much harder to provide a generic mechanism to state requirements on a document about allowed enum values. In some cases, there may be a strict linear ordering between values, but in other cases, the relationship may not be so clear. I'm happy to expand on that if it's useful, or maybe the best thing is to remove all mention of enums from the spec right now and reintroduce them later when there are actual use cases.

[torgo]

Thanks @clelland we are taking a look at the questions you raised and will endevour to get some thoughts back to you this week.

[cynthia]

There is an open question as to whether a JS API would be a good idea for introspecting the active policy.

Since there is already a permissions API, as long as the naming (of the permissions being queried) is consistent it feels like extending functionality that is missing on that end is more sensible. (if there is any - if it's just for querying then that's already covered?)

(Also noticed the same point was brought up in the issue - should I continue there?)

[torgo]

Regarding the naming - we've discussed in breakout and we don't have a better idea. However, we agree the current naming is not very self-descriptive and therefore could be confusing to developers who want to figure out what this does and how they can use this (though it does follow on from the header). We recommend you do some user-research with developers - explaining what it is and getting feedback. Regarding the mechanism, we don't see any issues with the CSP-based approach.

[cynthia]

There are also questions about how an enum type should work with required policies;
...
maybe the best thing is to remove all mention of enums from the spec right now and reintroduce them later when there are actual use cases.

This sounds like a reasonable plan forward. (We are a bit afraid of having a mechanism that doesn't cover a use case when we actually have one - we have made these mistakes in the past.)

[clelland]

Thanks for the feedback!

Since there is already a permissions API, as long as the naming (of the permissions being queried) is consistent it feels like extending functionality that is missing on that end is more sensible. (if there is any - if it's just for querying then that's already covered?)

(Also noticed the same point was brought up in the issue - should I continue there?)

This sounds more appropriate for Permissions Policy (where the point was definitely brought up) -- the features covered by that mechanism are mostly suitable for inclusion in permissions.query.

The configuration space of Document Policy features may be more complex, involving at a minimum floats, ints and bools for a given configuration point. An API would probably answer questions like "what was the (minimum) required policy on this document?", "what is the current policy for this configuration point?", "If I create an iframe like this, what will its required policy be?" -- I don't know if the permissions API is suited for that.

Regarding the naming - we've discussed in breakout and we don't have a better idea. However, we agree the current naming is not very self-descriptive and therefore could be confusing to developers who want to figure out what this does and how they can use this (though it does follow on from the header). We recommend you do some user-research with developers - explaining what it is and getting feedback.

I'll see what I can do along those lines, thanks!

Regarding the mechanism, we don't see any issues with the CSP-based approach.

That's great to hear 😄

This sounds like a reasonable plan forward. (We are a bit afraid of having a mechanism that doesn't cover a use case when we actually have one - we have made these mistakes in the past.)

Sounds good, thanks 👍 I'll see about removing that from the spec until there is a clear use case.

[cynthia]

Thanks for taking the time to discuss this with us! We'll close this for now and revisit when the spec is closer to it's final shape.