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

package/src/__tests__/localDevAuth.test.ts

@@ -0,0 +1,196 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import type { Request } from 'express';
+import jwt from 'jsonwebtoken';
+import { AuthProviderFactory } from '@memberjunction/auth-providers';
+import { UserInfo } from '@memberjunction/core';
+
+vi.mock('../config.js', () => ({
+  configInfo: {
+    devAuth: { enabled: false },
+    magicLink: {},
+    authProviders: [],
+  },
+}));
+
+import {
+  AssertLocalDevAuthAllowed,
+  IsLocalDevAuthEnabled,
+  IsLoopbackAddress,
+  MintLocalDevJwt,
+  RegisterLocalDevAuthProvider,
+  VerifyLocalhostRequest,
+} from '../auth/localDevAuth.js';
+import { MagicLinkKeyManager } from '../auth/magicLink/MagicLinkKeys.js';
+
+function createMockRequest(overrides: {
+  remoteAddress?: string;
+  host?: string;
+  origin?: string;
+  referer?: string;
+  xff?: string;
+}): Request {
+  const headers: Record<string, string | undefined> = {
+    host: overrides.host ?? 'localhost:4000',
+    origin: overrides.origin,
+    referer: overrides.referer,
+    'x-forwarded-for': overrides.xff,
+  };
+  return {
+    headers,
+    hostname: (overrides.host ?? 'localhost:4000').split(':')[0],
+    ip: overrides.remoteAddress ?? '127.0.0.1',
+    socket: {
+      remoteAddress: overrides.remoteAddress ?? '127.0.0.1',
+    },
+  } as unknown as Request;
+}
+
+describe('localDevAuth security invariants', () => {
+  beforeEach(() => {
+    AuthProviderFactory.Instance.clear();
+  });
+
+  it('IsLocalDevAuthEnabled detects MJ_DEV_AUTH_ENABLED=true or 1', () => {
+    expect(IsLocalDevAuthEnabled({})).toBe(false);
+    expect(IsLocalDevAuthEnabled({ MJ_DEV_AUTH_ENABLED: 'false' })).toBe(false);
+    expect(IsLocalDevAuthEnabled({ MJ_DEV_AUTH_ENABLED: 'true' })).toBe(true);
+    expect(IsLocalDevAuthEnabled({ MJ_DEV_AUTH_ENABLED: '1' })).toBe(true);
+  });
+
+  it('AssertLocalDevAuthAllowed fails loudly when NODE_ENV=production', () => {
+    expect(() =>
+      AssertLocalDevAuthAllowed({
+        MJ_DEV_AUTH_ENABLED: 'true',
+        NODE_ENV: 'development',
+      })
+    ).not.toThrow();
+
+    expect(() =>
+      AssertLocalDevAuthAllowed({
+        MJ_DEV_AUTH_ENABLED: 'true',
+        NODE_ENV: 'production',
+      })
+    ).toThrow(/strictly forbidden when NODE_ENV=production/);
+  });
+
+  it('IsLoopbackAddress accepts loopback and conditional Docker local bridge IPs', () => {
+    expect(IsLoopbackAddress('127.0.0.1', false)).toBe(true);
+    expect(IsLoopbackAddress('::1', false)).toBe(true);
+    expect(IsLoopbackAddress('::ffff:127.0.0.1', false)).toBe(true);
+    expect(IsLoopbackAddress('192.168.65.1', false)).toBe(false);
+    expect(IsLoopbackAddress('192.168.65.1', true)).toBe(true);
+    expect(IsLoopbackAddress('172.18.0.1', true)).toBe(true);
+    expect(IsLoopbackAddress('192.168.1.42', true)).toBe(false);
+    expect(IsLoopbackAddress('203.0.113.10', true)).toBe(false);
+  });
+
+  it('VerifyLocalhostRequest allows genuine localhost requests and blocks non-localhost vectors', () => {
+    // 1. Standard localhost IPv4 and IPv6
+    expect(
+      VerifyLocalhostRequest(
+        createMockRequest({ remoteAddress: '127.0.0.1', host: 'localhost:4000', origin: 'http://localhost:4202' }),
+        { NODE_ENV: 'development' }
+      ).Allowed
+    ).toBe(true);
+
+    expect(
+      VerifyLocalhostRequest(
+        createMockRequest({ remoteAddress: '::1', host: '127.0.0.1:4000', origin: 'http://127.0.0.1:4202' }),
+        { NODE_ENV: 'development' }
+      ).Allowed
+    ).toBe(true);
+
+    // 2. Docker Desktop host-gateway when Host is localhost, inside container, and no XFF is present
+    expect(
+      VerifyLocalhostRequest(
+        createMockRequest({ remoteAddress: '::ffff:192.168.65.1', host: 'localhost:4000' }),
+        { NODE_ENV: 'development', MJ_DEV_AUTH_ALLOW_DOCKER_BRIDGE: 'true' }
+      ).Allowed
+    ).toBe(true);
+
+    // 2b. Rejects Docker bridge IPs when NOT running inside a container
+    expect(
+      VerifyLocalhostRequest(
+        createMockRequest({ remoteAddress: '172.18.0.1', host: 'localhost:4000' }),
+        { NODE_ENV: 'development', MJ_DEV_AUTH_ALLOW_DOCKER_BRIDGE: 'false' }
+      ).Allowed
+    ).toBe(false);
+
+    // 2c. Rejects non-gateway RFC1918 172.16.0.0/12 addresses even inside a container
+    expect(IsLoopbackAddress('172.20.10.5', true)).toBe(false);
+
+    // 3. Rejects in production even from 127.0.0.1
+    expect(
+      VerifyLocalhostRequest(
+        createMockRequest({ remoteAddress: '127.0.0.1', host: 'localhost:4000' }),
+        { NODE_ENV: 'production' }
+      ).Allowed
+    ).toBe(false);
+
+    // 4. Rejects LAN IP on socket
+    expect(
+      VerifyLocalhostRequest(
+        createMockRequest({ remoteAddress: '192.168.1.50', host: 'localhost:4000' }),
+        { NODE_ENV: 'development' }
+      ).Allowed
+    ).toBe(false);
+
+    // 5. Rejects non-localhost Host header
+    expect(
+      VerifyLocalhostRequest(
+        createMockRequest({ remoteAddress: '127.0.0.1', host: '192.168.1.50:4000' }),
+        { NODE_ENV: 'development' }
+      ).Allowed
+    ).toBe(false);
+
+    // 6. Rejects external X-Forwarded-For
+    expect(
+      VerifyLocalhostRequest(
+        createMockRequest({ remoteAddress: '127.0.0.1', host: 'localhost:4000', xff: '203.0.113.5' }),
+        { NODE_ENV: 'development' }
+      ).Allowed
+    ).toBe(false);
+
+    // 7. Rejects external Origin
+    expect(
+      VerifyLocalhostRequest(
+        createMockRequest({
+          remoteAddress: '127.0.0.1',
+          host: 'localhost:4000',
+          origin: 'https://attacker.example.com',
+        }),
+        { NODE_ENV: 'development' }
+      ).Allowed
+    ).toBe(false);
+  });
+
+  it('MintLocalDevJwt mints an RS256 token verifiable by the registered LocalDevProvider', () => {
+    MagicLinkKeyManager.Instance.Initialize();
+    RegisterLocalDevAuthProvider('http://localhost:4000');
+
+    const mockUser = new UserInfo(undefined, {
+      ID: '11111111-2222-3333-4444-555555555555',
+      Name: 'Admin User',
+      Email: 'admin@memberjunction.org',
+      FirstName: 'Admin',
+      LastName: 'User',
+      IsActive: true,
+      Type: 'Owner',
+      UserRoles: [],
+    });
+
+    const { token, claims } = MintLocalDevJwt(mockUser, 'http://localhost:4000');
+    expect(claims.iss).toBe('http://localhost:4000/local-dev');
+    expect(claims.aud).toBe('mj-local-dev');
+    expect(claims.email).toBe('admin@memberjunction.org');
+    expect(claims['mj_magic_link']).toBeUndefined();
+
+    const provider = AuthProviderFactory.Instance.getByIssuer('http://localhost:4000/local-dev');
+    expect(provider).toBeDefined();
+    const decoded = jwt.decode(token) as jwt.JwtPayload;
+    const userInfo = provider!.extractUserInfo(decoded);
+    expect(userInfo.email).toBe('admin@memberjunction.org');
+    expect(userInfo.firstName).toBe('Admin');
+    expect(userInfo.lastName).toBe('User');
+  });
+});

