fasthtml-auth 0.1.0__py3-none-any.whl

fasthtml_auth/__init__.py

@@ -0,0 +1,31 @@
+"""
+FastHTML-Auth: Complete authentication system for FastHTML applications.
+
+Provides user authentication, session management, role-based access control,
+and beautiful UI components out of the box.
+"""
+
+__version__ = "0.1.0"
+__author__ = "John Richmond"
+__email__ = "confusedjohn46@gmail.com"
+
+from .manager import AuthManager
+from .models import User, Session
+from .middleware import AuthBeforeware
+from .database import AuthDatabase
+from .repository import UserRepository
+
+__all__ = [
+    'AuthManager', 
+    'User', 
+    'Session', 
+    'AuthBeforeware',
+    'AuthDatabase',
+    'UserRepository'
+]
+
+# Convenience imports for common usage patterns
+from .manager import AuthManager as Auth  # Shorter alias
+
+# Version info tuple
+VERSION = tuple(map(int, __version__.split('.')))

fasthtml_auth/database.py

@@ -0,0 +1,34 @@
+# auth/database.py
+from fasthtml.common import database
+from pathlib import Path
+
+class AuthDatabase:
+    """Database manager owned by auth system"""
+
+    def __init__(self, db_path="data/app.db"):
+        # Ensure directory exists
+        Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+        # Create database connection
+        self.db = database(db_path)
+        self.db_path = db_path
+        
+        # Table references (will be populated)
+        self.users = None
+        self.sessions = None  # Optional session storage
+        self.audit_log = None  # Optional security audit
+    
+    def initialize_auth_tables(self):
+        from .models import User, Session
+        
+        # Force User to be fully processed as a dataclass
+        import dataclasses
+        if not dataclasses.is_dataclass(User):
+            raise Exception("User is not a proper dataclass!")
+        
+        self.users = self.db.create(User, pk=User.pk)
+
+        return self.db
+    
+    def get_db(self):
+        """Get database instance for app to add tables"""
+        return self.db

fasthtml_auth/forms.py

