tenant.js

Go to the documentation of this file.

/**
 * @file Tenant Context and Multi-Tenancy Middleware
 * @module middleware/tenant
 * @description
 * Comprehensive multi-tenancy middleware providing tenant context extraction, isolation,
 * and Row-Level Security (RLS) enforcement. Extracts tenant from subdomain or JWT,
 * validates tenant status, and provides query filtering utilities.
 *
 * Key features:
 * - **Tenant extraction**: From subdomain (app.tenantname.ibghub.com) or JWT tenantId claim
 * - **Status validation**: Ensures tenant is active before allowing requests
 * - **MSP mode detection**: Identifies Root MSP tenants with cross-tenant access
 * - **RLS support**: PostgreSQL Row-Level Security integration via app.current_tenant
 * - **Query filtering**: SQL WHERE clause generators for tenant isolation
 *
 * Tenant hierarchy:
 * - Root MSP (tenant_id=1): Super-tenant with cross-tenant visibility (is_msp=true)
 * - Regular tenants: Isolated data visibility (is_msp=false)
 *
 * Middleware execution order (IMPORTANT):
 * 1. authenticateToken - Extract JWT and user info
 * 2. setTenantContext - Extract tenant context from subdomain/JWT
 * 3. requireTenant - Enforce tenant context exists (optional)
 * 4. requireRoot - Enforce MSP privileges (optional)
 * 5. applyRLS - Set PostgreSQL session context (optional)
 *
 * Public route handling:
 * - /users/login, /users/request-password-reset, etc. bypass tenant checks
 * - Unauthenticated requests attempt subdomain-only tenant resolution
 *
 * Development mode:
 * - Use X-Tenant-Subdomain header to override subdomain (localhost testing)
 * @requires db - PostgreSQL connection pool from services/db
 * @see {@link module:middleware/auth} for authentication middleware
 * @see {@link https://www.postgresql.org/docs/current/ddl-rowsecurity.html} PostgreSQL RLS docs
 * @example
 * // Standard tenant-isolated route
 * const { setTenantContext, getTenantFilter } = require('./middleware/tenant');
 * router.get('/customers', authenticateToken, setTenantContext, async (req, res) => {
 *   const filter = getTenantFilter(req);
 *   const customers = await pool.query(`SELECT * FROM customers ${filter.clause}`, filter.values);
 * });
 * @example
 * // Root MSP cross-tenant route
 * const { requireRoot } = require('./middleware/tenant');
 * router.get('/admin/all-tenants', authenticateToken, setTenantContext, requireRoot, handler);
 * @example
 * // Request with tenant context
 * req.tenant = {
 *   id: 5,             // Tenant ID
 *   isMsp: false,      // MSP privileges flag
 *   subdomain: 'acme'  // Resolved subdomain
 * };
 */
 
/**
 * Middleware to extract and set tenant context from subdomain or user
 * This middleware should run AFTER authentication middleware
 */
let pool = null;
/**
 * Lazy getter for database pool (avoids circular dependency).
 * @private
 * @function getPool
 * @returns {object} PostgreSQL connection pool
 */
function getPool() {
  if (!pool) pool = require('../services/db');
  return pool;
}
 
/**
 * Extracts and sets tenant context from subdomain or JWT.
 *
 * Resolves tenant from:
 * 1. JWT tenantId claim (authenticated requests)
 * 2. Subdomain in Host header (e.g., acme.ibghub.com → tenant with subdomain='acme')
 * 3. X-Tenant-Subdomain header (development override for localhost)
 *
 * Validates tenant status (must be 'active'). Public auth routes bypass tenant checks.
 * Attaches tenant context to req.tenant for downstream middleware/routes.
 * @function setTenantContext
 * @async
 * @param {object} req - Express request object
 * @param {object} [req.user] - User object from authenticateToken middleware
 * @param {number} [req.user.tenantId] - Tenant ID from JWT
 * @param {boolean} [req.user.is_msp] - MSP flag from JWT
 * @param {object} req.headers - HTTP headers
 * @param {string} req.headers.host - Host header with optional subdomain
 * @param {string} [req.headers['x-tenant-subdomain']] - Dev override for tenant subdomain
 * @param {string} req.originalUrl - Request URL path
 * @param {object} res - Express response object
 * @param {Function} next - Express next middleware function
 * @returns {void} Attaches req.tenant object and calls next()
 * @throws {403} Tenant is not active - Tenant exists but status != 'active'
 * @example
 * // Authenticated request with JWT tenantId
 * // JWT: { tenantId: 5, is_msp: false }
 * // => req.tenant = { id: 5, isMsp: false, subdomain: 'acme' }
 * @example
 * // Unauthenticated request with subdomain
 * // Host: acme.ibghub.com
 * // => req.tenant = { id: 5, isMsp: false, subdomain: 'acme' }
 * @example
 * // Public auth route (bypasses tenant check)
 * // URL: /users/login
 * // => req.tenant = { id: null, isMsp: false, subdomain: 'acme' }
 */
