https://github.com/nartix/next-csrf

A CSRF middleware for NextJS 15
https://github.com/nartix/next-csrf

csrf-protection nextjs

Last synced: 4 days ago
JSON representation

A CSRF middleware for NextJS 15

• Host: GitHub
• URL: https://github.com/nartix/next-csrf
• Owner: nartix
• License: mit
• Created: 2025-01-07T09:12:02.000Z (8 days ago)
• Default Branch: main
• Last Pushed: 2025-01-07T12:01:18.000Z (8 days ago)
• Last Synced: 2025-01-07T12:35:09.267Z (8 days ago)
• Topics: csrf-protection, nextjs
• Homepage:
• Size: 6.84 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# 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

```bash

npm install @nartix/next-csrf

```

## Quick Start

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

```typescript

// 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:

```js

// 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.

---