Skip to content

feat: experimental CSP docs #11736

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

feat: experimental CSP docs #11736

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
519d124
feat: experimental CSP docs
ematipico May 21, 2025
ea2fc92
add examples for runtime APIs
ematipico May 21, 2025
360a0da
Sarah's light text/formatting/consistency edits - to be reviewed!
sarah11918 May 23, 2025
0e2b613
consistent use of element instead of tag
sarah11918 May 29, 2025
aaf949c
Apply suggestions from code review
ematipico May 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions astro.sidebar.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
379 changes: 379 additions & 0 deletions src/content/docs/en/reference/experimental-flags/csp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This feature doesn't support things like inline scripts, so I wonder if this phrase is clear enough to tell the user that this feature doesn't cover them

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Noting that from a conversation with @ematipico , we will make sure to convey the following points:

  • only works for Astro's bundled/emitted styles and scripts

This means:

  • no out-of-the-box support for inline scripts (and by no support, that means no hashes will be generated, no checking will be done that these are "safe" sources of content); users can use the configuration to inject the hashes of those scripts. They just need to calculate them themselves.

  • not all cases work when using the for Astro's view transitions. If you navigate from one page to another, there's a possibility that styles won't be applied, as well as scripts not being executed

Copy link
Member

@sarah11918 sarah11918 Jun 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
Enabling this feature adds additional security to** Astro's handling of processed and bundled scripts and styles** by default, and allows you to further configure these, and additional, content types.
This experimental CSP feature has some limitations. Inline scripts are not supported out of the box, but you can [provide your own hashes](#hashes) for external and inline scripts. Additionally, [Astro's view transitions](/en/guides/view-transitions/) using the `<ClientRouter />` are not yet fully supported: when navigating from one page to another, some styles may not be applied and some scripts may not be executed.

@louisescher , care to weigh in on this suggestion?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd say that's perfect!


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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The [hash function](https://developer.mozilla.org/en-US/docs/Glossary/Hash_function) to use to generate the hashes of the styles and scripts.
The [hash function](https://developer.mozilla.org/en-US/docs/Glossary/Hash_function) to use to generate the hashes of the styles and scripts emitted by Astro.



```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';
"
>
```

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#### `strictDynamic`
<p>
**Type:** `boolean` <br />
**Default:** `false`<br />
<Since v="5.9.0" />
</p>
Enables the keyword `strict-dynamic`, to support the dynamic injection of scripts.
```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
csp: {
scriptsDirective: {
strictDynamic: true
}
}
}
});
```

Looks like this was hiding in the code but not documented!

## 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`.
:::