# @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.

Latest version **2.1.9** (published 2026-09-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install @zydon/auth
pnpm add @zydon/auth
yarn add @zydon/auth
bun add @zydon/auth
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.1.9 |
| Published | 2026-09-07 |
| First published | 2023-08-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 14.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Zydon Tech |
| Maintainers | marcos.zydon, ti-zydon |

## Links

- npm: https://www.npmjs.com/package/@zydon/auth
- Homepage: https://github.com/zydontecnologia/auth-react#readme
- Issues: https://github.com/zydontecnologia/auth-react
- npm.io page: https://npm.io/package/@zydon/auth

## Dependencies (3)

- [mitt](https://npm.io/package/mitt.md) ^3.0.1
- [jwt-decode](https://npm.io/package/jwt-decode.md) ^4.0.0
- [universal-cookie](https://npm.io/package/universal-cookie.md) ^7.2.0

## Recent versions

- 2.1.9 (latest) — 2026-09-07
- 2.1.8 — 2026-09-01
- 2.1.7 — 2026-08-18
- 2.1.6 — 2026-08-18
- 2.1.5 — 2026-07-21
- 2.1.4 — 2026-07-18
- 2.1.3 — 2026-07-17
- 2.1.2 — 2026-06-22
- 2.1.1 — 2026-06-14
- 2.0.18 — 2026-02-09
- 2.0.17 — 2025-11-10
- 2.0.16 — 2025-10-22
- 2.0.15 — 2025-10-22
- 2.0.13 — 2025-10-03
- 2.0.12 — 2025-09-14
- … 90 more at https://npm.io/package/@zydon/auth/versions

## README

# 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

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

### Funcoes standalone

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

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

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

### Componente guard

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

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

---
_Source: https://npm.io/package/@zydon/auth · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._