feat: Added interception points and return user from authorize

Added `preLogout` and `postLogout` interception points.
Also, return the user from `authorize`.  Previously this returned `true`.

BREAKING CHANGE: `authorize` returns a `user` instance, not a boolean.  If the `authorize` call fails, it will throw an exception as before.

Author: lmajano

.cfformat.json

@@ -0,0 +1,61 @@
+{
+	"array.empty_padding": false,
+	"array.padding": true,
+	"array.multiline.min_length": 40,
+	"array.multiline.element_count": 2,
+	"array.multiline.leading_comma.padding": true,
+	"array.multiline.leading_comma": false,
+	"alignment.consecutive.assignments": true,
+	"alignment.consecutive.properties": true,
+	"alignment.consecutive.params": true,
+	"brackets.padding": true,
+	"comment.asterisks": "align",
+	"binary_operators.padding": true,
+	"for_loop_semicolons.padding": true,
+	"function_call.empty_padding": false,
+	"function_call.padding": true,
+	"function_call.multiline.leading_comma.padding": true,
+	"function_call.casing.builtin": "cfdocs",
+	"function_call.casing.userdefined": "camel",
+	"function_call.multiline.element_count": 3,
+	"function_call.multiline.leading_comma": false,
+	"function_call.multiline.min_length": 40,
+	"function_declaration.padding": true,
+	"function_declaration.empty_padding": false,
+	"function_declaration.multiline.leading_comma": false,
+	"function_declaration.multiline.leading_comma.padding": true,
+	"function_declaration.multiline.element_count": 3,
+	"function_declaration.multiline.min_length": 40,
+	"function_declaration.group_to_block_spacing": "spaced",
+	"function_anonymous.empty_padding": false,
+	"function_anonymous.group_to_block_spacing": "spaced",
+	"function_anonymous.multiline.element_count": 3,
+	"function_anonymous.multiline.leading_comma": false,
+	"function_anonymous.multiline.leading_comma.padding": true,
+	"function_anonymous.multiline.min_length": 40,
+	"function_anonymous.padding": true,
+	"indent_size": 4,
+	"keywords.block_to_keyword_spacing": "spaced",
+	"keywords.group_to_block_spacing": "spaced",
+	"keywords.padding_inside_group": true,
+	"keywords.spacing_to_block": "spaced",
+	"keywords.spacing_to_group": true,
+	"keywords.empty_group_spacing": false,
+	"max_columns": 120,
+	"metadata.multiline.element_count": 3,
+	"metadata.multiline.min_length": 40,
+	"newline":"\n",
+	"property.multiline.element_count": 3,
+	"property.multiline.min_length": 40,
+	"parentheses.padding": true,
+	"strings.quote": "double",
+	"strings.attributes.quote": "double",
+	"struct.separator": ": ",
+	"struct.padding": true,
+	"struct.empty_padding": false,
+	"struct.multiline.leading_comma": false,
+	"struct.multiline.leading_comma.padding": true,
+	"struct.multiline.element_count": 2,
+	"struct.multiline.min_length": 40,
+	"tab_indent": true
+}

.editorconfig

@@ -0,0 +1,20 @@
+# http://editorconfig.org
+
+root = true
+
+[*]
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_style = tab
+indent_size = 4
+tab_width = 4
+
+[*.yml]
+indent_style = space
+indent_size = 2
+
+[*.{md,markdown}]
+trim_trailing_whitespace = false
+insert_final_newline = false

.travis.yml

@@ -2,24 +2,53 @@ language: java
 sudo: required
 jdk:
   - openjdk8
+cache:
+  directories:
+    - "$HOME/.CommandBox/artifacts/"
+    - "$HOME/.CommandBox/server/"
 env:
-  matrix:
-    - ENGINE=adobe@2018
-    - ENGINE=adobe@2016
-    - ENGINE=lucee@5
+  global:
+    - MODULE_ID=cbauth
+  jobs:
+    - ENGINE=adobe@2018 COLDBOX_VERSION=stable
+    - ENGINE=adobe@2016 COLDBOX_VERSION=stable
+    - ENGINE=lucee@5 COLDBOX_VERSION=stable
+    - ENGINE=adobe@2018 COLDBOX_VERSION=be
+    - ENGINE=adobe@2016 COLDBOX_VERSION=be
+    - ENGINE=lucee@5 COLDBOX_VERSION=be
 before_install:
   - curl -fsSl https://downloads.ortussolutions.com/debs/gpg | sudo apt-key add -
   - sudo echo "deb http://downloads.ortussolutions.com/debs/noarch /" | sudo tee -a /etc/apt/sources.list.d/commandbox.list
 install:
   - sudo apt-get update && sudo apt-get --assume-yes install commandbox
+  - box install commandbox-cfconfig,commandbox-cfformat
   - box install
+  - box install coldbox@${COLDBOX_VERSION} --force
 before_script:
   - box server start cfengine=$ENGINE port=8500
 script:
   - box testbox run runner='http://127.0.0.1:8500/tests/runner.cfm'
+  - box run-script format:check
 after_success:
