Add password creation/reset via token

Author: azvoleff

gefapi/models/__init__.py

@@ -53,6 +53,7 @@ def process_result_value(self, value, dialect):
 )
 from gefapi.models.execution import Execution  # noqa: E402
 from gefapi.models.execution_log import ExecutionLog  # noqa: E402
+from gefapi.models.password_reset_token import PasswordResetToken  # noqa: E402
 from gefapi.models.rate_limit_event import RateLimitEvent  # noqa: E402
 from gefapi.models.refresh_token import RefreshToken  # noqa: E402
 from gefapi.models.script import Script  # noqa: E402
@@ -66,6 +67,7 @@ def process_result_value(self, value, dialect):
     "AdminBoundary1Unit",
     "Execution",
     "ExecutionLog",
+    "PasswordResetToken",
     "RateLimitEvent",
     "RefreshToken",
     "Script",

gefapi/models/password_reset_token.py

@@ -0,0 +1,120 @@
+"""PASSWORD RESET TOKEN MODEL
+
+Provides secure time-limited tokens for password reset functionality.
+Tokens expire after 1 hour and can only be used once.
+"""
+
+import datetime
+import logging
+import secrets
+import uuid
+
+from gefapi import db
+from gefapi.models import GUID
+
+db.GUID = GUID
+
+logger = logging.getLogger(__name__)
+
+# Token expiry time in hours
+PASSWORD_RESET_TOKEN_EXPIRY_HOURS = 1
+
+
+class PasswordResetToken(db.Model):
+    """Password Reset Token Model
+
+    Stores secure tokens for password reset requests. Each token:
+    - Has a 1-hour expiry window
+    - Can only be used once
+    - Is associated with a single user
+    - Uses cryptographically secure random generation
+    """
+
+    id = db.Column(
+        db.GUID(),
+        default=lambda: str(uuid.uuid4()),
+        primary_key=True,
+        autoincrement=False,
+    )
+    # Cryptographically secure token (64 characters, URL-safe)
+    token = db.Column(db.String(128), unique=True, nullable=False, index=True)
+    user_id = db.Column(db.GUID(), db.ForeignKey("user.id"), nullable=False)
+    created_at = db.Column(
+        db.DateTime(), default=lambda: datetime.datetime.now(datetime.UTC)
+    )
+    expires_at = db.Column(db.DateTime(), nullable=False)
+    used_at = db.Column(db.DateTime(), nullable=True)  # Track when token was used
+
+    # Relationship to user
+    user = db.relationship("User", backref=db.backref("password_reset_tokens"))
+
+    def __init__(self, user_id):
+        self.user_id = user_id
+        self.token = self._generate_secure_token()
+        self.created_at = datetime.datetime.now(datetime.UTC)
+        self.expires_at = self.created_at + datetime.timedelta(
+            hours=PASSWORD_RESET_TOKEN_EXPIRY_HOURS
+        )
+
+    def __repr__(self):
+        return f"<PasswordResetToken user_id={self.user_id!r}>"
+
+    @staticmethod
+    def _generate_secure_token():
+        """Generate a cryptographically secure URL-safe token."""
+        return secrets.token_urlsafe(48)
+
+    def is_valid(self):
+        """Check if the token is valid (not expired and not used)."""
+        now = datetime.datetime.now(datetime.UTC)
+        return self.used_at is None and self.expires_at > now
+
+    def mark_used(self):
+        """Mark the token as used."""
+        self.used_at = datetime.datetime.now(datetime.UTC)
+
+    @classmethod
+    def get_valid_token(cls, token_string):
+        """Find a valid (unexpired, unused) token by its string value.
+
+        Args:
+            token_string: The token string to look up
+
+        Returns:
+            PasswordResetToken if found and valid, None otherwise
+        """
+        token = cls.query.filter_by(token=token_string).first()
+        if token and token.is_valid():
+            return token
+        return None
+
+    @classmethod
+    def invalidate_user_tokens(cls, user_id):
+        """Invalidate all existing tokens for a user.
+
+        Called when creating a new reset token to ensure only one
+        valid token exists per user at a time.
+        """
+        now = datetime.datetime.now(datetime.UTC)
+        cls.query.filter(
+            cls.user_id == user_id,
+            cls.used_at.is_(None),
+            cls.expires_at > now,
+        ).update({"used_at": now}, synchronize_session=False)
+
+    @classmethod
+    def cleanup_expired_tokens(cls, days_old=7):
+        """Remove tokens older than the specified number of days.
+
+        Args:
+            days_old: Remove tokens older than this many days (default 7)
+
+        Returns:
+            Number of tokens deleted
+        """
+        cutoff = datetime.datetime.now(datetime.UTC) - datetime.timedelta(days=days_old)
+        result = cls.query.filter(cls.created_at < cutoff).delete(
+            synchronize_session=False
+        )
+        db.session.commit()
+        return result

