@zydon/auth

Auth React (@zydon/auth)

Biblioteca de autenticacao para projetos React do ecossistema Zydon. Fornece funcoes de login, gerenciamento de tokens JWT, refresh automatico, logout com limpeza de cookies, hook reativo e componente guard para protecao de rotas.

Proposito

Centralizar toda a logica de autenticacao em um pacote reutilizavel, consumido por todos os microfrontends e aplicacoes React da Zydon. Publicado no npm como @zydon/auth com acesso publico.

Funcionalidades Principais

• Autenticacao: Login via POST para /account/auth/login com credenciais (username/password)
• Gerenciamento de tokens: Armazenamento em localStorage, decodificacao JWT, refresh via cookies httpOnly
• Sincronizacao cross-tab: Eventos de storage sincronizam estado de autenticacao entre abas do navegador
• Modo embedded: Sessao isolada por aba (sessionStorage) para contextos embarcados em sistemas externos (ex: Sankhya), sem disputar localStorage/cookie com a sessao normal
• Event bus interno: Utiliza mitt para comunicacao reativa entre contextos React e nao-React
• Hook useAuth: Estado reativo de autenticacao com loading, erro, dados do usuario e funcoes de login/logout
• Componente <Authed>: Guard que renderiza children apenas quando autenticado, com suporte a auto-login em dev
• Multi-ambiente: Suporte a development, homologation, production, qa e staging

Arquitetura e Stack

Categoria	Tecnologia	Versao
Linguagem	TypeScript	5.5.4
Build tool	tsup	8.2.4
Formato de saida	ESM (index.mjs)	-
JWT decode	jwt-decode	4.0.0
Event bus	mitt	3.0.1
Cookies	universal-cookie	7.2.0
Peer dependencies	react, react-dom	>= 18.x
Linting	ESLint + Prettier	8.47.0 / 3.0.2
Testes	Jest (jsdom) + ts-jest	29.x

Estrutura do Projeto

auth-react/
  src/
    index.ts                    # Barrel export principal
    auth/
      auth.ts                   # Funcoes core (authenticate, refreshToken, getToken, setToken, logout, modo embedded, etc.)
      types.ts                  # Interfaces (AuthenticationData, AuthData, Auth, Mode)
      constants.ts              # Chaves de storage (REFRESH_TOKEN_KEY, USER_STORAGE_KEY, EMBEDDED_MODE_KEY)
      eventBus.ts               # Event bus tipado com mitt (setToken, logout)
      useAuth.ts                # Hook React para estado reativo de autenticacao
    components/
      index.ts                  # Barrel export de componentes
      Authed/
        index.tsx               # Componente guard de autenticacao
        props.ts                # AuthedProps interface
    utils/
      jwt.ts                    # Wrapper de decodificacao JWT
  devops/
    jenkins/
      build.Jenkinsfile         # Pipeline de build e publicacao no npm
  tsup.config.ts                # Configuracao do bundler (ESM, minificado, tree-shake)
  tsconfig.json                 # TypeScript config (target ESNext, strict)

API Publica

Funcoes

Funcao	Assinatura	Descricao
authenticate	(data: AuthenticationData, mode: string) => Promise<string>	Realiza login e retorna o token JWT
refreshToken	(mode: string) => Promise<string>	Renova token via cookie httpOnly de refresh
getToken	() => string | null	Obtem token atual do localStorage
setToken	(token: string) => void	Salva token e emite evento no bus
getAuthData	() => AuthData | null	Decodifica token atual e retorna dados do usuario
decodeToken	(token: string) => AuthData | null	Decodifica um token JWT especifico
logout	() => void	Remove token, cookie de refresh e emite evento. No modo embedded remove apenas o token da aba
enableEmbeddedMode	() => void	Marca a aba atual como sessao embedded (token passa a viver em sessionStorage)
disableEmbeddedMode	() => void	Remove a marcacao embedded e o token de sessao da aba
isEmbeddedMode	() => boolean	Indica se a aba atual esta em modo embedded
jwtDecode	<T>(token: string) => T	Re-export generico do jwt-decode

Hook

Hook	Retorno	Descricao
useAuth(mode)	{ loggingIn, loginError, isAuthenticated, authData, token, authentication, logout }	Estado reativo de autenticacao com funcoes de login e logout

Componente

Componente	Props	Descricao
<Authed>	mode, fallback?	Guard que protege children. Sem token, tenta hidratar a sessao via refresh token (cookie); senao renderiza fallback

Tipos Exportados

Tipo	Descricao
AuthData	Payload decodificado do JWT (sub, jti, iat, exp, organization_id, solution_id, aud, name, email, namespace, etc.)
AuthenticationData	{ username: string; password: string }
Auth	{ token: string; authData: AuthData }
AuthedProps	Props do componente <Authed>

Mapeamento de Ambientes

Modo	URL da API
development	http://localhost:8080/api
homologation	https://api-homologation.zydon.com.br/api
production	https://api.zydon.com.br/api
qa	https://api-homologation.zydon.com.br/api
staging	https://api-staging.zydon.com.br/api

Storage e Cookies

Chave	Tipo	Descricao
@auth.mfe/user	localStorage (sessionStorage no modo embedded)	Token JWT bruto
@auth.mfe/embedded	sessionStorage	Flag por aba indicando sessao embedded
refreshToken	Cookie (httpOnly)	Token de refresh definido pelo backend, removido no logout (preservado no modo embedded)

No modo embedded (enableEmbeddedMode), o token vive em sessionStorage (escopo por aba), a sincronizacao cross-tab e ignorada e refreshToken() e rejeitado — a re-autenticacao e responsabilidade do handshake com o sistema host (ex: postMessage do Sankhya).

Como Utilizar

Instalacao

yarn add @zydon/auth
# ou
npm install @zydon/auth

Funcoes standalone

import { authenticate, getToken, getAuthData, refreshToken, logout } from '@zydon/auth';

const token = await authenticate({ username: 'user', password: 'pass' }, 'production');
const userData = getAuthData(); // { name, email, organization_id, ... }
await refreshToken('production');
logout();

Hook React

import { useAuth } from '@zydon/auth';

const { isAuthenticated, authData, authentication, logout, loggingIn } = useAuth('production');

Componente guard

import { Authed } from '@zydon/auth';

<Authed mode="production" fallback={<LoginPage />}>
  <ProtectedApp />
</Authed>

Desenvolvimento

Pre-requisitos

• Node.js
• Yarn

Comandos

Comando	Descricao
yarn build	Compila a biblioteca com tsup (ESM, minificado, com types)
yarn test	Roda os testes unitarios (Jest + jsdom)
yarn lint	Verifica codigo com ESLint
yarn lint:fix	Corrige problemas de lint
yarn format	Formata com Prettier

Publicacao

A publicacao no npm e automatizada via Jenkins (devops/jenkins/build.Jenkinsfile):

1. Checkout e incremento automatico da versao patch
2. Build com yarn && yarn build
3. Publicacao no npm com NPM_TOKEN
4. Commit da versao atualizada no GitHub

Testando localmente

yarn build
npm link
# Em outro projeto:
npm link @zydon/auth