withastro · sarah11918 · Jun 3, 2025 · May 21, 2025 · May 21, 2025 · May 23, 2025
diff --git a/astro.sidebar.ts b/astro.sidebar.ts
@@ -142,6 +142,7 @@ export const sidebar = [
 					'reference/experimental-flags/content-intellisense',
 					'reference/experimental-flags/preserve-scripts-order',
 					'reference/experimental-flags/heading-id-compat',
+					'reference/experimental-flags/csp',
 				],
 			}),
 			'reference/legacy-flags',

diff --git a/src/content/docs/en/reference/experimental-flags/csp.mdx b/src/content/docs/en/reference/experimental-flags/csp.mdx
@@ -0,0 +1,379 @@
+---
+title: Experimental Content Security Policy
+sidebar:
+  label: Content Security Policy
+i18nReady: true
+tableOfContents:
+  minHeadingLevel: 2
+  maxHeadingLevel: 6
+---
+
+import Since from '~/components/Since.astro'
+
+<p>
+
+  **Type:** `boolean | Csp`<br />
+  **Default:** `false`<br />
+  <Since v="5.9.0" />
+</p>
+
+Enables support for [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) to help minimize certain types of security threats by controlling which resources a document is allowed to load. This provides additional protection against [cross-site scripting (XSS)](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting) attacks.
+
+Enabling this feature adds additional security to Astro's handling of processed and bundled scripts and styles by default, and is further configurable for more control over these, and additional, content types.
+
+To enable this feature, add the experimental flag in your Astro config:
+
+```js title="astro.config.mjs" ins={4-6}
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+    experimental: {
+      csp: true
+    }
+});
+```
+
+When enabled, Astro will add a `<meta>` element inside the `<head>` element of each page.
+
+This element will have the `http-equiv="content-security-policy"` attribute, and the `content` attribute will provide values for the `script-src` and `style-src` [directives](#directives) based on the script and styles used in the page.
+
+```html
+<head>
+    <meta 
+        http-equiv="content-security-policy" 
+        content="
+            script-src 'self' 'sha256-somehash'; 
+            style-src:'self' 'sha256-somehash'"
+   >
+</head>
+```
+
+## Configuration
+
+You can further customize the `<meta>` element by enabling this feature with a configuration object that includes additional options.
+
+### `algorithm`
+
+<p>
+
+**Type:** `'SHA-256' | 'SHA-512' | 'SHA-384' `<br />
+**Default:** `'SHA-256'`<br />
+<Since v="5.9.0" />
+</p>
+
+The [hash function](https://developer.mozilla.org/en-US/docs/Glossary/Hash_function) to use to generate the hashes of the styles and scripts.
+
+
+```js title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+    experimental: {
+      csp: {
+        algorithm: 'SHA-512'
+      }
+    }
+});
+```
+
+### `directives`
+
+<p>
+
+**Type:** `[]` <br />
+**Default:** `[]`<br />
+<Since v="5.9.0" />
+</p>
+
+A list of [CSP directives](https://content-security-policy.com/#directive) that defines valid sources for specific content types.
+
+While Astro needs to control the `script-src` and `style-src` directives, it is possible to control other CSP directives using the `csp.directives` field. These directives are added to all pages. It accepts a list of type-safe directives:
+
+```js title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+    experimental: {
+      csp: {
+        directives: [
+          "default-src 'self'",
+          "image-src 'self' 'https://images.cdn.example.com'"
+        ]
+      }
+    }
+});
+```
+
+After the build, the `<meta>` element will add your directives into the `content` value alongside Astro's default directives:
+
+```html
+<meta
+    http-equiv="content-security-policy"
+    content="
+        default-src 'self'; 
+        image-src 'self' 'https://images.cdn.example.com';
+        script-src 'self' 'sha256-somehash'; style-src:'self' 'sha256-somehash'
+    "
+>
+```
+
+### `stylesDirective` and `scriptsDirective`
+
+<p>
+
+**Type:** `CspDirective` <br />
+**Default:** `{}`<br />
+<Since v="5.9.0" />
+</p>
+
+Configuration objects that allow you to override the default sources for the `style-src` and `script-src` directives with the [`resources`](#resources) property, or to provide additional [hashes](#hashes) to be rendered.
+
+These properties are added to all pages and **completeley override Astro's default resources**, not add to them. Therefore, you must explicitly specify any default values that you want to be included.
+
+#### `resources`
+
+<p>
+
+**Type:** `[]` <br />
+**Default:** `[]`<br />
+<Since v="5.9.0" />
+</p>
+
+A list of valid sources for the `script-src` and `style-src` directives.
+
+The `script-src` and `style-src` directives are handled by Astro by default, and use the `'self'` resource. This means that scripts and styles can only be downloaded by the current host (usually the current website).
+
+To override the default source, you can provide a list of resources instead. This will not include `'self'` by default, and must be included in this list if you wish to keep it. These resources are added to all pages.
+
+```js title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+    experimental: {
+      csp: {
+        stylesDirective: {
+          resources: [
+            "self",
+            "https://styles.cdn.example.com"
+          ]
+        },
+        scriptsDirective: {
+          resources: [
+            "https://cdn.example.com"
+          ]
+        }
+      }
+    }
+});
+```
+
+After the build, the `<meta>` element will instead apply your sources to the `style-src` and `script-src` directives:
+
+```html
+<head>
+    <meta 
+        http-equiv="content-security-policy" 
+        content="
+            script-src 'https://cdn.example.com' 'sha256-somehash'; 
+            style-src: 'self' 'https://styles.cdn.example.com' 'sha256-somehash'"
+    >
+</head>
+```
+
+#### `hashes`
+
+<p>
+
+**Type:** `[]` <br />
+**Default:** `[]`<br />
+<Since v="5.9.0" />
+</p>
+
+A list of additional hashes to be rendered.
+
+If you have external scripts or styles that aren't generated by Astro, or inline scripts, this configuration option allows you to provide additional hashes to be rendered. 
+
+You must provide hashes that start with `sha384-`, `sha512-` or `sha256-`. Other values will cause a validation error. These hashes are added to all pages.
+
+
+```js title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+    experimental: {
+      csp: {
+        stylesDirective: {
+          hashes: [
+            "sha384-styleHash",
+            "sha512-styleHash",
+            "sha256-styleHash"
+          ]
+        },
+        scriptsDirective: {
+          hashes: [
+            "sha384-scriptHash",
+            "sha512-scriptHash",
+            "sha256-scriptHash"
+          ]
+        }
+      }
+    }
+});
+```
+
+After the build, the `<meta>` element will include your additional hashes in the `script-src` and `style-src` directives:
+
+```html
+<meta
+    http-equiv="content-security-policy"
+    content="
+        script-src 'self' 'sha256-generatedByAstro' 'sha384-scriptHash' 'sha512-scriptHash' 'sha256-scriptHash'; 
+        style-src:'self' 'sha256-generatedByAstro' 'sha384-styleHash' 'sha512-styleHash' 'sha256-styleHash';
+    "
+>
+```
+
+## Runtime APIs
+
+You can customize the `<meta>` element per page via runtime APIs available from the `Astro` global inside `.astro` component, or the `APIContext` type in endpoints and middleware.
+
+### `addDirective`
+
+<p>
+  **Type:** `(directive: CspDirective) => void`<br />
+  <Since v="5.9.0" />
+</p>
+
+Adds a single directive to the current page. You can call this method multiple times to add additional directives.
+
+```astro
+---
+Astro.addDirective("default-src 'self'");
+Astro.addDirective("img-src 'self' 'https://images.cdn.example.com'");
+---
+```
+
+After the build, the `<meta>` element for this individual page will add your directives to the included `style-src` and `script-src` directives:
+
+```html
+<meta
+    http-equiv="content-security-policy"
+    content="
+        default-src 'self'; 
+        image-src 'self' 'https://images.cdn.example.com';
+        script-src 'self' 'sha256-somehash'; style-src:'self' 'sha256-somehash'
+    "
+>
+```
+
+### `insertStyleResource`
+
+<p>
+  **Type:** `(resource: string) => void`<br />
+  <Since v="5.9.0" />
+</p>
+
+Inserts a new resource to be used for the `style-src` directive.
+
+```astro
+---
+Astro.insertStyleResource("'https://styles.cdn.example.com'");
+---
+```
+
+After the build, the `<meta>` element for this individual page will add your source to the default `style-src` directive:
+
+```html
+<meta
+    http-equiv="content-security-policy"
+    content="
+        script-src 'self' 'sha256-somehash'; style-src: 'https://styles.cdn.example.com' 'sha256-somehash'
+    "
+>
+```
+
+
+### `addStyleHash`
+
+<p>
+  **Type:** `(hash: CspHash) => void`<br />
+  <Since v="5.9.0" />
+</p>
+
+Adds a new hash to the `style-src` directive.
+
+```astro
+---
+Astro.addStyleHash("sha512-styleHash");
+---
+```
+
+After the build, the `<meta>` element for this individual page will add your hash to the default `style-src` directive:
+
+```html
+<meta
+    http-equiv="content-security-policy"
+    content="
+        script-src 'self' 'sha256-somehash'; style-src: 'self' 'sha256-somehash' 'sha512-styleHash'
+    "
+>
+```
+
+
+### `insertScriptResource`
+
+<p>
+  **Type:** `(resource: string) => void`<br />
+  <Since v="5.9.0" />
+</p>
+
+Inserts a new valid source to be used for the `script-src` directive.
+
+
+```astro
+---
+Astro.insertScriptResource("'https://scripts.cdn.example.com'");
+---
+```
+
+After the build, the `<meta>` element for this individual page will add your source to the default `script-src` directive:
+
+```html
+<meta
+    http-equiv="content-security-policy"
+    content="
+        script-src 'https://scripts.cdn.example.com' 'sha256-somehash'; style-src: 'self' 'sha256-somehash'
+    "
+>
+```
+
+### `addScriptHash`
+
+<p>
+  **Type:** `(hash: CspHash) => void`<br />
+  <Since v="5.9.0" />
+</p>
+
+Adds a new hash to the `script-src` directive.
+
+
+```astro
+---
+Astro.addScriptHash("sha512-scriptHash");
+---
+```
+
+After the build, the `<meta>` element for this individual page will add your hash to the default `script-src` directive:
+
+```html
+<meta
+    http-equiv="content-security-policy"
+    content="
+        script-src 'self' 'sha256-somehash' 'sha512-styleHash'; style-src: 'self' 'sha256-somehash'
+    "
+>
+```
+
+:::caution
+Due to the nature of the Vite dev server, this feature isn't supported while working in `dev` mode. Instead, you can test this in your Astro project using `build` and `preview`.
+:::