Rotação de segredo sem indisponibilidade: trocar chave em produção sem derrubar integração

O modelo mental que produz o incidente é o de que um segredo é um valor único, guardado num lugar único, e que rotacionar significa substituir esse valor por outro num instante determinado. Esse modelo funcionaria se o sistema fosse um único processo lendo uma única variável, e é falso em qualquer arquitetura que tenha mais de uma instância. Na prática o segredo está simultaneamente no gerenciador de segredos, na variável de ambiente do contêiner que subiu há três dias, no cache em memória do processo que leu a variável uma vez na inicialização, no painel de configuração do parceiro externo, no token que já foi emitido e ainda não expirou, e na fila de mensagens que guarda uma requisição assinada esperando processamento. Trocar o valor na origem não troca nenhuma dessas cópias no mesmo instante.

A consequência é que existe sempre uma janela de propagação, e ela não é um detalhe operacional que pode ser encurtado até desaparecer. Ela é composta pelo tempo de detecção do gerenciador de segredos, pelo tempo de reinício ou de recarga de cada instância, pelo tempo de vida do cache local, pelo tempo de vida dos tokens já emitidos e pelo tempo que o parceiro externo leva para aplicar a mudança do lado dele, que pode ser de dias. Durante essa janela, parte do sistema conhece a chave nova e parte conhece a antiga, e as duas partes precisam conseguir conversar. Uma troca atômica declara por decreto que a janela tem duração zero, e todo tráfego que cai dentro dela falha.

TROCA ATOMICA (o que quebra)

  t0: chave K1 em todo lugar          verificacao: aceita K1
  t1: gerenciador passa a servir K2   emissao: K2 em 2 de 12 instancias
      |
      +-> instancia A (reiniciada)  assina com K2 -> receptor so aceita K1  FALHA
      +-> instancia B (nao reiniciada) assina com K1 -> parceiro so aceita K2  FALHA
      +-> webhook em voo assinado com K1 chega em t1+3s                      FALHA
      +-> token JWT emitido em t0-600s ainda valido por mais 3000s           FALHA

  Janela de falha = max(propagacao interna, TTL de token, aplicacao no parceiro)


ROTACAO POR CONJUNTO (o que funciona)

  fase 1  verifica: {K1, K2}   assina: K1     <- K2 introduzida, ninguem usa ainda
  fase 2  verifica: {K1, K2}   assina: K1     <- propaga ate 100% conhecer K2
  fase 3  verifica: {K1, K2}   assina: K2     <- promocao: so muda quem EMITE
  fase 4  verifica: {K2}       assina: K2     <- retirada, apos uso de K1 zerar

  Em nenhuma fase existe instante em que quem verifica desconhece
  a chave que alguem esta usando para assinar.

A inversão que resolve o problema é simples de enunciar e incômoda de aceitar: durante a rotação, o segredo deixa de ser um valor e passa a ser um conjunto. Quem verifica aceita todos os membros válidos do conjunto, quem emite escolhe exatamente um. Como verificar é uma operação tolerante e emitir é uma operação exclusiva, é possível introduzir uma chave nova sem que nada mude de comportamento, propagar essa introdução no ritmo que a infraestrutura permitir e só então mover a emissão. A troca deixa de ser um evento instantâneo e vira uma transição com quatro estados observáveis, e a indisponibilidade desaparece porque em nenhum momento existe alguém verificando com um conjunto que não contém a chave que o outro lado está usando.

A implementação dessa ideia exige uma mudança pequena no código e uma mudança grande no formato do que trafega. A mudança no código é aceitar uma lista de chaves na verificação em vez de uma só. A mudança no formato é que a mensagem precisa carregar o identificador da chave que a assinou, porque sem esse identificador a verificação vira uma tentativa por força bruta contra todos os membros do conjunto, e isso custa tempo de CPU proporcional ao tamanho do conjunto além de destruir a possibilidade de medir quem ainda usa o quê. O identificador de chave não é um enfeite, ele é o que torna a rotação observável.

