verge-auth-sdk 0.1.18__py3-none-any.whl

verge_auth_sdk/__init__.py

@@ -0,0 +1,12 @@
+# verge_auth_sdk/__init__.py
+"""
+verge_auth_sdk package public API.
+Exports:
+ - add_central_auth(app)  -> middleware to attach to FastAPI app
+ - get_secret(name)       -> secret retrieval helper
+"""
+from .middleware import add_central_auth
+from .secret_provider import get_secret
+from .verge_routes import verge_internal_routes
+
+__all__ = ["add_central_auth", "get_secret", "verge_internal_routes"]

verge_auth_sdk/middleware.py

@@ -0,0 +1,140 @@
+from fastapi import FastAPI, Request
+from fastapi.responses import RedirectResponse, JSONResponse
+import httpx
+import os
+
+from .secret_provider import get_secret
+from .verge_routes import router as verge_routes_router
+
+REGISTERED_ROUTES = []
+
+
+def add_central_auth(app: FastAPI):
+
+    AUTH_INTROSPECT_URL = os.getenv("AUTH_INTROSPECT_URL")
+    AUTH_LOGIN_URL = os.getenv("AUTH_LOGIN_URL")
+
+    CLIENT_ID = os.getenv("VERGE_CLIENT_ID")
+    CLIENT_SECRET = os.getenv("VERGE_CLIENT_SECRET")
+
+    SERVICE_NAME = os.getenv("SERVICE_NAME")
+    SERVICE_BASE_URL = os.getenv("SERVICE_BASE_URL")
+    AUTH_REGISTER_URL = os.getenv("AUTH_REGISTER_URL")
+
+    VERGE_SECRET = get_secret("VERGE_SERVICE_SECRET")
+
+    # ---------------------------------------
+    # INTERNAL ROUTES (MUST LOAD FIRST)
+    # ---------------------------------------
+    app.include_router(verge_routes_router)
+
+    # ---------------------------------------
+    # STARTUP — ONLY COLLECT ROUTES (NO REGISTER)
+    # ---------------------------------------
+    @app.on_event("startup")
+    async def collect_routes():
+        print("🔥 Verge bootstrap started")
+        REGISTERED_ROUTES.clear()
+
+        for route in app.routes:
+            path = getattr(route, "path", None)
+            methods = getattr(route, "methods", [])
+
+            if not path:
+                continue
+
+            if path.startswith(("/docs", "/openapi", "/__verge__")):
+                continue
+
+            for m in methods:
+                if m in ("GET", "POST", "PUT", "PATCH", "DELETE"):
+                    REGISTERED_ROUTES.append({"path": path, "method": m})
+
+        print("✅ Collected Routes:", REGISTERED_ROUTES)
+
+    # ---------------------------------------
+    # SUPER ADMIN TRIGGERED REGISTRATION
+    # ---------------------------------------
+    async def register_with_auth():
+        print("🔧 Triggered register_with_auth()")
+        print("📍 AUTH_REGISTER_URL =", AUTH_REGISTER_URL)
+        print("📍 SERVICE_NAME =", SERVICE_NAME)
+        print("📍 SERVICE_BASE_URL =", SERVICE_BASE_URL)
+        print("📍 CLIENT_ID =", CLIENT_ID)
+        print("📍 ROUTES =", REGISTERED_ROUTES)
+        try:
+            async with httpx.AsyncClient(timeout=20) as client:
+                resp = await client.post(
+                    AUTH_REGISTER_URL,
+                    params={
+                        "name": SERVICE_NAME,
+                        "base_url": SERVICE_BASE_URL,
+                        "client_id": CLIENT_ID,
+                        "client_secret": CLIENT_SECRET
+                    },
+                    headers={"X-Verge-Service-Secret": VERGE_SECRET}
+                )
+
+            print(f"📡 Registration: {resp.status_code}")
+            print(resp.text)
+
+        except Exception as e:
+            print("❌ Registration failed:", e)
+
+    # ---------------------------------------
+    # MIDDLEWARE AUTH
+    # ---------------------------------------
+    @app.middleware("http")
+    async def central_auth(request: Request, call_next):
+        path = request.url.path
+
+        # Whitelisted paths
+        if path.startswith("/__verge__") or path in {"/docs", "/openapi.json", "/health"}:
+            return await call_next(request)
+
+        # Extract token
+        token = None
+        auth_header = request.headers.get("authorization")
+
+        if auth_header and auth_header.lower().startswith("bearer "):
+            token = auth_header.split(" ")[1]
+
+        if not token:
+            token = request.cookies.get("access_token")
+
+        # redirect if HTML request
+        if not token and "text/html" in request.headers.get("accept", ""):
+            return RedirectResponse(
+                f"{AUTH_LOGIN_URL}?redirect_url={request.url}"
+            )
+
+        if not token:
+            return JSONResponse({"detail": "Unauthorized"}, status_code=401)
+
+        # Validate token
+        try:
+            async with httpx.AsyncClient(timeout=4) as client:
+                res = await client.post(
+                    AUTH_INTROSPECT_URL,
+                    headers={
+                        "Authorization": f"Bearer {token}",
+                        "X-Client-Id": CLIENT_ID,
+                        "X-Client-Secret": CLIENT_SECRET,
+                    },
+                )
+                data = res.json()
+
+        except Exception:
+            return JSONResponse({"detail": "Auth service unreachable"}, status_code=503)
+
+        if not data.get("active"):
+            return JSONResponse({"detail": "Session expired"}, status_code=401)
+
+        user = data.get("user", {})
+        request.state.user = user
+
+        # ----------------------------------------------
+        # ⭐ ANY authenticated user triggers auto-registration
+        # ----------------------------------------------
+        print("🔐 Authenticated user → auto-registering service")
+        await register_with_auth()

