@memberjunction/server 6.1.0-edge.2 → 6.1.0-edge.4

package/src/__tests__/SessionManager.test.ts

@@ -461,6 +461,61 @@ describe('SessionManager.Heartbeat', () => {
     });
 });
 
+describe('SessionManager.Heartbeat — bounded heartbeatLastWrite (Round 11 memory-leak fix)', () => {
+    // Regression coverage: heartbeatLastWrite used to be a plain, unbounded `Map`. SessionManager
+    // is constructed fresh by every resolver that needs one (AgentSessionResolver,
+    // RealtimeClientSessionResolver, RealtimeBridgeResolver) plus SessionJanitor's own instance, so
+    // each is itself a process-lifetime singleton with its own copy of the map. A session's
+    // heartbeats land through one resolver's instance, but the overwhelmingly common close path —
+    // a crashed tab, a dropped connection, anything that never round-trips an explicit close
+    // mutation — is reconciled by SessionJanitor's sweeps through ITS OWN SessionManager, which
+    // never touches the originating instance's map, so the entry was never deleted. The fix bounds
+    // the map with MJLruCache(maxSize 5_000, ttlMs 4h) so that scenario is capped instead of
+    // growing forever.
+
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    it('forces a fresh write once the 4h TTL elapses, even though CloseSession never ran on this instance', async () => {
+        const session = makeSessionEntity({ ID: 'session-ttl', Status: 'Active' });
+        const { provider } = makeProvider(() => session);
+        const mgr = new SessionManager();
+        const user = makeUser();
+
+        const first = await mgr.Heartbeat('session-ttl', user, provider);
+        expect(first).toBe(true);
+        expect(session.Save).toHaveBeenCalledTimes(1);
+
+        // Still within the coalescing window — no second write.
+        const second = await mgr.Heartbeat('session-ttl', user, provider);
+        expect(second).toBe(true);
+        expect(session.Save).toHaveBeenCalledTimes(1);
+
+        // Advance past the cache's 4h TTL backstop (well beyond the 3s coalescing window too).
+        vi.advanceTimersByTime(4 * 60 * 60 * 1000 + 1);
+
+        const third = await mgr.Heartbeat('session-ttl', user, provider);
+        expect(third).toBe(true);
+        // The TTL-expired entry forces a write again, exactly as a never-before-seen session would —
+        // proving the cache entry does not live forever when nothing on this instance ever calls
+        // CloseSession for it.
+        expect(session.Save).toHaveBeenCalledTimes(2);
+    });
+
+    it('is backed by a bounded MJLruCache, not a plain unbounded Map (structural regression guard)', () => {
+        const mgr = new SessionManager();
+        const internal = (mgr as unknown as { heartbeatLastWrite: { MaxSize: number; Size: number } })
+            .heartbeatLastWrite;
+        expect(internal.MaxSize).toBe(5_000);
+        expect(internal.Size).toBe(0);
+    });
+});
+
 describe('SessionManager.MarkIdle', () => {
     it('transitions Active → Idle', async () => {
         const session = makeSessionEntity({ ID: 'session-1', Status: 'Active' });

package/src/__tests__/UserResolver.currentUser.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { LogError } from '@memberjunction/core';
+import {
+  AssertRoleLoadSucceeded,
+  RequireContextUser,
+  RequireLoadedUser,
+  RequireRoleProvider,
+  UserIdExtraFilter,
+} from '../resolvers/currentUserRoles.js';
+
+vi.mock('@memberjunction/core', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@memberjunction/core')>();
+  return {
+    ...actual,
+    LogError: vi.fn(),
+  };
+});
+
+describe('CurrentUser role-load guards', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('RequireLoadedUser', () => {
+    it('returns the user when ID is present', () => {
+      const user = { ID: 'u-1', Email: 'a@b.com' };
+      expect(RequireLoadedUser(user, 'a@b.com')).toBe(user);
+    });
+
+    it('throws when the email fallback finds no user', () => {
+      expect(() => RequireLoadedUser(null, 'missing@example.com'))
+        .toThrow("CurrentUser: no user found for email 'missing@example.com'");
+      expect(() => RequireLoadedUser({ Email: 'x' }, undefined))
+        .toThrow("CurrentUser: no user found for email ''");
+    });
+  });
+
+  describe('RequireContextUser', () => {
+    it('returns the session user when present', () => {
+      const user = { ID: 'u-1' };
+      expect(RequireContextUser(user)).toBe(user);
+    });
+
+    it('throws when GetUserFromPayload would have handed undefined to RunView', () => {
+      expect(() => RequireContextUser(undefined))
+        .toThrow('CurrentUser: authenticated context user is required to load roles');
+    });
+  });
+
+  describe('RequireRoleProvider', () => {
+    it('throws when no provider is available', () => {
+      expect(() => RequireRoleProvider(null))
+        .toThrow('CurrentUser: no data provider available to load roles');
+    });
+  });
+
+  describe('UserIdExtraFilter', () => {
+    it('wraps a UUID in a UserID equality filter', () => {
+      expect(UserIdExtraFilter('aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'))
+        .toBe("UserID='aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'");
+    });
+
+    it('quote-escapes a value that contains a single quote', () => {
+      expect(UserIdExtraFilter("O'Brien")).toBe("UserID='O''Brien'");
+    });
+  });
+
+  describe('AssertRoleLoadSucceeded', () => {
+    it('is a no-op on Success', () => {
+      expect(() => AssertRoleLoadSucceeded({ Success: true }, 'u-1')).not.toThrow();
+      expect(LogError).not.toHaveBeenCalled();
+    });
+
+    it('logs and throws on failure instead of returning an empty role set', () => {
+      expect(() => AssertRoleLoadSucceeded({ Success: false, ErrorMessage: 'permission denied' }, 'u-1'))
+        .toThrow('CurrentUser: failed to load roles: permission denied');
+      expect(LogError).toHaveBeenCalledWith(
+        'CurrentUser: failed to load roles for user u-1: permission denied',
+      );
+    });
+
+    it('uses a fallback message when ErrorMessage is missing', () => {
+      expect(() => AssertRoleLoadSucceeded({ Success: false }, 'u-1'))
+        .toThrow('CurrentUser: failed to load roles: unknown error');
+    });
+  });
+});

package/src/__tests__/ViewOperationsHandler.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Tests for the REST view-operations layer (rest/ViewOperationsHandler.ts).
+ *
+ * Covers entity resolution, read-permission enforcement BEFORE any query
+ * executes (including the batch fail-fast contract), parameter sanitization
+ * (Fields/MaxRows/StartRow coercion, ResultType defaulting, EntityName
+ * requirement), and the error branches — plus documentation-style assertions
+ * for the case-sensitive entity lookup and the unescaped filter interpolation
+ * in getEntityViews, in the style of multiTenancy.security.test.ts.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// ─── Hoisted mocks ──────────────────────────────────────────────────────────
+const { mockRunViewFn, mockRunViewsFn, mockLogError, mockEntityList } = vi.hoisted(() => ({
+    mockRunViewFn: vi.fn(),
+    mockRunViewsFn: vi.fn(),
+    mockLogError: vi.fn(),
+    mockEntityList: [] as Array<{ Name: string; GetUserPermisions: (u: unknown) => { CanRead: boolean } }>,
+}));
+
+vi.mock('@memberjunction/core', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/core')>();
+    class MockMetadata {
+        public get Entities() {
+            return mockEntityList;
+        }
+    }
+    class MockRunView {
+        public RunView(params: unknown, contextUser?: unknown): Promise<unknown> {
+            return mockRunViewFn(params, contextUser);
+        }
+        public RunViews(params: unknown[], contextUser?: unknown): Promise<unknown> {
+            return mockRunViewsFn(params, contextUser);
+        }
+    }
+    return {
+        ...actual,
+        Metadata: MockMetadata,
+        RunView: MockRunView,
+        LogError: mockLogError,
+    };
+});
+
+import type { RunViewParams, RunViewResult, UserInfo } from '@memberjunction/core';
+import { ViewOperationsHandler } from '../rest/ViewOperationsHandler.js';
+
+// ─── Fixtures ───────────────────────────────────────────────────────────────
+
+function registerEntity(name: string, canRead: boolean): void {
+    mockEntityList.push({ Name: name, GetUserPermisions: () => ({ CanRead: canRead }) });
+}
+
+function makeUser(): UserInfo {
+    return { ID: 'user-1', Name: 'Reader' } as unknown as UserInfo;
+}
+
+const OK_RESULT = { Success: true, Results: [{ ID: '1' }], ErrorMessage: undefined };
+
+beforeEach(() => {
+    vi.clearAllMocks();
+    mockEntityList.length = 0;
+    registerEntity('Customers', true);
+    registerEntity('Restricted Ledger', false);
+    mockRunViewFn.mockResolvedValue(OK_RESULT);
+    mockRunViewsFn.mockResolvedValue([OK_RESULT]);
+});
+
+// ─── runView ────────────────────────────────────────────────────────────────
+
+describe('ViewOperationsHandler.runView', () => {
+    it('executes the view for a readable entity and returns the RunViewResult', async () => {
+        const user = makeUser();
+        const params: RunViewParams = { EntityName: 'Customers' };
+
+        const outcome = await ViewOperationsHandler.runView(params, user);
+
+        expect(outcome.success).toBe(true);
+        expect(outcome.result).toBe(OK_RESULT as unknown as RunViewResult);
+        expect(mockRunViewFn).toHaveBeenCalledWith(params, user);
+    });
+
+    it('fails when the entity does not exist — and never executes the view', async () => {
+        const outcome = await ViewOperationsHandler.runView({ EntityName: 'Ghost' }, makeUser());
+
+        expect(outcome.success).toBe(false);
+        expect(outcome.error).toBe(`Entity 'Ghost' not found`);
+        expect(mockRunViewFn).not.toHaveBeenCalled();
+    });
+
+    it('KNOWN GAP: entity lookup is case-sensitive (Entities.find ===), unlike EntityByName', async () => {
+        // The data-access convention is md.EntityByName (case-insensitive, trimmed).
+        // This handler scans Entities with strict equality, so a client sending
+        // 'customers' gets "not found" even though the entity exists. Pinned so a
+        // migration to EntityByName consciously flips this test.
+        const outcome = await ViewOperationsHandler.runView({ EntityName: 'customers' }, makeUser());
+
+        expect(outcome.success).toBe(false);
+        expect(outcome.error).toBe(`Entity 'customers' not found`);
+    });
+
+    it('denies before executing when the user lacks read permission', async () => {
+        const outcome = await ViewOperationsHandler.runView({ EntityName: 'Restricted Ledger' }, makeUser());
+
+        expect(outcome.success).toBe(false);
+        expect(outcome.error).toBe('User Reader does not have permission to read Restricted Ledger records');
+        expect(mockRunViewFn).not.toHaveBeenCalled();
+    });
+
+    describe('parameter sanitization', () => {
+        it('defaults ResultType to "simple" when unset and preserves an explicit one', async () => {
+            const defaulted: RunViewParams = { EntityName: 'Customers' };
+            await ViewOperationsHandler.runView(defaulted, makeUser());
+            expect((mockRunViewFn.mock.calls[0][0] as RunViewParams).ResultType).toBe('simple');
+
+            const explicit: RunViewParams = { EntityName: 'Customers', ResultType: 'entity_object' };
+            await ViewOperationsHandler.runView(explicit, makeUser());
+            expect((mockRunViewFn.mock.calls[1][0] as RunViewParams).ResultType).toBe('entity_object');
+        });
+
+        it('splits comma-separated Fields strings and coerces numeric strings for MaxRows/StartRow', async () => {
+            // REST clients send query-string-shaped values; the handler normalizes in place
+            const params = {
+                EntityName: 'Customers',
+                Fields: 'ID,Name,Email' as unknown as string[],
+                MaxRows: '50' as unknown as number,
+                StartRow: '10' as unknown as number,
+            } as RunViewParams;
+
+            const outcome = await ViewOperationsHandler.runView(params, makeUser());
+
+            expect(outcome.success).toBe(true);
+            const executed = mockRunViewFn.mock.calls[0][0] as RunViewParams;
+            expect(executed.Fields).toEqual(['ID', 'Name', 'Email']);
+            expect(executed.MaxRows).toBe(50);
+            expect(executed.StartRow).toBe(10);
+        });
+
+        it('rejects a missing EntityName at the lookup step — before any query executes', async () => {
+            // Note: sanitizeRunViewParams' "EntityName is required" branch is unreachable
+            // through the public entry points, because every caller does the metadata
+            // lookup FIRST and `find(e => e.Name === undefined)` misses. The effective
+            // behavior (still a safe failure, different message) is pinned here.
+            const outcome = await ViewOperationsHandler.runView({} as RunViewParams, makeUser());
+
+            expect(outcome.success).toBe(false);
+            expect(outcome.error).toBe(`Entity 'undefined' not found`);
+            expect(mockRunViewFn).not.toHaveBeenCalled();
+        });
+    });
+});
+
+// ─── runViews (batch) ───────────────────────────────────────────────────────
+
+describe('ViewOperationsHandler.runViews', () => {
+    it('validates EVERY entry before executing ANY view (fail-fast, no partial execution)', async () => {
+        const params: RunViewParams[] = [
+            { EntityName: 'Customers' },
+            { EntityName: 'Restricted Ledger' }, // second entry is unauthorized
+        ];
+
+        const outcome = await ViewOperationsHandler.runViews(params, makeUser());
+
+        expect(outcome.success).toBe(false);
+        expect(outcome.error).toBe('User Reader does not have permission to read Restricted Ledger records');
+        expect(mockRunViewsFn).not.toHaveBeenCalled(); // nothing ran — not even the allowed first view
+    });
+
+    it('fails the whole batch when any entity is unknown', async () => {
+        const outcome = await ViewOperationsHandler.runViews(
+            [{ EntityName: 'Customers' }, { EntityName: 'Ghost' }],
+            makeUser(),
+        );
+
+        expect(outcome.success).toBe(false);
+        expect(outcome.error).toBe(`Entity 'Ghost' not found`);
+        expect(mockRunViewsFn).not.toHaveBeenCalled();
+    });
+
+    it('sanitizes each entry and executes the batch through RunViews', async () => {
+        registerEntity('Orders', true);
+        const batchResults = [OK_RESULT, OK_RESULT];
+        mockRunViewsFn.mockResolvedValue(batchResults);
+        const params: RunViewParams[] = [
+            { EntityName: 'Customers' },
+            { EntityName: 'Orders', MaxRows: '5' as unknown as number },
+        ];
+
+        const outcome = await ViewOperationsHandler.runViews(params, makeUser());
+
+        expect(outcome.success).toBe(true);
+        expect(outcome.results).toBe(batchResults as unknown as RunViewResult[]);
+        const executed = mockRunViewsFn.mock.calls[0][0] as RunViewParams[];
+        expect(executed[0].ResultType).toBe('simple');
+        expect(executed[1].MaxRows).toBe(5);
+    });
+});
+
+// ─── listEntities ───────────────────────────────────────────────────────────
+
+describe('ViewOperationsHandler.listEntities', () => {
+    it('returns the RunViewResult for a readable entity', async () => {
+        const result = await ViewOperationsHandler.listEntities({ EntityName: 'Customers' }, makeUser());
+
+        expect(result).toBe(OK_RESULT as unknown as RunViewResult);
+    });
+
+    it('throws (for the router to map) when the entity is unknown', async () => {
+        await expect(ViewOperationsHandler.listEntities({ EntityName: 'Ghost' }, makeUser()))
+            .rejects.toThrow(`Entity 'Ghost' not found`);
+        expect(mockRunViewFn).not.toHaveBeenCalled();
+    });
+
+    it('throws on missing read permission without executing', async () => {
+        await expect(ViewOperationsHandler.listEntities({ EntityName: 'Restricted Ledger' }, makeUser()))
+            .rejects.toThrow('does not have permission to read Restricted Ledger');
+        expect(mockRunViewFn).not.toHaveBeenCalled();
+        expect(mockLogError).toHaveBeenCalled();
+    });
+});
+
+// ─── getEntityViews ─────────────────────────────────────────────────────────
+
+describe('ViewOperationsHandler.getEntityViews', () => {
+    it('queries MJ: User Views filtered to the entity and formats the results', async () => {
+        const createdAt = new Date('2026-01-01T00:00:00Z');
+        mockRunViewFn.mockResolvedValue({
+            Success: true,
+            Results: [{
+                ID: 'v1', Name: 'My View', Description: 'desc', IsShared: true, CreatedAt: createdAt,
+                InternalColumn: 'must not leak',
+            }],
+        });
+
+        const outcome = await ViewOperationsHandler.getEntityViews('Customers', makeUser());
+
+        expect(outcome.success).toBe(true);
+        expect(outcome.views).toEqual([
+            { ID: 'v1', Name: 'My View', Description: 'desc', IsShared: true, CreatedAt: createdAt },
+        ]);
+        const executed = mockRunViewFn.mock.calls[0][0] as RunViewParams;
+        expect(executed.EntityName).toBe('MJ: User Views');
+        expect(executed.ExtraFilter).toBe(`Entity = 'Customers'`);
+    });
+
+    it('fails for unknown entities and unauthorized readers without querying', async () => {
+        const unknown = await ViewOperationsHandler.getEntityViews('Ghost', makeUser());
+        const denied = await ViewOperationsHandler.getEntityViews('Restricted Ledger', makeUser());
+
+        expect(unknown.success).toBe(false);
+        expect(unknown.error).toBe(`Entity 'Ghost' not found`);
+        expect(denied.success).toBe(false);
+        expect(denied.error).toContain('does not have permission');
+        expect(mockRunViewFn).not.toHaveBeenCalled();
+    });
+
+    it('propagates the RunView ErrorMessage when the view query fails', async () => {
+        mockRunViewFn.mockResolvedValue({ Success: false, Results: [], ErrorMessage: 'timeout talking to DB' });
+
+        const outcome = await ViewOperationsHandler.getEntityViews('Customers', makeUser());
+
+        expect(outcome.success).toBe(false);
+        expect(outcome.error).toBe('timeout talking to DB');
+    });
+
+    it('KNOWN GAP: the entity name is interpolated into ExtraFilter without escaping', async () => {
+        // Reachable only for names registered in metadata, so a hostile value requires a
+        // hostile entity name — but an entity legitimately named with an apostrophe
+        // (e.g. "O'Brien Records") already produces a broken/injectable filter today.
+        registerEntity("O'Brien Records", true);
+        mockRunViewFn.mockResolvedValue({ Success: true, Results: [] });
+
+        await ViewOperationsHandler.getEntityViews("O'Brien Records", makeUser());
+
+        const executed = mockRunViewFn.mock.calls[0][0] as RunViewParams;
+        expect(executed.ExtraFilter).toBe(`Entity = 'O'Brien Records'`); // quote NOT doubled
+    });
+});

package/src/__tests__/config-units.test.ts

@@ -0,0 +1,74 @@
+/**
+ * Config-contract regression test for the metadata-cache refresh interval units.
+ *
+ * MJServer's `databaseSettings.metadataCacheRefreshInterval` is configured in
+ * MILLISECONDS (default 180000 = 3 minutes; METADATA_CACHE_REFRESH_INTERVAL env
+ * override). SQLServerProviderConfigData's third constructor parameter is
+ * `checkRefreshIntervalSeconds` — SECONDS. Commit 645c5a5e8 fixed MJServer
+ * handing the raw millisecond value across that seam, which turned the intended
+ * 3-minute refresh cadence into ~50 hours.
+ *
+ * Both provider bootstrap call sites in src/index.ts now route through the pure
+ * `MetadataCacheRefreshIntervalSeconds` helper (src/providerConfigUnits.ts).
+ * This suite pins:
+ *   1. the ms→s conversion itself, and
+ *   2. the handoff contract — the value stored on a REAL
+ *      SQLServerProviderConfigData (deep-imported so the test does not drag in
+ *      the provider package's heavy index graph) is in the unit the parameter
+ *      declares.
+ */
+import { describe, it, expect } from 'vitest';
+import type sql from 'mssql';
+// Deep import: the package index pulls the full provider (+aiengine/queue) graph,
+// which is far too heavy for a unit test. types.js only depends on core + mssql.
+import { SQLServerProviderConfigData } from '@memberjunction/sqlserver-dataprovider/dist/types.js';
+import { MetadataCacheRefreshIntervalSeconds } from '../providerConfigUnits.js';
+
+/** The shipped default for databaseSettings.metadataCacheRefreshInterval (ms) — see src/config.ts. */
+const DEFAULT_INTERVAL_MS = 180000;
+
+describe('MetadataCacheRefreshIntervalSeconds (ms → s conversion)', () => {
+    it('converts the shipped 180000ms default to 180 seconds (3 minutes, not ~50 hours)', () => {
+        const seconds = MetadataCacheRefreshIntervalSeconds(DEFAULT_INTERVAL_MS);
+
+        expect(seconds).toBe(180);
+        // The regression fixed by 645c5a5e8: the raw ms value must never appear on
+        // the seconds side of the seam. 180000 "seconds" is a 50-hour cadence.
+        expect(seconds).not.toBe(DEFAULT_INTERVAL_MS);
+        expect(seconds * 1000).toBe(DEFAULT_INTERVAL_MS); // exact round-trip, no truncation surprise
+    });
+
+    it('preserves 0 (auto-refresh disabled stays disabled)', () => {
+        expect(MetadataCacheRefreshIntervalSeconds(0)).toBe(0);
+    });
+
+    it('converts arbitrary env-override values proportionally', () => {
+        expect(MetadataCacheRefreshIntervalSeconds(60000)).toBe(60);
+        expect(MetadataCacheRefreshIntervalSeconds(1500)).toBe(1.5); // sub-second precision retained
+    });
+});
+
+describe('handoff contract with SQLServerProviderConfigData', () => {
+    // The constructor only stores the pool reference; no connection is opened.
+    const stubPool = {} as unknown as sql.ConnectionPool;
+
+    it('stores the derived value as CheckRefreshIntervalSeconds — the effective value is in SECONDS', () => {
+        const config = new SQLServerProviderConfigData(
+            stubPool,
+            '__mj',
+            MetadataCacheRefreshIntervalSeconds(DEFAULT_INTERVAL_MS),
+        );
+
+        expect(config.CheckRefreshIntervalSeconds).toBe(180);
+        expect(config.CheckRefreshIntervalSeconds).not.toBe(DEFAULT_INTERVAL_MS);
+    });
+
+    it('a disabled (0ms) interval reaches the provider as 0 — matching the provider default', () => {
+        const derived = new SQLServerProviderConfigData(stubPool, '__mj', MetadataCacheRefreshIntervalSeconds(0));
+        const omitted = new SQLServerProviderConfigData(stubPool, '__mj');
+
+        expect(derived.CheckRefreshIntervalSeconds).toBe(0);
+        // The provider's own default is 0 (auto refresh disabled) — the two paths agree.
+        expect(omitted.CheckRefreshIntervalSeconds).toBe(0);
+    });
+});

package/src/__tests__/initializeProviders.refresh.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+/**
+ * Tests for `refreshAuthProviders` — the runtime rebuild of the provider registry.
+ *
+ * The scenario that matters: the factory caches issuer→provider resolutions, so a catalog edit
+ * requires a full clear — but a clear also drops everything the CONFIG path registered
+ * (mj.config.cjs providers, magic-link). A refresh that re-registered only the metadata rows
+ * would silently lock those users out. These tests pin the two-source rebuild order:
+ * clear → config-declared providers → metadata rows layered on top.
+ */
+
+const { registerMock, createProviderMock, clearMock, discoverMock } = vi.hoisted(() => ({
+  registerMock: vi.fn(),
+  createProviderMock: vi.fn(),
+  clearMock: vi.fn(),
+  discoverMock: vi.fn(() => [])
+}));
+
+vi.mock('@memberjunction/auth-providers', () => ({
+  AuthProviderFactory: {
+    Instance: {
+      register: registerMock,
+      clear: clearMock
+    },
+    createProvider: createProviderMock,
+    DiscoverFromEnvironment: discoverMock
+  }
+}));
+
+vi.mock('../config.js', () => ({
+  configInfo: {
+    authProviders: [
+      {
+        name: 'config-okta',
+        type: 'okta',
+        issuer: 'https://config.okta.com',
+        audience: 'api://default',
+        jwksUri: 'https://config.okta.com/keys'
+      }
+    ]
+  }
+}));
+
+vi.mock('@memberjunction/credentials', () => ({
+  CredentialEngine: {
+    Instance: {
+      Config: vi.fn(async () => undefined),
+      getCredential: vi.fn()
+    }
+  }
+}));
+
+vi.mock('@memberjunction/core-entities', () => ({}));
+
+vi.mock('@memberjunction/core', () => {
+  const instances = new Map<unknown, unknown>();
+  return {
+    BaseEngine: class {
+      protected async Load(): Promise<void> {
+        /* no-op: tests inject rows directly */
+      }
+      protected GetConfigData<T>(propertyName: string): T[] {
+        return (this as unknown as Record<string, T[]>)[propertyName] ?? [];
+      }
+      public static getInstance<T>(this: new () => T): T {
+        if (!instances.has(this)) {
+          instances.set(this, new this());
+        }
+        return instances.get(this) as T;
+      }
+    },
+    RegisterForStartup: () => (target: unknown) => target,
+    LogError: vi.fn(),
+    LogStatus: vi.fn(),
+    LogStatusEx: vi.fn()
+  };
+});
+
+import { AuthProviderEngine } from '../auth/AuthProviderEngine.js';
+import { refreshAuthProviders } from '../auth/initializeProviders.js';
+
+/** Minimal stand-in for a generated MJAuthenticationProviderEntity row. */
+function metadataRow(name: string, driverClass: string) {
+  return {
+    Name: name,
+    DriverClass: driverClass,
+    Issuer: null,
+    Audience: null,
+    JWKSUri: null,
+    ClientID: null,
+    Domain: null,
+    Scopes: null,
+    AdditionalConfiguration: null,
+    ClientConfiguration: null,
+    CredentialID: null,
+    Credential: null
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  createProviderMock.mockImplementation((config: unknown) => ({ config }));
+  (AuthProviderEngine.Instance as unknown as { _providers: unknown[] })._providers = [];
+});
+
+describe('refreshAuthProviders', () => {
+  it('re-registers the config-declared providers after clearing, so a refresh cannot lock config-path users out', async () => {
+    await refreshAuthProviders();
+
+    expect(clearMock).toHaveBeenCalledTimes(1);
+    expect(createProviderMock).toHaveBeenCalledWith(expect.objectContaining({ name: 'config-okta' }));
+    expect(registerMock).toHaveBeenCalled();
+    // The config provider must land AFTER the clear, not survive from before it.
+    expect(Math.min(...registerMock.mock.invocationCallOrder)).toBeGreaterThan(clearMock.mock.invocationCallOrder[0]);
+  });
+
+  it('aborts BEFORE touching the registry when reading the catalog is permission-denied', async () => {
+    // GetConfigData throws PermissionConstrainedError when the load was skipped for permission
+    // reasons. That failure must surface while the registry still serves the previous provider
+    // set — throwing after the clear would deregister every metadata IdP until process restart.
+    const providersSpy = vi.spyOn(AuthProviderEngine.Instance, 'Providers', 'get').mockImplementation(() => {
+      throw new Error('PermissionConstrainedError: AuthProviderEngine load skipped');
+    });
+
+    try {
+      await expect(refreshAuthProviders()).rejects.toThrow('PermissionConstrainedError');
+      expect(clearMock).not.toHaveBeenCalled();
+      expect(registerMock).not.toHaveBeenCalled();
+    } finally {
+      providersSpy.mockRestore();
+    }
+  });
+
+  it('layers the metadata rows on top of the config-declared providers, in that order', async () => {
+    (AuthProviderEngine.Instance as unknown as { _providers: unknown[] })._providers = [metadataRow('Catalog WorkOS', 'workos')];
+
+    const count = await refreshAuthProviders();
+
+    expect(count).toBe(1);
+    expect(registerMock).toHaveBeenCalledTimes(2);
+    const registeredNames = createProviderMock.mock.calls.map((call) => (call[0] as { name: string }).name);
+    // Config first, metadata second — a name collision must resolve to the metadata row.
+    expect(registeredNames).toEqual(['config-okta', 'Catalog WorkOS']);
+  });
+});

package/src/__tests__/mjapi-bootstrap.test.ts

@@ -15,12 +15,6 @@ vi.mock('@memberjunction/server-bootstrap/mj-class-registrations', () => ({}));
 vi.mock('../generated/class-registrations-manifest.js', () => ({}));
 
 describe('MJAPI', () => {
-  it('should have a valid package structure', () => {
-    // This test validates that the mock setup works correctly,
-    // confirming that the imports in index.ts reference real modules
-    expect(true).toBe(true);
-  });
-
   it('should use createMJServer for bootstrapping', async () => {
     const { createMJServer } = await import('@memberjunction/server-bootstrap');
     expect(createMJServer).toBeDefined();