@nartix/next-csrf v0.1.3

Next CSRF

A lightweight CSRF protection middleware for Next.js on the Edge Runtime. It performs a double check on the CSRF token by comparing the token from the request body or headers with the token stored in the cookie. You can access the token via request header or by reading the cookie value.

Installation

npm install @nartix/next-csrf

Quick Start

Below is a minimal example of how to integrate this middleware in a Next.js app:

// middleware.ts (or middleware.js)
import { NextRequest, NextResponse } from 'next/server';
import { createNextCsrfMiddleware } from '@nartix/next-csrf';

export async function middleware(req: NextRequest) {
  const res = NextResponse.next();

  // Provide any custom options here
  const csrfOptions = {
    secret: 'your-secret-key', // Required
    // Additional options can be specified
  };

  return createNextCsrfMiddleware(req, res, csrfOptions);
}

Default Configuration

Below is an example of the default configuration. You can override any of these options in the middleware:

// default config

{
  headerName: 'X-CSRF-TOKEN',
  formFieldName: 'csrf_token',
  excludeMethods: ['GET', 'HEAD', 'OPTIONS'],
  algorithm: 'SHA-256',
  tokenByteLength: 32,
  separator: '.',
  enableHeaderCheckForJson: false,
  cookie: {
    name: 'CSRF-TOKEN',
    path: '/',
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict',
    maxAge: 60 * 60 * 24 * 7, // 1 week
    domain: undefined,
  },
}

How It Works

1. Token Generation: If the CSRF-TOKEN cookie does not exist, the middleware generates a new token and sets it as a cookie.
2. Double Check: It compares the token in the cookie to the token from the request—either via a form field, JSON body, or request header.
3. Verification: The token is then cryptographically validated with your secret.
4. Optional Header Access: You can configure enableHeaderCheckForJson to allow tokens to be read directly from headers for JSON requests.

Error Handling

If token validation fails, the middleware automatically returns a 403 Forbidden response with a JSON error message.

License

MIT License. Feel free to modify and use in your projects.