Timeouts de aprovação impedem que aprovações antigas executem novas ações

Uma aprovação é uma autorização para uma ação proposta em um determinado momento. Ela não é um cupom que um agente pode resgatar quando for conveniente.

Isso parece óbvio até que um agente coloque na fila uma implantação em produção, uma exclusão ou um comando SSH enquanto uma pessoa está ocupada. O revisor vê uma solicitação razoável, aprova e então o mundo muda. Uma build mais nova vence na fila. O conjunto de destinos muda. Alguém aponta um alias de ambiente para outro lugar. Um incidente altera as condições de segurança. Se a aprovação antiga ainda puder ser executada, o sistema transformou uma decisão sobre o estado de ontem em autoridade sobre o estado de hoje.

Os timeouts de aprovação resolvem apenas uma parte desse problema, mas é uma parte que as equipes costumam deixar aberta. Defina uma expiração curta e rígida para aprovações de ações cujo significado possa mudar. Depois, vincule a aprovação à ação exata proposta e verifique novamente, antes da execução, as condições que podem mudar. Faça as duas coisas. Cada controle isolado deixa uma brecha.

Toda aprovação tem um limite de validade

Toda aprovação perde tempo enquanto espera para ser executada. Quanto mais o destino puder mudar, menor deve ser esse limite.

Uma solicitação para reiniciar um worker descartável de preview pode continuar válida por meia hora. Uma solicitação para promover uma release para produção pode ficar desatualizada em poucos minutos se outra release, um rollback ou a resposta a um incidente puderem mudar o próximo passo correto. Um comando que exclui um snapshot de backup identificado deve expirar rapidamente quando a lista de snapshots estiver passando por um trabalho ativo de retenção. Um comando SSH contra um alias de host mutável merece a janela mais curta de todas.

O padrão ruim é escolher um número grande porque isso evita incomodar as pessoas. Oito horas parece conveniente. Na prática, permite que aprovações se acumulem durante o almoço, durante a noite ou na troca de turno. Um revisor pode aprovar uma implantação às 10:02, esquecê-la e descobrir às 16:40 que um estado muito mais recente da fila consumiu seu clique. A interface de aprovação parecia cuidadosa. O caminho de execução foi descuidado.

Defina a janela fazendo uma pergunta mais precisa: por quanto tempo exatamente essa ação proposta continuará sendo uma descrição correta do que vai acontecer?

Para a maioria das equipes, uma política inicial útil se parece com esta:

• Implantação ou rollback em produção: 5 a 15 minutos.
• Exclusão destrutiva: 2 a 10 minutos, dependendo de o conjunto de objetos ser fixo.
• Comando SSH com efeitos de escrita: 2 a 5 minutos.
• Inspeção SSH somente leitura: nenhuma aprovação por ação, ou uma janela maior se o ambiente ainda exigir uma.
• Mudanças rotineiras fora de produção com uma build fixada: 15 a 30 minutos.

Esses são padrões operacionais, não constantes universais. Uma expiração de cinco minutos é longa demais se um loop de automação puder alterar o destino a cada poucos segundos. Ela é curta demais se um revisor de plantão precisar reunir evidências antes. A resposta não é aumentar o prazo silenciosamente para sempre. Dê ao revisor o contexto necessário e facilite a regeneração da solicitação a partir do estado atual.

O GitHub Actions faz uma distinção importante aqui: um job de implantação pode esperar uma revisão obrigatória e, depois de aprovado, um job pendente pode prosseguir e obter acesso aos segredos do ambiente. O GitHub também documenta que um job não aprovado pode falhar depois de 30 dias. Isso impede que as filas durem para sempre, mas 30 dias não é uma janela de validade útil para uma aprovação sobre uma implantação em mudança. Seu próprio gate deve tratar a idade da aprovação como parte da autorização, não como simples manutenção da fila.

Vincule a decisão à ação, não a um rótulo

Uma aprovação deve abranger dados concretos da ação. «Aprovar implantação em produção» é um rótulo. Ele quase não informa ao revisor qual objeto será executado.

