devlab-auth 0.1.0__tar.gz

devlab_auth-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Distribution / Packaging
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing & Linting caches
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.coverage
+htmlcov/

devlab_auth-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.5
+Name: devlab-auth
+Version: 0.1.0
+Summary: Universal DevLab Authentication SDK for Python (RS256 JWKS & M2M API Keys with FastAPI guards)
+Author-email: Yuvaraj Pattabi <yuva.devlab@gmail.com>
+Requires-Python: >=3.11
+Requires-Dist: cachetools>=5.3.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyjwt[crypto]>=2.8.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# DevLab Auth — Python SDK
+
+Enterprise-grade authentication SDK and FastAPI security guards for the Yuva DevLab platform ecosystem.
+
+## Features
+- **Strict Typing:** 100% type-annotated with `py.typed` marker (PEP 561) and strict mypy compliance.
+- **RS256 JWKS Verification:** Validates DevLab Portal SSO tokens without network overhead using local in-memory public key caching.
+- **M2M API Key Validation:** Authenticates machine-to-machine callers (`dlk_...`) via DevLab Portal API with local TTL caching.
+- **FastAPI Dependency Injection:** Drop-in `Depends(get_current_principal)`, `require_role`, and `require_scope` guards.
+- **ASGI Middleware:** Global route protection via `DevLabAuthMiddleware`.
+
+## Installation
+```bash
+# Using uv
+uv add devlab-auth
+
+# Using pip
+pip install devlab-auth
+```
+
+## Quickstart (FastAPI)
+```python
+from fastapi import FastAPI, Depends
+from devlab_auth import AuthPrincipal, get_current_principal, require_role
+
+app = FastAPI()
+
+
+@app.get("/api/v1/forecast")
+async def get_forecast(principal: AuthPrincipal = Depends(get_current_principal)):
+    return {
+        "caller_id": principal.id,
+        "is_service": principal.is_m2m,
+        "role": principal.role,
+    }
+
+
+@app.post("/api/v1/admin/purge", dependencies=[Depends(require_role("admin", "super_admin"))])
+async def admin_purge():
+    return {"status": "purged"}
+```
+
+## Development & Verification
+```bash
+# Run test suite
+uv run pytest
+
+# Strict lint check & format
+uv run ruff check .
+uv run ruff format --check .
+
+# Strict typechecking (zero any, strict mode)
+uv run mypy src
+```

devlab_auth-0.1.0/README.md

@@ -0,0 +1,54 @@
+# DevLab Auth — Python SDK
+
+Enterprise-grade authentication SDK and FastAPI security guards for the Yuva DevLab platform ecosystem.
+
+## Features
+- **Strict Typing:** 100% type-annotated with `py.typed` marker (PEP 561) and strict mypy compliance.
+- **RS256 JWKS Verification:** Validates DevLab Portal SSO tokens without network overhead using local in-memory public key caching.
+- **M2M API Key Validation:** Authenticates machine-to-machine callers (`dlk_...`) via DevLab Portal API with local TTL caching.
+- **FastAPI Dependency Injection:** Drop-in `Depends(get_current_principal)`, `require_role`, and `require_scope` guards.
+- **ASGI Middleware:** Global route protection via `DevLabAuthMiddleware`.
+
+## Installation
+```bash
+# Using uv
+uv add devlab-auth
+
+# Using pip
+pip install devlab-auth
+```
+
+## Quickstart (FastAPI)
+```python
+from fastapi import FastAPI, Depends
+from devlab_auth import AuthPrincipal, get_current_principal, require_role
+
+app = FastAPI()
+
+
+@app.get("/api/v1/forecast")
+async def get_forecast(principal: AuthPrincipal = Depends(get_current_principal)):
+    return {
+        "caller_id": principal.id,
+        "is_service": principal.is_m2m,
+        "role": principal.role,
+    }
+
+
+@app.post("/api/v1/admin/purge", dependencies=[Depends(require_role("admin", "super_admin"))])
+async def admin_purge():
+    return {"status": "purged"}
+```
+
+## Development & Verification
+```bash
+# Run test suite
+uv run pytest
+
+# Strict lint check & format
+uv run ruff check .
+uv run ruff format --check .
+
+# Strict typechecking (zero any, strict mode)
+uv run mypy src
+```

