Skip to content

feat: document -elem and -attr CSP directives #14196

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
ematipico wants to merge 4 commits into
base: main
Choose a base branch
from
+145 −5
Open

feat: document -elem and -attr CSP directives #14196

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6ddf276
feat: document -elem and -attr CSP directives
ematipico Jul 2, 2026
f31c229
Update src/content/docs/en/reference/api-reference.mdx
ematipico Jul 3, 2026
0e44905
Apply suggestions from code review
ematipico Jul 3, 2026
4a9b66e
Update src/content/docs/en/reference/api-reference.mdx
ematipico Jul 3, 2026
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
110 changes: 105 additions & 5 deletions src/content/docs/en/reference/api-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1086,6 +1086,14 @@ You can customize the `<meta>` element per page from the `Astro` global inside `

When resources are inserted multiple times or from multiple sources (e.g. defined in your [`csp` config](/en/reference/configuration-reference/#securitycsp) and added using the following CSP runtime APIs, Astro will merge and deduplicate all resources to create your `<meta>` element.

:::caution[Scoping to more specific directives]
When you scope a source or hash to a more specific directive with the `kind` option (`'element'` or `'attribute'`), browsers use that directive instead of the generic `script-src`/`style-src` for its scope, and do not fall back to the generic directive.

Astro automatically moves the hashes it generates for your inline scripts and styles onto the more specific directive so they keep working. However, it does **not** move your generic (`'default'`) resources. If you combine generic resources with more specific resources or hashes for the same directive family, the generic resources will not apply to the specific scope. Astro logs a warning if it detects such a situation.

To fix the issue, move all the resources and hashes to the specific directives.
Comment thread
ematipico marked this conversation as resolved.
Outdated
:::


#### `csp.insertDirective()`

Expand Down Expand Up @@ -1122,7 +1130,7 @@ content="

<p>

**Type:** `(resource: string) => void`<br />
**Type:** `(resource: string | { resource: string; kind: 'element' | 'attribute' | 'default' }) => void`<br />
<Since v="6.0.0" />
</p>

Expand All @@ -1146,11 +1154,34 @@ content="
>
```

<p><Since v="7.1.0" /></p>

@ArmandPhilippot ArmandPhilippot Jul 2, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Ah, nice catch. I forgot about this pattern when I answered on Discord. I think it makes sense now that I have the content right in front of me!


You can also scope a source to a more specific directive by passing an object with a `kind` property. Use `'element'` for `style-src-elem`, `'attribute'` for `style-src-attr`, or `'default'` (the same as a bare string) for `style-src`.

```astro title="src/pages/index.astro"
---
Astro.csp?.insertStyleResource({ resource: "'unsafe-inline'", kind: "attribute" });
---
```

After the build, the `<meta>` element for this individual page will add your source to the `style-src-attr` directive, which applies only to inline `style` attributes:

```html
<meta
http-equiv="content-security-policy"
content="
script-src 'self';
style-src 'self';
style-src-attr 'unsafe-inline';
"
>
```

#### `csp.insertStyleHash()`

<p>

**Type:** `(hash: CspHash) => void`<br />
**Type:** `(hash: CspHash | { hash: CspHash; kind: 'element' | 'attribute' | 'default' }) => void`<br />
<Since v="6.0.0" />
</p>

Expand All @@ -1174,11 +1205,34 @@ content="
>
```

<p><Since v="7.1.0" /></p>

You can also scope a hash to a more specific directive by passing an object with a `kind` property. Use `'element'` for `style-src-elem`, `'attribute'` for `style-src-attr`, or `'default'` (the same as a bare hash) for `style-src`.

```astro title="src/pages/index.astro"
---
Astro.csp?.insertStyleHash({ hash: "sha512-styleHash", kind: "element" });
---
```

After the build, the `<meta>` element for this individual page will add your hash to the `style-src-elem` directive. Astro's automatically generated style hashes also move there, since `style-src-elem` takes precedence over `style-src` for `<style>` and `<link>` elements:

```html
<meta
http-equiv="content-security-policy"
content="
script-src 'self' 'sha256-somehash';
style-src 'self';
style-src-elem 'self' 'sha256-somehash' 'sha512-styleHash';
"
>
```

#### `csp.insertScriptResource()`

<p>

**Type:** `(resource: string) => void`<br />
**Type:** `(resource: string | { resource: string; kind: 'element' | 'attribute' | 'default' }) => void`<br />
<Since v="6.0.0" />
</p>

Expand All @@ -1202,11 +1256,34 @@ content="
>
```

<p><Since v="7.1.0" /></p>

You can also scope a source to a more specific directive by passing an object with a `kind` property. Use `'element'` for `script-src-elem`, `'attribute'` for `script-src-attr`, or `'default'` (the same as a bare string) for `script-src`.

```astro title="src/pages/index.astro"
---
Astro.csp?.insertScriptResource({ resource: "https://scripts.cdn.example.com", kind: "element" });
---
```

After the build, the `<meta>` element for this individual page will add your source to the `script-src-elem` directive, which governs `<script>` elements:

```html
<meta
http-equiv="content-security-policy"
content="
script-src 'self';
script-src-elem https://scripts.cdn.example.com;
style-src 'self';
"
>
```

