agentvalet 0.1.0__tar.gz

agentvalet-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

agentvalet-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: agentvalet
+Version: 0.1.0
+Summary: Call approved SaaS platforms from any Python agent. Your agent never holds the downstream credential.
+Project-URL: Homepage, https://agentvalet.ai
+Project-URL: Documentation, https://docs.agentvalet.ai
+Project-URL: Source, https://github.com/MCSEdwin/agentvalet
+Author: AgentValet
+License: MIT
+Keywords: agents,agentvalet,ai,authorization,credentials,mcp,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Requires-Dist: pyjwt[crypto]>=2.6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentvalet
+
+Call approved SaaS platforms from any Python agent. Your agent never holds the
+downstream credential — AgentValet signs a short-lived identity assertion,
+checks the call against the owner's grants and policy, injects the credential at
+call time, and writes an audit record.
+
+This is the Python port of
+[`@agentvalet/client`](https://www.npmjs.com/package/@agentvalet/client). Same
+endpoints, same approval semantics, same timings.
+
+## Install
+
+```bash
+pip install agentvalet
+```
+
+Python 3.9+. Two dependencies: `httpx` and `pyjwt[crypto]`.
+
+## Get an agent identity
+
+```bash
+agentvalet register --code <invite-or-enrollment-code>
+```
+
+The RSA keypair is generated **on your machine**. Only the public half is sent;
+the private key is written to `~/.agentvalet/agent.key` (mode 0600) and never
+crosses the wire. The code is either an invite's bind secret or the enrollment
+code from the "Try it free" flow.
+
+This writes the same files as `npx @agentvalet/register`, so the Node and Python
+tooling are interchangeable — you do not need Node installed.
+
+## Use it
+
+```python
+from agentvalet import AgentValet
+
+av = AgentValet.from_env()
+
+result = av.call(
+    platform="slack",
+    endpoint="/api/chat.postMessage",
+    method="POST",
+    scope="chat:write",
+    data={"channel": "#general", "text": "Deploy finished."},
+)
+```
+
+`from_env()` reads `AGENTVALET_AGENT_ID` / `AGENTVALET_OWNER_ID` (or the bare
+`AGENT_ID` / `OWNER_ID`) and finds the key via `AGENT_PRIVATE_KEY_B64`,
+`AGENT_PRIVATE_KEY_PATH`, `AGENT_PRIVATE_KEY`, or `~/.agentvalet/agent.key`. To
+wire it explicitly:
+
+```python
+av = AgentValet(
+    agent_id=os.environ["AGENT_ID"],
+    owner_id=os.environ["OWNER_ID"],
+    private_key=os.environ["AGENT_PRIVATE_KEY"],
+    proxy_url="https://api.agentvalet.ai",   # default
+)
+```
+
+Use it as a context manager to close the HTTP client cleanly:
+
+```python
+with AgentValet.from_env() as av:
+    av.call(platform="github", endpoint="/user", scope="read")
+```
+
+## Async
+
+`AsyncAgentValet` is a method-for-method mirror. All decision logic is shared,
+and the test suite runs the same behaviour table against both.
+
+```python
+from agentvalet import AsyncAgentValet
+
+async with AsyncAgentValet.from_env() as av:
+    result = await av.call(
+        platform="slack", endpoint="/api/chat.postMessage",
+        method="POST", scope="chat:write", data={...},
+    )
+```
+
+## Approvals are just a slower call
+
+When the owner has marked a scope as approval-gated, the proxy holds the action
+and `call()` waits. If the owner approves, the proxy re-runs the call and you
+get the result — from your code's point of view it simply took longer.
+
+```python
+av = AgentValet.from_env(
+    on_approval_pending=lambda i: print(f"waiting… {i['elapsed_s']:.0f}s")
+)
+```
+
+If nobody responds inside the budget (50s by default), you get an
+`ApprovalTimeoutError` — **not a failure**. The action stays queued. Keep the
+`approval_id` and resume whenever you like, in this process or another:
+
+```python
+from agentvalet import ApprovalTimeoutError
+
+try:
+    av.call(platform="stripe", endpoint="/v1/refunds", method="POST", scope="charge")
+except ApprovalTimeoutError as err:
+    queue.put(err.approval_id)          # hand off to a worker
+
+# …later, elsewhere:
+result = av.wait_for_approval(approval_id)
+```
+
+Pass `approval_timeout_s=0` if you never want to block.
+
+## Errors you can branch on
+
+Every exception is typed, so you never string-match an error envelope:
+
+| Error | Means | What to do |
+|---|---|---|
+| `ConfigError` | Bad/missing identity or key | Fix config; raised before any network call |
+| `NetworkError` | Transport failed | `.hint` diagnoses DNS / TLS / firewall / timeout |
+| `AccessDeniedError` | No grant, or policy blocked it | `request_access()` — see below |
+| `ApprovalDeniedError` | Owner said no | Terminal. Don't retry |
+| `ApprovalExpiredError` | Aged out server-side | Re-issue the call |
+| `ApprovalTimeoutError` | You stopped waiting | Resume via `wait_for_approval()` |
+| `UpstreamError` | The SaaS returned non-2xx | `.status` / `.data` hold the upstream reply |
+| `ProxyError` | Anything else from the broker | `.status` / `.body` |
+
+## Asking for access you don't have
+
+Deny-by-default means a scope you were never granted raises
+`AccessDeniedError`. Your agent can ask for it:
+
+```python
+result = av.request_access(
+    platform="slack",
+    scope="chat:write",
+    reason="Post deploy notifications to #general",
+)
+if result["status"] == "approved":
+    ...  # retry the original call
+```
+
+## Checking before you act
+
+```python
+av.list_platforms()                 # what this agent is actually granted
+av.pending_actions()                # queued behind an approval
+av.evaluate("stripe", "charge")     # dry-run the decision, no side effect
+```
+
+`evaluate()` is worth calling before anything destructive.
+
+## Self-hosting
+
+Point `proxy_url` at your own deployment. Everything else is identical.
+
+## License
+
+MIT

agentvalet-0.1.0/README.md

@@ -0,0 +1,162 @@
+# agentvalet
+
+Call approved SaaS platforms from any Python agent. Your agent never holds the
+downstream credential — AgentValet signs a short-lived identity assertion,
+checks the call against the owner's grants and policy, injects the credential at
+call time, and writes an audit record.
+
+This is the Python port of
+[`@agentvalet/client`](https://www.npmjs.com/package/@agentvalet/client). Same
+endpoints, same approval semantics, same timings.
+
+## Install
+
+```bash
+pip install agentvalet
+```
+
+Python 3.9+. Two dependencies: `httpx` and `pyjwt[crypto]`.
+
+## Get an agent identity
+
+```bash
+agentvalet register --code <invite-or-enrollment-code>
+```
+
+The RSA keypair is generated **on your machine**. Only the public half is sent;
+the private key is written to `~/.agentvalet/agent.key` (mode 0600) and never
+crosses the wire. The code is either an invite's bind secret or the enrollment
+code from the "Try it free" flow.
+
+This writes the same files as `npx @agentvalet/register`, so the Node and Python
+tooling are interchangeable — you do not need Node installed.
+
+## Use it
+
+```python
+from agentvalet import AgentValet
+
+av = AgentValet.from_env()
+
+result = av.call(
+    platform="slack",
+    endpoint="/api/chat.postMessage",
+    method="POST",
+    scope="chat:write",
+    data={"channel": "#general", "text": "Deploy finished."},
+)
+```
+
+`from_env()` reads `AGENTVALET_AGENT_ID` / `AGENTVALET_OWNER_ID` (or the bare
+`AGENT_ID` / `OWNER_ID`) and finds the key via `AGENT_PRIVATE_KEY_B64`,
+`AGENT_PRIVATE_KEY_PATH`, `AGENT_PRIVATE_KEY`, or `~/.agentvalet/agent.key`. To
+wire it explicitly:
+
+```python
+av = AgentValet(
+    agent_id=os.environ["AGENT_ID"],
+    owner_id=os.environ["OWNER_ID"],
+    private_key=os.environ["AGENT_PRIVATE_KEY"],
+    proxy_url="https://api.agentvalet.ai",   # default
+)
+```
+
+Use it as a context manager to close the HTTP client cleanly:
+
+```python
+with AgentValet.from_env() as av:
+    av.call(platform="github", endpoint="/user", scope="read")
+```
+
+## Async
+
+`AsyncAgentValet` is a method-for-method mirror. All decision logic is shared,
+and the test suite runs the same behaviour table against both.
+
+```python
+from agentvalet import AsyncAgentValet
+
+async with AsyncAgentValet.from_env() as av:
+    result = await av.call(
+        platform="slack", endpoint="/api/chat.postMessage",
+        method="POST", scope="chat:write", data={...},
+    )
+```
+
+## Approvals are just a slower call
+
+When the owner has marked a scope as approval-gated, the proxy holds the action
+and `call()` waits. If the owner approves, the proxy re-runs the call and you
+get the result — from your code's point of view it simply took longer.
+
+```python
+av = AgentValet.from_env(
+    on_approval_pending=lambda i: print(f"waiting… {i['elapsed_s']:.0f}s")
+)
+```
+
+If nobody responds inside the budget (50s by default), you get an
+`ApprovalTimeoutError` — **not a failure**. The action stays queued. Keep the
+`approval_id` and resume whenever you like, in this process or another:
+
+```python
+from agentvalet import ApprovalTimeoutError
+
+try:
+    av.call(platform="stripe", endpoint="/v1/refunds", method="POST", scope="charge")
+except ApprovalTimeoutError as err:
+    queue.put(err.approval_id)          # hand off to a worker
+
+# …later, elsewhere:
+result = av.wait_for_approval(approval_id)
+```
+
+Pass `approval_timeout_s=0` if you never want to block.
+
+## Errors you can branch on
+
+Every exception is typed, so you never string-match an error envelope:
+
+| Error | Means | What to do |
+|---|---|---|
+| `ConfigError` | Bad/missing identity or key | Fix config; raised before any network call |
+| `NetworkError` | Transport failed | `.hint` diagnoses DNS / TLS / firewall / timeout |
+| `AccessDeniedError` | No grant, or policy blocked it | `request_access()` — see below |
+| `ApprovalDeniedError` | Owner said no | Terminal. Don't retry |
+| `ApprovalExpiredError` | Aged out server-side | Re-issue the call |
+| `ApprovalTimeoutError` | You stopped waiting | Resume via `wait_for_approval()` |
+| `UpstreamError` | The SaaS returned non-2xx | `.status` / `.data` hold the upstream reply |
+| `ProxyError` | Anything else from the broker | `.status` / `.body` |
+
+## Asking for access you don't have
+
+Deny-by-default means a scope you were never granted raises
+`AccessDeniedError`. Your agent can ask for it:
+
+```python
+result = av.request_access(
+    platform="slack",
+    scope="chat:write",
+    reason="Post deploy notifications to #general",
+)
+if result["status"] == "approved":
+    ...  # retry the original call
+```
+
+## Checking before you act
+
+```python
+av.list_platforms()                 # what this agent is actually granted
+av.pending_actions()                # queued behind an approval
+av.evaluate("stripe", "charge")     # dry-run the decision, no side effect
+```
+
+`evaluate()` is worth calling before anything destructive.
+
+## Self-hosting
+
+Point `proxy_url` at your own deployment. Everything else is identical.
+
+## License
+
+MIT

agentvalet-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentvalet"
+version = "0.1.0"
+description = "Call approved SaaS platforms from any Python agent. Your agent never holds the downstream credential."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "AgentValet" }]
+keywords = ["ai", "agents", "agentvalet", "credentials", "authorization", "sdk", "mcp"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.24",
+  # [crypto] pulls `cryptography`, which also gives us RSA keygen for
+  # `agentvalet register` at no extra dependency cost.
+  "pyjwt[crypto]>=2.6",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.4",
+  "pytest-asyncio>=0.21",
+  "respx>=0.20",
+  "mypy>=1.8",
+  "ruff>=0.4",
+]
+
+[project.scripts]
+agentvalet = "agentvalet.register:main"
+
+[project.urls]
+Homepage = "https://agentvalet.ai"
+Documentation = "https://docs.agentvalet.ai"
+Source = "https://github.com/MCSEdwin/agentvalet"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentvalet"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+# Pin the rule set explicitly. Relying on ruff's defaults means the lint
+# surface silently changes on a ruff upgrade.
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests import their own conftest by name and shadow builtins freely.
+"tests/*" = ["E402", "E501"]  # long inline fixtures read better unwrapped
+
+[tool.mypy]
+# No python_version pin: recent mypy refuses 3.9 as a target, and the real
+# floor is enforced by requires-python. Strict still applies.
+strict = true

