Stateless CSRF Protection for Express (Double Submit Cookie)

Common errors

• Error: Invalid or missing CSRF token

  cause The client request did not include a valid CSRF token, or `getTokenFromRequest` was unable to find it, or the token provided did not match the one expected by the server.
  fix Ensure the frontend sends the CSRF token (obtained from `/csrf-token` endpoint) in the correct header (`x-csrf-token`) or body field (`_csrf`) as configured by `getTokenFromRequest`.

• ReferenceError: cookieParser is not defined

  cause The `cookie-parser` middleware was not correctly imported or initialized before being used in the Express application.
  fix Add `import cookieParser from 'cookie-parser';` (ESM) or `const cookieParser = require('cookie-parser');` (CJS, for versions <4) and `app.use(cookieParser(...))` before `app.use(doubleCsrfProtection)`.

• TypeError: secret must be a string or array of strings

  cause The `secret` option passed to the `doubleCsrf` function is either missing or not of the expected type.
  fix Provide a string secret to the `doubleCsrf` configuration object: `doubleCsrf({ secret: 'your-strong-secret', ... })`.

• ERR_REQUIRE_ESM

  cause Attempted to use `require()` to import `csrf-csrf` in a CommonJS module, but the package (version 4+) is exclusively an ES Module.
  fix Switch to ES Module syntax: `import { doubleCsrf } from 'csrf-csrf';`. Ensure your `package.json` specifies `"type": "module"` for your project, or rename files to `.mjs`.

Warnings

• breaking Version 4 introduces breaking changes. If upgrading from version 3, consult the `CHANGELOG.md` and `UPGRADING.md` guides for detailed migration steps, particularly regarding configuration options and import paths.
  Fix: Refer to the official upgrade guide (`UPGRADING.md`) and `CHANGELOG.md` for specific changes and adapt your code accordingly.
• gotcha The `cookie-parser` middleware MUST be registered *before* `doubleCsrfProtection`. Incorrect ordering will prevent `csrf-csrf` from accessing and setting the necessary CSRF cookies, leading to validation failures.
  Fix: Ensure `app.use(cookieParser(...))` is called before `app.use(doubleCsrfProtection)`. If using `express-session`, `cookie-parser` should be after `express-session` as well.
• gotcha The `getTokenFromRequest` configuration option requires explicit logic to retrieve the CSRF token. Avoid using fallthroughs (e.g., `||`, `??`) that might inadvertently accept tokens from multiple, potentially insecure locations, mimicking vulnerabilities found in older CSRF libraries.
  Fix: Implement `getTokenFromRequest` with clear, explicit checks, prioritizing trusted locations like a specific header or body field. For example, `if (req.headers['x-csrf-token']) { return req.headers['x-csrf-token']; } else if (req.body._csrf) { return req.body._csrf; } return '';`
• gotcha This package implements the Double Submit Cookie Pattern for *stateless* CSRF protection. If your application relies on *sessions*, it is strongly recommended to use `csrf-sync` (Synchronizer Token Pattern) instead, as it is designed for session-based CSRF protection and offers different security considerations.
  Fix: Assess your application's state management. If using sessions, consider `csrf-sync`. If strictly stateless, `csrf-csrf` is appropriate, but understand the pattern's implications.
• gotcha The `secret` provided to `doubleCsrf` (and any secret for `cookie-parser`) should be a strong, unique, and securely managed value, preferably loaded from environment variables. Using a hardcoded or weak secret compromises the integrity of your CSRF protection.
  Fix: Store secrets in environment variables (e.g., `process.env.CSRF_SECRET`) and ensure they are sufficiently long and random.

Install

• npm install csrf-csrf npm
• yarn add csrf-csrf yarn
• pnpm add csrf-csrf pnpm

Imports

• doubleCsrf
  wrong:

  const { doubleCsrf } = require('csrf-csrf');

  correct:

  import { doubleCsrf } from 'csrf-csrf';

  The `doubleCsrf` function is the primary named export and a factory for the middleware. Version 4+ is ESM-only; CommonJS `require` will result in an `ERR_REQUIRE_ESM` error.
• DoubleCsrfConfigOptions

  import type { DoubleCsrfConfigOptions } from 'csrf-csrf';

  Use `import type` for type-only imports to ensure correct TypeScript inference and prevent bundling issues. This interface defines the configuration options for `doubleCsrf`.
• CsrfRequest

  import type { CsrfRequest } from 'csrf-csrf';

  This type augments the Express `Request` object, adding properties like `csrfToken` or methods relevant to CSRF handling, useful for custom type declarations or explicit type hints.

Quickstart

Demonstrates a basic Express server configuring `csrf-csrf` with `cookie-parser`, exposing a route to fetch a CSRF token, and protecting a POST endpoint. It highlights proper middleware ordering and token retrieval.

import express from 'express';
import cookieParser from 'cookie-parser';
import { doubleCsrf } from 'csrf-csrf';
import { Request, Response } from 'express';

const app = express();
const port = 3000;

// Initialize doubleCsrf with a secret.
// For production, use a strong, securely generated secret from environment variables.
const {
  doubleCsrfProtection,
  generateToken,
} = doubleCsrf({
  secret: process.env.CSRF_SECRET ?? 'your-very-strong-and-secret-key-that-you-must-change-in-prod-12345',
  cookieName: 'x-csrf-token',
  cookieOptions: {
    httpOnly: true,
    sameSite: 'lax', // 'Lax' or 'Strict' is recommended for CSRF protection
    secure: process.env.NODE_ENV === 'production',
  },
  getTokenFromRequest: (req: Request) => {
    // IMPORTANT: Be explicit here. Do not use fallthroughs (||, ??).
    // Prioritize header, then body. If not found, return an empty string.
    if (req.headers['x-csrf-token']) {
      return req.headers['x-csrf-token'] as string;
    }
    if (req.body && req.body._csrf) {
      return req.body._csrf;
    }
    return '';
  },
});

app.use(express.json()); // For parsing application/json
app.use(express.urlencoded({ extended: true })); // For parsing application/x-www-form-urlencoded
app.use(cookieParser(process.env.COOKIE_SECRET ?? 'your-cookie-secret-for-signing-if-needed')); // Use a separate secret for cookie-parser

// CSRF protection middleware must be after cookie-parser
app.use(doubleCsrfProtection);

// Route to get a new CSRF token for the frontend
app.get('/csrf-token', (req: Request, res: Response) => {
  const csrfToken = generateToken(req);
  res.json({ csrfToken });
});

// Example protected POST route
app.post('/submit-data', (req: Request, res: Response) => {
  // If the doubleCsrfProtection middleware didn't throw an error,
  // the request is considered valid.
  res.json({ message: 'Data submitted successfully!', received: req.body });
});

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});