⚠ Work in progress ⚠

This module is work in progress. Feedback is very welcome. 🙂 Please open an issue if you have suggestions, ideas, bug reports or questions.

Planned todos before the first release:

• Tests with real browsers (at least manually, but prefered automated, e.g. with Playwright)
• Update the documentation, add a section to give more information about CSP and CSP reports

Thank you for your feedback!

Nuxt CSP Report

A Nuxt module for collecting, normalizing, and persisting Content Security Policy (CSP) reports.

• ✨  Release Notes

Features

• 📋 Register a POST endpoint for CSP reports
• 🔄 Support both legacy CSP and Report-To format reports
• ✅ Validate and normalize reports with Zod
• 💾 Persist reports via unstorage
• 📝 Full TypeScript support with proper type exports

Quick Setup

Install the module to your Nuxt application:

npm install nuxt-csp-report

Add it to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['nuxt-csp-report'],
  cspReport: {
    //  Module options
  },
})

Options

endpoint

• Type: string
• Default: /api/csp-report
• Description: Optional. Path for the CSP report endpoint.

reportingEndpointsHeader

• Type: boolean
• Default: false
• Description: Optional. Adds the Reporting-Endpoints header to your HTML responses, using 'csp-endpoint' as the key and endpoint from the configuration as the value. This header is needed if you want to use report-to csp-endpoint in your CSP configuration.

console

• Type: 'summary' | 'full' | false
• Default: 'summary'
• Description: Optional. Log reports to console on server. 'full' will print the NormalizedCspReport object.

storage

• Type: See fields below.
• Description: Optional. Sets up a storage using unstorage, which is part of Nitro and Nuxt.

storage.driver

• Type: BuiltinDriverOptions
• Description: Defines the driver from unstorage. You can use the same notation and drivers as in Nuxt:
  • https://nuxt.com/docs/4.x/directory-structure/server#server-storage
  • https://nitro.build/guide/storage
  • https://unstorage.unjs.io/drivers

storage.keyPrefix

• Type: string
• Default: csp-report
• Description: Optional. Key prefix for the stored reports.

Usage

The module is ready to go with the defaults. In most use cases simple logs are sufficient. If you want to analyze CSP reports, you can use the storage option to persist the reports in a KV store.

nuxt-security

The Content Security Policy is set through specific headers. You can handle that yourself with Nuxt/Nitro, but I highly recommend using nuxt-security. Here is a minimal example of how to use the two moduls in combination:

export default defineNuxtConfig({
  modules: ['nuxt-security', 'nuxt-csp-report'],
  security: {
    headers: {
      contentSecurityPolicy: {
        'report-uri': '/api/csp-report',
        // your CSP headers
      },
    },
  },
})

Advanced: Access reports

Depending on your use case you might want to access the CSP reports. You can do that with useStorage:

export default defineNuxtConfig({
  modules: ['nuxt-csp-report'],
  cspReport: {
    storage: {
      driver: {
        name: 'redis',
        options: {
          // Your redis configuration
        } 
      }
    },
  },
})

import  { type NormalizedCspReport } from 'nuxt-csp-report'

const storage = useStorage<NormalizedCspReport>('csp-report-storage')

Types

Legacy CSP Report Format

{
  "csp-report": {
    "document-uri": "https://example.com",
    "blocked-uri": "https://evil.com",
    "violated-directive": "script-src",
    "effective-directive": "script-src",
    "original-policy": "script-src 'self'",
    "disposition": "enforce"
  }
}

Report-To Format

[
  {
    "type": "csp-violation",
    "body": {
      "documentURI": "https://example.com",
      "blockedURI": "https://evil.com",
      "violatedDirective": "script-src",
      "effectiveDirective": "script-src",
      "originalPolicy": "script-src 'self'",
      "disposition": "enforce"
    }
  }
]

Normalized Report

interface NormalizedCspReport {
  ts: number
  documentURL?: string
  blockedURL?: string
  directive?: string
  sourceFile?: string
  line?: number
  column?: number
  disposition?: 'enforce' | 'report'
  raw: unknown
}

Contribution

Local development

# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Develop with the playground
pnpm run dev

# Build the playground
pnpm run dev:build

# Run ESLint
pnpm run lint

# Run Vitest
pnpm run test
pnpm run test:watch

# Build the module
pnpm run prepack

# Release new version
pnpm run release