diff --git a/docs/.env.example b/docs/.env.example new file mode 100644 index 00000000..d8e52d7b --- /dev/null +++ b/docs/.env.example @@ -0,0 +1,5 @@ +# To use Nuxt UI Pro in production +NUXT_UI_PRO_LICENSE= + +# Used when pre-rendering the docs for dynamic OG images +NUXT_PUBLIC_SITE_URL= diff --git a/docs/.gitignore b/docs/.gitignore old mode 100755 new mode 100644 index 75fb65a5..69f6b69d --- a/docs/.gitignore +++ b/docs/.gitignore @@ -10,4 +10,3 @@ dist sw.* .env .output -yarn.lock diff --git a/docs/.npmrc b/docs/.npmrc index bf2e7648..cf040424 100644 --- a/docs/.npmrc +++ b/docs/.npmrc @@ -1 +1,2 @@ shamefully-hoist=true +strict-peer-dependencies=false diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..de3725bf --- /dev/null +++ b/docs/README.md @@ -0,0 +1,35 @@ +# Nuxt Security docs + +Docs template with [Nuxt UI](https://ui.nuxt.com). + +## Setup + +Install dependencies inside `docs/`: + +```bash +yarn +``` + +## Development + +```bash +yarn dev +``` + +## Static Generation + +Use the `generate` command to build your application. + +The HTML files will be generated in the .output/public directory and ready to be deployed to any static compatible hosting. + +```bash +yarn generate +``` + +## Preview build + +You might want to preview the result of your build locally, to do so, run the following command: + +```bash +yarn preview +``` diff --git a/docs/app.config.ts b/docs/app.config.ts index 1f453872..06c2b277 100644 --- a/docs/app.config.ts +++ b/docs/app.config.ts @@ -1,41 +1,28 @@ export default defineAppConfig({ - github: { - owner: 'Baroshem', - repo: 'nuxt-security', - branch: 'main' - }, - docus: { - title: 'Nuxt Security', - description: '🛡️ Security Module for Nuxt based on HTTP Headers and Middleware', - image: '/preview.jpg', - url: 'https://nuxt-security.vercel.app', - socials: { - twitter: 'jacobandrewsky', - github: 'baroshem/nuxt-security', - nuxt: { - label: 'Nuxt', - icon: 'simple-icons:nuxtdotjs', - href: 'https://nuxt.com' - } - }, - aside: { - level: 1 - }, - github: { - dir: 'docs/content', - root: 'docs/content', - edit: true, - releases: true, - owner: 'baroshem', - repo: 'nuxt-security', - branch: 'main' + ui: { + primary: 'green', + gray: 'slate', + button: { + color: { + white: { + link: 'text-white dark:text-white hover:text-gray-300 dark:hover:text-gray-300 underline-offset-4 hover:underline focus-visible:ring-inset focus-visible:ring-2 focus-visible:ring-gray-500 dark:focus-visible:ring-gray-400 transition-all duration-200', + }, + transparent: { + outline: 'ring-1 ring-inset ring-gray-700 text-white dark:text-white hover:bg-gray-900 disabled:bg-gray-300 dark:hover:bg-gray-900 dark:disabled:bg-gray-300 focus-visible:ring-2 focus-visible:ring-gray-400 dark:focus-visible:ring-gray-400', + }, + }, }, - cover: { - src: '/preview.png', - alt: 'Security Module for Nuxt based on HTTP Headers and Middleware' + }, + elements: { + variables: { + light: { + background: '255 255 255', + foreground: 'var(--color-gray-700)', + }, + dark: { + background: 'var(--color-gray-950)', + foreground: 'var(--color-gray-200)', + }, }, - header: { - logo: true - } - } + }, }) diff --git a/docs/app.vue b/docs/app.vue new file mode 100644 index 00000000..c3d8308b --- /dev/null +++ b/docs/app.vue @@ -0,0 +1,138 @@ + + + diff --git a/docs/components/content/Illustration.vue b/docs/components/Illustration.vue similarity index 100% rename from docs/components/content/Illustration.vue rename to docs/components/Illustration.vue diff --git a/docs/components/content/Logo.vue b/docs/components/Logo.vue similarity index 100% rename from docs/components/content/Logo.vue rename to docs/components/Logo.vue diff --git a/docs/components/content/Releases.vue b/docs/components/content/Releases.vue deleted file mode 100644 index da4e9ed2..00000000 --- a/docs/components/content/Releases.vue +++ /dev/null @@ -1,20 +0,0 @@ - diff --git a/docs/content/0.index.md b/docs/content/0.index.md deleted file mode 100644 index 51bcfaaa..00000000 --- a/docs/content/0.index.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -description: 🛡️ Security Module for Nuxt based on HTTP Headers and Middleware -layout: page -navigation: false ---- - -:ellipsis{right=0px width=75% blur=150px} - -::block-hero ---- -cta: - - 🚀 Get Started - - /documentation/getting-started/setup -secondary: - - Star on GitHub → - - https://github.com/baroshem/nuxt-security ---- - -#title -More Secure Nuxt Apps - by default - -#description -Automatically configure your app to follow OWASP security patterns and principles by using
HTTP Headers and Middleware. - -#support -:illustration - -:: - -::card-grid -#title -
Protect your app with
no configuration
- -#root -:ellipsis{left=0px width=40rem top=10rem blur=140px} - -#default - ::card{icon=heroicons-outline:desktop-computer} - #title - Security response headers - #description - Add security headers that will make your application more secure by default (including Content Security Policy (CSP) for SSG apps) - :: - - ::card{icon=streamline:interface-alert-warning-triangle-frame-alert-warning-triangle-exclamation-caution} - #title - Request Size & Rate Limiters - #description - Limit the amount of incoming requests and their size to protect your application against disruptions. - :: - - ::card{icon=streamline:programming-script-2-language-programming-code} - #title - Cross Site Scripting (XSS) Validation - #description - Validate `GET` & `POST` requests against malicious code sent in query or body. - :: - - ::card{icon=carbon:software-resource-cluster} - #title - Cross-Origin Resource Sharing (CORS) support - #description - Permit from what origins (domain, scheme, or port) a browser can load resources - :: - - ::card{icon=material-symbols:checklist-rtl} - #title - Allowed HTTP Methods - #description - Reject requests that do not match allow list of HTTP methods - :: - - ::card{icon=system-uicons:files-stack} - #title - Cross Site Request Forgery (CSRF) protection - #description - Protect against unwanted state change by unaware users - :: -:: - -::block-hero ---- -cta: - - 🚀 Get Started - - /documentation/getting-started/setup ---- -#title -
Discover how it helps ship
secure applications
- - -#description -Nuxt Security solves several security issues automatically by implementing Headers and Middleware accordingly to OWASP & OWASP Top 10 documents. For others, it provides optional middleware that will help you handle more advanced cases like Cross Site Request Forgery. - -#support -:video-player{src="https://www.youtube.com/watch?v=sJVeU0KGmv4"} -:: - - - diff --git a/docs/content/1.documentation/4.utils/1.hide-x-powered-by-header.md b/docs/content/1.documentation/4.utils/1.hide-x-powered-by-header.md deleted file mode 100644 index 25d6bd6e..00000000 --- a/docs/content/1.documentation/4.utils/1.hide-x-powered-by-header.md +++ /dev/null @@ -1,26 +0,0 @@ -# Hide `X-Powered-By` - -:badge[Enabled]{type="success"} Avoid leaking info about your framework. - ---- - -:ellipsis{right=0px width=75% blur=150px} - -`X-Powered-By` header is used to inform what technology is used in the server side. This is an unnecessary header causing information leakage, so it should be removed from your application. - -::alert{type="info"} -ℹ Read more about it [here](https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html#use-appropriate-security-headers). -:: - -Fortunately, `nuxt-security` module hides this header by default so your application is not leaking this information in the response headers. - -However, if you prefer not to have this changed, you can always disable this functionality from the module configuration (which is not recommended but possible) like the following: - -```js{}[nuxt.config.ts] -export default defineNuxtConfig({ - modules: ['nuxt-security'], - security: { - hidePoweredBy: false - } -}) -``` diff --git a/docs/content/1.documentation/1.getting-started/1.setup.md b/docs/content/1.getting-started/1.installation.md similarity index 77% rename from docs/content/1.documentation/1.getting-started/1.setup.md rename to docs/content/1.getting-started/1.installation.md index 1189753c..32396f9c 100644 --- a/docs/content/1.documentation/1.getting-started/1.setup.md +++ b/docs/content/1.getting-started/1.installation.md @@ -1,10 +1,9 @@ -# Installation - -Having more secure Nuxt project is only one command away ✨ - --- +title: Installation +description: Having more secure Nuxt project is only one command away ✨. +--- + -:ellipsis{right=0px width=75% blur=150px} Install `nuxt-security` module: ```bash diff --git a/docs/content/1.documentation/1.getting-started/2.configuration.md b/docs/content/1.getting-started/2.configuration.md similarity index 96% rename from docs/content/1.documentation/1.getting-started/2.configuration.md rename to docs/content/1.getting-started/2.configuration.md index 0985a9dc..c294ca28 100644 --- a/docs/content/1.documentation/1.getting-started/2.configuration.md +++ b/docs/content/1.getting-started/2.configuration.md @@ -1,10 +1,9 @@ -# Configuration - -Nuxt Security is configured with sensible defaults. - --- +title: Configuration +description: Nuxt Security is configured with sensible defaults. +--- + -:ellipsis{right=0px width=75% blur=150px} 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). @@ -124,7 +123,7 @@ security: { } ``` -::alert{type="warning"} +::callout{icon="i-heroicons-exclamation-triangle" color="amber"} 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) :: diff --git a/docs/content/1.documentation/1.getting-started/3.usage.md b/docs/content/1.getting-started/3.usage.md similarity index 94% rename from docs/content/1.documentation/1.getting-started/3.usage.md rename to docs/content/1.getting-started/3.usage.md index 4513fb21..039eae94 100644 --- a/docs/content/1.documentation/1.getting-started/3.usage.md +++ b/docs/content/1.getting-started/3.usage.md @@ -1,15 +1,14 @@ -# Usage - -Learn how to use headers and middleware both globally and per route. - --- +title: Usage +description: Learn how to use headers and middleware both globally and per route. +--- + -:ellipsis{right=0px width=75% blur=150px} Nuxt Security by default registers a set of **global** Nuxt `routeRules` that will make your application more secure by default. Both headers and middleware can be easily configured and even disabled when needed. -::alert{type="info"} -ℹ Read more about security headers [here](https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html#use-appropriate-security-headers). +::callout{icon="i-heroicons-light-bulb"} + Read more about security headers [here](https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html#use-appropriate-security-headers). :: ## Global configuration @@ -64,7 +63,7 @@ export default defineNuxtConfig({ }) ``` -::alert{type="warning"} +::callout{icon="i-heroicons-exclamation-triangle" color="amber"} When using `routeRules`, do not use the standard `headers` property to define Nuxt Security options.
Instead, make sure to use the `security` property. This is a custom NuxtSecurity addition that does not exists in core Nuxt. @@ -102,7 +101,7 @@ export default defineNitroPlugin((nitroApp) => { }) ``` -::alert{type="warning"} +::callout{icon="i-heroicons-exclamation-triangle" color="amber"} Runtime-hook configuration only applies to headers delivered on HTML pages.
Headers delivered on other resources (e.g. images, js and css files, api routes etc.) are not modifiable via runtime hooks. @@ -222,7 +221,7 @@ defineRouteRules({ ``` -::alert{type="warning"} +::callout{icon="i-heroicons-exclamation-triangle" color="amber"} To enable this macro, add the following configuration to your `nuxt.config.ts` file: ```ts @@ -296,7 +295,7 @@ In the example above, Read more about [`defuReplaceArray`](/documentation/advanced/auto-imports/#defuReplaceArray) -::alert{type="info"} +::callout{icon="i-heroicons-light-bulb"} `defuReplaceArray` is auto-imported by Nuxt Security. You can use this utility anywhere in your /server folder. :: diff --git a/docs/content/1.documentation/1.getting-started/4.contributing.md b/docs/content/1.getting-started/4.contributing.md similarity index 80% rename from docs/content/1.documentation/1.getting-started/4.contributing.md rename to docs/content/1.getting-started/4.contributing.md index bad2f3a9..789742fc 100644 --- a/docs/content/1.documentation/1.getting-started/4.contributing.md +++ b/docs/content/1.getting-started/4.contributing.md @@ -1,13 +1,12 @@ -# Contributing - -We can never thank you enough for your contributions. ❤️ - --- +title: Contributing +description: We can never thank you enough for your contributions. ❤️ +--- + -:ellipsis{right=0px width=75% blur=150px} -::alert{type="info"} -ℹ Read more about Nuxt contribution guide [here](https://nuxt.com/docs/community/contribution). +::callout{icon="i-heroicons-light-bulb"} + Read more about Nuxt contribution guide [here](https://nuxt.com/docs/community/contribution). :: ## How to contribute? diff --git a/docs/content/1.documentation/2.headers/1.csp.md b/docs/content/2.headers/1.csp.md similarity index 95% rename from docs/content/1.documentation/2.headers/1.csp.md rename to docs/content/2.headers/1.csp.md index 191e8e80..cd712c05 100644 --- a/docs/content/1.documentation/2.headers/1.csp.md +++ b/docs/content/2.headers/1.csp.md @@ -1,15 +1,17 @@ -# Content Security Policy - -:badge[Enabled]{type="success"} Prevent unwanted content from being injected in your app. - --- - -:ellipsis{right=0px width=75% blur=150px} +title: Content Security Policy +description: Prevent unwanted content from being injected in your app. +links: + - label: Enabled + icon: i-heroicons-check-badge + color: green + size: xs +--- Content Security Policy (CSP) helps prevent unwanted content from being injected/loaded into your webpages. This can mitigate cross-site scripting (XSS) vulnerabilities, clickjacking, formjacking, malicious frames, unwanted trackers, and other web client-side attacks. -::alert{type="info"} -ℹ Read more about this header [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP). +::callout{icon="i-heroicons-light-bulb"} + Read more about this header [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP). :: ## Usage @@ -230,8 +232,8 @@ This will result in following code being added to your static app `` tag: ``` -::alert{type="info"} -ℹ Read more about this [here](https://content-security-policy.com/examples/meta/). +::callout{icon="i-heroicons-light-bulb"} + Read more about this [here](https://content-security-policy.com/examples/meta/). :: @@ -280,7 +282,7 @@ Nuxt Security will generate script hashes and style hashes for you according to - `hashStyles`: Set this option to `true` to parse all inline styles as well as all external styles. Nuxt-Security will compute the hashes of inline styles and find the `integrity` attributes of external styles, and will add them to your `style-src` policy. -::alert{type="warning"} +::callout{icon="i-heroicons-exclamation-triangle" color="amber"} Our default recommendation is to avoid setting the `ssg: hashStyles` option to `true`.
⚠ This is because Nuxt's mechanism for Client-Side hydration of styles could be blocked by CSP in that case. @@ -288,7 +290,7 @@ Our default recommendation is to avoid setting the `ssg: hashStyles` option to ` For further discussion and alternatives, please refer to our [Advanced Section on CSP](/documentation/advanced/strict-csp). :: -::alert{type="info"} +::callout{icon="i-heroicons-light-bulb"} Nuxt Security will automatically calculate the `integrity` attributes of all your bundled assets if you set the `sri` option to `true`. For unbundled assets, you may need to set the `integrity` attribute manually.
Please see below our section on [Integrity Hashes For SSG](#integrity-hashes-for-ssg) @@ -351,7 +353,7 @@ export default defineNuxtConfig({ You can include any external script (Google Analytics, Stripe, Cloudflare Turnstile, etc.) in your application without compromising the Strict CSP protection offered by Nuxt Security. -::alert{type="info"} +::callout{icon="i-heroicons-light-bulb"} You will need to have default values for the `'strict-dynamic'`, `nonce` and `ssg` options.
If you change these default values, please refer to our [Advanced Section on CSP](/documentation/advanced/strict-csp) for alternatives. diff --git a/docs/content/1.documentation/2.headers/10.xDNSPrefetchControl.md b/docs/content/2.headers/10.xDNSPrefetchControl.md similarity index 81% rename from docs/content/1.documentation/2.headers/10.xDNSPrefetchControl.md rename to docs/content/2.headers/10.xDNSPrefetchControl.md index d3928266..655d644d 100644 --- a/docs/content/1.documentation/2.headers/10.xDNSPrefetchControl.md +++ b/docs/content/2.headers/10.xDNSPrefetchControl.md @@ -1,15 +1,17 @@ -# X-DNS-Prefetch-Control - -:badge[Enabled]{type="success"} Smaller but still important security response headers. - --- - -:ellipsis{right=0px width=75% blur=150px} +title: X-DNS-Prefetch-Control +description: Control how domain name resolutions is done by the browsers. +links: + - label: Enabled + icon: i-heroicons-check-badge + color: green + size: xs +--- The X-DNS-Prefetch-Control HTTP response header controls DNS prefetching, a feature by which browsers proactively perform domain name resolution on both links that the user may choose to follow as well as URLs for items referenced by the document, including images, CSS, JavaScript, and so forth. This prefetching is performed in the background, so that the DNS is likely to have been resolved by the time the referenced items are needed. This reduces latency when the user clicks a link. -::alert{type="info"} -ℹ Read more about this header [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control). +::callout{icon="i-heroicons-light-bulb"} + Read more about this header [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control). :: ## Usage diff --git a/docs/content/1.documentation/2.headers/11.xDownloadOptions.md b/docs/content/2.headers/11.xDownloadOptions.md similarity index 78% rename from docs/content/1.documentation/2.headers/11.xDownloadOptions.md rename to docs/content/2.headers/11.xDownloadOptions.md index 3c45035a..3937405d 100644 --- a/docs/content/1.documentation/2.headers/11.xDownloadOptions.md +++ b/docs/content/2.headers/11.xDownloadOptions.md @@ -1,15 +1,17 @@ -# X-Download-Options - -:badge[Enabled]{type="success"} Instruct Internet Explorer to not open a downloaded file directly. - --- - -:ellipsis{right=0px width=75% blur=150px} +title: X-Download-Options +description: Instruct Internet Explorer to not open a downloaded file directly. +links: + - label: Enabled + icon: i-heroicons-check-badge + color: green + size: xs +--- The X-Download-Options HTTP header has only one option: X-Download-Options: noopen. This is for Internet Explorer from version 8 on to instruct the browser not to open a download directly in the browser but instead to provide only the Save option. The user has to first save it and then open it in an application. -::alert{type="info"} -ℹ Read more about this header [here](https://webtechsurvey.com/response-header/x-download-options). +::callout{icon="i-heroicons-light-bulb"} + Read more about this header [here](https://webtechsurvey.com/response-header/x-download-options). :: ## Usage diff --git a/docs/content/1.documentation/2.headers/12.xFrameOptions.md b/docs/content/2.headers/12.xFrameOptions.md similarity index 77% rename from docs/content/1.documentation/2.headers/12.xFrameOptions.md rename to docs/content/2.headers/12.xFrameOptions.md index b8d01980..2b3deec0 100644 --- a/docs/content/1.documentation/2.headers/12.xFrameOptions.md +++ b/docs/content/2.headers/12.xFrameOptions.md @@ -1,15 +1,17 @@ -# X-Frame-Options - -:badge[Enabled]{type="success"} Smaller but still important security response headers. - --- - -:ellipsis{right=0px width=75% blur=150px} +title: X-Frame-Options +description: Indicate if a browser should render a page as iframe, frame, embed, or object. +links: + - label: Enabled + icon: i-heroicons-check-badge + color: green + size: xs +--- The X-Frame-Options HTTP response header can be used to indicate whether or not a browser should be allowed to render a page in a ``, `