@memberjunction/server 6.1.2 → 6.1.4

package/src/__tests__/cacheInvalidationRecordData.test.ts

@@ -0,0 +1,177 @@
+// The gate lives beside the subscription it protects, and that module carries type-graphql
+// decorators — so the metadata shim has to be in place before it is imported.
+import 'reflect-metadata';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  ConfigureRecordDataBroadcast,
+  MayBroadcastRecordData,
+} from '../generic/CacheInvalidationResolver.js';
+
+/**
+ * The cache-invalidation subscription is delivered to every connected client with no per-user
+ * filter, so anything `MayBroadcastRecordData` lets through is readable by every signed-in session
+ * regardless of row-level security or any tenant scoping a consumer applies on the read path.
+ *
+ * The important case is the DEFAULT: an untouched deployment must broadcast no row data at all,
+ * because that is the configuration everyone upgrades into.
+ */
+describe('MayBroadcastRecordData', () => {
+  afterEach(() => ConfigureRecordDataBroadcast([]));
+
+  it('broadcasts nothing before anything has configured it', () => {
+    // No ConfigureRecordDataBroadcast call at all — the state a process starts in, and the state it
+    // stays in if bootstrap ever stops calling it. Failing closed there is the whole point.
+    expect(MayBroadcastRecordData('Users')).toBe(false);
+    expect(MayBroadcastRecordData('AI Models')).toBe(false);
+  });
+
+  it('broadcasts nothing when the deployment has not opted in', () => {
+    ConfigureRecordDataBroadcast([]);
+    expect(MayBroadcastRecordData('Users')).toBe(false);
+  });
+
+  it('broadcasts nothing when the config value is absent', () => {
+    ConfigureRecordDataBroadcast(undefined);
+    expect(MayBroadcastRecordData('Users')).toBe(false);
+  });
+
+  it('allows exactly the entities named, and no others', () => {
+    ConfigureRecordDataBroadcast(['AI Models']);
+    expect(MayBroadcastRecordData('AI Models')).toBe(true);
+    expect(MayBroadcastRecordData('Users')).toBe(false);
+    expect(MayBroadcastRecordData('AI Model Vendors')).toBe(false);
+    // The allowlisted name as a SUBSTRING of another entity must not carry it in. Written this way
+    // deliberately: 'AI Model Vendors' above does not contain 'AI Models', so it passes against a
+    // loose `includes` match too and proves nothing — a substring mutation survived it.
+    expect(MayBroadcastRecordData('Archived AI Models 2024')).toBe(false);
+    // ...and the reverse direction, where the entity name is a substring of the allowlisted one.
+    expect(MayBroadcastRecordData('AI Model')).toBe(false);
+  });
+
+  it('matches entity names case- and whitespace-insensitively', () => {
+    ConfigureRecordDataBroadcast(['  ai models  ']);
+    expect(MayBroadcastRecordData('AI Models')).toBe(true);
+  });
+
+  it("restores the previous broadcast-everything behaviour only on an explicit '*'", () => {
+    ConfigureRecordDataBroadcast(['*']);
+    expect(MayBroadcastRecordData('Users')).toBe(true);
+    expect(MayBroadcastRecordData('Organization Person Roles')).toBe(true);
+  });
+});
+
+/**
+ * Importing this module must not drag server config loading in with it.
+ *
+ * The first version of this change read `configInfo` at module scope. `config.ts` runs
+ * `loadConfig()` on import, so every test that touched the resolver — directly or through
+ * ResolverBase — died at import with "Configuration validation failed". CI caught it; this keeps
+ * it caught.
+ */
+describe('CacheInvalidationResolver module surface', () => {
+  it('imports without any server configuration present', async () => {
+    await expect(import('../generic/CacheInvalidationResolver.js')).resolves.toBeDefined();
+  });
+});
+
+/**
+ * The allowlist is normalised where it enters, not where it is compared.
+ *
+ * Raised in review: the wildcard was matched raw while entity names were trimmed and lowercased,
+ * so a hand-edited `[' * ']` matched neither branch and silently opted nothing in — a config that
+ * reads as "broadcast everything" while the gate stayed fully closed.
+ */
+describe('allowlist normalisation', () => {
+  afterEach(() => ConfigureRecordDataBroadcast([]));
+
+  it("honours a wildcard written with surrounding whitespace", () => {
+    ConfigureRecordDataBroadcast([' * ']);
+    expect(MayBroadcastRecordData('Users')).toBe(true);
+  });
+
+  it('ignores blank entries rather than letting one match something', () => {
+    ConfigureRecordDataBroadcast(['', '   ']);
+    expect(MayBroadcastRecordData('Users')).toBe(false);
+    // A blank entry must not become a wildcard by accident either.
+    expect(MayBroadcastRecordData('')).toBe(false);
+  });
+
+  it('still matches a normal name written with odd casing and padding', () => {
+    ConfigureRecordDataBroadcast(['  AI MODELS  ']);
+    expect(MayBroadcastRecordData('ai models')).toBe(true);
+    expect(MayBroadcastRecordData('Users')).toBe(false);
+  });
+});
+
+/**
+ * Entity-level delivery filtering, raised in review.
+ *
+ * An event for an entity a session cannot read at all tells that session the record exists, its
+ * stable key and when it changed — and the session could never have read it, so withholding costs
+ * nothing. This does NOT close the row-level case: two sessions that both hold read permission on
+ * an entity still see each other's keys. That is tracked separately and deliberately not faked
+ * green here.
+ */
+describe('cacheInvalidationFilter', () => {
+  const event = (entityName: string) => ({
+    entityName,
+    primaryKeyValues: '[{"FieldName":"ID","Value":"r1"}]',
+    action: 'save',
+    sourceServerId: 's1',
+    timestamp: new Date(),
+  });
+  const session = (userRecord: unknown) => ({ userPayload: { userRecord } });
+
+  const withEntities = async (entities: Array<{ Name: string; CanRead: boolean }>) => {
+    vi.resetModules();
+    vi.doMock('@memberjunction/core', () => ({
+      Metadata: class {
+        get Entities() {
+          return entities.map((e) => ({
+            Name: e.Name,
+            GetUserPermisions: () => ({ CanRead: e.CanRead }),
+          }));
+        }
+        // The real one is case-insensitive and trims — the filter relies on that, so the mock does too.
+        EntityByName(name: string) {
+          const key = name.trim().toLowerCase();
+          return this.Entities.find((e) => e.Name.toLowerCase() === key);
+        }
+      },
+    }));
+    return (await import('../generic/CacheInvalidationResolver.js')).cacheInvalidationFilter;
+  };
+
+  afterEach(() => vi.doUnmock('@memberjunction/core'));
+
+  it('delivers an event for an entity the session may read', async () => {
+    const filter = await withEntities([{ Name: 'AI Models', CanRead: true }]);
+    expect(filter({ payload: event('AI Models') as never, context: session({ ID: 'u1' }) })).toBe(true);
+  });
+
+  it('withholds an event for an entity the session may NOT read', async () => {
+    const filter = await withEntities([{ Name: 'Users', CanRead: false }]);
+    expect(filter({ payload: event('Users') as never, context: session({ ID: 'u1' }) })).toBe(false);
+  });
+
+  it('fails closed when the connection carries no user', async () => {
+    // onConnect rejects a socket whose token does not validate, so this should not arise — and it
+    // is the case least deserving of an unfiltered firehose if it does.
+    const filter = await withEntities([{ Name: 'AI Models', CanRead: true }]);
+    expect(filter({ payload: event('AI Models') as never, context: undefined })).toBe(false);
+    expect(filter({ payload: event('AI Models') as never, context: session(undefined) })).toBe(false);
+  });
+
+  it('delivers when the entity is unknown to this server, rather than silently going stale', async () => {
+    // Deliberately the opposite choice: a name absent from metadata cannot be permission-checked,
+    // and withholding would stop invalidating a legitimately cacheable entity — a correctness bug
+    // in place of a disclosure one.
+    const filter = await withEntities([{ Name: 'AI Models', CanRead: true }]);
+    expect(filter({ payload: event('Some Entity This Server Never Heard Of') as never, context: session({ ID: 'u1' }) })).toBe(true);
+  });
+
+  it('withholds an event with no entity name', async () => {
+    const filter = await withEntities([{ Name: 'AI Models', CanRead: true }]);
+    expect(filter({ payload: { ...event(''), entityName: '' } as never, context: session({ ID: 'u1' }) })).toBe(false);
+  });
+});

