Abstract:

This document provides the source code and documentation for fasthtml-admin, a Python library designed to add comprehensive user authentication, administration, and database management to FastHTML web applications. The library offers a modular toolkit for common backend functionalities, including user registration with email confirmation, secure login, and admin user creation. It features robust tools for administrators, such as SQLite database backup, restore, and upload capabilities, alongside a persistent maintenance mode to restrict site access. Key features include an extensible validation system with built-in rules for passwords and emails, seamless HTMX integration for real-time form validation, and OAuth support for third-party authentication with providers like GitHub. The library follows FastHTML best practices, utilizing Beforeware for centralized route protection and session management.

fasthtml-admin: A Guide to Features and Implementation

• README.md Core Functionality: The library provides a complete solution for user management (registration, authentication, confirmation), admin management (user creation, database operations), and extensible validation. It is designed for seamless integration into new or existing FastHTML projects.
• auth.py User and Authentication Management:
  • The UserManager class is the central component for handling user operations like create_user, authenticate_user, and confirm_user. It can work with a FastHTML database or a simple dictionary store.
  • Route protection is implemented using the auth_before function, which integrates with FastHTML's Beforeware system to secure endpoints and define public paths that do not require login.
  • A helper function, get_current_user, is provided to easily retrieve the currently authenticated user's data from the session within any route handler.
• example.py Extensible User Class: The default UserCredential class can be easily extended to include custom profile fields (e.g., first_name, bio, profile_image). This custom class is then passed to the UserManager to automatically handle the additional data fields in the database.
• admin.py Admin and Database Tools:
  • The AdminManager class provides high-level administrative functions. It can ensure an admin user exists (ensure_admin) and manage site-wide settings.
  • It includes utilities for managing the SQLite database, allowing admins to create backups, restore from backups, and upload a new database file, replacing the existing one.
  • A persistent maintenance mode can be enabled, which redirects all non-admin users to a dedicated maintenance page while allowing admins to log in and access the full site.
• validation.py Built-in and Custom Validation:
  • The library features a ValidationManager with pre-built validators for common tasks like checking password strength, validating email formats, and confirming that two password fields match.
  • The system is extensible, allowing developers to register their own custom validator functions for specific application needs, such as validating a username format.
• example.py Real-time Validation with HTMX: The validation endpoints are designed to integrate directly with HTMX. This allows for creating responsive user interfaces that provide real-time feedback on form fields as the user types, improving user experience and reducing submission errors.
• oauth.py OAuth Integration:
  • The OAuthManager class simplifies the integration of third-party login providers (e.g., GitHub, Google).
  • It automatically handles the entire OAuth flow, including redirecting the user, processing the callback, creating or retrieving a user in the local database based on the OAuth profile, and managing the user's session.
• example.py, example_oauth.py Complete Examples: The repository includes two fully functional example applications. example.py demonstrates the standard email/password registration and login flow, while example_oauth.py shows how to implement "Login with GitHub" using the OAuthManager.