#### `csp.insertScriptHash()`

<p>

**Type:** `(hash: CspHash) => void`<br />
**Type:** `(hash: CspHash | { hash: CspHash; kind: 'element' | 'attribute' | 'default' }) => void`<br />
<Since v="6.0.0" />
</p>

Expand All @@ -1224,7 +1301,30 @@ After the build, the `<meta>` element for this individual page will add your has
<meta
http-equiv="content-security-policy"
content="
script-src 'self' 'sha256-somehash' 'sha512-styleHash';
script-src 'self' 'sha256-somehash' 'sha512-scriptHash';
style-src 'self' 'sha256-somehash';
"
>
```

<p><Since v="7.1.0" /></p>

You can also scope a hash to a more specific directive by passing an object with a `kind` property. Use `'element'` for `script-src-elem`, `'attribute'` for `script-src-attr`, or `'default'` (the same as a bare hash) for `script-src`.

```astro title="src/pages/index.astro"
---
Astro.csp?.insertScriptHash({ hash: "sha512-scriptHash", kind: "element" });
---
```

After the build, the `<meta>` element for this individual page will add your hash to the `script-src-elem` directive. Astro's automatically generated script hashes also move there, since `script-src-elem` takes precedence over `script-src` for `<script>` elements:

```html
<meta
http-equiv="content-security-policy"
content="
script-src 'self';
script-src-elem 'self' 'sha256-somehash' 'sha512-scriptHash';
style-src 'self' 'sha256-somehash';
"
>
Expand Down
40 changes: 40 additions & 0 deletions src/content/docs/en/reference/integrations-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2496,6 +2496,10 @@ Specifies the [configured hash function](/en/reference/configuration-reference/#

##### `SSRManifest.csp.scriptHashes`

:::caution[Deprecated]
Use [`scriptDirective`](#ssrmanifestcspscriptdirective) instead. This property only lists hashes scoped to the generic `script-src` directive. Will be removed in a future major version.
:::

<p>

**Type:** `string[]`
Expand All @@ -2505,6 +2509,10 @@ Specifies a list of generated hashes for project scripts and [user-supplied hash

##### `SSRManifest.csp.scriptResources`

:::caution[Deprecated]
Use [`scriptDirective`](#ssrmanifestcspscriptdirective) instead. This property only lists sources scoped to the generic `script-src` directive. Will be removed in a future major version.
:::

<p>

**Type:** `string[]`
Expand All @@ -2514,15 +2522,33 @@ Specifies a list of valid sources combining the [configured script resources](/e

##### `SSRManifest.csp.isStrictDynamic`

:::caution[Deprecated]
Use [`scriptDirective.strictDynamic`](#ssrmanifestcspscriptdirective) instead. Will be removed in a future major version.
:::

<p>

**Type:** `boolean`
</p>

Determines whether support for [dynamic script injection is enabled in the configuration](/en/reference/configuration-reference/#securitycspscriptdirectivestrictdynamic).

##### `SSRManifest.csp.scriptDirective`

<p>

**Type:** `{ resources: Array<string | { resource: string; kind: 'element' | 'attribute' | 'default' }>; hashes: Array<string | { hash: string; kind: 'element' | 'attribute' | 'default' }>; strictDynamic: boolean }`<br />
<Since v="7.1.0" />
</p>

Describes the sources, hashes, and [`'strict-dynamic'`](/en/reference/configuration-reference/#securitycspscriptdirectivestrictdynamic) support for the `script-src` family of directives. Each source or hash can target a more specific directive through its `kind` property. Use `'element'` for `script-src-elem`, `'attribute'` for `script-src-attr`, or `'default'` (the same as a bare string) for `script-src`.

##### `SSRManifest.csp.styleHashes`

:::caution[Deprecated]
Use [`styleDirective`](#ssrmanifestcspstyledirective) instead. This property only lists hashes scoped to the generic `style-src` directive. Will be removed in a future major version.
:::

<p>

**Type:** `string[]`
Expand All @@ -2532,13 +2558,27 @@ Specifies a list of generated hashes for project styles and [user-supplied hashe

##### `SSRManifest.csp.styleResources`

:::caution[Deprecated]
Use [`styleDirective`](#ssrmanifestcspstyledirective) instead. This property only lists sources scoped to the generic `style-src` directive. Will be removed in a future major version.
:::

<p>

**Type:** `string[]`
</p>

Specifies a list of valid sources combining the [configured style resources](/en/reference/configuration-reference/#securitycspstyledirectiveresources) and the [injected style resources](/en/reference/api-reference/#cspinsertstyleresource).

##### `SSRManifest.csp.styleDirective`

<p>

**Type:** `{ resources: Array<string | { resource: string; kind: 'element' | 'attribute' | 'default' }>; hashes: Array<string | { hash: string; kind: 'element' | 'attribute' | 'default' }> }`<br />
<Since v="7.1.0" />
</p>

Describes the sources and hashes for the `style-src` family of directives. Each source or hash can target a more specific directive through its `kind` property. Use `'element'` for `style-src-elem`, `'attribute'` for `style-src-attr`, or `'default'` (the same as a bare string) for `style-src`.

##### `SSRManifest.csp.directives`

<p>
Expand Down
Loading