# Ciclo de credenciais e execução precisam de responsáveis distintos

Um gerenciador de segredos deve decidir qual credencial existe, quando ela expira e como deixa de funcionar. Um gateway no desktop deve decidir se este processo pode executar esta ação agora, executar a ação sem entregar a credencial ao processo e registrar o que aconteceu. Juntar essas tarefas parece mais simples até a primeira rotação, revogação ou investigação perguntar qual componente estava realmente no comando.

A fronteira depende de quem possui a credencial no momento do uso, não de onde ela fica armazenada. O HashiCorp Vault ou um fluxo apoiado no 1Password pode continuar como autoridade do ciclo de vida enquanto um gateway controla a execução, mas somente se a passagem preservar o estado e a identidade do ciclo sem transformar o gateway em um cache sem rastreamento. Se o gateway copiar um valor, esquecer seu lease e continuar a usá-lo, o diagrama terá duas caixas, mas o sistema terá dois gerenciadores de segredos.

Esse modelo compensa o trabalho adicional quando agentes autônomos podem alcançar APIs de produção ou destinos SSH. Esses agentes precisam de ações limitadas e controle humano. Não precisam de outra maneira de ler credenciais.

## A fronteira fica antes da ação autenticada

O sistema de ciclo de vida é responsável pela criação, rotação, expiração e revogação de credenciais; o gateway de execução é responsável por liberar cada ação autenticada. Essa frase é o teste da arquitetura. Cada campo, cache, nova tentativa e entrada de log deve ter um único lado capaz de responder por ele.

Responsabilidade pelo ciclo de vida significa mais do que guardar uma string criptografada. Para uma conta dinâmica de banco de dados, ela inclui o papel que cria a conta, o ID do lease, o TTL, as regras de renovação e a operação que apaga ou desativa a conta. Para um token de API estático, ela inclui o emissor, a geração atual, a hora de ativação, qualquer período de sobreposição e uma prova de que a geração antiga parou de funcionar. Um gerenciador de senhas pode guardar o registro oficial, mas a API remota ainda decide se aceita o token.

A responsabilidade pela execução começa depois que um chamador pede um efeito como `GET /billing/invoices`, `POST /deployments` ou um comando SSH em um host identificado. O gateway autentica o chamador, verifica a aprovação local, resolve a credencial autorizada, injeta-a no protocolo de saída e devolve apenas o resultado. Ele não deve oferecer uma ação genérica `read secret` ao agente. Isso faria a execução voltar a ser distribuição de segredos.

Uma interface clara, portanto, informa uma ação e uma referência de credencial, não um valor de credencial. Ela também informa a geração esperada, para que um pedido atrasado não atravesse uma rotação silenciosamente. Um envelope de solicitação útil tem esta forma:

```json
{
  "action_id": "01J...",
  "credential_ref": "vault:database/creds/agent-readonly",
  "expected_generation": "lease:database/creds/agent-readonly/2f6a...",
  "purpose": "read migration status",
  "target": "db-admin.internal",
  "caller": {
    "session_id": "sess_7f2...",
    "process_authority": "signed:TEAMID.example.agent"
  }
}
```

O gateway pode obter o valor subjacente, porque algum componente precisa colocar bytes em um cabeçalho Authorization ou em uma negociação SSH. A condição é que ele obtenha esse valor dentro do caminho de execução confiável, mantenha-o fora de argumentos, variáveis de ambiente, arquivos, resultados de ferramentas e mensagens de erro visíveis ao agente, e depois o descarte de acordo com uma regra de cache documentada. Manter o agente sem segredos não significa que nenhum componente processará texto simples.

## A autoridade do ciclo cria e retira credenciais

Use o Vault como responsável pelo ciclo quando seu mecanismo de segredos puder criar e revogar a credencial no sistema de destino. Use um fluxo apoiado no 1Password como responsável por uma credencial estática apenas quando esse fluxo também atualizar o emissor, registrar a nova geração e retirar a antiga. Guardar somente o valor mais recente é gerenciamento de inventário, não rotação.