devlab_auth-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "devlab-auth"
+version = "0.1.0"
+description = "Universal DevLab Authentication SDK for Python (RS256 JWKS & M2M API Keys with FastAPI guards)"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    { name = "Yuvaraj Pattabi", email = "yuva.devlab@gmail.com" }
+]
+dependencies = [
+    "pyjwt[crypto]>=2.8.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+    "cachetools>=5.3.0",
+]
+
+[project.optional-dependencies]
+fastapi = [
+    "fastapi>=0.100.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.4.0",
+    "mypy>=1.10.0",
+    "fastapi>=0.100.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+    "RUF", # ruff-specific rules
+]
+ignore = [
+    "B008",  # Allow Depends/Header in FastAPI argument defaults
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+show_error_codes = true
+pretty = true
+
+[[tool.mypy.overrides]]
+module = "cachetools.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "jwt.*"
+ignore_missing_imports = true

devlab_auth-0.1.0/src/devlab_auth/__init__.py

@@ -0,0 +1,33 @@
+"""DevLab Authentication SDK for Python (FastAPI, LangChain, Agents)."""
+
+from devlab_auth.client import DevLabAuth
+from devlab_auth.jwks import JwksValidator
+from devlab_auth.m2m import M2mApiKeyValidator
+from devlab_auth.models import AuthPrincipal, M2mValidationResult
+
+__all__ = [
+    "AuthPrincipal",
+    "DevLabAuth",
+    "JwksValidator",
+    "M2mApiKeyValidator",
+    "M2mValidationResult",
+]
+
+try:
+    from devlab_auth.fastapi import (
+        get_current_principal,
+        require_role,
+        require_scope,
+        set_devlab_auth,
+    )
+    from devlab_auth.middleware import DevLabAuthMiddleware
+
+    __all__ += [
+        "DevLabAuthMiddleware",
+        "get_current_principal",
+        "require_role",
+        "require_scope",
+        "set_devlab_auth",
+    ]
+except ImportError:
+    pass

devlab_auth-0.1.0/src/devlab_auth/client.py

@@ -0,0 +1,50 @@
+"""High-level DevLabAuth orchestrator combining JWKS and M2M validation."""
+
+import os
+
+from devlab_auth.jwks import JwksValidator
+from devlab_auth.m2m import M2mApiKeyValidator
+from devlab_auth.models import AuthPrincipal
+
+
+class DevLabAuth:
+    """Primary entry point for DevLab authentication verification."""
+
+    def __init__(
+        self,
+        portal_url: str | None = None,
+        required_app_id: str | None = None,
+        jwks_cache_ttl: int = 3600,
+        m2m_cache_ttl: int = 300,
+    ):
+        self.portal_url = (
+            portal_url or os.getenv("DEVLAB_PORTAL_API_URL") or "http://localhost:4000"
+        )
+        self.jwks_validator = JwksValidator(
+            portal_url=self.portal_url, cache_ttl_seconds=jwks_cache_ttl
+        )
+        self.m2m_validator = M2mApiKeyValidator(
+            portal_url=self.portal_url,
+            cache_ttl_seconds=m2m_cache_ttl,
+            required_app_id=required_app_id,
+        )
+
+    async def authenticate_async(self, credential: str) -> AuthPrincipal:
+        """Dispatches credential to M2M or JWKS validator asynchronously."""
+        cred = credential.strip()
+        if cred.startswith("Bearer "):
+            cred = cred[7:].strip()
+
+        if cred.startswith("dlk_"):
+            return await self.m2m_validator.validate_key_async(cred)
+        return self.jwks_validator.validate_token(cred)
+
+    def authenticate_sync(self, credential: str) -> AuthPrincipal:
+        """Dispatches credential to M2M or JWKS validator synchronously."""
+        cred = credential.strip()
+        if cred.startswith("Bearer "):
+            cred = cred[7:].strip()
+
+        if cred.startswith("dlk_"):
+            return self.m2m_validator.validate_key_sync(cred)
+        return self.jwks_validator.validate_token(cred)

devlab_auth-0.1.0/src/devlab_auth/fastapi.py

@@ -0,0 +1,93 @@
+"""FastAPI dependencies and security guards."""
+
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from fastapi import Header, HTTPException, Security, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from devlab_auth.client import DevLabAuth
+from devlab_auth.models import AuthPrincipal
+
+security = HTTPBearer(auto_error=False)
+_default_auth: DevLabAuth | None = None
+
+
+def get_devlab_auth() -> DevLabAuth:
+    """Resolves or initializes the global DevLabAuth singleton."""
+    global _default_auth
+    if _default_auth is None:
+        _default_auth = DevLabAuth()
+    return _default_auth
+
+
+def set_devlab_auth(auth_instance: DevLabAuth) -> None:
+    """Configures a custom DevLabAuth instance globally."""
+    global _default_auth
+    _default_auth = auth_instance
+
+
+async def get_current_principal(
+    credentials: HTTPAuthorizationCredentials | None = Security(security),
+    x_api_key: str | None = Header(None, alias="x-api-key"),
+    x_devlab_key: str | None = Header(None, alias="x-devlab-key"),
+) -> AuthPrincipal:
+    """Universal FastAPI dependency: resolves user JWT or M2M key."""
+    token = None
+    if credentials and credentials.credentials:
+        token = credentials.credentials.strip()
+    elif x_api_key:
+        token = x_api_key.strip()
+    elif x_devlab_key:
+        token = x_devlab_key.strip()
+
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing authentication credentials (Bearer token or x-api-key)",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    auth = get_devlab_auth()
+    try:
+        return await auth.authenticate_async(token)
+    except PermissionError as pe:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(pe)) from pe
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Authentication failed: {e!s}",
+            headers={"WWW-Authenticate": "Bearer"},
+        ) from e
+
+
+def require_role(*roles: str) -> Callable[..., Coroutine[Any, Any, AuthPrincipal]]:
+    """FastAPI dependency factory enforcing specified roles."""
+
+    async def role_checker(
+        principal: AuthPrincipal = Security(get_current_principal),
+    ) -> AuthPrincipal:
+        if not principal.has_role(*roles):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Insufficient role permissions. Required: {', '.join(roles)}",
+            )
+        return principal
+
+    return role_checker
+
+
+def require_scope(scope: str) -> Callable[..., Coroutine[Any, Any, AuthPrincipal]]:
+    """FastAPI dependency factory enforcing specified permission scope."""
+
+    async def scope_checker(
+        principal: AuthPrincipal = Security(get_current_principal),
+    ) -> AuthPrincipal:
+        if not principal.has_scope(scope):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Missing required permission scope: '{scope}'",
+            )
+        return principal
+
+    return scope_checker

