feat: Ability to use local override handlers if they exist

cbguard will first check the local handler for an `onAuthenticationFailure`
or `onAuthorizationFailure` function.  If it exists, it will be called.

BREAKING CHANGE: Dropped support for Lucee 4.5 and ACF 11
Special thanks to @Adrian-Sanchez for this PR.

Author: Adrian-Sanchez

.travis.yml

@@ -5,10 +5,8 @@ jdk:
 env:
   matrix:
     - ENGINE=lucee@5
-    - ENGINE=lucee@4.5
     - ENGINE=adobe@2018
     - ENGINE=adobe@2016
-    - ENGINE=adobe@11
 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

README.md

@@ -1,6 +1,6 @@
 # cbguard
 
-[![Master Branch Build Status](https://img.shields.io/travis/elpete/cbguard/master.svg?style=flat-square&label=master)](https://travis-ci.org/elpete/cbguard)
+[![Master Branch Build Status](https://img.shields.io/travis/coldbox-modules/cbguard/master.svg?style=flat-square&label=master)](https://travis-ci.org/coldbox-modules/cbguard)
 
 ## Annotation driven guards for authentication and authorization in ColdBox
 
@@ -93,15 +93,15 @@ When a user is denied access to a action, an event of your choosing is executed
 
 This is the event that is executed when the user is not logged in and is attempting to execute a secured action, whether or not that handler or action has permissions.
 
-1. `authorizationOverrideEvent` (Default: same as `authenticationOverrideEvent`)
+2. `authorizationOverrideEvent` (Default: same as `authenticationOverrideEvent`)
 
 This is the event that is executed when the user is logged in and is attempting to execute a secured action but does not have the requisite permissions.
 
-1. `authenticationAjaxOverrideEvent` (Default: `Main.onAuthenticationFailure`)
+3. `authenticationAjaxOverrideEvent` (Default: `Main.onAuthenticationFailure`)
 
 This is the event that is executed when the user is not logged in and is attempting to execute a secured action via ajax (`event.isAjax()`), whether or not that handler or action has permissions.  By default, this will execute the same action that is configured for `authenticationOverrideEvent`.
 
-1. `authorizationAjaxOverrideEvent` (Default: same as `authorizationOverrideEvent`)
+4. `authorizationAjaxOverrideEvent` (Default: same as `authorizationOverrideEvent`)
 
 This is the event that is executed when the user is logged in and is attempting to execute a secured action via ajax (`event.isAjax()`) but does not have the requisite permissions. By default, this will execute the same action that is configured for `authorizationOverrideEvent`.
 
@@ -160,7 +160,7 @@ moduleSettings = {
 The default `authenticationService` for `cbguard` is `AuthenticationService@cbauth`.  `cbauth` follows the `AuthenticationServiceInterface` out of the box.
 
 
-### Advanced Setup
+### config/ColdBox.cfc Settings
 
 You can change the method names called on the `AuthenticationService` and the returned `User` if you need to.  We highly discourage this use case, as it makes it harder to utilize the `cbguard` conventions across projects.  However, should the need arise, you can modify the method names as follows:
 
@@ -219,6 +219,43 @@ component {
 }
 ```
 
+### Local Handler Overrides
+
+If an `onAuthenticationFailure` or `onAuthorizationFailure` method exists on the handler being
+secured, it will be used in the case of an authentication or authorization failure event,
+respectively.
+
+```
+// handlers/Admin.cfc
+component secured {
+
+    function index( event, rc, prc ) {
+        event.setView( "admin/index" );
+    }
+
+    function secret( event, rc, prc ) secured="superadmin" {
+        event.setView( "admin/secret" );
+    }
+
+    function onAuthenticationFailure( event, rc, prc ) {
+        relocate( "/login" );
+    }
+
+    function onAuthenticationFailure( event, rc, prc ) {
+        flash.put( "authorizationError", "You don't have the correct permissions to access that resource." );
+        redirectBack(); // from the redirectBack module
+    }
+
+}
+```
+
+### Override Order
+cbguard will process your authorization and authentication failures in the following order:
+1. Inline handler methods (`onAuthenticationFailure` & `onAuthorizationFailure` within your handlers).
+2. cbguard settings in the ModuleConfig of the handler's module. (Overrides in `modules_app/api/ModuleConfig.cfc` when the handler is in the module, i.e. `modules_app/api/handlers/Main.cfc`.)
+3. Overrides in `config/ColdBox.cfc` using `moduleSettings`.
+4. Default settings for the module.
+
 ## `autoRegisterInterceptor`
 
 If you need more control over the order of your interceptors you can

interceptors/SecuredEventInterceptor.cfc

@@ -75,9 +75,17 @@ component extends="coldbox.system.Interceptor"{
         }
 
         if ( ! invoke( props.authenticationService, props.methodNames[ "isLoggedIn" ] ) ) {
+            // Override the coldbox.cfc global onAuthenticationFailure if it exists in the handler.
+            // Per docs, they will override for Ajax requests also.
             var eventType = event.isAjax() ? "authenticationAjaxOverrideEvent" : "authenticationOverrideEvent";
-            var relocateEvent = props[ eventType ];
+            var relocateEvent = getOverrideEvent( handlerMetadata, event, props, eventType );
             var overrideAction = props.overrideActions[ eventType ];
+
+            // If the override is within the same handler that is being secured,
+            // we have to override the event instead of relocating. Prevents a circle of death.
+            if ( event.getCurrentHandler() == handlerService.getHandlerBean( relocateEvent ).getHandler() ) {
+                overrideAction = "override";
+            }
             switch ( overrideAction ) {
                 case "relocate":
                     relocate( relocateEvent );
@@ -111,9 +119,17 @@ component extends="coldbox.system.Interceptor"{
             }
         }
 
+        // At this point, we know the user did NOT have any of the required permissions,
+        // so we will fire the appropriate authorization failure events
         var eventType = event.isAjax() ? "authorizationAjaxOverrideEvent" : "authorizationOverrideEvent";
-        var relocateEvent = props[ eventType ];
+        var relocateEvent = getOverrideEvent( handlerMetadata, event, props, eventType );
         var overrideAction = props.overrideActions[ eventType ];
+
+        // If the override is within the same handler that is being secured,
+        // we have to override the event instead of relocating. Prevents a circle of death.
+        if ( event.getCurrentHandler() == handlerService.getHandlerBean( relocateEvent ).getHandler() ) {
+            overrideAction = 'override';
+        }
         switch ( overrideAction ) {
             case "relocate":
                 relocate( relocateEvent );
@@ -168,10 +184,9 @@ component extends="coldbox.system.Interceptor"{
         if ( ! structKeyExists( targetActionMetadata, "secured" ) || targetActionMetadata.secured == false ) {
             return false;
         }
-
         if ( ! invoke( props.authenticationService, props.methodNames[ "isLoggedIn" ] ) ) {
             var eventType = event.isAjax() ? "authenticationAjaxOverrideEvent" : "authenticationOverrideEvent";
-            var relocateEvent = props[ eventType ];
+            var relocateEvent = getOverrideEvent( handlerMetadata, event, props, eventType );
             var overrideAction = props.overrideActions[ eventType ];
             switch ( overrideAction ) {
                 case "relocate":
@@ -206,9 +221,12 @@ component extends="coldbox.system.Interceptor"{
             }
         }
 
+        // Override the coldbox.cfc global onAuthorizationFailure if it exists in the handler.
+        // Per docs, they will override for Ajax requests also.
         var eventType = event.isAjax() ? "authorizationAjaxOverrideEvent" : "authorizationOverrideEvent";
-        var relocateEvent = props[ eventType ];
+        var relocateEvent = getOverrideEvent( handlerMetadata, event, props, eventType );
         var overrideAction = props.overrideActions[ eventType ];
+
         switch ( overrideAction ) {
             case "relocate":
                 relocate( relocateEvent );
@@ -224,5 +242,25 @@ component extends="coldbox.system.Interceptor"{
         }
         return true;
     }
-
+    /**
+     * Override the coldbox.cfc global on[eventType]Failure if it exists in the handler.
+     */
+    private function getOverrideEvent( handlerMetadata, event, props, eventType ) {
+        var handlerOverrides = arrayFilter( arguments.handlerMetadata.functions, function( func ) {
+            // In case some other override comes up in the future, using switch
+            switch( eventType ) {
+                case "authenticationOverrideEvent":
+                case "authenticationAjaxOverrideEvent":
+                    return func.name == "onAuthenticationFailure";
+                case "authorizationOverrideEvent":
+                case "authorizationAjaxOverrideEvent":
+                    return func.name == "onAuthorizationFailure";
+                default:
+                    return false;
+            }
+        } );
+        return handlerOverrides.isEmpty() ?
+            arguments.props[ eventType ] :
+            arguments.event.getCurrentHandler() & "." & handlerOverrides[ 1 ].name;
+    }
 }

server.json

@@ -1,5 +1,5 @@
 {
     "app":{
-        "cfengine":"adobe@11"
+        "cfengine":"adobe@2016"
     }
 }

tests/resources/ModuleIntegrationSpec.cfc

@@ -1,19 +1,30 @@
 component extends="coldbox.system.testing.BaseTestCase" {
 
+    property name="authenticationService" inject="AuthenticationService";
+
     function beforeAll() {
         super.beforeAll();
 
         getController().getModuleService()
             .registerAndActivateModule( "cbguard", "testingModuleRoot" );
+
+        getWireBox().autowire( this );
     }
 
     /**
-    * @beforeEach
-    */
+     * @beforeEach
+     */
     function setupIntegrationTest() {
         setup();
     }
 
+    /**
+     * @beforeEach
+     */
+    function autoLogOut() {
+        authenticationService.logout();
+    }
+
     function withSwappedSettings( applyOverrides, callback ) {
         var newSettings = duplicate( getController().getConfigSettings().modules.cbguard.settings );
         applyOverrides( newSettings );
@@ -28,4 +39,25 @@ component extends="coldbox.system.testing.BaseTestCase" {
         }
     }
 
+    private function createUser( overrides = {} ) {
+        var props = {
+            id = 1,
+            email = "johndoe@example.com",
+            username = "johndoe",
+            permissions = []
+        };
+        structAppend( props, overrides, true );
+        return tap( getInstance( "User" ), function( user ) {
+            user.setId( props.id );
+            user.setEmail( props.email );
+            user.setUsername( props.username );
+            user.setPermissions( props.permissions );
+        } );
+    }
+
+    private function tap( variable, callback ) {
+        callback( variable );
+        return variable;
+    }
+
 }

tests/resources/app/handlers/LocalOverrides.cfc

@@ -0,0 +1,19 @@
+component secured {
+
+    function index( event, rc, prc ) {
+        event.noRender();
+    }
+
+    function secret( event, rc, prc ) secured="superadmin" {
+        event.noRender();
+    }
+
+    function onAuthenticationFailure( event, rc, prc ) {
+        event.noRender();
+    }
+
+    function onAuthorizationFailure( event, rc, prc ) {
+        event.noRender();
+    }
+
+}

tests/specs/integration/APIRedirectsSpec.cfc

@@ -1,19 +1,9 @@
 component extends="tests.resources.ModuleIntegrationSpec" appMapping="/app" {
 
-    property name="authenticationService" inject="AuthenticationService";
     property name="interceptorService" inject="coldbox:interceptorService";
 
-    function beforeAll() {
-        super.beforeAll();
-        getWireBox().autowire( this );
-    }
-
     function run() {
         describe( "API Redirect Specs", function() {
-            beforeEach( function() {
-                authenticationService.logout();
-            } );
-
             it( "redirects the user to the normal authentication failure event if no API authentication event is set", function() {
                 var securedEventInterceptor = interceptorService.getInterceptor( "SecuredEventInterceptor" );
                 var authenticationFailureRedirect = securedEventInterceptor.getProperty( "authenticationOverrideEvent" );

tests/specs/integration/AuthorizationSpec.cfc

@@ -73,25 +73,4 @@ component extends="tests.resources.ModuleIntegrationSpec" appMapping="/app" {
         } );
     }
 
-    private function createUser( overrides = {} ) {
-        var props = {
-            id = 1,
-            email = "johndoe@example.com",
-            username = "johndoe",
-            permissions = []
-        };
-        structAppend( props, overrides, true );
-        return tap( getInstance( "User" ), function( user ) {
-            user.setId( props.id );
-            user.setEmail( props.email );
-            user.setUsername( props.username );
-            user.setPermissions( props.permissions );
-        } );
-    }
-
-    private function tap( variable, callback ) {
-        callback( variable );
-        return variable;
-    }
-
 }

tests/specs/integration/LocalHandlerOverridesSpec.cfc

@@ -0,0 +1,18 @@
+component extends="tests.resources.ModuleIntegrationSpec" appMapping="/app" {
+
+    function run() {
+        describe( "local handler overrides", function() {
+            it( "looks for a local onAuthenticationFailure method on the handler for authentication failure events first", function() {
+                var event = execute( event = "LocalOverrides.index" );
+                expect( event.getValue( "event", "" ) ).toBe( "LocalOverrides.onAuthenticationFailure" );
+            } );
+
+            it( "looks for a local onAuthorizationFailure method on the handler for authentication failure events first", function() {
+                authenticationService.login( createUser( { permissions = [] } ) );
+                var event = execute( event = "LocalOverrides.secret" );
+                expect( event.getValue( "relocate_event", "" ) ).toBe( "LocalOverrides.onAuthorizationFailure" );
+            } );
+        } );
+  }
+
+}