@memberjunction/server 5.8.0 → 5.9.0

package/src/index.ts

@@ -2,7 +2,7 @@ import dotenv from 'dotenv';
 
 dotenv.config({ quiet: true });
 
-import { expressMiddleware } from '@apollo/server/express4';
+import { expressMiddleware } from '@as-integrations/express5';
 import { mergeSchemas } from '@graphql-tools/schema';
 import { Metadata, DatabasePlatform, SetProvider, StartupManager as StartupManagerImport } from '@memberjunction/core';
 import { MJGlobal, UUIDsEqual } from '@memberjunction/global';
@@ -19,12 +19,13 @@ import { fileURLToPath } from 'node:url';
 import { sep } from 'node:path';
 import 'reflect-metadata';
 import { ReplaySubject } from 'rxjs';
-import { BuildSchemaOptions, buildSchemaSync, GraphQLTimestamp } from 'type-graphql';
+import { BuildSchemaOptions, buildSchemaSync, GraphQLTimestamp, PubSubEngine } from 'type-graphql';
+import { PubSub } from 'graphql-subscriptions';
 import sql from 'mssql';
 import { WebSocketServer } from 'ws';
 import buildApolloServer from './apolloServer/index.js';
 import { configInfo, dbDatabase, dbHost, dbPort, dbUsername, graphqlPort, graphqlRootPath, mj_core_schema, websiteRunFromPackage, RESTApiOptions } from './config.js';
-import { contextFunction, getUserPayload } from './context.js';
+import { contextFunction, createUnifiedAuthMiddleware, getUserPayload } from './context.js';
 import { requireSystemUserDirective, publicDirective } from './directives/index.js';
 import createMSSQLConfig from './orm.js';
 import { setupRESTEndpoints } from './rest/setupRESTEndpoints.js';
@@ -38,6 +39,10 @@ import { ScheduledJobsService } from './services/ScheduledJobsService.js';
 import { LocalCacheManager, StartupManager, TelemetryManager, TelemetryLevel } from '@memberjunction/core';
 import { getSystemUser } from './auth/index.js';
 import { GetAPIKeyEngine } from '@memberjunction/api-keys';
+import { RedisLocalStorageProvider } from '@memberjunction/redis-provider';
+import { GenericDatabaseProvider } from '@memberjunction/generic-database-provider';
+import { PubSubManager } from './generic/PubSubManager.js';
+import { CACHE_INVALIDATION_TOPIC } from './generic/CacheInvalidationResolver.js';
 
 const cacheRefreshInterval = configInfo.databaseSettings.metadataCacheRefreshInterval;
 