devlab_auth-0.1.0/src/devlab_auth/jwks.py

@@ -0,0 +1,63 @@
+"""RS256 JWKS token validation against DevLab Portal."""
+
+import os
+from typing import Any
+
+import jwt
+from jwt import PyJWKClient
+
+from devlab_auth.models import AuthPrincipal
+
+
+class JwksValidator:
+    """Cryptographic RS256 JWT validator using DevLab Portal JWKS endpoint."""
+
+    def __init__(
+        self,
+        portal_url: str | None = None,
+        jwks_uri: str | None = None,
+        cache_ttl_seconds: int = 3600,
+    ):
+        base_url = portal_url or os.getenv("DEVLAB_PORTAL_API_URL") or "http://localhost:4000"
+        self.jwks_uri = jwks_uri or f"{base_url.rstrip('/')}/.well-known/jwks.json"
+        self._client = PyJWKClient(self.jwks_uri, cache_jwk_set=True, lifespan=cache_ttl_seconds)
+
+    def validate_token(self, token: str) -> AuthPrincipal:
+        """Validates an RS256 JWT and returns the parsed AuthPrincipal."""
+        signing_key = self._client.get_signing_key_from_jwt(token)
+        payload: dict[str, Any] = jwt.decode(
+            token,
+            signing_key.key,
+            algorithms=["RS256"],
+            options={"verify_aud": False},
+        )
+
+        sub = str(payload.get("sub") or payload.get("id") or "")
+        email = payload.get("email")
+        name = payload.get("name")
+        role = payload.get("role")
+        tenant_id = payload.get("tenant_id")
+        app_id = payload.get("app_id")
+
+        raw_scopes = payload.get("scopes") or []
+        if isinstance(raw_scopes, str):
+            scopes = [raw_scopes]
+        elif isinstance(raw_scopes, list):
+            scopes = [str(s) for s in raw_scopes]
+        else:
+            scopes = []
+
+        if role and role not in scopes:
+            scopes.append(role)
+
+        return AuthPrincipal(
+            id=sub,
+            email=email,
+            name=name,
+            role=role,
+            tenant_id=tenant_id,
+            app_id=app_id,
+            scopes=scopes,
+            is_m2m=False,
+            metadata=payload,
+        )

