Ah-tdp-auth-plugin NPM

#ah-tdp-auth-plugin

##Version Master: v2.0.4

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

##Changelog See the changelog file

##Overview A fast, comprehensive, secure authentication plugin for actionHero with a MongoDB storage layer.

ah-tdp-auth-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

Configurable, cryptographically strong password hashing with configurable per-user salting. Configurable options are:
- Cipher (e.g. SHA256)
- Digest (e.g. base64)
- Salt length
Strict user input filtering on all fields in all methods
Configurable complexity requirements on all critical authentication parameters (with sensible defaults) e.g.
- Required/optional fields
- Min and max length conditions
- Must-contain conditions (you may specify one or more regexs)
- Disallowed character checking (e.g. non-printables as default setting)
- Predefined value-set restriction (like SQL enumerated fields)
- Allowed data type constraints e.g. String, Number etc.
Configurable password expiry periods
Includes user role (designed to be used with an ACL such as my own TDP-AH-ACL)
Configurable, automatic (on initialisation) index creation with constraints e.g. unique, dedupe, creation in background etc.
Optional soft deletion of user accounts (to enable post-deletion lookups for historical records)
Fast - most operations complete in a low, single-digit number of milliseconds on a moderately powered system
Asynchronous operation throughout
Included unit tests, automatically run via Travis-CI
Included default actions for all public methods
Included initialiser
MongoDB back end
- Optional MongoDB authentication (use it!)
- Configurable MongoDB server address/socket and port
- Configurable database and collection names

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

actionhero

###Production requirements

###Development/test requirements

##Installation Installation is relatively simple and is simplest using npm (optionally, suffix with --save as shown below to add the package to the local package.json file):

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

# Generate a skeleton actionhero project
./node_modules/.bin/actionhero generate

# Install ah-tdp-auth-plugin
npm install ah-tdp-auth-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/AHTDPAuthPlugin.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=
{
    AHTDPAuthPlugin: function(api)
    {
        return {
            ...
        }
    }
}

exports.production=
{
    AHTDPAuthPlugin: 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.

##Configuration file: fields You can configure the fields you want to be able to use with this module by adding them to the configuration file. You should not remove any of the default fields as they are required by the processing logic (though you can remove them from user-level output - see below).

##Configuration file: field constraints This module allows for several complexity and content requirements to be configured for each field. A full example of the current fields is shown below, using the userID field defaults as an example:

userID:
{
    required:true, // Is the field required?
    allowedTypes:["string"], // Allowed data types (currently only values returnable from typeof() are supported) (array, leave empty or omit to allow any data type)
    disallowedCharsRegex:/[^\x20-\x7e]/, // Disallowed chars (regex)
    mustContainCharsRegexArray:[/[a-z]/,/[A-Z]/], // Array of regex's which MUST be present in the value supplied (array of regex's)
    minLength:8, // Min length (chars) of passwords to allow (int)
    maxLength:null, // Max length (chars) of passwords to allow (int)
    defaultValue:null, // Default value if none is supplied, can be a function which must return one value, that being the defaultValue you want to set if none is supplied
    removeFromInput:false, // Remove from user input before processing (you normally should not edit this) (boolean)
    removeFromOutput:false // Remove from output before returning from functions. Ensure any sensitive fields (e.g. passwords, salts etc.) are removed (boolean)
}

##Actions A default set of actions are provided. You can choose to use or replace these as you see fit.

The default actions are in /actions/AHTDPAuth in this plugin module. The default actions are all "namespaced" via the AHTDPAuth prefix (to help avoid clashes) and thus from the front end you'd call them as such e.g. for the authenticateUser action, you'd do:

//....
client.action("ah-tdp-auth-plugin/authenticateUser", {u: "someUser", p:"somePassword"}, function(response)
{
    console.log("Server output is:");
    console.dir(response);
});

##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 AHTDPAuthPlugin=require("ah-tdp-auth-plugin");
var auth=new AHTDPAuthPlugin(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 filter all user input and output based on youre configured options in userObjectProperties
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

###createUser(userObjectToCreate, callback) Create user method.

####Arguments #####userObjectToCreate (object) An object containing properties commensurate with the configured userObjectProperties. The validity of the object will be checked prior to processing.