koa-csrf

CSRF tokens for koa

Showing:

Popularity

Downloads/wk

34.7K

GitHub Stars

256

Maintenance

Last Commit

5mos ago

Contributors

10

Package

Dependencies

1

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

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

NameWebsite
Nick Baughhttps://github.com/niftylettuce

License

MIT © Jonathan Ong

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial