Abstract:

This document provides an overview of fasthtml-admin, a Python library designed to add comprehensive user authentication, administration, and database management features to FastHTML web applications. The library is built around two core components: a UserManager for handling user registration, authentication, and email confirmation, and an AdminManager for creating privileged users and performing administrative tasks. Key features include a robust and extensible validation system with HTMX integration for real-time form feedback, seamless OAuth integration for third-party logins (e.g., GitHub), and admin utilities for SQLite database management, including backup, restore, and upload. The library also provides a persistent maintenance mode to restrict site access for non-admin users. It is designed for easy integration into existing FastHTML applications using Beforeware for centralized route protection.

A Comprehensive Guide to the fasthtml-admin Library

• Core Functionality: The fasthtml-admin library is a complete solution for adding user and admin management to FastHTML applications. It provides classes and functions to handle everything from user registration and login to database administration and third-party authentication.

• User Management: The UserManager class is the central component for all user-related operations.

  • Key Operations: It manages user creation (with secure password hashing via bcrypt), authentication (authenticate_user), and email confirmation flows (generate_confirmation_token, confirm_user).
  • Extensible User Model: The library uses a base UserCredential dataclass that can be easily extended with custom fields (e.g., first_name, bio, profile_image) to fit specific application needs.

• Admin Management: The AdminManager class provides tools for privileged users and system-level tasks.

  • Admin Creation: Easily bootstrap an admin user using the ensure_admin method, which is ideal for initial setup or using environment variables.
  • Database Utilities: Provides methods to manage the application's SQLite database directly from the admin panel, including backup_database, restore_database, and upload_database.
  • Maintenance Mode: Includes a persistent maintenance mode that can be toggled by an admin. When active, all non-admin users are redirected to a dedicated maintenance page, while admins retain full access.

• Authentication and Route Protection: The library integrates directly with FastHTML's Beforeware system for securing routes.

  • auth_before Function: A single function that can be added to your FastHTML app to protect all non-public routes. It checks for a valid user session and automatically redirects unauthenticated users to a login page.
  • Session Management: Relies on FastHTML's session support to store the current user's ID, which is retrieved using the get_current_user helper function.

• Validation System: A flexible validation system is included to handle user input securely.

  • Built-in Validators: Comes with pre-built validators for password strength, email format, and password matching.
  • Custom Validation: Developers can register their own custom validator functions with the validation_manager.
  • HTMX Integration: The system is designed to work seamlessly with HTMX, enabling real-time, as-you-type validation on registration forms for a modern user experience.

• OAuth Integration: The OAuthManager class simplifies the process of adding third-party authentication.

  • Seamless Flow: It integrates with FastHTML's OAuth clients (e.g., GitHubAppClient) to handle the entire login flow, from redirecting the user to the provider to processing the callback.
  • Automatic User Handling: When a user logs in via OAuth for the first time, the OAuthManager automatically creates a corresponding user account in the application's database. Subsequent logins will authenticate the existing user.

• Example Applications: The project includes two comprehensive example files (example.py and example_oauth.py) that demonstrate all the library's features in a runnable FastHTML application, serving as a practical guide and starting point.