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/config.py

@@ -37,3 +37,4 @@ class Config:
     SMTP_FROM_ADDRESS: str = os.environ.get("SMTP_FROM_ADDRESS", "")
     SMTP_FROM_NAME: str = os.environ.get("SMTP_FROM_NAME", "Fabled Assistant")
     SMTP_USE_TLS: bool = os.environ.get("SMTP_USE_TLS", "true").lower() in ("1", "true", "yes")
+    BASE_URL: str = os.environ.get("BASE_URL", "http://localhost:5000").rstrip("/")

src/fabledassistant/models/__init__.py

@@ -16,3 +16,4 @@ from fabledassistant.models.conversation import Conversation, Message  # noqa: E
 from fabledassistant.models.setting import Setting  # noqa: E402, F401
 from fabledassistant.models.user import User  # noqa: E402, F401
 from fabledassistant.models.app_log import AppLog  # noqa: E402, F401
+from fabledassistant.models.password_reset import PasswordResetToken  # noqa: E402, F401

src/fabledassistant/models/password_reset.py

@@ -0,0 +1,24 @@
+from datetime import datetime, timezone
+
+from sqlalchemy import Boolean, DateTime, ForeignKey, Index, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from fabledassistant.models import Base
+
+
+class PasswordResetToken(Base):
+    __tablename__ = "password_reset_tokens"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    token_hash: Mapped[str] = mapped_column(Text, nullable=False, unique=True)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    used: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+
+    __table_args__ = (
+        Index("ix_password_reset_tokens_token_hash", "token_hash"),
+        Index("ix_password_reset_tokens_user_id", "user_id"),
+    )

src/fabledassistant/routes/auth.py

@@ -3,17 +3,26 @@ import asyncio
 from quart import Blueprint, g, jsonify, request, session
 
 from fabledassistant.auth import login_required, get_current_user_id
+from fabledassistant.config import Config
 from fabledassistant.services.auth import (
     authenticate,
     change_password,
+    create_password_reset_token,
     create_user,
+    get_user_by_email,
     get_user_by_id,
     get_user_by_username,
     get_user_count,
     is_registration_open,
+    reset_password_with_token,
 )
 from fabledassistant.services.logging import log_audit
-from fabledassistant.services.notifications import notify_security_event
+from fabledassistant.services.notifications import (
+    notify_security_event,
+    send_password_reset_email,
+    send_password_reset_success_email,
+)
+from fabledassistant.services.email import is_smtp_configured
 
 auth_bp = Blueprint("auth", __name__, url_prefix="/api/auth")
 
@@ -121,6 +130,72 @@ async def update_password():
     return jsonify({"status": "ok"})
 
 
