Wondering what’s next for npm?Check out our public roadmap! »

    koa-csrf
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/koa-csrf package

    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

    67,582

    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