feat: add documentation and test for skipping 2FA verification

Author: arodu

Docs/Documentation/Two-Factor-Authenticator.md

@@ -52,3 +52,32 @@ the QR code shown (image 1).
 
 <img src="OneTimePasswordAuthenticator/App.png?raw=true" width="300"/>
 
+
+Skipping 2FA Verification
+-------------------------
+You can conditionally skip the Two-Factor Authentication verify step for specific users 
+or scenarios by listening to the `UsersPlugin::EVENT_2FA_SKIP_VERIFY` event.
+
+If the event returns `true`, the verification is skipped, and the user is logged in immediately. 
+The event receives the `user` data as a payload.
+
+**Example: Skipping 2FA based on User Role**
+
+In your `src/Application.php` or a dedicated Event Listener:
+
+```php
+use Cake\Event\EventInterface;
+use CakeDC\Users\UsersPlugin;
+
+// ...
+
+$this->getEventManager()->on(UsersPlugin::EVENT_2FA_SKIP_VERIFY, function (EventInterface $event) {
+    $user = $event->getData('user');
+
+    // Check if the user has the 'admin' role
+    if (!empty($user['role']) && $user['role'] === 'admin') {
+        // Return true to skip the 2FA verification for this user role
+        $event->setResult(true);
+    }
+});
+```

tests/TestCase/Controller/Traits/OneTimePasswordVerifyTraitTest.php

@@ -16,7 +16,11 @@
 use Cake\Core\Configure;
 use Cake\Http\ServerRequest;
 use Cake\ORM\TableRegistry;
+use Cake\Event\Event;
 use CakeDC\Auth\Controller\Component\OneTimePasswordAuthenticatorComponent;
+use CakeDC\Auth\Authentication\AuthenticationService;
+use CakeDC\Auth\Authenticator\TwoFactorAuthenticator;
+use CakeDC\Users\UsersPlugin;
 
 class OneTimePasswordVerifyTraitTest extends BaseTrait
 {
@@ -277,4 +281,49 @@ public function testVerifyGetDoesNotGenerateNewSecret()
             $session->read(),
         );
     }
+
+    /**
+     * testVerifySkipEventCheck
+     */
+    public function testVerifySkipEventCheck()
+    {
+        Configure::write('OneTimePasswordAuthenticator.login', true);
+        $request = $this->getMockBuilder('Cake\Http\ServerRequest')
+            ->onlyMethods(['is', 'getData', 'getSession'])
+            ->addMethods(['allow'])
+            ->getMock();
+        $this->Trait->setRequest($request);
+
+        $userData = [
+            'id' => 1,
+            'secret_verified' => 1,
+            'email' => 'test@example.com'
+        ];
+        $session = $this->_mockSession([
+            'temporarySession' => $userData,
+        ]);
+
+        $eventMock = $this->getMockBuilder(Event::class)
+            ->disableOriginalConstructor()
+            ->getMock();
+        $eventMock->method('getResult')->willReturn(true);
+
+        $this->Trait->expects($this->once())
+            ->method('dispatchEvent')
+            ->with(UsersPlugin::EVENT_2FA_SKIP_VERIFY, ['user' => $userData])
+            ->willReturn($eventMock);
+
+        $this->Trait->expects($this->once())
+            ->method('redirect');
+        $this->Trait->verify();
+        
+        $this->assertNull(
+            $session->read(AuthenticationService::TWO_FACTOR_VERIFY_SESSION_KEY)
+        );
+
+        $this->assertEquals(
+            $userData,
+            $session->read(TwoFactorAuthenticator::USER_SESSION_KEY)
+        );
+    }
 }