create-fluxstack 1.4.0 → 1.5.0

package/plugins/crypto-auth/README.md

@@ -1,238 +1,788 @@
-# FluxStack Crypto Auth Plugin
+# 🔐 FluxStack Crypto Auth Plugin
 
-Plugin de autenticação criptográfica baseado em Ed25519 para FluxStack.
+Sistema de autenticação baseado em criptografia **Ed25519** para FluxStack. Autenticação stateless sem sessões, usando assinaturas criptográficas.
 
-## Características
+## 📋 Índice
 
-- 🔐 **Zero-friction auth** - Sem cadastros, senhas ou emails
-- ✅ **Criptografia Ed25519** - Assinatura criptográfica de todas as requisições
-- 🌐 **Cross-platform** - Funciona em qualquer ambiente JavaScript
-- 💾 **Stateless backend** - Não precisa de banco para autenticação
-- 🎨 **Componentes React** - Componentes prontos para uso
-- ⚡ **Integração FluxStack** - Plugin nativo do FluxStack
+- [O Que É](#-o-que-é)
+- [Como Funciona](#-como-funciona)
+- [Instalação](#-instalação)
+- [Configuração](#️-configuração)
+- [Uso Básico](#-uso-básico)
+- [CLI Commands](#-cli-commands)
+- [Middlewares Disponíveis](#-middlewares-disponíveis)
+- [Helpers e Utilitários](#-helpers-e-utilitários)
+- [Fluxo de Autenticação](#-fluxo-de-autenticação)
+- [Segurança](#-segurança)
+- [Troubleshooting](#-troubleshooting)
 
-## Instalação
+---
 
-```bash
-# O plugin já está incluído na pasta plugins/
-# Apenas habilite no fluxstack.config.ts
+## 🎯 O Que É
+
+**Crypto Auth** é um plugin de autenticação que usa **assinaturas digitais Ed25519** ao invés de sessões tradicionais.
+
+### ✨ Principais Características
+
+- ✅ **Stateless**: Sem sessões, sem armazenamento de tokens
+- ✅ **Zero Trust**: Cada requisição é validada independentemente
+- ✅ **Ed25519**: Criptografia de curva elíptica (rápida e segura)
+- ✅ **Anti-Replay**: Proteção contra replay attacks com timestamps e nonces
+- ✅ **Admin Support**: Sistema de permissões com chaves administrativas
+- ✅ **TypeScript**: Totalmente tipado
+- ✅ **CLI Integration**: Geração automática de rotas protegidas
+
+### 🔄 Diferenças vs. Auth Tradicional
+
+| Característica | Auth Tradicional | Crypto Auth |
+|----------------|------------------|-------------|
+| **Armazenamento** | Sessões no servidor | Nenhum |
+| **Escalabilidade** | Limitada (sessões) | Infinita (stateless) |
+| **Segurança** | Token JWT ou session | Assinatura Ed25519 |
+| **Chave privada** | Armazenada no servidor | **NUNCA** sai do cliente |
+| **Performance** | Depende do DB/cache | Ultra-rápida (validação local) |
+
+---
+
+## 🔬 Como Funciona
+
+### 1. **Cliente Gera Par de Chaves (Uma Vez)**
+
+```typescript
+// No navegador (usando TweetNaCl ou similar)
+const keypair = nacl.sign.keyPair()
+
+// Armazenar no localStorage (chave privada NUNCA sai do navegador)
+localStorage.setItem('privateKey', toHex(keypair.secretKey))
+localStorage.setItem('publicKey', toHex(keypair.publicKey))
 ```
 
-## Configuração
+### 2. **Cliente Assina Cada Requisição**
 
-No seu `fluxstack.config.ts`:
+```typescript
+// Para cada request
+const timestamp = Date.now()
+const nonce = generateRandomNonce()
+const message = `${timestamp}:${nonce}:${requestBody}`
+
+// Assinar com chave privada
+const signature = nacl.sign.detached(message, privateKey)
+
+// Enviar headers
+headers = {
+  'x-public-key': publicKeyHex,
+  'x-timestamp': timestamp,
+  'x-nonce': nonce,
+  'x-signature': toHex(signature)
+}
+```
+
+### 3. **Servidor Valida Assinatura**
+
+```typescript
+// Plugin valida automaticamente
+const isValid = nacl.sign.detached.verify(
+  message,
+  signature,
+  publicKey
+)
+
+if (!isValid) {
+  throw new Error('Invalid signature')
+}
+
+// Verificar timestamp (previne replay attacks)
+if (Math.abs(Date.now() - timestamp) > maxTimeDrift) {
+  throw new Error('Timestamp expired')
+}
+```
+
+### 4. **Sem Armazenamento de Estado**
+
+- ✅ Servidor valida usando **apenas** a chave pública enviada
+- ✅ Nenhuma sessão ou token armazenado
+- ✅ Cada requisição é independente
+
+---
+
+## 📦 Instalação
+
+O plugin já vem incluído no FluxStack. Para habilitá-lo:
+
+### 1. **Adicionar ao `fluxstack.config.ts`**
 
 ```typescript
-export const config: FluxStackConfig = {
-  // ... outras configurações
-  
+import { cryptoAuthPlugin } from './plugins/crypto-auth'
+
+export default defineConfig({
   plugins: {
-    enabled: ['crypto-auth'],
+    enabled: [
+      cryptoAuthPlugin
+    ],
     config: {
       'crypto-auth': {
         enabled: true,
-        sessionTimeout: 1800000, // 30 minutos
         maxTimeDrift: 300000, // 5 minutos
         adminKeys: [
-          'sua_chave_publica_admin_aqui'
-        ],
-        protectedRoutes: [
-          '/api/admin/*',
-          '/api/protected/*'
-        ],
-        publicRoutes: [
-          '/api/auth/*',
-          '/api/health',
-          '/api/docs'
+          'a1b2c3d4e5f6...', // Chaves públicas de admins (hex 64 chars)
+          'f6e5d4c3b2a1...'
         ],
         enableMetrics: true
       }
     }
   }
-}
+})
 ```
 
-## Uso no Frontend
+### 2. **Variáveis de Ambiente (Opcional)**
 
-### 1. Configurar o Provider
+```bash
+# .env
+CRYPTO_AUTH_ENABLED=true
+CRYPTO_AUTH_MAX_TIME_DRIFT=300000
+CRYPTO_AUTH_ADMIN_KEYS=a1b2c3d4e5f6...,f6e5d4c3b2a1...
+CRYPTO_AUTH_ENABLE_METRICS=true
+```
 
-```tsx
-import React from 'react'
-import { AuthProvider } from '@/plugins/crypto-auth/client'
+---
 
-function App() {
-  return (
-    <AuthProvider
-      config={{
-        apiBaseUrl: 'http://localhost:3000',
-        storage: 'localStorage'
-      }}
-      onAuthChange={(isAuth, session) => {
-        console.log('Auth changed:', isAuth, session)
-      }}
-    >
-      <YourApp />
-    </AuthProvider>
-  )
+## ⚙️ Configuração
+
+### Schema de Configuração
+
+```typescript
+{
+  enabled: boolean              // Habilitar/desabilitar plugin
+  maxTimeDrift: number          // Máximo drift de tempo (ms) - previne replay
+  adminKeys: string[]           // Chaves públicas de administradores
+  enableMetrics: boolean        // Habilitar logs de métricas
 }
 ```
 
-### 2. Usar o Hook de Autenticação
-
-```tsx
-import React from 'react'
-import { useAuth } from '@/plugins/crypto-auth/client'
-
-function Dashboard() {
-  const { 
-    isAuthenticated, 
-    isAdmin, 
-    permissions, 
-    login, 
-    logout,
-    client 
-  } = useAuth()
-
-  const handleApiCall = async () => {
-    try {
-      const response = await client.fetch('/api/protected/data')
-      const data = await response.json()
-      console.log(data)
-    } catch (error) {
-      console.error('Erro na API:', error)
-    }
-  }
+### Valores Padrão
 
-  if (!isAuthenticated) {
-    return <button onClick={login}>Entrar</button>
-  }
-
-  return (
-    <div>
-      <h1>Dashboard {isAdmin && '(Admin)'}</h1>
-      <p>Permissões: {permissions.join(', ')}</p>
-      <button onClick={handleApiCall}>Chamar API</button>
-      <button onClick={logout}>Sair</button>
-    </div>
-  )
+```typescript
+{
+  enabled: true,
+  maxTimeDrift: 300000,    // 5 minutos
+  adminKeys: [],
+  enableMetrics: true
 }
 ```
 
-### 3. Componentes Prontos
-
-```tsx
-import React from 'react'
-import { 
-  LoginButton, 
-  ProtectedRoute, 
-  SessionInfo 
-} from '@/plugins/crypto-auth/client'
-
-function MyApp() {
-  return (
-    <div>
-      {/* Botão de login/logout */}
-      <LoginButton 
-        onLogin={(session) => console.log('Logado:', session)}
-        onLogout={() => console.log('Deslogado')}
-        showPermissions={true}
-      />
-
-      {/* Rota protegida */}
-      <ProtectedRoute requireAdmin={true}>
-        <AdminPanel />
-      </ProtectedRoute>
-
-      {/* Informações da sessão */}
-      <SessionInfo 
-        showPrivateKey={false}
-        compact={true}
-      />
-    </div>
+---
+
+## 🚀 Uso Básico
+
+### Opção 1: CLI (Recomendado)
+
+```bash
+# Criar rota com auth obrigatória
+bun flux crypto-auth:make:route users
+
+# Criar rota admin-only
+bun flux crypto-auth:make:route admin-panel --auth admin
+
+# Criar rota com auth opcional
+bun flux crypto-auth:make:route blog --auth optional
+
+# Criar rota pública
+bun flux crypto-auth:make:route public-api --auth public
+```
+
+### Opção 2: Manual
+
+```typescript
+// app/server/routes/users.routes.ts
+import { Elysia, t } from 'elysia'
+import { cryptoAuthRequired, getCryptoAuthUser } from '@/plugins/crypto-auth/server'
+
+export const usersRoutes = new Elysia({ prefix: '/users' })
+
+  // ========================================
+  // 🔒 ROTAS PROTEGIDAS
+  // ========================================
+  .guard({}, (app) =>
+    app.use(cryptoAuthRequired())
+
+      .get('/', ({ request }) => {
+        const user = getCryptoAuthUser(request)!
+
+        return {
+          message: 'Lista de usuários',
+          authenticatedAs: user.publicKey.substring(0, 8) + '...',
+          isAdmin: user.isAdmin
+        }
+      })
+
+      .post('/', ({ request, body }) => {
+        const user = getCryptoAuthUser(request)!
+
+        return {
+          message: 'Usuário criado',
+          createdBy: user.publicKey.substring(0, 8) + '...'
+        }
+      }, {
+        body: t.Object({
+          name: t.String(),
+          email: t.String()
+        })
+      })
   )
-}
 ```
 
-### 4. HOC para Proteção
+### Registrar Rotas
 
-```tsx
-import { withAuth } from '@/plugins/crypto-auth/client'
+```typescript
+// app/server/routes/index.ts
+import { usersRoutes } from './users.routes'
 
-const AdminComponent = () => <div>Área Admin</div>
+export const apiRoutes = new Elysia({ prefix: '/api' })
+  .use(usersRoutes)
+```
 
-// Proteger componente
-const ProtectedAdmin = withAuth(AdminComponent, {
-  requireAdmin: true,
-  requiredPermissions: ['admin']
-})
+---
+
+## 🎛️ CLI Commands
+
+### `crypto-auth:make:route`
+
+Gera arquivos de rotas com proteção crypto-auth automaticamente.
+
+#### **Sintaxe**
+
+```bash
+bun flux crypto-auth:make:route <name> [options]
 ```
 
-## Uso no Backend
+#### **Argumentos**
 
-O plugin automaticamente:
+- `name` - Nome da rota (ex: posts, users, admin)
 
-- Registra rotas de autenticação em `/api/auth/*`
-- Aplica middleware de autenticação nas rotas protegidas
-- Valida assinaturas Ed25519 em cada requisição
-- Gerencia sessões em memória
+#### **Opções**
+
+- `--auth, -a` - Tipo de autenticação (required, admin, optional, public)
+- `--output, -o` - Diretório de saída (padrão: app/server/routes)
+- `--force, -f` - Sobrescrever arquivo existente
+
+#### **Exemplos**
+
+```bash
+# Rota com auth obrigatória
+bun flux crypto-auth:make:route posts
+
+# Rota admin-only com output customizado
+bun flux crypto-auth:make:route admin --auth admin --output src/routes
+
+# Forçar sobrescrita
+bun flux crypto-auth:make:route users --force
+```
 
-### Rotas Automáticas
+#### **Templates Gerados**
 
-- `POST /api/auth/session/init` - Inicializar sessão
-- `POST /api/auth/session/validate` - Validar sessão
-- `GET /api/auth/session/info` - Informações da sessão
-- `POST /api/auth/session/logout` - Encerrar sessão
+| Tipo | Descrição | Rotas Geradas |
+|------|-----------|---------------|
+| `required` | Auth obrigatória | GET, POST, PUT, DELETE (CRUD completo) |
+| `admin` | Apenas admins | GET, POST, DELETE |
+| `optional` | Auth opcional | GET (lista), GET (detalhes com conteúdo extra) |
+| `public` | Sem auth | GET (lista), GET (detalhes) |
 
-### Acessar Usuário nas Rotas
+---
+
+## 🛡️ Middlewares Disponíveis
+
+### 1. `cryptoAuthRequired()`
+
+Autenticação **obrigatória**. Bloqueia requisições não autenticadas.
+
+```typescript
+import { cryptoAuthRequired, getCryptoAuthUser } from '@/plugins/crypto-auth/server'
+
+.guard({}, (app) =>
+  app.use(cryptoAuthRequired())
+    .get('/protected', ({ request }) => {
+      const user = getCryptoAuthUser(request)!  // ✅ Sempre existe
+      return { user }
+    })
+)
+```
+
+**Comportamento:**
+- ✅ Requisição autenticada → Prossegue
+- ❌ Requisição não autenticada → `401 Unauthorized`
+
+---
+
+### 2. `cryptoAuthAdmin()`
+
+Apenas **administradores**. Valida se a chave pública está em `adminKeys`.
 
 ```typescript
-// Em suas rotas FluxStack
-app.get('/api/protected/data', ({ user }) => {
-  // user estará disponível se autenticado
+import { cryptoAuthAdmin, getCryptoAuthUser } from '@/plugins/crypto-auth/server'
+
+.guard({}, (app) =>
+  app.use(cryptoAuthAdmin())
+    .delete('/delete/:id', ({ request }) => {
+      const user = getCryptoAuthUser(request)!  // ✅ Sempre admin
+      return { message: 'Deletado' }
+    })
+)
+```
+
+**Comportamento:**
+- ✅ Chave pública está em `adminKeys` → Prossegue
+- ❌ Não é admin → `403 Forbidden`
+- ❌ Não autenticado → `401 Unauthorized`
+
+---
+
+### 3. `cryptoAuthOptional()`
+
+Autenticação **opcional**. Não bloqueia, mas identifica usuários autenticados.
+
+```typescript
+import { cryptoAuthOptional, getCryptoAuthUser } from '@/plugins/crypto-auth/server'
+
+.guard({}, (app) =>
+  app.use(cryptoAuthOptional())
+    .get('/feed', ({ request }) => {
+      const user = getCryptoAuthUser(request)  // ⚠️ Pode ser null
+
+      if (user) {
+        return {
+          message: 'Feed personalizado',
+          recommendations: [...],
+          user: user.publicKey.substring(0, 8) + '...'
+        }
+      }
+
+      return {
+        message: 'Feed público',
+        trending: [...]
+      }
+    })
+)
+```
+
+**Comportamento:**
+- ✅ Requisição autenticada → `user` disponível
+- ✅ Requisição não autenticada → `user = null`, requisição prossegue
+
+---
+
+### 4. `cryptoAuthPermissions(permissions: string[])`
+
+Valida **permissões customizadas**.
+
+```typescript
+import { cryptoAuthPermissions, getCryptoAuthUser } from '@/plugins/crypto-auth/server'
+
+.guard({}, (app) =>
+  app.use(cryptoAuthPermissions(['write', 'delete']))
+    .put('/edit/:id', ({ request }) => {
+      const user = getCryptoAuthUser(request)!  // ✅ Tem as permissões
+      return { message: 'Editado' }
+    })
+)
+```
+
+**Comportamento:**
+- ✅ Usuário tem todas as permissões → Prossegue
+- ❌ Falta alguma permissão → `403 Forbidden`
+
+> **Nota**: Sistema de permissões requer extensão customizada. Por padrão, apenas `isAdmin` é verificado.
+
+---
+
+## 🔧 Helpers e Utilitários
+
+### `getCryptoAuthUser(request)`
+
+Retorna o usuário autenticado ou `null`.
+
+```typescript
+import { getCryptoAuthUser } from '@/plugins/crypto-auth/server'
+
+.get('/profile', ({ request }) => {
+  const user = getCryptoAuthUser(request)
+
   if (!user) {
-    return { error: 'Não autenticado' }
+    return { error: 'Not authenticated' }
   }
-  
+
   return {
-    message: 'Dados protegidos',
-    user: {
-      sessionId: user.sessionId,
-      isAdmin: user.isAdmin,
-      permissions: user.permissions
-    }
+    publicKey: user.publicKey,
+    isAdmin: user.isAdmin
   }
 })
 ```
 
-## Como Funciona
+**Retorno:**
+```typescript
+{
+  publicKey: string    // Chave pública do usuário (hex)
+  isAdmin: boolean     // Se é administrador
+} | null
+```
 
-1. **Cliente gera** par de chaves Ed25519 automaticamente
-2. **Session ID** = chave pública (64 chars hex)
-3. **Todas as requisições** são assinadas com a chave privada
-4. **Backend valida** a assinatura Ed25519 em cada request
-5. **Admin access** via chaves públicas autorizadas
+---
 
-## Segurança
+### `isCryptoAuthAuthenticated(request)`
 
-- ✅ Assinatura Ed25519 em todas as requisições
-- ✅ Nonce para prevenir replay attacks  
-- ✅ Validação de timestamp (5 min máximo)
-- ✅ Timeout de sessões (30 min padrão)
-- ✅ Chaves privadas nunca saem do cliente
-- ✅ Stateless - sem dependência de banco de dados
+Verifica se a requisição está autenticada.
 
-## Desenvolvimento
+```typescript
+import { isCryptoAuthAuthenticated } from '@/plugins/crypto-auth/server'
+
+.get('/status', ({ request }) => {
+  const isAuth = isCryptoAuthAuthenticated(request)
+
+  return {
+    authenticated: isAuth,
+    message: isAuth ? 'Você está logado' : 'Você não está logado'
+  }
+})
+```
+
+**Retorno:** `boolean`
+
+---
+
+### `isCryptoAuthAdmin(request)`
+
+Verifica se o usuário é administrador.
+
+```typescript
+import { isCryptoAuthAdmin } from '@/plugins/crypto-auth/server'
+
+.get('/admin-check', ({ request }) => {
+  const isAdmin = isCryptoAuthAdmin(request)
+
+  return {
+    isAdmin,
+    access: isAdmin ? 'granted' : 'denied'
+  }
+})
+```
+
+**Retorno:** `boolean`
+
+---
+
+### `hasCryptoAuthPermission(request, permission)`
+
+Verifica se o usuário tem uma permissão específica.
+
+```typescript
+import { hasCryptoAuthPermission } from '@/plugins/crypto-auth/server'
+
+.get('/can-delete', ({ request }) => {
+  const canDelete = hasCryptoAuthPermission(request, 'delete')
+
+  return { canDelete }
+})
+```
+
+**Retorno:** `boolean`
+
+---
+
+## 🔄 Fluxo de Autenticação
+
+### Diagrama Completo
+
+```
+┌─────────────┐                                    ┌─────────────┐
+│   Cliente   │                                    │   Servidor  │
+│  (Browser)  │                                    │  (Elysia)   │
+└──────┬──────┘                                    └──────┬──────┘
+       │                                                  │
+       │ 1. Gera par de chaves Ed25519 (uma vez)        │
+       │    privateKey, publicKey                        │
+       │    localStorage.setItem(...)                    │
+       │                                                  │
+       │ 2. Para cada request:                           │
+       │    - timestamp = Date.now()                     │
+       │    - nonce = random()                           │
+       │    - message = `${timestamp}:${nonce}:${body}`  │
+       │    - signature = sign(message, privateKey)      │
+       │                                                  │
+       │ 3. Envia request com headers                    │
+       │────────────────────────────────────────────────>│
+       │    x-public-key: <publicKey>                    │
+       │    x-timestamp: <timestamp>                     │
+       │    x-nonce: <nonce>                             │
+       │    x-signature: <signature>                     │
+       │                                                  │
+       │                                                  │ 4. Middleware valida:
+       │                                                  │    - Reconstrói message
+       │                                                  │    - verify(message, signature, publicKey)
+       │                                                  │    - Verifica timestamp
+       │                                                  │    - Verifica se é admin (se necessário)
+       │                                                  │
+       │ 5a. ✅ Válido                                   │
+       │<────────────────────────────────────────────────│
+       │    200 OK { data: ... }                         │
+       │                                                  │
+       │ 5b. ❌ Inválido                                 │
+       │<────────────────────────────────────────────────│
+       │    401 Unauthorized { error: ... }              │
+       │                                                  │
+```
+
+---
+
+## 🔒 Segurança
+
+### ✅ Proteções Implementadas
+
+1. **Anti-Replay Attacks**
+   - Timestamp validation (maxTimeDrift)
+   - Nonce único por requisição
+   - Assinatura inclui timestamp + nonce
+
+2. **Stateless Security**
+   - Sem sessões (não há o que roubar)
+   - Chave privada **NUNCA** sai do cliente
+   - Validação criptográfica a cada request
+
+3. **Admin Protection**
+   - Lista whitelist de chaves públicas administrativas
+   - Validação dupla (auth + isAdmin)
+
+4. **Type Safety**
+   - TypeScript completo
+   - Validação de schemas com TypeBox
+
+### ⚠️ Considerações de Segurança
+
+1. **HTTPS Obrigatório**
+   ```typescript
+   // Sempre use HTTPS em produção
+   if (process.env.NODE_ENV === 'production' && !request.url.startsWith('https')) {
+     throw new Error('HTTPS required')
+   }
+   ```
+
+2. **Rotação de Chaves**
+   ```typescript
+   // Cliente deve permitir rotação de chaves
+   function rotateKeys() {
+     const newKeypair = nacl.sign.keyPair()
+     // Migrar dados assinados com chave antiga
+     // Atualizar localStorage
+   }
+   ```
+
+3. **Rate Limiting**
+   ```typescript
+   // Adicionar rate limiting para prevenir brute force
+   import { rateLimit } from '@/plugins/rate-limit'
+
+   .use(rateLimit({ max: 100, window: '15m' }))
+   .use(cryptoAuthRequired())
+   ```
+
+4. **Admin Keys em Ambiente**
+   ```bash
+   # .env
+   CRYPTO_AUTH_ADMIN_KEYS=key1,key2,key3
+   ```
+
+---
+
+## 🧪 Troubleshooting
+
+### ❌ Erro: "Authentication required"
+
+**Problema**: Requisição sem headers de autenticação.
+
+**Solução**:
+```typescript
+// Cliente deve enviar headers
+headers: {
+  'x-public-key': publicKeyHex,
+  'x-timestamp': Date.now().toString(),
+  'x-nonce': generateNonce(),
+  'x-signature': signatureHex
+}
+```
 
-Para desenvolver o plugin:
+---
 
+### ❌ Erro: "Invalid signature"
+
+**Problema**: Assinatura não corresponde à mensagem.
+
+**Causas comuns**:
+1. Chave privada incorreta
+2. Mensagem reconstruída diferente
+3. Ordem dos campos alterada
+
+**Solução**:
+```typescript
+// Garantir ordem exata dos campos
+const message = `${timestamp}:${nonce}:${JSON.stringify(body)}`
+```
+
+---
+
+### ❌ Erro: "Timestamp drift too large"
+
+**Problema**: Diferença entre timestamp do cliente e servidor excede `maxTimeDrift`.
+
+**Solução**:
+```typescript
+// Sincronizar relógio do cliente com servidor
+const serverTime = await fetch('/api/time').then(r => r.json())
+const timeDrift = Date.now() - serverTime.timestamp
+// Ajustar timestamps futuros
+```
+
+---
+
+### ❌ Erro: "Admin access required"
+
+**Problema**: Usuário não está na lista de `adminKeys`.
+
+**Solução**:
+```typescript
+// Adicionar chave pública ao config
+{
+  'crypto-auth': {
+    adminKeys: [
+      'a1b2c3d4e5f6...',  // Sua chave pública
+    ]
+  }
+}
+```
+
+---
+
+### 🔍 Debug Mode
+
+Habilitar logs detalhados:
+
+```typescript
+// fluxstack.config.ts
+{
+  'crypto-auth': {
+    enableMetrics: true
+  }
+}
+```
+
+Verificar logs:
 ```bash
-# Instalar dependências
-npm install @noble/curves @noble/hashes
+# Requisições autenticadas
+Requisição autenticada {
+  publicKey: "a1b2c3d4...",
+  isAdmin: false,
+  path: "/api/users",
+  method: "GET"
+}
 
-# Para desenvolvimento com React
-npm install --save-dev @types/react react
+# Falhas de autenticação
+Falha na autenticação {
+  error: "Invalid signature",
+  path: "/api/users",
+  method: "POST"
+}
+```
+
+---
+
+## 📚 Recursos Adicionais
+
+### Documentação Relacionada
+
+- [`QUICK-START-CRYPTO-AUTH.md`](../../QUICK-START-CRYPTO-AUTH.md) - Início rápido em 5 minutos
+- [`EXEMPLO-ROTA-PROTEGIDA.md`](../../EXEMPLO-ROTA-PROTEGIDA.md) - Tutorial passo-a-passo
+- [`CRYPTO-AUTH-MIDDLEWARE-GUIDE.md`](../../CRYPTO-AUTH-MIDDLEWARE-GUIDE.md) - Referência de middlewares
+
+### Bibliotecas Cliente Recomendadas
+
+- **JavaScript/TypeScript**: [TweetNaCl.js](https://github.com/dchest/tweetnacl-js)
+- **React**: [@stablelib/ed25519](https://github.com/StableLib/stablelib)
+
+### Exemplo de Cliente
+
+```typescript
+// client-auth.ts
+import nacl from 'tweetnacl'
+import { encodeHex, decodeHex } from 'tweetnacl-util'
+
+export class CryptoAuthClient {
+  private privateKey: Uint8Array
+  private publicKey: Uint8Array
+
+  constructor() {
+    // Carregar ou gerar chaves
+    const stored = localStorage.getItem('cryptoAuthKeys')
+
+    if (stored) {
+      const keys = JSON.parse(stored)
+      this.privateKey = decodeHex(keys.privateKey)
+      this.publicKey = decodeHex(keys.publicKey)
+    } else {
+      const keypair = nacl.sign.keyPair()
+      this.privateKey = keypair.secretKey
+      this.publicKey = keypair.publicKey
+
+      localStorage.setItem('cryptoAuthKeys', JSON.stringify({
+        privateKey: encodeHex(keypair.secretKey),
+        publicKey: encodeHex(keypair.publicKey)
+      }))
+    }
+  }
+
+  async fetch(url: string, options: RequestInit = {}) {
+    const timestamp = Date.now().toString()
+    const nonce = encodeHex(nacl.randomBytes(16))
+    const body = options.body || ''
+
+    const message = `${timestamp}:${nonce}:${body}`
+    const signature = nacl.sign.detached(
+      new TextEncoder().encode(message),
+      this.privateKey
+    )
+
+    const headers = {
+      ...options.headers,
+      'x-public-key': encodeHex(this.publicKey),
+      'x-timestamp': timestamp,
+      'x-nonce': nonce,
+      'x-signature': encodeHex(signature)
+    }
+
+    return fetch(url, { ...options, headers })
+  }
+
+  getPublicKey() {
+    return encodeHex(this.publicKey)
+  }
+}
+
+// Uso
+const authClient = new CryptoAuthClient()
+const response = await authClient.fetch('/api/users', {
+  method: 'POST',
+  body: JSON.stringify({ name: 'João' })
+})
 ```
 
-## Licença
+---
+
+## 🤝 Contribuindo
+
+Para reportar bugs ou sugerir melhorias, abra uma issue no repositório do FluxStack.
+
+---
+
+## 📄 Licença
+
+Este plugin é parte do FluxStack e segue a mesma licença do framework.
+
+---
 
-MIT
+**Desenvolvido com ❤️ pela FluxStack Team**