A documentação da HashiCorp sobre leases do Vault deixa o contrato especialmente explícito. Todo segredo dinâmico recebe um lease com uma duração e um indicador de renovação. O Vault promete que os dados serão válidos durante esse período, mas depois da expiração o consumidor não pode mais presumir que a credencial funciona. Revogar um lease invalida o segredo e impede novas renovações; nos mecanismos compatíveis, o Vault também faz a limpeza subjacente, como apagar uma credencial de nuvem ou um usuário de banco de dados gerado.

Esse comportamento torna o Vault o responsável natural pelas credenciais dinâmicas compatíveis. O gateway deve pedir ou receber um lease, respeitar o TTL retornado e parar de usá-lo antes do fim. Ele nunca deve inventar uma duração local maior. A HashiCorp também avisa que o incremento solicitado numa renovação é apenas uma sugestão e que os clientes devem examinar a resposta. Um gateway que pede mais uma hora e presume que a recebeu já quebrou a responsabilidade pelo ciclo.

O mecanismo KV do Vault é diferente. A documentação do Vault diz que o KV não emite leases, mesmo quando uma resposta apresenta uma duração. Colocar um token de API no KV não o torna dinâmico, e apagar uma versão antiga do KV não necessariamente revoga o token no emissor. O fluxo de rotação precisa chamar o provedor, verificar o substituto, atualizar o registro oficial e desativar o token antigo.

A mesma ressalva vale para o 1Password. Sua documentação de CLI descreve referências de segredos e comandos como `op run`, `op read` e `op inject`. Esses mecanismos recuperam um segredo armazenado durante a execução. Sozinhos, eles não fazem a rotação de uma chave de API genérica de terceiros no emissor. Uma equipe ainda pode manter o registro oficial no 1Password, mas a automação ao redor dele deve cuidar da atualização remota e da retirada.

Não atribua a responsabilidade pelo ciclo conforme a categoria do fornecedor. Atribua conforme o controle comprovado sobre o emissor e uma mudança de geração que possa ser observada.

## Uma passagem segura leva referência e lease

O gateway precisa de uma referência que possa resolver, um limite de validade e um caminho de revogação. Passar apenas uma referência resolve o nome, mas perde o tempo. Passar apenas uma data de expiração perde a autoridade que pode revogar de fato. Passar apenas o valor secreto perde os dois.

Para segredos dinâmicos do Vault, o identificador natural de geração é o ID do lease. A resposta de `vault read database/creds/my-role` inclui `lease_id`, `lease_duration`, `lease_renewable`, `username` e `password`. O gateway precisa vincular os bytes da credencial e esses metadados em um só objeto. Não deve guardar a senha em um cache e o lease em outro que possa ficar defasado.

Para um registro estático no 1Password, crie um marcador de geração imutável no fluxo de rotação. Ele pode ser um identificador de versão exposto pela integração escolhida ou um ID de evento de rotação armazenado com a referência. Não use um nome mutável como `prod-api-key` para representar a geração. O nome diz ao gateway onde resolver, mas não prova qual valor ele recebeu.

O contrato de passagem deve incluir estas propriedades:

- `credential_ref` identifica a origem sem conter material secreto.
- `generation` muda sempre que a credencial utilizável muda.
- `not_after` dá ao gateway um horário local definitivo para parar, quando ele existe.
- `revocation_ref` informa às ferramentas de resposta qual objeto revogar ou retirar.
- `issued_for` vincula a credencial ao papel, destino e ambiente pretendidos.

Uma resposta do gateway deve repetir as partes que não são secretas, permitindo que o chamador e a estrutura de auditoria relacionem um efeito sem conhecer a credencial:

```json
{
  "action_id": "01J...",
  "status": 200,
  "credential_ref": "vault:database/creds/agent-readonly",
  "generation": "lease:database/creds/agent-readonly/2f6a...",
  "executed_at": "2026-07-27T14:03:12Z",
  "result_digest": "sha256:9b0..."
}
```

Esse contrato também expõe uma verdade incômoda: um gateway no desktop precisa de uma identidade de máquina própria para recuperar dados do sistema de ciclo de vida. Essa credencial inicial também tem um ciclo. Um token do Vault deve ter uma política limitada e seu próprio TTL ou comportamento de renovação. Um token de conta de serviço do 1Password deve alcançar apenas os cofres necessários. Esconder o token inicial num arquivo de configuração local apenas desloca o problema original um nível abaixo.

