Ncsrf NPM | npm.io

Nestjs CSRF token validator

About

Nestjs CSRF protection middleware. If you have questions on how this module is implemented, please read Understanding CSRF.

Deps version

current -> @nestjs/common >= 10.x
1.0.7 -> @nestjs/common ^9.4
1.0.2 -> @nestjs/common ^7.6

Prerequisites

Requires either a session middleware or cookie-parser to be initialized first, and need enableCors.

app.use(cookieParser());

Installing

This is a Node.js module available through the npm registry. Installation is done using the npm install command:

$ npm install ncsrf --save

$ yarn add ncsrf

Usage

Import in main.ts to enable the middleware globally

import { nestCsrf, CsrfFilter } from "ncsrf";
import cookieParser from "cookie-parser";

app.use(cookieParser());
app.use(nestCsrf());

nestCsrf(options)

signed - indicates if the cookie should be signed (defaults to false).
key - the name of the cookie to use to store the token secret (defaults to '_csrf').
ttl - The time to live of the cookie use to store the token secret (default 300s).

Custom exception message

app.useGlobalFilters(new CsrfFilter());

Or use your custom exception filter by catch 2 class

CsrfInvalidException;

And

CsrfNotFoundException;

How to verify csrf token

HTTP Request must be have at least one of these headers:

csrf-token
xsrf-token
x-csrf-token
x-xsrf-token
or query param:
_csrf
or body param:
_csrf

Restful API Setup

Important: Request must be sent with withCredentials set to true to allow cookies to be sent from the frontend or credentials set to include in fetch API.

Generate token here

  @Get('/token')
  getCsrfToken(@Req() req): any {
    return {
      token: req.csrfToken()
    }
  }

Protected route with csrf

  import {Csrf} from "ncsrf";
  ...
  @Post()
  @Csrf()
  needProtect(): string{
    return "Protected!";
  }

Protected route with csrf and custom exception message

  import {Csrf} from "ncsrf";
  ...
  @Post()
  @Csrf("Custom exception message")
  needProtect(): string{
    return "Protected!";
  }

GraphQL Setup

Important: Request must be sent with withCredentials set to true to allow cookies to be sent from the frontend or credentials set to include in fetch API.

Generate token here

  @Query((returns) => string, { name: 'getToken', nullable: false })
  async getUsers(@Context('req') req: any) {
    return req?.csrfToken();
  }

Protected route with csrf

  import {CsrfQL} from "ncsrf";
  ...
  @Mutation((returns) => string, { name: 'needProtect', nullable: false })
  @CsrfQL()
  needProtect(): string{
    return "Protected!";
  }

Protected route with csrf and custom exception message

  import {CsrfQL} from "ncsrf";
  ...
  @Mutation((returns) => string, { name: 'needProtect', nullable: false })
  @CsrfQL("Custom exception message")
  needProtect(): string{
    return "Protected!";
  }