Vale insistir num ponto de segurança que costuma ser tratado como detalhe: a comparação da assinatura precisa ser feita em tempo constante. Uma comparação de bytes que retorna assim que encontra a primeira diferença vaza, pelo tempo de resposta, quantos bytes iniciais estavam corretos, e isso permite que um atacante descubra a assinatura correta byte a byte com um número de tentativas linear em vez de exponencial. Em rotação isso importa ainda mais, porque o conjunto de chaves aceitas aumenta a superfície: cada chave adicional é mais uma comparação, e uma implementação ingênua que testa a chave nova primeiro e a antiga depois acaba respondendo mais devagar para mensagens assinadas com a chave antiga, o que por si só já revela informação sobre o estado da rotação.

import { createHmac, timingSafeEqual, randomBytes } from 'node:crypto';

// O segredo e um CONJUNTO. Cada membro tem identificador, estado e material.
// Estados: 'pending'   -> aceita na verificacao, nunca escolhida para assinar
//          'active'    -> aceita na verificacao, escolhida para assinar
//          'retiring'  -> aceita na verificacao, nao assina mais
//          'revoked'   -> fora do conjunto, rejeitada
const chaveiro = {
  'k-2026-03': { estado: 'retiring', material: process.env.SIGNING_KEY_2026_03 },
  'k-2026-09': { estado: 'active', material: process.env.SIGNING_KEY_2026_09 },
};

const assinar = (corpo) => {
  const entrada = Object.entries(chaveiro).find(([, k]) => k.estado === 'active');
  if (!entrada) throw new Error('chaveiro sem chave ativa: emissao bloqueada');

  const [kid, chave] = entrada;
  const assinatura = createHmac('sha256', chave.material).update(corpo).digest('hex');

  // O kid viaja com a mensagem. Sem ele nao ha como medir uso por chave
  // nem como verificar em tempo O(1) em vez de O(tamanho do conjunto).
  return { kid, assinatura };
};

const comparaConstante = (a, b) => {
  const bufA = Buffer.from(a, 'utf8');
  const bufB = Buffer.from(b, 'utf8');
  // timingSafeEqual exige mesmo tamanho: compara o tamanho antes, sem vazar
  // o conteudo, e so entao compara os bytes em tempo constante.
  if (bufA.length !== bufB.length) return false;
  return timingSafeEqual(bufA, bufB);
};

const verificar = ({ corpo, kid, assinatura }) => {
  const chave = chaveiro[kid];

  // Chave desconhecida ou revogada: rejeita sem tentar as outras.
  if (!chave || chave.estado === 'revoked') {
    metricas.assinaturaRejeitada({ kid, motivo: 'kid_desconhecido' });
    return false;
  }

  const esperada = createHmac('sha256', chave.material).update(corpo).digest('hex');
  const valida = comparaConstante(assinatura, esperada);

  // A metrica por kid e o que permite decidir a retirada com evidencia.
  metricas.verificacao({ kid, estado: chave.estado, valida });
  return valida;
};

// Emissao de uma chave nova: entra como 'pending', nunca como 'active'.
// Promover na mesma operacao em que se introduz e repetir a troca atomica.
const introduzirChave = () => ({
  kid: `k-${new Date().toISOString().slice(0, 7)}`,
  estado: 'pending',
  material: randomBytes(32).toString('hex'),
});

O detalhe que mais evita retrabalho está na última função do exemplo. Uma chave nova entra sempre no estado que é aceito na verificação mas nunca escolhido para assinar, e a promoção é uma operação separada, executada depois. Times que introduzem e promovem no mesmo passo reconstroem exatamente a troca atômica que estavam tentando evitar, com a diferença de que agora acreditam estar protegidos porque o código tem um chaveiro. A separação entre introduzir e promover é o que dá à infraestrutura o tempo de propagação de que ela precisa, e é o que permite que a promoção seja revertida em segundos sem que nada tenha sido revogado.

A rotação bem executada tem quatro fases, e cada uma responde a uma pergunta diferente com um critério de saída objetivo. A fase de introdução coloca a chave nova no conjunto aceito por todos os verificadores, sem que ninguém a use para assinar. A fase de propagação espera até que a introdução tenha alcançado cem por cento das instâncias, réplicas e parceiros. A fase de promoção move a emissão para a chave nova, mantendo a antiga aceita. A fase de retirada remove a chave antiga do conjunto aceito. Três dessas fases são reversíveis em segundos e praticamente não produzem incidentes. A quarta é irreversível e concentra quase todas as falhas.

