cl4im 0.2.0__py3-none-any.whl

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/adapters/__init__.py

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

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/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()

cl4im/adapters/flask.py

@@ -0,0 +1,139 @@
+"""Flask adapter for cl4im."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from ..client import Cl4imClient
+from ..decorators import get_registry, operation  # re-export
+from ..exceptions import Cl4imTokenError
+from ..models import TokenClaims
+
+if TYPE_CHECKING:
+    from flask import Flask
+
+__all__ = ["Cl4im", "operation"]
+
+
+def _resolve_operation(
+    endpoint_name: str | None,
+    app: Any,
+) -> tuple[str, str, str] | None:
+    """Return ``(identifier, op_method, level)`` for the current endpoint, or ``None``."""
+    if not endpoint_name:
+        return None
+
+    view_func = app.view_functions.get(endpoint_name)
+    if view_func is None:
+        return None
+
+    identifier = getattr(view_func, "__cl4im_id__", None)
+    op_method = getattr(view_func, "__cl4im_method__", None)
+    level = getattr(view_func, "__cl4im_level__", None)
+
+    if identifier and op_method and level:
+        return (identifier, op_method, level)
+
+    return None
+
+
+class Cl4im:
+    """Flask integration for cl4im.
+
+    Registers a ``before_request`` hook that handles startup (lazily on the
+    first request) and per-request authentication / authorisation.
+
+    Usage::
+
+        from flask import Flask, g
+        from cl4im.adapters.flask import Cl4im, operation
+
+        app = Flask(__name__)
+        cl4im = Cl4im(
+            app,
+            authorizer_url="http://localhost:4000/api",
+            app_id="<uuid>",
+            secret="<secret>",
+        )
+
+        @app.get("/items")
+        @operation(id="items.list", level="private")
+        def list_items():
+            user = g.cl4im_user  # TokenClaims
+            return {"user": user.sub}
+
+    Args:
+        app: The :class:`flask.Flask` 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: Flask,
+        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
+        self._started: bool = False
+
+        app.before_request(self._before_request)
+
+    # ──────────────────────────────────────────────────────────────
+    # Internal
+    # ──────────────────────────────────────────────────────────────
+
+    def _startup(self) -> None:
+        """Load operations from the global registry and bootstrap the client (sync)."""
+        for op in get_registry():
+            self.client.register_operation(op)
+        asyncio.run(self.client.startup())
+        self._started = True
+
+    def _before_request(self) -> Any:
+        """Flask ``before_request`` hook: startup + auth enforcement."""
+        from flask import g, jsonify, request
+
+        # Lazy startup on first real request
+        if not self._started:
+            self._startup()
+
+        # Resolve operation metadata from the matched endpoint
+        op_info = _resolve_operation(request.endpoint, self._app)
+
+        # No cl4im annotation — let the request pass through
+        if op_info is None:
+            return None
+
+        identifier, op_method, level = op_info
+
+        # Public operations need no token
+        if level == "public":
+            return None
+
+        # Extract Bearer token
+        auth: str = request.headers.get("Authorization", "")
+        scheme, _, token_str = auth.partition(" ")
+        token_str = token_str.strip() if scheme.lower() == "bearer" else ""
+
+        if not token_str:
+            return jsonify({"error": "unauthorized", "detail": "Bearer token required."}), 401
+
+        # Validate token (sync wrapper)
+        try:
+            claims: TokenClaims = asyncio.run(self.client.validate_token(token_str))
+        except Cl4imTokenError as exc:
+            return jsonify({"error": "unauthorized", "detail": str(exc)}), 401
+
+        # Check permission
+        if not self.client.check_permission(claims, identifier, op_method):
+            return jsonify({"error": "forbidden", "detail": "Insufficient permissions."}), 403
+
+        # Inject claims into Flask's request context
+        g.cl4im_user = claims
+        return None

cl4im/client.py

