@slynova/fence v1.0.6

fence is a framework-agnostic package which provides powerful ACL abilities to JavaScript. It lets you easily manage ACL with a fluent API easy to learn and to work with. :rocket:

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @slynova/fence
# or
$ yarn add @slynova/fence

When you require the package in your file, it will give you access to the Guard and Gate class.

const { Gate, Guard } = require('@slynova/fence')

Gate & Policy

A Gate is a closure that returns a boolean to determine if the user is allowed to perform a certain action. Instead of using a closure, you can also write a Policy. Those are classes that let you organise your authorisation around a particular model or resource.

Writing a Gate

To define a new Gate you will need to call the define method on the Gate facade.

Gate.define('name-of-the-gate', async (user, resource) => {
  // Payload
  // e.g. return user.id === resource.author_id
})

Writing a Policy

To define a new Policy you will need to call the policy method on the Gate facade.

Gate.policy(post, PostPolicy)

The first argument is the object you want to define the policy for. It can be a simple JSON or an ES2015 class.

The policy must be an ES2015 class.

Guard

The Guard is the guardian of your gates.

Most of the time, you'll want to use the authenticated user to test your gates. For this reason, node-fence let you use the method Guard.setDefaultUser().

// The user can be retrieve from the auth middleware you are using
const guard = Guard.setDefaultUser({ id: 1, username: 'romainlanz' })

Public API

guard.allows('gateName/Policy Method', resource) // It will use per default the defined user or return false if not defined
guard.denies('gateName/Policy Method', resource) // It will use per default the defined user or return true if not defined
guard.allows('gateName/Policy Method', resource, user)
guard.denies('gateName/Policy Method', resource, user)
guard.can(user).pass('gateName').for(resource)
guard.can(user).callPolicy('Policy Method', resource)

Contribution Guidelines

Any pull requests or discussions are welcome. Note that every pull request providing a new feature or correcting a bug should be created with appropriate unit tests.