https://github.com/slynova-org/fence
🔰 Framework-agnostic package who provides powerful ACL abilities to JavaScript
https://github.com/slynova-org/fence
acl acl-abilities framework-agnostic javascript nodejs security
Last synced: about 1 year ago
JSON representation
🔰 Framework-agnostic package who provides powerful ACL abilities to JavaScript
- Host: GitHub
- URL: https://github.com/slynova-org/fence
- Owner: Slynova-Org
- License: mit
- Created: 2016-06-06T14:46:37.000Z (about 10 years ago)
- Default Branch: develop
- Last Pushed: 2023-09-05T15:17:30.000Z (almost 3 years ago)
- Last Synced: 2025-04-11T20:08:45.057Z (about 1 year ago)
- Topics: acl, acl-abilities, framework-agnostic, javascript, nodejs, security
- Language: JavaScript
- Homepage:
- Size: 377 KB
- Stars: 65
- Watchers: 4
- Forks: 6
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
`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](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).
```bash
$ 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.
```javascript
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.
```js
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.
```js
Gate.policy(post, PostPolicy)
```
The first argument is the object you want to define the policy for. It can be a [simple JSON](https://github.com/Slynova-Org/node-fence/blob/master/tests/stubs/post.json) or an [ES2015 class](https://github.com/Slynova-Org/node-fence/blob/master/tests/stubs/Post.js).
The policy must be an [ES2015 class](https://github.com/Slynova-Org/node-fence/blob/master/tests/stubs/PostPolicy.js).
## 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()`.
```js
// The user can be retrieve from the auth middleware you are using
const guard = Guard.setDefaultUser({ id: 1, username: 'romainlanz' })
```
### Public API
```js
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.