nuxt-security

When configuring CSP, it is critical to understand how the browser treats different types of elements:

External Resources

These are elements loaded from a server via a URL.

• Examples: <img src="https://example.com/image.png">, <script src="/_nuxt/entry.js" />, or <link rel="stylesheet" href="https://cdn.com/style.css" />.
• CSP Defense: These are managed via whitelisting. If you define script-src https://example.com, any script from a different domain will be blocked.

Inline Elements

These are elements directly embedded within the HTML document.

• Examples: <script>console.log('Hello')</script> or <style>h1 { color: blue }</style>.
• CSP Defense: By default, CSP forbids all inline elements to prevent XSS (Cross-Site Scripting) attacks. Because Nuxt dynamically inserts many inline elements, you must use specific mechanisms like nonces (for SSR) or hashes (for SSG) to authorize them, rather than simply using the unsafe-inline directive.

<!-- An inlined script -->
<script>console.log('Hello World')></script>

<!-- An inlined style -->
<style>h1 { color: blue }</style>

<!-- An external resource -->
<script src="/_nuxt/entry.065a09b.js" />

CSP Level 2 allows you to specify exactly which inline elements are permitted using nonces or hashes.

Nonces

A unique random number generated by the server for each request. The server sends the nonce in the HTTP header (e.g., script-src 'nonce-somerandomstring') and the same value must be added to the HTML element: <script nonce="somerandomstring">...</script>.

Hashes

A SHA hash of the inline code. The server sends the hash in the header (e.g., script-src 'sha256-...'), and the browser validates the inline script by hashing its content and comparing it to the header.

Critical Nuxt Implications

1. Cancellation: Using hashes or nonces cancels 'unsafe-inline'. Every single inline element must have a nonce or hash, or it will be blocked.
2. Scope: Nonces and hashes only work for script-src and style-src. They cannot be used for other tags like <img> or <object>.
3. Hydration Issues: CSP Level 2 is often ineffective for Nuxt because client-side hydration attempts to insert elements that lack the required nonce or hash, causing them to be blocked.
4. SSG vs SSR: In SSR, nonces can whitelist both inline and external elements. However, for SSG (Static Site Generation), external elements must still be whitelisted by name (domain/file name).

export defaultNuxtConfig({
  security: {
    headers: {
      contentSecurityPolicy: {
        "script-src": [
          "'nonce-{{nonce}}'",
          // nonce will allow inline scripts that are inserted server-side
          // But the application will block if client-side hydration tries to insert a script 
          "https:example.com" 
          // example.com must still be whitelisted by name to support SSG
          // example.com must still be whitelisted by name to support hydration
        ]
      }
    }
  }
})

Implementing a Strict Content Security Policy (CSP) in a Nuxt application requires addressing three core challenges:

1. Resource Control: You must identify and authorize all scripts and stylesheets that Nuxt or its dependencies attempt to load. This includes distinguishing between external resources (loaded from a URL) and inlined resources (embedded directly in HTML).
2. Hydration: Because Nuxt uses an isomorphic hydration mechanism, the browser may inject scripts and styles during the transition from server-rendered HTML to a client-side application. Your CSP must be designed to allow these hydration-related injections without being blocked.
3. Rendering Mode (SSR vs. SSG):
   • In SSR (Server-Side Rendering) mode, Nuxt Security can leverage the Nitro server to control CSP delivery, typically using nonces.
   • In SSG (Static Site Generation) mode, files are served by a static provider rather than Nitro, so Nuxt Security uses hashes to authorize inline elements.

For Static Site Generation (SSG) applications, nonces are not available. Instead, Nuxt Security implements Strict CSP via hashes injected into a <meta http-equiv="Content-Security-Policy"> tag.

To enable this:

1. Set security.ssg.meta to true to enable the meta tag.
2. Set security.ssg.hashScripts to true to compute SHA hashes for inline and external scripts.
3. Set security.ssg.hashStyles (defaults to false). Warning: Setting this to true may block Nuxt's client-side style hydration.
4. Set security.sri to true to automatically calculate integrity attributes for bundled assets.

export default defineNuxtConfig({
  security: {
    ssg: {
      meta: true, // Enables CSP as a meta tag in SSG mode
      hashScripts: true, // Enables CSP hash support for scripts in SSG mode
      hashStyles: false, // Recommended to keep false to avoid hydration issues
      exportToPresets: true
    },
    sri: true,
    headers: {
      contentSecurityPolicy: {
        'script-src': ["'strict-dynamic'"]
      }
    }
  }
})

When using the nuxt-security:routeRules hook, you can choose how to apply your changes to existing rules:

1. Merging with replacement: Use defuReplaceArray (auto-imported) to replace specific array values (like CSP directives) while preserving other security options for that route.
2. Merging with addition: Use defu (requires import) to append new values to existing arrays (like adding a domain to script-src).
3. Overwriting: Assign a new object directly to the route rule to erase all existing security settings for that route and replace them entirely.

// 1. Merging with replacement (replaces specific array elements)
import { defuReplaceArray } from 'defu'
routeRules['/some/route'] = defuReplaceArray(
  { headers: { contentSecurityPolicy: { "script-src": ["'self'", "new-src"] } } },
  routeRules['/some/route']
)

// 2. Merging with addition (appends to existing arrays)
import { defu } from 'defu'
routeRules['/some/route'] = defu(
  { headers: { contentSecurityPolicy: { "script-src": ["'self'", "extra-src"] } } },
  routeRules['/some/route']
)

// 3. Overwriting (erases everything else)
routeRules['/some/route'] = {
  headers: { contentSecurityPolicy: { "script-src": ["'self'"] } }
}