Nearly Perfected Mystique

    @fastify/csrf
    TypeScript icon, indicating that this package has built-in type declarations

    6.0.0 • Public • Published

    CSRF

    CI NPM version js-standard-style

    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 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

    Keywords

    Install

    npm i @fastify/csrf

    DownloadsWeekly Downloads

    5,059

    Version

    6.0.0

    License

    MIT

    Unpacked Size

    37.9 kB

    Total Files

    20

    Last publish

    Collaborators

    • simenb
    • coopflow
    • simoneb
    • rafaelgss
    • starptech
    • delvedor
    • matteo.collina
    • allevo
    • jsumners
    • zekth
    • ethan_arrowood
    • eomm
    • fox1t
    • davidmarkclements
    • airhorns
    • kibertoad
    • climba03003
    • is2ei
    • fdawgs