A lightweight permissioning library.
🏠 Homepage
- node >=18.18.0
npm install allowjs
or
yarn add allowjs
Imports
import Ability, { Permissions, AbilityInterface, NotAuthorizedError } from 'allowjs';
const userAbility = new Ability<User>(abilityInterface => {
const { allow } = abilityInterface;
allow(Permissions.READ, SomeClass, (user: User, entity: SomeClass) => user.id === entity.userId);
});
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.
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)
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)
Out of the box the following permissions are provided:
Permissions.CREATE
Permissions.READ
Permissions.UPDATE
Permissions.DELETE
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);
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);
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.
yarn install
yarn test
yarn prettier:check
yarn lint:check
👤 Peter Myers
- Github: @petermyers
Contributions, issues and feature requests are welcome!
Feel free to check issues page.
Give a ⭐️ if this project helped you!
Copyright © 2020 Peter Myers.
This project is MIT licensed.
This README was generated with ❤️ by readme-md-generator