canhaz v0.1.0

canhaz - Simple access control.

No assumptions about user model and method of persistence. Classify users into roles. Grant permissions. Check them directly or through a middleware.

Deals with authorization, and nothing else. Plays well with a small-ish number of roles / permissions that doesn't change often -- which is not a very rare case.

Status

• Works. Grant and check simple permissions.
• Check permissions with wildcards in the middle. e.g. a.**.b.*.c

Example (as middleware)

var canhaz = require('canhaz')({
    'somebody': ['stuff']
});

canhaz.role('somebody', function(req) { return !!req.user; });

app.get('/stuff', canhaz('stuff'), function(req, res, next) {
    if (req.authorized)
        res.status(200).send('Hi!');
    else
        res.status(401).send('Pfft.');
});

Config Object

roles

A PlainObject, associating role names with their permissions. i.e. { RoleName: PermissionObject, ... }

Where PermissionObject is either an array consisting of permissions names, or a PlainObject associating permission names with null, indicating no sub-permissions, or a PermissionObject describing sub-permissions:

PermissionObject = PermissionArray | PermissionPlainObject
PermissionArray = [ Name | [ Name, PermissionObject ], ... ]
PermissionPlainObject = { Name: null | PermissionObject, ... }

When the key roles cannot be found in the config object, the object passed is assumed to be roles, and all the flags are set to their default value, as demonstrated in the example above.

Kitchen sink:

var config = {
    roles: {
        'nobody': [],
        'user': {
            'post': {
                'read': null,                 // post.read
                'create': null,               // post.create
                'comment': ['read', 'create'] // post.comment.read/create
            }
        },
        'editor': [['post', ['**.*']]],       // post.**.*
        'admin': ['**.*']                     // **.*
    }
};

allowMiddleWildcards: false

Enables checking of wildcards in the middle.

This is NOT implemented yet!

By default, only single wildcards for the subpermission name, and double wildcards in place for the last resource name are allowed. e.g. 'a.b.c.', 'a.b..d' and 'a.b..', but not 'a.*.b..c'.

Most of the time, this is all you need. However, more complex patterns could sometimes be useful. This flag allows that. Note that it turns the O(L) lookup into a O(NL) search operation, where L equals the '.' level of the query, and N equals the number of defined permission patterns.

memoize: true

Allows memoization of queries.

A naive in-memory store is used. In a typical case with a small-ish number of permissions, the memory usage should not be a problem.

API

require('canhaz')(config, field, classifier)

Creates a canhaz middleware factory instance.

config: PlainObject|String -> [String], Used to get eligible roles by permission. When object, should be a permission config object. When function, should return all eligible roles by permission.

field: String, Field name on request object to fill when used as middleware. Defaults to 'authorized'.

classifier: Classify, When not omitted, use the provided Classify instance instead of a new one.

Returns: function, The canhaz middleware factory.

canhaz(...names)

Creates a middleware instance.

names: ...String, Permissions to check for.

Returns: Middleware, Connect/Express middleware that checks for the specified permissions.

canhaz.query(permissions, context, next)

Manually query whether a set of permissions are given.

permissions: [String], Permissions to check for.

context: *, Context for role classification.

next: Boolean ->, Callback function.

canhaz.role(name, inherits, criteria)

Adds a role to the factory instance. If a role of the name already exists, appends the new criteria to it.

name: String, Name of the role.

inherits: [String], Names of prerequisite roles.

criteria: * -> Boolean|*, (Boolean ->) ->, Criteria function that is either synchronous or with a callback.

canhaz.removeRole(name, inherits, criteria)

Removes a role from the instance.

name: String, Name of the role.

License

The MIT License.