SecondBrain/credvault-integration-master-plan.md

type	title	summary	tags	scope	date	last_updated	related	source
plan	credvault — Bitwarden/Vaultwarden AI credential management master plan	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.	type/plan type/hub project/credvault tool/vaultwarden tool/claude-code domain/credential-management	project	2026-07-09	2026-07-09	credvault-gem-plan credvault-cc-plugin-plan credvault-vaultwarden-setup-plan credvault-security-backup-recovery-plan	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.