@@ -72,6 +77,8 @@ export {
 export * from './auth/APIKeyScopeAuth.js';
 
 export * from './generic/PushStatusResolver.js';
+export * from './generic/PubSubManager.js';
+export * from './generic/CacheInvalidationResolver.js';
 export * from './generic/ResolverBase.js';
 export * from './generic/RunViewResolver.js';
 export * from './resolvers/RunTemplateResolver.js';
@@ -118,9 +125,32 @@ export * from './resolvers/VersionHistoryResolver.js';
 export { GetReadOnlyDataSource, GetReadWriteDataSource, GetReadWriteProvider, GetReadOnlyProvider } from './util.js';
 
 export * from './generated/generated.js';
+export * from './hooks.js';
+export * from './multiTenancy/index.js';
 
+import type { ServerExtensibilityOptions, HookWithOptions } from './hooks.js';
+import { HookRegistry } from '@memberjunction/core';
+import type { HookRegistrationOptions } from '@memberjunction/core';
+import type { ApolloServerPlugin } from '@apollo/server';
+import { createTenantMiddleware, createTenantPreRunViewHook, createTenantPreSaveHook } from './multiTenancy/index.js';
 
-export type MJServerOptions = {
+/**
+ * Register a hook that may be a plain function or a `{ hook, Priority, Namespace }` object.
+ * Dynamic packages (e.g., BCSaaS) return hooks in object form to declare registration metadata.
+ */
+function registerHookEntry<T>(hookName: string, entry: T | HookWithOptions<T>): void {
+  if (typeof entry === 'function') {
+    HookRegistry.Register(hookName, entry);
+  } else if (entry && typeof entry === 'object' && 'hook' in entry) {
+    const { hook, Priority, Namespace } = entry as HookWithOptions<T>;
+    const options: HookRegistrationOptions = {};
+    if (Priority != null) options.Priority = Priority;
+    if (Namespace != null) options.Namespace = Namespace;
+    HookRegistry.Register(hookName, hook, options);
+  }
+}
+
+export type MJServerOptions = ServerExtensibilityOptions & {
   onBeforeServe?: () => void | Promise<void>;
   restApiOptions?: Partial<RESTApiOptions>; // Options for REST API configuration
 };
@@ -301,9 +331,53 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     console.log('Server telemetry disabled');
   }
 
-  // Initialize LocalCacheManager with the server-side storage provider (in-memory)
-  await LocalCacheManager.Instance.Initialize(Metadata.Provider.LocalStorageProvider);
-  console.log('LocalCacheManager initialized');
+  // Optionally inject Redis as the shared storage provider for cross-server cache invalidation
+  if (process.env.REDIS_URL) {
+    const redisProvider = new RedisLocalStorageProvider({
+      url: process.env.REDIS_URL,
+      keyPrefix: process.env.REDIS_KEY_PREFIX || 'mj',
+      enablePubSub: true,
+      enableLogging: true,
+    });
+    (Metadata.Provider as GenericDatabaseProvider).SetLocalStorageProvider(redisProvider);
+    await redisProvider.StartListening();
+
+    // Connect Redis pub/sub events to LocalCacheManager callback dispatch
+    // so cross-server cache invalidation messages are routed to registered callbacks
+    redisProvider.OnCacheChanged((event) => {
+        const sourceShort = event.SourceServerId ? event.SourceServerId.substring(0, 8) : 'unknown';
+        console.log(`[MJAPI] Redis pub/sub → DispatchCacheChange: ${event.Action} for "${event.CacheKey}" from server ${sourceShort}`);
+        LocalCacheManager.Instance.DispatchCacheChange(event);
+
+        // Also broadcast to connected browser clients via GraphQL subscription
+        // Extract entity name from the cache key (format: EntityName|Filter|OrderBy|...)
+        const entityName = event.CacheKey ? event.CacheKey.split('|')[0] : '';
+        if (entityName) {
+            PubSubManager.Instance.Publish(CACHE_INVALIDATION_TOPIC, {
+                entityName,
+                primaryKeyValues: null, // entity-level invalidation
+                action: event.Action || 'save',
+                sourceServerId: event.SourceServerId || 'unknown',
+                timestamp: new Date(),
+            });
+        }
+    });
+
+    console.log(`Redis cache provider connected: ${process.env.REDIS_URL}`);
+  }
+
+  // If Redis is available, swap LocalCacheManager's storage provider to Redis.
+  // LocalCacheManager may have already been initialized (with in-memory provider)
+  // during engine loading. SetStorageProvider migrates cached data to Redis.
+  if (process.env.REDIS_URL) {
+    await LocalCacheManager.Instance.SetStorageProvider(Metadata.Provider.LocalStorageProvider);
+    console.log('LocalCacheManager: storage provider swapped to Redis');
+  }
+  // Ensure LocalCacheManager is initialized (no-op if already done during engine loading)
+  if (!LocalCacheManager.Instance.IsInitialized) {
+    await LocalCacheManager.Instance.Initialize(Metadata.Provider.LocalStorageProvider);
+    console.log('LocalCacheManager initialized');
+  }
 
   // Initialize APIKeyEngine singleton — reads apiKeyGeneration from mj.config.cjs automatically
   // This must happen before any request handler calls GetAPIKeyEngine()
@@ -342,6 +416,15 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     Object.values(module).filter((value) => typeof value === 'function')
   ) as BuildSchemaOptions['resolvers'];
 
