arckode-framework 1.3.2 → 1.4.0

package/kernel/modules/system.ts

@@ -0,0 +1,149 @@
+import { InternalError, ModuleRuleError, NotFoundError } from '../errors'
+import type { Logger } from '../logger'
+import type { ConfigStore } from '../config'
+import type { Container } from '../container'
+import type { ORM } from '../db/orm'
+import type { Router } from '../http/router'
+import type { ServerAdapter } from '../http/server'
+import type { CacheAdapter } from '../cache'
+import type { Auth } from '../auth'
+import type {
+  ConnectorContext,
+  ConnectorDefinition,
+  ModuleDefinition,
+  ModuleDependencies,
+  SocketsAware,
+} from './types'
+
+export class System {
+  public readonly logger: Logger
+  public readonly config: ConfigStore
+  public readonly container: Container
+  public readonly orm: ORM
+  public readonly router: Router
+  public readonly http: ServerAdapter
+  public readonly cache: CacheAdapter
+  public readonly auth?: Auth
+
+  private modules = new Map<string, { definition: ModuleDefinition<unknown>; instance: unknown; sockets?: Record<string, unknown> }>()
+  private connectors: { name: string; fn: ConnectorDefinition }[] = []
+  private initialized = false
+
+  constructor(params: {
+    config: ConfigStore
+    container: Container
+    logger: Logger
+    orm: ORM
+    router: Router
+    http: ServerAdapter
+    cache: CacheAdapter
+    auth?: Auth
+  }) {
+    this.config = params.config
+    this.container = params.container
+    this.logger = params.logger
+    this.orm = params.orm
+    this.router = params.router
+    this.http = params.http
+    this.cache = params.cache
+    this.auth = params.auth
+  }
+
+  addModule<T>(definition: ModuleDefinition<T>): this {
+    if (this.initialized) throw new InternalError(`Cannot add module "${definition.name}" after initialization`)
+    const c = definition.contract
+    if (!c.name?.trim()) throw new ModuleRuleError(definition.name, 'contract.name no puede estar vacío')
+    if (!c.version?.trim()) throw new ModuleRuleError(definition.name, 'contract.version no puede estar vacío')
+    if (!c.description?.trim()) throw new ModuleRuleError(definition.name, 'contract.description no puede estar vacío')
+    for (const dep of c.dependencies ?? []) {
+      if (!this.modules.has(dep)) {
+        throw new ModuleRuleError(definition.name, `dependencia "${dep}" no está registrada — registrá los módulos en orden de dependencia`)
+      }
+    }
+    this.modules.set(definition.name, { definition, instance: undefined })
+    return this
+  }
+
+  addConnector(name: string, fn: ConnectorDefinition): this {
+    this.connectors.push({ name, fn })
+    return this
+  }
+
+  resolveModule<T>(name: string): T {
+    const entry = this.modules.get(name)
+    if (!entry?.instance) throw new NotFoundError(`Module "${name}" not found or not initialized`)
+    return entry.instance as T
+  }
+
+  getModule<T>(name: string): T {
+    return this.resolveModule<T>(name)
+  }
+
+  init(): void {
+    if (this.initialized) return
+    this.initialized = true
+
+    this.container.init()
+
+    for (const [name, entry] of this.modules) {
+      const deps: ModuleDependencies = {
+        logger: this.logger.child(name),
+        orm: this.orm,
+        router: this.router,
+        config: this.config,
+        cache: this.cache,
+        auth: this.auth,
+      }
+
+      entry.instance = entry.definition.create(deps)
+      this.logger.info(`Module initialized: ${name} v${entry.definition.version}`)
+    }
+
+    for (const connector of this.connectors) {
+      const ctx: ConnectorContext = {
+        resolveModule: <T>(name: string, sockets?: Record<string, unknown>): T => {
+          const instance = this.resolveModule<Record<string, unknown>>(name)
+          if (sockets && typeof instance === 'object' && instance) {
+            if ('setSockets' in instance && typeof (instance as unknown as SocketsAware).setSockets === 'function') {
+              ;(instance as unknown as SocketsAware).setSockets(sockets)
+            }
+          }
+          return instance as unknown as T
+        },
+      }
+
+      connector.fn(ctx)
+      this.logger.info(`Connector executed: ${connector.name}`)
+    }
+  }
+
+  async start(): Promise<void> {
+    this.router.setLogger(this.logger)
+    this.init()
+    await this.http.start((req) => this.router.resolve(req.method, req.path, req))
+    this.logger.info('══════════════════════════════════')
+    this.logger.info('  System started successfully')
+    this.logger.info(`  Modules: ${[...this.modules.keys()].join(', ')}`)
+    this.logger.info(`  Connectors: ${this.connectors.map(c => c.name).join(', ')}`)
+    this.logger.info('══════════════════════════════════')
+  }
+
+  async stop(): Promise<void> {
+    this.logger.info('Shutting down system...')
+
+    for (const [name, entry] of this.modules) {
+      if (entry.definition.onStop && entry.instance) {
+        try {
+          await entry.definition.onStop(entry.instance)
+          this.logger.info(`Module stopped: ${name}`)
+        } catch (e) {
+          this.logger.error(`Error stopping module "${name}"`, { error: String(e) })
+        }
+      }
+    }
+
+    await this.http.stop()
+    await this.container.destroy()
+    this.logger.info('System stopped')
+  }
+}

