diff --git a/src/content/docs/en/reference/configuration-reference.mdx b/src/content/docs/en/reference/configuration-reference.mdx index 4b04d1d560fea..15aa503b6f125 100644 --- a/src/content/docs/en/reference/configuration-reference.mdx +++ b/src/content/docs/en/reference/configuration-reference.mdx @@ -376,10 +376,9 @@ Using `'attribute'` is useful when you are manipulating the `class` attribute of

Determines the default behavior when two routes generate the same prerendered URL: - - - `error`: fail the build and display an error, forcing you to resolve the conflict - - `warn` (default): log a warning when conflicts occur, but build using the highest-priority route - - `ignore`: silently build using the highest-priority route when conflicts occur +- `error`: fail the build and display an error, forcing you to resolve the conflict +- `warn` (default): log a warning when conflicts occur, but build using the highest-priority route +- `ignore`: silently build using the highest-priority route when conflicts occur ```js { @@ -387,12 +386,11 @@ Determines the default behavior when two routes generate the same prerendered UR } ``` - ### vite

- **Type:** `ViteUserConfig` +**Type:** `ViteUserConfig`

Pass additional configuration options to Vite. Useful when Astro doesn't support some advanced configuration that you may need. @@ -421,7 +419,7 @@ View the full `vite` configuration object documentation on [vite.dev](https://vi } ``` -## security +### security

@@ -434,16 +432,6 @@ Enables security measures for an Astro website. These features only exist for pages rendered on demand (SSR) using `server` mode or pages that opt out of prerendering in `static` mode. - -### security.checkOrigin - -

- -**Type:** `boolean`
-**Default:** `true`
- -

- By default, Astro will automatically check that the “origin” header matches the URL sent by each request in on-demand rendered pages. You can disable this behavior by setting `checkOrigin` to `false`: @@ -458,6 +446,15 @@ export default defineConfig({ }) ``` +#### security.checkOrigin + +

+ +**Type:** `boolean`
+**Default:** `true`
+ +

+ Performs a check that the "origin" header, automatically passed by all modern browsers, matches the URL sent by each `Request`. This is used to provide Cross-Site Request Forgery (CSRF) protection. The "origin" check is executed only for pages rendered on demand, and only for the requests `POST`, `PATCH`, `DELETE` and `PUT` with @@ -465,11 +462,11 @@ one of the following `content-type` headers: `'application/x-www-form-urlencoded If the "origin" header doesn't match the `pathname` of the request, Astro will return a 403 status code and will not render the page. -### security.allowedDomains +#### security.allowedDomains

-**Type:** `RemotePattern[]`
+**Type:** `Array`
**Default:** `[]`

@@ -503,10 +500,10 @@ The patterns support wildcards for flexible hostname matching: When not configured, `X-Forwarded-Host` headers are not trusted and will be ignored. - -### `security.csp` +#### security.csp

