Nuxt Security Module

Common errors

• Cannot find module 'nuxt-security' or its corresponding type declarations.

  cause The module is not installed, or it's not correctly added to the `modules` array in `nuxt.config.ts`, or the type declarations are not properly resolved.
  fix Run `npx nuxi@latest module add security` or `npm install nuxt-security` to ensure the package is installed. Verify that `'nuxt-security'` is present in the `modules` array within your `nuxt.config.ts`.

• Refused to load the script '<URL>' because it violates the following Content Security Policy directive: "script-src".

  cause Your Content Security Policy (CSP) headers, configured by `nuxt-security`, are preventing a script from loading because its origin or attributes do not match the allowed directives.
  fix Review the `security.headers.contentSecurityPolicy` configuration in `nuxt.config.ts`. Add the problematic URL's domain to the `script-src` directive, or consider using `'unsafe-inline'`/`'unsafe-eval'` (with caution) or `nonce`/`hash` attributes if dynamic inline scripts are necessary.

• 405 Method Not Allowed

  cause The HTTP request used a method (e.g., PUT) that is not permitted for the specific route by the `security.allowedHTTPMethods` configuration.
  fix Check the `security.allowedHTTPMethods` configuration in `nuxt.config.ts` for the route in question. Ensure that the HTTP method used by your client is included in the `value` array. Adjust the configuration or client request method as appropriate.

• 429 Too Many Requests

  cause The rate limiter middleware, configured via `security.rateLimiter`, has detected that too many requests originated from the same client within the defined interval.
  fix Increase the `tokens` (maximum requests) or `interval` (time window) values in your `security.rateLimiter` configuration. Alternatively, if the client is legitimate and requires higher limits, consider adding its IP address to the `whiteList` option (if applicable).

• ERR_PNPM_PEER_DEP_ISSUES: Peer dependencies error (or similar npm/yarn error related to Node.js version)

  cause Your Node.js environment does not meet the minimum version requirement (Node.js >=20.0.0) specified by `nuxt-security` since version 2.3.0.
  fix Upgrade your local and deployment Node.js version to 20 or higher. Use a Node Version Manager like `nvm` or `fnm` to manage different Node.js versions efficiently.

Warnings

• breaking The module upgraded its minimum Node.js version requirement to 20.0.0 in v2.3.0. Applications deployed with older Node.js versions will encounter runtime errors or fail to build.
  Fix: Upgrade your Node.js environment to version 20 or higher using a Node Version Manager (e.g., nvm, fnm) or update your deployment platform's Node.js version.
• gotcha Prior to v2.1.2, `console.log` statements were removed in development mode by default if the `removeLoggers` option was implicitly or explicitly enabled, leading to unexpected debugging challenges. This behavior was changed in a hotfix.
  Fix: Upgrade to v2.1.2 or newer. If staying on an older version, explicitly set `removeLoggers: { value: false, route: '/**' }` in your development `nuxt.config.ts`.
• gotcha Incorrectly configured Content Security Policy (CSP) can severely restrict a web application, blocking legitimate scripts, styles, images, and other resources. This often results in a broken user interface or functionality, especially in SSR/SSG contexts where nonces or hashes might be required.
  Fix: Develop your CSP iteratively and test thoroughly across all environments (development, production, SSR, SSG). Utilize CSP reporting mechanisms to identify violations, and leverage `nonce` or `hash` attributes for dynamically generated content where 'unsafe-inline' is not desirable.
• gotcha The XSS validator can be overly aggressive and block legitimate user input, particularly in applications that handle rich text, HTML snippets, or other forms of complex data. This can lead to a poor user experience or data loss.
  Fix: Test the XSS validator rigorously with various expected user inputs. Consider applying XSS validation only to specific routes (e.g., `/forms/**`) where user-generated content is expected, or disable it entirely for routes where rich content is intentionally permitted and sanitized via other means.
• gotcha Aggressive rate limiting configurations can unexpectedly block legitimate API clients, bots, or integrations, leading to service disruption or inaccessible features. This is particularly problematic for applications with diverse client bases or sudden spikes in legitimate traffic.
  Fix: Configure rate limiter `tokens` and `interval` values based on a realistic assessment of expected traffic patterns and client behavior. Utilize the `whiteList` option (introduced in v2.2.0) to exempt known, high-volume clients or internal services from rate limiting.

Install

• npm install nuxt-security npm
• yarn add nuxt-security yarn
• pnpm add nuxt-security pnpm

Imports

• Module registration (string)
  wrong:

  import { nuxtSecurity } from 'nuxt-security'

  correct:

  export default defineNuxtConfig({
    modules: [
      'nuxt-security'
    ]
  })

  Nuxt modules are added as strings to the `modules` array in `nuxt.config.ts`, not imported as direct JavaScript symbols.
• ModuleOptions
  wrong:

  import { ModuleOptions } from 'nuxt-security'

  correct:

  import type { ModuleOptions } from 'nuxt-security'

  This type provides full IntelliSense and type checking for the `security` configuration object in `nuxt.config.ts`.
• BasicAuth
  wrong:

  import BasicAuth from 'nuxt-security/types/basic-auth'

  correct:

  import type { BasicAuth } from 'nuxt-security'

  Specific types for individual security features like `BasicAuth`, `CSPConfig`, or `RateLimiter` can be imported for more granular type-safety.

Quickstart

This configuration enables various security features for a Nuxt application, including a strict Content Security Policy, XSS protection, rate limiting for all API routes, restricted HTTP methods, XSS validation for form submissions, and basic authentication for an '/admin' section. Remember to set `BASIC_AUTH_USERNAME` and `BASIC_AUTH_PASSWORD` environment variables for basic authentication.

import { defineNuxtConfig } from 'nuxt';
import type { ModuleOptions } from 'nuxt-security';

const securityConfig: ModuleOptions = {
  headers: {
    contentSecurityPolicy: {
      value: {
        'default-src': ["'self'", "https://cdn.example.com"],
        'script-src': ["'self'", "'unsafe-inline'", "'unsafe-eval'", "https://cdn.example.com"],
        'style-src': ["'self'", "'unsafe-inline'", "https://cdn.example.com"]
      },
      route: '/**'
    },
    xXSSProtection: { value: '1; mode=block', route: '/**' },
    noSniff: { value: true, route: '/**' }
  },
  rateLimiter: {
    value: {
      tokens: 10,
      interval: 30000,
      headers: true,
      driver: {
        name: 'lru-cache',
        options: { max: 1000, ttl: 60000 }
      },
      statusCode: 429,
      statusMessage: 'Too Many Requests'
    },
    route: '/api/**'
  },
  allowedHTTPMethods: {
    value: ['GET', 'POST', 'PUT', 'DELETE'],
    route: '/api/**'
  },
  xssValidator: {
    value: true,
    route: '/forms/**'
  },
  basicAuth: {
    value: {
      name: process.env.BASIC_AUTH_USERNAME ?? 'admin',
      pass: process.env.BASIC_AUTH_PASSWORD ?? 'password',
      enabled: true,
      message: 'Authentication Required'
    },
    route: '/admin/**'
  }
};

export default defineNuxtConfig({
  modules: [
    'nuxt-security'
  ],
  security: securityConfig
});