docs/user_handler.py.md

# Secure User Authentication and Session Management

### Overview

This module, `user_handler.py`, is a standalone component for handling user authentication, session management, and security. It provides a secure, yet easy-to-use, system for managing user logins and protecting against common attacks like brute-force attempts and session fixation.

It is designed to be a direct Python equivalent of a user management class you might find in a web application built with a traditional framework, offering similar functionality and a focus on security.

-----

### Core Security Features

  - **Password Hashing:** Passwords are not stored in plain text. The module uses `passlib` with `pbkdf2_sha256` for robust, salted password hashing, making it nearly impossible to retrieve the original password from the database.
  - **Session Fixation Prevention:** The `login` method regenerates the session ID after a successful authentication, ensuring that an attacker cannot hijack a pre-existing session.
  - **Brute-Force Protection:** The system tracks failed login attempts. After a configurable number of failures (e.g., 5 attempts), it automatically locks the user's account to prevent further brute-force attacks.
  - **Session Validation:** Sessions are not just validated by an ID. The module also checks the user's IP address and user agent to ensure the session hasn't been hijacked.
  - **Data Storage:** A simple `SQLite` database is used as a placeholder. In a production environment, this would be replaced by a more robust and scalable solution like `PostgreSQL`.

-----

### Module Components

1.  **`Database` Class (Placeholder):**
    A simple wrapper for SQLite to simulate database interactions. This is where you would integrate a proper ORM or a more powerful database driver in a production application.

2.  **`Security` Class:**
    A static class responsible for core security functions. It handles password hashing and verification using `passlib` and includes a method to simulate session ID regeneration.

3.  **`UserHandler` Class:**
    The main class for handling user-related logic. It contains methods for:

      - `login(username, password, request_data)`: Verifies user credentials and establishes a secure session.
      - `logout()`: Terminates the user's session.
      - `is_logged_in()`: Checks if a user has an active session.
      - `is_admin()`: Determines if the logged-in user has administrator privileges.
      - `validate_session()`: Checks if the session is valid based on request details.
      - `lock_account()`: Manually locks a user's account.
      - `increment_failed_attempts()`: Increments the failed login counter and locks the account if a threshold is reached.

-----

### Example Usage

The `if __name__ == "__main__":` block at the end of the file provides a complete example of how to use the module:

1.  **Setup:** Initializes the database and creates the necessary tables.
2.  **User Registration:** Demonstrates how to create a regular user and an admin user with securely hashed passwords.
3.  **Successful Login:** Shows a successful login attempt, which creates a new session.
4.  **Logout:** Illustrates how to terminate the session.
5.  **Brute-Force Protection Test:** Simulates multiple failed login attempts to demonstrate the account-locking mechanism.
6.  **Account Reset:** Shows how to manually reset failed attempts to re-enable an account.

This module provides a robust and well-documented foundation for building a secure and reliable user authentication system.