## A expiração deve vencer caches e novas tentativas

A expiração sobrevive à passagem somente quando todo caminho de execução compara a hora atual com o limite retornado pela autoridade do ciclo. O gateway deve recusar uma nova ação quando o tempo restante não cobrir a resolução, a aprovação, a conexão, a execução e uma pequena margem para o relógio.

Suponha que o Vault emita uma credencial de banco de dados por dez minutos. Um agente começa uma exportação no nono minuto, o usuário passa quarenta segundos lendo um cartão de aprovação e o gateway tenta de novo duas vezes depois de uma falha de rede. Um cache que verificou o TTL apenas ao buscar a credencial pode iniciar a última tentativa depois da expiração. O destino devolve um erro de autenticação, mas o registro de auditoria pode classificá-lo incorretamente como falha de rede ou recusa do usuário.

Defina o prazo utilizável uma vez, a partir dos metadados oficiais:

```text
usable_until = min(authority_not_after, fetched_at + local_cache_cap)
latest_start = usable_until - approval_budget - connect_budget - clock_margin
```

Esses orçamentos são escolhas operacionais, não extensões da vida da credencial. Se `now` for posterior a `latest_start`, obtenha uma nova geração e mostre uma nova aprovação caso a ação aprovada mude de modo relevante. Nunca renove um lease do Vault apenas para salvar uma solicitação que ficou numa fila local. A renovação é uma decisão do ciclo e pode aumentar o período de exposição.

As novas tentativas precisam da mesma disciplina. Uma tentativa pode reutilizar uma credencial apenas quando a geração ainda corresponder, a credencial permanecer no prazo utilizável e a operação remota puder ser repetida com segurança. Idempotência HTTP e validade da credencial são verificações diferentes. Um token válido não torna inofensivo um `POST` duplicado.

Para credenciais estáticas sem expiração fornecida pelo emissor, use um limite local de cache para reduzir a vida de cópias antigas, mas chame-o de política de cache, não de expiração. O fluxo do ciclo ainda precisa de uma notificação de geração ou de uma nova resolução forçada após a rotação. Caso contrário, o gateway pode continuar usando um token antigo ainda válido durante a sobreposição e fazer o teste de retirada parecer bem-sucedido até o provedor finalmente desativá-lo.

## A revogação é um evento de ponta a ponta

A revogação só funciona quando a autoridade do ciclo desativa a credencial no emissor e o gateway impede todo uso futuro da geração armazenada em cache. Limpar apenas um lado é incompleto.

O Vault oferece aos operadores um mecanismo concreto. `vault lease revoke` invalida um lease, e a revogação por prefixo pode invalidar leases sob um caminho. A documentação de comandos da HashiCorp também distingue a revogação normal da remoção forçada. A remoção forçada pode fazer o Vault esquecer um lease mesmo quando o mecanismo de segredos não conseguiu revogá-lo, deixando o Vault fora de sincronia com o destino. Trate esse aviso como um incidente, não como mensagem de limpeza bem-sucedida.

Um gateway no desktop deve receber um sinal de revogação quando o sistema de ciclo puder enviá-lo, mas também precisa de uma defesa que consulte o estado atual. Antes de um uso sensível, ele pode validar a geração de novo ou resolvê-la outra vez. Para leases curtos do Vault, um TTL rígido e um cache breve podem bastar. Para um token de API estático, o coordenador de rotação deve invalidar o cache do gateway durante a troca e depois testar diretamente o token retirado num endpoint sem efeito.

Ações que já estão em execução precisam de uma regra explícita. A revogação pode impedir de forma confiável ações que não começaram. Ela talvez não desfaça uma solicitação já aceita por uma API remota, uma transação de banco de dados já confirmada ou um comando SSH já entregue ao shell. O gateway deve marcar o estado como `authorized`, `dispatched`, `acknowledged` ou `unknown`, em vez de afirmar que a revogação apagou o efeito.

Teste o caminho completo mantendo a geração antiga numa ferramenta controlada:

