Add recovery codes support for multi-factor authentication

Co-authored-by: anwarx4u <anwarx4u@gmail.com>

Author: cursoragent

README.md

@@ -23,6 +23,7 @@ Features
 - Google Authenticator compatible **TOTP** (RFC 6238) setup and verification
 - Built-in QR code generation to display TOTP provisioning URI (uses bacon/bacon-qr-code)
 - Remember device support via secure, hashed tokens stored in `mfa_remembered_devices`
+- Recovery Codes: generate, verify, and manage one-time backup codes
 - Simple API via `MFA` facade/service for issuing and verifying codes
 - Publishable config and migrations; encrypted storage of TOTP secret
 - Extendable channel system to add providers like WhatsApp, Twilio, etc.
@@ -63,6 +64,16 @@ $cookie = $result['cookie']; // Symfony Cookie instance — attach to response
 
 // Later, skip MFA if remembered device cookie is valid
 $shouldSkip = MFA::shouldSkipVerification(auth()->user(), MFA::getRememberTokenFromRequest(request()));
+
+// Recovery Codes
+// Generate a fresh set (returns plaintext codes to show once)
+$codes = MFA::generateRecoveryCodes(auth()->user());
+// Verify and consume a recovery code
+$ok = MFA::verifyRecoveryCode(auth()->user(), $inputCode);
+// Count remaining unused codes
+$remaining = MFA::getRemainingRecoveryCodesCount(auth()->user());
+// Clear all codes
+$deleted = MFA::clearRecoveryCodes(auth()->user());
 ```
 
 Remember Devices (Optional)
@@ -92,6 +103,12 @@ Configuration
     - cookie: cookie name (default `mfa_rd`)
     - lifetime_days: validity window (default 30)
     - path, domain, secure, http_only, same_site
+  - **recovery**:
+    - enabled (bool, default true)
+    - codes_count: number of codes to generate (default 10)
+    - code_length: length of each code (default 10)
+    - regenerate_on_use: whether to auto-regenerate when consumed (default false)
+    - hash_algo: hashing algorithm for stored codes (default `sha256`)
 
 Environment variables (examples)
 ```
@@ -115,13 +132,20 @@ MFA_REMEMBER_DOMAIN=
 MFA_REMEMBER_SECURE=null
 MFA_REMEMBER_HTTP_ONLY=true
 MFA_REMEMBER_SAME_SITE=lax
