⛔ restricted

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

• About
• Install
• Quick Start
• API
• License

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

  • AclManager#group()
  • AclManager#can()
  • AclManager#canAll()
  • AclManager#canSome()

• AclGroup

  • AclGroup#default()
  • AclGroup#alias()
  • AclGroup#query()
  • AclGroup#allow()
  • AclGroup#disallow()
  • AclGroup#forget()
  • AclGroup#inherit()

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)