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

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');
+    });
+});

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

@@ -0,0 +1,102 @@
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import type { AppContext, ProviderInfo, UserPayload } from '../../types.js';
+
+const service = vi.hoisted(() => ({
+    RequestVerification: vi.fn(),
+    SubmitCode: vi.fn(),
+    GetStatus: vi.fn(),
+}));
+vi.mock('../../realtimeSessions/RealtimeSessionVerificationService.js', () => ({ RealtimeSessionVerificationService: { Instance: service } }));
+
+import { RealtimeSessionVerificationResolver } from '../../resolvers/RealtimeSessionVerificationResolver.js';
+import { HasNoLogParameter } from '../../logging/NoLog.js';
+
+const SESSION_ID = 'BBBBBBBB-0000-4000-8000-000000000001';
+const OWNER = 'AAAAAAAA-0000-4000-8000-000000000001';
+const PROVIDER = { id: 'rw' } as unknown as IMetadataProvider;
+
+function context(over: { userRecord?: Partial<UserInfo> | null; email?: string; providers?: ProviderInfo[]; clientIp?: string } = {}): AppContext {
+    const userPayload = {
+        email: over.email ?? 'owner@example.com',
+        sessionId: 's',
+        userRecord: over.userRecord === null ? undefined : (over.userRecord ?? { ID: OWNER }),
+    } as UserPayload;
+    return {
+        userPayload,
+        providers: over.providers ?? ([{ provider: PROVIDER, type: 'Read-Write' }] as unknown as ProviderInfo[]),
+        ClientIp: over.clientIp ?? '203.0.113.7',
+    } as unknown as AppContext;
+}
+
+const OK = { Success: true, VerificationState: 'pending', Message: 'We emailed you a link and a code.', SendsRemaining: 2 };
+
+describe('RealtimeSessionVerificationResolver', () => {
+    const resolver = new RealtimeSessionVerificationResolver();
+
+    beforeEach(() => {
+        service.RequestVerification.mockReset().mockResolvedValue(OK);
+        service.SubmitCode.mockReset().mockResolvedValue({ Success: true, VerificationState: 'verified' });
+        service.GetStatus.mockReset().mockResolvedValue({ Success: true, VerificationState: 'unverified' });
+    });
+
+    describe('RequestRealtimeSessionVerification', () => {
+        it('calls the service as the authenticated principal with the request provider and client IP', async () => {
+            const result = await resolver.RequestRealtimeSessionVerification(SESSION_ID, 'Pat', 'pat@acme.com', context());
+            expect(result).toEqual(OK);
+            expect(service.RequestVerification).toHaveBeenCalledWith(
+                { AgentSessionID: SESSION_ID, Name: 'Pat', Email: 'pat@acme.com' },
+                { Kind: 'principal', ContextUser: { ID: OWNER }, Provider: PROVIDER, ClientIp: '203.0.113.7' },
+            );
+        });
+
+        it('refuses a caller with no authenticated userRecord — it does NOT fall back to an email lookup that would drop an anonymous guest\'s scope', async () => {
+            const result = await resolver.RequestRealtimeSessionVerification(SESSION_ID, 'Pat', 'pat@acme.com', context({ userRecord: null, email: 'anonymous@magic-link.local' }));
+            expect(result).toMatchObject({ Success: false, ErrorCode: 'session_not_found' });
+            expect(service.RequestVerification).not.toHaveBeenCalled();
+        });
+
+        it('refuses when there is no read-write provider', async () => {
+            const result = await resolver.RequestRealtimeSessionVerification(SESSION_ID, 'Pat', 'pat@acme.com', context({ providers: [] }));
+            expect(result.Success).toBe(false);
+            expect(service.RequestVerification).not.toHaveBeenCalled();
+        });
+
+        it('passes a failure result straight through', async () => {
+            service.RequestVerification.mockResolvedValue({ Success: false, VerificationState: 'unverified', ErrorCode: 'consumer_domain', Message: 'Please use your work email address.' });
+            expect(await resolver.RequestRealtimeSessionVerification(SESSION_ID, 'Pat', 'pat@gmail.com', context())).toMatchObject({ Success: false, ErrorCode: 'consumer_domain' });
+        });
+    });
+
+    describe('SubmitRealtimeSessionVerificationCode', () => {
+        it('calls the service with the code and the same principal', async () => {
+            await resolver.SubmitRealtimeSessionVerificationCode(SESSION_ID, '123456', context());
+            expect(service.SubmitCode).toHaveBeenCalledWith({ AgentSessionID: SESSION_ID, Code: '123456' }, expect.objectContaining({ Kind: 'principal', ContextUser: { ID: OWNER } }));
+        });
+
+        it('refuses an unauthenticated caller', async () => {
+            expect(await resolver.SubmitRealtimeSessionVerificationCode(SESSION_ID, '123456', context({ userRecord: null }))).toMatchObject({ Success: false });
+            expect(service.SubmitCode).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('RealtimeSessionVerificationStatus', () => {
+        it('reads the status as the principal', async () => {
+            expect(await resolver.RealtimeSessionVerificationStatus(SESSION_ID, context())).toEqual({ Success: true, VerificationState: 'unverified' });
+            expect(service.GetStatus).toHaveBeenCalledWith({ AgentSessionID: SESSION_ID }, expect.objectContaining({ ContextUser: { ID: OWNER } }));
+        });
+
+        it('refuses an unauthenticated caller', async () => {
+            expect(await resolver.RealtimeSessionVerificationStatus(SESSION_ID, context({ userRecord: null }))).toMatchObject({ Success: false });
+            expect(service.GetStatus).not.toHaveBeenCalled();
+        });
+    });
+
+    it('marks the email and the code @NoLog so they never reach variable logging', () => {
+        // Parameter index 2 of the request (email) and index 1 of the code submission.
+        expect(HasNoLogParameter(RealtimeSessionVerificationResolver, 'RequestRealtimeSessionVerification', 2)).toBe(true);
+        expect(HasNoLogParameter(RealtimeSessionVerificationResolver, 'SubmitRealtimeSessionVerificationCode', 1)).toBe(true);
+        expect(HasNoLogParameter(RealtimeSessionVerificationResolver, 'RequestRealtimeSessionVerification', 0)).toBe(false);
+    });
+});