Content Security Policy (CSP)

[ematipico]

• Accepted Date: 2025-04-02
• Reference Issues/Discussions: Do not force 'unsafe-inline' for astro component scripts #377
• Author: @gjdev
• Champion(s): @ematipico
• Implementation PR:

Summary

Add a new feature that allows Astro assets, mainly scripts and styles, to support Content Security Policy.

Background & Motivation

When creating astro components/layouts with client side scripts, as documented here: docs.astro.build/en/core-concepts/astro-components, the processed+bundled scripts are rendered inline in the html of the page, during a production build.
This forces the use of a CSP with script-src: 'unsafe-inline', which is called unsafe for obvious reasons.

It would be nice to have an astro config option, or a configration attribute for script tags, to instruct astro to create a javascript file for the bundled javascript, and then reference that file via a src attribute on the rendered script tag, instead of inlining the bundled javascript.

(During devlopment npm run dev the processed javascript is actually linked via a script src already, making dev builds and production builds behave differently with some content security policies).

The same could be done for stylesheets, making it configurable whether the stylesheet is inlined in the page (requiring style-src unsafe-inline), or included via a link.

Goals

• Support at least one solution (nonce, hash, etc.) that would support CSP.
• Allow Astro scripts (client islands, server islands, view transitions, etc.) and Astro styles to work out of the box.
• Update adapters to support the feature, if needed.
• Make the feature opt-in, even when it's outside of experimental.

Non-Goals

• Provide multiple solutions to fix the same problem
• Support for third-party scripts dynamically imported by users e.g. document.createElement("script"), import("https://path.to/script.js");
• Support for third-party styles dynamically imported by users.
• Performance. Users and authors are willing to overlook possible performance drawbacks in order to increase security.

[ematipico]

There are mostly two solutions that we are looking at:

• nonce Response header
• hashes

The nonce header solution

The servrer must create a completely new nonce header at each request (it can't be predictable), and this header needs to be used inside the rendered pages. Example:

function content(nonce) {
  return `
    <script nonce="${nonce}" src="/main.js"></script>
    <script nonce="${nonce}">console.log("hello!");</script>
    <h1>Hello world</h1> 
    `;
}

app.get("/", (req, res) => {
  const nonce = crypto.randomUUID();
  res.setHeader("Content-Security-Policy", `script-src 'nonce-${nonce}'`);
  res.send(content(nonce));
});

The hashes solution

The server must send an hash for each script and style present in the page. The hash is generated from the content of each <script> and <style> tag. Example:

const hash1 = "sha256-ex2O7MWOzfczthhKm6azheryNVoERSFrPrdvxRtP8DI=";
const hash2 = "sha256-H/eahVJiG1zBXPQyXX0V6oaxkfiBdmanvfG9eZWSuEc=";

const csp = `script-src '${hash1}' '${hash2}'`;
const content = `
  <script src="./main.js" integrity="${hash2}"></script>
  <script>console.log("hello!");</script>
    <h1>Hello world</h1> 
    `;

app.get("/", (req, res) => {
  res.setHeader("Content-Security-Policy", csp);
  res.send(content);
});

Pros and cons of the two solutions inside Astro

	nonce	hashes
SSG	Very limited support. Requires an adapter with an edge function, and modify all the HTML to add the nonce attribute. Static hosts can't support it.	Can work out-of-box with a <meta> tag
SSR	Supported. Requires an adapter.	Supported. Can use an adapter to enhance CSP.
Dynamic scripts	Covered natively. Astro can pass the value of nonce	Not covered nativily. The user must supplement their hashes.
Dynamic styles	Covered natively. Astro can pass the value of nonce	Not covered nativily. The user must supplement their hashes.
Implementation implications	Probably none in core. Implement a static adapter for adapters. Very easy to achieve	Might not require any work in the adapters. Requires a lot of work in core, as it touches many parts of the framework: islands (client and server), view transitions, etc. Requires some harness for future client scripts/styles.
Testing	Adapter level. Probably very brittle/limited. It might require hosted tests.	Achievable, but it still requires some new testing strategy to test pure SSG.

[dev-nicolaos]

I started using Astro when it was more focused on static websites and prefer to keep projects statically rendered until the requirements require otherwise, so I'm heavily in favor of a solution that supports SSG. I do see the how that could be burdensome for projects that generate dynamic scripts and styles though. I wonder if its possible to support both solutions and let the developer pick?

[ematipico]

It's currently non-goal, and the hashes solution seems to be a solution that would cover the majority of use cases.

However, we plan to provide some utilities where users can register their scripts and styles that need to import dynamically

[aivLuk]

Hey! Thanks for looking into this. One question. I see this solution adds nonces/hashes to inline scripts that we write in the code. What about inline scripts that astro injects itself for the client directives? These need to comply with CSP too. Like this one for example:
<script>(()=>{var e=async t=>{await(await t())()};(self.Astro||(self.Astro={})).only=e;window.dispatchEvent(new Event("astro:only”));})();</script>

[ematipico]

It's part of the goals

Allow Astro scripts (client islands, server islands, view transitions, etc.) and Astro styles to work out of the box

All scripts and styles emitted by Astro must comply

[Marocco2]

Hey! Thanks for looking into this. One question. I see this solution adds nonces/hashes to inline scripts that we write in the code. What about inline scripts that astro injects itself for the client directives? These need to comply with CSP too. Like this one for example:
<script>(()=>{var e=async t=>{await(await t())()};(self.Astro||(self.Astro={})).only=e;window.dispatchEvent(new Event("astro:only”));})();</script>

Using trusted-types would be a solution

[ematipico]

Closing in favour of #1168