@memberjunction/server 6.2.0-edge.3 → 6.2.0-edge.4

package/src/__tests__/newUsers.test.ts

@@ -30,6 +30,8 @@ const {
     mockBeginTransaction,
     mockCommitTransaction,
     mockRollbackTransaction,
+    mockGlobalProviderCalls,
+    mockCreateIsolatedProvider,
     mockGetDefaultApplicationsForNewUser,
     mockRolesArray,
     mockApplicationsArray,
@@ -69,6 +71,10 @@ const {
         mockBeginTransaction: vi.fn(),
         mockCommitTransaction: vi.fn(),
         mockRollbackTransaction: vi.fn(),
+        // Every call new-user creation makes on the SHARED Metadata.Provider. Must stay empty: a
+        // transaction there nests into every concurrent request's (see CreateIsolatedProvider).
+        mockGlobalProviderCalls: [] as string[],
+        mockCreateIsolatedProvider: vi.fn(),
         mockGetDefaultApplicationsForNewUser: vi.fn(),
         mockRolesArray: [] as Array<{ ID: string; Name: string }>,
         mockApplicationsArray: [] as Array<{ ID: string; Name: string }>,
@@ -79,6 +85,9 @@ const {
 
 vi.mock('../config.js', () => ({ configInfo: mockConfig }));
 
+// The provider new-user creation must use: its own instance, so its transaction is its own.
+vi.mock('../isolatedProvider.js', () => ({ CreateIsolatedProvider: mockCreateIsolatedProvider }));
+
 vi.mock('@memberjunction/generic-database-provider', () => {
     const instance = {
         get Users() {
@@ -89,6 +98,18 @@ vi.mock('@memberjunction/generic-database-provider', () => {
         },
         Refresh: mockRefresh,
         GetSystemUser: vi.fn(),
+        /**
+         * The real cache falls back to a database read on a miss. The stub answers from
+         * the same array `Users` exposes, so these tests still describe the cache's behaviour.
+         */
+        FindUser: vi.fn(async ({ Email }: { Email?: string }) =>
+            mockCacheUsers.find((u: UserInfo) => {
+                if (!u.Email || u.Email.trim() === '') {
+                    console.error(`SYSTEM METADATA ISSUE: User ${u.ID} has no email address`);
+                    return false;
+                }
+                return u.Email.toLowerCase().trim() === (Email ?? '').toLowerCase().trim();
+            })),
     };
     return {
         UserCache: class MockUserCache {
@@ -104,10 +125,11 @@ vi.mock('@memberjunction/generic-database-provider', () => {
 
 vi.mock('@memberjunction/core', async (importOriginal) => {
     const actual = await importOriginal<typeof import('@memberjunction/core')>();
-    const provider = {
-        BeginTransaction: mockBeginTransaction,
-        CommitTransaction: mockCommitTransaction,
-        RollbackTransaction: mockRollbackTransaction,
+    // The shared global provider: records any use instead of doing anything.
+    const globalProvider = {
+        BeginTransaction: async () => { mockGlobalProviderCalls.push('BeginTransaction'); },
+        CommitTransaction: async () => { mockGlobalProviderCalls.push('CommitTransaction'); },
+        RollbackTransaction: async () => { mockGlobalProviderCalls.push('RollbackTransaction'); },
         Dialect: { BooleanLiteral: (value: boolean) => (value ? '1' : '0') },
     };
     class MockMetadata {
@@ -118,9 +140,10 @@ vi.mock('@memberjunction/core', async (importOriginal) => {
             return mockApplicationsArray;
         }
         public GetEntityObject(entityName: string, contextUser?: UserInfo): Promise<unknown> {
+            mockGlobalProviderCalls.push(`GetEntityObject:${entityName}`);
             return mockGetEntityObject(entityName, contextUser);
         }
-        static Provider = provider;
+        static Provider = globalProvider;
     }
     class MockUserInfo {
         constructor(_provider: unknown, initData: Record<string, unknown>) {
@@ -128,6 +151,9 @@ vi.mock('@memberjunction/core', async (importOriginal) => {
         }
     }
     class MockRunView {
+        public static FromMetadataProvider(_provider: unknown): MockRunView {
+            return new MockRunView();
+        }
         public RunView(params: unknown, contextUser?: UserInfo): Promise<unknown> {
             return mockRunViewFn(params, contextUser);
         }
@@ -295,6 +321,21 @@ beforeEach(() => {
     });
     mockRunViewFn.mockResolvedValue({ Success: true, Results: [] });
     mockGetDefaultApplicationsForNewUser.mockReturnValue([]);
+
+    mockGlobalProviderCalls.length = 0;
+    mockCreateIsolatedProvider.mockImplementation(async () => ({
+        BeginTransaction: mockBeginTransaction,
+        CommitTransaction: mockCommitTransaction,
+        RollbackTransaction: mockRollbackTransaction,
+        Dialect: { BooleanLiteral: (value: boolean) => (value ? '1' : '0') },
+        get Roles() {
+            return mockRolesArray;
+        },
+        get Applications() {
+            return mockApplicationsArray;
+        },
+        GetEntityObject: (entityName: string, contextUser?: UserInfo) => mockGetEntityObject(entityName, contextUser),
+    }));
 });
 
 // ─── NewUserBase.createNewUser ──────────────────────────────────────────────
@@ -303,6 +344,34 @@ describe('NewUserBase.createNewUser', () => {
     const create = (first = 'Ada', last = 'Lovelace', email = 'ada@example.com') =>
         new NewUserBase().createNewUser(first, last, email);
 
+    describe('provider isolation', () => {
+        it('runs the whole provisioning on its own provider, never the shared Metadata.Provider', async () => {
+            mockConfig.userHandling.CreateUserApplicationRecords = true;
+            mockConfig.userHandling.UserApplications = ['CRM'];
+            mockRunViewFn.mockResolvedValue({ Success: true, Results: [{ EntityID: 'ent-1', Entity: 'Accounts' }] });
+
+            const user = await create();
+
+            expect(user).toBeTruthy();
+            expect(mockCreateIsolatedProvider).toHaveBeenCalledTimes(1);
+            expect(mockBeginTransaction).toHaveBeenCalledTimes(1);
+            expect(mockCommitTransaction).toHaveBeenCalledTimes(1);
+            // User, role, application and application-entity records all came from the isolated one.
+            expect(getEntityObjectCalls.map((c) => c.entityName)).toEqual([
+                'MJ: Users', 'MJ: User Roles', 'MJ: User Applications', 'MJ: User Application Entities',
+            ]);
+            expect(mockGlobalProviderCalls).toEqual([]);
+        });
+
+        it('rolls back on the isolated provider too, never the shared one', async () => {
+            saveBehavior['MJ: Users'] = () => false;
+
+            expect(await create()).toBeNull();
+            expect(mockRollbackTransaction).toHaveBeenCalledTimes(1);
+            expect(mockGlobalProviderCalls).toEqual([]);
+        });
+    });
+
     describe('context-user resolution', () => {
         it('uses the configured contextUserForNewUserCreation for every entity it creates', async () => {
             const user = await create();

package/src/__tests__/orphanedConversationDetailReconciler.test.ts

@@ -20,8 +20,10 @@ const { mockGetEntityObject, writableStore } = vi.hoisted(() => ({
     writableStore: { last: null as Record<string, unknown> | null },
 }));
 
-vi.mock('@memberjunction/global', () => ({
-    UUIDsEqual: (a: string, b: string) => String(a).toLowerCase() === String(b).toLowerCase(),
+// The real UUID helpers: the reconciler indexes users with IndexByUUID, so a stub that only
+// provides UUIDsEqual would make the owner lookup throw (and the pass silently do nothing).
+vi.mock('@memberjunction/global', async (importOriginal) => ({
+    ...(await importOriginal<typeof import('@memberjunction/global')>()),
 }));
 
 vi.mock('@memberjunction/sqlserver-dataprovider', () => ({
@@ -230,6 +232,19 @@ describe('ReconcileOrphanedConversationDetails', () => {
         );
     });
 
+    it('resolves the owner when the conversation spells the user ID in a different case', async () => {
+        // The cached user is 'OWNER-1'; SQL Server and PostgreSQL disagree on UUID case, so the
+        // conversation row may carry it lower-cased. The owner lookup must still find the user.
+        script([detail()], [{ ConversationDetailID: DETAIL_ID, Status: 'Failed', CompletedAt: longAgo() }], 'owner-1');
+
+        await ReconcileOrphanedConversationDetails(PROVIDER, USER);
+
+        expect(mockGetEntityObject).toHaveBeenCalledWith(
+            'MJ: Conversation Details',
+            expect.objectContaining({ ID: 'OWNER-1' })
+        );
+    });
+
     it('leaves the detail alone when no owner can be resolved', async () => {
         script([detail()], [{ ConversationDetailID: DETAIL_ID, Status: 'Failed', CompletedAt: longAgo() }], null);
 

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

@@ -0,0 +1,201 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { MJGlobal } from '@memberjunction/global';
+import type { PubSubEngine } from 'type-graphql';
+import { PubSubManager } from '../../generic/PubSubManager.js';
+import {
+    ParseReplicatedRealtimeSessionEvent,
+    REALTIME_SESSION_EVENTS_TOPIC,
+    RealtimeSessionEventService,
+    type RealtimeSessionEventTopicPayload,
+} from '../../realtimeSessions/RealtimeSessionEventService.js';
+
+const OWNER = 'AAAAAAAA-0000-4000-8000-000000000001';
+const SESSION_ID = 'BBBBBBBB-0000-4000-8000-000000000001';
+const CONVERSATION_ID = 'CCCCCCCC-0000-4000-8000-000000000001';
+const USER = { ID: OWNER } as UserInfo;
+
+const VERIFIED = { VerifiedEmail: 'pat@example.com', VerifiedName: 'Pat', VerifiedAt: '2026-10-02T12:00:00.000Z', Method: 'link' as const };
+
+/** A provider that serves one session (+ conversation) — or nothing. */
+function provider(found = true, externalId: string | null = 'scope-1'): IMetadataProvider {
+    return {
+        GetEntityObject: vi.fn(async (name: string) => {
+            if (name === 'MJ: AI Agent Sessions') {
+                return found
+                    ? { ID: SESSION_ID, UserID: OWNER, ConversationID: CONVERSATION_ID, Load: vi.fn(async () => true) }
+                    : { Load: vi.fn(async () => false) };
+            }
+            return { ExternalID: externalId, Load: vi.fn(async () => true) };
+        }),
+    } as unknown as IMetadataProvider;
+}
+
+describe('RealtimeSessionEventService', () => {
+    const published: Array<{ topic: string; payload: RealtimeSessionEventTopicPayload }> = [];
+
+    beforeEach(() => {
+        published.length = 0;
+        const engine = { publish: vi.fn(async (topic: string, payload: RealtimeSessionEventTopicPayload) => void published.push({ topic, payload })) };
+        PubSubManager.Instance.SetPubSubEngine(engine as unknown as PubSubEngine);
+        RealtimeSessionEventService.Instance.SetReplicationHook(undefined);
+    });
+
+    describe('Publish', () => {
+        it('publishes on the shared topic with the session routing snapshot', async () => {
+            const result = await RealtimeSessionEventService.Instance.Publish({
+                AgentSessionID: SESSION_ID,
+                Type: 'identity.verified',
+                Payload: VERIFIED,
+                ContextUser: USER,
+                Provider: provider(),
+            });
+            expect(result).toEqual({ Success: true });
+            expect(published).toHaveLength(1);
+            expect(published[0].topic).toBe(REALTIME_SESSION_EVENTS_TOPIC);
+            expect(published[0].payload).toMatchObject({
+                Type: 'identity.verified',
+                AgentSessionID: SESSION_ID,
+                OwnerUserID: OWNER,
+                ScopeKey: 'scope-1',
+                SourceServerId: MJGlobal.Instance.ProcessUUID,
+            });
+            expect(JSON.parse(published[0].payload.PayloadJson)).toEqual(VERIFIED);
+            expect(Date.parse(published[0].payload.OccurredAt)).not.toBeNaN();
+        });
+
+        it('snapshots a null scope for a session whose conversation carries none', async () => {
+            await RealtimeSessionEventService.Instance.Publish({
+                AgentSessionID: SESSION_ID,
+                Type: 'identity.verified',
+                Payload: VERIFIED,
+                ContextUser: USER,
+                Provider: provider(true, null),
+            });
+            expect(published[0].payload.ScopeKey).toBeNull();
+        });
+
+        it('fails (and publishes nothing) when the session cannot be found', async () => {
+            const result = await RealtimeSessionEventService.Instance.Publish({
+                AgentSessionID: SESSION_ID,
+                Type: 'identity.verified',
+                Payload: VERIFIED,
+                ContextUser: USER,
+                Provider: provider(false),
+            });
+            expect(result.Success).toBe(false);
+            expect(result.ErrorMessage).toContain('not found');
+            expect(published).toHaveLength(0);
+        });
+
+        it('returns a failure instead of throwing when reading the session throws', async () => {
+            const broken = { GetEntityObject: vi.fn(async () => { throw new Error('db down'); }) } as unknown as IMetadataProvider;
+            const result = await RealtimeSessionEventService.Instance.Publish({
+                AgentSessionID: SESSION_ID,
+                Type: 'identity.verified',
+                Payload: VERIFIED,
+                ContextUser: USER,
+                Provider: broken,
+            });
+            expect(result).toMatchObject({ Success: false });
+            expect(result.ErrorMessage).toContain('db down');
+        });
+    });
+
+    describe('PublishRouted', () => {
+        it('fails loudly when PubSub is not configured', () => {
+            PubSubManager.Instance.SetPubSubEngine(null as unknown as PubSubEngine);
+            const result = RealtimeSessionEventService.Instance.PublishRouted({ AgentSessionID: SESSION_ID, OwnerUserID: OWNER, ScopeKey: null }, 'identity.verified', VERIFIED);
+            expect(result).toMatchObject({ Success: false });
+            expect(result.ErrorMessage).toContain('PubSub is not configured');
+        });
+
+        it('hands every locally published event to the replication hook', () => {
+            const hook = vi.fn();
+            RealtimeSessionEventService.Instance.SetReplicationHook(hook);
+            RealtimeSessionEventService.Instance.PublishRouted({ AgentSessionID: SESSION_ID, OwnerUserID: OWNER, ScopeKey: null }, 'identity.verified', VERIFIED);
+            expect(hook).toHaveBeenCalledTimes(1);
+            expect(hook.mock.calls[0][0]).toMatchObject({ AgentSessionID: SESSION_ID, OwnerUserID: OWNER, Type: 'identity.verified' });
+        });
+
+        it('never lets a failing replication hook break local delivery', () => {
+            RealtimeSessionEventService.Instance.SetReplicationHook(() => {
+                throw new Error('redis down');
+            });
+            const result = RealtimeSessionEventService.Instance.PublishRouted({ AgentSessionID: SESSION_ID, OwnerUserID: OWNER, ScopeKey: null }, 'identity.verified', VERIFIED);
+            expect(result).toEqual({ Success: true });
+            expect(published).toHaveLength(1);
+        });
+    });
+
+    describe('PublishReplicated', () => {
+        it('republishes locally and never back through the replication hook (no loop)', () => {
+            const hook = vi.fn();
+            RealtimeSessionEventService.Instance.SetReplicationHook(hook);
+            const payload: RealtimeSessionEventTopicPayload = {
+                Type: 'identity.verified',
+                AgentSessionID: SESSION_ID,
+                OccurredAt: '2026-10-02T12:00:00.000Z',
+                PayloadJson: JSON.stringify(VERIFIED),
+                OwnerUserID: OWNER,
+                ScopeKey: null,
+                SourceServerId: 'other-instance',
+            };
+            RealtimeSessionEventService.Instance.PublishReplicated(payload);
+            expect(published).toEqual([{ topic: REALTIME_SESSION_EVENTS_TOPIC, payload }]);
+            expect(hook).not.toHaveBeenCalled();
+        });
+    });
+});
+
+describe('ParseReplicatedRealtimeSessionEvent', () => {
+    const wire = (over: Record<string, unknown> = {}) =>
+        JSON.stringify({
+            Type: 'identity.verified',
+            AgentSessionID: SESSION_ID,
+            OccurredAt: '2026-10-02T12:00:00.000Z',
+            PayloadJson: '{}',
+            OwnerUserID: OWNER,
+            ScopeKey: 'scope-1',
+            SourceServerId: 'other-instance',
+            ...over,
+        });
+
+    it('accepts a well-formed event from another instance', () => {
+        expect(ParseReplicatedRealtimeSessionEvent(wire(), 'this-instance')).toEqual({
+            Type: 'identity.verified',
+            AgentSessionID: SESSION_ID,
+            OccurredAt: '2026-10-02T12:00:00.000Z',
+            PayloadJson: '{}',
+            OwnerUserID: OWNER,
+            ScopeKey: 'scope-1',
+            SourceServerId: 'other-instance',
+        });
+    });
+
+    it('drops our own echo', () => {
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ SourceServerId: 'this-instance' }), 'this-instance')).toBeNull();
+    });
+
+    it('fails closed when the routing identity is missing or malformed', () => {
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ OwnerUserID: undefined }), 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ OwnerUserID: '' }), 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ OwnerUserID: 5 }), 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ ScopeKey: 5 }), 'x')).toBeNull();
+    });
+
+    it('normalises an absent scope to null and tolerates an absent source', () => {
+        const parsed = ParseReplicatedRealtimeSessionEvent(wire({ ScopeKey: undefined, SourceServerId: undefined }), 'x');
+        expect(parsed?.ScopeKey).toBeNull();
+        expect(parsed?.SourceServerId).toBeUndefined();
+    });
+
+    it('drops non-JSON, non-objects and events missing required strings', () => {
+        expect(ParseReplicatedRealtimeSessionEvent('{nope', 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent('"text"', 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent('null', 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ Type: undefined }), 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ PayloadJson: undefined }), 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ SourceServerId: 7 }), 'x')).toBeNull();
+    });
+});

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

@@ -0,0 +1,215 @@
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { PubSub } from 'graphql-subscriptions';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import type { PubSubEngine } from 'type-graphql';
+import { PubSubManager } from '../../generic/PubSubManager.js';
+import type { UserPayload } from '../../types.js';
+import { RealtimeSessionEventService, type RealtimeSessionEventTopicPayload } from '../../realtimeSessions/RealtimeSessionEventService.js';
+import type { LoadedSessionForAccess } from '../../realtimeSessions/sessionAccess.js';
+import { AuthorizeAndSubscribeToRealtimeSessionEvents, RealtimeSessionEventsResolver } from '../../resolvers/RealtimeSessionEventsResolver.js';
+import {
+    AuthorizeRealtimeSessionSubscription,
+    RealtimeSessionEventsFilter,
+    type RealtimeSessionEventsContext,
+    type SubscriptionAuthorizationDeps,
+} from '../../realtimeSessions/subscriptionAuthorization.js';
+
+const OWNER = 'AAAAAAAA-0000-4000-8000-000000000001';
+const STRANGER = 'AAAAAAAA-0000-4000-8000-000000000002';
+const SESSION_ID = 'BBBBBBBB-0000-4000-8000-000000000001';
+const OTHER_SESSION_ID = 'BBBBBBBB-0000-4000-8000-000000000002';
+
+/** A connection context for a principal. */
+function contextFor(user: Partial<UserInfo> & { ID: string }): RealtimeSessionEventsContext {
+    return { userPayload: { email: 'x@y.z', sessionId: 's', userRecord: user } as UserPayload };
+}
+
+const named = (id: string) => contextFor({ ID: id });
+const guest = (id: string, scope?: string) =>
+    contextFor({ ID: id, IsMagicLinkAnonymous: true, MagicLinkScope: scope ? { ResourceID: scope } : undefined } as Partial<UserInfo> & { ID: string });
+
+function event(over: Partial<RealtimeSessionEventTopicPayload> = {}): RealtimeSessionEventTopicPayload {
+    return {
+        Type: 'identity.verified',
+        AgentSessionID: SESSION_ID,
+        OccurredAt: '2026-10-02T12:00:00.000Z',
+        PayloadJson: '{"VerifiedEmail":"pat@example.com"}',
+        OwnerUserID: OWNER,
+        ScopeKey: null,
+        ...over,
+    };
+}
+
+describe('RealtimeSessionEventsFilter (per-event gate)', () => {
+    const filter = (payload: RealtimeSessionEventTopicPayload, agentSessionId: string | undefined, context: RealtimeSessionEventsContext | undefined) =>
+        RealtimeSessionEventsFilter({ payload, args: { agentSessionId }, context });
+
+    it('delivers an event for the requested session to its owner', () => {
+        expect(filter(event(), SESSION_ID, named(OWNER))).toBe(true);
+    });
+
+    it('does not deliver an event addressed to a different session', () => {
+        expect(filter(event({ AgentSessionID: OTHER_SESSION_ID }), SESSION_ID, named(OWNER))).toBe(false);
+    });
+
+    it('does not deliver to a non-owner who guessed the session id', () => {
+        expect(filter(event(), SESSION_ID, named(STRANGER))).toBe(false);
+    });
+
+    it('compares session and user ids case-insensitively', () => {
+        expect(filter(event({ AgentSessionID: SESSION_ID.toLowerCase(), OwnerUserID: OWNER.toLowerCase() }), SESSION_ID, named(OWNER))).toBe(true);
+    });
+
+    describe('anonymous guests share one Anonymous user — only the signed scope tells them apart', () => {
+        it('delivers to the guest whose scope matches', () => {
+            expect(filter(event({ ScopeKey: 'scope-1' }), SESSION_ID, guest(OWNER, 'scope-1'))).toBe(true);
+        });
+
+        it('does not deliver to another guest (same user id, different scope)', () => {
+            expect(filter(event({ ScopeKey: 'scope-1' }), SESSION_ID, guest(OWNER, 'scope-2'))).toBe(false);
+        });
+
+        it('does not deliver to an anonymous connection with no scope', () => {
+            expect(filter(event({ ScopeKey: 'scope-1' }), SESSION_ID, guest(OWNER))).toBe(false);
+        });
+    });
+
+    it('fails closed on a missing connection identity, owner or argument', () => {
+        expect(filter(event(), SESSION_ID, undefined)).toBe(false);
+        expect(filter(event(), SESSION_ID, { userPayload: undefined })).toBe(false);
+        expect(filter(event({ OwnerUserID: '' }), SESSION_ID, named(OWNER))).toBe(false);
+        expect(filter(event(), undefined, named(OWNER))).toBe(false);
+    });
+});
+
+describe('AuthorizeRealtimeSessionSubscription (subscribe-time gate)', () => {
+    /** Deps whose session load returns the given owner/scope (or nothing). */
+    const deps = (loaded: { UserID: string; ExternalID: string | null } | null): SubscriptionAuthorizationDeps & { LoadSession: ReturnType<typeof vi.fn> } => ({
+        LoadSession: vi.fn(async () =>
+            loaded ? ({ Session: { ID: SESSION_ID, UserID: loaded.UserID }, ConversationExternalID: loaded.ExternalID } as unknown as LoadedSessionForAccess) : null,
+        ),
+        GetProvider: () => ({}) as IMetadataProvider,
+    });
+
+    it('lets the owner subscribe and returns the validated id', async () => {
+        const d = deps({ UserID: OWNER, ExternalID: null });
+        await expect(AuthorizeRealtimeSessionSubscription({ agentSessionId: SESSION_ID }, named(OWNER), d)).resolves.toBe(SESSION_ID);
+        expect(d.LoadSession).toHaveBeenCalledWith(SESSION_ID, expect.objectContaining({ ID: OWNER }), expect.anything());
+    });
+
+    it('refuses a non-owner with the uniform not-found message', async () => {
+        await expect(AuthorizeRealtimeSessionSubscription({ agentSessionId: SESSION_ID }, named(STRANGER), deps({ UserID: OWNER, ExternalID: null }))).rejects.toThrow('Realtime session not found.');
+    });
+
+    it('gives the SAME message when the session does not exist, so ids cannot be probed', async () => {
+        await expect(AuthorizeRealtimeSessionSubscription({ agentSessionId: SESSION_ID }, named(OWNER), deps(null))).rejects.toThrow('Realtime session not found.');
+    });
+
+    it('refuses an anonymous guest whose scope does not match the session conversation', async () => {
+        await expect(AuthorizeRealtimeSessionSubscription({ agentSessionId: SESSION_ID }, guest(OWNER, 'scope-2'), deps({ UserID: OWNER, ExternalID: 'scope-1' }))).rejects.toThrow('Realtime session not found.');
+    });
+
+    it('accepts an anonymous guest whose scope matches', async () => {
+        await expect(AuthorizeRealtimeSessionSubscription({ agentSessionId: SESSION_ID }, guest(OWNER, 'scope-1'), deps({ UserID: OWNER, ExternalID: 'scope-1' }))).resolves.toBe(SESSION_ID);
+    });
+
+    it('refuses an anonymous connection with no scope', async () => {
+        await expect(AuthorizeRealtimeSessionSubscription({ agentSessionId: SESSION_ID }, guest(OWNER), deps({ UserID: OWNER, ExternalID: 'scope-1' }))).rejects.toThrow('Realtime session not found.');
+    });
+
+    it('refuses without touching the database when there is no identity or the id is malformed', async () => {
+        const d = deps({ UserID: OWNER, ExternalID: null });
+        await expect(AuthorizeRealtimeSessionSubscription({ agentSessionId: SESSION_ID }, undefined, d)).rejects.toThrow('Realtime session not found.');
+        await expect(AuthorizeRealtimeSessionSubscription({ agentSessionId: SESSION_ID }, { userPayload: undefined }, d)).rejects.toThrow();
+        await expect(AuthorizeRealtimeSessionSubscription({ agentSessionId: 'not-a-uuid' }, named(OWNER), d)).rejects.toThrow();
+        await expect(AuthorizeRealtimeSessionSubscription({}, named(OWNER), d)).rejects.toThrow();
+        expect(d.LoadSession).not.toHaveBeenCalled();
+    });
+});
+
+describe('RealtimeSessionEvents subscription, end to end over a real PubSub', () => {
+    let engine: PubSub;
+    const info = {};
+
+    beforeEach(() => {
+        engine = new PubSub();
+        PubSubManager.Instance.SetPubSubEngine(engine as unknown as PubSubEngine);
+        RealtimeSessionEventService.Instance.SetReplicationHook(undefined);
+    });
+
+    const allow = (loaded: { UserID: string; ExternalID: string | null }): SubscriptionAuthorizationDeps => ({
+        LoadSession: async () => ({ Session: { ID: SESSION_ID, UserID: loaded.UserID }, ConversationExternalID: loaded.ExternalID }) as unknown as LoadedSessionForAccess,
+        GetProvider: () => ({}) as IMetadataProvider,
+    });
+
+    const VERIFIED = { VerifiedEmail: 'pat@example.com', VerifiedName: 'Pat', VerifiedAt: '2026-10-02T12:00:00.000Z', Method: 'code' as const };
+
+    /** graphql-subscriptions registers its PubSub listener lazily, on the first `next()`; let that settle before publishing. */
+    const settled = () => new Promise<void>((resolve) => setImmediate(resolve));
+
+    it('refuses a non-owner before any stream is opened', async () => {
+        await expect(
+            AuthorizeAndSubscribeToRealtimeSessionEvents({}, { agentSessionId: SESSION_ID }, named(STRANGER), info, allow({ UserID: OWNER, ExternalID: null })),
+        ).rejects.toThrow('Realtime session not found.');
+    });
+
+    it('delivers only the owner\'s events for the requested session, in order, and nothing else', async () => {
+        const stream = await AuthorizeAndSubscribeToRealtimeSessionEvents({}, { agentSessionId: SESSION_ID }, named(OWNER), info, allow({ UserID: OWNER, ExternalID: null }));
+        const service = RealtimeSessionEventService.Instance;
+        const firstPull = stream.next(); // starts the subscription
+        await settled();
+
+        // Noise that must NOT arrive: another session of the same owner, and another owner's event for the same id.
+        service.PublishRouted({ AgentSessionID: OTHER_SESSION_ID, OwnerUserID: OWNER, ScopeKey: null }, 'identity.verified', VERIFIED);
+        service.PublishRouted({ AgentSessionID: SESSION_ID, OwnerUserID: STRANGER, ScopeKey: null }, 'identity.verified', { ...VERIFIED, VerifiedEmail: 'leak@example.com' });
+        // The two that must.
+        service.PublishRouted({ AgentSessionID: SESSION_ID, OwnerUserID: OWNER, ScopeKey: null }, 'identity.verified', VERIFIED);
+        service.PublishRouted({ AgentSessionID: SESSION_ID, OwnerUserID: OWNER, ScopeKey: null }, 'identity.verified', { ...VERIFIED, Method: 'link' });
+
+        const first = await firstPull;
+        const second = await stream.next();
+        expect(JSON.parse(first.value.PayloadJson)).toMatchObject({ VerifiedEmail: 'pat@example.com', Method: 'code' });
+        expect(JSON.parse(second.value.PayloadJson)).toMatchObject({ Method: 'link' });
+        expect(first.value.AgentSessionID).toBe(SESSION_ID);
+
+        // Nothing else is queued: a third event never arrives until one is published.
+        const pending = stream.next();
+        const raced = await Promise.race([pending.then(() => 'delivered'), new Promise((resolve) => setTimeout(() => resolve('quiet'), 30))]);
+        expect(raced).toBe('quiet');
+        await stream.return?.();
+    });
+
+    it('does not deliver a guest\'s event to a different guest sharing the Anonymous user', async () => {
+        const guestB = await AuthorizeAndSubscribeToRealtimeSessionEvents({}, { agentSessionId: SESSION_ID }, guest(OWNER, 'scope-B'), info, allow({ UserID: OWNER, ExternalID: 'scope-B' }));
+        const pull = guestB.next();
+        await settled();
+        // An event for guest A's session id would never reach B (the id differs); simulate the worst case: same id, A's scope.
+        RealtimeSessionEventService.Instance.PublishRouted({ AgentSessionID: SESSION_ID, OwnerUserID: OWNER, ScopeKey: 'scope-A' }, 'identity.verified', VERIFIED);
+        RealtimeSessionEventService.Instance.PublishRouted({ AgentSessionID: SESSION_ID, OwnerUserID: OWNER, ScopeKey: 'scope-B' }, 'identity.verified', { ...VERIFIED, VerifiedEmail: 'b@example.com' });
+        const got = await pull;
+        expect(JSON.parse(got.value.PayloadJson).VerifiedEmail).toBe('b@example.com');
+        await guestB.return?.();
+    });
+
+    it('fails when PubSub is not configured', async () => {
+        PubSubManager.Instance.SetPubSubEngine(null as unknown as PubSubEngine);
+        await expect(
+            AuthorizeAndSubscribeToRealtimeSessionEvents({}, { agentSessionId: SESSION_ID }, named(OWNER), info, allow({ UserID: OWNER, ExternalID: null })),
+        ).rejects.toThrow('PubSub is not configured');
+    });
+});
+
+describe('RealtimeSessionEventsResolver.RealtimeSessionEvents (resolve)', () => {
+    it('returns the wire event and never exposes the routing snapshot', () => {
+        const out = new RealtimeSessionEventsResolver().RealtimeSessionEvents(event({ ScopeKey: 'scope-1' }), SESSION_ID);
+        expect(out).toEqual({
+            Type: 'identity.verified',
+            AgentSessionID: SESSION_ID,
+            OccurredAt: '2026-10-02T12:00:00.000Z',
+            PayloadJson: '{"VerifiedEmail":"pat@example.com"}',
+        });
+        expect(Object.keys(out)).not.toContain('OwnerUserID');
+        expect(Object.keys(out)).not.toContain('ScopeKey');
+    });
+});