Rotating secrets

Workflow estándar para rotar tokens, API keys y passwords usando SOPS + age. Asume que la setup base de SOPS key rotation está hecha (al menos un keypair por nodo y por usuario humano).

Cuándo rotar

• Programado: cada 6 meses para tokens long-lived (CF API, Telegram, HA).
• Reactivo: filtración sospechada, ex-colaborador, dispositivo perdido.
• Tras la migración inicial (F3): los secretos pre-existentes en plaintext se consideran posiblemente expuestos en logs/history y deben rotarse.

Secretos en alcance

Inventario actual (post-migración F3 inicial):

Secreto	Archivo SOPS	Notas
Loki / Prom basic auth	secrets/observability.sops.yaml	Migrado
Home Assistant long-lived	secrets/homeassistant.sops.yaml	Pendiente
Telegram bot token (n8n)	secrets/telegram.sops.yaml	Pendiente
Cloudflare API token	secrets/cloudflare.sops.yaml	Pendiente
n8n webhook secret	secrets/n8n.sops.yaml	Pendiente
PBS API token	secrets/pbs.sops.yaml	Pendiente
PocketID OIDC client secrets	secrets/pocketid.sops.yaml	Pendiente (F5)
Hermes Anthropic API key	secrets/hermes.sops.yaml	Pendiente

Workflow base

1. Editar el archivo SOPS

bash cd ~/homelab-infra sops secrets/telegram.sops.yaml

Se abre el editor ($EDITOR) con el contenido descifrado. Edita el valor:

yaml bot_token: <NUEVO_TOKEN> chat_id: 123456789

Guarda y sal. SOPS re-cifra automáticamente.

2. Verificar el diff

bash git diff secrets/telegram.sops.yaml

Debería mostrar solo cambios en los campos cifrados (data:, mac:, lastmodified:). No debería aparecer texto plano.

3. Commit + push

bash git add secrets/telegram.sops.yaml git commit -m "secrets(telegram): rotate bot token" git push

4. Esperar Ansible-pull (15min) o forzar

bash ssh pmx-50 'ansible-pull -U https://github.com/monxas/homelab-infra.git ansible/playbook.yml --limit pmx-50'

(Igual para pmx-51 y nodos afectados.)

5. Reiniciar el servicio que usa el secreto

```bash

Ejemplo: n8n alert forwarder

ssh pmx-51 'pct exec 200 -- systemctl restart alert-forwarder' ```

6. Verificar

```bash

Trigger un alert de prueba

ssh pmx-51 'pct exec 200 -- curl -X POST http://localhost:5678/webhook/test-alert'

Comprobar que llega Telegram

```

Generar un secret nuevo

Token aleatorio (32 chars hex)

bash openssl rand -hex 32

Token aleatorio (URL-safe base64)

bash openssl rand -base64 32 | tr -d '=' | tr '+/' '-_'

Password humano-recordable (passphrase 5 palabras)

```bash

Si tienes diceware o pwgen

pwgen -s 24 1 ```

Bcrypt hash (para basic auth Caddy o htpasswd)

Genera en la máquina destino (no via SSH desde la Mac — el shell remoto expande $ y rompe el hash). Ver Creating OIDC client para más detalle.

bash ssh pmx-50 'pct exec 270 -- caddy hash-password --plaintext "<password>"'

Crear un archivo SOPS nuevo

```bash cd ~/homelab-infra

Edita partiendo de plantilla mínima

cat > secrets/newservice.sops.yaml.plain <<'EOF' api_key: EOF sops -e secrets/newservice.sops.yaml.plain > secrets/newservice.sops.yaml rm secrets/newservice.sops.yaml.plain

Edita el cifrado para meter el valor real

sops secrets/newservice.sops.yaml ```

Las reglas de .sops.yaml (creation_rules) determinan automáticamente las recipient keys para secrets/.*\.sops\.yaml$.

Después de rotar

• Borrar el token viejo en el provider (CF, Telegram, etc.) — si no, sigue válido.
• Buscar referencias al token viejo en logs (grep -r "<prefix-token>" /var/log) por si quedó en algún sitio.
• Documentar la rotación en el commit message + Hermes log si aplica.

Lista de tokens a rotar inmediatamente post-F3

Tras la migración a SOPS, considerar los siguientes como posiblemente expuestos (estuvieron en plaintext en .env/history/backups):

1. CF API token con permisos DNS — alta prioridad.
2. CF Tunnel credentials (<uuid>.json) — regenerar tunnel si dudas.
3. Telegram bot tokens (n8n alert forwarder + morning-report).
4. HA long-lived tokens (Hermes, ha-ml, scripts externos).
5. PBS API token.
6. NAS SMB/NFS share passwords.
7. PocketID admin password.
8. Vaultwarden admin token.

Plan: rotar 1-3 por semana para evitar romper algo y poder bisectar.