Merge remote-tracking branch 'origin/main' into pr/404

.stackblitz/package.json

@@ -11,6 +11,6 @@
     "nuxt": "3.9.3"
   },
   "dependencies": {
-    "nuxt-security": "^1.3.2"
+    "nuxt-security": "^1.4.2"
   }
 }

.stackblitz/yarn.lock

@@ -4296,10 +4296,10 @@ nuxt-csurf@^1.5.1:
     defu "^6.1.4"
     uncsrf "^1.1.1"
 
-nuxt-security@^1.3.2:
-  version "1.3.2"
-  resolved "https://registry.yarnpkg.com/nuxt-security/-/nuxt-security-1.3.2.tgz#0cd6bf1fa0f7e6f00875c8ccf2c99d201b12daf8"
-  integrity sha512-S585sJXWSiscne4BgixaWfT5uhY7ywEMxLY9e9y/Fbh8HeTIKPd7xSjPxh67FHqyO1yimwbgJcre3wdvRnicoQ==
+nuxt-security@^1.4.2:
+  version "1.4.2"
+  resolved "https://registry.yarnpkg.com/nuxt-security/-/nuxt-security-1.4.2.tgz#8ebff7b36c42373192322f6c115e80195c8daa26"
+  integrity sha512-0rxruaiKcSXqZS9bEQuXTzUMfw3Jd73Kx+AtqT9mwsstTihPZjdaQ/125KLrnBKrH9gGSPXiCNo09TgBvgf5DQ==
   dependencies:
     "@nuxt/kit" "^3.11.2"
     basic-auth "^2.0.1"

docs/components/content/Illustration.vue

@@ -227,7 +227,10 @@
         filterUnits="userSpaceOnUse"
         color-interpolation-filters="sRGB"
       >
-        <feFlood flood-opacity="0" result="BackgroundImageFix" />
+        <feFlood
+          flood-opacity="0"
+          result="BackgroundImageFix"
+        />
         <feColorMatrix
           in="SourceAlpha"
           type="matrix"
@@ -236,7 +239,10 @@
         />
         <feOffset dy="4" />
         <feGaussianBlur stdDeviation="2" />
-        <feComposite in2="hardAlpha" operator="out" />
+        <feComposite
+          in2="hardAlpha"
+          operator="out"
+        />
         <feColorMatrix
           type="matrix"
           values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.44 0"
@@ -262,7 +268,11 @@
         gradientUnits="userSpaceOnUse"
       >
         <stop stop-color="white" />
-        <stop offset="1" stop-color="white" stop-opacity="0" />
+        <stop
+          offset="1"
+          stop-color="white"
+          stop-opacity="0"
+        />
       </linearGradient>
       <linearGradient
         id="paint1_linear_1180_138"
@@ -273,7 +283,11 @@
         gradientUnits="userSpaceOnUse"
       >
         <stop stop-color="white" />
-        <stop offset="1" stop-color="white" stop-opacity="0" />
+        <stop
+          offset="1"
+          stop-color="white"
+          stop-opacity="0"
+        />
       </linearGradient>
       <linearGradient
         id="paint2_linear_1180_138"
@@ -284,10 +298,18 @@
         gradientUnits="userSpaceOnUse"
       >
         <stop stop-color="white" />
-        <stop offset="1" stop-color="white" stop-opacity="0" />
+        <stop
+          offset="1"
+          stop-color="white"
+          stop-opacity="0"
+        />
       </linearGradient>
       <clipPath id="clip0_1180_138">
-        <rect width="403" height="226" fill="white" />
+        <rect
+          width="403"
+          height="226"
+          fill="white"
+        />
       </clipPath>
     </defs>
   </svg>

docs/components/content/Releases.vue

@@ -1,10 +1,13 @@
 <template>
   <GithubReleases v-slot="{ releases }">
-    <div v-for="release in releases" :key="release.name">
+    <div
+      v-for="release in releases"
+      :key="release.name"
+    >
       <ProseH2 :id="release.name">
         <Badge :type="release.prerelease ? 'warning' : 'info'">
-          {{ release.prerelease ? "Pre-release" : "Release" }} </Badge
-        >{{ release.name }}
+          {{ release.prerelease ? "Pre-release" : "Release" }}
+        </Badge>{{ release.name }}
       </ProseH2>
       <details>
         <summary>

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

@@ -6,7 +6,7 @@ Nuxt Security is configured with sensible defaults.
 
 :ellipsis{right=0px width=75% blur=150px}
 
-The module by default will register **global** middleware and route roules to make your application more secure. You can also modify or disable any of middlewares/routes or your project cannot use them (i.e. some Statically Generated websites will not be able to use middlewares).
+The module by default will register **global** middleware and route rules to make your application more secure. You can also modify or disable any of middlewares/routes or your project cannot use them (i.e. some Statically Generated websites will not be able to use middlewares).
 
 ## Types
 

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

