Dynamic-acl NPM

node-dynamic-acl

Dynamic Access Control List for Node.js to fully control your Roles, Resources, Privileges and Conditions

#Install

$ npm install dynamic-acl

#Quick Start

var Acl = require('../dist').Acl;
var Role = require('../dist').Role;
var Resource = require('../dist').Resource;

var anonymous = {
roleId: 'visitor'
};
var bob = {
firstname: 'Bob',
lastname: 'Marley',
roleId: 'user'
};

var me = {
firtname: 'Timmmmy',
lastname: 'Timmmmy',
roleId: 'admin'
};

var page1 = {
id: 'page 1',
title: 'Go further with node',
resourceId: 'page'
};

var book = {
id: 'book 1',
title: 'Go further with JS',
resourceId: 'book'
};

var getUserRoleId = (user) => new Promise(resolve => resolve(user.roleId));

var getResourceId = (resource) => new Promise(resolve => resolve(resource.resourceId));

var userCanMarkPage = (user, page) => new Promise((resolve,reject) => {
if (user.firstname == 'Timmmmy')
return resolve();
return reject();
});

var acl = new Acl(getUserRoleId, getResourceId);
acl.addRole('visitor') // equivalent to acl.addRole(new Role('visitor', [], acl))
.addRole(new Role('user', ['visitor'], acl))
.addRole('admin', ['user']) //equivalent to acl.addRole(new Role('admin', ['user'], acl))
.addResource(new Resource('page', ['read', 'mark', 'change title']))
.addResource(new Resource('book'))
.build();

acl.allow('visitor', 'page', 'read')
.allow('user', 'page')
.allow('user', 'page', 'mark', userCanMarkPage)
.deny('user', 'page', 'change title')
.allow('admin', 'page', 'change title')
.allow('admin', 'book');

//console.log('---built permissions---');
//console.log('---visitor---');
//console.log(acl.getPermissions('visitor'));
//console.log('---user---');
//console.log(acl.getPermissions('user'));
//console.log('---admin---');
//console.log(acl.getPermissions('admin'));

//console.log('---anonymous permissions check---');
acl.isAllowed(anonymous, page1).then(
() => {
// anonymous should not be allowed
console.error('This should not be printed in console');
},
() => {
// anonymous is not allowed
console.log('anonymous isAllowed page1:* -> false');
}
);

acl.isAllowed(anonymous, page1, 'read').then(
// anonymous is allowed
() => {console.log('anonymous isAllowed page1:read -> true')},
() => {console.error('This should not be printed in console')}
);

acl.isAllowed(anonymous, page1, 'mark').then(
() => {console.error('This should not be printed in console')},
// anonymous is not allowed
() => {console.log('anonymous isAllowed page1:mark -> false')}
);

acl.isAllowed(anonymous, page1, 'change title').then(
() => {console.error('This should not be printed in console')},
// anonymous is not allowed
() => {console.log('anonymous isAllowed page1:change title -> false')}
);

acl.isAllowed(anonymous, book).then(
() => {console.error('This should not be printed in console')},
// anonymous is not allowed
() => {console.log('anonymous isAllowed book:* -> false')}
);

acl.isAllowed(anonymous, book, 'sell').then(
() => {console.error('This should not be printed in console')},
// anonymous is not allowed
() => {console.log('anonymous isAllowed book:sell -> false')}
);


//console.log('---user permissions check---');
acl.isAllowed(bob, page1).then(
() => {console.log('bob isAllowed page1:* -> true')},
() => {console.error('This should not be printed in console')}
);

acl.isAllowed(bob, page1, 'read').then(
() => {console.log('bob isAllowed page1:read -> true')},
() => {console.error('This should not be printed in console')}
);

acl.isAllowed(bob, page1, 'mark').then(
() => {console.error('This should not be printed in console')},
() => {console.log('bob isAllowed page1:mark -> false')}
);

acl.isAllowed(bob, page1, 'change title').then(
() => {console.error('This should not be printed in console')},
() => {console.log('bob isAllowed page1:change title -> false')}
);

acl.isAllowed(bob, book, 'book:*').then(
() => {console.error('This should not be printed in console')},
() => {console.log('bob isAllowed book:* -> false')}
);

acl.isAllowed(bob, book, 'book:sell').then(
() => {console.error('This should not be printed in console')},
() => {console.log('bob isAllowed book:sell -> false')}//privilege was not declared previously -> inherit from book:*
);

