Feat/account management (#41)

* added unit tests for account management endpoints.

* added account management endpoints (password change, profile update, account deletion).

* added param/return docstrings to all auth endpoints.

* added Pydantic models for logout, change_password, and delete_account endpoints.

* improved error handling for account management endpoints.

* simplified unit test imports.

* update min password verification length to 8 chars to match front-end Signup.js expectation.

* updated delete endpoint to include deleting PhD Canvases.

* updated delete_account docstring to note PhD Canvases also deleted.

* fix incorrect naming case

Co-authored-by: Daniel McKnight <34697904+NeonDaniel@users.noreply.github.com>

* fix UpdateProfileRequest name references.

* added model validators to ChangePasswordRequest and UpdateProfileRequest.

---------

Co-authored-by: Daniel McKnight <34697904+NeonDaniel@users.noreply.github.com>

multi_llm_chatbot_backend/app/api/routes/auth.py

@@ -1,9 +1,11 @@
 from fastapi import APIRouter, HTTPException, Depends, status
 from datetime import datetime, timedelta
-from bson import ObjectId
 from app.models.user import UserCreate, UserLogin, User, Token, UserResponse
+from pydantic import BaseModel, model_validator
+from typing import Optional
 from app.core.auth import (
     get_password_hash, 
+    verify_password,
     authenticate_user, 
     create_access_token, 
     get_user_by_email,
@@ -16,11 +18,50 @@ import logging
 
 logger = logging.getLogger(__name__)
 
+
+class MessageResponse(BaseModel):
+    message: str
+
+
+class ChangePasswordRequest(BaseModel):
+    current_password: str
+    new_password: str
+
+    @model_validator(mode="after")
+    def passwords_must_differ(self):
+        if self.current_password == self.new_password:
+            raise ValueError("New password must be different from the current password")
+        return self
+
+
+class UpdateProfileRequest(BaseModel):
+    first_name: Optional[str] = None
+    last_name: Optional[str] = None
+
+    @model_validator(mode="after")
+    def at_least_one_field(self):
+        if self.first_name is not None:
+            self.first_name = self.first_name.strip() or None
+        if self.last_name is not None:
+            self.last_name = self.last_name.strip() or None
+        if self.first_name is None and self.last_name is None:
+            raise ValueError("At least one field must be provided")
+        return self
+
+
+class DeleteAccountRequest(BaseModel):
+    password: str
+
+
 router = APIRouter()
 
 @router.post("/signup", response_model=Token)
 async def signup(user_data: UserCreate):
-    """Create a new user account"""
+    """
+    Register a new user and return an access token.
+    @param user_data: UserCreate with name, email, password, and optional academic fields
+    @return: Token containing a JWT access token and the created UserResponse
+    """
     try:
         db = get_database()
         
@@ -73,7 +114,11 @@ async def signup(user_data: UserCreate):
 
 @router.post("/login", response_model=Token)
 async def login(user_credentials: UserLogin):
-    """Login with email and password"""
+    """
+    Authenticate a user and return an access token.
+    @param user_credentials: UserLogin with email and password
+    @return: Token containing a JWT access token and the authenticated UserResponse
+    """
     try:
         # Authenticate user
         user = await authenticate_user(user_credentials.email, user_credentials.password)
@@ -116,15 +161,128 @@ async def login(user_credentials: UserLogin):
 
 @router.get("/me", response_model=UserResponse)
 async def get_current_user_profile(current_user: User = Depends(get_current_active_user)):
-    """Get current user profile"""
+    """
+    Retrieve the profile of the currently authenticated user.
+    @param current_user: Authenticated user from dependency injection
+    @return: UserResponse with the user's profile information
+    """
     return create_user_response(current_user)
 
-@router.post("/logout")
+@router.post("/logout", response_model=MessageResponse)
 async def logout():
-    """Logout (client should discard token)"""
-    return {"message": "Successfully logged out"}
+    """
+    Log out the current user (client should discard the token).
+    @return: MessageResponse with a confirmation message
+    """
+    return MessageResponse(message="Successfully logged out")
 
 @router.post("/verify-token", response_model=UserResponse)
 async def verify_token(current_user: User = Depends(get_current_active_user)):
-    """Verify token and return user info"""
-    return create_user_response(current_user)
+    """
+    Validate the caller's JWT and return their profile.
+    @param current_user: Authenticated user from dependency injection
+    @return: UserResponse with the user's profile information
+    """
+    return create_user_response(current_user)
+
+@router.post("/me/password", response_model=MessageResponse)
+async def change_password(
+    body: ChangePasswordRequest,
+    current_user: User = Depends(get_current_active_user),
+):
+    """
+    Change the authenticated user's password.
+    @param body: ChangePasswordRequest with the current and new passwords
+    @param current_user: Authenticated user from dependency injection
+    @return: MessageResponse with a confirmation message
+    """
+    try:
+        if not verify_password(body.current_password, current_user.hashed_password):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Current password is incorrect",
+            )
+        if len(body.new_password) < 8:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="New password must be at least 8 characters",
+            )
+        db = get_database()
+        await db.users.update_one(
+            {"_id": current_user.id},
+            {"$set": {"hashed_password": get_password_hash(body.new_password)}},
+        )
+        return MessageResponse(message="Password changed successfully")
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error during password change: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Could not change password"
+        )
+
+@router.patch("/me", response_model=UserResponse)
+async def update_profile(
+    body: UpdateProfileRequest,
+    current_user: User = Depends(get_current_active_user),
+):
+    """
+    Update the authenticated user's profile fields.
+    @param body: UpdateProfileRequest with optional firstName and lastName
+    @param current_user: Authenticated user from dependency injection
+    @return: UserResponse with the updated profile information
+    """
+    try:
+        updates = {}
+        if body.first_name is not None:
+            updates["firstName"] = body.first_name
+        if body.last_name is not None:
+            updates["lastName"] = body.last_name
+        db = get_database()
+        await db.users.update_one({"_id": current_user.id}, {"$set": updates})
+        updated_user = await db.users.find_one({"_id": current_user.id})
+        return create_user_response(User(**updated_user))
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error during profile update: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Could not update profile"
+        )
+
+@router.delete("/me", response_model=MessageResponse)
+async def delete_account(
+    body: DeleteAccountRequest,
+    current_user: User = Depends(get_current_active_user),
+):
+    """
+    Permanently delete the authenticated user's account, all chat sessions, and all PhD Canvas data.
+    @param body: DeleteAccountRequest with the user's password for confirmation
+    @param current_user: Authenticated user from dependency injection
+    @return: MessageResponse with a confirmation message
+    """
+    try:
+        if not verify_password(body.password, current_user.hashed_password):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Incorrect password",
+            )
+        db = get_database()
+        uid = current_user.id
+        await db.chat_sessions.delete_many({"user_id": uid})
+        await db.phd_canvases.delete_many({"user_id": uid})
+        await db.users.delete_one({"_id": uid})
+        return MessageResponse(message="Account deleted")
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error during account deletion: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Could not delete account"
+        )

