# Plan: Admin API Endpoint — Reset User Password

## Context
hiveops-auth has no password reset functionality. The login page has a dead "Forgot Password" link. The admin role and `/auth/api/admin/**` route prefix already exist. Adding an admin password reset endpoint gives operators a way to reset user passwords without direct DB access. The `PASSWORD_CHANGED` audit event type and `logPasswordChanged()` method are already defined but never called.

## Files to Create / Modify

| Action | File |
|--------|------|
| **CREATE** | `src/main/java/com/hiveops/auth/dto/request/AdminPasswordResetRequest.java` |
| **MODIFY** | `src/main/java/com/hiveops/auth/service/AuthService.java` |
| **CREATE** | `src/main/java/com/hiveops/auth/controller/UserAdminController.java` |

## Implementation Steps

### 1. DTO — `AdminPasswordResetRequest.java`
- Single field: `newPassword` (String)
- Jakarta validation: `@NotBlank`, `@Size(min=12)` — mirrors the existing `RegisterRequest` pattern
- Package: `com.hiveops.auth.dto.request`

### 2. AuthService — `resetUserPassword(String email, String newPassword)`
- Lookup user with `userRepository.findByEmail(email)` → throw `UsernameNotFoundException` (Spring Security) if absent (already handled by `GlobalExceptionHandler` returning 404-ish; check and use an appropriate existing exception or plain `RuntimeException`)
- Validate password strength via `PasswordValidator.validatePassword(newPassword)` — throw `IllegalArgumentException` with the error message if invalid
- Encode: `passwordEncoder.encode(newPassword)` → `user.setPasswordHash(...)`
- Side effects for security:
  - `user.resetFailedLoginAttempts()` — clears lock + counter
  - Revoke all existing refresh tokens via `refreshTokenRepository.revokeAllByUser(user)` (already exists — sets `revoked=true`, preserving audit history)
- `userRepository.save(user)`
- `authAuditService.logPasswordChanged(user)` — already implemented, just unused

### 3. Controller — `UserAdminController.java`
- Pattern mirrors `RateLimitAdminController` exactly:
  - `@RestController`, `@RequestMapping("/auth/api/admin/users")`, `@RequiredArgsConstructor`, `@Slf4j`
  - `@Tag(name = "User Admin", description = "User management (Admin only)")`
  - All endpoints: `@PreAuthorize("hasRole('ADMIN')")`
- Single endpoint for now:
  ```
  POST /auth/api/admin/users/{email}/reset-password
  Body: { "newPassword": "..." }
  Response 200: { "message": "Password reset successfully", "email": "..." }
  Response 404: { "message": "User not found", "email": "..." }
  Response 400: { "message": "<validation error>", "email": "..." }
  ```
- Log at INFO level: `"Admin password reset for user: {}"` (email only, never the password)

## Key Reused Components
- `PasswordEncoder` bean (BCrypt strength 12) — injected into `AuthService`
- `PasswordValidator.validatePassword()` — `util/PasswordValidator.java`
- `authAuditService.logPasswordChanged(user)` — `service/AuthAuditService.java`
- `userRepository.findByEmail()` — `repository/UserRepository.java`
- `refreshTokenRepository.revokeAllByUser(user)` — `repository/RefreshTokenRepository.java`
- `user.resetFailedLoginAttempts()` — `entity/User.java`
- `@PreAuthorize("hasRole('ADMIN')")` pattern — `RateLimitAdminController.java`

## Verification
1. Build: `./mvnw compile` — must be clean
2. Start service (dev profile, H2 in-memory)
3. Register a test user, obtain an admin JWT
4. `POST /auth/api/admin/users/{email}/reset-password` with valid new password → 200
5. `POST /auth/api/login` with old password → 401
6. `POST /auth/api/login` with new password → 200
7. Attempt same endpoint without ADMIN role → 403
8. Attempt with unknown email → 404
9. Attempt with weak password (< 12 chars) → 400
10. Check audit log table for `PASSWORD_CHANGED` event