//console.log('---admin permissions check---');
acl.isAllowed(me, page1).then(
() => {console.log('me isAllowed page1:* -> true')},
() => {console.error('This should not be printed in console')}
);
acl.isAllowed(me, page1, 'read').then(
() => {console.log('me isAllowed page1:read -> true')},
() => {console.error('This should not be printed in console')}
);
acl.isAllowed(me, page1, 'mark').then(
() => {console.log('me isAllowed page1:mark -> true')},
() => {console.error('This should not be printed in console')}
);
acl.isAllowed(me, page1, 'change title').then(
() => {console.log('me isAllowed page1:change title -> true')},
() => {console.error('This should not be printed in console')}
);
acl.isAllowed(me, book).then(
() => {console.log('me isAllowed book:* -> true')},
() => {console.error('This should not be printed in console')}
);
acl.isAllowed(me, book, 'sell').then(
() => {console.log('me isAllowed book:sell -> true')},//privilege was not declared previously -> inherit from book:*
() => {console.error('This should not be printed in console')}
);

#API Reference

Acl

This class holds all information about Roles, Resources and Permissions

Kind: global class

Acl
- new Acl(roleIdFetchFunc, resourceIdFetchFunc)
- .setRoleIdFetchFunc(func) ⇒ Acl
- .setResourceIdFetchFunc(func) ⇒ Acl
- .addRole(role, Parents) ⇒ Acl
- .removeRole(role) ⇒ Acl
- .getRole(id) ⇒ Role
- .addResource(resource) ⇒ Acl
- .removeResource(resource) ⇒ Acl
- .getResource(id) ⇒ Resource | null
- .build() ⇒ Acl
- .allow(roleId, resourceId, privilege, condition) ⇒ Acl
- .deny(roleId, resourceId, privilege, condition) ⇒ Acl
- ._allowOrDeny(allow, roleId, resourceId, privilege, condition)
- .isAllowed(user, resource, privilege) ⇒ Promise
- .isRoleAllowed(roleId, resourceId, privilege) ⇒ Promise
- .isAnyParentAllowed(roleId, resourceId, privilege) ⇒ Promise
- .getPermissions(roleId) ⇒ Array.<Object>

new Acl(roleIdFetchFunc, resourceIdFetchFunc)

Constructor

Param	Type	Description
roleIdFetchFunc	fetchRoleIdFunc	function that will let Acl fetch Role id (default will return empty string)
resourceIdFetchFunc	fetchResourceIdFunc	function that will let Acl fetch Resource id (default will return empty string)

Example

var myAcl = new Acl(function(user){
		return Promise.resolve(user.getRole());
}, function(resource){
		return Promise.resolve(resource.getResourceId());
});

acl.setRoleIdFetchFunc(func) ⇒ Acl

Sets how Acl should retrieve Role Id

Kind: instance method of Acl
Returns: Acl - this instance for chaining

Param	Type	Description
func	fetchRoleIdFunc	that will let Acl fetch Role Id from an object that may have a role

acl.setResourceIdFetchFunc(func) ⇒ Acl

Sets how Acl should retrieve Resource Id

Kind: instance method of Acl
Returns: Acl - this instance for chaining

Param	Type	Description
func	fetchResourceIdFunc	that will let Acl fetch Resource Id from an object that may be a resource

acl.addRole(role, Parents) ⇒ Acl

Add a new Role to Access Control List

Kind: instance method of Acl
Returns: Acl - this instanc@e for chaining
Throws:

Error if role is not an instance of Role or a string

Param	Type	Description
role	Role \| string	instance to add
Parents	Array.<string> \| Array.<Role>	default is empty array

Example

acl.addRole('anonyme');
acl.addRole('user', ['anonyme']);
acl.addRole(new Role('admin', ['user'], acl));
acl.addRole('super', [new Role('normal', [], acl)]);

acl.removeRole(role) ⇒ Acl

Deletes role from the list of declared roles

Kind: instance method of Acl
Returns: Acl - this instance for chaining

Param	Type
role	Role \| string

Example

acl.remove('anonymous');

acl.getRole(id) ⇒ Role

Retrieve an instance of Role identified by id. It must be added before calling this function

Kind: instance method of Acl
Returns: Role - a Role instance if it was previously added or null if not exists

Param	Type	Description
id	string	of Role to retrieve

acl.addResource(resource) ⇒ Acl

Add a new resource to Access Control List

Kind: instance method of Acl
Returns: Acl - this instance for chaining
Throws:

Error if resource is not an instance of Acl

Param	Type	Description
resource	Resource	to add to Access Control List

Example

