@memberjunction/server 6.2.0-edge.5 → 6.2.0-edge.6

package/src/__tests__/buildMagicLinkSessionUser.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, vi } from 'vitest';
+import { UserInfo } from '@memberjunction/core';
+import type jwt from 'jsonwebtoken';
+
+vi.mock('../config.js', () => ({
+  userEmailMap: {},
+  apiKey: 'test-api-key',
+  mj_core_schema: '__mj',
+  configInfo: {},
+}));
+vi.mock('../auth/index.js', () => ({
+  GetSigningKeys: vi.fn(),
+  GetSystemUser: vi.fn(),
+  GetValidationOptions: vi.fn(),
+  VerifyUserRecord: vi.fn(),
+  ExtractUserInfoFromPayload: vi.fn(),
+}));
+vi.mock('../util.js', () => ({
+  GetReadOnlyDataSource: vi.fn(),
+  GetReadWriteDataSource: vi.fn(),
+}));
+
+import { BuildMagicLinkSessionUser } from '../context.js';
+
+const uuid = (a: string, b: string) =>
+  [a.repeat(8), b.repeat(4), '4' + b.repeat(3), '8' + b.repeat(3), b.repeat(12)].join('-');
+const ANON_USER_ID = uuid('A', '0');
+const NAMED_USER_ID = uuid('B', '1');
+
+function makeUserRecord(id: string, email: string): UserInfo {
+  return new UserInfo(null, {
+    ID: id,
+    Name: 'Session Test User',
+    Email: email,
+    IsActive: true,
+    Type: 'User',
+    UserRoles: [],
+  });
+}
+
+describe('BuildMagicLinkSessionUser', () => {
+  it('sets AnonymousVisitorID from mj_sid for an anonymous magic-link token', () => {
+    const baseUser = makeUserRecord(ANON_USER_ID, 'anonymous@magic-link.local');
+    const payload: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_anon: true,
+      mj_sid: 'sid-visitor-123',
+      mj_scopes: [{ inviteId: 'inv-1', appId: 'app-1', role: 'Widget Guest', resourceId: 'res-shared' }],
+    };
+
+    const result = BuildMagicLinkSessionUser(baseUser, payload);
+
+    expect(result).not.toBe(baseUser);
+    expect(result.IsMagicLinkAnonymous).toBe(true);
+    expect(result.AnonymousVisitorID).toBe('sid-visitor-123');
+    expect(result.MagicLinkScope?.ResourceID).toBe('res-shared');
+    expect(baseUser.AnonymousVisitorID).toBeUndefined();
+  });
+
+  it('rejects an anonymous magic-link token without mj_sid', () => {
+    const baseUser = makeUserRecord(ANON_USER_ID, 'anonymous@magic-link.local');
+    const missingSid: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_anon: true,
+      mj_scopes: [{ inviteId: 'inv-1', appId: 'app-1', role: 'Widget Guest', resourceId: 'res-shared' }],
+    };
+    const blankSid: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_anon: true,
+      mj_sid: '   ',
+    };
+
+    expect(() => BuildMagicLinkSessionUser(baseUser, missingSid)).toThrow(/mj_sid/);
+    expect(() => BuildMagicLinkSessionUser(baseUser, blankSid)).toThrow(/mj_sid/);
+  });
+
+  it('leaves AnonymousVisitorID undefined for a named magic-link token (with or without resource scope)', () => {
+    const baseUser = makeUserRecord(NAMED_USER_ID, 'named@example.com');
+    const unscopedNamed: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_scopes: [{ inviteId: 'inv-named', appId: 'app-1', role: 'UI' }],
+    };
+    const scopedNamed: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_scopes: [{ inviteId: 'inv-named-2', appId: 'app-1', role: 'UI', resourceId: 'res-named-1', resourceType: 'Report' }],
+    };
+
+    const unscopedResult = BuildMagicLinkSessionUser(baseUser, unscopedNamed);
+    expect(unscopedResult.AnonymousVisitorID).toBeUndefined();
+
+    const scopedResult = BuildMagicLinkSessionUser(baseUser, scopedNamed);
+    expect(scopedResult.IsMagicLinkAnonymous).toBe(false);
+    expect(scopedResult.MagicLinkScope?.ResourceID).toBe('res-named-1');
+    expect(scopedResult.AnonymousVisitorID).toBeUndefined();
+  });
+});

package/src/__tests__/cacheBroadcastProviders.test.ts