devlab_auth-0.1.0/src/devlab_auth/m2m.py

@@ -0,0 +1,102 @@
+"""Machine-to-Machine (M2M) API key validation against DevLab Portal."""
+
+import os
+from typing import Any
+
+import httpx
+from cachetools import TTLCache
+
+from devlab_auth.models import AuthPrincipal
+
+
+class M2mApiKeyValidator:
+    """Validates DevLab M2M API keys (dlk_...) with in-memory caching."""
+
+    def __init__(
+        self,
+        portal_url: str | None = None,
+        cache_ttl_seconds: int = 300,
+        cache_maxsize: int = 1000,
+        required_app_id: str | None = None,
+    ):
+        base_url = portal_url or os.getenv("DEVLAB_PORTAL_API_URL") or "http://localhost:4000"
+        self.validate_url = f"{base_url.rstrip('/')}/api/v1/api-keys/validate"
+        self.cache: TTLCache[str, AuthPrincipal] = TTLCache(
+            maxsize=cache_maxsize, ttl=cache_ttl_seconds
+        )
+        self.required_app_id = required_app_id
+
+    async def validate_key_async(self, api_key: str) -> AuthPrincipal:
+        """Asynchronously validates an API key, using cache if available."""
+        if api_key in self.cache:
+            return self.cache[api_key]
+
+        async with httpx.AsyncClient(timeout=4.0) as client:
+            response = await client.post(
+                self.validate_url,
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "Content-Type": "application/json",
+                },
+            )
+            if response.status_code != 200:
+                raise ValueError(f"M2M validation failed with status {response.status_code}")
+
+            data = response.json()
+            if not data.get("valid"):
+                raise ValueError(data.get("message") or "Invalid API key")
+
+            principal = self._build_principal(data)
+            self._check_app_id(principal)
+            self.cache[api_key] = principal
+            return principal
+
+    def validate_key_sync(self, api_key: str) -> AuthPrincipal:
+        """Synchronously validates an API key, using cache if available."""
+        if api_key in self.cache:
+            return self.cache[api_key]
+
+        with httpx.Client(timeout=4.0) as client:
+            response = client.post(
+                self.validate_url,
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "Content-Type": "application/json",
+                },
+            )
+            if response.status_code != 200:
+                raise ValueError(f"M2M validation failed with status {response.status_code}")
+
+            data = response.json()
+            if not data.get("valid"):
+                raise ValueError(data.get("message") or "Invalid API key")
+
+            principal = self._build_principal(data)
+            self._check_app_id(principal)
+            self.cache[api_key] = principal
+            return principal
+
+    def _build_principal(self, data: dict[str, Any]) -> AuthPrincipal:
+        scopes = data.get("scopes", [])
+        if isinstance(scopes, str):
+            scopes = [scopes]
+        return AuthPrincipal(
+            id=str(data.get("keyId") or "m2m-key"),
+            name=data.get("name"),
+            app_id=data.get("appId"),
+            role="service",
+            scopes=scopes,
+            is_m2m=True,
+            metadata=data,
+        )
+
+    def _check_app_id(self, principal: AuthPrincipal) -> None:
+        if not self.required_app_id:
+            return
+        if principal.has_scope("*") or principal.has_scope(f"{self.required_app_id}:*"):
+            return
+        if principal.app_id and principal.app_id == self.required_app_id:
+            return
+        raise PermissionError(
+            f"API key belonging to '{principal.app_id}' lacks scope for '{self.required_app_id}'"
+        )

