laravel-auth

Overview

The laravel-auth agent specializes in authentication and authorization setup. It configures Laravel's built-in auth, Sanctum for APIs, creates policies for model authorization, and implements role-based access control systems.

Responsibilities

Authentication Setup - Session-based, token-based, or social login
Policy Creation - Model-specific authorization policies
Gate Definition - Application-wide ability checks
Sanctum Configuration - SPA authentication and API tokens
Role/Permission System - With Spatie or custom implementation
Multi-tenancy - Tenant isolation and scoping

What It Creates

Component	Location	Purpose
Policies	`app/Policies/`	Model authorization rules
Gates	`AuthServiceProvider`	Application-wide abilities
Middleware	`app/Http/Middleware/`	Role/permission checks
Migrations	`database/migrations/`	Roles/permissions tables

Generated Policy Example

<?php

namespace App\Policies;

use App\Models\Post;
use App\Models\User;

class PostPolicy
{
    /**
     * Runs before all other checks.
     */
    public function before(User $user, string $ability): ?bool
    {
        if ($user->hasRole('admin')) {
            return true; // Admins bypass all checks
        }

        return null; // Continue to specific check
    }

    public function viewAny(User $user): bool
    {
        return true; // Anyone can list posts
    }

    public function view(User $user, Post $post): bool
    {
        return $post->published_at !== null
            || $user->id === $post->user_id;
    }

    public function create(User $user): bool
    {
        return $user->hasPermission('posts.create');
    }

    public function update(User $user, Post $post): bool
    {
        return $user->id === $post->user_id
            || $user->hasPermission('posts.edit-any');
    }

    public function delete(User $user, Post $post): bool
    {
        return $user->id === $post->user_id
            && $post->comments()->count() === 0;
    }
}

Sanctum API Setup

// Creating tokens with abilities
$token = $user->createToken('api-token', [
    'posts:read',
    'posts:write',
    'comments:read',
]);

// Protecting routes
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', fn () => auth()->user());

    Route::apiResource('posts', PostController::class)
        ->middleware('abilities:posts:read,posts:write');
});

// Checking token abilities in controller
public function store(Request $request)
{
    if (!$request->user()->tokenCan('posts:write')) {
        abort(403, 'Token missing posts:write ability');
    }

    return Post::create($request->validated());
}

Role-Based Middleware

// app/Http/Middleware/EnsureUserHasRole.php
class EnsureUserHasRole
{
    public function handle(Request $request, Closure $next, string ...$roles)
    {
        if (!$request->user()?->hasAnyRole($roles)) {
            abort(403, 'Unauthorized action.');
        }

        return $next($request);
    }
}

// Usage in routes
Route::middleware(['auth', 'role:admin,editor'])->group(function () {
    Route::resource('posts', PostController::class);
});

// Usage in controller constructor
public function __construct()
{
    $this->middleware('permission:posts.create')->only(['create', 'store']);
    $this->middleware('permission:posts.delete')->only('destroy');
}

Gate Registration

// In AuthServiceProvider boot()
Gate::define('access-admin', function (User $user) {
    return $user->hasRole(['admin', 'super-admin']);
});

Gate::define('moderate-content', function (User $user) {
    return $user->hasAnyPermission(['moderate', 'admin']);
});

// Usage
if (Gate::allows('access-admin')) {
    // Show admin link
}

@can('moderate-content')
    Moderate
@endcan

Invoked By Commands

/laravel-agent:auth:setup - Setup authentication system

Package Integration

Integrates with authentication packages:

laravel/sanctum - SPA authentication and API tokens
laravel/passport - OAuth2 server implementation
spatie/laravel-permission - Role and permission management
laravel/socialite - Social login providers

Guardrails

The auth agent follows strict rules:

ALWAYS use policies for model authorization
ALWAYS rate limit authentication endpoints
ALWAYS regenerate session after login
NEVER expose user IDs in tokens without scoping
NEVER store passwords in plain text