package/src/__tests__/orphanedConversationDetailReconciler.test.ts

@@ -74,6 +74,7 @@ function writable(saveResult = true, loadedStatus = 'In-Progress') {
         ID: DETAIL_ID,
         Status: loadedStatus,
         Message: '',
+        MarkServerAuthoredReply: vi.fn(),
         Load: vi.fn(async () => true),
         Save: vi.fn(async () => saveResult),
         LatestResult: { CompleteMessage: 'denied' },
@@ -245,6 +246,15 @@ describe('ReconcileOrphanedConversationDetails', () => {
         );
     });
 
+    it("marks the close as the server's write: the reply gate refuses an unmarked change to a reply's status", async () => {
+        script([detail()], [{ ConversationDetailID: DETAIL_ID, Status: 'Failed', CompletedAt: longAgo() }]);
+
+        await ReconcileOrphanedConversationDetails(PROVIDER, USER);
+
+        expect(writableStore.last?.MarkServerAuthoredReply).toHaveBeenCalledOnce();
+        expect(writableStore.last?.Save).toHaveBeenCalled();
+    });
+
     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__/pushStatusResolver.filter.test.ts

@@ -10,7 +10,7 @@
  */
 import 'reflect-metadata';
 import { describe, it, expect } from 'vitest';
-import { StatusUpdatesFilter, type PushStatusNotificationPayload, type StatusUpdatesFilterContext } from '../generic/PushStatusResolver';
+import { StatusUpdatesFilter, StatusUpdateOwnerID, type PushStatusNotificationPayload, type StatusUpdatesFilterContext } from '../generic/PushStatusResolver';
 import type { UserPayload } from '../types';
 
 const OWNER = 'AA11BB22-0000-4000-8000-000000000001';
