Add password reset API and auth UI (dev reset link).

Implements forgot/reset endpoints with single-use tokens, migration,
and frontend flow. Email delivery is deferred to a follow-up issue.

Author: nimra06

backend/app.py

@@ -59,6 +59,8 @@
     SyncLibraryRequest,
     RegisterRequest,
     LoginRequest,
+    ForgotPasswordRequest,
+    ResetPasswordRequest,
     SetGoalRequest,
     GetStatsRequest,
     CollectionRequest,
@@ -72,9 +74,15 @@
     validate_jwt_secret,
     is_production_mode
 )
+from password_reset_service import (
+    FORGOT_PASSWORD_MESSAGE,
+    request_password_reset,
+    reset_password_with_token,
+)
 from collections import defaultdict, deque
 from math import ceil
 from time import time
+from urllib.parse import quote
 from error_responses import (
     ErrorCodes, error_response, success_response,
     validation_error, missing_fields_error, invalid_json_error,
@@ -1739,6 +1747,75 @@ def logout():
     return resp, status
 
 
+@app.route('/api/v1/auth/forgot-password', methods=['POST'])
+@csrf.exempt
+@limiter.limit("5 per minute")
+def forgot_password():
+    """Request a password reset link (always returns a generic success message)."""
+    try:
+        data = request.get_json(silent=True)
+        if data is None:
+            return invalid_json_error()
+
+        is_valid, validated_data = validate_request(ForgotPasswordRequest, data)
+        if not is_valid:
+            return jsonify(validated_data), 400
+
+        plain_token = None
+        try:
+            plain_token = request_password_reset(validated_data.email)
+        except SQLAlchemyError as e:
+            logger.error("forgot-password database error: %s", e, exc_info=True)
+
+        response_data = {"message": FORGOT_PASSWORD_MESSAGE}
+
+        if plain_token and app_config.is_development():
+            frontend_base = os.getenv(
+                'FRONTEND_ORIGIN',
+                'http://127.0.0.1:5500',
+            ).rstrip('/')
+            response_data["reset_url"] = (
+                f"{frontend_base}/pages/auth.html?token={quote(plain_token)}"
+            )
+            logger.info(
+                "Dev password reset link for %s: %s",
+                validated_data.email,
+                response_data["reset_url"],
+            )
+
+        return success_response(data=response_data)
+    except Exception as e:
+        logger.error("forgot-password failed: %s", e, exc_info=True)
+        return success_response(data={"message": FORGOT_PASSWORD_MESSAGE})
+
+
+@app.route('/api/v1/auth/reset-password', methods=['POST'])
+@csrf.exempt
+@limiter.limit("5 per minute")
+def reset_password():
+    """Set a new password using a valid reset token."""
+    try:
+        data = request.get_json(silent=True)
+        if data is None:
+            return invalid_json_error()
+
+        is_valid, validated_data = validate_request(ResetPasswordRequest, data)
+        if not is_valid:
+            return jsonify(validated_data), 400
+
+        ok, message = reset_password_with_token(
+            validated_data.token,
+            validated_data.password,
+        )
+        if not ok:
+            return jsonify({"error": message}), 400
+
+        return success_response(data={"message": message})
+    except Exception as e:
+        logger.error("reset-password failed: %s", e, exc_info=True)
+        return internal_error("Unable to reset password.")
+
+
 @app.route('/api/v1/auth/verify', methods=['GET'])
 @jwt_required()
 def verify_auth_session():
@@ -2491,6 +2568,8 @@ def get_books():
     SyncLibraryRequest,
     RegisterRequest,
     LoginRequest,
+    ForgotPasswordRequest,
+    ResetPasswordRequest,
     SetGoalRequest,
     GetStatsRequest,
     CollectionRequest,
@@ -2504,9 +2583,15 @@ def get_books():
     validate_jwt_secret,
     is_production_mode
 )
+from password_reset_service import (
+    FORGOT_PASSWORD_MESSAGE,
+    request_password_reset,
+    reset_password_with_token,
+)
 from collections import defaultdict, deque
 from math import ceil
 from time import time
