Add email-based password reset flow

Users who forget their password can now request a reset link via email.
Tokens are SHA-256 hashed before storage, expire after 1 hour, and
previous unused tokens are invalidated on new requests. The forgot-password
endpoint always returns success to prevent email enumeration.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/fabledassistant/services/auth.py

@@ -1,4 +1,7 @@
+import hashlib
 import logging
+import secrets
+from datetime import datetime, timedelta, timezone
 
 import bcrypt
 from sqlalchemy import func, select, update
@@ -6,6 +9,7 @@ from sqlalchemy import func, select, update
 from fabledassistant.models import async_session
 from fabledassistant.models.conversation import Conversation
 from fabledassistant.models.note import Note
+from fabledassistant.models.password_reset import PasswordResetToken
 from fabledassistant.models.setting import Setting
 from fabledassistant.models.user import User
 
@@ -150,3 +154,69 @@ async def delete_user(user_id: int) -> bool:
 async def set_registration_open(admin_user_id: int, open: bool) -> None:
     from fabledassistant.services.settings import set_setting
     await set_setting(admin_user_id, "registration_open", "true" if open else "false")
+
+
+async def get_user_by_email(email: str) -> User | None:
+    async with async_session() as session:
+        result = await session.execute(
+            select(User).where(func.lower(User.email) == email.lower())
+        )
+        return result.scalars().first()
+
+
+async def create_password_reset_token(user_id: int) -> str:
+    """Generate a password reset token. Returns the raw token (for the email link)."""
+    raw_token = secrets.token_urlsafe(32)
+    token_hash = hashlib.sha256(raw_token.encode()).hexdigest()
+    expires_at = datetime.now(timezone.utc) + timedelta(hours=1)
+
+    async with async_session() as session:
+        # Invalidate any existing unused tokens for this user
+        result = await session.execute(
+            select(PasswordResetToken).where(
+                PasswordResetToken.user_id == user_id,
+                PasswordResetToken.used.is_(False),
+            )
+        )
+        for old_token in result.scalars().all():
+            old_token.used = True
+
+        token = PasswordResetToken(
+            user_id=user_id,
+            token_hash=token_hash,
+            expires_at=expires_at,
+        )
+        session.add(token)
+        await session.commit()
+
+    logger.info("Password reset token created for user %d", user_id)
+    return raw_token
+
+
+async def reset_password_with_token(raw_token: str, new_password: str) -> bool:
+    """Validate a reset token and update the user's password. Returns True on success."""
+    token_hash = hashlib.sha256(raw_token.encode()).hexdigest()
+
+    async with async_session() as session:
+        result = await session.execute(
+            select(PasswordResetToken).where(PasswordResetToken.token_hash == token_hash)
+        )
+        reset_token = result.scalars().first()
+
+        if not reset_token:
+            return False
+        if reset_token.used:
+            return False
+        if reset_token.expires_at < datetime.now(timezone.utc):
+            return False
+
+        user = await session.get(User, reset_token.user_id)
+        if not user:
+            return False
+
+        user.password_hash = hash_password(new_password)
+        reset_token.used = True
+        await session.commit()
+
+        logger.info("Password reset via token for user %d (%s)", user.id, user.username)
+        return True