Authorization library

INSTALLATION

npm install 'cry-can' --save

Purpose

This library implements logic used for calculating authorizarion (access rights). It's core is the can function, accepting required permission set, actual (normally user's) permission set, and returning true if access should be granted, false otherwise.

Semantically, permissions are separated into modules, objects and operations.

For example:

• module = database, object = table, operation = (add, select, update, delete)
• module = rest, object = table, operation = (get, put, post, delete)
• module = ebus, object = worker, operation = (execute)

Access can be granted or denied on the level of resource, the resource being a module, module.object, or module.object.operation.

To check for authorization, call function can with parameters:

• requiredPermissionsObject
• usersPermissionObject (can be null to use defaults)
• operation
• object
• module

let Can = require('cry-can')
let can = new Can()

let requiredPermissions = { db: false, 'db.users.add': true  } // deny access to 'db'; except for 'app' operation on 'users' object of 'db' module
can.can(requiredPermissions,null,'add','users','db') // expect true
can.can(requiredPermissions,null,'add','users','delete') // expect false

let userPermissions = { db: true }  // the user can use all operations on all object of 'db'
can.can(requiredPermissions,userPermissions,'add','users','db') // expect true
can.can(requiredPermissions,userPermissions,'delete','users','db') // expect true

Default module, object, and operation can be specified in the Can constructor

let Can = require('cry-can')
let can0 = new Can()
let can1 = new Can('db')   // specify default module (db) 
let can2 = new Can('db','users')   // specify default module (db) and object (users)
let can3 = new Can('db','users','add')   // specify default module (db), object (users), and operation (add)

let requiredPermissions = { 'db.users.add': false }

// these calls are equivalent as parameters where specified in constructors
can0.can(requiredPermissions,null,'add','users','db')  // expect false
can1.can(requiredPermissions,null,'add','users')  // expect false
can2.can(requiredPermissions,null,'add')  // expect false
can3.can(requiredPermissions,null)  // expect false

Permissions object can use the dot-notation of the object hierarchy:

// use hierarchy
let permissions1 = {
    db: {
        users: {
            add: true
        }
    }
}

// use dot-notation in properties
let permissions2 = {
    'db.users.add': true
}

// permissions1 is equivalent to permissions2

Internally, dot-notiation objects are expanded into hierarchies before testing for authorization.

Note this special case:

let permissions0 = {
    db: true,
    'db.users': false,
    'db.users.add': true
}

// The above would mean that permissions.db is both a boolean (db:true)
// and an object at the same time with properties db.users (again an object)
// and db.users.add (a boolean)
// As this is not possible in Javascript, the above object is equivalent to

let permissions1 = {
    db: {
        _all: true,
        users: {
            _all: false,
            add: true
        } 
    }
}

Also note that using dot-notation, a less specific members must be specified before the more specific ones.

For example, db: true MUST appear BEFORE 'db.users.get':false.

// Also note that this case is NOT supported:
let permissions2 = {
    'db.users.add': false,
    db: true   // less specific member MUST be specified BEFORE a more specific one
}

Example use cases when user permissions are not specified (so the "defaults" of required permissions are used)

let Can = require('cry-can')
let can = new Can('db','users')   // specify default module (db) and object (users)

// Specify only required permissions, without user permissions 
can.can( { db: { users: false }}, null, 'any')  // expect false
can.can( { db: { users: true }}, null, 'any')  // expect true
can.can( { db: { users: { add: true } }}, null, 'add')  // expect true
can.can( { db: { users: { add: false } }}, null, 'add') // expect false
can.can( { 'db': true }, null, 'add') // expect true
can.can( { 'db.users': true }, null, 'add') // expect true
can.can( { 'db.users.add': true }, null, 'add') // expect true

Example use cases with both required permissions and user permissions specified (the latter override the former, so a user can be declined access to an otherwise accessible resource)

let Can = require('cry-can')
let can = new Can('db','users')   // specify default module (db) and object (users)

// User's permissions override required permissions
can.can( { 'db': true }, { 'db': false }, 'add') // expect false
can.can( { 'db': true }, { 'db': true }, 'add') // expect true
can.can( { 'db.users': true }, { 'db': false }, 'add') // expect false
can.can( { 'db.users': true }, { 'db': true }, 'add') // expect true
can.can( { 'db.users': false }, { 'db': false }, 'add') // expect false
can.can( { 'db.users': false }, { 'db': true }, 'add') // expect true
can.can( { 'db.users': false }, { 'db.users': false }, 'add') // expect false
can.can( { 'db.users': false }, { 'db.users': true }, 'add') // expect true
can.can( { 'db.users': false }, { 'db.users.add': false }, 'add') // expect false
can.can( { 'db.users': false }, { 'db.users.add': true }, 'add') // expect true
can.can( { 'db.users.add': false }, { 'db.users.add': false }, 'add') // expect false
can.can( { 'db.users.add': false }, { 'db.users.add': true }, 'add') // expect true
can.can( { 'db': false }, { 'db.users.add': false }, 'add') // expect false
can.can( { 'db': false }, { 'db.users.add': true }, 'add') // expect true
can.can( { 'db': true }, { 'db.users.add': false }, 'add') // expect false
can.can( { 'db': true }, { 'db.users.add': true }, 'add') // expect true
can.can( { 'db': false }, { 'db.users': true }, 'add') // expect true
can.can( { 'db': false }, { 'db.users': true }, 'add') // expect true

Finally, a function can be used for instead of constants true of false. The function must return a boolean.

If this function requires parameters, a single parameter can be specified either in the contructor as the 4th parameter, or by calling the bind(data) function.

let Can = require('cry-can')
let can = new Can('db','users')   // specify default module (db) and object (users)

let data = { t: true, f: false }

let returnTrue = function(x) { return x.t }
let returnFalse = function(x) { return x.f }

let requiredPermissions = { 'db': returnFalse }
let userPermissions = { 'db': returnTrue }

// bind function data in constructor
let can1 = new Can('db','users','get', data)
let r1 = can1.can(requiredPermissions)  // expect false
let r2 = can1.can(requiredPermissions, userPermissions)  // expect true

// bind function data explicitly
let can2 = new Can('db','users','get')
can2.bind(data)
let r3 = can2.can(requiredPermissions)  // expect false
let r4 = can2.can(requiredPermissions, userPermissions)  // expect true

To debug application calling can, you can either

• set CAN_DEBUG envieronment variable to an int>=0
• or call can.debug(level), where level is an int>=0

Debug levels:

• 0 ... print nothing
• 1 ... print question and answer
• 2 ... explain answer source
• 3 ... print required and user permission sets