Update docs

Author: Tom Kirkpatrick

README.md

@@ -1,11 +1,8 @@
-# Loopback Component Access
+# Loopback Component Group Access
 
-This loopback component enables you to add multi-tenant style access controls to a loopback application. It enables you
-to restrict access to model data based on a users roles within a specific context.
+This loopback component enables you to add multi-tenant style access controls to a loopback application. It enables you to restrict access to model data based on a users roles within a specific context.
 
-## Usage
-
-**Installation**
+### Installation
 
 1. Install in you loopback project:
 
@@ -23,7 +20,48 @@ to restrict access to model data based on a users roles within a specific contex
   }
   ```
 
-**Configuration**
+4. Create a middleware.json file in your server folder (if you don't already have one).
+
+5. Enable the `loopback#context`, `loopback#token` and `user-context` middleware.
+
+  ```json
+  {
+    "initial:before": {
+      "loopback#context": {},
+      "loopback#token": {},
+      "loopback-component-group-access#user-context": {}
+    },
+  }
+  ```
+
+### Usage
+
+In order to use this component you will need to create group access model that can be used to link users to groups and assign group roles. A user can have have multiple roles within the context of a group and each role can define different access grants to REST resources. The *Group Access Model* must have the following three properties:
+
+ - userId
+ - groupId (configurable foreign key)
+ - role
+
+Additionally you will need to designate one of your models the *Group Model*. This model will act as parent or container for related group content.
+
+Any other models that have a belongsTo relationship to your Group Model will be considered as Group Content. Access grants for Group Content is determined by the user's roles within the context of the group as defined in the Group Access Model.
+
+For example:
+
+ - **Group Model:** Store (id, name, desxription)
+ - **Group Access Model:** StoreUsers (userid, storeId, role)
+ - **Group Content Models:** Product, Invoice, Transaction, etc.
+
+You can have multiple stores.
+Each store can have multiple StoreUsers.
+Each StoreUser can have one or more Store Roles (eg, store manager, store administrator).
+Only Store Managers of Store A can create and edit products for Store A.
+Only Store Managers of Store B can create and edit products for Store B.
+Only Store Administrators of Store A can download transaction details for Store A.
+Only Store Administrators of Store B can download transaction details for Store B.
+etc.
+
+### Configuration
 
 Options:
 

TODO.md

@@ -1,7 +1,8 @@
 ### TODOs
 | Filename | line # | TODO
 |:------|:------:|:------
-| lib/utils.js | 138 | Should we allow the access group model to be treated as a group content model too?
-| lib/utils.js | 280 | Use promise cancellation to abort the chain early.
-| lib/utils.js | 338 | Cache this result so that it can be reused across each ACL lookup attempt.
-| lib/utils.js | 345 | Atempt to follow relationships in addition to the foreign key.
+| lib/index.js | 25 | Create Group Access model automatically if one hasn't been specified
+| lib/utils.js | 139 | Should we allow the access group model to be treated as a group content model too?
+| lib/utils.js | 281 | Use promise cancellation to abort the chain early.
+| lib/utils.js | 339 | Cache this result so that it can be reused across each ACL lookup attempt.
+| lib/utils.js | 346 | Attempt to follow relationships in addition to the foreign key.

lib/index.js

@@ -20,5 +20,7 @@ module.exports = function loopbackComponentAccess(app, options) {
 
   // Set up role resolvers.
   accessUtils.setupRoleResolvers();
+  // Set up model opertion hooks
   accessUtils.setupModels();
+  // TODO: Create Group Access model automatically if one hasn't been specified
 };

lib/utils.js

@@ -343,7 +343,7 @@ module.exports = class AccessUtils {
         skipAccess: true
       })
         .then(item => {
-          // TODO: Atempt to follow relationships in addition to the foreign key.
+          // TODO: Attempt to follow relationships in addition to the foreign key.
           if (item) {
             debug(`determined group id ${item[this.options.foreignKey]} from existing model %o`, item);
             groupId = item[this.options.foreignKey];