restricted gives you scoped Access Control Lists (ACL) for user groups.
What makes restricted different?
Many ACL modules on NPM are tied to frameworks[1][2] or conventions that force you to think in CRUDdy terms[3]. We're trying a different approach.
restricted lets you define cascading permissions, we call them scopes. All scopes are automatically divided into . For example, imagine the following set of possible actions for a guest:
USERS
✅ user.register
✅ user.view
⛔ user.view.email
✅ user.view.username
✅ user.view.photo
With restricted, you can set scopes on both broad and granular permissions for a group.
acl.group('users')
.allow('user')
.allow('user.view.email.own') // Like in CSS, specificity matters
.disallow('user.view.email')Depending on which library you compare with, the potential downside to be aware of is that it expects you to define your groups before you try to test permission scopes aganst them.
npm install restrictedOur recommended implementation strategy is to initialize an AclManager and expose it as a module in your project, letting you interact with the same instance regardless of where in your codebase you are.
const { AclManager } = require('restricted')
const acl = new AclManager
// Non-existent groups are created on the fly
acl.group('guest')
.alias('guests')
.allow([
'blogpost.view',
'comment.view',
'register',
])
acl.group('user')
.inherit('guest')
.allow([
'blogpost',
'comment',
])
.disallow('register')
module.exports = aclWe leave it up to you to decide how to manage memberships and when to actually check for permissions, but a rough implementation could look like this:
class User {
constructor() {
this.groupMemberships = [
'user'
]
}
can(action) {
return acl.can(action, this.groupMemberships)
}
}
// ... then, in your business logic:
user.can('blogpost.edit')-
AclGroup#default()AclGroup#alias()AclGroup#query()AclGroup#allow()AclGroup#disallow()AclGroup#forget()AclGroup#inherit()
The main class that keeps track of your defined groups, and lets you evaluate against them.
const acl = new AclManagerFind an ACL group by name or alias. Creates it if it does not exist.
Returns AclGroup
Alias for canAll()
Returns boolean
Evaluate whether the combination of groups can access all of the scopes.
scopes- a single scope as a string, or an array of several scopesgroups- a single group name as a string, or an array
Returns boolean
Evaluate whether any of the groups is allowed at least one of the scopes.
scopes- a single scope as a string, or an array of several scopesgroups- a single group name as a string, or an array
Returns boolean
Retrieve a list of unique (excluding aliases) AclGroups that have been defined.
Returns array of AclGroup
ACL groups are automatically initialized by the manager when you call AclManager#group(), so normally you wouldn't deal with the constructor itself.
However, if you're into hacking, the call signature is new AclGroup(name, AclManager), where AclManager is the reference to the parent class.
allowed- the fallback state for this group. Can be one oftrue,false,undefined(default)
Returns AclGroup
Register a nickname for the ACL group in the AclManager
aliases- a single group name as a string, or an array
Returns AclGroup
Evaluate whether the group has access to the scope(s).
scopes- a single permission scope as a string, or an array of multiple scopes that the group must be able to access all of.
Returns boolean
Define scope(s) that the group can access.
scopes- a single permission scope as a string, or an array of multiple scopes
Returns AclGroup
AclManager.group('logged-in')
.allow('profile.edit')
.allow(['user.logout', 'comment'])
AclManager.can('profile.edit.photo', 'user') // trueDefine scope(s) that the group is not allowed to access.
scopes- a single permission scope as a string, or an array of multiple scopes
Returns AclGroup
AclManager.group('guest')
.allow('comment.own')
.disallow('comment.own.delete')
AclManager.can('comment.own.delete', 'guest') // falseThe license declaration can be found in LICENSE. (It's MIT)