Para uma implantação, vincule a decisão ao digest imutável do artefato ou ao identificador do commit, ao destino, ao plano de migração se houver um, à revisão da configuração e à operação de release. Para uma exclusão, vincule-a a uma lista imutável de objetos ou a um snapshot do resultado da consulta, além do modo de exclusão. Para SSH, vincule-a à identidade verificada do host, ao usuário, ao modelo de comando, aos argumentos expandidos, ao diretório de trabalho quando relevante e a uma descrição limitada dos arquivos de entrada.

Esta é a distinção que as equipes mais confundem:

• Aprovação de uma intenção significa que o revisor concorda com um objetivo amplo, como «remover previews obsoletos».
• Aprovação de uma ação significa que o revisor concorda que este executor exclua estes identificadores de objetos, com este comando, antes deste prazo.

A aprovação de intenção tem seu lugar no gerenciamento de mudanças. Ela não substitui a aprovação da execução quando um agente pode agir em um sistema ativo. Se você aprova uma intenção e depois permite que o agente resolva os destinos mais tarde, delegou ao agente a parte mais importante da decisão.

O OWASP Transaction Authorization Cheat Sheet destaca isso em outro contexto. O documento diz que a pessoa que autoriza uma transação precisa identificar e reconhecer os dados significativos da transação, e alerta que alterar dados depois da autorização cria uma falha de time-of-check to time-of-use. O exemplo é financeiro, mas a regra se aplica diretamente: os dados da aprovação precisam estar protegidos contra alterações, e uma mudança nos dados deve invalidar a autorização existente.

Um digest dá ao executor algo preciso para comparar. Não faça hash de um resumo vago em linguagem natural e considere o trabalho concluído. Normalize os campos que controlam o efeito, serialize-os de forma determinística e depois calcule o hash dessa forma canônica.

{
  "request_id": "appr_01JX...",
  "action_type": "deploy",
  "action_digest": "sha256:8b1d...",
  "summary": {
    "artifact": "registry.example/app@sha256:4fa2...",
    "environment": "production",
    "operation": "promote",
    "config_revision": "7c0e...",
    "migration": "none"
  },
  "issued_at": "2026-07-22T14:03:00Z",
  "expires_at": "2026-07-22T14:13:00Z",
  "status": "pending"
}

O summary é para a pessoa. O action_digest é para o executor. Mantenha os dois. As pessoas precisam ver fatos úteis; os serviços precisam de uma verificação de igualdade exata. Se o agente alterar um único campo vinculado, deverá enviar uma nova solicitação e obter uma nova decisão.

Expiração e invalidação resolvem falhas diferentes

Um prazo impede que aprovações antigas permaneçam pendentes. A invalidação remove uma aprovação assim que fatos relevantes mudam. Você precisa das duas coisas porque esperar o timer terminar é descuidado quando o sistema já sabe que a solicitação não corresponde mais à realidade.

Invalide uma aprovação pendente quando o digest da ação mudar. Essa regra é obrigatória. Invalide também quando mudar uma dependência que afete o significado: a revisão de ambiente pretendida de uma implantação, o conjunto selecionado para exclusão, uma chave de host, o responsável por um lock de release ou o estado de um ticket de mudança obrigatório.

Não invalide a cada evento irrelevante. Se qualquer linha de log, commit sem relação ou mudança inofensiva em uma métrica cancelar uma aprovação, os revisores aprenderão que as solicitações não são confiáveis e começarão a aprová-las sem analisar. A regra deve acompanhar fatos que alterem o efeito solicitado ou as condições de segurança.

Use três estados, não dois:

1. pending significa que a solicitação exata ainda pode ser aprovada antes do prazo.
2. approved significa que um revisor a aprovou, mas o executor ainda não a consumiu.
3. consumed significa que a execução reivindicou a aprovação exatamente uma vez.

Adicione estados finais para expired, invalidated, rejected e failed. Uma solicitação rejeitada não deve voltar a ser pendente porque um agente repetiu uma chamada de rede. Uma execução com falha não deve reutilizar silenciosamente a mesma aprovação, a menos que você consiga provar que a ação não começou e que nenhum estado relevante mudou. Na maioria dos sistemas de ação, é mais seguro e mais fácil de explicar pedir uma nova aprovação ao agente.