package/kernel/modules/types.ts

@@ -0,0 +1,46 @@
+import type { Logger } from '../logger'
+import type { ORM } from '../db/orm'
+import type { Router } from '../http/router'
+import type { ConfigStore } from '../config'
+import type { CacheAdapter } from '../cache'
+import type { Auth } from '../auth'
+
+export interface ModuleContract {
+  name: string
+  version: string
+  description: string
+  actions: string[]
+  events: string[]
+  tables: string[]
+  dependencies: string[]
+  rules: string[]
+}
+
+export interface ModuleDependencies {
+  logger: Logger
+  orm: ORM
+  router: Router
+  config: ConfigStore
+  cache: CacheAdapter
+  auth?: Auth
+}
+
+export interface SocketsAware {
+  setSockets(sockets: Record<string, unknown>): void
+}
+
+export interface ModuleDefinition<TModule> {
+  name: string
+  version: string
+  description: string
+  contract: ModuleContract
+  create(deps: ModuleDependencies): TModule
+  validate?(instance: TModule): void
+  onStop?(instance: TModule): Promise<void>
+}
+
+export interface ConnectorContext {
+  resolveModule<T>(name: string, sockets?: Record<string, unknown>): T
+}
+
+export type ConnectorDefinition = (ctx: ConnectorContext) => void | Promise<void>

package/kernel/seeds.ts

@@ -0,0 +1,48 @@
+import { NotFoundError } from './errors'
+import type { Logger } from './logger'
+import type { ORM } from './db/orm'
+
+export type SeedFunction = (orm: ORM) => Promise<void>
+
+export class SeedRunner {
+  private seeds: { name: string; run: SeedFunction }[] = []
+
+  constructor(
+    private orm: ORM,
+    private logger: Logger,
+  ) {}
+
+  add(name: string, run: SeedFunction): this {
+    this.seeds.push({ name, run })
+    return this
+  }
+
+  async runAll(): Promise<void> {
+    for (const seed of this.seeds) {
+      try {
+        await seed.run(this.orm)
+        this.logger.info(`Seed executed: ${seed.name}`)
+      } catch (error) {
+        this.logger.error(`Error in seed "${seed.name}"`, { error: String(error) })
+        throw error
+      }
+    }
+  }
+
+  async runOne(name: string): Promise<void> {
+    const seed = this.seeds.find(s => s.name === name)
+    if (!seed) throw new NotFoundError(`Seed "${name}" not found`)
+
+    try {
+      await seed.run(this.orm)
+      this.logger.info(`Seed executed: ${name}`)
+    } catch (error) {
+      this.logger.error(`Error in seed "${name}"`, { error: String(error) })
+      throw error
+    }
+  }
+
+  get list(): string[] {
+    return this.seeds.map(s => s.name)
+  }
+}

