README

browser-acl 🔒

Simple access control (ACL) library for the browser inspired by Laravel's guards and policies.

Go to vue-browser-acl for the official Vue package.

example

Install

npm i browser-acl

Setup

import Acl from 'browser-acl'
const acl = new Acl()

acl.rule('view', Post)
acl.rule('moderate', Post, (user) => user.isModerator())
acl.rule(['edit', 'delete'], Post, (user, post) => post.userId === user.id)
acl.rule('purgeInactive', (user) => user.isAdmin)

Policies (rules through objects or classes) are also supported:

// using an object
acl.policy({
  view: true,
  edit: (user, post) => post.userId === user.id),
}, Post)

// using a class
acl.policy(OrganizationPolicy, Organization)

Note: policies takes precedence over rules.

Usage

// true if user owns post
acl.can(user, 'edit', post)

// true if user owns at least posts
acl.some(user, 'edit', posts)

// true if user owns all posts
acl.every(user, 'edit', posts)

You can add mixins to your user class:

acl.mixin(User) // class not instance

user.can('edit', post)
user.can.some('edit', posts)
user.can.every('edit', posts)

Verb object mapping

The process of mapping a verb object to rules

A verb object is an item, an object, an instance of a class.

The default verb object mapper makes use of "poor-man's reflection", that uses the name of the verb object's constructor to group the rules.

class Post {}
const post = new Post()
post.constructor.name // The verb object is: Post

Warning: When using webpack or similar this method can break if you are not careful.

Since code minifiers will rename functions you have to make sure you only rely on the function to set up your rules and asking for permission.

acl.rule('edit', 'Post', ...)
acl.can(user, 'edit', 'Post')  👍 works as expected
acl.can(user, 'edit', Post)    👎 'Post' isn't the name as you'd expect
acl.can(user, 'edit', post)    👎 same story here

If your build process minifies your code (specifically mangling of function and class names), this will break in line 3 since the constructor of post will likely not be Post but rather a single letter or a name prefixed with __WEBPACK_IMPORTED_MODULE.

- acl.rule('edit', 'Post', ...)
+ acl.rule('edit', Post, ...)
  acl.can(user, 'edit', 'Post')  👍 works as expected
  acl.can(user, 'edit', Post)    👍 and so does this
  acl.can(user, 'edit', post)    👍 this too, but see below

Passing the class or function, Post and whatever that name is after minification, is used to register the rules. As long as the same import is used throughout your code base it will work and you don't need to explicitly register a model.

Best practice

+ acl.register(Post, 'Post')
  acl.can(user, 'edit', 'Post')  👍 works as expected
  acl.can(user, 'edit', Post)    👍 and so does this
  acl.can(user, 'edit', post)    👍 this too

If you are using plain objects you may want to override the verbObjectMapper with a custom implementation.

acl.verbObjectMapper = verbObject => typeof verbObject === 'string'
  ? verbObject
  : verbObject.type

const post = { type: 'post', id: 1, title: 'My first post' }
acl.can(user, 'edit', post) 👍

See more verbObjectMapper

Additional Parameters and Global Rules

You can define global rules by omitting the verb object when defining rules.

acl.rule('purgeInactive', (user) => user.admin)
acl.can(user, 'purgeInactive')

Also you can pass additional parameters to the handler like this:

acl.rule('edit', Post, (user, post, verb, additionalParameter) => true)
acl.can(user, 'edit', post, additionalParameter)

However, you cannot combine the two without explicitly stating that you are defining a global rule. You do this by importing the special GlobalRule verb object.

import { GlobalRule } from 'browser-acl'
acl.rule('purgeInactive', GlobalRule, (user) => user.admin)
acl.can(user, 'purgeInactive', GlobalRule, additionalParameter)

Note: When defining the rule you can omit it, but is is required for can. This is only in the case when you need to pass additional parameters.

API

Acl
- rule
- policy
- register
- can
- some
- every
- mixin
- verbObjectMapper
- reset
- removeRules
- removePolicy
- removeAll

Acl

Simple ACL library for the browser inspired by Laravel's guards and policies.

Parameters

$0 Object (optional, default {})
- $0.strict (optional, default false)
options Object
null Boolean {strict=false}={} Errors out on unknown verbs when true

rule

You add rules by providing a verb, a verb object and an optional test (that otherwise defaults to true).

If the test is a function it will be evaluated with the params: user, verb object, and verbObjectName. The test value is ultimately evaluated for truthiness.

Examples:

