Metadata-Version: 2.4
Name: bastionik
Version: 0.1.0
Summary: Python SDK for the Bastionik AI agent trust boundary API
License: MIT
Project-URL: Homepage, https://bastionik.com
Project-URL: Repository, https://github.com/bastionik/bastionik-python
Project-URL: Bug Tracker, https://github.com/bastionik/bastionik-python/issues
Keywords: ai-agents,security,authentication,credentials,bastionik
Classifier: Development Status :: 3 - Alpha
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
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: PyNaCl>=1.5.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Dynamic: license-file

# bastionik-python

Python SDK for [Bastionik](https://bastionik.com) — the trust boundary service for AI agents.

Stop hardcoding API keys in your agents. Bastionik gives every agent a cryptographic identity, stores credentials in an encrypted vault, enforces fine-grained access policies, and keeps a complete audit trail. Your agent never sees the token.

> **Status:** Early access. Self-hosted only. [Hosted version coming soon.](#hosted-version)

---

## How it works

```
Your agent          Bastionik                   External API
    │                   │                            │
    │──── execute() ───►│                            │
    │    (signed with   │── verify Ed25519 sig       │
    │     private key)  │── check policy             │
    │                   │── decrypt credential       │
    │                   │────────────────────────────►
    │                   │◄────────────────────────────
    │◄── result ────────│   (credential deleted      │
    │                   │    from memory)            │
```

1. You register an agent with its Ed25519 public key
2. You store an encrypted credential (the agent never sees it)
3. You define a policy: what actions the agent is allowed to take
4. The agent signs execution requests with its private key
5. Bastionik verifies the signature, checks the policy, executes the call, returns the result

---

## Requirements

- Python 3.10+
- A running Bastionik instance ([core repo](https://github.com/bastionik/core))

---

## Installation

```bash
pip install git+https://github.com/bastionik/bastionik-python.git
```

Or clone and install in editable mode for development:

```bash
git clone https://github.com/bastionik/bastionik-python.git
cd bastionik-python
pip install -e .
```

---

## Quickstart

### 1. Start Bastionik locally

```bash
# In your bastionik/core repo
docker compose up
```

The API will be available at `http://localhost:8000`.

### 2. Generate a keypair for your agent

```python
import bastionik

keys = bastionik.generate_keypair()
# {
#   "private_key_hex": "...",   ← store this securely, pass to BastionikClient
#   "public_key_hex":  "...",   ← register agents with this
# }
```

### 3. Register, configure, and run

```python
from bastionik import BastionikClient

client = BastionikClient(
    base_url="http://localhost:8000",
    user_id="your-user-id",                              # management plane auth
    agent_private_key=bytes.fromhex(keys["private_key_hex"]),  # signs execute requests
)

# Register the agent
agent = client.register_agent(
    name="my-github-agent",
    public_key=keys["public_key_hex"],
)
agent_id = agent["id"]

# Store a credential — the agent will never see this token directly
client.store_credential(
    agent_id=agent_id,
    service="github",
    token="ghp_your_github_token",
)

# Define what the agent is allowed to do
client.create_policy(
    agent_id=agent_id,
    service="github",
    allowed_actions=["get_repo", "list_prs", "create_issue"],
    rate_limit=100,
)

# Execute a signed action
result = client.execute(
    agent_id=agent_id,
    service="github",
    action="get_repo",
    params={"owner": "octocat", "repo": "Hello-World"},
)
print(result["full_name"])  # octocat/Hello-World
```

---

## API Reference

### `BastionikClient(base_url, user_id, agent_private_key, timeout)`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `base_url` | `str` | `http://localhost:8000` | URL of your Bastionik instance |
| `user_id` | `str` | `None` | Developer user ID for management operations |
| `agent_private_key` | `bytes` | `None` | Ed25519 private key bytes for signing agent requests |
| `timeout` | `float` | `30.0` | Request timeout in seconds |

#### Management methods
These require `user_id` to be set.

| Method | Description |
|--------|-------------|
| `register_agent(name, public_key, description)` | Register a new AI agent |
| `store_credential(agent_id, service, token)` | Encrypt and store an API credential |
| `delete_credential(agent_id, service)` | Remove a stored credential |
| `create_policy(agent_id, service, allowed_actions, rate_limit)` | Define agent permissions |
| `list_policies(agent_id)` | List all policies for an agent |
| `delete_policy(policy_id)` | Delete a policy |

#### Execution methods
These require `agent_private_key` to be set.

| Method | Description |
|--------|-------------|
| `execute(agent_id, service, action, params)` | Execute a signed agent action |

#### Utilities

| Method | Description |
|--------|-------------|
| `health()` | Check server connectivity |
| `bastionik.generate_keypair()` | Generate a new Ed25519 keypair |

---

## Supported services and actions

### GitHub (`service="github"`)

| Action | Params | Description |
|--------|--------|-------------|
| `get_repo` | `owner`, `repo` | Get repository details |
| `list_repos` | `owner` | List repositories for a user/org |
| `list_prs` | `owner`, `repo` | List open pull requests |
| `create_pr` | `owner`, `repo`, `title`, `body`, `head`, `base` | Create a pull request |
| `create_issue` | `owner`, `repo`, `title`, `body` | Create an issue |
| `merge_pr` | `owner`, `repo`, `pull_number` | Merge a pull request |
| `close_issue` | `owner`, `repo`, `issue_number` | Close an issue |

More integrations are on the roadmap. [Request one →](https://github.com/bastionik/bastionik-python/issues)

---

## Running the example

```bash
git clone https://github.com/bastionik/bastionik-python.git
cd bastionik-python

# Install dependencies
pip install -e .

# Set your GitHub token
export GITHUB_TOKEN=ghp_your_token_here
export GITHUB_REPO=your-username/your-repo

# Run the demo (requires Bastionik running locally)
python examples/github_demo.py
```

---

## Running tests

Tests use mocked HTTP — no live server required.

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

---

## Error handling

All API errors raise `BastionikError`:

```python
from bastionik import BastionikError

try:
    result = client.execute(agent_id=agent_id, service="github", action="delete_repo", params={...})
except BastionikError as e:
    print(e.status_code)   # e.g. 403
    print(e.detail)        # raw error body from the API
```

Common status codes:

| Code | Meaning |
|------|---------|
| `401` | Invalid or missing Ed25519 signature |
| `403` | Action not permitted by policy |
| `404` | Agent or credential not found |
| `409` | Agent already registered |
| `429` | Rate limit exceeded |

---

## Security model

- **Credentials never leave the vault unencrypted.** Tokens are Fernet-encrypted (AES-128-CBC + HMAC-SHA256) before PostgreSQL storage and decrypted in memory only during execution.
- **Every request is signed.** Ed25519 signatures verify agent identity on each `/execute` call. Replay attacks are prevented by a 5-minute timestamp window.
- **Policies are enforced server-side.** Even if an agent's private key is compromised, it can only perform actions explicitly listed in its policy.
- **Complete audit trail.** Every action is logged before execution. You can prove exactly what every agent did, when, and with what parameters.

---

## Hosted version

A hosted version of Bastionik (`pip install bastionik` pointing at `api.bastionik.com`) is in development. Sign up for early access at [bastionik.com](https://bastionik.com).

---

## License

MIT