+  // Create an explicit PubSub instance so we can reference it outside of resolvers
+  // graphql-subscriptions v3 renamed asyncIterator→asyncIterableIterator, but
+  // type-graphql still calls asyncIterator. Shim for compatibility.
+  const pubSub = new PubSub() as unknown as Record<string, unknown>;
+  if (!pubSub.asyncIterator && typeof pubSub.asyncIterableIterator === 'function') {
+    pubSub.asyncIterator = pubSub.asyncIterableIterator;
+  }
+  PubSubManager.Instance.SetPubSubEngine(pubSub as unknown as PubSubEngine);
+
   let schema = mergeSchemas({
     schemas: [
       buildSchemaSync({
@@ -349,6 +432,7 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
         validate: false,
         scalarsMap: [{ type: Date, scalar: GraphQLTimestamp }],
         emitSchemaFile: websiteRunFromPackage !== 1,
+        pubSub,
       }),
     ],
     typeDefs: [requireSystemUserDirective.typeDefs, publicDirective.typeDefs],
@@ -356,6 +440,13 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
   schema = requireSystemUserDirective.transformer(schema);
   schema = publicDirective.transformer(schema);
 
+  // Apply user-provided schema transformers (after built-in directive transformers)
+  if (options?.SchemaTransformers) {
+    for (const transformer of options.SchemaTransformers) {
+      schema = transformer(schema);
+    }
+  }
+
   const httpServer = createServer(app);
 
   const webSocketServer = new WebSocketServer({ server: httpServer, path: graphqlRootPath });
@@ -385,7 +476,11 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     webSocketServer
   );
 
-  const apolloServer = buildApolloServer({ schema }, { httpServer, serverCleanup });
+  const apolloServer = buildApolloServer(
+    { schema },
+    { httpServer, serverCleanup },
+    options?.ApolloPlugins
+  );
   await apolloServer.start();
   
   // Fix #8: Add compression for better throughput performance
@@ -409,72 +504,81 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     level: 6
   }));
 
