diff --git a/docs/INTEGRATION-RESEARCH.md b/docs/INTEGRATION-RESEARCH.md new file mode 100644 index 0000000..7c07719 --- /dev/null +++ b/docs/INTEGRATION-RESEARCH.md @@ -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 -- `** — 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 -- ` + +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 + ✅ clavitor run -- + +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*