Fellowship
An unopinionated bitwise memory based ACL. To be used as a low level base for implementing a persistant module.
Installation
npm install fellowship --save
Usage
var Fellowship = require('fellowship')
, resources = { resourceOne: { permission1: 1, permission2: 2, permission3: 4 } }
, groups = { Admin: { resourceOne: 6 }}
, acl = new Fellowship(resources, groups)
acl.hasPermission('Admin', 'resourceOne', 'permission1')
acl.hasPermission('Admin', 'resourceOne', 'permission2')
acl.hasPermission('Admin', 'resourceOne', 'permission3')
acl.addResource('Blog', [ 'create,', 'read', 'update', 'delete' ])
acl.addGroup('Moderator')
acl.addPermission('Moderator', 'Blog', 'create')
acl.hasPermission('Moderator', 'Blog', 'create')
acl.addGroup('Root')
acl.addPermission('Root', 'Blog', '*')
acl.hasPermission('Root', 'Blog', 'read')
Methods
addGroup (name, [resourcePermissions])
- name - The identifier to the group, either a name or a data based id
- resourcePermissions - An optional object of permissions, e.g.
{ permission1: 1, permission2: 2, permission3: 4 }
addResource (name, permissions)
- name - The identifier to the resource, either a name or a data based id
- permissions - An array of permissions, e.g.
[ 'create,', 'read', 'update', 'delete' ]
addPermission (groupName, resourceName, permissionName)
- groupName - The identifier to the group, either a name or a data based id
- resourceName - The identifier to the resource, either a name or a data based id
- permissionName - Self explanatory, will throw an error if resource does not have such a permission
addPermission (groupName, resourceName, permissionNames)
- groupName - The identifier to the group, either a name or a data based id
- resourceName - The identifier to the resource, either a name or a data based id
- permissionNames - Self explanatory, array of permission names, will throw an error if resource does not have such a permission
Internally uses addPermission
deleteGroup (groupName)
- groupName - The identifier to the group, either a name or a data based id
deletePermission (resourceName, permissionName)
- resourceName - The identifier to the resource, either a name or a data based id
- permissionName - Self explanatory, will throw an error if resource does not have such a permission
Recalculates permission values and group resource values
deleteResource (resourceName)
- resourceName - The identifier to the resource, either a name or a data based id
Also removes the resource from all groups, use removeResource to only remove it from a particular group
getGroup (name)
- groupName - The identifier to the group, either a name or a data based id
Returns the groups resource permissions
getResource (name)
- name - The identifier to the resource, either a name or a data based id
Returns the resources permissions and their associated 'bit' value
hasPermission (groupName, resourceName, permissionName)
- groupName - The identifier to the group, either a name or a data based id
- resourceName - The identifier to the resource, either a name or a data based id
- permissionName - Self explanatory, will throw an error if resource does not have such a permission
Returns true if group has permission, false if not
newPermission (resourceName, permissionName)
- resourceName - The identifier to the resource, either a name or a data based id
- permissionName - Self explanatory, will throw an error if resource does not have such a permission
Adds a new permission to the resource, maximum of 31 permissions per resource
removePermission (groupName, resourceName, permissionName)
- groupName - The identifier to the group, either a name or a data based id
- resourceName - The identifier to the resource, either a name or a data based id
- permissionName - Self explanatory, will throw an error if resource does not have such a permission
Removes the permission from the group, and recalculates resource value for group
removeResource (groupName, resourceName)
- groupName - The identifier to the group, either a name or a data based id
- resourceName - The identifier to the resource, either a name or a data based id
Removes the resource from the group
Events
Every method apart from getters emit an event
fellowship.on('permission.removed', function (groupName, resourceName, permissionName) {
console.log(groupName, resourceName, permissionName)
})
-
group.added (name, resourcePermissions)
-
permission.added (groupName, resourceName, permissionName)
-
permissions.added (groupName, resourceName, permissions)
-
resource.added (name, permissions)
-
group.deleted (name)
-
permission.deleted (resourceName, permissionName)
-
resource.deleted (resourceName)
-
permission.new (resourceName, permissionName)
-
permission.removed (groupName, resourceName, permission)
-
resource.removed (groupName, resourceName)
FAQ
Why is there a limit on the amount of permissions per resource?
This is due to 32bit operations within JavaScript. If you find yourself needing a resource with more than 31 permissions, you should look into refactoring.
Bad
fellowship.addResource('Forum', [ 'createtopic', 'createpost', 'locktopic' ])
Good
fellowship.addResource('Topic', [ 'create', 'lock' ])
fellowship.addResource('Post', [ 'create', 'edit', 'delete' ])