-  // Setup REST API endpoints BEFORE GraphQL (since graphqlRootPath may be '/' which catches all routes)
-  const authMiddleware = async (req, res, next) => {
-    try {
-      const sessionIdRaw = req.headers['x-session-id'];
-      const requestDomain = new URL(req.headers.origin || '').hostname;
-      const sessionId = sessionIdRaw ? sessionIdRaw.toString() : '';
-      const bearerToken = req.headers.authorization ?? '';
-      const apiKey = String(req.headers['x-mj-api-key']);
-
-      const userPayload = await getUserPayload(bearerToken, sessionId, dataSources, requestDomain, apiKey);
-      if (!userPayload) {
-        return res.status(401).json({ error: 'Invalid token' });
-      }
-
-      // Set both req.user (standard Express convention) and req['mjUser'] (MJ REST convention)
-      // Note: userPayload contains { userRecord: UserInfo, email, sessionId }
-      // The mjUser property expects the UserInfo directly (userRecord)
-      req.user = userPayload;
-      req['mjUser'] = userPayload.userRecord;
-      next();
-    } catch (error) {
-      console.error('Auth error:', error);
-      return res.status(401).json({ error: 'Authentication failed' });
+  // Apply user-provided Express middleware (after compression, before routes)
+  if (options?.ExpressMiddlewareBefore) {
+    for (const mw of options.ExpressMiddlewareBefore) {
+      app.use(mw);
     }
-  };
+  }
+
+  // Escape hatch for advanced Express app configuration
+  if (options?.ConfigureExpressApp) {
+    await Promise.resolve(options.ConfigureExpressApp(app));
+  }
 
-  // Build public URL for OAuth callbacks
+  // ─── OAuth callback routes (unauthenticated, registered BEFORE auth) ─────
   const oauthPublicUrl = configInfo.publicUrl || `${configInfo.baseUrl}:${configInfo.graphqlPort}${configInfo.graphqlRootPath || ''}`;
   console.log(`[OAuth] publicUrl: ${oauthPublicUrl}`);
 
-  // Set up OAuth callback routes at /oauth (independent of REST API)
-  // These must be registered BEFORE GraphQL middleware since graphqlRootPath may be '/'
+  let oauthAuthenticatedRouter: ReturnType<typeof createOAuthCallbackHandler>['authenticatedRouter'] | undefined;
   if (oauthPublicUrl) {
     const { callbackRouter, authenticatedRouter } = createOAuthCallbackHandler({
       publicUrl: oauthPublicUrl,
-      // TODO: These should be configurable to point to the MJ Explorer UI
       successRedirectUrl: `${oauthPublicUrl}/oauth/success`,
       errorRedirectUrl: `${oauthPublicUrl}/oauth/error`
     });
+    oauthAuthenticatedRouter = authenticatedRouter;
 
-    // Create CORS middleware for OAuth routes (needed for cross-origin requests from frontend)
     const oauthCors = cors<cors.CorsRequest>();
 
     // OAuth callback is unauthenticated (called by external auth server)
     app.use('/oauth', oauthCors, callbackRouter);
     console.log('[OAuth] Callback route registered at /oauth/callback');
+  }
+
+  // ─── Global CORS (before auth so 401 responses include CORS headers) ─────
+  // Without this, the browser blocks 401 responses from the auth middleware
+  // because they lack Access-Control-Allow-Origin headers, preventing the
+  // client from reading the error code and triggering token refresh.
+  app.use(cors<cors.CorsRequest>());
 
-    // OAuth status, initiate, and exchange endpoints require authentication
-    // Must also have CORS for frontend requests and JSON body parsing
-    app.use('/oauth', oauthCors, BodyParser.json(), authMiddleware, authenticatedRouter);
+  // ─── Unified auth middleware (replaces both REST authMiddleware and contextFunction auth) ─────
+  app.use(createUnifiedAuthMiddleware(dataSources));
+
+  // ─── Built-in post-auth middleware (multi-tenancy) ─────
+  // Config-driven multi-tenancy middleware runs after auth so it can read req.userPayload.
+  if (configInfo.multiTenancy?.enabled) {
+    const tenantMiddleware = createTenantMiddleware(configInfo.multiTenancy);
+    app.use(tenantMiddleware);
+  }
+
+  // ─── Post-auth middleware from plugins ─────
+  // Middleware here has access to the authenticated user via req.userPayload.
+  // Use this for tenant context resolution, org membership loading, etc.
+  if (options?.ExpressMiddlewarePostAuth) {
+    for (const mw of options.ExpressMiddlewarePostAuth) {
+      app.use(mw);
+    }
+  }
+
+  // ─── OAuth authenticated routes (auth already handled by unified middleware) ─────
+  if (oauthAuthenticatedRouter) {
+    const oauthCors = cors<cors.CorsRequest>();
+    app.use('/oauth', oauthCors, BodyParser.json(), oauthAuthenticatedRouter);
     console.log('[OAuth] Authenticated routes registered at /oauth/status, /oauth/initiate, and /oauth/exchange');
   }
 
-  // Get REST API configuration
+  // ─── REST API endpoints (auth already handled by unified middleware) ─────
   const restApiConfig = {
     enabled: configInfo.restApiOptions?.enabled ?? false,
     includeEntities: configInfo.restApiOptions?.includeEntities,
     excludeEntities: configInfo.restApiOptions?.excludeEntities,
   };
 
-  // Apply options from server options if provided (these override the config file)
   if (options?.restApiOptions) {
     Object.assign(restApiConfig, options.restApiOptions);
   }
 
-  // Get REST API configuration from environment variables if present (env vars override everything)
   if (process.env.MJ_REST_API_ENABLED !== undefined) {
     restApiConfig.enabled = process.env.MJ_REST_API_ENABLED === 'true';
     if (restApiConfig.enabled) {
@@ -490,12 +594,10 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     restApiConfig.excludeEntities = process.env.MJ_REST_API_EXCLUDE_ENTITIES.split(',').map(e => e.trim());
   }
 
-  // Set up REST endpoints with the configured options and auth middleware
-  setupRESTEndpoints(app, restApiConfig, authMiddleware);
+  // No per-route authMiddleware needed — unified auth middleware already ran
+  setupRESTEndpoints(app, restApiConfig);
 
-  // GraphQL middleware (after REST so /api/v1/* routes are handled first)
-  // Note: Type assertion needed due to @apollo/server bundling older @types/express types
-  // that are incompatible with Express 5.x types (missing 'param' property)
+  // ─── GraphQL middleware (contextFunction reads req.userPayload, no re-auth) ─────
   app.use(
     graphqlRootPath,
     cors<cors.CorsRequest>(),
@@ -509,9 +611,16 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
                                  dataSource: extendConnectionPoolWithQuery(dataSources[0].dataSource), // default read-write data source
                                  dataSources // all data source
                                }),
-    }) as unknown as express.RequestHandler
+    })
   );
 
+  // ─── Post-route middleware (error handlers, catch-alls) ─────
+  if (options?.ExpressMiddlewareAfter) {
+    for (const mw of options.ExpressMiddlewareAfter) {
+      app.use(mw);
+    }
+  }
+
   // Initialize and start scheduled jobs service if enabled
   let scheduledJobsService: ScheduledJobsService | null = null;
   if (configInfo.scheduledJobs?.enabled) {
@@ -525,6 +634,46 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     }
   }
 