@@ -0,0 +1,403 @@
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { EntityInfo, UserInfo } from '@memberjunction/core';
+import type { PubSubEngine } from 'type-graphql';
+import {
+    AzureWebPubSubBroadcastProvider,
+    AWSIoTCoreBroadcastProvider,
+    CacheInvalidationBroadcastManager,
+    GCPPubSubBroadcastProvider,
+    SequencedRoleBucketBroadcastProvider,
+    type AzureWebPubSubGroupMessage,
+    type AWSIoTCoreTopicMessage,
+    type GCPPubSubTopicMessage,
+} from '../broadcast/index.js';
+import type { CacheInvalidationPayload } from '../generic/CacheInvalidationResolver.js';
+import {
+    GetSessionStatusTopic,
+    PUSH_STATUS_UPDATES_TOPIC,
+    ParseStatusUpdateMessage,
+    PublishStatusUpdate,
+    ShouldReplicateStatusUpdate,
+    type PushStatusNotificationPayload,
+} from '../generic/PushStatusResolver.js';
+import { CreateSessionRoutingPubSub, PubSubManager } from '../generic/PubSubManager.js';
+import {
+    ResolveServerRole,
+    ShouldRunBackgroundWorkers,
+    ShouldServeInteractiveTraffic,
+} from '../serverRoleConfigUnits.js';
+
+function makeUser(id: string, roleIds: string[]): UserInfo {
+    return {
+        ID: id,
+        Name: `User ${id}`,
+        Email: `${id}@example.com`,
+        UserRoles: roleIds.map((r) => ({ UserID: id, RoleID: r, RoleName: r })),
+    } as unknown as UserInfo;
+}
+
+function makePayload(overrides: Partial<CacheInvalidationPayload> = {}): CacheInvalidationPayload {
+    return {
+        entityName: 'Invoices',
+        primaryKeyValues: '[{"FieldName":"ID","Value":"inv-1"}]',
+        action: 'save',
+        sourceServerId: 'srv-1',
+        timestamp: new Date('2026-10-20T12:00:00Z'),
+        recordData: '{"ID":"inv-1","Total":500}',
+        ...overrides,
+    };
+}
+
+describe('CacheInvalidationBroadcastManager & SequencedRoleBucketBroadcastProvider (Topologies 1 & 2)', () => {
+    let provider: SequencedRoleBucketBroadcastProvider;
+
+    beforeEach(() => {
+        provider = CacheInvalidationBroadcastManager.Instance.Configure({
+            provider: 'SequencedRoleBucket',
+            ringBufferSize: 5,
+            excludedEntities: ['MJ: Audit Logs'],
+        }) as SequencedRoleBucketBroadcastProvider;
+        provider.ResetStateForTesting();
+    });
+
+    it('defaults to SequencedRoleBucket and stamps monotonically increasing sequences', () => {
+        expect(provider.Topology).toBe('SequencedRoleBucket');
+        expect(provider.CurrentSequence).toBe(0);
+
+        const p1 = provider.RecordInvalidation(makePayload({ primaryKeyValues: 'pk-1' }));
+        const p2 = provider.RecordInvalidation(makePayload({ primaryKeyValues: 'pk-2' }));
+
+        expect(p1.sequence).toBe(1);
+        expect(p2.sequence).toBe(2);
+        expect(provider.CurrentSequence).toBe(2);
+        expect(provider.BufferedEventCount).toBe(2);
+    });
+
+    it('suppresses excluded high-churn entities from sequencing and broadcast', () => {
+        expect(provider.ShouldBroadcastEntity('MJ: Audit Logs')).toBe(false);
+        expect(provider.ShouldBroadcastEntity('Invoices')).toBe(true);
+
+        const ignored = provider.RecordInvalidation(makePayload({ entityName: 'MJ: Audit Logs' }));
+        expect(ignored.sequence).toBeUndefined();
+        expect(provider.CurrentSequence).toBe(0);
+    });
+
+    it('computes canonical, order-independent role fingerprints and memoizes per user object', () => {
+        const u1 = makeUser('u1', ['Role-B', 'role-a']);
+        const u2 = makeUser('u2', ['ROLE-A', '  role-b ']);
+
+        const fp1 = provider.GetRoleFingerprint(u1);
+        const fp2 = provider.GetRoleFingerprint(u2);
+
+        expect(fp1).toBe('roles:role-a|role-b');
+        expect(fp2).toBe('roles:role-a|role-b');
+        // Second call hits WeakMap cache
+        expect(provider.GetRoleFingerprint(u1)).toBe(fp1);
+    });
+
+    it('coalesces permission & RLS evaluation to O(Roles) instead of O(Subscribers)', () => {
+        const getUserPermisionsSpy = vi.fn((user: UserInfo) => {
+            const hasDeniedOnly = user.UserRoles.every((r) => r.RoleID === 'role-none');
+            return { CanRead: !hasDeniedOnly };
+        });
+
+        const fakeEntity = {
+            Name: 'Invoices',
+            GetUserPermisions: getUserPermisionsSpy,
+            Permissions: [
+                { RoleID: 'role-open', CanRead: true, Type: 'Allow', ReadRLSFilterID: null },
+                { RoleID: 'role-rls', CanRead: true, Type: 'Allow', ReadRLSFilterID: 'rls-filter-1' },
+                { RoleID: 'role-none', CanRead: false, Type: 'Allow', ReadRLSFilterID: null },
+            ],
+        } as unknown as EntityInfo;
+
+        vi.spyOn(provider, 'ResolveEntityForPayload').mockReturnValue(fakeEntity);
+        const rlsSpy = vi.spyOn(provider, 'ReadIsRowFiltered');
+
+        const payload = makePayload();
+
+        // Create 300 subscribers across only 3 distinct role buckets (100 per bucket)
+        const openUsers = Array.from({ length: 100 }, (_, i) => makeUser(`open-${i}`, ['role-open']));
+        const rlsUsers = Array.from({ length: 100 }, (_, i) => makeUser(`rls-${i}`, ['role-rls']));
+        const deniedUsers = Array.from({ length: 100 }, (_, i) => makeUser(`denied-${i}`, ['role-none']));
+
+        for (const u of openUsers) {
+            expect(provider.EvaluateEntityReadAccess(payload, u)).toBe(true);
+            const shaped = provider.ShapeEventForSubscriber(payload, u, fakeEntity);
+            expect(shaped.PrimaryKeyValues).toBe(payload.primaryKeyValues);
+            expect(shaped.RecordData).toBe(payload.recordData);
+        }
+
+        for (const u of rlsUsers) {
+            expect(provider.EvaluateEntityReadAccess(payload, u)).toBe(true);
+            const shaped = provider.ShapeEventForSubscriber(payload, u, fakeEntity);
+            expect(shaped.PrimaryKeyValues).toBeUndefined();
+            expect(shaped.RecordData).toBeUndefined();
+        }
+
+        for (const u of deniedUsers) {
+            expect(provider.EvaluateEntityReadAccess(payload, u)).toBe(false);
+        }
+
+        // Despite 300 subscribers, GetUserPermisions ran only 3 times (once per unique role bucket)
+        // and ReadIsRowFiltered ran only 2 times (for the 2 allowed role buckets)!
+        expect(getUserPermisionsSpy).toHaveBeenCalledTimes(3);
+        expect(rlsSpy).toHaveBeenCalledTimes(2);
+    });
+
+    it('serves delta catch-up from the circular ring buffer and coalesces duplicate PK updates', () => {
+        const fakeEntity = {
+            Name: 'Invoices',
+            GetUserPermisions: () => ({ CanRead: true }),
+            Permissions: [{ RoleID: 'role-open', CanRead: true, Type: 'Allow', ReadRLSFilterID: null }],
+        } as unknown as EntityInfo;
+        vi.spyOn(provider, 'ResolveEntityForPayload').mockReturnValue(fakeEntity);
+
+        const user = makeUser('u1', ['role-open']);
+
+        // Record 4 events (two on inv-1, one on inv-2, one on inv-1 again)
+        provider.RecordInvalidation(makePayload({ primaryKeyValues: 'inv-1', recordData: '{"v":1}' })); // seq 1
+        provider.RecordInvalidation(makePayload({ primaryKeyValues: 'inv-2', recordData: '{"v":2}' })); // seq 2
+        provider.RecordInvalidation(makePayload({ primaryKeyValues: 'inv-1', recordData: '{"v":3}' })); // seq 3
+
+        const catchUp = provider.GetChangesSince(0, user);
+        expect(catchUp.RequiresFullRefresh).toBe(false);
+        expect(catchUp.CurrentSequence).toBe(3);
+        // inv-1 (seq 1 and seq 3) coalesced to latest (seq 3), so 2 events total
+        expect(catchUp.Events).toHaveLength(2);
+        const inv1Event = catchUp.Events.find((e) => e.PrimaryKeyValues === 'inv-1');
+        expect(inv1Event?.RecordData).toBe('{"v":3}');
+        expect(inv1Event?.Sequence).toBe(3);
+    });
+
+    it('signals RequiresFullRefresh when sinceSequence has been evicted from the circular ring buffer', () => {
+        const fakeEntity = {
+            Name: 'Invoices',
+            GetUserPermisions: () => ({ CanRead: true }),
+            Permissions: [{ RoleID: 'role-open', CanRead: true, Type: 'Allow', ReadRLSFilterID: null }],
+        } as unknown as EntityInfo;
+        vi.spyOn(provider, 'ResolveEntityForPayload').mockReturnValue(fakeEntity);
+
+        const user = makeUser('u1', ['role-open']);
+
+        // Ring buffer size is 5; push 7 events so sequences 1 and 2 are overwritten (oldest in buffer is 3)
+        for (let i = 1; i <= 7; i++) {
+            provider.RecordInvalidation(makePayload({ primaryKeyValues: `inv-${i}` }));
+        }
+
+        // Requesting sinceSequence = 1 (missed seq 2, which was evicted) -> RequiresFullRefresh: true
+        const evictedCatchUp = provider.GetChangesSince(1, user);
+        expect(evictedCatchUp.RequiresFullRefresh).toBe(true);
+        expect(evictedCatchUp.Events).toHaveLength(0);
+
+        // Requesting sinceSequence = 2 (oldest needed is seq 3, still in buffer) -> RequiresFullRefresh: false
+        const validCatchUp = provider.GetChangesSince(2, user);
+        expect(validCatchUp.RequiresFullRefresh).toBe(false);
+        expect(validCatchUp.Events).toHaveLength(5);
+    });
+});
+
+describe('Topology 3 Cloud Multiplexer Providers (AzureWebPubSub, AWSIoTCore, GCPPubSub)', () => {
+    afterEach(() => {
+        CacheInvalidationBroadcastManager.Instance.Configure({ provider: 'SequencedRoleBucket' });
+    });
+
+    it('AzureWebPubSubBroadcastProvider negotiates signed JWT URLs and publishes role-shaped group messages', async () => {
+        const azureProvider = CacheInvalidationBroadcastManager.Instance.Configure({
+            provider: 'AzureWebPubSub',
+            azureWebPubSub: {
+                endpoint: 'https://mj-test.webpubsub.azure.com',
+                hubName: 'mj_hub',
+                accessKey: 'test-secret-access-key-123456',
+                tokenTtlMinutes: 30,
+            },
+        }) as AzureWebPubSubBroadcastProvider;
+
+        expect(azureProvider).toBeInstanceOf(AzureWebPubSubBroadcastProvider);
+        expect(azureProvider.Topology).toBe('AzureWebPubSub');
+
+        const user = makeUser('u-azure', ['Role-Admin', 'Role-Finance']);
+        const negotiated = await azureProvider.NegotiateClientConnection(user);
+        expect(negotiated.Provider).toBe('AzureWebPubSub');
+        expect(negotiated.Url).toContain('wss://mj-test.webpubsub.azure.com/client/hubs/mj_hub?access_token=');
+        expect(negotiated.Token).toBeDefined();
+        expect(negotiated.Groups).toEqual(['mj-role-role-admin', 'mj-role-role-finance']);
+
+        const published: AzureWebPubSubGroupMessage[] = [];
+        azureProvider.SetGroupPublisher(async (msg) => {
+            published.push(msg);
+        });
+
+        const fakeEntity = {
+            Name: 'Invoices',
+            GetUserPermisions: () => ({ CanRead: true }),
+            Permissions: [
+                { RoleID: 'role-admin', CanRead: true, Type: 'Allow', ReadRLSFilterID: null },
+                { RoleID: 'role-rls', CanRead: true, Type: 'Allow', ReadRLSFilterID: 'rls-1' },
+            ],
+        } as unknown as EntityInfo;
+        vi.spyOn(azureProvider, 'ResolveEntityForPayload').mockReturnValue(fakeEntity);
+
+        azureProvider.RecordInvalidation(makePayload());
+        await new Promise((r) => setTimeout(r, 10));
+
+        expect(published).toHaveLength(2);
+        const adminMsg = published.find((m) => m.GroupName === 'mj-role-role-admin');
+        const rlsMsg = published.find((m) => m.GroupName === 'mj-role-role-rls');
+        expect(adminMsg?.Event.PrimaryKeyValues).toBeDefined();
+        expect(rlsMsg?.Event.PrimaryKeyValues).toBeUndefined();
+    });
+
+    it('AWSIoTCoreBroadcastProvider negotiates SigV4 presigned MQTT URLs and publishes role topics', async () => {
+        const awsProvider = CacheInvalidationBroadcastManager.Instance.Configure({
+            provider: 'AWSIoTCore',
+            awsIoTCore: {
+                endpoint: 'a1b2c3-ats.iot.us-east-1.amazonaws.com',
+                region: 'us-east-1',
+                topicPrefix: 'mj/prod/cache',
+                accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
+                secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+            },
+        }) as AWSIoTCoreBroadcastProvider;
+
+        expect(awsProvider).toBeInstanceOf(AWSIoTCoreBroadcastProvider);
+        const user = makeUser('u-aws', ['role-ops']);
+        const negotiated = await awsProvider.NegotiateClientConnection(user);
+        expect(negotiated.Provider).toBe('AWSIoTCore');
+        expect(negotiated.Url).toContain('wss://a1b2c3-ats.iot.us-east-1.amazonaws.com/mqtt?X-Amz-Algorithm=AWS4-HMAC-SHA256');
+        expect(negotiated.Groups).toEqual(['mj/prod/cache/roles/role-ops']);
+
+        const published: AWSIoTCoreTopicMessage[] = [];
+        awsProvider.SetTopicPublisher(async (msg) => {
+            published.push(msg);
+        });
+        const fakeEntity = {
+            Name: 'Invoices',
+            GetUserPermisions: () => ({ CanRead: true }),
+            Permissions: [{ RoleID: 'role-ops', CanRead: true, Type: 'Allow', ReadRLSFilterID: null }],
+        } as unknown as EntityInfo;
+        vi.spyOn(awsProvider, 'ResolveEntityForPayload').mockReturnValue(fakeEntity);
+
+        awsProvider.RecordInvalidation(makePayload());
+        await new Promise((r) => setTimeout(r, 10));
+        expect(published).toHaveLength(1);
+        expect(published[0].Topic).toBe('mj/prod/cache/roles/role-ops');
+    });
+
+    it('GCPPubSubBroadcastProvider negotiates gateway tokens and publishes Pub/Sub topic messages', async () => {
+        const gcpProvider = CacheInvalidationBroadcastManager.Instance.Configure({
+            provider: 'GCPPubSub',
+            gcpPubSub: {
+                projectId: 'mj-cloud-prod',
+                topicPrefix: 'mj-invalidation',
+                gatewayUrl: 'https://cache-gw.run.app/ws',
+                signingSecret: 'gcp-gateway-secret-key',
+            },
+        }) as GCPPubSubBroadcastProvider;
+
+        expect(gcpProvider).toBeInstanceOf(GCPPubSubBroadcastProvider);
+        const user = makeUser('u-gcp', ['role-analyst']);
+        const negotiated = await gcpProvider.NegotiateClientConnection(user);
+        expect(negotiated.Provider).toBe('GCPPubSub');
+        expect(negotiated.Url).toContain('wss://cache-gw.run.app/ws?token=');
+        expect(negotiated.Groups).toEqual(['projects/mj-cloud-prod/topics/mj-invalidation-role-role-analyst']);
+
+        const published: GCPPubSubTopicMessage[] = [];
+        gcpProvider.SetTopicPublisher(async (msg) => {
+            published.push(msg);
+        });
+        const fakeEntity = {
+            Name: 'Invoices',
+            GetUserPermisions: () => ({ CanRead: true }),
+            Permissions: [{ RoleID: 'role-analyst', CanRead: true, Type: 'Allow', ReadRLSFilterID: null }],
+        } as unknown as EntityInfo;
+        vi.spyOn(gcpProvider, 'ResolveEntityForPayload').mockReturnValue(fakeEntity);
+
+        gcpProvider.RecordInvalidation(makePayload());
+        await new Promise((r) => setTimeout(r, 10));
+        expect(published).toHaveLength(1);
+        expect(published[0].TopicName).toBe('projects/mj-cloud-prod/topics/mj-invalidation-role-role-analyst');
+    });
+});
+
+describe('PushStatusResolver O(1) session routing and WeakMap JSON memoization', () => {
+    it('routes session-specific updates to PUSH_STATUS_UPDATES:session:<id> and wildcard updates to PUSH_STATUS_UPDATES', async () => {
+        const rawPublish = vi.fn(async () => undefined);
+        const rawPubSub: PubSubEngine = {
+            publish: rawPublish,
+            subscribe: vi.fn(),
+            unsubscribe: vi.fn(),
+            asyncIterator: vi.fn(),
+        } as unknown as PubSubEngine;
+
+        PubSubManager.Instance.SetPubSubEngine(rawPubSub);
+        const routedPubSub = PubSubManager.Instance.PubSubEngine!;
+
+        PublishStatusUpdate(routedPubSub, {
+            sessionId: 'tab-abc',
+            ownerUserId: 'user-1',
+            message: '{"type":"Progress"}',
+        });
+
+        PublishStatusUpdate(routedPubSub, {
+            sessionId: '*',
+            ownerUserId: 'user-1',
+            message: '{"type":"Broadcast"}',
+        });
+
+        expect(rawPublish).toHaveBeenCalledTimes(2);
+        expect(rawPublish).toHaveBeenNthCalledWith(
+            1,
+            GetSessionStatusTopic('tab-abc'),
+            expect.objectContaining({ sessionId: 'tab-abc' })
+        );
+        expect(rawPublish).toHaveBeenNthCalledWith(
+            2,
+            PUSH_STATUS_UPDATES_TOPIC,
+            expect.objectContaining({ sessionId: '*' })
+        );
+    });
+
+    it('memoizes JSON.parse per PushStatusNotificationPayload object via WeakMap', () => {
+        const payload: PushStatusNotificationPayload = {
+            sessionId: 'tab-1',
+            ownerUserId: 'u-1',
+            message: JSON.stringify({ type: 'StreamingContent', step: 1 }),
+        };
+
+        const parseSpy = vi.spyOn(JSON, 'parse');
+        try {
+            const first = ParseStatusUpdateMessage(payload);
+            const second = ParseStatusUpdateMessage(payload);
+            const shouldReplicate = ShouldReplicateStatusUpdate(payload.message, payload);
+
+            expect(first).toBe(second);
+            expect(shouldReplicate).toBe(false);
+            expect(parseSpy).toHaveBeenCalledTimes(1);
+        } finally {
+            parseSpy.mockRestore();
+        }
+    });
+});
+
+describe('ServerRole configuration units (Pillar 4)', () => {
+    it('resolves all, api, and worker roles case-insensitively and defaults to all', () => {
+        expect(ResolveServerRole(undefined)).toBe('all');
+        expect(ResolveServerRole('')).toBe('all');
+        expect(ResolveServerRole('  API ')).toBe('api');
+        expect(ResolveServerRole('WORKER')).toBe('worker');
+        expect(ResolveServerRole('all')).toBe('all');
+        expect(() => ResolveServerRole('invalid-role')).toThrow(/Invalid MJ_SERVER_ROLE/);
+    });
+
+    it('correctly gates background workers and interactive traffic by role', () => {
+        expect(ShouldRunBackgroundWorkers('all')).toBe(true);
+        expect(ShouldRunBackgroundWorkers('worker')).toBe(true);
+        expect(ShouldRunBackgroundWorkers('api')).toBe(false);
+
+        expect(ShouldServeInteractiveTraffic('all')).toBe(true);
+        expect(ShouldServeInteractiveTraffic('api')).toBe(true);
+        expect(ShouldServeInteractiveTraffic('worker')).toBe(false);
+    });
+});