@@ -0,0 +1,316 @@
+"""Core Cl4imClient — handles auth, JWKS, operations and token validation."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+import jwt
+from jwt.algorithms import RSAAlgorithm
+
+from .exceptions import (
+    Cl4imAuthError,
+    Cl4imConfigError,
+    Cl4imError,
+    Cl4imSyncError,
+    Cl4imTokenError,
+)
+from .models import OperationDescriptor, OperationWithGroups, TokenClaims
+
+
+class Cl4imClient:
+    """Client for the Identora authorizer.
+
+    Handles app authentication, JWKS caching, operation sync and
+    token validation / permission checking.
+
+    Args:
+        authorizer_url: Base URL of the authorizer, e.g. ``http://localhost:4000/api``.
+        realm_id: Realm the app belongs to (name or UUID).
+        app_id: UUID of the backend app registered in ``auth.apps``.
+        secret: Raw secret (plain text) for the app.
+    """
+
+    JWKS_TTL: float = 3600.0
+
+    def __init__(
+        self,
+        authorizer_url: str,
+        realm_id: str,
+        app_id: str,
+        secret: str,
+    ) -> None:
+        self._base = authorizer_url.rstrip("/")
+        self._realm_id = realm_id
+        self._app_id = app_id
+        self._secret = secret
+
+        self._app_token: str | None = None
+        self._jwks: dict[str, Any] | None = None
+        self._jwks_fetched_at: float | None = None
+        self._operations: list[OperationWithGroups] = []
+        self._registered_operations: list[OperationDescriptor] = []
+
+    # ──────────────────────────────────────────────────────────────
+    # URL helpers
+    # ──────────────────────────────────────────────────────────────
+
+    @property
+    def _realm_base(self) -> str:
+        return f"{self._base}/realms/{self._realm_id}"
+
+    # ──────────────────────────────────────────────────────────────
+    # Public: lifecycle
+    # ──────────────────────────────────────────────────────────────
+
+    def register_operation(self, op: OperationDescriptor) -> None:
+        """Register an operation that this app exposes.
+
+        Must be called before :meth:`startup`.
+        """
+        self._registered_operations.append(op)
+
+    async def startup(self) -> None:
+        """Bootstrap the client.
+
+        Authenticates, fetches JWKS, syncs operations and retrieves the
+        authorised operation list. Raises :exc:`Cl4imConfigError` if no
+        operations have been registered.
+        """
+        if not self._registered_operations:
+            raise Cl4imConfigError(
+                "No operations registered. Call register_operation() before startup()."
+            )
+
+        await self.authenticate()
+        await self.fetch_jwks()
+        await self.sync_operations()
+        await self.fetch_operations()
+
+    # ──────────────────────────────────────────────────────────────
+    # Public: remote calls
+    # ──────────────────────────────────────────────────────────────
+
+    async def authenticate(self) -> None:
+        """Exchange app credentials for an app-level JWT.
+
+        Raises:
+            Cl4imAuthError: If the authorizer rejects the credentials.
+        """
+        url = f"{self._realm_base}/apps/token"
+        async with httpx.AsyncClient() as http:
+            try:
+                response = await http.post(
+                    url,
+                    json={"app_id": self._app_id, "secret": self._secret},
+                    timeout=10.0,
+                )
+            except httpx.RequestError as exc:
+                raise Cl4imAuthError(f"Network error during authentication: {exc}") from exc
+
+        if response.status_code != 200:
+            raise Cl4imAuthError(
+                f"Authentication failed: HTTP {response.status_code} — {response.text}"
+            )
+
+        data = response.json()
+        token = data.get("access_token")
+        if not token:
+            raise Cl4imAuthError("Authorizer returned no access_token.")
+
+        self._app_token = token
+
+    async def fetch_jwks(self) -> None:
+        """Fetch and cache the JWKS from the authorizer.
+
+        Raises:
+            Cl4imError: If the JWKS endpoint is unreachable or returns an error.
+        """
+        url = f"{self._realm_base}/protocol/openid-connect/certs"
+        async with httpx.AsyncClient() as http:
+            try:
+                response = await http.get(url, timeout=10.0)
+            except httpx.RequestError as exc:
+                raise Cl4imError(f"Network error fetching JWKS: {exc}") from exc
+
+        if response.status_code != 200:
+            raise Cl4imError(
+                f"JWKS fetch failed: HTTP {response.status_code} — {response.text}"
+            )
+
+        self._jwks = response.json()
+        self._jwks_fetched_at = time.monotonic()
+
+    async def fetch_operations(self) -> None:
+        """Fetch the operation list (with allowed groups) from the authorizer.
+
+        Requires a valid app token. Call :meth:`authenticate` first.
+
+        Raises:
+            Cl4imError: If the request fails.
+        """
+        self._ensure_app_token()
+        url = f"{self._realm_base}/apps/operations"
+        async with httpx.AsyncClient() as http:
+            try:
+                response = await http.get(
+                    url,
+                    headers={"Authorization": f"Bearer {self._app_token}"},
+                    timeout=10.0,
+                )
+            except httpx.RequestError as exc:
+                raise Cl4imError(f"Network error fetching operations: {exc}") from exc
+
+        if response.status_code != 200:
+            raise Cl4imError(
+                f"Fetch operations failed: HTTP {response.status_code} — {response.text}"
+            )
+
+        raw = response.json().get("operations", [])
+        self._operations = [
+            OperationWithGroups(
+                identifier=item["identifier"],
+                method=item["method"],
+                level=item["level"],
+                allowed_groups=item.get("allowed_groups", []),
+            )
+            for item in raw
+        ]
+
+    async def sync_operations(self) -> None:
+        """Sync the registered operations catalogue to the authorizer.
+
+        Requires a valid app token. Call :meth:`authenticate` first.
+
+        Raises:
+            Cl4imSyncError: If the sync request fails.
+        """
+        self._ensure_app_token()
+        url = f"{self._realm_base}/apps/operations/sync"
+        payload = {"operations": [op.to_dict() for op in self._registered_operations]}
+        async with httpx.AsyncClient() as http:
+            try:
+                response = await http.post(
+                    url,
+                    json=payload,
+                    headers={"Authorization": f"Bearer {self._app_token}"},
+                    timeout=10.0,
+                )
+            except httpx.RequestError as exc:
+                raise Cl4imSyncError(f"Network error during sync: {exc}") from exc
+
+        if response.status_code != 200:
+            raise Cl4imSyncError(
+                f"Sync failed: HTTP {response.status_code} — {response.text}"
+            )
+
+    # ──────────────────────────────────────────────────────────────
+    # Public: validation
+    # ──────────────────────────────────────────────────────────────
+
+    async def validate_token(self, token: str) -> TokenClaims:
+        """Validate a JWT and return its decoded claims.
+
+        Refreshes JWKS automatically if the cache has expired.
+
+        Args:
+            token: Raw JWT string (Bearer token from a user or service).
+
+        Returns:
+            :class:`TokenClaims` with the verified payload.
+
+        Raises:
+            Cl4imTokenError: If the token is invalid, expired, or uses an unknown key.
+        """
+        try:
+            header = jwt.get_unverified_header(token)
+        except jwt.exceptions.DecodeError as exc:
+            raise Cl4imTokenError(f"Malformed token header: {exc}") from exc
+
+        kid = header.get("kid")
+        if not kid:
+            raise Cl4imTokenError("Token header missing 'kid'.")
+
+        now = time.monotonic()
+        if (
+            self._jwks is None
+            or self._jwks_fetched_at is None
+            or (now - self._jwks_fetched_at) > self.JWKS_TTL
+        ):
+            await self.fetch_jwks()
+
+        public_key = self._find_key(kid)
+
+        if public_key is None:
+            await self.fetch_jwks()
+            public_key = self._find_key(kid)
+
+        if public_key is None:
+            raise Cl4imTokenError(f"No JWKS key found for kid='{kid}'.")
+
+        try:
+            payload: dict[str, Any] = jwt.decode(
+                token,
+                public_key,
+                algorithms=["RS256"],
+                options={"verify_exp": True},
+            )
+        except jwt.ExpiredSignatureError as exc:
+            raise Cl4imTokenError("Token has expired.") from exc
+        except jwt.InvalidTokenError as exc:
+            raise Cl4imTokenError(f"Invalid token: {exc}") from exc
+
+        return TokenClaims(
+            sub=payload["sub"],
+            realm_id=payload.get("realm_id", ""),
+            groups=payload.get("groups", []),
+            exp=payload["exp"],
+            raw=payload,
+        )
+
+    def check_permission(
+        self, claims: TokenClaims, identifier: str, method: str
+    ) -> bool:
+        """Check whether a token's claims authorise access to an operation."""
+        op = next(
+            (
+                o
+                for o in self._operations
+                if o.identifier == identifier and o.method == method
+            ),
+            None,
+        )
+        if op is None:
+            return False
+        if op.level == "public":
+            return True
+        if op.level == "private":
+            return bool(claims.groups)
+        if op.level == "protected":
+            return bool(set(claims.groups) & set(op.allowed_groups))
+        return False
+
+    # ──────────────────────────────────────────────────────────────
+    # Internal helpers
+    # ──────────────────────────────────────────────────────────────
+
+    def _ensure_app_token(self) -> None:
+        if not self._app_token:
+            raise Cl4imAuthError(
+                "No app token available. Call authenticate() or startup() first."
+            )
+
+    def _find_key(self, kid: str) -> Any | None:
+        if not self._jwks:
+            return None
+        jwk = next(
+            (k for k in self._jwks.get("keys", []) if k.get("kid") == kid),
+            None,
+        )
+        if jwk is None:
+            return None
+        try:
+            return RSAAlgorithm.from_jwk(jwk)
+        except Exception:
+            return None