+ **Type:** `boolean | object`
**Default:** `false`
@@ -514,11 +511,11 @@ When not configured, `X-Forwarded-Host` headers are not trusted and will be igno Enables support for [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/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)](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting) 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. +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 feature comes with some limitations: -- External scripts and external styles are not supported out of the box, but you can [provide your own hashes](#hashes). -- [Astro's view transitions](/en/guides/view-transitions/) using the `` are not supported, but you can [consider migrating to the browser native View Transition API](https://events-3bg.pages.dev/jotter/astro-view-transitions/) instead if you are not using Astro's enhancements to the native View Transitions and Navigation APIs. +This feature comes with some limitations: +- External scripts and external styles are not supported out of the box, but you can [provide your own hashes](https://v6.docs.astro.build/en/reference/configuration-reference/#hashes). +- [Astro's view transitions](https://v6.docs.astro.build/en/guides/view-transitions/) using the `` are not supported, but you can [consider migrating to the browser native View Transition API](https://events-3bg.pages.dev/jotter/astro-view-transitions/) instead if you are not using Astro's enhancements to the native View Transitions and Navigation APIs. - Shiki isn't currently supported. By design, Shiki functions using inline styles. :::note @@ -526,29 +523,28 @@ Due to the nature of the Vite dev server, this feature isn't supported while wor ::: When enabled, Astro will add a `` element inside the `` 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](#securitycspdirectives) based on the script and styles used in the 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](https://v6.docs.astro.build/en/reference/configuration-reference/#securitycspdirectives) based on the script and styles used in the page. ```html + ``` - You can further customize the `` element by enabling this feature with a configuration object that includes additional options. -##### `security.csp.algorithm` +##### security.csp.algorithm

-**Type:** `'SHA-256' | 'SHA-512' | 'SHA-384'`
+**Type:** `"SHA-256" | "SHA-384" | "SHA-512"`
**Default:** `'SHA-256'`

@@ -567,11 +563,11 @@ export default defineConfig({ }); ``` -##### `security.csp.directives` +##### security.csp.directives

-**Type:** `CspDirective[]`
+**Type:** `Array`
**Default:** `[]`

@@ -585,14 +581,13 @@ export default defineConfig({ security: { csp: { directives: [ - "default-src 'self'", + "default-src 'self'", "img-src 'self' https://images.cdn.example.com" ] } } }); ``` - After the build, the `` element will add your directives into the `content` value alongside Astro's default directives: ```html @@ -607,38 +602,69 @@ After the build, the `` element will add your directives into the `content > ``` -##### `security.csp.styleDirective` +##### security.csp.styleDirective

-**Type:** `object`
-**Default:** `{}`
+**Type:** `CspStyleDirective`
+**Default:** `undefined`

-A configuration object that allows you to override the default sources for the `style-src` directive with the [`resources`](#resources) property, or to provide additional [hashes](#hashes) to be rendered. +A configuration object that allows you to override the default sources for the `style-src` directive with the [`resources`](https://v6.docs.astro.build/en/reference/configuration-reference/#resources) property, or to provide additional [hashes](https://v6.docs.astro.build/en/reference/configuration-reference#hashes) to be rendered. -##### `security.csp.scriptDirective` +###### security.csp.styleDirective.hashes

- **Type:** `object`
- **Default:** `{}`
- +**Type:** `Array`
+**Default:** `[]`
+

-A configuration object that allows you to override the default sources for the `script-src` directive with the [`resources`](#resources) property, or to provide additional [hashes](#hashes) to be rendered. +A list of 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. + +```js title="astro.config.mjs" +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + security: { + csp: { + styleDirective: { + hashes: [ + "sha384-styleHash", + "sha512-styleHash", + "sha256-styleHash" + ] + } + } + } +}); +``` + +After the build, the `` element will include your additional hashes in the `style-src` directives: + +```html + +``` -##### `resources` +###### security.csp.styleDirective.resources

-**Type:** `string[]`
+**Type:** `Array`
**Default:** `[]`

-A list of valid sources for the `script-src` and `style-src` directives to override Astro's default sources. 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. +A list of valid sources for `style-src` directives to override Astro's default sources. 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. ```js title="astro.config.mjs" import { defineConfig } from 'astro/config'; @@ -651,38 +677,43 @@ export default defineConfig({ "'self'", "https://styles.cdn.example.com" ] - }, - scriptDirective: { - resources: [ - "https://cdn.example.com" - ] } } } }); - ``` +``` -After the build, the `` element will instead apply your sources to the `style-src` and `script-src` directives: +After the build, the `` element will instead apply your sources to the `style-src` directives: ```html ``` When resources are inserted multiple times or from multiple sources (e.g. defined in your `csp` config and added using [the CSP runtime API](/en/reference/api-reference/#csp)), Astro will merge and deduplicate all resources to create your `` element. -#### `hashes` +##### security.csp.scriptDirective + +

+ +**Type:** `CspScriptDirective`
+**Default:** `undefined`
+ +

+ +A configuration object that allows you to override the default sources for the `script-src` directive with the [`resources`](https://v6.docs.astro.build/en/reference/configuration-reference/#resources) property, or to provide additional [hashes](https://v6.docs.astro.build/en/reference/configuration-reference#hashes) to be rendered. + +###### security.csp.scriptDirective.hashes

-**Type:** `CspHash[]`
+**Type:** `Array`
**Default:** `[]`

@@ -697,13 +728,6 @@ import { defineConfig } from 'astro/config'; export default defineConfig({ security: { csp: { - styleDirective: { - hashes: [ - "sha384-styleHash", - "sha512-styleHash", - "sha256-styleHash" - ] - }, scriptDirective: { hashes: [ "sha384-scriptHash", @@ -716,19 +740,60 @@ export default defineConfig({ }); ``` -After the build, the `` element will include your additional hashes in the `script-src` and `style-src` directives: +After the build, the `` element will include your additional hashes in the `script-src` directives: ```html ``` -#### `strictDynamic` +###### security.csp.scriptDirective.resources + +

+ +**Type:** `Array`
+**Default:** `[]`
+ +

+ +A list of valid sources for the `script-src` directives to override Astro's default sources. 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. + +```js title="astro.config.mjs" +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + security: { + csp: { + scriptDirective: { + resources: [ + "'self'", "https://cdn.example.com" + ] + } + } + } +}); +``` + +After the build, the `` element will instead apply your sources to the `script-src` directives: + +```html + + + +``` + +When resources are inserted multiple times or from multiple sources (e.g. defined in your `csp` config and added using [the CSP runtime API](/en/reference/api-reference/#csp)), Astro will merge and deduplicate all resources to create your `` element. + +###### security.csp.scriptDirective.strictDynamic

@@ -2061,3 +2126,4 @@ export default defineConfig({ } }) ``` +