Pular para conteúdo

0006 — Adotar a lib xadm-seguranca (motor de auth)

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

Contexto

O motor de auth das telas (decisão 0005) nasceu portado byte-a-byte do onpetro/bi-comercial-xls — 9 classes de motor em br.com.xadm.webstormecom.security. A casa extraiu esse motor para a lib br.com.xadm:xadm-seguranca (pacote br.com.xadm.comum.seguranca; ADR 0019 no repo central). Como o validador do IdP Firebase compartilhado (xadm-6ab81) é 1-de-N, o drift entre as cópias vira exposição cross-client — cada app que mantém cópia é uma superfície a mais. O onpetro já adotou (app-piloto, e2e de paridade verde em prod).

Decisão

webstorm-ecom depende da xadm-seguranca (registro Maven Forgejo, org xadm pública → leitura anônima) — adotada na 0.2.0; a versão corrente é a do build.gradle.kts (fonte única, hoje 0.7.1) e deleta as 9 cópias do motor. Lift-and-shift: comportamento de auth idêntico ao pré-extração (Firebase → xadm_session → rota protegida → CSRF), provado por AuthE2EIT.

  • A policy de rota fica no app, não na lib — security/ViewWhitelist (local) guarda o que é app-específico do thoms: a whitelist de views, o alias /webhook/ (poke do integrador, linhagem 006) e as views públicas por UUID (isPublicView/UUID_RAIZ). A lib traz só o contrato (AUTH_*_ATTR, SESSION_COOKIE, deveRecusarAnonimo, isHttps) + os beans do motor. Não unificar /webhook//isPublicView na lib: não existem nos outros apps (policy per-app).
  • Issuer corrigido — a cópia carregava iss = "bi-comercial-xls" hardcoded (nome do onpetro). Com a lib o issuer virou config (AUTH_ISSUER, default webstorm-ecom). Corrigido na adoção: o iss passa a identificar o app certo.
  • Swap atômico — a dependência e a deleção das cópias entram no mesmo commit: com as cópias E a lib no classpath haveria dois beans do mesmo tipo (@ConfigurationProperties("auth"), AuthenticationFetcher, SecurityRule) e o DI não-único quebra o startup.

Consequências

  • Um re-login forçado no primeiro deploy: sessões vivas assinadas com iss=bi-comercial-xls falham a verificação (o segredo de sessão do thoms já é próprio, então a severidade é baixa — defesa em profundidade). TTL de sessão é 8h e o deploy já reinicia o app. Ver AUTH_ISSUER na implantação.
  • Atualização do motor (correções de segurança) passa a vir por bump de versão da lib, não por editar cópia — é o ganho central.
  • AuthExceptionHandler, ViewRejectionHandler (dependem do ProblemDetail local, RFC-7807) e ApiTokenGuard (guard de ingestão, não é auth-user) ficam locais — só repontam imports do motor.

    Superado em parte pela decisão 0007: o ProblemDetail local foi depois eliminado e os dois handlers passaram a usar o da lib xadm-comum-web. ApiTokenGuard segue local. Atualização 2026-09-11 — o ApiTokenGuard foi promovido à lib. A xadm-seguranca 0.7.2 trouxe o BearerTokenGuard (@Context), que faz o mesmo: app.api-token declarado e vazio recusa o boot fora de dev/test com a segurança ligada, e em dev/test só avisa. A migração da lib cita este repo; o ApiTokenGuard e o teste dele saíram no mesmo commit do bump — mantê-los deixaria dois donos da mesma checagem de boot.

Alternativas descartadas

  • Manter as cópias — zero trabalho, mas mantém o drift cross-client (o motivo da extração).
  • Preservar iss=bi-comercial-xls — zero re-login, mas carrega o bug adiante. Como a adoção já reinicia o app e o impacto é 1 re-login, o momento de corrigir é agora.
  • Unificar a whitelist/isPublicView na lib — reduz duplicação aparente, mas /webhook/ e as views por UUID são policy do thoms; forçá-las na lib acopla apps que não as têm.

Linhagem de trabalho: .ia/008-adota-xadm-seguranca-*.

Atualização 2026-08-19 — bump de manutenção 0.3.0 → 0.4.0

Acompanhamento do latest do registro (política da casa). Source-compatível: nenhum import ou assinatura do motor mudou neste app, zero adaptação de código, gate da stack verde. Sem efeito operacional (nenhum re-login, nenhuma config nova). A ViewSecurityRule local segue por desenho.