PKI & Activation

Ainda não implementado — design alvo, ver overview.

mTLS: por que autorizar por certificado, não por payload

TLS “normal” (o que protege qualquer HTTPS comum) autentica só um lado: o navegador verifica que o servidor é quem diz ser, o servidor não verifica nada sobre quem está do outro lado da conexão — quem quer que apresente uma requisição válida é atendido. mTLS (TLS mútuo) inverte isso: os dois lados apresentam certificado, os dois lados verificam. Aqui, o servidor (key-service) também exige que o cliente (o software instalado) prove identidade via certificado antes de aceitar qualquer requisição — a autenticação acontece no handshake TLS, antes de qualquer byte de aplicação trafegar.

A vantagem sobre autenticar por payload (um token dentro do corpo da requisição, por exemplo) é que a prova de identidade não depende do software da aplicação implementar isso certo: é a camada de transporte que recusa a conexão, não um middleware que alguém pode esquecer de aplicar numa rota nova. Por isso a autorização deste design é exclusivamente por fingerprint do certificado apresentado na conexão — não por um campo dentro de um token, que poderia ser copiado ou forjado se a chave privada não tivesse sido comprometida junto.

step-ca: autoridade certificadora automatizada

Uma CA (Certificate Authority) é quem assina certificados, atestando “esta chave pública pertence a esta identidade”. step-ca é uma CA que expõe esse processo via API, ao estilo ACME (o mesmo protocolo por trás do Let’s Encrypt) — emissão de certificado é uma chamada HTTP, não um processo manual com alguém aprovando cada pedido.

A CA roda como serviço separado do backend de negócio (Laravel) de propósito: a chave privada da CA — o segredo mais crítico de todo o sistema, porque quem a tem pode emitir certificado válido para qualquer identidade — nunca fica no mesmo processo nem no mesmo banco que guarda dado de cliente. Comprometer o license-manager não compromete a CA.

CSR e OTT: como uma ativação vira um certificado

Um CSR (Certificate Signing Request) é o que o software gera localmente: um par de chaves nova (a privada nunca sai da máquina do cliente) e um pedido assinado com essa chave, pedindo para a CA emitir um certificado para a chave pública correspondente. A CA nunca vê a chave privada — só assina o que foi pedido, atestando a identidade.

Autorizar qualquer CSR que chegue seria o mesmo problema do voucher sozinho (qualquer um que soubesse o endpoint poderia pedir certificado). Por isso a emissão usa OTT (one-time token): um token de uso único, emitido pelo key-service no momento da ativação bem-sucedida do voucher, que autoriza especificamente aquele CSR e nenhum outro — implementado à mão pelo key-service, não o fluxo padrão de step-ca de “qualquer requisição autenticada pode pedir certificado”.

O fluxo completo de ativação

1. Cliente é cadastrado no painel do license-manager. Um serial é gerado automaticamente.
2. O serial vai para o key-service (evento propagado via outbox — ver tokens-and-events).
3. O cliente recebe o serial por e-mail.
4. Na primeira execução do software, o usuário informa o serial num popout.
5. O software ativa contra o key-service usando esse serial, tratado como voucher: serve só para identificar e autorizar a ativação, uma vez.
6. O key-service emite um OTT, o software gera CSR localmente e o envia; o key-service ativa via step-ca, entrega certificado e token ao software.
7. O software grava localmente o serial e o certificado — não grava os dados da licença (plano, entitlements, limites) em arquivo. Esses dados são buscados a cada requisição, para que um script não consiga sobrescrever um license.json local e forjar direitos que a licença não tem.

O voucher é queimado de forma condicional na ativação — garantido por índice parcial no banco (uma constraint que o próprio banco recusa violar), não por um if de aplicação sujeito a race condition se duas ativações chegarem ao mesmo tempo. Sem essa garantia no nível de dado, duas requisições simultâneas com o mesmo voucher poderiam ambas passar pela checagem “ainda não foi usado” antes de qualquer uma marcar como usado — e o mesmo serial ativaria duas máquinas.