Merge pull request

Develop multi-factor authentication Laravel package

Author: coding-libs

README.md

@@ -1,2 +1,55 @@
 # 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');
+
+// Generate QR code (base64 PNG) from existing TOTP (uses bacon/bacon-qr-code)
+$base64 = MFA::generateTotpQrCodeBase64(auth()->user(), issuer: 'MyApp');
+// <img src="$base64" />
+```
+
+Configuration
+- See `config/mfa.php` for email/sms/totp options.
+
+Extending: Custom Channels
+```php
+use CodingLibs\MFA\Contracts\MfaChannel;
+use CodingLibs\MFA\Facades\MFA;
+use Illuminate\Contracts\Auth\Authenticatable;
+
+class WhatsAppChannel implements MfaChannel {
+    public function __construct(private array $config = []) {}
+    public function getName(): string { return 'whatsapp'; }
+    public function send(Authenticatable $user, string $code, array $options = []): void {
+        // send via provider...
+    }
+}
+
+// register at boot
+MFA::registerChannel(new WhatsAppChannel(config('mfa.whatsapp', [])));
+
+// then issue
+MFA::issueChallenge(auth()->user(), 'whatsapp');
+```

composer.json

@@ -0,0 +1,44 @@
+{
+  "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",
+    "bacon/bacon-qr-code": "^2.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/ChannelRegistry.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace CodingLibs\MFA;
+
+use CodingLibs\MFA\Contracts\MfaChannel;
+
+class ChannelRegistry
+{
+    /** @var array<string, MfaChannel> */
+    protected array $channels = [];
+
+    public function register(MfaChannel $channel): void
+    {
+        $this->channels[strtolower($channel->getName())] = $channel;
+    }
+
+    public function has(string $name): bool
+    {
+        return array_key_exists(strtolower($name), $this->channels);
+    }
+
+    public function get(string $name): ?MfaChannel
+    {
+        return $this->channels[strtolower($name)] ?? null;
+    }
+
+    /** @return array<string, MfaChannel> */
+    public function all(): array
+    {
+        return $this->channels;
+    }
+}
+

src/Channels/EmailChannel.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace CodingLibs\MFA\Channels;
+
+use CodingLibs\MFA\Contracts\MfaChannel;
+use Illuminate\Contracts\Auth\Authenticatable;
+use Illuminate\Support\Facades\Mail;
+
+class EmailChannel implements MfaChannel
+{
+    public function __construct(protected array $config = [])
+    {
+    }
+
+    public function getName(): string
+    {
+        return 'email';
+    }
+
+    public function send(Authenticatable $user, string $code, array $options = []): 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';
+        if (isset($options['subject'])) {
+            $subject = $options['subject'];
+        }
+
+        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,43 @@
+<?php
+
+namespace CodingLibs\MFA\Channels;
+
+use CodingLibs\MFA\Contracts\MfaChannel;
+use Illuminate\Contracts\Auth\Authenticatable;
+use Illuminate\Support\Facades\Log;
+
+class SmsChannel implements MfaChannel
+{
+    public function __construct(protected array $config = [])
+    {
+    }
+
+    public function getName(): string
+    {
+        return 'sms';
+    }
+
+    public function send(Authenticatable $user, string $code, array $options = []): 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 = $options['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/Contracts/MfaChannel.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace CodingLibs\MFA\Contracts;
+
+use Illuminate\Contracts\Auth\Authenticatable;
+
+interface MfaChannel
+{
+    public function getName(): string;
+
+    public function send(Authenticatable $user, string $code, array $options = []): void;
+}
+

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';
+    }
+}
+