Metadata-Version: 2.4
Name: hermes-passbolt-secret-source
Version: 1.1.0
Summary: Passbolt secret source plugin for Hermes Agent
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# hermes-passbolt-secret-source

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/hermes-passbolt-secret-source)](https://pypi.org/project/hermes-passbolt-secret-source/)

Passbolt secret source plugin for [Hermes Agent](https://github.com/NousResearch/hermes-agent).

Resolves provider API keys from Passbolt at process startup instead of storing
them in plaintext inside `~/.hermes/.env`.

## Install

**Option 1: Git via hermes plugins (recommended)**

```bash
hermes plugins install gitlab.com:AndreasBBS/hermes-passbolt-secret-source
```

**Option 2: Manual plugin directory**

```bash
cd ~/.hermes/plugins
git clone https://gitlab.com/AndreasBBS/hermes-passbolt-secret-source.git
```

Then enable:

```bash
hermes plugins enable hermes-passbolt-secret-source
```

## Prerequisites

- **Hermes Agent** ≥ v0.18.2 (SecretSource ABC)
- **go-passbolt-cli** installed and authenticated (`passbolt --version`)
- **Passbolt instance** with GPGAuth enabled

## Configuration

Add to `~/.hermes/config.yaml`:

```yaml
secrets:
  sources: [passbolt]
  passbolt:
    enabled: true
    server_url: "https://passbolt.example.com"
    private_key_file: "/home/user/.passbolt/private-key.asc"
    env:
      OPENROUTER_API_KEY: "passbolt://<resource_uuid>"
      ANTHROPIC_API_KEY: "passbolt://<resource_uuid>"
```

Add `PASSBOLT_PASSWORD` (your GPG passphrase) to `~/.hermes/.env`.

## How it works

1. Hermes starts up, loads the plugin via `hermes_agent.plugins` entry point
2. Plugin reads `PASSBOLT_PASSWORD` from environment
3. For each `passbolt://<uuid>` reference, calls `passbolt get resource --id <uuid> -j`
4. Extracts the `password` field from JSON output → sets env var
5. Agent sees resolved secrets in environment, never touches Passbolt directly

## Development

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, and commit conventions.

All tests run inside Docker — no local dependencies required.

```bash
# Unit tests (mocked CLI)
docker build -t hermes-passbolt-unit -f tests/unit/Dockerfile . && docker run --rm hermes-passbolt-unit

# Integration tests (live Passbolt)
cd tests/integration && bash run.sh
```

## Architecture

| Component | Shape | Auth |
|-----------|-------|------|
| `interface_type: cli` (current) | mapped | GPGAuth via `go-passbolt-cli` |
| `interface_type: rest-api` (planned) | mapped | JWT / Server-to-Server |

See [open issues](https://gitlab.com/AndreasBBS/hermes-passbolt-secret-source/-/issues)
for planned features: bulk mode, REST API interface, lazy CLI install.

## License

[MIT](LICENSE)
