Laravel 2FA

A Laravel package that adds multi-provider two-factor authentication (TOTP, WebAuthn/Passkey, SMS, and Email) to any Laravel application, with recovery codes and route-level middleware protection.

What's inside

• TOTP provider — compatible with Google Authenticator, Authy, and other standard TOTP apps, including QR code generation for enrollment.
• WebAuthn/Passkey provider — registration and verification backed by a WebAuthn credential repository, for hardware keys and platform authenticators.
• SMS provider — code generation and verification, with the actual SMS delivery left to be wired up to a provider of your choice.
• Email provider — verification codes sent via a built-in mailable.
• Recovery codes — generated per user, with regeneration and one-time-use verification.
• Middleware — two-factor to enforce a completed challenge on protected routes, and two-factor.verified to gate the challenge flow itself.
• Facade (TwoFactor) — programmatic access to enable/disable providers, verify codes, and check verification state.
• Extensible provider architecture — new providers can be registered against a common TwoFactorProvider contract.

Tech stack

• PHP
• Laravel (package targets the Laravel 10–12 range)
• pragmarx/google2fa for TOTP
• web-auth/webauthn-lib and web-auth/cose-lib for WebAuthn
• bacon/bacon-qr-code for QR code rendering

Quickstart

This is a Composer package meant to be installed into a host Laravel application, not run standalone.

# 1. Install into your Laravel app
composer require mortogo321/laravel-2fa

# 2. Publish config and migrations
php artisan vendor:publish --tag=two-factor-config
php artisan vendor:publish --tag=two-factor-migrations
php artisan migrate

# 3. (Optional) Publish views to customize the Blade templates
php artisan vendor:publish --tag=two-factor-views

Add the trait to your user model and protect routes with the middleware:

// app/Models/User.php
use YourVendor\Laravel2FA\Traits\HasTwoFactorAuthentication;

class User extends Authenticatable
{
    use HasTwoFactorAuthentication;
}

// routes/web.php
Route::middleware(['auth', 'two-factor'])->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

Note: the PSR-4 namespace declared in composer.json and used throughout src/ is YourVendor\Laravel2FA (a placeholder that has not been renamed to a real vendor namespace yet).

Project structure

• src/Contracts/ — TwoFactorProvider and TwoFactorAuthenticatable interfaces.
• src/Providers/ — the four built-in providers (TOTP, WebAuthn, SMS, Email).
• src/Services/ — TwoFactorManager (provider orchestration), RecoveryCodeService, WebAuthnCredentialRepository.
• src/Http/Controllers/ — TwoFactorAuthenticationController handling the challenge, settings, enable/disable, and recovery code actions.
• src/Http/Middleware/ — RequireTwoFactorAuthentication and EnsureTwoFactorIsVerified.
• src/Models/ — TwoFactorMethod, RecoveryCode, WebAuthnKey Eloquent models.
• src/Traits/HasTwoFactorAuthentication.php — mixed into the host app's user model.
• src/Facades/TwoFactor.php — facade over TwoFactorManager.
• config/two-factor.php — per-provider settings, table names, route prefix/middleware, rate limiting, and session behavior.
• database/migrations/ — tables for two-factor methods, recovery codes, and WebAuthn keys.
• routes/web.php — package routes, registered under the configurable two-factor prefix.

Routes

Registered under the configurable prefix (two-factor by default) with the middleware set in config/two-factor.php (web, auth by default):

License

MIT — see LICENSE.