+from urllib.parse import quote
 from error_responses import (
     ErrorCodes, error_response, success_response,
     validation_error, missing_fields_error, invalid_json_error,
@@ -3359,6 +3444,7 @@ def remove_from_library(item_id):
 
 
 db.init_app(app)
+migrate = Migrate(app, db)
 price_tracker = get_price_tracker(db)
 
 
@@ -3739,6 +3825,68 @@ def logout():
     return resp, status
 
 
+@app.route('/api/v1/auth/forgot-password', methods=['POST'])
+@limiter.limit("5 per minute")
+def forgot_password():
+    """Request a password reset link (always returns a generic success message)."""
+    try:
+        data = request.get_json(silent=True)
+        if data is None:
+            return invalid_json_error()
+
+        is_valid, validated_data = validate_request(ForgotPasswordRequest, data)
+        if not is_valid:
+            return jsonify(validated_data), 400
+
+        plain_token = request_password_reset(validated_data.email)
+        response_data = {"message": FORGOT_PASSWORD_MESSAGE}
+
+        if plain_token and app_config.is_development():
+            frontend_base = os.getenv(
+                'FRONTEND_ORIGIN',
+                'http://127.0.0.1:5500',
+            ).rstrip('/')
+            response_data["reset_url"] = (
+                f"{frontend_base}/pages/auth.html?token={quote(plain_token)}"
+            )
+            logger.info(
+                "Dev password reset link for %s: %s",
+                validated_data.email,
+                response_data["reset_url"],
+            )
+
+        return success_response(data=response_data)
+    except Exception as e:
+        logger.error("forgot-password failed: %s", e, exc_info=True)
+        return internal_error("Unable to process password reset request.")
+
+
+@app.route('/api/v1/auth/reset-password', methods=['POST'])
+@limiter.limit("5 per minute")
+def reset_password():
+    """Set a new password using a valid reset token."""
+    try:
+        data = request.get_json(silent=True)
+        if data is None:
+            return invalid_json_error()
+
+        is_valid, validated_data = validate_request(ResetPasswordRequest, data)
+        if not is_valid:
+            return jsonify(validated_data), 400
+
+        ok, message = reset_password_with_token(
+            validated_data.token,
+            validated_data.password,
+        )
+        if not ok:
+            return jsonify({"error": message}), 400
+
+        return success_response(data={"message": message})
+    except Exception as e:
+        logger.error("reset-password failed: %s", e, exc_info=True)
+        return internal_error("Unable to reset password.")
+
+
 # ==================== READING STATS ENDPOINTS ====================
 @app.route('/api/v1/stats/goal', methods=['POST'])
 @jwt_required()

backend/config.py

@@ -165,8 +165,11 @@ def from_env(cls) -> 'GoogleOAuthConfig':
             client_secret=os.getenv('GOOGLE_CLIENT_SECRET') or os.getenv('GOOGLE_OAUTH_CLIENT_SECRET'),
             redirect_uri=os.getenv('GOOGLE_OAUTH_REDIRECT_URI'),
             frontend_redirect_url=os.getenv('FRONTEND_URL', 'http://127.0.0.1:5500/frontend/pages/library.html'),
-            scope=os.getenv('GOOGLE_OAUTH_SCOPE', 'openid email profile')
-          
+            scope=os.getenv('GOOGLE_OAUTH_SCOPE', 'openid email profile'),
+        )
+
+
+@dataclass
 class EmailConfig:
     """Email service configuration (e.g., SendGrid, Mailgun)."""
     api_key: Optional[str]

backend/migrations/versions/0004_password_reset_tokens.py

