Merge pull request #86 from nyambati/develop

# Merge Develop to master

.gitignore

@@ -3,4 +3,5 @@ node_modules
 examples/node_modules
 coverage
 site
-.DS_Store
+.DS_Store
+env

README.md

@@ -165,6 +165,7 @@ This methods loads the configuration json file. When this method it looks for `n
 - **rules**: Allows you to set rules directly withour using config file.
 - **defaultRole** : The default role to be assigned to users if they have no role defined.
 - **decodedObjectName**: The name of the object in the request where the role resides.
+- **searchPath**: The path in which to look for the role within the req object
 
 ```js
   const acl = require('express-acl');
@@ -213,6 +214,13 @@ This methods loads the configuration json file. When this method it looks for `n
     decodedObjectName:'user'
   })
 
+// You can also specify a deep path in which to look for the role, in case it's not inside the usual locations
+
+  acl.config({
+    searchPath: 'user.Role.name' //will search for role in req.user.Role.name
+  })
+
+
 ```
 ## Response
 This is the custom error you would like returned when a user is denied access to a resource. This error will be bound to status code of `403`

docs/documentation/configuration.md

@@ -1,17 +1,24 @@
 # Overview
+
 This are the options that are passed to the config method. This options determin how the rules will be loaded and how resource matching should start from.
 
-# Options
+The config method takes in an object with possible five parameters, They include
+
+- filename: `String`
+- path: `String`
+- yml: `boolean`
+- baseUrl: `String`
+- rules: `Object`
+- defaultRole: `String`
+- decodedObjectName: `String`
+- searchPath: `String`
+- encoding: `String`
+- baseUrl: `String`
 
-  The config method takes in an object with possible five parameters, They include
+## Filename
 
-  * filename: `string`
-  * path: `string`
-  * yml: `boolean`
-  * encoding: `string`
-  * baseUrl: `string`
+`filename: <String> [optional]`
 
-## Filename `filename [optional]`
 This property holds the name of the file that contains the acl configurations. By default express-acl will look for `nacl.json` or `nacl.yml` in the root folder of your project. If you plan to change the name you can specify the name of your file in this property.
 
 ```javascript
@@ -23,9 +30,13 @@ This property holds the name of the file that contains the acl configurations. B
   acl.config(options);
 
 ```
+
 Its important to note that the filename should have an extension attached to it e.g `.json` or `.yml`.
 
-## Path `path [optional]`
+## Path
+
+`path: <String> [optional]`
+
 This property specifies the location of the configuration file. By default the acl configuration file is located in the root folder of the project. However sometimes you may want to place this file among other configuration files of your project. You can achieve this by adding the location of the file relative to the root folder.
 
 If the config folder is `/server/config`, then we can configure the path property as shown below.
@@ -42,7 +53,9 @@ If the config folder is `/server/config`, then we can configure the path propert
 
 Basically what this means is that, you are instructing express-acl to go to the `server/config` folder and load the contents of `acl.json`.
 
-## File Type `yml [optional]`.
+## File Type
+
+`yml: <Boolean> [optional]`
 
 Express acl supports two types of configuration syntax. `JSON` and `yml`. By default it uses JSON as its primary syntax, however you can change to whichever syntax that works for you.
 
@@ -59,25 +72,114 @@ This property is false by default therefore if you want to use `yml` as your syn
 
 ```
 
+## Encoding
+
+`encoding: <String> [optional]`
 
-## Encoding `encoding [optional]`.
 This is the encoding type `fs` module uses to read nacl file. For more information refer to the [file system ](https://nodejs.org/api/fs.html) Nodejs documentation.
 
-## Base URL `baseUrl [required]`.
+## Base URL
+
+`baseUrl: <String> [required]`
 
 The base URL represent the prefix of your API. This can either be `api`,`v1`,`/developer/v1` etc. This is important because express-acl will use this url to map the location of the resources. Take an example of the following url `/api/users`.
 
 In this URL our resource is users,and the base URL being `api`. If we donot specify the base URL express will treat `api` as our resource instead of `users`.
 
 ```js
-  const options = {
-    filename:'acl.yml',
-    path:'server/config',
-    baseUrl:'api'
-    yml:true
-  };
 
-  acl.config(options);
+const options = {
+  filename:'acl.yml',
+  path:'server/config',
+  baseUrl:'api'
+  yml:true
+};
+
+acl.config(options);
+
+```
+
+## Rules
+
+`rules: <String> [optional]`
+
+If you are not willing to use either json file or yml configuration you can pass the config method an array of rules. This can be rules saved in an external source such as database or a js file in your project.
+
+```js
+const arrayOfRules = [
+  {
+    group: "admin",
+    permissions: [
+      {
+        resource: "*",
+        methods: "*"
+      }
+    ],
+    action: "allow"
+  },
+];
+
+
+const options = {
+  baseUrl:'api',
+  rules: ArrayOfRules,
+  yml:true
+};
+
+acl.config(options);
 
 ```
 
+## Default Role
+
+`defaultRole: <String> [optional]`
+
+If You have a user in your system who has not been assigned a role, you can specify a role that will be assumed if such users exist. By the default this module will assign `guest` as a default role. You can override this by using `defaultRole` property.
+
+```js
+
+acl.config({
+    yml: true,
+    defaultRole: 'anonymous'
+});
+
+```
+
+## Search Path And Decoded Object Name
+
+This two properties enable you to customize how and where your user role will be located in the request object. By default this module looks for `req.decoded.role`, However this might be the case with everyone. if your decoed object uses different format you can specify using the above properties.
+
+!!! note
+    Both of these properties are use to locate the role in your request object, therefore  they cannot be used together.
+    You can only use on of each in your configuration.
+
+### Decoded Object Name
+
+`decodedObjectName: <String> [optional]`
+
+You can use this method to specify the name of the object holding your user object, this can be user, session, etc. The default value for this is `decoded`.
+
+```js
+
+acl.config({
+    yml: true,
+    decodedObjectName: 'user'
+});
+
+```
+
+### Search Path
+
+`searchPath: <String> [optional]`
+
+In some cases your user object can have the role name nested deep into your object. With the above config this module will look for the role name in `user.role`. If your role is nested in `user.role.name` you can specify this path as a search path so that this module can be able to find your role.
+
+
+```js
+
+acl.config({
+    yml: true,
+    searchPath: 'user.role.name'
+});
+
+```

docs/documentation/getting-started.md

@@ -8,8 +8,7 @@ $ npm install express-acl --save
 
 ```
 
