cantina-permissions

Utilizes node-relations for permissions stored in redis.

Table of Contents

• Usage
• Example
• API Reference
  • app.permissions
    • app.permissions.define(context, roles)
    • app.permissions[context].grant(role, args, cb)
    • app.permissions[context].revoke(role, args, cb)
    • app.permissions[context].hasRole(role, args, cb)
    • app.permissions[context].can(verb, args, cb)
    • app.permissions[context].any(verbs, args, cb)
    • app.permissions[context].all(verbs, args, cb)
    • app.permissions[context].whoIs(role, object, cb)
    • app.permissions[context].whoCan(verb, object, cb)
    • app.permissions[context].whatIs(user, role, cb)
    • app.permissions[context].whatCan(user, verb, cb)
    • app.permissions[context].whatActions(user, object, cb)

Usage

Include the cantina-permissions plugin in your cantina application and define your relations contexts. You'll then have the API for granting, revoking, and querying for your application's permissions.

var app = require('cantina').createApp();

app.boot(function (err) {
  // Handle err.
  if (err) throw err;

  // Load cantina-permissions.
  app.require('cantina-permissions');

  // Start the app.
  app.start();
});

module.exports = function (app) {
  var permissionDefinitions = {
    event: {
      author: ['read', 'edit', 'delete'],
      viewer: ['read'],
      collaborator: ['read', 'edit']
    },
    site: {
      admin: ['administrate']
    }
  };

  Object.keys(permissionDefinitions).forEach(function (ctx) {
    app.permissions.define(ctx, permissionDefinitions[ctx]);
  });
};

Example

module.exports = function (app) {
  var controller = app.controller();

  controller.get('/event/:id', function (req, res, next) {
    app.permissions.event.can('read', {user: req.user, object: req.params.id},
    function (err, hasAccess) {
      if (err) return next(err);
      if (hasAccess) {
        app.collections.event.load(req.params.id, function (err, event) {
          if (err) return next(err);
          res.vars.event = event;
          res.render('event', res.vars);
        });
      }
      else {
        res.renderStatus(403);
      }
    });
  });

  return controller;
};

API Reference

app.permissions

Namespace for permission-related APIs.

app.permissions.define(context, roles)

Proxies relations to create a context, which contains a list of roles which map to actions.

• context: A name for the context
• roles: A hash of roles and verbs

app.permissions.define('event', {
  author: ['read', 'edit', 'delete'],
  attendee: ['read'],
  admin: ['administrate']
});

app.permissions[context].grant(role, args, cb)

Grants a relations role to the user.

• role: The role to grant
• args: may be a user model, a user id, or a hash of:
  • user: The user model or id to grant the role to
  • object: (optional) The object model or id that the role relates to
• cb: The callback

Runs the stact-hook permissions:grant(options, done) so other plugins may react to the event.

