CSP without unsafe-inline & docusaurus-theme-classic

[bcaller]

docusaurus-theme-classic injects a script tag into the page.

This makes it difficult to apply a Content Security Policy without script-src 'unsafe-inline'. Is there a recommended way around this?

Things that could help are switching the injected tag into an external script file, or SHA384 hashing the script content on build and adding the hash to the CSP.

Anyway, just wondered if anyone has solved this before. There doesn't seem to be a nice plugin hook that would work both in dev server and in production builds where the script content can be inspected.

[slorber]

This script is inline because we need it to execute asap to avoid flash of unstyled content, notably reading the dark/light mode from localStorage before the UI prints anything.

If we moved this to an external resource, we'd have to block and to wait for it to download before the user sees anything, otherwise the UI would maybe first display the bad theme, and then the theme "gets fixed", producing bad blinking UX. For performance reasons it's much better to inline such scripts, and many other frameworks do the same. It's not just about the theme, but the announcement bar and the classes injected through data attributes too. All this needs to run as soon as possible.

I'm not an expert in CSP. Why do you need that "unsafe-inline" in the first place? Can you share an example of how to have an inline script, and yet make it pass your requirements?

[DougReeder]

I would say the key problem with the workarounds mentioned in this thread, is that they're all fragile — they require developers to understand how Docusaurus is doing things differently than a standard static site, and why one can't use a CSP without any "unsafe" directives. If Docusaurus is a major part of one's work, that's not a problem. But if the Docusaurus site is ancillary to one's main work, the differences are tribal knowledge, that requires extra effort.

Our team, for one, would like to have a configuration setting for Docusaurus, where we could use a CSP without any "unsafe" directives, even at the expense of some performance.

[slorber]

@DougReeder, what makes this fragile exactly?

they require developers to understand how Docusaurus is doing things differently than a standard static site

We don't! Look at all the other static sites that have a theme toggle feature; they all have an inline script to manage FOUC: Starlight, VitePress, Rspress...

That's a requirement for all sites using a theme, with both SSG and SSR.

But if the Docusaurus site is ancillary to one's main work, the differences are tribal knowledge, that requires extra effort.

I agree that it would be better if we could make your life easier.

However:

• If you need a CSP in the first place, you probably know what you are doing and how difficult it can be to create a good one
• You probably know that we can not set the Content-Security-Policy header for you. At best we can only give you a list of script hashes that you set yourself
• The solution to extract script hashes is not Docusaurus-specific, it's something that would be generic and work on any static deployment using inline scripts

As of today, to host our Docusaurus website with a stricter CSP, we would need that header:

"Content-Security-Policy": "script-src 'self' https://www.googletagmanager.com 'sha256-uxBt6cn5c9B9jugocyGCxjRMZxNHC6P+S78Fl6gpmj8=' 'sha256-LF3Z8n3CoT6+StShrU4zdlpOt7gwSfDDuFOnesPW+JI=' 'sha256-a5KkiGzhW4/G+XcbohgQNGbIt/2pk1dJoK6WLvubGtU='"

I tried that using our serve-handler package (used by docusaurus serve) and it seems works fine with the following config:

      headers: [
        {
          "source" : "**/*",
          "headers" : [{
            "key" : "Content-Security-Policy",
            "value" : "script-src 'self' https://www.googletagmanager.com 'sha256-uxBt6cn5c9B9jugocyGCxjRMZxNHC6P+S78Fl6gpmj8=' 'sha256-LF3Z8n3CoT6+StShrU4zdlpOt7gwSfDDuFOnesPW+JI=' 'sha256-a5KkiGzhW4/G+XcbohgQNGbIt/2pk1dJoK6WLvubGtU='"
          }]
        }
      ]

