# Secrets and Access Management Runbook

## Purpose

Define how Nimrod tracks, grants, revokes, rotates, and eventually centralizes homelab secrets and access without committing secret values to git.

## Approved Target Model

- Primary human/admin vault: Vaultwarden/Bitwarden-compatible vault.
- Preferred vault host: dedicated Proxmox VM.
- Vault exposure: LAN and Tailscale only by default.
- Public exposure requires a separate security review.
- User clarified on 2026-06-06 that enabling Nimrod/the assistant to access approved secrets safely is a primary purpose of Vaultwarden, especially for internal-network administration.
- Assistant vault access should be implemented deliberately with a dedicated assistant identity, limited collections/items, clear approval/retrieval procedures, audit/revocation steps, and no access to the user's personal vault login.
- Initial broad assistant vault access is not yet enabled; work is now tracking toward a controlled pilot.

## Never Store in Git

Do not commit:

- plaintext passwords
- private keys
- API token values
- app password values
- vault recovery codes
- 2FA recovery codes
- backup encryption keys
- emergency break-glass secret values

It is acceptable to document secret metadata, such as purpose, owner, storage location, and revocation path.

## Credential Metadata Template

Use this template in tickets, runbooks, or inventory when documenting a credential without exposing its value:

```markdown
### Credential: <reference name>

- Owner:
- Purpose:
- Scope/permissions:
- Created:
- Rotation due:
- Stored in: <vault item or host path, no value>
- Used by:
- Dependent services:
- Grant procedure:
- Revoke procedure:
- Rotation procedure:
- Verification after grant:
- Verification after revoke:
- Notes:
```

## SSH Credentials

Current pattern:

- dedicated `piagent` user per host
- key-only login
- locked password
- least necessary sudo/service permissions
- named alias in `.pi/ssh/hosts.json`
- destructive-command confirmation enabled

For grant/revoke/rotate details, use `runbooks/configure-assistant-ssh-access.md`.

## Service App Passwords / API Tokens

Grant:

1. Prefer a dedicated least-privilege service account.
2. Create a per-purpose token or app password.
3. Store the value only in the approved vault or host-local secret file.
4. Restrict local secret file permissions.
5. Restart dependent service if needed.
6. Verify the dependent service works.
7. Log the change in `docs/server-change-log.md` without the secret value.

Revoke:

1. Stop dependent service if practical.
2. Revoke the token/app password in the service UI/API.
3. Remove or blank local references.
4. Verify authentication fails or the service no longer uses the credential.
5. Log the revocation without the secret value.

Rotate:

1. Create replacement credential.
2. Update the dependent service.
3. Verify the replacement works.
4. Revoke the old credential.
5. Verify old credential no longer works where safe.
6. Log rotation metadata only.

## Vault Users

For each vault user/admin:

- document role and recovery owner
- require strong master password
- require 2FA where practical
- preserve recovery material outside the vault
- remove access promptly when no longer needed
- rotate shared credentials if a removed user may have seen them

## Break-Glass / Recovery Material

Recovery material must not exist only inside the vault it recovers.

Keep an offline or separately protected recovery kit containing, as applicable:

- vault admin recovery details
- 2FA recovery codes
- backup decryption key location
- restore instructions
- Proxmox emergency admin path
- Tailscale/admin account recovery information

The assistant may know where the recovery procedure is documented, but should not automatically possess break-glass secrets.

## Backup Expectations for Vaultwarden

Before relying on the vault for critical secrets:

1. Configure a basic backup.
2. Confirm backup artifacts are created and non-empty.
3. Store backup encryption/recovery material outside the vault.
4. Perform a restore test soon after initial deployment.
5. Log backup and restore verification in `docs/server-change-log.md`.

Backup scope should include:

- Vaultwarden data/database
- configuration
- attachments/sends/icons if enabled
- admin token material
- TLS/reverse-proxy configuration
- backup scripts/configuration

## Exposure Rules

- LAN and Tailscale access are approved for the target vault design.
- Public port forwarding or public reverse proxy exposure is not approved by default.
- Any public exposure requires a separate threat model/security review.

## Change Logging

Log secrets/access changes in `docs/server-change-log.md` with:

- host/service
- reason
- credential reference only, no value
- actions taken
- files/services changed
- verification
- rollback/revocation notes
- confirmation that no secret value was logged