cl4im/decorators.py

@@ -0,0 +1,81 @@
+"""Operation decorator and global registry."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .models import OperationDescriptor
+
+_registry: list[OperationDescriptor] = []
+
+_READ_PREFIXES = ("get_", "list_", "fetch_", "read_")
+_DELETE_PREFIXES = ("delete_", "remove_", "destroy_")
+_STREAM_KEYWORDS = ("stream", "subscribe", "watch", "listen")
+
+
+def _detect_method(func_name: str) -> str:
+    """Infer the operation method from the function name.
+
+    Rules (in order):
+    - Starts with a read prefix → ``'read'``
+    - Starts with a delete prefix → ``'delete'``
+    - Contains a stream keyword → ``'stream'``
+    - Anything else → ``'write'``
+    """
+    name = func_name.lower()
+    if any(name.startswith(p) for p in _READ_PREFIXES):
+        return "read"
+    if any(name.startswith(p) for p in _DELETE_PREFIXES):
+        return "delete"
+    if any(kw in name for kw in _STREAM_KEYWORDS):
+        return "stream"
+    return "write"
+
+
+def operation(id: str, level: str) -> Callable[[Any], Any]:
+    """Mark a function as a named operation and register it globally.
+
+    The operation method is inferred from the function name (see
+    :func:`_detect_method`).  The function itself is **not wrapped** —
+    this decorator is purely declarative.
+
+    Args:
+        id: Unique operation identifier (e.g. ``"users.list"``).
+        level: Visibility level — ``'public'``, ``'private'`` or
+               ``'protected'``.
+
+    Example::
+
+        @operation(id="users.list", level="private")
+        async def list_users(request: Request):
+            ...
+    """
+
+    def decorator(func: Any) -> Any:
+        method = _detect_method(func.__name__)
+        desc = OperationDescriptor(
+            identifier=id,
+            method=method,
+            level=level,
+            description=func.__doc__,
+        )
+        _registry.append(desc)
+
+        # Attach metadata so middleware can inspect the endpoint
+        func.__cl4im_id__ = id
+        func.__cl4im_method__ = method
+        func.__cl4im_level__ = level
+
+        return func
+
+    return decorator
+
+
+def get_registry() -> list[OperationDescriptor]:
+    """Return the global list of registered :class:`OperationDescriptor`\\s."""
+    return list(_registry)
+
+
+def clear_registry() -> None:
+    """Clear the global registry (useful in tests)."""
+    _registry.clear()

cl4im/exceptions.py

@@ -0,0 +1,25 @@
+"""Exception hierarchy for cl4im."""
+
+
+class Cl4imError(Exception):
+    """Base exception for all cl4im errors."""
+
+
+class Cl4imAuthError(Cl4imError):
+    """Raised when app authentication against the authorizer fails."""
+
+
+class Cl4imTokenError(Cl4imError):
+    """Raised when a user/service token is invalid or expired."""
+
+
+class Cl4imForbiddenError(Cl4imError):
+    """Raised when a token is valid but lacks permission for an operation."""
+
+
+class Cl4imSyncError(Cl4imError):
+    """Raised when syncing operations to the authorizer fails."""
+
+
+class Cl4imConfigError(Cl4imError):
+    """Raised when the client is misconfigured (e.g. no operations registered)."""

cl4im/middleware.py

@@ -0,0 +1,75 @@
+"""Framework-agnostic middleware helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .models import OperationDescriptor
+
+
+async def extract_token(request: Any) -> str | None:
+    """Extract a Bearer token from the ``Authorization`` header.
+
+    Compatible with any request object that exposes ``.headers`` as a
+    mapping (Starlette, Django, AIOHTTP, etc.).
+
+    Args:
+        request: An HTTP request object with a ``headers`` attribute.
+
+    Returns:
+        The raw token string, or ``None`` if the header is absent or
+        not a Bearer scheme.
+    """
+    auth: str = request.headers.get("Authorization", "") or request.headers.get(
+        "authorization", ""
+    )
+    if not auth:
+        return None
+    scheme, _, token = auth.partition(" ")
+    if scheme.lower() != "bearer" or not token:
+        return None
+    return token.strip()
+
+
+async def resolve_operation(
+    request: Any,
+    registered_operations: list[OperationDescriptor],
+) -> tuple[str, str] | None:
+    """Attempt to identify which operation a request maps to.
+
+    Strategy (in order):
+    1. If the route endpoint is already resolved (``request.scope["endpoint"]``
+       for Starlette), check for ``__cl4im_id__`` / ``__cl4im_method__``
+       attributes set by :func:`cl4im.decorators.operation`.
+    2. Otherwise return ``None``.
+
+    Args:
+        request: HTTP request object.  Must expose ``scope`` (Starlette) or
+                 ``route`` attribute for proper resolution.
+        registered_operations: List of :class:`OperationDescriptor` objects
+                                registered via the decorator.
+
+    Returns:
+        ``(identifier, method)`` tuple, or ``None`` if unresolvable.
+    """
+    # Starlette / FastAPI: scope["endpoint"] is set after routing
+    scope = getattr(request, "scope", {})
+    endpoint = scope.get("endpoint")
+
+    if endpoint is not None:
+        cl4im_id = getattr(endpoint, "__cl4im_id__", None)
+        cl4im_method = getattr(endpoint, "__cl4im_method__", None)
+        if cl4im_id and cl4im_method:
+            # Confirm it's in the registered list
+            match = next(
+                (
+                    op
+                    for op in registered_operations
+                    if op.identifier == cl4im_id and op.method == cl4im_method
+                ),
+                None,
+            )
+            if match:
+                return (cl4im_id, cl4im_method)
+
+    return None

