# RiLiGar Auth — Documentação Completa (LLM-Ready, End-to-End)

> Este arquivo é a **documentação integral** do sistema RiLiGar Auth. Não há outra referência: ele deve conter tudo que um desenvolvedor humano ou um LLM precisa para integrar, operar e estender o sistema em produção.
>
> O sistema é composto por três partes principais:
> 1. **`@riligar/auth-react`** — SDK front-end (React + Mantine) com componentes UI, hooks, store e cliente HTTP.
> 2. **`@riligar/auth-elysia`** — Plugin back-end para ElysiaJS que valida JWT/JWKS e protege rotas.
> 3. **Auth Worker** (`auth.worker.myinfrastructure.click`) — API HTTP em Cloudflare Workers que emite/valida tokens e gerencia usuários, sessões e os códigos de acesso.
>
> 4. **Servidor MCP** (`auth.worker.myinfrastructure.click/mcp/<applicationId>`) — Model Context Protocol, revisão `2026-07-28`. Permite que agentes de IA administrem o tenant por linguagem natural, e usa o Auth como authorization server OAuth 2.1. **Documentação completa e separada em [/llms-mcp.txt](https://myinfrastructure.click/products/auth/llms-mcp.txt).**
>
> A base URL padrão da API é `https://auth.worker.myinfrastructure.click`. Autenticação de aplicação é feita via `X-API-Key: pu_...` (public key) no cliente e `X-API-Key: sk_...` (secret key) no servidor.
>
> ---
>
> **Verificado contra o código em 2026-09-04.** Trechos marcados com ⛔ descrevem recursos que **não existem** — o SDK exporta funções que chamam rotas mortas, e este arquivo diz quais são. Se você é um agente de IA integrando este sistema, leia a seção **8. Checklist para Implementação por IA** antes de escrever qualquer linha, e principalmente a subseção **"O que NÃO existe"**.

---

## 0. Credenciais — LEIA ANTES DE ESCREVER CÓDIGO

O Auth tem **três** identificadores, e eles não são intercambiáveis. Pedir o errado custa uma
volta inteira ao usuário. Descubra primeiro **o que você está construindo**:

| Se você vai... | Precisa de | Segredo? |
| :--- | :--- | :--- |
| Montar o `<AuthProvider>` no React | `pu_…` (public key) | Não — vai no bundle |
| Montar o `authPlugin()` no Elysia | `sk_…` (secret key) | **Sim** — só no servidor |
| Conectar um agente ao MCP do Auth | `applicationId` + OAuth | Não — login no navegador |
| **Ser um agente e ainda não ter conta nem chave** | **nada — use a entrada por código (abaixo)** | Não — um código de 8 caracteres |

**Uma integração completa (frontend + backend) precisa das duas chaves.** Peça as duas de uma
vez; não descubra a segunda na metade do trabalho.

### Via MCP (para administrar a aplicação) — nenhuma chave

Se o seu host suporta Model Context Protocol e o objetivo é **administrar** o tenant (listar
usuários, ver estatísticas, revogar sessões), **use MCP com OAuth 2.1**. Não peça chave: o
usuário loga no navegador e aprova os escopos.

```bash
claude mcp add --transport http riligar-auth \
  https://auth.worker.myinfrastructure.click/mcp/<applicationId>
```

> Preciso do ID da aplicação para conectar. Ele está no seu **dashboard**, nas **Chaves de
> API** da aplicação, aba **MCP** — o endereço mostrado já traz o ID no final. Pode colar o
> endereço inteiro. O login é no navegador, então não preciso de chave secreta.

⚠️ O MCP **administra**; ele **não** integra login no seu app. Para colocar signin/signup numa
aplicação React, o caminho é o SDK, e aí as chaves abaixo são necessárias.

### Via SDK — as chaves `pu_` e `sk_`

**Como pedir ao usuário** — use este texto:

> Preciso das chaves da sua aplicação no RiLiGar Auth. Elas estão no seu **dashboard**, nas
> **Chaves de API** da aplicação. Preciso das duas:
> - a **Chave Pública** (`pu_…`) — vai no frontend, no `<AuthProvider>`;
> - a **Chave Secret** (`sk_…`) — vai só no backend, numa variável de ambiente.
>
> Se já existirem, é só copiar. **Uma chave recém-criada só aparece por inteiro uma vez** —
> se essa janela já fechou, gere outra.

Regras que o agente não pode violar:

- **Nunca** coloque a `sk_` no frontend, em `VITE_*`, em `NEXT_PUBLIC_*` ou em qualquer
  arquivo que vá para o bundle. Ela assina sessões.
- A `pu_` é pública por natureza — pode ficar no código do cliente sem medo.
- Se o usuário mandar só uma chave e você precisa das duas, **pare e peça a outra**, dizendo
  qual das duas está faltando pelo prefixo.

### Você consegue obter as chaves sozinho — a entrada por código

**Se você é um agente e o usuário ainda não tem conta, ou não tem as chaves em mãos, você não
precisa parar.** A entrada leva você de "nenhuma credencial" a uma `pu_`/`sk_` funcionando
com **uma única interação humana**: a pessoa lê um código de 8 caracteres no e-mail e informa
a você. Depois disso, você cria organização, aplicação e chaves sozinho, por HTTP.

É o MESMO caminho que uma pessoa percorre no painel — não existe um fluxo para humanos e
outro para agentes. A única diferença é quem digita o código.

```
POST /auth/code/start    {email, name?}    → sent, expiresIn, interval, deviceCode
   ↓  a pessoa recebe um código de 8 caracteres por e-mail (ABCD-EFGH) e informa a você
POST /auth/code/verify   {email, code}     → {user, token, session}
   ↓  daqui em diante você vai sozinho:
POST /organizations      {name}                  → orgId
POST /application/:orgId {name}                   → applicationId
POST /api-keys           {applicationId, type}    → pu_ / sk_
```

**Como pedir o código** — use este texto:

> Mandei um código de 8 caracteres para o seu e-mail. Me diga qual é para eu liberar o
> acesso e seguir sozinho a partir daqui. Pode digitar como preferir — maiúsculas,
> minúsculas, com ou sem o hífen.

Detalhes que importam:

- **O e-mail não traz link, traz um código.** Não há URL para abrir, e portanto nada para
  copiar de um navegador. Foi desenhado assim de propósito (ver abaixo).
- **O código vale 10 minutos, cinco tentativas e uma vez só.** Cinco erros destroem o
  pedido (`429`); aí comece de novo pelo `start`. Cada erro devolve
  `details.attemptsLeft`.
- **O `verify` exige o e-mail junto com o código.** É o que amarra a aprovação a um
  pedido específico, em vez de a qualquer pedido do sistema.
- **Um `start` novo substitui o anterior do mesmo e-mail.** Só o código do último funciona.
- **Se o e-mail não puder ser enviado**, o `start` responde `503 SERVICE_UNAVAILABLE`
  com `retry-after`. Não é falha sua: espere e repita.
- **Não existe cadastro separado.** Se o e-mail nunca entrou, a conta nasce aqui — já
  verificada e com uma organização própria. Se já existe, entra. Você não precisa saber
  qual é o caso, e a resposta do `start` é a mesma nos dois.
- **A sessão que sai daqui é de plataforma** (`applicationId: null`) quando você não manda
  chave pública, que é o que dá acesso a criar organizações e aplicações. Guarde o token:
  ele vale 7 dias.

**Se você NÃO consegue receber o código** — um agente headless, sem ninguém para ler a caixa
de entrada na hora — existe a variante com polling, que segue o RFC 8628:

```
POST /auth/code/start    {email}           → deviceCode, interval
POST /auth/code/poll     {deviceCode}      → 428 enquanto ninguém apresentou o código
                                           → {user, token, session} quando alguém apresentou
```

Enquanto a pessoa não informar o código, o `poll` responde `428` com `authorization_pending`.
Faça poll a cada 5 segundos (o campo `details.interval` diz). Se vier `429 slow_down`, use o
`interval` novo da resposta — você está mais rápido que o combinado. **No navegador, use
`verify`**: ele resolve na mesma chamada, sem espera.

**Por que não há link no e-mail.** Um link precisaria de um endereço de retorno, e o Auth
grava a primeira origem que vê como a origem oficial da aplicação. Um endereço provisório
usado numa única vez ficaria fixado ali. Com um código, esse risco não existe: não há
destino para gravar, e não há callback para um atacante sequestrar.

**Endereços descartáveis nunca viram a identidade da aplicação.** Previews de deploy
(`*.pages.dev`, `*.vercel.app`, `*.netlify.app`, `*.workers.dev`, `*.fly.dev` e afins), túneis
de localhost (`*.ngrok-free.app`, `*.trycloudflare.com`, `*.loca.lt`) e domínios de
desenvolvimento (`.local`, `.test`) **funcionam normalmente para autenticar, mas não são
aprendidos** como a origem da aplicação. Você pode testar a integração por um preview sem
medo de fixar aquele endereço para o seu cliente. A origem real é aprendida no primeiro
acesso vindo de um domínio de verdade — ou definida por você, no painel.

**O que continua exigindo um humano:** só a leitura do código. Não há caminho que dispense
isso, e não deve haver — é a prova de que quem pediu o acesso alcança a caixa de e-mail.
Não invente rota de criação de chave, e não gere código com placeholder `pu_xxx` fingindo
que terminou.

---

## Sumário

0. **Credenciais — leia antes de escrever código** (qual chave pedir, e o texto do pedido)
1. Arquitetura e Fluxo End-to-End
2. Instalação e Requisitos
3. Pacote `@riligar/auth-react` — Referência Completa
   - 3.1 `AuthProvider` (configuração global)
   - 3.2 Hooks
   - 3.3 Componentes de Controle (render condicional)
   - 3.4 Componente de Proteção de Rota (`<Protect>`)
   - 3.5 Componentes de Formulário (SignIn, UserProfile)
   - 3.6 `<UserProfile>` e `<UserInformation>`
   - 3.7 Botões Unstyled
   - 3.8 Funções do SDK HTTP (`authSdk`)
   - 3.9 Store Zustand (`useAuthStore`)
   - 3.10 Tipos, Eventos, LocalStorage
   - 3.11 Nomes removidos na 4.0.0
4. Pacote `@riligar/auth-elysia` — Referência Completa
   - 4.1 `authPlugin` e `AuthConfig`
   - 4.2 Rotas auto-registradas
   - 4.3 Contexto derivado (`user`)
   - 4.4 `RiLiGarAuthClient` (JWKS + verificação JWT)
   - 4.5 `fetchAuth` helper
   - 4.6 Multi-tenancy e RBAC manual
5. Endpoints da API (contrato backend)
6. Blueprint de Rotas SaaS
7. Design System (Zen Aesthetics)
8. Checklist para Implementação por IA
9. Troubleshooting
10. Servidor MCP (documento separado)

---

## 1. Arquitetura e Fluxo End-to-End

```
┌─────────────────────┐          ┌──────────────────────┐          ┌─────────────────────┐
│  React App          │          │  Backend (Elysia)    │          │  Auth Worker        │
│  @riligar/auth-react│──────────▶│  @riligar/auth-elysia│──────────▶│  auth.worker...     │
│                     │  Bearer  │                      │  JWKS    │                     │
│  useAuth / SignIn   │  token   │  derive({user})      │  + API   │  /auth/* endpoints  │
│  + SDK HTTP         │          │  onBeforeHandle 401  │          │  /.well-known/jwks  │
└─────────────────────┘          └──────────────────────┘          └─────────────────────┘
         │                                  │                                  │
         │  X-API-Key: pu_... (public)      │  X-API-Key: sk_... (secret)      │
         │  Authorization: Bearer <jwt>     │  Authorization: Bearer <jwt>     │
         └──────────────────────────────────┴──────────────────────────────────┘
```

**Ciclo de autenticação típico (código por e-mail — o único que existe):**

1. App React monta `<AuthProvider apiKey="pu_...">`.
2. `AuthProvider` lê `localStorage["auth:token"]` e, se existir e for válido, hidrata `user` via `GET /auth/session`.
3. Também chama `GET /application/by-api-key` para obter logo/branding da aplicação.
4. Usuário informa o e-mail em `<SignIn />` → `POST /auth/code/start` → um código de 8 caracteres sai por e-mail.
4b. Usuário digita o código na MESMA aba → `POST /auth/code/verify` → resposta traz `{ token, user, session }`. Se a conta não existia, nasce aqui — verificada e com organização própria.
5. Token é gravado em `localStorage["auth:token"]` e um `storage` event sincroniza outras abas.
6. A cada 30s o SDK revalida a expiração do token; a cada 4 minutos, se faltar <5min para expirar, chama `POST /auth/refresh`, que rotaciona o token da sessão atual sem criar linha nova.
7. Requisições subsequentes ao seu backend levam `Authorization: Bearer <token>`.
8. Backend (Elysia) valida o token **localmente** via JWKS (cache 1h) ou faz fallback remoto para `GET /auth/session`. Injeta `user` no contexto.
9. Logout: `POST /auth/sign-out` → remove `auth:token` → dispara `storage` event (`auth:logout`) → outras abas deslogam.

**Eventos customizados:**

- `auth:session-revoked` (window) — disparado quando o usuário revoga a própria sessão; força signOut local.
- `storage` com key `auth:logout` — sincronização cross-tab de logout.
- `storage` com key `auth:token` — sincronização cross-tab de login/refresh.

---

## 2. Instalação e Requisitos

### Frontend (React)

```bash
npm install @riligar/auth-react
npm install react react-dom react-router-dom zustand
npm install @mantine/core @mantine/form @mantine/hooks @tabler/icons-react
```

**Peer dependencies:**

| Dependência | Versão |
| :--- | :--- |
| `react` | `^18.0.0 \|\| ^19.0.0` (obrigatório) |
| `react-dom` | `^18.0.0 \|\| ^19.0.0` (obrigatório) |
| `react-router-dom` | `^6.0.0 \|\| ^7.0.0` (obrigatório) |
| `zustand` | `^5.0.0` (obrigatório) |
| `@mantine/core` | `^8.0.0` (opcional — necessário para usar componentes UI) |
| `@mantine/form` | `^8.0.0` (opcional) |
| `@mantine/hooks` | `^8.0.0` (opcional) |
| `@tabler/icons-react` | `^3.0.0` (opcional) |

### Backend (Elysia)

```bash
bun add @riligar/auth-elysia elysia
```

Peer: `elysia >= 1.0.0`.

**Variáveis de ambiente (backend):**

```bash
AUTH_SECRET_KEY=sk_...                            # secret key da aplicação (HS256)
AUTH_API_URL=https://auth.worker.myinfrastructure.click    # base URL do Auth Worker
NODE_ENV=production                               # ativa cookie.secure=true
```

---

## 3. Pacote `@riligar/auth-react` — Referência Completa

**Exports do entry point** (`src/index.js`):

- Funções SDK: `configure`, `isInternal`, `getApiUrl`, `decodeJWT`, `isAuthenticated`, `getCurrentUser`, `requestCode`, `verifyCode`, `pollCode`, `signOut`, `refreshToken`, `getSession`, `listSessions`, `revokeSession`, `revokeOtherSessions`, `getApplicationInfo`, `updateProfile`, `setStoredToken`.
- Store: `useAuthStore`.
- Provider + Hooks: `AuthProvider`, `useAuth`, `useSignIn`, `useSignOut`, `useCheckToken`, `useSession`, `useSessions`, `useAuthLoading`, `useUser`, `useApplicationLogo`.
- Proteção: `Protect`.
- Componentes UI: `AuthCard`, `SignIn`, `UserProfile`, `UserInformation`, `Wordmark`.
- Controle: `SignedIn`, `SignedOut`, `AuthLoading`, `AuthLoaded`.
- Unstyled: `SignInButton`, `SignOutButton`.
- Redirect: `resolveRedirect`, `applyRedirect`, `getRedirectFromLocation`.

**A 4.0.0 removeu os aliases depreciados** (`SignInForm`, `AccountModal`, `ProtectedRoute`,
`useProfile`…) junto com os componentes e funções dos fluxos de senha e link. Se o seu código
importa algum deles, troque pelo nome canônico da lista acima.

---

### 3.1 `AuthProvider`

Envolve a raiz da aplicação. Inicializa o SDK, hidrata sessão, inicia o refresh loop e sincroniza abas.

**Props:**

| Prop | Tipo | Default | Descrição |
| :--- | :--- | :--- | :--- |
| `children` | `ReactNode` | — | Obrigatório. |
| `apiKey` | `string` | — | Public key `pu_...`. Obrigatório, exceto quando `internal=true`. Enviado como header `X-API-Key`. |
| `apiUrl` | `string` | `"https://auth.worker.myinfrastructure.click"` | Override da base URL da API. |
| `internal` | `boolean` | `false` | Quando `true`, dispensa `apiKey` (app same-domain com o Auth Worker). |
| `onError` | `(error) => void` | — | Callback global de erro. |

**Exemplo:**

```jsx
import { AuthProvider } from '@riligar/auth-react'

<AuthProvider
  apiKey={import.meta.env.VITE_AUTH_PUBLIC_KEY}
  apiUrl="https://auth.worker.myinfrastructure.click"
  onError={(err) => console.error('[Auth]', err)}
>
  <App />
</AuthProvider>
```

**Comportamento interno:**

- `init()` ao montar: lê token, valida expiração, chama `GET /auth/session` se válido.
- `startRefresh()`: `setInterval` de 30s para checar validade; refresh 4 minutos antes da expiração.
- Listener `storage`: reage a `auth:logout` e `auth:token` para manter todas as abas em sincronia.
- Listener `auth:session-revoked`: força logout local quando o servidor indica revogação.

---

### 3.2 Hooks

Todos usam `zustand/react/shallow` para evitar re-renders desnecessários.

#### `useAuth()`

Hook central. **Retorna:**

```ts
{
  user: User | null,
  loading: boolean,
  error: Error | null,
  isAuthenticated: boolean,          // user !== null
  requestCode: (email, opts?) => Promise<{ sent, expiresIn, interval, deviceCode }>,
  verifyCode: (email, code) => Promise<{ token, user, session }>,
  signOut: () => Promise<void>,
}
```

#### `useSignIn()`

Os dois passos da entrada, e nada mais.

```ts
{
  requestCode: (email: string, opts?: { name?: string }) => Promise<{ sent, expiresIn, interval, deviceCode }>,
  verifyCode: (email: string, code: string) => Promise<{ token, user, session }>,
  sending: boolean,        // requestCode em andamento
  verifying: boolean,      // verifyCode em andamento
  error: Error | null,
}
```

Não há `useSignUp`: a conta nasce no primeiro `verifyCode`, já verificada e com uma
organização própria. E não há `useMagicLink`, `usePasswordReset` nem `useEmailVerification` —
os três fluxos saíram.

#### `useSignOut()`

Retorna: `() => Promise<void>`.

#### `useCheckToken()`

Retorna: `() => boolean`. Verifica se o token armazenado ainda é válido (não expirado).

#### `useSession()`

```ts
{
  getSession: () => Promise<{ user, session, application }>,
  user: User | null,
  setUser: (user | null) => void,
}
```

#### `useSessions()`

Gestão multi-device.

```ts
{
  currentSession: Session | null,
  sessions: Session[],
  getSession: () => Promise,
  listSessions: () => Promise<Session[]>,
  revokeSession: (sessionId: string) => Promise,
  revokeOtherSessions: () => Promise,
  loadingListSessions: boolean,
  loadingRevokeSession: null | string | 'all',   // id específico, 'all', ou null
  error: Error | null,
}
```

#### `useAuthLoading()`

Flags granulares de loading por operação:

```ts
{
  requestCode, verifyCode, signOut,
  updateProfile, listSessions,                    // boolean
  revokeSession: null | string | 'all',
}
```

Todos `boolean`, exceto `revokeSession`.

#### `useUser()`

```ts
{
  user: User | null,
  updateProfile: (data: Partial<User>) => Promise,
  changePassword: (currentPassword, newPassword, revokeOtherSessions?: boolean) => Promise,
  changeEmail: (newEmail: string, callbackURL?: string) => Promise,
  loadingUpdateProfile: boolean,
  loadingChangePassword: boolean,
  loadingChangeEmail: boolean,
  error: Error | null,
}
```

#### `useApplicationLogo()`

Retorna: `string | null`. URL/data-URI do logo da aplicação carregado via `GET /application/by-api-key`.

#### `useAuthStore()`

Acesso direto ao store Zustand (ver §3.9). Exportado, mas raramente necessário em componentes.

---

### 3.3 Componentes de Controle

Renderização condicional baseada em estado de autenticação.

| Componente | Renderiza `children` quando |
| :--- | :--- |
| `<SignedIn>` | `user !== null` **e** `loading === false` |
| `<SignedOut>` | `user === null` **e** `loading === false` |
| `<AuthLoading>` | `loading === true` |
| `<AuthLoaded>` | `loading === false` |

**Todos aceitam apenas:** `children: ReactNode`.

```jsx
<SignedIn><NotificationBell /></SignedIn>
<SignedOut><CTAButton /></SignedOut>
<AuthLoading><Spinner /></AuthLoading>
```

---

### 3.4 `<Protect>` — Guarda de Rota (React Router)

| Prop | Tipo | Default | Descrição |
| :--- | :--- | :--- | :--- |
| `fallback` | `ReactNode` | `<p>⌛ Carregando...</p>` | Exibido enquanto `loading`. |
| `redirectTo` | `string` | `'/login'` | Rota para `<Navigate>` se não autenticado. |

Renderiza `<Outlet />` quando autenticado.

```jsx
<Routes>
  <Route element={<Protect redirectTo="/auth/signin" />}>
    <Route path="/dashboard" element={<Dashboard />} />
    <Route path="/admin"     element={<AdminPanel />} />
  </Route>
</Routes>
```

---

### 3.5 Componentes de Formulário

**Convenções comuns a todos:**

- `variant: 'card' | 'modal'` — default: `'card'`.
- Se `variant='modal'`: `opened: boolean`, `onClose: () => void`, `modalProps?: object` (spread em `<Modal>` da Mantine).
- `logo?: string`, `logoWidth?: number` (default 133) — sobrescrevem o logo da aplicação.
- `labels?: object` — todos os textos são customizáveis (localização/tom).
- Props extras fazem spread no `AuthCard` (Paper ou Modal).

#### `<AuthCard>`

Wrapper genérico (usado internamente por todos os formulários).

| Prop | Tipo | Default |
| :--- | :--- | :--- |
| `children` | `ReactNode` | — |
| `title` | `string` | — |
| `subtitle` | `string` | — |
| `logo` | `string` | — |
| `logoWidth` | `number` | `133` |
| `width` | `number` | `350` |
| `variant` | `'card' \| 'modal'` | `'card'` |
| `opened` / `onClose` / `modalProps` | — | — |

#### `<SignIn>`

A tela de entrada inteira: pede o e-mail, depois recebe o código. Os dois passos na mesma
rota, sem navegação no meio.

| Prop | Tipo | Default |
| :--- | :--- | :--- |
| `title` | `string` | `'Entrar'` |
| `subtitle` | `string` | `'Enviamos um código para o seu e-mail'` |
| `logo` / `logoWidth` | — | logo da aplicação, ou o Wordmark |
| `variant` | `'card' \| 'modal'` | `'card'` |
| `opened` / `onClose` / `modalProps` | — | só em `variant="modal"` |
| `authenticatedRedirect` | `string \| null` | `'/'` — para onde mandar quem já tem sessão |
| `redirectingFallback` | `node` | `null` — o que mostrar durante o desvio |
| `handleRedirect` | `boolean` | `true` — honra `?redirect=` da URL |
| `redirectOrigins` | `string[]` | `[]` — origens extras permitidas no redirect |
| `onCodeSent(email)` | `fn` | — |
| `onSuccess(user, { result, redirectHandled })` | `fn` | — |
| `onError(error)` | `fn` | — |
| `labels` | `object` | ver abaixo |

**Labels de `<SignIn>`:** `email`, `emailPlaceholder`, `emailRequired`, `invalidEmail`,
`sendCodeButton`, `sendingCode`, `codeSentTo`, `codeLabel`, `verifyingCode`, `invalidCode`,
`resendCode`, `changeEmail`.

**`redirectHandled`** diz que o SDK já assumiu a navegação — é o fluxo OAuth voltando ao
ponto de origem. Quando vier `true`, não navegue no `onSuccess`: você levaria o usuário para
a home no meio da autorização.

**Não existem `<SignUp>`, `<MagicLink>`, `<MagicLinkCallback>`, `<ForgotPassword>`,
`<ResetPassword>` nem `<VerifyEmail>`.** Saíram na 4.0.0. A conta nasce no primeiro código
apresentado, então cadastro e verificação deixaram de ser telas.

#### `<UserProfile>`

Modal/card completo de gestão de conta. Seções: Avatar, Nome, Email (somente leitura) e Sessões.

**Props principais:**

| Prop | Tipo | Default |
| :--- | :--- | :--- |
| `variant` | `'card' \| 'modal'` | `'modal'` |
| `opened` / `onClose` | — | controla o modal |
| `title` | `string` | `'Account'` |
| `subtitle` | `string` | `'Manage your account info.'` |
| `logo` / `logoHeight` | `string / number` | — / `28` |
| `width` | `number` | `500` |
| `maxAvatarSize` | `number` (bytes) | `512000` (500 KB) |
| `showAvatar` / `showName` / `showEmail` / `showSessions` | `boolean` | `true` |
| `customSections` | `ReactNode` | — (renderizado após seções built-in) |

**Callbacks:** `onProfileUpdate(data)`, `onSessionRevoked(sessionId)`, `onOtherSessionsRevoked()`, `onError(err)`.

**Comportamento:**

- Avatar é enviado como base64 (validado contra `maxAvatarSize`).
- Seção de sessões lista `GET /auth/list-sessions` com parsing de user-agent; destaca "Este dispositivo".
- **O e-mail não se edita**: é ele que recebe o código de acesso, então trocá-lo é trocar de
  identidade — e isso exige provar a posse da caixa nova, que é o próprio fluxo de entrada.
- Não há seção de senha: não há senha.

**Labels** (extenso — ver código para lista completa): `avatar`, `update`, `updateAvatar`, `clickToChange`, `avatarRequired`, `avatarInvalidType`, `avatarTooLarge`, `avatarHint`, `remove`, `cancel`, `save`, `name`, `change`, `changeName`, `namePlaceholder`, `nameRequired`, `notDefined`, `email`, `sessions`, `manage`, `manageSessions`, `close`, `loadingSessions`, `noSessionsFound`, `endSession`, `signOutAndEnd`, `end`, `endOtherSessions`, `thisDevice`, `unknownIP`, `createdAt`, `at`, `profileSection`, `profileDescription`, `securitySection`, `securityDescription`.

#### `<UserInformation>`

Bloco compacto (header/sidebar/menu) com avatar + nome + email + signOut.

| Prop | Tipo | Default |
| :--- | :--- | :--- |
| `user` | `User` | obrigatório |
| `signOut` | `() => void` | obrigatório |
| `onAccountClick` / `onBillingClick` | `fn` | — |
| `accountLabel` | `string` | `'Conta'` |
| `billingLabel` | `string` | `'Assinatura'` |
| `padded` | `boolean` | `true` |
| `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` |

Inclui rodapé "Secured by Auth".

---

### 3.7 Botões Unstyled

Elementos `<button>` nativos, sem estilo, para uso em UIs próprias.

| Componente | Prop | Default |
| :--- | :--- | :--- |
| `<SignInButton>` | `redirectTo` | `'/login'` |
| `<SignOutButton>` | `onSignOut?: () => void` | — |

Todos aceitam `children` (texto) e fazem spread em `<button {...props}>`. Navegação via `useNavigate()` do React Router.

---

### 3.8 Funções do SDK HTTP (`authSdk`)

Exportadas diretamente de `@riligar/auth-react`. Use-as quando não quiser os hooks (ex: fora de componentes React).

| Função | Método + Endpoint | Retorno |
| :--- | :--- | :--- |
| `configure({ apiKey, apiUrl, internal })` | — | void |
| `isInternal()` | — | `boolean` |
| `decodeJWT(token)` | decodifica payload (sem verificar assinatura) | `object \| null` |
| `isAuthenticated()` | checa token + expiração locais | `boolean` |
| `requestCode(email, { name? })` | `POST /auth/code/start` | `{ sent, expiresIn, interval, deviceCode }` |
| `verifyCode(email, code)` | `POST /auth/code/verify` | `{ token, user, session }` — cria a conta se ela não existir |
| `pollCode(deviceCode)` | `POST /auth/code/poll` | `{ token, user, session }` ou `{ pending: true, interval }`. Só para quem não lê o e-mail |
| `signOut()` | `POST /auth/sign-out` | — (sempre limpa token local) |
| `refreshToken()` | `POST /auth/refresh` | `{ token, user, session }` |
| `getSession()` | `GET /auth/session` | `{ user, session, application }` |
| `listSessions()` | `GET /auth/list-sessions` | `Session[] \| null` |
| `revokeSession(id)` | `POST /auth/revoke-session-by-id` | result |
| `revokeOtherSessions()` | `POST /auth/revoke-other-sessions` | result |
| `updateProfile(data)` | `POST /auth/update-user` | result — só `name` e `image` |
| `getApplicationInfo()` | `GET /application/by-api-key` | appInfo ou null |

**Não existe `signUp`, `signIn`, `sendMagicLink`, `forgotPassword`, `resetPassword`,
`verifyEmail`, `resendVerification`, `changePassword` nem `changeEmail`.** Saíram na 4.0.0
junto com as rotas que chamavam. Quem entra usa `requestCode` + `verifyCode` — os dois, e
nada mais.

**Não há defaults de callback.** Nenhuma função monta URL de retorno, porque nenhum e-mail
leva link — é o que elimina, por construção, a família de bugs de origem e redirect.

---

### 3.9 Store Zustand (`useAuthStore`)

Forma completa do state (acessível via `useAuthStore()`):

```ts
{
  // Estado
  user: User | null,
  loading: boolean,
  error: Error | null,
  sessions: Session[],
  currentSession: Session | null,
  applicationInfo: { image?: string, [k:string]: any } | null,

  // Loading granular
  loadingStates: {
    requestCode, verifyCode, signOut,
    updateProfile, listSessions,         // boolean
    revokeSession: null | string | 'all',
  },

  // Ações (internas — prefira os hooks)
  setLoading(key, value),
  fetchApplicationInfo(),
  init(),
  requestCode(email, { name }),
  verifyCode(email, code),
  signOut(),
  getSession(),
  listSessions(),
  revokeSession(sessionId),
  revokeOtherSessions(),
  startRefresh(),
  checkTokenValidity(),
  setUser(user),
  updateProfile(data),
}
```

---

### 3.10 Tipos, Eventos, LocalStorage

**User:**

```ts
interface User {
  id: string
  email: string
  name?: string
  image?: string           // avatar (URL ou data-URI base64)
  // + demais claims do JWT
}
```

**Session:**

```ts
interface Session {
  id: string
  createdAt: string        // ISO 8601
  userAgent: string
  ipAddress: string
}
```

**LocalStorage keys:**

- `auth:token` — token JWT atual.
- `auth:logout` — timestamp escrito no logout (sinal cross-tab).

**Eventos do `window`:**

- `storage` com `key === 'auth:token'` ou `'auth:logout'` — sincronização cross-tab.
- `auth:session-revoked` (custom) — força signOut no cliente quando o servidor revoga a sessão.

**Cache JWKS (frontend):** 5 minutos em memória para `GET /.well-known/jwks.json`.

---

### 3.11 Nomes removidos na 4.0.0

Os aliases de compatibilidade saíram junto com os componentes que apontavam para fluxos que
não existem mais. Se o seu código importa um destes, o build quebra — troque pelo nome atual.

| Removido | O que usar |
| :--- | :--- |
| `SignInForm` | `SignIn` |
| `AccountModal` | `UserProfile` |
| `ProtectedRoute` | `Protect` |
| `useProfile` | `useUser` |
| `SignUpForm`, `SignUp`, `SignUpButton` | `SignIn` — a conta nasce na primeira entrada |
| `MagicLinkForm`, `MagicLink`, `MagicLinkVerify`, `MagicLinkCallback` | `SignIn` |
| `ForgotPasswordForm`, `ForgotPassword` | — não há senha |
| `ResetPasswordForm`, `ResetPassword` | — não há senha |
| `VerifyEmailCard`, `VerifyEmail` | — apresentar o código já verifica |

---

## 4. Pacote `@riligar/auth-elysia` — Referência Completa

**Exports do entry point** (`src/index.js`):

- `authPlugin(config?)` — plugin Elysia (também export default).
- `DEFAULT_CONFIG` — objeto de configuração padrão.
- `fetchAuth(url, options?)` — helper HTTP.
- `RiLiGarAuthClient` — classe de verificação JWT/JWKS.

### 4.1 `authPlugin(config?)` e `AuthConfig`

```ts
interface AuthConfig {
  prefix?: string                                    // default: '/auth'
  secretKey?: string                                 // default: process.env.AUTH_SECRET_KEY || 'your-secret-key'
  apiUrl?: string                                    // default: process.env.AUTH_API_URL || 'http://auth.worker.myinfrastructure.click'
  cookieName?: string                                // default: 'auth-token'
  cookieOptions?: {
    httpOnly?: boolean                               // default: true
    secure?: boolean                                 // default: NODE_ENV === 'production'
    sameSite?: 'strict' | 'lax' | 'none'            // default: 'lax'
    maxAge?: number                                  // default: 604800 (7 dias)
  }
  excludePaths?: string[]                            // default: ['/auth/login', '/auth/register', '/auth/session']
  onUnauthorized?: (set) => any                      // default: retorna JSON { success:false, error:{code:'UNAUTHORIZED', message:'...'} } com status 401
}
```

**Uso canônico:**

```js
import { Elysia } from 'elysia'
import { authPlugin } from '@riligar/auth-elysia'

const app = new Elysia()
  .use(authPlugin({
    apiUrl: process.env.AUTH_API_URL,
    secretKey: process.env.AUTH_SECRET_KEY,
    prefix: '/auth',
    excludePaths: ['/', '/health', '/products', '/auth/*'],
  }))

  // Público (em excludePaths)
  .get('/',       () => ({ message: 'Welcome' }))
  .get('/health', () => ({ status: 'ok' }))

  // Protegido (user injetado automaticamente)
  .get('/profile', ({ user }) => ({ id: user.id, name: user.name, email: user.email }))
  .post('/orders', ({ user, body }) => ({ userId: user.id, order: body }))

  .listen(3000)
```

**Fluxo de execução interno (hooks scoped):**

1. `.derive({ as: 'scoped' }, ...)` — extrai token de `cookie[cookieName].value` ou `Authorization: Bearer <token>`; valida via `RiLiGarAuthClient.verifySession(token)`; adiciona `{ user }` ao contexto.
2. `.onBeforeHandle({ as: 'scoped' }, ...)` — se o path **não** estiver em `excludePaths` e `user === null`, executa `onUnauthorized(set)` (401 JSON).
3. `.error(...)` — captura erros que referenciam `user.id`/`null`/`undefined` e padroniza como 401 JSON.
4. `.group(prefix, ...)` — registra 4 rotas (ver 4.2).

### 4.2 Rotas auto-registradas (sob `config.prefix`)

| Rota | Backend chamado | Body | Comportamento |
| :--- | :--- | :--- | :--- |
| `POST /auth/code/start` | `POST {apiUrl}/auth/code/start` | `{ email, name? }` | Manda o código por e-mail; retorna `{ sent, expiresIn, interval, deviceCode }`. 400 em falha. |
| `POST /auth/code/verify` | `POST {apiUrl}/auth/code/verify` | `{ email, code }` | Seta cookie `cookieName` com opções; retorna `{ user, token }`. 401 em falha. |
| `POST /auth/logout` | — | — | Remove o cookie `cookieName`. Retorna `'Sessão encerrada.'`. |
| `GET /auth/me` | — | — | Retorna `user` ou `onUnauthorized(set)`. |

`/auth/session` **não** é registrado pelo plugin; é responsabilidade do Auth Worker.

### 4.3 Contexto derivado

Todo handler passa a receber:

```ts
{ user: User | null }
```

Onde `User` é:

```ts
interface User {
  id: string                   // mapeado do claim JWT 'sub'
  email: string
  name?: string
  role?: string                // ⚠️ hoje é SEMPRE a string 'user'
  permissions?: string[]       // ⛔ hoje SEMPRE undefined — não está no JWT
  memberships?: Array<{        // ⛔ hoje SEMPRE undefined — não está no JWT
    organizationId: string
    role: string
    organization?: { id: string, name: string, [k:string]: any }
  }>
  iat?: number
  exp?: number
  iss?: string
  sub?: string
  [k: string]: any
}
```

### 4.4 `RiLiGarAuthClient`

Classe utilitária usada internamente; pode ser importada diretamente para casos avançados.

```ts
class RiLiGarAuthClient {
  constructor(baseUrl: string, secretKey: string)
  getJWKS(): Promise<{ keys: JWK[] } | null>       // cache 1h
  verifyJWTLocal(token: string): Promise<{ id, ...payload } | null>
  verifySession(token: string): Promise<{ user } | null>  // local → fallback remoto
}
```

**Algoritmo de `verifyJWTLocal`:**

1. Busca JWKS (cache 1h).
2. Decodifica header, casa `kid`/`alg` com um JWK.
3. Verifica assinatura:
   - **HS256:** `crypto.subtle.importKey('raw', ...)` com `secretKey`.
   - **RS256:** `crypto.subtle.importKey('jwk', ...)` com chave pública JWK.
4. Checa expiração (`exp`).
5. Retorna `{ id: payload.sub, ...payload }` ou `null`.

**`verifySession`:** tenta local; se falhar, faz `GET {baseUrl}/auth/session` com `Authorization: Bearer` + `X-API-Key: secretKey`.

### 4.5 `fetchAuth(url, options?)`

```js
async function fetchAuth(url, options = {}) {
  const res = await fetch(url, {
    headers: { 'Content-Type': 'application/json', ...options.headers },
    ...options,
  })
  if (!res.ok) throw new Error(res.status)
  return await res.json()
}
```

Helper JSON mínimo. Usado internamente em `/auth/login` e `/auth/register`, mas exportado para chamadas custom a outros endpoints da API.

### 4.6 Multi-tenancy e RBAC manual

> ⚠️ **ESTADO REAL EM 2026-08-17 — LEIA ANTES DE GERAR CÓDIGO.**
>
> O JWT emitido hoje **não carrega `memberships`, `organizationId` nem `permissions`.** O payload assinado é exatamente `{ role, email, name }` + `sub`/`iat`/`iss`/`exp`, e **`role` é sempre a string literal `'user'`** — não existe coluna `role` na tabela `users`.
>
> Portanto `user.memberships` é **sempre `undefined`** e `user.role` é **sempre `'user'`**. Os exemplos abaixo mostram o padrão de autorização para quando esses claims existirem, mas **hoje eles não existem**: um `find()` em `user.memberships` vai quebrar, e um `if (user.role !== 'admin')` vai barrar todo mundo.
>
> **O que existe hoje:** isolamento por **aplicação** — cada usuário pertence a uma `applicationId`, com chave única `(email, applicationId)`. Organizações, membros e papéis existem no banco e no painel administrativo, mas **não são expostos ao usuário final via SDK ou JWT**.
>
> **Instrução para agentes de IA:** não gere código que dependa de `user.memberships`, `user.role` ou `user.permissions`. Para autorização por organização hoje, mantenha a relação usuário↔organização no seu próprio banco.

O plugin injeta `user.memberships` e `user.role`/`user.permissions` **quando presentes no JWT** (hoje: nunca — ver aviso acima). Autorização por organização/role é **manual** no handler:

```js
// Acesso por organização
.post('/organizations/:orgId/orders', ({ params, body, user, set }) => {
  const m = user.memberships?.find(x => x.organizationId === params.orgId)
  if (!m) { set.status = 403; return { error: 'Sem permissão para esta organização' } }
  return { message: 'Order created', order: body }
})

// Acesso por role/permissions
.get('/admin/stats', ({ user, set }) => {
  if (user.role !== 'admin' && !user.permissions?.includes('admin:read')) {
    set.status = 403
    return { error: 'Admin access required' }
  }
  return { stats: { /* ... */ } }
})
```

---

## 5. Endpoints da API (contrato backend — Auth Worker)

Todos os endpoints aceitam `X-API-Key` (pu_ do frontend ou sk_ do backend). Protegidos exigem `Authorization: Bearer <token>`.

### Autenticação

| Método | Endpoint | Body | Resposta |
| :--- | :--- | :--- | :--- |
| `POST` | `/auth/code/start` | `{ email, name? }` | `{ sent: true, expiresIn, interval, deviceCode }` — `400 VALIDATION_ERROR`, `503 SERVICE_UNAVAILABLE` |
| `POST` | `/auth/code/verify` | `{ email, code }` | `{ token, user, session }` — cria a conta se ela não existir |
| `POST` | `/auth/code/poll` | `{ deviceCode }` | `{ token, user, session }` — ou `428` / `429`. Só para quem não consegue ler o e-mail |
| `POST` | `/auth/sign-out` | — | `{ signedOut: true }` |
| `POST` | `/auth/refresh` | — | `{ token, user, session }` — rotaciona o token da sessão atual |

**Não há outra forma de autenticar.** Senha, link mágico, cadastro separado, recuperação de
senha e verificação de e-mail não existem — os quatro respondiam à mesma pergunta ("esta
pessoa controla esta caixa de entrada?") e três respondiam com uma URL, que é de onde vinham
os bugs de origem e redirect. O código responde sem URL nenhuma.

Erros do `verify`: `VALIDATION_ERROR` (400, código inválido — com `details.attemptsLeft`; ou
expirado, 410) e `TOO_MANY_REQUESTS` (429, após 5 erros — o pedido foi destruído).
Erros do `poll`: `authorization_pending` (428, ainda não apresentado — siga no poll),
`slow_down` (429, poll rápido demais — use `details.interval`), `expired_token` (400, passou
dos 10 min), `access_denied` (400, código inválido, já usado, ou consumido por outro poll).

### Sessão e Perfil

| `GET`  | `/auth/session` | — | `{ user, session, application }` |
| `GET`  | `/auth/list-sessions` | — | `Session[]` |
| `POST` | `/auth/revoke-session-by-id` | `{ id }` | result |
| `POST` | `/auth/revoke-other-sessions` | — | result |
| `POST` | `/auth/update-user` | `Partial<User>` | result — só `name` e `image` |
| `GET`  | `/auth/list-connections` | — | `{ items: Connection[] }` — integrações OAuth autorizadas |
| `POST` | `/auth/revoke-connection` | `{ connectionId }` | result |

O e-mail não se troca: é ele que recebe o código, então trocá-lo é trocar de identidade — e
isso exige provar a posse da caixa nova, que é o próprio fluxo de entrada.

### Aplicação / Infra

| `GET`  | `/application/by-api-key` | — | `{ data: { image?, ... } }` |
| `GET`  | `/.well-known/jwks.json` | — | `{ keys: JWK[] }` |

### ⛔ Rotas não implementadas — NÃO GERE CÓDIGO QUE AS CHAME

Estas funções saíram do SDK na **4.0.0**, junto com as rotas que chamavam. Se você viu uma
delas em código antigo ou em documentação desatualizada, ela não existe mais.

| Função removida | O que fazer |
| :--- | :--- |
| `signUp()`, `signIn()` | `requestCode(email)` e depois `verifyCode(email, code)`. Não há cadastro separado |
| `sendMagicLink()`, `verifyMagicLink()` | idem — o código substitui o link |
| `forgotPassword()`, `resetPassword()` | não há senha para recuperar |
| `verifyEmail()`, `resendVerification()` | apresentar o código já verifica o e-mail |
| `changePassword()` | não há senha |
| `changeEmail()` | o e-mail é a credencial; trocá-lo é entrar com o novo |
| `socialRedirect()` | nunca existiu no worker (**404**) — não há login social |

`refreshToken()` **continua existindo e funcionando** (`POST /auth/refresh`, rotaciona o token
da sessão atual). Versões anteriores deste documento diziam que a rota respondia 404; era
erro do documento, não do worker — há teste na suíte que segura isso.

**Instrução para agentes de IA:** ao integrar, a entrada é `requestCode` + `verifyCode`, e mais nada. Não construa tela de cadastro, de senha, de recuperação, de "trocar e-mail" ou botão de login social — nenhum existe.

---

## 6. Blueprint de Rotas SaaS

Estrutura recomendada para um app React + React Router. **Uma tela de entrada, não seis** —
`<SignIn />` cobre os dois passos (pedir o código e apresentá-lo) na mesma rota, sem
navegação no meio.

| Rota | Componente | Função |
| :--- | :--- | :--- |
| `/auth/signin` | `<SignIn />` | Entrar — e criar a conta, se for a primeira vez |
| `/profile` | `<UserProfile variant="card" />` | Conta do usuário |
| `/dashboard`, `/admin`, etc. | protegidos por `<Protect redirectTo="/auth/signin" />` | — |

Não crie rota para cadastro, link mágico, recuperação de senha ou verificação de e-mail:
os componentes não existem mais, e as rotas do worker que eles chamavam também não.

**Exemplo de roteamento:**

```jsx
<BrowserRouter>
  <AuthProvider apiKey={KEY}>
    <Routes>
      <Route path="/auth/signin" element={<SignIn />} />

      <Route element={<Protect redirectTo="/auth/signin" />}>
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/profile"   element={<UserProfile variant="card" />} />
      </Route>
    </Routes>
  </AuthProvider>
</BrowserRouter>
```

---

## 7. Design System (Zen Aesthetics)

Todo componente UI segue estas regras — LLMs devem preservá-las ao gerar overrides:

- **Bordas:** sempre `radius: 0` (sharp corners).
- **Cores:** apenas tons de cinza + preto + branco (`gray.0` a `gray.9`).
- **Tipografia de títulos:** uppercase, `letter-spacing: 2px–4px`.
- **Botões:** variantes sólidas (fundo preto) ou outline (borda 1px).
- **Sombras:** nenhuma; hierarquia via borda e espaçamento.

Customizações adicionais devem ser feitas via props (`width`, `logoWidth`, `labels`) ou via spread para o `AuthCard`/Paper/Modal subjacentes. Não há prop `appearance` embutida no SDK — para temas, use o `MantineProvider` envolvendo o `AuthProvider`.

---

## 8. Checklist para Implementação por IA

Ao ser solicitado a integrar o RiLiGar Auth:

1. **Pedir as chaves antes de começar** — a Public Key (`pu_...`) para o `<AuthProvider apiKey>` e, se houver backend Elysia, também a Secret Key (`sk_...`). O texto exato do pedido e o caminho no painel estão no **§0. Credenciais**. Se faltar uma delas, pare e peça: não siga com placeholder.
2. Garantir `BrowserRouter` (ou equivalente) **por fora** do `AuthProvider`; os componentes usam `useNavigate`.
3. Criar as rotas do §6 (signin, profile) — são duas; não há tela de cadastro nem de recuperação.
4. Envolver áreas privadas com `<Protect redirectTo="/auth/signin" />`.
5. Usar `<SignedIn>` / `<SignedOut>` para navegação condicional (header, menu).
6. Para perfil/sessões: `<UserProfile variant="card" />` ou componentes próprios usando `useUser` + `useSessions`.
7. Para UI própria, preferir hooks (`useAuth`, `useSignIn`, `useSessions`, etc.) em vez de chamar `authSdk` diretamente.
8. No **backend Elysia**, montar `authPlugin({ apiUrl, secretKey, excludePaths })` e consumir `{ user }` no contexto. Não reimplementar validação JWT.
9. Nunca expor `secretKey` (sk_) no frontend; apenas `apiKey` (pu_).
10. **Para multi-tenant:** o JWT **não** carrega `memberships` hoje. Mantenha a relação usuário↔organização no seu próprio banco, usando `user.id` como chave estrangeira. Não gere código que leia `user.memberships`, `user.role` ou `user.permissions` — os dois primeiros são `undefined`/`'user'` e o terceiro não existe.

### ⛔ O que NÃO existe — não gere código para isto

Verificado no worker em 2026-09-11:

| Recurso | Situação | O que fazer |
| :--- | :--- | :--- |
| Senha, link mágico, cadastro à parte | ⛔ removidos na 4.0.0 | `requestCode` + `verifyCode` |
| Login social (Google, GitHub…) | ⛔ não implementado | Use o código por e-mail |
| Trocar e-mail | ⛔ não há endpoint | O e-mail é a credencial: entrar com o novo é a troca |
| `memberships`/`permissions` no JWT | ⛔ não estão no token | Modele no seu banco |
| Proteção de rota por papel | ⛔ `<Protect>` só distingue logado/deslogado | Cheque no seu backend |
| Convite de membro por e-mail | ⛔ não há endpoint | — |
| Importação de usuários de outro provedor | ⛔ não há endpoint | Fale com a engenharia |
| Export de dados | ⛔ não há endpoint ainda | Em desenvolvimento |

**Regra geral para agentes:** se um recurso não está descrito como implementado neste arquivo, ele não existe. Não improvise a partir do nome de uma função exportada pelo SDK — várias são herança de arquitetura anterior e chamam rotas mortas.

---

## 9. Troubleshooting

| Sintoma | Causa provável | Correção |
| :--- | :--- | :--- |
| 401 imediato em toda rota protegida do Elysia | `AUTH_SECRET_KEY` errado ou `apiUrl` inválido | Conferir envs; `RiLiGarAuthClient.verifySession` faz fallback remoto, mas precisa do `apiUrl` certo. |
| Logo não aparece | `GET /application/by-api-key` falhando | Verificar `apiKey` (pu_) e que a aplicação existe no painel. |
| Logout em uma aba não afeta outras | Storage event bloqueado (ex: domínios diferentes) | Usar mesmo origin; o sync usa `storage` event nativo. |
| Token expirado em loop | Relógio do cliente dessincronizado | `checkTokenValidity()` compara `exp` com `Date.now()/1000`. |
| `useNavigate` lança fora de `<Router>` | `AuthProvider` está fora do `BrowserRouter` | Inverter a hierarquia. |
| Componentes sem estilo / quebrados | Faltou `<MantineProvider>` | Mantine é peer opcional, mas obrigatório para os componentes UI. |
| `excludePaths` não libera rota pública | `startsWith` — padrões devem corresponder ao início do path | Usar prefixos, ex: `'/public'` cobre `/public/*`. |
| JWKS lento na primeira requisição | Cache 1h no plugin Elysia, 5min no frontend — a primeira é remota | Pré-aquecer no startup chamando `getJWKS()` manualmente. |

---

## 10. Servidor MCP (documento separado)

O Auth expõe um **servidor MCP** na revisão `2026-07-28` do Model Context Protocol, em
`https://auth.worker.myinfrastructure.click/mcp/<applicationId>`. Ele tem dois usos distintos:

1. **O Auth como servidor MCP** — sete ferramentas (`auth_get_application`,
   `auth_list_client_organizations`, `auth_list_users`, `auth_search`, `auth_get_statistics`,
   `auth_list_user_sessions`, `auth_revoke_user_sessions`) que deixam um agente administrar
   **uma** aplicação. O `applicationId` está no endereço, e o token só vale para ele: um
   consentimento dado ao app Blogs não alcança o Loja. Servidor remoto: nada para instalar.

2. **O Auth como authorization server do SEU servidor MCP** — a spec exige OAuth 2.1 com PKCE,
   Protected Resource Metadata (RFC 9728) e validação de audiência (RFC 8707). O Auth entrega
   tudo isso; do seu lado ficam dois endpoints e uma checagem de `aud`.

⚠️ **Não tente implementar contra este arquivo.** O contrato MCP — headers obrigatórios,
códigos de erro, catálogo de ferramentas, fluxo OAuth e a lista do que não existe — está em
um documento próprio:

**https://myinfrastructure.click/products/auth/llms-mcp.txt**

Dois avisos que economizam tempo:

- O pacote npm desta revisão é `@modelcontextprotocol/client@2.x` (não `@modelcontextprotocol/sdk@1.x`,
  que fala a geração anterior, com `initialize` e sessão).
- No SDK oficial, a negociação de versão é opt-in: sem `{ versionNegotiation: { mode: 'auto' } }`
  o cliente usa a era legada e a conexão falha.

---

**Versões atuais:** `@riligar/auth-react@1.37.0` · `@riligar/auth-elysia@1.7.1`.
**Licença:** MIT. **Repositório:** https://github.com/riligar-applications/auth