async function setTenantContext(req, res, next) {
  try {
    // Compute hostname without port and derive subdomain
    const host = req.get('host') || '';
    const hostname = host.split(':')[0];
    const subdomainFromHost = hostname.split('.')[0];
 
    // For localhost development, allow overriding subdomain via header
    const devSubdomain = req.get('x-tenant-subdomain');
    const targetSubdomain = devSubdomain || subdomainFromHost;
 
    // Public unauthenticated auth routes should NEVER block on tenant context
    const publicPaths = new Set([
      '/users/login',
      '/users/request-password-reset',
      '/users/reset-password',
      '/users/verify-email'
    ]);
    const pathNoQuery = (req.originalUrl || req.url || '').split('?')[0];
 
    // Default tenant context (none)
    let tenantId = null;
    let isMsp = false;
 
    // Short-circuit ONLY for public auth endpoints
    if (publicPaths.has(pathNoQuery)) {
      req.tenant = { id: null, isMsp: false, subdomain: targetSubdomain };
      return next();
    }
 
    console.log(`[Tenant] Host: ${host}, Resolved Hostname: ${hostname}, Subdomain: ${targetSubdomain}`);
 
    if (req.user && req.user.tenantId) {
      // Use tenantId and is_msp from JWT for tenant context
      tenantId = req.user.tenantId;
      isMsp = req.user.is_msp || false;
      
      // Verify tenant is active
      try {
        const tRes = await getPool().query(
          'SELECT status FROM tenants WHERE tenant_id = $1',
          [tenantId]
        );
        if (tRes.rows.length > 0) {
          if (tRes.rows[0].status !== 'active') {
            return res.status(403).json({ error: 'Tenant is not active', status: tRes.rows[0].status });
          }
        }
      } catch (e) {
        console.warn('[Tenant] Error looking up tenant from JWT:', e.message);
      }
      // Allow MSP/admin to impersonate tenant via header or query param
      let impersonateTenantId = req.get('x-impersonate-tenant-id') || req.query.tenant_id || req.query.tenantId;
      if ((req.user.role === 'msp' || req.user.role === 'admin') && impersonateTenantId) {
        tenantId = impersonateTenantId;
        try {
          const tRes = await getPool().query(
            'SELECT is_msp, subdomain, status FROM tenants WHERE tenant_id = $1',
            [tenantId]
          );
          if (tRes.rows.length > 0) {
            // When impersonating, isMsp should be false (act as tenant)
            isMsp = false;
            if (tRes.rows[0].status !== 'active') {
              return res.status(403).json({ error: 'Tenant is not active', status: tRes.rows[0].status });
            }
          }
        } catch (e) {
          console.warn('[Tenant] Error looking up impersonated tenant:', e.message);
        }
        // Always override context for impersonation
        req.tenant = {
          id: tenantId,
          isMsp: false,
          subdomain: targetSubdomain
        };
        console.log(`[Tenant] MSP/Admin impersonating tenant_id=${tenantId} (source: ${impersonateTenantId === req.get('x-impersonate-tenant-id') ? 'header' : 'query'})`);
        return next();
      }
      console.log(`[Tenant] Context from JWT: tenant_id=${tenantId}, isMsp=${isMsp}`);
    } else {
      // Unauthenticated: try resolving tenant by subdomain if not localhost
      try {
        if (targetSubdomain && targetSubdomain !== 'localhost') {
            const tenantQuery = await getPool().query(
            'SELECT tenant_id, is_msp, status FROM tenants WHERE subdomain = $1',
            [targetSubdomain]
          );
 
          if (tenantQuery.rows.length > 0) {
            const tenantData = tenantQuery.rows[0];
            tenantId = tenantData.tenant_id;
            isMsp = tenantData.is_msp;
 
            if (tenantData.status !== 'active') {
              return res.status(403).json({
                error: 'Tenant is not active',
                status: tenantData.status
              });
            }
 
            console.log(`[Tenant] Resolved tenant ${tenantId} from subdomain ${targetSubdomain}`);
          }
        }
      } catch (e) {
        console.warn('[Tenant] Skipping tenant lookup for unauthenticated request due to error:', e.message);
      }
    }
 
    // Attach tenant info to request
    req.tenant = {
      id: tenantId,
      isMsp: isMsp,
      subdomain: targetSubdomain
    };
 
    console.log(`[Tenant] Final context for request: tenant_id=${tenantId}, isMsp=${isMsp}`);
 
    next();
  } catch (err) {
    console.error('[Tenant] Error setting tenant context (unexpected):', err);
    req.tenant = { id: null, isMsp: false };
    next();
  }
}
 
