@memberjunction/server 5.44.0 → 5.45.0

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

package/src/__tests__/widgetHostIdentity.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from 'vitest';
+import jwt from 'jsonwebtoken';
+import { generateKeyPairSync } from 'node:crypto';
+import { verifyHostAssertion, extractHostIdentity } from '../realtimeWidget/host-identity.js';
+import { buildWidgetGuestClaims } from '../realtimeWidget/widgetCore.js';
+
+/** A throwaway RSA keypair for signing test host assertions. */
+function keypair(): { privatePem: string; publicPem: string } {
+    const { privateKey, publicKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });
+    return {
+        privatePem: privateKey.export({ type: 'pkcs8', format: 'pem' }) as string,
+        publicPem: publicKey.export({ type: 'spki', format: 'pem' }) as string,
+    };
+}
+
+const WIDGET_KEY = 'pk_live_acme';
+
+function sign(privatePem: string, claims: Record<string, unknown>, opts: jwt.SignOptions = {}): string {
+    return jwt.sign(claims, privatePem, { algorithm: 'RS256', audience: WIDGET_KEY, expiresIn: '5m', ...opts });
+}
+
+describe('verifyHostAssertion', () => {
+    it('accepts a valid host assertion and extracts the identity', () => {
+        const kp = keypair();
+        const token = sign(kp.privatePem, { email: 'jane@acme.com', given_name: 'Jane', family_name: 'Doe', sub: 'host-123' });
+        const result = verifyHostAssertion(token, kp.publicPem, WIDGET_KEY);
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.identity).toMatchObject({ email: 'jane@acme.com', firstName: 'Jane', lastName: 'Doe', hostUserId: 'host-123' });
+        }
+    });
+
+    it('rejects a missing assertion', () => {
+        const kp = keypair();
+        expect(verifyHostAssertion(undefined, kp.publicPem, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'missing' });
+    });
+
+    it('rejects when no host key is configured (fail-closed)', () => {
+        const kp = keypair();
+        const token = sign(kp.privatePem, { email: 'x@y.com' });
+        expect(verifyHostAssertion(token, undefined, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'no_key' });
+    });
+
+    it('rejects a signature from the wrong key', () => {
+        const signer = keypair();
+        const other = keypair();
+        const token = sign(signer.privatePem, { email: 'x@y.com' });
+        expect(verifyHostAssertion(token, other.publicPem, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'bad_signature' });
+    });
+
+    it('rejects a wrong-audience assertion', () => {
+        const kp = keypair();
+        const token = sign(kp.privatePem, { email: 'x@y.com' }, { audience: 'pk_live_someone_else' });
+        expect(verifyHostAssertion(token, kp.publicPem, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'bad_signature' });
+    });
+
+    it('rejects an expired assertion', () => {
+        const kp = keypair();
+        const token = sign(kp.privatePem, { email: 'x@y.com' }, { expiresIn: -10 });
+        expect(verifyHostAssertion(token, kp.publicPem, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'expired' });
+    });
+
+    it('rejects an assertion with no email', () => {
+        const kp = keypair();
+        const token = sign(kp.privatePem, { given_name: 'NoEmail' });
+        expect(verifyHostAssertion(token, kp.publicPem, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'no_email' });
+    });
+
+    it('rejects an assertion with no exp (unbounded lifetime)', () => {
+        const kp = keypair();
+        // Sign directly with no expiresIn so the token carries iat but no exp.
+        const token = jwt.sign({ email: 'x@y.com' }, kp.privatePem, { algorithm: 'RS256', audience: WIDGET_KEY });
+        expect(verifyHostAssertion(token, kp.publicPem, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'expired' });
+    });
+
+    it('rejects an assertion older than the maxAge cap even when its exp is still in the future', () => {
+        const kp = keypair();
+        const nowSec = Math.floor(Date.now() / 1000);
+        // iat one hour ago (well past the 10m maxAge) with a far-future exp — the age cap must still reject it.
+        const token = jwt.sign({ email: 'x@y.com', iat: nowSec - 3600, exp: nowSec + 3600 }, kp.privatePem, {
+            algorithm: 'RS256',
+            audience: WIDGET_KEY,
+        });
+        expect(verifyHostAssertion(token, kp.publicPem, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'expired' });
+    });
+});
+
+describe('buildWidgetGuestClaims with hostIdentity', () => {
+    it('carries the host identity as INFORMATIONAL claims but keeps the Anonymous principal email', () => {
+        const claims = buildWidgetGuestClaims({
+            issuer: 'iss',
+            audience: 'mj-magic-link',
+            widgetId: 'W',
+            sessionId: 's',
+            anonymousEmail: 'anonymous@magic-link.local',
+            applicationId: 'A',
+            guestRoleName: 'Widget Guest',
+            nowSeconds: 1000,
+            ttlSeconds: 900,
+            hostIdentity: { email: 'jane@acme.com', firstName: 'Jane', lastName: 'Doe' },
+        });
+        // Principal-resolving email stays anonymous (no escalation into a real account).
+        expect(claims.email).toBe('anonymous@magic-link.local');
+        expect(claims.mj_anon).toBe(true);
+        // Host identity rides as informational claims.
+        expect(claims.mj_host_email).toBe('jane@acme.com');
+        expect(claims.given_name).toBe('Jane');
+        expect(claims.name).toBe('Jane Doe');
+    });
+});
+
+describe('extractHostIdentity', () => {
+    it('tolerates firstName/lastName fallbacks', () => {
+        const id = extractHostIdentity({ email: 'a@b.com', firstName: 'Al', lastName: 'Bo' });
+        expect(id).toMatchObject({ email: 'a@b.com', firstName: 'Al', lastName: 'Bo' });
+    });
+});