feat: Add documentation for experimentalCspAllowList and CSP information

[pgoforth]

Documentation for stripCspDirectives experimentalCspAllowList feature

[netlify]

👷 Deploy request for cypress-docs pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	418592c

[CLAassistant]

All committers have signed the CLA.

[AtofStryker]

NOTE: we need to update the target branch to the next release and we also need to deploy target links during the release due to https://github.com/cypress-io/cypress/pull/26483/files#diff-9fde1fb2f7eaba5ea49b585c811461495bfbba88e614e900a96863ecfe6b980aR3059

[MikeMcC399]

One typo commented on in-line.

[pgoforth]

@MikeMcC399 Thanks for reviewing. Fixed the typo.

[MikeMcC399]

Typos are fixed. Thanks!

[emilyrohrbough]

Can you add a note that this experiment is not compatible with the experimentalSourceRewriting experiment?

[pgoforth]

@emilyrohrbough This should still be compatible in certain scenarios. Can we say may not be compatible?

[emilyrohrbough]

@pgoforth @AtofStryker had flagged this as a possible risk / scenario where this configuration opt-in may fail.

• JavaScript is re-written - PR does not handle this scenario
  • What we do know: Similar to SRI tags, nonces/shas need to be provided on inline-scripts CSP into the document before the actual inline script is fetched. If the inline script is rewritten by the proxy, the nonce will work fine, but the sha will break and the script will not execute. This is why when experimentalModifyObstructiveThirdPartyCode is enabled, integrity tags are stripped out of HTML documents as it is really difficult to inform the browser of the SHA to expect before the resource is rewritten and SHAed on the server (a bit of the chicken or the egg problem)

Mind adding a blurb stating if there are issues and this may be an known issue

[emilyrohrbough]

@pgoforth I didn't see any code changes in the rewriting that would indicate this wouldn't cause issues with the nonce injection. Did you test any by chance?

[pgoforth]

@emilyrohrbough Nonce injection is completely independent of SHA hashing. They are handled differently through CSP.

• A SHA hash is an inline validation against the script that gets downloaded and executed. If the version downloaded does not match the SHA hash, the script is not executed.
• A nonce value is randomly generated at runtime and does not rely on the file hash at all.

So even if Cypress made inline changes to a script, the nonce would still pass CSP validation. We are generating a nonce for inline script injections, but are currently not generating a nonce for scripts that have been modified by Cypress. experimentalSourceRewriting does not trigger a CSP violation by default unless a SHA is used on the script node in question. Therefore, allowing CSP headers is unlikely to cause a the source rewrite code to fail CSP unless there are already specific directive values in place that validate against those scripts. That's why I said it may be an issue, because it's totally dependent on the original CSP headers that Cypress intercepts.

Edit:
I think I was being unclear on re-reading what I've written. SRI integrity attributes do not function the same way CSP nonce attributes do. They are mutually exclusive. Adding a nonce after already removing the integrity attribute would be moot. The CSP headers that affect rewrites are 'trusted-types' and 'require-trusted-types-for', which we will ALWAYS strip.

[AtofStryker]

the main issue with SHA inline scripts is if the script is rewritten and the sha doesnt match the actual hash. But I think it might be OK to say it may work with experimentalSourceRewriting because it is going to depend on the context of what is rewritten, similar to how things work now with the regex rewriter

[pgoforth]

We can probably specify the scenario (using '<hash-algorithm>-<base64-value>' inside a CSP directive) as that's the only place it could trip against experimentalSourceRewriting or experimentalModifyObstructiveThirdPartyCode/modifyObstructiveCode.

I also genuinely feel like that is a problem that can be solved given our ability to modify individual directive values. We would just need to match the original SHA in the CSP directive with the one we replaced, and swap the value for the replacement. Outside of the scope of this PR, but definitely doable in the near future.

[emilyrohrbough]

@pgoforth @AtofStryker had flagged this as a possible risk / scenario where this configuration opt-in may fail.

• JavaScript is re-written - PR does not handle this scenario
  • What we do know: Similar to SRI tags, nonces/shas need to be provided on inline-scripts CSP into the document before the actual inline script is fetched. If the inline script is rewritten by the proxy, the nonce will work fine, but the sha will break and the script will not execute. This is why when experimentalModifyObstructiveThirdPartyCode is enabled, integrity tags are stripped out of HTML documents as it is really difficult to inform the browser of the SHA to expect before the resource is rewritten and SHAed on the server (a bit of the chicken or the egg problem)

Mind adding a blurb stating if there are issues and this may be an known issue

[pgoforth]

@emilyrohrbough I've addressed your comments and added a blurb about potential incompatibility with modifyObstructiveCode and experimentalSourceRewriting. Please have another look and make sure I didn't forget anything.

[pgoforth]

@emilyrohrbough Comments addressed.