multi_llm_chatbot_backend/app/tests/unit/test_account_management.py

@@ -0,0 +1,277 @@
+import asyncio
+import sys
+import unittest
+from datetime import datetime
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from bson import ObjectId
+from fastapi import APIRouter, HTTPException
+from pydantic import ValidationError
+
+# app.api.routes.__init__ eagerly imports and wires routers from every
+# sibling route module, several of which spin up the LLM stack, NLTK
+# downloads, and ChromaDB at import time. Stub those heavy modules with
+# harmless substitutes so the package imports cleanly and auth.py can
+# be loaded via normal import machinery.
+for _name in ("app.core.bootstrap", "app.core.rag_manager"):
+    sys.modules.setdefault(_name, MagicMock())
+
+_stub_router_module = MagicMock(router=APIRouter())
+for _name in (
+    "app.api.routes.chat",
+    "app.api.routes.documents",
+    "app.api.routes.sessions",
+    "app.api.routes.provider",
+    "app.api.routes.debug",
+    "app.api.routes.root",
+    "app.api.routes.phd_canvas",
+):
+    sys.modules.setdefault(_name, _stub_router_module)
+
+from app.api.routes.auth import (  # noqa: E402
+    ChangePasswordRequest,
+    DeleteAccountRequest,
+    UpdateProfileRequest,
+    change_password,
+    delete_account,
+    update_profile,
+)
+from app.models.user import User  # noqa: E402
+
+FAKE_USER_ID = ObjectId()
+
+
+def _make_fake_user(**overrides):
+    defaults = dict(
+        _id=FAKE_USER_ID,
+        firstName="Test",
+        lastName="User",
+        email="test@example.com",
+        hashed_password="$2b$12$fakehash",
+        is_active=True,
+        created_at=datetime(2025, 1, 1),
+    )
+    defaults.update(overrides)
+    return User(**defaults)
+
+
+def _mock_db():
+    db = MagicMock()
+    db.users.update_one = AsyncMock()
+    db.users.delete_one = AsyncMock()
+    db.users.find_one = AsyncMock()
+    db.chat_sessions.delete_many = AsyncMock()
+    db.phd_canvases.delete_many = AsyncMock()
+    return db
+
+
+# ------------------------------------------------------------------
+# POST /auth/me/password
+# ------------------------------------------------------------------
+
+
+@patch("app.api.routes.auth.get_database")
+@patch("app.api.routes.auth.get_password_hash", return_value="new_hashed")
+@patch("app.api.routes.auth.verify_password")
+class TestChangePassword(unittest.TestCase):
+
+    def test_success(self, mock_verify, mock_hash, mock_get_db):
+        mock_verify.return_value = True
+        db = _mock_db()
+        mock_get_db.return_value = db
+
+        user = _make_fake_user()
+        body = ChangePasswordRequest(
+            current_password="old", new_password="newsecure",
+        )
+
+        result = asyncio.run(change_password(body=body, current_user=user))
+
+        mock_verify.assert_called_once_with("old", user.hashed_password)
+        mock_hash.assert_called_once_with("newsecure")
+        db.users.update_one.assert_called_once_with(
+            {"_id": user.id},
+            {"$set": {"hashed_password": "new_hashed"}},
+        )
+        self.assertEqual(result.message, "Password changed successfully")
+
+    def test_wrong_current_password(self, mock_verify, mock_hash, mock_get_db):
+        mock_verify.return_value = False
+
+        user = _make_fake_user()
+        body = ChangePasswordRequest(
+            current_password="wrong", new_password="newsecure",
+        )
+
+        with self.assertRaises(HTTPException) as ctx:
+            asyncio.run(change_password(body=body, current_user=user))
+
+        self.assertEqual(ctx.exception.status_code, 400)
+        self.assertIn("incorrect", ctx.exception.detail.lower())
+
+    def test_new_password_too_short(self, mock_verify, mock_hash, mock_get_db):
+        mock_verify.return_value = True
+
+        user = _make_fake_user()
+        body = ChangePasswordRequest(
+            current_password="old", new_password="short",
+        )
+
+        with self.assertRaises(HTTPException) as ctx:
+            asyncio.run(change_password(body=body, current_user=user))
+
+        self.assertEqual(ctx.exception.status_code, 400)
+        self.assertIn("8 characters", ctx.exception.detail)
+
+    def test_db_not_called_on_wrong_password(self, mock_verify, mock_hash, mock_get_db):
+        mock_verify.return_value = False
+        db = _mock_db()
+        mock_get_db.return_value = db
+
+        user = _make_fake_user()
+        body = ChangePasswordRequest(
+            current_password="wrong", new_password="newsecure",
+        )
+
+        with self.assertRaises(HTTPException):
+            asyncio.run(change_password(body=body, current_user=user))
+
+        db.users.update_one.assert_not_called()
+
+    def test_same_password_rejected(self, mock_verify, mock_hash, mock_get_db):
+        with self.assertRaises(ValidationError) as ctx:
+            ChangePasswordRequest(
+                current_password="samepass", new_password="samepass",
+            )
+
+        self.assertIn("different", str(ctx.exception).lower())
+
+
+# ------------------------------------------------------------------
+# PATCH /auth/me
+# ------------------------------------------------------------------
+
+
+@patch("app.api.routes.auth.get_database")
+class TestUpdateProfile(unittest.TestCase):
+
+    def test_update_first_name(self, mock_get_db):
+        user = _make_fake_user()
+        updated_doc = {**user.model_dump(by_alias=True), "firstName": "Alice"}
+        db = _mock_db()
+        db.users.find_one = AsyncMock(return_value=updated_doc)
+        mock_get_db.return_value = db
+
+        body = UpdateProfileRequest(first_name="Alice")
+        result = asyncio.run(update_profile(body=body, current_user=user))
+
+        db.users.update_one.assert_called_once_with(
+            {"_id": user.id},
+            {"$set": {"firstName": "Alice"}},
+        )
+        self.assertEqual(result.firstName, "Alice")
+
+    def test_update_both_names(self, mock_get_db):
+        user = _make_fake_user()
+        updated_doc = {
+            **user.model_dump(by_alias=True),
+            "firstName": "Alice",
+            "lastName": "Smith",
+        }
+        db = _mock_db()
+        db.users.find_one = AsyncMock(return_value=updated_doc)
+        mock_get_db.return_value = db
+
+        body = UpdateProfileRequest(first_name="Alice", last_name="Smith")
+        result = asyncio.run(update_profile(body=body, current_user=user))
+
+        db.users.update_one.assert_called_once_with(
+            {"_id": user.id},
+            {"$set": {"firstName": "Alice", "lastName": "Smith"}},
+        )
+        self.assertEqual(result.firstName, "Alice")
+        self.assertEqual(result.lastName, "Smith")
+
+    def test_empty_body_rejected(self, mock_get_db):
+        with self.assertRaises(ValidationError) as ctx:
+            UpdateProfileRequest()
+
+        self.assertIn("at least one field", str(ctx.exception).lower())
+
+    def test_strips_whitespace(self, mock_get_db):
+        user = _make_fake_user()
+        updated_doc = {**user.model_dump(by_alias=True), "firstName": "Alice"}
+        db = _mock_db()
+        db.users.find_one = AsyncMock(return_value=updated_doc)
+        mock_get_db.return_value = db
+
+        body = UpdateProfileRequest(first_name="  Alice  ")
+        self.assertEqual(body.first_name, "Alice")
+
+        asyncio.run(update_profile(body=body, current_user=user))
+
+        db.users.update_one.assert_called_once_with(
+            {"_id": user.id},
+            {"$set": {"firstName": "Alice"}},
+        )
+
+    def test_whitespace_only_body_rejected(self, mock_get_db):
+        with self.assertRaises(ValidationError) as ctx:
+            UpdateProfileRequest(first_name="   ")
+
+        self.assertIn("at least one field", str(ctx.exception).lower())
+
+
+# ------------------------------------------------------------------
+# DELETE /auth/me
+# ------------------------------------------------------------------
+
+
+@patch("app.api.routes.auth.get_database")
+@patch("app.api.routes.auth.verify_password")
+class TestDeleteAccount(unittest.TestCase):
+
+    def test_success(self, mock_verify, mock_get_db):
+        mock_verify.return_value = True
+        db = _mock_db()
+        mock_get_db.return_value = db
+
+        user = _make_fake_user()
+        body = DeleteAccountRequest(password="correct")
+
+        result = asyncio.run(delete_account(body=body, current_user=user))
+
+        mock_verify.assert_called_once_with("correct", user.hashed_password)
+        db.chat_sessions.delete_many.assert_called_once_with({"user_id": user.id})
+        db.phd_canvases.delete_many.assert_called_once_with({"user_id": user.id})
+        db.users.delete_one.assert_called_once_with({"_id": user.id})
+        self.assertEqual(result.message, "Account deleted")
+
+    def test_wrong_password(self, mock_verify, mock_get_db):
+        mock_verify.return_value = False
+        db = _mock_db()
+        mock_get_db.return_value = db
+
+        user = _make_fake_user()
+        body = DeleteAccountRequest(password="wrong")
+
+        with self.assertRaises(HTTPException) as ctx:
+            asyncio.run(delete_account(body=body, current_user=user))
+
+        self.assertEqual(ctx.exception.status_code, 400)
+        self.assertIn("Incorrect password", ctx.exception.detail)
+
+    def test_no_deletion_on_wrong_password(self, mock_verify, mock_get_db):
+        mock_verify.return_value = False
+        db = _mock_db()
+        mock_get_db.return_value = db
+
+        user = _make_fake_user()
+        body = DeleteAccountRequest(password="wrong")
+
+        with self.assertRaises(HTTPException):
+            asyncio.run(delete_account(body=body, current_user=user))
+
+        db.users.delete_one.assert_not_called()
+        db.chat_sessions.delete_many.assert_not_called()
+        db.phd_canvases.delete_many.assert_not_called()