O executor deve fazer estas verificações em uma única transação ou em uma operação atômica de compare-and-set:

if now >= expires_at: reject as expired
if status != approved: reject as unavailable
if stored_digest != supplied_digest: reject as changed
if live_preconditions fail: reject as stale
atomically change status from approved to consumed
execute the action

Não marque a aprovação como consumida depois que a ação começar. Dois workers podem competir, ambos observar approved e ambos executar. Consuma primeiro com uma transição de estado atômica e só então registre que a execução começou. Se o processo morrer depois do consumo, trate o resultado como desconhecido até que o executor consiga determinar se alcançou o destino. Isso é inconveniente. Trabalho destrutivo duplicado é pior.

As aprovações de implantação devem acompanhar o artefato

Uma solicitação de implantação fica desatualizada quando seu artefato, destino, plano de release ou posição na fila muda. Nomes de branches e tags móveis não bastam.

O prompt da implantação deve identificar um artefato imutável. Pode ser um digest de imagem, o hash de um pacote de release assinado ou um registro imutável de build. Ele também deve informar ao revisor se o executor executará migrações de banco de dados, alterará a configuração de recursos, reiniciará instâncias ou substituirá uma implantação anterior. Esses detalhes afetam a aprovação. Escondê-los atrás de um botão genérico de «implantar» incentiva aprovações automáticas e sem análise.

Um contrato sólido de aprovação de implantação inclui:

• O identificador imutável da build e a revisão de origem.
• O ambiente de destino exato e a identidade da conta ou do cluster.
• A operação de release, como promover, fazer rollback ou reimplantar.
• As revisões de configuração e migração que serão aplicadas.
• Um token de concorrência ou uma geração de implantação.

O token de concorrência importa quando uma mudança posterior substitui uma solicitação anterior. Suponha que a build A espere aprovação. A build B termina, passa nas verificações e se torna a release que você pretende enviar. Se a solicitação da build A continuar válida, um revisor pode liberar acidentalmente a build antiga. Quando a build B entrar na mesma faixa de release, invalide a aprovação pendente da build A. Não dependa de revisores para perceber timestamps em uma fila movimentada.

A documentação de implantação do GitHub separa a proteção do ambiente da concorrência do workflow. Os controles de concorrência podem cancelar trabalho pendente em um grupo, enquanto a aprovação do ambiente controla se um job pode prosseguir. Essa separação é útil: uma política de fila pode decidir qual execução é a atual, enquanto um gate de aprovação pode decidir se essa execução exata pode ser executada. Combiná-los sem cuidado produz a falha clássica em que a pessoa certa aprova a execução errada.

O executor precisa verificar tudo novamente antes de implantar. Um preflight prático pode confirmar que o artefato solicitado ainda existe, que o ambiente ainda aponta para a identidade de destino esperada, que nenhuma release mais nova ocupa a faixa e que o plano de migração continua correspondendo ao digest aprovado. Se qualquer verificação falhar, marque a solicitação como invalidada e mostre ao revisor uma nova solicitação. Nunca substitua silenciosamente a build A pela build B porque a build A foi aprovada. Trata-se de outra ação.

Evite um padrão popular, mas fraco: aprovar um pull request e tratar essa aprovação como autorização para produção. A revisão de código responde se uma mudança proposta pertence à base de código. Ela não responde se esta build deve rodar em produção agora, depois do incidente atual, com as migrações e o estado de destino atuais. Mantenha essas decisões separadas.

Os prompts de exclusão precisam de um conjunto de objetos congelado

As aprovações de exclusão se tornam perigosas quando a solicitação contém uma consulta em vez dos objetos resolvidos. «Excluir backups com mais de 30 dias» pode descrever um conjunto diferente a cada minuto.

