johan
/
clavitor
1
0
Fork 0
Code Issues 7 Pull Requests Packages Projects Releases Wiki Activity
clavitor/docs/INTEGRATION-RESEARCH.md

10 KiB
Raw Blame History

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:

# .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:

clavitor read "clavitor://GitHub/Token"
# → ghp_xxxxxxxxxxxx

Use in templates (for clavitor inject):

# 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):

{
  "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.

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