create-fluxstack 1.4.1 → 1.5.0

package/.env.example

@@ -27,4 +27,11 @@ LOG_LEVEL=info
 
 # Build Configuration
 BUILD_TARGET=bun
-BUILD_OUTDIR=dist
+BUILD_OUTDIR=dist
+
+# Crypto Auth Plugin
+CRYPTO_AUTH_ENABLED=true
+CRYPTO_AUTH_MAX_TIME_DRIFT=300000
+# Adicione chaves públicas de admin separadas por vírgula (64 chars hex cada)
+CRYPTO_AUTH_ADMIN_KEYS=
+CRYPTO_AUTH_ENABLE_METRICS=true

package/CRYPTO-AUTH-MIDDLEWARE-GUIDE.md

@@ -0,0 +1,475 @@
+# 🔐 Crypto Auth - Guia de Middlewares
+
+> **✅ Nova Abordagem**: Middlewares declarativos - sem necessidade de configurar listas de paths!
+
+## 📖 **Visão Geral**
+
+O plugin Crypto Auth agora usa **middlewares Elysia nativos** aplicados diretamente nas rotas. Isso torna o código mais limpo, explícito e fácil de manter.
+
+## 🚀 **Quick Start**
+
+### **1. Configuração Simplificada**
+
+```typescript
+// fluxstack.config.ts
+plugins: {
+  enabled: ['crypto-auth'],
+  config: {
+    'crypto-auth': {
+      enabled: true,
+      maxTimeDrift: 300000, // 5 minutos
+      adminKeys: [
+        'abc123def456...' // Chaves públicas dos admins
+      ],
+      enableMetrics: true
+    }
+  }
+}
+```
+
+**✅ Removido**: `protectedRoutes` e `publicRoutes`
+**✅ Novo**: Middlewares aplicados diretamente nas rotas
+
+---
+
+## 🔌 **Middlewares Disponíveis**
+
+### **1. `cryptoAuthRequired()` - Requer Autenticação**
+
+Bloqueia a rota se não houver assinatura válida.
+
+```typescript
+import { cryptoAuthRequired, getCryptoAuthUser } from '@/plugins/crypto-auth/server'
+import { Elysia } from 'elysia'
+
+export const protectedRoutes = new Elysia()
+  .use(cryptoAuthRequired()) // ⚡ Middleware aplicado
+
+  .get('/profile', ({ request }) => {
+    const user = getCryptoAuthUser(request)! // Garantido que existe
+    return {
+      publicKey: user.publicKey,
+      isAdmin: user.isAdmin
+    }
+  })
+```
+
+**Response se não autenticado (401):**
+```json
+{
+  "error": {
+    "message": "Authentication required",
+    "code": "CRYPTO_AUTH_REQUIRED",
+    "statusCode": 401
+  }
+}
+```
+
+---
+
+### **2. `cryptoAuthAdmin()` - Requer Admin**
+
+Bloqueia a rota se não for administrador.
+
+```typescript
+import { cryptoAuthAdmin } from '@/plugins/crypto-auth/server'
+
+export const adminRoutes = new Elysia()
+  .use(cryptoAuthAdmin()) // ⚡ Requer admin
+
+  .delete('/users/:id', ({ params, request }) => {
+    const user = getCryptoAuthUser(request)! // Garantido admin
+    return {
+      deleted: params.id,
+      by: user.publicKey
+    }
+  })
+```
+
+**Response se não for admin (403):**
+```json
+{
+  "error": {
+    "message": "Admin privileges required",
+    "code": "ADMIN_REQUIRED",
+    "statusCode": 403,
+    "yourPermissions": ["user", "read"]
+  }
+}
+```
+
+---
+
+### **3. `cryptoAuthPermissions([...])` - Requer Permissões**
+
+Bloqueia se não tiver as permissões específicas.
+
+```typescript
+import { cryptoAuthPermissions } from '@/plugins/crypto-auth/server'
+
+export const writeRoutes = new Elysia()
+  .use(cryptoAuthPermissions(['write', 'edit'])) // ⚡ Requer ambas
+
+  .post('/posts', ({ body }) => {
+    return { created: body }
+  })
+```
+
+**Response se sem permissão (403):**
+```json
+{
+  "error": {
+    "message": "Insufficient permissions",
+    "code": "PERMISSION_DENIED",
+    "statusCode": 403,
+    "required": ["write", "edit"],
+    "yours": ["read"]
+  }
+}
+```
+
+---
+
+### **4. `cryptoAuthOptional()` - Autenticação Opcional**
+
+Não bloqueia, mas adiciona `user` se autenticado.
+
+```typescript
+import { cryptoAuthOptional, getCryptoAuthUser } from '@/plugins/crypto-auth/server'
+
+export const feedRoutes = new Elysia()
+  .use(cryptoAuthOptional()) // ⚡ Opcional
+
+  .get('/posts', ({ request }) => {
+    const user = getCryptoAuthUser(request) // Pode ser null
+
+    return {
+      posts: getPosts(),
+      personalizedFor: user ? user.publicKey : 'anonymous'
+    }
+  })
+```
+
+---
+
+## 🎯 **Padrões de Uso**
+
+### **Padrão 1: Grupo de Rotas Protegidas**
+
+```typescript
+import { Elysia } from 'elysia'
+import { cryptoAuthRequired } from '@/plugins/crypto-auth/server'
+
+export const apiRoutes = new Elysia({ prefix: '/api' })
+
+  // Rotas públicas
+  .get('/health', () => ({ status: 'ok' }))
+  .get('/docs', () => ({ version: '1.0.0' }))
+
+  // Grupo protegido
+  .group('/users', (app) => app
+    .use(cryptoAuthRequired()) // ⚡ Todas as rotas do grupo requerem auth
+
+    .get('/', ({ request }) => {
+      const user = getCryptoAuthUser(request)!
+      return { users: getUsers(user.publicKey) }
+    })
+
+    .post('/', ({ body }) => {
+      return { created: body }
+    })
+  )
+```
+
+---
+
+### **Padrão 2: Mix de Permissões no Mesmo Grupo**
+
+```typescript
+export const postsRoutes = new Elysia({ prefix: '/api/posts' })
+
+  // Leitura: apenas auth
+  .group('', (app) => app
+    .use(cryptoAuthRequired())
+
+    .get('/', () => ({ posts: [] }))
+    .get('/:id', ({ params }) => ({ post: params.id }))
+  )
+
+  // Escrita: auth + permissão write
+  .group('', (app) => app
+    .use(cryptoAuthPermissions(['write']))
+
+    .post('/', ({ body }) => ({ created: body }))
+    .put('/:id', ({ params, body }) => ({ updated: params.id }))
+  )
+
+  // Deleção: só admin
+  .group('', (app) => app
+    .use(cryptoAuthAdmin())
+
+    .delete('/:id', ({ params }) => ({ deleted: params.id }))
+  )
+```
+
+---
+
+### **Padrão 3: Auth Opcional com Comportamento Diferente**
+
+```typescript
+import { cryptoAuthOptional, getCryptoAuthUser, isCryptoAuthAdmin } from '@/plugins/crypto-auth/server'
+
+export const contentRoutes = new Elysia({ prefix: '/api/content' })
+  .use(cryptoAuthOptional()) // ⚡ Auth opcional para todas
+
+  .get('/articles/:id', ({ request, params }) => {
+    const user = getCryptoAuthUser(request)
+    const isAdmin = isCryptoAuthAdmin(request)
+    const article = getArticle(params.id)
+
+    return {
+      ...article,
+      premium: user ? article.premiumContent : '[Premium - Login Required]',
+      canEdit: isAdmin,
+      canComment: !!user
+    }
+  })
+```
+
+---
+
+## 🛠️ **Helpers Disponíveis**
+
+### **`getCryptoAuthUser(request)`**
+
+Retorna o usuário autenticado ou `null`.
+
+```typescript
+import { getCryptoAuthUser } from '@/plugins/crypto-auth/server'
+
+.get('/me', ({ request }) => {
+  const user = getCryptoAuthUser(request)
+
+  if (!user) {
+    return { error: 'Not authenticated' }
+  }
+
+  return { user }
+})
+```
+
+---
+
+### **`isCryptoAuthAuthenticated(request)`**
+
+Verifica se está autenticado.
+
+```typescript
+import { isCryptoAuthAuthenticated } from '@/plugins/crypto-auth/server'
+
+.get('/status', ({ request }) => {
+  return {
+    authenticated: isCryptoAuthAuthenticated(request)
+  }
+})
+```
+
+---
+
+### **`isCryptoAuthAdmin(request)`**
+
+Verifica se é admin.
+
+```typescript
+import { isCryptoAuthAdmin } from '@/plugins/crypto-auth/server'
+
+.get('/posts/:id', ({ request, params }) => {
+  const post = getPost(params.id)
+
+  return {
+    ...post,
+    canEdit: isCryptoAuthAdmin(request)
+  }
+})
+```
+
+---
+
+### **`hasCryptoAuthPermission(request, permission)`**
+
+Verifica permissão específica.
+
+```typescript
+import { hasCryptoAuthPermission } from '@/plugins/crypto-auth/server'
+
+.post('/posts/:id/publish', ({ request, params }) => {
+  if (!hasCryptoAuthPermission(request, 'publish')) {
+    return { error: 'Permission denied' }
+  }
+
+  return publishPost(params.id)
+})
+```
+
+---
+
+## 📋 **Estrutura do User**
+
+```typescript
+interface CryptoAuthUser {
+  publicKey: string      // Chave pública Ed25519 (hex)
+  isAdmin: boolean       // Se está na lista adminKeys
+  permissions: string[]  // ['read', 'write', 'admin', ...]
+}
+```
+
+**Como o `isAdmin` é determinado:**
+```typescript
+// Plugin verifica se a publicKey está em adminKeys
+const isAdmin = config.adminKeys.includes(user.publicKey)
+```
+
+---
+
+## 🔄 **Migrando da Abordagem Antiga**
+
+### **❌ Antes (listas de paths)**
+
+```typescript
+// fluxstack.config.ts
+plugins: {
+  config: {
+    'crypto-auth': {
+      protectedRoutes: ['/api/users/*', '/api/admin/*'],
+      publicRoutes: ['/api/health', '/api/docs']
+    }
+  }
+}
+
+// Rotas (sem controle explícito)
+export const routes = new Elysia()
+  .get('/api/users', handler) // Protegido pelo plugin
+```
+
+### **✅ Agora (middlewares declarativos)**
+
+```typescript
+// fluxstack.config.ts
+plugins: {
+  config: {
+    'crypto-auth': {
+      adminKeys: ['abc123...']
+      // Sem protectedRoutes/publicRoutes!
+    }
+  }
+}
+
+// Rotas (controle explícito)
+import { cryptoAuthRequired } from '@/plugins/crypto-auth/server'
+
+export const routes = new Elysia()
+  .get('/health', handler) // ✅ Público explicitamente
+
+  .group('/users', (app) => app
+    .use(cryptoAuthRequired()) // ✅ Protegido explicitamente
+    .get('/', handler)
+  )
+```
+
+---
+
+## 🎯 **Vantagens da Nova Abordagem**
+
+| Aspecto | Antes | Agora |
+|---------|-------|-------|
+| **Clareza** | Rotas implicitamente protegidas | ✅ Explícito no código |
+| **Manutenção** | Editar config + rotas | ✅ Editar apenas rotas |
+| **Type Safety** | Sem garantia de user | ✅ TypeScript sabe que user existe |
+| **Flexibilidade** | Apenas on/off | ✅ Permissões, admin, opcional |
+| **Debugging** | Difícil rastrear proteção | ✅ Fácil ver middleware aplicado |
+
+---
+
+## 🧪 **Testando**
+
+### **Rota Pública**
+```bash
+curl http://localhost:3000/api/crypto-auth/public
+# ✅ 200 OK - sem headers
+```
+
+### **Rota Protegida (sem auth)**
+```bash
+curl http://localhost:3000/api/crypto-auth/protected
+# ❌ 401 Unauthorized
+```
+
+### **Rota Protegida (com auth)**
+```bash
+curl http://localhost:3000/api/crypto-auth/protected \
+  -H "x-public-key: abc123..." \
+  -H "x-timestamp: 1234567890" \
+  -H "x-nonce: xyz789" \
+  -H "x-signature: def456..."
+# ✅ 200 OK
+```
+
+### **Rota Admin (sem ser admin)**
+```bash
+curl http://localhost:3000/api/crypto-auth/admin \
+  -H "x-public-key: user123..." \
+  -H "x-signature: ..."
+# ❌ 403 Forbidden - "Admin privileges required"
+```
+
+---
+
+## 📚 **Exemplos Completos**
+
+Veja exemplos práticos em:
+- `app/server/routes/crypto-auth-demo.routes.ts` - Rotas de demonstração
+- `plugins/crypto-auth/server/middlewares.ts` - Implementação dos middlewares
+
+---
+
+## 🆘 **Troubleshooting**
+
+### **Erro: "CryptoAuthService not initialized"**
+
+**Causa**: Plugin não está carregado.
+
+**Solução**:
+```typescript
+// fluxstack.config.ts
+plugins: {
+  enabled: ['crypto-auth'], // ✅ Adicione aqui
+}
+```
+
+### **User sempre null**
+
+**Causa**: Não está usando o middleware.
+
+**Solução**:
+```typescript
+// ❌ Errado
+.get('/protected', ({ request }) => {
+  const user = getCryptoAuthUser(request) // null
+})
+
+// ✅ Correto
+.use(cryptoAuthRequired())
+.get('/protected', ({ request }) => {
+  const user = getCryptoAuthUser(request)! // Garantido
+})
+```
+
+### **403 ao invés de 401**
+
+**Causa**: Usuário autenticado mas sem permissão.
+
+**Solução**: Verificar se `adminKeys` ou permissões estão corretas.
+
+---
+
+**✅ Pronto!** Agora você tem controle total e explícito sobre quais rotas são protegidas, sem precisar configurar listas de paths!