cl4im 0.2.0__tar.gz

cl4im-0.2.0/LICENSE

@@ -0,0 +1,26 @@
+CC0 1.0 Universal
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator and
+subsequent owner(s) of an original work of authorship and/or a database
+(each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for the
+purpose of contributing to a commons of creative, cultural and scientific works
+that the public can reliably and without fear of infringement build upon,
+modify, incorporate in other works, cite, and distribute, as freely as
+possible, without legal restriction.
+
+To the greatest extent permitted by, but not in contravention of, applicable
+law, Affirmer hereby overtly, fully, permanently, irrevocably and
+unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
+and Related Rights and associated claims and causes of action, in the Work.
+
+Should any part of this dedication be judged legally invalid or ineffective
+under applicable law, the dedication shall be preserved to the maximum extent
+permitted by law.
+
+For more information, please see:
+https://creativecommons.org/publicdomain/zero/1.0/

cl4im-0.2.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: cl4im
+Version: 0.2.0
+Summary: Python client for the Identora authorizer (OIDC + RBAC)
+Project-URL: Homepage, https://github.com/xlucvvs/cl4im-python
+Project-URL: Repository, https://github.com/xlucvvs/cl4im-python
+Project-URL: Bug Tracker, https://github.com/xlucvvs/cl4im-python/issues
+Author-email: Lucas Ribeiro <lucasribeiro.sec@gmail.com>
+License: CC0 1.0 Universal
+        
+        Statement of Purpose
+        
+        The laws of most jurisdictions throughout the world automatically confer
+        exclusive Copyright and Related Rights (defined below) upon the creator and
+        subsequent owner(s) of an original work of authorship and/or a database
+        (each, a "Work").
+        
+        Certain owners wish to permanently relinquish those rights to a Work for the
+        purpose of contributing to a commons of creative, cultural and scientific works
+        that the public can reliably and without fear of infringement build upon,
+        modify, incorporate in other works, cite, and distribute, as freely as
+        possible, without legal restriction.
+        
+        To the greatest extent permitted by, but not in contravention of, applicable
+        law, Affirmer hereby overtly, fully, permanently, irrevocably and
+        unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
+        and Related Rights and associated claims and causes of action, in the Work.
+        
+        Should any part of this dedication be judged legally invalid or ineffective
+        under applicable law, the dedication shall be preserved to the maximum extent
+        permitted by law.
+        
+        For more information, please see:
+        https://creativecommons.org/publicdomain/zero/1.0/
+License-File: LICENSE
+Keywords: auth,authorization,identora,jwt,oidc,rbac
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyjwt[crypto]>=2.8
+Requires-Dist: python-jose[cryptography]>=3.3
+Provides-Extra: dev
+Requires-Dist: cryptography>=42; extra == 'dev'
+Requires-Dist: django>=4.0; extra == 'dev'
+Requires-Dist: flask>=2.0; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.0; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.111; extra == 'fastapi'
+Requires-Dist: starlette>=0.37; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# cl4im
+
+Python client for the **Identora** authorizer — handles app authentication,
+JWT validation, permission checking and automatic operation sync.
+
+## Installation
+
+```bash
+pip install cl4im
+# With FastAPI support
+pip install "cl4im[fastapi]"
+```
+
+## Quick start with FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from cl4im.adapters.fastapi import Cl4im, operation
+
+app = FastAPI()
+
+cl4im = Cl4im(
+    app,
+    authorizer_url="http://localhost:4000/api",
+    app_id="your-app-uuid",
+    secret="your-app-secret",
+)
+
+
+@app.get("/public")
+@operation(id="public.info", level="public")
+async def public_info():
+    """Anyone can call this — no token needed."""
+    return {"message": "Hello, world!"}
+
+
+@app.get("/items")
+@operation(id="items.list", level="private")
+async def list_items(request: Request):
+    """Requires any authenticated user (token with non-empty groups)."""
+    user = request.state.user  # TokenClaims
+    return {"user": user.sub, "items": []}
+
+
+@app.delete("/items/{item_id}")
+@operation(id="items.delete", level="protected")
+async def delete_item(item_id: str, request: Request):
+    """Requires a user whose group has explicit permission for items.delete."""
+    return {"deleted": item_id}
+```
+
+## Standalone client
+
+```python
+import asyncio
+from cl4im import Cl4imClient, OperationDescriptor
+
+client = Cl4imClient(
+    authorizer_url="http://localhost:4000/api",
+    app_id="your-app-uuid",
+    secret="your-app-secret",
+)
+
+client.register_operation(
+    OperationDescriptor(identifier="items.list", method="read", level="private")
+)
+
+async def main():
+    await client.startup()
+
+    # Validate a token from an incoming request
+    claims = await client.validate_token("<bearer-token>")
+
+    # Check whether the token has permission
+    allowed = client.check_permission(claims, "items.list", "read")
+    print(f"Allowed: {allowed}")
+
+asyncio.run(main())
+```
+
+## Operation levels
+
+| Level       | Who can access |
+|-------------|----------------|
+| `public`    | Everyone — no token required |
+| `private`   | Any authenticated user (token with at least one group) |
+| `protected` | Only users whose groups intersect the operation's `allowed_groups` |
+
+## Method auto-detection
+
+The `@operation` decorator infers the method from the function name:
+
+| Function name prefix/keyword | Detected method |
+|------------------------------|-----------------|
+| `get_`, `list_`, `fetch_`, `read_` | `read` |
+| `delete_`, `remove_`, `destroy_` | `delete` |
+| contains `stream`, `subscribe`, `watch` | `stream` |
+| anything else | `write` |
+
+## Configuration
+
+| Parameter | Description |
+|-----------|-------------|
+| `authorizer_url` | Base URL of Identora, including the API prefix (e.g. `http://host/api`) |
+| `app_id` | UUID of the app registered in `auth.apps` |
+| `secret` | Plain-text app secret (never committed — use env vars) |
+
+```python
+import os
+from cl4im.adapters.fastapi import Cl4im
+
+cl4im = Cl4im(
+    app,
+    authorizer_url=os.environ["AUTHORIZER_URL"],
+    app_id=os.environ["APP_ID"],
+    secret=os.environ["APP_SECRET"],
+)
+```

cl4im-0.2.0/README.md

@@ -0,0 +1,118 @@
+# cl4im
+
+Python client for the **Identora** authorizer — handles app authentication,
+JWT validation, permission checking and automatic operation sync.
+
+## Installation
+
+```bash
+pip install cl4im
+# With FastAPI support
+pip install "cl4im[fastapi]"
+```
+
+## Quick start with FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from cl4im.adapters.fastapi import Cl4im, operation
+
+app = FastAPI()
+
+cl4im = Cl4im(
+    app,
+    authorizer_url="http://localhost:4000/api",
+    app_id="your-app-uuid",
+    secret="your-app-secret",
+)
+
+
+@app.get("/public")
+@operation(id="public.info", level="public")
+async def public_info():
+    """Anyone can call this — no token needed."""
+    return {"message": "Hello, world!"}
+
+
+@app.get("/items")
+@operation(id="items.list", level="private")
+async def list_items(request: Request):
+    """Requires any authenticated user (token with non-empty groups)."""
+    user = request.state.user  # TokenClaims
+    return {"user": user.sub, "items": []}
+
+
+@app.delete("/items/{item_id}")
+@operation(id="items.delete", level="protected")
+async def delete_item(item_id: str, request: Request):
+    """Requires a user whose group has explicit permission for items.delete."""
+    return {"deleted": item_id}
+```
+
+## Standalone client
+
+```python
+import asyncio
+from cl4im import Cl4imClient, OperationDescriptor
+
+client = Cl4imClient(
+    authorizer_url="http://localhost:4000/api",
+    app_id="your-app-uuid",
+    secret="your-app-secret",
+)
+
+client.register_operation(
+    OperationDescriptor(identifier="items.list", method="read", level="private")
+)
+
+async def main():
+    await client.startup()
+
+    # Validate a token from an incoming request
+    claims = await client.validate_token("<bearer-token>")
+
+    # Check whether the token has permission
+    allowed = client.check_permission(claims, "items.list", "read")
+    print(f"Allowed: {allowed}")
+
+asyncio.run(main())
+```
+
+## Operation levels
+
+| Level       | Who can access |
+|-------------|----------------|
+| `public`    | Everyone — no token required |
+| `private`   | Any authenticated user (token with at least one group) |
+| `protected` | Only users whose groups intersect the operation's `allowed_groups` |
+
+## Method auto-detection
+
+The `@operation` decorator infers the method from the function name:
+
+| Function name prefix/keyword | Detected method |
+|------------------------------|-----------------|
+| `get_`, `list_`, `fetch_`, `read_` | `read` |
+| `delete_`, `remove_`, `destroy_` | `delete` |
+| contains `stream`, `subscribe`, `watch` | `stream` |
+| anything else | `write` |
+
+## Configuration
+
+| Parameter | Description |
+|-----------|-------------|
+| `authorizer_url` | Base URL of Identora, including the API prefix (e.g. `http://host/api`) |
+| `app_id` | UUID of the app registered in `auth.apps` |
+| `secret` | Plain-text app secret (never committed — use env vars) |
+
+```python
+import os
+from cl4im.adapters.fastapi import Cl4im
+
+cl4im = Cl4im(
+    app,
+    authorizer_url=os.environ["AUTHORIZER_URL"],
+    app_id=os.environ["APP_ID"],
+    secret=os.environ["APP_SECRET"],
+)
+```

cl4im-0.2.0/cl4im/__init__.py

@@ -0,0 +1,27 @@
+"""cl4im — Python client for the Identora authorizer."""
+
+from .client import Cl4imClient
+from .decorators import operation
+from .exceptions import (
+    Cl4imAuthError,
+    Cl4imConfigError,
+    Cl4imError,
+    Cl4imForbiddenError,
+    Cl4imSyncError,
+    Cl4imTokenError,
+)
+from .models import OperationDescriptor, OperationWithGroups, TokenClaims
+
+__all__ = [
+    "Cl4imClient",
+    "OperationDescriptor",
+    "OperationWithGroups",
+    "TokenClaims",
+    "Cl4imError",
+    "Cl4imAuthError",
+    "Cl4imTokenError",
+    "Cl4imForbiddenError",
+    "Cl4imSyncError",
+    "Cl4imConfigError",
+    "operation",
+]

cl4im-0.2.0/cl4im/adapters/__init__.py

@@ -0,0 +1 @@
+# cl4im adapters

cl4im-0.2.0/cl4im/adapters/django.py

@@ -0,0 +1,145 @@
+"""Django adapter for cl4im."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Callable
+
+from ..client import Cl4imClient
+from ..decorators import get_registry, operation  # re-export
+from ..exceptions import Cl4imTokenError
+from ..models import TokenClaims
+
+__all__ = ["Cl4imMiddleware", "operation"]
+
+
+def _extract_token(request: Any) -> str:
+    """Extract Bearer token from HTTP_AUTHORIZATION."""
+    auth: str = request.META.get("HTTP_AUTHORIZATION", "")
+    scheme, _, token_str = auth.partition(" ")
+    return token_str.strip() if scheme.lower() == "bearer" else ""
+
+
+def _operation_info(view_func: Any) -> tuple[str, str, str] | None:
+    """Return ``(identifier, op_method, level)`` from view metadata, or ``None``."""
+    # Try the function itself, then __wrapped__ (functools.wraps)
+    for candidate in (view_func, getattr(view_func, "__wrapped__", None)):
+        if candidate is None:
+            continue
+        identifier = getattr(candidate, "__cl4im_id__", None)
+        op_method  = getattr(candidate, "__cl4im_method__", None)
+        level      = getattr(candidate, "__cl4im_level__", None)
+        if identifier and op_method and level:
+            return (identifier, op_method, level)
+    return None
+
+
+class Cl4imMiddleware:
+    """Django WSGI middleware for cl4im.
+
+    Uses Django's ``process_view`` hook — which runs *after* URL resolution
+    and receives the matched view function directly — so ``@operation``
+    metadata is always available regardless of middleware order.
+
+    Add to ``MIDDLEWARE`` in ``settings.py``::
+
+        MIDDLEWARE = [
+            ...
+            "cl4im.adapters.django.Cl4imMiddleware",
+            ...
+        ]
+
+    Required Django settings::
+
+        CL4IM_AUTHORIZER_URL = "http://localhost:4000/api"
+        CL4IM_APP_ID          = "<uuid>"
+        CL4IM_SECRET          = "<secret>"
+
+    Mark views with :func:`cl4im.decorators.operation`::
+
+        from django.http import JsonResponse
+        from cl4im.adapters.django import operation
+
+        @operation(id="items.list", level="private")
+        def list_items(request):
+            user = request.cl4im_user  # TokenClaims
+            return JsonResponse({"user": user.sub})
+
+    Args:
+        get_response: The next middleware or view callable (injected by Django).
+    """
+
+    def __init__(self, get_response: Callable[[Any], Any]) -> None:
+        from django.conf import settings
+
+        authorizer_url: str = getattr(settings, "CL4IM_AUTHORIZER_URL", "")
+        realm_id: str       = getattr(settings, "CL4IM_REALM_ID", "")
+        app_id: str         = getattr(settings, "CL4IM_APP_ID", "")
+        secret: str         = getattr(settings, "CL4IM_SECRET", "")
+
+        if not (authorizer_url and realm_id and app_id and secret):
+            raise RuntimeError(
+                "cl4im requires CL4IM_AUTHORIZER_URL, CL4IM_REALM_ID, "
+                "CL4IM_APP_ID and CL4IM_SECRET in Django settings."
+            )
+
+        self.get_response = get_response
+        self.client = Cl4imClient(authorizer_url, realm_id, app_id, secret)
+
+        for op in get_registry():
+            self.client.register_operation(op)
+        asyncio.run(self.client.startup())
+
+    def __call__(self, request: Any) -> Any:
+        """Pass the request through — auth is enforced in process_view."""
+        return self.get_response(request)
+
+    def process_view(
+        self,
+        request: Any,
+        view_func: Any,
+        view_args: Any,
+        view_kwargs: Any,
+    ) -> Any | None:
+        """Enforce authentication and permissions before the view runs.
+
+        Called by Django after URL resolution.  Returns ``None`` to let the
+        view proceed, or an :class:`~django.http.HttpResponse` to
+        short-circuit the request.
+        """
+        from django.http import JsonResponse
+
+        op_info = _operation_info(view_func)
+
+        # No cl4im annotation — pass through
+        if op_info is None:
+            return None
+
+        identifier, op_method, level = op_info
+
+        # Public — no token required
+        if level == "public":
+            return None
+
+        token_str = _extract_token(request)
+
+        if not token_str:
+            return JsonResponse(
+                {"error": "unauthorized", "detail": "Bearer token required."}, status=401
+            )
+
+        # Validate token (sync wrapper)
+        try:
+            claims: TokenClaims = asyncio.run(self.client.validate_token(token_str))
+        except Cl4imTokenError as exc:
+            return JsonResponse({"error": "unauthorized", "detail": str(exc)}, status=401)
+
+        # Check permission
+        if not self.client.check_permission(claims, identifier, op_method):
+            return JsonResponse(
+                {"error": "forbidden", "detail": "Insufficient permissions."}, status=403
+            )
+
+        # Inject claims — available in views as request.cl4im_user
+        request.cl4im_user = claims
+        return None

cl4im-0.2.0/cl4im/adapters/fastapi.py

@@ -0,0 +1,181 @@
+"""FastAPI / Starlette adapter for cl4im."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from starlette.datastructures import Headers
+from starlette.routing import Match
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from ..client import Cl4imClient
+from ..decorators import get_registry, operation  # re-export
+from ..exceptions import Cl4imForbiddenError, Cl4imTokenError
+from ..middleware import extract_token
+from ..models import TokenClaims
+
+__all__ = ["Cl4im", "operation"]
+
+
+def _json_response(send: Send, status: int, body: dict[str, Any]):
+    """Build a minimal ASGI JSON response without starlette.responses dependency."""
+
+    async def _send() -> None:
+        encoded = json.dumps(body).encode()
+        await send(
+            {
+                "type": "http.response.start",
+                "status": status,
+                "headers": [
+                    (b"content-type", b"application/json"),
+                    (b"content-length", str(len(encoded)).encode()),
+                ],
+            }
+        )
+        await send({"type": "http.response.body", "body": encoded})
+
+    return _send
+
+
+def _match_route(app: Any, path: str, method: str) -> Any | None:
+    """Walk the app's route tree to find the endpoint for path+method."""
+    routes = getattr(app, "routes", None)
+    if not routes:
+        # Might be wrapped (e.g. ExceptionMiddleware) — try .app
+        inner = getattr(app, "app", None)
+        if inner is not None:
+            return _match_route(inner, path, method)
+        return None
+
+    scope = {"type": "http", "path": path, "method": method.upper()}
+    for route in routes:
+        match, _ = route.matches(scope)
+        if match == Match.FULL:
+            # Could be a sub-application (APIRouter mount)
+            endpoint = getattr(route, "endpoint", None)
+            if endpoint is not None:
+                return endpoint
+            # Recurse into mounted sub-app
+            sub = getattr(route, "app", None)
+            if sub is not None:
+                result = _match_route(sub, path, method)
+                if result is not None:
+                    return result
+    return None
+
+
+class _Cl4imASGIMiddleware:
+    """ASGI middleware that validates Bearer tokens and enforces permissions."""
+
+    def __init__(self, app: ASGIApp, client: Cl4imClient) -> None:
+        self.app = app
+        self.client = client
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        headers = Headers(scope=scope)
+        path: str = scope.get("path", "/")
+        method: str = scope.get("method", "GET")
+
+        # Resolve the endpoint and check for cl4im metadata
+        endpoint = _match_route(self.app, path, method)
+        identifier: str | None = getattr(endpoint, "__cl4im_id__", None) if endpoint else None
+        op_method: str | None = getattr(endpoint, "__cl4im_method__", None) if endpoint else None
+        op_level: str | None = getattr(endpoint, "__cl4im_level__", None) if endpoint else None
+
+        # Extract Bearer token
+        auth = headers.get("authorization", "")
+        scheme, _, token_str = auth.partition(" ")
+        token_str = token_str.strip() if scheme.lower() == "bearer" else ""
+
+        # If no cl4im annotation, pass through
+        if identifier is None:
+            await self.app(scope, receive, send)
+            return
+
+        # Public: no token required
+        if op_level == "public":
+            await self.app(scope, receive, send)
+            return
+
+        # Token required from this point
+        if not token_str:
+            await _json_response(send, 401, {"error": "unauthorized", "detail": "Bearer token required."})()
+            return
+
+        # Validate token
+        try:
+            claims: TokenClaims = await self.client.validate_token(token_str)
+        except Cl4imTokenError as exc:
+            await _json_response(send, 401, {"error": "unauthorized", "detail": str(exc)})()
+            return
+
+        # Check permission
+        allowed = self.client.check_permission(claims, identifier, op_method or "read")
+        if not allowed:
+            await _json_response(send, 403, {"error": "forbidden", "detail": "Insufficient permissions."})()
+            return
+
+        # Inject claims into scope so handlers can access request.state.user
+        scope.setdefault("state", {})["user"] = claims
+
+        await self.app(scope, receive, send)
+
+
+class Cl4im:
+    """FastAPI integration for cl4im.
+
+    Registers a startup handler that loads operations and an ASGI middleware
+    that enforces authentication and permissions on every request.
+
+    Usage::
+
+        from fastapi import FastAPI
+        from cl4im.adapters.fastapi import Cl4im, operation
+
+        app = FastAPI()
+        cl4im = Cl4im(
+            app,
+            authorizer_url="http://localhost:4000/api",
+            app_id="<uuid>",
+            secret="<secret>",
+        )
+
+        @app.get("/items")
+        @operation(id="items.list", level="private")
+        async def list_items():
+            ...
+
+    Args:
+        app: The :class:`fastapi.FastAPI` (or any Starlette) application.
+        authorizer_url: Base URL of the Identora authorizer.
+        app_id: UUID of the registered backend app.
+        secret: Plain-text app secret.
+    """
+
+    def __init__(
+        self,
+        app: Any,
+        authorizer_url: str,
+        realm_id: str,
+        app_id: str,
+        secret: str,
+    ) -> None:
+        self.client = Cl4imClient(authorizer_url, realm_id, app_id, secret)
+        self._app = app
+
+        # Register startup handler
+        app.add_event_handler("startup", self._startup)
+
+        # Register ASGI middleware — must receive the app instance
+        app.add_middleware(_Cl4imASGIMiddleware, client=self.client)
+
+    async def _startup(self) -> None:
+        """Load operations from the global registry and bootstrap the client."""
+        for op in get_registry():
+            self.client.register_operation(op)
+        await self.client.startup()