arckode-framework 1.3.1 → 1.4.0

package/cli/stubs/module-stub.ts

@@ -1,552 +1,2 @@
-// cli/stubs/module-stub.ts — Plantillas para generar módulos completos
-// Usadas por el generador. Cada stub produce código 100% correcto.
-
-export interface ModuleStubParams {
-  name: string       // PascalCase: Producto
-  module: string     // kebab-case: productos
-  fields: { name: string; type: 'string' | 'number' | 'boolean' | 'date'; required: boolean; default?: unknown }[]
-  relations?: { type: 'hasMany' | 'belongsTo'; model: string; foreignKey: string }[]
-  softDelete?: boolean
-}
-
-export function indexStub(p: ModuleStubParams): string {
-  const actions = ['list', 'getById', 'create', 'update', 'delete']
-  const events = [`on${p.name}Created`, `on${p.name}Updated`, `on${p.name}Deleted`]
-
-  return `// ${p.module}/index.ts — PUERTA PÚBLICA
-// Solo esto es visible para otros módulos y conectores.
-// ⚠ REGLA: Append-only. No sacar ni modificar exports existentes.
-
-import { createModule, OrmRepository } from 'arckode-framework'
-import { register${p.name}Models } from './model'
-import { ${p.name}Service } from './service'
-import { ${p.name}Controller } from './controller'
-import type { ${p.name}DTO } from './types'
-
-export { ${p.name}Service }
-export type { ${p.name}DTO, Create${p.name}DTO, Update${p.name}DTO, ${p.name}Query, ${p.name}Paginated } from './types'
-export type { ${p.name}Sockets } from './sockets'
-export { ${p.name}Validator, Create${p.name}Schema, Update${p.name}Schema } from './validators/schema'
-
-export function ${p.name}Module() {
-  return createModule({
-    name: '${p.module}',
-    version: '1.0.0',
-    description: 'Módulo de ${p.module}',
-
-    contract: {
-      name: '${p.module}',
-      version: '1.0.0',
-      description: 'Módulo de ${p.module}',
-      actions: ${JSON.stringify(actions)},
-      events: ${JSON.stringify(events)},
-      tables: ['${p.module}'],
-      dependencies: [],
-      rules: ['No importar de otros módulos'],
-    },
-
-    create({ logger, orm, cache, router, auth }) {
-      // Registrar modelo(s) — delegado a model.ts
-      register${p.name}Models(orm)
-
-      const repo = new OrmRepository<${p.name}DTO>(orm, '${p.name}')
-      const log = logger.child('${p.module}')
-      const service = new ${p.name}Service(repo, log, cache)
-      const controller = new ${p.name}Controller(service, log)
-
-      // Rutas públicas por defecto — agregar [auth.authenticate()] para proteger
-      router.get('/${p.module}', (req) => controller.index(req))
-      router.get('/${p.module}/:id', (req) => controller.show(req))
-      router.post('/${p.module}', (req) => controller.store(req))
-      router.put('/${p.module}/:id', (req) => controller.update(req))
-      router.delete('/${p.module}/:id', (req) => controller.destroy(req))
-
-      log.info('Módulo ${p.module} listo')
-      return service
-    },
-  })
-}
-`
-}
-
-// ─── model.ts — Definición de DB (schema) ───
-// Separado de types.ts porque conceptualmente describe la PERSISTENCIA (la DB),
-// no el contrato de TypeScript (DTOs). Cambia con migraciones, no con la API.
-export function modelStub(p: ModuleStubParams): string {
-  const modelFields = p.fields
-    .filter(f => !['id', 'createdAt', 'updatedAt', 'deletedAt'].includes(f.name))
-    .map(f => {
-      const parts = [`    ${f.name}: { type: '${f.type}'`]
-      if (f.required) parts.push(`, required: true`)
-      if (f.default !== undefined) parts.push(`, default: ${JSON.stringify(f.default)}`)
-      parts.push(` }`)
-      return parts.join('')
-    })
-    .join(',\n')
-
-  return `// ${p.module}/model.ts — Schema de base de datos
-// Responsabilidad ÚNICA: describir la estructura física de la tabla.
-// Importado por index.ts → orm.define() para registrar el modelo.
-//
-// Si el módulo tiene 3+ tablas, agregá registerModels(orm) acá y delegá desde index.ts.
-
-import type { ModelDefinition, ORM } from 'arckode-framework'
-
-export const ${p.name}Model: ModelDefinition = {
-  table: '${p.module}',
-  fields: {
-${modelFields}
-  },
-  timestamps: true,
-${p.softDelete ? '  softDelete: true,' : ''}
-}
-
-// Helper opcional — usalo si el módulo registra 3+ tablas
-// (mantiene index.ts limpio, enfocado en wiring)
-export function register${p.name}Models(orm: ORM): void {
-  orm.define('${p.name}', ${p.name}Model)
-}
-`
-}
-
-export function typesStub(p: ModuleStubParams): string {
-  const fields = p.fields.map(f => `  ${f.name}${f.required ? '' : '?'}: ${mapTS(f.type)}`).join('\n')
-  const filterFields = p.fields.map(f => `  ${f.name}?: ${mapTS(f.type)}`).join('\n')
-
-  return `// ${p.module}/types.ts — DTOs y tipos de queries
-// Responsabilidad ÚNICA: contrato TypeScript del módulo (cómo se ven los datos).
-// El schema de DB vive en ./model.ts — son conceptos distintos.
-
-export interface ${p.name}DTO {
-  id: string
-${fields}
-  createdAt: string
-  updatedAt: string
-${p.softDelete ? '  deletedAt: string | null' : ''}
-}
-
-export interface Create${p.name}DTO {
-${p.fields.filter(f => !f.name.match(/^(id|createdAt|updatedAt|deletedAt)$/)).map(f => `  ${f.name}${f.required ? '' : '?'}: ${mapTS(f.type)}`).join('\n')}
-}
-
-export interface Update${p.name}DTO {
-${p.fields.filter(f => !f.name.match(/^(id|createdAt|updatedAt|deletedAt)$/)).map(f => `  ${f.name}?: ${mapTS(f.type)}`).join('\n')}
-}
-
-// ─── Consultas y paginación ────────────────────────────
-export interface ${p.name}Query {
-${filterFields}
-  page?: number
-  limit?: number
-  sortBy?: string
-  sortOrder?: 'asc' | 'desc'
-  search?: string
-}
-
-export interface ${p.name}Paginated {
-  data: ${p.name}DTO[]
-  pagination: {
-    page: number
-    limit: number
-    total: number
-    totalPages: number
-    hasNext: boolean
-    hasPrev: boolean
-  }
-}
-`
-}
-
-export function socketsStub(p: ModuleStubParams): string {
-  return `// ${p.module}/sockets.ts — Hooks OPCIONALES hacia otros módulos
-// Los sockets son opcionales. El módulo funciona sin ellos.
-// Un conector puede pasar sockets para reaccionar a eventos del módulo.
-
-import type { ${p.name}DTO } from './types'
-
-export interface ${p.name}Sockets {
-  on${p.name}Created?: (data: ${p.name}DTO) => Promise<void>
-  on${p.name}Updated?: (data: ${p.name}DTO) => Promise<void>
-  on${p.name}Deleted?: (id: string) => Promise<void>
-}
-`
-}
-
-export function serviceStub(p: ModuleStubParams): string {
-  const hasSearch = p.fields.some(f => f.type === 'string')
-
-  return `// ${p.module}/service.ts — Facade pública del módulo
-// Responsabilidad ÚNICA: casos de uso del módulo.
-// NO sabe de HTTP. NO importa de otros módulos.
-// Recibe dependencias por constructor (Dependency Inversion).
-//
-// Si este archivo supera 200 líneas → extraer casos de uso a ./usecases/{caso}.ts
-// y dejar acá solo el orquestador que delega.
-//
-// IMPORTANTE: depende de RepositoryAdapter<${p.name}DTO>, no del ORM directamente.
-// Esto permite swapear SQL → MongoDB → Prisma en composition-root.ts sin tocar este archivo.
-
-import type { RepositoryAdapter, Logger, CacheAdapter } from 'arckode-framework'
-import { NotFoundError } from 'arckode-framework'
-import type { ${p.name}DTO, Create${p.name}DTO, Update${p.name}DTO, ${p.name}Query, ${p.name}Paginated } from './types'
-import type { ${p.name}Sockets } from './sockets'
-
-export class ${p.name}Service {
-  private sockets: ${p.name}Sockets = {}
-
-  constructor(
-    private readonly repo: RepositoryAdapter<${p.name}DTO>,
-    private readonly logger: Logger,
-    private readonly cache: CacheAdapter,
-  ) {}
-
-  // ACUMULA handlers — nunca pisa el anterior.
-  // Si dos conectores registran el mismo evento, ambos corren en cadena (secuencial).
-  // Para ejecución paralela independiente → usar EventBus en composition-root.ts.
-  setSockets(s: Partial<${p.name}Sockets>): void {
-    const next = s as Record<string, any>
-    const cur = this.sockets as Record<string, any>
-    for (const key of Object.keys(next)) {
-      const h = next[key]
-      if (!h) continue
-      const prev = cur[key]
-      cur[key] = prev ? async (...a: any[]) => { await prev(...a); await h(...a) } : h
-    }
-  }
-
-  async list(query?: ${p.name}Query): Promise<${p.name}Paginated> {
-    this.logger.info('Listando ${p.module}', { query })
-
-    const page = query?.page ?? 1
-    const limit = query?.limit ?? 20
-    const offset = (page - 1) * limit
-    const filters: Record<string, unknown> = {}
-
-    ${p.fields.filter(f => f.name !== 'id').slice(0, 3).map(f => `if (query?.${f.name} !== undefined) filters.${f.name} = query.${f.name}`).join('\n    ')}
-
-    const result = await this.repo.paginate(filters, { limit, offset })
-
-    return {
-      data: result.data,
-      pagination: {
-        page,
-        limit,
-        total: result.total,
-        totalPages: result.pages,
-        hasNext: offset + limit < result.total,
-        hasPrev: page > 1,
-      },
-    }
-  }
-
-  async getById(id: string): Promise<${p.name}DTO> {
-    this.logger.info('Obteniendo ${p.module}', { id })
-    const item = await this.repo.findById(id)
-    if (!item) throw new NotFoundError('${p.name} no encontrado')
-    // IDOR: si el recurso tiene userId u ownerId, descomentar y adaptar:
-    // auth.assertOwnership(item.userId as string, currentUser.id, currentUser.role)
-    return item
-  }
-
-  async create(dto: Create${p.name}DTO): Promise<${p.name}DTO> {
-    this.logger.info('Creando ${p.module}')
-    const item = await this.repo.create(dto as Omit<${p.name}DTO, 'id'>)
-    await this.sockets.on${p.name}Created?.(item)
-    await this.cache.delete('${p.module}:list')
-    return item
-  }
-
-  async update(id: string, dto: Update${p.name}DTO): Promise<${p.name}DTO> {
-    this.logger.info('Actualizando ${p.module}', { id })
-    const item = await this.repo.update(id, dto as Partial<Omit<${p.name}DTO, 'id'>>)
-    if (!item) throw new NotFoundError('${p.name} no encontrado')
-    await this.sockets.on${p.name}Updated?.(item)
-    await this.cache.delete('${p.module}:list')
-    return item
-  }
-
-  async delete(id: string): Promise<void> {
-    this.logger.info('Eliminando ${p.module}', { id })
-    const deleted = await this.repo.delete(id)
-    if (!deleted) throw new NotFoundError('${p.name} no encontrado')
-    await this.sockets.on${p.name}Deleted?.(id)
-    await this.cache.delete('${p.module}:list')
-  }
-}
-`
-}
-
-export function controllerStub(p: ModuleStubParams): string {
-  return `// ${p.module}/controller.ts — Adaptador HTTP del módulo
-// Responsabilidad ÚNICA: traducir request → service → response.
-// SIN lógica de negocio. SIN llamadas directas al ORM. (REGLA #12)
-// Toda mutación (POST/PUT/PATCH) DEBE pasar por validateSchema(). (REGLA #11)
-
-import type { HttpRequest, Logger } from 'arckode-framework'
-import { validateSchema } from 'arckode-framework'
-import type { ${p.name}Service } from './service'
-import { Create${p.name}Schema, Update${p.name}Schema } from './validators/schema'
-
-export class ${p.name}Controller {
-  constructor(
-    private readonly service: ${p.name}Service,
-    private readonly logger: Logger,
-  ) {}
-
-  async index(req: HttpRequest) {
-    this.logger.info('GET /${p.module}')
-    const result = await this.service.list(req.query as any)
-    return { status: 200, body: result }
-  }
-
-  async show(req: HttpRequest) {
-    this.logger.info('GET /${p.module}/:id', { id: req.params.id })
-    const item = await this.service.getById(req.params.id)
-    return { status: 200, body: item }
-  }
-
-  async store(req: HttpRequest) {
-    this.logger.info('POST /${p.module}')
-    const data = validateSchema(Create${p.name}Schema, req.body)
-    const item = await this.service.create(data as any)
-    return { status: 201, body: item }
-  }
-
-  async update(req: HttpRequest) {
-    this.logger.info('PUT /${p.module}/:id', { id: req.params.id })
-    const data = validateSchema(Update${p.name}Schema, req.body)
-    const item = await this.service.update(req.params.id, data as any)
-    return { status: 200, body: item }
-  }
-
-  async destroy(req: HttpRequest) {
-    this.logger.info('DELETE /${p.module}/:id', { id: req.params.id })
-    await this.service.delete(req.params.id)
-    return { status: 204, body: null }
-  }
-}
-`
-}
-
-export function validatorStub(p: ModuleStubParams): string {
-  const createRules = p.fields
-    .filter(f => f.name !== 'id')
-    .map(f => {
-      const parts = [`  ${f.name}: { type: '${f.type}' as const`]
-      if (f.required && f.name !== 'createdAt' && f.name !== 'updatedAt') parts.push(', required: true')
-      if (f.type === 'string' && f.required) parts.push(', min: 2, max: 200')
-      parts.push(' }')
-      return parts.join('')
-    })
-    .join(',\n')
-
-  const updateRules = p.fields
-    .filter(f => f.name !== 'id' && f.name !== 'createdAt')
-    .map(f => {
-      const parts = [`  ${f.name}: { type: '${f.type}' as const`]
-      if (f.type === 'string') parts.push(', min: 2, max: 200')
-      parts.push(' }')
-      return parts.join('')
-    })
-    .join(',\n')
-
-  return `// ${p.module}/validators/schema.ts — Validación de entrada
-// Schemas planos, sin dependencias externas.
-
-import type { ValidationRule } from 'arckode-framework'
-
-export const Create${p.name}Schema: Record<string, ValidationRule> = {
-${createRules}
-}
-
-export const Update${p.name}Schema: Record<string, ValidationRule> = {
-${updateRules}
-}
-
-// Schema compuesto para usar en validación directa
-export const ${p.name}Validator = {
-  create: Create${p.name}Schema,
-  update: Update${p.name}Schema,
-}
-`
-}
-
-export function testStub(p: ModuleStubParams): string {
-  return `// ${p.module}/tests/service.test.ts — Tests del servicio
-// Usa RepositoryAdapter mock — sin dependencia de SQLite ni Postgres.
-
-import { describe, it, expect } from 'bun:test'
-import type { RepositoryAdapter, CacheAdapter } from 'arckode-framework'
-import { silentLogger } from 'arckode-framework/testing'
-import { ${p.name}Service } from '../service'
-import type { ${p.name}DTO } from '../types'
-
-// silentLogger es una factory function — SIEMPRE llamarla con ()
-const log = silentLogger()
-const silentCache: CacheAdapter = { get: async () => null, set: async () => {}, delete: async () => {}, clear: async () => {}, flush: async () => {} }
-
-function makeRepo(overrides: Partial<RepositoryAdapter<${p.name}DTO>> = {}): RepositoryAdapter<${p.name}DTO> {
-  return {
-    findMany: async () => [],
-    findById: async () => null,
-    findOne: async () => null,
-    create: async (data) => ({ id: 'test-id', ...data } as ${p.name}DTO),
-    update: async (id, data) => ({ id, ...data } as ${p.name}DTO),
-    delete: async () => true,
-    count: async () => 0,
-    paginate: async () => ({ data: [], total: 0, limit: 20, offset: 0, pages: 0 }),
-    ...overrides,
-  }
-}
-
-describe('${p.name}Service', () => {
-  describe('getById', () => {
-    it('lanza NotFound si el item no existe', async () => {
-      const service = new ${p.name}Service(makeRepo(), log, silentCache)
-      await expect(service.getById('no-existe')).rejects.toThrow('${p.name} no encontrado')
-    })
-
-    it('retorna el item si existe', async () => {
-      const item = { id: '1' } as ${p.name}DTO
-      const service = new ${p.name}Service(makeRepo({ findById: async () => item }), log, silentCache)
-      expect(await service.getById('1')).toEqual(item)
-    })
-  })
-
-  describe('create', () => {
-    it('crea y retorna el item', async () => {
-      const service = new ${p.name}Service(makeRepo(), log, silentCache)
-      const result = await service.create({} as any)
-      expect(result.id).toBe('test-id')
-    })
-  })
-
-  describe('delete', () => {
-    it('lanza NotFound si el item no existe', async () => {
-      const service = new ${p.name}Service(makeRepo({ delete: async () => false }), log, silentCache)
-      await expect(service.delete('no-existe')).rejects.toThrow('${p.name} no encontrado')
-    })
-  })
-})
-`
-}
-
-export function migrationStub(p: ModuleStubParams): string {
-  // Tipos ANSI SQL — compatibles con SQLite, MySQL y Postgres sin modificaciones
-  const sqlType = (f: ModuleStubParams['fields'][0]): string => {
-    if (f.name === 'id') return 'VARCHAR(36)'
-    const map: Record<string, string> = {
-      string:  'VARCHAR(255)',
-      number:  'DECIMAL(15,4)',
-      boolean: 'BOOLEAN',
-      date:    'TIMESTAMP',
-      json:    'TEXT',
-    }
-    return map[f.type] ?? 'TEXT'
-  }
-
-  const cols = p.fields.map(f => {
-    const pk  = f.name === 'id' ? ' PRIMARY KEY' : ''
-    const req = f.required && f.name !== 'id' ? ' NOT NULL' : ''
-    const def = f.default !== undefined ? ` DEFAULT ${typeof f.default === 'string' ? `'${f.default}'` : f.default}` : ''
-    return `      ${f.name} ${sqlType(f)}${pk}${req}${def}`
-  }).join('\n')
-
-  return `// migrations/${Date.now()}_create_${p.module}.ts
-// Migración generada por arckode make:module
-// SQL ANSI — compatible con SQLite, MySQL y Postgres sin modificaciones.
-
-export async function up(db: any): Promise<void> {
-  await db.run(\`
-    CREATE TABLE IF NOT EXISTS ${p.module} (
-${cols},
-      createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-      updatedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP${p.softDelete ? ',\n      deletedAt TIMESTAMP NULL' : ''}
-    )
-  \`)
-}
-
-export async function down(db: any): Promise<void> {
-  await db.run(\`DROP TABLE IF EXISTS ${p.module}\`)
-}
-`
-}
-
-export function seedStub(p: ModuleStubParams): string {
-  const sampleData = p.fields
-    .filter(f => f.name !== 'id' && f.name !== 'createdAt' && f.name !== 'updatedAt')
-    .map(f => {
-      if (f.name === 'nombre' || f.name === 'name') return `    ${f.name}: '${p.name} de ejemplo'`
-      if (f.name === 'email') return `    ${f.name}: 'ejemplo@correo.com'`
-      if (f.name === 'activo' || f.name === 'active') return `    ${f.name}: true`
-      if (f.type === 'number') return `    ${f.name}: 100`
-      if (f.type === 'boolean') return `    ${f.name}: false`
-      return `    ${f.name}: 'valor'`
-    })
-    .join('\n')
-
-  return `// seeds/${p.module}.ts — Datos de prueba
-
-export async function seed${p.name}(orm: any): Promise<void> {
-  const items = [
-    {
-${sampleData}
-    },
-    {
-${sampleData.replace(`'${p.name} de ejemplo'`, `'${p.name} de ejemplo 2'`).replace(`'ejemplo@correo.com'`, `'ejemplo2@correo.com'`)}
-    },
-  ]
-
-  await Promise.all(items.map(item => orm.create('${p.name}', item)))
-
-  console.log('  ✓ ${p.name} seeded: ' + items.length + ' items')
-}
-`
-}
-
-// ─── repository.ts — OPCIONAL ────────────────────────────
-// NO se genera por default. Crealo a mano cuando:
-//   1. El service repite los mismos filtros en varios métodos
-//      (ej: findOne({ user_id, currency }) en 4 lugares)
-//   2. Necesitás queries con JOIN, IN, LIKE — el ORM builtin no las soporta
-//   3. Querés expresar la query en lenguaje del DOMINIO
-//      (ej: findActiveByUser vs findMany({ user_id, status: 'active' }))
-//
-// Si solo hacés CRUD pelado → NO necesitás repository.ts.
-// Pasás el OrmRepository<T> directo al service.
-export function repositoryStub(p: ModuleStubParams): string {
-  return `// ${p.module}/repository.ts — Repository de dominio (OPCIONAL)
-// Encapsula queries con NOMBRES DEL DOMINIO en lugar de nombres de columna.
-//
-// Antes:  service.findOne({ user_id: userId, currency })   ← service conoce la DB
-// Ahora:  service.findByUserAndCurrency(userId, currency)  ← service habla el dominio
-//
-// Implementa RepositoryAdapter<${p.name}DTO> si necesitás queries complejas (JOIN, IN).
-
-import type { RepositoryAdapter } from 'arckode-framework'
-import type { ${p.name}DTO } from './types'
-
-export class ${p.name}Repository {
-  constructor(private readonly base: RepositoryAdapter<${p.name}DTO>) {}
-
-  // Métodos genéricos delegados al adapter base
-  findById(id: string)   { return this.base.findById(id) }
-  findMany(filters?: Record<string, unknown>) { return this.base.findMany(filters) }
-  create(data: Omit<${p.name}DTO, 'id'>) { return this.base.create(data) }
-  update(id: string, data: Partial<Omit<${p.name}DTO, 'id'>>) { return this.base.update(id, data) }
-  delete(id: string)     { return this.base.delete(id) }
-
-  // ─── Métodos específicos del dominio ───
-  // Agregá acá las queries que se repiten en el service
-  //
-  // async findActiveByUser(userId: string): Promise<${p.name}DTO[]> {
-  //   return this.base.findMany({ user_id: userId, active: true })
-  // }
-}
-`
-}
-
-function mapTS(type: string): string {
-  const map: Record<string, string> = { string: 'string', number: 'number', boolean: 'boolean', date: 'string' }
-  return map[type] ?? 'unknown'
-}
+// cli/stubs/module-stub.ts — Re-export shim (módulos reales en cli/stubs/module/)
+export * from './module/index'

