Pular para conteúdo

0020 — Rename auth → central-backend (identidade interna) mantendo auth.xadm.biz como protocolo

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-08-19 · Decidido em: 2026-08-19

Contexto

O serviço nasceu como auth-service (domínio auth.xadm.biz), mas cresceu muito além de autenticação: é o broker build-time da Central de Apps, o monitor de infra do Coolify e o backend da Central. O nome auth ficou estreito. A versão native já é servida em central-backend.xadm.biz. Decidiu-se renomear a identidade do serviço para central-backend — sem quebrar o que o PowerSync valida.

O risco: auth.xadm.biz não é só um domínio — é o host do JWKS que cada instância PowerSync busca (jwks_uri) e o iss dos JWT que ela valida. Movê-lo exige reconfigurar o PowerSync de todos os clientes em lockstep, senão todo o sync para.

Decisão

Separar identidade INTERNA de identidade de PROTOCOLO.

  • Interna → central-backend: repo, package Java br.com.xadm.integracao.central (era .auth), prefixo de config central.* (era auth.*), CentralSettings (era AuthSettings), micronaut.application.name, app.json (slug/app_id/production_url), docs (README, site_url).
  • Protocolo → permanece auth.xadm.biz: o iss do JWT e o /.well-known/jwks.json seguem em auth.xadm.biz (defaults issuer=https://auth.xadm.biz, kid=auth-1 inalterados). O serviço passa a ser servido também em central-backend.xadm.biz. Migrar o issuer/JWKS é um passo coordenado à parte (repointar jwks_uri+issuer em cada cliente PowerSync — ver runbook do PowerSync).
  • Env vars → dual-read CENTRAL_* sobrepõe AUTH_*: o application.yml lê AUTH_* (o que o Coolify tem hoje); a var CENTRAL_*, quando definida, sobrepõe via relaxed binding do Micronaut (env > yml). O Coolify migra AUTH_* → CENTRAL_* sem janela de quebra.
  • Banco db_auth permanece: nome interno, invisível externamente; renomear seria migração de dados sem ganho.

Alternativas preteridas

  • Mudar o issuer/JWKS para central-backend.xadm.biz agora: quebraria o PowerSync de todos os clientes sem uma janela de migração coordenada. Desacoplar é mais seguro.
  • Rename hard das env vars (AUTH_* → CENTRAL_* sem fallback): exigiria trocar as 21 vars no Coolify no mesmo deploy — quebra se desalinhar. O dual-read remove a janela de risco.
  • Renomear db_auth: migração de dados de risco por ganho cosmético nulo.

Consequências e gotchas (para o próximo rename)

  • Placeholder aninhado do Micronaut é traiçoeiro. ${CENTRAL_X:${AUTH_X:}} com default interno vazio não colapsa para "" nesta versão — resolve para um literal/lixo, que quebrou o carregamento da chave RSA (JwtService → Base64 "Input byte[] should at least have 2 bytes"). A forma robusta de dual-read é single-level ${AUTH_X:default} + deixar o CENTRAL_X (env) sobrepor via relaxed binding — não aninhar placeholders.
  • String de config-key não é FQN de package. Um sed de br.com.xadm.integracao.auth → .central não pega @Requires(property = "auth.firebase-project-id") nem @Value("${auth.integrator.token}"). Essas chaves de config precisam de rename à parte — um @Requires errado deixa um bean condicional ligar quando não devia (aqui: o FirebaseTokenValidatorService ligava com project-id vazio e explodia no @PostConstruct).
  • app_id mudou de auth → central-backend: se houver linha provisionada com app_id="auth" no db_auth (catálogo), o /xadm-setup com o novo id cria/atualiza central-backend e a antiga fica órfã — reconciliar/re-provisionar no primeiro setup pós-rename.