1. Execute uma leitura sem efeito pelo gateway e registre a geração.
2. Revogue o lease ou faça a rotação da credencial estática e desative-a no emissor.
3. Tente a mesma ação com um gateway cujo cache continua quente.
4. Tente usar diretamente a credencial retirada a partir da ferramenta.
5. Confirme as duas falhas e relacione-as aos registros de ciclo e execução.

Se o terceiro passo funcionar, o gateway ignorou a revogação. Se o quarto funcionar, o fluxo de ciclo não revogou no emissor. Se os dois falharem, mas os registros não identificarem a mesma geração, a equipe de resposta ainda não poderá provar o que aconteceu.

## A atribuição precisa da identidade do emissor e do chamador

Os logs do ciclo respondem quem criou, renovou, fez a rotação ou revogou uma credencial. Os logs do gateway respondem qual processo local pediu qual ação, quem a aprovou, qual destino a recebeu e qual resultado voltou. Nenhum deles substitui o outro.

Credenciais dinâmicas melhoram a atribuição no emissor quando cada lease produz uma identidade remota diferente. A documentação do mecanismo de segredos de banco de dados da HashiCorp observa que nomes de usuário únicos e gerados permitem relacionar o acesso a uma instância específica de serviço. Isso ajuda, mas o usuário do banco ainda identifica a identidade alugada do gateway, não necessariamente o processo de agente que pediu a consulta.

O gateway, portanto, precisa de uma identidade de sessão estável e de uma identidade de processo confiável. Um PID sozinho é fraco, pois sistemas operacionais reutilizam PIDs e processos podem iniciar filhos. Registre a identidade do executável disponível na plataforma, sua autoridade de assinatura quando houver, o processo pai, o início e o fim da sessão e um ID de sessão impossível de adivinhar. Vincule cada registro de ação a essa sessão.

O campo de junção é a geração da credencial. Coloque o ID de lease do Vault ou o ID de evento de rotação estático tanto no registro do ciclo quanto no registro da ação do gateway. Registre também o ID da solicitação remota quando a API devolver um. Durante um incidente, os investigadores devem conseguir seguir esta cadeia:

```text
agent session -> gateway action -> credential generation -> issuer event -> remote request
```

Não coloque valores secretos, cabeçalhos Authorization, chaves privadas nem blocos de ambiente resolvidos nesses logs. Ocultar depois do registro não é confiável, pois exceções, despejos de depuração e exportadores de rastreamento podem copiar os dados primeiro. Construa registros estruturados a partir de uma lista permitida de campos seguros.

A atribuição também falha quando todas as ações compartilham uma conta de serviço de longa duração e nenhum registro do gateway sobrevive. A rotação reduz a vida dessa conta, mas não identifica o chamador. No sentido oposto, logs de processo perfeitos não provam qual geração chegou ao destino se o gateway omitir o lease ou a versão. Preserve as duas dimensões.

## A injeção no ambiente atravessa a fronteira

Um fluxo que injeta um segredo no ambiente de um agente dá a posse ao agente, então o gateway deixa de controlar cada uso. Essa distinção importa mais nos padrões de CLI do 1Password, porque a facilidade de recuperação pode parecer controle de execução.

A documentação do 1Password diz que `op run` inicia um subprocesso com segredos fornecidos como variáveis de ambiente. Pode ser uma forma razoável de manter texto simples fora de um arquivo `.env` versionado, mas o processo filho pode ler a variável, imprimi-la, passá-la a outro processo ou usá-la numa solicitação não aprovada. `op inject` resolve referências em um fluxo de configuração, e `op read` devolve um valor resolvido ao chamador. Nenhum desses caminhos equivale a um gateway que mantém o segredo fora do agente.

Para scripts operados por pessoas que precisam do comportamento amplo de um SDK nativo, a injeção no ambiente pode ser aceitável. Para um agente autônomo cujas ações de rede e SSH exigem controle em cada uso, ela destrói a fronteira desejada. Dê ao gateway a identidade restrita de recuperação e exponha ferramentas orientadas a ações para o agente.

