README

Passwordless Log-In Links for Laravel

This package provides full-featured passwordless log-in links for Laravel applications.

✅ Rate limited
✅ Invalidated after first use
✅ Locked to the user's session
✅ Configurable expiration
✅ Detailed error messages
✅ Customizable mail template
✅ Auditable logs

Installation

1. Install the package via composer

composer require benbjurstrom/plink

2. Add the package's interface and trait to your Authenticatable model

// app/Models/User.php
namespace App\Models;

//...
use BenBjurstrom\Plink\Models\Concerns\HasPlinks;
use BenBjurstrom\Plink\Models\Concerns\Plinkable;

class User extends Authenticatable implements Plinkable
{
    use HasFactory, Notifiable, HasPlinks;
    
    // ...
}

3. Publish and run the migrations

php artisan vendor:publish --tag="plink-migrations"
php artisan migrate

4. Add the package provided routes

// routes/web.php
Route::plinkRoutes();

5. (Optional) Publish the views for custom styling

php artisan vendor:publish --tag="plink-views"

This package publishes the following views:

resources/
└── views/
    └── vendor/
        └── plink/
            ├── error.blade.php
            ├── components/
                └── template.blade.php
            └── mail/
                ├── notification.blade.php
                └── plink.blade.php

6. (Optional) Publish the config file

php artisan vendor:publish --tag="plink-config"

This is the contents of the published config file:

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | Link Expiration and Throttling
    |--------------------------------------------------------------------------
    |
    | These settings control the security aspects of the generated links,
    | including their expiration time and the throttling mechanism to prevent
    | abuse.
    |
    */

    'expiration' => 5, // Minutes

    'limits' => [
        ['limit' => 1, 'minutes' => 1],
        ['limit' => 3, 'minutes' => 5],
        ['limit' => 5, 'minutes' => 30],
    ],

    /*
    |--------------------------------------------------------------------------
    | Model Configuration
    |--------------------------------------------------------------------------
    |
    | This setting determines the model used by Plink to store and retrieve
    | one-time passwords. By default, it uses the 'App\Models\User' model.
    |
    */

    'models' => [
        'authenticatable' => env('AUTH_MODEL', App\Models\User::class),
    ],

    /*
    |--------------------------------------------------------------------------
    | Mailable Configuration
    |--------------------------------------------------------------------------
    |
    | This setting determines the Mailable class used by Plink to send emails.
    | Change this to your own Mailable class if you want to customize the email
    | sending behavior.
    |
    */

    'mailable' => BenBjurstrom\Plink\Mail\PlinkMail::class,

    /*
    |--------------------------------------------------------------------------
    | Template Configuration
    |--------------------------------------------------------------------------
    |
    | This setting determines the email template used by Plink to send emails.
    | Switch to 'plink::mail.notification' if you prefer to use the default 
    | Laravel notification template.
    |
    */

    'template' => 'plink::mail.plink',
    // 'template' => 'plink::mail.notification',
];

Usage

Laravel Breeze Livewire Example

Replace the Breeze provided App\Livewire\Forms\LoginForm::authenticate method with a sendEmail method that runs the SendPlink action. Also be sure to remove password from the LoginForm's properties.

    // app/Livewire/Forms/LoginForm.php

    use BenBjurstrom\Plink\Actions\SendPlink;
    use BenBjurstrom\Plink\Exceptions\PlinkThrottleException;
    use BenBjurstrom\Plink\Models\Plink;
    //...

    #[Validate('required|string|email')]
    public string $email = '';

    #[Validate('boolean')]
    public bool $remember = false;
    //...

    public function sendEmail(): void
    {
        $this->validate();

        $this->ensureIsNotRateLimited();
        RateLimiter::hit($this->throttleKey(), 300);

        try {
            (new SendPlink)->handle($this->email, $this->remember);
        } catch (PlinkThrottleException $e) {
            throw ValidationException::withMessages([
                'form.email' => $e->getMessage(),
            ]);
        }

        RateLimiter::clear($this->throttleKey());
    }

Update resources/views/livewire/pages/auth/login.blade.php such that the login function calls our new sendEmail method and redirects back with a status confirmation. You can also remove the password input field in this same file.

    public function login(): void
    {
        $this->validate();

        $this->form->sendEmail();

        redirect()->back()->with(['status' => 'Login link sent!']);
    }

Laravel Breeze Inertia Example

Replace the Breeze provided App\Http\Requests\Auth\LoginRequest::authenticate method with a sendEmail method that runs the SendPlink action. Also be sure to remove password from the rules array.

    // app/Http/Requests/Auth/LoginRequest.php

    use BenBjurstrom\Plink\Actions\SendPlink;
    use BenBjurstrom\Plink\Exceptions\PlinkThrottleException;
    use BenBjurstrom\Plink\Models\Plink;
    //...
    
    public function rules(): array
    {
        return [
            'email' => ['required', 'string', 'email']
        ];
    }
    //...
    
    public function sendEmail(): Void
    {
        $this->ensureIsNotRateLimited();
        RateLimiter::hit($this->throttleKey(), 300);

        try {
            (new SendPlink)->handle($this->email, $this->remember);
        } catch (PlinkThrottleException $e) {
            throw ValidationException::withMessages([
                'email' => $e->getMessage(),
            ]);
        }

        RateLimiter::clear($this->throttleKey());
    }

Update the App\Http\Controllers\Auth\AuthenticatedSessionController::store method to call our new sendEmail method and redirect back with a status confirmation.

    // app/Http/Controllers/Auth/AuthenticatedSessionController.php

    public function store(LoginRequest $request): RedirectResponse
    {
        $request->sendEmail();

        return back()->with(['status' => 'Login link sent!']);
    }

Remove the password input field from the resources/js/Pages/Auth/Login.vue file.

Everything else is handled by the package components.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

benbjurstrom / plink

Maintainers

Details