@fastify/csrf

CSRF

Logic behind CSRF token creation and verification.

Read Understanding-CSRF for more information on CSRF. Use this module to create custom CSRF middleware.

Looking for a CSRF framework for your favorite framework that uses this module?

• Express/connect: csurf or alt-xsrf
• Koa: koa-csrf or koa-atomic-session

This module is a fork of https://github.com/pillarjs/csrf at f0d66c91ea4be6d30a03bd311ed9518951d9c3e4.

Install

$ npm i @fastify/csrf

TypeScript

This module includes a TypeScript declaration file to enable auto complete in compatible editors and type information for TypeScript projects.

API

const Tokens = require('@fastify/csrf')

new Tokens([options])

Create a new token generation/verification instance. The options argument is optional and will just use all defaults if missing.

Options

Tokens accepts these properties in the options object.

algorithm

The hash-algorithm to generate the token. Defaults to sha256.

saltLength

The length of the internal salt to use, in characters. Internally, the salt is a base 62 string. Defaults to 8 characters.

secretLength

The length of the secret to generate, in bytes. Note that the secret is passed around base-64 encoded and that this length refers to the underlying bytes, not the length of the base-64 string. Defaults to 18 bytes.

userInfo

Require user-specific information in tokens.create() and tokens.verify().

validity

The maximum validity of the token to generate, in milliseconds. Note that the epoch is passed around base-36 encoded. Defaults to 0 milliseconds (disabled).

tokens.create(secret[, userInfo])

Create a new CSRF token attached to the given secret. The secret is a string, typically generated from the tokens.secret() or tokens.secretSync() methods. This token is what you should add into HTML <form> blocks and expect the user's browser to provide back.

const secret = tokens.secretSync()
const token = tokens.create(secret)

The userInfo parameter can be used to protect against cookie tossing attacks (and similar) when the application is deployed with untrusted subdomains. It will encode some user-specific information within the token. It is used only if userInfo: true is passed as option in the constructor.

tokens.secret(callback)

Asynchronously create a new secret, which is a string. The secret is to be kept on the server, typically stored in a server-side session for the user. The secret should be at least per user.

tokens.secret(function (err, secret) {
  if (err) throw err
  // do something with the secret
})

tokens.secret()

Asynchronously create a new secret and return a Promise. Please see tokens.secret(callback) documentation for full details.

Note: To use promises in Node.js prior to 0.12, promises must be "polyfilled" using global.Promise = require('bluebird').

tokens.secret().then(function (secret) {
  // do something with the secret
})

tokens.secretSync()

A synchronous version of tokens.secret(callback). Please see tokens.secret(callback) documentation for full details.

const secret = tokens.secretSync()

tokens.verify(secret, token[, userInfo])

Check whether a CSRF token is valid for the given secret, returning a Boolean.

if (!tokens.verify(secret, token)) {
  throw new Error('invalid token!')
}

The userInfo paramater is required if userInfo: true was configured during initialization. The user-specific information must match what was passed in tokens.create().

License

MIT