create-fluxstack 1.5.1 → 1.5.3

package/EXEMPLO-ROTA-PROTEGIDA.md

@@ -0,0 +1,347 @@
+# 🔐 Como Criar Rotas com Crypto-Auth
+
+Guia prático para desenvolvedores criarem rotas usando o sistema de autenticação.
+
+## 📋 Passo a Passo
+
+### 1️⃣ Criar Arquivo de Rotas
+
+Crie um arquivo em `app/server/routes/`:
+
+```typescript
+// app/server/routes/posts.routes.ts
+import { Elysia, t } from 'elysia'
+import {
+  cryptoAuthRequired,
+  cryptoAuthAdmin,
+  cryptoAuthOptional,
+  getCryptoAuthUser
+} from '@/plugins/crypto-auth/server'
+
+export const postsRoutes = new Elysia({ prefix: '/posts' })
+
+  // ========================================
+  // 🌐 ROTA PÚBLICA - Qualquer um pode acessar
+  // ========================================
+  .get('/', () => {
+    return {
+      success: true,
+      posts: [
+        { id: 1, title: 'Post público' },
+        { id: 2, title: 'Outro post' }
+      ]
+    }
+  })
+
+  // ========================================
+  // 🔒 ROTA PROTEGIDA - Requer autenticação
+  // ========================================
+  .guard({}, (app) =>
+    app.use(cryptoAuthRequired())
+
+      // GET /api/posts/my-posts - Lista posts do usuário autenticado
+      .get('/my-posts', ({ request }) => {
+        const user = getCryptoAuthUser(request)!
+
+        return {
+          success: true,
+          message: `Posts de ${user.publicKey.substring(0, 8)}...`,
+          posts: [
+            { id: 1, title: 'Meu post privado', author: user.publicKey }
+          ]
+        }
+      })
+
+      // POST /api/posts - Criar novo post (autenticação obrigatória)
+      .post('/', ({ request, body }) => {
+        const user = getCryptoAuthUser(request)!
+        const { title, content } = body as { title: string; content: string }
+
+        return {
+          success: true,
+          message: 'Post criado com sucesso',
+          post: {
+            id: Date.now(),
+            title,
+            content,
+            author: user.publicKey,
+            createdAt: new Date().toISOString()
+          }
+        }
+      }, {
+        body: t.Object({
+          title: t.String(),
+          content: t.String()
+        })
+      })
+  )
+
+  // ========================================
+  // 👑 ROTA ADMIN - Apenas administradores
+  // ========================================
+  .guard({}, (app) =>
+    app.use(cryptoAuthAdmin())
+
+      // DELETE /api/posts/:id - Deletar qualquer post (só admin)
+      .delete('/:id', ({ request, params }) => {
+        const user = getCryptoAuthUser(request)!
+
+        return {
+          success: true,
+          message: `Post ${params.id} deletado por admin`,
+          deletedBy: user.publicKey.substring(0, 8) + '...'
+        }
+      })
+
+      // GET /api/posts/moderation - Painel de moderação
+      .get('/moderation', ({ request }) => {
+        const user = getCryptoAuthUser(request)!
+
+        return {
+          success: true,
+          message: 'Painel de moderação',
+          admin: user.publicKey.substring(0, 8) + '...',
+          pendingPosts: [],
+          reportedPosts: []
+        }
+      })
+  )
+
+  // ========================================
+  // 🌓 ROTA COM AUTH OPCIONAL - Funciona com/sem auth
+  // ========================================
+  .guard({}, (app) =>
+    app.use(cryptoAuthOptional())
+
+      // GET /api/posts/:id - Detalhes do post (conteúdo extra se autenticado)
+      .get('/:id', ({ request, params }) => {
+        const user = getCryptoAuthUser(request)
+        const isAuthenticated = !!user
+
+        return {
+          success: true,
+          post: {
+            id: params.id,
+            title: 'Post de exemplo',
+            content: 'Conteúdo público',
+            // ✅ Conteúdo extra apenas para autenticados
+            extraContent: isAuthenticated
+              ? 'Conteúdo premium para usuários autenticados'
+              : null,
+            canEdit: isAuthenticated,
+            viewer: user ? user.publicKey.substring(0, 8) + '...' : 'anonymous'
+          }
+        }
+      })
+  )
+```
+
+### 2️⃣ Registrar no Router Principal
+
+```typescript
+// app/server/routes/index.ts
+import { Elysia } from 'elysia'
+import { postsRoutes } from './posts.routes'  // ✅ Importar suas rotas
+
+export const apiRoutes = new Elysia({ prefix: '/api' })
+  .use(userRoutes)
+  .use(postsRoutes)  // ✅ Adicionar aqui
+  // ... outras rotas
+```
+
+### 3️⃣ Como o Cliente Faz Login
+
+O cliente precisa enviar headers de autenticação criptográfica:
+
+```typescript
+// Frontend/Cliente
+import { generateKeyPair, sign } from './crypto-utils'
+
+// 1. Gerar par de chaves (feito uma vez)
+const { publicKey, privateKey } = generateKeyPair()
+
+// 2. Fazer requisição autenticada
+const timestamp = Date.now()
+const nonce = crypto.randomUUID()
+const message = `GET:/api/posts/my-posts:${timestamp}:${nonce}`
+const signature = sign(message, privateKey)
+
+fetch('http://localhost:3000/api/posts/my-posts', {
+  headers: {
+    'X-Public-Key': publicKey,
+    'X-Timestamp': timestamp.toString(),
+    'X-Nonce': nonce,
+    'X-Signature': signature
+  }
+})
+```
+
+## 🧪 Testando as Rotas
+
+### Rota Pública (sem auth)
+```bash
+curl http://localhost:3000/api/posts
+# ✅ 200 OK
+```
+
+### Rota Protegida (sem auth)
+```bash
+curl http://localhost:3000/api/posts/my-posts
+# ❌ 401 {"error": {"message": "Authentication required"}}
+```
+
+### Rota Protegida (com auth)
+```bash
+curl http://localhost:3000/api/posts/my-posts \
+  -H "X-Public-Key: abc123..." \
+  -H "X-Timestamp: 1234567890" \
+  -H "X-Nonce: uuid-here" \
+  -H "X-Signature: signature-here"
+# ✅ 200 OK {"posts": [...]}
+```
+
+### Rota Admin (sem admin)
+```bash
+curl http://localhost:3000/api/posts/moderation \
+  -H "X-Public-Key: user-key..." \
+  # ... outros headers
+# ❌ 403 {"error": {"message": "Admin privileges required"}}
+```
+
+### Rota Opcional (ambos funcionam)
+```bash
+# Sem auth
+curl http://localhost:3000/api/posts/123
+# ✅ 200 OK {"post": {"extraContent": null}}
+
+# Com auth
+curl http://localhost:3000/api/posts/123 -H "X-Public-Key: ..."
+# ✅ 200 OK {"post": {"extraContent": "Conteúdo premium..."}}
+```
+
+## 📦 Middlewares Disponíveis
+
+### `cryptoAuthRequired()`
+Bloqueia acesso se não autenticado.
+```typescript
+.use(cryptoAuthRequired())
+.get('/protected', ({ request }) => {
+  const user = getCryptoAuthUser(request)! // ✅ Sempre existe
+})
+```
+
+### `cryptoAuthAdmin()`
+Bloqueia se não for admin.
+```typescript
+.use(cryptoAuthAdmin())
+.delete('/users/:id', ({ request }) => {
+  const user = getCryptoAuthUser(request)! // ✅ Sempre admin
+})
+```
+
+### `cryptoAuthOptional()`
+Adiciona user se autenticado, mas não bloqueia.
+```typescript
+.use(cryptoAuthOptional())
+.get('/feed', ({ request }) => {
+  const user = getCryptoAuthUser(request) // ⚠️ Pode ser null
+  if (user) {
+    return { message: 'Feed personalizado' }
+  }
+  return { message: 'Feed público' }
+})
+```
+
+### `cryptoAuthPermissions(['write', 'delete'])`
+Bloqueia se não tiver permissões específicas.
+```typescript
+.use(cryptoAuthPermissions(['write', 'delete']))
+.put('/posts/:id', ({ request }) => {
+  const user = getCryptoAuthUser(request)! // ✅ Tem as permissões
+})
+```
+
+## 🔑 Helpers Úteis
+
+```typescript
+import {
+  getCryptoAuthUser,
+  isCryptoAuthAuthenticated,
+  isCryptoAuthAdmin,
+  hasCryptoAuthPermission
+} from '@/plugins/crypto-auth/server'
+
+// Dentro de uma rota
+({ request }) => {
+  // Pegar usuário autenticado (null se não autenticado)
+  const user = getCryptoAuthUser(request)
+
+  // Verificar se está autenticado
+  if (!isCryptoAuthAuthenticated(request)) {
+    return { error: 'Login required' }
+  }
+
+  // Verificar se é admin
+  if (isCryptoAuthAdmin(request)) {
+    return { message: 'Admin panel' }
+  }
+
+  // Verificar permissão específica
+  if (hasCryptoAuthPermission(request, 'delete')) {
+    return { message: 'Can delete' }
+  }
+}
+```
+
+## ⚠️ Boas Práticas
+
+### ✅ Fazer
+- Usar `.guard({})` para isolar middlewares
+- Verificar `null` em rotas com `cryptoAuthOptional()`
+- Usar `!` apenas após middlewares obrigatórios
+- Separar rotas por nível de permissão
+
+### ❌ Não Fazer
+- Usar `.use()` fora de `.guard()` (afeta TODAS as rotas seguintes)
+- Esquecer `.as('plugin')` ao criar middlewares customizados
+- Assumir que `user` existe sem middleware de proteção
+
+## 🎯 Padrão Recomendado
+
+```typescript
+export const myRoutes = new Elysia({ prefix: '/my-feature' })
+
+  // Públicas primeiro
+  .get('/public', () => ({ ... }))
+
+  // Auth opcional (separado)
+  .guard({}, (app) =>
+    app.use(cryptoAuthOptional())
+      .get('/optional', ({ request }) => {
+        const user = getCryptoAuthUser(request)
+        // ...
+      })
+  )
+
+  // Protegidas (separado)
+  .guard({}, (app) =>
+    app.use(cryptoAuthRequired())
+      .get('/protected', ({ request }) => {
+        const user = getCryptoAuthUser(request)!
+        // ...
+      })
+  )
+
+  // Admin (separado)
+  .guard({}, (app) =>
+    app.use(cryptoAuthAdmin())
+      .delete('/admin-only', ({ request }) => {
+        const user = getCryptoAuthUser(request)!
+        // ...
+      })
+  )
+```
+
+---
+
+**Pronto!** Agora você sabe criar rotas com autenticação crypto-auth no FluxStack. 🚀

