prosader 0.1.0__tar.gz

prosader-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,87 @@
+# 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/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/prosader.egg-info/PKG-INFO

@@ -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/prosader.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+prosader/__init__.py
+prosader.egg-info/PKG-INFO
+prosader.egg-info/SOURCES.txt
+prosader.egg-info/dependency_links.txt
+prosader.egg-info/top_level.txt
+tests/test_client.py

prosader-0.1.0/prosader.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

prosader-0.1.0/prosader.egg-info/top_level.txt

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

prosader-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "prosader"
+version = "0.1.0"
+description = "Guard AI agent tool calls with a Prosader runtime security gateway"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Prosader" }]
+keywords = ["ai-agents", "security", "audit", "compliance", "mcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+]
+# Intentionally no runtime dependencies — standard library only.
+dependencies = []
+
+[project.urls]
+Homepage = "https://prosader.com"
+
+[tool.setuptools.packages.find]
+include = ["prosader*"]

prosader-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

prosader-0.1.0/tests/test_client.py

@@ -0,0 +1,196 @@
+"""Tests for the Prosader Python SDK against a stub gateway.
+
+Run from sdk/python/:  python -m unittest discover -s tests -v
+"""
+
+import json
+import os
+import sys
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+import prosader  # noqa: E402
+
+
+class StubGateway(BaseHTTPRequestHandler):
+    """Minimal stand-in for POST /v1/action.
+
+    Behaviour is driven by the requested tool_name:
+      allow_tool   → 200 allowed:true
+      deny_tool    → 200 allowed:false (DENY)
+      stepup_tool  → 200 allowed:false (STEP_UP)
+      billing_tool → 402
+      bad_tool     → 400
+    """
+
+    received = []  # (headers, body) of every request, newest last
+
+    def do_POST(self):  # noqa: N802
+        assert self.path == "/v1/action"
+        raw = self.rfile.read(int(self.headers.get("Content-Length", "0")))
+        body = json.loads(raw)
+        StubGateway.received.append((dict(self.headers), body))
+        tool = body.get("tool_name", "")
+
+        if tool == "billing_tool":
+            self._json(402, {"error": "monthly decision limit of 100 reached",
+                             "status": "limit_exceeded",
+                             "code": "DECISION_LIMIT_EXCEEDED"})
+            return
+        if tool == "bad_tool":
+            self._json(400, {"error": "missing required field: agent_id",
+                             "code": "VALIDATION_ERROR"})
+            return
+
+        if tool == "deny_tool":
+            outcome, resp = "DENY", {"allowed": False,
+                                     "reason": "forbidden by policy",
+                                     "rule_id": "FA-001",
+                                     "receipt_id": "rcpt-deny"}
+        elif tool == "stepup_tool":
+            outcome, resp = "STEP_UP", {"allowed": False,
+                                        "reason": "held for human approval",
+                                        "rule_id": "FA-007",
+                                        "receipt_id": "rcpt-stepup"}
+        else:
+            outcome, resp = "ALLOW", {"allowed": True, "receipt_id": "rcpt-allow"}
+
+        self._json(200, resp, extra={
+            "X-Prosader-Decision": outcome,
+            "X-Prosader-Receipt-ID": resp["receipt_id"],
+            "X-Prosader-Latency-Ms": "3",
+        })
+
+    def _json(self, status, obj, extra=None):
+        data = json.dumps(obj).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        for k, v in (extra or {}).items():
+            self.send_header(k, v)
+        self.end_headers()
+        self.wfile.write(data)
+
+    def log_message(self, *args):  # silence test output
+        pass
+
+
+class SDKTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = HTTPServer(("127.0.0.1", 0), StubGateway)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.url = f"http://127.0.0.1:{cls.server.server_port}"
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+
+    def setUp(self):
+        StubGateway.received.clear()
+        self.client = prosader.Client(
+            gateway_url=self.url, api_key="psk-test-123", agent_id="agent-test")
+
+    # ── check() ───────────────────────────────────────────────────────────────
+
+    def test_allow(self):
+        d = self.client.check("allow_tool", parameters={"path": "/tmp/x"})
+        self.assertTrue(d.allowed)
+        self.assertEqual(d.outcome, "ALLOW")
+        self.assertEqual(d.receipt_id, "rcpt-allow")
+        self.assertEqual(d.latency_ms, 3)
+
+    def test_deny(self):
+        d = self.client.check("deny_tool")
+        self.assertFalse(d.allowed)
+        self.assertEqual(d.outcome, "DENY")
+        self.assertEqual(d.rule_id, "FA-001")
+        self.assertEqual(d.reason, "forbidden by policy")
+
+    def test_step_up(self):
+        d = self.client.check("stepup_tool")
+        self.assertFalse(d.allowed)
+        self.assertEqual(d.outcome, "STEP_UP")
+
+    def test_billing_error(self):
+        with self.assertRaises(prosader.BillingError) as ctx:
+            self.client.check("billing_tool")
+        self.assertEqual(ctx.exception.code, "DECISION_LIMIT_EXCEEDED")
+
+    def test_bad_request(self):
+        with self.assertRaises(prosader.ProsaderError):
+            self.client.check("bad_tool")
+
+    def test_gateway_unreachable_raises(self):
+        dead = prosader.Client(
+            gateway_url="http://127.0.0.1:1", agent_id="agent-test", timeout=0.5)
+        with self.assertRaises(prosader.GatewayError):
+            dead.check("allow_tool")
+
+    def test_request_wire_format(self):
+        self.client.check("allow_tool", parameters={"n": 3, "cmd": "ls"})
+        headers, body = StubGateway.received[-1]
+        self.assertEqual(headers.get("X-Prosader-Check-Only"), "true")
+        self.assertEqual(headers.get("Authorization"), "Bearer psk-test-123")
+        self.assertEqual(body["agent_id"], "agent-test")
+        self.assertEqual(body["session_id"], self.client.session_id)
+        self.assertTrue(body["request_id"])
+        self.assertTrue(body["timestamp"])
+        # Non-string parameter values are stringified for rule matching.
+        self.assertEqual(body["parameters"], {"n": "3", "cmd": "ls"})
+
+    # ── wrap() ────────────────────────────────────────────────────────────────
+
+    def test_wrap_allows_and_passes_through(self):
+        @self.client.wrap("allow_tool")
+        def add(a, b=10):
+            return a + b
+
+        self.assertEqual(add(5), 15)
+        _, body = StubGateway.received[-1]
+        # Bound arguments (including defaults) become parameters.
+        self.assertEqual(body["parameters"], {"a": "5", "b": "10"})
+
+    def test_wrap_denied_raises_without_executing(self):
+        calls = []
+
+        @self.client.wrap("deny_tool")
+        def dangerous():
+            calls.append(1)
+
+        with self.assertRaises(prosader.Denied) as ctx:
+            dangerous()
+        self.assertEqual(calls, [])
+        self.assertEqual(ctx.exception.decision.rule_id, "FA-001")
+
+    def test_wrap_defaults_tool_name_to_function_name(self):
+        @self.client.wrap()
+        def allow_tool():
+            return "ran"
+
+        self.assertEqual(allow_tool(), "ran")
+        _, body = StubGateway.received[-1]
+        self.assertEqual(body["tool_name"], "allow_tool")
+
+    # ── module-level API ──────────────────────────────────────────────────────
+
+    def test_module_level_configure_and_wrap(self):
+        prosader.configure(
+            gateway_url=self.url, api_key="psk-test-123", agent_id="agent-mod")
+
+        @prosader.wrap("allow_tool")
+        def do_thing(x):
+            return x * 2
+
+        self.assertEqual(do_thing(4), 8)
+        _, body = StubGateway.received[-1]
+        self.assertEqual(body["agent_id"], "agent-mod")
+
+        self.assertTrue(prosader.check("allow_tool").allowed)
+
+
+if __name__ == "__main__":
+    unittest.main()