README

Bottled authentication for Laravel projects.

SwiftAuth is a production-ready authentication package for Laravel that provides a robust, secure, and flexible identity management system. It supports traditional session-based auth, multi-factor authentication (OTP & WebAuthn/Passkeys), role-based access control, and comprehensive session management.

This package is designed to be a drop-in solution for Laravel applications requiring enterprise-grade authentication features without the boilerplate.

Documentation Index

• Deployment Instructions
• Securing Routes ← Session & API Token Authentication
• API Documentation (Public Endpoints)
• Routes Documentation
• Artisan Commands
• Tests Documentation
• Architecture Diagrams
• Monitoring
• Business Logic & Core Processes
• Open Questions & Assumptions

This documentation and the codebase follow the project’s Coding Standards Guide and PHPDoc Style Guide.

Tech Stack & Requirements

• Type: Laravel Package
• PHP: 8.2+
• Laravel: 11.x / 12.x
• Key Dependencies:
  • equidna/bird-flock (Notification Bus)
  • laragear/webauthn (Passkey Support)
  • inertiajs/inertia-laravel (Frontend Interop)

Quick Start

1. Install the package:

   composer require equidna/swift-auth

2. Publish assets and configuration:

   php artisan swift-auth:install

   This will publish the config file (config/swift-auth.php), migrations, and frontend assets.

3. Run migrations:

   php artisan migrate

4. Create an initial admin user:

   php artisan swift-auth:create-admin-user

5. Serve and visit:

   Start your server:

   php artisan serve

   Visit /swift-auth/login (or your configured route prefix) to see the login page.

Localization

SwiftAuth includes full localization support for English and Spanish. Users can dynamically switch languages through a UI component, and the package automatically persists their preference in the session.

Supported Languages

• English (en) - Default
• Spanish (es)

Features

• Dynamic language switching via LanguageSwitcher component
• Session-based locale persistence
• All UI elements, emails, and notifications are fully translated
• Translation files organized by module (auth, email, session, user, role)

Usage

In PHP/Blade:

{{ __('swift-auth::auth.login_title') }}
@lang('swift-auth::email.verification_button')

In JavaScript/TypeScript:

import { __ } from "../../../lang/translations";
<h1>{__("auth.login_title")}</h1>;

For comprehensive localization documentation, including how to add new languages and customize translations, see Localization Guide.

Securing Routes

SwiftAuth provides two authentication systems:

Session Authentication (Web):

Route::middleware('SwiftAuth.RequireAuthentication')->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

// With role-based access
Route::middleware([
    'SwiftAuth.RequireAuthentication',
    'SwiftAuth.CanPerformAction:admin-panel',
])->group(function () {
    Route::get('/admin', [AdminController::class, 'index']);
});

API Token Authentication:

Route::middleware('SwiftAuth.AuthenticateWithToken')->group(function () {
    Route::get('/api/posts', [PostController::class, 'index']);
});

// With ability-based access
Route::middleware([
    'SwiftAuth.AuthenticateWithToken',
    'SwiftAuth.CheckTokenAbilities:posts:create',
])->group(function () {
    Route::post('/api/posts', [PostController::class, 'store']);
});

For complete examples, testing strategies, and best practices, see Securing Routes Guide.