verge_auth_sdk/secret_provider.py

@@ -0,0 +1,65 @@
+import os
+from functools import lru_cache
+
+
+# ----- Internal provider functions -----
+def _from_env(name: str) -> str:
+    return os.getenv(name)
+
+
+def _from_aws(name: str) -> str:
+    raise NotImplementedError("AWS secret provider not implemented yet")
+
+
+def _from_azure(name: str) -> str:
+    raise NotImplementedError("Azure secret provider not implemented yet")
+
+
+def _from_gcp(name: str) -> str:
+    raise NotImplementedError("GCP secret provider not implemented yet")
+
+
+def _from_oracle(name: str) -> str:
+    raise NotImplementedError("Oracle secret provider not implemented yet")
+
+
+# ----- Main entry point -----
+@lru_cache(maxsize=128)
+def get_secret(name: str) -> str:
+    """
+    Universal secret provider supporting:
+    - Local .env
+    - AWS Secrets Manager
+    - Azure Key Vault
+    - Google Cloud Secret Manager
+    - Oracle Cloud Vault
+    """
+
+    provider = os.getenv("SECRETS_PROVIDER", "env").lower()
+
+    try:
+        if provider == "env":
+            return _from_env(name)
+
+        if provider == "aws":
+            return _from_aws(name)
+
+        if provider == "azure":
+            return _from_azure(name)
+
+        if provider == "gcp":
+            return _from_gcp(name)
+
+        if provider == "oracle":
+            return _from_oracle(name)
+
+    except Exception as e:
+        # fallback to environment variables
+        value = os.getenv(name)
+        if value:
+            return value
+        raise Exception(
+            f"Secret '{name}' not found via provider '{provider}': {e}"
+        )
+
+    raise Exception(f"Unknown SECRETS_PROVIDER '{provider}'")

verge_auth_sdk/verge_routes.py