A leitura dessa tabela costuma reorganizar a discussão dentro do time. O risco não está distribuído pelo processo, ele está inteiro na última linha, e é exatamente ali que a pressa aparece, porque a retirada é a fase que fecha a tarefa e que satisfaz o requisito de auditoria. Depois da promoção, a rotação parece pronta: o tráfego novo já usa a chave nova, os painéis estão verdes e o incidente que motivou a rotação já foi endereçado. A tentação de revogar a chave antiga no mesmo dia vem justamente daí. Manter a chave antiga aceita por mais alguns dias custa muito pouco e evita a única falha irreversível do processo.

1. Gerar a chave nova e adicionar ao conjunto no estado que é aceito na verificação e nunca escolhido para assinar, sem tocar em quem emite.
2. Implantar e confirmar, por métrica e não por suposição, que cem por cento das instâncias carregaram o chaveiro contendo a chave nova.
3. Aguardar o maior entre o tempo de vida do cache de segredos, o tempo de vida do token mais longo e o prazo que o parceiro externo declara para aplicar a mudança.
4. Promover a chave nova a ativa, mantendo a antiga aceita, e observar a proporção de assinaturas emitidas por identificador de chave subir para o valor esperado.
5. Mover a chave antiga para o estado que ainda aceita na verificação mas não assina, e aguardar o uso dela cair a zero de forma sustentada.
6. Revogar a chave antiga apenas depois de um período de uso zero maior que o tempo de vida do artefato assinado mais longo do sistema, e manter o registro da revogação para auditoria.

O uso da chave antiga costuma cair rápido logo após a promoção e depois estacionar num valor baixo que não chega a zero, e é esse resíduo que decide o calendário da retirada. Ele quase nunca vem de instâncias que não reiniciaram, porque essas aparecem cedo e são corrigidas no mesmo dia. Ele vem de artefatos assinados que continuam válidos e de cópias do segredo em lugares que ninguém inventariou. Um token de acesso com validade de sete dias emitido no dia anterior à promoção vai ser apresentado por sete dias, e cada apresentação é uma verificação que exige a chave antiga no conjunto. Um webhook que falhou e entrou em política de nova tentativa com espera exponencial pode voltar dezoito horas depois carregando a assinatura original.

Há ainda três origens que produzem resíduo indefinido e que precisam ser tratadas como bloqueio explícito, não como ruído. A primeira é o parceiro externo que aplica a mudança em ritmo próprio, às vezes exigindo um chamado formal e uma janela de várias semanas, e que em alguns casos simplesmente não suporta duas chaves ao mesmo tempo do lado dele. A segunda é o segredo copiado para fora do gerenciador, num arquivo de configuração de um serviço legado, num trabalho agendado que ninguém executa há meses, ou num script de operação que alguém guardou. A terceira, mais traiçoeira, é o dado em repouso cifrado ou assinado com a chave antiga: revogar a chave nesse caso não interrompe uma integração, ele torna o dado ilegível de forma permanente.

// Descoberta do que ainda depende da chave antiga, feita por evidencia
// e nao por inventario manual. Roda antes de qualquer revogacao.

const AGORA = Date.now();
const HORA = 3600 * 1000;

// 1) Uso observado por chave, vindo da metrica emitida na verificacao.
const usoPorChave = await metricas.consultar({
  metrica: 'verificacao_assinatura_total',
  agruparPor: ['kid', 'origem'],
  janela: '72h',
});

// 2) Artefatos assinados que ainda podem ser apresentados no futuro.
//    Este e o prazo minimo de sobrevida da chave antiga.
const artefatos = [
  { nome: 'token_de_acesso', ttlHoras: 24 },
  { nome: 'token_de_atualizacao', ttlHoras: 24 * 30 },
  { nome: 'link_de_convite_assinado', ttlHoras: 24 * 7 },
  { nome: 'retentativa_de_webhook', ttlHoras: 18 },
];

const sobrevidaMinimaHoras = Math.max(...artefatos.map((a) => a.ttlHoras));

// 3) Criterio objetivo de retirada, avaliado por origem.
const bloqueios = usoPorChave
  .filter((linha) => linha.kid === 'k-2026-03' && linha.total > 0)
  .map((linha) => ({
    origem: linha.origem,
    total: linha.total,
    ultimoUsoHaHoras: Math.round((AGORA - linha.ultimoUso) / HORA),
  }));