A credencial inicial ainda merece análise. O 1Password recomenda contas de serviço para aplicar o menor privilégio e permite restringir o acesso a cofres específicos. Isso reduz o que o gateway pode recuperar. Não restringe o que ele pode fazer depois da recuperação, portanto sua superfície de ações, aprovações e validação dos destinos de saída continuam necessárias.

Evite uma saída popular: resolver o segredo num wrapper, chamar o gateway com a credencial como parâmetro e prometer que o gateway irá ocultá-la. O agente ou wrapper já teve o valor, o histórico do shell e a inspeção de processos podem expô-lo, e o gateway não pode provar que não houve um segundo uso. Passe a referência pela fronteira e resolva-a dentro do componente que executa.

## A aprovação é independente da rotação

Uma credencial recém-rotacionada ainda pode autorizar uma ação ruim, e uma ação cuidadosamente aprovada ainda pode usar uma credencial antiga. Rotação e aprovação reduzem riscos diferentes, então nenhuma deve substituir silenciosamente a outra.

A autoridade do ciclo responde: "Esta geração de credencial é válida?" O gateway responde: "Este chamador pode causar este efeito agora?" O serviço remoto responde: "Esta identidade autenticada tem permissão?" Mantenha as três respostas visíveis. Um cartão verde de aprovação não deve sugerir que a credencial está atualizada sem que o gateway tenha verificado. Um lease vigente não deve ignorar a aprovação humana exigida para uma chamada destrutiva.

A reutilização da aprovação precisa de um escopo definido. Se o gateway aprovar uma sessão de agente, vincule essa aprovação à sessão do processo e encerre-a quando o processo sair ou o usuário a revogar. Se uma credencial exigir aprovação em cada chamada, a rotação deve preservar a exigência na nova geração. Um novo valor não deve devolver uma credencial sensível a uma configuração padrão mais fraca.

O texto da aprovação deve descrever a ação, o destino e o chamador, não o segredo. "Permitir que o processo assinado X execute `POST /deployments` em produção" oferece algo que uma pessoa pode avaliar. "Permitir uso da chave de API prod-3" obriga a reconstruir a intenção a partir de nomes de inventário e acostuma as pessoas a aprovar avisos opacos.

O Sallyport implementa essa metade da execução para ações HTTP API e SSH no macOS: os agentes se conectam pelo shim MCP, as credenciais ficam no cofre criptografado dentro do processo e o aplicativo executa a ação. Seus controles fixos separam o cofre bloqueado, a aprovação da sessão de processo e a aprovação opcional em cada uso; esse modelo não elimina a necessidade de uma autoridade externa do ciclo quando outro sistema cria ou rotaciona a credencial.

## Duas rotações criam duas autoridades aparentes

Não deixe o sistema de ciclo e o gateway fazerem a rotação da mesma credencial de forma independente. Algumas equipes chamam isso de defesa em profundidade, mas dois escritores criam gerações ambíguas, reversões pouco confiáveis e corridas de revogação.

Imagine um provedor estático que permita duas chaves de API ativas. O fluxo do 1Password cria a chave B, testa-a e atualiza o item oficial enquanto a chave A continua ativa por um breve período de troca. Ao mesmo tempo, o agendador local do gateway cria a chave C porque sua cópia de A atingiu uma idade configurada. Alguns processos resolvem B, o cache quente ainda guarda A e o gateway começa a usar C. Desativar A prova muito pouco, porque ninguém sabe se B ou C deve sobreviver.

Um coordenador deve ser responsável pela máquina de estados de rotação. Para um segredo dinâmico do Vault, o próprio Vault coordena por meio de papéis e leases; o gateway consome leases e não rotaciona a conta remota. Para um registro estático administrado pelo 1Password, o trabalho de rotação coordena o provedor e o item armazenado; o gateway observa mudanças de geração e invalida o cache. A criptografia local do gateway protege uma cópia armazenada, mas criptografar o armazenamento novamente não é fazer a rotação da credencial no emissor.

Uma rotação estática funcional tem estados explícitos em vez de um único marcador `rotated`:

```text
prepared -> activated -> distributed -> old_disabled -> verified
                |             |
                +-> rollback <-+
```