+@auth_bp.route("/forgot-password", methods=["POST"])
+async def forgot_password():
+    data = await request.get_json()
+    email = (data.get("email") or "").strip().lower()
+
+    if not email:
+        return jsonify({"error": "Email is required"}), 400
+
+    # Always return success to prevent email enumeration
+    user = await get_user_by_email(email)
+    if user and await is_smtp_configured():
+        raw_token = await create_password_reset_token(user.id)
+        reset_url = f"{Config.BASE_URL}/reset-password?token={raw_token}"
+        asyncio.create_task(send_password_reset_email(user.email, reset_url))
+        await log_audit(
+            "password_reset_requested",
+            user_id=user.id,
+            username=user.username,
+            ip_address=request.remote_addr,
+        )
+
+    return jsonify({"status": "ok"})
+
+
+@auth_bp.route("/reset-password", methods=["POST"])
+async def reset_password():
+    data = await request.get_json()
+    token = (data.get("token") or "").strip()
+    new_password = data.get("new_password") or ""
+
+    if not token:
+        return jsonify({"error": "Reset token is required"}), 400
+    if len(new_password) < 8:
+        return jsonify({"error": "Password must be at least 8 characters"}), 400
+
+    success = await reset_password_with_token(token, new_password)
+    if not success:
+        return jsonify({"error": "Invalid or expired reset link"}), 400
+
+    # Look up user by token to send notifications (token is now used, so look up by hash)
+    import hashlib
+    from fabledassistant.models import async_session
+    from fabledassistant.models.password_reset import PasswordResetToken
+    from sqlalchemy import select
+
+    token_hash = hashlib.sha256(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 reset_token:
+            user = await get_user_by_id(reset_token.user_id)
+            if user:
+                await log_audit(
+                    "password_reset_completed",
+                    user_id=user.id,
+                    username=user.username,
+                    ip_address=request.remote_addr,
+                )
+                if user.email:
+                    asyncio.create_task(send_password_reset_success_email(user.email))
+
+    return jsonify({"status": "ok"})
+
+
 @auth_bp.route("/status", methods=["GET"])
 async def status():
     count = await get_user_count()

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

src/fabledassistant/services/notifications.py

@@ -92,6 +92,52 @@ async def notify_security_event(
         logger.exception("Failed to send security notification for user %d", user_id)
 
 
+async def send_password_reset_email(email: str, reset_url: str) -> None:
+    """Send a password reset email with a link to reset the user's password."""
+    html = f"""
+    <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 480px; margin: 0 auto; padding: 24px;">
+        <div style="background: #6366f1; color: #fff; padding: 16px 24px; border-radius: 8px 8px 0 0; text-align: center;">
+            <h1 style="margin: 0; font-size: 20px;">Password Reset</h1>
+        </div>
+        <div style="background: #f9fafb; padding: 24px; border: 1px solid #e5e7eb; border-top: none; border-radius: 0 0 8px 8px;">
+            <p style="margin: 0 0 16px; color: #374151; font-size: 15px;">
+                We received a request to reset your password. Click the button below to choose a new password:
+            </p>
+            <div style="text-align: center; margin: 24px 0;">
+                <a href="{reset_url}" style="display: inline-block; background: #6366f1; color: #fff; padding: 12px 32px; border-radius: 6px; text-decoration: none; font-weight: 600; font-size: 15px;">
+                    Reset Password
+                </a>
+            </div>
+            <p style="margin: 0 0 8px; color: #6b7280; font-size: 13px;">This link expires in 1 hour.</p>
+            <p style="margin: 0; color: #6b7280; font-size: 13px;">If you didn't request this, you can safely ignore this email.</p>
+            <hr style="border: none; border-top: 1px solid #e5e7eb; margin: 16px 0;" />
+            <p style="margin: 0; color: #9ca3af; font-size: 12px;">If the button doesn't work, copy and paste this link into your browser:</p>
+            <p style="margin: 4px 0 0; color: #9ca3af; font-size: 12px; word-break: break-all;">{reset_url}</p>
+        </div>
+    </div>
+    """
+    await send_email(email, "Fabled Assistant - Password Reset", html)
+
+
+async def send_password_reset_success_email(email: str) -> None:
+    """Send a notification that the password was successfully reset."""
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+    html = f"""
+    <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 480px; margin: 0 auto; padding: 24px;">
+        <div style="background: #6366f1; color: #fff; padding: 16px 24px; border-radius: 8px 8px 0 0; text-align: center;">
+            <h1 style="margin: 0; font-size: 20px;">Password Changed</h1>
+        </div>
+        <div style="background: #f9fafb; padding: 24px; border: 1px solid #e5e7eb; border-top: none; border-radius: 0 0 8px 8px;">
+            <p style="margin: 0 0 16px; color: #374151; font-size: 15px;">
+                Your password was successfully reset at {timestamp}.
+            </p>
+            <p style="margin: 0; color: #6b7280; font-size: 13px;">If you didn't make this change, please contact your administrator immediately.</p>
+        </div>
+    </div>
+    """
+    await send_email(email, "Fabled Assistant - Password Changed", html)
+
+
 async def check_due_tasks() -> None:
     """Check for tasks due today and send reminder emails."""
     if not await is_smtp_configured():