alexeyplodenko / laravel-agent-auth

v1.0.0 2026-09-24 13:29 UTC

Requires

• php: ^8.2
• illuminate/auth: ^11.0|^12.0
• illuminate/console: ^11.0|^12.0
• illuminate/http: ^11.0|^12.0
• illuminate/routing: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0

MIT

• Alexey Plodenko

• laravel
• mcp
• puppeteer
• chrome-devtools
• signed-url
• filament
• filament-admin
• playwright
• filamentphp
• model-context-protocol
• passwordless-login
• ai-agents
• agent-authentication
• temporary-signed-route
• testing-automation

Published on Packagist.org on 2026-09-24 13:31 UTC

README

Laravel Agent Auth provides seamless, passwordless authentication and temporary signed-URL login for AI agents, browser automation tools (Chrome DevTools MCP, Playwright, Cypress, Puppeteer), and local developers.

It includes out-of-the-box automatic detection for Filament Admin Panels (Filament v3, v4, and v5) with zero configuration required.

The Problem It Solves

When an AI coding assistant (like Claude Code, Cursor, or Google Antigravity) uses browser automation tools (such as the Chrome DevTools MCP) to test pages, verify UI, or submit forms, it gets stopped at your authentication barrier (/login or /admin/login).

Manually typing credentials into forms or hardcoding passwords in automation scripts is brittle, slow, and insecure.

Laravel Agent Auth solves this by generating short-lived, cryptographically signed URLs from the Artisan CLI. An agent navigates to the URL once, receives an authenticated session cookie, and is immediately redirected to the target page or Filament dashboard.

Key Features

• ⚡ Instant CLI Login: Run php artisan agent:url and navigate directly into an authenticated session.
• 🎯 First-Class Filament Support: Automatically detects Filament (v3, v4, v5), redirects to the active panel URL, and selects users passing canAccessPanel().
• 🧩 Zero Hard Dependencies: Pure Laravel. Does not require filament/filament as a Composer dependency—works in standard Blade, Inertia, Livewire, and custom dashboards too.
• 🛡️ Production Safe: Active only in local environment by default. Hard-blocked in production unless explicitly opted-in via environment variables.
• 🔒 Cryptographically Signed: Utilizes Laravel's HMAC URL::temporarySignedRoute with configurable expiration (TTL).
• 🤖 Headless & CI/CD Ready: Supports optional high-entropy static tokens for headless testing runners.
• 📊 Security Auditing: Every agent login logs user ID, email, IP address, and auth method to Laravel's logger.

Requirements

• PHP ^8.2
• Laravel Framework ^11.0 or ^12.0
• Optional: Filament ^3.0, ^4.0, or ^5.0

Installation

Install the package via Composer:

composer require alexeyplodenko/laravel-agent-auth

The service provider will automatically register via Laravel's package discovery.

(Optional) Publish the configuration file:

php artisan vendor:publish --tag=agent-auth-config

Usage

1. Generating a Signed Login URL (Artisan CLI)

Generate a 15-minute temporary signed login URL for the default admin/user:

php artisan agent:url

Output:

Temporary Agent Authentication URL generated (valid for 15 minutes):

http://your-app.test/_agent/login?signature=a1b2c3d4e5f6...

Details:
  - User: First available admin/user
  - Redirect: /admin (auto-detected Filament panel)
  - Lifetime: 15 minutes

2. Specifying a User or Target Route

Authenticate as a specific user:

php artisan agent:url --email=[e-mail]

Redirect to a specific page after login:

php artisan agent:url --redirect=/admin/pages/create

Change URL lifetime (in minutes):

php artisan agent:url --ttl=30

Using with Filament Admin Panels

Laravel Agent Auth works with Filament out of the box.

When Filament is detected in your application:

1. Redirect Target: Defaults automatically to your Filament panel URL (e.g. /admin).
2. User Authorization: If your User model implements FilamentUser (or contains a canAccessPanel() method), the resolver will automatically pick the first user in the database authorized to access that panel.

Example in AI Agent Workflows (Chrome DevTools MCP / Playwright)

1. The AI Agent runs:

   php artisan agent:url

2. The agent takes the generated URL and instructs the browser tool:

   {
     "tool": "navigate_page",
     "url": "http://your-app.test/_agent/login?expires=1727187600&signature=..."
   }

3. The browser session is authenticated, session ID is regenerated, and the agent arrives directly on the Filament panel.

Using with Standard Laravel Apps (Blade / Inertia / Livewire)

In applications without Filament, the package defaults to redirecting to / (or whatever URL you specify in config/agent-auth.php or --redirect=). It logs in the first user found in your users table, or the user matching --email.

Headless CI / Static Token Mode

In headless CI/CD environments where generating signed URLs per test is impractical, you can configure a secret static token (minimum 16 characters):

In your .env.testing:

AGENT_AUTH_TOKEN=super-secret-token-min-16-characters

Direct login URL:

http://your-app.test/_agent/login?token=super-secret-token-min-16-characters&redirect=/dashboard

Configuration Reference (config/agent-auth.php)

return [
    // Enable agent authentication (default: true in 'local' environment)
    'enabled' => env('AGENT_AUTH_ENABLED', env('APP_ENV') === 'local'),

    // Hard safeguard preventing execution in production
    'allow_production' => (bool) env('AGENT_AUTH_ALLOW_PRODUCTION', false),

    // URI endpoint for login
    'route' => env('AGENT_AUTH_ROUTE', '/_agent/login'),

    // Optional domain constraint (for multi-tenant/subdomain setups)
    'domain' => env('AGENT_AUTH_DOMAIN', null),

    // Middleware applied (throttled by default)
    'middleware' => ['web', 'throttle:10,1'],

    // Auth guard used to authenticate the user
    'guard' => env('AGENT_AUTH_GUARD', 'web'),

    // Default user email (null = auto-discover first admin/user)
    'user_email' => env('AGENT_AUTH_USER_EMAIL', null),

    // Default redirect URL (null = auto-discover Filament panel or '/')
    'redirect_url' => env('AGENT_AUTH_REDIRECT_URL', null),

    // Default signed URL lifetime in minutes
    'ttl' => (int) env('AGENT_AUTH_TTL', 15),

    // Optional static token for headless CI mode
    'token' => env('AGENT_AUTH_TOKEN', null),
];

Security Considerations

1. Local-Only by Default: The package refuses requests unless APP_ENV=local.
2. Production Killswitch: If app()->isProduction() is true, access throws a 403 Forbidden unless AGENT_AUTH_ALLOW_PRODUCTION=true is explicitly set in .env.
3. HMAC Cryptographic Verification: Signed URLs use Laravel's URL::hasValidSignature(). Modifying the timestamp or parameters invalidates the signature immediately.
4. Session Fixation Protection: Every login executes $request->session()->regenerate().
5. Rate Limiting: Protected by throttle:10,1 middleware to prevent brute-forcing.

Troubleshooting

"Invalid or expired agent authentication credentials (403)"

• Ensure your APP_URL in .env matches the exact host, port, and protocol used in your browser (e.g. http://localhost:8000 vs http://127.0.0.1:8000). Laravel HMAC signatures validate the entire root URL.
• Check if the signed URL has exceeded its TTL (default 15 minutes).

"No suitable user found to authenticate (404)"

• Ensure your database has at least one user seeded (php artisan db:seed).
• If using Filament, ensure at least one user returns true for canAccessPanel().

License

The MIT License (MIT). Please see License File for more information.