跳转到内容

Experimental CSP Level 3 directives

此内容尚不支持你的语言。

Type: boolean
Default: false

添加于： astro@6.2.0 Beta

This experimental feature enables support for CSP Level 3 granular directives: script-src-elem, script-src-attr, style-src-elem, and style-src-attr.

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.

To enable this feature, set experimental.cspLevel3 to true in your Astro config along with a security.csp configuration:

astro.config.mjs
import { defineConfig } from "astro/config"


export default defineConfig({
  experimental: {
    cspLevel3: true,
  },
  security: {
    csp: true,
  },
})

Usage

Section titled “Usage”

With CSP Level 3 enabled, you can configure the new scriptElemDirective and styleElemDirective options in your security.csp configuration, and add the corresponding script-src-attr and style-src-attr values via the existing directives array:

astro.config.mjs
import { defineConfig } from "astro/config"


export default defineConfig({
  experimental: {
    cspLevel3: true,
  },
  security: {
    csp: {
      scriptElemDirective: {
        hashes: ['sha256-abc123'],
        resources: ['https://scripts.cdn.example.com/'],
      },
      styleElemDirective: {
        hashes: ['sha256-def456'],
        resources: ['https://styles.cdn.example.com/'],
      },
      directives: [
        "script-src-attr 'none'",
        "style-src-attr 'unsafe-inline'",
      ],
    },
  },
})

You can also inject Level 3 resources and hashes at runtime via Astro.csp:

src/pages/index.astro
---
Astro.csp.insertScriptElemResource('https://scripts.cdn.example.com/');
Astro.csp.insertStyleElemHash('sha256-abc123');
---


<html>
  <head><title>My Page</title></head>
  <body>
    <h1>Hello</h1>
  </body>
</html>

Configuration

Section titled “Configuration”

scriptElemDirective

Section titled “scriptElemDirective”

Type: { hashes?: string[], resources?: string[] }

A configuration object for the script-src-elem directive. This controls which inline <script> elements are allowed to execute.

scriptElemDirective.hashes

Section titled “scriptElemDirective.hashes”

Type: string[]
Default: []

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.

scriptElemDirective.resources

Section titled “scriptElemDirective.resources”

Type: string[]
Default: []

An array of allowed source URLs for the script-src-elem directive.

styleElemDirective

Section titled “styleElemDirective”

Type: { hashes?: string[], resources?: string[] }

A configuration object for the style-src-elem directive. This controls which inline <style> elements are allowed.

styleElemDirective.hashes

Section titled “styleElemDirective.hashes”

Type: string[]
Default: []

An array of CSP hashes to add to the style-src-elem directive.

styleElemDirective.resources

Section titled “styleElemDirective.resources”

Type: string[]
Default: []

An array of allowed source URLs for the style-src-elem directive.

Attribute directives

Section titled “Attribute directives”

The script-src-attr and style-src-attr directives can be set using the existing directives array:

  • script-src-attr controls event-handler attributes like onclick, onload, etc.
  • style-src-attr controls the style attribute on HTML elements.
astro.config.mjs
export default defineConfig({
  experimental: {
    cspLevel3: true,
  },
  security: {
    csp: {
      directives: [
        "script-src-attr 'none'",
        "style-src-attr 'unsafe-inline'",
      ],
    },
  },
})

Runtime API

Section titled “Runtime API”

When experimental.cspLevel3 is enabled, four additional methods are available on the Astro.csp object:

  • insertScriptElemResource(resource) — adds a source URL to the script-src-elem directive
  • insertScriptElemHash(hash) — adds a hash to the script-src-elem directive
  • insertStyleElemResource(resource) — adds a source URL to the style-src-elem directive
  • insertStyleElemHash(hash) — adds a hash to the style-src-elem directive

These methods are also available on the context.csp object in middleware:

src/middleware.ts
export function onRequest(context, next) {
  context.csp.insertScriptElemResource('https://scripts.cdn.example.com/');
  return next();
}

How it works

Section titled “How it works”

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.

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.

The script-src-attr and style-src-attr directives are not auto-populated and must be configured explicitly via the directives array.

Further reading

Section titled “Further reading”
贡献 社区 赞助