arckode-framework 1.0.0

package/skills/auth/SKILL.md

@@ -0,0 +1,243 @@
+# SKILL: Arckode Auth — JWT, Roles, Passwords y IDOR
+
+> Activar cuando: implementar login, registro, proteger rutas, verificar permisos, manejar passwords.
+
+---
+
+## 1. SETUP EN COMPOSITION-ROOT
+
+```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 — actions/service.ts
+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)
+  }
+}
+```
+
+**Crítico:** Siempre usar el mismo mensaje de error para usuario no encontrado y contraseña incorrecta — previene user enumeration.
+
+---
+
+## 3. PROTEGER RUTAS
+
+```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))
+```
+
+**El middleware agrega `req.user` con `{ id: string, role: string }` para handlers autenticados.**
+
+---
+
+## 4. ACCESO AL USUARIO ACTUAL
+
+```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 }
+}
+```
+
+---
+
+## 5. PREVENCIÓN DE IDOR (obligatorio)
+
+Todo `findById` que devuelve datos de un usuario específico **DEBE** verificar ownership:
+
+```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
+}
+
+// ✅ 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
+}
+```
+
+**`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
+
+- [ ] `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

package/skills/cli/SKILL.md

@@ -0,0 +1,258 @@
+# SKILL: Arckode CLI — Generadores y Comandos
+
+> Activar cuando: crear módulo nuevo, generar código, correr migraciones, analizar arquitectura, listar rutas.
+
+---
+
+## 1. COMANDOS DISPONIBLES
+
+```bash
+arckode new <nombre>                    # Crear proyecto nuevo
+arckode make:module <Nombre>            # Generar módulo completo (7 archivos)
+arckode make:connector <nombre> <m1> <m2>  # Generar conector entre módulos
+arckode make:migration <descripcion>    # Crear archivo de migración SQL
+arckode make:seed <nombre>             # Crear archivo de seed
+arckode make:auth                      # Generar módulo de autenticación completo
+arckode analyze                        # Detectar violaciones de arquitectura
+arckode analyze --strict               # Idem, falla con exit 1 si hay violaciones
+arckode routes                         # Listar todas las rutas del proyecto
+arckode db:migrate                     # Correr migraciones pendientes
+arckode db:migrate --rollback          # Revertir última migración
+```
+
+---
+
+## 2. `arckode make:module` — Lo que genera
+
+```bash
+arckode make:module Producto
+```
+
+Genera en `src/modules/producto/`:
+```
+index.ts              ← ProductoModule() con createModule + OrmRepository + rutas
+types.ts              ← ProductoModel (ModelDefinition) + ProductoDTO + CreateProductoDTO
+sockets.ts            ← ProductosSockets interface + SocketsAware
+actions/
+  service.ts          ← ProductosService con RepositoryAdapter<ProductoDTO>
+  controller.ts       ← ProductosController con validateSchema en store/update
+validators/
+  schema.ts           ← crearProductoSchema + actualizarProductoSchema
+tests/
+  service.test.ts     ← 2 test cases: listar + crear con error
+```
+
+**Importante:** El nombre se usa en PascalCase para clases, camelCase para variables, kebab-case para rutas:
+- `arckode make:module LineaPedido` → clase `LineaPedidoService`, tabla `linea_pedidos`, ruta `/linea-pedidos`
+
+**Después de generar:**
+1. Revisar `types.ts` → ajustar campos al dominio real
+2. Revisar `validators/schema.ts` → ajustar validaciones
+3. Agregar a `composition-root.ts`:
+   ```ts
+   import { ProductoModel } from './modules/producto/types'
+   import { ProductoModule } from './modules/producto'
+
+   orm.define('Producto', ProductoModel)
+   system.addModule(ProductoModule())
+   ```
+
+---
+
+## 3. `arckode make:connector` — Lo que genera
+
+```bash
+arckode make:connector pedido-inventario pedidos inventario
+```
+
+Genera `src/connectors/pedido-inventario.ts`:
+```ts
+import type { ConnectorContext } from 'arckode-framework'
+import type { PedidosService }    from '../modules/pedidos'
+import type { InventarioService } from '../modules/inventario'
+
+export function conectarPedidoConInventario(ctx: ConnectorContext): void {
+  const pedidos    = ctx.resolveModule<PedidosService>('pedidos')
+  const inventario = ctx.resolveModule<InventarioService>('inventario')
+
+  // TODO: inyectar sockets
+  pedidos.setSockets({
+    // onEventoEjemplo: async (data) => { await inventario.accion(data) }
+  })
+}
+```
+
+**Después de generar:**
+1. Implementar los sockets necesarios
+2. Agregar a `composition-root.ts`:
+   ```ts
+   import { conectarPedidoConInventario } from './connectors/pedido-inventario'
+   system.addConnector('pedido-inventario', conectarPedidoConInventario)
+   ```
+
+---
+
+## 4. `arckode analyze` — Violaciones detectadas
+
+```bash
+arckode analyze
+```
+
+Output ejemplo:
+```
+🔍 Analizando proyecto...
+
+❌ DIRECT_MODULE_IMPORT         modules/pedidos/actions/service.ts:5
+   "import { ProductosService } from '../productos/actions/service'"
+   → Los módulos no pueden importar de otros módulos directamente.
+
+❌ CONTROLLER_MISSING_VALIDATION modules/productos/actions/controller.ts:23
+   "router.post sin validateSchema()"
+   → Todo POST debe validar el body antes de llamar al service.
+
+⚠️  MISSING_SOCKETS             modules/usuarios/
+   → El módulo no tiene sockets.ts
+
+✅ Sin violaciones en: pedidos, inventario, auth
+
+Resumen: 2 errores, 1 advertencia
+```
+
+**Violaciones críticas (❌):** Deben corregirse antes del merge.
+**Advertencias (⚠️):** Recomendadas pero no bloqueantes.
+
+### Tabla completa de checks
+
+| Código | Severidad | Descripción |
+|--------|-----------|-------------|
+| `MISSING_INDEX` | ❌ | Módulo sin index.ts |
+| `MISSING_SERVICE` | ❌ | Sin actions/service.ts |
+| `MISSING_CONTROLLER` | ❌ | Sin actions/controller.ts |
+| `MISSING_TYPES` | ❌ | Sin types.ts |
+| `MISSING_VALIDATORS` | ❌ | Sin validators/schema.ts |
+| `MISSING_TESTS` | ❌ | Sin directorio tests/ |
+| `MISSING_SOCKETS` | ⚠️ | Sin sockets.ts |
+| `MISSING_CONNECTORS` | ⚠️ | 2+ módulos sin conectores definidos |
+| `DIRECT_MODULE_IMPORT` | ❌ | Un módulo importa de otro |
+| `CONNECTOR_BUSINESS_LOGIC` | ❌ | Conector con if/for/lógica |
+| `CONTROLLER_MISSING_VALIDATION` | ❌ | POST/PUT/PATCH sin validateSchema |
+| `BUSINESS_LOGIC_IN_CONTROLLER` | ❌ | ORM directo en controller |
+| `EMPTY_MODULE_DESCRIPTION` | ❌ | description: '' en createModule |
+| `TESTS_WITHOUT_CASES` | ❌ | Archivo test sin test() |
+| `SERVICE_IMPORTS_OTHER_MODULE` | ❌ | Service importa de otro módulo |
+| `GOD_SERVICE` | ⚠️ | Service > 200 líneas |
+| `N_PLUS_ONE_RISK` | ⚠️ | ORM dentro de loop |
+| `IDOR_RISK` | ❌ | findById sin assertOwnership |
+| `SERVICE_DEPENDS_ON_ORM` | ❌ | Service recibe ORM, no RepositoryAdapter |
+
+---
+
+## 5. `arckode routes` — Ver rutas registradas
+
+```bash
+arckode routes
+```
+
+Output:
+```
+GET    /productos
+POST   /productos          [validate: crearProductoSchema]
+GET    /productos/:id
+PUT    /productos/:id      [auth: admin] [validate: actualizarProductoSchema]
+DELETE /productos/:id      [auth: admin]
+POST   /auth/login
+POST   /auth/registro
+POST   /auth/refresh
+```
+
+---
+
+## 6. `arckode db:migrate` — Migraciones SQL
+
+```bash
+# Ver pendientes y correrlos
+arckode db:migrate
+
+# Revertir último
+arckode db:migrate --rollback
+```
+
+**Tabla de control:** `_arckode_migrations` (columnas: name, runAt, direction)
+
+**Los archivos de migración van en `src/migrations/`:**
+```
+src/migrations/
+  1716000000_create_productos.ts
+  1716100000_add_stock_to_productos.ts
+  1716200000_add_index_pedidos_usuario.ts
+```
+
+El timestamp en el nombre determina el orden de ejecución.
+
+---
+
+## 7. `arckode new` — Proyecto desde cero
+
+```bash
+arckode new mi-api
+cd mi-api
+```
+
+Genera:
+```
+mi-api/
+├── src/
+│   ├── composition-root.ts   ← con loadEnv(), ORM, Router, System
+│   └── modules/
+│       └── .gitkeep
+├── .env.example
+├── .gitignore
+├── CLAUDE.md                 ← apunta a este skill
+├── package.json              ← arckode-framework como dependencia
+└── tsconfig.json             ← strict mode
+```
+
+---
+
+## 8. INTEGRAR CON CI/CD
+
+```yaml
+# .github/workflows/ci.yml
+- name: Analyze architecture
+  run: arckode analyze --strict  # falla el CI si hay violaciones
+
+- name: Run tests
+  run: bun test
+
+- name: Type check
+  run: bun run --bun tsc --noEmit
+```
+
+---
+
+## 9. WORKFLOW COMPLETO — Agregar feature
+
+```bash
+# 1. Generar el módulo
+arckode make:module Pago
+
+# 2. Ajustar types.ts con los campos reales
+
+# 3. Ajustar validators/schema.ts
+
+# 4. Implementar service.ts (lógica de negocio)
+
+# 5. Si se conecta con otro módulo
+arckode make:connector pago-pedido pagos pedidos
+
+# 6. Agregar a composition-root.ts
+
+# 7. Si necesita migración SQL
+arckode make:migration add_pagos_table
+
+# 8. Verificar todo
+bun run src/composition-root.ts  # sin errores TypeScript
+arckode analyze                  # 0 violaciones críticas
+bun test modules/pago            # tests pasan
+arckode routes                   # rutas visibles
+```