jengolabs-auth 0.1.0__tar.gz

jengolabs_auth-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+node_modules
+dist
+.next
+.turbo
+.env
+.env.local
+.env.*.local
+*.log
+.DS_Store
+coverage
+.vercel

jengolabs_auth-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: jengolabs-auth
+Version: 0.1.0
+Summary: Python SDK for Jengo Auth — session verification, FastAPI middleware, and role-based access control
+Project-URL: Repository, https://github.com/jengolabs/jen-auth
+Project-URL: Documentation, https://github.com/jengolabs/jen-auth/blob/main/docs/dx/DX.md
+Author: Jengo Labs
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: uvicorn>=0.30.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# jengolabs-auth
+
+Python SDK for [Jengo Auth](https://github.com/jengolabs/jen-auth) — session verification, FastAPI middleware, and role-based access control.
+
+## Install
+
+```bash
+pip install jengolabs-auth[fastapi]
+```
+
+## Quick Start (FastAPI)
+
+### Option 1: Dependency Injection
+
+```python
+from fastapi import FastAPI, Depends
+from jengolabs_auth import AuthClient, AuthClientConfig
+from jengolabs_auth.fastapi import require_auth, require_app_role
+
+auth_client = AuthClient(AuthClientConfig(
+    auth_server_url="http://localhost:4000",
+    tenant_api_key="your-tenant-api-key",
+    app_slug="my-service",
+    cache_ttl_seconds=30,
+))
+
+app = FastAPI()
+
+@app.get("/api/me")
+async def get_me(session=require_auth(auth_client)):
+    return {"id": session.user.id, "email": session.user.email}
+
+@app.delete("/api/resource/{resource_id}")
+async def delete_resource(
+    resource_id: str,
+    session=require_app_role("admin", auth_client=auth_client),
+):
+    return {"deleted": resource_id}
+```
+
+### Option 2: Middleware
+
+```python
+from fastapi import FastAPI, Request
+from jengolabs_auth import AuthClient, AuthClientConfig
+from jengolabs_auth.fastapi import JengoAuthMiddleware
+
+auth_client = AuthClient(AuthClientConfig(
+    auth_server_url="http://localhost:4000",
+    tenant_api_key="your-tenant-api-key",
+    app_slug="my-service",
+))
+
+app = FastAPI()
+app.add_middleware(
+    JengoAuthMiddleware,
+    auth_client=auth_client,
+    public_paths=["/health", "/docs", "/openapi.json"],
+)
+
+@app.get("/api/me")
+async def get_me(request: Request):
+    user = request.state.auth_user
+    return {"id": user.id, "email": user.email}
+```
+
+### Option 3: Manual Verification
+
+```python
+from jengolabs_auth import AuthClient, AuthClientConfig, AuthenticationError
+
+auth_client = AuthClient(AuthClientConfig(
+    auth_server_url="http://localhost:4000",
+    tenant_api_key="your-tenant-api-key",
+    app_slug="my-service",
+))
+
+async def verify_token(token: str):
+    try:
+        session = await auth_client.verify_session(f"Bearer {token}")
+        return session.user
+    except AuthenticationError:
+        return None
+```
+
+## Models
+
+All models are Pydantic v2 and support both snake_case and camelCase fields:
+
+| Model | Fields |
+|---|---|
+| `AuthUser` | id, email, name, email_verified, image, role, created_at, updated_at |
+| `AuthSessionData` | id, token, expires_at |
+| `AuthAppGrant` | app_slug, role, granted_at |
+| `AuthSessionWithGrant` | user, session, app_grant, organization |
+
+## Session Caching
+
+Enable in-memory caching to reduce auth server calls:
+
+```python
+auth_client = AuthClient(AuthClientConfig(
+    auth_server_url="http://localhost:4000",
+    tenant_api_key="your-tenant-api-key",
+    app_slug="my-service",
+    cache_ttl_seconds=30,  # cache sessions for 30 seconds
+))
+```
+
+## License
+
+MIT

jengolabs_auth-0.1.0/README.md

@@ -0,0 +1,112 @@
+# jengolabs-auth
+
+Python SDK for [Jengo Auth](https://github.com/jengolabs/jen-auth) — session verification, FastAPI middleware, and role-based access control.
+
+## Install
+
+```bash
+pip install jengolabs-auth[fastapi]
+```
+
+## Quick Start (FastAPI)
+
+### Option 1: Dependency Injection
+
+```python
+from fastapi import FastAPI, Depends
+from jengolabs_auth import AuthClient, AuthClientConfig
+from jengolabs_auth.fastapi import require_auth, require_app_role
+
+auth_client = AuthClient(AuthClientConfig(
+    auth_server_url="http://localhost:4000",
+    tenant_api_key="your-tenant-api-key",
+    app_slug="my-service",
+    cache_ttl_seconds=30,
+))
+
+app = FastAPI()
+
+@app.get("/api/me")
+async def get_me(session=require_auth(auth_client)):
+    return {"id": session.user.id, "email": session.user.email}
+
+@app.delete("/api/resource/{resource_id}")
+async def delete_resource(
+    resource_id: str,
+    session=require_app_role("admin", auth_client=auth_client),
+):
+    return {"deleted": resource_id}
+```
+
+### Option 2: Middleware
+
+```python
+from fastapi import FastAPI, Request
+from jengolabs_auth import AuthClient, AuthClientConfig
+from jengolabs_auth.fastapi import JengoAuthMiddleware
+
+auth_client = AuthClient(AuthClientConfig(
+    auth_server_url="http://localhost:4000",
+    tenant_api_key="your-tenant-api-key",
+    app_slug="my-service",
+))
+
+app = FastAPI()
+app.add_middleware(
+    JengoAuthMiddleware,
+    auth_client=auth_client,
+    public_paths=["/health", "/docs", "/openapi.json"],
+)
+
+@app.get("/api/me")
+async def get_me(request: Request):
+    user = request.state.auth_user
+    return {"id": user.id, "email": user.email}
+```
+
+### Option 3: Manual Verification
+
+```python
+from jengolabs_auth import AuthClient, AuthClientConfig, AuthenticationError
+
+auth_client = AuthClient(AuthClientConfig(
+    auth_server_url="http://localhost:4000",
+    tenant_api_key="your-tenant-api-key",
+    app_slug="my-service",
+))
+
+async def verify_token(token: str):
+    try:
+        session = await auth_client.verify_session(f"Bearer {token}")
+        return session.user
+    except AuthenticationError:
+        return None
+```
+
+## Models
+
+All models are Pydantic v2 and support both snake_case and camelCase fields:
+
+| Model | Fields |
+|---|---|
+| `AuthUser` | id, email, name, email_verified, image, role, created_at, updated_at |
+| `AuthSessionData` | id, token, expires_at |
+| `AuthAppGrant` | app_slug, role, granted_at |
+| `AuthSessionWithGrant` | user, session, app_grant, organization |
+
+## Session Caching
+
+Enable in-memory caching to reduce auth server calls:
+
+```python
+auth_client = AuthClient(AuthClientConfig(
+    auth_server_url="http://localhost:4000",
+    tenant_api_key="your-tenant-api-key",
+    app_slug="my-service",
+    cache_ttl_seconds=30,  # cache sessions for 30 seconds
+))
+```
+
+## License
+
+MIT

jengolabs_auth-0.1.0/jengolabs_auth/__init__.py

@@ -0,0 +1,24 @@
+from jengolabs_auth.client import AuthClient, AuthClientConfig
+from jengolabs_auth.errors import AuthenticationError, AuthorizationError, AuthTransportError
+from jengolabs_auth.models import (
+    AuthAppGrant,
+    AuthOrganization,
+    AuthSession,
+    AuthSessionData,
+    AuthSessionWithGrant,
+    AuthUser,
+)
+
+__all__ = [
+    "AuthClient",
+    "AuthClientConfig",
+    "AuthenticationError",
+    "AuthTransportError",
+    "AuthorizationError",
+    "AuthAppGrant",
+    "AuthOrganization",
+    "AuthSession",
+    "AuthSessionData",
+    "AuthSessionWithGrant",
+    "AuthUser",
+]

jengolabs_auth-0.1.0/jengolabs_auth/client.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Callable
+
+import httpx
+
+from jengolabs_auth.errors import AuthenticationError, AuthTransportError
+from jengolabs_auth.models import AuthSessionWithGrant
+
+
+@dataclass(frozen=True)
+class AuthClientConfig:
+    auth_server_url: str
+    tenant_api_key: str
+    app_slug: str
+    cache_ttl_seconds: float = 0
+    timeout_seconds: float = 5.0
+    on_error: Callable[[Exception], None] | None = None
+
+
+@dataclass
+class _CacheEntry:
+    session: AuthSessionWithGrant
+    expires_at: float
+
+
+class AuthClient:
+    def __init__(self, config: AuthClientConfig) -> None:
+        self._config = config
+        self._cache: dict[str, _CacheEntry] = {}
+        self._http = httpx.AsyncClient(
+            base_url=config.auth_server_url,
+            timeout=config.timeout_seconds,
+        )
+
+    async def verify_session(self, bearer_token_or_cookie: str) -> AuthSessionWithGrant:
+        cached = self._get_from_cache(bearer_token_or_cookie)
+        if cached is not None:
+            return cached
+
+        is_bearer = bearer_token_or_cookie.startswith("Bearer ")
+        headers: dict[str, str] = {
+            "X-Tenant-Key": self._config.tenant_api_key,
+            "X-App-Slug": self._config.app_slug,
+        }
+
+        if is_bearer:
+            headers["Authorization"] = bearer_token_or_cookie
+        else:
+            headers["Cookie"] = bearer_token_or_cookie
+
+        try:
+            response = await self._http.get("/api/auth/session", headers=headers)
+        except httpx.HTTPError as exc:
+            error = AuthTransportError()
+            if self._config.on_error:
+                self._config.on_error(error)
+            raise error from exc
+
+        if response.status_code != 200:
+            error = AuthenticationError("Invalid or expired session")
+            if self._config.on_error:
+                self._config.on_error(error)
+            raise error
+
+        session = AuthSessionWithGrant.model_validate(response.json())
+        self._set_cache(bearer_token_or_cookie, session)
+        return session
+
+    def clear_cache(self) -> None:
+        self._cache.clear()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AuthClient:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()
+
+    def _get_from_cache(self, key: str) -> AuthSessionWithGrant | None:
+        if self._config.cache_ttl_seconds <= 0:
+            return None
+
+        entry = self._cache.get(key)
+        if entry is None:
+            return None
+
+        if time.monotonic() > entry.expires_at:
+            del self._cache[key]
+            return None
+
+        return entry.session
+
+    def _set_cache(self, key: str, session: AuthSessionWithGrant) -> None:
+        if self._config.cache_ttl_seconds <= 0:
+            return
+
+        self._cache[key] = _CacheEntry(
+            session=session,
+            expires_at=time.monotonic() + self._config.cache_ttl_seconds,
+        )

jengolabs_auth-0.1.0/jengolabs_auth/errors.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+
+class AuthenticationError(Exception):
+    status_code = 401
+
+    def __init__(self, message: str = "Authentication required") -> None:
+        self.message = message
+        super().__init__(self.message)
+
+
+class AuthTransportError(AuthenticationError):
+    """Raised when the auth server cannot be reached (network / timeout).
+
+    Distinct from AuthenticationError so callers can return 503 instead
+    of 401 and avoid leaking connectivity details to clients.
+    """
+
+    status_code = 503
+
+    def __init__(self, message: str = "Authentication service unavailable") -> None:
+        super().__init__(message)
+
+
+class AuthorizationError(Exception):
+    status_code = 403
+
+    def __init__(self, message: str = "Insufficient permissions") -> None:
+        self.message = message
+        super().__init__(self.message)

jengolabs_auth-0.1.0/jengolabs_auth/fastapi/__init__.py

@@ -0,0 +1,13 @@
+from jengolabs_auth.fastapi.dependencies import (
+    AuthDependencies,
+    require_app_role,
+    require_auth,
+)
+from jengolabs_auth.fastapi.middleware import JengoAuthMiddleware
+
+__all__ = [
+    "AuthDependencies",
+    "JengoAuthMiddleware",
+    "require_app_role",
+    "require_auth",
+]

jengolabs_auth-0.1.0/jengolabs_auth/fastapi/dependencies.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Callable
+
+from fastapi import Depends, Request
+from fastapi.exceptions import HTTPException
+
+from jengolabs_auth.client import AuthClient
+from jengolabs_auth.errors import AuthenticationError, AuthorizationError, AuthTransportError
+from jengolabs_auth.models import AuthSessionWithGrant
+
+
+class AuthDependencies:
+    def __init__(self, auth_client: AuthClient) -> None:
+        self._auth_client = auth_client
+
+    async def get_session(self, request: Request) -> AuthSessionWithGrant:
+        credential = _extract_credential(request)
+        if credential is None:
+            raise HTTPException(status_code=401, detail="Authentication required")
+
+        try:
+            session = await self._auth_client.verify_session(credential)
+        except AuthTransportError as exc:
+            raise HTTPException(
+                status_code=503, detail="Authentication service unavailable"
+            ) from exc
+        except AuthenticationError as exc:
+            raise HTTPException(status_code=401, detail="Invalid or expired session") from exc
+
+        if session.app_grant is None:
+            raise HTTPException(status_code=403, detail="Access denied for this application")
+
+        return session
+
+    @property
+    def dependency(self) -> Callable[..., AuthSessionWithGrant]:
+        return self.get_session
+
+
+def require_auth(auth_client: AuthClient) -> Callable[..., AuthSessionWithGrant]:
+    deps = AuthDependencies(auth_client)
+    return Depends(deps.get_session)
+
+
+def require_app_role(
+    *allowed_roles: str,
+    auth_client: AuthClient,
+) -> Callable[..., AuthSessionWithGrant]:
+    deps = AuthDependencies(auth_client)
+
+    async def _check_role(
+        request: Request,
+    ) -> AuthSessionWithGrant:
+        session = await deps.get_session(request)
+
+        if session.app_grant is None or session.app_grant.role not in allowed_roles:
+            raise HTTPException(
+                status_code=403,
+                detail=f"Required role: {' or '.join(allowed_roles)}",
+            )
+
+        return session
+
+    return Depends(_check_role)
+
+
+def _extract_credential(request: Request) -> str | None:
+    auth_header = request.headers.get("Authorization")
+    if auth_header and auth_header.startswith("Bearer "):
+        return auth_header
+
+    cookie_header = request.headers.get("Cookie")
+    if cookie_header:
+        return cookie_header
+
+    return None

jengolabs_auth-0.1.0/jengolabs_auth/fastapi/middleware.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from jengolabs_auth.client import AuthClient
+from jengolabs_auth.errors import AuthenticationError
+
+
+class JengoAuthMiddleware(BaseHTTPMiddleware):
+    def __init__(
+        self,
+        app: object,
+        auth_client: AuthClient,
+        public_paths: list[str] | None = None,
+    ) -> None:
+        super().__init__(app)  # type: ignore[arg-type]
+        self._auth_client = auth_client
+        self._public_paths = public_paths or []
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        if self._is_public(request.url.path):
+            return await call_next(request)
+
+        credential = self._extract_credential(request)
+        if credential is None:
+            return JSONResponse({"error": "Authentication required"}, status_code=401)
+
+        try:
+            session = await self._auth_client.verify_session(credential)
+        except AuthenticationError:
+            return JSONResponse({"error": "Invalid or expired session"}, status_code=401)
+
+        if session.app_grant is None:
+            return JSONResponse({"error": "Access denied for this application"}, status_code=403)
+
+        request.state.auth_user = session.user
+        request.state.auth_session = session.session
+        request.state.auth_app_grant = session.app_grant
+        request.state.auth_organization = session.organization
+
+        return await call_next(request)
+
+    def _is_public(self, path: str) -> bool:
+        return any(path.startswith(p) for p in self._public_paths)
+
+    @staticmethod
+    def _extract_credential(request: Request) -> str | None:
+        auth_header = request.headers.get("Authorization")
+        if auth_header and auth_header.startswith("Bearer "):
+            return auth_header
+
+        cookie_header = request.headers.get("Cookie")
+        if cookie_header:
+            return cookie_header
+
+        return None

jengolabs_auth-0.1.0/jengolabs_auth/models.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class AuthUser(BaseModel):
+    id: str
+    email: str
+    name: str
+    email_verified: bool = Field(alias="emailVerified")
+    image: str | None = None
+    role: str | None = None
+    created_at: str = Field(alias="createdAt")
+    updated_at: str = Field(alias="updatedAt")
+
+    model_config = {"populate_by_name": True}
+
+
+class AuthSessionData(BaseModel):
+    id: str
+    token: str
+    expires_at: str = Field(alias="expiresAt")
+
+    model_config = {"populate_by_name": True}
+
+
+class AuthAppGrant(BaseModel):
+    app_slug: str = Field(alias="appSlug")
+    role: str
+    granted_at: str = Field(alias="grantedAt")
+
+    model_config = {"populate_by_name": True}
+
+
+class AuthOrganizationInfo(BaseModel):
+    id: str
+    name: str
+    role: str
+
+
+class AuthSession(BaseModel):
+    user: AuthUser
+    session: AuthSessionData
+
+
+class AuthSessionWithGrant(AuthSession):
+    app_grant: AuthAppGrant | None = Field(default=None, alias="appGrant")
+    organization: AuthOrganizationInfo | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class AuthOrganization(BaseModel):
+    id: str
+    name: str
+    slug: str
+    role: str
+    members: list[OrganizationMember]
+
+
+class OrganizationMember(BaseModel):
+    user_id: str = Field(alias="userId")
+    role: str
+
+    model_config = {"populate_by_name": True}
+
+
+AuthOrganization.model_rebuild()

jengolabs_auth-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jengolabs-auth"
+version = "0.1.0"
+description = "Python SDK for Jengo Auth — session verification, FastAPI middleware, and role-based access control"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Jengo Labs" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100.0"]
+all = ["fastapi>=0.100.0"]
+dev = [
+    "fastapi>=0.100.0",
+    "uvicorn>=0.30.0",
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "ruff>=0.8.0",
+    "mypy>=1.13.0",
+]
+
+[project.urls]
+Repository = "https://github.com/jengolabs/jen-auth"
+Documentation = "https://github.com/jengolabs/jen-auth/blob/main/docs/dx/DX.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["jengolabs_auth"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "TCH"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"