agentvalet-0.1.0/src/agentvalet/__init__.py

@@ -0,0 +1,55 @@
+"""agentvalet — call approved SaaS platforms from any Python agent.
+
+Your agent never holds the downstream credential. This client signs a
+short-lived RS256 identity assertion; the AgentValet broker checks it against
+the owner's grants and policy, injects the credential at call time, and writes
+an audit record.
+
+    from agentvalet import AgentValet
+
+    av = AgentValet.from_env()
+    av.call(
+        platform="slack",
+        endpoint="/api/chat.postMessage",
+        method="POST",
+        scope="chat:write",
+        data={"channel": "#general", "text": "Deploy finished."},
+    )
+
+Use :class:`agentvalet.aio.AsyncAgentValet` for the async equivalent.
+"""
+
+from __future__ import annotations
+
+from ._constants import DEFAULT_PROXY_URL
+from .aio import AsyncAgentValet
+from .client import AgentValet
+from .errors import (
+    AccessDeniedError,
+    AgentValetError,
+    ApprovalDeniedError,
+    ApprovalExpiredError,
+    ApprovalTimeoutError,
+    ConfigError,
+    NetworkError,
+    ProxyError,
+    UpstreamError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_PROXY_URL",
+    "AccessDeniedError",
+    "AgentValet",
+    "AgentValetError",
+    "ApprovalDeniedError",
+    "ApprovalExpiredError",
+    "ApprovalTimeoutError",
+    "AsyncAgentValet",
+    "ConfigError",
+    "NetworkError",
+    "ProxyError",
+    "UpstreamError",
+    "__version__",
+]

