CSRF Protection | Bootspring Docs

Patterns for Cross-Site Request Forgery protection in Next.js applications.

Overview#

CSRF attacks trick authenticated users into submitting malicious requests. This pattern covers:

Token-based CSRF protection
Double submit cookie pattern
SameSite cookie protection
Middleware integration

Prerequisites#

# No additional packages required - uses Node.js crypto

Code Example#

Token-Based CSRF Protection#

// lib/csrf.ts
import { randomBytes, createHmac } from 'crypto'
import { cookies } from 'next/headers'

const CSRF_SECRET = process.env.CSRF_SECRET!
const CSRF_COOKIE = 'csrf_token'
const CSRF_HEADER = 'x-csrf-token'

export function generateCsrfToken(): string {
  const token = randomBytes(32).toString('hex')
  const signature = createHmac('sha256', CSRF_SECRET)
    .update(token)
    .digest('hex')

  return `${token}.${signature}`
}

export function validateCsrfToken(token: string): boolean {
  const [value, signature] = token.split('.')

  if (!value || !signature) return false

  const expectedSignature = createHmac('sha256', CSRF_SECRET)
    .update(value)
    .digest('hex')

  return signature === expectedSignature
}

export async function setCsrfCookie() {
  const token = generateCsrfToken()
  const cookieStore = await cookies()

  cookieStore.set(CSRF_COOKIE, token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict',
    path: '/'
  })

  return token
}

export async function verifyCsrfToken(headerToken: string | null): Promise<boolean> {
  if (!headerToken) return false

  const cookieStore = await cookies()
  const cookieToken = cookieStore.get(CSRF_COOKIE)?.value

  if (!cookieToken) return false

  return headerToken === cookieToken && validateCsrfToken(headerToken)
}

CSRF Middleware#

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

const SAFE_METHODS = ['GET', 'HEAD', 'OPTIONS']

export function middleware(request: NextRequest) {
  // Skip CSRF check for safe methods
  if (SAFE_METHODS.includes(request.method)) {
    return NextResponse.next()
  }

  // Skip for API routes that use other auth (API keys, webhooks)
  if (request.nextUrl.pathname.startsWith('/api/webhooks')) {
    return NextResponse.next()
  }

  const csrfHeader = request.headers.get('x-csrf-token')
  const csrfCookie = request.cookies.get('csrf_token')?.value

  if (!csrfHeader || !csrfCookie || csrfHeader !== csrfCookie) {
    return NextResponse.json(
      { error: 'Invalid CSRF token' },
      { status: 403 }
    )
  }

  return NextResponse.next()
}

export const config = {
  matcher: '/api/:path*'
}

CSRF Token Provider#

// components/providers/CsrfProvider.tsx
'use client'

import { createContext, useContext, useEffect, useState } from 'react'

const CsrfContext = createContext<string | null>(null)

export function CsrfProvider({ children }: { children: React.ReactNode }) {
  const [token, setToken] = useState<string | null>(null)

  useEffect(() => {
    fetch('/api/csrf')
      .then(res => res.json())
      .then(data => setToken(data.token))
  }, [])

  return (
    <CsrfContext.Provider value={token}>
      {children}
    </CsrfContext.Provider>
  )
}

export function useCsrfToken() {
  return useContext(CsrfContext)
}

Protected Form#

// components/forms/ProtectedForm.tsx
'use client'

import { useCsrfToken } from '@/components/providers/CsrfProvider'

export function ProtectedForm() {
  const csrfToken = useCsrfToken()

  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault()
    const formData = new FormData(e.currentTarget)

    const response = await fetch('/api/submit', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-CSRF-Token': csrfToken ?? ''
      },
      body: JSON.stringify(Object.fromEntries(formData))
    })

    // Handle response...
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="hidden" name="csrf_token" value={csrfToken ?? ''} />
      {/* Form fields */}
      <button type="submit">Submit</button>
    </form>
  )
}

// lib/session.ts
// Modern approach: rely on SameSite cookies
import { cookies } from 'next/headers'

export async function setSessionCookie(sessionId: string) {
  const cookieStore = await cookies()

  cookieStore.set('session', sessionId, {
    httpOnly: true,
    secure: true,
    sameSite: 'lax', // or 'strict' for more protection
    path: '/',
    maxAge: 60 * 60 * 24 * 7 // 1 week
  })
}

// SameSite=Lax: Cookie sent with top-level navigations and GET from third-party
// SameSite=Strict: Cookie only sent in first-party context
// Combined with secure: true, this prevents most CSRF attacks

Usage Instructions#

Generate CSRF tokens for each session or form
Include the token in a cookie and require it in request headers
Validate tokens on all state-changing requests (POST, PUT, DELETE)
Skip validation for safe methods and webhook endpoints
Use SameSite cookies as an additional layer of protection

Best Practices#

Use strong secrets - Generate CSRF_SECRET with openssl rand -base64 32
Validate on server - Never trust client-side validation alone
Rotate tokens - Generate new tokens periodically or per-request
Skip webhooks - Webhooks use signature verification instead
Combine with SameSite - Use both CSRF tokens and SameSite cookies
Handle failures gracefully - Return clear error messages

Input Validation - Validate all user input
Security Headers - HTTP security headers
Session Management - Secure session handling
API Middleware - Request middleware patterns