gefapi/routes/api/v1/users.py

@@ -95,9 +95,20 @@ def create_user():
     - `403 Forbidden`: Insufficient privileges to create the requested role
     - `429 Too Many Requests`: Rate limit exceeded
     - `500 Internal Server Error`: User creation failed
+
+    **Query Parameters**:
+    - `legacy`: If "true" (default), emails the password directly for backwards
+      compatibility with the QGIS plugin. If "false", sends a password reset
+      link instead (more secure).
     """
     logger.info("[ROUTER]: Creating user")
     body = request.get_json()
+
+    # Check for legacy query parameter (defaults to true for backwards
+    # compatibility with QGIS plugin)
+    legacy_param = request.args.get("legacy", "true")
+    legacy = legacy_param.lower() != "false"
+
     if request.headers.get("Authorization", None) is not None:
 
         @jwt_required()
@@ -114,7 +125,7 @@ def identity():
     else:
         body["role"] = "USER"
     try:
-        user = UserService.create_user(body)
+        user = UserService.create_user(body, legacy=legacy)
     except UserDuplicated as e:
         logger.error("[ROUTER]: " + e.message)
         return error(status=400, detail=e.message)
@@ -656,13 +667,27 @@ def recover_password(user):
     **Path Parameters**:
     - `user`: User identifier (email address or numeric ID)
 
+    **Query Parameters**:
+    - `legacy`: (optional, default=true) Password recovery mode:
+        - `true` (default): Legacy mode - generates new password and emails it
+          directly. Maintained for backwards compatibility with older QGIS
+          plugin versions.
+        - `false`: Secure mode - sends a password reset link that expires after
+          1 hour. Recommended for new integrations.
+
     **Request**: No request body required
 
-    **Recovery Process**:
+    **Recovery Process (legacy=true, default)**:
+    1. Validates user exists
+    2. Generates a new secure password
+    3. Updates user's password in database
+    4. Emails the new password to user
+
+    **Recovery Process (legacy=false)**:
     1. Validates user exists and account is active
-    2. Generates secure password reset token with expiration
+    2. Generates secure password reset token with 1-hour expiration
     3. Sends password recovery email with reset link
-    4. Logs recovery attempt for security monitoring
+    4. User clicks link and sets new password via /user/reset-password endpoint
 
     **Success Response Schema**:
     ```json
@@ -671,39 +696,30 @@ def recover_password(user):
         "id": "user-123",
         "email": "user@example.com",
         "name": "John Doe",
-        "role": "USER",
-        "recovery_initiated": true,
-        "recovery_token_expires": "2025-01-15T16:00:00Z"
+        "role": "USER"
       }
     }
     ```
 
-    **Email Content**:
-    - Secure reset link with time-limited token
-    - Clear instructions for password reset process
-    - Security notice about unsolicited requests
-    - Link expiration time (typically 1-2 hours)
-
-    **Security Features**:
-    - Rate limiting prevents email flooding attacks
-    - Tokens expire automatically for security
-    - Email delivery doesn't reveal if account exists (privacy)
-    - Multiple recovery attempts are logged and monitored
-
-    **Use Cases**:
-    - User forgot their password
-    - Account recovery after security incident
-    - Password reset for inactive accounts
-    - Initial password setup (in some configurations)
+    **Security Notes**:
+    - Legacy mode (default) is DEPRECATED but maintained for backwards
+      compatibility. It sends passwords via email which is less secure.
+    - New integrations should use `legacy=false` for better security.
+    - Rate limiting prevents email flooding attacks in both modes.
 
     **Error Responses**:
-    - `404 Not Found`: User does not exist (for security, may return success)
+    - `404 Not Found`: User does not exist
     - `429 Too Many Requests`: Rate limit exceeded
     - `500 Internal Server Error`: Email delivery failed or system error
     """
     logger.info("[ROUTER]: Recovering password")
