What is csurf?
The csurf npm package is a middleware for Node.js that provides Cross-Site Request Forgery (CSRF) protection. It helps secure web applications by ensuring that state-changing requests are made by authenticated users and not by malicious actors.
What are csurf's main functionalities?
Basic CSRF Protection
This code demonstrates how to set up basic CSRF protection using the csurf middleware in an Express application. It includes setting up the middleware, generating a CSRF token, and embedding it in a form.
const express = require('express');
const csrf = require('csurf');
const cookieParser = require('cookie-parser');
const app = express();
const csrfProtection = csrf({ cookie: true });
app.use(cookieParser());
app.use(csrfProtection);
app.get('/form', (req, res) => {
res.send(`<form action="/process" method="POST">
<input type="hidden" name="_csrf" value="${req.csrfToken()}">
<button type="submit">Submit</button>
</form>`);
});
app.post('/process', (req, res) => {
res.send('Form processed');
});
app.listen(3000, () => {
console.log('Server is running on port 3000');
});
CSRF Protection with Session Storage
This example shows how to use csurf with session storage for CSRF protection. The session middleware is used to store the CSRF token, which is then embedded in a form and validated upon form submission.
const express = require('express');
const session = require('express-session');
const csrf = require('csurf');
const app = express();
const csrfProtection = csrf();
app.use(session({ secret: 'mySecret', resave: false, saveUninitialized: true }));
app.use(csrfProtection);
app.get('/form', (req, res) => {
res.send(`<form action="/process" method="POST">
<input type="hidden" name="_csrf" value="${req.csrfToken()}">
<button type="submit">Submit</button>
</form>`);
});
app.post('/process', (req, res) => {
res.send('Form processed');
});
app.listen(3000, () => {
console.log('Server is running on port 3000');
});
Other packages similar to csurf
helmet
Helmet is a collection of middleware functions that help secure Express applications by setting various HTTP headers. While it does not provide CSRF protection directly, it offers a range of other security features such as XSS protection, content security policy, and more. It can be used alongside csurf for comprehensive security.
lusca
Lusca is another security middleware for Express that provides various security features, including CSRF protection. It is similar to csurf but also includes additional features like XSS protection, HSTS, and CORS. Lusca can be a more comprehensive solution if you need multiple security features in one package.
csurf
![Gratipay](https://img.shields.io/gratipay/dougwilson.svg)
Node.js CSRF protection middleware.
Requires either a session middleware or cookie-parser to be initialized first.
If you have questions on how this module is implemented, please read
Understanding CSRF.
Installation
$ npm install csurf
API
var csurf = require('csurf')
csurf([options])
Create a middleware for CSRF token creation and validation. This middleware
adds a req.csrfToken()
function to make a token which should be added to
requests which mutate state, within a hidden form field, query-string etc.
This token is validated against the visitor's session or csrf cookie.
Options
The csurf
function takes an optional options
object that may contain
any of the following keys:
cookie
Determines if the token secret for the user should be stored in a cookie
(when set to true
or an object, requires a cookie parsing module) or in
req.session
(when set to false
, provided by another module). Defaults
to false
.
When set to an object, cookie storage of the secret is enabled and the
object contains options for this functionality (when set to true
, the
defaults for the options are used). The options may contain any of the
following keys:
key
- the name of the cookie to use to store the token secret
(defaults to '_csrf'
).path
- the path of the cookie (defaults to '/'
).- any other res.cookie
option can be set.
ignoreMethods
An array of the methods for which CSRF token checking will disabled.
Defaults to ['GET', 'HEAD', 'OPTIONS']
.
value
Provide a function that the middleware will invoke to read the token from
the request for validation. The function is called as value(req)
and is
expected to return the token as a string.
The default value is a function that reads the token from the following
locations, in order:
req.body._csrf
- typically generated by the body-parser
module.req.query._csrf
- a built-in from Express.js to read from the URL
query string.req.headers['csrf-token']
- the CSRF-Token
HTTP request header.req.headers['xsrf-token']
- the XSRF-Token
HTTP request header.req.headers['x-csrf-token']
- the X-CSRF-Token
HTTP request header.req.headers['x-xsrf-token']
- the X-XSRF-Token
HTTP request header.
Example
Simple express example
The following is an example of some server-side code that generates a form
that requires a CSRF token to post back.
var cookieParser = require('cookie-parser')
var csrf = require('csurf')
var bodyParser = require('body-parser')
var express = require('express')
var csrfProtection = csrf({ cookie: true })
var parseForm = bodyparser.urlencoded({ extended: false })
var app = express()
app.use(cookieParser())
app.get('/form', csrfProtection, function(req, res) {
res.render('send', { csrfToken: req.csrfToken() })
})
app.post('/process', parseForm, csrfProtection, function(req, res) {
res.send('data is being processed')
})
Inside the view (depending on your template language; handlebars-style
is demonstrated here), set the csrfToken
value as the value of a hidden
input field named _csrf
:
<form action="/process" method="POST">
<input type="hidden" name="_csrf" value="{{csrfToken}}">
Favorite color: <input type="text" name="favoriteColor">
<button type="submit">Submit</button>
</form>
Custom error handling
When the CSRF token validation fails, an error is thrown that has
err.code === 'EBADCSRFTOKEN'
. This can be used to display custom
error messages.
var bodyParser = require('body-parser')
var cookieParser = require('cookie-parser')
var csrf = require('csurf')
var express = require('express')
var app = express()
app.use(bodyParser.urlencoded({ extended: false }))
app.use(cookieParser())
app.use(csrf({ cookie: true }))
app.use(function (err, req, res, next) {
if (err.code !== 'EBADCSRFTOKEN') return next(err)
res.status(403)
res.send('form tampered with')
})
License
MIT