@@ -0,0 +1,38 @@
+"""Add password_reset_token table.
+
+Revision ID: 0004
+Revises: 0003
+Create Date: 2026-05-18 12:00:00.000000
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = '0004'
+down_revision = '0003'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'password_reset_token',
+        sa.Column('id', sa.Integer(), nullable=False),
+        sa.Column('user_id', sa.Integer(), nullable=False),
+        sa.Column('token_hash', sa.String(length=64), nullable=False),
+        sa.Column('expires_at', sa.DateTime(), nullable=False),
+        sa.Column('used_at', sa.DateTime(), nullable=True),
+        sa.Column('created_at', sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(['user_id'], ['user.id']),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('token_hash'),
+    )
+    op.create_index('ix_password_reset_token_user_id', 'password_reset_token', ['user_id'], unique=False)
+    op.create_index('ix_password_reset_token_token_hash', 'password_reset_token', ['token_hash'], unique=False)
+
+
+def downgrade() -> None:
+    op.drop_index('ix_password_reset_token_token_hash', table_name='password_reset_token')
+    op.drop_index('ix_password_reset_token_user_id', table_name='password_reset_token')
+    op.drop_table('password_reset_token')

backend/models.py

@@ -131,6 +131,19 @@ def to_dict(self):
             "is_deleted": self.is_deleted
         }
 
+
+class PasswordResetToken(db.Model):
+    """Single-use token for password reset (stores SHA-256 hash only)."""
+    id = db.Column(db.Integer, primary_key=True)
+    user_id = db.Column(db.Integer, db.ForeignKey('user.id'), nullable=False, index=True)
+    token_hash = db.Column(db.String(64), nullable=False, unique=True, index=True)
+    expires_at = db.Column(db.DateTime, nullable=False)
+    used_at = db.Column(db.DateTime, nullable=True)
+    created_at = db.Column(db.DateTime, default=lambda: datetime.now(timezone.utc))
+
+    user = db.relationship('User', backref=db.backref('password_reset_tokens', lazy='dynamic'))
+
+
 class Book(db.Model, SoftDeleteMixin):
     query_class = SoftDeleteQuery
     id = db.Column(db.Integer, primary_key=True)

backend/password_reset_service.py

@@ -0,0 +1,101 @@
+"""Password reset token issuance and consumption."""
+import hashlib
+import logging
+import secrets
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from sqlalchemy.exc import SQLAlchemyError
+
+from sqlalchemy import func
+
+try:
+    from .models import PasswordResetToken, User, db
+except ImportError:
+    from models import PasswordResetToken, User, db
+
+logger = logging.getLogger(__name__)
+
+RESET_TOKEN_BYTES = 32
+RESET_TOKEN_TTL = timedelta(hours=1)
+
+FORGOT_PASSWORD_MESSAGE = (
+    "If an account exists for that email, password reset instructions have been sent."
+)
+
+
+def _hash_token(token: str) -> str:
+    return hashlib.sha256(token.encode('utf-8')).hexdigest()
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _invalidate_active_tokens(user_id: int) -> None:
+    now = _utcnow()
+    (
+        PasswordResetToken.query.filter_by(user_id=user_id)
+        .filter(PasswordResetToken.used_at.is_(None))
+        .update({'used_at': now}, synchronize_session=False)
+    )
+
+
+def create_password_reset_token(user: User) -> str:
+    """Create a new reset token for the user; returns the plaintext token."""
+    plain_token = secrets.token_urlsafe(RESET_TOKEN_BYTES)
+    record = PasswordResetToken(
+        user_id=user.id,
+        token_hash=_hash_token(plain_token),
+        expires_at=_utcnow() + RESET_TOKEN_TTL,
+    )
+    _invalidate_active_tokens(user.id)
+    db.session.add(record)
+    db.session.commit()
+    return plain_token
+
+
+def reset_password_with_token(token: str, new_password: str) -> tuple[bool, str]:
+    """Validate token and set a new password. Returns (success, message)."""
+    if not token or not token.strip():
+        return False, "Invalid or expired reset link."
+
+    token_hash = _hash_token(token.strip())
+    record = PasswordResetToken.query.filter_by(token_hash=token_hash).first()
+    now = _utcnow()
+
+    if not record or record.used_at is not None:
+        return False, "Invalid or expired reset link."
+
+    expires = record.expires_at
+    if expires.tzinfo is None:
+        expires = expires.replace(tzinfo=timezone.utc)
+
+    if expires < now:
+        return False, "Invalid or expired reset link."
+
+    user = User.query.get(record.user_id)
+    if not user:
+        return False, "Invalid or expired reset link."
+
+    try:
+        user.set_password(new_password)
+        record.used_at = now
+        db.session.commit()
+        return True, "Password updated successfully. You can sign in with your new password."
+    except SQLAlchemyError as exc:
+        db.session.rollback()
+        logger.error("Password reset failed for user %s: %s", user.id, exc)
+        return False, "Unable to reset password. Please try again later."
+
+
+def request_password_reset(email: str) -> Optional[str]:
+    """
+    Start reset flow for a local account email.
+    Returns plaintext token when a matching user exists, else None.
+    """
+    normalized = email.strip().lower()
+    user = User.query.filter(func.lower(User.email) == normalized).first()
+    if not user:
+        return None
+    return create_password_reset_token(user)