| Name | fasthtml-auth JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | Complete authentication system for FastHTML applications with beautiful UI, role-based access control, and session management |
| upload_time | 2025-09-12 08:22:21 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2024 John Richmond
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
fasthtml
authentication
web
framework
auth
login
session
bcrypt
monsterui
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# FastHTML-Auth
**Complete authentication system for FastHTML applications with built-in admin interface**
Drop-in authentication with beautiful UI, role-based access control, and a powerful admin dashboard for user management. No configuration required – just install and go!
```bash
pip install fasthtml-auth
```
[](https://badge.fury.io/py/fasthtml-auth)
[](https://www.python.org/downloads/)
---
## ⭐ Key Features
- 🔐 **Complete Authentication** - Login, logout, registration with secure bcrypt hashing
- 👑 **Built-in Admin Interface** - Full user management dashboard (NEW!)
- 🎨 **Beautiful UI** - Responsive MonsterUI components, zero custom CSS needed
- 🛡️ **Role-Based Access** - User, Manager, Admin roles with decorators
- 📱 **Mobile Ready** - Works perfectly on all devices
- ⚡ **Zero Config** - Works out of the box, customize as needed
---
## 🚀 Quick Start
### Basic Authentication
```python
from fasthtml.common import *
from monsterui.all import *
from fasthtml_auth import AuthManager
# Initialize auth system
auth = AuthManager(db_path="data/app.db")
db = auth.initialize()
beforeware = auth.create_beforeware()
# Create app
app = FastHTML(before=beforeware, hdrs=Theme.blue.headers())
auth.register_routes(app)
@app.route("/")
def dashboard(req):
user = req.scope['user'] # Automatically available
return H1(f"Welcome, {user.username}!")
@app.route("/admin")
@auth.require_admin()
def admin_only(req):
return H1("Admin Area")
serve()
```
**That's it!** Your app now has:
- Login/logout at `/auth/login` and `/auth/logout`
- User registration at `/auth/register`
- Profile management at `/auth/profile`
- Role-based access control
- Default admin account: `admin` / `admin123`
---
## 👑 Built-in Admin Interface
Enable powerful user management with one parameter:
```python
# Add this one parameter to get a complete admin dashboard
auth.register_routes(app, include_admin=True)
```
**Instantly adds:**
| Feature | Route | Description |
|---------|-------|-------------|
| 📊 **Admin Dashboard** | `/auth/admin` | User statistics and quick actions |
| 👥 **User Management** | `/auth/admin/users` | List, search, filter all users |
| ➕ **Create Users** | `/auth/admin/users/create` | Add users with role assignment |
| ✏️ **Edit Users** | `/auth/admin/users/edit?id={id}` | Modify details, roles, status |
| 🗑️ **Delete Users** | `/auth/admin/users/delete?id={id}` | Remove users (with protection) |
### Admin Interface Features
- **🔍 Search & Filter** - Find users by username, email, role, or status
- **📄 Pagination** - Handle thousands of users efficiently
- **🛡️ Safety Features** - Prevent self-deletion and last admin removal
- **📊 Statistics Dashboard** - User counts by role and status
- **🎨 Beautiful UI** - Consistent MonsterUI design throughout
---
## 📖 Real-World Example
See **FastHTML-Auth** in action with a complete todo application:
**[📝 FastHTML Todo App](https://github.com/fromLittleAcorns/fasthtml_todo)**
This real-world example shows:
- User authentication and registration
- Role-based task management
- Admin interface for user management
- Database integration patterns
- Production deployment setup
---
## ⚙️ Configuration
```python
config = {
'allow_registration': True, # Enable user registration
'public_paths': ['/about', '/api'], # Routes that skip authentication
'login_path': '/auth/login', # Custom login URL
}
auth = AuthManager(db_path="data/app.db", config=config)
```
## 🔐 Role-Based Access Control
### Built-in Roles
- **`user`** - Basic authenticated access
- **`manager`** - Manager privileges + user access
- **`admin`** - Full system access + admin interface
### Route Protection
```python
# Require specific roles
@app.route("/manager-area")
@auth.require_role('manager', 'admin')
def manager_view(req):
return H1("Manager+ Only")
# Admin only (shortcut)
@app.route("/admin")
@auth.require_admin()
def admin_panel(req):
return H1("Admin Only")
# Check roles in templates
@app.route("/dashboard")
def dashboard(req):
user = req.scope['user']
admin_link = A("Admin Panel", href="/auth/admin") if user.role == 'admin' else None
return Div(admin_link)
```
## 📊 User Object
In protected routes, access user data via `req.scope['user']`:
```python
user.id # Unique user ID
user.username # Username
user.email # Email address
user.role # 'user', 'manager', or 'admin'
user.active # Boolean - account status
user.created_at # Account creation timestamp
user.last_login # Last login timestamp
```
## 🎨 Styling & Themes
FastHTML-Auth uses [MonsterUI](https://github.com/answerdotai/monsterui) for beautiful, responsive components:
```python
# Choose your theme
app = FastHTML(
before=beforeware,
hdrs=Theme.blue.headers() # or red, green, slate, etc.
)
```
All forms include professional styling, validation, error handling, and mobile optimization.
## 🛠️ API Reference
### AuthManager
```python
auth = AuthManager(db_path="data/app.db", config={})
auth.initialize() # Set up database
auth.register_routes(app, include_admin=True) # Add all routes
auth.create_beforeware() # Create middleware
@auth.require_admin() # Admin-only decorator
@auth.require_role('manager', 'admin') # Role-based decorator
```
### Available Routes
**Authentication Routes:**
- `GET/POST /auth/login` - User login
- `GET /auth/logout` - Logout and redirect
- `GET/POST /auth/register` - User registration
- `GET/POST /auth/profile` - Profile management
**Admin Routes** (when `include_admin=True`):
- `GET /auth/admin` - Admin dashboard
- `GET /auth/admin/users` - User management
- `GET/POST /auth/admin/users/create` - Create user
- `GET/POST /auth/admin/users/edit?id={id}` - Edit user
- `GET/POST /auth/admin/users/delete?id={id}` - Delete user
## 📁 Examples
For complete examples, see the `/examples` directory:
- [`basic_app.py`](examples/basic_app.py) - Simple authentication setup
- [`example_with_admin.py`](examples/example_with_admin.py) - Full admin interface demo
- [**FastHTML Todo App**](https://github.com/fromLittleAcorns/fasthtml_todo) - Real-world application
## 🔒 Security Features
- **Bcrypt password hashing** - Industry standard security
- **Session management** - Secure session handling with FastHTML
- **Remember me functionality** - Optional persistent sessions
- **Role-based protection** - Automatic route access control
- **Admin safety** - Prevent self-deletion and last admin removal
- **Input validation** - Server-side validation for all forms
## 📦 Installation & Dependencies
```bash
pip install fasthtml-auth
```
**Dependencies:**
- `python-fasthtml>=0.12.0` - Web framework
- `monsterui>=1.0.20` - UI components
- `fastlite>=0.2.0` - Database ORM
- `bcrypt>=4.0.0` - Password hashing
## 🤝 Contributing
We welcome contributions! Areas for contribution:
- Password reset functionality
- Two-factor authentication
- OAuth integration (Google, GitHub)
- Email verification
- Bulk user operations
- Custom user fields
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 📝 Changelog
### v0.2.0 (Current Release)
- ✅ Built-in admin interface for user management
- ✅ User CRUD operations with beautiful UI
- ✅ Dashboard with user statistics
- ✅ Search, filter, and pagination
- ✅ Safety features for admin operations
### v0.1.2
- ✅ "Remember me" functionality
- ✅ Terms acceptance validation
- ✅ Improved form styling
### v0.1.0
- ✅ Initial release with core authentication
- ✅ Role-based access control
- ✅ MonsterUI integration
---
**FastHTML-Auth** - Authentication made simple for FastHTML applications.
For questions and support: [GitHub Issues](https://github.com/fromlittleacorns/fasthtml-auth/issues)
Raw data
{
"_id": null,
"home_page": null,
"name": "fasthtml-auth",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "John Richmond <confusedjohn46@gmail.com>",
"keywords": "fasthtml, authentication, web, framework, auth, login, session, bcrypt, monsterui",
"author": null,
"author_email": "John Richmond <confusedjohn46@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/be/21/9cfa575b0b16e1994d612c3f7c5e86d6ebe13e389168607199b4aac16c4c/fasthtml_auth-0.2.0.tar.gz",
"platform": null,
"description": "# FastHTML-Auth\n\n**Complete authentication system for FastHTML applications with built-in admin interface**\n\nDrop-in authentication with beautiful UI, role-based access control, and a powerful admin dashboard for user management. No configuration required \u2013 just install and go!\n\n```bash\npip install fasthtml-auth\n```\n\n[](https://badge.fury.io/py/fasthtml-auth)\n[](https://www.python.org/downloads/)\n\n---\n\n## \u2b50 Key Features\n\n- \ud83d\udd10 **Complete Authentication** - Login, logout, registration with secure bcrypt hashing\n- \ud83d\udc51 **Built-in Admin Interface** - Full user management dashboard (NEW!)\n- \ud83c\udfa8 **Beautiful UI** - Responsive MonsterUI components, zero custom CSS needed\n- \ud83d\udee1\ufe0f **Role-Based Access** - User, Manager, Admin roles with decorators\n- \ud83d\udcf1 **Mobile Ready** - Works perfectly on all devices\n- \u26a1 **Zero Config** - Works out of the box, customize as needed\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### Basic Authentication\n\n```python\nfrom fasthtml.common import *\nfrom monsterui.all import *\nfrom fasthtml_auth import AuthManager\n\n# Initialize auth system\nauth = AuthManager(db_path=\"data/app.db\")\ndb = auth.initialize()\nbeforeware = auth.create_beforeware()\n\n# Create app\napp = FastHTML(before=beforeware, hdrs=Theme.blue.headers())\nauth.register_routes(app)\n\n@app.route(\"/\")\ndef dashboard(req):\n user = req.scope['user'] # Automatically available\n return H1(f\"Welcome, {user.username}!\")\n\n@app.route(\"/admin\")\n@auth.require_admin()\ndef admin_only(req):\n return H1(\"Admin Area\")\n\nserve()\n```\n\n**That's it!** Your app now has:\n- Login/logout at `/auth/login` and `/auth/logout`\n- User registration at `/auth/register`\n- Profile management at `/auth/profile`\n- Role-based access control\n- Default admin account: `admin` / `admin123`\n\n---\n\n## \ud83d\udc51 Built-in Admin Interface\n\nEnable powerful user management with one parameter:\n\n```python\n# Add this one parameter to get a complete admin dashboard\nauth.register_routes(app, include_admin=True)\n```\n\n**Instantly adds:**\n\n| Feature | Route | Description |\n|---------|-------|-------------|\n| \ud83d\udcca **Admin Dashboard** | `/auth/admin` | User statistics and quick actions |\n| \ud83d\udc65 **User Management** | `/auth/admin/users` | List, search, filter all users |\n| \u2795 **Create Users** | `/auth/admin/users/create` | Add users with role assignment |\n| \u270f\ufe0f **Edit Users** | `/auth/admin/users/edit?id={id}` | Modify details, roles, status |\n| \ud83d\uddd1\ufe0f **Delete Users** | `/auth/admin/users/delete?id={id}` | Remove users (with protection) |\n\n### Admin Interface Features\n\n- **\ud83d\udd0d Search & Filter** - Find users by username, email, role, or status\n- **\ud83d\udcc4 Pagination** - Handle thousands of users efficiently \n- **\ud83d\udee1\ufe0f Safety Features** - Prevent self-deletion and last admin removal\n- **\ud83d\udcca Statistics Dashboard** - User counts by role and status\n- **\ud83c\udfa8 Beautiful UI** - Consistent MonsterUI design throughout\n\n---\n\n## \ud83d\udcd6 Real-World Example\n\nSee **FastHTML-Auth** in action with a complete todo application:\n\n**[\ud83d\udcdd FastHTML Todo App](https://github.com/fromLittleAcorns/fasthtml_todo)**\n\nThis real-world example shows:\n- User authentication and registration\n- Role-based task management\n- Admin interface for user management\n- Database integration patterns\n- Production deployment setup\n\n---\n\n## \u2699\ufe0f Configuration\n\n```python\nconfig = {\n 'allow_registration': True, # Enable user registration\n 'public_paths': ['/about', '/api'], # Routes that skip authentication \n 'login_path': '/auth/login', # Custom login URL\n}\n\nauth = AuthManager(db_path=\"data/app.db\", config=config)\n```\n\n## \ud83d\udd10 Role-Based Access Control\n\n### Built-in Roles\n- **`user`** - Basic authenticated access\n- **`manager`** - Manager privileges + user access\n- **`admin`** - Full system access + admin interface\n\n### Route Protection\n```python\n# Require specific roles\n@app.route(\"/manager-area\")\n@auth.require_role('manager', 'admin')\ndef manager_view(req):\n return H1(\"Manager+ Only\")\n\n# Admin only (shortcut)\n@app.route(\"/admin\")\n@auth.require_admin()\ndef admin_panel(req):\n return H1(\"Admin Only\")\n\n# Check roles in templates\n@app.route(\"/dashboard\")\ndef dashboard(req):\n user = req.scope['user']\n \n admin_link = A(\"Admin Panel\", href=\"/auth/admin\") if user.role == 'admin' else None\n return Div(admin_link)\n```\n\n## \ud83d\udcca User Object\n\nIn protected routes, access user data via `req.scope['user']`:\n\n```python\nuser.id # Unique user ID \nuser.username # Username\nuser.email # Email address\nuser.role # 'user', 'manager', or 'admin'\nuser.active # Boolean - account status\nuser.created_at # Account creation timestamp\nuser.last_login # Last login timestamp\n```\n\n## \ud83c\udfa8 Styling & Themes\n\nFastHTML-Auth uses [MonsterUI](https://github.com/answerdotai/monsterui) for beautiful, responsive components:\n\n```python\n# Choose your theme\napp = FastHTML(\n before=beforeware,\n hdrs=Theme.blue.headers() # or red, green, slate, etc.\n)\n```\n\nAll forms include professional styling, validation, error handling, and mobile optimization.\n\n## \ud83d\udee0\ufe0f API Reference\n\n### AuthManager\n```python\nauth = AuthManager(db_path=\"data/app.db\", config={})\nauth.initialize() # Set up database\nauth.register_routes(app, include_admin=True) # Add all routes\nauth.create_beforeware() # Create middleware\n\n@auth.require_admin() # Admin-only decorator\n@auth.require_role('manager', 'admin') # Role-based decorator\n```\n\n### Available Routes\n\n**Authentication Routes:**\n- `GET/POST /auth/login` - User login\n- `GET /auth/logout` - Logout and redirect \n- `GET/POST /auth/register` - User registration\n- `GET/POST /auth/profile` - Profile management\n\n**Admin Routes** (when `include_admin=True`):\n- `GET /auth/admin` - Admin dashboard\n- `GET /auth/admin/users` - User management\n- `GET/POST /auth/admin/users/create` - Create user\n- `GET/POST /auth/admin/users/edit?id={id}` - Edit user\n- `GET/POST /auth/admin/users/delete?id={id}` - Delete user\n\n## \ud83d\udcc1 Examples\n\nFor complete examples, see the `/examples` directory:\n\n- [`basic_app.py`](examples/basic_app.py) - Simple authentication setup\n- [`example_with_admin.py`](examples/example_with_admin.py) - Full admin interface demo\n- [**FastHTML Todo App**](https://github.com/fromLittleAcorns/fasthtml_todo) - Real-world application\n\n## \ud83d\udd12 Security Features\n\n- **Bcrypt password hashing** - Industry standard security\n- **Session management** - Secure session handling with FastHTML\n- **Remember me functionality** - Optional persistent sessions\n- **Role-based protection** - Automatic route access control\n- **Admin safety** - Prevent self-deletion and last admin removal\n- **Input validation** - Server-side validation for all forms\n\n## \ud83d\udce6 Installation & Dependencies\n\n```bash\npip install fasthtml-auth\n```\n\n**Dependencies:**\n- `python-fasthtml>=0.12.0` - Web framework\n- `monsterui>=1.0.20` - UI components \n- `fastlite>=0.2.0` - Database ORM\n- `bcrypt>=4.0.0` - Password hashing\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Areas for contribution:\n\n- Password reset functionality\n- Two-factor authentication \n- OAuth integration (Google, GitHub)\n- Email verification\n- Bulk user operations\n- Custom user fields\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83d\udcdd Changelog\n\n### v0.2.0 (Current Release)\n- \u2705 Built-in admin interface for user management\n- \u2705 User CRUD operations with beautiful UI\n- \u2705 Dashboard with user statistics\n- \u2705 Search, filter, and pagination\n- \u2705 Safety features for admin operations\n\n### v0.1.2\n- \u2705 \"Remember me\" functionality\n- \u2705 Terms acceptance validation\n- \u2705 Improved form styling\n\n### v0.1.0\n- \u2705 Initial release with core authentication\n- \u2705 Role-based access control\n- \u2705 MonsterUI integration\n\n---\n\n**FastHTML-Auth** - Authentication made simple for FastHTML applications.\n\nFor questions and support: [GitHub Issues](https://github.com/fromlittleacorns/fasthtml-auth/issues)\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2024 John Richmond\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Complete authentication system for FastHTML applications with beautiful UI, role-based access control, and session management",
"version": "0.2.0",
"project_urls": {
"Changelog": "https://github.com/fromLittleAcorns/fasthtml-auth/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/fromLittleAcorns/fasthtml-auth#readme",
"Homepage": "https://github.com/fromLittleAcorns/fasthtml-auth",
"Issues": "https://github.com/fromLittleAcorns/fasthtml-auth/issues",
"Repository": "https://github.com/fromLittleAcorns/fasthtml-toolkit"
},
"split_keywords": [
"fasthtml",
" authentication",
" web",
" framework",
" auth",
" login",
" session",
" bcrypt",
" monsterui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ddeb6909be5efd3fd9c68e65704afb0737dc5acec66e31b47ef31ecbd92c18b1",
"md5": "2e1ca7ed58b81c418b5e4d3de3d1acb1",
"sha256": "93d33b92bc269212481f91a2a79b7b2b1ddcea8d638ae35debc67f959bc3a405"
},
"downloads": -1,
"filename": "fasthtml_auth-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2e1ca7ed58b81c418b5e4d3de3d1acb1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25920,
"upload_time": "2025-09-12T08:22:20",
"upload_time_iso_8601": "2025-09-12T08:22:20.571443Z",
"url": "https://files.pythonhosted.org/packages/dd/eb/6909be5efd3fd9c68e65704afb0737dc5acec66e31b47ef31ecbd92c18b1/fasthtml_auth-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "be219cfa575b0b16e1994d612c3f7c5e86d6ebe13e389168607199b4aac16c4c",
"md5": "8745e9bffa8c53b7ceb6ce6fca848913",
"sha256": "fe2ed422ecd11f60acbd4143acc99f929034a3e7df553385f23448e89563eabb"
},
"downloads": -1,
"filename": "fasthtml_auth-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "8745e9bffa8c53b7ceb6ce6fca848913",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 30398,
"upload_time": "2025-09-12T08:22:21",
"upload_time_iso_8601": "2025-09-12T08:22:21.980413Z",
"url": "https://files.pythonhosted.org/packages/be/21/9cfa575b0b16e1994d612c3f7c5e86d6ebe13e389168607199b4aac16c4c/fasthtml_auth-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 08:22:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fromLittleAcorns",
"github_project": "fasthtml-auth",
"github_not_found": true,
"lcname": "fasthtml-auth"
}