-
-# Configuration
+## Configuration
 
 Express acl uses acl rules to manage and protect your resources, They have to be loaded and configured before being used.
 
@@ -26,11 +25,12 @@ Express acl uses acl rules to manage and protect your resources, They have to be
 
 For more details check the [configuration options](/documentation/configuration) page
 
-# Adding Rules
+## Adding Rules
 
 The config method loads the rules for the local file. By default this module will look for `nacl.json` file in the root folder of your project. This can be overidden by adding more options to the config method as we have added yml which will look for `nacl.yml` file instead.
 
 ```yaml
+
 - group: user
   permissions:
     - resource: users
@@ -43,13 +43,14 @@ The config method loads the rules for the local file. By default this module wil
 
 This file instructs this module on how to manage access to your resources. The contets of this file will be covered in details in the [Acl rules](/documentation/acl-rules) section
 
+## Authentication
 
-# Authentication
 Express Acl depends on the `role` of each authenticated user to pick the corresponding ACL policy for each defined user groups. Therefore, You should always place the acl middleware after the authenticate middleware.
 
 Below is an example of an Authenticatio middleware implementation using jsonwebtokens.
 
-```javascript
+```js
+
   ROUTER.use(function(req, res, next) {
     var token = req.headers['x-access-token'];
     if (token) {
@@ -66,16 +67,14 @@ Below is an example of an Authenticatio middleware implementation using jsonwebt
 
 ```
 
-# Authorize
+## Authorize
 
 The acl module provides a middleware `authorize`. This middleware should be placed after the authentication middleware. It will intercept all the requests made for all the resources and apply relevant policies ton these to either deny or allow access depending on the configuration.
 
-```javascript
+```js
 
 ROUTER.use(acl.authorize);
 
 ```
 
 Once this middware is called, express-acl will pick the role from the authenticated user,and apply corresponding polices dependng on he role and resource sbeing requested for.
-
-

docs/documentation/methods.md

@@ -0,0 +1,30 @@
+# Api Methods
+
+## authorize
+    [type: middleware]
+
+This is the middleware that manages your application requests based on the role and acl rules.
+
+```js
+app.get(acl.authorize);
+
+```
+
+## unless
+    [type:function, params: function or object]
+
+By default any route that has no defined policy against it is blocked, this means you cannot access this route untill you specify a policy.
+This method enables you to exclude unprotected routes. This method uses express-unless package to achive this functionality.
+For more details on its usage follow this link [express-unless](https://github.com/jfromaniello/express-unless/blob/master/README.md)
+
+```js
+//assuming we want to hide /auth/google from express acl
+
+app.use(acl.authorize.unless({path:['/auth/google']}));
+
+```
+
+Anytime that this route is visited, unless method will exlude it from being passed though our middleware.
+
+!!! note
+    You don't have to install express-unless it has already been included into the project.

docs/documentation/acl-rules.md → docs/documentation/rules.md

@@ -5,7 +5,9 @@ Express acl uses Rules to define what access should be given to certain user gro
 The first step to making acl rules is by creating nacl.json or nacl.yml depending on the syntax you prefer to use. Below is an example of ACL rules using both syntax.
 
 JSON syntax
+
 ```json
+
 [{
   "group": "admin",
   "permissions": [{
@@ -28,7 +30,9 @@ JSON syntax
 ```
 
 YAML syntax
+
 ```yml
+
 - group: admin
   permissions:
     - resource: *
@@ -46,6 +50,7 @@ YAML syntax
 ```
 
 ## Understanding ACL rules
+
 Its important to Understand each property that consitute an acl. Below is a table that has a Description of each property.
 
 Property | Type | Description
@@ -64,7 +69,8 @@ Assuming you have a blog application, and you want to make blogs read only, deny
 
 **solution:**
 
-```
+```yaml
+
 admin:
   resource: all
   methods: all
@@ -96,6 +102,7 @@ For you to formulate good ACL rules, you need to understand the princple of nega
 Now that we have established that lets write our config file. Our nacl.json will look like this.
 
 ```json
+
 [{
    "group": "admin",
    "permissions": [{

examples/nacl.json

@@ -1,12 +1,22 @@
-[{
-  "group": "user",
-  "permissions": [{
-    "resource": "users",
-    "methods": [
-      "POST",
-      "GET",
-      "PUT"
-    ],
-    "action": "allow"
-  }]
-}]
+[
+  {
+    "group": "admin",
+    "permissions": [
+      {
+        "resource": "*",
+        "methods": "*",
+        "action": "allow"
+      }
+    ]
+  },
+  {
+    "group": "user1",
+    "permissions": [
+      {
+        "resource": "admin",
+        "methods": "*",
+        "action": "deny"
+      }
+    ]
+  }
+]