Create Permissions Plugin about annotator

[aron]

Suggested API.

Plugin Options

user:        A string or object to represent the current user. This will be
             attached to the `annotation.user` property.

permissions: An object of permissions, each permission can have an array
             of tokens that will be validated against the user object.
             By default the permission will be an empty array meaning
             anyone can edit it.

             Available permissions are as follows:

               read:    Can the user view the annotation.
               update:  Can the user edit the annotation.
               destroy: Can the user delete the annotation.
               admin:   Can the user edit the annotation.permissions object.

userId:      A callback function that receives the `user` object and returns
             a unique id for that user. By default it just returns `user`

userDisplay: A callback function that returns a display name for the user.
             By default it just returns `user`

authorize:   A callback function that receives the `user` object and a
             permissions `token`. The function should return true if the
             `user` can perform the action. By default the function will
             check to see if `user` === `token`.

Example Usage (Basic)

// All annotations will be world editable but will have a user.
annotator.addPlugin('Permissions', {
  user: 'Alice'
});

Example Usage (With Permissions)

A simple permissions model. By default the Permissions plugin will check
the contents of the permissions array for each action to see if it contains
the current user as it does now.

// Anyone can read the annotations but only "Alice" can modify them.
annotator.addPlugin('Permissions', {
  user: 'Alice',
  permissions: {
    'read':    [],
    'update':  ['Alice'],
    'destroy': ['Alice'],
    'admin':   ['Alice'] 
  }
});

Example Usage (Complex With Permissions)

Here we extend the current idea of providing callbacks via the options to allow
complex permission logic such as groups without having to complicate the
Annotator itself.

annotator.addPlugin('Permissions', {

  // A user object for the current user.
  user: { id: 'alice', name: 'Alice' },

  // Object of permissions for the annotation. By default these will be set to
  // an empty array. Meaning anyone can edit.
  permissions: {
    'read':    [],
    'update':  ['alice', 'bob', 'group:logged-in', 'group:admin'],
    'destroy': ['alice', 'group:admin'],
    'admin':   ['alice', 'group:admin']
  },

  // Function to return the id for a user.
  // Allows custom user objects to be used.
  userId: function (user) {
    return user.id;
  },

  // Function to return the display name for the user.
  userDisplay: function (user) {
    return user.name;
  },

  // Callback function returns true if user matches the token. This allows
  // complex logic such as groups to be implemented without complicating
  // the annotator.
  authorize: function (user, token) {
    var group;

    if (token.indexOf('group:') === 0) {
       group = token.replace('group:', '');

       // Local function to check whether this user is in the group. Not
       // part of the Annotator.
       if (userInGroup(user, group)) {
         return true;
       }
    }
    else if (user.id === permission) {
      return true;
    }

    return false;
  }
});

[aron]

The above has been implemented as of 544f9f2, by default Permissions#authorize() will match simple permission tokens as described in the "simple example" above.