Registry / auth-security / csrf-csrf

csrf-csrf

JSON →
library4.0.3jsnpmunverified

csrf-csrf is a utility package designed to provide stateless Cross-Site Request Forgery (CSRF) protection for Express applications, implementing the Double Submit Cookie Pattern. Currently at version 4.0.3, it offers a robust alternative to the deprecated `csurf` library, aiming for a simpler and more explicit configuration. Unlike session-based CSRF protection mechanisms like `csrf-sync` (which uses the Synchronizer Token Pattern), `csrf-csrf` is suited for stateless architectures, making it a distinct choice for specific application designs. The library ships with comprehensive TypeScript types (requiring TypeScript >= 3.8) and emphasizes clear implementation guidance to prevent common misconfigurations that can render CSRF protection ineffective. Development is active, with a recent major version release bringing breaking changes and improvements, and it explicitly recommends consulting upgrade guides for migration.

npm install csrf-csrf
INSTALL
IMPORT
SIG · CSRF-CSRF
C
csrf-csrf
auth-securityjavascriptv4.0.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

doubleCsrf
import { doubleCsrf } from 'csrf-csrf';
const { doubleCsrf } = require('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.

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}`); });
Debug
Known issues
breakingVersion 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.
affects: >=4.0.0
gotchaThe `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.
affects: >=1.0.0
gotchaThe `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 '';`
affects: >=1.0.0
gotchaThis 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.
affects: >=1.0.0
gotchaThe `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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Invalid or missing CSRF token
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
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
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
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`.
Upgrade
Version history
4.0.3latest on npm
Audit
Dependencies
cookie-parserrequired`cookie-parser` middleware is required to be registered before `doubleCsrfProtection` to handle HTTP cookies.
Agent activity
19 hits · last 30 days
node
16
OpenAI (training)
1
Resources
csrf-csrf — npm install csrf-csrf · libregistry