Create Laravel MFA package with email, SMS, and TOTP support

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

Author: cursoragent

README.md

@@ -1,2 +1,30 @@
 # mfa
 Multi Factor Authentication
+CodingLibs Laravel MFA
+
+Installation
+- Require in your Laravel 12 app composer.json or via path repository.
+- The service provider auto-registers. Publish config and migrations:
+```
+php artisan vendor:publish --tag=mfa-config
+php artisan vendor:publish --tag=mfa-migrations
+php artisan migrate
+```
+
+Usage
+```php
+use CodingLibs\MFA\Facades\MFA;
+
+// Email/SMS
+$challenge = MFA::issueChallenge(auth()->user(), 'email');
+// then later
+$ok = MFA::verifyChallenge(auth()->user(), 'email', '123456');
+
+// TOTP
+$setup = MFA::setupTotp(auth()->user());
+// $setup['otpauth_url'] -> QR code; then verify
+$ok = MFA::verifyTotp(auth()->user(), '123456');
+```
+
+Configuration
+- See `config/mfa.php` for email/sms/totp options.

composer.json

@@ -0,0 +1,43 @@
+{
+  "name": "codinglibs/laravel-mfa",
+  "description": "Laravel 12 Multi-Factor Authentication package (Email, SMS, Google Authenticator TOTP)",
+  "type": "library",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "CodingLibs",
+      "email": "support@codinglibs.example"
+    }
+  ],
+  "require": {
+    "php": ">=8.2",
+    "illuminate/support": "^12.0",
+    "illuminate/database": "^12.0",
+    "illuminate/mail": "^12.0",
+    "illuminate/config": "^12.0",
+    "illuminate/console": "^12.0"
+  },
+  "autoload": {
+    "psr-4": {
+      "CodingLibs\\MFA\\": "src/"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "CodingLibs\\MFA\\Tests\\": "tests/"
+    }
+  },
+  "extra": {
+    "laravel": {
+      "providers": [
+        "CodingLibs\\MFA\\MFAServiceProvider"
+      ],
+      "aliases": {
+        "MFA": "CodingLibs\\MFA\\Facades\\MFA"
+      }
+    }
+  },
+  "minimum-stability": "stable",
+  "prefer-stable": true
+}
+

config/mfa.php

@@ -0,0 +1,27 @@
+<?php
+
+return [
+    'code_length' => 6,
+    'code_ttl_seconds' => 300,
+
+    'email' => [
+        'enabled' => true,
+        'from_address' => env('MFA_EMAIL_FROM_ADDRESS', env('MAIL_FROM_ADDRESS')),
+        'from_name' => env('MFA_EMAIL_FROM_NAME', env('MAIL_FROM_NAME', 'Laravel')),
+        'subject' => env('MFA_EMAIL_SUBJECT', 'Your verification code'),
+    ],
+
+    'sms' => [
+        'enabled' => true,
+        'driver' => env('MFA_SMS_DRIVER', 'log'), // log|null
+        'from' => env('MFA_SMS_FROM', ''),
+    ],
+
+    'totp' => [
+        'issuer' => env('MFA_TOTP_ISSUER', config('app.name')),
+        'digits' => (int) env('MFA_TOTP_DIGITS', 6),
+        'period' => (int) env('MFA_TOTP_PERIOD', 30),
+        'window' => (int) env('MFA_TOTP_WINDOW', 1),
+    ],
+];
+

database/migrations/create_mfa_tables.php

