ORG-0026 — Serviços de apoio expostos

Pela ORG-0017, uma aplicação é uma imagem, um serviço, um endereço e uma família de cor, e só uma aplicação tem endereço público. Os serviços de apoio (banco, armazenamento de objetos, filas) ficam na rede interna, e tudo o que o navegador recebe passa pela aplicação.

Às vezes isso custa caro: um arquivo grande ocupa a aplicação durante todo o download ou envio, quando o armazenamento poderia entregá-lo direto, com um link pré-assinado. A primeira stack a precisar disso expôs o armazenamento de objetos num endereço próprio, <produto>-arquivos.hibex.app, com um proxy na frente. A ORG-0017 não dizia como nomear esse endereço, quem autoriza o acesso nem o que a stack precisa declarar.

Um serviço de apoio exposto não é uma aplicação: não tem tela, família de cor, client no Keycloak nem sessão. O risco também é outro. Uma aplicação decide por sessão e permissão. Um armazenamento exposto responde a quem tiver a URL certa.

1. A regra continua sendo passar pela aplicação. Expor um serviço de apoio é exceção, decidida numa ADR da stack que diz por que a aplicação não serve no lugar dele (tamanho, volume, latência).

2. A aplicação autoriza, o serviço só confere. Todo acesso ao serviço exposto leva uma autorização que a aplicação emite depois de conferir a sessão e a permissão (ORG-0020): um link assinado, de um objeto só, com os métodos mínimos e um prazo curto, dito na ADR. Sem autorização, o serviço recusa. Ele não tem login, sessão nem cookie próprios.

3. O endereço é do produto, no domínio do público mais externo que o usa: <produto>-<função>.hibex.app quando algum usuário final o alcança, e <produto>-<função>.<plataforma>.hibex.net quando só colaboradores o alcançam. <função> é um substantivo do que ele entrega (arquivos, por exemplo).

4. Um proxy na frente, atrás do kamal-proxy, que faz o TLS. O proxy:

   • responde o healthcheck do kamal-proxy;
   • aceita só os métodos que a stack usa;
   • acrescenta os cabeçalhos que impedem o conteúdo do usuário de virar página (X-Content-Type-Options: nosniff e Content-Security-Policy: sandbox, no mínimo);
   • registra o acesso sem a query, que carrega a assinatura.

   A API de administração do serviço nunca fica exposta, e o serviço não publica porta no host.

5. A stack declara cada serviço exposto, na ADR que o decide e na ficha:

   • o endereço e o público;
   • o que ele expõe e o que nunca expõe;
   • a autorização (o tipo, o prazo e os métodos);
   • a aplicação dona, em cujo deploy.yml ele é um accessory.

• O que o navegador alcança direto passa a ter uma regra escrita, conferível na revisão da ADR da stack.
• A segurança do serviço exposto depende da assinatura: uma chave vazada abre o armazenamento. A ADR da stack diz o que a chave alcança e como se troca.
• O acesso ao conteúdo aparece no log do proxy, não nos traces da aplicação, que registram só a autorização emitida.
• Cada serviço exposto acrescenta ao deploy um registro de DNS e um accessory.

O detalhe está na documentação da arquitetura.