package/QUICK-START-CRYPTO-AUTH.md

@@ -0,0 +1,221 @@
+# ⚡ Quick Start: Crypto-Auth em 5 Minutos
+
+## 🎯 Como Criar uma Rota Protegida
+
+### 🚀 Opção 1: CLI (Recomendado)
+
+Use o comando `crypto-auth:make:route` para gerar rotas automaticamente:
+
+```bash
+# Rota com autenticação obrigatória (padrão)
+bun flux crypto-auth:make:route users
+
+# Rota apenas para admins
+bun flux crypto-auth:make:route admin-panel --auth admin
+
+# Rota com autenticação opcional
+bun flux crypto-auth:make:route blog --auth optional
+
+# Rota pública (sem auth)
+bun flux crypto-auth:make:route public-api --auth public
+```
+
+O comando cria automaticamente:
+- ✅ Arquivo de rotas em `app/server/routes/[nome].routes.ts`
+- ✅ Middlewares de autenticação configurados
+- ✅ Templates de CRUD completos
+- ✅ Exemplos de uso de `getCryptoAuthUser()`
+
+**Tipos de `--auth` disponíveis:**
+- `required` - Autenticação obrigatória (padrão)
+- `admin` - Apenas administradores
+- `optional` - Auth opcional (rota pública com conteúdo extra para autenticados)
+- `public` - Completamente pública (sem middleware)
+
+---
+
+### ⚙️ Opção 2: Manual
+
+#### 1️⃣ Criar Arquivo de Rotas
+
+```typescript
+// app/server/routes/minhas-rotas.routes.ts
+import { Elysia } from 'elysia'
+import { cryptoAuthRequired, getCryptoAuthUser } from '@/plugins/crypto-auth/server'
+
+export const minhasRotas = new Elysia({ prefix: '/minhas-rotas' })
+
+  // Rota pública
+  .get('/publica', () => ({ message: 'Todos podem ver' }))
+
+  // Rota protegida
+  .guard({}, (app) =>
+    app.use(cryptoAuthRequired())
+      .get('/protegida', ({ request }) => {
+        const user = getCryptoAuthUser(request)!
+        return {
+          message: 'Área restrita',
+          user: user.publicKey.substring(0, 8) + '...'
+        }
+      })
+  )
+```
+
+#### 2️⃣ Registrar no Router
+
+```typescript
+// app/server/routes/index.ts
+import { minhasRotas } from './minhas-rotas.routes'
+
+export const apiRoutes = new Elysia({ prefix: '/api' })
+  .use(minhasRotas)  // ✅ Adicionar aqui
+```
+
+#### 3️⃣ Testar
+
+```bash
+# Pública (funciona)
+curl http://localhost:3000/api/minhas-rotas/publica
+# ✅ {"message": "Todos podem ver"}
+
+# Protegida (sem auth)
+curl http://localhost:3000/api/minhas-rotas/protegida
+# ❌ {"error": {"message": "Authentication required", "code": "CRYPTO_AUTH_REQUIRED", "statusCode": 401}}
+```
+
+## 🔐 Tipos de Middleware
+
+### `cryptoAuthRequired()` - Autenticação Obrigatória
+```typescript
+.guard({}, (app) =>
+  app.use(cryptoAuthRequired())
+    .get('/protegida', ({ request }) => {
+      const user = getCryptoAuthUser(request)!  // ✅ Sempre existe
+      return { user }
+    })
+)
+```
+
+### `cryptoAuthAdmin()` - Apenas Administradores
+```typescript
+.guard({}, (app) =>
+  app.use(cryptoAuthAdmin())
+    .delete('/deletar/:id', ({ request, params }) => {
+      const user = getCryptoAuthUser(request)!  // ✅ Sempre admin
+      return { message: `${params.id} deletado` }
+    })
+)
+```
+
+### `cryptoAuthOptional()` - Autenticação Opcional
+```typescript
+.guard({}, (app) =>
+  app.use(cryptoAuthOptional())
+    .get('/feed', ({ request }) => {
+      const user = getCryptoAuthUser(request)  // ⚠️ Pode ser null
+
+      if (user) {
+        return { message: 'Feed personalizado', user }
+      }
+      return { message: 'Feed público' }
+    })
+)
+```
+
+### `cryptoAuthPermissions([...])` - Permissões Específicas
+```typescript
+.guard({}, (app) =>
+  app.use(cryptoAuthPermissions(['write', 'delete']))
+    .put('/editar/:id', ({ request }) => {
+      const user = getCryptoAuthUser(request)!  // ✅ Tem as permissões
+      return { message: 'Editado' }
+    })
+)
+```
+
+## 📊 Exemplo Real Funcionando
+
+Veja o arquivo criado: **`app/server/routes/exemplo-posts.routes.ts`**
+
+Rotas disponíveis:
+- ✅ `GET /api/exemplo-posts` - Pública
+- ✅ `GET /api/exemplo-posts/:id` - Auth opcional
+- ✅ `GET /api/exemplo-posts/meus-posts` - Protegida
+- ✅ `POST /api/exemplo-posts/criar` - Protegida
+- ✅ `GET /api/exemplo-posts/admin/todos` - Admin
+- ✅ `DELETE /api/exemplo-posts/admin/:id` - Admin
+
+## 🧪 Testando Agora
+
+```bash
+# Pública
+curl http://localhost:3000/api/exemplo-posts
+# ✅ {"success":true,"posts":[...]}
+
+# Auth opcional (sem auth)
+curl http://localhost:3000/api/exemplo-posts/1
+# ✅ {"success":true,"post":{"premiumContent":null,"viewer":"Visitante anônimo"}}
+
+# Protegida (sem auth)
+curl http://localhost:3000/api/exemplo-posts/meus-posts
+# ❌ {"error":{"message":"Authentication required"}}
+
+# Admin (sem auth)
+curl http://localhost:3000/api/exemplo-posts/admin/todos
+# ❌ {"error":{"message":"Authentication required"}}
+```
+
+## 🔑 Helpers Úteis
+
+```typescript
+import {
+  getCryptoAuthUser,
+  isCryptoAuthAuthenticated,
+  isCryptoAuthAdmin,
+  hasCryptoAuthPermission
+} from '@/plugins/crypto-auth/server'
+
+({ request }) => {
+  const user = getCryptoAuthUser(request)  // User | null
+  const isAuth = isCryptoAuthAuthenticated(request)  // boolean
+  const isAdmin = isCryptoAuthAdmin(request)  // boolean
+  const canDelete = hasCryptoAuthPermission(request, 'delete')  // boolean
+}
+```
+
+## ⚠️ Importante
+
+### ✅ Fazer
+```typescript
+// Isolar middlewares com .guard({})
+.guard({}, (app) =>
+  app.use(cryptoAuthRequired())
+    .get('/protected', () => {})
+)
+
+// Verificar null em auth opcional
+.guard({}, (app) =>
+  app.use(cryptoAuthOptional())
+    .get('/feed', ({ request }) => {
+      const user = getCryptoAuthUser(request)
+      if (user) { /* autenticado */ }
+    })
+)
+```
+
+### ❌ Não Fazer
+```typescript
+// ❌ Usar .use() sem .guard() (afeta TODAS as rotas seguintes)
+export const myRoutes = new Elysia()
+  .use(cryptoAuthRequired())  // ❌ ERRADO
+  .get('/publica', () => {})  // Esta rota ficará protegida!
+```
+
+## 📚 Documentação Completa
+
+- **Guia Detalhado**: `EXEMPLO-ROTA-PROTEGIDA.md`
+- **Referência de Middlewares**: `CRYPTO-AUTH-MIDDLEWARE-GUIDE.md`
+
+---
+
+**Pronto!** Agora você pode criar rotas protegidas em minutos. 🚀

