Skip to content

Commit 7d50a45

Browse files
amoreyArmandPhilippot
amorey
and
ArmandPhilippot
committed
docs(experimental): add CSP Level 3 directives flag documentation
Add documentation for the experimental `cspLevel3` flag with translations for es, fr, ko, and zh-cn. Update sidebar config. Signed-off-by: Andres Morey <andres@kubetail.com> Co-authored-by: Armand Philippot <git@armand.philippot.eu> Assisted-by: Claude:claude-opus-4-6
1 parent cf23254 commit 7d50a45

2 files changed

Lines changed: 178 additions & 0 deletions

File tree

‎astro.sidebar.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,7 @@ export const sidebar = [
155155
'reference/experimental-flags/content-intellisense',
156156
'reference/experimental-flags/chrome-devtools-workspace',
157157
'reference/experimental-flags/svg-optimization',
158+
'reference/experimental-flags/csp-level3-directives',
158159
'reference/experimental-flags/queued-rendering',
159160
'reference/experimental-flags/rust-compiler',
160161
],

‎src/content/docs/en/reference/experimental-flags/csp-level3-directives.mdx‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
title: Experimental CSP Level 3 directives
3+
sidebar:
4+
label: CSP Level 3 directives
5+
i18nReady: true
6+
---
7+
8+
import Since from '~/components/Since.astro'
9+
10+
<p>
11+
12+
**Type:** `boolean`<br />
13+
**Default:** `false`<br />
14+
<Since v="6.2.0" />
15+
</p>
16+
17+
This experimental feature enables support for [CSP Level 3](https://www.w3.org/TR/CSP3/) granular directives: `script-src-elem`, `script-src-attr`, `style-src-elem`, and `style-src-attr`.
18+
19+
These directives let you apply separate Content Security Policies to inline `<script>` and `<style>` elements versus event-handler attributes (e.g. `onclick`) and the `style` attribute, giving you finer-grained control than the base `script-src` and `style-src` directives alone.
20+
21+
To enable this feature, set `experimental.cspLevel3` to `true` in your Astro config along with a [`security.csp`](/en/reference/configuration-reference/#securitycsp) configuration:
22+
23+
```js title="astro.config.mjs" ins={5}
24+
import { defineConfig } from "astro/config"
25+
26+
export default defineConfig({
27+
experimental: {
28+
cspLevel3: true,
29+
},
30+
security: {
31+
csp: true,
32+
},
33+
})
34+
```
35+
36+
## Usage
37+
38+
With CSP Level 3 enabled, you can configure the new `scriptElemDirective` and `styleElemDirective` options in your [`security.csp`](/en/reference/configuration-reference/#securitycsp) configuration, and add the corresponding `script-src-attr` and `style-src-attr` values via the existing [`directives`](/en/reference/configuration-reference/#securitycspdirectives) array:
39+
40+
```js title="astro.config.mjs"
41+
import { defineConfig } from "astro/config"
42+
43+
export default defineConfig({
44+
experimental: {
45+
cspLevel3: true,
46+
},
47+
security: {
48+
csp: {
49+
scriptElemDirective: {
50+
hashes: ['sha256-abc123'],
51+
resources: ['https://scripts.cdn.example.com/'],
52+
},
53+
styleElemDirective: {
54+
hashes: ['sha256-def456'],
55+
resources: ['https://styles.cdn.example.com/'],
56+
},
57+
directives: [
58+
"script-src-attr 'none'",
59+
"style-src-attr 'unsafe-inline'",
60+
],
61+
},
62+
},
63+
})
64+
```
65+
66+
You can also inject Level 3 resources and hashes at runtime via `Astro.csp`:
67+
68+
```astro title="src/pages/index.astro"
69+
---
70+
Astro.csp.insertScriptElemResource('https://scripts.cdn.example.com/');
71+
Astro.csp.insertStyleElemHash('sha256-abc123');
72+
---
73+
74+
<html>
75+
<head><title>My Page</title></head>
76+
<body>
77+
<h1>Hello</h1>
78+
</body>
79+
</html>
80+
```
81+
82+
## Configuration
83+
84+
### `scriptElemDirective`
85+
86+
**Type:** `{ hashes?: string[], resources?: string[] }`<br />
87+
88+
A configuration object for the `script-src-elem` directive. This controls which inline `<script>` elements are allowed to execute.
89+
90+
#### `scriptElemDirective.hashes`
91+
92+
**Type:** `string[]`<br />
93+
**Default:** `[]`
94+
95+
An array of CSP hashes (e.g. `sha256-...`, `sha384-...`, `sha512-...`) to add to the `script-src-elem` directive. These hashes authorize specific inline script content.
96+
97+
#### `scriptElemDirective.resources`
98+
99+
**Type:** `string[]`<br />
100+
**Default:** `[]`
101+
102+
An array of allowed source URLs for the `script-src-elem` directive.
103+
104+
### `styleElemDirective`
105+
106+
**Type:** `{ hashes?: string[], resources?: string[] }`<br />
107+
108+
A configuration object for the `style-src-elem` directive. This controls which inline `<style>` elements are allowed.
109+
110+
#### `styleElemDirective.hashes`
111+
112+
**Type:** `string[]`<br />
113+
**Default:** `[]`
114+
115+
An array of CSP hashes to add to the `style-src-elem` directive.
116+
117+
#### `styleElemDirective.resources`
118+
119+
**Type:** `string[]`<br />
120+
**Default:** `[]`
121+
122+
An array of allowed source URLs for the `style-src-elem` directive.
123+
124+
### Attribute directives
125+
126+
The `script-src-attr` and `style-src-attr` directives can be set using the existing [`directives`](/en/reference/configuration-reference/#securitycspdirectives) array:
127+
128+
- `script-src-attr` controls event-handler attributes like `onclick`, `onload`, etc.
129+
- `style-src-attr` controls the `style` attribute on HTML elements.
130+
131+
```js title="astro.config.mjs"
132+
export default defineConfig({
133+
experimental: {
134+
cspLevel3: true,
135+
},
136+
security: {
137+
csp: {
138+
directives: [
139+
"script-src-attr 'none'",
140+
"style-src-attr 'unsafe-inline'",
141+
],
142+
},
143+
},
144+
})
145+
```
146+
147+
## Runtime API
148+
149+
When `experimental.cspLevel3` is enabled, four additional methods are available on the [`Astro.csp` object](/en/reference/api-reference/#csp):
150+
151+
- `insertScriptElemResource(resource)` — adds a source URL to the `script-src-elem` directive
152+
- `insertScriptElemHash(hash)` — adds a hash to the `script-src-elem` directive
153+
- `insertStyleElemResource(resource)` — adds a source URL to the `style-src-elem` directive
154+
- `insertStyleElemHash(hash)` — adds a hash to the `style-src-elem` directive
155+
156+
These methods are also available on the `context.csp` object in [middleware](/en/guides/middleware/):
157+
158+
```js title="src/middleware.ts"
159+
export function onRequest(context, next) {
160+
context.csp.insertScriptElemResource('https://scripts.cdn.example.com/');
161+
return next();
162+
}
163+
```
164+
165+
## How it works
166+
167+
When CSP Level 3 directives are enabled, Astro adds the `script-src-elem` and `style-src-elem` directives to the CSP `<meta>` tag alongside the existing `script-src` and `style-src` directives.
168+
169+
Auto-generated hashes from `script-src` and `style-src` are automatically inherited into `script-src-elem` and `style-src-elem` when you have configured hash or resource values for the corresponding Level 3 directive. This means you do not need to duplicate your hashes manually.
170+
171+
The `script-src-attr` and `style-src-attr` directives are not auto-populated and must be configured explicitly via the `directives` array.
172+
173+
## Further reading
174+
175+
- [CSP header reference on MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy)
176+
- [W3C CSP Level 3 specification](https://www.w3.org/TR/CSP3/)
177+
- [Astro CSP configuration reference](/en/reference/configuration-reference/#securitycsp)

0 commit comments

Comments
 (0)