From 6ddf276edf2f8c9cf9d10c7fa3085b4cfb0205c7 Mon Sep 17 00:00:00 2001
From: ematipico <estoppa@cloudflare.com>
Date: Thu, 2 Jul 2026 17:39:14 +0100
Subject: [PATCH 1/4] feat: document -elem and -attr CSP directives

---
 .../docs/en/reference/api-reference.mdx       | 110 +++++++++++++++++-
 .../en/reference/integrations-reference.mdx   |  40 +++++++
 2 files changed, 145 insertions(+), 5 deletions(-)

diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx
index e75b24c83e28e..987250a45ea5a 100644
--- a/src/content/docs/en/reference/api-reference.mdx
+++ b/src/content/docs/en/reference/api-reference.mdx
@@ -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 some warning if it detects in case a situation such as this one happens.
+
+  To fix the issue, you have move all the resources and hashes to the specific directives.
+:::
+
 
 #### `csp.insertDirective()`
 
@@ -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>
 
@@ -1146,11 +1154,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`: `'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>
 
@@ -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`: `'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>
 
@@ -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`: `'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>
 
@@ -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`: `'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';
   "
 >
diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx
index a76230bb5277a..fbdca0dbbd66a 100644
--- a/src/content/docs/en/reference/integrations-reference.mdx
+++ b/src/content/docs/en/reference/integrations-reference.mdx
@@ -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[]`
@@ -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[]`
@@ -2514,6 +2522,10 @@ 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`
@@ -2521,8 +2533,22 @@ Specifies a list of valid sources combining the [configured script resources](/e
 
 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`: `'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[]`
@@ -2532,6 +2558,10 @@ 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[]`
@@ -2539,6 +2569,16 @@ Specifies a list of generated hashes for project styles and [user-supplied hashe
 
 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`: `'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>

From f31c2294f5092f0eb5b94b86858240515621492b Mon Sep 17 00:00:00 2001
From: Emanuele Stoppa <estoppa@cloudflare.com>
Date: Fri, 3 Jul 2026 06:41:22 +0100
Subject: [PATCH 2/4] Update src/content/docs/en/reference/api-reference.mdx

Co-authored-by: Armand Philippot <git@armand.philippot.eu>
---
 src/content/docs/en/reference/api-reference.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx
index 987250a45ea5a..a1d0395947cfd 100644
--- a/src/content/docs/en/reference/api-reference.mdx
+++ b/src/content/docs/en/reference/api-reference.mdx
@@ -1089,9 +1089,9 @@ When resources are inserted multiple times or from multiple sources (e.g. define
 :::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 some warning if it detects in case a situation such as this one happens.
+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, you have move all the resources and hashes to the specific directives.
+  To fix the issue, move all the resources and hashes to the specific directives.
 :::
 
 

From 0e449059fcf10080ea640735bbbe037b99ff3a61 Mon Sep 17 00:00:00 2001
From: Emanuele Stoppa <estoppa@cloudflare.com>
Date: Fri, 3 Jul 2026 08:16:42 +0100
Subject: [PATCH 3/4] Apply suggestions from code review

Co-authored-by: Armand Philippot <git@armand.philippot.eu>
---
 src/content/docs/en/reference/api-reference.mdx          | 8 ++++----
 src/content/docs/en/reference/integrations-reference.mdx | 4 ++--
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx
index a1d0395947cfd..e80b185d2b435 100644
--- a/src/content/docs/en/reference/api-reference.mdx
+++ b/src/content/docs/en/reference/api-reference.mdx
@@ -1156,7 +1156,7 @@ 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`: `'element'` for `style-src-elem`, `'attribute'` for `style-src-attr`, or `'default'` (the same as a bare string) for `style-src`.
+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"
 ---
@@ -1207,7 +1207,7 @@ 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`: `'element'` for `style-src-elem`, `'attribute'` for `style-src-attr`, or `'default'` (the same as a bare hash) for `style-src`.
+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"
 ---
@@ -1258,7 +1258,7 @@ 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`: `'element'` for `script-src-elem`, `'attribute'` for `script-src-attr`, or `'default'` (the same as a bare string) for `script-src`.
+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"
 ---
@@ -1309,7 +1309,7 @@ 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`: `'element'` for `script-src-elem`, `'attribute'` for `script-src-attr`, or `'default'` (the same as a bare hash) for `script-src`.
+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"
 ---
diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx
index fbdca0dbbd66a..4a48161415304 100644
--- a/src/content/docs/en/reference/integrations-reference.mdx
+++ b/src/content/docs/en/reference/integrations-reference.mdx
@@ -2541,7 +2541,7 @@ Determines whether support for [dynamic script injection is enabled in the confi
 <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`: `'element'` for `script-src-elem`, `'attribute'` for `script-src-attr`, or `'default'` (the same as a bare string) for `script-src`.
+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`
 
@@ -2577,7 +2577,7 @@ Specifies a list of valid sources combining the [configured style resources](/en
 <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`: `'element'` for `style-src-elem`, `'attribute'` for `style-src-attr`, or `'default'` (the same as a bare string) for `style-src`.
+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`
 

From 4a9b66ea0956652402bac6fbbb8ed330b7621f63 Mon Sep 17 00:00:00 2001
From: Emanuele Stoppa <estoppa@cloudflare.com>
Date: Fri, 3 Jul 2026 15:09:29 +0100
Subject: [PATCH 4/4] Update src/content/docs/en/reference/api-reference.mdx

Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com>
---
 src/content/docs/en/reference/api-reference.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx
index e80b185d2b435..3a6a9698d00af 100644
--- a/src/content/docs/en/reference/api-reference.mdx
+++ b/src/content/docs/en/reference/api-reference.mdx
@@ -1091,7 +1091,7 @@ When you scope a source or hash to a more specific directive with the `kind` opt
 
 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.
+To fix the issue, move all the resources and hashes to the specific directives.
 :::