package/app/client/src/App.tsx

@@ -15,6 +15,7 @@ import { OverviewPage } from './pages/Overview'
 import { DemoPage } from './pages/Demo'
 import { HybridLivePage } from './pages/HybridLive'
 import { ApiDocsPage } from './pages/ApiDocs'
+import { CryptoAuthPage } from './pages/CryptoAuthPage'
 import { MainLayout } from './components/MainLayout'
 import { LiveClock } from './components/LiveClock'
 
@@ -166,6 +167,7 @@ function AppContent() {
                       {[
                         { id: 'overview', label: 'Visão Geral', icon: <FaClipboardList />, path: '/' },
                         { id: 'demo', label: 'Demo', icon: <FaRocket />, path: '/demo' },
+                        { id: 'crypto-auth', label: 'Crypto Auth', icon: <FaShieldAlt />, path: '/crypto-auth' },
                         { id: 'hybrid-live', label: 'Hybrid Live', icon: <FaBolt />, path: '/hybrid-live' },
                         { id: 'live-app', label: 'Live App', icon: <FaFire />, path: '/live-app' },
                         { id: 'api-docs', label: 'API Docs', icon: <FaBook />, path: '/api-docs' },
@@ -208,8 +210,8 @@ function AppContent() {
                     {[
                       { id: 'overview', label: 'Visão', icon: <FaClipboardList />, path: '/' },
                       { id: 'demo', label: 'Demo', icon: <FaRocket />, path: '/demo' },
+                      { id: 'crypto-auth', label: 'Crypto', icon: <FaShieldAlt />, path: '/crypto-auth' },
                       { id: 'hybrid-live', label: 'Hybrid', icon: <FaBolt />, path: '/hybrid-live' },
-                      { id: 'live-app', label: 'Live', icon: <FaFire />, path: '/live-app' },
                       { id: 'api-docs', label: 'Docs', icon: <FaBook />, path: '/api-docs' },
                       { id: 'tests', label: 'Testes', icon: <FaTest />, path: '/tests' }
                     ].map(tab => (
@@ -256,6 +258,7 @@ function AppContent() {
                     />
                   }
                 />
+                <Route path="/crypto-auth" element={<CryptoAuthPage />} />
                 <Route path="/hybrid-live" element={<HybridLivePage />} />
                 <Route path="/api-docs" element={<ApiDocsPage />} />
                 <Route path="/tests" element={