Admittance

* Intro
* Usage
* Writing permissions
* Writing assignments
* Business rules
* API
* Tests
* Example

Intro

This is a rewrite of the original incomplete V1 version of admittance. I decided that V1 was trying to do too much and that V2 should be as simple as possible, both in API and in what it actually does under the hood.

Admittance now reads permissions from plain old javascript objects. This, I think helps to keep the module doing just one thing. To load data you just need create javascript objects and store them somewhere. You could simply require a json file and load it. This also makes it very easy to work with a nosql db. Just get and set your permissions to the db.

Usage

$3

``js
var admittance = require('admittance')

var permissions = {
'admin': 'subscriber'
}

var assignments = {
1: 'admin'
}

var user = admittance(permissions, assignments)

user(1).is('admin') //true
user(1).isnt('admin') //false
`

$3

`js
//require admittance and example json permissions file
var permissionData = require('/some/example/permissions.json')
, assignmentData = require('/some/example/assignments.json')
, admittance = require('admittance')

//load in permissions from json permissions file. This could easily be loaded
//from a db instead
var user = admittance(permissionData, assignmentData)

//do permissions checks

if (user(1).is('admin'))
console.log('user 1 is an admin')

if (user(1).is('reportViewer'))
console.log('user 1 is a report viewer')

if (user(1).is('editor'))
console.log('user 1 is an editor since admin is a parent of editor')

if (user(1).is('user'))
console.log('user 1 passes a user check since admin is a parent of user')

if (user(1).isnt('superadmin'))
console.log('user 1 isnt a superadmin since superadmin is a parent of admin')

if (user(1).can('readPosts'))
console.log('user 1 can read posts')

if (user(1).can('listPosts'))
console.log('user 1 can list posts')

var post = {
creator: 1
}

if (user(1).can('editPosts', post.creator))
console.log('user 1 can edit the post because he/she created it')

if (user(1).can('editPosts', post.creator === 1))
console.log('user 1 can edit the post because the given business rule passed')

if (user(1).can('deletePosts'))
console.log('user 1 can delete posts')

if (user(1).can('manageUsers'))
console.log('user 1 can manage users')

if (user(1).can('readReports'))
console.log('user 1 can read reports')

if (user(1).can('listReports'))
console.log('user 1 can list reports')

if (user(1).cant('eatCake'))
console.log('user 1 cant eat cake since the cake is a lie')
`

Writing permissions

Permissions are strings or an array of strings. The strings are simply permission names that make sense for your application context. Permissions can be parents for other permissions and they in turn
can be parents to further permissions etc. Define these hierarchies however you see fit.
When it comes time to check, admittance with traverse your permission hierarchy to determine
if a given user has a given permission.

example:

`js
{
//Permissions structure. This is simple a key for a parent permission and
//a value (either string or array) representing children permission(s)

//"user" has children "readPosts" and "listPosts" which means a user can read
//and list posts
"user": [
"readPosts",
"listPosts"
],

//"editor" has children "editPosts" and "deletePosts" and "user".
//An editor can edit and delete posts as well as do anything a user can.
//(In this case can read and list posts)
"editor": [
"user",
"editPosts",
"deletePosts"
],

//"admin" is the parent of "editor" with the extra permission "manageUsers"
"admin": [
"manageUsers",
"editor"
],

//"superadmin" is an alias for admin since they essentially have the exact
//same permissions
"superadmin": "admin",

//"reportViewer" is a separate permission with no direct relationship to
//the other permissions
"reportViewer": [
"readReports",
"listReports"
]

}
`

Writing assignments

Admittance expects a simple map from userids to permissions (defined in permissions map)
A userid can be assigned a single permission string or an array of permissions strings.

example:

`js
{
//Assigning permissions to users.
//Based on the permissions hierarchy we can assign permissions to given user ids

//userid "1" is an "admin" and a "reportViewer"
"1": ["admin", "reportViewer"],

//userid "2" is an "editor"
"2": "editor",

//userid "3" is a "user"
"3": "user"

}
`

Business rules

Business rules are extra tests relevant to your application that go along side
permission checks. An example of this is when you have a user that is allowed
to edit posts ONLY if he or she is the owner (creator) of that post.
Business rules allow you to provide such tests along side permissions checks.

$3

A simple and useful way to solve the example above in admittance is to simply
pass a matching id as a second parameter to your check. Admittance will then
verify that this id matches the user id.

Heres an example of how that might look:

`js
var permissions = {
'editPosts'
}

var assignments = {
2: 'editPosts'
}

var check = admittance(permissions, assignments)

var user = {
id: 2,
name: 'Mr Banana'
}

var post = {
id: 1
owner: 2
}

check(user.id).can('editPosts', post.owner) //true

`

$3

Another simple way to add custom checks to specific checks is to pass an
expression that evaluates to true or false as a second parameter to is,
can, isnt or cant

Example:

`js
var permissions = {
'editPosts'
}

var assignments = {
2: 'editPosts'
}

var check = admittance(permissions, assignments)

var user = {
id: 2,
name: 'Mr Banana'
}

var post = {
id: 1
owner: 2
}

check(user.id).can('editPosts', post.owner === user.id) //true
`

API

$3

Load permissions and assignments from js objects and return an admittance instance. See Writing permissions and Writing assignments for how to write permissions and assignments objects

Parameters:

- permissions