restricted

1.0.1 • Public • Published

⛔ restricted

npm version CircleCI Issues

restricted gives you scoped Access Control Lists (ACL) for user groups.


About

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.


Install

npm install restricted

Quick Start

Our 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 = acl

We 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')

API


new AclManager()

The main class that keeps track of your defined groups, and lets you evaluate against them.

const acl = new AclManager

AclManager#group(name)

Find an ACL group by name or alias. Creates it if it does not exist.

Returns AclGroup


AclManager#can()

Alias for canAll()

Returns boolean


AclManager#canAll(scopes, groups)

Evaluate whether the combination of groups can access all of the scopes.

  • scopes - a single scope as a string, or an array of several scopes
  • groups - a single group name as a string, or an array

Returns boolean


AclManager#canSome(scopes, groups)

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 scopes
  • groups - a single group name as a string, or an array

Returns boolean


AclManager#originalGroups()

Retrieve a list of unique (excluding aliases) AclGroups that have been defined.

Returns array of AclGroup


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.


AclGroup#default(allowed)

  • allowed - the fallback state for this group. Can be one of true, false, undefined (default)

Returns AclGroup


AclGroup#alias(aliases)

Register a nickname for the ACL group in the AclManager

  • aliases - a single group name as a string, or an array

Returns AclGroup


AclGroup#query(scopes)

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


AclGroup#allow(scopes)

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') // true

AclGroup#disallow(scopes)

Define 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') // false

License

The license declaration can be found in LICENSE. (It's MIT)

Package Sidebar

Install

npm i restricted

Weekly Downloads

7

Version

1.0.1

License

MIT

Unpacked Size

21.1 kB

Total Files

14

Last publish

Collaborators

  • sleavely