expressjs-csurf

Forked from expressjs/csurf September 2023

Security update

September 2023

Following the publication¹² of a security vulnerability in the original expressjs/csrf module this fork attempts to remediate the issues as the upstream package has been archived rather than address them directly. The remediation itself was to remove the cookie option that allowed the use of the 'double-submit-cookie-pattern'³ as although the pattern is not at fault, we do not use it so have simply removed it from this repository.

Node.js CSRF protection middleware.

Requires a session middleware to be initialized first.

• You must use a session middleware before this module. For example:
  • express-session
  • cookie-session

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

Installation

This is a Node.js module available through the npm registry. Installation is done using the npm install command:

$ 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:

ignoreMethods

An array of the methods for which CSRF token checking will disabled. Defaults to ['GET', 'HEAD', 'OPTIONS'].

sessionKey

Determines what property ("key") on req the session object is located. Defaults to 'session' (i.e. looks at req.session). The CSRF secret from this library is stored and read as req[sessionKey].csrfSecret.

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')

// ... set up your session handler

// setup route middlewares
var csrfProtection = csrf()
var parseForm = bodyParser.urlencoded({ extended: false })

// create express app
var app = express()

app.get('/form', csrfProtection, function (req, res) {
  // pass the csrfToken to the view
  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>

Using AJAX

When accessing protected routes via ajax both the csrf token will need to be passed in the request. Typically this is done using a request header, as adding a request header can typically be done at a central location easily without payload modification.

The CSRF token is obtained from the req.csrfToken() call on the server-side. This token needs to be exposed to the client-side, typically by including it in the initial page content. One possibility is to store it in an HTML <meta> tag, where value can then be retrieved at the time of the request by JavaScript.

The following can be included in your view (handlebar example below), where the csrfToken value came from req.csrfToken():

<meta name="csrf-token" content="{{csrfToken}}">

The following is an example of using the Fetch API to post to the /process route with the CSRF token from the <meta> tag on the page:

// Read the CSRF token from the <meta> tag
var token = document.querySelector('meta[name="csrf-token"]').getAttribute('content')

// Make a request using the Fetch API
fetch('/process', {
  credentials: 'same-origin', // <-- includes cookies in the request
  headers: {
    'CSRF-Token': token // <-- is the csrf token as a header
  },
  method: 'POST',
  body: {
    favoriteColor: 'blue'
  }
})

Single Page Application (SPA)

Many SPA frameworks like Angular have CSRF support built in automatically. Typically they will reflect the value from a specific cookie, like XSRF-TOKEN (which is the case for Angular).

To take advantage of this, set the value from req.csrfToken() in the cookie used by the SPA framework. This is only necessary to do on the route that renders the page (where res.render or res.sendFile is called in Express, for example).

The following is an example for Express of a typical SPA response:

app.all('*', function (req, res) {
  res.cookie('XSRF-TOKEN', req.csrfToken())
  res.render('index')
})

Ignoring Routes

Note CSRF checks should only be disabled for requests that you expect to come from outside of your website. Do not disable CSRF checks for requests that you expect to only come from your website. An existing session, even if it belongs to an authenticated user, is not enough to protect against CSRF attacks.

The following is an example of how to order your routes so that certain endpoints do not check for a valid CSRF token.

var cookieParser = require('cookie-parser')
var csrf = require('csurf')
var bodyParser = require('body-parser')
var express = require('express')

// create express app
var app = express()

// create api router
var api = createApiRouter()

// mount api before csrf is appended to the app stack
app.use('/api', api)

// now add csrf and other middlewares, after the "/api" was mounted
app.use(bodyParser.urlencoded({ extended: false }))
app.use(csrf())

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

app.post('/process', function (req, res) {
  res.send('csrf was required to get here')
})

function createApiRouter () {
  var router = new express.Router()

  router.post('/getProfile', function (req, res) {
    res.send('no csrf to get here')
  })

  return router
}

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 csrf = require('csurf')
var express = require('express')

var app = express()
app.use(bodyParser.urlencoded({ extended: false }))
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('form tampered with')
})

References

• Cross-side request forgery on Wikipedia
• OWASP Cross-Site Request Forgery Prevention Cheat Sheet

License

MIT

Footnotes

1. https://fortbridge.co.uk/research/a-csrf-vulnerability-in-the-popular-csurf-package/ ↩

2. https://www.veracode.com/blog/research/analysis-and-remediation-guidance-csrf-vulnerability-csurf-expressjs-middleware ↩

3. https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#double-submit-cookie ↩