Guarda secretos en el OS keychain

Una env variable regular vive en texto plano dentro de envs/<env>.toml. Eso está bien para BASE_URL, pero no para PAYMENTS_API_TOKEN o tu contraseña de Postgres. Marcar una variable como secret cambia donde se guarda: OS keychain (Keychain en macOS, Credential Manager en Windows, Secret Service en Linux), con solo un valor sentinel en el TOML / SQLite.

Marca una variable como secret

En el Environment manager (ícono LuLayers del sidebar → elige env → haz clic en una fila de variable):

1. Haz clic en el 🔒 lock toggle al lado del campo de valor.
2. La primera vez, httui te pregunta: “Enter the secret value for PAYMENTS_API_TOKEN”. Tipea el valor real, hit Enter.
3. httui guarda el valor en tu OS keychain y escribe el sentinel __KEYCHAIN__ en envs/<env>.toml / SQLite.

El TOML ahora se ve así:

envs/staging.toml

[vars]
BASE_URL = "https://staging-api.example.com"
PAYMENTS_API_TOKEN = "__KEYCHAIN__"   # valor real en el keychain

Puedes commitear este archivo con seguridad — el token real nunca toca git.

Referencia el secret como cualquier otra variable

La misma sintaxis {{KEY}}:

```http
GET {{BASE_URL}}/payments
Authorization: Bearer {{PAYMENTS_API_TOKEN}}
```

En tiempo de ejecución, httui:

1. Ve la referencia, busca PAYMENTS_API_TOKEN.
2. Encuentra el sentinel __KEYCHAIN__.
3. Trae el valor real del OS keychain.
4. Sustituye y envía la request.

El tab Raw en el panel de respuesta NO muestra el secret resuelto — está enmascarado como *** para que las screen recordings se queden seguras.

Contraseñas de conexión

Mismo flujo para connections.toml. Cuando agregas una conexión Postgres:

[connections.pg-staging]
type = "postgres"
host = "pg-staging.acme.local"
port = 5432
database = "payments"
user = "{{keychain:pg-staging:user}}"
password = "{{keychain:pg-staging:password}}"
ssl_mode = "require"

La sintaxis {{keychain:<scope>:<key>}} le dice a httui “busca esto en el keychain bajo el namespace <scope>”. La primera vez que un bloque usa esta conexión, httui pregunta por los valores y los guarda.

Nombrando la entrada del keychain

{{keychain:pg-staging:password}} pasa a ser una entrada del keychain como httui::pg-staging::password en tu SO. Abre Keychain.app / Credential Manager / secret-tool para ver y borrar entradas que httui creó.

Compartiendo conexiones sin compartir secretos

El connections.toml de arriba commitea limpio — host, port, database, user/password como referencias. Tu compañero clona el vault, lo abre, y httui ve las referencias pero no las entradas del keychain.

httui muestra un “Resolve secrets” banner arriba del editor:

⚠ Este vault referencia 2 secretos que no están en tu keychain: pg-staging:user, pg-staging:password. Resolve →

Haz clic → prompt por cada uno → keychain poblado. Ambas máquinas ahora ejecutan el mismo runbook contra la misma conexión, pero la contraseña de cada developer se queda en su propia máquina.

Qué pasa si el keychain está locked / no disponible

Situación	Comportamiento
Keychain locked (macOS sleep / Linux no logged in)	El primer bloque dispara el prompt del system password; los bloques siguientes en la misma sesión reutilizan el keychain unlocked
Entrada de keychain missing	Aparece el banner “Resolve secrets”; el bloque no ejecuta hasta poblar
Backend del keychain no disponible (CI runner, headless)	httui cae al valor en texto plano en TOML / SQLite, loggea un warning

El fallback es intencional — preferirías tener un runbook de CI que ejecute con secretos inyectados vía env vars antes que fallar porque no hay Keychain.app en el runner.

Rotando un secret

1. Abre Environment manager → elige la variable.
2. Haz clic en el campo de valor (todavía muestra ***).
3. Tipea el nuevo valor, hit Enter.
4. httui sobreescribe la entrada del keychain. El sentinel en el TOML no cambia.

Todos los bloques que referencian la variable usan el nuevo valor en el siguiente run — los caches keyados con el valor viejo invalidan automáticamente (la cache key incluye una fingerprint de los secretos resueltos).

Removiendo un secret

En Environment manager, haz clic en el ícono de tacho al lado de la fila de la variable. httui:

1. Remueve la entrada del keychain.
2. Remueve la línea de envs/<env>.toml / SQLite.

Si un bloque todavía referencia la key borrada, el siguiente run muestra un banner “Resolve secrets” con la key faltante listada.

Gotchas comunes

Síntoma	Causa	Fix
El bloque envía Bearer __KEYCHAIN__ literal	Entrada de keychain missing; httui no pudo resolver	Haz clic en “Resolve secrets” en el banner
El valor del secret cambió pero el bloque sigue usando el viejo	Cache de bloque obsoleto (improbable — el cache invalida en cambio de env)	Engranaje de la toolbar → “Clear cache”
Quiero ver el secret real para debuggear	La UI enmascara los valores intencionalmente	Abre la UI del OS keychain (Keychain Access / Credential Manager)