Allow TwoFactor providers to be stateless

src/bundle/Security/TwoFactor/Provider/TwoFactorProviderInitiator.php

@@ -8,6 +8,11 @@
 use Scheb\TwoFactorBundle\Security\Authentication\Token\TwoFactorTokenInterface;
 use Scheb\TwoFactorBundle\Security\TwoFactor\AuthenticationContextInterface;
 use Scheb\TwoFactorBundle\Security\TwoFactor\Provider\Exception\UnknownTwoFactorProviderException;
+use function array_walk;
+use function count;
+use function method_exists;
+use function trigger_error;
+use const E_USER_DEPRECATED;
 
 /**
  * @final
@@ -21,12 +26,9 @@ public function __construct(
     ) {
     }
 
-    /**
-     * @return string[]
-     */
-    private function getActiveTwoFactorProviders(AuthenticationContextInterface $context): array
+    public function beginTwoFactorAuthentication(AuthenticationContextInterface $context): TwoFactorTokenInterface|null
     {
-        $activeTwoFactorProviders = [];
+        $activeTwoFactorProviders = $statelessProviders = [];
 
         // Iterate over two-factor providers and begin the two-factor authentication process.
         foreach ($this->providerRegistry->getAllProviders() as $providerName => $provider) {
@@ -35,32 +37,40 @@ private function getActiveTwoFactorProviders(AuthenticationContextInterface $con
             }
 
             $activeTwoFactorProviders[] = $providerName;
-        }
 
-        return $activeTwoFactorProviders;
-    }
+            if (!method_exists($provider, 'needsPreparation')) {
+                @trigger_error(
+                    'Two-factor provider "'.$providerName.'" does not implement needsPreparation() method. This method will be required in the next major version.',
+                    E_USER_DEPRECATED,
+                );
+            }
 
-    public function beginTwoFactorAuthentication(AuthenticationContextInterface $context): TwoFactorTokenInterface|null
-    {
-        $activeTwoFactorProviders = $this->getActiveTwoFactorProviders($context);
+            if (!method_exists($provider, 'needsPreparation') || $provider->needsPreparation()) {
+                continue;
+            }
+
+            $statelessProviders[] = $providerName;
+        }
+
+        if (0 === count($activeTwoFactorProviders)) {
+            return null;
+        }
 
         $authenticatedToken = $context->getToken();
-        if ($activeTwoFactorProviders) {
-            $twoFactorToken = $this->twoFactorTokenFactory->create($authenticatedToken, $context->getFirewallName(), $activeTwoFactorProviders);
+        $twoFactorToken = $this->twoFactorTokenFactory->create($authenticatedToken, $context->getFirewallName(), $activeTwoFactorProviders);
 
-            $preferredProvider = $this->twoFactorProviderDecider->getPreferredTwoFactorProvider($activeTwoFactorProviders, $twoFactorToken, $context);
+        array_walk($statelessProviders, static fn (string $providerName) => $twoFactorToken->setTwoFactorProviderPrepared($providerName));
 
-            if (null !== $preferredProvider) {
-                try {
-                    $twoFactorToken->preferTwoFactorProvider($preferredProvider);
-                } catch (UnknownTwoFactorProviderException) {
-                    // Bad user input
-                }
-            }
+        $preferredProvider = $this->twoFactorProviderDecider->getPreferredTwoFactorProvider($activeTwoFactorProviders, $twoFactorToken, $context);
 
-            return $twoFactorToken;
+        if (null !== $preferredProvider) {
+            try {
+                $twoFactorToken->preferTwoFactorProvider($preferredProvider);
+            } catch (UnknownTwoFactorProviderException) {
+                // Bad user input
+            }
         }
 
-        return null;
+        return $twoFactorToken;
     }
 }

src/bundle/Security/TwoFactor/Provider/TwoFactorProviderInterface.php

@@ -6,13 +6,25 @@
 
 use Scheb\TwoFactorBundle\Security\TwoFactor\AuthenticationContextInterface;
 
+/**
+ * @method bool needsPreparation()
+ */
 interface TwoFactorProviderInterface
 {
     /**
      * Return true when two-factor authentication process should be started.
      */
     public function beginAuthentication(AuthenticationContextInterface $context): bool;
 
+    /**
+     * Determine whether this Provider needs to be prepared (if the prepareAuthentication method needs to be called).
+     *
+     * In version 9, this method will be introduced, and all providers will need to implement it.
+     * Currently, it will be called, but is not required.
+     *
+     * public function needsPreparation(): bool;
+     */
+
     /**
      * Do all steps necessary to prepare authentication, e.g. generate & send a code.
      */

src/email/Security/TwoFactor/Provider/Email/EmailTwoFactorProvider.php

@@ -34,6 +34,11 @@ public function beginAuthentication(AuthenticationContextInterface $context): bo
         return $user instanceof TwoFactorInterface && $user->isEmailAuthEnabled();
     }
 
