From 0a9cd55c730abbc79d160a820be81ef948f3042d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s=20Correa=20Casablanca?= <andreu@kindspells.dev>
Date: Tue, 17 Sep 2024 17:11:18 +0200
Subject: [PATCH] docs: document experimental netlify support

Signed-off-by: Andres Correa Casablanca <andreu@kindspells.dev>
---
 @kindspells/astro-shield/src/core.mts         | 11 ++-
 @kindspells/astro-shield/src/main.mts         | 10 ++-
 .../content-security-policy.mdx               | 16 ++++-
 .../netlify-static-content.mdx                | 68 +++++++++++++++++++
 4 files changed, 99 insertions(+), 6 deletions(-)
 create mode 100644 docs/src/content/docs/guides/security-headers/netlify-static-content.mdx

diff --git a/@kindspells/astro-shield/src/core.mts b/@kindspells/astro-shield/src/core.mts
index 2ed7e75..06e94e9 100644
--- a/@kindspells/astro-shield/src/core.mts
+++ b/@kindspells/astro-shield/src/core.mts
@@ -767,13 +767,22 @@ export const processStaticFiles = async (
 	if (securityHeaders?.enableOnStaticPages !== undefined) {
 		const provider = securityHeaders.enableOnStaticPages.provider
 		switch (provider) {
-			case 'netlify':
+			case 'netlify': {
+				if (
+					(securityHeaders.enableOnStaticPages.mode ?? '_headers') !==
+					'_headers'
+				) {
+					throw new Error(
+						'Netlify provider only supports "_headers" mode for now',
+					)
+				}
 				await patchNetlifyHeadersConfig(
 					resolve(distDir, '_headers'),
 					securityHeaders,
 					h,
 				)
 				break
+			}
 			case 'vercel':
 				throw new Error('Vercel provider is still not supported')
 			default:
diff --git a/@kindspells/astro-shield/src/main.mts b/@kindspells/astro-shield/src/main.mts
index 812ccbd..03f6fe6 100644
--- a/@kindspells/astro-shield/src/main.mts
+++ b/@kindspells/astro-shield/src/main.mts
@@ -9,17 +9,23 @@ import { fileURLToPath } from 'node:url'
 import type { AstroIntegration } from 'astro'
 
 import { getAstroConfigSetup, processStaticFiles } from '#as/core'
-import type { ShieldOptions, SRIOptions } from './types.mts'
+import type {
+	SecurityHeadersOptions,
+	ShieldOptions,
+	SRIOptions,
+} from './types.mts'
 
 type AstroHooks = AstroIntegration['hooks']
 
 const getAstroBuildDone = (
 	sri: Required<SRIOptions>,
+	securityHeaders: SecurityHeadersOptions | undefined,
 ): NonNullable<AstroHooks['astro:build:done']> =>
 	(async ({ dir, logger }) =>
 		await processStaticFiles(logger, {
 			distDir: fileURLToPath(dir),
 			sri,
+			securityHeaders,
 		})) satisfies NonNullable<AstroHooks['astro:build:done']>
 
 const logWarn = (msg: string): void =>
@@ -69,7 +75,7 @@ export const shield = ({
 		hooks: {
 			...(_sri.enableStatic === true
 				? {
-						'astro:build:done': getAstroBuildDone(_sri),
+						'astro:build:done': getAstroBuildDone(_sri, securityHeaders),
 					}
 				: undefined),
 			...(_sri.enableMiddleware === true
diff --git a/docs/src/content/docs/guides/security-headers/content-security-policy.mdx b/docs/src/content/docs/guides/security-headers/content-security-policy.mdx
index 79ef04b..c33ec0f 100644
--- a/docs/src/content/docs/guides/security-headers/content-security-policy.mdx
+++ b/docs/src/content/docs/guides/security-headers/content-security-policy.mdx
@@ -31,7 +31,7 @@ export default defineConfig({
   integrations: [
     shield({
       sri: {
-        enableMiddleware: true,   // MUST be enabled!
+        enableMiddleware: true,   // MUST be enabled for dynamic pages!
         hashesModule: modulePath, // SHOULD be set!
       },
 
@@ -42,6 +42,7 @@ export default defineConfig({
         // - If set, it controls how the CSP (Content Security Policy) header will
         //   be generated in the middleware.
         // - If not set, no CSP header will be generated in the middleware.
+        //   (there is no need to specify its inner options)
         contentSecurityPolicy: {
           // - If set, it controls the "default" CSP directives (they can be
           //   overriden at runtime).
@@ -65,6 +66,15 @@ export default defineConfig({
 </Aside>
 
 <Aside type="caution">
-  When enabling CSP headers, you must also set the `sri.enableMiddleware` option
-  to `true`. It is also recommended to set the `sri.hashesModule` option.
+  When enabling CSP headers, it is advisable to also set the
+  `sri.enableMiddleware` option to `true`. It is also recommended to set the
+  `sri.hashesModule` option.
+</Aside>
+
+<Aside type='tip'>
+  If you want to set CSP headers for your static content, check the specific
+  guide for your deployment platform:
+
+  - [Netlify](/guides/security-headers/netlify-static-content/)
+  - Vercel: Coming soon!
 </Aside>
diff --git a/docs/src/content/docs/guides/security-headers/netlify-static-content.mdx b/docs/src/content/docs/guides/security-headers/netlify-static-content.mdx
new file mode 100644
index 0000000..267fc76
--- /dev/null
+++ b/docs/src/content/docs/guides/security-headers/netlify-static-content.mdx
@@ -0,0 +1,68 @@
+---
+# SPDX-FileCopyrightText: 2024 KindSpells Labs S.L.
+#
+# SPDX-License-Identifier: MIT
+
+title: Configuring CSP headers for static content on Netlify
+description: How to configure the Content-Security-Policy headers of your static pages on Netlify with Astro-Shield
+---
+
+import { Aside, Code } from '@astrojs/starlight/components';
+
+Ensuring that Netlify serves your static content with the correct
+`Content-Security-Policy` headers requires some additional configuration.
+Specifically, set `securityHeaders.enableOnStaticPages.provider` to the value
+`"netlify"`.
+
+See a more complete example:
+
+<Code
+    lang="javascript"
+    code={`
+import { resolve } from 'node:path'
+
+import { defineConfig } from 'astro/config'
+import { shield } from '@kindspells/astro-shield'
+
+const rootDir = new URL('.', import.meta.url).pathname
+const modulePath = resolve(rootDir, 'src', 'generated', 'sriHashes.mjs')
+
+export default defineConfig({
+  integrations: [
+    shield({
+      sri: {
+        hashesModule: modulePath, // SHOULD be set!
+      },
+
+      // - If set, it controls how the security headers will be generated in the
+      //   middleware.
+      // - If not set, no security headers will be generated in the middleware.
+      securityHeaders: {
+        // This option is required to configure CSP headers for your static
+        // content on Netlify.
+        enableOnStaticPages: { provider: "netlify" },
+
+        // - If set, it controls how the CSP (Content Security Policy) header will
+        //   be generated in the middleware.
+        // - If not set, no CSP header will be configured for your static content.
+        //   (there is no need to specify its inner options)
+        contentSecurityPolicy: {
+          // - If set, it controls the "default" CSP directives (they can be
+          //   overriden at runtime).
+          // - If not set, the middleware will use a minimal set of default
+          //   directives.
+          cspDirectives: {
+            'default-src': "'none'",
+          }
+        }
+      }
+    })
+  ]
+})
+`}
+/>
+
+<Aside type='tip'>
+  To see how to configure CSP headers for your dynamic content, check the page
+  [Content-Security-Policy (CSP)](/guides/security-headers/content-security-policy/).
+</Aside>