Bitwarden Secrets Manager

Bitwarden Secrets Manager

Puxe chaves de API do Bitwarden Secrets Manager na inicialização do processo, em vez de guardá-las em texto puro dentro de ~/.hermes/.env. Um único segredo de bootstrap (um token de acesso de conta de máquina) substitui N chaves por provedor, e rotacionar uma credencial vira uma única alteração no aplicativo web do Bitwarden.

Como funciona

1. Você cria uma conta de máquina no Bitwarden Secrets Manager, dá a ela acesso de leitura a um projeto e gera um token de acesso.
2. O Hermes guarda esse único token em ~/.hermes/.env como BWS_ACCESS_TOKEN.
3. Toda vez que o hermes (ou o gateway, ou uma tarefa de cron) inicia, depois que o ~/.hermes/.env foi carregado, o Hermes chama bws secret list <project_id> e coloca as chaves devolvidas em os.environ.
4. Por padrão, o Hermes sobrescreve valores que já estão no seu ambiente, então o Bitwarden é a fonte da verdade — rotacione uma chave uma vez no aplicativo web e todo processo do Hermes pega a nova no próximo início. Mude override_existing: false na configuração se você preferir que o .env vença.

O binário bws é baixado automaticamente para ~/.hermes/bin/ no primeiro uso — sem apt, sem brew, sem sudo.

Por que contas de máquina (e por que não pede 2FA)

O Bitwarden Secrets Manager foi feito para cargas de trabalho não interativas: contas de máquina não podem ser protegidas por 2FA porque não há gente no meio do caminho. O token de acesso é a credencial. Quem tiver o token consegue ler todo segredo a que a conta de máquina tem acesso, então trate-o como um token portador de alto valor — guarde no .env (não no config.yaml) e revogue + gere de novo pelo aplicativo web do Bitwarden se ele vazar.

Você configura a conta de máquina no aplicativo web, onde o seu 2FA normal vale. Depois disso, o token é autônomo.

Configuração

1. Crie uma conta de máquina e um token de acesso

No aplicativo web do Bitwarden (ou vault.bitwarden.eu, para contas da UE):

1. Mude para o Secrets Manager no seletor de produto.
2. Crie ou escolha um Project (por exemplo, "Hermes keys").
3. Adicione as suas chaves de provedor como segredos. O Name do segredo vira o nome da variável de ambiente — use OPENROUTER_API_KEY, ANTHROPIC_API_KEY etc.
4. Machine accounts → New machine account → My Hermes machine → aba Projects → conceda acesso de leitura ao seu projeto.
5. Aba Access tokens → Create access token → expiração Never (ou escolha uma data) → copie o token (começa com 0.). O Bitwarden não consegue mostrá-lo de novo — guarde a cópia.

O Secrets Manager está incluído no plano gratuito do Bitwarden, com limites; não é preciso plano pago para experimentar.

2. Rode o assistente

hermes secrets bitwarden setup

Ele vai:

1. Baixar e verificar o bws v2.0.0 em ~/.hermes/bin/bws.
2. Pedir o token de acesso (a digitação fica oculta). Guardado em ~/.hermes/.env como BWS_ACCESS_TOKEN.
3. Perguntar a que região do Bitwarden a sua conta de máquina pertence — US Cloud, EU Cloud ou auto-hospedada / URL personalizada. Guardado no config.yaml como secrets.bitwarden.server_url e repassado ao bws como BWS_SERVER_URL.
4. Listar os projetos que a conta de máquina enxerga; escolha um. Guardado no config.yaml como secrets.bitwarden.project_id.
5. Fazer uma busca de teste dos segredos do projeto e mostrar quais variáveis de ambiente vão ser resolvidas.
6. Mudar secrets.bitwarden.enabled: true.

Também dá para configurar de forma não interativa, por opções:

hermes secrets bitwarden setup \
  --access-token "$BWS_ACCESS_TOKEN" \
  --server-url https://vault.bitwarden.eu \
  --project-id <project-uuid>

3. Confirme

hermes secrets bitwarden status

Daqui em diante, toda chamada do hermes puxa segredos novos na inicialização. Você vê um resumo de uma linha no stderr na primeira vez que os segredos são aplicados em um processo.

CLI

Comando	O que faz
hermes secrets bitwarden setup	Assistente interativo (instala o binário, pede o token, escolhe o projeto, testa a busca)
hermes secrets bitwarden status	Mostra a configuração + versão do binário + presença/validação do token
hermes secrets bitwarden token	Rotaciona o token de acesso: valida o novo token no Bitwarden e depois guarda no .env
hermes secrets bitwarden sync	Simulação: puxa os segredos agora e mostra o que seria aplicado
hermes secrets bitwarden sync --apply	Puxa e exporta para o ambiente do shell atual
hermes secrets bitwarden install	Só baixa o binário bws na versão fixada (não precisa de autenticação)
hermes secrets bitwarden disable	Muda para enabled: false; mantém o token + o id do projeto no lugar

Rotacionar um token expirado ou revogado

Quando o token da conta de máquina expira, é revogado ou a conta é apagada, a inicialização mostra:

Bitwarden Secrets Manager: Bitwarden rejected the machine-account access token (BWS_ACCESS_TOKEN) — it was likely revoked, expired, or belongs to another region.  (...)
Bitwarden Secrets Manager: → Run `hermes secrets bitwarden token` to paste a fresh access token ...

