crumb
Installation:

npm: npm install @hapi/crumb

yarn: yarn add @hapi/crumb

About

Crumb is used to diminish CSRF attacks using a random unique token that is validated on the server side.

Crumb may be used whenever you want to prevent malicious code to execute system commands, that are performed by HTTP requests. For example, if users are able to publish code on your website, malicious code added by a user could force every other user who opens the page, to load and execute code from a third party website e.g. via an HTML image tag. With Crumb implemented into your hapi.js application, you are able to verify requests with unique tokens and prevent the execution of malicious requests.

CORS

Crumb has been refactored to securely work with CORS, as OWASP recommends using CSRF protection with CORS.

It is highly discouraged to have a production servers cors.origin setting set to "[*]" or "true" with Crumb as it will leak the crumb token to potentially malicious sites

Usage

  const Hapi = require('@hapi/hapi');
  const Crumb = require('@hapi/crumb');

  const server = new Hapi.Server({ port: 8000 });

  (async () => {
    await server.register({
      plugin: Crumb,

      // plugin options
      options: {}
    });

    server.route({
      path: '/login',
      method: 'GET',
      options: {
        plugins: {
          // route specific options
          crumb: {}
        },
        handler(request, h) {
          // this requires to have a view engine configured
          return h.view('some-view');
        }
      }
    });
  })();

For a complete example see the examples folder.

Options

The following options are available when registering the plugin.

Registration options

  • key - the name of the cookie to store the csrf crumb into. Defaults to crumb.
  • size - the length of the crumb to generate. Defaults to 43, which is 256 bits, see cryptile for more information.
  • autoGenerate - whether to automatically generate a new crumb for requests. Defaults to true.
  • addToViewContext - whether to automatically add the crumb to view contexts as the given key. Defaults to true.
  • cookieOptions - storage options for the cookie containing the crumb, see the server.state documentation of hapi for more information. Default to cookieOptions.path=/ . Note that the cookie is not set as secure by default. It should be set as 'secure:true' for production use.
  • headerName - specify the name of the custom CSRF header. Defaults to X-CSRF-Token.
  • restful - RESTful mode that validates crumb tokens from "X-CSRF-Token" request header for POST, PUT, PATCH and DELETE server routes. Disables payload/query crumb validation. Defaults to false.
  • skip - a function with the signature of function (request, h) {}, which when provided, is called for every request. If the provided function returns true, validation and generation of crumb is skipped. Defaults to false.
  • enforce - defaults to true, using enforce with false will set the CSRF header cookie but won't execute the validation
  • logUnauthorized - whether to add to the request log with tag 'crumb' and data 'validation failed' (defaults to false)

Routes configuration

Additionally, some configuration can be passed on a per-route basis. Disable Crumb for a particular route by passing false instead of a configuration object.

  • key - the key used in the view contexts and payloads for the crumb. Defaults to plugin.key.
  • source - can be either payload or query specifying how the crumb will be sent in requests. Defaults to payload.
  • restful - an override for the server's 'restful' setting. Defaults to plugin.restful.

Changelog

#135
Update joi
#131
validate crumb when autoGenerate is false and crumb not defined on route
#134
Update deps
#129
Change module namespace
#112
adds logUnauthorized option - addresses #56
#111
Remove new Buffer usage
#103
Add an option to specify the CSRF header name
#56
Provide more relevant feedback
7.0.0
breaking changes
#107
Update contact details/maintainer
#106
Upgrade Crumb to Hapi 17
#105
hapi v17 support
#101
Enable Crumb for specific routes only
#99
Add sentence to README about how to disable the plugin for a particular route.
#98
Make both examples runnable with a package.json and proper dependencies
#97
Example won't launch: `Server.views is not a function`
#93
Documentation Improvement
#91
Cors origin
#90
Generate function never called when Vision route has CORS enabled
#89
Generate is running a second time and 500-ing hapi
#87
remove arrow function to fix context
#54
Getting 403 forbidden because token has changed
#84
#80: fixes crumb route settings bug
#82
Test on node v6, update dependencies
#80
6.0.1 update breaks route-restful option
#79
Fixes #74 -- restful configured through routes is not superceded by global config
#78
Purpose readme contribution
#69
Update restful example to respond with JSON. Closes #64
6.0.0
breaking changes
#70
Hapi12
#68
Heroku disallows host binding but Crumb requires it
#67
ES6 style changes and node v4
#61
Ignore CORS
5.0.0
breaking changes
#63
Update 9
#58
update to hapi 9/10
#51
crumb request.plugins.crumb: undefined
#53
correct linting issues
#52
Updated joi to 6.x.x
#49
Return error during plugin registration for invalid options.
#46
fix internals.originParser + tests to add protocol in all origin/allowOrigins values
#34
Host header cannot include URI scheme
4.0.0
breaking changes
#37
hapi8. Closes #35. internals bug. Closes #33
#35
hapi 8.0 API
#33
Don't use internals for plugin state
#11
Support hapi 3.0
clipboard