authorizedjs/README.md

A tool for authorization based on permits

## authorizedjs - simple authorization tool for node applications

## Usage

It's very easy to use the tool with CoffeeScript.

### Permits

Set up permits.

```
Auth = require 'authorizedjs'

class MyTestPermits extends Auth.Permits
    adminOnlyAction: (resource) ->
        @user.role is "admin"

    everyUserAction: (resource) ->
        @user.role is "user"

    resourceBasedAction: (resource) ->
        resource.user.id is @user.id

    validForEverybody: (resource) ->
        true

    secret: (resource) ->
        false

now in your route/controller you can check for authorization:

1. set up authorization:

```
auth = new Auth.Authorization({MyTest: MyTestPermits})
```

This is the place where you map your resource with permits. In this example
`MyTest` is a name of your resource and `MyTestPermits` is an object where permits for actions are defined.

2. check if a user can perform an action (assuming that `currentUser` is the user you are going to check):

a) you can catch `error` or `success` events emitted by auth
```
auth.on 'error', (error) ->
    # user is not authenticated and should be redirected to some other action
    #
    # there are 3 types of `error`
    # MissingPermits - Permits are missing, you should include them
    # MissingPermit - Permit cannot be found, maybe typo?
    # UnauthorizedAccess - user is not authorized

auth.on 'success', (data) ->
    # user is authenticated
    # you can proceed with your action here

# perform checking
auth.check currenUser, 'MyTest', 'someAction'
```

b) you can also pass `success` and `error` functions to auth.check
```
auth.check currentUser, 'MyTest', 'someAction', (data) ->
    # user is authenticated
, (error) ->
    # user is not authenticated
    # error messages are the same as described above
```

c) last but not least, you can simply check if user is able to perform the action. Note please that we are using `test` method!
```
if auth.test currentUser, 'MyTest', 'adminOnlyAction'
    # we're ok to go!
else
    # rights are not sufficient to see that resource!
```

3. It's also possible to use class as resource (Mongoose objects are also supported):
```
class MyTest
    constructor: ->

if auth.test currentUser, MyTest, 'adminOnlyAction'
    # we're ok to go!
else
    # rights are not sufficient to see that resource!
```

It works with auth.check as well.

You need to ensure that this resource returns its name with `resource.name`. In our case it should be:

```
console.log MyTest.name
>> 'MyTest'
```

4. when user can manage only his/her resource then it's better to use the resource object

```
class MyTest
    constructor: (@user) ->

myTestObject = new MyTest(someUser)

if auth.test currentUser, myTestObject, 'resourceBasedAction'
    # we're ok to go!
else
    # rights are not sufficient
```

It works with auth.check as well.

it's very important that resource returns its name with `resource.constructor.name`! In our case it should be:

```
console.log myTestObject.constructor.name 
>> MyTest
```