const podeRevogar =
  bloqueios.length === 0 &&
  horasDesdeAPromocao() > sobrevidaMinimaHoras;

if (!podeRevogar) {
  console.error('revogacao bloqueada. dependencias vivas na chave antiga:');
  console.table(bloqueios);
  console.error(`sobrevida minima exigida: ${sobrevidaMinimaHoras}h`);
  process.exit(1);
}

// 4) Dado em repouso: verificacao separada, porque aqui a revogacao
//    nao causa indisponibilidade e sim perda permanente de acesso.
const registrosComChaveAntiga = await db.contar({
  tabela: 'documentos_cifrados',
  onde: { kid_da_chave: 'k-2026-03' },
});

if (registrosComChaveAntiga > 0) {
  console.error(
    `${registrosComChaveAntiga} registros ainda cifrados com a chave antiga. ` +
      'Recifre antes de revogar: revogar aqui e perda de dado, nao queda de servico.',
  );
  process.exit(1);
}

A separação entre as duas verificações finais do exemplo é deliberada e vale ser explicada em qualquer revisão de código. Uma chave usada para autenticar tráfego e uma chave usada para cifrar dado em repouso têm perfis de risco opostos na retirada. No primeiro caso, revogar cedo demais causa uma falha ruidosa, imediata e reversível: a integração cai, alguém percebe em minutos e a chave volta ao conjunto. No segundo, revogar cedo demais causa uma falha silenciosa e definitiva, que só aparece quando alguém tenta ler um documento antigo, possivelmente meses depois, quando o material da chave já não existe em lugar nenhum. Por isso a rotação de chave de cifragem exige recifragem completa antes da revogação, e não apenas uma janela de espera.

A pergunta que decide a retirada é sempre a mesma: alguém ainda depende da chave antiga? Sem instrumentação, essa pergunta é respondida por argumento de autoridade, por leitura de código ou por memória de quem participou da implantação, e as três formas erram. A instrumentação que responde de fato é um contador de verificações rotulado pelo identificador da chave e pela origem da requisição, e ele custa uma linha na função de verificação. A partir dele a retirada deixa de ser uma decisão de calendário e passa a ser uma decisão de evidência: a chave antiga sai do conjunto quando o contador dela está em zero há mais tempo que o artefato assinado mais longo do sistema.

O rótulo de origem é o que separa uma métrica útil de um número agregado inútil. Saber que a chave antiga foi usada duzentas vezes nas últimas vinte e quatro horas não permite agir. Saber que cento e noventa e oito dessas vezes vieram de um único parceiro e duas vieram de um trabalho agendado interno permite abrir um chamado com o parceiro e corrigir o trabalho agendado no mesmo dia. Vale limitar a cardinalidade desse rótulo a um conjunto pequeno e conhecido, como o nome do serviço chamador ou o identificador do parceiro, e nunca usar algo aberto como o endereço de origem, que multiplica séries temporais sem adicionar poder de decisão.

• Verificações com identificador de chave desconhecido acima de zero por cinco minutos: alguém está assinando com uma chave que saiu do conjunto cedo demais, ou a chave nova não chegou a todos os verificadores.
• Proporção de emissões com a chave antiga acima de um por cento vinte e quatro horas depois da promoção: existe instância que não recarregou o chaveiro e ela vai falhar no momento da retirada.
• Falhas de verificação com identificador de chave conhecido acima de zero de forma sustentada: o material da chave difere entre os lados, o que costuma ser erro de cópia ou de codificação e não problema de propagação.
• Idade da chave ativa acima do prazo definido na política, medida em dias: a rotação preventiva não aconteceu, e o alerta precisa disparar antes do vencimento e não depois.
• Qualquer chave em estado que aceita mas não assina há mais tempo que o dobro da sobrevida mínima: a retirada travou por algum bloqueio que ninguém está acompanhando.

O último item dessa lista existe porque o modo de falha mais comum de uma rotação bem projetada não é o incidente, é o abandono. A promoção resolve o problema visível, o painel fica verde, a tarefa sai do quadro e a chave antiga permanece aceita indefinidamente, às vezes por anos. O resultado é um sistema que acumula chaves válidas, o que anula boa parte do benefício de segurança que motivou a rotação, já que a chave possivelmente comprometida continua funcionando. Um alerta sobre chaves paradas no estado intermediário é o que transforma a rotação de um evento em um processo que realmente termina.

