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
• 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 |

Estrutura do Projeto

auth-react/
  src/
    index.ts                    # Barrel export principal
    auth/
      auth.ts                   # Funcoes core (authenticate, refreshToken, getToken, setToken, logout, etc.)
      types.ts                  # Interfaces (AuthenticationData, AuthData, Auth, Mode)
      constants.ts              # Chaves de storage (REFRESH_TOKEN_KEY, USER_STORAGE_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 | | 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?, username?, password? | Guard que protege children. Suporta auto-login em dev via username/password |

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 | Token JWT bruto | | refreshToken | Cookie (httpOnly) | Token de refresh definido pelo backend, removido no logout |

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 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