+
+MFA_RECOVERY_ENABLED=true
+MFA_RECOVERY_CODES_COUNT=10
+MFA_RECOVERY_CODE_LENGTH=10
+MFA_RECOVERY_REGENERATE_ON_USE=false
+MFA_RECOVERY_HASH_ALGO=sha256
 ```
 
 Database
 - Publishing migrations creates tables:
   - `mfa_methods`: tracks enabled MFA methods per user; stores encrypted TOTP `secret`
   - `mfa_challenges`: stores pending OTP codes for email/sms with expiry and consumed_at
   - `mfa_remembered_devices`: stores hashed tokens for device recognition with IP, UA, and expiry
+  - `mfa_recovery_codes`: stores hashed recovery codes and usage timestamp
 
 API Overview (Facade `MFA`)
 - **issueChallenge(Authenticatable $user, string $method): ?MfaChallenge**
@@ -140,6 +164,11 @@ API Overview (Facade `MFA`)
   - **shouldSkipVerification(Authenticatable $user, ?string $token): bool**
   - **makeRememberCookie(string $token, ?int $lifetimeDays = null): Cookie**
   - **forgetRememberedDevice(Authenticatable $user, string $token): int**
+  - Recovery codes:
+    - **generateRecoveryCodes(Authenticatable $user, ?int $count = null, ?int $length = null, bool $replaceExisting = true): array** returns plaintext codes
+    - **verifyRecoveryCode(Authenticatable $user, string $code): bool**
+    - **getRemainingRecoveryCodesCount(Authenticatable $user): int**
+    - **clearRecoveryCodes(Authenticatable $user): int**
 
 Creating a Custom MFA Channel
 Steps

config/mfa.php

@@ -34,5 +34,13 @@
         'http_only'      => env('MFA_REMEMBER_HTTP_ONLY', true),
         'same_site'      => env('MFA_REMEMBER_SAME_SITE', 'lax'), // lax|strict|none
     ],
+
+    'recovery' => [
+        'enabled'            => env('MFA_RECOVERY_ENABLED', true),
+        'codes_count'        => (int) env('MFA_RECOVERY_CODES_COUNT', 10),
+        'code_length'        => (int) env('MFA_RECOVERY_CODE_LENGTH', 10),
+        'regenerate_on_use'  => env('MFA_RECOVERY_REGENERATE_ON_USE', false),
+        'hash_algo'          => env('MFA_RECOVERY_HASH_ALGO', 'sha256'),
+    ],
 ];
 

database/migrations/create_mfa_tables.php

@@ -46,10 +46,22 @@ public function up(): void
             $table->unique(['user_type', 'user_id', 'token_hash'], 'mfa_rd_unique');
             $table->index(['user_type', 'user_id'], 'mfa_rd_user_idx');
         });
+
+        Schema::create('mfa_recovery_codes', function (Blueprint $table) {
+            $table->id();
+            $table->string('user_type');
+            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
+            $table->string('code_hash', 128);
+            $table->timestamp('used_at')->nullable();
+            $table->timestamps();
+
+            $table->index(['user_type', 'user_id'], 'mfa_rc_user_idx');
+        });
     }
 
     public function down(): void
     {
+        Schema::dropIfExists('mfa_recovery_codes');
         Schema::dropIfExists('mfa_remembered_devices');
         Schema::dropIfExists('mfa_challenges');
         Schema::dropIfExists('mfa_methods');

src/Facades/MFA.php

@@ -27,6 +27,10 @@
  * @method static bool disableMethod(\Illuminate\Contracts\Auth\Authenticatable $user, string $method)
  * @method static bool isEnabled(\Illuminate\Contracts\Auth\Authenticatable $user, string $method)
  * @method static ?\CodingLibs\MFA\Models\MfaMethod getMethod(\Illuminate\Contracts\Auth\Authenticatable $user, string $method)
+ * @method static array generateRecoveryCodes(\Illuminate\Contracts\Auth\Authenticatable $user, ?int $count = null, ?int $length = null, bool $replaceExisting = true)
+ * @method static bool verifyRecoveryCode(\Illuminate\Contracts\Auth\Authenticatable $user, string $code)
+ * @method static int getRemainingRecoveryCodesCount(\Illuminate\Contracts\Auth\Authenticatable $user)
+ * @method static int clearRecoveryCodes(\Illuminate\Contracts\Auth\Authenticatable $user)
  *
  * @mixin \CodingLibs\MFA\MFA
  * @see \CodingLibs\MFA\MFA

src/MFA.php

@@ -10,6 +10,7 @@
 use CodingLibs\MFA\Models\MfaChallenge;
 use CodingLibs\MFA\Models\MfaMethod;
 use CodingLibs\MFA\Models\MfaRememberedDevice;
+use CodingLibs\MFA\Models\MfaRecoveryCode;
 use CodingLibs\MFA\Totp\GoogleTotp;
 use Illuminate\Contracts\Auth\Authenticatable;
 use Illuminate\Http\Request;
@@ -293,5 +294,103 @@ public function getMethod(Authenticatable $user, string $method): ?MfaMethod
             ->where('method', strtolower($method))
             ->first();
     }
+
+    /**
+     * Generate and persist recovery codes for the given user.
+     * Returns the plaintext codes; hashes are stored in DB.
+     */
+    public function generateRecoveryCodes(Authenticatable $user, ?int $count = null, ?int $length = null, bool $replaceExisting = true): array
+    {
+        $count = $count ?? (int) Arr::get($this->config, 'recovery.codes_count', 10);
+        $length = $length ?? (int) Arr::get($this->config, 'recovery.code_length', 10);
+
+        if ($replaceExisting) {
+            MfaRecoveryCode::query()
+                ->where('user_type', get_class($user))
+                ->where('user_id', $user->getAuthIdentifier())
+                ->delete();
+        }
+
+        $plaintextCodes = [];
+        for ($i = 0; $i < $count; $i++) {
+            $code = $this->generateReadableCode($length);
+            $hash = $this->hashRecoveryCode($code);
+
+            $record = new MfaRecoveryCode();
+            $record->user_type = get_class($user);
+            $record->user_id = $user->getAuthIdentifier();
+            $record->code_hash = $hash;
+            $record->used_at = null;
+            $record->save();
+
+            $plaintextCodes[] = $code;
+        }
+
+        return $plaintextCodes;
+    }
+
+    /** Verify and consume a recovery code for the user. */
+    public function verifyRecoveryCode(Authenticatable $user, string $code): bool
+    {
+        $hash = $this->hashRecoveryCode($code);
+        $record = MfaRecoveryCode::query()
+            ->where('user_type', get_class($user))
+            ->where('user_id', $user->getAuthIdentifier())
+            ->whereNull('used_at')
+            ->where('code_hash', $hash)
+            ->first();
+
+        if (! $record) {
+            return false;
+        }
+
+        $record->used_at = Carbon::now();
+        $record->save();
+
+        if ((bool) Arr::get($this->config, 'recovery.regenerate_on_use', false)) {
+            $length = (int) Arr::get($this->config, 'recovery.code_length', 10);
+            // Generate a single replacement code to keep the pool size steady
+            $this->generateRecoveryCodes($user, 1, $length, false);
+        }
+
+        return true;
+    }
+
+    /** Get remaining (unused) recovery codes count for the user. */
+    public function getRemainingRecoveryCodesCount(Authenticatable $user): int
+    {
+        return MfaRecoveryCode::query()
+            ->where('user_type', get_class($user))
+            ->where('user_id', $user->getAuthIdentifier())
+            ->whereNull('used_at')
+            ->count();
+    }
+
+    /** Delete all recovery codes for the user. Returns number deleted. */
+    public function clearRecoveryCodes(Authenticatable $user): int
+    {
+        return MfaRecoveryCode::query()
+            ->where('user_type', get_class($user))
+            ->where('user_id', $user->getAuthIdentifier())
+            ->delete();
+    }
+
+    protected function generateReadableCode(int $length): string
+    {
+        $alphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // exclude ambiguous chars
+        $maxIndex = strlen($alphabet) - 1;
+        $code = '';
+        for ($i = 0; $i < $length; $i++) {
+            $idx = random_int(0, $maxIndex);
+            $code .= $alphabet[$idx];
+        }
+        return $code;
+    }
+
+    protected function hashRecoveryCode(string $code): string
+    {
+        $algo = (string) Arr::get($this->config, 'recovery.hash_algo', 'sha256');
+        return hash($algo, $code);
+    }
 }
 

src/Models/MfaRecoveryCode.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace CodingLibs\MFA\Models;
+
+use Illuminate\Database\Eloquent\Model;
+
+class MfaRecoveryCode extends Model
+{
+    protected $table = 'mfa_recovery_codes';
+
+    protected $guarded = [];
+
+    protected $casts = [
+        'used_at' => 'datetime',
+    ];
+}
+