package/src/config.ts

@@ -230,6 +230,29 @@ const cacheSettingsSchema = z.object({
   evictionSweepIntervalSeconds: z.number().optional().default(300),
   /** Enable verbose cache logging (hits, misses, evictions). Default: false. */
   verboseLogging: z.boolean().optional().default(false),
+  /**
+   * Entity names whose FULL ROW may ride along with a cache-invalidation broadcast.
+   *
+   * The cache-invalidation subscription is delivered to EVERY connected client with no per-user
+   * filter (see CacheInvalidationResolver), so any row named here is disclosed to every signed-in
+   * session, whatever row-level security or tenant scoping would otherwise apply to reading it.
+   *
+   * Defaults to `[]`: invalidation still carries the entity name and primary key, which is all a
+   * client needs to evict, and the client re-fetches through the normal read path where access
+   * control applies. Listing an entity re-enables the apply-in-place optimisation for it — correct
+   * only for reference data every signed-in user is allowed to read.
+   *
+   * What the re-fetch costs depends on the consumer. `ConversationEngine` re-reads the ONE record
+   * by primary key. `BaseEngine` (every engine subclass with `AutoRefresh`, the default) applies a
+   * remote save in place only when the row is present, so without it a remote save falls through to
+   * a full reload of each matching config — a `RunView` of that entity, not a keyed read. Remote
+   * deletes still apply in place from the primary key. Engine-cached reference entities that every
+   * signed-in user may read are the ones worth listing here.
+   *
+   * `['*']` opts every entity in, restoring the previous behaviour. Only safe on a deployment where
+   * every signed-in user may read every row of every entity.
+   */
+  recordDataBroadcastEntities: z.array(z.string()).optional().default([]),
 });
 
 const loggingSettingsSchema = z.object({

package/src/generic/CacheInvalidationResolver.ts

@@ -1,7 +1,57 @@
 import { Field, ObjectType, Resolver, Root, Subscription } from 'type-graphql';
+import { Metadata, UserInfo } from '@memberjunction/core';
 
 export const CACHE_INVALIDATION_TOPIC = 'CACHE_INVALIDATION';
 
+/**
+ * Entities whose rows may ride along with an invalidation event. Empty until the server entry point
+ * supplies the configured list, so the default — including in any process that never configures it
+ * — is to broadcast nothing.
+ */
+let allowedRecordDataEntities: readonly string[] = [];
+
+/**
+ * Supply the configured allowlist. Called once from the server entry point during bootstrap.
+ *
+ * INJECTED rather than read from `configInfo` here, deliberately. `config.ts` runs `loadConfig()` at
+ * module scope, so importing it from this module would drag full config validation into every
+ * import chain that touches the resolver — including unit tests, which have no server config and
+ * would fail at import with "Configuration validation failed". This module deliberately imports
+ * nothing from MJServer itself — only type-graphql and `@memberjunction/core` (for the entity
+ * permission check in the subscription filter), neither of which loads config.
+ */
+export function ConfigureRecordDataBroadcast(entities: readonly string[] | undefined | null): void {
+  // Normalised HERE, once, rather than at each comparison. The wildcard used to be matched raw
+  // (`includes('*')`) while entity names were trimmed and lowercased two lines below, so a
+  // hand-edited `[' * ']` matched neither branch and silently opted nothing in — a config that
+  // looks like it disables the gate while leaving it fully on. Empty entries are dropped so a
+  // stray `''` cannot match an entity whose name is somehow blank.
+  allowedRecordDataEntities = (entities ?? [])
+    .map((e) => e.trim().toLowerCase())
+    .filter((e) => e.length > 0);
+}
+
+/**
+ * May the full row of `entityName` be broadcast alongside its cache-invalidation event?
+ *
+ * The subscription below is filtered only by ENTITY-level read permission, so anything included
+ * here is disclosed to every signed-in session that may read the entity at all — regardless of
+ * row-level security or any tenant scoping a consumer applies on the read path, neither of which
+ * this push traverses. The answer is therefore NO unless a deployment has explicitly opted the
+ * entity in via `cacheSettings.recordDataBroadcastEntities`.
+ *
+ * Callers that get `false` simply omit `recordData`; the event still carries the entity name and
+ * primary key, so clients evict and re-fetch through the normal access-controlled read path.
+ *
+ * Matching is exact (trimmed, case-insensitive) rather than substring: a loose match would let an
+ * allowlisted name drag in every entity whose name contains it.
+ */
+export function MayBroadcastRecordData(entityName: string): boolean {
+  if (allowedRecordDataEntities.length === 0) return false;
+  if (allowedRecordDataEntities.includes('*')) return true;
+  return allowedRecordDataEntities.includes(entityName.trim().toLowerCase());
+}
+
 @ObjectType()
 export class CacheInvalidationNotification {
     @Field(() => String)
@@ -40,15 +90,101 @@ export interface CacheInvalidationPayload {
     recordData?: string;
 }
 
+/**
+ * What the subscription filter needs off the WS connection.
+ *
+ * Declared structurally rather than importing MJServer's `UserPayload`, which reaches `types.ts`
+ * and through it `auth/index.js` and config. Keeping this module's imports minimal is not fussiness
+ * — importing `configInfo` here is what previously broke every unit test that touched the resolver,
+ * and the import-surface test in this package exists to keep it that way.
+ */
+export interface CacheInvalidationFilterContext {
+    userPayload?: { userRecord?: unknown };
+}
+
+/**
+ * Should this subscriber hear about this event at all?
+ *
+ * Entity-level narrowing, raised in review: an event for an entity a session has no read
+ * permission on tells that session the record exists, its stable key, and when it changed — and
+ * the session could never have read it anyway, so nothing is lost by withholding it. This is a
+ * monotonic reduction in disclosure that needs no tenancy model, which is why it is here and the
+ * row-level question is not.
+ *
+ * What it does NOT close: two sessions that both hold read permission on an entity still see each
+ * other's keys, because what separates them is row-level. That predicate is tracked separately —
+ * see the class docblock below.
+ *
+ * `GetUserPermisions` is an in-memory match of the entity's permission rows against the user's
+ * roles, so this stays cheap enough to run per subscriber per event. It is not free: it runs for
+ * every connected socket on every save, so keep it free of I/O.
+ */
+export function cacheInvalidationFilter(data: {
+    payload: CacheInvalidationPayload;
+    context: CacheInvalidationFilterContext | undefined;
+}): boolean {
+    const user = data.context?.userPayload?.userRecord as UserInfo | undefined;
+    // FAIL CLOSED on identity, matching `statusUpdatesFilter`. `onConnect` rejects a socket whose
+    // token does not validate, so a subscriber with no user record should not exist; if one does,
+    // it is the case least deserving of an unfiltered firehose.
+    if (!user) {
+        return false;
+    }
+
+    const entityName = data.payload?.entityName;
+    if (!entityName) {
+        return false;
+    }
+
+    // A pub/sub subscription filter has no per-request provider to thread: it runs on the server's
+    // own metadata, which is the one place the entity's permission rows can be answered from.
+    const entity = new Metadata().EntityByName(entityName); // global-provider-ok: subscription filter — server-wide metadata, no request-scoped provider exists here
+    // DELIVER when the entity is unknown here, deliberately — the opposite of the choice above.
+    // A name absent from metadata cannot be permission-checked, and withholding would silently
+    // stop invalidating a legitimately cacheable entity, which is a correctness bug rather than a
+    // disclosure one. All it discloses is the name and key of something this server cannot
+    // describe.
+    if (!entity) {
+        return true;
+    }
+
+    return entity.GetUserPermisions(user).CanRead;
+}
+
 @Resolver()
 export class CacheInvalidationResolver {
     /**
-     * Subscription that broadcasts cache invalidation events to ALL connected clients.
-     * No session filter — every browser connected via WebSocket receives every event.
-     * This enables cross-server cache invalidation to propagate to browser clients.
+     * Subscription that broadcasts cache invalidation events to connected clients, so cross-server
+     * cache invalidation reaches browsers.
+     *
+     * Delivery is filtered only by ENTITY-level read permission (see {@link cacheInvalidationFilter}).
+     * Every session that may read an entity at all still receives every event for it, from every
+     * other session and tenant.
+     *
+     * Because that narrowing stops well short of row level, `RecordData` is only populated for entities a
+     * deployment has opted in through `cacheSettings.recordDataBroadcastEntities` — see
+     * {@link MayBroadcastRecordData}, applied at both publish sites.
+     *
+     * `EntityName`, `PrimaryKeyValues`, `Action` and `Timestamp` ARE still broadcast to every
+     * session, and that is a disclosure, not a safe residue. An earlier version of this comment
+     * called them "safe to broadcast" on the grounds that reading the record still goes through
+     * the access-controlled path — true of the row's CONTENTS, and beside the point for the
+     * metadata itself. A session with no relationship to a record still learns that it exists,
+     * its stable key, and every time it changes; across entities it learns the cadence and volume
+     * of another tenant's activity.
+     *
+     * The key is kept deliberately, because consumers need it to re-read the record they were
+     * told about (see `ResolveEntityEventKey` in @memberjunction/core) and because the alternative
+     * — a coarse "something in this entity changed" — forces whole-entity invalidation on the
+     * hottest write paths. That is a trade, not an absence of cost. Narrowing it means filtering
+     * delivery per subscriber, which needs an authorization predicate cheap enough to run per
+     * subscriber per event; entity-level permissions (`EntityInfo.GetUserPermisions`, an in-memory
+     * role match) would cover part of it, row-level tenancy would not.
      */
     @Subscription(() => CacheInvalidationNotification, {
         topics: CACHE_INVALIDATION_TOPIC,
+        filter: (data: { payload: CacheInvalidationPayload; context: CacheInvalidationFilterContext | undefined }) =>
+            cacheInvalidationFilter(data),
     })
     cacheInvalidation(
         @Root() payload: CacheInvalidationPayload

package/src/generic/DeleteOptionsInput.ts

@@ -50,9 +50,16 @@ export class DeleteOptionsInput {
      * schema-sync gate requires `DeleteOptionsInput` to carry every `EntityDeleteOptions` field;
      * {@link DeleteOptionsInput.SanitizeFromWire} forces it back to false on every request. See
      * that method for why.
+     *
+     * **Optional on the wire, on purpose.** This field did not exist in 5.51.x, and every other
+     * field here is required, so making it required too turned a 6.1 upgrade into a hard failure
+     * for every client that spells out `options___` on a delete (`Field
+     * "DeleteOptionsInput.SkipRecordChanges" of required type "Boolean!" was not provided`). A
+     * 5.51 client that omits it and a 6.1 client that sends `false` mean the same thing, and the
+     * server forces it to `false` regardless, so `null`/absent defaults to `false` here.
      */
-    @Field(() => Boolean)
-    SkipRecordChanges: boolean;
+    @Field(() => Boolean, { nullable: true, defaultValue: false })
+    SkipRecordChanges?: boolean;
 
     /**
      * Strips wire-unreachable capabilities from client-supplied delete options.

package/src/generic/ResolverBase.ts

@@ -40,7 +40,7 @@ import { SQLParser } from '@memberjunction/sql-parser';
 import { PostgreSQLDialect, SQLServerDialect, type SQLParserDialect } from '@memberjunction/sql-dialect';
 import { EncryptionEngine } from '@memberjunction/encryption';
 import { PUSH_STATUS_UPDATES_TOPIC, publishStatusUpdate } from './PushStatusResolver.js';
-import { CACHE_INVALIDATION_TOPIC } from './CacheInvalidationResolver.js';
+import { CACHE_INVALIDATION_TOPIC, MayBroadcastRecordData } from './CacheInvalidationResolver.js';
 import { PubSubManager } from './PubSubManager.js';
 import { FieldMapper } from '@memberjunction/graphql-dataprovider';
 import { Subscription } from 'rxjs';
@@ -1449,16 +1449,24 @@ export class ResolverBase {
    * Publishes a CACHE_INVALIDATION event to connected browser clients after a successful
    * entity save or delete. Includes the originSessionId so the originating browser can
    * skip redundant re-fetches (it already handled the event locally).
+   *
+   * The row itself rides along ONLY for entities opted in via
+   * `cacheSettings.recordDataBroadcastEntities` — this event reaches every connected client
+   * unfiltered, so the row would otherwise be readable by sessions that could not read the record.
    */
   protected PublishCacheInvalidation(entityObject: BaseEntity, action: 'save' | 'delete', userPayload: UserPayload): void {
+    const entityName = entityObject.EntityInfo.Name;
     PubSubManager.Instance.Publish(CACHE_INVALIDATION_TOPIC, {
-      entityName: entityObject.EntityInfo.Name,
+      entityName,
       primaryKeyValues: JSON.stringify(entityObject.PrimaryKey.KeyValuePairs),
       action,
       sourceServerId: MJGlobal.Instance.ProcessUUID,
       timestamp: new Date(),
       originSessionId: userPayload?.sessionId || null,
-      recordData: action === 'save' ? JSON.stringify(entityObject.GetAll()) : undefined,
+      recordData:
+        action === 'save' && MayBroadcastRecordData(entityName)
+          ? JSON.stringify(entityObject.GetAll())
+          : undefined,
     });
   }
 

package/src/index.ts

@@ -67,7 +67,7 @@ import { RegisterRSUProgressBridge } from './integration/RSUProgressBridge.js';
 import { ClientToolRequestManager, AgentRunWatchdog } from '@memberjunction/ai-agents';
 import { SessionJanitor } from './agentSessions/index.js';
 import { StartTaskGraphDispatcher } from './services/StartTaskGraphDispatcher.js';
-import { CACHE_INVALIDATION_TOPIC } from './generic/CacheInvalidationResolver.js';
+import { CACHE_INVALIDATION_TOPIC, MayBroadcastRecordData, ConfigureRecordDataBroadcast } from './generic/CacheInvalidationResolver.js';
 import { ConnectorFactory, IntegrationEngine, IntegrationSyncOptions } from '@memberjunction/integration-engine';
 import { CronExpressionHelper } from '@memberjunction/scheduling-engine';
 import {
@@ -896,6 +896,11 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
   // publish hook above so the first RSU event also reaches live subscribers.
   RegisterRSUProgressBridge();
 
+  // Hand the resolver its allowlist before anything can publish. It cannot read configInfo itself:
+  // config.ts loads and validates at module scope, so importing it there would pull full config
+  // validation into every import chain that touches the resolver, unit tests included.
+  ConfigureRecordDataBroadcast(configInfo.cacheSettings?.recordDataBroadcastEntities);
+
   // Global listener: broadcast CACHE_INVALIDATION to all browser clients whenever
   // ANY BaseEntity save/delete occurs on this server — regardless of whether it
   // originated from a GraphQL mutation or internal server-side code (agents, actions,
@@ -905,14 +910,21 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     if (event.event === MJEventType.ComponentEvent && event.eventCode === BaseEntity.BaseEventCode) {
       const beEvent = event.args as BaseEntityEvent;
       if (beEvent.type === 'save' || beEvent.type === 'delete') {
+        const entityName = beEvent.baseEntity.EntityInfo.Name;
         PubSubManager.Instance.Publish(CACHE_INVALIDATION_TOPIC, {
-          entityName: beEvent.baseEntity.EntityInfo.Name,
+          entityName,
           primaryKeyValues: JSON.stringify(beEvent.baseEntity.PrimaryKey.KeyValuePairs),
           action: beEvent.type,
           sourceServerId: MJGlobal.Instance.ProcessUUID,
           timestamp: new Date(),
           originSessionId: null,
-          recordData: beEvent.type === 'save' ? JSON.stringify(beEvent.baseEntity.GetAll()) : undefined,
+          // Opt-in only: this event reaches every connected client unfiltered, and this listener
+          // fires for server-internal saves too (agents, actions, orchestrator), which are exactly
+          // the ones no browser session asked for.
+          recordData:
+            beEvent.type === 'save' && MayBroadcastRecordData(entityName)
+              ? JSON.stringify(beEvent.baseEntity.GetAll())
+              : undefined,
         });
       }
     }