Experimental Content Security Policy
Type: boolean | object
Default: false
astro@5.9.0
New
Enables support for Content Security Policy (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) attacks.
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 for external and inline scripts. Additionally, Astro’s 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.
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
.
To enable this feature, add the experimental flag in your Astro config:
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 based on the script and styles used in the page.
<head> <meta http-equiv="content-security-policy" content=" script-src 'self' 'sha256-somehash'; style-src 'self' 'sha256-somehash'; " ></head>
Configuration
Section titled ConfigurationYou can further customize the <meta>
element by enabling this feature with a configuration object that includes additional options.
algorithm
Section titled algorithmType: 'SHA-256' | 'SHA-512' | 'SHA-384'
Default: 'SHA-256'
astro@5.9.0
New
The hash function to use when generating the hashes of the styles and scripts emitted by Astro.
import { defineConfig } from 'astro/config';
export default defineConfig({ experimental: { csp: { algorithm: 'SHA-512' } }});
directives
Section titled directivesType: CspDirective[]
Default: []
astro@5.9.0
New
A list of CSP directives 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:
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:
<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'; ">
styleDirective
and scriptDirective
Section titled styleDirective and scriptDirectiveType: object
Default: {}
astro@5.9.0
New
Configuration objects that allow you to override the default sources for the style-src
and script-src
directives with the resources
property, or to provide additional hashes to be rendered.
These properties are added to all pages and completely override Astro’s default resources, not add to them. Therefore, you must explicitly specify any default values that you want to be included.
resources
Section titled resourcesType: string[]
Default: []
astro@5.9.0
New
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.
import { defineConfig } from 'astro/config';
export default defineConfig({ experimental: { csp: { styleDirective: { resources: [ "self", "https://styles.cdn.example.com" ] }, scriptDirective: { resources: [ "https://cdn.example.com" ] } } }});
After the build, the <meta>
element will instead apply your sources to the style-src
and script-src
directives:
<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
Section titled hashesType: CspHash[]
Default: []
astro@5.9.0
New
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.
import { defineConfig } from 'astro/config';
export default defineConfig({ experimental: { csp: { styleDirective: { hashes: [ "sha384-styleHash", "sha512-styleHash", "sha256-styleHash" ] }, scriptDirective: { 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:
<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'; ">
strictDynamic
Section titled strictDynamicType: boolean
Default: false
astro@5.9.0
New
Enables the strict-dynamic
keyword to support the dynamic injection of scripts.
import { defineConfig } from 'astro/config';
export default defineConfig({ experimental: { csp: { scriptDirective: { strictDynamic: true } } }});
Runtime APIs
Section titled Runtime APIsYou can customize the <meta>
element per page via runtime APIs available from the Astro
global inside .astro
components, or the APIContext
type in endpoints and middleware.
addDirective
Section titled addDirectiveType: (directive: CspDirective) => void
astro@5.9.0
New
Adds a single directive to the current page. You can call this method multiple times to add additional directives.
---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:
<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
Section titled insertStyleResourceType: (resource: string) => void
astro@5.9.0
New
Inserts a new resource to be used for the style-src
directive.
---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:
<meta http-equiv="content-security-policy" content=" script-src 'self' 'sha256-somehash'; style-src 'https://styles.cdn.example.com' 'sha256-somehash'; ">
addStyleHash
Section titled addStyleHashType: (hash: CspHash) => void
astro@5.9.0
New
Adds a new hash to the style-src
directive.
---Astro.addStyleHash("sha512-styleHash");---
After the build, the <meta>
element for this individual page will add your hash to the default style-src
directive:
<meta http-equiv="content-security-policy" content=" script-src 'self' 'sha256-somehash'; style-src 'self' 'sha256-somehash' 'sha512-styleHash'; ">
insertScriptResource
Section titled insertScriptResourceType: (resource: string) => void
astro@5.9.0
New
Inserts a new valid source to be used for the script-src
directive.
---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:
<meta http-equiv="content-security-policy" content=" script-src 'https://scripts.cdn.example.com' 'sha256-somehash'; style-src 'self' 'sha256-somehash'; ">
addScriptHash
Section titled addScriptHashType: (hash: CspHash) => void
astro@5.9.0
New
Adds a new hash to the script-src
directive.
---Astro.addScriptHash("sha512-scriptHash");---
After the build, the <meta>
element for this individual page will add your hash to the default script-src
directive:
<meta http-equiv="content-security-policy" content=" script-src 'self' 'sha256-somehash' 'sha512-styleHash'; style-src 'self' 'sha256-somehash'; ">