package/kernel/static.ts

@@ -3,7 +3,7 @@
 // SOLID: responsabilidad ÚNICA de servir archivos estáticos
 
 import { readFile, access } from 'node:fs/promises'
-import { join, extname } from 'node:path'
+import { join, extname, resolve, sep } from 'node:path'
 import type { Router, MiddlewareHandler } from './framework'
 
 export interface StaticOptions {
@@ -37,9 +37,18 @@ export function serveStatic(
 ): void {
   const { prefix = '', fallback, cacheControl = 'public, max-age=3600' } = options
 
+  const resolvedBase = resolve(basePath)
+
   // GET /* → intenta servir archivo estático
   router.get(`${prefix}/:path(*)`, async (req) => {
-    const filePath = join(basePath, req.params['path'] || 'index.html')
+    const requestedPath = req.params['path'] || 'index.html'
+    const filePath = join(basePath, requestedPath)
+
+    // Path traversal protection: %2e%2e%2f decodificado puede escapar basePath
+    const resolvedFile = resolve(filePath)
+    if (!resolvedFile.startsWith(resolvedBase + sep) && resolvedFile !== resolvedBase) {
+      return { status: 403, body: { error: 'Forbidden' } }
+    }
 
     try {
       await access(filePath)

package/kernel/testing.ts

@@ -4,10 +4,15 @@
 // Diseño: sin dependencias externas, compatible con bun:test, Jest y Vitest.
 
 import { request as httpRequest } from 'node:http'
-import type { HttpRequest, HttpResponse, MiddlewareHandler } from './framework'
+import type { HttpRequest, HttpResponse, MiddlewareHandler, LoggerTransport } from './framework'
 import { Router, ORM, Logger, NodeServer } from './framework'
 import type { DbAdapter } from './framework'
 
+// Transport que descarta todo — silencia ABSOLUTAMENTE todos los logs en tests
+class NoopTransport implements LoggerTransport {
+  write(): void {}
+}
+
 // ═══════════════════════════════════════════════════════════════
 // TEST CLIENT — hace requests a un Router sin levantar HTTP
 // ═══════════════════════════════════════════════════════════════
@@ -140,14 +145,14 @@ export function mockAuth(opts: MockAuthOptions = {}): MiddlewareHandler {
 // ═══════════════════════════════════════════════════════════════
 
 /**
- * Logger que no imprime nada. Úsalo en tests para silenciar output.
+ * Logger que no imprime nada — ni errores. Úsalo en tests para silenciar output.
  *
  * @example
  * const logger = silentLogger()
  * const service = new MiService(orm, logger)
  */
 export function silentLogger(): Logger {
-  return new Logger('test', 'error')
+  return new Logger('test', 'error', [new NoopTransport()])
 }
 
 // ═══════════════════════════════════════════════════════════════

package/kernel/validator.ts

@@ -0,0 +1,116 @@
+import { ValidationError } from './errors'
+
+export type ValidatorType = 'string' | 'number' | 'boolean' | 'email' | 'url' | 'date'
+
+export interface ValidationRule {
+  type: ValidatorType
+  required?: boolean
+  min?: number
+  max?: number
+  pattern?: RegExp
+  enum?: string[]
+  message?: string
+  sanitize?: boolean | 'html'
+}
+
+export type ValidationSchema = Record<string, ValidationRule>
+
+export function validateSchema(schema: ValidationSchema, input: unknown): Record<string, unknown> {
+  const errors: Record<string, string[]> = {}
+  const output: Record<string, unknown> = {}
+
+  if (typeof input !== 'object' || input === null) {
+    throw new ValidationError('Request body must be an object')
+  }
+
+  const data = input as Record<string, unknown>
+
+  for (const [field, rule] of Object.entries(schema)) {
+    const value = data[field]
+    const fieldErrors: string[] = []
+
+    if (value === undefined || value === null) {
+      if (rule.required) {
+        fieldErrors.push(rule.message ?? `${field} is required`)
+        errors[field] = fieldErrors
+      }
+      continue
+    }
+
+    switch (rule.type) {
+      case 'string': {
+        if (typeof value !== 'string') {
+          fieldErrors.push(`${field} must be a string`)
+        } else {
+          let sanitized = value.trim().replace(/\s+/g, ' ')
+          if (rule.sanitize === 'html') {
+            sanitized = sanitized
+              .replace(/&/g, '&amp;')
+              .replace(/</g, '&lt;')
+              .replace(/>/g, '&gt;')
+              .replace(/"/g, '&quot;')
+              .replace(/'/g, '&#x27;')
+          }
+          if (rule.min !== undefined && sanitized.length < rule.min) fieldErrors.push(`Minimum ${rule.min} characters`)
+          if (rule.max !== undefined && sanitized.length > rule.max) fieldErrors.push(`Maximum ${rule.max} characters`)
+          if (rule.pattern && !rule.pattern.test(sanitized)) fieldErrors.push(rule.message ?? 'Invalid format')
+          if (rule.enum && !rule.enum.includes(sanitized)) fieldErrors.push(`Must be one of: ${rule.enum.join(', ')}`)
+          output[field] = sanitized
+        }
+        break
+      }
+      case 'number': {
+        const num = typeof value === 'string' ? Number(value) : value
+        if (typeof num !== 'number' || isNaN(num)) {
+          fieldErrors.push(`${field} must be a number`)
+        } else {
+          if (rule.min !== undefined && num < rule.min) fieldErrors.push(`Minimum ${rule.min}`)
+          if (rule.max !== undefined && num > rule.max) fieldErrors.push(`Maximum ${rule.max}`)
+          output[field] = num
+        }
+        break
+      }
+      case 'boolean': {
+        if (typeof value !== 'boolean') {
+          fieldErrors.push(`${field} must be a boolean`)
+        } else {
+          output[field] = value
+        }
+        break
+      }
+      case 'email': {
+        if (typeof value !== 'string' || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+          fieldErrors.push(rule.message ?? `${field} is not a valid email`)
+        } else {
+          output[field] = value
+        }
+        break
+      }
+      case 'url': {
+        if (typeof value !== 'string') { fieldErrors.push(`${field} must be a string`) }
+        else {
+          try { new URL(value); output[field] = value } catch { fieldErrors.push(rule.message ?? `${field} is not a valid URL`) }
+        }
+        break
+      }
+      case 'date': {
+        if (typeof value !== 'string' || isNaN(Date.parse(value))) {
+          fieldErrors.push(rule.message ?? `${field} is not a valid date`)
+        } else {
+          output[field] = value
+        }
+        break
+      }
+    }
+
+    if (fieldErrors.length > 0) {
+      errors[field] = fieldErrors
+    }
+  }
+
+  if (Object.keys(errors).length > 0) {
+    throw new ValidationError('Validation error', errors)
+  }
+
+  return output
+}

package/modules/events/index.ts

@@ -18,12 +18,28 @@ export interface EventBusAdapter {
   unsubscribe(name: string, handler: EventHandler): void
 }
 
+export interface EventBusOptions {
+  adapter?: EventBusAdapter
+  onError?: (event: string, error: unknown) => void
+}
+
 export class EventBus {
   private handlers = new Map<string, Set<EventHandler>>()
   private history: EventMessage[] = []
   private maxHistory = 100
-
-  constructor(private adapter?: EventBusAdapter) {}
+  private onError: (event: string, error: unknown) => void
+  private adapter?: EventBusAdapter
+
+  constructor(adapterOrOptions?: EventBusAdapter | EventBusOptions) {
+    if (adapterOrOptions && 'publish' in adapterOrOptions) {
+      this.adapter = adapterOrOptions
+      this.onError = (ev, e) => console.error(`[EventBus] Error en handler para "${ev}":`, e)
+    } else {
+      const opts = (adapterOrOptions ?? {}) as EventBusOptions
+      this.adapter = opts.adapter
+      this.onError = opts.onError ?? ((ev, e) => console.error(`[EventBus] Error en handler para "${ev}":`, e))
+    }
+  }
 
   async emit(name: string, data: unknown, source: string = 'system'): Promise<void> {
     const event: EventMessage = {
@@ -42,7 +58,7 @@ export class EventBus {
     const localHandlers = this.handlers.get(name)
     if (localHandlers) {
       await Promise.allSettled([...localHandlers].map(h => h(event).catch(e => {
-        console.error(`[EventBus] Error en handler para "${name}":`, e)
+        this.onError(name, e)
       })))
     }
 

package/modules/mail/index.ts

@@ -34,18 +34,30 @@ export class MailService {
   }
 
   async sendWelcome(email: string, name: string): Promise<void> {
+    const safeName = MailService.escapeHtml(name)
     await this.send({
       to: { address: email, name },
       subject: 'Welcome',
-      html: `<h1>Welcome, ${name}!</h1><p>Thanks for signing up.</p>`,
+      html: `<h1>Welcome, ${safeName}!</h1><p>Thanks for signing up.</p>`,
     })
   }
 
   async sendPasswordReset(email: string, token: string): Promise<void> {
+    const safeToken = MailService.escapeHtml(token)
     await this.send({
       to: { address: email },
       subject: 'Password reset',
-      html: `<p>Use this token to reset your password: <b>${token}</b></p>`,
+      html: `<p>Use this token to reset your password: <b>${safeToken}</b></p>`,
     })
   }
+
+  /** Escapa caracteres HTML especiales en strings que se insertan en plantillas de email. */
+  static escapeHtml(str: string): string {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#x27;')
+  }
 }

package/modules/storage/local-adapter.ts

@@ -2,23 +2,36 @@
 // Almacena archivos en el sistema de archivos local
 
 import { mkdir, writeFile, unlink } from 'node:fs/promises'
-import { join, extname } from 'node:path'
+import { join, extname, resolve, sep } from 'node:path'
 import type { StorageAdapter, FileUpload, StoredFile } from './index'
 
 export class LocalStorageAdapter implements StorageAdapter {
+  private readonly resolvedBase: string
+
   constructor(
     private basePath: string = './uploads',
     private baseUrl: string = '/uploads',
-  ) {}
+  ) {
+    this.resolvedBase = resolve(basePath)
+  }
+
+  /** Resuelve un subpath de forma segura. Lanza si intenta escapar del basePath. */
+  private resolveSafe(subpath: string): string {
+    const full = resolve(join(this.basePath, subpath))
+    if (!full.startsWith(this.resolvedBase + sep) && full !== this.resolvedBase) {
+      throw new Error(`Path traversal detectado: "${subpath}" escapa del directorio de uploads`)
+    }
+    return full
+  }
 
   async upload(file: FileUpload, directory?: string): Promise<StoredFile> {
     const dir = directory ?? 'general'
     const ext = extname(file.originalName)
     const filename = `${Date.now()}-${Math.random().toString(36).slice(2)}${ext}`
     const relativePath = `${dir}/${filename}`
-    const fullPath = join(this.basePath, relativePath)
+    const fullPath = this.resolveSafe(relativePath)
 
-    await mkdir(join(this.basePath, dir), { recursive: true })
+    await mkdir(resolve(join(this.basePath, dir)), { recursive: true })
     await writeFile(fullPath, file.buffer)
 
     return {
@@ -31,11 +44,12 @@ export class LocalStorageAdapter implements StorageAdapter {
   }
 
   async delete(path: string): Promise<void> {
-    const fullPath = join(this.basePath, path)
+    const fullPath = this.resolveSafe(path)
     await unlink(fullPath).catch(() => {})
   }
 
   getUrl(path: string): string {
+    // Solo construye la URL — no accede al sistema de archivos, no hay riesgo de traversal.
     return `${this.baseUrl}/${path}`
   }
 }