Metadata-Version: 2.4
Name: bastionik
Version: 0.1.3
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

**Your AI agents have your API keys. Do you know what they're doing with them?**

Bastionik is a trust boundary for AI agents. Register an agent, store your API credentials in our encrypted vault, define what the agent is allowed to do — and Bastionik handles everything else. The agent signs its requests, Bastionik verifies, checks policy, executes the call, and returns the result. The agent never sees your token.

---

## Quick Start (2 minutes)

```bash
pip install bastionik
```

```python
import bastionik

# Create an account — save the returned API key to an environment variable
client, api_key = bastionik.Client.signup("you@example.com")
print(f"Save this now: BASTIONIK_API_KEY={api_key}")

# On subsequent runs, load from your environment instead:
# client = bastionik.Client(api_key=os.environ["BASTIONIK_API_KEY"])

# Register an agent — Bastionik generates and manages the keypair for you
agent = client.agents.create(name="my-first-agent")
# Save agent.id — you'll need it to execute actions later
# The private key is stored on the agent object automatically; you don't handle it directly

# Store a credential — encrypted at rest, never exposed to the agent
cred = client.credentials.store(
    agent_id=agent.id,
    service="github",
    token="ghp_yourtoken",
)
# A safe read-only policy is created automatically:
print(cred.default_policy)  # {"policy_id": "...", "allowed_actions": ["get_repo", ...]}

# Execute an action on the agent's behalf
result = client.execute(
    agent_id=agent.id,
    service="github",
    action="get_repo",
    params={"repo": "your-username/your-repo"},
)
print(result)
```

That's it. No Docker, no database setup, no key management. Bastionik handles signing, verification, encryption, and policy enforcement — a sensible default policy is created automatically when you store your first credential.

[Get your API key →](https://bastionik.com)

---

## How It Works

```
┌─────────┐    signed request    ┌─────────────────────────────────┐
│  Agent  │ ──────────────────▶  │           Bastionik             │
│         │ ◀──────────────────  │  verifies → policy → vault      │
└─────────┘       result         └─────────────────┬───────────────┘
                                                    │
                                                    ▼
                                            ┌──────────────┐
                                            │  GitHub /    │
                                            │  Slack / etc │
                                            └──────────────┘
```

1. Your agent calls `client.execute(...)`
2. The SDK signs the request automatically using the key Bastionik issued at registration
3. Bastionik verifies the signature, checks your policy, and decrypts the relevant credential in memory only
4. Bastionik calls the external API and returns the result
5. The credential is discarded immediately — it never reaches your agent

---

## Core Concepts

| Concept | What it means |
|---|---|
| **Agent** | A registered identity for one of your AI agents. Bastionik issues and manages its cryptographic keys. |
| **Credential** | An API token (GitHub, Slack, etc.) stored encrypted in the vault. Never returned in plaintext. |
| **Policy** | Rules defining what actions an agent can perform on a service. A safe read-only default is created automatically when you store a credential. |
| **Execute** | The single endpoint your agent calls to perform an action. Handles auth, policy, and execution in one step. |

---

## Managing Policies

A read-only default policy is created automatically when you store a credential. To grant additional permissions:

```python
cred = client.credentials.store(agent_id=agent.id, service="github", token="ghp_...")
policy_id = cred.default_policy["policy_id"]

# Expand to include write actions when you're ready
client.policies.update(
    policy_id=policy_id,
    allowed_actions=[
        "get_repo", "list_repos", "list_prs", "list_issues",  # reads (already allowed)
        "create_pr", "create_issue",                           # writes (newly granted)
    ],
    rate_limits={"requests_per_hour": 200},
)
```

---

## Restarting Your Application

Agent private keys are returned once at registration and stored on the `Agent` object in memory. When your application restarts, load them back in:

```python
import os
import bastionik

client = bastionik.Client(api_key=os.environ["BASTIONIK_API_KEY"])

# Restore a previously registered agent from its stored private key
client.load_agent(
    agent_id=os.environ["MY_AGENT_ID"],
    private_key=os.environ["MY_AGENT_PRIVATE_KEY"],
)

# execute() will work immediately
result = client.execute(agent_id=os.environ["MY_AGENT_ID"], ...)
```

---

## Supported Integrations

| Integration | Status |
|---|---|
| **GitHub** | ✅ Available |
| Slack | 🔜 Coming soon |
| Gmail | 🔜 Coming soon |

---

## Examples

See [`examples/github_demo.py`](./examples/github_demo.py) for a complete working example.

---

## Self-Hosting

Bastionik's core is open for inspection via this SDK, but the full backend (vault, policy engine, executor) is closed-source and run as a hosted service. If you're interested in a self-hosted enterprise deployment, contact [hello@bastionik.dev](mailto:hello@bastionik.dev).

---

## Security

- Credentials encrypted at rest with Fernet (AES-128-CBC + HMAC-SHA256)
- Every request signed with Ed25519 and verified before execution
- Credentials decrypted in memory only, discarded immediately after use
- Every action logged in an immutable audit trail

Read the full [Security Whitepaper →](https://bastionik.com/whitepaper)

---

## Support

- Email: [hello@bastionik.dev](mailto:hello@bastionik.dev)
- Issues: [GitHub Issues](https://github.com/bastionik/bastionik-python/issues)

---

## License

MIT © Bastionik
