Koa-permissions

A library providing permissions utility methods and a middleware to protect routes and or attributes based on koa-acl

Features

• Roles Based Access control
• Attribute restriction based on role
• Attribute injections into this.request.body based on defined role-relation values

Todo

• Socket.io support

Installation

  npm install koa-permissions --save

Usage

Setting permissions.

permissions are to be save in JSON object either hardcoded for now or in a JSON file that is put into ACL options.

var permissions = [
    {
        roles:['admin', 'staff'],
        allows:[
            {resources:'/api/users', permissions: ['post','get'], blacklist:['balance', 'age'], relation:'owner'},
            {resources:'/api/events', permissions: ['get'], blacklist:['balance', 'age']},
        ],
    },
    {
        roles:['guest'],
        allows:[
            {resources:'/api/users', permissions: ['get'], blacklist:['balance', 'age'], relation:'owner'}
        ]
    }
}

• blacklist - array of blacklisted words. if found in the query app sends 403 message.
• relations - used to inject object into query based on role relationship array. e.g relation owner injects {owner : userID} into this.request.body, note that user getter must return an object for this to work and object must contain the object keys used in the permissions object

Available backends.

Using redis backend

new acl.redisBackend(redisClient, prefix);

Or Using the memory backend

new acl.memoryBackend();

Or Using the mongodb backend

new acl.mongodbBackend(dbInstance, prefix);

Methods

Acl(options)

Configure options for Acl.

Arguments

options.user    {Object|Function} user getter.
options.backend {Object|Function} backend getter.
options.permissions {Object:Function} permissions getter.
 

---

Acl.middleware(numPathComponents[, userId, actions])

Authorizing by user.

Arguments

numPathComponents   {Number}    number of components in the url to be considered part of the resource name (defaults to number of components in the full url).
userId {String|Function}   user ID (defaults to options.user).
actions {String|Array}    lowercase.

---

Setting Options

ACL function takes either string or function as options. which are values that hen become accessible to the underlying acl function including the middleware backend can be memory of

var ACL = require('koa-permissions');
var backend = new Acl.memoryBackend();
 
app.use(
    ACL({
        user: ctx => {
            return ctx.state.user   //Accepts String or Object
        },
        backend: ctx => {
            return Promise.resolve(backend)   //backend getter
        },
 
        permissions: ctx => {
           return permissions   //permissions getter
        }
    })
);

---

Custom Middleware Example

ACL.middleware = (numPathComponents, userId, actions) => {
    return function*(next) {
        var _userId, _resource, _session, _actions, _permissions
        this.state.numPathComponents = numPathComponents;
        this.state.userId = userId;
        this.state.actions = actions;
        var ctx = this;
 
        function* args(next) {
          _actions = this.state._actions;
          _resource = this.state._resource;
          _userId = this.state._userId;
          _session = this.state._session;
          _permissions = this.state._permissions
            yield next
        };
 
        function* control(next) {
            //custom ACL function
            yield next
        };
 
        yield ACL.default.call(this, args.call(this, control.call(this, next)));
    };
};```
 
----------
 
#### Middleware Usage
 
Simple Middleware to run the permissions module. See methods for parameters
 
```js
route.delete(
    '/api/users/:user',
    ACL.middleware(2),
    function* (next) {
        //do something...
    }
);

NB: if no args are supplied to ACL.middleware then resources longer than those in permissions will be disallowed. e.g

for /api/users/11

ACL.middleware()

Matches full resources Only

ACL.middleware(2)

Matches /api/users and /api/users/X

---

Accessing acl methods

All functions under acl are found under the this.acl object or ACL.options.acl object. This allows developers to use acl functions anywhere within the app. see node-acl function for more guidance.

ACL.options.acl
 
or
 
this.acl

Tests

  npm test

---

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code.

Release History

• v1.0.4
  • Refined Restriction module to inject attribute based on relations.
  • tweaked User Getter to allow objects
  • redesign to allow custom acl middlware with standard attributes
• v1.0.3
  • Fixed readme and Test
• v1.0.2
  • Added more Test
• v1.0.0
  • Initial release

---

Authors

• Tonderai Khatai

---

Licences

MIT