package/kernel/auth.ts

@@ -0,0 +1,114 @@
+import { AuthError, ForbiddenError } from './errors'
+import type { Logger } from './logger'
+import type { MiddlewareHandler } from './http/types'
+
+export interface JwtAdapter {
+  sign(payload: Record<string, unknown>, secret: string, expiresIn: string): string
+  verify(token: string, secret: string): Record<string, unknown>
+}
+
+export class Auth {
+  private readonly refreshSecret: string
+
+  constructor(
+    private jwt: JwtAdapter,
+    private secret: string,
+    private logger: Logger,
+    private expiresIn: string = '24h',
+    private refreshExpiresIn: string = '30d',
+  ) {
+    this.refreshSecret = secret + '__refresh__'
+  }
+
+  createToken(payload: { id: string; role: string }, expiresIn?: string): string {
+    const ttl = expiresIn ?? this.expiresIn
+    const token = this.jwt.sign({ id: payload.id, role: payload.role, type: 'access' }, this.secret, ttl)
+    this.logger.debug('Token creado', { userId: payload.id, expiresIn: ttl })
+    return token
+  }
+
+  createRefreshToken(payload: { id: string; role: string }): string {
+    const token = this.jwt.sign(
+      { id: payload.id, role: payload.role, type: 'refresh', jti: crypto.randomUUID() },
+      this.refreshSecret,
+      this.refreshExpiresIn,
+    )
+    this.logger.debug('Refresh token creado', { userId: payload.id })
+    return token
+  }
+
+  refresh(refreshToken: string): { accessToken: string; refreshToken: string } {
+    try {
+      const payload = this.jwt.verify(refreshToken, this.refreshSecret)
+      if (payload.type !== 'refresh') throw new AuthError('Invalid token type')
+      const user = { id: payload.id as string, role: payload.role as string }
+      return {
+        accessToken: this.createToken(user),
+        refreshToken: this.createRefreshToken(user),
+      }
+    } catch (e) {
+      if (e instanceof AuthError) throw e
+      throw new AuthError('Invalid or expired refresh token')
+    }
+  }
+
+  verifyToken(token: string): { id: string; role: string } {
+    try {
+      const payload = this.jwt.verify(token, this.secret)
+      if (payload.type !== 'access') throw new AuthError('Invalid token type')
+      return { id: payload.id as string, role: payload.role as string }
+    } catch (e) {
+      if (e instanceof AuthError) throw e
+      throw new AuthError('Invalid or expired token')
+    }
+  }
+
+  authenticate(...allowedRoles: string[]): MiddlewareHandler {
+    return async (req, next) => {
+      const header = req.headers['authorization']
+      if (!header?.startsWith('Bearer ')) {
+        throw new AuthError('Authentication token required')
+      }
+
+      const user = this.verifyToken(header.slice(7))
+
+      if (allowedRoles.length > 0 && !allowedRoles.includes(user.role)) {
+        throw new ForbiddenError(`Required role: ${allowedRoles.join(' or ')}`)
+      }
+
+      req.user = user
+      return next()
+    }
+  }
+
+  assertOwnership(
+    resourceOwnerId: string,
+    requestingUserId: string,
+    requestingUserRole?: string,
+    adminRole = 'admin',
+  ): void {
+    if (requestingUserId === resourceOwnerId) return
+    if (requestingUserRole === adminRole) return
+    throw new ForbiddenError('Forbidden: resource belongs to another user')
+  }
+
+  async hashPassword(password: string): Promise<string> {
+    const { scrypt, randomBytes } = await import('node:crypto')
+    const salt = randomBytes(16).toString('hex')
+    const hash = await new Promise<Buffer>((resolve, reject) =>
+      scrypt(password, salt, 64, (err, key) => (err ? reject(err) : resolve(key))),
+    )
+    return `${salt}:${hash.toString('hex')}`
+  }
+
+  async comparePassword(password: string, stored: string): Promise<boolean> {
+    const { scrypt, timingSafeEqual } = await import('node:crypto')
+    const [salt, hash] = stored.split(':')
+    if (!salt || !hash) return false
+    const storedBuf = Buffer.from(hash, 'hex')
+    const attempt = await new Promise<Buffer>((resolve, reject) =>
+      scrypt(password, salt, 64, (err, key) => (err ? reject(err) : resolve(key))),
+    )
+    return timingSafeEqual(storedBuf, attempt)
+  }
+}