-  - box install commandbox-semantic-release
+  - box install commandbox-docbox,commandbox-semantic-release
   - box config set endpoints.forgebox.APIToken=${FORGEBOX_TOKEN}
   - box semantic-release
+before_deploy:
+  - # Set Current Version
+  - TARGET_VERSION=`cat $TRAVIS_BUILD_DIR/box.json | jq '.version' -r`
+  - box run-script generateAPIDocs
+deploy:
+  provider: s3
+  on:
+    branch: master
+    condition: $ENGINE = adobe@2018
+  skip_cleanup: true
+  #AWS Credentials need to be set in Travis
+  access_key_id: $AWS_ACCESS_KEY
+  secret_access_key: $AWS_ACCESS_SECRET
+  bucket: "apidocs.ortussolutions.com"
+  local_dir: $TRAVIS_BUILD_DIR/.tmp/apidocs
+  upload_dir: coldbox-modules/$MODULE_ID/$TARGET_VERSION
+  acl: public_read
 notifications:
   email: false

ModuleConfig.cfc

@@ -1,8 +1,12 @@
 component {
 
     this.title = "cbauth";
+    // Don't map models, we will do it manually
     this.autoMapModels = false;
+    // Module Dependencies
     this.dependencies = [ "cbstorages" ];
+    // Helpers automatically loaded
+	this.applicationHelper 	= [ "helpers/Mixins.cfm" ];
 
     function configure() {
         settings = {
@@ -11,31 +15,26 @@ component {
             requestStorage = "RequestStorage@cbstorages"
         };
 
+        // Custom Events
         interceptorSettings = {
-            customInterceptionPoints = "preAuthentication,postAuthentication"
+            customInterceptionPoints = [
+                "preAuthentication",
+                "postAuthentication",
+                "preLogout",
+                "postLogout",
+                "preLogin",
+                "postLogin"
+            ]
         };
     }
 
     function onLoad() {
         binder.map( "SessionStorage@cbauth" ).toDSL( settings.sessionStorage );
         binder.map( "RequestStorage@cbauth" ).toDSL( settings.requestStorage );
         binder.map( "AuthenticationService@cbauth" ).to( "#moduleMapping#.models.AuthenticationService" );
-
-        var helpers = controller.getSetting( "applicationHelper" );
-        arrayAppend(
-            helpers,
-            "#moduleMapping#/helpers/AuthenticationServiceHelpers.cfm"
-        );
-        controller.setSetting( "applicationHelper", helpers );
     }
 
     function onUnload() {
-        controller.setSetting(
-            "applicationHelper",
-            arrayFilter( controller.getSetting( "applicationHelper" ), function( helper ) {
-                return helper != "#moduleMapping#/helpers/AuthenticationServiceHelpers.cfm";
-            } )
-        );
     }
 
 }

README.md

@@ -1,6 +1,11 @@
 # cbauth
 
-Wrapper for authentication for ColdBox.
+Authentication services for ColdBox Applications.
+
+## Requirements 
+
+- Lucee 5+
+- Adobe ColdFusion 2016+
 
 ## Installation
 
@@ -14,7 +19,9 @@ Specify a `userServiceClass` in your `config/ColdBox.cfc` inside `moduleSettings
 2. `retrieveUserByUsername( username )`
 3. `retrieveUserById( id )`
 
-Additionally, the user component returned by the `retrieve` methods needs to respond to `getId()`.
+> We have provided an interface to implement and can be found at `cbauth.interfaces.IUserService`.
+
+Additionally, the user component returned by the `retrieve` methods needs to respond to `getId()`. We have also provided a nice interface for you to follow: `cbauth.interfaces.IAuthUser`
 
 You can also specify a `sessionStorage` and a `requestStorage` WireBox mapping.
 These will be used inside `AuthenticationService`.  By default, these are
@@ -51,7 +58,7 @@ This is very useful in views.  And since WireBox handles singleton management, y
 | user | any | true | | The user component to log in.  The component must respond to the `getId()` method. |
 
 Logs a user in to the system.  The user component must respond to the `getId()` method.  Additionally, the user is cached in the `request` scope.  If a user is already in the session, this will replace it with the given user.
-
+This method returns the passed in `user` object.
 
 ### `logout`
 
@@ -61,7 +68,6 @@ Logs a user in to the system.  The user component must respond to the `getId()`
 
 Logs a user out of system.  This method can be called regardless of if there is currently a logged in user.
 
-
 ### `authenticate`
 
 | name | type | required | default | description |
@@ -71,8 +77,7 @@ Logs a user out of system.  This method can be called regardless of if there is
 
 Attempts to log a user by calling the `isValidCredentials` and `retrieveUserByUsername` on the provided `userServiceClass`.  If `isValidCredentials` returns `false`, it throws a `InvalidCredentials` exception.
 
-If it succeeds, it returns `true`.  If it succeeds, it also sets the user id (obtained by calling `getId()` on the returned user component) in the session and the returned user component in the request.
-
+If it succeeds, it returns the logged in `user` object.  If it succeeds, it also sets the user id (obtained by calling `getId()` on the returned user component) in the session and the returned user component in the request.
 
 ### `isLoggedIn`
 
@@ -82,7 +87,6 @@ If it succeeds, it returns `true`.  If it succeeds, it also sets the user id (ob
 
 Returns whether a user is logged in to the system.
 
-
 ### `check`
 
 | name | type | required | default | description |
@@ -91,7 +95,6 @@ Returns whether a user is logged in to the system.
 
 _Alias for [`isLoggedIn`](#isLoggedIn)_
 
-
 ### `guest`
 
 | name | type | required | default | description |
@@ -100,7 +103,6 @@ _Alias for [`isLoggedIn`](#isLoggedIn)_
 
 Returns whether a user is logged out of the system.
 
-
 ### `getUser`
 
 | name | type | required | default | description |
@@ -113,7 +115,6 @@ If there is no logged in user, it throws a `NoUserLoggedIn` exception.
 
 Additionally, it sets the user in the `request` scope so subsequent calls to `getUser` don't re-fetch the user from the database or other permanent storage.
 
-
 ### `user`
 
 | name | type | required | default | description |
@@ -122,7 +123,6 @@ Additionally, it sets the user in the `request` scope so subsequent calls to `ge
 
 _Alias for [`getUser`](#getUser)_
 
-
 ### `getUserId`
 
 | name | type | required | default | description |
@@ -133,10 +133,9 @@ Returns the currently logged in user id.
 
 If there is no logged in user, it throws a `NoUserLoggedIn` exception.
 
+## Interception Points
 
-## Interception Points — (preAuthentication & postAuthentication)
-
-cbauth announces several custom interception points.  You can use these interception points to change request data or add additional values to session or request scopes.  The `preAuthentication` and `postAuthentication` events fire during the standard `authenticate()` method call with a username and password.  The `preLogin` and `postLogin` events fire during the `login()` method call.
+cbauth announces several custom interception points.  You can use these interception points to change request data or add additional values to session or request scopes.  The `preAuthentication` and `postAuthentication` events fire during the standard `authenticate()` method call with a username and password.  The `preLogin` and `postLogin` events fire during the `login()` method call. The `preLogout` and `postLogout` events fire during the `logout()` method call.
 
 Note: the `preLogin` and `postLogin` interception points will be called during the course of `authenticate()`.  The order of the calls then are `preAuthentication` -> `preLogin` -> `postLogin` -> `postAuthentication`.
 
@@ -151,7 +150,6 @@ interceptData
 
 Modifying the values in the `interceptData` will change what is passed to `isValidCredentials` and `retrieveUserByUsername`.  This is the prime time to ignore certain requests or remove or pad usernames.
 
-
 ### `postAuthentication`
 
 interceptData
@@ -172,7 +170,6 @@ interceptData
 | --- | --- |
 | user | The user component to be logged in. |
 
-
 ### `postLogin`
 
 interceptData
@@ -183,5 +180,19 @@ interceptData
 | sessionStorage | The sessionStorage object to store additional values if needed. |
 | requestStorage | The requestStorage object to store additional values if needed. |
 
-
 This is a good opportunity to store additional data if your application logged the user in manually without authenticating via a username/password like a "remember me" system.
+
+### `preLogout`
+
+interceptData
+
+| name | description |
+| --- | --- |
+| user | The user component that is logged in if you are logged in, else `null` |
+
+### `postLogout`
+
+interceptData
+
+| name | description |
+| --- | --- |

box.json

@@ -4,14 +4,15 @@
     "location":"forgeboxStorage",
     "author":[
         "Eric Peterson",
-        "Mike Burt"
+        "Mike Burt",
+        "Luis Majano"
     ],
     "repository":{
         "type":"git",
         "URL":"https://github.com/coldbox-modules/cbauth"
     },
     "slug":"cbauth",
-    "shortDescription":"Helpers for authentication in ColdBox",
+    "shortDescription":"Authentication services for ColdBox Applications.",
     "type":"modules",
     "keywords":[
         "authentication",
@@ -34,10 +35,16 @@
         "testbox":"testbox/",
         "cbstorages":"modules/cbstorages/"
     },
-    "scripts":{},
+    "scripts":{
+        "format": "cfformat run models/**/*.cfc,tests/specs/**/*.cfc --overwrite",
+        "format:check": "cfformat check models/**/*.cfc,tests/specs/**/*.cfc --verbose",
+        "generateAPIDocs":"rm .tmp --recurse --force && docbox generate mapping=cbauth excludes=tests|ModuleConfig strategy-outputDir=.tmp/apidocs strategy-projectTitle=cbauth"
+    },
     "ignore":[
         "**/.*",
         "test",
-        "tests"
+        "tests",
+        "docs/**/*.*",
+        "server.json"
     ]
 }

helpers/AuthenticationServiceHelpers.cfm renamed to helpers/Mixins.cfm

@@ -0,0 +1,14 @@
+/**
+ * Copyright since 2016 by Ortus Solutions, Corp
+ * www.ortussolutions.com
+ * ---
+ * If you use a user with a user service or authentication service, it must implement this interface
+ */
+interface{
+
+    /**
+     * Return the unique identifier for the user
+     */
+    function getId();
+
+}