+
+    # Parse legacy parameter - defaults to True for backwards compatibility
+    legacy_param = request.args.get("legacy", "true").lower()
+    use_legacy = legacy_param not in ("false", "0", "no")
+
     try:
-        user = UserService.recover_password(user)
+        user = UserService.recover_password(user, legacy=use_legacy)
     except UserNotFound as e:
         logger.error("[ROUTER]: " + e.message)
         return error(status=404, detail=e.message)
@@ -716,6 +732,84 @@ def recover_password(user):
     return jsonify(data=user.serialize()), 200
 
 
+@endpoints.route("/user/reset-password", strict_slashes=False, methods=["POST"])
+@limiter.limit(
+    lambda: ";".join(RateLimitConfig.get_password_reset_limits()) or "3 per hour",
+    key_func=get_admin_aware_key,
+    exempt_when=is_rate_limiting_disabled,
+)
+def reset_password_with_token():
+    """
+    Reset password using a secure token from password recovery email.
+
+    **Rate Limited**: Subject to password recovery rate limits (configurable)
+    **Access**: Public endpoint - no authentication required
+    **Security**: Token-based authentication, tokens expire after 1 hour
+
+    **Request Body Schema**:
+    ```json
+    {
+      "token": "secure-reset-token-from-email",
+      "password": "new-secure-password"
+    }
+    ```
+
+    **Password Requirements**:
+    - Minimum 8 characters
+    - Must contain at least one uppercase letter
+    - Must contain at least one lowercase letter
+    - Must contain at least one digit
+
+    **Success Response Schema**:
+    ```json
+    {
+      "data": {
+        "message": "Password reset successful"
+      }
+    }
+    ```
+
+    **Security Features**:
+    - Tokens are single-use (marked as used after successful reset)
+    - Tokens expire after 1 hour
+    - Rate limiting prevents brute force attacks
+    - Password strength validation enforced
+
+    **Error Responses**:
+    - `400 Bad Request`: Missing token or password
+    - `404 Not Found`: Invalid or expired token
+    - `422 Unprocessable Entity`: Password doesn't meet requirements
+    - `429 Too Many Requests`: Rate limit exceeded
+    - `500 Internal Server Error`: System error
+    """
+    logger.info("[ROUTER]: Reset password with token")
+    try:
+        body = request.get_json()
+        if not body:
+            return error(status=400, detail="Request body required")
+
+        token = body.get("token")
+        password = body.get("password")
+
+        if not token:
+            return error(status=400, detail="Reset token is required")
+        if not password:
+            return error(status=400, detail="New password is required")
+
+        UserService.reset_password_with_token(token, password)
+        return jsonify(data={"message": "Password reset successful"}), 200
+
+    except UserNotFound as e:
+        logger.error("[ROUTER]: " + e.message)
+        return error(status=404, detail=e.message)
+    except PasswordValidationError as e:
+        logger.error("[ROUTER]: " + e.message)
+        return error(status=422, detail=e.message)
+    except Exception as e:
+        logger.error("[ROUTER]: " + str(e))
+        return error(status=500, detail="Generic Error")
+
+
 @endpoints.route("/user/<user>", strict_slashes=False, methods=["PATCH"])
 @jwt_required()
 @validate_user_update