signed-token-csrf

CSRF connect middlewares using signed tokens

• API
  • new Csrf(secret, [opts])
  • create
  • verify
  • verifyXhr
  • csrf
• Example
  • Forms
  • XHR
• Installation
• Tests
• License
• References

API

new Csrf(secret, [opts])

Parameters

parameter	type	description
secret	string	a server side secret
[opts]	Object	optional: options
[opts.name=csrf]	string	optional: header & cookie name of token
[opts.cookie]	Object	optional: cookie options - defaults to {path: '/', httpOnly: true, secure: true, sameSite: true}
[opts.token]	Object	optional: signedToken options - defaults to {digest: 'sha256', commonlen: 24, tokenlen: 48}
[opts.ignoreMethods]	Array<string>	optional: ignore methods ['HEAD', 'OPTIONS']
[opts.host]	string	optional: hostname of service to check against

create

Connect middleware (req, res, next) => {}

Creates method req.csrfToken() to get CSRF token as well as the secret for signing in req.session.csrf if available or sets a csrf cookie. Name of session key and cookie name can be changed via opts.name. Default name is csrf.

NOTE: If used together with verifyXhr() only set CSRF Cookie on successful login!

verify

Connect middleware (req, res, next) => {}

Obtains a token from a request using either req.body.csrf, req.query.csrf or req.headers['x-csrf-token'] and verifies it with the secret from req.session.csrf if available or from the csrf cookie. body-parser is required to obtain the token from the request body. Name of session key and cookie name can be changed via opts.name

verifyXhr

Connect middleware (req, res, next) => {}

Verifies the cookie only; For token based xhr requests. See Your API-Centric Web App Is Probably Not Safe Against XSS and CSRF.

NOTE: Only set CSRF Cookie with create() on successful login!

csrf

Connect middleware (req, res, next) => {} which chains create and verify.

Example

Forms

See ./example/app.js. Run with node exampe/app.js and open http://localhost:3000 in browser.

const Csrf = require('signed-token-csrf')
const bodyParser = require('body-parser')
const session = require('express-session')
const app = require('express')()
const csrf = new Csrf('csrfSecret', {cookie: {secure: false}})

// works with or without a session
app.use(session({secret: 'sessionSecret', resave: false, saveUninitialized: true}))

app.use(csrf.checkOrigin)

app.get('/form',
  csrf.create, // adds CSRF protection
  (req, res) => { // render a form
    res.end(`
      <form action="/form" method="POST">
        <input type="hidden" name="csrf" value="${req.csrfToken()}" >
        <input type="text" name="text" value="some text"><br>
        <button>Submit</button>
      </form>
    `)
  }
)
app.post('/form', // render the submitted values or throw
  bodyParser.urlencoded({extended: false}),
  csrf.verify,
  (req, res) => {
    res.end(`
<h2>Parameters</h2>
<pre>
text: ${req.body.text}
csrf: ${req.body.csrf}
</pre>
    `)
  }
)

app.use('/', (req, res) => {
  res.redirect('/form')
})

app.listen(3000)

XHR

Run example and browse to http://localhost:3000/xhr

app.use(csrf.checkOrigin)

app.get('/api/login',
  (req, res, next) => {
    // prevent creating a new csrf cookie if authenticated
    const err = req.headers.authorization && httpError(403, 'already authenticated')
    next(err)
  },
  csrf.create,
  (req, res) => res.json({token: 'your-auth-token'})
)

app.use('/api',
  csrf.verifyXhr,
  (req, res) => res.json({})
)

Installation

Requires nodejs.

$ npm install signed-token-csrf

Tests

$ npm test

License

Unlicense https://unlicense.org

References

• Cross-Site Request Forgery (CSRF) Prevention Cheat Sheet - OWASP
• Your API-Centric Web App Is Probably Not Safe Against XSS and CSRF