Merge pull request #448 from Baroshem/chore/2.0.0-rc.1

Chore/2.0.0 rc.1

Author: vejja

docs/content/1.documentation/1.getting-started/2.configuration.md

@@ -117,7 +117,9 @@ security: {
   ssg: {
     meta: true,
     hashScripts: true,
-    hashStyles: false
+    hashStyles: false,
+    nitroHeaders: true,
+    exportToPresets: true,
   },
   sri: true
 }

docs/content/1.documentation/1.getting-started/3.usage.md

@@ -102,6 +102,12 @@ export default defineNitroPlugin((nitroApp) => {
 })
 ```
 
+::alert{type="warning"}
+Runtime-hook configuration only applies to headers delivered on HTML pages.
+<br>
+Headers delivered on other resources (e.g. images, js and css files, api routes etc.) are not modifiable via runtime hooks.
+::
+
 ## Configuration priority order
 
 Nuxt-Security applies your rules in the following prority order:
@@ -256,31 +262,95 @@ export default defineNuxtConfig({
 ```
 
 
-## Overwriting or modifying existing values
+## Modifying security options
 
-Within your runtime hooks, you can either overwrite or modify the existing values for any security option.
-One of the easiest way to merge existing rules with your own is to use `defu`:
+Within your runtime hooks, you can either modify or overwrite the existing values for any security option.
+
+### Merging with replacement
+
+One of the easiest way to merge existing rules with your own is to use `defuReplaceArray`:
 
 ```ts{}[server/plugins/filename.ts]
-import defu from 'defu'
+// You don't need to import defuReplaceArray as it is auto-imported by Nuxt Security
 
 export default defineNitroPlugin((nitroApp) => {
   nitroApp.hooks.hook('nuxt-security:routeRules', async(routeRules) => {
-    // You can fetch configuration data asynchronously from an external source
-    const validDomain = await $fetch('https://some-site.com/rules')
-    // You can then override the security options of any route
+    routeRules['/some/route'] = defuReplaceArray(
+      { 
+        headers: {
+          contentSecurityPolicy: {
+            "script-src": ["'self'", "..."]
+            // The script-src directive will be replaced with "'self' ..."
+          }
+        }
+      },
+      routeRules['/some/route'] // The other existing rules for /some/route will be preserved
+    )
+  })
+})
+```
+
+In the example above, 
+- All existing security options for `/some/route` will be maintained, and only the `script-src` CSP directive will be modified. 
+- The existing content of the `script-src` directive will be erased and replaced by your values
+
+Read more about [`defuReplaceArray`](/documentation/advanced/auto-imports/#defuReplaceArray)
+
+::alert{type="info"}
+`defuReplaceArray` is auto-imported by Nuxt Security. You can use this utility anywhere in your /server folder.
+::
+
+### Merging with addition
+
+If you want to add additional values to the existing settings, you can use the standard `defu` utility to merge your rules.
+
+```ts{}[server/plugins/filename.ts]
+// You will need to import defu
+import { defu } from 'defu'
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('nuxt-security:routeRules', async(routeRules) => {
     routeRules['/some/route'] = defu(
       { 
         headers: {
           contentSecurityPolicy: {
-            "connect-src": ["'self'", validDomain]
-          },
-          xFrameOptions: false
-        },
-        hidePoweredBy: false
+            "script-src": ["'self'", "..."]
+            // The values "'self' ..." will be added to the existing values
+          }
+        }
       },
-      routeRules['/some/route']
+      routeRules['/some/route'] // The other existing rules for /some/route will be preserved
     )
   })
 })
 ```
+
+In the example above, 
+- All existing security options for `/some/route` will be maintained, and only the `script-src` CSP directive will be modified. 
+- The existing content of the `script-src` directive will be preserved, and your values will be added to the existing values.
+
+Read more about [`defu`](https://github.com/unjs/defu)
+
+
+### Overwriting rules
+
+If you want to erase the existing settings, don't use defu and overwrite the values:
+
+```ts{}[server/plugins/filename.ts]
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('nuxt-security:routeRules', async(routeRules) => {
+    routeRules['/some/route'] = { 
+      headers: {
+        contentSecurityPolicy: {
+          "script-src": ["'self'", "..."]
+        }
+      }
+    }
+    // Any existing rules for /some/route will be erased
+  })
+})
+```
+
+In the example above, 
+- All existing security options for `/some/route` will be erased. 
+- The `script-src` directive will contain your values.
+

docs/content/1.documentation/2.headers/1.csp.md

@@ -75,7 +75,6 @@ contentSecurityPolicy: {
   'sandbox'?: CSPSandboxValue[] | false;
   'form-action'?: CSPSourceValue[] | false;
   'frame-ancestors'?: ("'self'" | "'none'" | string)[] | false;
-  'navigate-to'?: ("'self'" | "'none'" | "'unsafe-allow-redirects'" | string)[] | false;
   'report-uri'?: string[] | false;
   'report-to'?: string | false;
   'upgrade-insecure-requests'?: boolean;
@@ -255,6 +254,7 @@ export default defineNuxtConfig({
       meta: true, // Enables CSP as a meta tag in SSG mode
       hashScripts: true, // Enables CSP hash support for scripts in SSG mode
       hashStyles: false // Disables CSP hash support for styles in SSG mode (recommended)
+      exportToPresets: true // Export security headers to Nitro presets
     },
     sri: true,
     headers: {

docs/content/1.documentation/5.advanced/2.faq.md

@@ -385,7 +385,6 @@ If you want to expose your app in local network to test it by using other device
 security: {
     headers: {
       crossOriginEmbedderPolicy: process.env.NODE_ENV === 'development' ? 'unsafe-none' : 'require-corp', //https://github.com/Baroshem/nuxt-security/issues/101
-      strictTransportSecurity: true,
       contentSecurityPolicy: {
         "upgrade-insecure-requests": process.env.NODE_ENV === 'development' ? false : true // USE ONLY IN DEV MODE
       }

docs/content/1.documentation/5.advanced/3.strict-csp.md

@@ -669,16 +669,42 @@ Nuxt Security uses a different approach, depending on whether SSR or SSG is used
 
 **CSP Headers for SSG via Nitro Presets**
 
+Nuxt Security supports CSP via HTTP headers for Nitro Presets that generate HTTP headers.
+
 When using the SSG mode, some static hosting services such as Vercel or Netlify provide the ability to specify a configuration file that governs the value of the headers that will be generated. When these hosting services benefit from a [Nitro Preset](https://nitro.unjs.io/deploy/#overview), it is possible for Nuxt Security to predict the value of the CSP headers for each page and write the value to the configuration file.
 
-Nuxt Security supports CSP via HTTP headers for Nitro Presets that output HTTP headers.
+This feature is enabled by default with the `ssg: exportToPresets` option.
 
 ::alert{type="info"}
 If you deploy your SSG site on Vercel or Netlify, you will benefit automatically from CSP Headers.
 <br>
 CSP will be delivered via HTTP headers, in addition to the standard `<meta http-equiv>` approach. If you want to disable the meta tag, so that only the HTTP headers are used, you can do so with the `ssg: meta` option.
 ::
 
+**CSP Headers for SSG via `prerenderedHeaders` hook**
+
+Nuxt Security allows you to generate your own headers rules with the `nuxt-security:prerenderedHeaders` buildtime hook.
+
+If you do not deploy with a Nitro preset, or if you have specific requirements that are not met by the `ssg: exportToPresets` default, you can use this hook to generate your headers configuration file yourself.
+
+See our documentation on the [prerenderedPages hook](/documentation/advanced/hooks/#prerendered-headers-hook)
+
+::alert{type="info"}
+This will allow you to deliver CSP via HTTP headers, in addition to the standard `<meta http-equiv>` approach.
+::
+
+**CSP Headers for Hybrid Pre-Rendered Pages**
+
+Nuxt Security supports CSP via HTTP headers for pre-rendered pages of Hybrid applications.
+
+This feature is enabled by default with the `ssg: nitroHeaders` option.
+
+::alert{type="info"}
+In Hybrid applications, CSP of pre-rendered pages will be delivered via HTTP headers, in addition to the standard `<meta http-equiv>` approach.
+<br>
+If you want to disable the meta tag, so that only the HTTP headers are used, you can do so with the `ssg: meta` option.
+::
+
 ### Per Route CSP
 
 Nuxt Security gives you the ability to define per-route CSP. For instance, you can have Strict CSP on the admin section of your application, and a more relaxed policy on the blog section.
@@ -718,6 +744,8 @@ export default defineNuxtConfig({
       meta: true, // Enables CSP as a meta tag in SSG mode
       hashScripts: true, // Enables CSP hash support for scripts in SSG mode
       hashStyles: false // Disables CSP hash support for styles in SSG mode (recommended)
+      nitroHeaders: true // Allow Nitro to serve security headers for pre-rendered routes 
+      exportToPresets: true // Export pre-rendered security headers to Nitro presets
     },
     // You can use nonce and ssg simultaneously
     // Nuxt Security will take care of choosing the adequate parameters when you build for either SSR or SSG