allowjs

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 a NotAuthorizedError 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

👤 Peter Myers

• Github: @petermyers

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page.

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2020 Peter Myers.
This project is MIT licensed.

---

This README was generated with ❤️ by readme-md-generator