@volcanicminds/backend 2.3.2 → 3.0.0

package/lib/api/tenants/routes.ts

@@ -0,0 +1,145 @@
+const { multi_tenant } = global.config?.options || {}
+const isEnabled = multi_tenant?.enabled || false
+
+export default {
+  config: {
+    title: 'Tenant Management',
+    description: 'Administration of tenants (global scope)',
+    controller: 'controller',
+    enable: isEnabled,
+    tenantContext: false, // Critical: Operate on global scope (public schema), bypass tenant context
+    tags: ['tenants']
+  },
+  routes: [
+    {
+      method: 'GET',
+      path: '/',
+      roles: [roles.admin],
+      handler: 'tenants.list',
+      middlewares: ['global.isAuthenticated'],
+      config: {
+        title: 'List Tenants',
+        description: 'Retrieve all tenants.',
+        response: {
+          200: { $ref: 'tenantListResponseSchema#' }
+        }
+      }
+    },
+    {
+      method: 'POST',
+      path: '/',
+      roles: [roles.admin],
+      handler: 'tenants.create',
+      middlewares: ['global.isAuthenticated'],
+      config: {
+        title: 'Create Tenant',
+        description: 'Create a new tenant with its own schema.',
+        body: { $ref: 'tenantBodySchema#' },
+        response: {
+          201: { $ref: 'tenantResponseSchema#' }
+        }
+      }
+    },
+    {
+      method: 'GET',
+      path: '/:id',
+      roles: [roles.admin],
+      handler: 'tenants.findOne',
+      middlewares: ['global.isAuthenticated'],
+      config: {
+        title: 'Get Tenant',
+        description: 'Retrieve a single tenant by ID.',
+        params: { $ref: 'globalParamsSchema#' },
+        response: {
+          200: { $ref: 'tenantResponseSchema#' }
+        }
+      }
+    },
+    {
+      method: 'PUT',
+      path: '/:id',
+      roles: [roles.admin],
+      handler: 'tenants.update',
+      middlewares: ['global.isAuthenticated'],
+      config: {
+        title: 'Update Tenant',
+        description: 'Update an existing tenant.',
+        params: { $ref: 'globalParamsSchema#' },
+        body: { $ref: 'tenantUpdateBodySchema#' },
+        response: {
+          200: { $ref: 'tenantResponseSchema#' }
+        }
+      }
+    },
+    {
+      method: 'DELETE',
+      path: '/:id',
+      roles: [roles.admin],
+      handler: 'tenants.remove',
+      middlewares: ['global.isAuthenticated'],
+      config: {
+        title: 'Archive Tenant',
+        description: 'Soft delete (archive) a tenant.',
+        params: { $ref: 'globalParamsSchema#' },
+        response: {
+          200: { $ref: 'defaultResponse#' }
+        }
+      }
+    },
+    {
+      method: 'POST',
+      path: '/:id/restore',
+      roles: [roles.admin],
+      handler: 'tenants.restore',
+      middlewares: ['global.isAuthenticated'],
+      config: {
+        title: 'Restore Tenant',
+        description: 'Restore a soft-deleted tenant.',
+        params: { $ref: 'globalParamsSchema#' },
+        response: {
+          200: { $ref: 'defaultResponse#' }
+        }
+      }
+    },
+    {
+      method: 'POST',
+      path: '/impersonate',
+      roles: [roles.admin],
+      handler: 'tenants.impersonate',
+      middlewares: ['global.isAuthenticated'],
+      config: {
+        title: 'Impersonate User',
+        description:
+          'Generate an impersonation token for a specific user in a target tenant (System Admin or Tenant Admin).',
+        tenantContext: true, // Enable tenant context to allow Tenant Admins to be authenticated
+        // Optional: Define body schema for documentation
+        body: {
+          type: 'object',
+          properties: {
+            targetTenantSlug: { type: 'string' },
+            targetTenantId: { type: 'string' },
+            targetRole: { type: 'string' },
+            targetUserEmail: { type: 'string' },
+            targetUserId: { type: 'string' }
+          }
+        },
+        response: {
+          200: {
+            type: 'object',
+            properties: {
+              token: { type: 'string' },
+              expiresAt: { type: 'string', format: 'date-time' },
+              impersonatedUser: {
+                type: 'object',
+                properties: {
+                  email: { type: 'string' },
+                  id: { type: 'string' }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/lib/config/plugins.ts

@@ -44,7 +44,7 @@ export default [
   },
   {
     name: 'helmet',
-    enable: false,
+    enable: true,
     options: {}
   },
   {

package/lib/database/typeorm/entities/change.ts

@@ -0,0 +1,11 @@
+import { BaseEntity } from 'typeorm'
+
+export abstract class Change extends BaseEntity {
+  abstract createdAt: Date
+  abstract updatedAt: Date
+  abstract userId: string
+  abstract status: string
+  abstract entityName: string
+  abstract entityId: string
+  abstract contents: object
+}

package/lib/database/typeorm/entities/tenant.ts

@@ -0,0 +1,20 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { BaseEntity } from 'typeorm'
+
+export abstract class Tenant extends BaseEntity {
+  abstract id: any
+  abstract name: string
+  abstract slug: string
+
+  // Campi specifici per strategia
+  abstract dbSchema?: string // Per Postgres (schema splitting)
+  abstract dbName?: string // Per Mongo (database splitting, opzionale)
+
+  abstract status: 'active' | 'suspended' | 'archived'
+
+  abstract createdAt: Date
+  abstract updatedAt: Date
+
+  // Configurazione opzionale
+  abstract getConfig(): Record<string, any>
+}

package/lib/database/typeorm/entities/token.ts

@@ -0,0 +1,18 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { BaseEntity } from 'typeorm'
+
+export abstract class Token extends BaseEntity {
+  // abstract id: any
+  abstract externalId: string
+  abstract name: string
+  abstract description: string
+  abstract blocked: boolean
+  abstract blockedReason: string
+  abstract blockedAt: Date
+  abstract roles: string[]
+  abstract createdAt: Date
+  abstract updatedAt: Date
+  abstract deletedAt: Date
+  abstract setId(id: any)
+  abstract getId(): any
+}

package/lib/database/typeorm/entities/user.ts

@@ -0,0 +1,33 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { BaseEntity } from 'typeorm'
+
+export abstract class User extends BaseEntity {
+  // abstract id: any
+  abstract externalId: string
+  abstract username: string
+  abstract email: string
+  abstract password: string
+  abstract confirmed: boolean
+  abstract confirmedAt: Date
+  abstract passwordChangedAt: Date
+  abstract blocked: boolean
+  abstract blockedReason: string
+  abstract blockedAt: Date
+  abstract resetPasswordToken: string
+  abstract resetPasswordTokenAt: Date
+  abstract confirmationToken: string
+  abstract roles: string[]
+  abstract version: number
+  abstract createdAt: Date
+  abstract updatedAt: Date
+  abstract deletedAt: Date
+
+  // MFA Fields
+  abstract mfaEnabled: boolean
+  abstract mfaSecret: string
+  abstract mfaType: string
+  abstract mfaRecoveryCodes: string[]
+
+  abstract setId(id: any): void
+  abstract getId(): any
+}

package/lib/database/typeorm/loader/dataBaseManager.ts

@@ -0,0 +1,89 @@
+import { QueryRunner, EntityManager } from 'typeorm'
+import * as log from '../util/logger.js'
+
+export function isImplemented() {
+  return true
+}
+
+export async function synchronizeSchemas(runner?: QueryRunner) {
+  try {
+    if (runner) {
+      await runner.connection.synchronize()
+    } else {
+      await global.connection.synchronize()
+    }
+    return true
+  } catch (error) {
+    log.error(`Volcanic-TypeORM: ${error}`)
+    throw error
+  }
+}
+
+export async function retrieveBy(entityName: string, entityId: string, context?: QueryRunner | EntityManager) {
+  try {
+    const { multi_tenant } = (global as any).config?.options || {}
+
+    if (multi_tenant?.enabled && !context) {
+      const errorMsg =
+        '[DataBaseManager] ⛔️ CRITICAL: Missing DB Context (Runner/Manager) in Multi-Tenant Environment! Implicit fallback to public schema forbidden.'
+      log.error(errorMsg)
+      throw new Error(errorMsg)
+    }
+
+    if (context) {
+      // Handle QueryRunner logic
+      if ((context as QueryRunner).manager) {
+        return await (context as QueryRunner).manager.findOneBy(entityName, { id: entityId })
+      }
+      // Handle EntityManager logic
+      return await (context as EntityManager).findOneBy(entityName, { id: entityId })
+    }
+    return await global.connection.getRepository(global.entity[entityName]).findOneBy({ id: entityId })
+  } catch (error) {
+    if (!(entityName in global.entity)) {
+      log.error(`Volcanic-TypeORM: ${entityName} not found in global.entity`)
+    }
+    throw error
+  }
+}
+
+export async function addChange(
+  entityName: string,
+  entityId: string,
+  status: string,
+  userId: string,
+  contents: unknown,
+  changeEntity = 'Change',
+  context?: QueryRunner | EntityManager
+) {
+  try {
+    const { multi_tenant } = (global as any).config?.options || {}
+
+    if (multi_tenant?.enabled && !context) {
+      const errorMsg =
+        '[DataBaseManager] ⛔️ CRITICAL: Missing DB Context (Runner/Manager) in Multi-Tenant Environment! Implicit fallback to public schema forbidden.'
+      log.error(errorMsg)
+      throw new Error(errorMsg)
+    }
+
+    if (context) {
+      let repo
+      if ((context as QueryRunner).manager) {
+        repo = (context as QueryRunner).manager.getRepository(changeEntity)
+      } else {
+        repo = (context as EntityManager).getRepository(changeEntity)
+      }
+
+      const newChange = repo.create({ entityName, entityId, status, userId, contents })
+      return repo.save(newChange)
+    }
+    const repo = global.connection.getRepository(global.entity[changeEntity])
+    const newChange = repo.create({ entityName, entityId, status, userId, contents })
+    return repo.save(newChange)
+  } catch (error) {
+    if (!(changeEntity in global.entity)) {
+      log.error(`Volcanic-TypeORM: ${changeEntity} not found in global.entity`)
+    }
+    throw error
+  }
+}

package/lib/database/typeorm/loader/entities.ts

@@ -0,0 +1,47 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import * as path from 'path'
+import { globSync } from 'glob'
+import pluralize from 'pluralize'
+import { fileURLToPath, pathToFileURL } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+export async function load() {
+  const classes: any = {}
+  const repositories: any = {}
+  const entities: any[] = []
+
+  const patterns = [
+    path.join(__dirname, '..', 'entities', '*.e.{ts,js}'),
+    path.join(process.cwd(), 'src', 'entities', '*.e.{ts,js}'),
+    path.join(process.cwd(), 'dist', 'src', 'entities', '*.e.{ts,js}')
+  ]
+
+  for (const pattern of patterns) {
+    const files = globSync(pattern, { nodir: true, windowsPathsNoEscape: true })
+
+    const modules = await Promise.all(
+      files.map((f) => {
+        const fileUrl = pathToFileURL(f).href
+        return import(fileUrl)
+      })
+    )
+
+    for (const entityModule of modules) {
+      const entityClass = entityModule.default || entityModule
+      const entityNames = Object.keys(entityClass)
+
+      entityNames.forEach((name) => {
+        const entity = entityClass[name]
+        if (typeof entity === 'function') {
+          classes[name] = entity
+          repositories[pluralize(name.toLowerCase())] = entity
+          entities.push(entity)
+        }
+      })
+    }
+  }
+
+  return { classes, repositories, entities }
+}

package/lib/database/typeorm/loader/tenantManager.ts

@@ -0,0 +1,260 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { DataSource, EntityManager } from 'typeorm'
+import { Tenant } from '../entities/tenant.js'
+
+export class TenantManager {
+  constructor(private dataSource: DataSource) {}
+
+  isImplemented() {
+    return true
+  }
+
+  async resolveTenant(req: any): Promise<Tenant | null> {
+    const { multi_tenant } = (global as any).config?.options || {}
+    const headerKey = multi_tenant?.header_key || 'x-tenant-id'
+
+    // 1. Single Tenant Mode (Default)
+    if (!multi_tenant?.enabled) {
+      return null
+    }
+
+    // 2. Multi-Tenant Mode: Extract Identifiers
+    // Parse JWT from headers if not already attached (Fastify might attach it to req.user)
+    const jwtTid = req.user?.tid
+    const headerTid = req.headers[headerKey]
+
+    // 3. Validation Logic (Strict)
+    // Rule A: Header is MANDATORY in Multi-Tenant
+    if (!headerTid) {
+      // Log debug and return null to let the caller handle 404/403
+      if ((global as any).log?.d) (global as any).log.debug('[TenantManager] No tenant header found')
+      return null
+    }
+
+    // Rule B: JWT is OPTIONAL (For Public Routes/Login).
+    // Rule C: If the JWT carries a tenant binding, the header MUST match it.
+    //   A token bound to tenant X requesting tenant Y via header is a tenant-isolation
+    //   bypass (IDOR) attempt — REJECT it, do not merely warn. If a privileged
+    //   System-Admin impersonation flow is ever required, gate it HERE behind an
+    //   explicit, verified role check on `req.user` (e.g. a dedicated `system_admin`
+    //   role) — never relax this default.
+    if (jwtTid && jwtTid !== headerTid) {
+      if ((global as any).log?.w)
+        (global as any).log.warn(`[TenantManager] Tenant spoofing blocked: Token(${jwtTid}) vs Header(${headerTid})`)
+      return null
+    }
+
+    // Prefer the JWT-bound tenant when present; fall back to the header (public/login routes).
+    const tenantId = jwtTid || headerTid
+
+    // 5. Database Lookup
+    const tenantRepo = this.dataSource.getRepository('Tenant')
+
+    // Support lookup by ID or SLUG
+    const tenant = (await tenantRepo.findOne({
+      where: [{ slug: tenantId }]
+    })) as unknown as Tenant
+
+    if (!tenant) {
+      if ((global as any).log?.d) (global as any).log.debug(`[TenantManager] Tenant ${tenantId} not found in DB`)
+      return null
+    }
+
+    if (tenant.status !== 'active') {
+      if ((global as any).log?.d) (global as any).log.debug(`[TenantManager] Tenant ${tenantId} is not active`)
+      return null
+    }
+
+    return tenant
+  }
+
+  /**
+   * Switches the database context to the specific tenant schema.
+   * CRITICAL SECURITY: This method MUST receive an EntityManager (db) when using Postgres Multi-Tenancy.
+   * Modifying the global search_path is strictly forbidden to prevent data leaks.
+   */
+  async switchContext(tenant: Tenant, db?: EntityManager) {
+    const driver = this.dataSource.driver.options.type
+
+    if (driver === 'postgres') {
+      const schema = tenant.dbSchema || 'public'
+      const safeSchema = schema.replace(/[^a-z0-9_]/gi, '')
+
+      if (db) {
+        if ((global as any).log?.t)
+          (global as any).log.trace(`[TenantManager] Context-Aware Switch Schema to: ${safeSchema}`)
+        // Execute SET search_path only on the specific transactional QueryRunner
+        await db.query(`SET search_path TO "${safeSchema}", public`)
+      } else {
+        // STRICT SECURITY CHECK
+        // If no db (EntityManager) is provided, we used to fallback to global dataSource.
+        // This is now FORBIDDEN as it poisons the connection pool.
+        const errorMsg =
+          '[TenantManager] ⛔️ CRITICAL: Attempted UNSAFE global context switch without QueryRunner. This operation has been blocked to prevent data leaks.'
+        if ((global as any).log?.f) (global as any).log.fatal(errorMsg)
+        throw new Error(errorMsg)
+      }
+    } else if (driver === 'mongodb') {
+      // Mongo implementation stub
+      if ((global as any).log?.w)
+        (global as any).log.warn('[TenantManager] Mongo Multi-Tenancy context switch is not enforcing isolation yet.')
+    }
+  }
+
+  async createTenant(data: any): Promise<Tenant> {
+    const driver = this.dataSource.driver.options.type
+    const repo = this.dataSource.getRepository('Tenant')
+
+    // Data validation should be handled by Schema validation in API
+    // Enforce lowercase slug
+    if (data.slug) data.slug = data.slug.toLowerCase()
+
+    // Check existence
+    const existing = await repo.findOne({
+      where: [{ slug: data.slug }, { dbSchema: data.dbSchema }]
+    })
+    if (existing) {
+      throw new Error('Tenant with this slug or dbSchema already exists')
+    }
+
+    const tenant = repo.create({
+      ...data,
+      status: 'active'
+    })
+    const savedTenant = (await repo.save(tenant)) as any as Tenant
+
+    if (driver === 'postgres') {
+      const schema = data.dbSchema
+      if (!schema) throw new Error('dbSchema is required for Postgres Multi-Tenancy')
+
+      const safeSchema = schema.replace(/[^a-z0-9_]/gi, '')
+      const qr = this.dataSource.createQueryRunner()
+      await qr.connect()
+      try {
+        await qr.query(`CREATE SCHEMA IF NOT EXISTS "${safeSchema}"`)
+
+        // --- Schema Synchronization ---
+        // We create an ephemeral DataSource to force TypeORM to synchronize only the specific schema.
+        // This is necessary because the global DataSource is bound to the public/default schema.
+        if ((global as any).log?.i)
+          (global as any).log.info(`[TenantManager] Synchronizing tables for schema: ${safeSchema}`)
+
+        const tenantDs = new DataSource({
+          ...(this.dataSource.options as any),
+          schema: safeSchema,
+          synchronize: true,
+          name: `sync_${safeSchema}_${Date.now()}`
+        })
+        await tenantDs.initialize()
+        await tenantDs.destroy()
+
+        if ((global as any).log?.i)
+          (global as any).log.info(`[TenantManager] Schema ${safeSchema} synchronized successfully`)
+
+        await qr.startTransaction()
+
+        // Context Switch within the same transaction to seed the user
+        // Use SET LOCAL so it automatically reverts at the end of the transaction
+        await qr.query(`SET LOCAL search_path TO "${safeSchema}", public`)
+
+        if (data.adminEmail && data.adminPassword) {
+          if ((global as any).log?.i) (global as any).log.info(`[TenantManager] Seeding Admin User: ${data.adminEmail}`)
+          const { createUser } = await import('./userManager.js')
+
+          await createUser(
+            {
+              email: data.adminEmail,
+              password: data.adminPassword,
+              roles: ['admin'],
+              firstName: data.adminFirstName || 'Tenant',
+              lastName: data.adminLastName || 'Admin'
+            } as any,
+            qr
+          )
+        }
+
+        await qr.commitTransaction()
+        if ((global as any).log?.i) (global as any).log.info(`[TenantManager] Created Schema & Admin: ${safeSchema}`)
+      } catch (err) {
+        if (qr.isTransactionActive) {
+          await qr.rollbackTransaction()
+        }
+        throw err
+      } finally {
+        try {
+          // Reset to public for safety before releasing
+          await qr.query(`SET search_path TO public`)
+        } catch (cleanupErr) {
+          if ((global as any).log?.e)
+            (global as any).log.error(`[TenantManager] Failed to reset search_path: ${cleanupErr}`)
+        }
+        await qr.release()
+      }
+    } else {
+      // Mongo or others
+      if ((global as any).log?.i) (global as any).log.info(`[TenantManager] Created Tenant Record for ${driver}`)
+    }
+
+    return savedTenant
+  }
+
+  async deleteTenant(id: string): Promise<void> {
+    const repo = this.dataSource.getRepository('Tenant')
+    await repo.softDelete(id)
+  }
+
+  async restoreTenant(id: string) {
+    const repo = this.dataSource.getRepository('Tenant')
+    await repo.restore(id)
+    return repo.findOneBy({ id })
+  }
+
+  async getTenant(id: string) {
+    const repo = this.dataSource.getRepository('Tenant')
+    return (await repo.findOneBy({ id })) as unknown as Tenant
+  }
+
+  async updateTenant(id: string, data: Partial<Tenant>) {
+    const repo = this.dataSource.getRepository('Tenant')
+    // Exclude dbSchema from updates as it requires migration of tables
+     
+    const { dbSchema: _ignore, ...updateData } = data
+    await repo.update(id, updateData as any)
+    return repo.findOneBy({ id })
+  }
+
+  async listTenants() {
+    const repo = this.dataSource.getRepository('Tenant')
+    return repo.find({ order: { createdAt: 'DESC' } as any })
+  }
+
+  /**
+   * Safe utility to execute a function within a specific Tenant Context (e.g. for Background Jobs or System Admin tasks).
+   * This handles the creation, connection, context switch, and release of a QueryRunner automatically.
+   */
+  async runInTenantContext<T>(tenantId: string, callback: (em: EntityManager) => Promise<T>): Promise<T> {
+    const tenant = await this.getTenant(tenantId)
+    if (!tenant) throw new Error(`Tenant ${tenantId} not found`)
+    if (tenant.status !== 'active') throw new Error(`Tenant ${tenantId} is not active`)
+
+    const qr = this.dataSource.createQueryRunner()
+    await qr.connect()
+
+    try {
+      // Enforce context switch on this specific runner
+      await this.switchContext(tenant, qr.manager)
+
+      // Execute callback with the isolated EntityManager
+      const result = await callback(qr.manager)
+      return result
+    } finally {
+      try {
+        await qr.query('SET search_path TO public')
+      } catch (e) {
+        if ((global as any).log?.w)
+          (global as any).log.warn(`[TenantManager] Failed to reset search_path context: ${e}`)
+      }
+      await qr.release()
+    }
+  }
+}