/**
 * Enforces tenant context exists on request.
 *
 * Validates req.tenant.id is set by setTenantContext middleware. Returns 400 error
 * if tenant context missing. Use on routes requiring strict tenant isolation.
 * @function requireTenant
 * @param {object} req - Express request object
 * @param {object} [req.tenant] - Tenant context from setTenantContext
 * @param {number} [req.tenant.id] - Tenant ID
 * @param {object} res - Express response object
 * @param {Function} next - Express next middleware function
 * @returns {void} Calls next() if tenant exists, sends 400 otherwise
 * @throws {400} Tenant context required - Missing or null tenant ID
 * @example
 * // Route requiring tenant context
 * router.get('/customers', authenticateToken, setTenantContext, requireTenant, handler);
 */
 
/**
 * Middleware to enforce tenant context is set.
 * Use this on routes that require tenant isolation.
 * @function requireTenant
 * @param {object} req - Express request object
 * @param {object} res - Express response object
 * @param {Function} next - Express next middleware function
 * @returns {void} Calls next() or sends 400 error if no tenant context
 * @example
 * router.get('/customers', authenticateToken, setTenantContext, requireTenant, handler);
 */
function requireTenant(req, res, next) {
  if (!req.tenant || !req.tenant.id) {
    return res.status(400).json({ 
      error: 'Tenant context required. Please ensure subdomain is set.' 
    });
  }
  next();
}
 
/**
 * Enforces Root MSP privileges (cross-tenant access).
 *
 * Validates req.tenant.isMsp is true (set by setTenantContext from JWT). Returns 403
 * error if not MSP tenant. Use on routes requiring cross-tenant visibility (admin
 * operations, global reports, tenant management).
 * @function requireRoot
 * @param {object} req - Express request object
 * @param {object} [req.tenant] - Tenant context from setTenantContext
 * @param {boolean} [req.tenant.isMsp] - MSP privileges flag
 * @param {object} res - Express response object
 * @param {Function} next - Express next middleware function
 * @returns {void} Calls next() if MSP, sends 403 otherwise
 * @throws {403} Root tenant privileges required - User is not Root MSP
 * @example
 * // Root MSP-only route
 * const { setTenantContext, requireRoot } = require('./middleware/tenant');
 * router.get('/admin/all-customers', authenticateToken, setTenantContext, requireRoot, handler);
 */
 
/**
 * Middleware to require root tenant privileges.
 * Use this on routes that need cross-tenant access.
 * @function requireRoot
 * @param {object} req - Express request object
 * @param {object} res - Express response object
 * @param {Function} next - Express next middleware function
 * @returns {void} Calls next() or sends 403 error if not root MSP
 */
function requireRoot(req, res, next) {
  if (!req.tenant || !req.tenant.isMsp) {
    return res.status(403).json({ 
      error: 'Root tenant privileges required for this operation' 
    });
  }
  next();
}
 
/**
 * Helper function to get tenant WHERE clause for queries
 * Root tenant users get no filter (can see all tenants),
 * regular users get scoped to their tenant,
 * and routes can disable tenant filtering entirely.
 * @param {object} req - Express request with req.tenant attached
 * @param {string} [tableAlias] - Optional table alias (e.g., 't' for tickets)
 * @param {boolean} [enforce] - If false, disables tenant filter
 * @returns {object} - { clause: string, params: array, nextParamIndex: number }
 */