package/src/__tests__/cacheInvalidationRecordData.test.ts

@@ -8,6 +8,8 @@ import {
   ReadIsRowFiltered,
   ShapeCacheInvalidationEvent,
 } from '../generic/CacheInvalidationResolver.js';
+import { EntityInfo } from '@memberjunction/core';
+import { EmployeeEntity } from './fieldSecurityFixtures.js';
 
 /**
  * The cache-invalidation subscription is delivered to every connected client with no per-user
@@ -62,6 +64,49 @@ describe('MayBroadcastRecordData', () => {
   });
 });
 
+/**
+ * An entity under field-level security never broadcasts its row, whatever the allowlist says.
+ *
+ * The event reaches every signed-in session that may read the entity, with no per-user
+ * projection, so a row of an entity whose fields are restricted per role would hand every
+ * session the columns it may not read. The check is the IS-A-aware one: a child whose parent has
+ * field security carries the parent's restricted fields as its own.
+ */
+describe('MayBroadcastRecordData: entities under field-level security', () => {
+  afterEach(() => ConfigureRecordDataBroadcast([]));
+
+  it("REGRESSION: refuses an FLS entity even under an explicit '*'", () => {
+    ConfigureRecordDataBroadcast(['*']);
+    expect(MayBroadcastRecordData('Employees', EmployeeEntity(true))).toBe(false);
+  });
+
+  it('REGRESSION: refuses an FLS entity that is named in the allowlist', () => {
+    ConfigureRecordDataBroadcast(['Employees']);
+    expect(MayBroadcastRecordData('Employees', EmployeeEntity(true))).toBe(false);
+  });
+
+  it('still allows the same entity with field security off', () => {
+    ConfigureRecordDataBroadcast(['Employees']);
+    expect(MayBroadcastRecordData('Employees', EmployeeEntity(false))).toBe(true);
+  });
+
+  it("REGRESSION: refuses MJ: Record Changes under '*', with or without its metadata", () => {
+    // A Record Change row carries other entities' values in ChangesJSON / FullRecordJSON, and its
+    // own FieldLevelSecurityApplies is false; the per-row projection never runs on this push.
+    ConfigureRecordDataBroadcast(['*']);
+    const recordChanges = new EntityInfo({ ID: 'rc', Name: 'MJ: Record Changes', SchemaName: '__mj', BaseTable: 'RecordChange', BaseView: 'vwRecordChanges', Fields: [] });
+    expect(recordChanges.FieldLevelSecurityApplies).toBe(false);
+    expect(MayBroadcastRecordData('MJ: Record Changes', recordChanges)).toBe(false);
+    expect(MayBroadcastRecordData('MJ: Record Changes')).toBe(false);
+    expect(MayBroadcastRecordData(' mj: record changes ')).toBe(false);
+  });
+
+  it('REGRESSION: refuses MJ: Record Changes even when named in the allowlist', () => {
+    ConfigureRecordDataBroadcast(['MJ: Record Changes']);
+    expect(MayBroadcastRecordData('MJ: Record Changes')).toBe(false);
+  });
+});
+
 /**
  * Importing this module must not drag server config loading in with it.
  *

package/src/__tests__/fieldSecurityFixtures.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared field-security fixtures for the transport tests: an `Employees` entity whose `Salary`
+ * and `Base Salary` only the HR role may read, plus users holding either role.
+ *
+ * Built from real `EntityInfo` / `UserInfo` objects so the denied sets come from the same
+ * aggregation production uses, not from a stub.
+ */
+import { EntityInfo, FieldSecurityClientInputMessage, UserInfo, UserRoleInfo } from '@memberjunction/core';
+
+export const HR_ROLE_ID = 'A0000000-0000-0000-0000-000000000001';
+export const INTERN_ROLE_ID = 'A0000000-0000-0000-0000-000000000003';
+export const EMPLOYEES_ENTITY_ID = 'entity-employees';
+export const EMPLOYEES_ENTITY_NAME = 'Employees';
+
+/** The salary an HR user may read and an intern may not. Distinctive so a leak is easy to spot. */
+export const SECRET_SALARY = 987654.32;
+
+function openTo(fieldId: string, roles: string[] = [HR_ROLE_ID, INTERN_ROLE_ID]): Record<string, unknown>[] {
+    return roles.map((roleId, i) => ({
+        ID: `${fieldId}-open-${i}`,
+        EntityFieldID: fieldId,
+        RoleID: roleId,
+        ReadAccess: 'Allow',
+        UpdateAccess: 'Allow',
+        CreateAccess: 'Allow',
+    }));
+}
+
+/** Init data for the `Employees` entity. `withFls: false` switches field security off entirely. */
+export function EmployeeEntityInit(withFls = true): Record<string, unknown> {
+    const field = (id: string, sequence: number, name: string, type: string, extra: Record<string, unknown> = {}) => ({
+        ID: id, EntityID: EMPLOYEES_ENTITY_ID, Sequence: sequence, Name: name, Entity: EMPLOYEES_ENTITY_NAME, Type: type, ...extra,
+    });
+    return {
+        ID: EMPLOYEES_ENTITY_ID,
+        Name: EMPLOYEES_ENTITY_NAME,
+        SchemaName: 'dbo',
+        BaseTable: 'Employee',
+        BaseView: 'vwEmployees',
+        IncludeInAPI: true,
+        AllowCreateAPI: true,
+        AllowUpdateAPI: true,
+        AllowDeleteAPI: true,
+        EnableFieldLevelSecurity: withFls,
+        Permissions: [
+            { EntityID: EMPLOYEES_ENTITY_ID, RoleID: HR_ROLE_ID, CanCreate: true, CanRead: true, CanUpdate: true, CanDelete: true },
+            { EntityID: EMPLOYEES_ENTITY_ID, RoleID: INTERN_ROLE_ID, CanCreate: true, CanRead: true, CanUpdate: true, CanDelete: true },
+        ],
+        Fields: [
+            field('f-id', 1, 'ID', 'uniqueidentifier', { IsPrimaryKey: true }),
+            field('f-name', 2, 'Name', 'nvarchar', { EntityFieldPermissions: openTo('f-name') }),
+            field('f-salary', 3, 'Salary', 'money', { EntityFieldPermissions: openTo('f-salary', [HR_ROLE_ID]) }),
+            field('f-base-salary', 4, 'Base Salary', 'money', { EntityFieldPermissions: openTo('f-base-salary', [HR_ROLE_ID]) }),
+            field('f-notes', 5, 'Notes', 'nvarchar', { EntityFieldPermissions: openTo('f-notes') }),
+        ],
+    };
+}
+
+export function EmployeeEntity(withFls = true): EntityInfo {
+    return new EntityInfo(EmployeeEntityInit(withFls));
+}
+
+export function BuildUser(roleIds: string[], id = 'user-1'): UserInfo {
+    const u = new UserInfo();
+    u.ID = id;
+    u.Name = 'Test User';
+    u.Email = `${id}@test.com`;
+    u.IsActive = true;
+    (u as unknown as Record<string, unknown>)['_UserRoles'] =
+        roleIds.map(rid => new UserRoleInfo({ UserID: id, RoleID: rid, Role: `Role-${rid}` }));
+    return u;
+}
+
+export const Intern = (): UserInfo => BuildUser([INTERN_ROLE_ID], 'intern-1');
+export const HRUser = (): UserInfo => BuildUser([HR_ROLE_ID], 'hr-1');
+
+/** A full-width employee row: what a system-identity load, or a save's re-read, returns. */
+export function FullWidthEmployeeRow(): Record<string, unknown> {
+    return { ID: 'emp-1', Name: 'Ada', Salary: SECRET_SALARY, 'Base Salary': SECRET_SALARY, Notes: 'n' };
+}
+
+/** The refusal text for a key, identical whether the key is denied or names no field. */
+export function RefusalFor(key: string): string {
+    return FieldSecurityClientInputMessage(key, EMPLOYEES_ENTITY_NAME);
+}
+
+/** A metadata source the projection accepts; Record Changes resolution is never reached for Employees. */
+export const NoRecordChangesMetadata = {
+    Entities: [] as EntityInfo[],
+    EntityByID: (): EntityInfo | undefined => undefined,
+};