devlab_auth-0.1.0/src/devlab_auth/middleware.py

@@ -0,0 +1,52 @@
+"""Pure ASGI / FastAPI middleware for global request authentication."""
+
+from typing import Any
+
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.responses import JSONResponse
+
+from devlab_auth.client import DevLabAuth
+
+
+class DevLabAuthMiddleware(BaseHTTPMiddleware):
+    """ASGI middleware authenticating requests and injecting 'request.state.principal'."""
+
+    def __init__(
+        self,
+        app: Any,
+        auth: DevLabAuth | None = None,
+        public_paths: set[str] | None = None,
+    ) -> None:
+        super().__init__(app)
+        self.auth = auth or DevLabAuth()
+        self.public_paths = public_paths or {
+            "/health",
+            "/ready",
+            "/docs",
+            "/openapi.json",
+            "/redoc",
+        }
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        if request.url.path in self.public_paths:
+            return await call_next(request)
+
+        header = request.headers.get("Authorization") or request.headers.get("x-api-key")
+        if not header:
+            return JSONResponse(
+                status_code=401,
+                content={"error": "Unauthorized: Missing Authorization Bearer token or x-api-key"},
+            )
+
+        try:
+            principal = await self.auth.authenticate_async(header)
+            request.state.principal = principal
+            return await call_next(request)
+        except PermissionError as pe:
+            return JSONResponse(status_code=403, content={"error": str(pe)})
+        except Exception as e:
+            return JSONResponse(
+                status_code=401,
+                content={"error": f"Authentication rejected: {e!s}"},
+            )

devlab_auth-0.1.0/src/devlab_auth/models.py

@@ -0,0 +1,46 @@
+"""Data models for DevLab authentication principals, tokens, and verification results."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class AuthPrincipal(BaseModel):
+    """Represents an authenticated entity in the DevLab ecosystem."""
+
+    id: str = Field(description="Unique subject or key identifier")
+    email: str | None = Field(default=None, description="User email if user session")
+    name: str | None = Field(default=None, description="Display name if available")
+    role: str | None = Field(default=None, description="User role (operator/admin)")
+    tenant_id: str | None = Field(default=None, description="Workspace or tenant identifier")
+    app_id: str | None = Field(default=None, description="Originating application identifier")
+    scopes: list[str] = Field(default_factory=list, description="Granted permission scopes")
+    is_m2m: bool = Field(default=False, description="True if authenticated via M2M API key")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Raw claims metadata")
+
+    def has_scope(self, required_scope: str) -> bool:
+        """Checks if principal has wildcard '*' or specific scope."""
+        if "*" in self.scopes:
+            return True
+        if required_scope in self.scopes:
+            return True
+        prefix = required_scope.split(":")[0] + ":*"
+        return prefix in self.scopes
+
+    def has_role(self, *required_roles: str) -> bool:
+        """Checks if principal has one of the required roles."""
+        if self.role == "super_admin":
+            return True
+        return bool(self.role and self.role in required_roles)
+
+
+class M2mValidationResult(BaseModel):
+    """Result of an M2M API key validation against DevLab Portal."""
+
+    valid: bool
+    key_id: str | None = None
+    name: str | None = None
+    app_id: str | None = None
+    scopes: list[str] = Field(default_factory=list)
+    rate_limit_rpm: int | None = None
+    error: str | None = None

devlab_auth-0.1.0/src/devlab_auth/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561. This package uses inline types.