Guarde secrets no keychain do SO

Uma env var normal vive em texto puro dentro de envs/<env>.toml. Isso tá ok pra BASE_URL, mas não pra PAYMENTS_API_TOKEN ou sua senha do Postgres. Marcar uma variável como secret muda onde ela é guardada: keychain do SO (Keychain no macOS, Credential Manager no Windows, Secret Service no Linux), com só uma sentinela no TOML / SQLite.

Marque uma variável como secret

No Environment manager (ícone LuLayers no sidebar → escolha env → clique numa linha de variável):

1. Clique no 🔒 toggle de lock ao lado do campo de valor.
2. Da primeira vez, o httui pergunta: “Digite o valor secret pra PAYMENTS_API_TOKEN”. Digite o valor real, aperte Enter.
3. O httui guarda o valor no keychain do seu SO e escreve a sentinela __KEYCHAIN__ em envs/<env>.toml / SQLite.

O TOML agora fica:

envs/staging.toml

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

Você pode commitar esse arquivo com segurança — o token real nunca toca o git.

Referencie o secret como qualquer outra variável

Mesma sintaxe {{KEY}}:

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

Na hora da run, o httui:

1. Vê a referência, faz lookup de PAYMENTS_API_TOKEN.
2. Acha a sentinela __KEYCHAIN__.
3. Busca o valor real no keychain do SO.
4. Substitui e manda a request.

A aba Raw do painel de response NÃO mostra o secret resolvido — é mascarada como *** pra gravações de tela ficarem seguras.

Senhas de conexão

Mesmo fluxo pra connections.toml. Quando você adiciona uma conexão 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"

A sintaxe {{keychain:<scope>:<key>}} diz pro httui “procura isso no keychain sob o namespace <scope>”. Na primeira vez que um bloco usa essa conexão, o httui pergunta pelos valores e guarda.

Nomeando a entrada do keychain

{{keychain:pg-staging:password}} vira uma entrada de keychain tipo httui::pg-staging::password no seu SO. Abra Keychain.app / Credential Manager / secret-tool pra ver e remover entradas que o httui criou.

Compartilhando conexões sem compartilhar secrets

O connections.toml acima commita limpo — host, port, database, user/password como referências. Seu colega clona o vault, abre, e o httui vê as referências mas nenhuma entrada de keychain.

O httui mostra um banner “Resolve secrets” no topo do editor:

⚠ Esse vault referencia 2 secrets que não estão no seu keychain: pg-staging:user, pg-staging:password. Resolve →

Clique → pergunta pra cada → keychain populado. As duas máquinas agora rodam o mesmo runbook contra a mesma conexão, mas a senha de cada dev fica na máquina dele.

O que acontece se o keychain tá travado / indisponível

Situação	Comportamento
Keychain travado (macOS dormindo / Linux sem login)	Primeiro bloco bate em prompt pra senha do sistema; blocos seguintes na mesma sessão reusam o keychain destravado
Entrada de keychain faltando	Banner “Resolve secrets” aparece; bloco não roda até ser populado
Backend de keychain indisponível (CI runner, headless)	O httui cai pra valor plaintext no TOML / SQLite, loga um warning

O fallback é intencional — você prefere ter um runbook de CI rodando com secrets injetados via env vars do que falhar porque não tem Keychain.app no runner.

Rotacionando um secret

1. Abra Environment manager → escolha a variável.
2. Clique no campo de valor (ainda mostra ***).
3. Digite o valor novo, aperte Enter.
4. O httui sobrescreve a entrada do keychain. A sentinela no TOML não muda.

Todos os blocos que referenciam a variável usam o valor novo na próxima run — caches chaveados no valor antigo invalidam automaticamente (a key de cache inclui um fingerprint dos secrets resolvidos).

Removendo um secret

No Environment manager, clique no ícone de lixeira ao lado da linha da variável. O httui:

1. Remove a entrada do keychain.
2. Remove a linha de envs/<env>.toml / SQLite.

Se um bloco ainda referencia a key deletada, a próxima run mostra um banner “Resolve secrets” com a key faltante listada.

Gotchas comuns

Sintoma	Causa	Correção
Bloco envia Bearer __KEYCHAIN__ literal	Entrada de keychain faltando; o httui não resolveu	Clique em “Resolve secrets” no banner
Valor do secret mudou mas bloco ainda usa o antigo	Cache de bloco velho (improvável — cache invalida em troca de env)	Engrenagem da toolbar → “Clear cache”
Quero ver o secret real pra debug	A UI mascara valores de propósito	Abra a UI do keychain do SO (Keychain Access / Credential Manager)