acl.addResource(new Resource('page'));
acl.addResource(new Resource('book', ['read', 'buy']);

acl.removeResource(resource) ⇒ Acl

Removes a resource from Access Control List

Kind: instance method of Acl
Returns: Acl - this instance for chaining
Throws:

Error if resource is not an instance of Resource or of type string

Param	Type	Description
resource	Resource \| string	to remove

Example

acl.removeResource('page');
acl.removeResource(bookResourceInstance);

acl.getResource(id) ⇒ Resource | null

Get resource instance by its Id if it was previously added to Access Control List

Kind: instance method of Acl
Returns: Resource | null - Resource instance if it exists. will return null otherwise

Param	Type	Description
id	string \| Resource	of resource to get

Example

acl.getResource('page');

acl.build() ⇒ Acl

Build all permissions based on added Role and Resource. Permissions are initialized to allow = false and condition = null

Kind: instance method of Acl
Returns: Acl - this instance for chaining

acl.allow(roleId, resourceId, privilege, condition) ⇒ Acl

Allow User with Role Id to access Privileged Resource (which have Resource Id) under condition

Kind: instance method of Acl
Returns: Acl - this instance for chaining

Param	Type	Default	Description
roleId	string \| Role		Role Id or Role instance
resourceId	string \| Resource		Resource Id or Resource instance
privilege	string \| Array.<string>	"*"	Privilege (default is '*' all)
condition	permissionConditionFunc		Conditional permission function (default is null)

Example

acl.allow('user', 'article', 'write')
   .allow('user', 'article', ['read', 'comment']);
   .allow('user', 'article', 'modify', function(user, blog){
		return user.id == article.author_id;
		});

acl.deny(roleId, resourceId, privilege, condition) ⇒ Acl

Deny User with Role Id to access Privileged Resource (which have Resource Id) under condition

Kind: instance method of Acl
Returns: Acl - this instance for chaining

Param	Type	Default	Description
roleId	string \| Role		Role Id or Role instance
resourceId	string \| Resource		Resource Id or Resource instance
privilege	string \| Array.<string>	"*"	Privilege (default is '*' all)
condition	permissionConditionFunc		Conditional permission function (default is null)

Example

acl.deny('anonymous', 'article', 'write')
   .deny('anonymous', 'article', ['modify', 'comment'])
   .deny('anonymous', 'article', 'read', function(user, article){
		return article.is_public;
	  });

acl._allowOrDeny(allow, roleId, resourceId, privilege, condition)

Allow User with Role Id to access Privileged Resource (which have Resource Id) under condition

Kind: instance method of Acl

Param	Type	Default	Description
allow	boolean		true = allowed, false = denied
roleId	string \| Role		Role Id or Role instance
resourceId	string \| Resource		Resource Id or Resource instance
privilege	string	"*"	Privilege (default is '*' all)
condition	permissionConditionFunc		Conditional permission function (default is null)

acl.isAllowed(user, resource, privilege) ⇒ Promise

Checks if user is allowed to access resource with a given privilege. If yes, it checks condition

Kind: instance method of Acl

Param	Type	Default
user	*
resource	*
privilege	string	"*"

Example

acl.isAllowed(userObject, resourceObject, 'read');
acl.isAllowed(userObject, resourceObject);

acl.isRoleAllowed(roleId, resourceId, privilege) ⇒ Promise

Checks if roleId has access to resourceId with privilege. If not, it will check if one of the related parents has access to resource id

Kind: instance method of Acl

Param	Type	Default
roleId	string
resourceId	string
privilege	string	"*"

Example

acl.isRoleAllowed('user', 'book', 'read');
acl.isRoleAllow('user', 'page');

acl.isAnyParentAllowed(roleId, resourceId, privilege) ⇒ Promise

Checks if any role's parents is allowed to access resourceId with privileges

Kind: instance method of Acl

Param	Type
roleId	string
resourceId	string
privilege	string

acl.getPermissions(roleId) ⇒ Array.<Object>

Returns an object representing roleId permissions

Kind: instance method of Acl
Returns: Array.<Object> - Permissions for each resource

Param	Type
roleId	string \| Role

Example

acl.getPermissions('user');

<a name="Role"></a>

Role

Role class

Kind: global class

Role
- new Role(id, parents, acl)
- .setAcl(acl)
- .getAcl() ⇒ Acl | *
- .setId(id) ⇒ Role
- .getId() ⇒ string
- .setParents(parents) ⇒ Role
- .getParents() ⇒ Array | Array.<Role>
- .getParent(role) ⇒ Role | null
- .addParent(role) ⇒ Role
- .addParents(roles) ⇒ Role
- .removeParent({Role|string) ⇒ Role
- .removeParents(roles) ⇒ Role
- .toString() ⇒ string

new Role(id, parents, acl)

Creates a new role and attach it to Acl

Throws:

Error if acl is not an instance of {Acl} or given parents were not declared before

Param	Type	Description
id	string	role's id
parents	Array.<string> \| Array.<Role>	list of parents
acl	Acl	ACL to which this role will be attached

role.setAcl(acl)

Sets the ACL to which this role will be attached

Kind: instance method of Role

Param	Type
acl	Acl

role.getAcl() ⇒ Acl | *

Returns the ACL to which this role is attached

Kind: instance method of Role

role.setId(id) ⇒ Role

Sets the role id of this instance

Kind: instance method of Role
Returns: Role - - This object
Throws:

Error - if id is not a string

Param	Type	Description
id	string	Role identification

role.getId() ⇒ string

Returns this Role id

Kind: instance method of Role
Returns: string - id - Role id

role.setParents(parents) ⇒ Role

Sets role parents.

Kind: instance method of Role
Returns: Role - this instance for chaining
Throws:

Error if one of the given parents was not declared before

Param	Type	Description
parents	Array.<string> \| Array.<Role> \| null	Role parents: must be declared as individual roles before

role.getParents() ⇒ Array | Array.<Role>

Returns parents roles of this instance

Kind: instance method of Role

role.getParent(role) ⇒ Role | null

Get a parent from this role

Kind: instance method of Role
Returns: Role | null - null if parent role was not found

Param	Type	Description
role	Role \| string	id or role instance to retrieve

role.addParent(role) ⇒ Role

Add parent to this role. If it already exists in parents list, it will be replaced

Kind: instance method of Role
Returns: Role - this instance for chaining
Throws:

Error if no Acl was attached to this role or if parent was not declared previously

Param	Type	Description
role	Role \| string	Parent Role instance of its id

role.addParents(roles) ⇒ Role

Add an array of parents role to this instance

Kind: instance method of Role
Returns: Role - this instance for chaining
Throws:

Error if no Acl was attached to this role or if one parent was not declared previously

Param	Type	Description
roles	Array.<Role> \| Array.<string>	to add as parents to this instance

role.removeParent({Role|string) ⇒ Role

Remove a parent from the list of this role's parents

Kind: instance method of Role
Returns: Role - this instance for chaining

Param	Description
{Role	string	role Parent role isntance or its role id

role.removeParents(roles) ⇒ Role

Remove a role from parent list

Kind: instance method of Role
Returns: Role - this instance for chaining

Param	Type	Description
roles	Array.<string> \| Array.<Role>	to remove from parents list

role.toString() ⇒ string

Returns

Kind: instance method of Role
Returns: string - - role Id

Resource

Kind: global class
Trows: Error if privileges is not an Array of strings

Resource
- new Resource(id, privileges)
- .setId(id) ⇒ Resource
- .getId() ⇒ string
- .getPrivileges() ⇒ Array.<string>
- .setPrivileges(privileges) ⇒ Resource
- .addPrivilege(privilege) ⇒ Resource
- .removePrivilege(privilege) ⇒ Resource

new Resource(id, privileges)

Constructor

Param	Type	Description
id	string	of this Resource
privileges	Array.<string>	access privileges for this resource

resource.setId(id) ⇒ Resource

Sets this resource Id

Kind: instance method of Resource
Returns: Resource - instance for chaining
Throws:

Error if id is not a string

Param	Type
id	string

resource.getId() ⇒ string

Retrieve resource id

Kind: instance method of Resource
Returns: string - id of this resource

resource.getPrivileges() ⇒ Array.<string>

Retrieve access privileges for this resource

Kind: instance method of Resource
Returns: Array.<string> - Array of access privileges

resource.setPrivileges(privileges) ⇒ Resource

Sets access privileges for this resource

Kind: instance method of Resource
Throws:

Error if privileges is not an array of strings

Param	Type	Description
privileges	Array.<string>	to set

resource.addPrivilege(privilege) ⇒ Resource

Add an access privilege to this resource

Kind: instance method of Resource
Throw: Error - if privilege is not a string

Param	Type
privilege	string

resource.removePrivilege(privilege) ⇒ Resource

Removes access privilege from this resource

Kind: instance method of Resource
Returns: Resource - - this instance

Param	Type	Description
privilege	string	access privilege to remove

lodash source-map-support debug

@infinitebrahmanuniverse/nolb-dynami @everything-registry/sub-chunk-1541 @zalastax/nolb-dynami

7 years ago

7 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago