# Ticket: Consolidated homelab secrets and access management

## Metadata
- Type: Ticket
- Status: In Progress
- Project: Homelab security / remote administration
- Created: 2026-05-18
- Updated: 2026-06-06
- Priority: Highest / Critical

## Goal

Design and deploy a consolidated secrets and access management system for the homelab so the user can grant, revoke, and temporarily grant access to servers and clients on the LAN in a controlled, auditable way.

## Why

Current access is being handled ad hoc with SSH keys, passwords, API tokens, and per-system setup. As the assistant gains access to more infrastructure, the environment needs a safer and more maintainable model for:

- centralized secrets storage
- temporary/expiring access
- rapid revocation
- auditability
- least-privilege permissions
- avoiding long-lived root passwords or scattered credentials
- enabling safe assistant operations across homelab servers and clients

## Scope

Included:
- Inventory current access methods and credentials in use, without storing secrets in this repository.
- Choose a secrets/access management approach suitable for a homelab.
- Evaluate options such as Bitwarden/Vaultwarden, HashiCorp Vault/OpenBao, SOPS/age, SSH certificates, Tailscale ACLs, OPNsense/API credentials, Proxmox API tokens, and short-lived assistant credentials.
- Define an access model for:
  - permanent user/admin access
  - assistant access
  - emergency break-glass access
  - temporary grants with expiry
  - service/API tokens
- Define revocation procedures for SSH keys, API tokens, VPN access, and passwords.
- Create a runbook for granting/removing assistant access to a host.
- Create a runbook for rotating compromised or stale credentials.
- Ensure approach works for LAN servers, Proxmox, OPNsense, VMs/LXCs, and later client machines where appropriate.
- Prefer auditable, least-privilege access over shared root credentials.

Not included:
- Storing plaintext secrets in git.
- Exposing management interfaces publicly without deliberate security review.
- Replacing all existing credentials before a design is approved.
- Making destructive access-control changes without backup/snapshot and explicit approval.

## Acceptance Criteria

This ticket is done when:
- A documented secrets/access architecture exists.
- A primary secrets management tool/system is selected and justified.
- A bootstrap plan exists for initial deployment.
- A revocation model exists for assistant access and user access.
- At least one representative host can be granted and revoked assistant access using the new process.
- Access procedures are documented in runbooks.
- Sensitive credentials are not committed to the repository.
- Server-side changes are logged in `docs/server-change-log.md`.

## Questions

- Should the primary secrets vault be self-hosted, cloud-backed, or hybrid?
- Does the user want browser/mobile password-manager access, machine-to-machine secrets, or both?
- Should temporary access be implemented with SSH certificates, Tailscale ACLs, expiring API tokens, or another mechanism?
- Which systems are in scope first: Proxmox, OPNsense, AMP, Nextcloud, Home Assistant, desktops/laptops?
- Should the assistant have direct vault access, or should the user mediate secret release?
- What is the desired emergency/break-glass procedure if the vault is unavailable?

## Plan / Next Actions

- [x] Create a short spec comparing candidate approaches.
- [x] Inventory current systems and access types without recording secret values.
- [x] Identify the minimum viable access model for the next 1–2 weeks.
- [x] Pick a first implementation target: disposable SSH lifecycle management pilot.
- [x] Draft grant/revoke runbooks.
- [x] Implement a pilot on one non-critical host.
- [x] Review Vaultwarden deployment details with the user before broad rollout.
- [x] User creates initial Vaultwarden account, then signups are disabled.
- [ ] Backup MVP is approved/implemented before critical secrets migrate.
- [ ] Temporary bootstrap sudo and broad bootstrap tokens are reduced/revoked if practical after hardening.
- [x] Obtain approvals for remaining Vaultwarden bootstrap details: setup TLS/bootstrap path, `piagent` SSH bootstrap/maintenance model, snapshot timing, and Proxmox token revocation/reduction timing.
- [x] Capture initial Vaultwarden preferences: VM/name label `Vaultwarden`, FQDN `vw.dropcutstud.io`, DHCP, default bridge, default storage, assistant-selected OS, Proxmox default/next VMID, minimum required sizing, and no public exposure.
- [x] Create follow-up tickets for Vaultwarden backup and recovery/restore planning.

## Notes