+    public function needsPreparation(): bool
+    {
+        return true;
+    }
+
     public function prepareAuthentication(object $user): void
     {
         if (!($user instanceof TwoFactorInterface)) {

src/google-authenticator/Security/TwoFactor/Provider/Google/GoogleAuthenticatorTwoFactorProvider.php

@@ -38,6 +38,11 @@ public function beginAuthentication(AuthenticationContextInterface $context): bo
         return true;
     }
 
+    public function needsPreparation(): bool
+    {
+        return false;
+    }
+
     public function prepareAuthentication(object $user): void
     {
     }

src/totp/Security/TwoFactor/Provider/Totp/TotpAuthenticatorTwoFactorProvider.php

@@ -42,6 +42,11 @@ public function beginAuthentication(AuthenticationContextInterface $context): bo
         return true;
     }
 
+    public function needsPreparation(): bool
+    {
+        return false;
+    }
+
     public function prepareAuthentication(object $user): void
     {
     }

tests/Security/TwoFactor/Provider/TwoFactorProviderInitiatorTest.php

@@ -18,24 +18,48 @@
 class TwoFactorProviderInitiatorTest extends AbstractAuthenticationContextTestCase
 {
     private MockObject&TwoFactorTokenFactoryInterface $twoFactorTokenFactory;
-    private MockObject&TwoFactorProviderInterface $provider1;
-    private MockObject&TwoFactorProviderInterface $provider2;
+    private MockObject&TwoFactorProviderWithNeedsPreparationInterface $statefulProvider;
+    private MockObject&TwoFactorProviderWithNeedsPreparationInterface $statelessProvider;
+    private MockObject&TwoFactorProviderInterface $withoutNeedsPreparationProvider;
     private MockObject&TwoFactorProviderDeciderInterface $providerDecider;
     private TwoFactorProviderInitiator $initiator;
 
     protected function setUp(): void
     {
-        $this->provider1 = $this->createMock(TwoFactorProviderInterface::class);
-        $this->provider2 = $this->createMock(TwoFactorProviderInterface::class);
+        $this->statefulProvider = $this->createMock(TwoFactorProviderWithNeedsPreparationInterface::class);
+        $this->statefulProvider
+            ->expects($this->any())
+            ->method('needsPreparation')
+            ->willReturn(true);
+
+        $this->statelessProvider = $this->createMock(TwoFactorProviderWithNeedsPreparationInterface::class);
+        $this->statelessProvider
+            ->expects($this->any())
+            ->method('needsPreparation')
+            ->willReturn(false);
+
+        $this->withoutNeedsPreparationProvider = $this->createMock(TwoFactorProviderInterface::class);
 
         $providerRegistry = $this->createMock(TwoFactorProviderRegistry::class);
         $providerRegistry
             ->expects($this->any())
             ->method('getAllProviders')
             ->willReturn([
-                'test1' => $this->provider1,
-                'test2' => $this->provider2,
+                'statefulProvider' => $this->statefulProvider,
+                'statelessProvider' => $this->statelessProvider,
+                'withoutNeedsPreparation' => $this->withoutNeedsPreparationProvider,
             ]);
+        $providerRegistry
+            ->expects($this->any())
+            ->method('getProvider')
+            ->willReturnCallback(function (string $name) {
+                return match ($name) {
+                    'statefulProvider' => $this->statefulProvider,
+                    'statelessProvider' => $this->statelessProvider,
+                    'withoutNeedsPreparation' => $this->withoutNeedsPreparationProvider,
+                    default => null,
+                };
+            });
 
         $this->twoFactorTokenFactory = $this->createMock(TwoFactorTokenFactory::class);
 
@@ -60,17 +84,22 @@ private function createUserWithPreferredProvider(string $preferredProvider): Moc
         return $user;
     }
 
-    private function stubProvidersReturn(bool $provider1Returns, bool $provider2Returns): void
+    private function stubProvidersReturn(bool $statefulProviderReturns, bool $statelessProviderReturns, bool $legacyProviderReturns): void
     {
-        $this->provider1
-            ->expects($this->any())
+        $this->statefulProvider
+            ->expects($this->once())
             ->method('beginAuthentication')
-            ->willReturn($provider1Returns);
+            ->willReturn($statefulProviderReturns);
 
-        $this->provider2
-            ->expects($this->any())
+        $this->statelessProvider
+            ->expects($this->once())
             ->method('beginAuthentication')
-            ->willReturn($provider2Returns);
+            ->willReturn($statelessProviderReturns);
+
+        $this->withoutNeedsPreparationProvider
+            ->expects($this->once())
+            ->method('beginAuthentication')
+            ->willReturn($legacyProviderReturns);
     }
 
     private function stubTwoFactorTokenFactoryReturns(MockObject $token): void
@@ -94,12 +123,17 @@ public function beginAuthentication_multipleProviders_beginAuthenticationOnEachT
     {
         $context = $this->createAuthenticationContext();
 
-        $this->provider1
+        $this->statefulProvider
+            ->expects($this->once())
+            ->method('beginAuthentication')
+            ->with($context);
+
+        $this->statelessProvider
             ->expects($this->once())
             ->method('beginAuthentication')
             ->with($context);
 
-        $this->provider2
+        $this->withoutNeedsPreparationProvider
             ->expects($this->once())
             ->method('beginAuthentication')
             ->with($context);
@@ -112,13 +146,13 @@ public function beginAuthentication_oneProviderStarts_returnTwoFactorToken(): vo
     {
         $originalToken = $this->createToken();
         $context = $this->createAuthenticationContext(null, $originalToken);
-        $this->stubProvidersReturn(false, true);
+        $this->stubProvidersReturn(false, true, false);
 
         $twoFactorToken = $this->createMock(TwoFactorTokenInterface::class);
         $this->twoFactorTokenFactory
             ->expects($this->once())
             ->method('create')
-            ->with($originalToken, self::FIREWALL_NAME, ['test2'])
+            ->with($originalToken, self::FIREWALL_NAME, ['statelessProvider'])
             ->willReturn($twoFactorToken);
 
         $returnValue = $this->initiator->beginTwoFactorAuthentication($context);
@@ -130,7 +164,7 @@ public function beginAuthentication_noProviderStarts_returnNull(): void
     {
         $originalToken = $this->createToken();
         $context = $this->createAuthenticationContext(null, $originalToken);
-        $this->stubProvidersReturn(false, false);
+        $this->stubProvidersReturn(false, false, false);
 
         $returnValue = $this->initiator->beginTwoFactorAuthentication($context);
         $this->assertNull($returnValue);
@@ -144,7 +178,7 @@ public function beginAuthentication_hasPreferredProvider_setThatProviderPreferre
         $twoFactorToken = $this->createTwoFactorToken();
 
         $context = $this->createAuthenticationContext(null, $originalToken, $user);
-        $this->stubProvidersReturn(true, true);
+        $this->stubProvidersReturn(true, true, true);
         $this->stubTwoFactorTokenFactoryReturns($twoFactorToken);
         $this->stubTwoFactorProviderDeciderReturns('preferredProvider');
 
@@ -155,4 +189,21 @@ public function beginAuthentication_hasPreferredProvider_setThatProviderPreferre
 
         $this->initiator->beginTwoFactorAuthentication($context);
     }
+
+    #[Test]
+    public function beginAuthentication_statelessProviderPrepared_setThatProviderIsPrepared(): void
+    {
+        $originalToken = $this->createToken();
+        $context = $this->createAuthenticationContext(null, $originalToken);
+        $this->stubProvidersReturn(true, true, true);
+
+        $twoFactorToken = $this->createTwoFactorToken();
+        $this->stubTwoFactorTokenFactoryReturns($twoFactorToken);
+        $twoFactorToken
+            ->expects($this->once())
+            ->method('setTwoFactorProviderPrepared')
+            ->with('statelessProvider');
+
+        $this->initiator->beginTwoFactorAuthentication($context);
+    }
 }

tests/Security/TwoFactor/Provider/TwoFactorProviderWithNeedsPreparationInterface.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scheb\TwoFactorBundle\Tests\Security\TwoFactor\Provider;
+
+use Scheb\TwoFactorBundle\Security\TwoFactor\Provider\TwoFactorProviderInterface;
+
+/**
+ * Used to mock providers with the needsPreparation method for forward compatibility testing.
+ * In version 9, needsPreparation() will be required on TwoFactorProviderInterface.
+ */
+interface TwoFactorProviderWithNeedsPreparationInterface extends TwoFactorProviderInterface
+{
+    public function needsPreparation(): bool;
+}