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