@nestjs-kitchen/csrf

@nestjs-kitchen/csrf

A CSRF module in NextJS.

Feature

• ✅ Supports double-csrf validation strategy (cookie-based, stateless)

• ✅ Supports traditional session-based validation strategy (stateful)

• ✅ Supports one-time-use CSRF tokens

• ✅ Compatible with both @nestjs/platform-express and @nestjs/platform-fastify

Install

$ npm install --save @nestjs-kitchen/csrf

Usage

double-csrf Strategy (Cookie-Based)

This strategy stores the CSRF secret in the cookie and requires cookie support.

For @nestjs/platform-express:

npm install cookie-parser

For @nestjs/platform-fastify:

npm install @fastify/cookie

Example

Register module:

// in app.module.ts

@Module({
  imports: [
    // ...
    CsrfModule.register({
      type: 'double-csrf'
    })
    // ...
  ],
  controllers: [AppController],
  providers: [],
})
export class AppModule {}

Apply CSRF in a Controller:

// in app.controller.ts

import { Controller, Get, Post } from '@nestjs/common';
import { Csrf, CsrfInterceptor, CsrfGuard } from '@nestjs-kitchen/csrf';

@UseGuards(CsrfGuard)
@UseInterceptors(CsrfInterceptor)
@Controller()
export class AppController {

  @Csrf()
  @Post('/require-csrf')
  post(){
    // This handler will only execute if CSRF validation passes
    // ...
  }

  @Csrf.Sign()
  @Get('/csrf')
  csrf() {
    // Generates and stores a new CSRF token (skips CSRF validation)
    return true;
  }
}

session Strategy (Session-Based)

This strategy stores the CSRF secret in the session and requires session support.

For @nestjs/platform-express:

npm install express-session

For @nestjs/platform-fastify:

npm install @fastify/session

Alternatively, for Fastify, you can also use:

npm install @fastify/secure-session

⚠️ Note: When using @fastify/secure-session, one-time CSRF tokens are not supported because secure-session is stateless.

Example

Register module:

// in app.module.ts

import { Module } from "@nestjs/common";
import { CsrfModule } from '@nestjs-kitchen/csrf';
import { AppController } from './app.controller.ts';

@Module({
  imports: [
    // ...
    CsrfModule.register({
      type: 'session'
    })
    // ...
  ],
  controllers: [AppController],
  providers: [],
})
export class AppModule {}

Apply CSRF in a Controller:

Same as double-csrf example.

Options

Common options:

Option	Type	Description	Default
getToken	(req: any) => string	Function to extract CSRF token from the request.	(req) => req.headers['x-csrf-token']
headerKey	string	Response header name to expose the CSRF token.	'x-csrf-token'
verifyMethods	HttpMethod[]	List of HTTP methods that require CSRF validation.	['PATCH', 'PUT', 'POST', 'DELETE', 'CONNECT', 'TRACE']
global	boolean	If set to true, automatically applies CsrfGuard and CsrfInterceptor globally.	false

double-csrf options:

Option	Type	Description	Default
type	'double-csrf'	Strategy type: stores token in cookie only. Requires cookie support.	'double-csrf'
cookieKey	string	Cookie name to store CSRF secret.	'_csrf'
cookieOptions.path	string	Cookie path.	'/'
cookieOptions.secure	boolean	Use secure cookie (only sent over HTTPS).	false
cookieOptions.sameSite	string	SameSite policy.	'strict'
cookieOptions.httpOnly	boolean	Whether the cookie is HttpOnly.	true
cookieOptions.signed	boolean	Whether the cookie is signed.	false
cookieOptions.maxAge	number	Cookie expiration.	undefined
cookieOptions[...]	any	Additional cookie options.	—

session options:

Option	Type	Description	Default
type	'session'	Strategy type: stores token in session. Requires session support.	'session'
sessionKey	string	Session key to store the CSRF secret.	'_csrf'
oneTimeToken	boolean	Enable one-time-use tokens (valid for a single use only).	false
oneTimeTokenTTL	number	TTL for one-time tokens in milliseconds.	undefined
nonceStore.get	(key: string) => any | Promise<any>	Retrieve one-time token from store.	In-memory
nonceStore.set	(key: string, value: string, ttl?: number) => void | Promise<void>	Store one-time token.	In-memory
nonceStore.del	(key: string) => void | Promise<void>	Delete one-time token.	In-memory

License

MIT License