@@ -0,0 +1,41 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::create('mfa_methods', function (Blueprint $table) {
+            $table->id();
+            $table->string('user_type');
+            $table->string('user_id');
+            $table->string('method'); // email|sms|totp
+            $table->text('secret')->nullable(); // for totp
+            $table->timestamp('enabled_at')->nullable();
+            $table->timestamp('last_used_at')->nullable();
+            $table->timestamps();
+            $table->index(['user_type', 'user_id', 'method']);
+        });
+
+        Schema::create('mfa_challenges', function (Blueprint $table) {
+            $table->id();
+            $table->string('user_type');
+            $table->string('user_id');
+            $table->string('method'); // email|sms
+            $table->string('code');
+            $table->timestamp('expires_at');
+            $table->timestamp('consumed_at')->nullable();
+            $table->timestamps();
+            $table->index(['user_type', 'user_id', 'method']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('mfa_challenges');
+        Schema::dropIfExists('mfa_methods');
+    }
+};
+

src/Channels/EmailChannel.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace CodingLibs\MFA\Channels;
+
+use Illuminate\Contracts\Auth\Authenticatable;
+use Illuminate\Support\Facades\Mail;
+
+class EmailChannel
+{
+    public function __construct(protected array $config = [])
+    {
+    }
+
+    public function send(Authenticatable $user, string $code): void
+    {
+        if (! ($this->config['enabled'] ?? true)) {
+            return;
+        }
+
+        $to = method_exists($user, 'getEmailForVerification') ? $user->getEmailForVerification() : ($user->email ?? null);
+        if (! $to) {
+            return;
+        }
+
+        $fromAddress = $this->config['from_address'] ?? null;
+        $fromName = $this->config['from_name'] ?? null;
+        $subject = $this->config['subject'] ?? 'Your verification code';
+
+        Mail::raw("Your verification code is: {$code}", function ($message) use ($to, $fromAddress, $fromName, $subject) {
+            $message->to($to)->subject($subject);
+            if ($fromAddress) {
+                $message->from($fromAddress, $fromName);
+            }
+        });
+    }
+}
+

src/Channels/SmsChannel.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace CodingLibs\MFA\Channels;
+
+use Illuminate\Contracts\Auth\Authenticatable;
+use Illuminate\Support\Facades\Log;
+
+class SmsChannel
+{
+    public function __construct(protected array $config = [])
+    {
+    }
+
+    public function send(Authenticatable $user, string $code): void
+    {
+        if (! ($this->config['enabled'] ?? true)) {
+            return;
+        }
+
+        $driver = $this->config['driver'] ?? 'log';
+        $to = method_exists($user, 'getPhoneNumberForVerification') ? $user->getPhoneNumberForVerification() : ($user->phone ?? null);
+        if (! $to) {
+            return;
+        }
+
+        $message = "Your verification code is: {$code}";
+
+        if ($driver === 'log') {
+            Log::info('MFA SMS', ['to' => $to, 'message' => $message]);
+            return;
+        }
+
+        // Placeholder: extendable for twilio/aws pinoint/etc via events or bindings.
+        Log::warning('MFA SMS driver not implemented', ['driver' => $driver, 'to' => $to]);
+    }
+}
+

src/Facades/MFA.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace CodingLibs\MFA\Facades;
+
+use Illuminate\Support\Facades\Facade;
+
+class MFA extends Facade
+{
+    protected static function getFacadeAccessor(): string
+    {
+        return 'mfa';
+    }
+}
+

src/MFA.php

@@ -0,0 +1,160 @@
+<?php
+
+namespace CodingLibs\MFA;
+
+use CodingLibs\MFA\Channels\EmailChannel;
+use CodingLibs\MFA\Channels\SmsChannel;
+use CodingLibs\MFA\Models\MfaChallenge;
+use CodingLibs\MFA\Models\MfaMethod;
+use CodingLibs\MFA\Totp\GoogleTotp;
+use Illuminate\Contracts\Auth\Authenticatable;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\DB;
+
+class MFA
+{
+    protected array $config;
+
+    public function __construct(array $config)
+    {
+        $this->config = $config;
+    }
+
+    public function setupTotp(Authenticatable $user, ?string $issuer = null, ?string $label = null): array
+    {
+        $secret = GoogleTotp::generateSecret();
+        $issuer = $issuer ?: Arr::get($this->config, 'totp.issuer', 'Laravel');
+        $label = $label ?: method_exists($user, 'getEmailForVerification') ? $user->getEmailForVerification() : ($user->email ?? (string) $user->getAuthIdentifier());
+        $otpauth = GoogleTotp::buildOtpAuthUrl($secret, $label, $issuer, Arr::get($this->config, 'totp.digits', 6));
+
+        $this->enableMethod($user, 'totp', ['secret' => $secret]);
+
+        return [
+            'secret' => $secret,
+            'otpauth_url' => $otpauth,
+        ];
+    }
+
+    public function verifyTotp(Authenticatable $user, string $code): bool
+    {
+        $method = $this->getMethod($user, 'totp');
+        if (! $method || ! $method->secret) {
+            return false;
+        }
+
+        $digits = Arr::get($this->config, 'totp.digits', 6);
+        $period = Arr::get($this->config, 'totp.period', 30);
+        $window = Arr::get($this->config, 'totp.window', 1);
+
+        $verified = GoogleTotp::verifyCode($method->secret, $code, $digits, $period, $window);
+        if ($verified) {
+            $method->last_used_at = Carbon::now();
+            $method->save();
+        }
+        return $verified;
+    }
+
+    public function issueChallenge(Authenticatable $user, string $method): ?MfaChallenge
+    {
+        $method = strtolower($method);
+        if (! in_array($method, ['email', 'sms'], true)) {
+            return null;
+        }
+
+        $codeLength = Arr::get($this->config, 'code_length', 6);
+        $ttlSeconds = Arr::get($this->config, 'code_ttl_seconds', 300);
+        $code = str_pad((string) random_int(0, (10 ** $codeLength) - 1), $codeLength, '0', STR_PAD_LEFT);
+
+        $challenge = new MfaChallenge();
+        $challenge->user_type = get_class($user);
+        $challenge->user_id = $user->getAuthIdentifier();
+        $challenge->method = $method;
+        $challenge->code = $code;
+        $challenge->expires_at = Carbon::now()->addSeconds($ttlSeconds);
+        $challenge->save();
+
+        if ($method === 'email') {
+            (new EmailChannel($this->config['email'] ?? []))->send($user, $code);
+        } else if ($method === 'sms') {
+            (new SmsChannel($this->config['sms'] ?? []))->send($user, $code);
+        }
+
+        return $challenge;
+    }
+
+    public function verifyChallenge(Authenticatable $user, string $method, string $code): bool
+    {
+        $now = Carbon::now();
+
+        $challenge = MfaChallenge::query()
+            ->where('user_type', get_class($user))
+            ->where('user_id', $user->getAuthIdentifier())
+            ->where('method', strtolower($method))
+            ->whereNull('consumed_at')
+            ->where('expires_at', '>', $now)
+            ->latest('id')
+            ->first();
+
+        if (! $challenge) {
+            return false;
+        }
+
+        if (hash_equals($challenge->code, $code)) {
+            $challenge->consumed_at = $now;
+            $challenge->save();
+
+            $this->enableMethod($user, $challenge->method);
+
+            return true;
+        }
+
+        return false;
+    }
+
+    public function enableMethod(Authenticatable $user, string $method, array $attributes = []): MfaMethod
+    {
+        $record = $this->getMethod($user, $method);
+        if (! $record) {
+            $record = new MfaMethod();
+            $record->user_type = get_class($user);
+            $record->user_id = $user->getAuthIdentifier();
+            $record->method = strtolower($method);
+        }
+
+        foreach ($attributes as $key => $value) {
+            $record->setAttribute($key, $value);
+        }
+
+        $record->enabled_at = Carbon::now();
+        $record->save();
+
+        return $record;
+    }
+
+    public function disableMethod(Authenticatable $user, string $method): bool
+    {
+        $record = $this->getMethod($user, $method);
+        if (! $record) {
+            return false;
+        }
+        $record->enabled_at = null;
+        return $record->save();
+    }
+
+    public function isEnabled(Authenticatable $user, string $method): bool
+    {
+        $record = $this->getMethod($user, $method);
+        return (bool) ($record && $record->enabled_at);
+    }
+
+    public function getMethod(Authenticatable $user, string $method): ?MfaMethod
+    {
+        return MfaMethod::query()
+            ->where('user_type', get_class($user))
+            ->where('user_id', $user->getAuthIdentifier())
+            ->where('method', strtolower($method))
+            ->first();
+    }
+}
+