Toda a estratégia descrita até aqui depende de que o verificador aceite um conjunto, e existe um caso em que isso não está sob controle: o parceiro externo cujo painel tem um único campo de segredo. Nesse arranjo, o momento em que o valor é salvo do lado dele é uma troca atômica de verdade, e a única pergunta que importa é quem verifica o quê. Se o parceiro envia webhooks assinados para o sistema e a verificação acontece do lado de dentro, o problema é confortável, porque o conjunto está sob controle: basta aceitar as duas chaves e pedir que o parceiro troque quando quiser. Se o sistema é que assina requisições enviadas ao parceiro, o controle está do outro lado e o conjunto não existe.

Nesse segundo caso, a técnica que funciona é deslocar a atomicidade para um ponto onde a reversão é barata. Em vez de trocar a chave e torcer, o cliente que chama o parceiro passa a tratar a falha de autenticação como sinal de rotação em andamento e a tentar a outra chave uma única vez, registrando qual delas funcionou. Isso converte uma janela de indisponibilidade total numa janela de latência ligeiramente maior para uma fração das requisições, e ela se fecha sozinha assim que a chave nova passa a funcionar de forma consistente. Duas salvaguardas tornam a técnica segura: a segunda tentativa acontece apenas para erro de autenticação, nunca para outros erros, e apenas para requisições idempotentes ou que carreguem chave de idempotência, sob risco de duplicar um efeito colateral no parceiro.

// Cliente resiliente a rotacao quando o parceiro so aceita UMA chave.
// Converte janela de indisponibilidade em janela de latencia.

const CHAVES = [
  { kid: 'k-2026-09', material: process.env.PARTNER_KEY_NEW },
  { kid: 'k-2026-03', material: process.env.PARTNER_KEY_OLD },
];

// Lembra qual chave funcionou por ultimo para nao pagar a tentativa extra
// em toda requisicao. Comeca pela nova, que e a esperada apos a promocao.
let kidPreferido = CHAVES[0].kid;

const ordenarChaves = () => {
  const preferida = CHAVES.find((c) => c.kid === kidPreferido);
  const demais = CHAVES.filter((c) => c.kid !== kidPreferido);
  return preferida ? [preferida, ...demais] : CHAVES;
};

const chamarParceiro = async ({ caminho, corpo, chaveIdempotencia }) => {
  const tentativas = ordenarChaves();
  let ultimaResposta;

  for (const chave of tentativas) {
    const resposta = await fetch(`https://api.parceiro.com${caminho}`, {
      method: 'POST',
      headers: {
        'content-type': 'application/json',
        // A chave de idempotencia e o que torna a segunda tentativa segura:
        // sem ela, repetir uma requisicao que ja teve efeito duplica a acao.
        'idempotency-key': chaveIdempotencia,
        'x-signature': assinarCom(chave.material, corpo),
      },
      body: corpo,
    });

    ultimaResposta = resposta;

    // Sucesso: fixa a preferencia e sai.
    if (resposta.ok) {
      if (kidPreferido !== chave.kid) {
        kidPreferido = chave.kid;
        metricas.rotacaoParceiro({ kid: chave.kid, evento: 'preferencia_trocada' });
      }
      return resposta;
    }

    // So 401 e 403 indicam chave errada. Repetir em 500 ou em 429
    // com a outra chave nao corrige nada e dobra a carga no parceiro.
    if (resposta.status !== 401 && resposta.status !== 403) return resposta;

    metricas.rotacaoParceiro({ kid: chave.kid, evento: 'auth_recusada' });
  }

  // Nenhuma chave funcionou: e falha de verdade, nao rotacao.
  return ultimaResposta;
};

A restrição de status no penúltimo bloco do exemplo é a linha que impede que essa técnica se transforme num amplificador de incidente. Repetir com a outra chave diante de um erro de servidor ou de um limite de taxa não corrige nada, porque o problema não é a chave, e dobra a carga enviada a um parceiro que já está sinalizando dificuldade, o que é exatamente o comportamento que transforma uma degradação em queda. A segunda tentativa só faz sentido quando o parceiro afirmou explicitamente que a credencial não serve, e mesmo assim apenas uma vez por requisição.