agentvalet-0.1.0/src/agentvalet/_constants.py

@@ -0,0 +1,31 @@
+"""Behavioural contract with the AgentValet proxy.
+
+These are NOT preferences. Each value is matched by
+``packages/client/src/client.ts`` (TypeScript) and ``apps/mcp-server``. If one
+of them changes here and not there, an operator debugging the Python SDK is no
+longer debugging the same system as the Node one.
+
+``tests/test_constants.py`` asserts every value, so changing one is a
+deliberate, reviewed act rather than a drive-by edit.
+
+Note the unit: the TypeScript client uses milliseconds; Python uses **seconds**,
+matching the httpx/requests convention. The underlying values are the same.
+"""
+
+DEFAULT_PROXY_URL = "https://api.agentvalet.ai"
+
+#: Approval long-poll budget. Sits under Claude Desktop's hardcoded 60s tool
+#: timeout so the MCP path and the SDK path give up at the same moment.
+APPROVAL_TIMEOUT_S = 50.0
+
+#: How often we ask the proxy whether the owner has decided.
+APPROVAL_POLL_S = 2.0
+
+#: Per-request network timeout.
+REQUEST_TIMEOUT_S = 15.0
+
+#: Agent assertions are deliberately short-lived; the proxy rejects long-dated
+#: ones. Seconds.
+JWT_LIFETIME_S = 60
+
+JWT_ALGORITHM = "RS256"