Na criação da solicitação, resolva a consulta em identificadores de objetos e registre um marcador de snapshot. A tela de aprovação deve mostrar a quantidade, alguns identificadores representativos, a base da retenção e o modo exato de exclusão. O executor deve usar esse conjunto congelado, não executar novamente a consulta ampla depois da aprovação.

Se o conjunto for grande demais para ser exibido por completo, forneça um identificador estável do manifesto e um resumo conciso. Não reduza o prompt a «Excluir 8.421 itens» sem mostrar os limites. Uma quantidade não informa ao revisor se a lista inclui o tenant errado, backups atuais ou um prefixo inesperado.

Considere esta solicitação:

{
  "action_type": "delete_objects",
  "scope": "archive/preview/",
  "selection": {
    "manifest_digest": "sha256:19e7...",
    "object_count": 184,
    "newest_object_at": "2026-06-19T03:11:00Z",
    "oldest_object_at": "2025-11-02T18:24:00Z"
  },
  "mode": "permanent",
  "expires_at": "2026-07-22T14:08:00Z"
}

Na execução, confirme que o manifesto ainda existe e que cada identificador de objeto ainda corresponde à versão esperada. Se o sistema de armazenamento oferecer versionamento, vincule a exclusão às versões, não aos nomes. Nomes podem ser reutilizados. Um novo objeto gravado no mesmo caminho depois da aprovação não deve herdar a sentença de morte do objeto antigo.

Um prazo curto é especialmente importante quando a solicitação se baseia em idade ou em um inventário atual. Quanto mais tempo ela esperar, maior a chance de que um objeto recém-elegível, um item restaurado ou um registro reclassificado altere o conjunto pretendido. Se o sistema não puder congelar o conjunto, não deve permitir que uma única aprovação autorize uma consulta ampla de exclusão. Peça uma solicitação recente e mais restrita.

Exclusão lógica e exclusão permanente merecem prompts e janelas de expiração diferentes. A exclusão lógica pode ser reversível, mas não use a reversibilidade como desculpa para aprovações vagas. A recuperação costuma ser lenta, incompleta ou depender de permissões que a pessoa que solicitou a exclusão não controla.

As aprovações SSH envelhecem mais rápido do que parece

O SSH é especialmente sensível ao contexto desatualizado porque nomes, sessões, variáveis de ambiente e árvores de trabalho podem mudar sob o mesmo texto de comando.

systemctl restart api parece específico até que você pergunte qual máquina o recebe, para onde api aponta nela, qual implantação está ativa e se um incidente posterior mudou o motivo para reiniciar qualquer coisa. rm -rf /srv/tmp/job-123 pode ser seguro em um host e catastrófico em outro se um alias, um mount ou uma expansão do shell mudar.

Para uma ação SSH, aprove uma solicitação de comando estruturada, não uma transcrição do terminal. A solicitação deve incluir a identidade verificada do host, o usuário de destino, um modelo de comando fixo, argumentos permitidos totalmente expandidos, o diretório de trabalho declarado e qualquer digest de entrada esperado. Se o agente precisar de um shell, restrinja o comando do shell a um payload explícito em vez de autorizar uma sessão interativa aberta.

Um cartão de aprovação razoável poderia ser:

Host: prod-api-03, host key SHA256:K4f...
User: deploy
Command: /usr/local/bin/release-health --release 2026.07.22.4 --repair-cache
Directory: /srv/api
Effect: writes cache state, may restart one service
Expires: 14:08 UTC

Isso ainda não prova que o comando é seguro. É informação suficiente para que uma pessoa reconheça o que está autorizando. O executor então se reconecta, verifica novamente a identidade do host, confirma o digest do comando e o executa antes do prazo.

Nunca permita que a aprovação de um comando em prod-api autorize a execução depois que DNS, o inventário ou um mapeamento de bastion resolverem esse rótulo para outro host. Vincule a identidade criptográfica do host quando a configuração da conexão permitir. Se ocorrer uma rotação legítima da chave do host enquanto a aprovação espera, invalide a solicitação. Isso pode parecer incômodo durante uma manutenção. Ainda é melhor do que aprovar um comando para uma máquina e enviá-lo para outra.

