SecondBrain/credvault-vaultwarden-setup-plan.md

type	title	summary	tags	scope	date	last_updated	related	source
plan	credvault Phase 0 — Vaultwarden org, bot account, and CLI auth setup	Step-by-step plan to prepare the self-hosted Vaultwarden instance for AI credential management — organization, restricted collection, bot account, API-key auth lifecycle, and version/parity audit.	type/plan project/credvault tool/vaultwarden domain/credential-management	project	2026-07-09	2026-07-09	credvault-integration-master-plan	ruby-gems

credvault Phase 0 — Vaultwarden Setup

Preconditions for everything else. Interactive (web vault + email), driven with the human.

Steps

1. Version audit: record Vaultwarden server version and bw --version on the host that will run credvault. Check instance config for TRASH_AUTO_DELETE_DAYS (default: trash is never auto-purged) and ORG_CREATION_USERS/signup settings.
2. Organization: confirm or create a Vaultwarden Organization owned by the human account. Create collection AI Managed Credentials.
3. Bot account: invite bot+jaredmswanson@gmail.com (invite lands in the human's Gmail). Set a distinct master password (never reused). Log into web vault once; generate personal API key (Settings → Security → Keys). Confirm the account holds org role User with access to ONLY the AI Managed Credentials collection, Edit permission.
4. Known limitation to accept: Vaultwarden Edit permission includes item deletion; no org toggle restricts it. Posture is deter-and-detect: wrapper (no delete command) + plugin hooks + trash/export recovery (see credvault-security-backup-recovery-plan).
5. CLI auth proof: on the target host, as the user that will run credvault: bw config server <url> → bw login --apikey (BW_CLIENTID/BW_CLIENTSECRET) → bw unlock --passwordfile <mode-600 file> → bw sync → create/read/edit a test item in the collection → bw lock. Use BITWARDENCLI_APPDATA_DIR=~/.config/credvault/bitwarden.
6. Verify assumptions empirically (feeds the gem's adapter design):
   • Does bw list items --collectionid <id> include custom fields in JSON? (expected: yes, but search does NOT match custom fields — client-side filtering required)
   • Does editing via bw edit preserve password history? ("last 5" is client-written; verify)
   • Does org encrypted-JSON export work under the human account on this version?
7. Record outputs: org ID, collection ID, server URL → these become the gem's trusted config (~/.config/credvault/config.yml), never agent-supplied.

Exit criteria

Bot account can create/read/edit (and, acknowledged, delete) items in exactly one collection; cannot see the human's personal vault or other collections; full non-interactive auth cycle proven on the target host; empirical answers to step 6 documented in the repo.