Conserte sem rodar o assistente inteiro de novo:

hermes secrets bitwarden token                     # prompt mascarado
hermes secrets bitwarden token --access-token 0.…  # não interativo

O comando testa o novo token no Bitwarden antes de escrever qualquer coisa — um token rejeitado deixa o seu .env atual intocado. Se der certo, ele guarda o token, limpa os caches de busca e avisa se o projeto configurado não está visível para a nova conta de máquina.

Configuração

Padrões em ~/.hermes/config.yaml:

secrets:
  bitwarden:
    enabled: false
    access_token_env: BWS_ACCESS_TOKEN
    project_id: ""
    server_url: ""
    cache_ttl_seconds: 300
    encrypted_cache:
      enabled: false
      max_stale_seconds: 0
    override_existing: true
    auto_install: true

Chave	Padrão	O que faz
enabled	false	Chave-mestra. Quando é false, o Bitwarden nunca é contatado.
access_token_env	BWS_ACCESS_TOKEN	Nome da variável de ambiente que guarda o token de bootstrap. Mude se você já usa BWS_ACCESS_TOKEN para outra coisa.
project_id	""	UUID do projeto de onde sincronizar.
server_url	""	Região do Bitwarden ou endpoint auto-hospedado. Vazio = padrão do bws (US Cloud, https://vault.bitwarden.com). Use https://vault.bitwarden.eu para a EU Cloud, ou a sua própria URL para auto-hospedado. Repassado ao subprocesso bws como BWS_SERVER_URL.
cache_ttl_seconds	300	Por quanto tempo o resultado de uma busca em processo ou em disco é reaproveitado. Use 0 para desativar o reaproveitamento de cache novo.
encrypted_cache.enabled	false	Guarda a última busca bem-sucedida em um cache criptografado com AES-GCM em ~/.hermes/cache/bws_cache.enc.json.
encrypted_cache.max_stale_seconds	0	Com o cache criptografado ligado, permite usar esse cache só depois de falhas de rede/tempo esgotado, até esta idade. Falhas de autenticação nunca usam segredos velhos. Uma escrita criptografada bem-sucedida remove o cache/bws_cache.json legado em texto puro.
override_existing	true	Quando é true, os valores do Bitwarden sobrescrevem o que já estiver no ambiente (para a rotação no aplicativo web realmente valer). Mude para false se você quiser que o .env / os exports do shell vençam localmente.
auto_install	true	Quando é true, o bws é baixado automaticamente para ~/.hermes/bin/ no primeiro uso.

Modos de falha

O Bitwarden nunca trava a inicialização do Hermes. Se algo der errado, você vê um aviso de uma linha no stderr e o Hermes continua com as credenciais que o .env já tinha:

Sintoma	Causa	Correção
BWS_ACCESS_TOKEN is not set	Ligado na configuração, mas o token foi apagado do .env	Rode de novo hermes secrets bitwarden setup
Bitwarden rejected the machine-account access token … invalid_client	Token revogado, expirado, conta de máquina apagada — ou o token é de outra região (por exemplo, token da UE batendo no endpoint de identidade dos EUA)	Rode hermes secrets bitwarden token para colar um token novo; se for descompasso de região, rode o setup de novo e escolha EU/auto-hospedado (ou defina secrets.bitwarden.server_url)
bws exited 1: invalid access token	Token revogado ou errado	Rode hermes secrets bitwarden token com um token novo
bws timed out	Rede bloqueada ou API do Bitwarden lenta	Confira a conectividade com api.bitwarden.com (ou o seu server_url)
bws binary not available	auto_install: false e o bws não está no PATH	Instale na mão a partir de github.com/bitwarden/sdk-sm/releases ou volte a ligar o auto_install
Checksum mismatch	Download corrompido ou adulterado	Rode de novo, ele tenta outra vez; se persistir, abra uma issue

Os avisos de inicialização agora incluem uma linha de correção com →, dizendo exatamente qual comando resolve a falha.

Notas de segurança

• O token de bootstrap (BWS_ACCESS_TOKEN) é sensível por si só — quem tiver o token consegue ler todo segredo a que a conta de máquina tem acesso. Trate-o como qualquer outra chave de API.
• O Hermes se recusa a deixar o Bitwarden sobrescrever o próprio token de bootstrap, mesmo com override_existing: true. Se você guardar BWS_ACCESS_TOKEN como segredo dentro do projeto, ele é silenciosamente ignorado na hora de aplicar.
• O download do binário bws é verificado contra o checksum SHA-256 publicado no mesmo release do GitHub. Divergência aborta a instalação.
• A versão fixada (bws v2.0.0 na hora em que isto foi escrito) é atualizada por PRs neste repositório — o Hermes não atualiza o bws para a "última" automaticamente, porque o formato dos releases lá em cima pode mudar.

Quando NÃO usar isto

• Instalações pessoais em uma máquina só, em que o ~/.hermes/.env já resolve. Você está trocando uma credencial por outra e acrescentando uma dependência de rede na inicialização.
• Ambientes isolados da rede, que não alcançam api.bitwarden.com.
• CI/CD onde o mecanismo de injeção de segredos já existe (secrets do GitHub Actions, Vault etc.) — escolha um caminho, não dois.

O bom caso de uso aqui é frota de várias máquinas, máquinas de desenvolvimento compartilhadas, VPS de gateway, ou qualquer arranjo em que você queira rotação e revogação centralizadas em várias instalações do Hermes.

---