1Password

Resolva as chaves de API dos provedores a partir do 1Password na inicialização do processo, em vez de guardá-las em texto puro dentro de ~/.hermes/.env. Você mantém as chaves como itens do 1Password e as referencia por op://cofre/item/campo; girar uma credencial vira uma única mudança no 1Password.

Como funciona

1. Você instala a CLI oficial do 1Password (op) e faz a autenticação — com um token de conta de serviço (servidores sem interação) ou com uma sessão interativa/desktop (seu notebook).
2. Você mapeia nomes de variáveis de ambiente para referências op:// em ~/.hermes/config.yaml.
3. Toda vez que o hermes (ou o gateway, ou um job de cron) inicia, depois que ~/.hermes/.env é carregado, o Hermes roda op read para cada referência e coloca os valores resolvidos em os.environ.
4. Por padrão o Hermes sobrescreve valores que já estavam no ambiente, então o 1Password é a fonte da verdade — gire uma credencial uma vez e todo processo do Hermes a pega no próximo início. Mude override_existing: false se preferir que o .env prevaleça.

O Hermes nunca autentica no seu lugar e nunca baixa o op: ele apenas chama a CLI que você já instalou e já confia. Se o op estiver ausente, sua sessão estiver bloqueada ou uma referência estiver errada, o Hermes imprime um aviso de uma linha e continua com as credenciais que o .env já tinha — ele nunca trava a inicialização.

Autenticação

O op aceita dois modos amigáveis a execução não interativa; o Hermes funciona com qualquer um dos dois:

• Contas de serviço (recomendado para servidores/CI): crie uma conta de serviço no 1Password, dê a ela acesso de leitura ao cofre relevante e exporte o token como OP_SERVICE_ACCOUNT_TOKEN em ~/.hermes/.env. O token é a credencial — trate-o como qualquer outro token bearer.
• Sessões desktop / interativas (notebooks): rode op signin (ou habilite a integração com a CLI no aplicativo do 1Password). O Hermes repassa suas variáveis OP_SESSION_* para o processo filho op. A chave de cache do 1Password inclui essas variáveis de sessão, então entrar em outra conta nunca entrega um valor cacheado sob a identidade anterior.

Token de bootstrap

Quando você autentica com um token de conta de serviço, esse token é a credencial de bootstrap de que o Hermes precisa antes de conseguir resolver qualquer referência op://. Ele precisa estar em os.environ de todo processo que resolve segredos — incluindo jobs de cron (kanban.dispatch_in_gateway: false), chamadas em subprocesso, execuções da CLI, agentes launchd do macOS e contêineres Docker — não só o gateway interativo. Há três formas de disponibilizá-lo, em ordem de precedência:

1. Em ~/.hermes/.env (recomendado). O hermes secrets onepassword setup --token <token> escreve o token em ~/.hermes/.env, exatamente como o BWS_ACCESS_TOKEN do Bitwarden. Como load_hermes_dotenv() sempre carrega o .env, o token fica disponível em todo lugar sem nenhuma configuração extra. Essa é a opção confiável mais simples.

2. Em ~/.hermes/.op.env (fora do git). Se você prefere manter o token de conta de serviço fora do .env — por exemplo, para que o .env possa ir para um repositório privado de dotfiles enquanto o token fica fora do controle de versão —, coloque-o em ~/.hermes/.op.env:

   echo 'OP_SERVICE_ACCOUNT_TOKEN=ops_...' > ~/.hermes/.op.env
   chmod 600 ~/.hermes/.op.env

   O Hermes carrega o .op.env automaticamente na inicialização, depois do .env, e nunca sobrescreve um token que já esteja no ambiente. O .op.env está no gitignore, então o token nunca entra em um arquivo commitado.

3. Via EnvironmentFile do systemd (gateway em Linux). Se você roda o gateway sob systemd, dá para injetar o token direto no ambiente do serviço:

   [Service]
   EnvironmentFile=-/home/seuusuario/.hermes/.op.env

   Um token injetado assim tem precedência — o Hermes detecta que OP_SERVICE_ACCOUNT_TOKEN já está definido e pula por completo o carregamento do .op.env.

Se o token só puder ser alcançado por um shell interativo (op signin, exports de OP_SESSION_* no .bashrc etc.), ele não será herdado por jobs de cron nem por subprocessos recém-criados, e esses contextos vão registrar um aviso e recair sobre as credenciais que o .env já tinha. Use uma das três opções acima para qualquer carga de trabalho não interativa.

Configuração inicial

1. Instale o op e faça login

Siga o guia de primeiros passos da CLI do 1Password. Confirme que funciona:

op whoami

2. Habilite a integração

hermes secrets onepassword setup

Isso verifica se o op está no PATH (ou use --binary-path), registra suas configurações de conta/token, checa se há sessão ativa e liga secrets.onepassword.enabled: true. Flags para uso não interativo:

hermes secrets onepassword setup \
  --account my.1password.com \
  --token-env OP_SERVICE_ACCOUNT_TOKEN \
  --token "$OP_SERVICE_ACCOUNT_TOKEN"

3. Mapeie suas credenciais

O formato da referência é op://<cofre>/<item>/<campo>:

hermes secrets onepassword set OPENAI_API_KEY    "op://Private/OpenAI/api key"
hermes secrets onepassword set ANTHROPIC_API_KEY "op://Private/Anthropic/credential"

4. Pré-visualize e confirme

hermes secrets onepassword sync     # simulação: resolve agora e mostra o que seria aplicado
hermes secrets onepassword status   # config + binário + referências + autenticação

Daqui em diante, toda chamada do hermes resolve as referências na inicialização. Você vai ver um resumo de uma linha no stderr na primeira vez que os segredos forem aplicados em um processo.