+  // Register provider-level hooks with the global HookRegistry.
+  // Each entry can be a plain function or a { hook, Priority, Namespace } object.
+  if (options?.PreRunViewHooks) {
+    for (const entry of options.PreRunViewHooks) {
+      registerHookEntry('PreRunView', entry);
+    }
+  }
+  if (options?.PostRunViewHooks) {
+    for (const entry of options.PostRunViewHooks) {
+      registerHookEntry('PostRunView', entry);
+    }
+  }
+  if (options?.PreSaveHooks) {
+    for (const entry of options.PreSaveHooks) {
+      registerHookEntry('PreSave', entry);
+    }
+  }
+
+  // Auto-register multi-tenancy hooks when enabled in config
+  // (The tenant Express middleware was already registered above in the post-auth slot)
+  if (configInfo.multiTenancy?.enabled) {
+    console.log('[MultiTenancy] Enabled — registering tenant isolation hooks');
+    const tenantConfig = configInfo.multiTenancy;
+
+    // Register tenant PreRunView hook (injects WHERE clauses)
+    // Priority 50 + namespace allows middle layers to replace with their own implementation
+    HookRegistry.Register('PreRunView', createTenantPreRunViewHook(tenantConfig), {
+      Priority: 50,
+      Namespace: 'mj:tenantFilter',
+    });
+
+    // Register tenant PreSave hook (validates tenant column on writes)
+    HookRegistry.Register('PreSave', createTenantPreSaveHook(tenantConfig), {
+      Priority: 50,
+      Namespace: 'mj:tenantSave',
+    });
+
+    console.log(`[MultiTenancy] Context source: ${tenantConfig.contextSource}, scoping: ${tenantConfig.scopingStrategy}, write protection: ${tenantConfig.writeProtection}`);
+  }
+
   if (options?.onBeforeServe) {
     await Promise.resolve(options.onBeforeServe());
   }

package/src/multiTenancy/index.ts