@@ -14,9 +14,9 @@ Nuxt Security by default registers a set of **global** Nuxt `routeRules` that wi
 
 ## Global configuration
 
-To override default behavior for Nuxt Security globally, follow this pattern:
+To override the default behavior for Nuxt Security globally, follow this pattern:
 
-```ts
+```ts{}[nuxt.config.ts]
 export default defineNuxtConfig({
   security: {
     headers: {
@@ -36,7 +36,7 @@ export default defineNuxtConfig({
 
 To enable per-route configuration, use the `routeRules` like following:
 
-```ts
+```ts{}[nuxt.config.ts]
 export default defineNuxtConfig({
   routeRules: {
     '/custom-route': {
@@ -74,11 +74,96 @@ If your application defines conflicting headers at both levels, the `security` p
 
 For more information on `routeRules` please see the [Nuxt documentation](https://nuxt.com/docs/guide/concepts/rendering#hybrid-rendering)
 
-## Nested route configuration
 
-Nuxt Security will recursively resolve nested routes using your `routeRules` definitions:
+## Runtime hooks
 
-```ts
+If you need to change the configuration at runtime, it is possible to do it through the `nuxt-security:routeRules` hook.
+
+In order to use the runtime hooks feature, you will need to create a Nitro plugin.
+
+In the `server/plugins` directory, create a new file with the name of your choice:
+
+```ts{}[server/plugins/filename.ts]
+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'] = { 
+      headers: {
+        contentSecurityPolicy: {
+          "connect-src": ["'self'", validDomain]
+        },
+        xFrameOptions: false
+      },
+      hidePoweredBy: false
+    }
+  })
+})
+```
+
+## Configuration priority order
+
+Nuxt-Security applies your rules in the following prority order:
+
+
+1. Default rules
+
+  Nuxt-Security default values.
+  See [here](/documentation/getting-started/configuration#default)
+
+
+2. Inline module options
+
+  ```ts{}[nuxt.config.ts]
+  export default defineNuxtConfig({
+    modules: [
+      ['nuxt-security', { /* Inline Options */ }]
+    ]
+  })
+  ```
+
+
+3. Global module options
+
+  ```ts{}[nuxt.config.ts]
+  export default defineNuxtConfig({
+    security: {
+      // Global Options
+    }
+  })
+  ```
+
+4. Per-route options
+
+  ```ts{}[nuxt.config.ts]
+  export default defineNuxtConfig({
+    routeRules: {
+      '/some-route': {
+        security: {
+          // Per-route Options
+        }
+      }
+    }
+  })
+  ```
+
+5. Runtime-hook options
+
+  ```ts{}[server/plugins/filename.ts]
+  export default defineNitroPlugin((nitroApp) => {
+    nitroApp.hooks.hook('nuxt-security:routeRules', routeRules => {
+      // Runtime Options
+    })
+  })
+  ```
+
+
+## Route merging strategy (nested router)
+
+If you define nested route rules in your `routeRules` definitions, Nuxt Security will recursively merge the options to resolve the security rules of a given route:
+
+```ts{}[nuxt.config.ts]
 export default defineNuxtConfig({
   // Global
   security: {
@@ -146,7 +231,7 @@ experimental: {
 
 To disable certain middleware or headers, follow this pattern:
 
-```ts
+```ts{}[nuxt.config.ts]
 export default defineNuxtConfig({
   // global
   security: {
@@ -170,40 +255,32 @@ export default defineNuxtConfig({
 })
 ```
 
-## Runtime configuration
 
-If you need to change the headers configuration at runtime, it is possible to do it through `nuxt-security:headers` hook.
+## Overwriting or modifying existing values
 
-### Enabling the option
+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`:
 
-This feature is optional, you can enable it with
+```ts{}[server/plugins/filename.ts]
+import defu from 'defu'
 
-```ts
-export default defineNuxtConfig({
-    modules: ['nuxt-security'],
-    security: {
-        runtimeHooks: true
-    }
-})
-```
-
-### Usage
-
-Within your nitro plugin. You can override the previous configuration of a route with `nuxt-security:headers`.
-
-```ts
 export default defineNitroPlugin((nitroApp) => {
-    nitroApp.hooks.hook('nuxt-security:ready', () => {
-        nitroApp.hooks.callHook('nuxt-security:headers',
-        { 
-            route: '/**',
-            headers: {
-                contentSecurityPolicy: {
-                    "script-src": ["'self'", "'unsafe-inline'"],
-                },
-                xFrameOptions: false
-            }
-        })
-    })
+  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'] = defu(
+      { 
+        headers: {
+          contentSecurityPolicy: {
+            "connect-src": ["'self'", validDomain]
+          },
+          xFrameOptions: false
+        },
+        hidePoweredBy: false
+      },
+      routeRules['/some/route']
+    )
+  })
 })
 ```