function getTenantFilter(req, tableAlias = '', enforce = true) {
  if (!enforce) {
    return { clause: '', params: [], nextParamIndex: 1 };
  }
 
  const prefix = tableAlias ? `${tableAlias}.` : '';
 
  // MSP/root users: use impersonated tenant if provided
  if (req.tenant && req.tenant.isMsp) {
    // Check for impersonated tenant in query/body (support both camelCase and snake_case)
    const impersonatedTenantId = req.query?.tenantId || req.query?.tenant_id || req.body?.tenantId || req.body?.tenant_id;
    if (impersonatedTenantId) {
      return {
        clause: `${prefix}tenant_id = $1`,
        params: [impersonatedTenantId],
        nextParamIndex: 2
      };
    }
    // If no impersonation, show all tenants (no filter)
    return { clause: '', params: [], nextParamIndex: 1 };
  }
 
  // Regular users only see their own tenant's data
  if (req.tenant && req.tenant.id) {
    return {
      clause: `${prefix}tenant_id = $1`,
      params: [req.tenant.id],
      nextParamIndex: 2
    };
  }
 
  // No tenant context — return restrictive fallback
  return {
    clause: `${prefix}tenant_id IS NULL`,
    params: [],
    nextParamIndex: 1
  };
}
 
/**
 * Helper function to execute a query with tenant context set via RLS.
 * This wraps the query in a transaction and sets session variables.
 * @function withTenantContext
 * @param {object} client - pg client or pool
 * @param {string} tenantId - UUID of the tenant
 * @param {boolean} isMsp - Whether this is an MSP user with cross-tenant access
 * @param {Function} callback - Async function that performs queries
 * @returns {Promise<*>} Result from the callback function
 */
async function withTenantContext(client, tenantId, isMsp, callback) {
  const shouldRelease = !client.query; // If passed a pool, we need to get a client
  const dbClient = shouldRelease ? await pool.connect() : client;
 
  try {
    await dbClient.query('BEGIN');
    
    // Set RLS session variables
    await dbClient.query('SELECT set_config($1, $2, true)', ['app.tenant_id', tenantId]);
    await dbClient.query('SELECT set_config($1, $2, true)', [
      'app.is_msp', 
      isMsp ? 'on' : 'off'
    ]);
 
    console.log(`[RLS] Set tenant context: ${tenantId}, MSP: ${isMsp}`);
 
    // Execute the callback with the client
    const result = await callback(dbClient);
 
    await dbClient.query('COMMIT');
    return result;
  } catch (err) {
    await dbClient.query('ROLLBACK');
    console.error('[RLS] Transaction error:', err);
    throw err;
  } finally {
    if (shouldRelease) {
      dbClient.release();
    }
  }
}
 
/**
 * Express middleware wrapper for withTenantContext.
 * Sets up RLS context for the request and attaches db client.
 * Use AFTER setTenantContext and authentication.
 * @function applyRLS
 * @param {object} req - Express request object
 * @param {object} res - Express response object
 * @param {Function} next - Express next middleware function
 * @returns {Promise<void>} Calls next() or sends error response
 */
async function applyRLS(req, res, next) {
  if (!req.tenant || !req.tenant.id) {
    return res.status(400).json({ 
      error: 'Tenant context required before applying RLS' 
    });
  }
 
  try {
      const client = await getPool().connect();
    
    // Set RLS context
    await client.query('SELECT set_config($1, $2, true)', ['app.tenant_id', req.tenant.id]);
    await client.query('SELECT set_config($1, $2, true)', [
      'app.is_msp', 
      req.tenant.isMsp ? 'on' : 'off'
    ]);
 
    // Attach client to request so routes can use it
    req.dbClient = client;
    
    // Clean up client after response
    res.on('finish', () => {
      if (req.dbClient) {
        req.dbClient.release();
      }
    });
 
    next();
  } catch (err) {
    console.error('[RLS] Error applying RLS:', err);
    res.status(500).json({ error: 'Failed to apply tenant security' });
  }
}
 
module.exports = {
  setTenantContext,
  getTenantFilter,
  requireRoot,
  requireTenant,
  applyRLS,
  withTenantContext
};