README

Modern authentication for Laravel with Paseto V4 tokens, 2FA, and Magic Links

Installation • Quick Start • Features • API Reference

Why BetterAuth?

BetterAuth uses Paseto V4 (Platform-Agnostic Security Tokens) - a modern, secure alternative to JWT that eliminates entire classes of vulnerabilities by design.

Installation

composer require betterauth/laravel

php artisan betterauth:install

That's it. The installer configures everything automatically.

Quick Start

use BetterAuth\Laravel\Facades\BetterAuth;

// Register
$result = BetterAuth::signUp([
    'email' => 'user@example.com',
    'password' => 'securepassword',
]);

// Login
$result = BetterAuth::signIn('user@example.com', 'password');
// → access_token, refresh_token, user

// Verify token
$payload = BetterAuth::verify($accessToken);

// Protected routes
Route::middleware('auth:betterauth')->get('/me', fn() => auth()->user());

Features

Core Authentication

• Paseto V4 Tokens - Encrypted, not just signed
• Argon2id Passwords - Memory-hard hashing (PHC winner)
• Refresh Token Rotation - One-time use with automatic rotation
• UUID v7 IDs - Time-ordered, database-friendly

Advanced Features

• Two-Factor Auth (TOTP) - With recovery codes
• Magic Links - Passwordless email authentication
• OAuth Providers - Google, GitHub, Facebook, and more
• Passkeys/WebAuthn - Biometric authentication (coming soon)

Laravel Native

• Works with Auth::guard('betterauth')
• Eloquent models and migrations
• Artisan commands
• Event dispatching

Requirements

Configuration

After installation, configure via environment variables:

BETTERAUTH_SECRET=your-64-character-secret-key
BETTERAUTH_MODE=api
BETTERAUTH_ACCESS_LIFETIME=3600
BETTERAUTH_REFRESH_LIFETIME=2592000

Or edit config/betterauth.php:

return [
    'mode' => 'api',                    // 'api', 'session', 'hybrid'
    'secret' => env('BETTERAUTH_SECRET'),
    'tokens' => [
        'access_lifetime' => 3600,      // 1 hour
        'refresh_lifetime' => 2592000,  // 30 days
    ],
    'user_model' => App\Models\User::class,
    'id_strategy' => 'uuid',            // 'uuid' or 'int'
];

Generate a new secret key:

php artisan betterauth:secret

API Reference

Authentication Endpoints

Two-Factor Authentication

Magic Links

User Model

Add the HasBetterAuth trait to your User model:

use BetterAuth\Laravel\Models\Traits\HasBetterAuth;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasBetterAuth;

    protected $fillable = ['email', 'password', 'name'];
}

The trait provides:

$user->getRoles();              // ['ROLE_USER', 'ROLE_ADMIN']
$user->hasRole('ROLE_ADMIN');   // true/false
$user->addRole('ROLE_ADMIN');
$user->removeRole('ROLE_ADMIN');
$user->createTokens();          // Generate new token pair
$user->revokeAllTokens();       // Revoke all refresh tokens

Two-Factor Authentication

Enable in configuration:

// config/betterauth.php
'two_factor' => [
    'enabled' => true,
    'issuer' => 'My App',
],

Using the service:

use BetterAuth\Laravel\Services\TwoFactorService;

$twoFactor = app(TwoFactorService::class);

// Setup
$setup = $twoFactor->generateSecret($user);
// → secret, qr_code_url, uri

// Enable
$result = $twoFactor->verifyAndEnable($user, '123456');
// → enabled, recovery_codes

// Verify
$valid = $twoFactor->verify($user, '123456');

Magic Links

Enable in configuration:

// config/betterauth.php
'magic_link' => [
    'enabled' => true,
    'expire' => 15, // minutes
],

Using the service:

use BetterAuth\Laravel\Services\MagicLinkService;

$magicLink = app(MagicLinkService::class);
$magicLink->send('user@example.com');

Events

// EventServiceProvider.php
protected $listen = [
    \BetterAuth\Laravel\Events\UserRegistered::class => [
        \App\Listeners\SendWelcomeEmail::class,
    ],
];

Middleware

// Require authentication
Route::middleware('auth:betterauth')->group(function () {
    // Protected routes
});

// Require email verification
Route::middleware(['auth:betterauth', EnsureEmailIsVerified::class])->group(...);

// Require 2FA enabled
Route::middleware(['auth:betterauth', RequiresTwoFactor::class])->group(...);

Security

Token Security (Paseto V4)

• XChaCha20-Poly1305 encryption
• Tokens are encrypted, not just signed
• No algorithm confusion attacks
• No key type confusion

Password Security (Argon2id)

• Winner of Password Hashing Competition
• Memory-hard to prevent GPU attacks
• Configurable memory/time/threads

Refresh Token Security

• Hashed before storage (SHA-256)
• One-time use - revoked after refresh
• Automatic rotation - new token on each refresh

Testing

# Run tests
composer test

# With coverage
composer test-coverage

# Static analysis
composer phpstan

License

MIT License. See LICENSE for details.