@hapi/crumb

Crumb is designed to work securely with Cross-Origin Resource Sharing (CORS). However, you must be careful with your server configuration:

Warning: It is highly discouraged to set your production server's cors.origin to "["*]" or true while using Crumb. Doing so can leak the crumb token to potentially malicious sites.

To use Crumb, register it as a plugin during your Hapi server initialization. You can provide global plugin options during registration.

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');
      }
    }
  });
})();

You can override the global crumb settings for individual routes by using the plugins.crumb key in the route configuration.

When configuring a route, you can specify:

• key: The key in the payload/query where the crumb is expected.
• restful: Whether to use header-based validation for this route.
• source: The source of the crumb in the request (defaults to 'payload').

If you set crumb: false in the route plugins, crumb generation and validation will be disabled for that specific route.

server.route({
    method: 'POST',
    path: '/submit',
    options: {
        plugins: {
            crumb: {
                key: 'csrfToken', // The crumb must be present in request.payload.csrfToken
                restful: false
            }
        }
    }
});

By default, @hapi/crumb expects the crumb to be inside the request payload (e.g., request.payload.crumb).

To use a custom header instead (common for AJAX/SPA applications), set restful: true in the plugin options or route configuration. When restful is enabled, the plugin looks for the crumb in the header specified by headerName (defaulting to X-CSRF-Token).

Note: When restful is enabled, the plugin only validates POST, PUT, PATCH, and DELETE methods if a route-specific crumb configuration is present.

To use @hapi/crumb in a Hapi server, register it as a plugin. You can provide a configuration object to customize how CSRF tokens (crumbs) are generated, stored, and validated.

By default, the plugin:

• Uses a cookie named crumb.
• Automatically generates a new crumb if one doesn't exist.
• Validates crumbs for POST requests by looking for a key in the request payload.
• Adds the crumb to the view context if the response is a view.
• Enforces validation (throws 403 Forbidden on failure).

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

const init = async () => {
    const server = Hapi.server({
        port: 3000,
        host: 'localhost'
    });

    await server.register({
        plugin: Crumb,
        options: {
            // Configuration options go here
        }
    });

    await server.start();
};

init();

You can override global Crumb settings for specific routes using the plugins.crumb object in the route options. To completely disable Crumb for a route, pass false instead of an object.

```js
server.route({
  path: '/some-route',
  method: 'POST',
  options: {
    plugins: {
      crumb: {
        key: 'custom-key',
        source: 'payload', // or 'query'
        restful: true      // override global restful setting
      }
    }
  }
});

Route Configuration Options:

If autoGenerate is set to false in the plugin options, you must manually generate a crumb and attach it to the response. The plugin exposes a generate method via server.expose.

Inside a handler, you can call request.plugins.crumb.generate(request, h) to create a new crumb, set the cookie, and return the value.

server.route({
    method: 'GET',
    path: '/get-token',
    handler: async (request, h) => {
        // Manually generate the crumb
        const token = await request.plugins.crumb.generate(request, h);
        return { token };
    }
});