scopebound 0.1.0__tar.gz

scopebound-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/

scopebound-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: scopebound
+Version: 0.1.0
+Summary: Zero-trust identity and enforcement for AI agents
+License: Apache-2.0
+Keywords: agents,ai,enforcement,langchain,security
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: langchain-core>=0.2.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.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# Scopebound Python SDK
+
+Zero-trust identity and enforcement for AI agents.
+
+## Installation
+```bash
+pip install scopebound
+```
+
+## Quickstart — LangChain
+```python
+from scopebound import ScopeboundSDK, enforce
+from langchain_core.tools import BaseTool
+
+sb = ScopeboundSDK(base_url="http://localhost:8080")
+
+@enforce(sb, role="invoice-processor")
+class ReadInvoicesTool(BaseTool):
+    name = "read_invoices"
+    description = "Read invoices from the database"
+
+    def _run(self, query: str) -> str:
+        return "invoice data"
+```
+
+## License
+
+Apache-2.0

scopebound-0.1.0/README.md

@@ -0,0 +1,28 @@
+# Scopebound Python SDK
+
+Zero-trust identity and enforcement for AI agents.
+
+## Installation
+```bash
+pip install scopebound
+```
+
+## Quickstart — LangChain
+```python
+from scopebound import ScopeboundSDK, enforce
+from langchain_core.tools import BaseTool
+
+sb = ScopeboundSDK(base_url="http://localhost:8080")
+
+@enforce(sb, role="invoice-processor")
+class ReadInvoicesTool(BaseTool):
+    name = "read_invoices"
+    description = "Read invoices from the database"
+
+    def _run(self, query: str) -> str:
+        return "invoice data"
+```
+
+## License
+
+Apache-2.0

