Merge pull request #23

Document and test recovery code feature

Author: coding-libs

README.md

@@ -82,6 +82,46 @@ Remember Devices (Optional)
 - On subsequent requests, use `MFA::shouldSkipVerification($user, MFA::getRememberTokenFromRequest($request))`
 - To revoke a remembered device, call `MFA::forgetRememberedDevice($user, $token)`
 
+Recovery Codes
+- What they are: single‑use backup codes that let users complete MFA when they cannot access their primary factor (e.g., lost phone or no network).
+- Storage and security:
+  - Plaintext codes are returned only once at generation time; only their hashes are stored in `mfa_recovery_codes`.
+  - Hashing algorithm is configurable via `mfa.recovery.hash_algo` (default `sha256`).
+  - Codes are marked as used at first successful verification and cannot be reused.
+- Generating and displaying to the user:
+```php
+// Generate N codes (defaults come from config)
+$codes = MFA::generateRecoveryCodes($user); // array of plaintext codes
+
+// Show these codes once to the user and prompt them to store securely
+// e.g., render as a list and offer a download/print option
+```
+- Verifying a code and optional regeneration-on-use:
+```php
+if (MFA::verifyRecoveryCode($user, $input)) {
+    // Success: log user in and consider rotating codes if desired
+}
+```
+- Pool size maintenance: set `mfa.recovery.regenerate_on_use = true` to automatically replace a consumed code with a new one so the remaining count stays steady.
+- Managing codes:
+```php
+// Count remaining unused codes
+$remaining = MFA::getRemainingRecoveryCodesCount($user);
+
+// Replace all existing codes with a new set
+$fresh = MFA::generateRecoveryCodes($user); // replaceExisting=true by default
+
+// Append without deleting existing codes
+$extra = MFA::generateRecoveryCodes($user, count: 2, replaceExisting: false);
+
+// Clear all codes
+$deleted = MFA::clearRecoveryCodes($user);
+```
+- UX recommendations:
+  - Require the user to confirm they’ve saved the codes before leaving the setup screen.
+  - Offer copy, download (txt), and print actions. Avoid storing plaintext on your servers.
+  - Warn that each code is one-time and will be invalid after use.
+
 Configuration
 - See `config/mfa.php` for all options. Key settings:
   - **code_length**: OTP digits for email/sms (default 6)

composer.json

@@ -25,7 +25,8 @@
   },
   "autoload-dev": {
     "psr-4": {
-      "CodingLibs\\MFA\\Tests\\": "tests/"
+      "CodingLibs\\MFA\\Tests\\": "tests/",
+      "Tests\\": "tests/"
     }
   },
   "extra": {

tests/Feature/RecoveryCodesTest.php

@@ -0,0 +1,100 @@
+<?php
+
+use CodingLibs\MFA\Models\MfaRecoveryCode;
+use Illuminate\Contracts\Auth\Authenticatable;
+
+uses(Tests\TestCase::class);
+
+class FakeUser implements Authenticatable
+{
+	public function __construct(public int|string $id) {}
+	public function getAuthIdentifierName()
+	{
+		return 'id';
+	}
+	public function getAuthIdentifier()
+	{
+		return $this->id;
+	}
+	public function getAuthPassword()
+	{
+		return '';
+	}
+	public function getRememberToken()
+	{
+		return null;
+	}
+	public function setRememberToken($value): void {}
+	public function getRememberTokenName()
+	{
+		return 'remember_token';
+	}
+}
+
+it('generates recovery codes and persists hashed versions', function () {
+	$user = new FakeUser(1);
+	$mfa = app(\CodingLibs\MFA\MFA::class);
+
+	$codes = $mfa->generateRecoveryCodes($user, 5, 12);
+	expect($codes)->toHaveCount(5);
+	foreach ($codes as $code) {
+		expect(strlen($code))->toBe(12);
+	}
+
+	$remaining = $mfa->getRemainingRecoveryCodesCount($user);
+	expect($remaining)->toBe(5);
+
+	$records = MfaRecoveryCode::query()
+		->where('model_type', get_class($user))
+		->where('model_id', $user->getAuthIdentifier())
+		->get();
+	expect($records)->toHaveCount(5);
+	foreach ($records as $rec) {
+		// Ensure hashes are stored, not plaintext
+		expect($codes)->not->toContain($rec->code_hash);
+		expect($rec->used_at)->toBeNull();
+	}
+});
+
+it('verifies and consumes a recovery code', function () {
+	$user = new FakeUser(2);
+	$mfa = app(\CodingLibs\MFA\MFA::class);
+
+	$codes = $mfa->generateRecoveryCodes($user, 3, 10);
+	$ok = $mfa->verifyRecoveryCode($user, $codes[0]);
+	expect($ok)->toBeTrue();
+
+	// cannot reuse the same code
+	$okAgain = $mfa->verifyRecoveryCode($user, $codes[0]);
+	expect($okAgain)->toBeFalse();
+
+	$remaining = $mfa->getRemainingRecoveryCodesCount($user);
+	expect($remaining)->toBe(2);
+});
+
+it('regenerates on use when enabled', function () {
+	config(['mfa.recovery.regenerate_on_use' => true]);
+	$user = new FakeUser(3);
+	$mfa = app(\CodingLibs\MFA\MFA::class);
+
+	$codes = $mfa->generateRecoveryCodes($user, 4, 8);
+	$ok = $mfa->verifyRecoveryCode($user, $codes[1]);
+	expect($ok)->toBeTrue();
+
+	// Pool size remains steady due to auto-regeneration
+	$remaining = $mfa->getRemainingRecoveryCodesCount($user);
+	expect($remaining)->toBe(4);
+});
+
+it('clearRecoveryCodes deletes all codes', function () {
+	$user = new FakeUser(4);
+	$mfa = app(\CodingLibs\MFA\MFA::class);
+
+	$mfa->generateRecoveryCodes($user, 2, 10);
+	$deleted = $mfa->clearRecoveryCodes($user);
+	expect($deleted)->toBeGreaterThanOrEqual(2);
+
+	$remaining = $mfa->getRemainingRecoveryCodesCount($user);
+	expect($remaining)->toBe(0);
+});
+

tests/Pest.php

@@ -2,3 +2,6 @@
 
 /* Minimal Pest bootstrap for unit tests */
 uses()->group('unit');
+
+// Enable Laravel Testbench for Feature tests
+uses(Tests\TestCase::class)->in('Feature');

tests/TestCase.php

@@ -2,9 +2,31 @@
 
 namespace Tests;
 
-use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
+use CodingLibs\MFA\MFAServiceProvider;
+use Orchestra\Testbench\TestCase as BaseTestCase;
 
 abstract class TestCase extends BaseTestCase
 {
-    //
+    protected function getPackageProviders($app)
+    {
+        return [MFAServiceProvider::class];
+    }
+
+    protected function getEnvironmentSetUp($app): void
+    {
+        config()->set('database.default', 'testing');
+        config()->set('database.connections.testing', [
+            'driver'   => 'sqlite',
+            'database' => ':memory:',
+            'prefix'   => '',
+        ]);
+    }
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        // Run package migrations
+        $migration = require __DIR__ . '/../database/migrations/create_mfa_tables.php';
+        $migration->up();
+    }
 }