feat(users): add email change verification flow

Introduces a verified email change workflow for users. New email is
stored as pending until confirmed via signed link, with cancel support
and panel-aware notifications for both old and new addresses.

- Domain actions: InitiateEmailChange, ConfirmEmailChange, CancelEmailChange
- Events + notifications for initiated/confirmed/cancelled states
- Filament pages for confirm/cancel and EditProfile integration
- Migrations adding pending_email columns
- UpgradeCommand for both packages

Author: mhortulanus

README.md

@@ -201,6 +201,96 @@ Contributions are welcome! Please follow the PSR-12 coding standard and submit p
 
 ---
 
+## ✉️ Email change with confirmation
+
+This package ships the building blocks for a confirmed email-change flow:
+actions, events and notifications. **Routing, URL generation and the
+listener that sends the mail are intentionally left to your application** —
+this keeps the package framework-agnostic and lets you decide where the
+confirmation link points.
+
+### What's included
+
+- Migration: `pending_email`, `pending_email_token`, `pending_email_token_expires_at`, `pending_email_requested_at`.
+- Actions:
+    - `Backstage\Laravel\Users\Domain\Email\Actions\InitiateEmailChange`
+    - `Backstage\Laravel\Users\Domain\Email\Actions\ConfirmEmailChange`
+    - `Backstage\Laravel\Users\Domain\Email\Actions\CancelEmailChange`
+- Events: `EmailChangeInitiated`, `EmailChangeConfirmed`, `EmailChangeCancelled` (under `Backstage\Laravel\Users\Events\Email\`).
+- Notifications (URL is supplied via constructor): `Backstage\Laravel\Users\Notifications\Email\ConfirmEmailChange`, `Backstage\Laravel\Users\Notifications\Email\EmailChangeRequested`.
+- Config block `users.email_change.*` for token lifetime, cooldown and old-address notification.
+
+### Minimal setup in your application
+
+```php
+// app/Providers/AppServiceProvider.php
+use Backstage\Laravel\Users\Events\Email\EmailChangeInitiated;
+use Backstage\Laravel\Users\Notifications\Email\ConfirmEmailChange;
+use Backstage\Laravel\Users\Notifications\Email\EmailChangeRequested;
+use Illuminate\Support\Facades\Event;
+use Illuminate\Support\Facades\Notification;
+use Illuminate\Support\Facades\URL;
+
+public function boot(): void
+{
+    Event::listen(function (EmailChangeInitiated $event) {
+        $confirmUrl = URL::temporarySignedRoute(
+            'email.confirm',
+            now()->addMinutes($event->expiresInMinutes),
+            ['user' => $event->user->id, 'token' => $event->rawToken],
+        );
+
+        Notification::route('mail', $event->user->pending_email)
+            ->notify(new ConfirmEmailChange($event->newEmail, $confirmUrl));
+
+        if (config('users.email_change.notify_old_address')) {
+            $cancelUrl = URL::temporarySignedRoute(
+                'email.cancel',
+                now()->addMinutes($event->expiresInMinutes),
+                ['user' => $event->user->id, 'token' => $event->rawToken],
+            );
+
+            $event->user->notify(new EmailChangeRequested($event->newEmail, $cancelUrl));
+        }
+    });
+}
+```
+
+```php
+// routes/web.php
+use Backstage\Laravel\Users\Domain\Email\Actions\CancelEmailChange;
+use Backstage\Laravel\Users\Domain\Email\Actions\ConfirmEmailChange;
+use Backstage\Laravel\Users\Eloquent\Models\User;
+
+Route::middleware('signed')->group(function () {
+    Route::get('/email/confirm/{user}/{token}', function (User $user, string $token) {
+        ConfirmEmailChange::run($user, $token);
+
+        return redirect('/');
+    })->name('email.confirm');
+
+    Route::get('/email/cancel/{user}/{token}', function (User $user, string $token) {
+        CancelEmailChange::run($user, $token);
+
+        return redirect('/');
+    })->name('email.cancel');
+});
+```
+
+```php
+// trigger from your controller / Filament page / Livewire component
+use Backstage\Laravel\Users\Domain\Email\Actions\InitiateEmailChange;
+
+InitiateEmailChange::run($user, $request->input('email'));
+```
+
+The `?string $source` parameter on `InitiateEmailChange` is opaque to this
+package; pass any identifier you need on the receiving end (panel ID, tenant
+slug, channel, …). Listeners can branch on `$event->source` to decide which
+URL to build.
+
+---
+
 ## 📄 License
 
 This package is open-sourced software licensed under the [MIT license](LICENSE.md).

config/users.php

@@ -50,4 +50,22 @@
             'special_chars' => '!@#$%^&*()_+-=[]{}|;:,.<>?',
         ],
     ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Email change
+    |--------------------------------------------------------------------------
+    |
+    | This package only ships the building blocks (actions, events,
+    | notifications). Consumers must wire their own routes, controllers and
+    | a listener for `EmailChangeInitiated` that builds the confirmation URL
+    | and dispatches the notification. See the README for a minimal example.
+    |
+    */
+    'email_change' => [
+        'enabled' => true,
+        'token_lifetime_minutes' => 60 * 24,
+        'notify_old_address' => true,
+        'cooldown_minutes' => 5,
+    ],
 ];

database/migrations/8_add_pending_email_to_users_table.php.stub

@@ -0,0 +1,34 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table(config('users.eloquent.user.table', 'users'), function (Blueprint $table) {
+            $table->string('pending_email')->nullable()->after('email');
+            $table->string('pending_email_token')->nullable()->after('pending_email');
+            $table->timestamp('pending_email_token_expires_at')->nullable()->after('pending_email_token');
+            $table->timestamp('pending_email_requested_at')->nullable()->after('pending_email_token_expires_at');
+
+            $table->index('pending_email_token');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table(config('users.eloquent.user.table', 'users'), function (Blueprint $table) {
+            $table->dropIndex([config('users.eloquent.user.table', 'users').'_pending_email_token_index']);
+
+            $table->dropColumn([
+                'pending_email',
+                'pending_email_token',
+                'pending_email_token_expires_at',
+                'pending_email_requested_at',
+            ]);
+        });
+    }
+};

src/Console/Commands/UpgradeCommand.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace Backstage\Laravel\Users\Console\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Schema;
+
+use function Laravel\Prompts\confirm;
+use function Laravel\Prompts\info;
+use function Laravel\Prompts\note;
+use function Laravel\Prompts\warning;
+
+class UpgradeCommand extends Command
+{
+    protected $signature = 'users:upgrade
+        {--force : Skip confirmation prompts}
+        {--no-migrate : Skip running migrations}';
+
+    protected $description = 'Upgrade backstage/laravel-users: publish config and run pending migrations.';
+
+    public function handle(): int
+    {
+        info('Upgrading backstage/laravel-users…');
+
+        if (! $this->option('force') && ! confirm(
+            label: 'This will publish the package config (if missing) and run pending migrations. Continue?',
+            default: true,
+        )) {
+            warning('Upgrade cancelled.');
+
+            return self::SUCCESS;
+        }
+
+        $this->publishConfig();
+
+        if (! $this->option('no-migrate')) {
+            $this->runMigrations();
+        }
+
+        $this->reportEmailChangeFeature();
+
+        info('backstage/laravel-users is up to date.');
+
+        return self::SUCCESS;
+    }
+
+    protected function publishConfig(): void
+    {
+        if (file_exists(config_path('users.php'))) {
+            note('Config already published at config/users.php — skipping.');
+
+            return;
+        }
+
+        $this->call('vendor:publish', [
+            '--provider' => 'Backstage\Laravel\Users\LaravelUsersServiceProvider',
+            '--tag' => 'config',
+            '--force' => false,
+        ]);
+    }
+
+    protected function runMigrations(): void
+    {
+        $this->call('migrate', [
+            '--force' => true,
+        ]);
+    }
+
+    protected function reportEmailChangeFeature(): void
+    {
+        $usersTable = config('users.eloquent.user.table', 'users');
+
+        $hasPendingEmail = Schema::hasColumn($usersTable, 'pending_email');
+
+        if (! $hasPendingEmail) {
+            warning(__('Email-change columns are missing on the :table table. Run migrations to enable the feature.', ['table' => $usersTable]));
+
+            return;
+        }
+
+        info(__('Email-change toolkit is ready.'));
+
+        if (config('users.email_change.enabled', true)) {
+            note(__('Reminder: backstage/laravel-users does not register a listener for EmailChangeInitiated by default. If you are not using backstage/users, wire your own listener that builds the confirmation URL and dispatches the notification (see the package README).'));
+        }
+    }
+}

src/Domain/Email/Actions/CancelEmailChange.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Backstage\Laravel\Users\Domain\Email\Actions;
+
+use Backstage\Laravel\Users\Domain\Email\Exceptions\EmailChangeException;
+use Backstage\Laravel\Users\Eloquent\Models\User;
+use Backstage\Laravel\Users\Events\Email\EmailChangeCancelled;
+use Lorisleiva\Actions\Concerns\AsAction;
+
+class CancelEmailChange
+{
+    use AsAction;
+
+    public function handle(User $user, string $rawToken): void
+    {
+        if ($user->pending_email === null || $user->pending_email_token === null) {
+            throw EmailChangeException::noPendingChange();
+        }
+
+        if (! hash_equals((string) $user->pending_email_token, hash('sha256', $rawToken))) {
+            throw EmailChangeException::tokenInvalid();
+        }
+
+        $abandonedEmail = (string) $user->pending_email;
+
+        $user->forceFill([
+            'pending_email' => null,
+            'pending_email_token' => null,
+            'pending_email_token_expires_at' => null,
+            'pending_email_requested_at' => null,
+        ])->save();
+
+        EmailChangeCancelled::dispatch($user->fresh(), $abandonedEmail);
+    }
+}

src/Domain/Email/Actions/ConfirmEmailChange.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace Backstage\Laravel\Users\Domain\Email\Actions;
+
+use Backstage\Laravel\Users\Domain\Email\Exceptions\EmailChangeException;
+use Backstage\Laravel\Users\Eloquent\Models\User;
+use Backstage\Laravel\Users\Events\Email\EmailChangeConfirmed;
+use Illuminate\Support\Facades\DB;
+use Lorisleiva\Actions\Concerns\AsAction;
+
+class ConfirmEmailChange
+{
+    use AsAction;
+
+    public function handle(User $user, string $rawToken): User
+    {
+        if ($user->pending_email === null || $user->pending_email_token === null) {
+            throw EmailChangeException::noPendingChange();
+        }
+
+        if (! hash_equals((string) $user->pending_email_token, hash('sha256', $rawToken))) {
+            throw EmailChangeException::tokenInvalid();
+        }
+
+        if ($user->pending_email_token_expires_at !== null && $user->pending_email_token_expires_at->isPast()) {
+            throw EmailChangeException::tokenExpired();
+        }
+
+        $oldEmail = (string) $user->email;
+        $newEmail = (string) $user->pending_email;
+
+        DB::transaction(function () use ($user, $newEmail) {
+            $userClass = config('auth.providers.users.model', User::class);
+
+            $taken = $userClass::query()
+                ->where('id', '!=', $user->getKey())
+                ->whereRaw('LOWER(email) = ?', [mb_strtolower($newEmail)])
+                ->exists();
+
+            if ($taken) {
+                throw EmailChangeException::alreadyTaken();
+            }
+
+            $user->forceFill([
+                'email' => $newEmail,
+                'email_verified_at' => now(),
+                'pending_email' => null,
+                'pending_email_token' => null,
+                'pending_email_token_expires_at' => null,
+                'pending_email_requested_at' => null,
+            ])->save();
+        });
+
+        EmailChangeConfirmed::dispatch($user->fresh(), $oldEmail);
+
+        return $user;
+    }
+}