Merge pull request #397 from kenjis/refactor-auth-actions

refactor: Auth Actions (action classes are executed in the order set in `Config/Auth::$actions`)

Author: kenjis

docs/auth_actions.md

@@ -7,32 +7,35 @@
 Authentication Actions are a way to group actions that can happen after login or registration.
 Shield ships with two actions you can use, and makes it simple for you to define your own.
 
-1. **Email-based Two Factor Authentication** (Email2FA) will send a 6-digit code to the user's
+1. **Email-based Account Activation** (EmailActivate) confirms a new user's email address by
+   sending them an email with a link they must follow in order to have their account activated.
+2. **Email-based Two Factor Authentication** (Email2FA) will send a 6-digit code to the user's
     email address that they must confirm before they can continue.
-2. **Email-based Account Activation** (EmailActivate) confirms a new user's email address by
-    sending them an email with a link they must follow in order to have their account activated.
 
 ## Configuring Actions
 
 Actions are setup in the `Auth` config file, with the `$actions` variable.
 
 ```php
 public $actions = [
-    'login'    => null,
     'register' => null,
+    'login'    => null,
 ];
 ```
 
 To define an action to happen you will specify the class name as the value for the appropriate task:
 
 ```php
 public $actions = [
-    'login'    => 'CodeIgniter\Shield\Authentication\Actions\Email2FA',
     'register' => 'CodeIgniter\Shield\Authentication\Actions\EmailActivator',
+    'login'    => 'CodeIgniter\Shield\Authentication\Actions\Email2FA',
 ];
 ```
 
-Once configured, everything should work out of the box. The routes are added with the basic `auth()->routes($routes)`
+You must register actions in the order of the actions to be performed.
+Once configured, everything should work out of the box.
+
+The routes are added with the basic `auth()->routes($routes)`
 call, but can be manually added if you choose not to use this helper method.
 
 ```php
@@ -50,8 +53,8 @@ Views for all of these pages are defined in the `Auth` config file, with the `$v
         'action_email_2fa'            => '\CodeIgniter\Shield\Views\email_2fa_show',
         'action_email_2fa_verify'     => '\CodeIgniter\Shield\Views\email_2fa_verify',
         'action_email_2fa_email'      => '\CodeIgniter\Shield\Views\Email\email_2fa_email',
-        'action_email_activate_email' => '\CodeIgniter\Shield\Views\Email\email_activate_email',
         'action_email_activate_show'  => '\CodeIgniter\Shield\Views\email_activate_show',