Comandos somente leitura merecem uma categoria própria. As equipes muitas vezes exigem aprovação para cada chamada SSH porque têm um único controle e o aplicam em todos os lugares. O resultado é fadiga de aprovação, e então os revisores clicam em comandos que não conseguem interpretar. Separe inspeções inofensivas de ações que gravam, reiniciam, alteram acessos ou expõem informações sensíveis. Use aprovação por chamada quando os efeitos do comando justificarem e mantenha o prompt curto o bastante para ser lido.

A tela de aprovação precisa tornar as mudanças visíveis

Um contrato preciso no backend não serve de nada se o revisor vê apenas uma frase escrita pelo agente. A tela precisa mostrar os campos que poderiam mudar a resposta.

Comece pelo efeito: implantar este digest neste ambiente; excluir permanentemente este manifesto fixo; executar este comando neste host verificado. Coloque o prazo em um local que o revisor note antes de aprovar e mostre o horário em um fuso inequívoco. Exiba uma contagem regressiva apenas como conveniência. O timestamp do servidor do executor decide a validade.

Quando uma solicitação mudar, não substitua o conteúdo antigo no mesmo lugar deixando o botão de aprovação ativo. Marque-a como invalidada. Crie uma nova solicitação com uma explicação visível, como «artefato alterado» ou «inventário de destinos alterado». Um revisor que aprovou a versão anterior deve tomar uma nova decisão. Esse clique extra é justamente o objetivo.

O NIST SP 800-63B-4 descreve a intenção de autenticação como uma intervenção do usuário que confirma que uma pessoa pretende autenticar ou autenticar novamente. A aprovação de ações exige a mesma disciplina, mas de forma mais específica. Um toque ou clique de confirmação deve expressar intenção para a operação exibida, não uma disposição geral de deixar um agente continuar.

Evite prompts que transformem a pressão do tempo em uma armadilha. Uma janela de dois minutos para uma exclusão complexa força o revisor a escolher entre aprovar às cegas e deixar a solicitação expirar. A solicitação deve estar pronta para análise antes de chegar ao revisor. Use um prazo curto de execução depois que o revisor tiver contexto suficiente, não um prazo de decisão apressado que puna uma leitura cuidadosa.

Um campo de comentário pode ajudar quando o revisor precisa explicar por que uma ação incomum é aceitável. Não torne o comentário obrigatório para o trabalho normal. Texto padronizado obrigatório gera conteúdo que ninguém lê. Exija-o para exceções, extensões de prazo fora do padrão ou ações que ultrapassem um raio de impacto definido.

O executor é responsável pela aplicação

O sistema que tem autoridade para realizar a ação precisa aplicar a expiração, o vínculo e o consumo único. Uma interface de workflow, um bot de chat ou uma estrutura de agentes pode solicitar aprovação, mas não pode ser o juiz final se outro componente puder contorná-la.

Por isso, um gateway de ações é uma fronteira útil. O agente faz uma chamada HTTP ou solicita um comando SSH. O gateway verifica se a solicitação tem uma aprovação atual, injeta a credencial quando apropriado, realiza a operação e retorna o resultado. O agente nunca precisa de uma credencial reutilizável que permitiria contornar o fluxo de aprovação mais tarde.

O Sallyport segue esse formato para APIs HTTP e SSH: o agente se conecta pelo seu shim MCP enquanto as credenciais permanecem no cofre criptografado do aplicativo, e o aplicativo executa a ação em vez de entregar os segredos ao agente. Suas chaves por chamada são um lugar natural para exigir uma nova confirmação em ações cujo contexto muda rapidamente. A lógica de timeout e vínculo da ação ainda precisa estar explícita no caminho da solicitação. Uma confirmação sem essas verificações pode envelhecer e produzir o mesmo problema.

Mantenha o estado da aprovação próximo do executor ou torne-o verificável criptograficamente pelo executor. Um token de aprovação assinado pode funcionar se incluir o identificador da solicitação, o digest da ação, o horário de emissão, a expiração, a identidade do revisor e um nonce. O executor ainda precisa verificar a revogação e consumir o nonce uma única vez. Um token assinado que continua válido depois que a solicitação foi invalidada é simplesmente uma aprovação desatualizada bem assinada.

