# Assistant Vaultwarden Access Runbook

## Purpose

Enable Nimrod/the assistant to access approved Vaultwarden secrets safely for internal-network administration without exposing the user's full vault or committing secrets to git.

## Current Approved Direction

- Use a dedicated assistant Vaultwarden user.
- Share limited collections/items only.
- Use confirmed reads for high-risk secrets.
- Start with one low-risk real service credential pilot.
- Store assistant Vaultwarden session/login material only on the server-hosted assistant runtime with strict permissions.
- A limited low-risk pilot may happen before full backup/recovery, but critical secrets must wait.

## Do Not Do

- Do not give the assistant the user's personal Vaultwarden login.
- Do not make the assistant a vault admin by default.
- Do not store master passwords, session tokens, API keys, recovery codes, or item values in git.
- Do not paste secret values into tickets, docs, or server change logs.
- Do not migrate high-risk infrastructure credentials until backup/recovery is done or explicitly risk-accepted.

## Implementation (Current State)

### Infrastructure Ready (Nimrod LXC 104)

- Bitwarden CLI (`bw` v2026.6.0) installed at `/usr/local/bin/bw`
- Helper script: `scripts/vault-assistant.sh` (provides `vault-login`, `vault-unlock`, `vault-get`, etc.)
- Secure directory: `~/.vault/` (mode 700)
- Server configured: `https://vw.dropcutstud.io`
- Architecture doc: `docs/assistant-vault-access-model.md`

### User-Side Steps Required (in Vaultwarden UI)

1. Create the assistant account in Vaultwarden (either invite via admin panel or temporarily enable signups)
2. Create an organization (e.g., `Nimrod` or `Homelab`) if using org collections
3. Create the `nimrod-pilot` collection and share with the assistant account (Can Read)
4. Add a pilot credential to the collection (e.g., Homarr admin credentials)
5. Generate an API key for the assistant account (Settings → Security → API Key)
6. Share the API key and assistant master password securely with the assistant runtime

### Then

1. Store the API key at `~/.vault/api-key` on Nimrod LXC
2. Set `VAULT_PASSWORD` and run `vault-login` → `vault-unlock` → `vault-get`
3. Complete the pilot checklist below
4. Proceed to Proxmox token rotation (documented in architecture doc)

## Secrets Classification

See `docs/assistant-vault-access-model.md` for full classification and item naming conventions.

## Secret Classification

### Low-risk

Examples: test service credential, non-admin app password, easily rotated token for a non-critical service.

Policy: task-level approval is enough.

### Medium-risk

Examples: service API token with write access, internal app admin credential with limited blast radius.

Policy: assistant must state purpose, command/action, and rollback/revocation path.

### High-risk

Examples: Proxmox admin token, OPNsense admin, DNS provider, Tailscale admin, root/admin SSH keys.

Policy: explicit per-read confirmation. Prefer scoped temporary credentials. Backup/recovery should be complete first.

### Break-glass

Examples: vault recovery material, emergency admin credentials, backup decryption keys.

Policy: not shared with assistant by default.

## Retrieval Procedure Draft

Before retrieving a secret, assistant states:

- Vault item reference, not value.
- Why access is needed.
- Intended command/action.
- Whether the operation is read-only or mutating.
- Where the secret will be used.
- How the secret will be avoided in logs/history.
- Revocation/rotation path if exposed.

For high-risk items, stop and request explicit confirmation.

## Pilot Checklist

- [ ] Dedicated assistant account exists.
- [ ] Pilot collection exists.
- [ ] One low-risk credential is added by the user.
- [ ] Assistant runtime location is selected and has strict permissions.
- [ ] Bitwarden/Vaultwarden CLI or approved client is installed on runtime.
- [ ] Assistant logs in/unlocks without storing secret values in git/chat.
- [ ] Assistant retrieves item metadata first.
- [ ] Assistant uses credential for harmless verification without printing value.
- [ ] User confirms result.
- [ ] Revocation/rotation path is documented.

## Revocation

To revoke assistant vault access:

1. Disable/remove assistant Vaultwarden account or collection share.
2. Revoke active sessions for the assistant account.
3. Remove assistant CLI/session material from runtime host.
4. Rotate any secrets the assistant could read if compromise is suspected.
5. Verify assistant can no longer access the vault or collection.
6. Log revocation without secret values.