From 25fc89fd30df3bb81975dbe46332c8905f405cc9 Mon Sep 17 00:00:00 2001
From: matiasperrone-exo <matias.perrone@exomindset.co>
Date: Wed, 27 May 2026 21:50:43 +0000
Subject: [PATCH] feat: MFAGateService (Two-Factor Gate Decision Service)

---
 app/Services/Auth/ITwoFactorGateService.php   |  33 +++++
 app/Services/Auth/MFAGateService.php          |  38 ++++++
 .../Auth/TwoFactorServiceProvider.php         |   4 +
 phpunit.xml                                   |   1 +
 tests/Unit/MFAGateServiceTest.php             | 113 ++++++++++++++++++
 5 files changed, 189 insertions(+)
 create mode 100644 app/Services/Auth/ITwoFactorGateService.php
 create mode 100644 app/Services/Auth/MFAGateService.php
 create mode 100644 tests/Unit/MFAGateServiceTest.php

diff --git a/app/Services/Auth/ITwoFactorGateService.php b/app/Services/Auth/ITwoFactorGateService.php
new file mode 100644
index 00000000..ad229f63
--- /dev/null
+++ b/app/Services/Auth/ITwoFactorGateService.php
@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Services\Auth;
+
+/**
+ * Copyright 2025 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 Auth\User;
+
+/**
+ * Interface ITwoFactorGateService
+ * @package App\Services\Auth
+ */
+interface ITwoFactorGateService
+{
+    /**
+     * Determines whether the given user must complete a 2FA challenge for the current login attempt.
+     * Pure decision — no session writes, no OTP generation, no persistence side effects.
+     *
+     * Infrastructure exceptions from the underlying device-trust check are not caught and propagate to the caller.
+     */
+    public function requiresChallenge(User $user, ?string $cookieToken): bool;
+}
diff --git a/app/Services/Auth/MFAGateService.php b/app/Services/Auth/MFAGateService.php
new file mode 100644
index 00000000..8c82bee3
--- /dev/null
+++ b/app/Services/Auth/MFAGateService.php
@@ -0,0 +1,38 @@
+<?php
+
+namespace App\Services\Auth;
+
+/**
+ * Copyright 2025 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 Auth\User;
+
+/**
+ * Class MFAGateService
+ * @package App\Services\Auth
+ */
+final class MFAGateService implements ITwoFactorGateService
+{
+    public function __construct(
+        private readonly IDeviceTrustService $deviceTrustService
+    ) {
+    }
+
+    public function requiresChallenge(User $user, ?string $cookieToken): bool
+    {
+        if (!$user->shouldRequire2FA()) {
+            return false;
+        }
+        return !$this->deviceTrustService->isDeviceTrusted($user, $cookieToken);
+    }
+}
diff --git a/app/Services/Auth/TwoFactorServiceProvider.php b/app/Services/Auth/TwoFactorServiceProvider.php
index 705eda7a..081eed76 100644
--- a/app/Services/Auth/TwoFactorServiceProvider.php
+++ b/app/Services/Auth/TwoFactorServiceProvider.php
@@ -1,5 +1,7 @@
 <?php
+
 namespace App\Services\Auth;