agentvalet-0.1.0/src/agentvalet/_protocol.py

@@ -0,0 +1,168 @@
+"""Pure protocol logic — no I/O, no awaits.
+
+Everything that decides *what* to send and *what a response means* lives here,
+so the sync and async clients can share it verbatim. Only transport differs
+between them. If you find yourself adding a branch to one client and not the
+other, it belongs in this module instead.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from .errors import (
+    AccessDeniedError,
+    ApprovalDeniedError,
+    ApprovalExpiredError,
+    ProxyError,
+    UpstreamError,
+)
+
+
+def build_action_body(
+    platform: str,
+    endpoint: str,
+    scope: str,
+    method: str = "GET",
+    data: Any = None,
+    connection_id: str | None = None,
+    reason: str | None = None,
+) -> dict[str, Any]:
+    """Wire body for ``POST /v1/actions``.
+
+    Optional fields are omitted entirely rather than sent as null — the proxy
+    distinguishes absent from null for ``data``.
+    """
+    body: dict[str, Any] = {
+        "platform": platform,
+        "endpoint": endpoint,
+        "method": method,
+        "scope": scope,
+    }
+    if data is not None:
+        body["data"] = data
+    if connection_id:
+        body["connection_id"] = connection_id
+    if reason:
+        body["reason"] = reason
+    return body
+
+
+def authzen_body(agent_id: str, platform: str, scope: str) -> dict[str, Any]:
+    return {
+        "subject": {"type": "agent", "id": agent_id},
+        "action": {"name": "tool_call"},
+        "resource": {"type": "platform_scope", "id": f"{platform}:{scope}"},
+    }
+
+
+def try_parse_json(text: str) -> Any:
+    """Parse only if it looks structured; otherwise hand back the raw text.
+
+    Mirrors the Node client so a non-JSON upstream body (a plain-text error,
+    an empty 204) surfaces identically in both SDKs.
+    """
+    trimmed = text.strip()
+    if not (trimmed.startswith("{") or trimmed.startswith("[")):
+        return text
+    try:
+        return json.loads(trimmed)
+    except ValueError:
+        return text
+
+
+def approval_id_from_202(text: str) -> str | None:
+    parsed = try_parse_json(text)
+    if isinstance(parsed, dict):
+        value = parsed.get("approval_id")
+        if isinstance(value, str):
+            return value
+    return None
+
+
+def interpret_action_response(
+    status: int, text: str, platform: str, scope: str
+) -> Any:
+    """Turn a ``/v1/actions`` reply into a value or the right exception.
+
+    Callers must handle the 202 branch *before* this — an approval is a
+    continuation, not a result.
+    """
+    if status == 403:
+        # The proxy's authorize pipeline denies with 403 for both "no grant"
+        # and "policy blocked". Its own type so callers can branch into
+        # request_access() instead of dead-ending on a generic failure.
+        raise AccessDeniedError(status, text, platform, scope)
+    if not 200 <= status < 300:
+        raise ProxyError(status, text)
+    return try_parse_json(text)
+
+
+def interpret_approval_status(payload: Mapping[str, Any], approval_id: str) -> tuple[bool, Any]:
+    """Interpret one poll of ``GET /v1/approvals/:id``.
+
+    Returns ``(done, value)``. ``done=False`` means keep polling. Terminal
+    failures raise.
+    """
+    status = payload.get("status")
+
+    if status == "denied":
+        raise ApprovalDeniedError(approval_id, _as_str(payload.get("execution_error")))
+    if status == "expired":
+        raise ApprovalExpiredError(approval_id)
+
+    execution_error = payload.get("execution_error")
+    if execution_error:
+        # Approved, but re-execution failed (upstream down, agent revoked
+        # between approval and execution).
+        raise ProxyError(502, f"Approved but re-execution failed: {execution_error}")
+
+    if status == "approved" and payload.get("executed_at") and payload.get("result"):
+        result = payload["result"]
+        upstream_status = int(result.get("status", 0))
+        if not 200 <= upstream_status < 300:
+            raise UpstreamError(upstream_status, result.get("data"))
+        return True, result.get("data")
+
+    return False, None
+
+
+def diagnose_network_error(err: BaseException, proxy_url: str) -> str:
+    """Turn a transport failure into something a developer can act on.
+
+    httpx's bare "Connection error" says nothing about whether it's DNS, a
+    corporate MITM proxy, or the broker being down.
+    """
+    raw = str(err)
+    lower = raw.lower()
+
+    if "getaddrinfo" in lower or "name or service not known" in lower or "nodename" in lower:
+        return (
+            f"Cannot resolve {proxy_url}. Check DNS / corporate proxy / VPN, or confirm "
+            f"proxy_url is correct. Raw: {raw}"
+        )
+    if "refused" in lower or "reset" in lower:
+        return (
+            f"Connection to {proxy_url} was refused or reset. The broker may be down — check "
+            f"https://status.agentvalet.ai — or a firewall is blocking it. Raw: {raw}"
+        )
+    if "timeout" in lower or "timed out" in lower:
+        return (
+            f"Request to {proxy_url} timed out. Likely VPN routing, corporate proxy buffering, "
+            f"or a slow network. Raw: {raw}"
+        )
+    if "certificate" in lower or "ssl" in lower or "tls" in lower:
+        return (
+            f"TLS / certificate problem talking to {proxy_url}. A corporate MITM proxy may be "
+            f"intercepting traffic. Raw: {raw}"
+        )
+    return (
+        f"Network error reaching {proxy_url}: {raw}. Check VPN, corporate proxy, and firewall "
+        f"rules for api.agentvalet.ai."
+    )
+
+
+def _as_str(value: Any) -> str | None:
+    return value if isinstance(value, str) else None