@heavybit/pendoadmin-shared-lib 1.0.0 → 1.1.0

package/src/tenant/tenant-access-control.ts

@@ -0,0 +1,370 @@
+// pendoadmin-shared-lib/src/tenant/tenant-access-control.ts
+//
+// Feature-gating middleware and helpers.
+// Restricts tenant access to services/features based on their subscription plan
+// and per-service activation status (ICompanyServiceConfig).
+
+import type { Request, Response, NextFunction } from "express";
+import type { Knex } from "knex";
+
+// ─── Feature & Plan Definitions ─────────────────────────
+
+/**
+ * Every discrete feature / service area that can be gated.
+ * Extend this union as the platform grows.
+ */
+export type Feature =
+  | "sms"
+  | "email"
+  | "whatsapp"
+  | "ussd"
+  | "mpesa"
+  | "analytics"
+  | "ai"
+  | "notifications"
+  | "api-gateway"
+  | (string & {}); // allow custom feature strings while providing autocomplete
+
+/**
+ * Named subscription plans. Each plan grants access to a set of features.
+ * Plans are ordered by tier — higher tiers include all features of lower tiers.
+ */
+export interface SubscriptionPlan {
+  name: string;
+  /** Numeric tier level — higher = more features */
+  tier: number;
+  /** Features included in this plan */
+  features: Feature[];
+}
+
+/** Default plans — consumers can override with their own */
+export const DEFAULT_PLANS: SubscriptionPlan[] = [
+  {
+    name: "starter",
+    tier: 1,
+    features: ["sms", "notifications"],
+  },
+  {
+    name: "professional",
+    tier: 2,
+    features: ["sms", "email", "notifications", "analytics"],
+  },
+  {
+    name: "business",
+    tier: 3,
+    features: ["sms", "email", "whatsapp", "mpesa", "notifications", "analytics"],
+  },
+  {
+    name: "enterprise",
+    tier: 4,
+    features: ["sms", "email", "whatsapp", "ussd", "mpesa", "analytics", "ai", "notifications", "api-gateway"],
+  },
+];
+
+// ─── Access Control Config ──────────────────────────────
+
+export interface TenantAccessControlConfig {
+  /**
+   * Function that looks up a company's active features.
+   * Should return the list of feature names the company is entitled to.
+   * This is called once per request and cached on the request object.
+   */
+  getCompanyFeatures: (companyId: string) => Promise<Feature[]>;
+
+  /**
+   * Optional: check whether the tenant (company) itself is active.
+   * If it returns false the request is rejected with 403.
+   * Default: always active (not checked).
+   */
+  isCompanyActive?: (companyId: string) => Promise<boolean>;
+
+  /** Cache TTL in seconds for feature lookups. 0 = no cache. Default: 60. */
+  cacheTtlSeconds?: number;
+
+  /** Custom logger (default: console) */
+  logger?: Pick<Console, "info" | "warn" | "error">;
+}
+
+// ─── In-Memory Feature Cache ────────────────────────────
+
+interface CacheEntry {
+  features: Feature[];
+  expiresAt: number;
+}
+
+const featureCache = new Map<string, CacheEntry>();
+
+function getCachedFeatures(companyId: string, ttl: number): Feature[] | null {
+  if (ttl <= 0) return null;
+  const entry = featureCache.get(companyId);
+  if (entry && Date.now() < entry.expiresAt) return entry.features;
+  featureCache.delete(companyId);
+  return null;
+}
+
+function setCachedFeatures(companyId: string, features: Feature[], ttl: number): void {
+  if (ttl <= 0) return;
+  featureCache.set(companyId, { features, expiresAt: Date.now() + ttl * 1000 });
+}
+
+/** Clear the entire feature cache (useful for tests or after plan changes) */
+export function clearFeatureCache(): void {
+  featureCache.clear();
+}
+
+/** Invalidate cache for a specific company (call after plan upgrade/downgrade) */
+export function invalidateCompanyFeatureCache(companyId: string): void {
+  featureCache.delete(companyId);
+}
+
+// ─── Middleware Factory ─────────────────────────────────
+
+/**
+ * Creates an Express middleware that checks whether the requesting tenant
+ * is active and has access to the specified feature(s).
+ *
+ * Usage:
+ * ```ts
+ * const ctrl = createTenantAccessControl({ getCompanyFeatures, isCompanyActive });
+ *
+ * // Gate an entire router
+ * router.use(ctrl.requireFeature("whatsapp"));
+ *
+ * // Gate a specific route with multiple required features
+ * router.post("/campaigns", ctrl.requireAllFeatures(["sms", "analytics"]), handler);
+ *
+ * // Gate where ANY one feature is sufficient
+ * router.get("/inbox", ctrl.requireAnyFeature(["sms", "whatsapp", "email"]), handler);
+ * ```
+ */
+export function createTenantAccessControl(config: TenantAccessControlConfig) {
+  const {
+    getCompanyFeatures,
+    isCompanyActive,
+    cacheTtlSeconds = 60,
+    logger = console,
+  } = config;
+
+  // ─── Resolve features (with cache) ─────────────────
+
+  async function resolveFeatures(companyId: string): Promise<Feature[]> {
+    const cached = getCachedFeatures(companyId, cacheTtlSeconds);
+    if (cached) return cached;
+
+    const features = await getCompanyFeatures(companyId);
+    setCachedFeatures(companyId, features, cacheTtlSeconds);
+    return features;
+  }
+
+  // ─── Tenant active check ───────────────────────────
+
+  async function checkTenantActive(companyId: string, res: Response): Promise<boolean> {
+    if (!isCompanyActive) return true;
+    const active = await isCompanyActive(companyId);
+    if (!active) {
+      logger.warn(`[TenantAccess] Company ${companyId} is disabled — blocking request`);
+      res.status(403).json({
+        success: false,
+        message: "Your account has been disabled. Please contact support.",
+      });
+      return false;
+    }
+    return true;
+  }
+
+  // ─── Middleware: require a single feature ──────────
+
+  function requireFeature(feature: Feature) {
+    return async (req: Request, res: Response, next: NextFunction) => {
+      const companyId = extractCompanyId(req);
+      if (!companyId) {
+        return res.status(401).json({ success: false, message: "Company context required." });
+      }
+
+      if (!(await checkTenantActive(companyId, res))) return;
+
+      const features = await resolveFeatures(companyId);
+      if (!features.includes(feature)) {
+        logger.info(
+          `[TenantAccess] Company ${companyId} denied access to "${feature}" — not in plan`,
+        );
+        return res.status(403).json({
+          success: false,
+          message: `Your subscription does not include access to the "${feature}" service. Please upgrade your plan.`,
+        });
+      }
+      next();
+    };
+  }
+
+  // ─── Middleware: require ALL listed features ───────
+
+  function requireAllFeatures(features: Feature[]) {
+    return async (req: Request, res: Response, next: NextFunction) => {
+      const companyId = extractCompanyId(req);
+      if (!companyId) {
+        return res.status(401).json({ success: false, message: "Company context required." });
+      }
+
+      if (!(await checkTenantActive(companyId, res))) return;
+
+      const allowed = await resolveFeatures(companyId);
+      const missing = features.filter((f) => !allowed.includes(f));
+      if (missing.length > 0) {
+        logger.info(
+          `[TenantAccess] Company ${companyId} missing features: ${missing.join(", ")}`,
+        );
+        return res.status(403).json({
+          success: false,
+          message: `Your subscription is missing access to: ${missing.join(", ")}. Please upgrade your plan.`,
+        });
+      }
+      next();
+    };
+  }
+
+  // ─── Middleware: require ANY one of listed features ─
+
+  function requireAnyFeature(features: Feature[]) {
+    return async (req: Request, res: Response, next: NextFunction) => {
+      const companyId = extractCompanyId(req);
+      if (!companyId) {
+        return res.status(401).json({ success: false, message: "Company context required." });
+      }
+
+      if (!(await checkTenantActive(companyId, res))) return;
+
+      const allowed = await resolveFeatures(companyId);
+      const hasAny = features.some((f) => allowed.includes(f));
+      if (!hasAny) {
+        return res.status(403).json({
+          success: false,
+          message: `Your subscription does not include any of: ${features.join(", ")}. Please upgrade your plan.`,
+        });
+      }
+      next();
+    };
+  }
+
+  // ─── Middleware: just check tenant is active ───────
+
+  function requireActiveTenant() {
+    return async (req: Request, res: Response, next: NextFunction) => {
+      const companyId = extractCompanyId(req);
+      if (!companyId) {
+        return res.status(401).json({ success: false, message: "Company context required." });
+      }
+      if (!(await checkTenantActive(companyId, res))) return;
+      next();
+    };
+  }
+
+  return {
+    requireFeature,
+    requireAllFeatures,
+    requireAnyFeature,
+    requireActiveTenant,
+    resolveFeatures,
+    clearFeatureCache,
+    invalidateCompanyFeatureCache,
+  };
+}
+
+// ─── Knex-backed Feature Resolver ───────────────────────
+
+/**
+ * Default implementation of `getCompanyFeatures` using Knex
+ * against the `company_service_configs` table.
+ *
+ * Returns the `service_name` of every row where `is_active = true`
+ * for the given company.
+ */
+export function knexFeatureResolver(knex: Knex) {
+  return async (companyId: string): Promise<Feature[]> => {
+    const rows = await knex("company_service_configs")
+      .select("service_name")
+      .where({ company_id: companyId, is_active: true });
+    return rows.map((r: any) => r.service_name as Feature);
+  };
+}
+
+/**
+ * Default implementation of `isCompanyActive` using Knex
+ * against the `companies` table.
+ */
+export function knexCompanyActiveChecker(knex: Knex) {
+  return async (companyId: string): Promise<boolean> => {
+    const row = await knex("companies")
+      .select("is_active")
+      .where({ id: companyId })
+      .first();
+    return row?.is_active === true || row?.is_active === 1;
+  };
+}
+
+// ─── Plan Helpers ───────────────────────────────────────
+
+/**
+ * Given a plan name, return the set of features it grants.
+ * Useful for provisioning a new company.
+ */
+export function getFeaturesForPlan(
+  planName: string,
+  plans: SubscriptionPlan[] = DEFAULT_PLANS,
+): Feature[] {
+  const plan = plans.find((p) => p.name === planName);
+  return plan ? [...plan.features] : [];
+}
+
+/**
+ * Provision a company's service configs based on a plan.
+ * Inserts rows into `company_service_configs` for each feature in the plan.
+ */
+export async function provisionCompanyPlan(
+  knex: Knex,
+  companyId: string,
+  planName: string,
+  plans: SubscriptionPlan[] = DEFAULT_PLANS,
+): Promise<void> {
+  const features = getFeaturesForPlan(planName, plans);
+  if (features.length === 0) return;
+
+  // Deactivate all existing configs
+  await knex("company_service_configs")
+    .where({ company_id: companyId })
+    .update({ is_active: false });
+
+  // Upsert new configs
+  for (const feature of features) {
+    const existing = await knex("company_service_configs")
+      .where({ company_id: companyId, service_name: feature })
+      .first();
+
+    if (existing) {
+      await knex("company_service_configs")
+        .where({ id: existing.id })
+        .update({ is_active: true, updated_at: knex.fn.now() });
+    } else {
+      await knex("company_service_configs").insert({
+        id: knex.raw("UUID()"),
+        company_id: companyId,
+        service_name: feature,
+        config: JSON.stringify({}),
+        is_active: true,
+        created_at: knex.fn.now(),
+        updated_at: knex.fn.now(),
+      });
+    }
+  }
+}
+
+// ─── Helpers ────────────────────────────────────────────
+
+function extractCompanyId(req: Request): string | undefined {
+  // Gateway sets x-company-id header; fallback to req.user.company_id / companyId
+  return (
+    (req.headers["x-company-id"] as string) ||
+    (req as any).user?.company_id ||
+    (req as any).user?.companyId
+  );
+}