@slynova/fence

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' })

Testing a Gate

You can test your gate with a short or a long syntax.

// Long
await Guard.can(user).goThroughGate('XXX').for(resource) // true or false

// Short - will need to have an instance of Guard with the specific user
await guard.allows('XXX', resource) // true or false
await guard.denies('XXX', resource) // true or false

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.

Changelog

1.0.3 (2018-07-19)

Bug Fixes

• ability: remove default value for fields (6f2d243)
• bouncer: return this' from 'pass' method (5a724a6)
• bouncer: use lodash instead of ES2015 includes (838db92)
• coverage: fix coverage tool (9b1eaa2)
• export: fix global export (a5dff29)
• Guard: fix method order (c3730f6)
• package: fix github link (8367fe4)
• fix merging conflict (505518c)
• fix testing and guard (2fcedcc)
• remove duplicate from case git issue (b4ab486)
• package: update node-exceptions to version 2.0.0 (5da60bc)
• package: update node-exceptions to version 3.0.0 (83656cf)
• readme: correct title (ede5628)
• test: fix testing policy (039e989)
• travis: update node version needed (08b699f)

Features

• guard: generator is handled correctly (1073117)
• add short syntax (ad5b70b)
• gate: overwrite resourceName formatter (9fd6dd4)
• generator can be used (193b118)
• Guard & Gate become a Facade (f713a6e)
• move to async/await (c812f49)
• move to TypeScript (a107d03)
• Guard: add non-static can method (3f81586)
• Guard: let us override default user in short syntax (757544c)
• policy: add policy management (39661ea)
• policy: allow to call all method for a policy class (d4f1595)
• policy: short syntax denies is available (b83112f)