Segredos e vazamento¶

Para: Dev · Adm — Conferido em 2026-10-18.

Esta página diz onde guardar cada segredo, como rotacionar sem derrubar a integração e o que fazer, em ordem, quando um segredo vaza. Leia o procedimento de emergência antes do go-live: no meio de um incidente, as esperas de 24 h do painel não deixam improvisar.

O que é¶

Três materiais sensíveis da sua integração:

Material	Formato	Quem vê	Validade
Chave de API	key id key_test_… ou key_live_… e um segredo	o segredo aparece uma vez, a quem pediu	sem prazo; vale até ser revogada
Segredo de webhook	whsec_…	aparece uma vez, a quem gira o segredo	sem prazo; rotação com sobreposição de 7 dias
Credenciais de pessoas	senha, passkey, app autenticador, códigos de recuperação	cada pessoa	veja Conta, login e dispositivos

Duas observações:

• O Dracma guarda o segredo da chave cifrado e o devolve apenas na revelação. Ele não consegue mostrar o segredo de novo. Segredo perdido é segredo substituído.
• O prazo de 90 dias para trocar a chave é uma recomendação. O Dracma não expira chaves ativas nem avisa aos 75 dias.

Quando usar¶

Use esta página ao montar o deploy do conector, ao agendar a rotação periódica e quando houver suspeita de vazamento (commit com segredo, log com cabeçalho, ex-funcionário com acesso, máquina comprometida).

Como funciona¶

Onde guardar¶

1. Cofre: gerenciador de segredos da sua empresa. É a única cópia permanente.
2. No host: arquivo legível só pelo usuário do sistema que roda o conector (permissão 0400), gravado pela ferramenta de deploy a partir do cofre. Nunca à mão no servidor.
3. Nunca:
4. em repositório de código, imagem de contêiner ou artefato de build;
5. em log, ticket, chat ou e-mail;
6. em variável de front (NEXT_PUBLIC_*, VITE_*) ou em app de jogador: o Dracma é chamado só do servidor;
7. na linha de comando, onde ps mostra o valor;
8. em cabeçalho Dracma-Signature registrado por inteiro.

O segredo do webhook fica em um arquivo com uma linha por segredo ativo (um, ou dois durante a rotação), para o verificador aceitar os dois.

Rotação planejada sem downtime¶

Chave de API:

1. Uma pessoa pede uma chave nova no painel, com fator forte. Outra pessoa aprova. A chave só nasce depois de 24 horas de espera.
2. Quem pediu revela o segredo em até 24 h, uma vez, com fator forte.
3. Entregue o segredo ao conector pelo cofre e faça o deploy. Uma operação aceita até duas chaves ativas, então a antiga continua valendo.
4. Confira no painel o "último uso" de cada chave. Quando a antiga estiver sem uso e sem erros, revogue-a.
5. A revogação é imediata, de uma pessoa, com motivo e fator forte, e vale em todas as réplicas em até 30 segundos.

Segredo de webhook:

1. Gire o segredo no painel (uma pessoa com permissão de gerir webhooks, com fator forte). O valor novo aparece uma vez.
2. Durante 7 dias o Dracma assina com os dois segredos (dois v1= no cabeçalho). Acrescente o novo ao arquivo do receptor e confirme que as entregas continuam aceitas.
3. Depois dos 7 dias, remova o antigo do arquivo.

Veja Chaves de API e Segredo e rotação.

Procedimento de emergência: um segredo vazou¶

Defina antes do go-live quem faz cada passo.

Chave de API vazada

1. Peça já uma chave de reposição (aprovação de outra pessoa e 24 h de espera correm em paralelo). Se já houver duas chaves ativas, revogue a que não é mais usada primeiro.
2. Revogue a chave vazada. É imediato (uma pessoa, motivo, fator forte) e efetivo em até 30 segundos. Depois disso a chave recebe 401 unknown_key.
3. Se a revogação deixar a integração sem chave até a reposição ficar pronta, aceite o tempo parado: o seu conector continua subindo sem o Dracma (pagamentos ficam indisponíveis ou em fila). A alternativa, manter a chave vazada ativa, é pior.
4. Revele a chave de reposição, entregue pelo cofre e faça o deploy.
5. Procure no painel (último uso, contadores de recusa e trilha de auditoria) chamadas que você não reconheça.
6. Se houver sinal de uso indevido, suspenda o saque automático na tela "Regras, listas e emergência": é imediato, zera o automático da moeda e uma segunda pessoa confirma em até 24 h. Os saques passam a ir para revisão manual. Para religar, abra uma proposta de mudança de regra.

Segredo de webhook vazado

1. Gire o segredo (uma pessoa, fator forte). O Dracma passa a assinar com o novo e com o antigo por 7 dias.
2. Atualize o receptor para aceitar o novo.
3. Enquanto o antigo valer, o fetch-back protege você: um evento forjado com assinatura válida não credita nada, porque o valor vem de GET /deposits/{id}.

Credencial de pessoa vazada

1. A pessoa (ou outro administrador) encerra todas as sessões em "Conta, Sair de todos os dispositivos".
2. Troque a senha e os fatores. Remover o último fator forte tem atraso de 24 h cancelável.
3. Um administrador remove os pacotes da pessoa em "Usuários e papéis", se for o caso.

Exemplos¶

Verificar a permissão do arquivo do segredo no host:

stat -c '%a %U' /caminho/seguro/dracma-live.key     # esperado: 400 <usuário do conector>
grep -r "key_live_" ./repositorio-do-conector       # esperado: sem resultado

Erros e casos de borda¶

Situação	O que acontece	O que fazer
Perdi o segredo da chave	não há como mostrar de novo	peça uma chave nova
A janela de 24 h para revelar venceu	a chave nunca foi revelada	peça outra
Já existem duas chaves ativas	key_limit_reached	revogue uma antes de pedir
O segredo foi colado num ticket ou chat	está vazado	trate como vazamento
Só uma pessoa na equipe	os pedidos de chave não fecham	tenha ao menos duas pessoas (veja O que preparar)

Veja também¶

• Rede, allowlist e mTLS
• Chaves de API
• Segredo e rotação
• Checklist de go-live