PR: Add Admin Password Reset Tool & Overhaul Auth Error UX

[DJJones66]

PR: Add Admin Password Reset Tool & Overhaul Auth Error UX

Summary

This PR introduces a secure admin-side password reset script and significantly improves the frontend authentication experience with accessible form fields, structured error handling, and real-time validation. It also adds unit/integration tests and small service-level safeguards to prevent retry loops. The net effect is safer user management, clearer feedback, and more accessible forms—without changing API contracts.

---

Problem / Motivation

• No safe password reset flow: admins lacked a supported method to reset user passwords outside of DB edits.
• Unclear/missing feedback: login/registration failures surfaced as vague alerts or nothing at all.
• Accessibility gaps: form fields lacked ARIA bindings; errors weren’t exposed correctly to screen readers.
• Operational friction: weak/mismatched passwords weren’t validated client-side, leading to repeated server trips.
• Retry loop risk: login/register requests could trigger token refresh attempts, producing noisy failures.

---

What’s Changed

1) Backend: New Admin Reset Script

• backend/scripts/reset_password.py

  • Async DB init/cleanup.
  • Lookup by email (username hook stubbed).
  • Password strength validation + double-entry confirmation.
  • Secure hashing (hash_password) and DB save.
  • Audit logging to backend/logs/password_reset_audit.log with timestamp, user, success flag.
  • CLI UX with examples and exit codes.

---

2) Frontend – New Components

• AccessibleFormField.tsx

  • ARIA-correct wrapper around MUI TextField.
  • Custom help/error rendering with consistent spacing.

• EnhancedErrorDisplay.tsx

  • Severity-aware alerts (network/validation/server).
  • Optional “Need help?” expandable suggestions.
  • Actionable CTAs (e.g., “Create Account”).
  • Persists briefly to avoid flicker.

• PasswordStrengthIndicator.tsx

  • Progress bar + criteria checklist (length, case, numbers, special chars).
  • Compact/detail modes based on focus.

---

3) Frontend – Login / Registration Flows

• Login.tsx

  • Integrated new components.
  • Real-time validation for email/username/password/confirm.
  • Uses centralized authErrorHandler for structured error messages.
  • Preserves legacy error fallback for compatibility.
  • Smarter tab-switch clearing (resets validation state).

• utils/authErrorHandler.ts (new)

  • Maps API/Network errors → user-friendly messages.
  • Validation helpers: email, username, password (+ confirmation).

---

4) Services

• ApiService.ts

  • Skips token refresh retry for /auth/login and /auth/register requests.

---

5) Tests

• Login.integration.test.tsx

  • Covers 401/404/network errors, CTA actions, suggestions, no-flicker behavior, validation, and strength meter.

• authErrorHandler.test.ts

  • Unit tests for error mapping and all validation utilities.

---

User-Visible Behavior

• Admins can run a secure password reset script with strength checks + logging.

• End users see:

  • Clear, actionable login/registration errors.
  • Inline validation + password strength indicator.
  • Consistent helper/error messages with screen reader support.

• No API contract changes; only frontend UX is improved.

---

Configuration & Ops Notes

• Audit log is written to backend/logs/password_reset_audit.log.

  • Contains timestamp, user id, username, email, success flag.
  • ⚠️ Confirm retention/rotation policy for PII.

Example password reset usage:

python backend/scripts/reset_password.py --username user@example.com

---

Backward Compatibility

• ✅ No schema changes.
• ✅ No API contract changes.
• ✅ Legacy error handling preserved; new enhanced path layered on top.

---

TL;DR: This PR empowers admins with a safe reset tool and gives users a vastly improved login/registration experience: accessible forms, richer error feedback, real-time validation, and a password strength meter—without touching API contracts or DB schema.