#ah-tdp-acl-plugin

##Version
Master: v2.2.1

##Semver This project aims to maintain the semver version numbering scheme.

##Changelog See the changelog file

##Overview A fast, secure role-based access control list (ACL) plugin for actionhero

ah-tdp-acl-plugin is designed specifically for use with the actionHero API framework and thus is unlikely to work directly with any other application. You're welcome to fork and modify of course if that is of interest of course.

##Features

• Role-based access control (RBAC) to resources (API endpoints A.K.A. actions) by their actionhero API call path
• Supports all actionhero servers
• Configuration options:
  • Roles can inherit permissions from other roles
  • Unlimited number of rules per role
  • Unlimited number of roles
  • Resource (action) deny/allow rulescan be action version number-dependent
  • Allow and deny rules with configurable order (allow then deny or deny then allow)
  • Wildcards are supported for API call paths e.g. path/to/api/endpoint/*
  • Configurable role variable location (default: connection.sessionData.role)
• Extremely fast - per-request overhead is minimal, not much more than a single function call which executes simple checks and an if()
• Asynchronous operation throughout
• Included unit tests, automatically run via Travis-CI
• Included default actions for automated testing
• Included initialiser
• Supports dedicated per actionhero environment configurations

##Requirements
###Prerequisite since it's the plugin host

• actionhero

###Production requirements

• semver

###Development/test requirements

• mocha
• should
• actionhero

##Installation Installation is relatively simple and is simplest using npm:

# Install actionhero (skip this if you have already got it installed)
npm install actionhero

# Generate a skeleton actionhero project (skip if already done)
./node_modules/.bin/actionhero generate

# Install ah-tdp-acl-plugin (and save to package.json file - optional)
npm install ah-tdp-acl-plugin --save

Then you'll need to edit the actionhero config file, config/api.js and add the plugin name into the plugins array.

After that, you can start your API server using npm start.

No doubt you'll want to change lots more things but the above is a generic set of instructions.

##Usage This module is an actionhero plugin so it conforms to the base requirements, this means it provides:

• Actions
• An initialiser
• An editable, userland config file (which is actionhero 'environment' (development, production etc.) aware) which will appear as <project root>/config/plugins/AHTDPACLPlugin.js assuming the postinstall NPM script worked properly
• The core module itself

##Configuration You should edit the userland config file as required, this is where you can customise the module to fit your project requirements. This file will not be replaced by module updates so you need to manually keep it up to date, at least until I create some automated method.

For detailed explanation of the fields, check the userland or default config file comments.

###Configuration file: environments Configuration options can be defined for all or (overridden) for individual environments using the following structure:

exports.default=
{
    AHTDPACLPlugin: function(api)
    {
        return {
            ...
        }
    }
}

exports.production=
{
    AHTDPACLPlugin: function(api)
    {
        return {
            ...
        }
    }
}

...

This structure is as per the common actionhero configuration model. The environment is set via a environment variable (on *nix systems this is NODE_ENV) which override the base/default options in exports.defaults{}. So you should put common (environment agnostic/independent) configuration options in the exports.defaults{} section and then override/augment those with any environment-specific options as required.

##Actions The included actions are for automated testing only and can be ignored.

##Constructor The constructor is very simple and since the module is function-scoped, it requires the 'new' syntax in the constructor to instantiate a new instance e.g.:

var AHTDPACLPlugin=require("ah-tdp-acl-plugin");
var acl=new AHTDPACLPlugin(api); // (where api is the actionhero api instance)
...

The module will self-initialise, using the actionhero environment-specific config options. A successful initialisation results in an object being returned

##Public methods

###General principals All public methods conform to the below principals:

• They are asynchronous and thus receive a callback function as the last argument
• They will (in async mode) return two values, error and result, where:
  • error is a string, object or array if an error occurred, null otherwise
  • result is a string, object, array, number etc. on success, null otherwise
• They will never throw errors, instead they will return accordingly
• All arguments are required

###roleHasPermissionsOnAction(role, actionName, actionVersion, callback) Determine whether a user (via their assigned role) has permission to run the requested resource (action) via the action name and version.

####Arguments #####role (string) The role of the user requesting the resource

#####actionName (string) The action name of the resource (API endpoint/method) the user is requesting

#####actionVersion (string) The action version (in semver format) of the resource (API endpoint/method) the user is requesting

#####callback (function) The callback function to execute on completion of this function.

####Returns (callback arguments) The callback function currently receives only one argument:

• success (boolean) - true if the user role does have permission on the requested resource/version

###getUserRole(connection, callback) Gets the user role for the specified connection.

####Arguments #####connection (object) The actionhero connection object. This is user-specific and thus can contain their session data.

#####callback (function) The callback function to execute on completion of this function.

####Returns (callback arguments) The callback function currently receives only one argument:

• err (string || null) - A descriptive error string if an error occurred or null otherwise
• role (string || null) - A user role as a string if a role was found or null otherwise

###normaliseActionVersion(actionVersion) Normalises an action version to be in a standard, semver format. It will return the unaltered action version if it's already semver compliant, otherwise will convert:

• "2" to "2.0.0"
• "2.0" to "2.0.0" and as a last-ditch will return "1.0.0".
  As such, it's guaranteed to always return a semver compliant version number.

####Arguments #####actionVersion (string || number) The string or number (integer or floating point) representing the action version number e.g. 2, 2.0, 2.0.0 or 2.0.0-alpha etc.

####Returns (callback arguments)

• actionVersion in semver format

###normaliseActionName(actionName) Normalises the action name. Currently, this simply does a .toString().trim() on the action version and returns the result.

####Arguments #####actionName (string) The string action name

####Returns (callback arguments)

• actionName as a trimmed, forced string

##Known issues

• Verify: Looks like wildcard rules may only match the first matching rule

##To do/roadmap

• Check whether wildcard rules are working correctly in terms of matching multiple sub directories and document it
• Create test(s) which verify deny,allow versus allow,deny
• Ensure default config is coherent with other plugins
• Consider splitting config into a main file and several json files which are included. This would allow programmatic amending of config.

##Tests Tests currently run automatically in travis and use mocha and should.

##License ah-tdp-acl-plugin is issued under a Creative Commons attribution share-alike license. This means you can share and adapt the code provided you attribute the original aclor(s) and you share your resulting source code. If, for some specific reason you need to use this library under a different license then please contact me and i'll see what I can do - though I should mention that I am committed to all my code being open-source so closed licenses will almost certainly not be possible.