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?
This module is a fork of https://github.com/pillarjs/csrf at f0d66c91ea4be6d30a03bd311ed9518951d9c3e4.
Install
$ npm install @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.
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
})
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) {
})
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