`prepared` significa que o emissor criou uma geração candidata. `activated` significa que uma solicitação autenticada e sem efeito funcionou com ela. `distributed` significa que a referência oficial resolve para a candidata e os gateways reconhecem a nova geração. `old_disabled` significa que o emissor rejeita a anterior. `verified` significa que um gateway com cache quente e uma ferramenta direta falham com o valor antigo. Mantenha a reversão possível apenas enquanto a geração anterior permanecer ativa de propósito.

O gateway deve receber mudanças de estado contendo referências e IDs de geração, nunca os dois valores secretos. Um evento de invalidação pode informar `credential_ref`, `old_generation`, `new_generation` e `effective_at`. Ao recebê-lo, o gateway remove a entrada antiga do cache, cancela ações em fila vinculadas a ela e resolve novamente quando a próxima ação aprovada começar. Se o evento nunca chegar, o limite de cache e a verificação da geração ainda devem convergir para o valor oficial.

A reversão exige o mesmo rigor. Apontar um item do 1Password de volta para a chave A não funciona depois de o provedor desativar A. Emitir um novo valor sob o nome visível antigo também não restaura a geração anterior. O coordenador deve criar ou reativar somente o que o provedor oferece, atribuir um novo ID de geração e repetir as fases normais de distribuição e verificação.

Mantenha o registro de responsabilidades curto o bastante para ser lido durante um incidente. Para cada referência de credencial, indique um coordenador de rotação, um emissor, uma política de cache do gateway, um comando de revogação e uma pessoa ou serviço autorizado a iniciar uma retirada de emergência. Se duas linhas afirmarem que podem criar a próxima geração, pare. Isso não é redundância, é uma corrida com material secreto.

## Teste a junção em vez de cada caixa

Um teste bem-sucedido do Vault e outro do gateway não provam que a passagem funciona. Teste na fronteira caches antigos, gerações sobrepostas, aprovações atrasadas, revogações que falham, reinícios de processo e campos de junção ausentes.

Use uma identidade de destino descartável e execute esta matriz de aceitação antes da produção:

| Condição | Decisão esperada do gateway | Evidência exigida |
| --- | --- | --- |
| Geração atual, TTL suficiente | Executar | Sessão, ação, geração, solicitação remota |
| Geração atual, TTL curto demais | Resolver de novo ou negar | TTL retornado e decisão local de tempo |
| Registro rotacionado, cache antigo quente | Rejeitar geração antiga | Invalidação de cache e rejeição do emissor |
| Lease do Vault revogado | Negar sem tentar o lease antigo | Registro de revogação e falha de autenticação no destino |
| Aprovação expira durante a espera | Negar ou pedir nova aprovação | Prazo da aprovação e ausência de envio |
| Gateway reinicia depois da aprovação | Exigir a decisão de sessão configurada | Nova identidade de sessão e fim da anterior |
| Revogação no emissor falha | Marcar incidente e preservar evidência | Erro do provedor e geração não resolvida |
| Destino aceita token retirado | Falhar o teste do ciclo | Resultado da sondagem direta e decisão de reversão |

Execute a matriz nos mesmos caminhos que os agentes usarão. Um mock que devolve `401` quando solicitado não revela se um plugin real de banco removeu um usuário, se um provedor permite chaves sobrepostas nem se uma conexão SSH continua ativa depois da revogação da credencial.

Defina critérios explícitos de aprovação. Nenhuma ação começa depois de `not_after`. Uma geração revogada ou retirada falha até por um cache quente. Cada registro de execução se junta a uma geração do ciclo sem material secreto. Uma falha de revogação no emissor impede a declaração de retirada bem-sucedida. Um registro de aprovação identifica uma sessão de processo e expira de acordo com o controle configurado.

A fronteira cumpre seu papel quando as falhas ficam contidas. O Vault ou o fluxo de rotação do 1Password pode substituir credenciais sem ensinar valores secretos ao agente. O gateway pode mudar o comportamento de aprovação sem se tornar emissor. A equipe de resposta pode revogar uma geração, parar uma sessão e ver quais efeitos remotos talvez já tenham ocorrido. Se o teste da junção não provar essas três operações separadamente, corrija o contrato antes de adicionar outro sistema de segredos.