Merge pull request #130 from Baroshem/0.13.0

0.13.0
nuxt-modules · Mar 21, 2023 · 87afdec · 87afdec · vercel · Mar 21, 2023
2 parents dc0192b + ec61db1
commit 87afdec
Show file tree

Hide file tree

Showing 55 changed files with 1,520 additions and 653 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -38,8 +38,8 @@ jobs:
       - name: Lint
         run: yarn lint
 
-      # - name: Test
-      #   run: yarn test
+      - name: Test
+        run: yarn test
 
       # - name: Coverage
       #   run: yarn codecov

diff --git a/.stackblitz/nuxt.config.ts b/.stackblitz/nuxt.config.ts
@@ -1,7 +1,7 @@
 // https://v3.nuxtjs.org/api/configuration/nuxt.config
 export default defineNuxtConfig({
   modules: ['nuxt-security'],
-  // Following configuration is only necessary to make Stackblitz work correctly. 
+  // Following configuration is only necessary to make Stackblitz work correctly.
   // For local projects, you do not need any configuration to try it out.
   security: {
     headers: {

diff --git a/README.md b/README.md
@@ -22,9 +22,7 @@
 - Request Size & Rate Limiters
 - Cross Site Scripting (XSS) Validation
 - Cross-Origin Resource Sharing (CORS) support
-- Allowed HTTP Methods Restricter
-- `[Optional]` Basic Auth support
-- `[Optional]` CSRF support
+- `[Optional]` Allowed HTTP Methods, Basic Auth, CSRF
 
 ## Usage
 

diff --git a/docs/content/1.getting-started/1.setup.md b/docs/content/1.getting-started/1.setup.md
@@ -35,26 +35,14 @@ export default defineNuxtConfig({
 That's it! The Nuxt Security module will now register routeRoules and middlewares to make your application more secure ✨
 ::
 
-## Static site generation (SSG)
-
-This module is meant to work with SSR apps but you can also use this module in SSG apps where you will get a Content Security Policy (CSP) support.
-
 ::alert{type="info"}
-You can find more about configuring Content Security Policy (CSP) [here](/security/headers#content-security-policy).
+You can find more about configuring `nuxt-security` [here](/getting-started/configuration).
 ::
 
-## Configuration
-
-You can add configuration to the module like following:
+## Static site generation (SSG)
 
-```js{}[nuxt.config.ts]
-export default defineNuxtConfig({
-  security: {
-    // options
-  }
-})
-```
+This module is meant to work with SSR apps but you can also use this module in SSG apps where you will get a Content Security Policy (CSP) support.
 
 ::alert{type="info"}
-You can find more about configuring `nuxt-security` [here](/getting-started/configuration).
+You can find more about configuring Content Security Policy (CSP) [here](/security/headers#content-security-policy).
 ::
diff --git a/docs/content/1.getting-started/2.configuration.md b/docs/content/1.getting-started/2.configuration.md
@@ -1,54 +1,100 @@
 ---
 title: Configuration
-description: ''
+description: ""
 ---
 
-The module by default will register middlewares and route roules to make your application more secure. If you need, you can also modify or disable any of middlewares/routes if you do not need them 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** middlewares 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).
 
-You can add configuration to the module like following:
+You can add **global** configuration to the module like following:
 
 ```js{}[nuxt.config.ts]
 export default defineNuxtConfig({
   security: {
-    requestSizeLimiter: {
-      value: {
-        maxRequestSizeInBytes: 3000000,
-        maxUploadFileRequestInBytes: 9000000,
-      },
-      route: '/upload-file'
+    rateLimiter: {
+      tokensPerInterval: 2,
+      interval: 'hour',
+    }
+  }
+})
+```
+
+You can disable them from the module configuration like following:
+
+```js{}[nuxt.config.ts]
+export default defineNuxtConfig({
+  security: {
+    rateLimiter: false
+  }
+})
+```
+
+In general, the `security` object in nuxt configuration should be used to register functionality that will be used **globally** in your application. For per route configuration, check out the next section.
+
+## Per route middleware configuration
+
+By default, middlewares are configured to work globally, but you can easily configure them per route by using `routeRules`:
+
+```js{}[nuxt.config.ts]
+export default defineNuxtConfig({
+  routeRules: {
+    '/custom-route': {
+      security: {
+        rateLimiter: {
+          tokensPerInterval: 2,
+          interval: 'hour',
+        }
+      }
+    }
+  }
+})
+```
+
+By adding this you will have global middleware for all routes (regarding rate limiting) and specific configuration to the `/custom-route` route.
+
+You can also disable certain middlewares per route like following:
+
+```js{}[nuxt.config.ts]
+export default defineNuxtConfig({
+  routeRules: {
+    '/custom-route': {
+      security: {
+        rateLimiter: false
+      }
     }
-    // Other options
   }
 })
 ```
 
 ## Configuration Types
 
-Each middleware configuration object is build using same TS type:
+::alert{type="warning"}
+The following previous interface for registering middlewares is now deprecated due to the introduction of `per-route` configuration.
 
 ```ts
 type MiddlewareConfiguration<MIDDLEWARE> = {
   value: MIDDLEWARE;
   route: string;
-}
+};
 ```
 
-* `value` is the value of certain header or middleware. It may be a simple string or an object depending on the method.
-* `route` is the route that should this header or middleware be attached to. By default for routeRoules (headers) the route is `/**` and for middlewares is `''` (empty string) -> global middleware.
+Make sure to use the `security` object in `nuxt.config.ts` to register global functionality and `routeRules` for per-route configuration.
+
+::
 
 All module configuration is the following type:
 
 ```ts
 interface ModuleOptions {
   headers: SecurityHeaders | false;
-  requestSizeLimiter: MiddlewareConfiguration<RequestSizeLimiter> | false;
-  rateLimiter: MiddlewareConfiguration<RateLimiter> | false;
-  xssValidator: MiddlewareConfiguration<XssValidator> | false;
-  corsHandler: MiddlewareConfiguration<CorsOptions> | false;
-  allowedMethodsRestricter: MiddlewareConfiguration<AllowedHTTPMethods> | false;
+  requestSizeLimiter: RequestSizeLimiter | false;
+  rateLimiter: RateLimiter | false;
+  xssValidator: XssValidator | false;
+  corsHandler: CorsOptions | false;
+  allowedMethodsRestricter: AllowedHTTPMethods | false;
   hidePoweredBy: boolean;
-  basicAuth: MiddlewareConfiguration<BasicAuth> | boolean;
+  basicAuth: BasicAuth | boolean;
   enabled: boolean;
+  csrf: CsrfOptions | boolean;
 }
 ```
 
@@ -61,127 +107,67 @@ This module will by default set the following configuration options to enable mi
 ```ts
 security: {
   headers: {
-    crossOriginResourcePolicy: {
-      value: 'same-origin',
-      route: '/**'
-    },
-    crossOriginOpenerPolicy: {
-      value: 'same-origin',
-      route: '/**'
-    },
-    crossOriginEmbedderPolicy: {
-      value: 'require-corp',
-      route: '/**'
-    },
+    crossOriginResourcePolicy: 'same-origin',
+    crossOriginOpenerPolicy: 'same-origin',
+    crossOriginEmbedderPolicy: 'require-corp',
     contentSecurityPolicy: {
-      value: {
-        'base-uri': ["'self'"],
-        'font-src': ["'self'", 'https:', 'data:'],
-        'form-action': ["'self'"],
-        'frame-ancestors': ["'self'"],
-        'img-src': ["'self'", 'data:'],
-        'object-src': ["'none'"],
-        'script-src-attr': ["'none'"],
-        'style-src': ["'self'", 'https:', "'unsafe-inline'"],
-        'upgrade-insecure-requests': true
-      },
-      route: '/**'
-    },
-    originAgentCluster: {
-      value: '?1',
-      route: '/**'
-    },
-    referrerPolicy: {
-      value: 'no-referrer',
-      route: '/**'
-    },
+      'base-uri': ["'self'"],
+      'font-src': ["'self'", 'https:', 'data:'],
+      'form-action': ["'self'"],
+      'frame-ancestors': ["'self'"],
+      'img-src': ["'self'", 'data:'],
+      'object-src': ["'none'"],
+      'script-src-attr': ["'none'"],
+      'style-src': ["'self'", 'https:', "'unsafe-inline'"],
+      'upgrade-insecure-requests': true
+    },
+    originAgentCluster: '?1',
+    referrerPolicy: 'no-referrer',
     strictTransportSecurity: {
-      value: {
-        maxAge: 15552000,
-        includeSubdomains: true
-      },
-      route: '/**'
-    },
-    xContentTypeOptions: {
-      value: 'nosniff',
-      route: '/**'
-    },
-    xDNSPrefetchControl: {
-      value: 'off',
-      route: '/**'
-    },
-    xDownloadOptions: {
-      value: 'noopen',
-      route: '/**'
-    },
-    xFrameOptions: {
-      value: 'SAMEORIGIN',
-      route: '/**'
-    },
-    xPermittedCrossDomainPolicies: {
-      value: 'none',
-      route: '/**'
-    },
-    xXSSProtection: {
-      value: '0',
-      route: '/**'
-    },
-        permissionsPolicy: {
-      value: {
-        'camera': ['()'],
-        'display-capture': ['()'],
-        'fullscreen': ['()'],
-        'geolocation': ['()'],
-        'microphone': ['()'],
-      },
-      route: '/**'
+      maxAge: 15552000,
+      includeSubdomains: true
+    },
+    xContentTypeOptions: 'nosniff',
+    xDNSPrefetchControl: 'off',
+    xDownloadOptions: 'noopen',
+    xFrameOptions: 'SAMEORIGIN',
+    xPermittedCrossDomainPolicies: 'none',
+    xXSSProtection:  '0',
+    permissionsPolicy: {
+      'camera': ['()'],
+      'display-capture': ['()'],
+      'fullscreen': ['()'],
+      'geolocation': ['()'],
+      'microphone': ['()'],
     }
   },
   requestSizeLimiter: {
-    value: {
       maxRequestSizeInBytes: 2000000,
       maxUploadFileRequestInBytes: 8000000,
-    },
-    route: '',
-    throwError?: true,
   },
   rateLimiter: {
     // Twitter search rate limiting
-    value: {
       tokensPerInterval: 150,
       interval: "hour",
       fireImmediately: true,
-    },
-    route: '',
-    throwError?: true,
-  },
-  xssValidator: {
-    value: {},
-    route: '',
-    throwError?: true,
   },
+  xssValidator: {},
   corsHandler: {
-    value: {
-      origin: '*',
-      methods: ['GET','HEAD','PUT','PATCH','POST','DELETE'],
-      preflight: {
-        statusCode: 204
-      }
-    },
-    route: '',
-  },
-  allowedMethodsRestricter: {
-    value: '*',
-    route: '',
-    throwError?: true,
+    origin: '*',
+    methods: ['GET','HEAD','PUT','PATCH','POST','DELETE'],
+    preflight: {
+      statusCode: 204
+    }
   },
+  allowedMethodsRestricter: '*',
   hidePoweredBy: true,
   basicAuth: false,
   enabled: true,
+  csrf: false,
 }
 ```
 
-To read more about every security middleware, go to that middleware page in middlewares section.
+To read more about every security middleware, go to that middleware page in `security` section.
 
 ## Using with Nuxt DevTools
 
@@ -192,10 +178,7 @@ export default defineNuxtConfig({
   modules: ['nuxt-security', '@nuxt/devtools'],
   security: {
     headers: {
-      crossOriginEmbedderPolicy: {
-        value: process.env.NODE_ENV === 'development' ? 'unsafe-none' : 'require-corp',
-        route: '/**',
-      }
+      crossOriginEmbedderPolicy: process.env.NODE_ENV === 'development' ? 'unsafe-none' : 'require-corp',
     },
   },
 });

diff --git a/docs/content/1.index.md b/docs/content/1.index.md
@@ -30,8 +30,6 @@ Security Module for Nuxt based on OWASP Top 10 and Helmet
     - Request Size & Rate Limiters
     - Cross Site Scripting (XSS) Validation
     - Cross-Origin Resource Sharing (CORS) support
-    - Allowed HTTP Methods Restricter
-    - `[Optional]` Basic Auth support
-    - `[Optional]` CSRF support
+    - `[Optional]` Allowed HTTP Methods, Basic Auth, CSRF
   ::
 ::