README

Otzi (Authorization module for SenecaJS)

Otzi is based on the Casbin library to provide a flexible way to handle authorizations in SenecaJS actions

In a Nutshell

By registering the plugin in a Seneca instance, each pattern already added to the Seneca instance is override by a new "authorization" action.

This action evaluates the user's authorizations and call the prior (aka parent) action if access is granted.

As Seneca plugins are registered in a deterministic order, it is important to register Otzi after all the patterns to protect have been declared in the Seneca instance.

Installation

> npm i @aeroline_1025/otzi

Quick start

In order to configure Otzi you should prepare a Casbin model and policies, they will be needed to initialize the plugin

const Seneca = require('seneca')();
const Otzi = require('@aeroline_1025/Otzi');

const options = {
    adapter: './tests/fixtures/casbin_policy.txt',
    model: './tests/fixtures/casbin_model.txt',
    pins: [{ role: 'test' }]
};


Seneca
    .add({ role: 'test', cmd: 'doSomething' }, (msg, done) => {

        console.log(`handler ${msg.value}`);
        done(null, { status: true });
    })
    .use(Otzi, options)
    .ready(function() {
        // Call seneca command
        Seneca
            .listen()
            .act({ role: 'test', cmd: 'list' }, { value: 456 });
    });

How it works

Upon initialization, Otzi plugin override every patterns registered earlier that matched one of the "pins" options.

When an overrode action is executed, Otzi action is run first, it passes the return of the injector function to casbin enforcer parameters. Casbin enforcer evaluates user's authorizations and grant (or not) execution of the action. if access is granted, prior action is called.

Policy evaluation

When evaluating the authorization, Otzi injects message's attributes in Casbin enforcer's request. You can change the default injector function in Otzi's options.

Options

model

String: Passed directly to the casbin enforcer. Check casbin documentation for more information

adapter

String | Object: if string, it is the path to the file containing the policies, will be used by the default FileAdapter. If object, it is an adapter that will be directly passed to casbin enforcer.

pins

Array: An array of patterns to protect with a casbin policy, items could be:

A Jsonic string of a Seneca pattern (more information)
The pattern as a JSON object.
A JSON object with following keys:
- pattern (Jsonic | Object): This key is required.
- inject (function): An injector function with signature (message), this key is optional.

inject

function: function using the signature async function(msg) where:

msg is the message passed to the seneca action.

This function overrides the default injector for Casbin enforcer. It shall return the parameters for Casbin enforcer as an array.

The default inject function is:

const inject = function(userId, msg){

   return [userId, msg.role, msg.cmd]
}

Usage no npm install needed!