Class: CABR

cabr~CABR

new CABR(rbac, optionsopt)

Constructs a new instance of CABR.
Parameters:
Name Type Attributes Description
rbac Object The RBAC-A instance to use
options Object <optional>
 The options to setup the class
Properties
Name Type Attributes Description
userProvider Object <optional>
 An RBAC-A provider which get method will be called with the current request to determine the current user. Defaults to the provider of the passed rbac instance.
routes Object <optional>
 An object of regular expression strings mapped to a string or array of strings (see the RBAC-A Grouped permissions syntax), or an object with keys defining HTTP methods (upper or lowercase) mapped to a permission syntax string or array. The keys of the route object are used as regular expressions to determine if a route configuration applies for the current request.
unauthorizedHandler function <optional>
 A middleware function that is called if a permission or attribute validation failed. Defaults to a simple function sending a 401 status and calling the next handler with an error message. The failed permission or attribute is attached as rbacFailed to the request object.
Source:
Example
const rbac = require('rbac-a');
const CABR = require('cabr');

// init the rbac instance ...

const routes = {
	// every route, every HTTP method needs the awesome permission
	'.*': 'awesome',

	// every route, every HTTP method needs the 'awesome', yolo' and 'funky' permission
	'^\\/funky$': ['yolo', 'funky'],

	// every route, every HEAD request needs the 'clever' and 'smart' permission
	// plus the 'awesome' permission
	'.*': {HEAD: ['clever', 'smart']}, // or 'clever && smart'

	// every route, every COPY request needs the either the 'clever' or 'smart' permission
	// plus the 'awesome' permission
	'.*': {COPY: 'clever || smart']},

	// ALL HTTP methods for '/pets' will be checked with the 'pets.read'
	// permission and 'awesome' permissions
	'^\\/pets$': 'pets.read',

	// Custom config for '/cats', different HTTP methods
	// will apply different permissions
	'^\\/pets\\/cats$': {GET: 'pets.read', POST: 'cats.create', DELETE: ['pets.create', 'pets.delete']},
};

// init the cabr instance
const cabr = new CABR(rbac, {routes});

// use a custom user provider
const get = (req) => Promise.resolve(req.user);
cabr = new CABR(rbac, {routes, userProvider: {get}});

Methods

guard(permissions, paramsopt) → {function}

Return a middleware function checking access based on the given permissions. The rbac check function is called with the request as req param, the response as res param, any additional params can be feed with the params parameter.
Parameters:
Name Type Attributes Description
permissions Array Array of permissions or permission syntax strings that should be checked for this route.
params <optional>
 Additional params to be passed to the attribute validation, beside req and res.
Source:
Returns:
A middleware function calling next if the rbac check succeeded, calls the options unauthorizedHandler otherwise.
Type
function

registerApp(app)

Register an express app on this CABR instance. All mapped requests will be validated with the configured RBAC-A permissions. For all attributes of a role, the RBAC-A attribute function will be called with params.permissions: permissions object, params.req: request and params.res: response for request validation, and additionally params.body for response validation and manipulation, after all other middleware has been called. The registerApp method must be called before any route handling middleware is registered that modifies the response body, also note that it may cause errors if the response body object is dereferenced in an attribute function!
Parameters:
Name Type Description
app Object The express app to register.
Source:
Example
const express = require('express');
const cabr = new CABR(...);
const app = express();

cabr.registerApp(app).use(...);

// or
const cabredApp = cabr.registerApp(express());

registerRoute(route, permissions)

Add a route configuration at runtime. CABR supports dynamically building the route configuration.
Parameters:
Name Type Description
route String String used as a regular expression. The route the permissions should be applied to
permissions Array.<Array> | Array | String | Object The permission object. The same formats as for the route options are supported. Also see the RBAC-A Grouped permissions syntax.
Source:
Example
cabr.registerRoute('^\/api$', {GET: 'read', POST: 'create'});