# Mandatory Password Change - Quick Reference

## For Clients

### First Login Process
1. **Receive credentials**: Email and IC number (used as temporary password)
2. **Login**: Visit `/client/login` and enter email + IC number
3. **Redirect**: System automatically redirects to password change page
4. **Change Password**: 
   - Enter your IC number (current password)
   - Enter new strong password
   - Confirm new password
   - Click "Change Password"
5. **Access Portal**: After successful change, redirected to dashboard

### Password Requirements
- Minimum 8 characters
- At least one UPPERCASE letter
- At least one lowercase letter
- At least one number
- Example: `MyPass123` ✅ | `password123` ❌ | `MyPassword` ❌

### After First Login
- Can change password anytime via `/client/change-password`
- No forced redirects after first change
- Password change is optional on subsequent logins

---

## For Administrators/Staff

### Client Setup Process
1. Create new client in agent/staff/lawyer portal
2. Client receives email with temporary login credentials
3. First login uses IC number as password
4. Client **must** change password before accessing portal

### Checking Password Change Status
```sql
-- Find clients who haven't changed password yet (first-time users)
SELECT u.id, u.email, u.password_changed_at 
FROM users u 
WHERE u.role = 'client' AND u.password_changed_at IS NULL;
```

### Resetting a Client's Password
```sql
-- Set password_changed_at to NULL to force password change on next login
UPDATE users SET password_changed_at = NULL WHERE id = [CLIENT_ID];
```

---

## URL Routes

| Route | Method | Purpose |
|-------|--------|---------|
| `/client/change-password` | GET | Show password change form |
| `/client/change-password` | POST | Process password change |

**Access**: Both routes require authentication and `client` role

---

## Troubleshooting for Clients

### "Current password is incorrect"
- Use your IC number as current password on first login
- Example: If IC is `123456789012`, that's your current password

### "Password must contain uppercase letters, lowercase letters, and numbers"
- Your password is too simple
- Examples:
  - ✅ Good: `ClientPass123`, `MyWill2024`, `Safe@Pass99`
  - ❌ Bad: `password`, `PASSWORD`, `123456789`

### "Passwords don't match"
- Confirm password field doesn't match new password
- Retype both carefully

### "Session expired"
- Try logging in again
- If issue persists, clear browser cookies

---

## Technical Details for Developers

### Database Column
```sql
ALTER TABLE users ADD password_changed_at TIMESTAMP NULL AFTER password;
```

### Middleware Check
Location: `app/Http/Middleware/CheckPasswordChanged.php`

The middleware:
- Runs on all client portal routes
- Checks if `password_changed_at` is NULL
- Redirects to change password page if needed
- Shows warning message

### Controller Methods
Location: `app/Http/Controllers/ClientController.php`

**showChangePassword()**: Displays change password form
**updatePassword()**: Processes the password change

### Model Casting
Location: `app/Models/User.php`

```php
'password_changed_at' => 'datetime',  // Auto-casts to Carbon
```

---

## Security Notes

✅ **Passwords are hashed** with bcrypt (never stored in plain text)
✅ **Current password verified** before allowing new password
✅ **Strong requirements enforced** (no weak passwords allowed)
✅ **CSRF protected** (all forms include token)
✅ **Middleware protected** (can't bypass by URL manipulation)
✅ **Error messages generic** (don't reveal if email exists)

---

## Support

For issues:
1. Check browser console for JavaScript errors
2. Check server logs: `storage/logs/laravel.log`
3. Verify email account is receiving credentials
4. Ensure IC number is entered correctly (temporary password)