koa-csrf-header

Koa CSRF Header Validation

The CSRF module provided by Koa's maintainers doesn't support validating CSRF tokens as an HTTP header field. This package provides that alternative exclusively.

This method requires client-side JavaScript enabled to craft the AJAX request, but validating an HTTP header field can be more convenient since your form templates don't need to be concerned with outputting a hidden field.

This package will be deprecated if the Koa team provided package supports validation in the header in the future.

Update:

The koa-csrf package does actually accept CSRF tokens in the HTTP header. It's just not documented. I recommend using the official package over this one.

https://github.com/koajs/csrf/blob/d798482/src/index.js#L57

Install

$ npm install --save koa-csrf-header

Usage

There are multiple ways to store a CSRF token throughout a user session. There are also multiple ways to send a CSRF token downstream. This package is agnostic to all methods. By default, ctx.session.csrfToken is used to retain the token.

Here's an example that uses the default options.

const Koa = require("koa");
const session = require("koa-session");
const crypto = require("crypto");
const csrf = require("koa-csrf-header");

const app = new Koa();

app.keys = [process.env.APP_KEY || crypto.randomBytes(256)];

app.use(session(app));

// Equivalent to app.use(csrf())
app.use(
  csrf({
    invalidTokenMessage: "Invalid CSRF Token",
    invalidTokenStatusCode: 403,
    excludedMethods: ["GET", "HEAD", "OPTIONS"],
    headerField: "X-CSRF-Token",
    getToken: ctx => ctx.session.csrfToken,
    setToken: (token, ctx) => {
      ctx.session.csrfToken = token;
    }
  })
);

app.use(ctx => {
  ctx.body = ctx.session.csrfToken;
});

app.listen(3000);

To show that there's multiple ways to store and send a CSRF Token, here's an example that uses a simple cookie for delivery.

const Koa = require("koa");
const csrf = require("koa-csrf-header");

const app = new Koa();

app.use(
  csrf({
    getToken: ctx => ctx.cookies.get("csrf-token"),
    setToken: (token, ctx) => {
      // We need httpOnly to be false so client-side JavaScript can read the
      // cookie and inject it into an AJAX request header later.
      ctx.cookies.set("csrf-token", token, { httpOnly: false });
    }
  })
);

app.use(ctx => {
  ctx.body = ctx.cookies.get("csrf-token");
});

app.listen(3000);