Document + add config for current_password

Author: dvlpp

demo/app/Sharp/Profile/Commands/ChangePasswordCommand.php

@@ -25,7 +25,7 @@ protected function executeSingle(array $data): array
     {
         // We do not really update the password in the context of the demo
         //        auth()->user()->update([
-        //            'password' => $data['password'],
+        //            'password' => $data['new_password'],
         //        ]);
 
         $this->notify('Password updated!');

docs/guide/authentication.md

@@ -243,7 +243,7 @@ class My2faNotificationHandler extends Sharp2faNotificationHandler // or Sharp2f
 
 ## Forgotten password
 
-You can activate the classic Laravel Breeze workflow of forgotten password with a simple config:
+You can activate the classic Laravel workflow of forgotten password with a simple config:
 
 ```php
 class SharpServiceProvider extends SharpAppServiceProvider
@@ -306,9 +306,62 @@ class SharpServiceProvider extends SharpAppServiceProvider
 
 These customizations will not interfere with any default behavior that you may have implemented for your app, outside Sharp.
 
+## Allow the current user to change his password
+
+Sharp provides a helper trait to quickly build a command that lets the currently authenticated user change his password: `Code16\Sharp\Auth\Password\Command\IsChangePasswordCommandTrait`. Using this trait, you can quickly build a Sharp command, with a few configuration options.
+
+The trat will take care of the form, validation and rate-limiting. Note that:
+
+- This helper is designed for the “current user changes his own password” scenario. If you need admin-managed password resets for other users, implement a different command with the proper authorization checks.
+- Persisting the new password is up to you (see example below).
+
+### Configuration and behavior
+
+You can configure the behavior of the command with the following methods (should be called in your `buildCommandConfig()` method):
+
+- `configureConfirmPassword(?bool $confirm = true)`: enable password confirmation (false by default)
+- `configurePasswordRule(Password $rule)`: change the default password validation rule (default: `Password::min(8)`)
+- `configureValidateCurrentPassword(?bool $validate = true)`: if true, a `password` field that uses Laravel’s `current_password` rule, which compares against the currently authenticated user’s stored password, is added. Make sure your `User` model stores a hashed password as usual. (true by default)
+
+### Example
+
+```php
+use Code16\Sharp\Auth\Password\Command\IsChangePasswordCommandTrait;
+// ...
+
+class ChangePasswordCommand extends SingleInstanceCommand
+{
+    use IsChangePasswordCommandTrait;
+
+    public function buildCommandConfig(): void
+    {
+        $this->configureConfirmPassword()
+            ->configurePasswordRule(
+                Password::min(8)
+                    ->numbers()
+                    ->symbols()
+                    ->uncompromised()
+            );
+    }
+
+    protected function executeSingle(array $data): array
+    {
+        // The trait handles validation and rate limiting.
+    
+        auth()->user()->update([
+            'password' => $data['new_password'], // Considering hashing is done by the model (cast)
+        ]);
+
+        $this->notify('Password updated!');
+
+        return $this->reload();
+    }
+}
+```
+
 ## User impersonation (dev only)
 
-At the development stage, it can be useful to replace the login form by a user impersonation. Sharp allows to do that out of the box:
+At the development stage, it can be useful to replace the login form by a user impersonation. Sharp allows doing that out of the box:
 
 ```php
 class SharpServiceProvider extends SharpAppServiceProvider
@@ -392,3 +445,4 @@ class SharpServiceProvider extends SharpAppServiceProvider
     }
 }
 ```
+

src/Auth/Password/Command/IsChangePasswordCommandTrait.php

@@ -11,6 +11,7 @@
 trait IsChangePasswordCommandTrait
 {
     private bool $confirmPassword = false;
+    private bool $validateCurrentPassword = true;
     private ?Password $passwordRule = null;
 
     public function label(): ?string
@@ -21,10 +22,13 @@ public function label(): ?string
     public function buildFormFields(FieldsContainer $formFields): void
     {
         $formFields
-            ->addField(
-                SharpFormTextField::make('password')
-                    ->setLabel(trans('sharp::auth.password_change.command.fields.current_password'))
-                    ->setInputTypePassword()
+            ->when(
+                $this->validateCurrentPassword,
+                fn (FieldsContainer $formFields) => $formFields->addField(
+                    SharpFormTextField::make('password')
+                        ->setLabel(trans('sharp::auth.password_change.command.fields.current_password'))
+                        ->setInputTypePassword()
+                )
             )
             ->addField(
                 SharpFormTextField::make('new_password')
@@ -47,10 +51,9 @@ public function rules(): array
             'sharp-password-change-'.auth()->id(),
             3,
             fn () => [
-                'password' => [
-                    'required',
-                    'current_password',
-                ],
+                ...$this->validateCurrentPassword
+                    ? ['password' => ['required', 'current_password']]
+                    : [],
                 'new_password' => [
                     'required',
                     'string',
@@ -80,6 +83,13 @@ protected function configureConfirmPassword(?bool $confirmPassword = true): self
         return $this;
     }
 
+    protected function configureValidateCurrentPassword(?bool $validateCurrentPassword = true): self
+    {
+        $this->validateCurrentPassword = $validateCurrentPassword;
+
+        return $this;
+    }
+
     protected function configurePasswordRule(Password $passwordRule): self
     {
         $this->passwordRule = $passwordRule;

tests/Http/Auth/ChangePasswordCommandTraitTest.php

@@ -131,6 +131,54 @@ protected function executeSingle(array $data): array
         ->assertOk();
 });
 
+it('allows to hide the current password field', function () {
+    fakeShowFor(SinglePersonEntity::class, new class() extends SinglePersonShow
+    {
+        public function getInstanceCommands(): ?array
+        {
+            return [
+                'change_password_confirm' => new class() extends SingleInstanceCommand
+                {
+                    use IsChangePasswordCommandTrait;
+
+                    public function buildCommandConfig(): void
+                    {
+                        $this->configureValidateCurrentPassword(false);
+                    }
+
+                    protected function executeSingle(array $data): array
+                    {
+                        return $this->reload();
+                    }
+                },
+            ];
+        }
+    });
+
+    // Form does not contain the current password field
+    $this
+        ->getJson(route('code16.sharp.api.show.command.singleInstance.form', [
+            'entityKey' => 'single-person',
+            'commandKey' => 'change_password_confirm',
+        ]))
+        ->assertOk()
+        ->assertJson(function (Assert $json) {
+            $json
+                ->missing('fields.password')
+                ->where('fields.new_password.key', 'new_password')
+                ->etc();
+        });
+
+    // Succeeds with valid data
+    $this
+        ->postJson(route('code16.sharp.api.show.command.instance', ['single-person', 'change_password_confirm']), [
+            'data' => [
+                'new_password' => 'Password1!',
+            ],
+        ])
+        ->assertOk();
+});
+
 it('rate limits after too many attempts and returns a helpful message', function () {
     fakeShowFor(SinglePersonEntity::class, new class() extends SinglePersonShow
     {