feat: change password while signed in

[stsepelin]

POST /auth/password — the counterpart to password reset, without the email round-trip. Re-verifies the current password, applies Password::defaults() to the new one, revokes every other session, fires Events\PasswordChanged.

Closes the first Fortify-parity item on the roadmap.

Why it asks for the current password

This is the whole security story, and it's worth being explicit about: a stolen access token must not be enough to take an account over permanently.

An attacker with a token already has the account until it expires. If that token could also change the password, they'd have it forever — and the owner would be locked out of their own recovery flow. Requiring the existing secret means the token alone isn't enough.

One budget, not two

Because it verifies the same secret as login and step-up, it runs on the same throttle (lukk-confirm) and the same confirm lockout counter — not a second set. Two independent allowances for guessing one password is just a larger allowance.

A success clears the counter (those failures were against a password that no longer exists), and the attempt is reserved before the credential check, like every other password path, so concurrency can't overrun the cap.

Which session survives

Every other session is revoked; the one it was done from lives. Changing a password is what someone does when they suspect another party is in the account, so leaving those alive defeats the point — but logging the user out of the tab they just used is a bad answer to a good instinct.

The session to keep is read from the caller's own verified token, not the request body, so it can't be aimed at someone else's session to spare it from the sweep. Revocation denylists before revoking, so the other sessions' access tokens die immediately rather than at TTL.

Details worth flagging

• The new password must differ from the current one — a no-op would report success for a change that didn't happen, having revoked every other session for nothing.
• On by default (features.change_password), like logout_all: needs no configuration, and refusing a signed-in user the ability to change their own password isn't a sensible default. Off is a real configuration for apps whose passwords live in an identity provider.
• Testing "off" needed a new harness: routes register during boot, so a config() call inside a test is too late to un-register one. tests/DisabledFeatureTestCase boots with flags forced off, and lives in tests/Isolated because Pest binds tests/Feature to the default TestCase.
• lukk-nuxt has no composable for this yet — the docs show the useLukkFetch call to use meanwhile.

Verification

341 passed (897 assertions), 100% coverage, Pint clean. Docs in stsepelin/lukk-docs#9.

Greptile Summary

The PR adds an authenticated password-change endpoint that verifies the current password, applies the default password policy, shares confirmation throttling and lockout state, and revokes other token families.

• Adds the ChangePassword action, request validation, event, controller, route, feature flag, and service binding.
• Adds coverage for authentication, validation, throttling, lockout handling, session revocation, event dispatch, and feature disabling.
• Documents the new default-enabled route and upgrade considerations.

Confidence Score: 4/5

The PR appears safe to merge, with a non-blocking response-customization inconsistency in the new controller.

The password-change behavior is comprehensively implemented and tested, but its success response is hard-coded instead of using the package's required response-contract extension point.

Files Needing Attention: src/Http/Controllers/PasswordController.php

Important Files Changed

Filename	Overview
src/Actions/ChangePassword.php	Implements current-password verification, lockout accounting, password persistence, other-session revocation, and event dispatch.
src/Http/Controllers/PasswordController.php	Extracts the caller's token-family claim and invokes the action, but bypasses the repository's configurable response-contract convention.
src/Http/Requests/ChangePasswordRequest.php	Applies confirmation, difference, length, and default password-policy validation.
src/routes/api.php	Registers the feature-gated authenticated endpoint on the shared confirmation throttle.
tests/Feature/ChangePasswordTest.php	Covers the primary password-change, security, lockout, throttling, revocation, and event behaviors.
tests/DisabledFeatureTestCase.php	Provides a pre-boot feature-disabling harness for route-registration tests.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Guard
    participant Controller
    participant Action
    participant Provider as UserProvider
    participant Sessions as SessionRepository

    Client->>Guard: POST /auth/password + bearer token
    Guard->>Controller: Authenticated request
    Controller->>Controller: Verify token and read family ID
    Controller->>Action: User, current password, new password, family ID
    Action->>Provider: Validate current credentials
    Provider-->>Action: Valid
    Action->>Action: Hash and persist new password
    Action->>Sessions: Revoke all other token families
    Action-->>Controller: Dispatch PasswordChanged
    Controller-->>Client: password-changed

Loading

Prompt To Fix All With AI

### Issue 1
src/Http/Controllers/PasswordController.php:39
**Hard-coded success response**

This controller constructs a raw `JsonResponse` instead of returning a response contract, preventing consumers from customizing the new endpoint's successful response through the package's established extension seam.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "feat: change password while signed in" | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

Context used:

• Context used - CLAUDE.md (source)