@@ -0,0 +1,388 @@
+# auth/forms.py
+from fasthtml.common import *
+from monsterui.all import *
+
+
+def create_login_form(error=None, action="/auth/login", redirect_to="/"):
+    """Create login form component with consistent styling"""
+    error_message = None
+    if error == 'invalid':
+        error_message = "Invalid username or password. Please try again."
+    elif error == 'inactive':
+        error_message = "Your account has been deactivated. Please contact support."
+    elif error == 'system':
+        error_message = "System error. Please try again."
+    
+    return DivCentered(
+        Card(
+            CardHeader(
+                H3("Welcome Back", cls="text-center"),
+                Subtitle("Sign in to your account", cls="text-center")
+            ),
+            CardBody(
+                Alert(error_message, cls=AlertT.error) if error_message else None,
+                Form(
+                    LabelInput(
+                        "Username",
+                        id="username",
+                        name="username",
+                        placeholder="Enter your username",
+                        required=True,
+                        autofocus=True
+                    ),
+                    LabelInput(
+                        "Password", 
+                        id="password",
+                        name="password",
+                        type="password",
+                        placeholder="Enter your password",
+                        required=True
+                    ),
+                    Input(type="hidden", name="redirect_to", value=redirect_to),
+                    
+                    Div(
+                        Label(
+                            Input(type="checkbox", name="remember_me"),
+                            " Remember me",
+                            cls="flex items-center text-sm"
+                        ),
+                        cls="mb-4"
+                    ),
+                    
+                    Button("Sign In", type="submit", cls=(ButtonT.primary, "w-full")),
+                    
+                    Div(
+                        A("Forgot password?", href="/auth/forgot", 
+                          cls="text-sm text-muted-foreground hover:underline"),
+                        cls="text-center mt-4"
+                    ),
+                    
+                    method="post",
+                    action=action
+                )
+            ),
+            footer=DivCentered(
+                P("Don't have an account? ", 
+                  A("Register", href="/auth/register", cls="font-medium hover:underline"),
+                  cls="text-sm text-muted-foreground"),
+                cls="p-4"
+            ),
+            cls="w-full max-w-md shadow-lg"
+        ),
+        cls="min-h-screen flex items-center justify-center p-4"
+    )
+
+def create_register_form(error=None, action="/auth/register"):
+    """Create registration form component with same style as login"""
+    error_message = None
+    if error == 'username_taken':
+        error_message = "Username already taken. Please choose another."
+    elif error == 'email_taken':
+        error_message = "Email already registered. Please sign in or use another email."
+    elif error == 'password_mismatch':
+        error_message = "Passwords do not match. Please try again."
+    elif error == 'password_weak':
+        error_message = "Password must be at least 8 characters long."
+    elif error == 'invalid_email':
+        error_message = "Please enter a valid email address."
+    elif error == 'creation_failed':
+        error_message = "Failed to create account. Please try again."
+    
+    return DivCentered(
+        Card(
+            CardHeader(
+                H3("Create Account", cls="text-center"),
+                Subtitle("Join us today", cls="text-center")
+            ),
+            CardBody(
+                Alert(error_message, cls=AlertT.error) if error_message else None,
+                Form(
+                    LabelInput(
+                        "Username",
+                        id="username",
+                        name="username",
+                        placeholder="Choose a username",
+                        required=True,
+                        autofocus=True,
+                        pattern="[a-zA-Z0-9_]{3,20}",
+                        title="3-20 characters, letters, numbers and underscore only"
+                    ),
+                    
+                    LabelInput(
+                        "Email",
+                        id="email",
+                        name="email",
+                        type="email",
+                        placeholder="your@email.com",
+                        required=True
+                    ),
+                    
+                    LabelInput(
+                        "Password", 
+                        id="password",
+                        name="password",
+                        type="password",
+                        placeholder="Choose a strong password (8+ characters)",
+                        required=True,
+                        minlength=8
+                    ),
+                    
+                    LabelInput(
+                        "Confirm Password", 
+                        id="confirm_password",
+                        name="confirm_password",
+                        type="password",
+                        placeholder="Re-enter your password",
+                        required=True,
+                        minlength=8
+                    ),
+                    
+                    Div(
+                        Label(
+                            Input(type="checkbox", name="accept_terms", required=True),
+                            " I accept the Terms and Conditions",
+                            cls="flex items-center text-sm"
+                        ),
+                        cls="mb-4"
+                    ),
+                    
+                    Button("Create Account", type="submit", cls=(ButtonT.primary, "w-full")),
+                    
+                    method="post",
+                    action=action
+                )
+            ),
+            footer=DivCentered(
+                P("Already have an account? ", 
+                  A("Sign In", href="/auth/login", cls="font-medium hover:underline"),
+                  cls="text-sm text-muted-foreground"),
+                cls="p-4"
+            ),
+            cls="w-full max-w-md shadow-lg"
+        ),
+        cls="min-h-screen flex items-center justify-center p-4"
+    )
+
+def create_forgot_password_form(error=None, success=None, action="/auth/forgot"):
+    """Create password reset request form with same style"""
+    error_message = None
+    success_message = None
+    
+    if error == 'user_not_found':
+        error_message = "No account found with that email address."
+    elif error == 'send_failed':
+        error_message = "Failed to send reset email. Please try again."
+    
+    if success == 'sent':
+        success_message = "Password reset instructions have been sent to your email."
+    
+    return DivCentered(
+        Card(
+            CardHeader(
+                H3("Reset Password", cls="text-center"),
+                Subtitle("We'll send you reset instructions", cls="text-center")
+            ),
+            CardBody(
+                Alert(error_message, cls=AlertT.error) if error_message else None,
+                Alert(success_message, cls=AlertT.success) if success_message else None,
+                
+                Form(
+                    LabelInput(
+                        "Email Address",
+                        id="email",
+                        name="email",
+                        type="email",
+                        placeholder="your@email.com",
+                        required=True,
+                        autofocus=True
+                    ),
+                    
+                    Button("Send Reset Link", type="submit", cls=(ButtonT.primary, "w-full")),
+                    
+                    method="post",
+                    action=action
+                ) if not success_message else Div(
+                    P("Check your email for further instructions.", cls="text-center text-muted-foreground")
+                ),
+                
+                DivCentered(
+                    A("← Back to Sign In", href="/auth/login", 
+                      cls=(ButtonT.secondary, "mt-4"))
+                )
+            ),
+            cls="w-full max-w-md shadow-lg"
+        ),
+        cls="min-h-screen flex items-center justify-center p-4"
+    )
+
+def create_reset_password_form(token, error=None, action="/auth/reset"):
+    """Create password reset form (after clicking email link)"""
+    error_message = None
+    
+    if error == 'invalid_token':
+        error_message = "Invalid or expired reset token. Please request a new one."
+    elif error == 'password_mismatch':
+        error_message = "Passwords do not match. Please try again."
+    elif error == 'password_weak':
+        error_message = "Password must be at least 8 characters long."
+    
+    return DivCentered(
+        Card(
+            CardHeader(
+                H3("Choose New Password", cls="text-center"),
+                Subtitle("Enter your new password below", cls="text-center")
+            ),
+            CardBody(
+                Alert(error_message, cls=AlertT.error) if error_message else None,
+                
+                Form(
+                    Input(type="hidden", name="token", value=token),
+                    
+                    LabelInput(
+                        "New Password", 
+                        id="password",
+                        name="password",
+                        type="password",
+                        placeholder="Enter new password (8+ characters)",
+                        required=True,
+                        minlength=8,
+                        autofocus=True
+                    ),
+                    
+                    LabelInput(
+                        "Confirm New Password", 
+                        id="confirm_password",
+                        name="confirm_password",
+                        type="password",
+                        placeholder="Re-enter new password",
+                        required=True,
+                        minlength=8
+                    ),
+                    
+                    Button("Reset Password", type="submit", cls=(ButtonT.primary, "w-full")),
+                    
+                    method="post",
+                    action=action
+                )
+            ),
+            footer=DivCentered(
+                P("Remember your password? ", 
+                  A("Sign In", href="/auth/login", cls="font-medium hover:underline"),
+                  cls="text-sm text-muted-foreground"),
+                cls="p-4"
+            ),
+            cls="w-full max-w-md shadow-lg"
+        ),
+        cls="min-h-screen flex items-center justify-center p-4"
+    )
+
+def create_profile_form(user, success=None, error=None, action="/auth/profile"):
+    """Create profile edit form for logged-in users"""
+    return Container(
+        DivFullySpaced(
+            H1("Profile Settings"),
+            A("← Back to Dashboard", href="/", cls=ButtonT.secondary)
+        ),
+        
+        Grid(
+            Card(
+                CardHeader(H3("Account Information")),
+                CardBody(
+                    Alert("Profile updated successfully!", cls=AlertT.success) if success else None,
+                    Alert(error, cls=AlertT.error) if error else None,
+                    
+                    Form(
+                        Grid(
+                            LabelInput(
+                                "Username",
+                                value=user.username,
+                                disabled=True,
+                                cls="bg-muted"
+                            ),
+                            LabelInput(
+                                "Email",
+                                name="email",
+                                type="email",
+                                value=user.email,
+                                required=True
+                            ),
+                            cols=1, cols_md=2
+                        ),
+                        
+                        Hr(cls="my-6"),
+                        
+                        H4("Change Password", cls="text-lg font-semibold mb-4"),
+                        
+                        LabelInput(
+                            "Current Password",
+                            name="current_password",
+                            type="password",
+                            placeholder="Enter current password to change"
+                        ),
+                        
+                        Grid(
+                            LabelInput(
+                                "New Password",
+                                name="new_password",
+                                type="password",
+                                placeholder="Enter new password (8+ chars)",
+                                minlength=8
+                            ),
+                            LabelInput(
+                                "Confirm New Password",
+                                name="confirm_password",
+                                type="password",
+                                placeholder="Confirm new password",
+                                minlength=8
+                            ),
+                            cols=1, cols_md=2
+                        ),
+                        
+                        DivRAligned(
+                            Button("Save Changes", type="submit", cls=ButtonT.primary),
+                            cls="mt-6"
+                        ),
+                        
+                        method="post",
+                        action=action
+                    )
+                )
+            ),
+            
+            Card(
+                CardHeader(H3("Account Details")),
+                CardBody(
+                    Div(
+                        InfoRow("Username", user.username),
+                        InfoRow("Role", user.role.title()),
+                        InfoRow("Status", "Active" if user.active else "Inactive"),
+                        InfoRow("Member Since", user.created_at[:10] if user.created_at else "Unknown"),
+                        InfoRow("Last Login", user.last_login[:10] if user.last_login else "Never"),
+                        cls="space-y-3"
+                    )
+                )
+            ),
+            
+            cols=1, cols_lg=2
+        ),
+        cls=ContainerT.xl
+    )
+
+def InfoRow(label, value):
+    """Helper for info display in profile"""
+    return DivFullySpaced(
+        Span(label, cls="font-medium"),
+        Span(str(value), cls="text-muted-foreground")
+    )
+
+# Utility function for consistent error/success messaging
+def create_message_alert(message, type="info"):
+    """Create consistent alert messages"""
+    alert_class = {
+        "error": AlertT.error,
+        "success": AlertT.success,
+        "warning": AlertT.warning,
+        "info": AlertT.info
+    }.get(type, AlertT.info)
+    
+    return Alert(message, cls=alert_class)

