{"id":29040580,"url":"https://github.com/layinded/xuserauth","last_synced_at":"2026-05-15T13:34:14.459Z","repository":{"id":301035508,"uuid":"1007914103","full_name":"layinded/xUserAuth","owner":"layinded","description":"A modular, production-ready authentication and user management library for FastAPI.","archived":false,"fork":false,"pushed_at":"2025-06-24T20:09:38.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-03T13:43:23.640Z","etag":null,"topics":["fastapi","jwt","jwt-auth","oauth","python","rbac"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/layinded.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-24T18:20:10.000Z","updated_at":"2025-06-24T20:09:41.000Z","dependencies_parsed_at":"2025-06-24T21:25:43.717Z","dependency_job_id":"3d783158-7129-4ce6-8478-4efe5d862b2f","html_url":"https://github.com/layinded/xUserAuth","commit_stats":null,"previous_names":["layinded/xuserauth"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/layinded/xUserAuth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layinded%2FxUserAuth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layinded%2FxUserAuth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layinded%2FxUserAuth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layinded%2FxUserAuth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/layinded","download_url":"https://codeload.github.com/layinded/xUserAuth/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/layinded%2FxUserAuth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33068574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","jwt","jwt-auth","oauth","python","rbac"],"created_at":"2025-06-26T14:36:25.137Z","updated_at":"2026-05-15T13:34:14.423Z","avatar_url":"https://github.com/layinded.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📦 xUserAuth\n\nA modular, production-ready authentication and user management library for FastAPI.\n\n**Supports:**\n\n* JWT-based auth (access, refresh, email verification, password reset)\n* Role-based access control (RBAC)\n* Password hashing\n* Google OAuth integration\n* Custom user model support\n\n---\n\n## 📌 Installation\n\n```bash\npip install xuserauth\n```\n\nOr for development:\n\n```bash\ngit clone https://github.com/yourusername/xuserauth.git\ncd xuserauth\npip install -e .\n```\n\n---\n\n## 🧠 Core Components\n\n| Module             | Purpose                                   |\n| ------------------ | ----------------------------------------- |\n| `auth_manager.py`  | Central class for managing auth workflows |\n| `jwt_utils.py`     | JWT encoding/decoding helpers             |\n| `hashing.py`       | Password hashing \u0026 verification           |\n| `roles.py`         | Role checking utilities                   |\n| `exceptions.py`    | Standardized auth errors                  |\n| `schemas.py`       | Pydantic base user schemas                |\n| `social/google.py` | Google OAuth2 login/callback              |\n\n---\n\n## 🛠 Setup \u0026 Configuration\n\n### ✅ 1. Define your user model\n\n```python\n# myapp/models.py\nclass User:\n    def __init__(self, id, email, password, is_active=True, roles=[\"user\"], email_verified=False):\n        self.id = id\n        self.email = email\n        self.password = password\n        self.is_active = is_active\n        self.roles = roles\n        self.email_verified = email_verified\n```\n\n### ✅ 2. Define a user loader\n\n```python\nasync def get_user_by_id(user_id: str):\n    # Replace with your DB query logic\n    return fake_user_db.get(user_id)\n```\n\n### ✅ 3. Initialize `AuthManager`\n\n```python\nfrom xuserauth import AuthManager\nfrom myapp.models import User\n\nauth = AuthManager(\n    user_model=User,\n    jwt_secret=\"your_secret_key_here\",\n    user_loader=get_user_by_id\n)\n```\n\n---\n\n## 🔐 Usage Examples\n\n### 🧪 Register / Hash Password\n\n```python\nhashed = auth.hash_password(\"mypassword\")\n```\n\n### 🔐 Login\n\n```python\nif auth.verify_password(\"mypassword\", user.password):\n    access_token = auth.generate_token(user)\n    refresh_token = auth.generate_refresh_token(user)\n```\n\n### 🔄 Refresh Token\n\n```python\nnew_token = await auth.refresh_access_token(refresh_token)\n```\n\n### 🛡 Protect Routes (Auth + Role)\n\n```python\n@app.get(\"/me\")\n@auth.require_authenticated\nasync def get_profile(user):\n    return {\"email\": user.email, \"roles\": user.roles}\n```\n\n```python\n@app.get(\"/admin\")\n@auth.require_role(\"admin\")\nasync def get_admin_panel(user):\n    return {\"message\": \"Welcome Admin\"}\n```\n\n---\n\n## 📬 Token Types\n\n| Type      | Use                                |\n| --------- | ---------------------------------- |\n| `access`  | Short-lived access token (default) |\n| `refresh` | Refresh token for session renewal  |\n| `email`   | Email verification token           |\n| `reset`   | Password reset token               |\n\n---\n\n## 🧪 Google OAuth Login\n\n### Redirect to Google:\n\n```python\n@app.get(\"/login/google\")\nasync def google_login(request: Request):\n    return await login_with_google(request)\n```\n\n### Google Callback:\n\n```python\n@app.get(\"/auth/google/callback\")\nasync def google_callback(request: Request):\n    user_info = await auth_google_callback(request)\n    # Link or register user in your DB\n```\n\n---\n\n## 🔍 Testing\n\nTests included for:\n\n* JWT creation/verification\n* Password hashing\n* Role-based access\n* Google OAuth\n* Error handling\n\nRun tests:\n\n```bash\npytest test/\n```\n\n---\n\n## ⚠️ Exception Classes\n\n* `InvalidToken`\n* `PermissionDenied`\n* `UserNotFound`\n* `AuthError`\n\n---\n\n## ✅ Schema Examples (Pydantic)\n\n```python\nfrom xuserauth.schemas import UserCreate, UserRead\n\nuser = UserCreate(email=\"a@a.com\", password=\"secure123\")\n```\n\n---\n\n## 📎 Example Folder Structure\n\n```\nyourapp/\n├── main.py\n├── models.py\n├── routes.py\n├── auth/\n│   └── auth_manager.py\n├── utils/\n│   └── hashing.py\n```\n\n---\n\n## 🧩 Roadmap\n\n* ✅ Google login\n* ✅ RBAC\n* ⏳ Facebook login (planned)\n* ⏳ Refresh token rotation\n* ⏳ Database adapters (SQLModel, Tortoise, Prisma)\n\n---\n\n## 📝 License\n\nMIT License © 2025 Aliyu Abdulbasit Ayinde\n\n---","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flayinded%2Fxuserauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flayinded%2Fxuserauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flayinded%2Fxuserauth/lists"}