├── LICENSE
├── Model
    └── BackupCodeInterface.php
├── README.md
├── Security
    ├── Http
    │   └── EventListener
    │   │   └── CheckBackupCodeListener.php
    └── TwoFactor
    │   ├── Backup
    │       ├── BackupCodeManager.php
    │       ├── BackupCodeManagerInterface.php
    │       └── NullBackupCodeManager.php
    │   └── Event
    │       └── BackupCodeEvents.php
└── composer.json


/LICENSE:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2024 Christian Scheb
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of
 6 | this software and associated documentation files (the "Software"), to deal in
 7 | the Software without restriction, including without limitation the rights to
 8 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 9 | the Software, and to permit persons to whom the Software is furnished to do so,
10 | subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 | 


--------------------------------------------------------------------------------
/Model/BackupCodeInterface.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Scheb\TwoFactorBundle\Model;
 6 | 
 7 | interface BackupCodeInterface
 8 | {
 9 |     /**
10 |      * Check if it is a valid backup code.
11 |      */
12 |     public function isBackupCode(string $code): bool;
13 | 
14 |     /**
15 |      * Invalidate a backup code.
16 |      */
17 |     public function invalidateBackupCode(string $code): void;
18 | }
19 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | scheb/2fa-backup-code
 2 | =====================
 3 | 
 4 | [![Build Status](https://github.com/scheb/2fa/actions/workflows/ci.yaml/badge.svg?branch=7.x)](https://github.com/scheb/2fa/actions?query=workflow%3ACI+branch%3A7.x)
 5 | [![Code Coverage](https://codecov.io/gh/scheb/2fa/branch/7.x/graph/badge.svg)](https://app.codecov.io/gh/scheb/2fa/branch/7.x)
 6 | [![Latest Stable Version](https://img.shields.io/packagist/v/scheb/2fa-backup-code)](https://packagist.org/packages/scheb/2fa-backup-code)
 7 | [![Monthly Downloads](https://img.shields.io/packagist/dm/scheb/2fa-backup-code)](https://packagist.org/packages/scheb/2fa-backup-code/stats)
 8 | [![Total Downloads](https://img.shields.io/packagist/dt/scheb/2fa-backup-code)](https://packagist.org/packages/scheb/2fa-backup-code/stats)
 9 | [![License](https://poser.pugx.org/scheb/2fa-backup-code/license.svg)](https://packagist.org/packages/scheb/2fa-backup-code)
10 | 
11 | This package extends [scheb/2fa-bundle](https://github.com/scheb/2fa-bundle) with backup codes support.
12 | 
13 | ---
14 | 
15 | This repository is a sub-repository of [scheb/2fa](https://github.com/scheb/2fa) and is **READ ONLY**.
16 | 
17 | **Please do not submit any Pull Request here.** Use the [main repository](https://github.com/scheb/2fa) instead.
18 | 
19 | Installation
20 | ------------
21 | Please follow the [bundle's installation instructions](https://symfony.com/bundles/SchebTwoFactorBundle/7.x/installation.html).
22 | 
23 | Documentation
24 | -------------
25 | Documentation can be found on the
26 | [Symfony Bundles Documentation](https://symfony.com/bundles/SchebTwoFactorBundle/7.x/index.html) website.
27 | 
28 | License
29 | -------
30 | This software is available under the [MIT license](LICENSE).
31 | 


--------------------------------------------------------------------------------
/Security/Http/EventListener/CheckBackupCodeListener.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Scheb\TwoFactorBundle\Security\Http\EventListener;
 6 | 
 7 | use Scheb\TwoFactorBundle\Security\TwoFactor\Backup\BackupCodeManagerInterface;
 8 | use Scheb\TwoFactorBundle\Security\TwoFactor\Event\BackupCodeEvents;
 9 | use Scheb\TwoFactorBundle\Security\TwoFactor\Event\TwoFactorCodeEvent;
10 | use Scheb\TwoFactorBundle\Security\TwoFactor\Provider\PreparationRecorderInterface;
11 | use Symfony\Component\Security\Http\Event\CheckPassportEvent;
12 | use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
13 | 
14 | /**
15 |  * @final
16 |  */
17 | class CheckBackupCodeListener extends AbstractCheckCodeListener
18 | {
19 |     // Must be called before CheckTwoFactorCodeListener, because CheckTwoFactorCodeListener will throw an exception
20 |     // when the code is wrong.
21 |     public const LISTENER_PRIORITY = CheckTwoFactorCodeListener::LISTENER_PRIORITY + 16;
22 | 
23 |     public function __construct(
24 |         PreparationRecorderInterface $preparationRecorder,
25 |         private readonly BackupCodeManagerInterface $backupCodeManager,
26 |         private readonly EventDispatcherInterface $eventDispatcher,
27 |     ) {
28 |         parent::__construct($preparationRecorder);
29 |     }
30 | 
31 |     protected function isValidCode(string $providerName, object $user, string $code): bool
32 |     {
33 |         $event = new TwoFactorCodeEvent($user, $code);
34 |         $this->eventDispatcher->dispatch($event, BackupCodeEvents::CHECK);
35 | 
36 |         if ($this->backupCodeManager->isBackupCode($user, $code)) {
37 |             $this->eventDispatcher->dispatch($event, BackupCodeEvents::VALID);
38 |             $this->backupCodeManager->invalidateBackupCode($user, $code);
39 | 
40 |             return true;
41 |         }
42 | 
43 |         $this->eventDispatcher->dispatch($event, BackupCodeEvents::INVALID);
44 | 
45 |         return false;
46 |     }
47 | 
48 |     /**
49 |      * {@inheritDoc}
50 |      */
51 |     public static function getSubscribedEvents(): array
52 |     {
53 |         return [CheckPassportEvent::class => ['checkPassport', self::LISTENER_PRIORITY]];
54 |     }
55 | }
56 | 


--------------------------------------------------------------------------------
/Security/TwoFactor/Backup/BackupCodeManager.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Scheb\TwoFactorBundle\Security\TwoFactor\Backup;
 6 | 
 7 | use Scheb\TwoFactorBundle\Model\BackupCodeInterface;
 8 | use Scheb\TwoFactorBundle\Model\PersisterInterface;
 9 | 
10 | /**
11 |  * @final
12 |  */
13 | class BackupCodeManager implements BackupCodeManagerInterface
14 | {
15 |     public function __construct(private readonly PersisterInterface $persister)
16 |     {
17 |     }
18 | 
19 |     public function isBackupCode(object $user, string $code): bool
20 |     {
21 |         if ($user instanceof BackupCodeInterface) {
22 |             return $user->isBackupCode($code);
23 |         }
24 | 
25 |         return false;
26 |     }
27 | 
28 |     public function invalidateBackupCode(object $user, string $code): void
29 |     {
30 |         if (!($user instanceof BackupCodeInterface)) {
31 |             return;
32 |         }
33 | 
34 |         $user->invalidateBackupCode($code);
35 |         $this->persister->persist($user);
36 |     }
37 | }
38 | 


--------------------------------------------------------------------------------
/Security/TwoFactor/Backup/BackupCodeManagerInterface.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Scheb\TwoFactorBundle\Security\TwoFactor\Backup;
 6 | 
 7 | interface BackupCodeManagerInterface
 8 | {
 9 |     /**
10 |      * Check if the code is a valid backup code of the user.
11 |      */
12 |     public function isBackupCode(object $user, string $code): bool;
13 | 
14 |     /**
15 |      * Invalidate a backup code from a user.
16 |      */
17 |     public function invalidateBackupCode(object $user, string $code): void;
18 | }
19 | 


--------------------------------------------------------------------------------
/Security/TwoFactor/Backup/NullBackupCodeManager.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Scheb\TwoFactorBundle\Security\TwoFactor\Backup;
 6 | 
 7 | /**
 8 |  * @final
 9 |  */
10 | class NullBackupCodeManager implements BackupCodeManagerInterface
11 | {
12 |     public function isBackupCode(object $user, string $code): bool
13 |     {
14 |         return false;
15 |     }
16 | 
17 |     public function invalidateBackupCode(object $user, string $code): void
18 |     {
19 |     }
20 | }
21 | 


--------------------------------------------------------------------------------
/Security/TwoFactor/Event/BackupCodeEvents.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Scheb\TwoFactorBundle\Security\TwoFactor\Event;
 6 | 
 7 | /**
 8 |  * @final
 9 |  */
10 | class BackupCodeEvents
11 | {
12 |     /**
13 |      * When a code is checked if it is a valid backup code.
14 |      */
15 |     public const CHECK = 'scheb_two_factor.backup_code.check';
16 | 
17 |     /**
18 |      * When the code was deemed to be a valid backup code.
19 |      */
20 |     public const VALID = 'scheb_two_factor.backup_code.valid';
21 | 
22 |     /**
23 |      * When the code was deemed to be an invalid backup code.
24 |      */
25 |     public const INVALID = 'scheb_two_factor.backup_code.invalid';
26 | }
27 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "scheb/2fa-backup-code",
 3 |     "type": "library",
 4 |     "description": "Extends scheb/2fa-bundle with backup codes support",
 5 |     "keywords": ["2fa", "two-factor", "two-step", "authentication", "symfony", "backup-codes"],
 6 |     "homepage": "https://github.com/scheb/2fa",
 7 |     "license": "MIT",
 8 |     "authors": [
 9 |         {
10 |             "name": "Christian Scheb",
11 |             "email": "me@christianscheb.de"
12 |         }
13 |     ],
14 |     "require": {
15 |         "php": "~8.2.0 || ~8.3.0 || ~8.4.0",
16 |         "scheb/2fa-bundle": "self.version"
17 |     },
18 |     "autoload": {
19 |         "psr-4": {
20 |             "Scheb\\TwoFactorBundle\\": ""
21 |         }
22 |     }
23 | }
24 | 


--------------------------------------------------------------------------------