@@ -61,3 +61,59 @@ describe('statusUpdatesFilter (B49 session-hijack gate)', () => {
   });
 });
 
+
+describe('StatusUpdateOwnerID (#4931)', () => {
+    it('is the request user, or the user an elevated payload stands in for', () => {
+        expect(StatusUpdateOwnerID({ sessionId: 's', email: 'e', userRecord: { ID: 'user-1' } } as UserPayload)).toBe('user-1');
+        expect(StatusUpdateOwnerID({ sessionId: 's', email: 'e', userRecord: { ID: 'system' }, ElevatedFrom: { ID: 'guest' } } as unknown as UserPayload)).toBe('guest');
+        expect(StatusUpdateOwnerID(undefined)).toBe('');
+    });
+});
+
+describe('statusUpdatesFilter — anonymous visitors share one user id (#4931)', () => {
+    const ANON = 'AAAAAAAA-0000-4000-8000-0000000000A0';
+    const visitor = (sid: string) => ({ ID: ANON, IsMagicLinkAnonymous: true, AnonymousVisitorID: sid, MagicLinkScope: { ResourceID: sid } });
+    const connection = (user: object): StatusUpdatesFilterContext => ({ userPayload: { sessionId: 'same-session', email: 'anonymous@magic-link.local', userRecord: user } as unknown as UserPayload });
+    // Visitor A's run, elevated to the system user: the event's owner comes from ElevatedFrom.
+    const aRun = { sessionId: 'same-session', email: 'system@example.com', userRecord: { ID: 'system' }, ElevatedFrom: visitor('sid-a') } as unknown as UserPayload;
+    const event = (): PushStatusNotificationPayload => ({ sessionId: 'same-session', ownerUserId: StatusUpdateOwnerID(aRun), message: 'complete' });
+
+    it("delivers visitor A's run events to visitor A's connection", () => {
+        expect(StatusUpdatesFilter({ payload: event(), args: { sessionId: 'same-session' }, context: connection(visitor('sid-a')) })).toBe(true);
+    });
+
+    it('does not deliver them to visitor B, even with the same (client-chosen) session id', () => {
+        expect(StatusUpdatesFilter({ payload: event(), args: { sessionId: 'same-session' }, context: connection(visitor('sid-b')) })).toBe(false);
+    });
+
+    it('does not deliver them to an anonymous connection with no scope identity (fail closed)', () => {
+        expect(StatusUpdatesFilter({ payload: event(), args: { sessionId: 'same-session' }, context: connection({ ID: ANON, IsMagicLinkAnonymous: true }) })).toBe(false);
+    });
+});
+
+describe('statusUpdatesFilter — an anonymous owner key matches exactly', () => {
+    // The scope part is a signed, case-significant identity (an mj_sid or a resource scope), so the anonymous key is
+    // compared exactly. A UUID comparison (case- and whitespace-insensitive) would let a visitor whose scope differs
+    // only in case or padding receive another visitor's run events.
+    const ANON = 'AAAAAAAA-0000-4000-8000-0000000000A0';
+    const visitor = (sid: string) => ({ ID: ANON, IsMagicLinkAnonymous: true, AnonymousVisitorID: sid, MagicLinkScope: { ResourceID: sid } });
+    const connection = (user: object): StatusUpdatesFilterContext => ({ userPayload: { sessionId: 's', email: 'anonymous@magic-link.local', userRecord: user } as UserPayload });
+    const eventOwnedBy = (sid: string): PushStatusNotificationPayload => ({
+        sessionId: 's',
+        ownerUserId: `${ANON.toLowerCase()}|${sid}`,
+        message: 'complete',
+    });
+
+    it('delivers to the visitor whose scope is identical', () => {
+        expect(StatusUpdatesFilter({ payload: eventOwnedBy('sid-a'), args: { sessionId: 's' }, context: connection(visitor('sid-a')) })).toBe(true);
+    });
+
+    it('does not deliver when the scopes differ only by case', () => {
+        expect(StatusUpdatesFilter({ payload: eventOwnedBy('SID-A'), args: { sessionId: 's' }, context: connection(visitor('sid-a')) })).toBe(false);
+    });
+
+    it('does not deliver when the scopes differ only by surrounding whitespace', () => {
+        expect(StatusUpdatesFilter({ payload: eventOwnedBy('sid-a '), args: { sessionId: 's' }, context: connection(visitor('sid-a')) })).toBe(false);
+        expect(StatusUpdatesFilter({ payload: eventOwnedBy('sid-a'), args: { sessionId: 's' }, context: connection(visitor(' sid-a')) })).toBe(false);
+    });
+});