- This is now the highest-priority infrastructure/security ticket.
- Motivation came from needing repeated access to AMP, Proxmox, and potentially OPNsense while avoiding scattered root-password workflows.
- Candidate direction to investigate: combine a human-friendly password manager such as Vaultwarden/Bitwarden with infrastructure access controls such as SSH certificates or Tailscale ACLs. More sensitive automation may require Vault/OpenBao or SOPS/age later.
- 2026-06-06: QRSPI artifacts now select Vaultwarden/Bitwarden-compatible vault in a dedicated Proxmox VM, LAN/Tailscale-only by default, with assistant direct vault access deferred. Disposable SSH lifecycle pilot completed on LXC 102 `access-pilot` and destroyed after revoke verification.
- 2026-06-06: Drafted planning runbooks for Vaultwarden deployment, operations, backup, and restore testing. Vaultwarden infrastructure was later created and bootstrap-deployed; keep backup/restore tickets open before critical secret migration.
- 2026-06-06: User provided initial Vaultwarden preferences: VM/name label `Vaultwarden`, FQDN `vw.dropcutstud.io`, DHCP IP, default bridge, default storage, assistant may choose OS image. Backup and recovery planning are now separate follow-up tickets.
- 2026-06-06: User approved Proxmox default/next VMID allocation, minimum required CPU/RAM/disk, and no public exposure. Assistant recommended `piagent` key-only SSH with temporary passwordless sudo for bootstrap, Proxmox snapshots at deployment checkpoints, and reducing/revoking the broad Proxmox token after bootstrap.
- 2026-06-06: User said to ignore DNS provider automation for now; they will set up a LAN Unbound exception for `vw.dropcutstud.io`. Tailscale will be handled separately.
- 2026-06-06: Read-only Proxmox preflight found next available VMID `102`, default bridge `vmbr0`, default VM storage candidate `local-lvm`, and no suitable Debian/Ubuntu VM ISO initially available. User made Debian ISO available.
- 2026-06-06: Created Proxmox VM `102` named `Vaultwarden` with 1 vCPU, 1024 MB RAM, 16 GB disk on `local-lvm`, DHCP on `vmbr0`, and no public exposure; later converted to an unattended Debian 13 cloud-image bootstrap path.


## 2026-06-06 Vaultwarden Bootstrap Update

- User approved continuing deployment, `piagent` temporary sudo, self-signed/internal TLS, deferred backups with no critical secret migration, and offline physical recovery material.
- VMID `102` (`Vaultwarden`) is running Debian 13 at DHCP IP `192.168.0.238`.
- Vaultwarden is deployed behind Nginx HTTPS with a self-signed certificate for `vw.dropcutstud.io`.
- Verified endpoint with local DNS override returned HTTP `200`.
- Proxmox snapshots created: `pre-vaultwarden-install` and `post-vaultwarden-service-installed`.
- User initial account was created; `SIGNUPS_ALLOWED=false` and `INVITATIONS_ALLOWED=false` were recorded after hostname correction.
- Do not migrate critical secrets until backup/recovery work is complete or explicitly risk-accepted.

## 2026-06-07 — Infrastructure Ready for Assistant Vault Access Pilot

### What was done

**Infrastructure (Nimrod LXC 104):**
- Bitwarden CLI (`bw` v2026.5.0) installed at `/usr/local/bin/bw`
- Server configured to `https://vw.dropcutstud.io`
- Secure session directory: `~/.vault/` (mode 700)

**Tooling:**
- Created `scripts/vault-assistant.sh` — helper with functions:
  - `vault-login` (API key auth)
  - `vault-unlock` (master password unlock, exports BW_SESSION)
  - `vault-list`, `vault-search`, `vault-get`, `vault-get-field`
  - `vault-logout`, `vault-status`
- Created `docs/assistant-vault-access-model.md` — architecture doc
- Updated `runbooks/assistant-vaultwarden-access.md` with concrete implementation

**Architecture design:**
- Account/collection structure defined (pilot infra proxmox)
- Item naming convention standardized
- Secret classification documented (low/medium/high/break-glass)
- Proxmox token rotation plan documented
- Revocation procedure documented

### User-side steps remaining (blocking)

1. [ ] Create the assistant Vaultwarden account (`nimrod-vault` or preferred name)
2. [ ] Create `nimrod-pilot` collection, share with assistant (Can Read)
3. [ ] Add one low-risk credential to the collection (Homepage/Homarr admin)
4. [ ] Generate API key for assistant account
5. [ ] Share API key + master password with assistant runtime

### Remaining Next Actions

- [ ] Test vault-login vault-unlock vault-get on Nimrod LXC
- [ ] Complete pilot checklist (see runbook)
- [ ] Create least-privilege Proxmox token, store in vault
- [ ] Rotate/reduce old broad Proxmox bootstrap token
- [ ] Document token lifecycle and revocation