Trate os relógios com cuidado. Use um relógio confiável do serviço para decisões de expiração, armazene timestamps em UTC e rejeite aprovações no instante de expiração ou depois dele. O relógio local do agente e a contagem regressiva do navegador servem apenas para exibição. Eles não são entradas de autorização.

Os logs devem explicar por que a execução ocorreu ou não

Quando uma aprovação expira, as equipes precisam de um registro que diga mais do que «negado». Elas precisam saber se um revisor nunca respondeu, se a solicitação mudou depois da aprovação, se o executor encontrou uma condição prévia com falha ou se outro worker já consumiu a aprovação.

Escreva uma trilha de eventos imutável que conecte a proposta, o resumo exibido, a decisão de aprovação, a invalidação ou expiração, as verificações de preflight, a tentativa de execução e o resultado. Armazene o digest da ação em cada evento. Se a solicitação foi recriada, registre o identificador da solicitação substituta sem sugerir que a aprovação anterior foi transferida.

Um formato útil de evento seria:

{
  "event": "approval.invalidated",
  "request_id": "appr_01JX...",
  "action_digest": "sha256:8b1d...",
  "reason": "release_lane_superseded",
  "replaced_by": "appr_01JY...",
  "recorded_at": "2026-07-22T14:06:22Z"
}

Registre também as tentativas de consumir aprovações expiradas. Elas revelam agentes que repetem tentativas às cegas, workers com relógios incorretos e caminhos da interface que não foram atualizados. Também permitem que um revisor de incidente distinga uma solicitação expirada de uma ação que realmente chegou à produção.

O diário de sessões e o diário de atividades do Sallyport são projetados a partir de um log de auditoria criptografado e encadeado por hash, e o comando sp audit verify verifica essa cadeia offline sobre o texto cifrado. Esse tipo de trilha só é útil se o vocabulário de eventos for honesto. Inclua eventos de expiração, invalidação e falha de preflight, não apenas chamadas bem-sucedidas que deixam o painel com boa aparência.

Não confunda auditabilidade com prevenção. Um registro perfeito de uma aprovação antiga executada contra um estado novo é evidência de uma falha. A verificação preventiva precisa ocorrer antes de o executor enviar a solicitação ou abrir o canal SSH.

Torne barato substituir solicitações expiradas

Janelas curtas só funcionam quando criar uma nova solicitação é mais fácil do que discutir com uma antiga. Se regenerar a solicitação exigir redigitar um número de ticket, reconstruir um comando manualmente e procurar três pessoas, as equipes pressionarão você a aumentar cada timeout até que ele perca o significado.

O agente deve conseguir reenviar a solicitação a partir do estado atual, mas precisa mostrar claramente os novos fatos. Se apenas a expiração mudou e todos os campos vinculados continuam idênticos, uma nova solicitação pode manter o mesmo resumo legível, recebendo um novo identificador e um novo prazo. Se algum campo da ação ou alguma condição atual mudou, informe o que mudou. Não faça o revisor comparar hashes opacos.

Trate a extensão de prazo como exceção. Se oferecer uma, exija que o executor execute novamente todas as verificações de preflight e que o revisor veja o resumo atual outra vez. Um botão «estender por 30 minutos» que renova o token antigo é um contorno da aprovação com uma tipografia mais bonita.

Comece medindo quatro coisas: com que frequência as aprovações expiram, com que frequência ações aprovadas são invalidadas antes da execução, quanto tempo as solicitações esperam e quais tipos de ação geram novas tentativas repetidas. Esses resultados mostram se o prazo é curto demais, se a fila está lenta ou se o agente cria solicitações antes de ter entradas estáveis.

Uma aprovação desatualizada deve falhar de forma silenciosa e específica: o executor a rejeita, o log informa o motivo e o agente solicita uma decisão atual se o trabalho ainda fizer sentido. Essa pequena recusa é o que mantém o controle humano ligado à ação que realmente acontece.