package/src/__tests__/globalCors.test.ts

@@ -58,7 +58,7 @@ async function startApp(extensions: ServerExtensionConfig[]): Promise<string> {
     app.use(CreateGlobalCorsMiddleware({ allowedOrigins: ['*'] }, GetCorsOwningServerExtensionRoots(extensions)));
     mountBallotExtension(app);
     app.get('/core', (_req, res) => { res.json({ ok: true }); });
-    server = app.listen(0);
+    server = app.listen(0, '127.0.0.1');
     await new Promise<void>((resolve) => server!.once('listening', () => resolve()));
     return `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
 }
@@ -138,7 +138,7 @@ describe('CreateGlobalCorsMiddleware', () => {
         const app = express();
         app.use(CreateGlobalCorsMiddleware({ allowedOrigins: ['*'], allowCredentials: true }));
         app.get('/core', (_req, res) => { res.json({ ok: true }); });
-        server = app.listen(0);
+        server = app.listen(0, '127.0.0.1');
         await new Promise<void>((resolve) => server!.once('listening', () => resolve()));
         const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
         const res = await fetch(`${base}/core`, { headers: { Origin: OTHER_ORIGIN } });
@@ -164,7 +164,7 @@ async function startAppWithGraphQLMount(withFallback: boolean): Promise<string>
         app.use(CreateExtensionOwnedPreflightFallback(ownedRoots));
     }
     app.use('/', cors(), (_req, res) => { res.json({ graphql: true }); });
-    server = app.listen(0);
+    server = app.listen(0, '127.0.0.1');
     await new Promise<void>((resolve) => server!.once('listening', () => resolve()));
     return `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
 }