nrbac

Easy to use generic RBAC(Role-Based Access Control) for node.

Inspired by nconf !

Install

$ npm install nrbac --save

Example

var rbac = require('nrbac');
var async = require('async');

async.waterfall([
  function(next) {
    rbac.Permission.create({
      action: 'create',
      resource: 'post'
    }, next);
  },
  function(next) {
    rbac.Role.create({
      name: 'admin'
    }, function(err, role) {
      if (err) {
        return next(err);
      }
      // grant permission
      role.grant(permission, next);
    });
  }
], function(err, role) {
  role.can('create', 'post');  // true
  role.can('update', 'post');  // false
});

API Documentation

The top-level of nrbac is an instance of the nrbac.Provider abstracts this all for you into a simple API.

nrbac.Permission.create(permission, callback)

Creates permissions, permission param can be an object consists of an action and a resource, or an array of objects.

nrbac.Permission.create({
  action: 'create',
  resource: 'post'
}, function(err, permission) {
  // permission is an instance of nrbac.PermissionModel
});

nrbac.Permission.create([
  { action: 'update', resource: 'post' },
  { action: 'delete', resource: 'post' }
], function(err, permissions) {});

nrbac.Permission.get(action, resource)

Gets permission with the specified action and resource, return an instance of nrbac.PermissionModel.

var createPostPermission = nrbac.Permission.get('create', 'post');

nrbac.Permission.list()

Lists all permissions.

var permissions = nrbac.Permission.list();

nrbac.Permission.destroy()

Deletes all permissions.

nrbac.Permission.destroy();
nrbac.Permission.list().should.be.empty;

nrbac.Role.create(role, callback)

Creates roles, role param can be an object consists of a unique name, or an array of objects.

nrbac.Role.create({ name: 'member' }, function(err, role) {
  // role is an instance of nrbac.RoleModel
});

nrbac.Role.create([
  { name: 'admin' },
  { name: 'superadmin' }
], function(err, roles) {});

nrbac.Role.get(name)

Gets role with the specified name, return an instance of nrbac.RoleModel.

var admin = nrbac.Role.get('admin');

nrbac.Role.list()

Lists all roles.

var roles = nrbac.Role.list();

nrbac.Role.destroy()

Deletes all roles.

nrbac.Role.destroy();
nrbac.Role.list().should.be.empty;

nrbac.PermissionModel

permission.update(updateObj, [callback])

Updates the permission instance.

var permission = nrbac.Permission.get('create', 'post');
permission.update({
  resource: 'article'
});

permission.remove([callback])

Deletes the permission instance.

var permission = nrbac.Permission.get('create', 'post');
permission.remove();

nrbac.RoleModel

role.grant(permissions, callback)

Grants permissions to the role. permissions param can be an instance of nrbac.PermissionModel, or an array of objects.

var createPostPermission = nrbac.Permission.get('create', 'post');
var admin = nrbac.Role.get('admin');
admin.grant(createPostPermission, function(err, role) {
  // role granted permissions
});

role.can(action, resource)

Check if the role has the specified permission.

var createPostPermission = nrbac.Permission.get('create', 'post');
var admin = nrbac.Role.get('admin');
admin.grant(createPostPermission, function(err, role) {
  role.can('create', 'post');  // true
  role.can('update', 'post');  // false
});

role.update(updateObj, [callback])

Updates the role instance.

var role = nrbac.Role.get('superadmin');
role.update({ name: 'root' });

role.remove([callback])

Deletes the role instance.

var role = nrbac.Role.get('superadmin');
role.remove();

nrbac.use(storage)

Use the specified storage.

nrbac.use(new nrbac.MemoryStorage());

nrbac.sync(callback)

Synchronous data between nrbac and storage engine you are using.

var memoryStorage = new nrbac.MemoryStorage({
  Permission: [{ action: 'read', resource: 'post' }],
  Role: [{ name: 'admin' }]
});
nrbac.use(memoryStorage);

nrbac.sync(function(err) {
  // now you can get the storage data
  should.exist(nrbac.Permission.get('read', 'post'));
});

// if you create permissions or roles, or grant permissions to roles
//   you must call the `sync` method to synchronous the data to storage.
nrbac.Role.create({ name: 'vip' });
nrbac.sync(function(err) {
  // data has been synchronized to the storage you are using
});

nrbac.list(callback)

Lists all data.

nrbac.list(function(err, data) {
  // data output:
  // {
  //   Permission: [{ action: 'action', resource: 'resource' }, ...],
  //   Role: [{ name: 'roleName' }, ...]
  // }
});

Storage Engines

Memory

A simple in-memory storage engine that stores a literal Object representation of the RBAC data.

var memoryStorage = new nrbac.MemoryStorage();
nrbac.use(MemoryStorage);

// you can specify the memory storage initial data
var memoryStorage = new nrbac.MemoryStorage({
  Permission: [{ action: 'read', resource: 'post' }],
  Role: [{ name: 'admin' }]
});

File

File storage engine allow you to read your RBAC data from .json file, and data will be persisted to disk when a call to nrbac.sync() is made.

MongoDB

A MongoDB-based storage engine.

SQL

A SQL-based storage engine, you can use MySQL, PostgreSQL, and SQLite3.

Run Tests

$ npm install
$ npm test

Author: Heroic Yang

License: MIT