Navel Pondering Mantra
Introducing npm Teams! Private packages + team management tools.Learn more »

koa-csrf

3.0.8 • Public • Published

koa-csrf

build status code coverage code style styled with prettier made with lass license

CSRF tokens for Koa

Table of Contents

Install

For versions of Koa <2.x please use koa-csrf@2.x

npm:

npm install koa-csrf

yarn:

yarn add koa-csrf

Usage

  1. Add middleware in Koa app (default options are shown):

    const Koa = require('koa');
    const bodyParser = require('koa-bodyparser');
    const session = require('koa-generic-session');
    const convert = require('koa-convert');
    const CSRF = require('koa-csrf');
     
    const app = new Koa();
     
    // set the session keys
    app.keys = [ 'a', 'b' ];
     
    // add session support
    app.use(convert(session()));
     
    // add body parsing
    app.use(bodyParser());
     
    // add the CSRF middleware
    app.use(new CSRF({
      invalidTokenMessage: 'Invalid CSRF token',
      invalidTokenStatusCode: 403,
      excludedMethods: [ 'GET', 'HEAD', 'OPTIONS' ],
      disableQuery: false
    }));
     
    // your middleware here (e.g. parse a form submit)
    app.use((ctx, next) => {
      if (![ 'GET', 'POST' ].includes(ctx.method))
        return next();
      if (ctx.method === 'GET') {
        ctx.body = ctx.csrf;
        return;
      }
      ctx.body = 'OK';
    });
     
    app.listen();
  2. Add the CSRF token in your template forms:

    Jade Template:

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

    EJS Template:

    <form action="/register" method="POST">
      <input type="hidden" name="_csrf" value="<%= csrf %>" />
      <input type="email" name="email" placeholder="Email" />
      <input type="password" name="password" placeholder="Password" />
      <button type="submit">Register</button>
    </form>

Options

  • invalidTokenMessage (String or Function) - defaults to Invalid CSRF token, but can also be a function that accepts one argument ctx (useful for i18n translation, e.g. using ctx.request.t('some message') via @ladjs/i18n
  • invalidTokenStatusCode (Number) - defaults to 403
  • excludedMethods (Array) - defaults to [ 'GET', 'HEAD', 'OPTIONS' ]
  • disableQuery (Boolean) - defaults to false

Open Source Contributor Requests

  • Existing methods from 1.x package added to 3.x
  • Existing tests from 1.x package added to 3.x

Contributors

Name Website
Nick Baugh https://github.com/niftylettuce

License

MIT © Jonathan Ong

Install

npm i koa-csrf

DownloadsWeekly Downloads

13,238

Version

3.0.8

License

MIT

Unpacked Size

9.19 kB

Total Files

6

Last publish

Collaborators

  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar