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