caronte-sdk 0.2.4__py3-none-any.whl

argos/__init__.py

@@ -0,0 +1,27 @@
+"""argos — Python client for the Argos authorizer."""
+
+from .client import ArgosClient
+from .decorators import operation
+from .exceptions import (
+    ArgosAuthError,
+    ArgosConfigError,
+    ArgosError,
+    ArgosForbiddenError,
+    ArgosSyncError,
+    ArgosTokenError,
+)
+from .models import OperationDescriptor, OperationWithGroups, TokenClaims
+
+__all__ = [
+    "ArgosClient",
+    "OperationDescriptor",
+    "OperationWithGroups",
+    "TokenClaims",
+    "ArgosError",
+    "ArgosAuthError",
+    "ArgosTokenError",
+    "ArgosForbiddenError",
+    "ArgosSyncError",
+    "ArgosConfigError",
+    "operation",
+]

argos/adapters/__init__.py

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

argos/adapters/django.py

@@ -0,0 +1,145 @@
+"""Django adapter for argos."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Callable
+
+from ..client import ArgosClient
+from ..decorators import get_registry, operation  # re-export
+from ..exceptions import ArgosTokenError
+from ..models import TokenClaims
+
+__all__ = ["ArgosMiddleware", "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, "__argos_id__", None)
+        op_method  = getattr(candidate, "__argos_method__", None)
+        level      = getattr(candidate, "__argos_level__", None)
+        if identifier and op_method and level:
+            return (identifier, op_method, level)
+    return None
+
+
+class ArgosMiddleware:
+    """Django WSGI middleware for argos.
+
+    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 = [
+            ...
+            "argos.adapters.django.ArgosMiddleware",
+            ...
+        ]
+
+    Required Django settings::
+
+        ARGOS_AUTHORIZER_URL = "http://localhost:4000/api"
+        ARGOS_APP_ID          = "<uuid>"
+        ARGOS_SECRET          = "<secret>"
+
+    Mark views with :func:`argos.decorators.operation`::
+
+        from django.http import JsonResponse
+        from argos.adapters.django import operation
+
+        @operation(id="items.list", level="private")
+        def list_items(request):
+            user = request.argos_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, "ARGOS_AUTHORIZER_URL", "")
+        realm_id: str       = getattr(settings, "ARGOS_REALM_ID", "")
+        app_id: str         = getattr(settings, "ARGOS_APP_ID", "")
+        secret: str         = getattr(settings, "ARGOS_SECRET", "")
+
+        if not (authorizer_url and realm_id and app_id and secret):
+            raise RuntimeError(
+                "argos requires ARGOS_AUTHORIZER_URL, ARGOS_REALM_ID, "
+                "ARGOS_APP_ID and ARGOS_SECRET in Django settings."
+            )
+
+        self.get_response = get_response
+        self.client = ArgosClient(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 argos 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 ArgosTokenError 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.argos_user
+        request.argos_user = claims
+        return None

argos/adapters/fastapi.py

@@ -0,0 +1,181 @@
+"""FastAPI / Starlette adapter for argos."""
+
+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 ArgosClient
+from ..decorators import get_registry, operation  # re-export
+from ..exceptions import ArgosForbiddenError, ArgosTokenError
+from ..middleware import extract_token
+from ..models import TokenClaims
+
+__all__ = ["Argos", "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 _ArgosASGIMiddleware:
+    """ASGI middleware that validates Bearer tokens and enforces permissions."""
+
+    def __init__(self, app: ASGIApp, client: ArgosClient) -> 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 argos metadata
+        endpoint = _match_route(self.app, path, method)
+        identifier: str | None = getattr(endpoint, "__argos_id__", None) if endpoint else None
+        op_method: str | None = getattr(endpoint, "__argos_method__", None) if endpoint else None
+        op_level: str | None = getattr(endpoint, "__argos_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 argos 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 ArgosTokenError 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 Argos:
+    """FastAPI integration for argos.
+
+    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 argos.adapters.fastapi import Argos, operation
+
+        app = FastAPI()
+        argos = Argos(
+            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 Argos 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 = ArgosClient(authorizer_url, realm_id, app_id, secret)
+        self._app = app
+
+        # Register startup handler (compatible with FastAPI 0.109+)
+        app.router.on_startup.append(self._startup)
+
+        # Register ASGI middleware — must receive the app instance
+        app.add_middleware(_ArgosASGIMiddleware, 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()

argos/adapters/flask.py

@@ -0,0 +1,128 @@
+"""Flask adapter for argos."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from ..client import ArgosClient
+from ..decorators import get_registry, operation  # re-export
+from ..exceptions import ArgosTokenError
+from ..models import TokenClaims
+
+if TYPE_CHECKING:
+    from flask import Flask
+
+__all__ = ["Argos", "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, "__argos_id__", None)
+    op_method = getattr(view_func, "__argos_method__", None)
+    level = getattr(view_func, "__argos_level__", None)
+
+    if identifier and op_method and level:
+        return (identifier, op_method, level)
+
+    return None
+
+
+class Argos:
+    """Flask integration for argos.
+
+    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 argos.adapters.flask import Argos, operation
+
+        app = Flask(__name__)
+        argos = Argos(
+            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.argos_user  # TokenClaims
+            return {"user": user.sub}
+
+    Args:
+        app: The :class:`flask.Flask` application.
+        authorizer_url: Base URL of the Argos 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 = ArgosClient(authorizer_url, realm_id, app_id, secret)
+        self._app = app
+
+        for op in get_registry():
+            self.client.register_operation(op)
+        asyncio.run(self.client.startup())
+
+        app.before_request(self._before_request)
+
+    def _before_request(self) -> Any:
+        """Flask ``before_request`` hook: auth enforcement."""
+        from flask import g, jsonify, request
+
+
+        # Resolve operation metadata from the matched endpoint
+        op_info = _resolve_operation(request.endpoint, self._app)
+
+        # No argos 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 ArgosTokenError 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.argos_user = claims
+        return None

argos/adapters/strawberry.py

@@ -0,0 +1,181 @@
+"""Strawberry GraphQL adapter for argos."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Callable
+
+from strawberry.extensions import SchemaExtension
+
+from ..client import ArgosClient
+from ..decorators import get_registry, operation  # re-export
+from ..exceptions import ArgosTokenError
+from ..models import TokenClaims
+
+__all__ = ["Argos", "operation"]
+
+
+def _get_argos_attrs(func: Any) -> tuple[str, str, str] | None:
+    """Extract argos metadata from a resolver function or bound method."""
+    for candidate in (func, getattr(func, "__func__", None), getattr(func, "__wrapped__", None)):
+        if candidate is None:
+            continue
+        identifier = getattr(candidate, "__argos_id__", None)
+        op_method  = getattr(candidate, "__argos_method__", None)
+        level      = getattr(candidate, "__argos_level__", None)
+        if identifier and op_method and level:
+            return identifier, op_method, level
+    return None
+
+
+def _make_extension(client: ArgosClient) -> type[SchemaExtension]:
+    """Return a SchemaExtension class bound to the given ArgosClient."""
+
+    class ArgosExtension(SchemaExtension):
+        async def on_executing_start(self) -> None:
+            """Validate Bearer token before any resolver runs.
+
+            For HTTP requests (queries/mutations): reads from the
+            ``Authorization`` header.
+
+            For WebSocket subscriptions (graphql-ws protocol): browsers
+            cannot set custom headers on WebSocket connections, so the token
+            is expected in the ``connection_init`` payload::
+
+                { "type": "connection_init", "payload": { "Authorization": "Bearer <token>" } }
+
+            Strawberry exposes this payload as ``context["connection_params"]``.
+            """
+            context = self.execution_context.context
+            claims: TokenClaims | None = None
+            token_str = ""
+
+            # 1. HTTP Authorization header (queries & mutations)
+            request = context.get("request")
+            if request is not None:
+                headers = getattr(request, "headers", {})
+                auth: str = headers.get("authorization", "") or headers.get("Authorization", "")
+                scheme, _, raw = auth.partition(" ")
+                if scheme.lower() == "bearer":
+                    token_str = raw.strip()
+
+            # 2. graphql-ws connection_init payload (subscriptions)
+            if not token_str:
+                params: dict = context.get("connection_params") or {}
+                auth = params.get("Authorization", "") or params.get("authorization", "")
+                scheme, _, raw = auth.partition(" ")
+                if scheme.lower() == "bearer":
+                    token_str = raw.strip()
+
+            if token_str:
+                try:
+                    claims = await client.validate_token(token_str)
+                except ArgosTokenError:
+                    claims = None
+
+            context["argos_user"] = claims
+
+        def resolve(
+            self,
+            _next: Callable,
+            root: Any,
+            info: Any,
+            *args: Any,
+            **kwargs: Any,
+        ) -> Any:
+            """Enforce permissions before each resolver that carries argos metadata."""
+            attrs = _get_argos_attrs(_next)
+
+            if attrs is None:
+                return _next(root, info, *args, **kwargs)
+
+            identifier, op_method, level = attrs
+
+            if level == "public":
+                return _next(root, info, *args, **kwargs)
+
+            claims: TokenClaims | None = info.context.get("argos_user")
+
+            if claims is None:
+                raise PermissionError("Bearer token required.")
+
+            if not client.check_permission(claims, identifier, op_method):
+                raise PermissionError("Insufficient permissions.")
+
+            return _next(root, info, *args, **kwargs)
+
+    return ArgosExtension
+
+
+class Argos:
+    """Strawberry GraphQL integration for argos.
+
+    Authenticates the app, syncs the operation catalogue, and provides a
+    :class:`strawberry.extensions.SchemaExtension` that enforces per-resolver
+    authentication and permissions.
+
+    Usage (with FastAPI lifespan)::
+
+        import strawberry
+        from contextlib import asynccontextmanager
+        from fastapi import FastAPI
+        from strawberry.fastapi import GraphQLRouter
+        from argos.adapters.strawberry import Argos, operation
+
+        argos = Argos(
+            authorizer_url="http://localhost:4000/api",
+            realm_id="test-realm",
+            app_id="<uuid>",
+            secret="<secret>",
+        )
+
+        @strawberry.type
+        class Query:
+            @strawberry.field
+            @operation(id="tasks:list", level="private")
+            async def tasks(self, info: strawberry.types.Info) -> list[Task]:
+                user = info.context["argos_user"]
+                ...
+
+        schema = strawberry.Schema(query=Query, extensions=[argos.extension])
+
+        @asynccontextmanager
+        async def lifespan(app: FastAPI):
+            await argos.startup_async()
+            yield
+
+        app = FastAPI(lifespan=lifespan)
+        app.include_router(GraphQLRouter(schema), prefix="/graphql")
+
+    Args:
+        authorizer_url: Base URL of the Argos authorizer.
+        realm_id: Realm the app belongs to (name or UUID).
+        app_id: UUID of the registered backend app.
+        secret: Plain-text app secret.
+    """
+
+    def __init__(
+        self,
+        authorizer_url: str,
+        realm_id: str,
+        app_id: str,
+        secret: str,
+    ) -> None:
+        self.client = ArgosClient(authorizer_url, realm_id, app_id, secret)
+        self.extension: type[SchemaExtension] = _make_extension(self.client)
+
+    def startup(self) -> None:
+        """Register operations and bootstrap the client (sync).
+
+        Call this after all ``@operation`` decorators have been applied,
+        i.e. after all resolver modules are imported.
+        """
+        for op in get_registry():
+            self.client.register_operation(op)
+        asyncio.run(self.client.startup())
+
+    async def startup_async(self) -> None:
+        """Async variant — use with FastAPI lifespan or any async startup hook."""
+        for op in get_registry():
+            self.client.register_operation(op)
+        await self.client.startup()