Pular para conteúdo

0018 — Adotar a lib xadm-seguranca (motor de auth) por versão publicada

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

Contexto

A stack de auth das views (login Firebase → cookie de sessão HS256 → gate micronaut-security → CSRF double-submit; spec 006, decisão 0003) nasceu como cópia byte-a-byte entre onpetro e thoms/vantroba — 13 classes em security/. A casa extraiu o motor para a lib br.com.xadm:xadm-seguranca (ADR 0019 do repo xadm-commons/raiz): 9 classes no pacote br.com.xadm.comum.seguranca, publicada em 0.2.0 no Forgejo Packages.

Enquanto o onpetro mantinha as cópias, o validador do IdP Firebase compartilhado (xadm-6ab81) era 1-de-N cópias — um drift no check de domínio/audience de um app viraria exposição cross-client.

Decisão

bi-comercial-xls depende de xadm-seguranca:0.2.0 por versão publicada (não includeBuild / fonte local), deleta as 9 cópias do motor e mantém local só o que é policy/coisa de app:

  • Whitelist de rota fica local (security/ViewWhitelist) — é policy per-app: o onpetro tem /compras/ (import aberto), que os irmãos não têm. O motor traz só o contrato (AuthSupport: AUTH_*, deveRecusarAnonimo, isHttps).
  • issuer config per-app (auth.issuer, env AUTH_ISSUER, default bi-comercial-xls) — a lib lê de AuthSettings.getIssuer(); antes era hardcoded. Mantido idêntico ao valor anterior → zero invalidação das sessões de 8h em voo.
  • Handlers acoplados ao ProblemDetail (AuthExceptionHandler, ViewRejectionHandler) e o view-model (GlobalViewModel) ficam locais — dependem de dto.ProblemDetail (RFC 7807, decisão 0015); re-extrair só após o xadm-comum-web (fase futura).
  • Testes-espelho do motor deletados (SessionTokenServiceTest, FirebaseIdTokenValidatorTest, os predicados de AuthSupportTest) — a fonte de verdade deles passou pra lib (testada no xadm-commons); e acessavam membros package-private que não sobrevivem à troca de pacote. Fica o que é do app: ViewWhitelistTest (novo) + ViewSecurityRuleTest + o e2e de paridade AuthIntegrationTest.

Consequências

  • security/ passou de 13 classes para 5 locais (ViewSecurityRule, ViewWhitelist, ViewRejectionHandler, AuthExceptionHandler, GlobalViewModel); o resto vem da lib.
  • Validador Firebase agora é fonte única (audience/domínio seguem config per-app) — some o risco de drift cross-client.
  • Gate fiel ao artefato: o build compila contra o jar que a produção embarca (ADR 0019).
  • Paridade provada por e2e contra o artefato publicado (./gradlew check -PdockerTests verde): login RS256 → cookie xadm_session HS256 iss=bi-comercial-xls → rota protegida → CSRF (403 em mismatch), sem regressão de status/redirect.
  • Leitura anônima: a org xadm no Forgejo é pública → repositories { maven { url = ".../api/packages/xadm/maven" } } sem credencial. Se virar privada, adicionar credentials (token read:package).
  • Fica pra depois (não é débito): re-extrair os handlers ProblemDetail quando sair o xadm-comum-web; bump da lib pra 1.0.0 após validar a API em produção (decisão da casa no xadm-commons).

Alternativas consideradas

  • includeBuild / fonte local da lib: descartada — o gate compilaria contra fonte, não contra o artefato que a produção embarca; ADR 0019 exige fidelidade ao publicado.
  • Unificar a whitelist na lib: descartada — whitelist é policy de rota per-app (/compras/ só existe no onpetro); subir pra lib acoplaria os apps sem ganho.
  • Migrar os testes-espelho (só trocar import): impossível — usam construtor 2-arg / init() package-private, que não são visíveis de outro pacote; e reimplementariam o que a lib já testa.