docs(claude): criterio SOPS vs Bitwarden y descifrado vía SOPS_AGE_KEY_CMD

[dferraes]

Propaga a este repo dos decisiones del 2026-08-25 sobre secretos — parte de la propagación a los 61 repos activos de dferraes + ITEVOX y a los 4 agentes locales (Claude Code, Codex, Gemini/Antigravity, Kimi).

1. Qué secreto va a SOPS y cuál va a Bitwarden

"Todo secreto se cifra con SOPS+age" suena a regla simple, pero mezcla dos necesidades distintas bajo un mismo mecanismo. La mezcla ya produjo un caso real: el password semilla del superusuario de NetBox terminó dentro de un vault SOPS de Ansible junto a claves que sí son de despliegue, cuando en realidad es el login de una persona a un panel.

• ¿Quién lo consume? Una herramienta que renderiza un archivo del repo → SOPS. Una persona → Bitwarden.
• ¿Quién lo generó? Lo generó el despliegue y nadie lo teclea (SECRET_KEY_BASE, un DES key) → SOPS siempre. Lo eligió una persona o lo emitió un tercero → nunca es sólo-SOPS.
• Desempate: si aplican las dos, Bitwarden es la fuente de verdad; la copia en SOPS, si hace falta, va marcada como espejo y se rota desde el origen.
• Tercer bucket: lo que consume GitHub Actions vive en GitHub Secrets, con Bitwarden como custodia.

2. Descifrar sin llave local (SOPS_AGE_KEY_CMD + Bitwarden)

Copiar ~/.config/sops/age/keys.txt a mano en cada máquina nueva era el precio de que un dev container o un remoto no traigan la llave por diseño. Con SOPS_AGE_KEY_CMD apuntando a rbw get, cualquier máquina con la bóveda desbloqueada descifra sin que nadie copie un archivo.

• Es aditivo y no toca .sops.yaml: es del lado de quien descifra, no cambia los recipients.
• Apunta al item que ya existe (Llave age personal) en vez de crear uno nuevo — dos items con el mismo secreto son dos fuentes de verdad.
• Sólo aplica a la llave personal de David; las llaves generadas en un host y que nunca salen de ahí no se migran.
• Documenta el falso OK de la verificación: sops cae de vuelta al archivo local sin avisar, así que un sops -d exitoso en la máquina principal no prueba que el CMD sirva.

Verificado empíricamente el 2026-08-25 con sops 3.13.3: con la config local aislada, el control falla y el SOPS_AGE_KEY_CMD descifra.

Alcance

Solo documentación — este PR no mueve, cifra, rota ni reclasifica ningún secreto, y no cambia ningún .sops.yaml.

Criterio completo: spec-gestion-secretos.md (§Capa 0 y §Capa 1)

🤖 Generated with Claude Code

https://claude.ai/code/session_01Vym5o4grvEgVWTFSFvuHy8