Experimental Content Security Policy

Type: boolean | object
Default: false

Added in: 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.

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

You can further customize the <meta> element by enabling this feature with a configuration object that includes additional options.

`algorithm`

Type: 'SHA-256' | 'SHA-512' | 'SHA-384'
Default: 'SHA-256'

Added in: 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`

Type: CspDirective[]
Default: []

Added in: 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`

Type: object
Default: {}

Added in: 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`

Type: string[]
Default: []

Added in: 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`

Type: CspHash[]
Default: []

Added in: 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`

Type: boolean
Default: false

Added in: 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

You 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`

Type: (directive: CspDirective) => void

Added in: 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`

Type: (resource: string) => void

Added in: 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`

Type: (hash: CspHash) => void

Added in: 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`

Type: (resource: string) => void

Added in: 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`

Type: (hash: CspHash) => void

Added in: 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';
  "
>

Contribute Community Sponsor

Experimental Content Security Policy

Configuration

algorithm

directives

styleDirective and scriptDirective

resources

hashes

strictDynamic

Runtime APIs

addDirective

insertStyleResource

addStyleHash

insertScriptResource

addScriptHash

`algorithm`

`directives`

`styleDirective` and `scriptDirective`

`resources`

`hashes`

`strictDynamic`

`addDirective`

`insertStyleResource`

`addStyleHash`

`insertScriptResource`

`addScriptHash`