caronte-sdk 0.2.4__tar.gz

caronte_sdk-0.2.4/.gitignore

@@ -0,0 +1,41 @@
+# Env files
+.env
+.env.*
+!.env.example
+
+# Node
+node_modules/
+dist/
+*.tgz
+*.tsbuildinfo
+npm-debug.log*
+
+# Angular
+.angular/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.pytest_cache/
+.venv/
+venv/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+
+hermes/docs/demo/
+hermes/docs/storybook/
+hermes/docs/figma/
+hermes/docs/documentation.json
+hermes/docs/website/src/compiled-content/*
+!hermes/docs/website/src/compiled-content/.gitkeep
+
+# Clone de referência do shadcn-ui/ui upstream — não é nosso repo, não deve virar gitlink.
+/shadcn/

caronte_sdk-0.2.4/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/

caronte_sdk-0.2.4/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: caronte-sdk
+Version: 0.2.4
+Summary: Python client for the Argos authorizer (OIDC + RBAC)
+Project-URL: Homepage, https://github.com/xlucvvs/argos-python
+Project-URL: Repository, https://github.com/xlucvvs/argos-python
+Project-URL: Bug Tracker, https://github.com/xlucvvs/argos-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: argos,auth,authorization,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'
+Provides-Extra: strawberry
+Requires-Dist: strawberry-graphql>=0.235; extra == 'strawberry'
+Description-Content-Type: text/markdown
+
+# argos
+
+Python client for the **Argos** authorizer — handles app authentication,
+JWT validation, permission checking and automatic operation sync.
+
+## Installation
+
+```bash
+pip install argos
+# With FastAPI support
+pip install "argos[fastapi]"
+```
+
+## Quick start with FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from argos.adapters.fastapi import Argos, operation
+
+app = FastAPI()
+
+argos = Argos(
+    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 argos import ArgosClient, OperationDescriptor
+
+client = ArgosClient(
+    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 Argos, 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 argos.adapters.fastapi import Argos
+
+argos = Argos(
+    app,
+    authorizer_url=os.environ["AUTHORIZER_URL"],
+    app_id=os.environ["APP_ID"],
+    secret=os.environ["APP_SECRET"],
+)
+```

caronte_sdk-0.2.4/README.md

@@ -0,0 +1,118 @@
+# argos
+
+Python client for the **Argos** authorizer — handles app authentication,
+JWT validation, permission checking and automatic operation sync.
+
+## Installation
+
+```bash
+pip install argos
+# With FastAPI support
+pip install "argos[fastapi]"
+```
+
+## Quick start with FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from argos.adapters.fastapi import Argos, operation
+
+app = FastAPI()
+
+argos = Argos(
+    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 argos import ArgosClient, OperationDescriptor
+
+client = ArgosClient(
+    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 Argos, 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 argos.adapters.fastapi import Argos
+
+argos = Argos(
+    app,
+    authorizer_url=os.environ["AUTHORIZER_URL"],
+    app_id=os.environ["APP_ID"],
+    secret=os.environ["APP_SECRET"],
+)
+```

caronte_sdk-0.2.4/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",
+]

caronte_sdk-0.2.4/argos/adapters/__init__.py

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

caronte_sdk-0.2.4/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