@memberjunction/server 5.44.0 → 5.45.1

package/src/__tests__/twilio-telephony-service.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect, vi } from 'vitest';
+import { TwilioTelephonyService } from '../telephony/TwilioTelephonyService.js';
+import { TwilioCallMediaRegistry } from '../telephony/twilioMediaRegistry.js';
+import { TwilioCallSdk } from '@memberjunction/ai-bridge-twilio';
+import type { BaseTelephonyBridge } from '@memberjunction/ai-bridge-base';
+
+const CONFIG = { accountSid: 'AC1', authToken: 'tok', streamPublicUrl: 'wss://api.test/telephony/twilio/media' };
+
+describe('TwilioTelephonyService.buildBindSdk', () => {
+    it('binds a TwilioCallSdk factory onto the telephony driver (the live REST + media wiring seam)', () => {
+        const service = new TwilioTelephonyService(CONFIG, new TwilioCallMediaRegistry());
+        const setSdkFactory = vi.fn();
+        const fakeDriver = { SetSdkFactory: setSdkFactory } as unknown as BaseTelephonyBridge;
+
+        service.buildBindSdk()(fakeDriver);
+
+        expect(setSdkFactory).toHaveBeenCalledTimes(1);
+        const factory = setSdkFactory.mock.calls[0][0] as () => unknown;
+        expect(typeof factory).toBe('function');
+        // The factory yields a real (bound) TwilioCallSdk — proving the offline seam meets live plumbing.
+        expect(factory()).toBeInstanceOf(TwilioCallSdk);
+    });
+});

