agent-vault-sdk 0.1.0__tar.gz

agent_vault_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: agent-vault-sdk
+Version: 0.1.0
+Summary: Zero-trust credential manager for AI agents — Python SDK
+Author: agent-vault contributors
+License: MIT
+Project-URL: Homepage, https://github.com/ewimsatt/agent-vault
+Project-URL: Repository, https://github.com/ewimsatt/agent-vault
+Project-URL: Issues, https://github.com/ewimsatt/agent-vault/issues
+Keywords: security,encryption,credentials,ai-agents,age,mcp
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyrage>=1.2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: gitpython>=3.1
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# agent-vault Python SDK
+
+Read-only Python SDK for [agent-vault](https://github.com/ewimsatt/agent-vault) — a zero-trust credential manager for AI agents.
+
+## Installation
+
+```bash
+pip install agent-vault
+
+# With MCP server support:
+pip install 'agent-vault[mcp]'
+```
+
+## Quick Start
+
+```python
+from agent_vault import Vault
+
+vault = Vault(
+    repo_path="/path/to/vault",
+    key_path="~/.agent-vault/agents/my-agent.key",
+)
+
+# Pull latest and decrypt
+api_key = vault.get("stripe/api-key")
+```
+
+## Key Resolution
+
+The SDK resolves the identity key in this order:
+
+1. `key_str=` parameter (raw key string)
+2. `key_path=` parameter (path to key file)
+3. `AGENT_VAULT_KEY` environment variable (key as string)
+4. `~/.agent-vault/owner.key` (default owner key)
+
+## API
+
+### `Vault(repo_path, key_path=None, key_str=None, auto_pull=True)`
+
+Create a read-only vault connection.
+
+- `repo_path`: Path to the Git repo containing `.agent-vault/`
+- `key_path`: Path to an age private key file
+- `key_str`: Raw age private key string
+- `auto_pull`: Git pull before each `get()` (default: True)
+
+### `vault.get(secret_path) -> str`
+
+Decrypt and return a secret. Raises `SecretNotFoundError` or `NotAuthorizedError`.
+
+### `vault.list_secrets(group=None) -> list[SecretMetadata]`
+
+List secret metadata without decrypting.
+
+### `vault.list_agents() -> list[dict]`
+
+List agents and their group memberships.
+
+### `vault.pull()`
+
+Manually pull latest changes from Git remote.
+
+### `vault.reload()`
+
+Reload the manifest from disk (e.g., after a pull).
+
+## MCP Server
+
+The package includes an MCP server for use with MCP-compatible AI agents:
+
+```bash
+agent-vault-mcp --repo /path/to/vault --key ~/.agent-vault/agents/my-agent.key
+```
+
+This runs a stdio-based MCP server exposing:
+
+- `agent_vault_get(secret)` — retrieve and decrypt a secret
+- `agent_vault_list(group?)` — list available secrets
+
+### Claude Desktop Configuration
+
+```json
+{
+  "mcpServers": {
+    "agent-vault": {
+      "command": "agent-vault-mcp",
+      "args": ["--repo", "/path/to/vault", "--key", "/path/to/agent.key"]
+    }
+  }
+}
+```

agent_vault_sdk-0.1.0/README.md

@@ -0,0 +1,92 @@
+# agent-vault Python SDK
+
+Read-only Python SDK for [agent-vault](https://github.com/ewimsatt/agent-vault) — a zero-trust credential manager for AI agents.
+
+## Installation
+
+```bash
+pip install agent-vault
+
+# With MCP server support:
+pip install 'agent-vault[mcp]'
+```
+
+## Quick Start
+
+```python
+from agent_vault import Vault
+
+vault = Vault(
+    repo_path="/path/to/vault",
+    key_path="~/.agent-vault/agents/my-agent.key",
+)
+
+# Pull latest and decrypt
+api_key = vault.get("stripe/api-key")
+```
+
+## Key Resolution
+
+The SDK resolves the identity key in this order:
+
+1. `key_str=` parameter (raw key string)
+2. `key_path=` parameter (path to key file)
+3. `AGENT_VAULT_KEY` environment variable (key as string)
+4. `~/.agent-vault/owner.key` (default owner key)
+
+## API
+
+### `Vault(repo_path, key_path=None, key_str=None, auto_pull=True)`
+
+Create a read-only vault connection.
+
+- `repo_path`: Path to the Git repo containing `.agent-vault/`
+- `key_path`: Path to an age private key file
+- `key_str`: Raw age private key string
+- `auto_pull`: Git pull before each `get()` (default: True)
+
+### `vault.get(secret_path) -> str`
+
+Decrypt and return a secret. Raises `SecretNotFoundError` or `NotAuthorizedError`.
+
+### `vault.list_secrets(group=None) -> list[SecretMetadata]`
+
+List secret metadata without decrypting.
+
+### `vault.list_agents() -> list[dict]`
+
+List agents and their group memberships.
+
+### `vault.pull()`
+
+Manually pull latest changes from Git remote.
+
+### `vault.reload()`
+
+Reload the manifest from disk (e.g., after a pull).
+
+## MCP Server
+
+The package includes an MCP server for use with MCP-compatible AI agents:
+
+```bash
+agent-vault-mcp --repo /path/to/vault --key ~/.agent-vault/agents/my-agent.key
+```
+
+This runs a stdio-based MCP server exposing:
+
+- `agent_vault_get(secret)` — retrieve and decrypt a secret
+- `agent_vault_list(group?)` — list available secrets
+
+### Claude Desktop Configuration
+
+```json
+{
+  "mcpServers": {
+    "agent-vault": {
+      "command": "agent-vault-mcp",
+      "args": ["--repo", "/path/to/vault", "--key", "/path/to/agent.key"]
+    }
+  }
+}
+```

agent_vault_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-vault-sdk"
+version = "0.1.0"
+description = "Zero-trust credential manager for AI agents — Python SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "agent-vault contributors"}]
+keywords = ["security", "encryption", "credentials", "ai-agents", "age", "mcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "pyrage>=1.2.0",
+    "pyyaml>=6.0",
+    "gitpython>=3.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/ewimsatt/agent-vault"
+Repository = "https://github.com/ewimsatt/agent-vault"
+Issues = "https://github.com/ewimsatt/agent-vault/issues"
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.2.0"]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+]
+
+[project.scripts]
+agent-vault-mcp = "agent_vault.mcp_server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

agent_vault_sdk-0.1.0/setup.cfg

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

agent_vault_sdk-0.1.0/src/agent_vault/__init__.py

@@ -0,0 +1,18 @@
+"""agent-vault: Zero-trust credential manager for AI agents."""
+
+from agent_vault.vault import Vault
+from agent_vault.errors import (
+    VaultError,
+    VaultNotFoundError,
+    SecretNotFoundError,
+    NotAuthorizedError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Vault",
+    "VaultError",
+    "VaultNotFoundError",
+    "SecretNotFoundError",
+    "NotAuthorizedError",
+]

agent_vault_sdk-0.1.0/src/agent_vault/crypto.py

@@ -0,0 +1,33 @@
+"""Cryptographic operations using pyrage (age encryption)."""
+
+from __future__ import annotations
+
+from pyrage import decrypt, x25519
+
+
+def load_identity(key_path: str) -> x25519.Identity:
+    """Load an age x25519 identity (private key) from a file.
+
+    The file should contain a line starting with AGE-SECRET-KEY-.
+    """
+    with open(key_path, "r") as f:
+        for line in f:
+            line = line.strip()
+            if line.startswith("AGE-SECRET-KEY-"):
+                return x25519.Identity.from_str(line)
+    raise ValueError(f"No age secret key found in {key_path}")
+
+
+def load_identity_from_str(key_str: str) -> x25519.Identity:
+    """Load an age x25519 identity from a string."""
+    for line in key_str.splitlines():
+        line = line.strip()
+        if line.startswith("AGE-SECRET-KEY-"):
+            return x25519.Identity.from_str(line)
+    raise ValueError("No age secret key found in provided string")
+
+
+def decrypt_secret(ciphertext: bytes, identity: x25519.Identity) -> str:
+    """Decrypt an age-encrypted secret and return the plaintext string."""
+    plaintext_bytes = decrypt(ciphertext, [identity])
+    return plaintext_bytes.decode("utf-8")

agent_vault_sdk-0.1.0/src/agent_vault/errors.py

@@ -0,0 +1,21 @@
+"""Error types for agent-vault."""
+
+
+class VaultError(Exception):
+    """Base error for all vault operations."""
+
+
+class VaultNotFoundError(VaultError):
+    """No .agent-vault directory found at the given path."""
+
+
+class SecretNotFoundError(VaultError):
+    """The requested secret does not exist in the vault."""
+
+
+class NotAuthorizedError(VaultError):
+    """The provided key cannot decrypt the requested secret."""
+
+
+class ManifestError(VaultError):
+    """Error parsing or querying the manifest."""

agent_vault_sdk-0.1.0/src/agent_vault/manifest.py

@@ -0,0 +1,76 @@
+"""Manifest parsing for vault access control."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from agent_vault.errors import ManifestError
+
+
+class Manifest:
+    """Parsed manifest.yaml — access control policy."""
+
+    def __init__(self, data: dict):
+        self._data = data
+        self._agents = {a["name"]: a for a in data.get("agents", [])}
+        self._groups = {g["name"]: g for g in data.get("groups", [])}
+
+    @classmethod
+    def load(cls, path: Path) -> "Manifest":
+        """Load a manifest from a YAML file."""
+        try:
+            with open(path, "r") as f:
+                data = yaml.safe_load(f) or {}
+        except FileNotFoundError:
+            raise ManifestError(f"Manifest not found: {path}")
+        except yaml.YAMLError as e:
+            raise ManifestError(f"Invalid manifest YAML: {e}")
+        return cls(data)
+
+    def agent_groups(self, agent_name: str) -> list[str]:
+        """Return the list of groups an agent belongs to."""
+        agent = self._agents.get(agent_name)
+        if agent is None:
+            return []
+        return list(agent.get("groups", []))
+
+    def group_secrets(self, group_name: str) -> list[str]:
+        """Return the list of secret paths in a group."""
+        group = self._groups.get(group_name)
+        if group is None:
+            return []
+        return list(group.get("secrets", []))
+
+    def agents_for_secret(self, secret_path: str) -> list[str]:
+        """Return agent names authorized for a given secret."""
+        agents = []
+        for agent_name, agent in self._agents.items():
+            for group_name in agent.get("groups", []):
+                group = self._groups.get(group_name)
+                if group and secret_path in group.get("secrets", []):
+                    agents.append(agent_name)
+                    break
+        return agents
+
+    def list_agents(self) -> list[dict]:
+        """Return all agents with their group memberships."""
+        return [
+            {"name": a["name"], "groups": list(a.get("groups", []))}
+            for a in self._data.get("agents", [])
+        ]
+
+    def list_groups(self) -> list[str]:
+        """Return all group names."""
+        return list(self._groups.keys())
+
+    def list_secrets(self, group: Optional[str] = None) -> list[str]:
+        """Return all secret paths, optionally filtered by group."""
+        if group is not None:
+            return self.group_secrets(group)
+        secrets = []
+        for g in self._groups.values():
+            secrets.extend(g.get("secrets", []))
+        return secrets

agent_vault_sdk-0.1.0/src/agent_vault/mcp_server.py

@@ -0,0 +1,117 @@
+"""MCP server exposing agent_vault_get tool via stdio transport.
+
+Usage:
+    agent-vault-mcp --repo /path/to/vault --key ~/.agent-vault/agents/my-agent.key
+
+The server holds the agent's private key in memory so the agent process
+never touches key material directly.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+
+def create_server(repo_path: str, key_path: str | None = None, key_str: str | None = None):
+    """Create and configure the MCP server.
+
+    Importing mcp is deferred so the module can be imported without the
+    mcp extra installed (e.g., for type checking or vault-only usage).
+    """
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError:
+        print(
+            "Error: MCP server requires the 'mcp' extra.\n"
+            "Install with: pip install 'agent-vault[mcp]'",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    from agent_vault.vault import Vault
+
+    vault = Vault(
+        repo_path=repo_path,
+        key_path=key_path,
+        key_str=key_str,
+        auto_pull=True,
+    )
+
+    mcp = FastMCP("agent-vault")
+
+    @mcp.tool()
+    def agent_vault_get(secret: str) -> str:
+        """Retrieve a decrypted secret from the agent-vault.
+
+        Args:
+            secret: The secret path (e.g. "stripe/api-key").
+
+        Returns:
+            The decrypted plaintext value.
+        """
+        return vault.get(secret)
+
+    @mcp.tool()
+    def agent_vault_list(group: str | None = None) -> str:
+        """List available secrets in the vault.
+
+        Args:
+            group: Optional group name to filter by.
+
+        Returns:
+            A formatted list of secrets with metadata.
+        """
+        secrets = vault.list_secrets(group)
+        if not secrets:
+            return "No secrets found."
+
+        lines = []
+        for meta in secrets:
+            expires_str = ""
+            if meta.expires:
+                expires_str = f"  expires={meta.expires.strftime('%Y-%m-%d')}"
+            lines.append(
+                f"{meta.name}  group={meta.group}  "
+                f"agents=[{', '.join(meta.authorized_agents)}]  "
+                f"rotated={meta.rotated.strftime('%Y-%m-%d')}"
+                f"{expires_str}"
+            )
+        return "\n".join(lines)
+
+    return mcp
+
+
+def main():
+    """Entry point for the agent-vault-mcp command."""
+    parser = argparse.ArgumentParser(
+        description="MCP server for agent-vault credential retrieval"
+    )
+    parser.add_argument(
+        "--repo",
+        default=os.getcwd(),
+        help="Path to the Git repository containing the vault (default: cwd)",
+    )
+    parser.add_argument(
+        "--key",
+        default=None,
+        help="Path to the agent's private key file",
+    )
+    args = parser.parse_args()
+
+    # Also support AGENT_VAULT_KEY env var (key as string)
+    key_str = os.environ.get("AGENT_VAULT_KEY")
+
+    server = create_server(
+        repo_path=args.repo,
+        key_path=args.key,
+        key_str=key_str if not args.key else None,
+    )
+
+    server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

agent_vault_sdk-0.1.0/src/agent_vault/metadata.py

@@ -0,0 +1,46 @@
+"""Secret metadata parsing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+@dataclass
+class SecretMetadata:
+    """Plaintext metadata for a single secret."""
+
+    name: str
+    group: str
+    created: datetime
+    rotated: datetime
+    expires: Optional[datetime]
+    authorized_agents: list[str]
+
+    @classmethod
+    def load(cls, path: Path) -> "SecretMetadata":
+        """Load metadata from a .meta YAML file."""
+        with open(path, "r") as f:
+            data = yaml.safe_load(f) or {}
+
+        return cls(
+            name=data.get("name", ""),
+            group=data.get("group", ""),
+            created=_parse_dt(data.get("created")),
+            rotated=_parse_dt(data.get("rotated")),
+            expires=_parse_dt(data.get("expires")) if data.get("expires") else None,
+            authorized_agents=list(data.get("authorized_agents", [])),
+        )
+
+
+def _parse_dt(val) -> datetime:
+    """Parse a datetime from YAML (may be string or datetime)."""
+    if isinstance(val, datetime):
+        return val
+    if isinstance(val, str):
+        return datetime.fromisoformat(val)
+    return datetime.min

agent_vault_sdk-0.1.0/src/agent_vault/vault.py

@@ -0,0 +1,233 @@
+"""Main Vault class — read-only agent access to secrets."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+from agent_vault.crypto import decrypt_secret, load_identity, load_identity_from_str
+from agent_vault.errors import (
+    NotAuthorizedError,
+    SecretNotFoundError,
+    VaultNotFoundError,
+)
+from agent_vault.manifest import Manifest
+from agent_vault.metadata import SecretMetadata
+
+logger = logging.getLogger("agent_vault")
+
+
+def _resolve_repo_path(repo_path: str | Path) -> Path:
+    """Resolve repo_path to a local directory.
+
+    If repo_path is a Git remote URL (https://, git@, ssh://, git://),
+    clones or updates a cached copy under ~/.agent-vault/cache/<hash>.
+    Otherwise returns the local path directly.
+    """
+    path_str = str(repo_path)
+
+    if not any(
+        path_str.startswith(prefix)
+        for prefix in ("https://", "git@", "ssh://", "git://")
+    ):
+        return Path(repo_path).expanduser().resolve()
+
+    # Compute stable cache directory from URL
+    url_hash = hashlib.sha256(path_str.encode()).hexdigest()[:16]
+    cache_dir = Path.home() / ".agent-vault" / "cache" / url_hash
+
+    try:
+        import git as gitmodule
+
+        if cache_dir.exists() and (cache_dir / ".git").exists():
+            try:
+                repo = gitmodule.Repo(str(cache_dir))
+                if repo.remotes:
+                    repo.remotes[0].pull(rebase=False)
+            except Exception as e:
+                logger.warning("git pull failed for cached repo: %s", e)
+                print(
+                    f"Warning: git pull failed for cached repo: {e}",
+                    file=sys.stderr,
+                )
+        else:
+            cache_dir.parent.mkdir(parents=True, exist_ok=True)
+            gitmodule.Repo.clone_from(path_str, str(cache_dir))
+    except Exception as e:
+        raise VaultNotFoundError(f"Failed to clone/update {path_str}: {e}") from e
+
+    return cache_dir
+
+
+class Vault:
+    """Read-only vault for agents to retrieve secrets.
+
+    Example::
+
+        vault = Vault(
+            repo_path="/path/to/vault",
+            key_path="~/.agent-vault/agents/my-agent.key",
+        )
+        api_key = vault.get("stripe/api-key")
+    """
+
+    def __init__(
+        self,
+        repo_path: str | Path,
+        key_path: Optional[str | Path] = None,
+        key_str: Optional[str] = None,
+        auto_pull: bool = True,
+    ):
+        """Initialize the vault.
+
+        Args:
+            repo_path: Path to the Git repository (local or remote URL).
+            key_path: Path to the age private key file. If not provided,
+                falls back to AGENT_VAULT_KEY env var (as key string),
+                then ~/.agent-vault/owner.key.
+            key_str: Raw age private key string. Overrides key_path.
+            auto_pull: Whether to git pull before each get() call.
+        """
+        self._repo_path = _resolve_repo_path(repo_path)
+        self._vault_dir = self._repo_path / ".agent-vault"
+        self._auto_pull = auto_pull
+
+        if not self._vault_dir.is_dir():
+            raise VaultNotFoundError(
+                f"No vault found at {self._repo_path}. "
+                "Run 'agent-vault init' first."
+            )
+
+        # Load identity (private key)
+        if key_str is not None:
+            self._identity = load_identity_from_str(key_str)
+        elif key_path is not None:
+            self._identity = load_identity(str(Path(key_path).expanduser()))
+        elif os.environ.get("AGENT_VAULT_KEY"):
+            self._identity = load_identity_from_str(os.environ["AGENT_VAULT_KEY"])
+        else:
+            default_key = Path.home() / ".agent-vault" / "owner.key"
+            if default_key.exists():
+                self._identity = load_identity(str(default_key))
+            else:
+                raise VaultNotFoundError(
+                    "No key provided. Pass key_path=, key_str=, "
+                    "set AGENT_VAULT_KEY env var, or ensure "
+                    "~/.agent-vault/owner.key exists."
+                )
+
+        # Load manifest
+        self._manifest = Manifest.load(self._vault_dir / "manifest.yaml")
+
+    def pull(self) -> None:
+        """Pull latest changes from the Git remote (best-effort)."""
+        try:
+            import git
+
+            repo = git.Repo(str(self._repo_path))
+            if repo.remotes:
+                origin = repo.remotes[0]
+                origin.pull(rebase=False)
+        except Exception as e:
+            logger.warning("git pull failed (continuing with local state): %s", e)
+            print(f"Warning: git pull failed: {e}", file=sys.stderr)
+
+    def get(self, secret_path: str) -> str:
+        """Retrieve and decrypt a secret.
+
+        Args:
+            secret_path: The secret path (e.g. "stripe/api-key").
+
+        Returns:
+            The decrypted plaintext value.
+
+        Raises:
+            SecretNotFoundError: If the secret doesn't exist.
+            NotAuthorizedError: If the key can't decrypt the secret.
+        """
+        if self._auto_pull:
+            self.pull()
+
+        # Resolve the encrypted file path
+        # Secret path "stripe/api-key" -> .agent-vault/secrets/stripe/api-key.enc
+        enc_path = self._vault_dir / "secrets" / _to_file_path(secret_path, ".enc")
+
+        if not enc_path.exists():
+            raise SecretNotFoundError(f"Secret not found: {secret_path}")
+
+        ciphertext = enc_path.read_bytes()
+
+        try:
+            return decrypt_secret(ciphertext, self._identity)
+        except Exception as e:
+            raise NotAuthorizedError(
+                f"Cannot decrypt '{secret_path}': {e}"
+            ) from e
+
+    def list_secrets(self, group: Optional[str] = None) -> list[SecretMetadata]:
+        """List secret metadata without decrypting.
+
+        Args:
+            group: Optional group name to filter by.
+
+        Returns:
+            List of SecretMetadata objects.
+        """
+        secrets_dir = self._vault_dir / "secrets"
+        if not secrets_dir.exists():
+            return []
+
+        results = []
+        for meta_path in sorted(secrets_dir.rglob("*.meta")):
+            try:
+                meta = SecretMetadata.load(meta_path)
+                if group is None or meta.group == group:
+                    results.append(meta)
+            except Exception:
+                continue
+
+        return results
+
+    def list_agents(self) -> list[dict]:
+        """List all agents and their group memberships.
+
+        Returns:
+            List of dicts with "name" and "groups" keys.
+        """
+        return self._manifest.list_agents()
+
+    @property
+    def manifest(self) -> Manifest:
+        """Access the parsed manifest."""
+        return self._manifest
+
+    def reload(self) -> None:
+        """Reload the manifest from disk (e.g. after a pull)."""
+        self._manifest = Manifest.load(self._vault_dir / "manifest.yaml")
+
+    def __enter__(self) -> "Vault":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        return False
+
+
+def _to_file_path(secret_path: str, suffix: str) -> Path:
+    """Convert a secret path like "stripe/api-key" to a file path.
+
+    The convention used by the Rust CLI is:
+      secret_path = "group/name"
+      file = secrets/group/name.enc (and .meta)
+
+    But the actual file path uses the last component as the filename.
+    e.g. "stripe/api-key" -> "stripe/api-key.enc"
+    """
+    parts = secret_path.split("/")
+    if len(parts) < 2:
+        return Path(parts[0] + suffix)
+    # group/name -> group/name.enc
+    return Path(*parts[:-1]) / (parts[-1] + suffix)

agent_vault_sdk-0.1.0/src/agent_vault_sdk.egg-info/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: agent-vault-sdk
+Version: 0.1.0
+Summary: Zero-trust credential manager for AI agents — Python SDK
+Author: agent-vault contributors
+License: MIT
+Project-URL: Homepage, https://github.com/ewimsatt/agent-vault
+Project-URL: Repository, https://github.com/ewimsatt/agent-vault
+Project-URL: Issues, https://github.com/ewimsatt/agent-vault/issues
+Keywords: security,encryption,credentials,ai-agents,age,mcp
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyrage>=1.2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: gitpython>=3.1
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# agent-vault Python SDK
+
+Read-only Python SDK for [agent-vault](https://github.com/ewimsatt/agent-vault) — a zero-trust credential manager for AI agents.
+
+## Installation
+
+```bash
+pip install agent-vault
+
+# With MCP server support:
+pip install 'agent-vault[mcp]'
+```
+
+## Quick Start
+
+```python
+from agent_vault import Vault
+
+vault = Vault(
+    repo_path="/path/to/vault",
+    key_path="~/.agent-vault/agents/my-agent.key",
+)
+
+# Pull latest and decrypt
+api_key = vault.get("stripe/api-key")
+```
+
+## Key Resolution
+
+The SDK resolves the identity key in this order:
+
+1. `key_str=` parameter (raw key string)
+2. `key_path=` parameter (path to key file)
+3. `AGENT_VAULT_KEY` environment variable (key as string)
+4. `~/.agent-vault/owner.key` (default owner key)
+
+## API
+
+### `Vault(repo_path, key_path=None, key_str=None, auto_pull=True)`
+
+Create a read-only vault connection.
+
+- `repo_path`: Path to the Git repo containing `.agent-vault/`
+- `key_path`: Path to an age private key file
+- `key_str`: Raw age private key string
+- `auto_pull`: Git pull before each `get()` (default: True)
+
+### `vault.get(secret_path) -> str`
+
+Decrypt and return a secret. Raises `SecretNotFoundError` or `NotAuthorizedError`.
+
+### `vault.list_secrets(group=None) -> list[SecretMetadata]`
+
+List secret metadata without decrypting.
+
+### `vault.list_agents() -> list[dict]`
+
+List agents and their group memberships.
+
+### `vault.pull()`
+
+Manually pull latest changes from Git remote.
+
+### `vault.reload()`
+
+Reload the manifest from disk (e.g., after a pull).
+
+## MCP Server
+
+The package includes an MCP server for use with MCP-compatible AI agents:
+
+```bash
+agent-vault-mcp --repo /path/to/vault --key ~/.agent-vault/agents/my-agent.key
+```
+
+This runs a stdio-based MCP server exposing:
+
+- `agent_vault_get(secret)` — retrieve and decrypt a secret
+- `agent_vault_list(group?)` — list available secrets
+
+### Claude Desktop Configuration
+
+```json
+{
+  "mcpServers": {
+    "agent-vault": {
+      "command": "agent-vault-mcp",
+      "args": ["--repo", "/path/to/vault", "--key", "/path/to/agent.key"]
+    }
+  }
+}
+```

agent_vault_sdk-0.1.0/src/agent_vault_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/agent_vault/__init__.py
+src/agent_vault/crypto.py
+src/agent_vault/errors.py
+src/agent_vault/manifest.py
+src/agent_vault/mcp_server.py
+src/agent_vault/metadata.py
+src/agent_vault/vault.py
+src/agent_vault_sdk.egg-info/PKG-INFO
+src/agent_vault_sdk.egg-info/SOURCES.txt
+src/agent_vault_sdk.egg-info/dependency_links.txt
+src/agent_vault_sdk.egg-info/entry_points.txt
+src/agent_vault_sdk.egg-info/requires.txt
+src/agent_vault_sdk.egg-info/top_level.txt
+tests/test_vault.py

agent_vault_sdk-0.1.0/src/agent_vault_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_vault_sdk-0.1.0/src/agent_vault_sdk.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-vault-mcp = agent_vault.mcp_server:main

agent_vault_sdk-0.1.0/src/agent_vault_sdk.egg-info/requires.txt

@@ -0,0 +1,10 @@
+pyrage>=1.2.0
+pyyaml>=6.0
+gitpython>=3.1
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21
+
+[mcp]
+mcp>=1.2.0

agent_vault_sdk-0.1.0/src/agent_vault_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+agent_vault

agent_vault_sdk-0.1.0/tests/test_vault.py

@@ -0,0 +1,337 @@
+"""Tests for agent-vault Python SDK.
+
+These tests create a vault using the Rust CLI, then verify the Python SDK
+can read secrets, list metadata, and handle errors correctly.
+"""
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from agent_vault import Vault, SecretNotFoundError, NotAuthorizedError, VaultNotFoundError
+
+
+# Resolve the pre-built binary path once at module load
+_BINARY = str(Path(__file__).parent.parent.parent / "target" / "debug" / "agent-vault")
+
+
+def _run_cli(*args, cwd, env):
+    """Run the agent-vault CLI binary."""
+    result = subprocess.run(
+        [_BINARY] + list(args),
+        cwd=cwd,
+        env=env,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"CLI failed: {args}\nstdout: {result.stdout}\nstderr: {result.stderr}"
+        )
+    return result
+
+
+@pytest.fixture
+def vault_env(tmp_path):
+    """Set up a temporary vault with a secret for testing."""
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    fake_home = tmp_path / "fakehome"
+    fake_home.mkdir()
+
+    env = os.environ.copy()
+    env["HOME"] = str(fake_home)
+
+    # Init git repo
+    subprocess.run(["git", "init", str(repo)], capture_output=True, check=True)
+    subprocess.run(
+        ["git", "config", "user.email", "test@test.com"],
+        cwd=str(repo), capture_output=True, check=True
+    )
+    subprocess.run(
+        ["git", "config", "user.name", "Test"],
+        cwd=str(repo), capture_output=True, check=True
+    )
+
+    # Init vault
+    _run_cli("init", cwd=str(repo), env=env)
+
+    # Add agent
+    _run_cli("add-agent", "test-bot", cwd=str(repo), env=env)
+
+    # Set a secret
+    _run_cli("set", "stripe/api-key", "sk_test_123", cwd=str(repo), env=env)
+
+    # Grant agent access
+    _run_cli("grant", "test-bot", "stripe", cwd=str(repo), env=env)
+
+    owner_key = fake_home / ".agent-vault" / "owner.key"
+    agent_key = fake_home / ".agent-vault" / "agents" / "test-bot.key"
+
+    return {
+        "repo": repo,
+        "fake_home": fake_home,
+        "env": env,
+        "owner_key": owner_key,
+        "agent_key": agent_key,
+    }
+
+
+class TestVaultInit:
+    def test_vault_not_found(self, tmp_path):
+        """Opening a vault on a dir without .agent-vault raises."""
+        with pytest.raises(VaultNotFoundError):
+            Vault(repo_path=tmp_path, key_str="AGE-SECRET-KEY-1FAKE")
+
+    def test_no_key_raises(self, vault_env):
+        """Vault without key raises an error."""
+        # Clear env so no fallback key is found
+        env = vault_env["env"].copy()
+        env.pop("AGENT_VAULT_KEY", None)
+        # Use a fake home with no owner.key
+        fake_home2 = vault_env["fake_home"].parent / "emptyhome"
+        fake_home2.mkdir()
+        env["HOME"] = str(fake_home2)
+
+        # Temporarily change HOME for the Vault constructor
+        old_home = os.environ.get("HOME")
+        try:
+            os.environ["HOME"] = str(fake_home2)
+            with pytest.raises(VaultNotFoundError, match="No key"):
+                Vault(repo_path=vault_env["repo"])
+        finally:
+            if old_home:
+                os.environ["HOME"] = old_home
+
+
+class TestVaultGet:
+    def test_get_with_owner_key(self, vault_env):
+        """Owner can decrypt secrets."""
+        vault = Vault(
+            repo_path=vault_env["repo"],
+            key_path=vault_env["owner_key"],
+            auto_pull=False,
+        )
+        assert vault.get("stripe/api-key") == "sk_test_123"
+
+    def test_get_with_agent_key(self, vault_env):
+        """Agent with granted access can decrypt secrets."""
+        vault = Vault(
+            repo_path=vault_env["repo"],
+            key_path=vault_env["agent_key"],
+            auto_pull=False,
+        )
+        assert vault.get("stripe/api-key") == "sk_test_123"
+
+    def test_get_nonexistent_secret(self, vault_env):
+        """Requesting a missing secret raises SecretNotFoundError."""
+        vault = Vault(
+            repo_path=vault_env["repo"],
+            key_path=vault_env["owner_key"],
+            auto_pull=False,
+        )
+        with pytest.raises(SecretNotFoundError):
+            vault.get("nope/missing")
+
+    def test_get_unauthorized(self, vault_env):
+        """Agent without access gets NotAuthorizedError."""
+        # Add a second agent without granting access
+        _run_cli("add-agent", "no-access-bot", cwd=str(vault_env["repo"]), env=vault_env["env"])
+        no_access_key = vault_env["fake_home"] / ".agent-vault" / "agents" / "no-access-bot.key"
+
+        vault = Vault(
+            repo_path=vault_env["repo"],
+            key_path=no_access_key,
+            auto_pull=False,
+        )
+        with pytest.raises(NotAuthorizedError):
+            vault.get("stripe/api-key")
+
+    def test_get_with_key_str(self, vault_env):
+        """Can load key from string instead of file."""
+        key_content = vault_env["owner_key"].read_text()
+        vault = Vault(
+            repo_path=vault_env["repo"],
+            key_str=key_content,
+            auto_pull=False,
+        )
+        assert vault.get("stripe/api-key") == "sk_test_123"
+
+    def test_get_with_env_var(self, vault_env):
+        """Can load key from AGENT_VAULT_KEY env var."""
+        key_content = vault_env["owner_key"].read_text()
+        old_env = os.environ.get("AGENT_VAULT_KEY")
+        old_home = os.environ.get("HOME")
+        try:
+            os.environ["AGENT_VAULT_KEY"] = key_content
+            # Set HOME to empty dir so it doesn't find owner.key
+            empty = vault_env["fake_home"].parent / "emptyhome2"
+            empty.mkdir(exist_ok=True)
+            os.environ["HOME"] = str(empty)
+
+            vault = Vault(
+                repo_path=vault_env["repo"],
+                auto_pull=False,
+            )
+            assert vault.get("stripe/api-key") == "sk_test_123"
+        finally:
+            if old_env is None:
+                os.environ.pop("AGENT_VAULT_KEY", None)
+            else:
+                os.environ["AGENT_VAULT_KEY"] = old_env
+            if old_home:
+                os.environ["HOME"] = old_home
+
+
+class TestVaultList:
+    def test_list_secrets(self, vault_env):
+        """Can list secrets with metadata."""
+        vault = Vault(
+            repo_path=vault_env["repo"],
+            key_path=vault_env["owner_key"],
+            auto_pull=False,
+        )
+        secrets = vault.list_secrets()
+        assert len(secrets) == 1
+        assert secrets[0].name == "stripe/api-key"
+        assert secrets[0].group == "stripe"
+
+    def test_list_secrets_by_group(self, vault_env):
+        """Can filter secrets by group."""
+        # Add another secret in a different group
+        _run_cli(
+            "set", "postgres/conn", "postgres://...",
+            "--group", "postgres",
+            cwd=str(vault_env["repo"]),
+            env=vault_env["env"],
+        )
+
+        vault = Vault(
+            repo_path=vault_env["repo"],
+            key_path=vault_env["owner_key"],
+            auto_pull=False,
+        )
+        all_secrets = vault.list_secrets()
+        assert len(all_secrets) == 2
+
+        stripe_only = vault.list_secrets(group="stripe")
+        assert len(stripe_only) == 1
+        assert stripe_only[0].name == "stripe/api-key"
+
+    def test_list_agents(self, vault_env):
+        """Can list agents with group memberships."""
+        vault = Vault(
+            repo_path=vault_env["repo"],
+            key_path=vault_env["owner_key"],
+            auto_pull=False,
+        )
+        agents = vault.list_agents()
+        assert len(agents) == 1
+        assert agents[0]["name"] == "test-bot"
+        assert "stripe" in agents[0]["groups"]
+
+
+class TestMultipleSecrets:
+    def test_multiple_secrets_and_groups(self, vault_env):
+        """Can handle multiple secrets across groups."""
+        _run_cli(
+            "set", "stripe/webhook-secret", "whsec_456",
+            cwd=str(vault_env["repo"]),
+            env=vault_env["env"],
+        )
+        _run_cli(
+            "set", "postgres/conn", "postgres://localhost",
+            "--group", "postgres",
+            cwd=str(vault_env["repo"]),
+            env=vault_env["env"],
+        )
+
+        vault = Vault(
+            repo_path=vault_env["repo"],
+            key_path=vault_env["owner_key"],
+            auto_pull=False,
+        )
+
+        assert vault.get("stripe/api-key") == "sk_test_123"
+        assert vault.get("stripe/webhook-secret") == "whsec_456"
+        assert vault.get("postgres/conn") == "postgres://localhost"
+
+        assert len(vault.list_secrets()) == 3
+        assert len(vault.list_secrets(group="stripe")) == 2
+        assert len(vault.list_secrets(group="postgres")) == 1
+
+
+class TestPullWarnings:
+    def test_pull_warns_on_failure(self, vault_env, capsys):
+        """Pull failure logs to stderr instead of silently swallowing."""
+        import shutil
+
+        vault = Vault(
+            repo_path=vault_env["repo"],
+            key_path=vault_env["owner_key"],
+            auto_pull=False,
+        )
+        # Break git by temporarily renaming .git
+        git_dir = vault_env["repo"] / ".git"
+        git_dir_backup = vault_env["repo"] / ".git_backup"
+        shutil.move(str(git_dir), str(git_dir_backup))
+
+        try:
+            vault.pull()  # Should warn, not raise
+            captured = capsys.readouterr()
+            assert "Warning" in captured.err
+        finally:
+            shutil.move(str(git_dir_backup), str(git_dir))
+
+
+class TestResolveRepoPath:
+    def test_local_path_unchanged(self):
+        """Local paths pass through unchanged."""
+        from agent_vault.vault import _resolve_repo_path
+
+        result = _resolve_repo_path("/tmp/some/path")
+        # On macOS /tmp -> /private/tmp, so compare resolved paths
+        assert result == Path("/tmp/some/path").resolve()
+
+    def test_url_detected(self):
+        """URL-like strings are detected as remote."""
+        from agent_vault.vault import _resolve_repo_path
+
+        # These should be detected as URLs (will fail to clone, but
+        # we're testing detection, not actual cloning)
+        for url in [
+            "https://github.com/example/repo.git",
+            "git@github.com:example/repo.git",
+            "ssh://git@github.com/example/repo.git",
+            "git://github.com/example/repo.git",
+        ]:
+            from agent_vault.errors import VaultNotFoundError
+            try:
+                _resolve_repo_path(url)
+            except VaultNotFoundError:
+                pass  # Expected — can't actually clone
+            except Exception:
+                pass  # Network error is also fine
+
+    def test_relative_path_not_url(self):
+        """Relative paths are not treated as URLs."""
+        from agent_vault.vault import _resolve_repo_path
+
+        result = _resolve_repo_path("./my-repo")
+        assert not str(result).startswith("https://")
+        assert result.is_absolute()
+
+
+class TestContextManager:
+    def test_with_statement(self, vault_env):
+        """Vault works as a context manager."""
+        with Vault(
+            repo_path=vault_env["repo"],
+            key_path=vault_env["owner_key"],
+            auto_pull=False,
+        ) as vault:
+            assert vault.get("stripe/api-key") == "sk_test_123"