app.permissions.event.grant('author', {
  user: userModel,
  object: eventModel
}, function (err) {
  if (err) return app.emit('error', err);
);

app.permissions.event.grant('admin', userModel, function (err) {
  if (err) return app.emit('error', err);
);

app.permissions[context].revoke(role, args, cb)

Revokes a relations role from the user.

• role: The role to grant
• args: may be a user model, a user id, or a hash of:
  • user: The user model or id to grant the role to
  • object: (optional) The object model or id that the role relates to
• cb: The callback

Runs the stact-hook permissions:revoke(options, done) so other plugins may react to the event.

app.permissions.event.revoke('author', {
  user: userModel,
  object: eventModel
}, function (err) {
  if (err) return app.emit('error', err);
);

app.permissions.event.revoke('admin', userModel, function (err) {
  if (err) return app.emit('error', err);
);

app.permissions[context].hasRole(role, args, cb)

Checks whether a user has a role.

• role: The role to check for
• args: may be a user model, a user id, or a hash of:
  • user: The user model or id to grant the role to
  • object: (optional) The object model or id that the role relates to
• cb: The callback

app.permissions.event.hasRole('author', {
  user: userModel,
  object: eventModel
}, function (err, hasRole) {
  if (err) return app.emit('error', err);
  if (hasRole) {
    // do something
  }
);

app.permissions.event.hasRole('admin', userModel, function (err, hasRole) {
  if (err) return app.emit('error', err);
  if (hasRole) {
    // do something
  }
);

app.permissions[context].can(verb, args, cb)

Checks whether a user can perform an action.

• verb: The action to check for
• args: may be a user model, a user id, or a hash of:
  • user: The user model or id to grant the role to
  • object: (optional) The object model or id that the role relates to
• cb: The callback

app.permissions.event.can('edit', {
  user: userModel,
  object: eventModel
}, function (err, hasAccess) {
  if (err) return app.emit('error', err);
  if (hasAccess) {
    // do something
  }
);

app.permissions.event.can('administrate', userModel, function (err, hasAccess) {
  if (err) return app.emit('error', err);
  if (hasAccess) {
    // do something
  }
);

app.permissions[context].any(verbs, args, cb)

Checks whether a user can perform at least one of an array of actions

• verbs: an array of actions to check for
• args: may be a user model, a user id, or a hash of:
  • user: The user model or id to grant the role to
  • object: (optional) The object model or id that the role relates to
• cb: The callback

app.permissions.event.any(['delete', 'edit'], {
    user: 'erin',
    object: 'doc1'
  }, function (err, hasAnyAccess) {
  if (err) return app.emit('error', err);
  if (hasAnyAccess) {
    // do something
  }
);

app.permissions[context].all(verbs, args, cb)

Checks whether a user can perform all of an array of actions.

• verbs: an array of actions to check for
• args: may be a user model, a user id, or a hash of:
  • user: The user model or id to grant the role to
  • object: (optional) The object model or id that the role relates to
• cb: The callback

app.permissions.event.all(['delete', 'edit' ], {
    user: 'erin',
    object: 'doc1'
  }, function (err, hasAllAccess) {
  if (err) return app.emit('error', err);
  if (hasAllAccess) {
    // do something
  }
);

app.permissions[context].whoCan(verb, object, cb)

Returns an array of user ids who can perform an action on an object.

• verb: The verb to check for
• object: The object model or id that the query relates to
• cb: The callback

app.permissions.event.whoCan('read', eventModel, function (err, userIds) {
  if (err) return app.emit('error', err);

  // do something with userIds
);

app.permissions[context].whoIs(role, object, cb)

Returns an array of user ids who have a role over an object.

• role: The role to check for
• object: The object model or id that the query relates to
• cb: The callback

app.permissions.event.whoIs('author', eventModel, function (err, userIds) {
  if (err) return app.emit('error', err);

  // do something with userIds
);

app.permissions[context].whatCan(user, verb, cb)

Returns an array of object ids on which a user can perform an action.

• user: The user model or id to check access for
• verb: The verb to check for
• cb: The callback

app.permissions.event.whatCan(userModel, 'edit', function (err, objectIds) {
  if (err) return app.emit('error', err);

  // do something with objectIds
);

app.permissions[context].whatIs(user, role, cb)

Returns an array of object ids on which a user has a role

• user: The user model or id to check access for
• role: The role to check for
• cb: The callback

app.permissions.event.whatIs(userModel, 'author', function (err, objectIds) {
  if (err) return app.emit('error', err);

  // do something with objectIds
);

app.permissions[context].whatActions(user, object, cb)

Returns an array of verbs a user can perform on an object.

• user: The user model or id to check access for
• object: The object model or id that the query relates to
• cb: The callback

app.permissions.event.whatActions(userModel, eventModel, function (err, verbs) {
  if (err) return app.emit('error', err);

  // do something with verbs
);

Developed by TerraEclipse

Terra Eclipse, Inc. is a nationally recognized political technology and strategy firm located in Santa Cruz, CA and Washington, D.C.