👋
Welcome to Allow
A lightweight permissioning library.
🏠 Homepage
Prerequisites
- node >=10.0.0
Installation
npm install allowjs
or
yarn add allowjs
Usage
Imports
import Ability, { Permissions, AbilityInterface, NotAuthorizedError } from 'allowjs';
Simple Allowance
const userAbility = new Ability<User>(abilityInterface => {
const { allow } = abilityInterface;
allow(Permissions.READ, SomeClass, (user: User, entity: SomeClass) => user.id === entity.userId);
});
Disallowing
const userAbility = new Ability<User>(abilityInterface => {
const { allow, disallow } = abilityInterface;
allow(Permissions.READ, SomeClass, (user: User, entity: SomeClass) => user.id === entity.userId);
disallow(Permissions.READ, SomeClass, (user: User, entity: SomeClass) => user.roles.includes("role"));
});
Permissions are granted based on the following conditions:
- At least one
allow
criteria is satisfied the by provided user. - No
disallow
criteria are satisfied by the provided user.
Checking Permissions
You can check permissions by using permits
and ensures
functions on the ability.
-
permits
- Will return a boolean, whether or not the user has the specified permissions. -
ensure
- Will throw aNotAuthorizedError
if the user does not have the required permissions. This can be useful in frameworks like Express where you can specify an error handler for this type of exception and return a 401 status code.
if(userAbility.permits(user).toPerform(Permissions.READ).on(someEntity)) {
// Take some action
}
// Throws a NotAuthorizedError if user cannot perform READ on someEntity
userAbility.ensure(user).canPerform(Permissions.READ).on(someEntity)
Class Level Permissions
You can also specify that some particular user has permissions broadly across some class type.
const userAbility = new Ability<User>(abilityInterface => {
const { allow, disallow } = abilityInterface;
allow(Permissions.READ, SomeClass, (user: User) => user.roles.includes('role'));
});
and check them by passing in the class type instead of an instance during the permissions check
if(userAbility.permits(user).toPerform(Permissions.READ).on(SomeClass)) {
// Take some action
}
or
// Throws a NotAuthorizedError if user cannot perform READ on SomeClass
userAbility.ensure(user).canPerform(Permissions.READ).on(SomeClass)
Default Permissions
Out of the box the following permissions are provided:
Permissions.CREATE
Permissions.READ
Permissions.UPDATE
Permissions.DELETE
CRUD Expansion
Permissions.CRUD
is provided as a shorthand for specifying all of Permissions.CREATE
, Permissions.READ
, Permissions.UPDATE
, and Permissions.DELETE
.
allow(Permissions.CRUD, SomeClass, (user: User, entity: SomeClass) => entity.userId === user.id);
// is equivalent to
allow(Permissions.CREATE, SomeClass, (user: User, entity: SomeClass) => entity.userId === user.id);
allow(Permissions.READ, SomeClass, (user: User, entity: SomeClass) => entity.userId === user.id);
allow(Permissions.UPDATE, SomeClass, (user: User, entity: SomeClass) => entity.userId === user.id);
allow(Permissions.DELETE, SomeClass, (user: User, entity: SomeClass) => entity.userId === user.id);
Custom Permissions
You can provide permissions in the form of a string if the standard CRUD
operations are insufficent.
userAbility.allow('permission.custom', SomeClass, (user: User, entity: SomeClass) => entity.userId === user.id);
userAbility.permits(user).toPerform('permission.custom').on(someEntity);
Freeform Entity Types
You can also specify a custom entity type that isn't restricted to a particular class as a name string. When checking the permissions against the object, you will need to specify the type you want to treat it as.
userAbility.allow(Permission.READ, 'type.custom', (user: User, entity: { userId: string }) => entity.userId === user.id);
userAbility.permits(user).toPerform(Permission.READ).on(someObject, 'type.custom');
If you don't mind it, you could also just entity: any
in plcae of the entity
type definition.
Development
Install
yarn install
Tests
yarn test
yarn prettier:check
yarn lint:check
Author
- Github: @petermyers
🤝 Contributing
Contributions, issues and feature requests are welcome!
Feel free to check issues page.
Show your support
Give a
📝 License
Copyright © 2020 Peter Myers.
This project is MIT licensed.
This README was generated with