feat: Add MultiFactor Authentication

Author: matiasperrone-exo

app/libs/Auth/Models/User.php

@@ -76,6 +76,15 @@ class User extends BaseEntity
         self::SpamTypeHam
     ];
 
+    public const MFAMethod_OTP = 'email_otp';
+    public const MFAMethod_SMS = 'sms_otp';
+    public const MFAMethod_TOTP = 'totp';
+    public const MFAMethod_PASSKEY = 'passkey';
+
+    public const ValidMFAMethods = [
+        self::MFAMethod_OTP
+    ];
+
     /**
      * @var string
      */
@@ -303,6 +312,25 @@ class User extends BaseEntity
      */
     #[ORM\Column(name: 'email_verified_date', nullable: true, type: 'datetime')]
     private $email_verified_date;
+
+    /**
+     * @var bool
+     */
+    #[ORM\Column(name: 'two_factor_enabled', type: 'boolean', options: ['default' => false])]
+    private $two_factor_enabled;
+
+    /**
+     * @var string
+     */
+    #[ORM\Column(name: 'two_factor_method', type: 'string', length: 32, options: ['default' => self::MFAMethod_OTP])]
+    private $two_factor_method;
+
+    /**
+     * @var \DateTime|null
+     */
+    #[ORM\Column(name: 'two_factor_enforced_at', nullable: true, type: 'datetime')]
+    private $two_factor_enforced_at;
+
     /**
      * @var string
      */
@@ -457,6 +485,9 @@ public function __construct()
         parent::__construct();
         $this->active = true;
         $this->email_verified = false;
+        $this->two_factor_enabled = false;
+        $this->two_factor_method = self::MFAMethod_OTP;
+        $this->two_factor_enforced_at = null;
         // user profile settings
         $this->public_profile_show_photo = false;
         $this->public_profile_show_email = false;
@@ -2359,4 +2390,142 @@ public function getAuthPasswordName()
         return 'password';
     }
 
+    // --- Two-factor authentication ---------------------------------------
+
+    public function isTwoFactorEnabled(): bool
+    {
+        return (bool) $this->two_factor_enabled;
+    }
+
+    public function setTwoFactorEnabled(bool $enabled): void
+    {
+        $this->two_factor_enabled = $enabled;
+    }
+
+    public function getTwoFactorMethod(): string
+    {
+        return $this->two_factor_method;
+    }
+
+    /**
+     * @throws ValidationException
+     */
+    protected function setTwoFactorMethod(string $method): void
+    {
+        $this->two_factor_method = $method;
+    }
+
+    public function getTwoFactorEnforcedAt(): ?\DateTime
+    {
+        return $this->two_factor_enforced_at;
+    }
+
+    public function setTwoFactorEnforcedAt(?\DateTime $at): void
+    {
+        $this->two_factor_enforced_at = $at;
+    }
+
+    /**
+     * Whether this user is required to complete 2FA to sign in.
+     *
+     * A user is required when they belong to any of the groups listed in
+     * config('two_factor.enforced_groups'); otherwise the stored flag applies.
+     */
+    public function shouldRequire2FA(): bool
+    {
+        $enforcedGroups = config('two_factor.enforced_groups', []);
+        foreach ($enforcedGroups as $slug) {
+            if($this->belongToGroup($slug)) {
+                return true;
+            }
+        }
+        return (bool) $this->two_factor_enabled;
+    }
+
+    /**
+     * @throws ValidationException
+     */
+    public function enable2FA(string $method): void
+    {
+        $availableMethods = $this->getAvailableTwoFactorMethods();
+        if(!in_array($method, self::ValidMFAMethods, true)) {
+            throw new ValidationException(
+                sprintf(
+                    "Invalid 2FA method '%s'. Allowed methods: %s. Enabled methods: %s",
+                    $method,
+                    implode(', ', self::ValidMFAMethods),
+                    implode(', ', $availableMethods)
+                )
+            );
+        }
+
+        if(!in_array($method, $availableMethods, true)) {
+            throw new ValidationException(
+                sprintf(
+                    "Disabled 2FA method '%s'. Enabled methods: %s",
+                    $method,
+                    implode(', ', $availableMethods)
+                )
+            );
+        }
+
+        $this->setTwoFactorMethod($method);
+        $this->setTwoFactorEnabled(true);
+        $this->setTwoFactorEnforcedAt(new \DateTime('now', new \DateTimeZone('UTC')));
+    }
+
+    public function disable2FA(): void
+    {
+        $this->setTwoFactorEnabled(false);
+        $this->setTwoFactorEnforcedAt(null);
+    }
+
+    /**
+     * Returns the set of 2FA methods currently available to this user.
+     * Phase I only supports email_otp; other methods are stubs that will
+     * light up in Phase II/III once the backing verifications exist.
+     *
+     * @return string[]
+     */
+    public function getAvailableTwoFactorMethods(): array
+    {
+        $methods = [];
+        if($this->isEmailVerified() && in_array(self::MFAMethod_OTP, self::ValidMFAMethods, true)) {
+            $methods[] = self::MFAMethod_OTP;
+        }
+        if($this->isPhoneNumberVerified() && in_array(self::MFAMethod_SMS, self::ValidMFAMethods, true)) {
+            $methods[] = self::MFAMethod_SMS;
+        }
+        if($this->isTOTPConfirmed() && in_array(self::MFAMethod_TOTP, self::ValidMFAMethods, true)) {
+            $methods[] = self::MFAMethod_TOTP;
+        }
+        if($this->isPassKeyEnabled() && in_array(self::MFAMethod_PASSKEY, self::ValidMFAMethods, true)) {
+            $methods[] = self::MFAMethod_PASSKEY;
+        }
+        return $methods;
+    }
+
+    public function isTwoFactorMethodEnabled(string $method): bool
+    {
+        return in_array($method, $this->getAvailableTwoFactorMethods(), true);
+    }
+
+    // Phase II stub
+    public function isPhoneNumberVerified(): bool
+    {
+        return false;
+    }
+
+    // Phase III stub
+    public function isTOTPConfirmed(): bool
+    {
+        return false;
+    }
+
+    // Phase III stub
+    public function isPassKeyEnabled(): bool
+    {
+        return false;
+    }
+
 }

config/two_factor.php

@@ -0,0 +1,33 @@
+<?php
+/**
+ * Copyright 2026 OpenStack Foundation
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+
+use App\libs\Auth\Models\IGroupSlugs;
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Enforced Groups
+    |--------------------------------------------------------------------------
+    |
+    | Users that belong to any of these groups are required to complete 2FA
+    | regardless of the value of their `two_factor_enabled` flag.
+    |
+    */
+    'enforced_groups' => [
+        IGroupSlugs::SuperAdminGroup,
+        IGroupSlugs::AdminGroup,
+        IGroupSlugs::OAuth2ServerAdminGroup,
+        IGroupSlugs::OpenIdServerAdminsGroup,
+    ],
+];

phpunit.xml

@@ -22,6 +22,10 @@
     <testsuite name="OTEL Custom Formatters Test Suite">
       <directory>./tests/OpenTelemetry/Formatters/</directory>
     </testsuite>
+    <testsuite name="Two Factor Authentication Test Suite">
+      <file>./tests/TwoFactorRepositoriesTest.php</file>
+      <file>./tests/unit/UserTwoFactorTest.php</file>
+    </testsuite>
   </testsuites>
   <php>
     <env name="APP_ENV" value="testing"/>