@@ -0,0 +1,98 @@
+from fastapi import APIRouter, Request, HTTPException
+from .secret_provider import get_secret
+import os
+
+router = APIRouter()
+
+SERVICE_NAME = os.getenv("SERVICE_NAME")
+SERVICE_BASE_URL = os.getenv("SERVICE_BASE_URL")
+
+
+@router.get("/__verge__/routes", include_in_schema=False)
+async def verge_internal_routes(request: Request):
+
+    expected_secret = get_secret("VERGE_SERVICE_SECRET")
+    received_secret = request.headers.get("X-Verge-Service-Secret")
+
+    # Enforce exact secret match
+    if not expected_secret or expected_secret != received_secret:
+        raise HTTPException(status_code=403, detail="Forbidden")
+
+    collected = []
+
+    # FastAPI auto-generated system paths you DON'T want to sync
+    INTERNAL_PREFIXES = (
+        "/__verge__",
+        "/openapi",
+        "/docs",
+        "/redoc"
+    )
+
+    for route in request.app.routes:
+        path = getattr(route, "path", None)
+        methods = getattr(route, "methods", [])
+
+        if not path:
+            continue
+
+        # Skip internal/system routes
+        if path.startswith(INTERNAL_PREFIXES):
+            continue
+
+        # Filter HTTP methods
+        for method in methods:
+            if method in ("GET", "POST", "PUT", "PATCH", "DELETE"):
+                collected.append({
+                    "path": path,
+                    "method": method
+                })
+
+    # Sort for consistency (helps prevent duplicate entries in DB)
+    collected.sort(key=lambda r: (r["path"], r["method"]))
+
+    return collected
+
+
+@router.post("/sync/service-routes", include_in_schema=False)
+async def sync_service_routes(request: Request):
+
+    expected_secret = get_secret("VERGE_SERVICE_SECRET")
+    received_secret = request.headers.get("X-Verge-Service-Secret")
+
+    if not expected_secret or expected_secret != received_secret:
+        raise HTTPException(status_code=403, detail="Forbidden")
+
+    collected = []
+
+    INTERNAL_PREFIXES = (
+        "/__verge__",
+        "/openapi",
+        "/docs",
+        "/redoc"
+    )
+
+    # Collect routes from the app
+    for route in request.app.routes:
+        path = getattr(route, "path", None)
+        methods = getattr(route, "methods", [])
+
+        if not path:
+            continue
+
+        if path.startswith(INTERNAL_PREFIXES):
+            continue
+
+        for method in methods:
+            if method in ("GET", "POST", "PUT", "PATCH", "DELETE"):
+                collected.append({
+                    "path": path,
+                    "method": method
+                })
+
+    collected.sort(key=lambda r: (r["path"], r["method"]))
+
+    return {
+        "service": SERVICE_NAME,
+        "base_url": SERVICE_BASE_URL,
+        "routes": collected
+    }

verge_auth_sdk-0.1.18.dist-info/METADATA

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: verge-auth-sdk
+Version: 0.1.18
+Summary: Secure centralized authentication SDK for FastAPI microservices
+Author-email: Verge Infosoft <contactus@vergeinfosoft.com>
+License: MIT
+Project-URL: Homepage, https://www.vergeinfosoft.com
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi
+Requires-Dist: httpx
+Requires-Dist: python-dotenv
+Dynamic: license-file
+
+🔐 Verge Auth SDK
+Secure Identity & Access Management for FastAPI Microservices
+
+Verge Auth SDK is a lightweight integration library that connects your FastAPI microservices to the Verge Auth Platform — a centralized identity, role management, and access-control system built for modern SaaS applications.
+
+With a single line of code, your service is fully protected and becomes part of a unified authentication ecosystem:
+
+from verge_auth_sdk import add_central_auth
+add_central_auth(app)
+
+🚀 What Verge Auth Provides
+
+✓ Centralized Login
+
+Your users authenticate through the Verge Auth hosted login experience.
+
+✓ Role-Based Access Control (RBAC)
+
+Create roles inside the Verge Auth Dashboard and assign access to microservices and their granular operations.
+
+✓ Route-Level Permissions
+
+When a service integrates the SDK, its available routes automatically appear in the Verge Auth dashboard for permissions assignment.
+
+✓ Group & User Management
+
+Assign roles to users or user groups for highly flexible access control.
+
+✓ Secure Communication
+
+All microservice-to-auth communication is secured using service credentials provided during onboarding.
+
+🧭 End-to-End User Flow
+
+1. Account Creation
+
+Users sign up with their organization details, company domain, and email.
+
+2. Email Verification
+
+A verification link is sent from no-reply@vergeinfosoft.com
+.
+Once verified, the user is redirected to the Verge Auth platform.
+
+3. Login
+
+Users can sign in through the “Verge IAM” login page using their verified email and password.
+
+4. Auth Dashboard
+
+Once logged in, the dashboard displays:
+
+Total users
+
+Active groups
+
+Available roles
+
+Audit logs
+
+Permissions overview
+
+🎛 Role-Based Access Control (RBAC)
+
+RBAC inside Verge Auth is designed to be extremely intuitive — while supporting enterprise-level control.
+
+Creating a Role
+
+Inside the Roles section:
+
+Click New Role
+
+Enter the role name (e.g., HR Manager, Operations Admin)
+
+Optional: Add a description
+
+Select the Service you want this role to access
+
+Example: employees-service, billing-service, appointments-service
+
+After selecting a service, the system automatically shows all available routes for that service
+
+Example:
+
+/employees/
+
+/employees/{id}
+
+/employees/create
+
+/employees/update
+
+/employees/delete
+
+Each route is presented with clear CRUD permissions:
+
+Create
+
+Read
+
+Update
+
+Delete
+
+You can either:
+
+Grant Full Access to that service
+
+OR choose granular permissions route-by-route
+
+Save the role
+
+It instantly becomes available for assignment
+
+Role creation modal with a dropdown for service selection and an auto-generated route list for CRUD assignment.
+
+🧑‍🤝‍🧑 Assigning Roles to Users or Groups
+
+After creating a role, you can:
+
+Assign to a User
+
+Go to Manage Users
+
+Edit a user
+
+Select one or more roles
+
+Save changes
+
+Assign to a User Group
+
+Create a group (e.g., HR Team, Finance Department)
+
+Assign roles to the group
+
+Add users into the group
+(they automatically inherit the group’s permissions)
+
+This makes onboarding smoother and keeps role management scalable.
+
+🔌 Integrating the SDK Into a Microservice
+Install from PyPI
+pip install verge_auth_sdk
+
+Add the Middleware
+from fastapi import FastAPI
+from verge_auth_sdk import add_central_auth
+
+app = FastAPI()
+add_central_auth(app)
+
+That’s it.
+The service will now:
+
+✓ Authenticate incoming requests
+✓ Communicate securely with Verge Auth
+✓ Provide user identity + roles
+✓ Automatically register its routes for RBAC assignment
+
+⚙ Environment Configuration
+
+Each service requires a minimal set of environment variables:
+
+######################################################################
+
+AUTH_INTROSPECT_URL=<auth-server-introspection-endpoint>
+AUTH_LOGIN_URL=<auth-server-login-ui>
+
+VERGE_CLIENT_ID=<client-id>
+VERGE_CLIENT_SECRET=<client-secret>
+
+VERGE_SERVICE_SECRET=<service-integration-secret>
+
+# These are provided by Verge Infosoft during onboarding.
+
+# Optional secret provider:
+
+SECRETS_PROVIDER=env # azure | aws
+
+########################################################################
+
+🛡 Middleware Responsibilities
+
+The SDK transparently handles:
+
+User authentication
+
+Role injection
+
+Cookie vs header auth
+
+Unauthorized access responses
+
+Service-level authentication
+
+Route registration
+
+You do not need to implement any auth or RBAC logic manually.
+
+🔐 Security Highlights
+
+RSA-based JWT verification
+
+Centralized session & token lifecycle management
+
+Strong encryption for service credentials
+
+Multi-layer permission checks (Role → Service → Route → Operation)
+
+HTTPS-only communication
+
+Support for cloud key vaults
+
+💼 Ideal For
+
+HRMS, ERP, CRM, Billing platforms
+
+Multi-tenant SaaS applications
+
+Modern microservice architectures
+
+Secure admin dashboards
+
+Enterprise platforms needing consistent access control
+
+🆘 Support & Onboarding
+
+For enterprise onboarding, custom integrations, or troubleshooting:
+
+🌐 Website
+https://www.vergeinfosoft.com
+
+📧 Email
+contactus@vergeinfosoft.com

