lelu-agent-auth-sdk 0.1.0__tar.gz

lelu_agent_auth_sdk-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Binaries
+bin/
+*.exe
+
+# Go
+engine/gen/
+coverage.out
+*.test
+
+# Node
+node_modules/
+**/node_modules/
+**/.next/
+*.tsbuildinfo
+sdk/typescript/node_modules/
+sdk/typescript/dist/
+platform/ui/node_modules/
+platform/ui/.next/
+
+# Python
+sdk/python/__pycache__/
+sdk/python/*.egg-info/
+sdk/python/.pytest_cache/
+sdk/python/.mypy_cache/
+__pycache__/
+*.pyc
+
+# Docker
+.docker/
+
+# Local caches
+engine/.gomodcache/
+
+# Local env
+.env
+.env.*
+!.env.example
+
+# OS
+.DS_Store
+Thumbs.db

lelu_agent_auth_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: lelu-agent-auth-sdk
+Version: 0.1.0
+Summary: Python SDK for Lelu — the confidence-aware authorization engine for autonomous AI agents
+Project-URL: Homepage, https://github.com/lelu-auth/lelu
+Project-URL: Repository, https://github.com/lelu-auth/lelu
+License: MIT
+Keywords: ai-agents,auth,authorization,langchain,langgraph,permissions
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.7.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=8.2.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.111.0; extra == 'fastapi'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.1.0; extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+# Lelu · Python SDK
+
+Python client for [Lelu](https://github.com/lelu-auth/lelu) — the confidence-aware authorization engine for autonomous AI agents.
+
+## Installation
+
+```bash
+pip install lelu-agent-auth-sdk
+```
+
+## Quick start
+
+```python
+import asyncio
+from lelu import LeluClient, AgentAuthRequest, AgentContext
+
+async def main():
+    async with LeluClient(base_url="http://localhost:8082") as client:
+        result = await client.agent_authorize(AgentAuthRequest(
+            actor="invoice_bot",
+            action="invoice:create",
+            context=AgentContext(
+                confidence=0.92,
+                acting_for="user_123",
+            ),
+        ))
+        print(result.allowed, result.reason)
+
+asyncio.run(main())
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `agent_authorize(req)` | Confidence-aware agent authorization |
+| `authorize(req)` | Human RBAC authorization |
+| `mint_token(req)` | Mint a JIT-scoped JWT |
+| `revoke_token(token_id)` | Revoke a token immediately |
+| `is_healthy()` | Health-check the engine |
+
+## License
+
+MIT

lelu_agent_auth_sdk-0.1.0/README.md

@@ -0,0 +1,44 @@
+# Lelu · Python SDK
+
+Python client for [Lelu](https://github.com/lelu-auth/lelu) — the confidence-aware authorization engine for autonomous AI agents.
+
+## Installation
+
+```bash
+pip install lelu-agent-auth-sdk
+```
+
+## Quick start
+
+```python
+import asyncio
+from lelu import LeluClient, AgentAuthRequest, AgentContext
+
+async def main():
+    async with LeluClient(base_url="http://localhost:8082") as client:
+        result = await client.agent_authorize(AgentAuthRequest(
+            actor="invoice_bot",
+            action="invoice:create",
+            context=AgentContext(
+                confidence=0.92,
+                acting_for="user_123",
+            ),
+        ))
+        print(result.allowed, result.reason)
+
+asyncio.run(main())
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `agent_authorize(req)` | Confidence-aware agent authorization |
+| `authorize(req)` | Human RBAC authorization |
+| `mint_token(req)` | Mint a JIT-scoped JWT |
+| `revoke_token(token_id)` | Revoke a token immediately |
+| `is_healthy()` | Health-check the engine |
+
+## License
+
+MIT

lelu_agent_auth_sdk-0.1.0/auth_pe/__init__.py

@@ -0,0 +1,66 @@
+"""
+Lelu Python SDK.
+
+Quick start::
+
+    from lelu import LeluClient, AgentAuthRequest, AgentContext
+
+    async with LeluClient(base_url="http://localhost:8080") as lelu:
+        decision = await lelu.agent_authorize(
+            AgentAuthRequest(
+                actor="invoice_bot",
+                action="approve_refunds",
+                context=AgentContext(confidence=0.92, acting_for="user_123"),
+            )
+        )
+        if not decision.allowed:
+            print(decision.reason)
+"""
+
+from .client import LeluClient
+from .autogpt_plugin import LeluAutoGPTPlugin
+from .middleware import AgentMiddleware
+from .models import (
+    AgentAuthDecision,
+    AgentAuthRequest,
+    AgentContext,
+    AuthDecision,
+    AuthEngineError,
+    AuthRequest,
+    DelegateScopeRequest,
+    DelegateScopeResult,
+    MintTokenRequest,
+    MintTokenResult,
+    RevokeTokenResult,
+)
+
+# CrewAI integration — requires `pip install crewai`
+try:
+    from .crewai import LeluTool, PermissionDeniedError as CrewAIPermissionDeniedError  # noqa: F401
+except ImportError:
+    pass  # crewai not installed; LeluTool not available
+
+__all__ = [
+    "LeluClient",
+    "LeluAutoGPTPlugin",
+    "AgentMiddleware",
+    # CrewAI
+    "LeluTool",
+    "CrewAIPermissionDeniedError",
+    # Requests
+    "AuthRequest",
+    "AgentAuthRequest",
+    "AgentContext",
+    "MintTokenRequest",
+    "DelegateScopeRequest",
+    # Decisions
+    "AuthDecision",
+    "AgentAuthDecision",
+    "MintTokenResult",
+    "DelegateScopeResult",
+    "RevokeTokenResult",
+    # Errors
+    "AuthEngineError",
+]
+
+__version__ = "0.1.0"

lelu_agent_auth_sdk-0.1.0/auth_pe/autogpt_plugin.py

@@ -0,0 +1,63 @@
+"""AutoGPT plugin scaffold for Lelu Auth Permission Engine."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .client import LeluClient
+from .models import AgentAuthRequest, AgentContext
+
+
+@dataclass(slots=True)
+class LeluAutoGPTPlugin:
+    """
+    Minimal plugin helper for AutoGPT-style tool execution guards.
+
+    This is framework-agnostic so it can be plugged into different AutoGPT
+    runtimes without requiring a hard dependency.
+    """
+
+    client: LeluClient
+    actor: str
+
+    async def can_execute(
+        self,
+        action: str,
+        *,
+        confidence: float,
+        acting_for: str = "",
+        scope: str = "",
+        resource: dict[str, Any] | None = None,
+    ) -> tuple[bool, str]:
+        req = AgentAuthRequest(
+            actor=self.actor,
+            action=action,
+            resource=resource or {},
+            context=AgentContext(
+                confidence=confidence,
+                acting_for=acting_for,
+                scope=scope,
+            ),
+        )
+        decision = await self.client.agent_authorize(req)
+        return decision.allowed, decision.reason
+
+    async def enforce(
+        self,
+        action: str,
+        *,
+        confidence: float,
+        acting_for: str = "",
+        scope: str = "",
+        resource: dict[str, Any] | None = None,
+    ) -> None:
+        allowed, reason = await self.can_execute(
+            action,
+            confidence=confidence,
+            acting_for=acting_for,
+            scope=scope,
+            resource=resource,
+        )
+        if not allowed:
+            raise PermissionError(reason)

lelu_agent_auth_sdk-0.1.0/auth_pe/client.py

@@ -0,0 +1,208 @@
+"""Auth Permission Engine — async Python client (httpx-backed)."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+
+from .models import (
+    AgentAuthDecision,
+    AgentAuthRequest,
+    AuthDecision,
+    AuthEngineError,
+    AuthRequest,
+    DelegateScopeRequest,
+    DelegateScopeResult,
+    MintTokenRequest,
+    MintTokenResult,
+    RevokeTokenResult,
+)
+
+
+class LeluClient:
+    """
+    Async client for the Auth Permission Engine HTTP API.
+
+    Usage::
+
+        async with LeluClient(base_url="http://localhost:8080") as lelu:
+            decision = await lelu.agent_authorize(
+                AgentAuthRequest(
+                    actor="invoice_bot",
+                    action="approve_refunds",
+                    context=AgentContext(confidence=0.92, acting_for="user_123"),
+                )
+            )
+            if not decision.allowed:
+                print(decision.reason)
+
+    Or without a context manager::
+
+        lelu = LeluClient()
+        decision = await lelu.authorize(AuthRequest(user_id="u1", action="view_invoices"))
+        await lelu.aclose()
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8080",
+        timeout: float = 5.0,
+        api_key: str | None = None,
+    ) -> None:
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            headers=headers,
+            timeout=timeout,
+        )
+
+    # ── Context manager ───────────────────────────────────────────────────────
+
+    async def __aenter__(self) -> "LeluClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    # ── Human authorization ───────────────────────────────────────────────────
+
+    async def authorize(self, req: AuthRequest) -> AuthDecision:
+        """Check whether a human user is permitted to perform an action."""
+        payload = {
+            "user_id": req.user_id,
+            "action": req.action,
+            "resource": req.resource,
+        }
+        data = await self._post("/v1/authorize", payload)
+        return AuthDecision(
+            allowed=data["allowed"],
+            reason=data["reason"],
+            trace_id=data["trace_id"],
+        )
+
+    # ── Agent authorization ───────────────────────────────────────────────────
+
+    async def agent_authorize(self, req: AgentAuthRequest) -> AgentAuthDecision:
+        """
+        Check whether an AI agent is permitted to perform an action.
+
+        The confidence score in ``req.context`` is passed through the
+        Confidence-Aware Auth gate ★ before policy evaluation.
+        """
+        payload = {
+            "actor": req.actor,
+            "action": req.action,
+            "resource": req.resource,
+            "confidence": req.context.confidence,
+            "acting_for": req.context.acting_for,
+            "scope": req.context.scope,
+        }
+        data = await self._post("/v1/agent/authorize", payload)
+        return AgentAuthDecision(
+            allowed=data["allowed"],
+            reason=data["reason"],
+            trace_id=data["trace_id"],
+            downgraded_scope=data.get("downgraded_scope"),
+            requires_human_review=data.get("requires_human_review", False),
+            confidence_used=data.get("confidence_used", 0.0),
+        )
+
+    # ── JIT token minting ─────────────────────────────────────────────────────
+
+    async def mint_token(self, req: MintTokenRequest) -> MintTokenResult:
+        """Mint a scoped JIT token for an agent. Default TTL is 60 seconds."""
+        payload = {
+            "scope": req.scope,
+            "acting_for": req.acting_for,
+            "ttl_seconds": req.ttl_seconds or 60,
+        }
+        data = await self._post("/v1/tokens/mint", payload)
+        return MintTokenResult(
+            token=data["token"],
+            token_id=data["token_id"],
+            expires_at=datetime.fromtimestamp(data["expires_at"], tz=timezone.utc),
+        )
+
+    # ── Token revocation ──────────────────────────────────────────────────────
+
+    async def revoke_token(self, token_id: str) -> RevokeTokenResult:
+        """Immediately revoke a JIT token by its ID."""
+        resp = await self._client.delete(f"/v1/tokens/{token_id}")
+        await self._raise_for_status(resp)
+        return RevokeTokenResult(**resp.json())
+
+    # ── Multi-agent delegation ────────────────────────────────────────
+
+    async def delegate_scope(self, req: DelegateScopeRequest) -> DelegateScopeResult:
+        """
+        Delegate a constrained sub-scope from one agent to another.
+
+        Validates the delegation rule in the policy, caps the TTL, and mints a
+        child JIT token scoped to the granted actions.
+
+        Confidence-Aware: the delegator's confidence score is checked against
+        ``require_confidence_above`` in the policy before delegation is granted.
+        """
+        payload = {
+            "delegator": req.delegator,
+            "delegatee": req.delegatee,
+            "scoped_to": req.scoped_to,
+            "ttl_seconds": req.ttl_seconds or 60,
+            "confidence": req.confidence,
+            "acting_for": req.acting_for or "",
+            "tenant_id": req.tenant_id or "",
+        }
+        data = await self._post("/v1/agent/delegate", payload)
+        from datetime import datetime, timezone
+        return DelegateScopeResult(
+            token=data["token"],
+            token_id=data["token_id"],
+            expires_at=datetime.fromtimestamp(data["expires_at"], tz=timezone.utc),
+            delegator=data["delegator"],
+            delegatee=data["delegatee"],
+            granted_scopes=data["granted_scopes"],
+            trace_id=data["trace_id"],
+        )
+
+    # ── Health check ──────────────────────────────────────────────────────────
+
+    async def is_healthy(self) -> bool:
+        """Return True if the engine sidecar is reachable and healthy."""
+        try:
+            resp = await self._client.get("/healthz")
+            return resp.status_code == 200 and resp.json().get("status") == "ok"
+        except httpx.HTTPError:
+            return False
+
+    # ── HTTP helpers ──────────────────────────────────────────────────────────
+
+    async def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        resp = await self._client.post(path, json=payload)
+        await self._raise_for_status(resp)
+        return resp.json()  # type: ignore[no-any-return]
+
+    @staticmethod
+    async def _raise_for_status(resp: httpx.Response) -> None:
+        if not resp.is_error:
+            return
+        try:
+            detail = resp.json().get("error", resp.text)
+        except Exception:
+            detail = resp.text
+        raise AuthEngineError(
+            message=str(detail),
+            status=resp.status_code,
+            details=resp.text,
+        )
+
+
+# Backward compatibility alias.
+LeluClient = LeluClient

lelu_agent_auth_sdk-0.1.0/auth_pe/crewai.py

@@ -0,0 +1,189 @@
+"""
+Lelu integration for CrewAI agents.
+
+Provides ``LeluTool`` — a CrewAI-compatible tool base class that gates every
+``_run()`` call through Lelu's Confidence-Aware Auth before execution.
+
+Usage
+-----
+.. code-block:: python
+
+    from crewai.tools import BaseTool
+    from lelu.crewai import LeluTool
+    from lelu import LeluClient
+
+    client = LeluClient(base_url="http://localhost:8080")
+
+    class RefundTool(LeluTool):
+        name: str = "process_refund"
+        description: str = "Process a customer refund by invoice ID."
+        actor: str = "invoice_bot"
+        action: str = "invoice:refund"
+        confidence: float = 0.92  # set dynamically per-call if needed
+
+        def _execute(self, invoice_id: str) -> str:
+            # Your real tool logic here
+            return f"Refund processed for invoice {invoice_id}"
+
+    tool = RefundTool(lelu_client=client)
+
+    # Use in a CrewAI agent
+    from crewai import Agent, Task, Crew
+    agent = Agent(role="Finance Bot", tools=[tool], ...)
+
+Notes
+-----
+- ``_execute()`` is the method you override (not ``_run()``).
+- If Lelu denies the action, ``_run()`` returns a structured refusal string
+  that the LLM can use to self-correct.
+- If the action requires human review, it is queued automatically and a
+  pending message is returned.
+- Set ``throw_on_deny=True`` to raise ``PermissionDeniedError`` instead.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from pydantic import Field
+
+from .client import LeluClient
+from .models import AgentAuthRequest, AgentContext
+
+logger = logging.getLogger(__name__)
+
+# ─── Attempt to import CrewAI ────────────────────────────────────────────────
+
+try:
+    from crewai.tools import BaseTool as CrewAIBaseTool
+
+    _CREWAI_AVAILABLE = True
+except ImportError:
+    _CREWAI_AVAILABLE = False
+    CrewAIBaseTool = object
+
+
+# ─── Exceptions ───────────────────────────────────────────────────────────────
+
+
+class PermissionDeniedError(Exception):
+    """Raised by LeluTool when ``throw_on_deny=True`` and Lelu denies."""
+
+    def __init__(self, message: str, reason: str) -> None:
+        super().__init__(message)
+        self.reason = reason
+
+
+# ─── LeluTool ────────────────────────────────────────────────────────────────
+
+
+class LeluTool(CrewAIBaseTool):  # type: ignore[misc]
+    """CrewAI ``BaseTool`` with Lelu Confidence-Aware Auth.
+
+    Subclass this and implement ``_execute()`` instead of ``_run()``.
+    Every call to ``_run()`` is intercepted and gated through Lelu first.
+
+    Attributes
+    ----------
+    actor:
+        The Lelu agent scope / actor name registered in your ``auth.yaml``.
+    action:
+        The permission string being checked (e.g. ``"invoice:refund"``).
+    confidence:
+        LLM confidence score for this invocation (0.0–1.0). Can be set
+        dynamically before calling the tool.
+    throw_on_deny:
+        If ``True``, raise :class:`PermissionDeniedError` on denial.
+        If ``False`` (default), return a structured refusal string for LLM
+        self-correction.
+    acting_for:
+        Optional user ID the agent is acting on behalf of.
+    """
+
+    # Lelu-specific fields (Pydantic v2 model fields)
+    actor: str = Field(..., description="Lelu agent actor / scope name")
+    action: str = Field(..., description="Permission string to authorize")
+    confidence: float = Field(default=1.0, ge=0.0, le=1.0, description="LLM confidence score")
+    throw_on_deny: bool = Field(default=False, description="Raise on deny instead of returning refusal")
+    acting_for: str | None = Field(default=None, description="User the agent acts on behalf of")
+
+    # LeluClient is injected at construction time.
+    model_config = {"arbitrary_types_allowed": True}
+    _lelu: LeluClient
+
+    def __init__(self, lelu_client: LeluClient, **data: Any) -> None:
+        if not _CREWAI_AVAILABLE:
+            raise ImportError(
+                "crewai is not installed. Install it with: pip install crewai"
+            )
+        super().__init__(**data)
+        self._lelu = lelu_client
+
+    # ── Intercept CrewAI's _run ───────────────────────────────────────────────
+
+    def _run(self, *args: Any, **kwargs: Any) -> str:
+        """
+        Gate the tool call through Lelu before executing ``_execute()``.
+        Called by CrewAI's agent loop automatically.
+        """
+        try:
+            decision = asyncio.run(
+                self._lelu.agent_authorize(
+                    AgentAuthRequest(
+                        actor=self.actor,
+                        action=self.action,
+                        context=AgentContext(
+                            confidence=self.confidence,
+                            acting_for=self.acting_for,
+                        ),
+                    )
+                )
+            )
+        except Exception as exc:  # noqa: BLE001
+            msg = f"[Lelu] Authorization check failed for '{self.name}': {exc}"
+            logger.error("lelu: %s", msg)
+            if self.throw_on_deny:
+                raise PermissionDeniedError(msg, str(exc)) from exc
+            return msg
+
+        # ── Human review required ──────────────────────────────────────────
+        if decision.requires_human_review:
+            logger.info(
+                "lelu: tool=%s queued for human review reason=%r",
+                self.name,
+                decision.reason,
+            )
+            return (
+                f"[Lelu] Action '{self.name}' is queued for human review. "
+                f"Reason: {decision.reason}. Please wait for approval before retrying."
+            )
+
+        # ── Hard deny ─────────────────────────────────────────────────────
+        if not decision.allowed:
+            msg = (
+                f"[Lelu] Action '{self.name}' was denied for agent '{self.actor}'. "
+                f"Reason: {decision.reason}."
+            )
+            if decision.downgraded_scope:
+                msg += f" Downgraded to: {decision.downgraded_scope}."
+            logger.warning("lelu: %s", msg)
+            if self.throw_on_deny:
+                raise PermissionDeniedError(msg, decision.reason)
+            return msg
+
+        # ── Authorized — run the real tool ────────────────────────────────
+        logger.debug(
+            "lelu: tool=%s authorized confidence=%.2f trace_id=%s",
+            self.name,
+            decision.confidence_used,
+            decision.trace_id,
+        )
+        return self._execute(*args, **kwargs)
+
+    def _execute(self, *args: Any, **kwargs: Any) -> str:
+        """Override this method with your actual tool logic."""
+        raise NotImplementedError(
+            f"LeluTool subclass '{type(self).__name__}' must implement _execute()"
+        )