feat(Login): Add new preLogin and postLogin interception points

Adding new interception points for `preLogin` and `postLogin` will allow applications which will log a user in by calling `auth().logIn()` explicitly instead of `auth().authenticate()` to perform important post-login actions.  This would be especially useful for a site that has "remember me" functionality, where a user will be logged in based on a special cookie on their browser as opposed to them entering their username/password.

Author: homestar9

README.md

@@ -136,7 +136,9 @@ If there is no logged in user, it throws a `NoUserLoggedIn` exception.
 
 ## Interception Points — (preAuthentication & postAuthentication)
 
-cbauth announces two custom interception points — preAuthentication and postAuthentication.  You can use these interception points to change request data or add additional values to session or request scopes.
+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.
+
+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`.
 
 ### `preAuthentication`
 
@@ -161,3 +163,25 @@ interceptData
 | requestStorage | The requestStorage object to store additional values if needed. |
 
 This is the prime time to store additional values based on the user returned.
+
+### `preLogin`
+
+interceptData
+
+| name | description |
+| --- | --- |
+| user | The user component to be logged in. |
+
+
+### `postLogin`
+
+interceptData
+
+| name | description |
+| --- | --- |
+| user | The user component to be logged in. |
+| 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.

models/AuthenticationService.cfc

@@ -10,33 +10,44 @@ component singleton {
     variables.USER_KEY = "cbauth__user";
 
     public void function logout() {
-        sessionStorage.delete( USER_ID_KEY );
-        requestStorage.delete( USER_KEY );
+        variables.sessionStorage.delete( variables.USER_ID_KEY );
+        variables.requestStorage.delete( variables.USER_KEY );
     }
 
     public void function login( required user ) {
-        sessionStorage.set( USER_ID_KEY, user.getId() );
-        requestStorage.set( USER_KEY, user );
+        variables.interceptorService.processState( "preLogin", {
+            user = arguments.user
+        } );
+        
+        variables.sessionStorage.set( variables.USER_ID_KEY, arguments.user.getId() );
+        variables.requestStorage.set( variables.USER_KEY, arguments.user );
+        
+        variables.interceptorService.processState( "postLogin", {
+            user = arguments.user,
+            sessionStorage = variables.sessionStorage,
+            requestStorage = variables.requestStorage
+        } );
     }
 
     public boolean function authenticate( required string username, required string password ) {
-        var args = {
-            username = username,
-            password = password
-        };
-
-        interceptorService.processState( "preAuthentication", args );
+        variables.interceptorService.processState( "preAuthentication", {
+            "username" = arguments.username,
+            "password" = arguments.password
+        } );
 
-        if ( NOT getUserService().isValidCredentials( args.username, args.password ) ) {
-            throw( "Incorrect Credentials Entered", "InvalidCredentials" );
+        if ( ! getUserService().isValidCredentials( arguments.username, arguments.password ) ) {
+            throw(
+                type = "InvalidCredentials",
+                message = "Incorrect Credentials Entered"
+            );
         }
 
-        var user = getUserService().retrieveUserByUsername( args.username );
+        var user = getUserService().retrieveUserByUsername( arguments.username );
 
-        interceptorService.processState( "postAuthentication", {
+        variables.interceptorService.processState( "postAuthentication", {
             user = user,
-            sessionStorage = sessionStorage,
-            requestStorage = requestStorage
+            sessionStorage = variables.sessionStorage,
+            requestStorage = variables.requestStorage
         } );
 
         login( user );
@@ -45,7 +56,7 @@ component singleton {
     }
 
     public boolean function isLoggedIn() {
-        return sessionStorage.exists( USER_ID_KEY );
+        return variables.sessionStorage.exists( variables.USER_ID_KEY );
     }
 
     public boolean function check() {
@@ -57,12 +68,12 @@ component singleton {
     }
 
     public any function getUser() {
-        if ( ! requestStorage.exists( USER_KEY ) ) {
+        if ( ! variables.requestStorage.exists( variables.USER_KEY ) ) {
             var userBean = getUserService().retrieveUserById( getUserId() );
-            requestStorage.set( USER_KEY, userBean );
+            variables.requestStorage.set( variables.USER_KEY, userBean );
         }
 
-        return requestStorage.get( USER_KEY );
+        return variables.requestStorage.get( variables.USER_KEY );
     }
 
     public any function user() {
@@ -71,19 +82,25 @@ component singleton {
 
     public any function getUserId() {
         if ( ! isLoggedIn() ) {
-            throw( "No user is currently logged in.", "NoUserLoggedIn" );
+            throw(
+                type = "NoUserLoggedIn",
+                message = "No user is currently logged in."
+            );
         }
 
-        return sessionStorage.get( USER_ID_KEY );
+        return variables.sessionStorage.get( variables.USER_ID_KEY );
     }
 
     private any function getUserService() {
         if ( ! structKeyExists( variables, "userService" ) ) {
-            if ( userServiceClass == "" ) {
-                throw( "No [userServiceClass] provided.  Please set in `config/ColdBox.cfc` under `moduleSettings.cbauth.userServiceClass`.", "IncompleteConfiguration" );
+            if ( variables.userServiceClass == "" ) {
+                throw(
+                    type = "IncompleteConfiguration",
+                    message = "No [userServiceClass] provided.  Please set in `config/ColdBox.cfc` under `moduleSettings.cbauth.userServiceClass`."
+                );
             }
 
-            variables.userService = wirebox.getInstance( userServiceClass );
+            variables.userService = variables.wirebox.getInstance( variables.userServiceClass );
         }
 
         return variables.userService;

tests/specs/AuthenticationSpec.cfc

@@ -269,11 +269,16 @@ component extends="testbox.system.BaseSpec" {
                         var processStateCallLog = interceptorServiceMock.$callLog().processState;
 
                         expect( processStateCallLog )
-                            .toHaveLength( 2, "Two events should have been announced" );
+                            .toHaveLength( 4, "Four events should have been announced" );
                         expect( processStateCallLog[1][1] )
                             .toBe( "preAuthentication", "[preAuthentication] should have been announced." );
                         expect( processStateCallLog[2][1] )
                             .toBe( "postAuthentication", "[postAuthentication] should have been announced." );
+                        expect( processStateCallLog[3][1] )
+                            .toBe( "preLogin", "[preLogin] should have been announced." );
+                        expect( processStateCallLog[4][1] )
+                            .toBe( "postLogin", "[postLogin] should have been announced." );
+                        
                     } );
                 } );