acl.rule('create', Post)
acl.rule('edit', Post, (user, post) => post.userId === user.id)
acl.rule(
  'edit',
  Post,
  (user, post, verb, additionalParameter, secondAdditionalParameter) => true,
)
acl.rule('delete', Post, false) // deleting disabled
acl.rule('purgeInactive', (user) => user.isAdmin) // global rule

Parameters

verbs (Array<string> | string)
verbObject (Function | Object | string) ?
test (Boolean | Function) =true (optional, default true)

Returns Acl

policy

You can group related rules into policies for a verb object. The policies properties are verbs and they can plain values or functions.

If the policy is a function it will be new'ed up before use.

class Post {
  constructor() {
    this.view = true // no need for a functon
    this.delete = false // not really necessary since an abscent
    // verb has the same result
  }
  beforeAll(verb, user, ...theRest) {
    if (user.isAdmin) {
      return true
    }
    // return nothing (undefined) to pass it on to the other rules
  }
  edit(user, post, verb, additionalParameter, secondAdditionalParameter) {
    return post.id === user.id
  }
}

Policies are useful for grouping rules and adding more complex logic.

Parameters

policy Object A policy with properties that are verbs
verbObject (Function | Object | string)

Returns Acl

register

Explicitly map a class or constructor function to a name.

You would want to do this in case your code is heavily minified in which case the default mapper cannot use the simple "reflection" to resolve the verb object name.

Note: If you override the verbObjectMapper this is not used, bud it can be used manually through this.registry.

Parameters

klass Function A class or constructor function
verbObjectName string

can

Performs a test if a user can perform action on verb object.

The action is a verb and the verb object can be anything the verbObjectMapper can map to a verb object name.

E.g. if you can to test if a user can delete a post you would pass the actual post. Where as if you are testing us a user can create a post you would pass the class function or a string.

acl.can(user, 'create', Post)
acl.can(user, 'edit', post)
acl.can(user, 'edit', post, additionalParameter, secondAdditionalParameter)

Note that these are also available on the user if you've used the mixin:

user.can('create', Post)
user.can('edit', post)

Parameters

user Object
verb string
verbObject (Function | Object | string)
args ...any Any other param is passed into rule

Returns any Boolean

some

Like can but verb object is an array where only some has to be true for the rule to match.

Note the verb objects do not need to be of the same kind.

Parameters

user Object
verb
verbObjects Array<(Function | Object | string)>
args ...any Any other param is passed into rule

Returns any Boolean

every

Like can but verb object is an array where all has to be true for the rule to match.

Note the verb objects do not need to be of the same kind.

Parameters

user Object
verb
verbObjects Array<(Function | Object | string)>
args ...any Any other param is passed into rule

Returns any Boolean

mixin

Mix in augments your user class with a can function object. This is optional and you can always call can directly on your Acl instance.

user.can()
user.can.some()
user.can.every()

Parameters

User Function A user class or contructor function

verbObjectMapper

Rules are grouped by verb objects and this default mapper tries to map any non falsy input to a verb object name.

This is important when you want to try a verb against a rule passing in an instance of a class.

strings becomes verb objects
function's names are used for verb object
object's constructor name is used for verb object

Override this function if your models do not match this approach.

E.g. say that you are using plain data objects with a type property to indicate the type of the object.

acl.verbObjectMapper = (s) => (typeof s === 'string' ? s : s.type)

can will now use this function when you pass in your objects.

acl.rule('edit', 'book', (user, book) => user.id === book.authorId)
const thing = { title: 'The Silmarillion', authorId: 1, type: 'book' }
acl.can(user, 'edit', thing)

In the example above the 'thing' will follow the rules for 'book'. The user can edit the book if they are the author.

See register() for how to manually map classes to verb object name.

Parameters

verbObject (Function | Object | string)

Returns string A verb object

reset

Removes all rules, policies, and registrations

Returns Acl

removeRules

Remove rules for verb object

Optionally limit to a single verb.

Parameters

verbObject (Object | Function | String)
verb String? an optional verb (optional, default null)

Returns Acl

removePolicy

Remove policy for verb object

Parameters

verbObject (Object | Function | String)

Returns Acl

removeAll

Convenience method for removing all rules and policies for a verb object

Parameters

verbObject (Object | Function | String)

Returns Acl

browser-acl

Usage no npm install needed!

README

browser-acl 🔒

Install

Setup

Usage

Verb object mapping

Best practice

Additional Parameters and Global Rules

API

Table of Contents

Acl

rule

policy

register

can

some

every

mixin

verbObjectMapper

reset

removeRules

removePolicy

removeAll