picatic/node-permission-architect

Provides a dynamic ACL framework, where you fill in the blanks.

Why another ACL manager?

Something that has bothered me about some ACL managers is how restricted they are. I often come across cases where dynamically determining the role based on more than ACL records is required. I also wanted to reflect different permissions based on the resources life cycle. I also wanted something that was not coupled to any sort of datasource. Sometimes you can do things statically, other times you can query a datasource to get what you need to know.

I wanted to provide a layer that clearly defined what handled determining the role and permissions of each part of the system.

Features

• You provide the data layer
• Built for async work-flows
• Supports multiple instances, so you can provide different ACL mappings within the same process.
• You can pass your own context/state to use within each Provider
• Easy to migrate too from your existing ACL system (probably, let us know!)
• Bunyan compatible logger

Some implementation details

• If a method takes multiple models, they will always be in this order: Profile, Resource, Role, Permission.
• null is considered intentionally not defined.

Model

SessionRegistry

An globally registred instance with an optional name.

var sessionRegistry.get();

// Or

var sessionRegstry.get('myInstance');

Profile

This represents an accessor of resources. In most cases, a User. It could also indicate a Group, Organization or any other sort accessor you which to check.

var profile = sessionRegistry.buildProfile('User', 1000, userModel);

Resource

This represents something to be accessed. Common cases are models: User, Profile, Post, etc. But could also reflect actual resources: A queue, ports, etc.

var resource = sessionRegistry.buildResource('Post', 2000, postModel);

RoleProvider

Every combination of Profile to Resource has to register a RoleProvider. This provider is tasks with determining what role best fits the provided profile and resource. You can statically code these, or have it look up the roles from your datasource.

var roleProvider = sessionRegistry.buildRoleProvider('User', 'Post', {
  getRoles: function(roleProvider, profile, resource, callback) {
    var role = this.sessionProvider.buildRole('owner', profile, resource);
    callback(null, [roll]);
  }
});

RoleProviderRegistry

After creating a RoleProvider you need to register it so future lookups can be completed.

sessionRegistry.registerRoleProvider(roleProvider);

PermissionProvider

PermissionProviders provided for each permission on a named Resource.

var create = sessionRegistry.buildPermissionProvider('create', {
  getPermission: function(permissionProvider, resource, role, cb) {
    return permissionProvider.getSessionRegistry().buildPermission(true, {}, permissionProvider);
  }
}
);

PermissionRegistry

A collection of PermissionProviders for a named Resource must be registered for future lookups.

sessionRegistry.registerPermissionProvider('Post', [create]);

Permission

Represents a permission derived from a PermissionProvided with a provided Resource.

sessionRegistry.buildPermisison(
  true, //granted or not
  {limit: 10}, //additional contextual information you can provided
  permissionProvider // reference to the permissionProvider that made this Permission
);

Usage

rolesFor

Find all the applicable Roles for the provided Profile and Resource.

sessionRegistry.rolesFor(profile, resource, function(err, roles) {
  // roles is an array of Role
});

## bestRoleFor

Find a single Role that is the best by weight.

sessionRegistry.bestRoleFor(profile, resource, function(err, role) { // role is a single Role });

getPermission

Fetch a Permission for a Resource being accessed with the provided Role.

sessionRegistry.getPermission('create', resource, role, function(err, permission) {
  if (permission.granted === false) {
    throw new Error('Permission denied');
  } else {
    // granted!
  }
}
});

node-permission-architect's Issues

Fill in [description] seconds in jsdocs

Complete the package.json details

Session Interface

Provide interface that is implemented by the entry registry but also allows sub sessions based on those registered sessions.

Role contain references to Profile and Resource when created

To ensure a role is not misused to authorize an unrelated permission later on.

Cache Role Lookups

Cache Role Lookup calls

Working Static Example

Create an example project that probes a few of the common use cases.

Enforce RoleProvider implementation return Role instances

implment bestRoleFor(profile, resource, cb)

On SecurityRegistry provide a way to get a single role back.

Return Type check errors on async methods that are passed incorrect [arams

Working towards strict enforcement of types to prevent undefined behaviour within the SecurityRegistry.

Require Role's to be Registered

Building roles in the SecurityRegistry factory method skips the weight assignment and possibly lets roles that are not expected to be specified.

• add registerRole(name, weight=0)
• update buildRole(name) to require the role to be previously registered and assign the weight
• throw Exception on buildRole if Role not registered

Permissions are strict on using a Role that was derived for the Resource in question

Prevent a role derived from a different combination of Profile/Resource from being using with a different Resource.

Log when a fallback is used

If the fallback role/permission gets used, log it as a warning.

PermissionProvider contains reference to SecurityRegsitry

Set with constructor, accessed via setter/getter

Logger message as INFO that should be TRACE

When calling securityRegistry.getPermission(...)

Permission read on TicketPriceModelProxy (undefined) as guest => true

Add bunyan logger

Allow security-context to have a bunyan style logger instance assigned. Providers/Resolvers will log if present.

Support Promises

Waiting for native promises, but when they come we will add them.

sync methods should indicate success/failure with return result

Better to be verbose than eat error conditions or make bad assumptions when it comes to security.

Update readme documentation

sync methods throw exceptions on invalid parameter type related issues

Another strict type enforcement measure.

Provide prototype.toString implementations on models

Should simplify debugging and logging.

Implement remove TicketPriceModelProxy

Missed implementing this. Should clean up a TPD if required.

Rename Security Registry to something more project related

Cache Permission Lookups

Cache Permission lookups

Write blog post on gh_pages on simple ACL use case

Great gh_pages site

Setup gh_pages with a plain template for site, update package.json for new homepage

Reverse calling implementations in scope of their providers

Turns out this was a terrible idea, preventing parameterized classes from being used to implement similar functionality in practical applications.

To implementations method prototypes will be adjusted to accept the provider as a reference to compensate.

implementations need to be called within the models scope

Will need to wrap calls to user provided implementations with .apply(this, ...)