fasthtml_auth/manager.py

@@ -0,0 +1,78 @@
+from fasthtml.common import *
+from monsterui.all import *
+from dataclasses import dataclass
+from .middleware import AuthBeforeware
+from .database import AuthDatabase
+from .repository import UserRepository
+from .routes import AuthRoutes
+from .models import User
+
+class AuthManager:
+    """ A class to manage user authentication and route access for fasthtml apps.  Intended to be
+    modular to enable easy re-use
+
+    Methods:
+        initialize: Initialize the auth system and database
+        create_beforeware: Create authentication middleware  
+        register_routes: Register authentication routes
+        require_role: Decorator for role-based access control
+        require_admin: Decorator for admin-only access
+        get_user: Get user by username 
+
+    """
+    def __init__(self, db_path="data/app.db", config=None):
+        self.config = config or {}
+        self.auth_db = AuthDatabase(db_path)
+        self.middleware = AuthBeforeware(self, self.config)
+        self.db=None
+        self.routes = {}  # Store route references
+        self.user_repo = None
+        self.route_handler = AuthRoutes(self)
+
+    def initialize(self):
+        """Initialise the auth system"""
+        # Create tables
+        self.db = self.auth_db.initialize_auth_tables()
+
+        # Create repo to manage users
+        self.user_repo = UserRepository(self.db)
+
+        # Create default admin
+        self._create_default_admin()
+
+        admin = self.get_user('admin')
+        (f"Admin User class: {type(admin)}")
+        print(f"Are they the same class? {type(admin) is User}")    
+        
+        return self.db
+    
+    def create_beforeware(self, additional_public_paths=None):
+        return self.middleware.create_beforeware(additional_public_paths)
+
+    def require_role(self, *roles):
+        """Get role requirement decorator"""
+        return self.middleware.require_role(*roles)
+
+    def require_admin(self):
+        """Get admin requirement decorator"""
+        return self.middleware.require_admin()
+
+    def get_user(self, username: str):
+        return self.user_repo.get_by_username(username)
+    
+    def register_routes(self, app, prefix='/auth'):
+        """Delegate to route handler"""
+        return self.route_handler.register_all(app, prefix)
+    
+    # Create default admin
+    def _create_default_admin(self):
+        """Create default admin if needed"""
+        if not self.user_repo.get_by_username('admin'):
+            self.user_repo.create(
+                username='admin',
+                email='admin@system.local',
+                password='admin123',  # Will be hashed by repository
+                role='admin'
+            )
+    
+

