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

package/src/__tests__/realtimeSessions/sessionAccess.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
-import { AuthorizeSessionAccess, AuthorizeConversationTurn, AuthorizeAnonymousRoomSessions, LoadSessionForAccess, LoadConversationScope } from '../../realtimeSessions/sessionAccess.js';
+import type { MJAIAgentSessionEntity } from '@memberjunction/core-entities';
+import { AuthorizeSessionAccess, AuthorizeConversationTurn, AuthorizeAnonymousRoomSessions, LoadSessionForAccess, LoadSessionConversationScope, LoadConversationScope, AuthorizeLoadedSession } from '../../realtimeSessions/sessionAccess.js';
 
 const OWNER = 'AAAAAAAA-0000-4000-8000-000000000001';
 const OTHER = 'AAAAAAAA-0000-4000-8000-000000000002';
@@ -190,6 +191,25 @@ describe('LoadSessionForAccess', () => {
     });
 });
 
+describe('LoadSessionConversationScope', () => {
+    const sessionWithConversation = { ID: SESSION_ID, UserID: OWNER, ConversationID: CONVERSATION_ID } as unknown as MJAIAgentSessionEntity;
+
+    it('reads the conversation for an unscoped named user too, so its result is the conversation as that user sees it', async () => {
+        const provider = fakeProvider({ conversation: { ExternalID: 'scope-1' } });
+        const scope = await LoadSessionConversationScope(sessionWithConversation, USER, provider);
+        expect(scope).toEqual({ ExternalID: 'scope-1', Readable: true });
+        expect(provider.GetEntityObject).toHaveBeenCalledTimes(1);
+    });
+
+    it('reads the conversation when the caller carries a scope identity', async () => {
+        const scopedUser = { ID: OWNER, MagicLinkScope: { ResourceID: 'scope-1' } } as unknown as UserInfo;
+        const provider = fakeProvider({ conversation: { ExternalID: 'scope-1' } });
+        const scope = await LoadSessionConversationScope(sessionWithConversation, scopedUser, provider);
+        expect(scope).toEqual({ ExternalID: 'scope-1', Readable: true });
+        expect(provider.GetEntityObject).toHaveBeenCalledTimes(1);
+    });
+});
+
 describe('LoadConversationScope (a conversation addressed directly, e.g. by a text agent turn)', () => {
     it('reports the owner and scope id of a readable conversation', async () => {
         const scope = await LoadConversationScope(CONVERSATION_ID, USER, fakeProvider({ conversation: { UserID: OWNER, ExternalID: 'scope-1' } }));
@@ -266,3 +286,61 @@ describe('AuthorizeAnonymousRoomSessions (who of the anonymous visitors owns a L
     });
 });
 
+
+describe('AuthorizeLoadedSession', () => {
+    const principals: Array<[string, UserInfo]> = [
+        ['named owner, no scope', { ID: OWNER } as UserInfo],
+        ['named owner, scope-1', { ID: OWNER, MagicLinkScope: { ResourceID: 'scope-1' } } as unknown as UserInfo],
+        ['named owner, scope-2', { ID: OWNER, MagicLinkScope: { ResourceID: 'scope-2' } } as unknown as UserInfo],
+        ['anonymous, scope-1', { ID: OWNER, IsMagicLinkAnonymous: true, AnonymousVisitorID: 'scope-1', MagicLinkScope: { ResourceID: 'scope-1' } } as unknown as UserInfo],
+        ['anonymous, scope-2', { ID: OWNER, IsMagicLinkAnonymous: true, AnonymousVisitorID: 'scope-2', MagicLinkScope: { ResourceID: 'scope-2' } } as unknown as UserInfo],
+        ['anonymous, visitor id only', { ID: OWNER, IsMagicLinkAnonymous: true, AnonymousVisitorID: 'scope-1' } as unknown as UserInfo],
+        ['anonymous, no scope', { ID: OWNER, IsMagicLinkAnonymous: true } as unknown as UserInfo],
+        ['named non-owner', { ID: OTHER } as UserInfo],
+    ];
+    const conversations: Array<[string, { conversationId: string | null; rows: Parameters<typeof fakeProvider>[0] }]> = [
+        ['no conversation', { conversationId: null, rows: {} }],
+        ['missing or refused', { conversationId: CONVERSATION_ID, rows: { conversation: null } }],
+        ['read fails', { conversationId: CONVERSATION_ID, rows: { conversation: {}, conversationThrows: true } }],
+        ['unstamped', { conversationId: CONVERSATION_ID, rows: { conversation: { ExternalID: null } } }],
+        ['stamped scope-1', { conversationId: CONVERSATION_ID, rows: { conversation: { ExternalID: 'scope-1' } } }],
+        ['stamped scope-2', { conversationId: CONVERSATION_ID, rows: { conversation: { ExternalID: 'scope-2' } } }],
+    ];
+
+    for (const [principalName, principal] of principals) {
+        for (const [conversationName, { conversationId, rows }] of conversations) {
+            it(`decides as if it always read the conversation: ${principalName} × ${conversationName}`, async () => {
+                const session = { ID: SESSION_ID, UserID: OWNER, ConversationID: conversationId } as unknown as MJAIAgentSessionEntity;
+                const scope = await LoadConversationScope(conversationId, principal, fakeProvider(rows));
+                const alwaysRead = AuthorizeSessionAccess(
+                    { SessionUserID: session.UserID, ConversationExternalID: scope.ExternalID, ConversationReadable: scope.Readable },
+                    principal,
+                );
+                expect(await AuthorizeLoadedSession(session, principal, fakeProvider(rows))).toEqual(alwaysRead);
+            });
+        }
+    }
+
+    const sessionWithConversation = { ID: SESSION_ID, UserID: OWNER, ConversationID: CONVERSATION_ID } as unknown as MJAIAgentSessionEntity;
+    const conversationReads = (provider: IMetadataProvider) =>
+        vi.mocked(provider.GetEntityObject).mock.calls.filter(([name]) => name === 'MJ: Conversations').length;
+
+    it('does not read the conversation for a named owner without a scope, the usual signed-in caller', async () => {
+        const provider = fakeProvider({ conversation: { ExternalID: 'scope-1' } });
+        expect(await AuthorizeLoadedSession(sessionWithConversation, USER, provider)).toEqual({ Allowed: true });
+        expect(conversationReads(provider)).toBe(0);
+    });
+
+    it('does not read the conversation for a caller who does not own the session', async () => {
+        const provider = fakeProvider({ conversation: { ExternalID: 'scope-1' } });
+        expect(await AuthorizeLoadedSession(sessionWithConversation, { ID: OTHER } as UserInfo, provider)).toEqual({ Allowed: false, Reason: 'not_owner' });
+        expect(conversationReads(provider)).toBe(0);
+    });
+
+    it('reads the conversation once for a caller with a scope identity', async () => {
+        const provider = fakeProvider({ conversation: { ExternalID: 'scope-1' } });
+        const guest = { ID: OWNER, IsMagicLinkAnonymous: true, AnonymousVisitorID: 'scope-1', MagicLinkScope: { ResourceID: 'scope-1' } } as unknown as UserInfo;
+        expect(await AuthorizeLoadedSession(sessionWithConversation, guest, provider)).toEqual({ Allowed: true });
+        expect(conversationReads(provider)).toBe(1);
+    });
+});

package/src/__tests__/requestOrigin.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import { NormalizeOrigin, ReadRequestOrigin } from '../requestOrigin.js';
+import { IsOriginAllowed, ParseAllowedOrigins } from '../realtimeWidget/widgetCore.js';
+
+describe('NormalizeOrigin', () => {
+  it('trims, lowercases and strips trailing slashes', () => {
+    expect(NormalizeOrigin('  HTTPS://App.Example.COM//  ')).toBe('https://app.example.com');
+  });
+
+  it('keeps an explicit port, default or not', () => {
+    expect(NormalizeOrigin('https://a.com:443')).toBe('https://a.com:443');
+    expect(NormalizeOrigin('http://localhost:4200/')).toBe('http://localhost:4200');
+  });
+
+  it('returns a value made only of slashes as empty', () => {
+    expect(NormalizeOrigin('///')).toBe('');
+  });
+
+  it('handles a long run of slashes that is not at the end in linear time', () => {
+    const hostile = 'https://a.com' + '/'.repeat(100_000) + 'x';
+    const started = Date.now();
+    expect(NormalizeOrigin(hostile)).toBe(hostile);
+    expect(ReadRequestOrigin(hostile)).toBeUndefined();
+    expect(Date.now() - started).toBeLessThan(1000);
+  });
+});
+
+describe('ReadRequestOrigin', () => {
+  describe('origin present', () => {
+    it('returns the normalized origin', () => {
+      expect(ReadRequestOrigin('https://Embed.Example.com')).toBe('https://embed.example.com');
+    });
+
+    it('strips a trailing slash', () => {
+      expect(ReadRequestOrigin('https://embed.example.com/')).toBe('https://embed.example.com');
+    });
+
+    it('accepts an IPv6 host with a port', () => {
+      expect(ReadRequestOrigin('http://[::1]:3000')).toBe('http://[::1]:3000');
+    });
+  });
+
+  describe('origin absent', () => {
+    it('returns undefined for a missing header', () => {
+      expect(ReadRequestOrigin(undefined)).toBeUndefined();
+    });
+
+    it('returns undefined for a blank header', () => {
+      expect(ReadRequestOrigin('')).toBeUndefined();
+      expect(ReadRequestOrigin('   ')).toBeUndefined();
+    });
+
+    it('returns undefined for a repeated header', () => {
+      expect(ReadRequestOrigin(['https://a.com', 'https://b.com'])).toBeUndefined();
+    });
+  });
+
+  describe('origin malformed', () => {
+    it('returns undefined for the opaque "null" origin', () => {
+      expect(ReadRequestOrigin('null')).toBeUndefined();
+    });
+
+    it('returns undefined for a value that is not a URL', () => {
+      expect(ReadRequestOrigin('not an origin')).toBeUndefined();
+      expect(ReadRequestOrigin('https://')).toBeUndefined();
+    });
+
+    it('returns undefined for a non-http(s) scheme', () => {
+      expect(ReadRequestOrigin('file://')).toBeUndefined();
+      expect(ReadRequestOrigin('chrome-extension://abcdef')).toBeUndefined();
+    });
+
+    it('returns undefined when a path, query, fragment or credentials are present', () => {
+      expect(ReadRequestOrigin('https://a.com/path')).toBeUndefined();
+      expect(ReadRequestOrigin('https://a.com?x=1')).toBeUndefined();
+      expect(ReadRequestOrigin('https://a.com#frag')).toBeUndefined();
+      expect(ReadRequestOrigin('https://user:pw@a.com')).toBeUndefined();
+    });
+  });
+
+  describe('default ports', () => {
+    it('keeps an explicit default port as sent', () => {
+      expect(ReadRequestOrigin('https://a.com:443')).toBe('https://a.com:443');
+      expect(ReadRequestOrigin('http://a.com:80')).toBe('http://a.com:80');
+    });
+
+    it('keeps a non-default port', () => {
+      expect(ReadRequestOrigin('https://a.com:8443')).toBe('https://a.com:8443');
+    });
+
+    it('does not add a default port when none was sent', () => {
+      expect(ReadRequestOrigin('https://a.com')).toBe('https://a.com');
+    });
+  });
+
+  describe('agreement with the widget allowlist', () => {
+    it('a request origin matches the allowlist entry it was normalized against', () => {
+      const allowed = ParseAllowedOrigins('["https://Embed.Example.com/"]');
+      const origin = ReadRequestOrigin('https://embed.example.com');
+      expect(origin).toBe(allowed[0]);
+      expect(IsOriginAllowed(origin, allowed)).toBe(true);
+    });
+  });
+});

package/src/__tests__/securityHardeningPr6034.test.ts

@@ -0,0 +1,120 @@
+import 'reflect-metadata';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type express from 'express';
+
+const logStatusExCalls: Array<{ message: string; verboseOnly?: boolean }> = [];
+const runViewSpy = vi.fn();
+
+vi.mock('@memberjunction/core', async () => {
+    const actual = await vi.importActual<typeof import('@memberjunction/core')>('@memberjunction/core');
+    return {
+        ...actual,
+        LogStatusEx: vi.fn((entry: { message: string; verboseOnly?: boolean }) => {
+            logStatusExCalls.push(entry);
+        }),
+        RunView: class MockRunView {
+            public RunView = runViewSpy;
+        },
+    };
+});
+
+import {
+    DEFAULT_REST_API_OPTIONS,
+    REST_API_BASE_PATH,
+    SetupRESTEndpoints,
+} from '../rest/setupRESTEndpoints.js';
+import { OAuthCallbackHandler } from '../rest/OAuthCallbackHandler.js';
+import type { UserInfo } from '@memberjunction/core';
+
+function createSpyExpressApp(): { app: express.Application; useCalls: express.RequestHandler[][] } {
+    const useCalls: express.RequestHandler[][] = [];
+    const partialApp = {
+        use: vi.fn((...args: express.RequestHandler[]) => {
+            useCalls.push(args);
+            return partialApp as express.Application;
+        }),
+    };
+    return { app: partialApp as express.Application, useCalls };
+}
+
+describe('PR #6034 security hardening in MJServer', () => {
+    beforeEach(() => {
+        logStatusExCalls.length = 0;
+        runViewSpy.mockReset();
+    });
+
+    describe('SetupRESTEndpoints fail-closed default & auth warning', () => {
+        it('defaults DEFAULT_REST_API_OPTIONS.enabled to false and mounts nothing when called without options', () => {
+            expect(DEFAULT_REST_API_OPTIONS.enabled).toBe(false);
+
+            const { app, useCalls } = createSpyExpressApp();
+            SetupRESTEndpoints(app);
+
+            expect(useCalls).toHaveLength(0);
+        });
+
+        it('logs a non-verbose warning when enabled without a route-level authMiddleware', () => {
+            const { app, useCalls } = createSpyExpressApp();
+            SetupRESTEndpoints(app, { enabled: true });
+
+            expect(useCalls).toHaveLength(1);
+            expect(useCalls[0][0]).toBe(REST_API_BASE_PATH);
+            const warning = logStatusExCalls.find((c) =>
+                c.message.includes('WITHOUT a route-level auth middleware'),
+            );
+            expect(warning).toBeDefined();
+            expect(warning?.verboseOnly).toBeUndefined();
+        });
+
+        it('mounts authMiddleware and omits the unauthenticated warning when authMiddleware is supplied', () => {
+            const { app, useCalls } = createSpyExpressApp();
+            const authMw: express.RequestHandler = (_req, _res, next) => next();
+
+            SetupRESTEndpoints(app, { enabled: true }, authMw);
+
+            expect(useCalls).toHaveLength(1);
+            expect(useCalls[0]).toContain(authMw);
+            const warning = logStatusExCalls.find((c) =>
+                c.message.includes('WITHOUT a route-level auth middleware'),
+            );
+            expect(warning).toBeUndefined();
+        });
+    });
+
+    describe('OAuthCallbackHandler UUID validation on ExtraFilter IDs', () => {
+        it('refuses SQL injection connectionId before executing RunView', async () => {
+            const handler = new OAuthCallbackHandler({ baseUrl: 'https://api.example.com' });
+            const fakeUser = { ID: '00000000-0000-0000-0000-000000000001' } as UserInfo;
+
+            const loader = Reflect.get(handler, 'loadConnectionConfig') as (
+                connectionId: string,
+                contextUser: UserInfo,
+            ) => Promise<Record<string, string> | null>;
+
+            const injectedResult = await loader.call(handler, "' OR '1'='1", fakeUser);
+            expect(injectedResult).toBeNull();
+            expect(runViewSpy).not.toHaveBeenCalled();
+        });
+
+        it('refuses non-UUID MCPServerID returned from connection lookup before querying servers', async () => {
+            runViewSpy.mockResolvedValueOnce({
+                Success: true,
+                Results: [{ MCPServerID: "1234' UNION SELECT * FROM __mj.vwUsers --" }],
+            });
+
+            const handler = new OAuthCallbackHandler({ baseUrl: 'https://api.example.com' });
+            const fakeUser = { ID: '00000000-0000-0000-0000-000000000001' } as UserInfo;
+            const validConnId = '11111111-2222-3333-4444-555555555555';
+
+            const loader = Reflect.get(handler, 'loadConnectionConfig') as (
+                connectionId: string,
+                contextUser: UserInfo,
+            ) => Promise<Record<string, string> | null>;
+
+            const result = await loader.call(handler, validConnId, fakeUser);
+            expect(result).toBeNull();
+            // First query ran with validated connectionId; second query was blocked before executing
+            expect(runViewSpy).toHaveBeenCalledTimes(1);
+        });
+    });
+});

package/src/__tests__/sessionDeadline.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { ExpiryCloseReason, ParseSessionDeadlineMs, VerifyTimeLimitClaim } from '../agentSessions/sessionDeadline.js';
+
+const T = Date.parse('2026-10-29T12:00:00Z');
+const MIN = 60_000;
+const row = (lastActive: number | null, deadline?: number): { LastActiveAt: Date | string | null; Config_: string } => ({
+  LastActiveAt: lastActive === null ? null : new Date(lastActive),
+  Config_: deadline === undefined ? '{}' : JSON.stringify({ maxSessionDeadlineIso: new Date(deadline).toISOString() }),
+});
+
+describe('ExpiryCloseReason', () => {
+  it('deadline passed, recently active → TimeLimit', () => expect(ExpiryCloseReason(row(T - MIN, T - MIN), T, 15 * MIN)).toBe('TimeLimit'));
+  it('idle past threshold, no deadline → Idle', () => expect(ExpiryCloseReason(row(T - 16 * MIN), T, 15 * MIN)).toBe('Idle'));
+  it('both passed, idle moment earlier → Idle', () => expect(ExpiryCloseReason(row(T - 20 * MIN, T - 2 * MIN), T, 15 * MIN)).toBe('Idle'));
+  it('both passed, deadline moment earlier → TimeLimit', () => expect(ExpiryCloseReason(row(T - 16 * MIN, T - 5 * MIN), T, 15 * MIN)).toBe('TimeLimit'));
+  it('same instant → TimeLimit', () => expect(ExpiryCloseReason(row(T - 15 * MIN, T), T, 15 * MIN)).toBe('TimeLimit'));
+  it('nothing passed → null', () => expect(ExpiryCloseReason(row(T - MIN, T + MIN), T, 15 * MIN)).toBeNull());
+  it('a row without LastActiveAt is never Idle', () => {
+    expect(ExpiryCloseReason(row(null), T, 15 * MIN)).toBeNull();
+    expect(ExpiryCloseReason(row(null, T - MIN), T, 15 * MIN)).toBe('TimeLimit');
+  });
+  it('nowMs exactly at the deadline → TimeLimit', () => expect(ExpiryCloseReason(row(T - MIN, T), T, 15 * MIN)).toBe('TimeLimit'));
+  it('a string LastActiveAt past the threshold → Idle', () => {
+    const r = { ...row(null), LastActiveAt: new Date(T - 16 * MIN).toISOString() };
+    expect(ExpiryCloseReason(r, T, 15 * MIN)).toBe('Idle');
+  });
+  it('an invalid LastActiveAt string is never Idle, TimeLimit still works', () => {
+    expect(ExpiryCloseReason({ ...row(null), LastActiveAt: 'garbage' }, T, 15 * MIN)).toBeNull();
+    expect(ExpiryCloseReason({ ...row(null, T - MIN), LastActiveAt: 'garbage' }, T, 15 * MIN)).toBe('TimeLimit');
+  });
+  it('a non-finite closeThresholdMs is never Idle', () => expect(ExpiryCloseReason(row(T - 99 * MIN), T, Number.NaN)).toBeNull());
+});
+
+describe('ParseSessionDeadlineMs', () => {
+  it('reads an ISO deadline', () => expect(ParseSessionDeadlineMs(JSON.stringify({ maxSessionDeadlineIso: '2026-10-29T12:00:00Z' }))).toBe(T));
+  it('treats a malformed deadline as absent', () => {
+    expect(ParseSessionDeadlineMs(JSON.stringify({ maxSessionDeadlineIso: 'soon' }))).toBeNull();
+    expect(ParseSessionDeadlineMs(JSON.stringify({ maxSessionDeadlineIso: 42 }))).toBeNull();
+    expect(ParseSessionDeadlineMs('not json')).toBeNull();
+    expect(ParseSessionDeadlineMs(null)).toBeNull();
+  });
+});
+
+describe('VerifyTimeLimitClaim', () => {
+  it('deadline passed → TimeLimit', () => expect(VerifyTimeLimitClaim(row(T - MIN, T - MIN), T)).toBe('TimeLimit'));
+  it('50 s ahead (inside the skew) → TimeLimit', () => expect(VerifyTimeLimitClaim(row(T - MIN, T + 50_000), T)).toBe('TimeLimit'));
+  it('10 min ahead → Explicit', () => expect(VerifyTimeLimitClaim(row(T - MIN, T + 10 * MIN), T)).toBe('Explicit'));
+  it('no stored deadline → Explicit', () => expect(VerifyTimeLimitClaim(row(T - MIN), T)).toBe('Explicit'));
+  it('Config_ null → Explicit', () => expect(VerifyTimeLimitClaim({ LastActiveAt: new Date(T), Config_: null }, T)).toBe('Explicit'));
+  it('a long-idle session is never promoted to TimeLimit by idleness', () => expect(VerifyTimeLimitClaim(row(T - 999 * MIN), T)).toBe('Explicit'));
+});

package/src/__tests__/sharedCache.test.ts

@@ -80,6 +80,17 @@ describe('shared cache event routing', () => {
         expect(publish).toHaveBeenCalledWith('CACHE_INVALIDATION', expect.objectContaining({ entityName: 'MJ: AI Models', action: 'set', primaryKeyValues: null }));
     });
 
+    it('dispatches a RunView row_delta to LocalCacheManager while normalizing browser CACHE_INVALIDATION action to set', () => {
+        const deltaEvt = event({
+            CacheKey: 'MJ: AI Models|_|_|-1|0|_|_|imr:1',
+            Action: 'row_delta',
+            Data: JSON.stringify({ primaryKeyFields: ['ID'], upsertedRows: [{ ID: '1' }], deletedPrimaryKeys: [], rowCount: 1, maxUpdatedAt: '' }),
+        });
+        RouteSharedCacheEvent(deltaEvt, provider(false));
+        expect(dispatch).toHaveBeenCalledWith(deltaEvt);
+        expect(publish).toHaveBeenCalledWith('CACHE_INVALIDATION', expect.objectContaining({ entityName: 'MJ: AI Models', action: 'set', primaryKeyValues: null }));
+    });
+
     it('does not relay other categories or category clears to browsers', () => {
         RouteSharedCacheEvent(event({ Category: 'default', CacheKey: '___MJCore_Metadata_AllMetadata' }), provider(false));
         RouteSharedCacheEvent(event({ Category: 'DatasetCache', CacheKey: 'ds' }), provider(false));

package/src/__tests__/unifiedAuth.test.ts

@@ -8,7 +8,7 @@
  * module (context.ts), vi.mock cannot intercept the intra-module call.
  * Instead we mock the LOWER-LEVEL dependencies that `getUserPayload` calls.
  */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 
 // ─── Hoisted mocks (available inside vi.mock factories) ─────────────────────
 const {
@@ -102,6 +102,7 @@ vi.mock('@memberjunction/api-keys', () => ({
 }));
 
 import { CreateUnifiedAuthMiddleware } from '../context.js';
+import { userEmailMap } from '../config.js';
 import type { Request, Response, NextFunction } from 'express';
 import type { DataSourceInfo } from '../types.js';
 
@@ -136,6 +137,8 @@ function makeMockRes(): Response & { _status: number; _json: Record<string, unkn
 }
 
 const mockDataSources: DataSourceInfo[] = [];
+/** The mocked config's map object; tests add entries and the afterEach clears them. */
+const mockedUserEmailMap = userEmailMap as Record<string, string>;
 const MOCK_POOL = {} as unknown as import('mssql').ConnectionPool;
 
 const mockUserRecord = {
@@ -464,3 +467,72 @@ describe('createUnifiedAuthMiddleware', () => {
     });
   });
 });
+
+// ─── Login identity reporting ───────────────────────────────────────────────
+// The session-audit block runs once per issued token (deduped on iss/sub/iat), so each test
+// presents a token with its own `iat`.
+
+describe('login identity reporting', () => {
+  let middleware: ReturnType<typeof CreateUnifiedAuthMiddleware>;
+  let iat = 1_700_000_000;
+
+  function presentToken(email: string): void {
+    iat += 1;
+    mockJwtDecode.mockReturnValue({
+      iss: 'https://test-issuer.com',
+      sub: 'user-1',
+      iat,
+      exp: Math.floor(Date.now() / 1000) + 3600,
+    });
+    mockExtractUserInfo.mockReturnValue({ email, preferredUsername: email });
+  }
+
+  async function authenticate(): Promise<void> {
+    const req = makeMockReq({ headers: { authorization: `Bearer token-${iat}` } });
+    await middleware(req, makeMockRes(), vi.fn());
+  }
+
+  function warnings(spy: ReturnType<typeof vi.spyOn>): string[] {
+    return spy.mock.calls.map((call) => String(call[0]));
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    setupSuccessfulAuth();
+    middleware = CreateUnifiedAuthMiddleware(mockDataSources);
+  });
+
+  afterEach(() => {
+    for (const key of Object.keys(mockedUserEmailMap)) {
+      delete mockedUserEmailMap[key];
+    }
+  });
+
+  it('logs nothing when the token identity and the user record agree', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    presentToken('test@example.com');
+    await authenticate();
+    expect(warnings(warn).filter((w) => w.startsWith('[Auth]'))).toEqual([]);
+    warn.mockRestore();
+  });
+
+  it('looks the user up by the mapped email and logs the remap', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    mockedUserEmailMap['other@example.org'] = 'test@example.com';
+    presentToken('other@example.org');
+    await authenticate();
+    expect(mockVerifyUserRecord.mock.calls[0][0]).toBe('test@example.com');
+    expect(warnings(warn)).toContainEqual(expect.stringContaining("USER_EMAIL_MAP remapped login 'other@example.org' to 'test@example.com'"));
+    warn.mockRestore();
+  });
+
+  it('logs a login that resolved to a record with a different email', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    presentToken('someone-else@example.org');
+    await authenticate();
+    expect(warnings(warn)).toContainEqual(
+      expect.stringContaining("Login identity 'someone-else@example.org' resolved to user user-1 with a different email (test@example.com)"),
+    );
+    warn.mockRestore();
+  });
+});