+        'action_email_activate_email' => '\CodeIgniter\Shield\Views\Email\email_activate_email',
     ];
 ```
 
@@ -61,7 +64,7 @@ While the provided email-based activation and 2FA will work for many sites, othe
 needs, like using SMS to verify or something completely different. Actions have only one requirement:
 they must implement `CodeIgniter\Shield\Authentication\Actions\ActionInterface`.
 
-The interface defines three methods:
+The interface defines three methods for `ActionController`:
 
 **show()** should display the initial page the user lands on immediately after the authentication task,
 like login. It will typically display instructions to the user and provide an action to take, like
@@ -77,4 +80,4 @@ and provides feedback. In the `Email2FA` class, it verifies the code against wha
 database and either sends them back to the previous form to try again or redirects the user to the
 page that a `login` task would have redirected them to anyway.
 
-All methods should return either a `RedirectResponse` or a view string (e.g. using the `view()` function).
+All methods should return either a `Response` or a view string (e.g. using the `view()` function).

docs/quickstart.md

@@ -110,8 +110,8 @@ Turned off by default, Shield's Email-based 2FA can be enabled by specifying the
 
 ```php
 public array $actions = [
-    'login'    => 'CodeIgniter\Shield\Authentication\Actions\Email2FA',
     'register' => null,
+    'login'    => 'CodeIgniter\Shield\Authentication\Actions\Email2FA',
 ];
 ```
 
@@ -121,8 +121,8 @@ By default, once a user registers they have an active account that can be used.
 
 ```php
 public array $actions = [
-    'login'    => null,
     'register' => 'CodeIgniter\Shield\Authentication\Actions\EmailActivator',
+    'login'    => null,
 ];
 ```
 

src/Authentication/Actions/ActionInterface.php

@@ -6,6 +6,7 @@
 
 use CodeIgniter\HTTP\IncomingRequest;
 use CodeIgniter\HTTP\Response;
+use CodeIgniter\Shield\Entities\User;
 
 /**
  * Interface ActionInterface
@@ -47,4 +48,11 @@ public function verify(IncomingRequest $request);
      * E.g., 'email_2fa', 'email_activate'.
      */
     public function getType(): string;
+
+    /**
+     * Creates an identity for the action of the user.
+     *
+     * @return string secret
+     */
+    public function createIdentity(User $user): string;
 }

src/Authentication/Actions/Email2FA.php

@@ -8,6 +8,7 @@
 use CodeIgniter\HTTP\RedirectResponse;
 use CodeIgniter\Shield\Authentication\Authenticators\Session;
 use CodeIgniter\Shield\Entities\User;
+use CodeIgniter\Shield\Entities\UserIdentity;
 use CodeIgniter\Shield\Exceptions\RuntimeException;
 use CodeIgniter\Shield\Models\UserIdentityModel;
 
@@ -94,13 +95,20 @@ public function handle(IncomingRequest $request)
      */
     public function verify(IncomingRequest $request)
     {
-        $token = $request->getPost('token');
-
         /** @var Session $authenticator */
         $authenticator = auth('session')->getAuthenticator();
 
+        $postedToken = $request->getPost('token');
+
+        $user = $authenticator->getPendingUser();
+        if ($user === null) {
+            throw new RuntimeException('Cannot get the pending login User.');
+        }
+
+        $identity = $this->getIdentity($user);
+
         // Token mismatch? Let them try again...
-        if (! $authenticator->checkAction($this->type, $token)) {
+        if (! $authenticator->checkAction($identity, $postedToken)) {
             session()->setFlashdata('error', lang('Auth.invalid2FAToken'));
 
             return view(setting('Auth.views')['action_email_2fa_verify']);
@@ -111,21 +119,21 @@ public function verify(IncomingRequest $request)
     }
 
     /**
-     * Called from `Session::attempt()`.
+     * Creates an identity for the action of the user.
+     *
+     * @return string secret
      */
-    public function afterLogin(User $user): void
-    {
-        $this->createIdentity($user);
-    }
-
-    final protected function createIdentity(User $user): void
+    public function createIdentity(User $user): string
     {
         /** @var UserIdentityModel $identityModel */
         $identityModel = model(UserIdentityModel::class);
 
+        // Delete any previous identities for action
+        $identityModel->deleteIdentitiesByType($user, $this->type);
+
         $generator = static fn (): string => random_string('nozero', 6);
 
-        $identityModel->createCodeIdentity(
+        return $identityModel->createCodeIdentity(
             $user,
             [
                 'type'  => $this->type,
@@ -136,6 +144,23 @@ final protected function createIdentity(User $user): void
         );
     }
 
+    /**
+     * Returns an identity for the action of the user.
+     */
+    private function getIdentity(User $user): ?UserIdentity
+    {
+        /** @var UserIdentityModel $identityModel */
+        $identityModel = model(UserIdentityModel::class);
+
+        return $identityModel->getIdentityByType(
+            $user,
+            $this->type
+        );
+    }
+
+    /**
+     * Returns the string type of the action class.
+     */
     public function getType(): string
     {
         return $this->type;

src/Authentication/Actions/EmailActivator.php

@@ -10,6 +10,7 @@
 use CodeIgniter\HTTP\Response;
 use CodeIgniter\Shield\Authentication\Authenticators\Session;
 use CodeIgniter\Shield\Entities\User;
+use CodeIgniter\Shield\Entities\UserIdentity;
 use CodeIgniter\Shield\Exceptions\LogicException;
 use CodeIgniter\Shield\Exceptions\RuntimeException;
 use CodeIgniter\Shield\Models\UserIdentityModel;
@@ -77,13 +78,20 @@ public function handle(IncomingRequest $request)
      */
     public function verify(IncomingRequest $request)
     {
-        $token = $request->getVar('token');
-
         /** @var Session $authenticator */
         $authenticator = auth('session')->getAuthenticator();
 
+        $postedToken = $request->getVar('token');
+
+        $user = $authenticator->getPendingUser();
+        if ($user === null) {
+            throw new RuntimeException('Cannot get the pending login User.');
+        }
+
+        $identity = $this->getIdentity($user);
+
         // No match - let them try again.
-        if (! $authenticator->checkAction($this->type, $token)) {
+        if (! $authenticator->checkAction($identity, $postedToken)) {
             session()->setFlashdata('error', lang('Auth.invalidActivateToken'));
 
             return view(setting('Auth.views')['action_email_activate_show']);
@@ -100,18 +108,18 @@ public function verify(IncomingRequest $request)
     }
 
     /**
-     * Called from `RegisterController::registerAction()`
+     * Creates an identity for the action of the user.
+     *
+     * @return string secret
      */
-    public function afterRegister(User $user): void
-    {
-        $this->createIdentity($user);
-    }
-
-    final protected function createIdentity(User $user): string
+    public function createIdentity(User $user): string
     {
         /** @var UserIdentityModel $identityModel */
         $identityModel = model(UserIdentityModel::class);
 
+        // Delete any previous identities for action
+        $identityModel->deleteIdentitiesByType($user, $this->type);
+
         $generator = static fn (): string => random_string('nozero', 6);
 
         return $identityModel->createCodeIdentity(
@@ -125,6 +133,23 @@ final protected function createIdentity(User $user): string
         );
     }
 
+    /**
+     * Returns an identity for the action of the user.
+     */
+    private function getIdentity(User $user): ?UserIdentity
+    {
+        /** @var UserIdentityModel $identityModel */
+        $identityModel = model(UserIdentityModel::class);
+
+        return $identityModel->getIdentityByType(
+            $user,
+            $this->type
+        );
+    }
+
+    /**
+     * Returns the string type of the action class.
+     */
     public function getType(): string
     {
         return $this->type;