prosader 0.1.0__py3-none-any.whl

prosader/__init__.py

@@ -0,0 +1,378 @@
+"""Prosader Python SDK — guard AI agent tool calls with a Prosader gateway.
+
+Every guarded call is evaluated against your Prosader policy and produces a
+signed, tamper-evident audit receipt, whatever the outcome.
+
+Quick start::
+
+    import prosader
+
+    client = prosader.Client(
+        gateway_url="https://gateway.example.com:8443",
+        api_key="psk-live-...",          # or PROSADER_API_KEY
+        agent_id="billing-agent",        # or PROSADER_AGENT_ID
+    )
+
+    # Explicit check before executing a tool yourself:
+    decision = client.check("bash", parameters={"command": "ls /tmp"})
+    if decision.allowed:
+        ...  # run the tool
+
+    # Or wrap a function so the check happens automatically:
+    @client.wrap("send_email")
+    def send_email(to, subject, body): ...
+
+    send_email(to="a@b.com", subject="hi", body="...")  # raises prosader.Denied if blocked
+
+The SDK is intentionally dependency-free (Python standard library only).
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import json
+import os
+import ssl
+import urllib.error
+import urllib.request
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Optional
+
+__all__ = [
+    "Client",
+    "Decision",
+    "ProsaderError",
+    "Denied",
+    "BillingError",
+    "GatewayError",
+    "configure",
+    "check",
+    "wrap",
+]
+
+__version__ = "0.1.0"
+
+_DEFAULT_TIMEOUT_S = 35  # slightly above the gateway's 30 s request budget
+
+
+# ── Results and errors ────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class Decision:
+    """The gateway's verdict for one tool call."""
+
+    allowed: bool
+    outcome: str  # "ALLOW" | "DENY" | "STEP_UP"
+    reason: str = ""
+    rule_id: str = ""
+    receipt_id: str = ""
+    latency_ms: int = 0
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+class ProsaderError(Exception):
+    """Base class for all SDK errors."""
+
+
+class Denied(ProsaderError):
+    """Raised by wrapped functions when the gateway blocks the call."""
+
+    def __init__(self, decision: Decision):
+        self.decision = decision
+        msg = f"blocked by Prosader ({decision.outcome})"
+        if decision.rule_id:
+            msg += f" rule={decision.rule_id}"
+        if decision.reason:
+            msg += f": {decision.reason}"
+        super().__init__(msg)
+
+
+class BillingError(ProsaderError):
+    """Raised on HTTP 402 — subscription inactive or decision quota exhausted."""
+
+    def __init__(self, message: str, status: str = "", code: str = ""):
+        self.status = status
+        self.code = code
+        super().__init__(message)
+
+
+class GatewayError(ProsaderError):
+    """Raised when the gateway is unreachable or returns an unexpected response.
+
+    Prosader is fail-closed: treat this as a denial unless you have a
+    considered reason not to.
+    """
+
+
+# ── Client ────────────────────────────────────────────────────────────────────
+
+
+class Client:
+    """A connection to one Prosader gateway for one agent.
+
+    Args:
+        gateway_url: Base URL of the gateway mediator (e.g.
+            ``https://gateway.example.com:8443``). Falls back to the
+            ``PROSADER_GATEWAY_URL`` environment variable.
+        api_key: Prosader API key (``psk-...``). Falls back to
+            ``PROSADER_API_KEY``. Optional; without it the gateway attributes
+            activity to the default tenant.
+        agent_id: Stable identifier for this agent, shown in the dashboard
+            and stamped on every receipt. Falls back to ``PROSADER_AGENT_ID``.
+        session_id: Groups related calls into one session. A fresh ID is
+            generated per Client if omitted.
+        verify_tls: Set to ``False`` only for gateways using a self-signed
+            certificate in development.
+        timeout: Per-request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        gateway_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        verify_tls: bool = True,
+        timeout: float = _DEFAULT_TIMEOUT_S,
+    ):
+        gateway_url = gateway_url or os.environ.get("PROSADER_GATEWAY_URL", "")
+        if not gateway_url:
+            raise ValueError(
+                "gateway_url is required (or set PROSADER_GATEWAY_URL)")
+        self.gateway_url = gateway_url.rstrip("/")
+        self.api_key = api_key or os.environ.get("PROSADER_API_KEY", "")
+        self.agent_id = agent_id or os.environ.get("PROSADER_AGENT_ID", "")
+        if not self.agent_id:
+            raise ValueError("agent_id is required (or set PROSADER_AGENT_ID)")
+        self.session_id = session_id or f"sdk-{uuid.uuid4().hex[:16]}"
+        self.timeout = timeout
+        self._ssl_context: Optional[ssl.SSLContext] = None
+        if not verify_tls:
+            self._ssl_context = ssl.create_default_context()
+            self._ssl_context.check_hostname = False
+            self._ssl_context.verify_mode = ssl.CERT_NONE
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def check(
+        self,
+        tool_name: str,
+        parameters: Optional[Dict[str, Any]] = None,
+        payload: Any = None,
+    ) -> Decision:
+        """Ask the gateway whether this tool call is allowed.
+
+        Sends a check-only request: the gateway evaluates policy and writes a
+        signed receipt but does not forward the call anywhere — executing the
+        tool remains the caller's responsibility.
+
+        Returns a :class:`Decision`. Raises :class:`BillingError` on quota or
+        subscription problems and :class:`GatewayError` when the gateway is
+        unreachable (fail closed: do not run the tool in that case).
+        """
+        body = {
+            "session_id": self.session_id,
+            "request_id": f"req-{uuid.uuid4().hex}",
+            "tool_name": tool_name,
+            "agent_id": self.agent_id,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        if parameters:
+            body["parameters"] = {str(k): _stringify(v) for k, v in parameters.items()}
+        if payload is not None:
+            body["payload"] = payload
+
+        status, headers, resp = self._post_action(body)
+
+        if status == 402:
+            raise BillingError(
+                resp.get("error", "payment required"),
+                status=resp.get("status", ""),
+                code=resp.get("code", ""),
+            )
+        if status == 400:
+            raise ProsaderError(
+                f"gateway rejected request: {resp.get('error', 'bad request')}")
+        if status not in (200, 429):
+            raise GatewayError(f"unexpected gateway response: HTTP {status}")
+
+        outcome = headers.get("X-Prosader-Decision", "")
+        if not outcome:
+            outcome = "ALLOW" if resp.get("allowed") else "DENY"
+        try:
+            latency_ms = int(headers.get("X-Prosader-Latency-Ms", "0"))
+        except ValueError:
+            latency_ms = 0
+
+        return Decision(
+            allowed=bool(resp.get("allowed", False)),
+            outcome=outcome,
+            reason=resp.get("reason", ""),
+            rule_id=resp.get("rule_id", ""),
+            receipt_id=resp.get("receipt_id", headers.get("X-Prosader-Receipt-ID", "")),
+            latency_ms=latency_ms,
+            raw=resp,
+        )
+
+    def wrap(self, tool_name: Optional[str] = None) -> Callable:
+        """Decorator: check with the gateway before every call to the function.
+
+        The function's arguments are sent as the tool call's parameters so
+        policy rules can match on them. Blocked calls raise :class:`Denied`
+        instead of executing.
+
+        ::
+
+            @client.wrap("bash")
+            def run_bash(command): ...
+        """
+        def decorator(fn: Callable) -> Callable:
+            name = tool_name or fn.__name__
+            try:
+                sig = inspect.signature(fn)
+            except (TypeError, ValueError):
+                sig = None
+
+            @functools.wraps(fn)
+            def guarded(*args: Any, **kwargs: Any) -> Any:
+                params: Dict[str, Any] = {}
+                if sig is not None:
+                    try:
+                        bound = sig.bind(*args, **kwargs)
+                        bound.apply_defaults()
+                        params = dict(bound.arguments)
+                    except TypeError:
+                        params = dict(kwargs)
+                else:
+                    params = dict(kwargs)
+
+                decision = self.check(name, parameters=params)
+                if not decision.allowed:
+                    raise Denied(decision)
+                return fn(*args, **kwargs)
+
+            return guarded
+
+        return decorator
+
+    # ── Internals ─────────────────────────────────────────────────────────────
+
+    def _post_action(self, body: Dict[str, Any]):
+        """POST the action to the gateway; returns (status, headers, json_body)."""
+        data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(
+            self.gateway_url + "/v1/action",
+            data=data,
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "X-Prosader-Check-Only": "true",
+                "User-Agent": f"prosader-python/{__version__}",
+            },
+        )
+        if self.api_key:
+            req.add_header("Authorization", f"Bearer {self.api_key}")
+
+        try:
+            with urllib.request.urlopen(
+                req, timeout=self.timeout, context=self._ssl_context
+            ) as r:
+                return r.status, dict(r.headers), _parse_json(r.read())
+        except urllib.error.HTTPError as e:
+            # Non-2xx responses (400/402/429/...) still carry a JSON body.
+            with e:
+                return e.code, dict(e.headers), _parse_json(e.read())
+        except (urllib.error.URLError, OSError, TimeoutError) as e:
+            raise GatewayError(f"gateway unreachable: {e}") from e
+
+
+def _stringify(v: Any) -> str:
+    """Render a parameter value the way policy rules expect to match it."""
+    if isinstance(v, str):
+        return v
+    try:
+        return json.dumps(v)
+    except (TypeError, ValueError):
+        return str(v)
+
+
+def _parse_json(raw: bytes) -> Dict[str, Any]:
+    try:
+        parsed = json.loads(raw)
+        return parsed if isinstance(parsed, dict) else {}
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return {}
+
+
+# ── Module-level convenience (single global client) ───────────────────────────
+
+_default_client: Optional[Client] = None
+
+
+def configure(**kwargs: Any) -> Client:
+    """Create and install the module-level default client.
+
+    Accepts the same arguments as :class:`Client`. After calling this,
+    :func:`prosader.check` and :func:`prosader.wrap` use the configured
+    client.
+    """
+    global _default_client
+    _default_client = Client(**kwargs)
+    return _default_client
+
+
+def _require_default() -> Client:
+    global _default_client
+    if _default_client is None:
+        # Attempt implicit configuration from environment variables.
+        _default_client = Client()
+    return _default_client
+
+
+def check(
+    tool_name: str,
+    parameters: Optional[Dict[str, Any]] = None,
+    payload: Any = None,
+) -> Decision:
+    """Module-level :meth:`Client.check` using the default client."""
+    return _require_default().check(tool_name, parameters=parameters, payload=payload)
+
+
+def wrap(tool_name: Optional[str] = None) -> Callable:
+    """Module-level :meth:`Client.wrap` using the default client.
+
+    The client is resolved at call time, so ``@prosader.wrap()`` can decorate
+    functions before :func:`configure` runs.
+    """
+    def decorator(fn: Callable) -> Callable:
+        try:
+            sig = inspect.signature(fn)
+        except (TypeError, ValueError):
+            sig = None
+        name = tool_name or fn.__name__
+
+        @functools.wraps(fn)
+        def guarded(*args: Any, **kwargs: Any) -> Any:
+            client = _require_default()
+            params: Dict[str, Any] = {}
+            if sig is not None:
+                try:
+                    bound = sig.bind(*args, **kwargs)
+                    bound.apply_defaults()
+                    params = dict(bound.arguments)
+                except TypeError:
+                    params = dict(kwargs)
+            else:
+                params = dict(kwargs)
+            decision = client.check(name, parameters=params)
+            if not decision.allowed:
+                raise Denied(decision)
+            return fn(*args, **kwargs)
+
+        return guarded
+
+    return decorator

prosader-0.1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: prosader
+Version: 0.1.0
+Summary: Guard AI agent tool calls with a Prosader runtime security gateway
+Author: Prosader
+License: Apache-2.0
+Project-URL: Homepage, https://prosader.com
+Keywords: ai-agents,security,audit,compliance,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Prosader Python SDK
+
+Guard AI agent tool calls with a [Prosader](https://prosader.com) runtime
+security gateway. Every guarded call is evaluated against your policy and
+produces a signed, tamper-evident audit receipt — evidence you can hand to an
+auditor and verify independently with `prosader-verify`.
+
+No dependencies: the SDK uses only the Python standard library (3.9+).
+
+## Install
+
+```bash
+pip install prosader
+```
+
+## Usage
+
+```python
+import prosader
+
+client = prosader.Client(
+    gateway_url="https://gateway.example.com:8443",
+    api_key="psk-live-...",
+    agent_id="billing-agent",
+)
+
+# Option 1 — explicit check before you execute a tool:
+decision = client.check("bash", parameters={"command": "rm -rf /tmp/cache"})
+if decision.allowed:
+    run_command(...)
+else:
+    print(f"blocked by rule {decision.rule_id}: {decision.reason}")
+    # decision.receipt_id — signed audit receipt either way
+
+# Option 2 — wrap a function; blocked calls raise prosader.Denied:
+@client.wrap("send_email")
+def send_email(to, subject, body):
+    ...
+
+try:
+    send_email(to="cfo@example.com", subject="Invoice", body="...")
+except prosader.Denied as e:
+    print(e.decision.reason)
+```
+
+Or configure once and use module-level helpers:
+
+```python
+prosader.configure(gateway_url="https://...", api_key="psk-...", agent_id="my-agent")
+
+@prosader.wrap("bash")
+def run_bash(command): ...
+```
+
+Configuration falls back to environment variables: `PROSADER_GATEWAY_URL`,
+`PROSADER_API_KEY`, `PROSADER_AGENT_ID`.
+
+## Outcomes
+
+| Outcome   | `decision.allowed` | Meaning                                            |
+|-----------|--------------------|----------------------------------------------------|
+| `ALLOW`   | `True`             | Proceed.                                           |
+| `DENY`    | `False`            | Blocked by policy (`rule_id`, `reason` populated). |
+| `STEP_UP` | `False`            | Held for human approval in the Prosader dashboard. |
+
+Errors:
+
+- `prosader.Denied` — raised by wrapped functions when blocked.
+- `prosader.BillingError` — subscription inactive or decision quota exhausted (HTTP 402).
+- `prosader.GatewayError` — gateway unreachable. Prosader is fail-closed:
+  treat this as a denial.
+
+## Notes
+
+- Function arguments of wrapped functions are sent as the tool call's
+  `parameters` so policy rules can match on them (e.g. deny `bash` where
+  `command` contains `rm -rf`).
+- For development gateways with a self-signed certificate, pass
+  `verify_tls=False`. Never do this in production.
+- Requires a gateway new enough to support check-only mode
+  (`X-Prosader-Check-Only`), July 2026 or later.
+
+## Running tests
+
+```bash
+python -m unittest discover -s tests -v
+```

prosader-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+prosader/__init__.py,sha256=paxeiWzp9hBpTqQO3gDh9PPLHy6fDxumzXVtXI-mlcE,13278
+prosader-0.1.0.dist-info/METADATA,sha256=cXpjWh2RSj5nm6L0arDeavrDR9kkV9Hjt9Bmkp9m0HU,3201
+prosader-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+prosader-0.1.0.dist-info/top_level.txt,sha256=l1ncwE0n8ZgCBMsHBzkzlKmkZnnur0SR1uE4km8pMyw,9
+prosader-0.1.0.dist-info/RECORD,,

prosader-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

prosader-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+prosader