Document Policy

[clelland]

Request for Mozilla Position on an Emerging Web Specification

• Specification Title: Document Policy

• Specification or proposal URL: Spec, Explainer

• Caniuse.com URL (optional): Not yet

• Bugzilla URL (optional): Not yet

• Mozillians who can provide input (optional): @annevk @martinthomson

Other information

Document Policy arose out of a long series of discussions between Google, Mozilla, and web developers to find a way to extend Feature Policy(#24) to handle different kinds of use cases (sandboxing, restricting your own content without affecting embedded content, promoting best-practices). The eventual consensus was to try to split the new functionality into a separate mechanism, leaving Feature Policy to handle delegation of permissions and similar powerful features. Document Policy is that new mechanism.

There is a lot of background context in these issues:

• Define the scope of feature policy w3c/webappsec-permissions-policy#252
• https://github.com/w3c/webappsec-feature-policy/issues/282
• Dividing features across different types of policies w3c/webappsec-permissions-policy#296
• Architecture discussion: Document Policies w3c/webappsec-permissions-policy#299

Ongoing TAG review is here: w3ctag/design-reviews#408

Chrome is specifically interested in shipping this as the opt-out mechanism for Scroll-to-text(#194), though there are certainly many other use cases.

[martinthomson]

Seems like a reasonable general framework for restricting how embedded content can operate. By declaring constraints and requiring acknowledgment, you can be quite aggressive about what is restricted. The risk is that content doesn't load, but presumably you can test that fairly easily.

It's complicated though. That is where I think we should focus attention. I note that we are also considering a CSP extension in #326, which has similar characteristics.

The assessment of whether an acknowledgment conforms to the rules means that you need to have the browser understand every rule before passing it along. Otherwise it won't know whether it requires acknowledgment, or how to assess whether an acknowledgment is conformant.

The potential for features to require acknowledgment and to grant capabilities means that this is not generically forward-compatible, so there will likely be a need for some way to query what parameters are supported. (The CSP variant says that it's OK to have new rules, but that is because CSP is always restrictive.) If this were phrased strictly in the negative - that is, as a set of restrictions - that would be much simpler to provide forward compatibility (but it would mean not having parameterized directives). This wouldn't be able to grant new capabilities then, but I think that this is better left to other mechanisms, like feature policy.

The overhead imposed by header fields is likely bearable here, but the design should probably be more efficient.

@clelland, did you consider naming this 'embed-policy'? It's shorter.

I'm inclined to say non-harmful at the moment, but there's potential here for this to be worth prototyping if this can be improved (as I expect it will be). Of course, I might have missed something, and would be happy to hear other opinions.

[clelland]

Thanks, @martinthomson -- let me see if I can address at least some of your points:

On the relation to CSPEE: thanks for calling that out, the similarity there is deliberate. If we are to have multiple mechanisms by which the user agent can refuse to embed one document inside of another, then they should all behave the same way. The <iframe foo=bar> / Require-Foo: bar / Foo: bar header dance seems like a sensible pattern to follow here.

The issue of whether features require acknowledgment or not, and how that affects compatibility, is tricky. One hard-line option which I think @annevk suggested originally, would be that only the existing sandbox features don't require explicit acknowledgement, while all other features do. I suspect that might go a bit too far, as there could certainly be a whole class of feature which can, like the sandbox features, be generally seen as safe to impose without acknowledgment.

If a particular browser doesn't understand a rule, then it cannot enforce a restriction in any case, so I would suggest that the directive not form part of any required policy, so it would not be passed along to subframes as a requirement. I don't think that there is any other reasonable way of handling that situation, which doesn't quickly turn into "the browser reflects arbitrary data from one document into all subframe requests". That probably means that we need to carefully consider the effects of introducing new configuration points, when not all browsers will understand them, but that's the same consideration we have to give to other new web APIs and behaviors. Also, I agree that granting capabilities is best left to feature policy.

Q: Why does making this restrictive-only preclude parameterized directives? There are several features which can take numeric params, where the default is effectively 'unlimited', such as the image compression or downscaling policies.

On naming: I'm more than happy to bikeshed names -- the TAG discussion had some thoughts on names, and might be a better venue for that topic. We had briefly considered something like 'embed-policy', the concern was that a primary use case for this mechanism is to just set your policy in your headers, to configure your own documents, without ever forcing restrictions on embedded content. (In the same way that the existence of CSPEE doesn't mean that CSP is about embedding in general)