package/src/__tests__/realtimeRecordingHandler.test.ts

@@ -135,6 +135,10 @@ class FakeLedger implements IRealtimeRecordingLedger {
         throw new Error('not used by the routes');
     }
 
+    public async StampFile(): Promise<{ RecordingStatus: string | null }> {
+        throw new Error('not used by the routes');
+    }
+
     public async LoadShards(sessionID: string): Promise<LedgerShard[]> {
         return [...this.shardsOf(sessionID).values()].sort((a, b) => a.Index - b.Index)
             .map(s => ({ Index: s.Index, StartSample: s.StartSample, SampleCount: s.SampleCount, Data: s.Data }));
@@ -198,6 +202,7 @@ function callerLedger(inner: FakeLedger): IRealtimeRecordingLedger {
         ClaimAssembly: id => inner.ClaimAssembly(id),
         FinishAssembly: input => inner.FinishAssembly(input),
         StampAssemblyGaps: () => inner.StampAssemblyGaps(),
+        StampFile: () => inner.StampFile(),
         LoadShards: refuse,
         LoadShardMetadata: refuse,
         CountShardsBelow: refuse,
@@ -221,7 +226,7 @@ describe('realtime recording REST routes', () => {
         const app = express();
         app.use(REALTIME_RECORDING_MOUNT_PATH, CreateRealtimeRecordingRouter(deps));
         server = await new Promise<Server>(resolve => {
-            const s = app.listen(0, () => resolve(s));
+            const s = app.listen(0, '127.0.0.1', () => resolve(s));
         });
         baseUrl = `http://127.0.0.1:${(server.address() as AddressInfo).port}${REALTIME_RECORDING_MOUNT_PATH}`;
     }
@@ -264,11 +269,15 @@ describe('realtime recording REST routes', () => {
                 const user = {
                     ID: id,
                     IsMagicLinkAnonymous: req.header('x-test-anonymous') === 'true',
+                    AnonymousVisitorID: scope ?? undefined,
                     MagicLinkScope: scope ? { ResourceID: scope } : undefined,
                 };
                 return id ? { ContextUser: user as unknown as UserInfo, Provider: {} as unknown as DatabaseProviderBase } : null;
             },
-            LoadConversationExternalID: async session => ledger.Sessions.get(session.ID)?.ConversationExternalID ?? null,
+            LoadConversationScope: async session => {
+                const row = ledger.Sessions.get(session.ID);
+                return { ExternalID: row?.ConversationExternalID ?? null, Readable: row?.ConversationExternalID !== undefined };
+            },
             LoadOwnedSession: async (agentSessionId, contextUser) => {
                 const row = ledger.Sessions.get(agentSessionId);
                 if (!row) {
@@ -391,6 +400,14 @@ describe('realtime recording REST routes', () => {
                 expect((await post(`/${SESSION}/end?lastShardIndex=0&capturedSamples=${SHARD_SAMPLES}`, null, OWNER_ID, headers)).status).toBe(200);
             });
 
+            it('accepts a named owner holding a resource-scoped link on its own unstamped conversation, and refuses another stamp (#4931)', async () => {
+                const headers = { 'x-test-scope': 'res-1' };
+                addSession(SESSION, { ConversationExternalID: null });
+                expect((await post(`/${SESSION}/shard/0`, shardBytes(0), OWNER_ID, headers)).status).toBe(200);
+                addSession(SESSION, { ConversationExternalID: 'res-2' });
+                expect((await post(`/${SESSION}/shard/1`, shardBytes(1), OWNER_ID, headers)).status).toBe(403);
+            });
+
             it('leaves a named owner (no scope, not anonymous) unaffected', async () => {
                 expect((await postShard(0)).status).toBe(200);
             });

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

@@ -27,7 +27,12 @@ function contextFor(user: Partial<UserInfo> & { ID: string }): RealtimeSessionEv
 
 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 });
+    contextFor({
+        ID: id,
+        IsMagicLinkAnonymous: true,
+        AnonymousVisitorID: scope,
+        MagicLinkScope: scope ? { ResourceID: scope } : undefined,
+    } as Partial<UserInfo> & { ID: string });
 
 function event(over: Partial<RealtimeSessionEventTopicPayload> = {}): RealtimeSessionEventTopicPayload {
     return {
@@ -75,6 +80,18 @@ describe('RealtimeSessionEventsFilter (per-event gate)', () => {
         });
     });
 
+    describe('a named user holding a resource-scoped magic link (#4931)', () => {
+        const namedScoped = (scope: string) => contextFor({ ID: OWNER, MagicLinkScope: { ResourceID: scope } } as Partial<UserInfo> & { ID: string });
+
+        it('delivers its own session\'s events when the conversation carries no scope stamp', () => {
+            expect(filter(event({ ScopeKey: null }), SESSION_ID, namedScoped('res-1'))).toBe(true);
+        });
+
+        it('does not deliver events of a session stamped with its other link\'s scope', () => {
+            expect(filter(event({ ScopeKey: 'res-2' }), SESSION_ID, namedScoped('res-1'))).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);
@@ -98,6 +115,17 @@ describe('AuthorizeRealtimeSessionSubscription (subscribe-time gate)', () => {
         expect(d.LoadSession).toHaveBeenCalledWith(SESSION_ID, expect.objectContaining({ ID: OWNER }), expect.anything());
     });
 
+    it('lets a named scoped owner subscribe to its session on a readable, unstamped conversation, and refuses it when unreadable (#4931)', async () => {
+        const namedScoped = contextFor({ ID: OWNER, MagicLinkScope: { ResourceID: 'res-1' } } as Partial<UserInfo> & { ID: string });
+        const load = (readable: boolean): SubscriptionAuthorizationDeps => ({
+            LoadSession: vi.fn(async () =>
+                ({ Session: { ID: SESSION_ID, UserID: OWNER }, ConversationExternalID: null, ConversationReadable: readable } as unknown as LoadedSessionForAccess)),
+            GetProvider: () => ({}) as IMetadataProvider,
+        });
+        await expect(AuthorizeRealtimeSessionSubscription({ agentSessionId: SESSION_ID }, namedScoped, load(true))).resolves.toBe(SESSION_ID);
+        await expect(AuthorizeRealtimeSessionSubscription({ agentSessionId: SESSION_ID }, namedScoped, load(false))).rejects.toThrow('Realtime session not found.');
+    });
+
     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.');
     });

package/src/__tests__/realtimeSessions/ownedRealtimeSession.anonymous.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { LoadOwnedRealtimeSession, RealtimeSessionOwnershipError } from '../../realtimeSessions/ownedRealtimeSession.js';
+
+// Fixture UUIDs are assembled at runtime so the brief itself carries no record id.
+const uuid = (a: string, b: string) => [a.repeat(8), b.repeat(4), '4' + b.repeat(3), '8' + b.repeat(3), b.repeat(12)].join('-');
+const ANON = uuid('A', '0');
+const SESSION = uuid('1', '1');
+const CONVERSATION = uuid('2', '2');
+const guest = (scope: string) =>
+    ({ ID: ANON, IsMagicLinkAnonymous: true, AnonymousVisitorID: scope, MagicLinkScope: { ResourceID: scope } } as unknown as UserInfo);
+
+/** A session owned by the shared Anonymous user; its conversation is stamped with visitor 1's scope. */
+function provider(): IMetadataProvider {
+    return {
+        GetEntityObject: vi.fn(async (entity: string) =>
+            entity === 'MJ: AI Agent Sessions'
+                ? { UserID: ANON, ConversationID: CONVERSATION, Load: vi.fn(async () => true) }
+                : { ExternalID: 'scope-visitor-1', Load: vi.fn(async () => true) }),
+    } as unknown as IMetadataProvider;
+}
+
+describe('LoadOwnedRealtimeSession with two anonymous visitors', () => {
+    it('allows the visitor whose scope matches', async () => {
+        await expect(LoadOwnedRealtimeSession(SESSION, guest('scope-visitor-1'), provider())).resolves.toBeDefined();
+    });
+    it('refuses a second anonymous visitor (same Anonymous user id, different scope)', async () => {
+        await expect(LoadOwnedRealtimeSession(SESSION, guest('scope-visitor-2'), provider()))
+            .rejects.toBeInstanceOf(RealtimeSessionOwnershipError);
+    });
+});

package/src/__tests__/realtimeSessions/ownedRealtimeSession.namedScoped.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { LoadOwnedRealtimeSession, RealtimeSessionOwnershipError } from '../../realtimeSessions/ownedRealtimeSession.js';
+
+// Fixture UUIDs are assembled at runtime so no literal record id appears in the source.
+const uuid = (a: string, b: string) => [a.repeat(8), b.repeat(4), '4' + b.repeat(3), '8' + b.repeat(3), b.repeat(12)].join('-');
+const NAMED = uuid('B', '1');
+const SESSION = uuid('1', '1');
+const CONVERSATION = uuid('2', '2');
+
+/** A named magic-link user (found by email) holding a link scoped to `scope`. */
+const namedScoped = (scope: string) => ({ ID: NAMED, IsMagicLinkAnonymous: false, MagicLinkScope: { ResourceID: scope } } as unknown as UserInfo);
+
+/** The named user's own session; its conversation loads with `externalID`, or not at all when `readable` is false. */
+function provider(externalID: string | null, readable = true): IMetadataProvider {
+    return {
+        GetEntityObject: vi.fn(async (entity: string) =>
+            entity === 'MJ: AI Agent Sessions'
+                ? { UserID: NAMED, ConversationID: CONVERSATION, Load: vi.fn(async () => true) }
+                : { ExternalID: externalID, Load: vi.fn(async () => readable) }),
+    } as unknown as IMetadataProvider;
+}
+
+describe('LoadOwnedRealtimeSession for a named user with a resource-scoped link', () => {
+    it('allows its own session on a conversation it can read that carries no scope stamp (one started from the Conversations app)', async () => {
+        await expect(LoadOwnedRealtimeSession(SESSION, namedScoped('res-1'), provider(null))).resolves.toBeDefined();
+    });
+    it('allows its own session on a conversation stamped with the same scope', async () => {
+        await expect(LoadOwnedRealtimeSession(SESSION, namedScoped('res-1'), provider('res-1'))).resolves.toBeDefined();
+    });
+    it('refuses its own session on a conversation stamped with another scope (a session from its other link)', async () => {
+        await expect(LoadOwnedRealtimeSession(SESSION, namedScoped('res-2'), provider('res-1'))).rejects.toBeInstanceOf(RealtimeSessionOwnershipError);
+    });
+    it('refuses when it cannot read the conversation (fail closed)', async () => {
+        await expect(LoadOwnedRealtimeSession(SESSION, namedScoped('res-1'), provider(null, false))).rejects.toBeInstanceOf(RealtimeSessionOwnershipError);
+    });
+});