package/src/agentSessions/BridgeHostInstance.ts

@@ -1,6 +1,7 @@
-import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { IMetadataProvider, LogError, UserInfo } from '@memberjunction/core';
 import { AIBridgeEngine } from '@memberjunction/ai-bridge-server';
 import { GetCurrentHostInstance } from './HostInstance.js';
+import { DEFAULT_BRIDGE_RECONCILER_SETTINGS, type BridgeReconcilerSettings } from '../backgroundSweepConfigUnits.js';
 
 /**
  * Gives the realtime bridge engine (`AIBridgeEngine`) this MJAPI instance's identity, the one its agent-session rows
@@ -17,8 +18,11 @@ export function BindBridgeEngineHostInstance(): void {
 }
 
 /**
- * Starts the realtime bridge engine's orphan reconcile: now, then every 10 minutes, it closes the bridges an earlier
- * boot of this instance left `Connecting` or `Connected` (reason `Janitor`) and finalizes their co-agent runs.
+ * Starts the realtime bridge engine's orphan reconcile: now, then every `settings.sweepIntervalMs` (10 minutes by
+ * default), it closes the bridges an earlier boot of this instance left `Connecting` or `Connected` (reason `Janitor`)
+ * and finalizes their co-agent runs. With `settings.enabled` false it reconciles once now and schedules no repeat, so an
+ * idle server sends no periodic queries for it (`agentSessions.bridgeReconciler`; see the Serverless Database
+ * Auto-Pause guide).
  *
  * `Serve` calls it once the server listens on its port, where it starts the session janitor. Holding the port is what
  * makes another boot of this instance a process that has ended; before that, an MJAPI started on a port another MJAPI
@@ -26,7 +30,18 @@ export function BindBridgeEngineHostInstance(): void {
  *
  * @param provider The server's metadata provider, for the reads and writes.
  * @param systemUser The user the writes run as.
+ * @param settings Whether to repeat the reconcile, and how often. Defaults to the shipped settings.
  */
