csurf

Node.js CSRF protection middleware.

Requires either a session middleware or cookie-parser to be initialized first.

• express-session
• cookie-session

If you have questions on how this module is implemented, please read Understanding CSRF.

Install

$ npm install csurf

API

var csrf = require('csurf')

csrf(options)

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

• value a function accepting the request, returning the token.
  • The default function checks four possible token locations:
    • _csrf parameter in req.body generated by the body-parser middleware.
    • _csrf parameter in req.query generated by query().
    • x-csrf-token and x-xsrf-token header fields.
• cookie set to a truthy value to enable cookie-based instead of session-based csrf secret storage.
  • If cookie is an object, these options can be configured, otherwise defaults are used:
    • key the name of the cookie to use (defaults to _csrf) to store the csrf secret
    • any other res.cookie options can be set
• ignoreMethods An array of the methods CSRF token checking will disabled. (default: ['GET', 'HEAD', 'OPTIONS'])

req.csrfToken()

Lazy-loads the token associated with the request.

Example

Simple express example

The following is an example of some server-side code that protects all non-GET/HEAD/OPTIONS routes with a CSRF token.

var express = require('express')
var csrf    = require('csurf')

var app = express()
app.use(csrf())

// error handler
app.use(function (err, req, res, next) {
  if (err.code !== 'EBADCSRFTOKEN') return next(err)

  // handle CSRF token errors here
  res.status(403)
  res.send('session has expired or form tampered with')
})

// pass the csrfToken to the view
app.get('/form', function(req, res) {
  res.render('send', { csrfToken: req.csrfToken() })
})

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

var express = require('express')
var csrf    = require('csurf')

var app = express()
app.use(csrf())

// error handler
app.use(function (err, req, res, next) {
  if (err.code !== 'EBADCSRFTOKEN') return next(err)

  // handle CSRF token errors here
  res.status(403)
  res.send('session has expired or form tampered with')
})

License

MIT