verge_auth_sdk-0.1.18.dist-info/RECORD

@@ -0,0 +1,9 @@
+verge_auth_sdk/__init__.py,sha256=n76KSaK3CohCP7dzrUXWlTPNPGzWesLTlYl-C7rfW60,411
+verge_auth_sdk/middleware.py,sha256=8bwOOVELZs_yqGuG_OjQnW3P7T0zaF1_Fj_Cvyk0Y_w,5037
+verge_auth_sdk/secret_provider.py,sha256=j89rj9LZHl4qTI2fdf0qnn-mgDD3oTbdP3imsm0S9n8,1653
+verge_auth_sdk/verge_routes.py,sha256=hRPHe32tBEdiAOj7qbfaa4m-obOBfATLSrx6z70xvIY,2773
+verge_auth_sdk-0.1.18.dist-info/licenses/LICENSE,sha256=OLuFd1VUvl1QKIJJ_qJ8zR4ypcDhzeRkEywc7PX2ABQ,1090
+verge_auth_sdk-0.1.18.dist-info/METADATA,sha256=-ETqtoG-z8Rk1fThTUXhO-vv9TKb9XfePAnDGnZLbR0,5702
+verge_auth_sdk-0.1.18.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+verge_auth_sdk-0.1.18.dist-info/top_level.txt,sha256=0ik2K2CJZrP11DvuR7USTYJkX_kv2DSJS5wyhP1yAfA,15
+verge_auth_sdk-0.1.18.dist-info/RECORD,,

verge_auth_sdk-0.1.18.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

verge_auth_sdk-0.1.18.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Verge Infosoft
+
+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 COPYRIGHT HOLDERS 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.

verge_auth_sdk-0.1.18.dist-info/top_level.txt

@@ -0,0 +1 @@
+verge_auth_sdk