-export function StartBridgeOrphanReconciliation(provider: IMetadataProvider, systemUser: UserInfo): void {
-    AIBridgeEngine.Instance.StartOrphanReconciliation(systemUser, provider);
+export function StartBridgeOrphanReconciliation(
+    provider: IMetadataProvider,
+    systemUser: UserInfo,
+    settings: BridgeReconcilerSettings = DEFAULT_BRIDGE_RECONCILER_SETTINGS,
+): void {
+    if (settings.enabled) {
+        AIBridgeEngine.Instance.StartOrphanReconciliation(systemUser, provider, settings.sweepIntervalMs);
+        return;
+    }
+    void AIBridgeEngine.Instance.ReconcileOrphans(systemUser, provider).catch((err) =>
+        LogError(`[AIBridgeEngine] orphan reconciliation failed: ${err instanceof Error ? err.message : String(err)}`),
+    );
 }

package/src/agentSessions/HandoffOfferExpiry.ts

@@ -0,0 +1,18 @@
+import { HandoffOfferRegistry } from '@memberjunction/livekit-room-server';
+import type { HandoffOfferSweepSettings } from '../backgroundSweepConfigUnits.js';
+
+/**
+ * Applies `agentSessions.handoffOfferExpiry` to the process-wide handoff offer registry. The registry
+ * starts its expiry sweep (a read of `MJ: Interaction Offers` every 15 seconds) as soon as it loads, on
+ * every MJAPI whatever its role; this either stops that sweep, so an idle server sends no periodic
+ * query for it, or restarts it on the configured interval. Overdue offers still read as expired when
+ * the sweep is off. See the Serverless Database Auto-Pause guide.
+ */
+export function ApplyHandoffOfferExpirySettings(settings: HandoffOfferSweepSettings): void {
+    const registry = HandoffOfferRegistry.Instance;
+    if (settings.enabled) {
+        registry.StartPeriodicSweep(settings.sweepIntervalMs);
+    } else {
+        registry.StopPeriodicSweep();
+    }
+}

package/src/agentSessions/ReturningVisitorRecap.ts

@@ -146,6 +146,7 @@ async function recapAlreadyExists(conversationId: string, contextUser: UserInfo)
       ExtraFilter: `SourceConversationID = '${conversationId}' AND IsAutoGenerated = 1 AND Type = 'Context'`,
       Fields: ['ID'],
       MaxRows: 1,
+      SkipTotalRowCount: true,
       ResultType: 'simple',
     },
     contextUser,