+
 /**
  * Copyright 2025 OpenStack Foundation
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -31,6 +33,7 @@ public function register(): void
     {
         $this->app->singleton(IDeviceTrustService::class, DeviceTrustService::class);
         $this->app->singleton(ITwoFactorAuditService::class, TwoFactorAuditService::class);
+        $this->app->singleton(ITwoFactorGateService::class, MFAGateService::class);
     }
 
     public function provides(): array
@@ -38,6 +41,7 @@ public function provides(): array
         return [
             IDeviceTrustService::class,
             ITwoFactorAuditService::class,
+            ITwoFactorGateService::class,
         ];
     }
 }
diff --git a/phpunit.xml b/phpunit.xml
index 005f6b46..4c4f8d12 100644
--- a/phpunit.xml
+++ b/phpunit.xml
@@ -29,6 +29,7 @@
       <file>./tests/Unit/MFA/EmailOTPMFAChallengeStrategyTest.php</file>
       <file>./tests/Unit/MFA/MFAChallengeStrategyFactoryTest.php</file>
       <file>./tests/Unit/TwoFactorAuditServiceTest.php</file>
+      <file>./tests/Unit/MFAGateServiceTest.php</file>
     </testsuite>
   </testsuites>
   <php>
diff --git a/tests/Unit/MFAGateServiceTest.php b/tests/Unit/MFAGateServiceTest.php
new file mode 100644
index 00000000..49c66822
--- /dev/null
+++ b/tests/Unit/MFAGateServiceTest.php
@@ -0,0 +1,113 @@
+<?php
+
+namespace Tests\Unit;
+
+/**
+ * Copyright 2025 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\Services\Auth\IDeviceTrustService;
+use App\Services\Auth\MFAGateService;
+use Auth\User;
+use Mockery;
+use Tests\TestCase;
+use Mockery\MockInterface;
+
+/**
+ * Class MFAGateServiceTest
+ * @package Tests\Unit
+ */
+final class MFAGateServiceTest extends TestCase
+{
+    private MFAGateService $service;
+
+    private MockInterface&IDeviceTrustService $deviceTrustService;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->deviceTrustService = Mockery::mock(IDeviceTrustService::class);
+        $this->service = new MFAGateService($this->deviceTrustService);
+    }
+
+    protected function tearDown(): void
+    {
+        Mockery::close();
+        parent::tearDown();
+    }
+
+    // -------------------------------------------------------------------------
+    // Non-admin/non-enforced user with 2FA disabled returns false
+    // -------------------------------------------------------------------------
+
+    public function testRequiresChallengeReturnsFalseWhenUserDoesNotRequire2FA(): void
+    {
+        $user = Mockery::mock(User::class);
+        $user->shouldReceive('shouldRequire2FA')->once()->andReturn(false);
+        $this->deviceTrustService->shouldNotReceive('isDeviceTrusted');
+
+        $this->assertFalse($this->service->requiresChallenge($user, null));
+    }
+
+    // -------------------------------------------------------------------------
+    // Admin/enforced user with no cookie returns true
+    // -------------------------------------------------------------------------
+
+    public function testRequiresChallengeReturnsTrueWhenEnforcedAndNoCookie(): void
+    {
+        $user = Mockery::mock(User::class);
+        $user->shouldReceive('shouldRequire2FA')->once()->andReturn(true);
+        $this->deviceTrustService->shouldReceive('isDeviceTrusted')->once()->with($user, null)->andReturn(false);
+
+        $this->assertTrue($this->service->requiresChallenge($user, null));
+    }
+
+    // -------------------------------------------------------------------------
+    // Admin/enforced user with trusted device returns false
+    // -------------------------------------------------------------------------
+
+    public function testRequiresChallengeReturnsFalseWhenEnforcedAndDeviceTrusted(): void
+    {
+        $user = Mockery::mock(User::class);
+        $user->shouldReceive('shouldRequire2FA')->once()->andReturn(true);
+        $this->deviceTrustService->shouldReceive('isDeviceTrusted')->once()->with($user, 'valid-token')->andReturn(true);
+
+        $this->assertFalse($this->service->requiresChallenge($user, 'valid-token'));
+    }
+
+    // -------------------------------------------------------------------------
+    // Admin/enforced user with expired/revoked/wrong device returns true
+    // -------------------------------------------------------------------------
+
+    public function testRequiresChallengeReturnsTrueWhenEnforcedAndDeviceNotTrusted(): void
+    {
+        $user = Mockery::mock(User::class);
+        $user->shouldReceive('shouldRequire2FA')->once()->andReturn(true);
+        $this->deviceTrustService->shouldReceive('isDeviceTrusted')->once()->with($user, 'expired-token')->andReturn(false);
+
+        $this->assertTrue($this->service->requiresChallenge($user, 'expired-token'));
+    }
+
+    // -------------------------------------------------------------------------
+    // Empty-string cookie is forwarded as-is (not coerced to null) and treated
+    // as untrusted — documents the ?string contract between gate and trust layers
+    // -------------------------------------------------------------------------
+
+    public function testRequiresChallengePassesThroughEmptyStringCookieToDeviceTrustService(): void
+    {
+        $user = Mockery::mock(User::class);
+        $user->shouldReceive('shouldRequire2FA')->once()->andReturn(true);
+        $this->deviceTrustService->shouldReceive('isDeviceTrusted')->once()->with($user, '')->andReturn(false);
+
+        $this->assertTrue($this->service->requiresChallenge($user, ''));
+    }
+}