verge-auth-sdk 0.1.21__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,216 @@
+from fastapi import FastAPI, Request
+from fastapi.responses import RedirectResponse, JSONResponse
+from .secret_provider import get_secret
+from .verge_routes import router as verge_routes_router
+import httpx
+import os
+import asyncio
+
+REGISTERED_ROUTES = []
+
+
+async def _post_with_retries(client, url, json=None, headers=None, timeout=10, retries=8, backoff=1):
+    last_exc = None
+    for attempt in range(1, retries + 1):
+        try:
+            resp = await client.post(
+                url,
+                json=json,
+                headers=headers,
+                timeout=timeout,
+            )
+            return resp  # success
+        except Exception as e:
+            last_exc = e
+            print(
+                f"❗ Retry {attempt}/{retries} failed for {url}: {type(e).__name__}: {e}")
+            await asyncio.sleep(backoff * attempt)  # linear backoff
+    raise last_exc
+
+
+def add_central_auth(app: FastAPI):
+
+    AUTH_INTROSPECT_URL = os.getenv("AUTH_INTROSPECT_URL")
+    AUTH_LOGIN_URL = os.getenv("AUTH_LOGIN_URL")
+
+    SERVICE_NAME = os.getenv("SERVICE_NAME")
+    SERVICE_BASE_URL = os.getenv("SERVICE_BASE_URL")
+
+    CLIENT_ID = os.getenv("VERGE_CLIENT_ID")
+    CLIENT_SECRET = os.getenv("VERGE_CLIENT_SECRET")
+
+    VERGE_SERVICE_SECRET = get_secret("VERGE_SERVICE_SECRET")
+
+    AUTH_REGISTER_URL = os.getenv("AUTH_REGISTER_URL")
+    AUTH_ROUTE_SYNC_URL = os.getenv("AUTH_ROUTE_SYNC_URL")
+
+    # -----------------------------------------------------------
+    # INTERNAL VERGE ROUTES
+    # -----------------------------------------------------------
+    app.include_router(verge_routes_router)
+
+    # -----------------------------------------------------------
+    # MICROSERVICE BOOTSTRAP ON STARTUP
+    # -----------------------------------------------------------
+    @app.on_event("startup")
+    async def verge_bootstrap():
+        print("🔥 Verge bootstrap started")
+
+        await asyncio.sleep(2)
+
+        REGISTERED_ROUTES.clear()
+
+        print("📌 Collecting routes...")
+
+        for route in app.routes:
+            try:
+                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})
+
+            except Exception as e:
+                print("❌ Error collecting route:", e)
+
+        print("✅ Collected routes:", REGISTERED_ROUTES)
+
+        print("\n📡 Registering service with Auth Service...")
+        # print("SERVICE_NAME =", SERVICE_NAME)
+        # print("SERVICE_BASE_URL =", SERVICE_BASE_URL)
+        # print("AUTH_REGISTER_URL =", AUTH_REGISTER_URL)
+        # print("AUTH_ROUTE_SYNC_URL =", AUTH_ROUTE_SYNC_URL)
+        # print("VERGE_SERVICE_SECRET =",
+        #       VERGE_SERVICE_SECRET if VERGE_SERVICE_SECRET else "MISSING")
+        # print("CLIENT_ID =", CLIENT_ID if CLIENT_ID else "MISSING")
+        # print("CLIENT_SECRET =",
+        #       CLIENT_SECRET if CLIENT_SECRET else "MISSING")
+
+        async with httpx.AsyncClient() as client:
+            if AUTH_REGISTER_URL:
+                try:
+                    resp = await _post_with_retries(
+                        client,
+                        AUTH_REGISTER_URL,
+                        json={"service_name": SERVICE_NAME,
+                              "base_url": SERVICE_BASE_URL},
+                        headers={
+                            "X-Client-Id": CLIENT_ID or "",
+                            "X-Client-Secret": CLIENT_SECRET or "",
+                            "X-Verge-Service-Secret": VERGE_SERVICE_SECRET or "",
+                        },
+                        timeout=10,
+                        retries=8,
+                        backoff=1
+                    )
+                    text = resp.text if hasattr(resp, "text") else await resp.text()
+                    print("📡 Registration response:", resp.status_code, text)
+
+                except Exception as e:
+                    print("❌ Registration ultimately failed:",
+                          type(e).__name__, str(e))
+
+            else:
+                print("⚠️ AUTH_REGISTER_URL missing")
+
+            if AUTH_ROUTE_SYNC_URL:
+                try:
+                    resp = await _post_with_retries(
+                        client,
+                        AUTH_ROUTE_SYNC_URL,
+                        json={
+                            "service_name": SERVICE_NAME,
+                            "base_url": SERVICE_BASE_URL,
+                            "routes": REGISTERED_ROUTES,
+                        },
+                        headers={
+                            "X-Client-Id": CLIENT_ID or "",
+                            "X-Client-Secret": CLIENT_SECRET or "",
+                            "X-Verge-Service-Secret": VERGE_SERVICE_SECRET or "",
+                        },
+                        timeout=20,
+                        retries=8,
+                        backoff=1
+                    )
+                    text = resp.text if hasattr(resp, "text") else await resp.text()
+                    print("📡 Route sync response:", resp.status_code, text)
+
+                except Exception as e:
+                    print("❌ Route sync ultimately failed:",
+                          type(e).__name__, str(e))
+
+            else:
+                print("⚠️ AUTH_ROUTE_SYNC_URL missing")
+
+    # -----------------------------------------------------------
+    # CENTRAL AUTHZ MIDDLEWARE (unchanged)
+    # -----------------------------------------------------------
+    @app.middleware("http")
+    async def central_auth(request: Request, call_next):
+        path = request.url.path
+
+        SKIP_PATHS = {
+            "/health",
+            "/docs",
+            "/openapi.json",
+            "/favicon.ico",
+            "/service-registry/register",
+            "/route-sync",
+            "/__verge__",
+        }
+
+        if path in SKIP_PATHS or path.startswith("/__verge__"):
+            return await call_next(request)
+
+        token = None
+        auth_header = request.headers.get("authorization")
+
+        if auth_header and auth_header.lower().startswith("bearer "):
+            token = auth_header.split(" ", 1)[1].strip()
+
+        if not token:
+            token = request.cookies.get("access_token")
+
+        if not token:
+            if "text/html" in request.headers.get("accept", ""):
+                return RedirectResponse(f"{AUTH_LOGIN_URL}?redirect_url={request.url}")
+            return JSONResponse({"detail": "Unauthorized"}, status_code=401)
+
+        try:
+            async with httpx.AsyncClient(timeout=5) as client:
+                res = await client.post(
+                    AUTH_INTROSPECT_URL,
+                    headers={
+                        "Authorization": f"Bearer {token}",
+                        "X-Client-Id": CLIENT_ID or "",
+                        "X-Client-Secret": CLIENT_SECRET or "",
+                    },
+                )
+                data = res.json()
+        except Exception as e:
+            return JSONResponse({"detail": "Auth service unreachable", "error": str(e)}, status_code=503)
+
+        if not data.get("active"):
+            return JSONResponse({"detail": "Session expired"}, status_code=401)
+
+        request.state.user = data.get("user")
+        permissions = (data.get("roles") or [])
+
+        route_obj = request.scope.get("route")
+        route_path = route_obj.path if route_obj is not None else path
+        method = request.method
+
+        required_key = f"{SERVICE_NAME}:{route_path}:{method}".lower()
+        normalized_permissions = [p.lower() for p in permissions]
+
+        if required_key not in normalized_permissions:
+            return JSONResponse({"detail": "Contact admin for access"}, status_code=403)
+
+        return await call_next(request)

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,55 @@
+from fastapi import APIRouter, Request, HTTPException
+from .secret_provider import get_secret
+
+router = APIRouter()
+
+
+@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")
+    
+    print("expected_secret********", expected_secret)
+    print("received_secret********", received_secret)
+    if not expected_secret or expected_secret != received_secret:
+        print("secrets did not match************")
+
+    # Enforce exact secret match
+    # for debugging stopping secret check 
+    # 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

