koa-csrf

CSRF tokens for Koa

NOTE: As of v5.0.0+ ctx.csrf, ctx_csrf, and ctx.response.csrf are removed – instead use ctx.state._csrf. Furthermore we have dropped invalidTokenMessage and invalidTokenStatusCode in favor of an errorHandler function option.

Table of Contents

• Install
• Usage
• Options
• Contributors
• License

Install

npm:

1npm install koa-csrf

Usage

1. Add middleware in Koa app (see options below):

   1const Koa = require('koa');
   2const bodyParser = require('koa-bodyparser');
   3const session = require('koa-generic-session');
   4const convert = require('koa-convert');
   5const CSRF = require('koa-csrf');
   6
   7const app = new Koa();
   8
   9// set the session keys
   10app.keys = [ 'a', 'b' ];
   11
   12// add session support
   13app.use(convert(session()));
   14
   15// add body parsing
   16app.use(bodyParser());
   17
   18// add the CSRF middleware
   19app.use(new CSRF());
   20
   21// your middleware here (e.g. parse a form submit)
   22app.use((ctx, next) => {
   23  if (![ 'GET', 'POST' ].includes(ctx.method))
   24    return next();
   25  if (ctx.method === 'GET') {
   26    ctx.body = ctx.state._csrf;
   27    return;
   28  }
   29  ctx.body = 'OK';
   30});
   31
   32app.listen();

2. Add the CSRF token in your template forms:

   Jade Template:

   1form(action='/register', method='POST')
   2  input(type='hidden', name='_csrf', value=_csrf)
   3  input(type='email', name='email', placeholder='Email')
   4  input(type='password', name='password', placeholder='Password')
   5  button(type='submit') Register

   EJS Template:

   1<form action="/register" method="POST">
   2  <input type="hidden" name="_csrf" value="<%= _csrf %>" />
   3  <input type="email" name="email" placeholder="Email" />
   4  <input type="password" name="password" placeholder="Password" />
   5  <button type="submit">Register</button>
   6</form>

Options

• errorHandler (Function) - defaults to a function that returns ctx.throw(403, 'Invalid CSRF token')
• excludedMethods (Array) - defaults to [ 'GET', 'HEAD', 'OPTIONS' ]
• disableQuery (Boolean) - defaults to false
• ignoredPathGlobs (Array) - defaults to an empty Array, but you can pass an Array of glob paths to ignore

Contributors

Name	Website
Nick Baugh	https://github.com/niftylettuce
Imed Jaberi	https://www.3imed-jaberi.com/

License

MIT © Jonathan Ong