cl4im/models.py

@@ -0,0 +1,49 @@
+"""Domain models for cl4im."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class OperationDescriptor:
+    """Describes an operation exposed by a backend app."""
+
+    identifier: str
+    method: str          # 'read' | 'write' | 'delete' | 'stream'
+    level: str           # 'public' | 'private' | 'protected'
+    protocol: str | None = None
+    native_ref: str | None = None
+    description: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "identifier": self.identifier,
+            "method": self.method,
+            "level": self.level,
+            "protocol": self.protocol,
+            "native_ref": self.native_ref,
+            "description": self.description,
+        }
+
+
+@dataclass
+class OperationWithGroups:
+    """An operation with its authorized group IDs."""
+
+    identifier: str
+    method: str
+    level: str
+    allowed_groups: list[str] = field(default_factory=list)
+
+
+@dataclass
+class TokenClaims:
+    """Decoded and verified JWT claims."""
+
+    sub: str
+    realm_id: str
+    groups: list[str]
+    exp: int
+    raw: dict[str, Any]

cl4im-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+cl4im/__init__.py,sha256=A66fLK3g4N6_jNkAwLCFnkLfGGh_5779JkNQSRNw7vY,612
+cl4im/client.py,sha256=9GKStWk3bx_oq5HWWc6QJQ0rrKtUlLqqvSVCE3F0aj4,11791
+cl4im/decorators.py,sha256=rbdrpZLa1nlOeR9IaQDkDErc63xmufBE_Y5moAumabc,2363
+cl4im/exceptions.py,sha256=zjBvjCnEmHdcXFvqZYwBTcr3UAyD35GaXXl-oMieLeM,667
+cl4im/middleware.py,sha256=8UwBUamu7a0UrrDmbQDCM--PiUigW01TOE3lgDZe8FE,2447
+cl4im/models.py,sha256=keZYtanjMeu3R_1UdHk_M6bhqlliR6hIODgfbmZgpkE,1160
+cl4im/adapters/__init__.py,sha256=IAuWPxVHYzdg5-NSAFraG3j7U71kVG_IoTjoOFntpdw,17
+cl4im/adapters/django.py,sha256=p7znQTBHiUJAwXGBXsn5JMenh_C7P7ELd8htTDfZp_U,4981
+cl4im/adapters/fastapi.py,sha256=eitml2-doRqoc2Jm4dK6GrBEeF9h28hoFrZ0B3ePy14,6146
+cl4im/adapters/flask.py,sha256=OXvC-9B50BTPGCUeuek7hlOqHL0Lo8NY5XSq16bb_4E,4490
+cl4im-0.2.0.dist-info/METADATA,sha256=UxoMDjEDSjpusCU06U26YnE6oeu3UwDaO0F5I28BC-A,6231
+cl4im-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cl4im-0.2.0.dist-info/licenses/LICENSE,sha256=1PM2LvmD4zNHtGPCd0hpxq0w1wmRlERaYLBuvIHYY10,1176
+cl4im-0.2.0.dist-info/RECORD,,

cl4im-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

cl4im-0.2.0.dist-info/licenses/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/