Merge pull request #483 from Baroshem/vejja/issue470

feat(core): introduce `strict` mode

Author: vejja

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

@@ -14,6 +14,7 @@ All module configuration is the following type:
 
 ```ts
 interface ModuleOptions {
+  strict: boolean;
   headers: SecurityHeaders | false;
   requestSizeLimiter: RequestSizeLimiter | false;
   rateLimiter: RateLimiter | false;
@@ -33,76 +34,49 @@ interface ModuleOptions {
 
 All above `ModuleOptions` are explained in more details in the next sections.
 
-## Default
+## Defaults
 
-This module will by default set the following configuration options to enable middlewares and route roules:
+This module will automatically set default values for each option. 
+
+By default, this module chooses reasonable defaults that ensure that your application will not break. The following configuration options are set:
 
 ```ts
 security: {
+  strict: false,
   headers: {
     crossOriginResourcePolicy: 'same-origin',
     crossOriginOpenerPolicy: 'same-origin',
-    crossOriginEmbedderPolicy: 'require-corp',
+    crossOriginEmbedderPolicy: 'credentialless',
     contentSecurityPolicy: {
       'base-uri': ["'none'"],
-      'default-src' : ["'none'"],
-      'connect-src': ["'self'", 'https:'],
       'font-src': ["'self'", 'https:', 'data:'],
       'form-action': ["'self'"],
       'frame-ancestors': ["'self'"],
-      'frame-src': ["'self'"],
       'img-src': ["'self'", 'data:'],
-      'manifest-src': ["'self'"],
-      'media-src': ["'self'"],
       'object-src': ["'none'"],
       'script-src-attr': ["'none'"],
       'style-src': ["'self'", 'https:', "'unsafe-inline'"],
       'script-src': ["'self'", 'https:', "'unsafe-inline'", "'strict-dynamic'", "'nonce-{{nonce}}'"],
-      'upgrade-insecure-requests': true,
-      'worker-src': ["'self'"],
+      'upgrade-insecure-requests': true
     },
     originAgentCluster: '?1',
     referrerPolicy: 'no-referrer',
     strictTransportSecurity: {
-      maxAge: 31536000,
-      includeSubdomains: true
+      maxAge: 15552000,
+      includeSubdomains: true,
     },
     xContentTypeOptions: 'nosniff',
     xDNSPrefetchControl: 'off',
     xDownloadOptions: 'noopen',
-    xFrameOptions: 'DENY',
+    xFrameOptions: 'SAMEORIGIN',
     xPermittedCrossDomainPolicies: 'none',
     xXSSProtection: '0',
     permissionsPolicy: {
-      accelerometer: [],
-      'ambient-light-sensor':[],
-      autoplay:[],
-      battery:[],
-      camera:[],
-      'display-capture':[],
-      'document-domain':[],
-      'encrypted-media':[],
-      fullscreen:[],
-      gamepad:[],
-      geolocation:[],
-      gyroscope:[],
-      'layout-animations':['self'],
-      'legacy-image-formats':['self'],
-      magnetometer:[],
-      microphone:[],
-      midi:[],
-      'oversized-images':['self'],
-      payment:[],
-      'picture-in-picture':[],
-      'publickey-credentials-get':[],
-      'speaker-selection':[],
-      'sync-xhr':['self'],
-      'unoptimized-images':['self'],
-      'unsized-media':['self'],
-      usb:[],
-      'screen-wake-lock':[],
-      'web-share':[],
-      'xr-spatial-tracking':[]
+      camera: [],
+      'display-capture': [],
+      fullscreen: [],
+      geolocation: [],
+      microphone: []
     }
   },
   requestSizeLimiter: {
@@ -155,7 +129,9 @@ security: {
 }
 ```
 
-To read more about every security middleware, go to that middleware page in `security` section.
+::alert{type="warning"}
+To modify these default settings and further increase the security of your application, read about our `strict` mode and our user-friendly approach on how to [Improve Security](/documentation/advanced/improve-security)
+::
 
 ## Overriding a layer's configuration
 

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

@@ -42,10 +42,10 @@ You can also disable this header by `contentSecurityPolicy: false`.
 
 ## Default value
 
-By default, Nuxt Security will set following value for this header:
+By default, Nuxt Security will set the following value for this header:
 
 ```http
-Content-Security-Policy: base-uri 'none'; default-src 'none'; connect-src 'self' https:; font-src 'self' https: data:; form-action 'self'; frame-ancestors 'self'; frame-src 'self'; img-src 'self' data:; manifest-src 'self'; media-src 'self'; object-src 'none'; script-src-attr 'none'; style-src 'self' https: 'unsafe-inline'; script-src 'self' https: 'unsafe-inline' 'strict-dynamic' 'nonce-{{nonce}}'; upgrade-insecure-requests; worker-src 'self';
+Content-Security-Policy: base-uri 'none'; font-src 'self' https: data:; form-action 'self'; img-src 'self' data:; object-src 'none'; script-src-attr 'none'; style-src 'self' https: 'unsafe-inline'; script-src 'self' https: 'unsafe-inline' 'strict-dynamic' 'nonce-{{nonce}}'; upgrade-insecure-requests;
 ```
 
 ## Available values
@@ -161,8 +161,6 @@ export default defineNuxtConfig({
           "'unsafe-inline'" // Recommended default for most Nuxt apps
         ],
         'base-uri': ["'none'"],
-        'default-src': ["'self'"],
-        'connect-src': ["'self'", 'https:'],
         'img-src': ["'self'", "data:"], // Add relevant https://... sources if you load images from external sources 
         'font-src': ["'self'", "https:", "data:"], //  For increased security, replace by the specific sources for fonts
         'object-src': ["'none'"],

docs/content/1.documentation/2.headers/10.xDNSPrefetchControl.md

@@ -42,7 +42,7 @@ You can also disable this header by `xDNSPrefetchControl: false`.
 
 ## Default value
 
-By default, Nuxt Security will set following value for this header.
+By default, Nuxt Security will set the following value for this header.
 
 ```http
 X-DNS-Prefetch-Control: off

docs/content/1.documentation/2.headers/11.xDownloadOptions.md

@@ -42,7 +42,7 @@ You can also disable this header by `xDownloadOptions: false`.
 
 ## Default value
 
-By default, Nuxt Security will set following value for this header.
+By default, Nuxt Security will set the following value for this header.
 
 ```http
 X-Download-Options: noopen

docs/content/1.documentation/2.headers/12.xFrameOptions.md

@@ -42,7 +42,7 @@ You can also disable this header by `xFrameOptions: false`.
 
 ## Default value
 
-By default, Nuxt Security will set following value for this header.
+By default, Nuxt Security will set the following value for this header.
 
 ```http
 X-Frame-Options: SAMEORIGIN

docs/content/1.documentation/2.headers/13.xPermittedCrossDomainPolicies.md

@@ -42,7 +42,7 @@ You can also disable this header by `xPermittedCrossDomainPolicies: false`.
 
 ## Default value
 
-By default, Nuxt Security will set following value for this header.
+By default, Nuxt Security will set the following value for this header.
 
 ```http
 X-Permitted-Cross-Domain-Policies: none

docs/content/1.documentation/2.headers/14.xXSSProtection.md

@@ -42,7 +42,7 @@ You can also disable this header by `xXSSProtection: false`.
 
 ## Default value
 
-By default, Nuxt Security will set following value for this header.
+By default, Nuxt Security will set the following value for this header.
 
 ```http
 X-XSS-Protection: 0

docs/content/1.documentation/2.headers/2.permissions-policy.md

@@ -54,10 +54,10 @@ export default defineNuxtConfig({
 
 ## Default value
 
-By default, Nuxt Security will set following value for this header.
+By default, Nuxt Security will set the following value for this header:
 
 ```http
-Permissions-Policy: accelerometer=(), autoplay=(), camera=(), display-capture=(), encrypted-media=(), fullscreen=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), midi=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(self), usb=(), web-share=(), xr-spatial-tracking=()
+Permissions-Policy: camera=(), display-capture=(), fullscreen=(), geolocation=(), microphone=()
 ```
 
 ## Available values

docs/content/1.documentation/2.headers/3.crossOriginEmbedderPolicy.md

@@ -44,10 +44,10 @@ You can also disable this header by `crossOriginEmbedderPolicy: false`.
 
 ## Default value
 
-By default, Nuxt Security will set following value for this header.
+By default, Nuxt Security will set the following value for this header.
 
 ```http
-Cross-Origin-Embedder-Policy: require-corp
+Cross-Origin-Embedder-Policy: credentialless
 ```
 
 ## Available values
@@ -73,3 +73,27 @@ no-cors cross-origin requests are sent without credentials. In particular, it me
 ::alert{type="warning"}
 ⚠️ Read more about `Avoiding blockage with CORS` [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy#avoiding_coep_blockage_with_cors).
 ::
+
+## Cross-Origin Isolation issues
+
+Setting cross-origin isolation by using the COEP header can sometimes have tricky consequences. This is because the COEP/COOP specification requires **both** your application **and** the embedded resource to set corresponding headers properly. If only one of the two parties does not set the headers properly, the frame can be blocked.
+
+As a consequence, in order to avoid being blocked in websites that do not have COEP/COOP headers, some major third-party providers have chosen to _not_ deliver COEP/COOP headers. This in turn prevents you from using COEP in your application! If you want some background, please read the [excellent blog note from Stackblitz that explains their decision](https://blog.stackblitz.com/posts/cross-browser-with-coop-coep/).
+
+If you encounter this situation, you will be left with a tough dilemna:
+- If you choose to apply the `require-corp` option, the embedded resource will be blocked _if it does not deliver the proper headers_.
+- If you choose to apply the `unsafe-none` option, the embedded resource will not be cross-origin isolated and therefore _might not work properly_.
+
+This is the reason why we use the `credentialless` option by default, which is a reasonable fallback. 
+However even with this setting, you might encounter difficulties. 
+
+1. Inspect COEP/COOP issues in your browser's Developer Tools:
+
+  - If your console logs tell you that the Embedded Resource is blocked because it does not deliver proper COEP/COOP headers, this means that the third-party resource prevents you from using `credentialless`. In that case you might have to fallback to `unsafe-none`.
+  - If your console logs tell you that some features (e.g. SharedArrayBuffers) are blocked because your application is not cross-origin isolated, your application might still be able to run properly. If it's not the case, you might have to upgrade to `require-corp`.
+
+2. Have a look at our documentation example code
+
+Our own documentation website includes iframes from Youtube and Stackblitz.
+Please have a look at our [Github source code](https://github.com/Baroshem/nuxt-security/blob/main/docs/nuxt.config.ts) to see how we set the Nuxt Security options to allow these iframes.
+

docs/content/1.documentation/2.headers/4.crossOriginOpenerPolicy.md

@@ -44,7 +44,7 @@ You can also disable this header by `crossOriginOpenerPolicy: false`.
 
 ## Default value
 
-By default, Nuxt Security will set following value for this header.
+By default, Nuxt Security will set the following value for this header.
 
 ```http
 Cross-Origin-Opener-Policy: same-origin

docs/content/1.documentation/2.headers/5.crossOriginResourcePolicy.md

@@ -42,7 +42,7 @@ You can also disable this header by `crossOriginResourcePolicy: false`.
 
 ## Default value
 
-By default, Nuxt Security will set following value for this header.
+By default, Nuxt Security will set the following value for this header.
 
 ```http
 Cross-Origin-Resource-Policy: same-origin

docs/content/1.documentation/2.headers/6.originAgentCluster.md

@@ -42,7 +42,7 @@ You can also disable this header by `originAgentCluster: false`.
 
 ## Default value
 
-By default, Nuxt Security will set following value for this header.
+By default, Nuxt Security will set the following value for this header.
 
 ```http
 Origin-Agent-Cluster: ?1

docs/content/1.documentation/2.headers/7.referrerPolicy.md

@@ -42,7 +42,7 @@ You can also disable this header by `referrerPolicy: false`.
 
 ## Default value
 
-By default, Nuxt Security will set following value for this header.
+By default, Nuxt Security will set the following value for this header.
 
 ```http
 Referrer-Policy: no-referrer

docs/content/1.documentation/2.headers/8.strictTransportSecurity.md

@@ -42,7 +42,7 @@ You can also disable this header by `strictTransportSecurity: false`.
 
 ## Default value
 
-By default, Nuxt Security will set following value for this header.
+By default, Nuxt Security will set the following value for this header.
 
 ```http
 Strict-Transport-Security: max-age=15552000; includeSubDomains;

docs/content/1.documentation/2.headers/9.xContentTypeOptions.md

@@ -42,7 +42,7 @@ You can also disable this header by `xContentTypeOptions: false`.
 
 ## Default value
 
-By default, Nuxt Security will set following value for this header.
+By default, Nuxt Security will set the following value for this header.
 
 ```http
 X-Content-Type-Options: nosniff