docs: add integration research and proposal for CLI (C-009)
This commit is contained in:
James
parent
09b749876d
commit
9b33ed212b
|
|
@ -0,0 +1,234 @@
|
|||
# Clavitor CLI — Integration Research & Proposal
|
||||
*C-009 | Research: integrations with competing password managers*
|
||||
*Completed: 2026-03-24*
|
||||
|
||||
---
|
||||
|
||||
## 1. How Competitors Integrate with Other Tools
|
||||
|
||||
### Bitwarden
|
||||
- **CLI (`bw`)** — standard Unix CLI, used as the backbone of their MCP server. MCP wraps `bw` subprocess calls.
|
||||
- **MCP server** (`@bitwarden/mcp-server`) — launched July 2025, expanded Oct 2025. Exposes full vault CRUD + TOTP + org admin to any MCP-compatible AI client (Claude Desktop, etc.). No field-level access control — all-or-nothing read.
|
||||
- **Secret references** — `bw://item_id/field` URIs that can be injected into config files or env vars. Intended for developer workflows, not AI agents.
|
||||
- **Export formats**: JSON (structured), CSV, password-protected JSON. Wide import coverage: 1Password, LastPass, KeePass, Dashlane, Chrome, Firefox, ~50 others.
|
||||
- **Integration model**: "Install the MCP server, unlock the vault, AI sees everything."
|
||||
|
||||
### 1Password
|
||||
- **`op` CLI** — the gold standard for developer secret injection. Key patterns:
|
||||
- `op run -- myapp` — injects secrets as env vars at process spawn time, secrets never written to disk
|
||||
- `op inject -i .env.tpl -o .env` — template substitution for config files
|
||||
- `op read op://vault/item/field` — direct field reads in scripts
|
||||
- **Secret references** (`op://vault/item/field`) — URI scheme used across CI/CD, GitHub Actions, Terraform providers, K8s operators
|
||||
- **Developer integrations**: GitHub Actions, CircleCI, Kubernetes, Terraform, Ansible, SSH, Docker, .NET/Java/Python SDKs
|
||||
- **No MCP server** yet (as of research date). No field-level AI access control.
|
||||
- **Integration model**: "Replace secrets in your config/pipeline with op:// references, resolve at runtime."
|
||||
|
||||
### KeePass / KeePassXC
|
||||
- **SSH Agent integration** — KeePassXC loads SSH keys into `ssh-agent` on unlock, removes them on lock. Works on Linux (socket), macOS, Windows.
|
||||
- **Secret Service (D-Bus)** — acts as `org.freedesktop.secrets` provider on Linux; any `libsecret` app can resolve secrets from KeePassXC without opening the GUI.
|
||||
- **Browser extension** — KeePassXC-Browser communicates via native messaging protocol.
|
||||
- **`keepassxc-cli`** — entry CRUD, password generation, TOTP, attachment management. No AI/MCP integration.
|
||||
- **Integration model**: Platform-native protocols (SSH agent, Secret Service D-Bus) rather than cloud APIs.
|
||||
|
||||
### HashiCorp Vault
|
||||
- **Agent (Vault Agent)** — sidecar process that auto-renews tokens and renders secrets into files/env vars via template engine. Heavily used in Kubernetes.
|
||||
- **`vault` CLI** — `vault kv get`, `vault read`, etc. Used in scripts and CI.
|
||||
- **Template engine** — Go templates that pull secrets into config files on disk.
|
||||
- **Integration model**: Infrastructure-first. Secrets pushed/rendered to where apps expect them (files, env vars), not pulled at query time.
|
||||
|
||||
### Doppler
|
||||
- **`doppler run -- <cmd>`** — exactly mirrors `op run`. Injects secrets as env vars for a subprocess.
|
||||
- **`doppler secrets download`** — exports secrets in .env, JSON, YAML, etc.
|
||||
- **Branch/environment awareness** — secrets auto-switch when you change branches (via git hook integration).
|
||||
- **Integration model**: Developer experience focus. Treats secrets as environment-scoped configuration.
|
||||
|
||||
### OpenClaw / Agentic Platforms
|
||||
- **No native credential store** — agent frameworks (OpenClaw, Claude Code, etc.) rely on the host's MCP ecosystem for secrets. There's no "Nanoclaw" product with a documented credential integration strategy in public sources.
|
||||
- **Claude secure deployment docs** (Anthropic) recommend a **credential proxy pattern**: agent calls a tool → tool calls a local proxy that injects credentials → proxy calls the real API. Agent never sees the raw secret.
|
||||
- **MCP Gateway Registry** (community) — enterprise pattern: centralized MCP registry with OAuth/Keycloak in front, all tool calls audited. Not a password manager but a credential governance layer.
|
||||
- **Integration pattern emerging**: scoped, short-lived credentials per agent session, not persistent vault access.
|
||||
|
||||
---
|
||||
|
||||
## 2. What Clavitor Has That Competitors Don't
|
||||
|
||||
Before proposing, note the unique position we're building from:
|
||||
|
||||
| Feature | Clavitor | Bitwarden | 1Password | KeePassXC |
|
||||
|---|---|---|---|---|
|
||||
| Field-level AI visibility (L1/L2) | ✅ | ❌ | ❌ | ❌ |
|
||||
| Scoped MCP tokens per agent | ✅ | ❌ | ❌ | ❌ |
|
||||
| Self-hosted, single binary | ✅ | ✅ | ❌ | ✅ |
|
||||
| `op run`-style env injection | ❌ **← gap** | ❌ | ✅ | ❌ |
|
||||
| Secret reference URI scheme | ❌ **← gap** | ✅ | ✅ | ❌ |
|
||||
| Export for migration | partial | ✅ | ✅ | ✅ |
|
||||
| Import from others | LLM-based | ✅ | ✅ | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 3. Integration Proposal
|
||||
|
||||
### Priority 1: `clavitor run` — Secret Injection at Process Spawn (High)
|
||||
|
||||
**The ask**: `clavitor run -- <command>`
|
||||
|
||||
Mirrors `op run` and `doppler run`. This is the single highest-value integration because it:
|
||||
- Lets Clavitor work in any CI/CD pipeline, shell script, or dev workflow today
|
||||
- Requires zero changes to the target app
|
||||
- Secrets never touch disk or appear in `ps aux`
|
||||
|
||||
**How it works**:
|
||||
1. Parse `.env` / config template for `clavitor://` references (see below)
|
||||
2. Resolve each reference via `GET /api/ext/field/:entry_id/:field_label` using a local token
|
||||
3. Set resolved values as env vars
|
||||
4. `execvp(command, env)` — replace current process
|
||||
|
||||
**CLI usage**:
|
||||
```bash
|
||||
# .env file contains: DATABASE_URL=clavitor://my-postgres/Connection String
|
||||
clavitor run --env .env -- node server.js
|
||||
clavitor run --set GITHUB_TOKEN=clavitor://GitHub/Token -- make deploy
|
||||
```
|
||||
|
||||
**Implementation notes** (C CLI, `clovis-cli`):
|
||||
- Add `cmd_run()` in `main.c`
|
||||
- Load `.env` file, regex-scan for `clavitor://` scheme
|
||||
- Resolve each reference via HTTP to local vault
|
||||
- Build `envp[]` array, call `execvp()`
|
||||
- ~200 lines of C, no new deps
|
||||
|
||||
---
|
||||
|
||||
### Priority 2: `clavitor://` URI Scheme (High)
|
||||
|
||||
**The ask**: A canonical secret reference URI: `clavitor://entry-title/field-label`
|
||||
|
||||
Examples:
|
||||
```
|
||||
clavitor://GitHub/Token
|
||||
clavitor://My Postgres/Connection String
|
||||
clavitor://AWS Production/Access Key ID
|
||||
```
|
||||
|
||||
This gives Clavitor a portable reference format like `op://` and `bw://`. Any tool that understands the scheme can resolve it.
|
||||
|
||||
**Resolution command**:
|
||||
```bash
|
||||
clavitor read "clavitor://GitHub/Token"
|
||||
# → ghp_xxxxxxxxxxxx
|
||||
```
|
||||
|
||||
**Use in templates** (for `clavitor inject`):
|
||||
```ini
|
||||
# database.conf
|
||||
host = postgres.internal
|
||||
password = {{ clavitor://Postgres/Password }}
|
||||
```
|
||||
|
||||
**Implementation**: Add `cmd_read()` to CLI + `clavitor inject` subcommand for template rendering.
|
||||
|
||||
---
|
||||
|
||||
### Priority 3: Bitwarden-Compatible Export (Medium)
|
||||
|
||||
**The ask**: `clavitor export --format bitwarden` (and 1Password, CSV)
|
||||
|
||||
This is essential for user trust — people need to know they can leave. Bitwarden's JSON schema is the de-facto standard.
|
||||
|
||||
**Bitwarden JSON schema** (relevant fields):
|
||||
```json
|
||||
{
|
||||
"items": [{
|
||||
"type": 1,
|
||||
"name": "GitHub",
|
||||
"login": { "username": "...", "password": "...", "totp": "..." },
|
||||
"fields": [{"name": "Token", "value": "...", "type": 0}]
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
**What we export**: L1 fields only (L2 fields marked as `[PROTECTED - L2]` in notes, user warned). This is correct behavior — we never export L2 plaintext.
|
||||
|
||||
**Output formats**:
|
||||
- `--format bitwarden` → Bitwarden JSON
|
||||
- `--format csv` → Generic CSV (title, username, password, url, notes)
|
||||
- `--format json` → Clavitor native JSON (full fidelity, for backup/restore)
|
||||
|
||||
**Implementation**: Server-side `GET /api/export?format=bitwarden` + CLI `clavitor export`.
|
||||
|
||||
---
|
||||
|
||||
### Priority 4: OpenClaw Skill — `clavitor` (Medium)
|
||||
|
||||
**The ask**: An OpenClaw skill that wraps the Clavitor MCP endpoint.
|
||||
|
||||
This is the native integration for the OpenClaw platform. The skill would:
|
||||
- Connect to `http://localhost:8765/mcp` using a stored scoped token
|
||||
- Expose `get_credential`, `search_vault`, `get_totp`, `list_credentials` as tools
|
||||
- Handle L2 gracefully (return a user-facing note, never throw)
|
||||
|
||||
**Skill SKILL.md** would live in `~/.openclaw/skills/clavitor/SKILL.md` with the token stored in the agent's `TOOLS.md`.
|
||||
|
||||
**Why this matters**: Makes Clavitor the default credential resolver for any OpenClaw agent on the host — which is exactly the positioning we want.
|
||||
|
||||
---
|
||||
|
||||
### Priority 5: SSH Agent Integration (Low)
|
||||
|
||||
**The ask**: `clavitor ssh-agent` — load SSH private keys from vault into `ssh-agent` on unlock.
|
||||
|
||||
Mirrors KeePassXC's SSH integration. Entries of type `ssh_key` with a private key field get loaded via `SSH_AUTH_SOCK` when the vault session starts.
|
||||
|
||||
```bash
|
||||
clavitor ssh-agent --add # load all ssh_key entries into agent
|
||||
clavitor ssh-agent --remove # flush on vault lock
|
||||
```
|
||||
|
||||
**Why**: SSH keys are currently orphaned in most password managers. This makes Clavitor the single source of truth for both credentials and SSH identities.
|
||||
|
||||
---
|
||||
|
||||
### Priority 6: Secret Service (D-Bus) Provider (Low / Linux only)
|
||||
|
||||
**The ask**: Clavitor implements `org.freedesktop.secrets` D-Bus interface.
|
||||
|
||||
This makes Clavitor a drop-in replacement for GNOME Keyring / KWallet on Linux. Any `libsecret` app (git credential helper, GNOME apps, Python keyring, etc.) automatically uses Clavitor.
|
||||
|
||||
**Scope**: Linux only. High complexity, narrow audience for MVP. Defer to v2.
|
||||
|
||||
---
|
||||
|
||||
## 4. Recommended Sequencing
|
||||
|
||||
```
|
||||
Sprint 1 (CLI v0.2):
|
||||
✅ clavitor:// URI scheme
|
||||
✅ clavitor read <ref>
|
||||
✅ clavitor run -- <cmd>
|
||||
|
||||
Sprint 2 (Server + Export):
|
||||
✅ clavitor export --format bitwarden|csv|json
|
||||
✅ /api/export endpoint
|
||||
|
||||
Sprint 3 (Ecosystem):
|
||||
✅ OpenClaw skill
|
||||
✅ clavitor inject (template rendering)
|
||||
|
||||
Later:
|
||||
- SSH agent integration
|
||||
- D-Bus Secret Service (v2, Linux)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Key Differentiator to Emphasize
|
||||
|
||||
Every competitor does **all-or-nothing** credential access. Our story is different:
|
||||
|
||||
> "1Password gives your agent a master key. Clavitor gives your agent a keycard — access to exactly what it needs, nothing else. Your card number stays yours."
|
||||
|
||||
The `clavitor run` + scoped token combination is unique: you can give each agent a token scoped to specific tags/entries, then use `clavitor run` to inject only those secrets into that agent's subprocess. No other password manager supports this today.
|
||||
|
||||
---
|
||||
|
||||
*Researched and written by Research Agent | C-009*
|
||||
Loading…
Reference in New Issue