Nuxt Csurf

Nuxt Csurf is a security module for the Nuxt framework that prevents Cross-Site Request Forgery (CSRF) attacks by creating a middleware for CSRF token creation and validation. It runs on Nuxt servers and serverless environments, supplies composables for attaching tokens to fetch requests, and is configured in nuxt.config.js.

What is Nuxt Csurf?

Nuxt Csurf is a Nuxt module that adds CSRF protection to projects by generating and validating tokens. It takes configuration for HTTPS mode, cookie settings, protected HTTP methods, and encryption, and produces a middleware that embeds tokens in the DOM and checks incoming request headers. It is written in TypeScript and maintained on GitHub.

Key Features

• Node.js and serverless support — Works on Node.js servers and serverless runtimes, with separate default encryption algorithms: aes-256-cbc for Node and AES-CBC for serverless.
• Universal and client-side rendering — Supports both ssr: true and ssr: false configurations, covering universal and SPA Nuxt apps.
• Per-route configuration — Use routeRules to disable protection on specific routes such as /api/nocsrf or customize methods per route like protecting only POST on /api/test.
• Configurable methods to protect — Defaults to protecting POST, PUT, and PATCH; adjustable via methodsToProtect.
• Cookie-based token storage — Stores the CSRF token in a cookie with configurable path, httpOnly, and sameSite options (default strict), and uses __Host-csrf as the cookie key when HTTPS is enabled.
• Composables and helpers — useCsrfFetch wraps useFetch, $csrfFetch wraps $fetch from useNuxtApp(), and useCsrf exposes the token value.
• TypeScript support — Fully typed module, suitable for TypeScript projects.
• HTTPS-aware defaults — https defaults to true in production; the cookieKey becomes __Host-csrf when HTTPS is true, otherwise just csrf.

Who is it for?

• Nuxt developers with server-rendered API routes — They can protect endpoints from CSRF without writing manual token middleware.
• Serverless deployers — Since the module supports serverless environments and uses a configurable encryptSecret for stateless tokens, it fits functions on edge or cloud platforms.
• Teams with mixed SSR and SPA apps — The module works under both ssr: true and ssr: false, making it applicable across universal and client-side rendered Nuxt sites.

What can you do with Nuxt Csurf?

• Secure form endpoints — Protect POST, PUT, and PATCH API routes by requiring a valid CSRF token in the csrf-token header.
• Automate token attachment — Use useCsrfFetch to automatically include the CSRF token in data calls like /api/login, avoiding manual header code.
• Carve out exceptions — Set routeRules with csurf: false to exempt public webhooks or routes that don't need CSRF protection.

How does Nuxt Csurf work?

The middleware checks each request: if the method is protected, it validates the token in the configured header against the token stored in the cookie. The module also generates a fresh token and embeds it in the DOM during server-side rendering, so client composables can read it and attach it to outgoing requests. Token values look like a pair of base64 strings separated by a colon.

Limitations

Nuxt Csurf does not support static hosting or Nitro prerendering. The CSRF token is stored in the DOM as recommended by OWASP, which means the DOM must be generated on every page request; static or prerendered pages can't refresh the token per request.

Alternatives

• tiny-csrf — a minimal, framework-agnostic CSRF library that inspired nuxt-csurf.
• expressjs/csurf — Express middleware for CSRF protection, also cited as a source of inspiration.

FAQ

How do I install Nuxt Csurf?

Run npx nuxi@latest module add csurf in your Nuxt project directory. Then add 'nuxt-csurf' to the modules array in nuxt.config.js and optionally set a csurf configuration block.

Does Nuxt Csurf work with static site generation?

No. The module does not support static hosting or Nitro prerender. Because the CSRF token is embedded in the DOM, each page request must generate a fresh DOM, which static and prerendered pages don't do.

Which HTTP methods are protected by default?

By default, Nuxt Csurf protects POST, PUT, and PATCH requests. You can change this set with the methodsToProtect configuration option in nuxt.config.js.

How can I get the CSRF token in my client code?

Use the useCsrf composable, which returns a csrf value. Alternatively, useCsrfFetch and $csrfFetch automatically attach the token to requests, so you don't need to read it manually.

What encryption algorithms does Nuxt Csurf use?

The default algorithm is aes-256-cbc on Node.js and AES-CBC on serverless runtimes. You can override it with encryptAlgorithm, and for serverless, set encryptSecret to a 32-byte secret so tokens validate across stateless instances.