91 lines
4.9 KiB
Markdown
91 lines
4.9 KiB
Markdown
---
|
||
type: plan
|
||
title: "credvault — Bitwarden/Vaultwarden AI credential management master plan"
|
||
summary: Master plan for letting a Claude Code bot account manage infrastructure credentials in Vaultwarden via a Ruby CLI gem (credvault) and a skill-only Claude Code plugin, with a deter-and-detect security posture (hooks + audit + rotation runbook) rather than OS isolation.
|
||
tags:
|
||
- type/plan
|
||
- type/hub
|
||
- project/credvault
|
||
- tool/vaultwarden
|
||
- tool/claude-code
|
||
- domain/credential-management
|
||
scope: project
|
||
date: 2026-07-09
|
||
last_updated: 2026-07-09
|
||
related:
|
||
- credvault-gem-plan
|
||
- credvault-cc-plugin-plan
|
||
- credvault-vaultwarden-setup-plan
|
||
- credvault-security-backup-recovery-plan
|
||
source: ruby-gems
|
||
---
|
||
|
||
# credvault — Master Plan
|
||
|
||
Goal: AI agents (Claude Code) create/manage server & service credentials directly in
|
||
Vaultwarden via a dedicated bot account, so the human never has to manually back up
|
||
AI-generated credentials again.
|
||
|
||
Source design: `~/dev/ruby-gems/docs/bitwarden-ai-integration/synthesized-note.md`
|
||
(ChatGPT PRD + Opus critique; the "Post-critique revisions" section is authoritative).
|
||
|
||
## Architecture (settled)
|
||
|
||
```
|
||
Claude Code
|
||
→ cc-plugin skill (policy: when/how to use credvault; PreToolUse hook blocks raw bw)
|
||
→ credvault Ruby gem CLI (capability: ensure/get/rotate/list/status — NO delete/export)
|
||
→ bw CLI (auth material mode-600 under the user; hooks block direct reads of auth paths and raw bw)
|
||
→ Vaultwarden bot account (bot+jaredmswanson@gmail.com), org "AI Managed Credentials" collection only
|
||
```
|
||
|
||
## Load-bearing decisions
|
||
|
||
1. **Deter-and-detect posture, not OS isolation (decided 2026-07-09).** Vaultwarden has NO
|
||
org setting restricting item deletion — Edit permission includes delete — and hooks are
|
||
advisory, so a determined bypass is technically possible. Accepted because the blast
|
||
radius is bounded: the bot sees only the `AI Managed Credentials` collection (rotatable
|
||
infra creds, not the human's vault). Deletion is recoverable (trash + human-owned export);
|
||
exfiltration is remediated by the rotation runbook. Controls: gem surface (no delete),
|
||
plugin hooks (block raw `bw` AND reads of credvault auth/config paths / env dumping),
|
||
skill instructions, audited `get`. The `bitwarden-agent` OS user + sudoers design is
|
||
documented as a future hardening option in [[credvault-security-backup-recovery-plan]].
|
||
2. **No MCP** — skill-only plugin (context economy). No Secrets Manager (doesn't exist in Vaultwarden).
|
||
3. **Idempotency via deterministic `managed_key`** custom field (`<host>/<app>/<env>/<purpose>`);
|
||
fail explicitly on duplicates; `bw sync` before every read; one global lock serializes all bw calls.
|
||
4. **Prompt injection is the dominant confidentiality risk** — `get` needs an exact known key,
|
||
every `get` is audited, `ensure_and_inject` (secret never returns to the model) is prioritized post-MVP.
|
||
5. **Recovery is independent of the bot**: scheduled encrypted export under the HUMAN account;
|
||
bot-compromise runbook exists before go-live.
|
||
|
||
## Phases
|
||
|
||
| Phase | What | Plan |
|
||
|---|---|---|
|
||
| 0 | Vaultwarden org/collection/bot account, version audit, CLI auth on target host | [[credvault-vaultwarden-setup-plan]] |
|
||
| 1 | Ruby gem: status/get/list, then ensure/rotate (private GitHub repo in ~/dev/ruby-gems) | [[credvault-gem-plan]] |
|
||
| 2 | Backup (human-owned export) + compromise/rotation runbooks; auth files mode-600 | [[credvault-security-backup-recovery-plan]] |
|
||
| 3 | Claude Code plugin in ~/dev/cc-plugins/ (skill + hook), install per-project | [[credvault-cc-plugin-plan]] |
|
||
| 4 | End-to-end validation: real deployment creates a credential, rerun creates no duplicate, credential visible in human's vault UI | (acceptance criteria in gem plan) |
|
||
|
||
Phases 1–3 are parallelizable after Phase 0; each sub-plan is written to be executable by a
|
||
delegated subagent with the plan + synthesized note as its only context.
|
||
|
||
## Subagent delegation strategy
|
||
|
||
Each agent gets its sub-plan + the synthesized note as full context, an explicit return
|
||
format, and must hand back with tests green — one round per batch, no mid-slice judgment
|
||
calls (all decisions are pre-made in the plans).
|
||
|
||
- **Round 0 (interactive, main loop)**: Phase 0 — web vault clicks, invite email, CLI auth
|
||
proof, empirical checks. Cannot be delegated.
|
||
- **Round 1 (one sonnet agent)**: gem slice 1 — skeleton, config, error model,
|
||
ProcessRunner/Client/Session, `status` end-to-end. Sequential blocker: it defines the
|
||
interfaces everything else builds on.
|
||
- **Round 2 (parallel)**: gem slice 2 (`get`+`list`, sonnet) ∥ gem slice 3
|
||
(`ensure`+`rotate`+audit+policies, sonnet) — disjoint operations against slice-1
|
||
interfaces ∥ plugin skill+hooks (sonnet) ∥ backup cron + runbook docs (haiku — mechanical
|
||
once specced). Merge gem slices before review.
|
||
- **Round 3**: opus security review + /code-review + security-misuse perspective agent on
|
||
the gem before first prod use.
|