At best, we could give you the 3 hashes, printing them somewhere or emitting a build/csp.json file that you could have to use to configure your host headers (we can't do this for you).

Manual solution

I understood this is not what you want to hear, but there's already a convenient way to retrieve those hashes manually: just open the Chrome console with a strict CSP and see the error messages:

If your company cares about strict CSP, they probably have observability tools like Sentry to report when such errors occur in staging/production, too. Or that could be part of your upgrade process.

Generic solution.

If manual extraction is not an option, the solution to automate this CSP extraction would not be Docusaurus-specific.

If you trust us that the website/build output is secure, you would only have to extract the hashes from the static files through a generic solution, one that would work for any static deployment as well.

npm run docusaurus build
npm run extract-csp-hashes ./build ./build/csp.json

For a typical Docusaurus website, all the problematic inline scripts are likely in build/index.html, so you could even optimize and only process that specific file. Keep in mind, we don't have control over inline scripts defined by third-party plugins, so we can't strictly guarantee that.

npm run docusaurus build
npm run extract-csp-hashes ./build/index.html ./build/csp.json

Now, are you asking us to build that generic solution for the whole SSG community?

That's something we could consider, but maybe it has already been built in other communities?

False sense of security?

The goal of CSP is to tighten the security of your site, not simply to blindly comply with a meaningless corporate security policy.

As a static site, you probably want to ensure that your SSG pipeline is not compromised. For example, you want to prevent any first/third-party Docusaurus plugin from injecting a malicious JS script.

Reviewing inline scripts to prevent such issues can be seen as a feature and good security practice, not a bug. If you fully automate the process, then what prevents a third-party plugin from running a Bitcoin miner on your site's visitors after any npm upgrade?

If you automate the process, you just add a potentially harmful hash to your header without even knowing.

That is why it is important to understand what you want to protect yourself from in the first place with this CSP. A supply chain risk? A compromised host server? Something else?

[slorber]

Our team, for one, would like to have a configuration setting for Docusaurus, where we could use a CSP without any "unsafe" directives, even at the expense of some performance.

If that helps, we could add an option to our classic theme to emit the inline script to a separate file.

However, this would only work on a per-plugin basis, and we can't force third-party plugin authors to do the same and prevent all inline scripts.

For example, our gtag plugin currently uses an inline script too, as shown on the gtag installation guide: https://developers.google.com/tag-platform/gtagjs

[DougReeder]

FWIW, light-dark theming can now be done with the light-dark() CSS function

I'm coming from using 11ty, which does not require CSP unsafe- directives or hashes (and, yes, can't do many of the things Docusaurus can do). We inherited Docusaurus from a previous team — it appears that Docusaurus is a heavier-weight tool than we want to support.

Thanks for the clarification!

[slorber]

FWIW, light-dark theming can now be done with the light-dark() CSS function

This is not widely supported, and doesn't permit implementing a theme toggle button. It only follows the theme of your OS.

To implement a theme toggle button and have this CSS function react to the change, this would require another proposal to land in the spec: https://github.com/WICG/web-preferences-api

---

I'm coming from using 11ty, which does not require CSP unsafe- directives or hashes (and, yes, can't do many of the things Docusaurus can do).

Show me an Eleventy website with a theme toggle that doesn't have an inline script tag. If they don't have it, they have a flash of bad theme on load, not much better.

These sites have inline scripts:

• https://www.11ty.dev
• https://eleventy-libdoc.netlify.app/

If you compare Docusaurus with the classic theme VS an empty/homemade Eleventy site, that's not fair. You can also implement your own custom theme in Docusaurus and have no inline script if you really want to.

---

We inherited Docusaurus from a previous team — it appears that Docusaurus is a heavier-weight tool than we want to support.

Docusaurus builds a React SPA, so it is indeed heavier than MPAs by design. There are pros and cons to each approach.

We are also opinionated toward docs/blog/pages use case, and our theme provides a theme switch and other features requiring inline scripts to work well.

Those features are not strictly mandatory and we could eventually give an option to disable them on the classic theme.