package/src/__tests__/twilioMediaRegistry.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, vi } from 'vitest';
+import { TwilioCallMediaRegistry, type ITelephonyMediaSocket } from '../telephony/twilioMediaRegistry.js';
+import type { TwilioMediaFrame } from '@memberjunction/ai-bridge-twilio';
+
+/** A fake Media-Streams socket capturing sends + tracking close. */
+function fakeSocket(): ITelephonyMediaSocket & { sent: string[]; closed: boolean } {
+    const sent: string[] = [];
+    return {
+        sent,
+        closed: false,
+        send(data: string) {
+            sent.push(data);
+        },
+        close() {
+            (this as { closed: boolean }).closed = true;
+        },
+    };
+}
+
+const mediaFrame = (payload: string): TwilioMediaFrame => ({ event: 'media', streamSid: 'MZ1', media: { payload } });
+
+describe('TwilioCallMediaRegistry', () => {
+    describe('outbound buffering', () => {
+        it('buffers outbound frames before the socket connects, then flushes on AttachSocket in order', () => {
+            const reg = new TwilioCallMediaRegistry();
+            reg.RegisterCall('CA1');
+            reg.Send('CA1', mediaFrame('a'));
+            reg.Send('CA1', mediaFrame('b'));
+
+            const sock = fakeSocket();
+            reg.AttachSocket('CA1', sock, 'MZ1');
+
+            expect(sock.sent).toHaveLength(2);
+            expect(JSON.parse(sock.sent[0]).media.payload).toBe('a');
+            expect(JSON.parse(sock.sent[1]).media.payload).toBe('b');
+        });
+
+        it('sends immediately once the socket is attached', () => {
+            const reg = new TwilioCallMediaRegistry();
+            const sock = fakeSocket();
+            reg.AttachSocket('CA1', sock, 'MZ1');
+            reg.Send('CA1', mediaFrame('c'));
+            expect(sock.sent).toHaveLength(1);
+            expect(JSON.parse(sock.sent[0]).media.payload).toBe('c');
+        });
+    });
+
+    describe('inbound dispatch', () => {
+        it('delivers inbound frames to handlers registered before the socket existed', () => {
+            const reg = new TwilioCallMediaRegistry();
+            const received: TwilioMediaFrame[] = [];
+            reg.OnFrame('CA1', (f) => received.push(f));
+
+            reg.DispatchInbound('CA1', mediaFrame('in'));
+
+            expect(received).toHaveLength(1);
+            expect(received[0].media?.payload).toBe('in');
+        });
+
+        it('captures the stream SID from a start frame and exposes it via GetStreamSid', () => {
+            const reg = new TwilioCallMediaRegistry();
+            reg.RegisterCall('CA1');
+            expect(reg.GetStreamSid('CA1')).toBe('');
+            reg.DispatchInbound('CA1', { event: 'start', streamSid: 'MZ-XYZ' });
+            expect(reg.GetStreamSid('CA1')).toBe('MZ-XYZ');
+        });
+
+        it('drops inbound frames for an unknown call (no channel) without throwing', () => {
+            const reg = new TwilioCallMediaRegistry();
+            expect(() => reg.DispatchInbound('UNKNOWN', mediaFrame('x'))).not.toThrow();
+        });
+
+        it('fans out to multiple handlers (audio + dtmf + status all registered on one call)', () => {
+            const reg = new TwilioCallMediaRegistry();
+            const h1 = vi.fn();
+            const h2 = vi.fn();
+            reg.OnFrame('CA1', h1);
+            reg.OnFrame('CA1', h2);
+            reg.DispatchInbound('CA1', mediaFrame('y'));
+            expect(h1).toHaveBeenCalledTimes(1);
+            expect(h2).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe('lifecycle', () => {
+        it('EndCall closes the socket and forgets the channel', () => {
+            const reg = new TwilioCallMediaRegistry();
+            const sock = fakeSocket();
+            reg.AttachSocket('CA1', sock, 'MZ1');
+            expect(reg.HasCall('CA1')).toBe(true);
+
+            reg.EndCall('CA1');
+
+            expect(sock.closed).toBe(true);
+            expect(reg.HasCall('CA1')).toBe(false);
+        });
+
+        it('EndCall on an unknown call is a no-op', () => {
+            const reg = new TwilioCallMediaRegistry();
+            expect(() => reg.EndCall('NOPE')).not.toThrow();
+        });
+    });
+});

package/src/__tests__/vonageMediaRegistry.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect, vi } from 'vitest';
+import { VonageCallMediaRegistry, type ITelephonyMediaSocket } from '../telephony/vonageMediaRegistry.js';
+import type { VonageControlEvent } from '@memberjunction/ai-bridge-vonage';
+
+/** A fake media socket capturing outbound BINARY audio + TEXT control frames + tracking close. */
+function fakeSocket(): ITelephonyMediaSocket & { sent: Uint8Array[]; text: string[]; closed: boolean } {
+    const sent: Uint8Array[] = [];
+    const text: string[] = [];
+    return {
+        sent,
+        text,
+        closed: false,
+        sendBinary(data: Uint8Array) {
+            sent.push(data);
+        },
+        sendText(data: string) {
+            text.push(data);
+        },
+        close() {
+            (this as { closed: boolean }).closed = true;
+        },
+    };
+}
+
+/** A small PCM16 ArrayBuffer carrying one recognizable little-endian sample, for ordering/round-trip checks. */
+const pcm = (sample: number): ArrayBuffer => {
+    const buf = new ArrayBuffer(2);
+    new DataView(buf).setInt16(0, sample, true);
+    return buf;
+};
+
+/** Vonage's outbound frame size: 20 ms @ 8 kHz / 16-bit = 320 bytes. */
+const FRAME_BYTES = 320;
+
+/** Builds an N-byte PCM ArrayBuffer whose first byte is `tag`, so frames are distinguishable. */
+const audio = (bytes: number, tag = 0): ArrayBuffer => {
+    const buf = new Uint8Array(bytes);
+    if (bytes > 0) buf[0] = tag;
+    return buf.buffer;
+};
+
+describe('VonageCallMediaRegistry', () => {
+    describe('outbound audio framing (20 ms / 320-byte slices)', () => {
+        it('buffers whole 320-byte frames before the socket connects, then flushes them on AttachSocket in order', () => {
+            const reg = new VonageCallMediaRegistry();
+            reg.RegisterCall('CALL-1');
+            reg.SendAudio('CALL-1', audio(FRAME_BYTES, 0xa1));
+            reg.SendAudio('CALL-1', audio(FRAME_BYTES, 0xb2));
+
+            const sock = fakeSocket();
+            reg.AttachSocket('CALL-1', sock);
+
+            expect(sock.sent).toHaveLength(2);
+            expect(sock.sent[0]).toHaveLength(FRAME_BYTES);
+            expect(sock.sent[0][0]).toBe(0xa1);
+            expect(sock.sent[1][0]).toBe(0xb2);
+        });
+
+        it('slices an oversized delta into multiple 320-byte frames and carries the sub-frame remainder', () => {
+            const reg = new VonageCallMediaRegistry();
+            const sock = fakeSocket();
+            reg.AttachSocket('CALL-1', sock);
+
+            // 800 bytes = two whole frames + 160 left over (held, not sent).
+            reg.SendAudio('CALL-1', audio(800));
+            expect(sock.sent).toHaveLength(2);
+            expect(sock.sent.every((f) => f.length === FRAME_BYTES)).toBe(true);
+
+            // Another 160 bytes completes the carried remainder into a third whole frame.
+            reg.SendAudio('CALL-1', audio(160));
+            expect(sock.sent).toHaveLength(3);
+            expect(sock.sent[2]).toHaveLength(FRAME_BYTES);
+        });
+
+        it('holds a sub-frame delta until enough bytes accumulate (no silence-padded partial frame)', () => {
+            const reg = new VonageCallMediaRegistry();
+            const sock = fakeSocket();
+            reg.AttachSocket('CALL-1', sock);
+            reg.SendAudio('CALL-1', audio(100));
+            expect(sock.sent).toHaveLength(0); // < one frame — nothing sent yet
+        });
+    });
+
+    describe('inbound audio dispatch', () => {
+        it('delivers inbound audio to handlers registered before the socket existed', () => {
+            const reg = new VonageCallMediaRegistry();
+            const received: number[] = [];
+            reg.OnAudio('CALL-1', (p) => received.push(new DataView(p).getInt16(0, true)));
+
+            reg.DispatchInboundAudio('CALL-1', pcm(42));
+
+            expect(received).toEqual([42]);
+        });
+
+        it('drops inbound audio for an unknown call (no channel) without throwing', () => {
+            const reg = new VonageCallMediaRegistry();
+            expect(() => reg.DispatchInboundAudio('UNKNOWN', pcm(1))).not.toThrow();
+        });
+
+        it('fans out audio to multiple handlers registered on one call', () => {
+            const reg = new VonageCallMediaRegistry();
+            const h1 = vi.fn();
+            const h2 = vi.fn();
+            reg.OnAudio('CALL-1', h1);
+            reg.OnAudio('CALL-1', h2);
+            reg.DispatchInboundAudio('CALL-1', pcm(7));
+            expect(h1).toHaveBeenCalledTimes(1);
+            expect(h2).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe('inbound control-event dispatch', () => {
+        it('delivers parsed control events (DTMF / close) to event handlers, separate from audio', () => {
+            const reg = new VonageCallMediaRegistry();
+            const events: VonageControlEvent[] = [];
+            const audio = vi.fn();
+            reg.OnEvent('CALL-1', (e) => events.push(e));
+            reg.OnAudio('CALL-1', audio);
+
+            reg.DispatchInboundEvent('CALL-1', { event: 'websocket:dtmf', digit: '5', duration: 260 });
+            reg.DispatchInboundEvent('CALL-1', { event: 'close' });
+
+            expect(audio).not.toHaveBeenCalled();
+            expect(events).toHaveLength(2);
+            expect(events[0].digit).toBe('5');
+            expect(events[1].event).toBe('close');
+        });
+
+        it('drops inbound events for an unknown call without throwing', () => {
+            const reg = new VonageCallMediaRegistry();
+            expect(() => reg.DispatchInboundEvent('UNKNOWN', { event: 'close' })).not.toThrow();
+        });
+    });
+
+    describe('barge-in flush (Clear)', () => {
+        it('sends Vonage {"action":"clear"} on the live socket and drops locally-buffered audio', () => {
+            const reg = new VonageCallMediaRegistry();
+            const sock = fakeSocket();
+            reg.AttachSocket('CALL-1', sock);
+            reg.Clear('CALL-1');
+            expect(sock.text).toEqual([JSON.stringify({ action: 'clear' })]);
+        });
+
+        it('drops outbound frames buffered before the socket connected, sending nothing on attach', () => {
+            const reg = new VonageCallMediaRegistry();
+            reg.RegisterCall('CALL-1');
+            reg.SendAudio('CALL-1', audio(FRAME_BYTES)); // a whole frame, buffered (no socket yet)
+            reg.SendAudio('CALL-1', audio(100)); // sub-frame remainder, held in partial
+            reg.Clear('CALL-1'); // barge-in before the media socket connected
+
+            const sock = fakeSocket();
+            reg.AttachSocket('CALL-1', sock);
+            expect(sock.sent).toHaveLength(0); // both the buffered frame and the partial were cleared
+        });
+
+        it('Clear on an unknown call is a no-op', () => {
+            const reg = new VonageCallMediaRegistry();
+            expect(() => reg.Clear('NOPE')).not.toThrow();
+        });
+    });
+
+    describe('lifecycle', () => {
+        it('EndCall closes the socket and forgets the channel', () => {
+            const reg = new VonageCallMediaRegistry();
+            const sock = fakeSocket();
+            reg.AttachSocket('CALL-1', sock);
+            expect(reg.HasCall('CALL-1')).toBe(true);
+
+            reg.EndCall('CALL-1');
+
+            expect(sock.closed).toBe(true);
+            expect(reg.HasCall('CALL-1')).toBe(false);
+        });
+
+        it('EndCall on an unknown call is a no-op', () => {
+            const reg = new VonageCallMediaRegistry();
+            expect(() => reg.EndCall('NOPE')).not.toThrow();
+        });
+    });
+});

package/src/__tests__/widget.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect } from 'vitest';
+import jwt from 'jsonwebtoken';
+import { createPublicKey } from 'node:crypto';
+import {
+  parseAllowedOrigins,
+  isOriginAllowed,
+  isModalityEnabled,
+  evaluateWidgetMint,
+  buildWidgetGuestClaims,
+  looksLikeBot,
+} from '../realtimeWidget/widgetCore.js';
+import { MagicLinkKeyManager } from '../auth/magicLink/MagicLinkKeys.js';
+
+describe('widget core — parseAllowedOrigins', () => {
+  it('parses a JSON array of origins', () => {
+    expect(parseAllowedOrigins('["https://a.com","https://b.com"]')).toEqual(['https://a.com', 'https://b.com']);
+  });
+
+  it('tolerates a comma-separated string', () => {
+    expect(parseAllowedOrigins('https://a.com, https://b.com')).toEqual(['https://a.com', 'https://b.com']);
+  });
+
+  it('normalizes case and strips trailing slashes', () => {
+    expect(parseAllowedOrigins('["HTTPS://Acme.COM/"]')).toEqual(['https://acme.com']);
+  });
+
+  it('returns empty (fail-closed) for null / blank / non-array JSON', () => {
+    expect(parseAllowedOrigins(null)).toEqual([]);
+    expect(parseAllowedOrigins('   ')).toEqual([]);
+    expect(parseAllowedOrigins('{"not":"an-array"}')).toEqual([]);
+  });
+});
+
+describe('widget core — isOriginAllowed (fail-closed)', () => {
+  const allowed = ['https://acme.com', 'https://www.acme.com'];
+
+  it('accepts an exact (normalized) match', () => {
+    expect(isOriginAllowed('https://acme.com', allowed)).toBe(true);
+    expect(isOriginAllowed('HTTPS://ACME.COM/', allowed)).toBe(true);
+  });
+
+  it('rejects a non-listed origin', () => {
+    expect(isOriginAllowed('https://evil.com', allowed)).toBe(false);
+    expect(isOriginAllowed('https://sub.acme.com', allowed)).toBe(false);
+  });
+
+  it('rejects a missing request origin', () => {
+    expect(isOriginAllowed(undefined, allowed)).toBe(false);
+    expect(isOriginAllowed('', allowed)).toBe(false);
+  });
+
+  it('rejects everything when the allowlist is empty (never "*")', () => {
+    expect(isOriginAllowed('https://acme.com', [])).toBe(false);
+  });
+});
+
+describe('widget core — isModalityEnabled', () => {
+  it('Both enables text and voice', () => {
+    expect(isModalityEnabled('Both', 'Text')).toBe(true);
+    expect(isModalityEnabled('Both', 'Voice')).toBe(true);
+  });
+  it('Text enables only text', () => {
+    expect(isModalityEnabled('Text', 'Text')).toBe(true);
+    expect(isModalityEnabled('Text', 'Voice')).toBe(false);
+  });
+  it('Voice enables only voice', () => {
+    expect(isModalityEnabled('Voice', 'Voice')).toBe(true);
+    expect(isModalityEnabled('Voice', 'Text')).toBe(false);
+  });
+});
+
+describe('widget core — evaluateWidgetMint', () => {
+  const base = { Status: 'Active', AllowedOrigins: '["https://acme.com"]', Modality: 'Both' };
+
+  it('passes for an active widget from an allowed origin', () => {
+    expect(evaluateWidgetMint(base, 'https://acme.com')).toEqual({ ok: true });
+  });
+
+  it('rejects a disabled widget', () => {
+    expect(evaluateWidgetMint({ ...base, Status: 'Disabled' }, 'https://acme.com')).toEqual({
+      ok: false,
+      errorCode: 'disabled',
+    });
+  });
+
+  it('rejects a disallowed origin', () => {
+    expect(evaluateWidgetMint(base, 'https://evil.com')).toEqual({ ok: false, errorCode: 'origin_not_allowed' });
+  });
+
+  it('rejects a missing origin (fail-closed)', () => {
+    expect(evaluateWidgetMint(base, undefined)).toEqual({ ok: false, errorCode: 'origin_not_allowed' });
+  });
+});
+
+describe('widget core — buildWidgetGuestClaims', () => {
+  const args = {
+    issuer: 'https://mj.example.com',
+    audience: 'mj-magic-link',
+    widgetId: 'WIDGET-123',
+    sessionId: 'sess-abc',
+    anonymousEmail: 'anonymous@magic-link.local',
+    applicationId: 'APP-1',
+    guestRoleName: 'Widget Guest',
+    nowSeconds: 1_000_000,
+    ttlSeconds: 900,
+  };
+
+  it('marks the session anonymous + magic-link and binds the widget id', () => {
+    const claims = buildWidgetGuestClaims(args);
+    expect(claims.mj_anon).toBe(true);
+    expect(claims.mj_magic_link).toBe(true);
+    expect(claims.mj_widget_id).toBe('WIDGET-123');
+  });
+
+  it('scopes to the application + guest role and the configured anon email', () => {
+    const claims = buildWidgetGuestClaims(args);
+    expect(claims.mj_app_id).toBe('APP-1');
+    expect(claims.mj_role).toBe('Widget Guest');
+    expect(claims.email).toBe('anonymous@magic-link.local');
+    expect(claims.sub).toBe('magic-link|sess-abc');
+    expect(claims.mj_sid).toBe('sess-abc');
+  });
+
+  it('carries a single scope entry for the guest grant', () => {
+    const claims = buildWidgetGuestClaims(args);
+    expect(claims.mj_scopes).toHaveLength(1);
+    expect(claims.mj_scopes?.[0]).toMatchObject({ appId: 'APP-1', role: 'Widget Guest' });
+  });
+
+  it('sets exp = iat + ttl', () => {
+    const claims = buildWidgetGuestClaims(args);
+    expect(claims.iat).toBe(1_000_000);
+    expect(claims.exp).toBe(1_000_900);
+  });
+});
+
+describe('widget core — RS256 sign + verify roundtrip (reuses MagicLinkKeyManager)', () => {
+  it('mints a widget guest token that verifies against the published JWKS with the widget claim intact', () => {
+    const km = MagicLinkKeyManager.Instance;
+    km.Initialize(); // ephemeral keypair (idempotent if already initialized in-process)
+
+    const claims = buildWidgetGuestClaims({
+      issuer: 'https://mj.example.com',
+      audience: 'mj-magic-link',
+      widgetId: 'WIDGET-XYZ',
+      sessionId: 'sess-roundtrip',
+      anonymousEmail: 'anonymous@magic-link.local',
+      applicationId: 'APP-9',
+      guestRoleName: 'Widget Guest',
+      nowSeconds: Math.floor(Date.now() / 1000),
+      ttlSeconds: 900,
+    });
+    const token = km.Sign(claims);
+
+    const publicKey = createPublicKey({ key: km.GetJWKS().keys[0] as object, format: 'jwk' });
+    const decoded = jwt.verify(token, publicKey, { algorithms: ['RS256'], audience: 'mj-magic-link' }) as jwt.JwtPayload;
+
+    expect(decoded.mj_widget_id).toBe('WIDGET-XYZ');
+    expect(decoded.mj_anon).toBe(true);
+    expect(decoded.mj_magic_link).toBe(true);
+    expect(decoded.mj_app_id).toBe('APP-9');
+  });
+
+  it('rejects a tampered widget token', () => {
+    const km = MagicLinkKeyManager.Instance;
+    km.Initialize();
+    const claims = buildWidgetGuestClaims({
+      issuer: 'https://mj.example.com',
+      audience: 'mj-magic-link',
+      widgetId: 'W',
+      sessionId: 's',
+      anonymousEmail: 'anonymous@magic-link.local',
+      applicationId: 'A',
+      guestRoleName: 'Widget Guest',
+      nowSeconds: Math.floor(Date.now() / 1000),
+      ttlSeconds: 900,
+    });
+    const token = km.Sign(claims);
+    const publicKey = createPublicKey({ key: km.GetJWKS().keys[0] as object, format: 'jwk' });
+    const tampered = token.slice(0, -3) + 'AAA';
+    expect(() => jwt.verify(tampered, publicKey, { algorithms: ['RS256'] })).toThrow();
+  });
+});
+
+describe('widget core — looksLikeBot (W6 mint heuristic)', () => {
+  it('flags a missing / blank user-agent as a bot', () => {
+    expect(looksLikeBot(undefined)).toBe(true);
+    expect(looksLikeBot(null)).toBe(true);
+    expect(looksLikeBot('   ')).toBe(true);
+  });
+
+  it('flags known automation user-agents', () => {
+    expect(looksLikeBot('curl/8.4.0')).toBe(true);
+    expect(looksLikeBot('python-requests/2.31')).toBe(true);
+    expect(looksLikeBot('Googlebot/2.1 (+http://www.google.com/bot.html)')).toBe(true);
+    expect(looksLikeBot('Mozilla/5.0 (compatible; bingbot/2.0)')).toBe(true);
+    expect(looksLikeBot('HeadlessChrome/120.0.0.0')).toBe(true);
+  });
+
+  it('allows real browser user-agents', () => {
+    expect(looksLikeBot('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36')).toBe(false);
+    expect(looksLikeBot('Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 Version/17.0 Mobile/15E148 Safari/604.1')).toBe(false);
+  });
+});

package/src/__tests__/widgetGuestElevation.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import type { DatabaseProviderBase, UserInfo } from '@memberjunction/core';
+import { resolveWidgetGuestRunContext, elevateUserPayload } from '../realtimeWidget/widgetGuestElevation.js';
+import type { UserPayload } from '../types.js';
+
+/** A provider stub — the guard paths under test return before ever touching the provider. */
+const providerStub = {} as DatabaseProviderBase;
+
+/** Builds a UserPayload whose synthesized userRecord carries the given guest flags. */
+function payloadWith(userRecord: Partial<UserInfo>): UserPayload {
+  return { email: 'anonymous@magic-link.local', userRecord, sessionId: 'sess-123' };
+}
+
+describe('widgetGuestElevation — resolveWidgetGuestRunContext (guard paths, no DB)', () => {
+  it('returns null for a normal authenticated user (not anonymous)', async () => {
+    const result = await resolveWidgetGuestRunContext(payloadWith({ IsMagicLinkAnonymous: false }), providerStub);
+    expect(result).toBeNull();
+  });
+
+  it('returns null for an anonymous magic-link session that is NOT a widget guest (no WidgetGuestContext)', async () => {
+    const result = await resolveWidgetGuestRunContext(
+      payloadWith({ IsMagicLinkAnonymous: true, WidgetGuestContext: undefined }),
+      providerStub,
+    );
+    expect(result).toBeNull();
+  });
+
+  it('returns null when userRecord is absent', async () => {
+    const result = await resolveWidgetGuestRunContext({ email: '', userRecord: undefined, sessionId: 's' }, providerStub);
+    expect(result).toBeNull();
+  });
+});
+
+describe('widgetGuestElevation — elevateUserPayload', () => {
+  it('swaps in the elevated principal while preserving the guest sessionId for PubSub routing', () => {
+    const guestPayload = payloadWith({ IsMagicLinkAnonymous: true });
+    const systemUser = { Email: 'system@system.org' } as UserInfo;
+
+    const elevated = elevateUserPayload(guestPayload, systemUser);
+
+    expect(elevated.userRecord).toBe(systemUser);
+    expect(elevated.email).toBe('system@system.org');
+    expect(elevated.isSystemUser).toBe(true);
+    // The session id MUST be preserved so progress/streaming still routes to the guest's websocket.
+    expect(elevated.sessionId).toBe('sess-123');
+  });
+
+  it('does not mutate the original guest payload', () => {
+    const guestPayload = payloadWith({ IsMagicLinkAnonymous: true });
+    const systemUser = { Email: 'system@system.org' } as UserInfo;
+
+    elevateUserPayload(guestPayload, systemUser);
+
+    expect(guestPayload.isSystemUser).toBeUndefined();
+    expect(guestPayload.email).toBe('anonymous@magic-link.local');
+  });
+});