feat(auth): password reset, forgot username, and admin user management for local accounts

- Add /forgot-password and /forgot-username page routes and templates
- Update login page label to "Username or Email" (both already accepted by backend)
- Add "Forgot password?" and "Forgot username?" links to login page
- Add POST /api/auth/forgot-username endpoint + send_forgot_username_email() utility
- Add admin endpoints: PATCH /local/{id}, POST /local/{id}/send-password-reset, POST /local/{id}/set-password
- Update admin_users.html with Edit, Password, and Reset action buttons + modals
- Add 23 tests; fix code review issues (import style, display_name clearing behaviour)
- Update docs/API.md and docs/UserGuide.md

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>

app/api/admin_users.py

@@ -15,6 +15,7 @@ from pydantic import BaseModel, Field
 from sqlalchemy import func
 from sqlalchemy.orm import Session
 
+from app.config import settings
 from app.database import get_db
 from app.models import FileRecord, LocalUser, UserProfile
 from app.utils.local_auth import generate_token, hash_password, send_password_reset_email
@@ -393,7 +394,8 @@ def update_local_user(local_user_id: int, body: LocalUserUpdate, db: DbSession,
         user.email = body.email
 
     if body.display_name is not None:
-        user.display_name = body.display_name
+        # Normalise empty string to None so that clearing the field removes the display name
+        user.display_name = body.display_name or None
 
     if body.is_admin is not None:
         user.is_admin = body.is_admin
@@ -431,9 +433,7 @@ def update_local_user(local_user_id: int, body: LocalUserUpdate, db: DbSession,
     status_code=status.HTTP_200_OK,
     summary="Send a password reset email to a local user",
 )
-def admin_send_password_reset(
-    local_user_id: int, request: Request, db: DbSession, _admin: AdminUser
-) -> dict[str, Any]:
+def admin_send_password_reset(local_user_id: int, request: Request, db: DbSession, _admin: AdminUser) -> dict[str, Any]:
     """Generate a password reset token and email the reset link to the local user.
 
     This is a last-resort tool for admins to help users who are locked out.
@@ -443,13 +443,11 @@ def admin_send_password_reset(
     Raises:
         404: Local user not found.
     """
-    from app.config import settings as _settings
-
     user = db.query(LocalUser).filter(LocalUser.id == local_user_id).first()
     if not user:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Local user not found.")
 
-    if not _settings.email_host:
+    if not settings.email_host:
         logger.warning("Admin requested password reset for %s but SMTP is not configured", user.email)
         return {"sent": False, "reason": "SMTP is not configured on this server."}
 
@@ -500,10 +498,10 @@ def admin_set_password(
         db.rollback()
         raise
 
-    logger.info(
-        "[SECURITY] ADMIN_SET_PASSWORD user=%s admin=%s", user.email, _admin.get("email", "unknown")
-    )
+    logger.info("[SECURITY] ADMIN_SET_PASSWORD user=%s admin=%s", user.email, _admin.get("email", "unknown"))
     return {"updated": True, "email": user.email}
+
+
 def get_user(user_id: str, db: DbSession, _admin: AdminUser) -> dict[str, Any]:
     """Return profile and document statistics for a specific user."""
     doc_count = db.query(func.count(FileRecord.id)).filter(FileRecord.owner_id == user_id).scalar() or 0

app/api/local_auth.py

@@ -31,6 +31,7 @@ from app.utils.local_auth import (
     generate_token,
     hash_password,
     is_token_expired,
+    send_forgot_username_email,
     send_password_reset_email,
     send_verification_email,
 )
@@ -79,6 +80,12 @@ class PasswordResetBody(BaseModel):
     new_password_confirm: str
 
 
+class ForgotUsernameBody(BaseModel):
+    """Body for the forgot-username endpoint."""
+
+    email: str
+
+
 # ---------------------------------------------------------------------------
 # Page routes (return HTML)
 # ---------------------------------------------------------------------------
@@ -107,6 +114,19 @@ async def verify_email_sent_page(request: Request) -> Any:
     return templates.TemplateResponse("verify_email_sent.html", {"request": request})
 
 
+@router.get("/forgot-username", include_in_schema=False)
+async def forgot_username_page(request: Request) -> Any:
+    """Render the forgot-username page where users can request a username reminder email."""
+    return templates.TemplateResponse(
+        "forgot_username.html",
+        {
+            "request": request,
+            "csrf_token": getattr(request.state, "csrf_token", ""),
+            "app_version": settings.version,
+        },
+    )
+
+
 @router.get("/forgot-password", include_in_schema=False)
 async def forgot_password_page(request: Request) -> Any:
     """Render the forgot-password page where users can request a reset email."""
@@ -350,3 +370,19 @@ async def reset_password(body: PasswordResetBody, db: DbSession) -> dict[str, st
 
     logger.info("[SECURITY] PASSWORD_RESET_SUCCESS user=%s", user.email)
     return {"message": "Password updated successfully."}
+
+
+@router.post("/api/auth/forgot-username")
+async def forgot_username(body: ForgotUsernameBody, db: DbSession) -> dict[str, str]:
+    """Send a username reminder email.
+
+    Always returns 200 to avoid leaking whether an email is registered.
+    """
+    user = db.query(LocalUser).filter(LocalUser.email == body.email).first()
+    if user:
+        try:
+            send_forgot_username_email(user.email, user.username)
+        except Exception as exc:
+            logger.warning("Failed to send forgot-username email to %s: %s", user.email, exc)
+
+    return {"message": "Username reminder sent if account exists."}