CLI

Comando	O que faz
hermes secrets onepassword setup	Verifica o op, define conta / variável do token, habilita
hermes secrets onepassword status	Mostra config, binário, autenticação e referências configuradas
hermes secrets onepassword token	Gira o token de conta de serviço: valida com op whoami e guarda no .env
hermes secrets onepassword set ENV_VAR "op://…"	Mapeia uma variável de ambiente para uma referência (guardada limpa + validada)
hermes secrets onepassword remove ENV_VAR	Remove um mapeamento
hermes secrets onepassword sync	Simulação: resolve as referências agora e mostra o que seria aplicado
hermes secrets onepassword sync --apply	Resolve e exporta para o ambiente do shell atual
hermes secrets onepassword disable	Coloca enabled: false; mantém os mapeamentos

op e 1password são aceitos como apelidos de onepassword.

Configuração

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

secrets:
  onepassword:
    enabled: false
    env:
      OPENAI_API_KEY: "op://Private/OpenAI/api key"
      ANTHROPIC_API_KEY: "op://Private/Anthropic/credential"
    account: ""
    service_account_token_env: OP_SERVICE_ACCOUNT_TOKEN
    binary_path: ""
    cache_ttl_seconds: 300
    override_existing: true

Chave	Padrão	O que faz
enabled	false	Interruptor geral. Quando falso, o op nunca é chamado.
env	{}	Mapeamento de nome de variável de ambiente → referência op://cofre/item/campo. Entradas cujo nome não seja um nome válido de variável de ambiente, ou cujo valor não seja uma referência op://, são ignoradas com um aviso.
account	""	Apelido da conta / endereço de login passado como op read --account. Vazio usa a conta padrão do op.
service_account_token_env	OP_SERVICE_ACCOUNT_TOKEN	Variável de ambiente de onde o Hermes lê o token de conta de serviço. O valor é exportado para o processo filho op como OP_SERVICE_ACCOUNT_TOKEN (o nome que o op espera). Deixe a variável sem valor para usar uma sessão desktop/interativa.
binary_path	""	Caminho absoluto do op. Quando definido, é usado tal como está e o PATH não é consultado — fixe este valor para não depender de qualquer op que apareça primeiro no PATH.
cache_ttl_seconds	300	Por quanto tempo os valores resolvidos são reaproveitados (em memória e em disco). Use 0 para desligar as duas camadas de cache — nenhum valor é escrito em disco.
override_existing	true	Quando verdadeiro, os valores resolvidos sobrescrevem o que já estiver no ambiente (para que a rotação tenha efeito). Mude para false para deixar o .env / os exports do shell vencerem; nesse caso essas referências são ignoradas antes de o op ser chamado.

Modos de falha

O 1Password nunca trava a inicialização do Hermes. Se algo der errado, você vê um aviso de uma linha no stderr e o Hermes segue:

Sintoma	Causa	Solução
the op CLI was not found on PATH	op não instalado / fora do PATH	Instale a CLI ou defina secrets.onepassword.binary_path
op read failed for 'op://…': …	Sessão bloqueada, token expirado ou sem acesso ao cofre	Rode op signin, use hermes secrets onepassword token para girar o token de conta de serviço, ou dê acesso à conta de serviço
op read returned an empty value for 'op://…'	O campo referenciado existe mas está vazio	Corrija o item/campo no 1Password (um valor vazio nunca é aplicado — sua variável de ambiente atual fica intacta)
… is not an op:// secret reference	O valor de um mapeamento não é uma referência op://	Defina de novo, na forma correta op://cofre/item/campo
op read timed out	Rede bloqueada ou 1Password lento	Verifique a conectividade / a integração com o aplicativo desktop

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

Cache

Buscas bem-sucedidas e completas são cacheadas em memória e em disco, em <hermes_home>/cache/op_cache.json (escrito de forma atômica, modo 0600), para que chamadas curtas e seguidas do hermes não precisem chamar o op de novo para cada referência. O cache:

• guarda apenas os valores dos segredos resolvidos — nunca o token de conta de serviço nem qualquer material bruto de autenticação (a autenticação entra na chave do cache só como impressão digital);
• é invalidado quando o token, a conta, as variáveis OP_SESSION_* ou o conjunto de referências mudam;
• não é escrito quando a busca teve algum erro em qualquer referência, para que uma falha momentânea de autenticação não fique congelada durante o TTL;
• fica totalmente desligado — leitura e escrita — com cache_ttl_seconds: 0.

Notas de segurança

• Um token de conta de serviço do 1Password consegue ler todo segredo a que a conta tem acesso. Guarde-o em ~/.hermes/.env (não em config.yaml) e revogue + gere outro pelo 1Password se ele vazar.
• O Hermes se recusa a deixar um valor resolvido sobrescrever a própria variável do token, mesmo com override_existing: true.
• O processo filho op recebe um ambiente mínimo, com lista de permissão (variáveis de autenticação/sessão + PATH/HOME), e não uma cópia de todo o os.environ, então as credenciais de provedor carregadas depois do dotenv não são todas herdadas pelo filho.
• As referências são validadas para começar com op://, e a referência é passada depois de um terminador de opções --, para que um valor malicioso não possa ser interpretado como uma flag do op.

Quando NÃO usar isto

• Configurações pessoais em uma máquina só, em que ~/.hermes/.env já resolve.
• Ambientes isolados da rede que não conseguem alcançar o 1Password.
• CI/CD onde já existe um mecanismo de injeção de segredos — escolha um caminho, não dois.

O bom caso de uso são frotas de várias máquinas, máquinas de desenvolvimento compartilhadas, VPSes de gateway ou qualquer lugar onde você queira rotação e revogação centralizadas em várias instalações do Hermes.

---