fasthtml_auth/middleware.py

@@ -0,0 +1,105 @@
+from fasthtml.common import *
+from typing import Optional, List
+
+class AuthBeforeware:
+    """Authentication middleware for fastHTML"""
+
+    def __init__(self, auth_manager, config=None):
+        self.auth_manager = auth_manager
+        self.config = config or {}
+
+        # Configure paths
+        login_path = '/auth/login'
+        self.login_path = self.config.get("login_path", login_path)
+        self.public_paths = self.config.get("public_paths", [])
+        # Static files patterns
+        self.static_patterns = [
+            r'/favicon\.ico',
+            r'/static/.*',
+            r'.*\.css',
+            r'.*\.js',
+            r'.*\.png',
+            r'.*\.jpg',
+            r'.*\.jpeg',
+            r'.*\.gif',
+            r'.*\.svg',
+        ]
+
+    def create_beforeware(self, additional_public_paths=None):
+        """Create beforeware for fastHTML"""
+        skip_patterns = self._build_skip_patterns(additional_paths=additional_public_paths)
+
+        # Create Beforeware authentication check function
+        def auth_check(req, sess):
+            """Check authentication prior to check"""
+            auth_username = sess.get('auth')
+
+            if not auth_username:
+                # No auth, redirect to login
+                return RedirectResponse(self.login_path, status_code=303)
+            
+            # Verify user is still valid
+            user = self.auth_manager.get_user(auth_username)
+            if not user or not user.active:
+                # Invalid user, clear session and redirect
+                sess.clear()
+                return RedirectResponse(self.login_path, status_code=303)
+            
+            # Add user info to request scope for route handlers
+            req.scope['auth'] = auth_username
+            req.scope['user'] = user
+            req.scope['user.id'] = user.id
+            req.scope['user_role'] = user.role
+            req.scope['user_is_admin'] = user.role == "admin"
+
+        # Return configured Beforeware
+        return Beforeware(auth_check, skip=skip_patterns)
+
+
+    def _build_skip_patterns(self, additional_paths=None) -> list:
+        """Build list of paths to skip auth check"""
+
+        skip = []
+
+        # Static files
+        skip.extend(self.static_patterns)
+
+        # Auth routes
+        skip.extend([
+            '/auth/login', 
+            '/auth/register',
+            '/auth/forgot',
+            '/auth/reset'
+        ])
+
+        # Configured public paths
+        skip.extend(self.public_paths)
+
+        # Additional paths from caller
+        if additional_paths:
+            skip.extend(additional_paths)
+
+        # Health check and api endpoints
+        skip.extend([
+            "/health",
+            "/api/public"
+        ])
+
+        return skip
+    
+    def require_admin(self):
+        """Decorator for paths requiting admin role to access"""
+        return self.require_role('admin')
+    
+    def require_role(self, *allowed_roles):
+        """Decorator to require a specific role"""
+        def decorator(func):
+            def wrapper(req, *args, **kwargs):
+                user = req.scope.get('user')
+                if not user or user.role not in allowed_roles:
+                    return Response("Forbidden", status_code=403)
+                return func(req, *args, **kwargs)
+            return wrapper
+        return decorator
+
+