# Assistant Vault Access Plan

## Trigger

On 2026-06-06, the user clarified that the main reason for deploying Vaultwarden is so Nimrod/the assistant can access secrets safely, especially for administering the internal network.

## Goal

Enable assistant access to approved homelab secrets without giving the assistant uncontrolled access to the user's full vault or storing secret values in git/chat.

## Safety Principles

- Use a dedicated assistant identity, never the user's personal vault login.
- Grant least-privilege access to specific collections/items.
- Prefer explicit user approval for each sensitive secret release until a stronger authorization workflow exists.
- Store secret values only in Vaultwarden or approved host-local secret stores, not in this repository.
- Record metadata and procedures only: item name, purpose, scope, owner, storage location, rotation/revocation path.
- Keep backup and recovery material outside Vaultwarden before relying on it for critical secrets.
- Make revocation simple: disable/delete assistant vault account, rotate exposed credentials, remove sessions/tokens.

## Candidate Access Models

### Model A — User-mediated retrieval, no assistant vault login

User logs into Vaultwarden and gives the assistant only the specific secret needed at the moment, preferably through an ephemeral local mechanism or manual copy.

Pros:
- Safest initial posture.
- No assistant vault credentials to protect.
- Easy to reason about.

Cons:
- Does not satisfy autonomous/efficient network administration well.
- User remains a bottleneck.

### Model B — Dedicated assistant Vaultwarden user with limited collection access

Create a `nimrod`/`piagent` Vaultwarden user and share only approved collections/items.

Pros:
- Aligns with user's stated goal.
- Access can be scoped by collection.
- Account can be disabled/revoked.

Cons:
- Assistant session/master password handling must be designed carefully.
- Vaultwarden itself has limited fine-grained audit compared with enterprise secret managers.
- Any secret read by an assistant may need to be considered exposed and rotated if access is revoked after compromise.

### Model C — Dedicated assistant user plus user-approved retrieval workflow

Create dedicated assistant account, but require user confirmation before retrieving high-risk secrets. Store only session material in an approved runtime secret location, not git.

Pros:
- Balances utility and safety.
- Enables repeatable administration while preserving user control.

Cons:
- Requires additional tooling/procedure.
- Need to define where assistant session material lives and how it is revoked.

### Model D — Later machine-to-machine broker

Use Vaultwarden as human vault, but introduce OpenBao/Vault/SOPS/SSH certificates later for short-lived machine credentials.

Pros:
- Stronger fit for dynamic secrets and temporary access.

Cons:
- More complexity; not MVP.

## Recommended MVP Direction

Use **Model C** in phases:

1. Complete backup/recovery minimum or get explicit risk acceptance for a limited pilot.
2. Create a dedicated assistant Vaultwarden user, e.g. `nimrod` or `piagent`, not an admin.
3. Create collections by risk/scope:
   - `homelab-low-risk-pilot`
   - `homelab-admin-ssh`
   - `homelab-service-api-tokens`
   - `homelab-break-glass` (not shared with assistant by default)
4. Share only the pilot collection first.
5. Add one low-risk item or test credential/reference.
6. Define a retrieval procedure that avoids logging secret values.
7. Verify the assistant can use the secret for a harmless/read-only action.
8. Revoke assistant access and verify loss of access.
9. Only then expand to internal-network administration credentials.

## Open Decisions

- Dedicated assistant account name/email.
- Whether assistant should know/store its Vaultwarden master password or require user unlock each session.
- Where any assistant vault session/token may live, if used at all.
- Whether to use Bitwarden CLI from the server-hosted Pi environment or another integration.
- Which first low-risk secret/credential should be used for the pilot.
- Which collections should exist and which should never be shared with assistant.
- What approval level is required for high-risk reads such as Proxmox, OPNsense, DNS, Tailscale, and break-glass credentials.

## Immediate Next Steps