scopebound-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "scopebound"
+version = "0.1.0"
+description = "Zero-trust identity and enforcement for AI agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+keywords = ["ai", "agents", "security", "enforcement", "langchain"]
+dependencies = [
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+langchain = [
+    "langchain-core>=0.2.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-httpx>=0.30.0",
+    "langchain-core>=0.2.0",
+    "respx>=0.21.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

scopebound-0.1.0/scopebound/__init__.py

@@ -0,0 +1,24 @@
+"""
+Scopebound Python SDK — zero-trust identity and enforcement for AI agents.
+"""
+from .client import ScopeboundSDK
+from .exceptions import ScopeboundDenyError, ScopeboundTimeoutError, ScopeboundUnavailableError
+from .adapters.langchain import enforce
+from .adapters.openai_assistants import ScopeboundSession
+from .adapters.crewai import CrewEnforcer
+from .adapters.autogen import enforce_autogen, AutoGenSession
+from .adapters.semantic_kernel import enforce_sk
+
+__all__ = [
+    "ScopeboundSDK",
+    "ScopeboundDenyError",
+    "ScopeboundTimeoutError",
+    "ScopeboundUnavailableError",
+    "enforce",
+    "ScopeboundSession",
+    "CrewEnforcer",
+    "enforce_autogen",
+    "AutoGenSession",
+    "enforce_sk",
+]
+__version__ = "0.1.0"

scopebound-0.1.0/scopebound/adapters/autogen.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import atexit
+import functools
+import uuid
+from contextlib import contextmanager
+from typing import Any, Callable, Generator
+
+from ..client import ScopeboundSDK
+from ..exceptions import ScopeboundDenyError
+
+
+def enforce_autogen(sdk: ScopeboundSDK, role: str) -> Callable:
+    """
+    Decorator that wraps an AutoGen tool function with Scopebound enforcement.
+
+    Works with both plain functions and AutoGen FunctionTool callables.
+    The decorated function is intercepted before execution — enforcement
+    happens before the tool runs.
+
+    Usage:
+        sb = ScopeboundSDK(base_url="http://localhost:8080")
+
+        @enforce_autogen(sb, role="invoice-processor")
+        def read_invoices(limit: int = 10) -> str:
+            return f"found {limit} invoices"
+
+        # Register with AutoGen agent:
+        agent = AssistantAgent(
+            name="agent",
+            tools=[read_invoices],
+        )
+
+    On deny, the function returns a structured error dict so the AutoGen
+    conversation can handle it gracefully without crashing the run.
+    """
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapped(*args: Any, **kwargs: Any) -> Any:
+            call_id = str(uuid.uuid4())[:8]
+            call_args = _extract_args(args, kwargs)
+            try:
+                sdk.enforce(
+                    role_id=role,
+                    tool_name=func.__name__,
+                    call_args=call_args,
+                    call_id=call_id,
+                )
+            except ScopeboundDenyError as e:
+                # Return structured error dict — AutoGen conversation handles it.
+                return {
+                    "error":          e.deny_code,
+                    "reason":         e.reason,
+                    "retry_guidance": e.retry_guidance,
+                }
+            return func(*args, **kwargs)
+
+        # Preserve AutoGen metadata — name and description must be accessible.
+        wrapped.__name__ = func.__name__
+        wrapped.__doc__  = func.__doc__
+
+        atexit.register(sdk.revoke)
+        return wrapped
+
+    return decorator
+
+
+class AutoGenSession:
+    """
+    Manages Scopebound session lifecycle around an AutoGen conversation run.
+
+    Provisions sessions for all agent roles at the start of a conversation
+    and revokes them when the conversation ends.
+
+    Usage:
+        sb = ScopeboundSDK(base_url="http://localhost:8080")
+
+        with AutoGenSession(sb, roles={"researcher": "read-only-analyst"}) as session:
+            await Console(agent.run_stream(...))
+    """
+
+    def __init__(self, sdk: ScopeboundSDK, roles: dict[str, str]):
+        """
+        Args:
+            sdk:   A ScopeboundSDK instance shared across the conversation.
+            roles: Dict mapping AutoGen agent names to Scopebound role IDs.
+                   Example: {"researcher": "read-only-analyst"}
+        """
+        self.sdk   = sdk
+        self.roles = roles
+
+    @contextmanager
+    def conversation(self) -> Generator[None, None, None]:
+        """
+        Context manager that provisions all role sessions at entry
+        and revokes them at exit (including on exception).
+
+        Usage:
+            with session.conversation():
+                result = await agent.run(task="...")
+        """
+        for role_id in self.roles.values():
+            self.sdk.provision(role_id=role_id)
+        try:
+            yield
+        finally:
+            self.sdk.revoke()
+
+    def __enter__(self) -> "AutoGenSession":
+        for role_id in self.roles.values():
+            self.sdk.provision(role_id=role_id)
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.sdk.revoke()
+
+    def enforce_tool(self, agent_name: str) -> Callable:
+        """
+        Returns an @enforce_autogen decorator bound to the given agent's role.
+
+        Usage:
+            session = AutoGenSession(sb, roles={"researcher": "read-only-analyst"})
+
+            @session.enforce_tool("researcher")
+            def search_web(query: str) -> str:
+                return "results"
+        """
+        role_id = self.roles.get(agent_name)
+        if role_id is None:
+            raise ValueError(
+                f"Agent {agent_name!r} not found in roles dict. "
+                f"Available: {list(self.roles.keys())}"
+            )
+        return enforce_autogen(self.sdk, role_id)
+
+
+def _extract_args(args: tuple, kwargs: dict) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    if args:
+        result["args"] = list(args)
+    result.update(kwargs)
+    return result

scopebound-0.1.0/scopebound/adapters/crewai.py

@@ -0,0 +1,154 @@
+import atexit
+import functools
+import uuid
+from contextlib import contextmanager
+from typing import Any, Generator
+
+from ..client import ScopeboundSDK
+from ..exceptions import ScopeboundDenyError
+
+
+class CrewEnforcer:
+    """
+    Wraps CrewAI BaseTool subclasses with Scopebound enforcement and manages
+    session lifecycle around crew.kickoff() runs.
+
+    Usage:
+        sb = ScopeboundSDK(base_url="http://localhost:8080")
+
+        enforcer = CrewEnforcer(sb, roles={
+            "researcher": "read-only-analyst",
+            "writer":     "email-sender",
+        })
+
+        # Wrap individual tools:
+        @enforcer.enforce_tool(agent_role="researcher")
+        class SearchTool(BaseTool):
+            name: str        = "search"
+            description: str = "Search the web"
+            def _run(self, query: str = "") -> str:
+                return "results"
+
+        # Run the crew with automatic session lifecycle:
+        with enforcer.crew_session():
+            result = crew.kickoff()
+    """
+
+    def __init__(self, sdk: ScopeboundSDK, roles: dict[str, str]):
+        """
+        Args:
+            sdk:   A ScopeboundSDK instance shared across the crew run.
+            roles: Dict mapping CrewAI agent role names to Scopebound role IDs.
+                   Example: {"researcher": "read-only-analyst", "writer": "email-sender"}
+        """
+        self.sdk   = sdk
+        self.roles = roles
+        self._active_sessions: list[str] = []
+
+    def enforce_tool(self, agent_role: str):
+        """
+        Class decorator that wraps a CrewAI BaseTool with Scopebound enforcement.
+
+        Args:
+            agent_role: The CrewAI agent role name (key in the roles dict).
+
+        Raises:
+            ValueError: If agent_role is not in the roles dict.
+        """
+        if agent_role not in self.roles:
+            raise ValueError(
+                f"Agent role {agent_role!r} not found in roles dict. "
+                f"Available roles: {list(self.roles.keys())}"
+            )
+        scopebound_role = self.roles[agent_role]
+
+        def decorator(cls):
+            original_run  = cls._run
+            original_arun = getattr(cls, "_arun", None)
+
+            @functools.wraps(original_run)
+            def wrapped_run(self_tool, *args, **kwargs):
+                call_id = str(uuid.uuid4())[:8]
+                call_args = _extract_args(args, kwargs)
+                try:
+                    self.sdk.enforce(
+                        role_id   = scopebound_role,
+                        tool_name = self_tool.name,
+                        call_args = call_args,
+                        call_id   = call_id,
+                    )
+                except ScopeboundDenyError as e:
+                    # CrewAI expects ToolException on tool failure.
+                    # Import lazily so crewai is not a hard dependency.
+                    raise _make_tool_exception(e) from e
+                return original_run(self_tool, *args, **kwargs)
+
+            cls._run = wrapped_run
+
+            if original_arun is not None:
+                @functools.wraps(original_arun)
+                async def wrapped_arun(self_tool, *args, **kwargs):
+                    call_id = str(uuid.uuid4())[:8]
+                    call_args = _extract_args(args, kwargs)
+                    try:
+                        self.sdk.enforce(
+                            role_id   = scopebound_role,
+                            tool_name = self_tool.name,
+                            call_args = call_args,
+                            call_id   = call_id,
+                        )
+                    except ScopeboundDenyError as e:
+                        raise _make_tool_exception(e) from e
+                    return await original_arun(self_tool, *args, **kwargs)
+
+                cls._arun = wrapped_arun
+
+            return cls
+
+        return decorator
+
+    @contextmanager
+    def crew_session(self) -> Generator[None, None, None]:
+        """
+        Context manager that provisions sessions for all roles at entry
+        and revokes them at exit.
+
+        Usage:
+            with enforcer.crew_session():
+                crew.kickoff()
+        """
+        # Provision a session for each role at kickoff start.
+        for scopebound_role in self.roles.values():
+            self.sdk.provision(role_id=scopebound_role)
+
+        try:
+            yield
+        finally:
+            # Revoke all sessions at kickoff end.
+            self.sdk.revoke()
+            self._active_sessions.clear()
+
+    def revoke_all(self) -> None:
+        """Revoke all active sessions. Called by atexit handler."""
+        self.sdk.revoke()
+
+
+def _extract_args(args: tuple, kwargs: dict) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    if args:
+        result["args"] = list(args)
+    result.update(kwargs)
+    return result
+
+
+def _make_tool_exception(deny_error: ScopeboundDenyError) -> Exception:
+    """
+    Wrap ScopeboundDenyError in a CrewAI ToolException if crewai is installed,
+    otherwise re-raise the original error. This allows CrewAI error handling
+    to work correctly while keeping crewai as an optional dependency.
+    """
+    try:
+        from crewai.tools.tool_usage import ToolException
+        return ToolException(str(deny_error))
+    except ImportError:
+        return deny_error

scopebound-0.1.0/scopebound/adapters/langchain.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+import atexit
+import functools
+import uuid
+from typing import Any, Callable, Type, TypeVar
+from langchain_core.tools import BaseTool
+from ..client import ScopeboundSDK
+from ..exceptions import ScopeboundDenyError
+
+T = TypeVar("T", bound=BaseTool)
+
+
+def enforce(sdk: ScopeboundSDK, role: str) -> Callable:
+    """Class decorator that wraps a LangChain BaseTool with Scopebound enforcement."""
+    def decorator(cls):
+        original_run = cls._run
+        original_arun = getattr(cls, "_arun", None)
+
+        @functools.wraps(original_run)
+        def wrapped_run(self, *args, **kwargs):
+            call_id = str(uuid.uuid4())[:8]
+            sdk.enforce(
+                role_id=role,
+                tool_name=self.name,
+                call_args=_extract_args(args, kwargs),
+                call_id=call_id,
+            )
+            return original_run(self, *args, **kwargs)
+
+        cls._run = wrapped_run
+
+        if original_arun is not None:
+            @functools.wraps(original_arun)
+            async def wrapped_arun(self, *args, **kwargs):
+                call_id = str(uuid.uuid4())[:8]
+                sdk.enforce(
+                    role_id=role,
+                    tool_name=self.name,
+                    call_args=_extract_args(args, kwargs),
+                    call_id=call_id,
+                )
+                return await original_arun(self, *args, **kwargs)
+            cls._arun = wrapped_arun
+
+        atexit.register(sdk.revoke)
+        return cls
+
+    return decorator
+
+
+def _extract_args(args, kwargs):
+    result = {}
+    if args:
+        result["args"] = list(args)
+    result.update(kwargs)
+    return result

scopebound-0.1.0/scopebound/adapters/openai_assistants.py

@@ -0,0 +1,138 @@
+import json
+from typing import Any, Callable
+
+from ..client import ScopeboundSDK
+from ..exceptions import ScopeboundDenyError
+
+
+# Type aliases matching the OpenAI SDK structures we interact with.
+# We use duck typing rather than importing openai directly so the adapter
+# works without openai as a hard dependency.
+ToolCall = Any   # openai.types.beta.threads.required_action_submit_tool_outputs.ToolCall
+Handler  = Callable[[str, dict], str]  # handler(tool_name, arguments) -> output
+
+
+class ScopeboundSession:
+    """
+    Wraps the OpenAI Assistants API run polling loop with Scopebound enforcement.
+
+    Usage:
+        sb  = ScopeboundSDK(base_url="http://localhost:8080")
+        session = ScopeboundSession(sb, role="invoice-processor")
+
+        # In your run polling loop:
+        tool_outputs = session.execute_tool_calls(
+            tool_calls=run.required_action.submit_tool_outputs.tool_calls,
+            handlers={
+                "read_invoices": read_invoices_handler,
+                "send_email":    send_email_handler,
+            }
+        )
+        client.beta.threads.runs.submit_tool_outputs(
+            thread_id=thread.id,
+            run_id=run.id,
+            tool_outputs=tool_outputs,
+        )
+
+    Denied tool calls are submitted as structured error JSON so the LLM
+    can handle them gracefully rather than causing the run to fail.
+    """
+
+    def __init__(self, sdk: ScopeboundSDK, role: str):
+        """
+        Args:
+            sdk:  A ScopeboundSDK instance. The session JWT is provisioned
+                  lazily on the first execute_tool_calls() call and reused.
+            role: The agent role to enforce against.
+        """
+        self.sdk  = sdk
+        self.role = role
+
+    def execute_tool_calls(
+        self,
+        tool_calls: list[ToolCall],
+        handlers: dict[str, Handler],
+    ) -> list[dict[str, str]]:
+        """
+        Enforce and execute a list of tool calls from an Assistants API run.
+
+        For each tool_call:
+        - Sends /v1/enforce with the tool name and arguments.
+        - If allowed: calls the corresponding handler and collects its output.
+        - If denied:  submits a structured error JSON as the tool output so
+                      the LLM can handle the denial gracefully.
+
+        Args:
+            tool_calls: The list of tool calls from
+                        run.required_action.submit_tool_outputs.tool_calls.
+            handlers:   Dict mapping tool function names to callables.
+                        Each callable receives (tool_name, arguments: dict) -> str.
+
+        Returns:
+            A list of tool output dicts ready for submit_tool_outputs:
+            [{"tool_call_id": "...", "output": "..."}, ...]
+        """
+        outputs = []
+        for tool_call in tool_calls:
+            output = self._handle_single(tool_call, handlers)
+            outputs.append({
+                "tool_call_id": tool_call.id,
+                "output":       output,
+            })
+        return outputs
+
+    def _handle_single(self, tool_call: ToolCall, handlers: dict[str, Handler]) -> str:
+        """Enforce and execute a single tool call. Returns the output string."""
+        func      = tool_call.function
+        tool_name = func.name
+        call_id   = tool_call.id  # use Assistants API ID for audit correlation
+
+        # Parse arguments — Assistants API returns them as a JSON string.
+        try:
+            arguments = json.loads(func.arguments or "{}")
+        except json.JSONDecodeError:
+            arguments = {}
+
+        # Enforce the call.
+        try:
+            self.sdk.enforce(
+                role_id   = self.role,
+                tool_name = tool_name,
+                call_args = arguments,
+                call_id   = call_id[:128],  # enforce 128-char limit
+            )
+        except ScopeboundDenyError as e:
+            # Submit denial as structured JSON — LLM handles it gracefully.
+            return json.dumps({
+                "error":          e.deny_code,
+                "reason":         e.reason,
+                "retry_guidance": e.retry_guidance,
+            })
+        except Exception as e:
+            # Unexpected error from enforcement plane.
+            return json.dumps({"error": "ENFORCEMENT_ERROR", "reason": str(e)})
+
+        # Call the handler.
+        handler = handlers.get(tool_name)
+        if handler is None:
+            return json.dumps({
+                "error":  "HANDLER_NOT_FOUND",
+                "reason": f"No handler registered for tool '{tool_name}'",
+            })
+
+        try:
+            result = handler(tool_name, arguments)
+            # Handlers must return a string — coerce if needed.
+            return result if isinstance(result, str) else json.dumps(result)
+        except Exception as e:
+            return json.dumps({"error": "HANDLER_ERROR", "reason": str(e)})
+
+    def revoke(self) -> None:
+        """Revoke the underlying session. Call when the assistant run is complete."""
+        self.sdk.revoke()
+
+    def __enter__(self) -> "ScopeboundSession":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.revoke()