arckode-framework 1.3.2 → 1.4.0

package/modules/ws/index.ts

@@ -22,12 +22,15 @@ export interface WSAdapter {
 // ─── WebSocket nativo (sin dependencias externas) ───
 // Usa el servidor HTTP de Node. Para producción usar `ws` o `uWebSockets`.
 
+/** Máximo payload por frame. Un frame más grande cierra la conexión (DoS protection). */
+const WS_MAX_PAYLOAD = 1 * 1024 * 1024 // 1 MB
+
 export class WSServer implements WSAdapter {
   private clients = new Map<string, WSClient>()
+  private buffers = new Map<string, Buffer>()
 
   attach(server: HttpServer): void {
-    server.on('upgrade', (req, socket, head) => {
-      // Implementación básica de WebSocket handshake
+    server.on('upgrade', (req, socket, _head) => {
       const key = req.headers['sec-websocket-key']
       if (!key) { socket.destroy(); return }
 
@@ -45,21 +48,34 @@ export class WSServer implements WSAdapter {
       const client: WSClient = {
         id: clientId,
         send: (data) => this.sendFrame(socket, JSON.stringify(data)),
-        close: () => socket.end(),
+        close: () => {
+          this.sendCloseFrame(socket)
+          socket.end()
+        },
         onMessage: () => {},
         onClose: () => {},
       }
 
       this.clients.set(clientId, client)
+      this.buffers.set(clientId, Buffer.alloc(0))
       console.log(`[WS] Client connected: ${clientId}`)
 
-      socket.on('data', (buffer) => {
-        const message = this.parseFrame(buffer)
-        if (message) client.onMessage(message)
+      socket.on('data', (chunk: Buffer) => {
+        let buf = Buffer.concat([this.buffers.get(clientId) ?? Buffer.alloc(0), chunk])
+        while (buf.length > 0) {
+          const frameLen = this.getFrameLength(buf)
+          if (frameLen === -1) break // frame incompleto — esperar más datos
+          const frame = buf.slice(0, frameLen)
+          buf = buf.slice(frameLen)
+          const result = this.parseFrame(frame, socket)
+          if (result !== null) client.onMessage(result)
+        }
+        this.buffers.set(clientId, buf)
       })
 
       socket.on('close', () => {
         this.clients.delete(clientId)
+        this.buffers.delete(clientId)
         client.onClose()
         console.log(`[WS] Client disconnected: ${clientId}`)
       })
@@ -89,42 +105,131 @@ export class WSServer implements WSAdapter {
     return createHash('sha1').update(key + GUID).digest('base64')
   }
 
+  private buildFrame(firstByte: number, payload: Buffer): Buffer {
+    let headerLen = 2
+    if (payload.length > 65535) headerLen += 8
+    else if (payload.length > 125) headerLen += 2
+
+    const frame = Buffer.alloc(headerLen + payload.length)
+    frame[0] = firstByte
+
+    if (payload.length > 65535) {
+      frame[1] = 127
+      frame.writeBigUInt64BE(BigInt(payload.length), 2)
+    } else if (payload.length > 125) {
+      frame[1] = 126
+      frame.writeUInt16BE(payload.length, 2)
+    } else {
+      frame[1] = payload.length
+    }
+
+    payload.copy(frame, headerLen)
+    return frame
+  }
+
   private sendFrame(socket: any, data: string): void {
-    const buffer = Buffer.from(data, 'utf-8')
-    const frame = Buffer.alloc(2 + buffer.length)
-    frame[0] = 0x81 // FIN + texto
-    frame[1] = buffer.length
-    buffer.copy(frame, 2)
-    socket.write(frame)
+    const payload = Buffer.from(data, 'utf-8')
+    socket.write(this.buildFrame(0x81, payload)) // FIN + opcode text
+  }
+
+  private sendPongFrame(socket: any, payload: Buffer): void {
+    socket.write(this.buildFrame(0x8A, payload)) // FIN + opcode pong
   }
 
-  private parseFrame(buffer: Buffer): string | null {
+  private sendCloseFrame(socket: any): void {
+    socket.write(this.buildFrame(0x88, Buffer.alloc(0))) // FIN + opcode close
+  }
+
+  /**
+   * Retorna la longitud total del frame (header + payload) si el buffer contiene
+   * al menos un frame completo, o -1 si el frame está incompleto (fragmentación TCP).
+   */
+  private getFrameLength(buf: Buffer): number {
+    if (buf.length < 2) return -1
+    const masked = ((buf[1] ?? 0) & 0x80) !== 0
+    let payloadLength = (buf[1] ?? 0) & 0x7F
+    let offset = 2
+
+    if (payloadLength === 126) {
+      if (buf.length < 4) return -1
+      payloadLength = buf.readUInt16BE(2)
+      offset = 4
+    } else if (payloadLength === 127) {
+      if (buf.length < 10) return -1
+      payloadLength = Number(buf.readBigUInt64BE(2))
+      offset = 10
+    }
+
+    if (masked) offset += 4
+    const total = offset + payloadLength
+    return buf.length >= total ? total : -1
+  }
+
+  /**
+   * Parsea un frame RFC 6455. Retorna el texto del payload o null.
+   * - Ping → responde con pong (RFC 6455 §5.5.2)
+   * - Close → responde con close y destruye el socket
+   * - Oversized → destruye el socket (DoS protection)
+   */
+  private parseFrame(buffer: Buffer, socket?: any): string | null {
     if (buffer.length < 2) return null
+
     const opcode = (buffer[0] ?? 0) & 0x0F
-    if (opcode !== 0x01) return null // solo texto
     const masked = ((buffer[1] ?? 0) & 0x80) !== 0
     let payloadLength = (buffer[1] ?? 0) & 0x7F
     let offset = 2
 
     if (payloadLength === 126) {
+      if (buffer.length < 4) return null
       payloadLength = buffer.readUInt16BE(2)
       offset = 4
     } else if (payloadLength === 127) {
-      payloadLength = Number(buffer.readBigUInt64BE(2))
+      if (buffer.length < 10) return null
+      const bigLen = buffer.readBigUInt64BE(2)
+      payloadLength = Number(bigLen)
       offset = 10
     }
 
+    // DoS protection: rechazar frames con payload mayor al límite configurado
+    if (payloadLength > WS_MAX_PAYLOAD) {
+      if (socket) { this.sendCloseFrame(socket); socket.destroy() }
+      return null
+    }
+
+    let payload: Buffer
     if (masked) {
+      if (buffer.length < offset + 4) return null
       const mask = buffer.slice(offset, offset + 4)
       offset += 4
-      const payload = Buffer.alloc(payloadLength)
+      payload = Buffer.alloc(payloadLength)
       for (let i = 0; i < payloadLength; i++) {
         payload[i] = (buffer[offset + i] ?? 0) ^ (mask[i % 4] ?? 0)
       }
-      return payload.toString('utf-8')
+    } else {
+      payload = buffer.slice(offset, offset + payloadLength)
     }
 
-    return buffer.slice(offset, offset + payloadLength).toString('utf-8')
+    // RFC 6455 control frames
+    if (opcode === 0x08) {
+      // Close — responder y cerrar limpiamente
+      if (socket) { this.sendCloseFrame(socket); socket.destroy() }
+      return null
+    }
+
+    if (opcode === 0x09) {
+      // Ping — responder con pong obligatorio (RFC 6455 §5.5.2)
+      if (socket) this.sendPongFrame(socket, payload)
+      return null
+    }
+
+    if (opcode === 0x0A) {
+      // Pong — ignorar (respuesta a nuestro ping)
+      return null
+    }
+
+    if (opcode !== 0x01) return null // solo texto (no binario ni fragmentado)
+
+    return payload.toString('utf-8')
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arckode-framework",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "AI-first TypeScript/Bun framework. Modular, SOLID, zero magic. The AI reads the composition root and knows everything.",
   "type": "module",
   "main": "./kernel/framework.ts",
@@ -19,22 +19,19 @@
     "./modules/storage": "./modules/storage/index.ts",
     "./modules/storage/local-adapter": "./modules/storage/local-adapter.ts",
     "./modules/queue": "./modules/queue/index.ts",
-    "./testing": "./kernel/testing.ts"
+    "./testing": "./kernel/testing.ts",
+    "./cli/commands/db-migrate": "./cli/commands/db-migrate.ts",
+    "./cli/commands/db-seed": "./cli/commands/db-seed.ts"
   },
   "bin": {
     "arckode": "bin/arckode.js"
   },
   "files": [
     "bin/",
-    "kernel/framework.ts",
-    "kernel/middlewares.ts",
-    "kernel/static.ts",
-    "kernel/testing.ts",
-    "adapters/jwt.ts",
-    "adapters/mysql.ts",
-    "adapters/postgres.ts",
-    "adapters/redis-cache.ts",
-    "adapters/sqlite.ts",
+    "kernel/",
+    "!kernel/__tests__/",
+    "adapters/",
+    "!adapters/__tests__/",
     "modules/events/index.ts",
     "modules/mail/",
     "modules/queue/index.ts",

package/skills/auth/SKILL.md

@@ -1,243 +1,59 @@
-# SKILL: Arckode Auth — JWT, Roles, Passwords y IDOR
+# Auth — JWT, Roles, Ownership
 
-> Activar cuando: implementar login, registro, proteger rutas, verificar permisos, manejar passwords.
+## Stack
 
----
+`jsonwebtoken` (JWT RS256) + middleware `authMw` + helper `auth.assertOwnership()`.
 
-## 1. SETUP EN COMPOSITION-ROOT
+## Flujo
 
-```ts
-import { Auth } from 'arckode-framework'
-import { jwtTokenAdapter } from 'arckode-framework/adapters/jwt'
-
-const auth = new Auth(
-  jwtTokenAdapter,
-  config.get('JWT_SECRET'),      // REQUERIDO — string largo y aleatorio
-  logger,
-  {
-    accessTokenExpiry:  '15m',   // default: '15m'
-    refreshTokenExpiry: '7d',    // default: '7d'
-    adminRole:          'admin',  // default: 'admin'
-  }
-)
-
-// Pasar al System y a los módulos que lo necesiten
-const system = new System({ config, logger, orm, router, http, cache, auth })
-```
-
-**Config requerida en .env:**
-```env
-JWT_SECRET=una-cadena-larga-y-aleatoria-de-al-menos-32-chars
-JWT_REFRESH_SECRET=otra-cadena-distinta-para-refresh-tokens
 ```
-
----
-
-## 2. REGISTRO Y LOGIN (patrón completo)
-
-```ts
-// En el módulo de autenticación — service.ts (al root del módulo)
-export class AuthService {
-  constructor(
-    private repo: RepositoryAdapter<UserDTO>,
-    private auth: Auth,
-    private logger: Logger,
-  ) {}
-
-  async registrar(dto: RegisterDTO): Promise<{ accessToken: string; refreshToken: string }> {
-    const existente = await this.repo.findOne({ email: dto.email })
-    if (existente) throw new ConflictError('El email ya está registrado')
-
-    const hashedPassword = await this.auth.hashPassword(dto.password)
-    const user = await this.repo.create({
-      email: dto.email,
-      password: hashedPassword,
-      role: 'user',
-    } as Omit<UserDTO, 'id'>)
-
-    return {
-      accessToken:  this.auth.createToken({ id: user.id, role: user.role }),
-      refreshToken: this.auth.createRefreshToken({ id: user.id, role: user.role }),
-    }
-  }
-
-  async login(dto: LoginDTO): Promise<{ accessToken: string; refreshToken: string }> {
-    const user = await this.repo.findOne({ email: dto.email })
-    if (!user) throw new AuthError('Credenciales inválidas')
-
-    const ok = await this.auth.comparePassword(dto.password, user.password as string)
-    if (!ok) throw new AuthError('Credenciales inválidas')
-
-    return {
-      accessToken:  this.auth.createToken({ id: user.id, role: user.role }),
-      refreshToken: this.auth.createRefreshToken({ id: user.id, role: user.role }),
-    }
-  }
-
-  async refresh(refreshToken: string): Promise<{ accessToken: string; refreshToken: string }> {
-    return this.auth.refresh(refreshToken)
-  }
-}
+Login → JWT (access + refresh) → authMw verify → req.user → assertOwnership()
 ```
 
-**Crítico:** Siempre usar el mismo mensaje de error para usuario no encontrado y contraseña incorrecta — previene user enumeration.
-
----
-
-## 3. PROTEGER RUTAS
+## authMw — JWT Verify
 
 ```ts
-// En index.ts del módulo — al registrar rutas:
-
-// Requiere cualquier usuario autenticado
-router.get('/perfil', [auth.authenticate()], req => controller.perfil(req))
-
-// Requiere rol específico
-router.post('/admin/config', [auth.authenticate('admin')], req => controller.setConfig(req))
-
-// Múltiples roles permitidos
-router.get('/reportes', [auth.authenticate('admin', 'supervisor')], req => controller.reportes(req))
-
-// Ruta pública (sin middleware)
-router.post('/auth/login', req => controller.login(req))
-router.post('/auth/registro', req => controller.registrar(req))
+// en router
+router.get('/pedidos/:id', authMw, pedidosController.findById)
+// req.user = { id, role, ... }
 ```
 
-**El middleware agrega `req.user` con `{ id: string, role: string }` para handlers autenticados.**
-
----
-
-## 4. ACCESO AL USUARIO ACTUAL
+## assertOwnership — Anti IDOR
 
 ```ts
-// En el controller — req.user está disponible en rutas protegidas
-async perfil(req: HttpRequest): Promise<HttpResponse> {
-  const user = req.user!  // { id: string, role: string }
-  const data = await this.service.getPerfil(user.id, user)
-  return { status: 200, body: data }
-}
+// LLAMAR después de findById SIEMPRE
+const pedido = await pedidosService.findById(id)
+auth.assertOwnership(pedido, req.user)
+// compara pedido.usuarioId === req.user.id
 ```
 
----
+| Recurso | Campo owner |
+|---------|-------------|
+| Pedido | `usuarioId` |
+| Wallet | `userId` |
+| Profile | `userId` |
 
-## 5. PREVENCIÓN DE IDOR (obligatorio)
-
-Todo `findById` que devuelve datos de un usuario específico **DEBE** verificar ownership:
+## Roles y Permisos
 
 ```ts
-// ❌ PROHIBIDO — cualquier usuario autenticado puede ver datos de otro
-async getMiPedido(id: string): Promise<PedidoDTO> {
-  const pedido = await this.repo.findById(id)
-  if (!pedido) throw new NotFoundError('Pedido no encontrado')
-  return pedido  // IDOR: usuario B puede ver pedidos de usuario A con ID correcto
+export enum Role {
+  ADMIN = 'admin',
+  USER = 'user',
+  MODERATOR = 'moderator',
 }
-
-// ✅ OBLIGATORIO — verificar ownership
-async getMiPedido(id: string, currentUser: { id: string; role: string }): Promise<PedidoDTO> {
-  const pedido = await this.repo.findById(id)
-  if (!pedido) throw new NotFoundError('Pedido no encontrado')
-
-  // Lanza ForbiddenError si currentUser.id !== pedido.usuarioId
-  // EXCEPTO si currentUser.role === adminRole (admin bypassa el check)
-  this.auth.assertOwnership(pedido.usuarioId as string, currentUser.id, currentUser.role)
-
-  return pedido
+export const Permissions: Record<Role, string[]> = {
+  [Role.ADMIN]:     ['*'],
+  [Role.MODERATOR]: ['pedidos:read', 'users:read'],
+  [Role.USER]:      ['pedidos:read', 'pedidos:write'],
 }
 ```
 
-**`arckode analyze` detecta:** `IDOR_RISK` — findById sin assertOwnership.
-
----
-
-## 6. ROLES Y AUTORIZACIÓN
-
-```ts
-// Verificar rol manualmente en service (cuando la lógica es más compleja)
-async cancelarPedido(id: string, currentUser: { id: string; role: string }): Promise<void> {
-  const pedido = await this.repo.findById(id)
-  if (!pedido) throw new NotFoundError('Pedido no encontrado')
-
-  // Solo el dueño o admin puede cancelar
-  this.auth.assertOwnership(pedido.usuarioId as string, currentUser.id, currentUser.role)
-
-  // Solo se puede cancelar si está pendiente (lógica de negocio)
-  if (pedido.estado !== 'pendiente') {
-    throw new ConflictError('Solo se pueden cancelar pedidos pendientes')
-  }
-
-  await this.repo.update(id, { estado: 'cancelado' })
-}
-```
-
----
-
-## 7. HASHING DE PASSWORDS
-
-```ts
-// Hashear al registrar o cambiar contraseña
-const hash = await auth.hashPassword(plainPassword)
-
-// Verificar al hacer login
-const matches = await auth.comparePassword(plainPassword, storedHash)
-
-// Usar timing-safe comparison internamente (previene timing attacks)
-```
-
-**Algoritmo:** scrypt + salt aleatorio. No implementar hashing propio.
-
----
-
-## 8. REFRESH DE TOKEN
-
-```ts
-// En el controller de auth
-async refreshToken(req: HttpRequest): Promise<HttpResponse> {
-  const { refreshToken } = req.body as { refreshToken: string }
-  if (!refreshToken) throw new ValidationError('refreshToken requerido')
-
-  const tokens = await this.service.refresh(refreshToken)
-  return { status: 200, body: tokens }
-}
-
-// En el service (delegar a auth)
-async refresh(refreshToken: string) {
-  return this.auth.refresh(refreshToken)  // lanza AuthError si expiró o es inválido
-}
-```
-
-**Importante:** El refresh token tiene `type: 'refresh'` en el payload. `auth.verifyToken()` (para access tokens) rechaza tokens con `type: 'refresh'` — son tokens distintos por diseño.
-
----
-
-## 9. NUNCA EXPONER AL CLIENTE
-
-```ts
-// ❌ PROHIBIDO en responses HTTP
-{
-  password: user.password,       // hash de contraseña
-  jwtSecret: 'el-secreto',       // secreto JWT
-  internalId: 'uuid-interno',    // IDs internos innecesarios
-  stackTrace: error.stack,       // stack trace de error
-}
-
-// ✅ Proyectar solo lo necesario en el DTO de respuesta
-export interface UserPublicDTO {
-  id: string
-  email: string
-  role: string
-  createdAt: string
-  // SIN password, SIN tokens internos
-}
-```
-
----
-
-## 10. CHECKLIST AUTH
+## Errores silenciosos
 
-- [ ] `JWT_SECRET` en .env, no hardcodeado
-- [ ] Login usa mismo mensaje para "usuario no existe" y "contraseña incorrecta"
-- [ ] Passwords hasheados con `auth.hashPassword()` al guardar
-- [ ] `auth.authenticate()` en array de middlewares: `[auth.authenticate('admin')]`
-- [ ] Todo `findById` de recurso de usuario tiene `assertOwnership()`
-- [ ] El DTO de respuesta nunca incluye password, tokens ni stack traces
-- [ ] Refresh token endpoint separado del login
+| Error | Señal | Fix |
+|-------|-------|-----|
+| IDOR: user ve pedido ajeno | Faltó `assertOwnership` | Siempre después de `findById` |
+| Token expirado sin refresh | 401 sin renewal | Refresh token + interceptor |
+| Role check en controller | `if (req.user.role !== 'admin')` | Helper `auth.hasRole(role)` |
+| JWT sin secret fuerte | `'secret123'` | `JWT_SECRET` de 256 bits+ |
+| Refresh token sin rotación | Refresh reutilizable | Rotar en cada refresh |