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 = Acl;var Role = Role;var Resource = 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 ; var ; var {if userfirstname == 'Timmmmy'return ;return ;}; var acl = getUserRoleId getResourceId;acl // equivalent to acl.addRole(new Role('visitor', [], acl)) //equivalent to acl.addRole(new Role('admin', ['user'], acl)); acl; //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; acl; acl; acl; acl; acl; //console.log('---user permissions check---');acl; acl; acl; acl; acl; acl; //console.log('---admin permissions check---');acl;acl;acl;acl;acl;acl;
API Reference
<a name="Acl"></a>
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 = { return Promise;} { return Promise;};
Acl
acl.setRoleIdFetchFunc(func) ⇒ 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
acl.setResourceIdFetchFunc(func) ⇒ 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
acl.addRole(role, Parents) ⇒ 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;acl;acl;acl;
Acl
acl.removeRole(role) ⇒ 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;
Role
acl.getRole(id) ⇒ 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
acl.addResource(resource) ⇒ 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;acl
Acl
acl.removeResource(resource) ⇒ 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;acl;
Resource
| null
acl.getResource(id) ⇒ 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;
Acl
acl.build() ⇒ 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
acl.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
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 ; ;
Acl
acl.deny(roleId, resourceId, privilege, condition) ⇒ 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 ;
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) |
Promise
acl.isAllowed(user, resource, privilege) ⇒ 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;acl;
Promise
acl.isRoleAllowed(roleId, resourceId, privilege) ⇒ 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;acl;
Promise
acl.isAnyParentAllowed(roleId, resourceId, privilege) ⇒ 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 |
Array.<Object>
acl.getPermissions(roleId) ⇒ 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;
<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 | Default | 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 |
Acl
| *
role.getAcl() ⇒ Returns the ACL to which this role is attached
Kind: instance method of Role
Role
role.setId(id) ⇒ 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 |
string
role.getId() ⇒ Returns this Role id
Kind: instance method of Role
Returns: string
- id - Role id
Role
role.setParents(parents) ⇒ 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 |
Array
| Array.<Role>
role.getParents() ⇒ Returns parents roles of this instance
Kind: instance method of Role
Role
| null
role.getParent(role) ⇒ 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
role.addParent(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
role.addParents(roles) ⇒ 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
role.removeParent({Role|string) ⇒ 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
role.removeParents(roles) ⇒ 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 |
string
role.toString() ⇒ 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
resource.setId(id) ⇒ 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 |
string
resource.getId() ⇒ Retrieve resource id
Kind: instance method of Resource
Returns: string
- id of this resource
Array.<string>
resource.getPrivileges() ⇒ Retrieve access privileges for this resource
Kind: instance method of Resource
Returns: Array.<string>
- Array of access privileges
Resource
resource.setPrivileges(privileges) ⇒ 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
resource.addPrivilege(privilege) ⇒ 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
resource.removePrivilege(privilege) ⇒ Removes access privilege from this resource
Kind: instance method of Resource
Returns: Resource
- - this instance
Param | Type | Description |
---|---|---|
privilege | string |
access privilege to remove |