Glossário do projeto¶

Vocabulário do domínio de autenticação que este app usa. Termos da plataforma X-Adm (Forgejo, Coolify, Garage…) não são redefinidos aqui — linkam para o glossário da plataforma.

Tokens e chaves¶

JWT: JSON Web Token (RFC 7519). Token compacto e auto-contido para transmitir claims entre partes. Três partes Base64url separadas por ponto: header, payload e assinatura.
JWKS: JSON Web Key Set (RFC 7517). Formato padrão para publicar chaves públicas. O endpoint /.well-known/jwks.json permite que qualquer serviço (ex. o PowerSync) obtenha a chave pública e verifique JWTs sem configuração manual.
RS256: Algoritmo de assinatura JWT com RSA + SHA-256. Criptografia assimétrica: a chave privada assina, a chave pública verifica. O alg=RS256 explícito no JWKS é obrigatório — o PowerSync recusa chaves sem ele.
kid: Key ID — identifica qual chave pública do JWKS valida um token. Configurável via AUTH_KEY_ID; viabiliza rotação de chaves.
AES-256-GCM: Cifra simétrica autenticada (AEAD) usada para guardar a senha do banco de cada cliente (clientes.db_pass) em db_auth. Qualquer adulteração do ciphertext quebra a decifragem, em vez de devolver dado corrompido. (Legado — sem efeito após a centralização de pabast_senhas, decisão 0003.)

Domínio de autenticação¶

pAbast: Sistema de autenticação proprietário do X-Adm/ERP. Usa senha de 4 dígitos e senha complementar de 3 dígitos, guardadas como hashes em pabast_senhas.
Algoritmo pAbast: A função de hash do pAbast, portada sem alteração do integrador (Java) e do app Flutter (Dart) para o central-backend. A lógica idêntica nos três lugares garante compatibilidade com os hashes já gravados em produção.
Token anônimo: JWT emitido por POST /api/auth/anon sem autenticar usuário. Tem scope=pabast_only e autoriza sincronizar apenas pabast_senhas via PowerSync. Usado no bootstrap offline.
Bootstrap offline: Primeira sincronização da tabela pabast_senhas para o dispositivo, feita com o token anônimo. Quebra o ciclo ovo-e-galinha (o app precisa dos hashes para logar offline, mas precisaria estar logado para sincronizá-los). Depois disso, o login offline funciona sem internet.
scope: Claim do JWT que controla quais buckets o PowerSync libera: pabast_only (só hashes de senha) ou full (todos os dados de BI).
xadm_admin: Claim booleano em JWTs emitidos por POST /api/auth/firebase/login para e-mails @xadm.com.br. Quando true, autoriza o acesso a /api/admin/**.
Firebase ID Token: Token emitido pelo Firebase Authentication após login Google/e-mail. O central-backend o valida pelo JWKS público do Google e, se o e-mail for @xadm.com.br, emite um JWT próprio com xadm_admin=true.

Integrador-client (on-premise)¶

Instalação: Uma cópia do integrador-client rodando num cliente. O central guarda uma por cliente (integrador_instancias), registrada sozinha no 1º heartbeat — não há cadastro prévio além do cliente existir em clientes.
Heartbeat: Sinal de vida que a instalação manda no startup e a cada 60 min (versão, fluxos, hostname). Vai ao integrador-server do próprio cliente, que carimba o cliente_id e o repassa ao central (POST /api/integrador/heartbeat, Bearer CENTRAL_API_TOKEN).
Horas úteis: Tempo contado só dentro de 07:00–22:00, de segunda a sexta, fora de feriado nacional, no fuso America/Sao_Paulo. É a régua do alerta de silêncio — noite, fim de semana e feriado não contam.
Silêncio (episódio de): Instalação que passou de 6 horas úteis sem heartbeat. O central alerta uma vez por episódio (marca alertado_em) e o próximo heartbeat o encerra.
Situação: Estado da instalação na lista admin: cliente_inativo (cliente desativado no central, não alerta), senão silencioso (episódio aberto), senão ativo.

Integração¶

PowerSync: Serviço de sincronização offline-first que replica dados do PostgreSQL para o SQLite local do app Flutter. Valida JWTs via JWKS para autorizar conexões. Cada cliente tem a sua instância (ex. ps.vantroba.xadm.biz), mas todas apontam para o mesmo jwks_uri deste serviço.