verge_auth_sdk-0.1.21.dist-info/METADATA

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: verge-auth-sdk
+Version: 0.1.21
+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.21.dist-info/RECORD

@@ -0,0 +1,9 @@
+verge_auth_sdk/__init__.py,sha256=n76KSaK3CohCP7dzrUXWlTPNPGzWesLTlYl-C7rfW60,411
+verge_auth_sdk/middleware.py,sha256=tsh6vUoRqNcBbYTf9m7sBojQZXzJEvlvqvXxFx6-nkM,8268
+verge_auth_sdk/secret_provider.py,sha256=j89rj9LZHl4qTI2fdf0qnn-mgDD3oTbdP3imsm0S9n8,1653
+verge_auth_sdk/verge_routes.py,sha256=IPQHNGK-IiFEb8DmcqiI-PUVagaVi8ZUCTbkwvwi-EU,1728
+verge_auth_sdk-0.1.21.dist-info/licenses/LICENSE,sha256=OLuFd1VUvl1QKIJJ_qJ8zR4ypcDhzeRkEywc7PX2ABQ,1090
+verge_auth_sdk-0.1.21.dist-info/METADATA,sha256=85mYzAHXOOM-gLx_d9Y9wavzHb4Et2jVp8avjPU6huM,5702
+verge_auth_sdk-0.1.21.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+verge_auth_sdk-0.1.21.dist-info/top_level.txt,sha256=0ik2K2CJZrP11DvuR7USTYJkX_kv2DSJS5wyhP1yAfA,15
+verge_auth_sdk-0.1.21.dist-info/RECORD,,

verge_auth_sdk-0.1.21.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.21.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.21.dist-info/top_level.txt

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