- Ask user to approve the assistant access model and pilot scope.
- Create/update `runbooks/secrets-management.md` with assistant vault access procedure.
- Consider installing/testing Bitwarden CLI only after deciding where Pi will run and how assistant sessions are protected.
- Keep `SIGNUPS_ALLOWED=false`; use invitation/manual user creation for the assistant account if approved.

## User Decisions — 2026-06-06

- Target model: dedicated assistant Vaultwarden user plus confirmed reads for high-risk secrets.
- First pilot: one low-risk real service credential with easy rotation.
- Assistant Vaultwarden login/session material should live only on the server-hosted assistant runtime with strict filesystem permissions, not in git and not in ordinary chat logs.
- Backup gate: user accepts a limited real low-risk pilot before full backup/recovery is complete, but critical/high-risk secrets remain blocked until backup/recovery is implemented or separately risk-accepted.

## Updated MVP Design

### Identities

- Human/admin user: the user's personal Vaultwarden account; never shared with the assistant.
- Assistant user: dedicated account such as `nimrod` or `piagent-vault`; not a Vaultwarden admin unless separately approved.

### Collections

Recommended starting collections:

1. `nimrod-pilot-low-risk`
   - First collection shared with the assistant.
   - Contains one low-risk, easy-to-rotate real credential.
2. `nimrod-internal-admin-approved`
   - Future internal-network admin credentials, added only after pilot and backup/recovery.
3. `break-glass-offline`
   - Do not share with assistant by default.
   - Store only references/procedures in repo; values remain offline or under user control.

### Retrieval Policy

Classify vault items before sharing:

- Low-risk: assistant may retrieve after task-level approval.
- Medium-risk: assistant must state why it needs the secret and what command/action will use it.
- High-risk: explicit per-read confirmation required; prefer temporary scoped credentials.
- Break-glass: not available to assistant by default.

### Runtime Storage

Assistant vault CLI/session data should be stored only on the server-hosted Pi/Nimrod runtime, under a dedicated user, with restrictive permissions. Until that runtime exists, do not persist assistant vault session material in this local repo/container.

### Pilot Acceptance Criteria

The pilot is complete when:

- Dedicated assistant Vaultwarden account exists.
- A pilot collection exists and is shared only as needed.
- One low-risk credential is placed in the pilot collection by the user.
- Assistant can retrieve/use the credential without logging the value.
- Use of the credential is verified for a harmless operation.
- Revocation is tested or at least documented.
- Secret value never appears in git, logs, ticket text, or chat.

## Pilot Details — 2026-06-06

- Assistant Vaultwarden account identity: `nimrod`.
- First low-risk pilot target: SearxNG/admin-like low-risk item, if a suitable non-critical credential/reference exists.

Operational note:
- Since signups are currently disabled, creating the `nimrod` Vaultwarden account will require either a short controlled signup window, an invitation/account creation path approved by the user, or waiting until an admin/account-management method is configured.
- Keep the pilot item low-risk and easy to rotate. Do not add high-risk Proxmox/OPNsense/DNS/Tailscale/break-glass credentials yet.

## Account Creation Status — 2026-06-06

- Dedicated assistant Vaultwarden account `nimrod` was created by the user through the working temporary hostname `vm.dropcutstud.io`.
- Signups were disabled immediately afterward and verified through `/api/config` (`disableUserRegistration=true`).
- The assistant does not know or store the `nimrod` master password yet.
- Current Vaultwarden `DOMAIN` remains temporarily set to `https://vm.dropcutstud.io` until the `vw.dropcutstud.io` DNS/rebind issue is fixed.

## Hostname Status — 2026-06-06

- User fixed LAN DNS/rebind for `vw.dropcutstud.io`.
- Vaultwarden `DOMAIN` restored to `https://vw.dropcutstud.io`.
- Signups remain disabled.
- Verified from Proxmox: `vw.dropcutstud.io -> 192.168.0.238` and HTTPS returns `200`.