Correct CSP source values

[wbamberg]

This PR fixes a few errors in the documentation of CSP directive syntax.

• the page at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources says that the sandbox directive uses the source expression syntax, but I don't think it does: I think this directive just uses keyword values.
• the page at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources also says that the base-uri, form-action, and frame-ancestors directives use the source expression syntax, which is half true: they can use a subset of it
• the documentation says that 'none' is one of the source expression values, which implies that you can combine 'none' and other source expression values, but you can't: if you have 'none', it stands alone: https://w3c.github.io/webappsec-csp/#grammardef-serialized-source-list.
• nonces are not only for inline scripts. There's a lot more we could/should update around nonces but I'm not going there yet.

The page for frame-ancestors does not point to https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources, instead redefining the values. I have left this as it is for now, because the definition for this directive does use a different type (https://w3c.github.io/webappsec-csp/#directive-frame-ancestors) although it seems to be functionally identical. I think we should update this to point to the "sources" page, but before doing that I want to check there isn't some subtle reason why the syntax is redefined for this directive.

The changes are quite repetitive for the directives pages: I changed/corrected the syntax and removed the ### Sources heading, as it seemed easier to talk about 'none' without it.

In https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources I removed the list of fetch directives, since we already have that in https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#fetch_directives, so that's just 2 places we have to maintain it.

[github-actions]

Preview URLs (22 pages)

• /en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_security_policy
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/base-uri
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/child-src
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/connect-src
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/default-src
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/font-src
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/form-action
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-src
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/img-src
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/manifest-src
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/media-src
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/object-src
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/prefetch-src
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src-attr
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src-elem
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src-attr
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src-elem
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/worker-src
• /en-US/docs/Web/HTTP/Headers/Content-Security-Policy

(comment last updated: 2024-10-02 18:55:49)

[hamishwillee]

Yes/agree to everything you said in the introduction - I wandered the same path through the spec you must have and agree.

Not sure about the pattern you adopted though. I would have preferred the more familiar DL list approach (comment above).
A few other minor points which you might choose to ignore, but I think we could look at while we're here - specifically, in all the directive docs we refer to the sources, but you don't get the idea that these are URL patterns or keywords until you get down to the examples. That seems a bit wrong.

[wbamberg]

Thanks for your comments Hamish, very helpful. This is ready for another round.

[hamishwillee]

Thanks @wbamberg - whole thing much better. Merging.

Two slight niggles since they are on my mind, is that when you're on the Source page,

• we refer that they are used by fetch directives, and those are listed in the sidebar - but if you click the link you get taken to a completely different context that does not include the directives. So if you aren't sure about what directives are you'll be out of context. We might have listed a couple here (i.e. "fetch directives such as ...")
• The sources page is very abstract - showing an example using one of them in this context might have been useful.

I'm just niggling, as you say, so much that might be done around this area.

[wbamberg]

Thanks @wbamberg - whole thing much better. Merging.

Two slight niggles since they are on my mind, is that when you're on the Source page,

• we refer that they are used by fetch directives, and those are listed in the sidebar - but if you click the link you get taken to a completely different context that does not include the directives. So if you aren't sure about what directives are you'll be out of context. We might have listed a couple here (i.e. "fetch directives such as ...")

• The sources page is very abstract - showing an example using one of them in this context might have been useful.

I'm just niggling, as you say, so much that might be done around this area.

Happy for you to file issues for these two. I think nav/IA for the CSP docs is a bit tricky though. It might be better to subsume the "Sources" page inside the CSP header page - currently "Sources" appears under "CSP directives" (and has that page type) but it isn't a directive of course.

[hamishwillee]

It might be better to subsume the "Sources" page inside the CSP header page - currently "Sources" appears under "CSP directives" (and has that page type) but it isn't a directive of course.

I was going to say "no, that's a huge page and this would make it even more monolithic. "
However on reflection I do think it would be significantly better because I find the sources page to be so isolated from its context.

My reasoning is that the page already has a values section: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#values . That section makes sense to me because you have the context and examples. The additional information that you'd add by merging would not make this much bigger.

[wbamberg]

It might be better to subsume the "Sources" page inside the CSP header page - currently "Sources" appears under "CSP directives" (and has that page type) but it isn't a directive of course.

I was going to say "no, that's a huge page and this would make it even more monolithic. " However on reflection I do think it would be significantly better because I find the sources page to be so isolated from its context.

My reasoning is that the page already has a values section: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#values . That section makes sense to me because you have the context and examples. The additional information that you'd add by merging would not make this much bigger.

Having spent some time with this "source values" page, another option, which you might not like but bear with me.

The history of this page is something like: back in the days of the {{page}} macro:

• the script-src* and style-src* pages transcluded their content from default-src
• the other directives transcluded their content from connect-src

Then through #5732 and #11185, we ended up factoring the source value syntax into a single separate page.

Although I advocated for this at the time, I didn't understand directive syntax very well and now I wonder if this was a mistake.

In particular, the script-src* and style-src* directives are the only ones that support the keywords (except 'self'). So in all cases like connect-src, font-src etc, people have to read this page and mentally exclude all those keywords, making it more complicated than it needs to be.

Apart from that, there are smaller differences, to accommodate which means we end up being quite elliptical or misleading in our language. For instance, in the doc for <host-source> we say things like "Matches all attempts to load ..." but with base-uri we're not loading anything.

Maybe we should after all duplicate this syntax in all the directives. I think we could also streamline some of the existing items here (e.g. I think the list of schemes at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#scheme-source is odd - are these the only possible values? I don't think so, so why are just these ones listed? Similarly most of https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#host-source is taken up with a list of examples, maybe we could find a single place to have some examples?).

[hamishwillee]

@wbamberg Re ^^^ #35947 (comment)

Either subsuming the source page into the header page or splitting the sources into the directive pages would vastly improve the context problem.

For readers duplicating would easily be the best solution if we can live with the duplication/maintenance.

Might we consider reverting to the original pattern for script-src* and style-src* pages default-src, but linking rather than transcluding?
In other words

• move all of this source doc to default-src and link to that from script-src* and style-src* pages.
• Duplicate the host-source, scheme source, self for all the other cases, fixing up as needed to be specific.

I think the list of schemes at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#scheme-source is odd - are these the only possible values? I don't think so, so why are just these ones listed?

Yes. That's the same as any other list case - we either need to cut this back and link to or provide info about the comprehensive support, or provide a full list.

Similarly most of https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#host-source is taken up with a list of examples, maybe we could find a single place to have some examples?).

I think I'd cut the examples back to 2 say, and link to the default source for more?

[wbamberg]

@wbamberg Re ^^^ #35947 (comment)

Either subsuming the source page into the header page or splitting the sources into the directive pages would vastly improve the context problem.

For readers duplicating would easily be the best solution if we can live with the duplication/maintenance.

Might we consider reverting to the original pattern for script-src* and style-src* pages default-src, but linking rather than transcluding? In other words

* move all of this source doc to `default-src` and **link** to that from `script-src*` and `style-src*` pages.

* Duplicate the host-source, scheme source, self for all the other cases, fixing up as needed to be specific.

This would effectively revert the fix for #5286, although we could fix that in the prose by talking about "scripts or styles" although that's kind of what I meant about "elliptical and misleading language". But maybe that's a better tradeoff that full duplication.

Main thing I think is for non-script and style directives to omit the keyword values, as this adds a lot of stuff to ignore.

I think the list of schemes at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#scheme-source is odd - are these the only possible values? I don't think so, so why are just these ones listed?

Yes. That's the same as any other list case - we either need to cut this back and link to or provide info about the comprehensive support, or provide a full list.

Exactly. Presenting things a list always seems to carry the expectation that it will be exhaustive. Better IMO to give the commonest examples and warn people about data:.

Maybe I will repurpose #36198 to try out some version of this plan.

[hamishwillee]

Maybe I will repurpose #36198 to try out some version of this plan.

Sure. I think trying a minimal version and getting feedback would be good - i.e. update default-src and link from scrip-src. That would tell us if this is acceptable cross linking.