# Structure: Consolidated Homelab Secrets and Access Management

## Approach

Build the secrets/access-management capability in small vertical slices that each leave behind usable documentation, a verifiable operational practice, or a safer deployment foundation. Start with documentation and a disposable SSH lifecycle pilot before touching production services. Treat Vaultwarden as critical infrastructure: plan deployment, establish a basic backup, then prove restore before relying on it broadly. Defer direct assistant vault access to a later authorization/security design.

## Phase 1: Documentation and Runbook Baseline

**Files:**
- `runbooks/configure-assistant-ssh-access.md`
- `runbooks/secrets-management.md` or equivalent new runbook
- `docs/server-change-log.md`
- `systems/inventory.md`
- `tickets/artifacts/2026-05-18-consolidated-homelab-secrets-management/04-structure.md`

**Key changes:**
- Document the target secrets model: Vaultwarden/Bitwarden-compatible vault for human/admin secrets, user-mediated assistant access, no secret values in git.
- Add or update runbook sections for credential metadata: owner, purpose, scope, storage location, rotation date, and revocation path.
- Capture SSH grant/revoke/rotate procedures as reusable operational checklists.
- Add explicit break-glass/recovery documentation expectations without recording secret values.
- Define when server-side changes must be logged in `docs/server-change-log.md`.

**Verify:**
- Automated:
  - Confirm markdown files exist and contain no obvious plaintext secret placeholders or copied secret values.
  - Optionally run available markdown/link checks if the repo has them.
- Manual:
  - Review the runbooks for completeness against the design decisions in `03-design.md`.
  - Confirm the user understands that secrets remain outside git and assistant vault access is not part of MVP.

## Phase 2: Disposable SSH Lifecycle Pilot

**Files:**
- `.pi/ssh/hosts.json`
- `runbooks/configure-assistant-ssh-access.md`
- `docs/server-change-log.md`
- `systems/inventory.md`
- Relevant ticket notes under `tickets/`

**Key changes:**
- Use a disposable Debian/Ubuntu VM or LXC as the first pilot target.
- Add a temporary named SSH alias for the disposable host with raw hosts still disabled and destructive confirmation enabled.
- Exercise the full assistant SSH lifecycle: grant, verify, rotate, revoke, and verify failure after revocation.
- Log each operational change without recording private keys or secret values.
- Keep production systems such as Nextcloud, AMP, Proxmox, OPNsense, and Home Assistant out of the pilot.

**Verify:**
- Automated:
  - Validate `.pi/ssh/hosts.json` remains parseable JSON.
  - Confirm expected SSH alias behavior using non-secret key paths and known-host policy.
- Manual:
  - Confirm login succeeds after grant.
  - Confirm the rotated key works before removing the old key.
  - Confirm old/revoked access fails.
  - Confirm rollback is available by destroying/reverting the disposable VM/LXC snapshot.

## Phase 3: Vaultwarden VM Deployment Planning

**Files:**
- New or updated Vaultwarden deployment plan/runbook under `runbooks/`
- `systems/inventory.md`
- `systems/network-plan.md`
- `docs/server-change-log.md`
- Relevant ticket/spec artifacts under `tickets/`

**Key changes:**
- Plan a dedicated Proxmox VM for Vaultwarden rather than LXC.
- Define VM sizing, hostname, LAN/Tailscale-only exposure, TLS approach, update model, admin access model, and snapshot expectations.
- Identify what must be backed up: Vaultwarden database/data, config, attachments/sends/icons if enabled, admin token material, TLS/reverse-proxy config, and backup encryption material.
- Define initial credential categories to migrate without requiring a full migration on day one.
- Add checkpoint/rollback notes for pre-deployment snapshots and stopping before public exposure or assistant vault access.

**Verify:**
- Automated:
  - Validate any structured inventory/config snippets if added.
  - Optionally run markdown/link checks if available.
- Manual:
  - User approves VM-vs-LXC choice, hostname, access boundary, and TLS strategy.
  - User confirms no public port forwarding is planned.
  - User confirms recovery material will be stored outside the vault.

## Phase 4: Basic Backup and Restore Test

**Files:**
- Vaultwarden backup runbook under `runbooks/`
- Restore-test notes or runbook under `runbooks/`
- `docs/server-change-log.md`
- `systems/inventory.md`
- Relevant ticket notes under `tickets/`

**Key changes:**
- Establish a basic backup process before relying on Vaultwarden for critical secrets.
- Include backup scope, destination, encryption, retention, operator steps, and verification method.
- Perform a restore test soon after the basic backup exists, preferably into an isolated disposable restore target.
- Record backup success/failure, restore-test date, and rollback notes.
- Document recovery prerequisites that must not live only inside the vault.

**Verify:**
- Automated:
  - Confirm backup job or script exits successfully if implemented in a later phase.
  - Confirm expected backup artifacts are present and non-empty.
- Manual:
  - Confirm restored Vaultwarden data is usable in the isolated restore target.
  - Confirm restore does not require inaccessible vault-only secrets.
  - Confirm the production vault can be left unchanged if restore testing fails.

## Phase 5: Later Assistant Authorization Design

**Files:**
- New design/security artifact under `tickets/artifacts/` or `docs/`
- `docs/assistant-role-architecture.md`
- `docs/agentic-engineering-lite.md`
- Relevant runbooks for vault/API token authorization

**Key changes:**
- Design whether and how the assistant may request or receive secrets from the vault after a separate security review.
- Include explicit user approval, least privilege, audit logging, revocation, session/expiry controls, and emergency stop paths.
- Consider alternatives before direct vault access: user-mediated copy/paste, per-service app passwords, scoped API tokens, SSH certificates, Tailscale ACLs, SOPS/age, or OpenBao/Vault.
- Define assistant authorization boundaries by role/task rather than broad vault access.
- Keep this out of the MVP deployment and block implementation until approved.

**Verify:**
- Automated:
  - Documentation checks only; no assistant vault access automation in this phase unless separately approved.
- Manual:
  - User reviews and approves the assistant authorization model before any implementation.
  - Confirm blast radius, auditability, and revocation are acceptable.
  - Confirm rollback/disable path is clear and tested where practical.

## Testing Checkpoints

- Documentation baseline reviewed before touching any host.
- Disposable SSH pilot completed before production-host access lifecycle changes.
- Production Vaultwarden deployment plan approved before VM creation or service installation.
- Backup process exists before critical secrets are migrated into Vaultwarden.
- Restore test passes before Vaultwarden is treated as authoritative.
- Assistant direct vault access remains explicitly deferred until a later authorization/security design is approved.
- Rollback checkpoints: disposable VM/LXC snapshot or destroy path, Proxmox snapshot before Vaultwarden changes, documented backup restore path, and logged revocation steps for any access granted.