@@ -0,0 +1,183 @@
+/**
+ * Multi-tenant data separation framework.
+ *
+ * Provides factory functions that create Express middleware and provider hooks
+ * based on the `multiTenancy` section of mj.config.cjs. All functions return
+ * standard hook/middleware types from WS2 so they integrate seamlessly with
+ * the MJServer extensibility system.
+ */
+
+import type { RequestHandler } from 'express';
+import type { PreRunViewHook, PreSaveHook } from '@memberjunction/core';
+import { Metadata, type UserInfo, type TenantContext } from '@memberjunction/core';
+import type { MultiTenancyConfig } from '../config.js';
+import type { UserPayload } from '../types.js';
+
+/** Custom tenant context extractor signature */
+export type TenantContextExtractor = (
+  user: UserInfo,
+  req: Express.Request
+) => Promise<{ TenantID: string } | null>;
+
+/**
+ * Creates Express middleware that resolves and attaches TenantContext
+ * to the authenticated user's UserInfo for each request.
+ *
+ * This middleware runs in the post-auth slot (after `createUnifiedAuthMiddleware`)
+ * so `req.userPayload` is available. It reads the tenant ID from the configured
+ * source and attaches it directly to `userPayload.userRecord.TenantContext`.
+ *
+ * By the time GraphQL resolvers or REST handlers run, the contextUser already
+ * has TenantContext set — no deferred pickup via `req['__mj_tenantId']` needed.
+ */
+export function createTenantMiddleware(config: MultiTenancyConfig): RequestHandler {
+  return (req, _res, next) => {
+    const userPayload = (req as { userPayload?: UserPayload }).userPayload;
+    if (!userPayload?.userRecord) {
+      // No authenticated user — skip tenant resolution
+      next();
+      return;
+    }
+
+    if (config.contextSource === 'header') {
+      const tenantId = req.headers[config.tenantHeader.toLowerCase()] as string | undefined;
+      if (tenantId) {
+        attachTenantContext(userPayload.userRecord as UserInfo, tenantId, 'header');
+      }
+    }
+    next();
+  };
+}
+
+/**
+ * Attaches TenantContext to a UserInfo object.
+ * Called from the GraphQL context function after authentication.
+ */
+export function attachTenantContext(
+  user: UserInfo,
+  tenantId: string,
+  source: TenantContext['Source']
+): void {
+  user.TenantContext = { TenantID: tenantId, Source: source };
+}
+
+/**
+ * Determines whether a given entity name should have tenant filtering applied.
+ */
+function isEntityScoped(entityName: string, config: MultiTenancyConfig): boolean {
+  // Auto-exclude core MJ entities (entities in the __mj schema)
+  if (config.autoExcludeCoreEntities) {
+    const md = new Metadata();
+    const entity = md.Entities.find(
+      e => e.Name.trim().toLowerCase() === entityName.trim().toLowerCase()
+    );
+    if (entity && entity.SchemaName === '__mj') {
+      return false;
+    }
+  }
+
+  const normalizedName = entityName.trim().toLowerCase();
+  const normalizedScoped = config.scopedEntities.map(e => e.trim().toLowerCase());
+
+  if (config.scopingStrategy === 'allowlist') {
+    // Only entities explicitly listed are scoped
+    return normalizedScoped.includes(normalizedName);
+  }
+
+  // Denylist: all entities are scoped EXCEPT those listed
+  return !normalizedScoped.includes(normalizedName);
+}
+
+/**
+ * Checks if a user has an admin role that bypasses tenant filtering.
+ */
+function isAdminUser(user: UserInfo, adminRoles: string[]): boolean {
+  if (!user.UserRoles || user.UserRoles.length === 0) return false;
+  const normalizedAdmin = adminRoles.map(r => r.trim().toLowerCase());
+  return user.UserRoles.some(
+    ur => normalizedAdmin.includes(ur.Role?.trim().toLowerCase() ?? '')
+  );
+}
+
+/**
+ * Creates a PreRunViewHook that auto-injects tenant WHERE clauses
+ * into RunView queries for scoped entities.
+ */
+export function createTenantPreRunViewHook(config: MultiTenancyConfig): PreRunViewHook {
+  return (params, contextUser) => {
+    // No tenant context → no filtering
+    if (!contextUser?.TenantContext) return params;
+
+    // Admin users bypass tenant filtering
+    if (isAdminUser(contextUser, config.adminRoles)) return params;
+
+    // Resolve entity name from params
+    const entityName = params.EntityName;
+    if (!entityName) return params; // Can't filter without knowing the entity
+
+    // Check if this entity should be scoped
+    if (!isEntityScoped(entityName, config)) return params;
+
+    // Determine which column holds the tenant ID
+    const tenantColumn = config.entityColumnMappings[entityName] ?? config.defaultTenantColumn;
+    const tenantFilter = `[${tenantColumn}] = '${contextUser.TenantContext.TenantID}'`;
+
+    // Inject the tenant filter
+    if (params.ExtraFilter && typeof params.ExtraFilter === 'string' && params.ExtraFilter.trim().length > 0) {
+      params.ExtraFilter = `(${params.ExtraFilter}) AND ${tenantFilter}`;
+    } else {
+      params.ExtraFilter = tenantFilter;
+    }
+
+    return params;
+  };
+}
+
+/**
+ * Creates a PreSaveHook that validates the tenant column on writes.
+ *
+ * In 'strict' mode, rejects saves where the tenant column value doesn't
+ * match the user's TenantContext. In 'log' mode, warns but allows. In
+ * 'off' mode, this hook is a no-op.
+ */
+export function createTenantPreSaveHook(config: MultiTenancyConfig): PreSaveHook {
+  return (entity, contextUser) => {
+    // No validation needed if write protection is off
+    if (config.writeProtection === 'off') return true;
+
+    // No tenant context → no validation
+    if (!contextUser?.TenantContext) return true;
+
+    // Admin users bypass write validation
+    if (isAdminUser(contextUser, config.adminRoles)) return true;
+
+    // Check if this entity should be scoped
+    const entityName = entity.EntityInfo?.Name;
+    if (!entityName) return true;
+    if (!isEntityScoped(entityName, config)) return true;
+
+    // Determine which column holds the tenant ID
+    const tenantColumn = config.entityColumnMappings[entityName] ?? config.defaultTenantColumn;
+
+    // Get the value of the tenant column from the entity
+    const tenantFieldValue = entity.Get(tenantColumn);
+
+    // For new records without the tenant column set, auto-assign the tenant ID
+    if (!entity.IsSaved && (tenantFieldValue === null || tenantFieldValue === undefined)) {
+      entity.Set(tenantColumn, contextUser.TenantContext.TenantID);
+      return true;
+    }
+
+    // Validate the tenant column matches
+    if (tenantFieldValue && String(tenantFieldValue) !== contextUser.TenantContext.TenantID) {
+      const message = `Save rejected: ${entityName} record belongs to tenant '${tenantFieldValue}' but user is in tenant '${contextUser.TenantContext.TenantID}'`;
+      if (config.writeProtection === 'strict') {
+        return message; // Reject with error message
+      }
+      // 'log' mode — warn but allow
+      console.warn(`[MultiTenancy] ${message}`);
+    }
+
+    return true;
+  };
+}