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

package/src/__tests__/DuplicateEntryCheckResolver.test.ts

@@ -0,0 +1,300 @@
+// type-graphql decorators call `Reflect.getMetadata`, which only exists once this polyfill is
+// loaded. MUST precede any import that pulls in the resolver file.
+import 'reflect-metadata';
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+/** The slice of `APIKeyEngine.Authorize` that ResolverBase.CheckAPIKeyScopeAuthorization calls. */
+type AuthorizeFn = (
+  apiKeyHash: string,
+  application: string,
+  scopePath: string,
+  resource: string
+) => Promise<{ Allowed: boolean; Reason: string }>;
+
+const { mockAuthorize, mockLogError } = vi.hoisted(() => ({
+  mockAuthorize: vi.fn<AuthorizeFn>(),
+  mockLogError: vi.fn<(message: string) => void>(),
+}));
+
+// As in RunDecisionResolver.test.ts: vitest's esbuild transform does not apply
+// `emitDecoratorMetadata`, so the decorators are no-ops and the resolver runs as a plain class.
+vi.mock('type-graphql', () => {
+  const noopDecorator = () => () => undefined;
+  return {
+    Resolver: noopDecorator, Mutation: noopDecorator, Query: noopDecorator, Subscription: noopDecorator,
+    ObjectType: noopDecorator, InputType: noopDecorator, Field: noopDecorator, Arg: noopDecorator,
+    Args: noopDecorator, Ctx: noopDecorator, PubSub: noopDecorator, Root: noopDecorator,
+    Directive: noopDecorator, Authorized: noopDecorator, UseMiddleware: noopDecorator,
+    createUnionType: () => class {},
+    AuthorizationError: class AuthorizationError extends Error {
+      constructor(message?: string) {
+        super(message);
+        this.name = 'AuthorizationError';
+      }
+    },
+    Float: class {}, Int: class {}, ID: class {},
+  };
+});
+
+// Only logging is replaced, so a test can tell a logged fault from a quiet answer.
+vi.mock('@memberjunction/core', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return { ...actual, LogError: mockLogError };
+});
+
+// Only the API-key engine is replaced; ResolverBase's scope check itself is the production code.
+vi.mock('@memberjunction/api-keys', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return { ...actual, GetAPIKeyEngine: () => ({ Authorize: mockAuthorize }) };
+});
+
+// The resolver's tests replace the detector through CreateEntryChecker, so the detector package
+// is never exercised here; it has its own specs.
+vi.mock('@memberjunction/ai-vector-dupe', () => ({ DuplicateRecordDetector: class {} }));
+
+import { EntityInfo, Metadata, UserInfo } from '@memberjunction/core';
+import { UserCache } from '@memberjunction/generic-database-provider';
+import type { DuplicateEntryCheckResult } from '@memberjunction/ai-vector-dupe';
+import {
+  DUPLICATE_ENTRY_CHECK_MAX_VALUES_JSON_LENGTH,
+  DuplicateEntryCheckResolver,
+  type DuplicateEntryChecker,
+} from '../resolvers/DuplicateEntryCheckResolver.js';
+import type { UserPayload } from '../types.js';
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+const USER = new UserInfo(null, {
+  ID: 'user-1',
+  Name: 'Entry Person',
+  Email: 'person@example.com',
+  UserRoles: [{ UserID: 'user-1', RoleID: 'role-ui' }],
+});
+const SYSTEM_USER = new UserInfo(null, { ID: 'user-system', Name: 'System', Email: 'system@example.com' });
+
+/** An entity the user's role may read. */
+const ACCOUNTS = new EntityInfo({
+  ID: 'entity-accounts',
+  Name: 'Accounts',
+  Status: 'Active',
+  Fields: [
+    { Name: 'ID', Type: 'uniqueidentifier', IsPrimaryKey: true },
+    { Name: 'Name', Type: 'nvarchar', IsNameField: true, AllowUpdateAPI: true },
+    { Name: 'City', Type: 'nvarchar', AllowUpdateAPI: true },
+    { Name: 'Owner', Type: 'nvarchar', AllowUpdateAPI: false },
+    { Name: '__mj_CreatedAt', Type: 'datetimeoffset', AllowUpdateAPI: false },
+  ],
+  EntityPermissions: [{ RoleID: 'role-ui', CanRead: true }],
+});
+
+/** An entity only another role may read. */
+const PAYROLL = new EntityInfo({
+  ID: 'entity-payroll',
+  Name: 'Payroll',
+  Status: 'Active',
+  Fields: [{ Name: 'ID', Type: 'uniqueidentifier', IsPrimaryKey: true }],
+  EntityPermissions: [{ RoleID: 'role-finance', CanRead: true }],
+});
+
+const CHECKED: DuplicateEntryCheckResult = {
+  Status: 'Checked',
+  Candidates: [{ RecordID: 'acct-7', DisplayName: 'Acme Corp', VectorScore: 0.93, Probability: 0.81 }],
+  ElapsedMs: 212,
+};
+
+/** A session authenticated by JWT: no API key, so no scope check. */
+const sessionPayload = (): UserPayload => ({ email: USER.Email, userRecord: USER, sessionId: 'session-1' });
+/** A session authenticated by an MJ API key: scope-checked. */
+const apiKeyPayload = (): UserPayload => ({ ...sessionPayload(), apiKeyId: 'key-1', apiKeyHash: 'hash-1' });
+
+/** The resolver with its detector replaced by a double. */
+class TestResolver extends DuplicateEntryCheckResolver {
+  public readonly Checker = { CheckRecordValues: vi.fn<DuplicateEntryChecker['CheckRecordValues']>() };
+
+  protected override CreateEntryChecker(): DuplicateEntryChecker {
+    return this.Checker;
+  }
+}
+
+let resolver: TestResolver;
+
+const check = (entityName: string, valuesJSON: string, payload: UserPayload = sessionPayload()) =>
+  resolver.RunEntryCheck(entityName, valuesJSON, payload, null);
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  mockAuthorize.mockReset();
+  mockLogError.mockReset();
+  vi.spyOn(Metadata.prototype, 'EntityByName').mockImplementation((name: string) =>
+    [ACCOUNTS, PAYROLL].find(e => e.Name.toLowerCase() === name.trim().toLowerCase())
+  );
+  vi.spyOn(UserCache.prototype, 'GetSystemUser').mockReturnValue(SYSTEM_USER);
+  resolver = new TestResolver();
+  resolver.Checker.CheckRecordValues.mockResolvedValue(CHECKED);
+});
+
+// ─── Authorization ───────────────────────────────────────────────────────────
+
+/** The scope checks made, other than the full_access fast path, as [scope, resource]. */
+const scopeChecks = () => mockAuthorize.mock.calls.filter(call => call[2] !== 'full_access').map(call => [call[2], call[3]]);
+
+describe('CheckDuplicateEntry: authorization', () => {
+  it('answers NotAuthorized, without logging, for a user who cannot read the entity', async () => {
+    const result = await check('Payroll', '{"ID":"x"}');
+
+    expect(result.Status).toBe('NotAuthorized');
+    expect(result.ErrorMessage).toContain('does not have read permissions on Payroll');
+    expect(result.Candidates).toEqual([]);
+    expect(resolver.Checker.CheckRecordValues).not.toHaveBeenCalled();
+    expect(mockLogError).not.toHaveBeenCalled();
+  });
+
+  it('fails an unknown entity without running the check', async () => {
+    const result = await check('No Such Entity', '{}');
+
+    expect(result).toMatchObject({ Status: 'Failed', ErrorMessage: 'Entity not found in metadata' });
+    expect(resolver.Checker.CheckRecordValues).not.toHaveBeenCalled();
+  });
+
+  it('applies the view:run API-key scope for the entity, and a denial is a status', async () => {
+    mockAuthorize.mockResolvedValue({ Allowed: false, Reason: 'scope not granted' });
+
+    const result = await check('Accounts', '{"Name":"Acme"}', apiKeyPayload());
+
+    expect(scopeChecks()).toEqual([['view:run', 'Accounts']]);
+    expect(result.Status).toBe('NotAuthorized');
+    expect(result.ErrorMessage).toContain("requires the 'view:run' scope");
+    expect(resolver.Checker.CheckRecordValues).not.toHaveBeenCalled();
+    expect(mockLogError).not.toHaveBeenCalled();
+  });
+
+  it('also requires prompt:execute, so a read-only key cannot spend on model calls', async () => {
+    mockAuthorize.mockImplementation(async (_hash, _app, scopePath) =>
+      scopePath === 'view:run' ? { Allowed: true, Reason: '' } : { Allowed: false, Reason: 'scope not granted' }
+    );
+
+    const result = await check('Accounts', '{"Name":"Acme"}', apiKeyPayload());
+
+    expect(scopeChecks()).toEqual([['view:run', 'Accounts'], ['prompt:execute', '*']]);
+    expect(result.Status).toBe('NotAuthorized');
+    expect(result.ErrorMessage).toContain("requires the 'prompt:execute' scope");
+    expect(resolver.Checker.CheckRecordValues).not.toHaveBeenCalled();
+  });
+
+  it('runs the check for a key holding both scopes', async () => {
+    mockAuthorize.mockImplementation(async (_hash, _app, scopePath) =>
+      ({ Allowed: scopePath !== 'full_access', Reason: '' })
+    );
+
+    const result = await check('Accounts', '{"Name":"Acme"}', apiKeyPayload());
+
+    expect(scopeChecks()).toEqual([['view:run', 'Accounts'], ['prompt:execute', '*']]);
+    expect(result.Status).toBe('Checked');
+  });
+});
+
+// ─── The values ──────────────────────────────────────────────────────────────
+
+describe('CheckDuplicateEntry: the values', () => {
+  it('returns an error status, not a throw, for values that are not JSON', async () => {
+    const result = await check('Accounts', '{ Name: ');
+
+    expect(result.Status).toBe('Failed');
+    expect(result.ErrorMessage).toMatch(/^valuesJSON is not valid JSON: /);
+    expect(resolver.Checker.CheckRecordValues).not.toHaveBeenCalled();
+  });
+
+  it('returns an error status for JSON that is not an object', async () => {
+    const result = await check('Accounts', '["Acme"]');
+
+    expect(result).toMatchObject({ Status: 'Failed', ErrorMessage: 'valuesJSON must be the JSON of an object of field values' });
+  });
+
+  it('ignores the fields the entity does not have, and keys the rest by the real field name', async () => {
+    await check('Accounts', JSON.stringify({ name: 'Acme', City: 'Boston', Revenue: 5, NotAField: 'x' }));
+
+    expect(resolver.Checker.CheckRecordValues).toHaveBeenCalledWith('Accounts', { Name: 'Acme', City: 'Boston' }, USER);
+  });
+
+  it('ignores primary keys, read-only fields and MJ system fields', async () => {
+    await check('Accounts', JSON.stringify({ ID: 'acct-7', Name: 'Acme', Owner: 'someone', __mj_CreatedAt: '2026-01-01' }));
+
+    expect(resolver.Checker.CheckRecordValues).toHaveBeenCalledWith('Accounts', { Name: 'Acme' }, USER);
+  });
+
+  it('accepts strings, numbers, booleans and null', async () => {
+    await check('Accounts', JSON.stringify({ Name: 'Acme', City: null, Revenue: 5, Active: true }));
+
+    expect(resolver.Checker.CheckRecordValues).toHaveBeenCalledWith('Accounts', { Name: 'Acme', City: null }, USER);
+  });
+
+  it.each([
+    ['an array', { Name: ['Acme', 'Corp'] }],
+    ['an object', { Name: { first: 'Acme' } }],
+  ])('refuses a value that is %s', async (_kind, values) => {
+    const result = await check('Accounts', JSON.stringify(values));
+
+    expect(result).toMatchObject({ Status: 'Failed', ErrorMessage: "valuesJSON field 'Name' must be a string, number, boolean or null" });
+    expect(resolver.Checker.CheckRecordValues).not.toHaveBeenCalled();
+  });
+
+  it('refuses a value of an unknown field that is not a scalar', async () => {
+    const result = await check('Accounts', JSON.stringify({ Name: 'Acme', Extra: [1, 2, 3] }));
+
+    expect(result.Status).toBe('Failed');
+    expect(resolver.Checker.CheckRecordValues).not.toHaveBeenCalled();
+  });
+
+  it('accepts valuesJSON up to DUPLICATE_ENTRY_CHECK_MAX_VALUES_JSON_LENGTH characters and refuses one more', async () => {
+    const padding = DUPLICATE_ENTRY_CHECK_MAX_VALUES_JSON_LENGTH - JSON.stringify({ Name: '' }).length;
+    const atLimit = JSON.stringify({ Name: 'x'.repeat(padding) });
+    const overLimit = JSON.stringify({ Name: 'x'.repeat(padding + 1) });
+    expect(atLimit).toHaveLength(DUPLICATE_ENTRY_CHECK_MAX_VALUES_JSON_LENGTH);
+
+    expect((await check('Accounts', atLimit)).Status).toBe('Checked');
+    const refused = await check('Accounts', overLimit);
+
+    expect(refused).toMatchObject({
+      Status: 'Failed',
+      ErrorMessage: `valuesJSON is ${DUPLICATE_ENTRY_CHECK_MAX_VALUES_JSON_LENGTH + 1} characters; the limit is ${DUPLICATE_ENTRY_CHECK_MAX_VALUES_JSON_LENGTH}`,
+    });
+    expect(resolver.Checker.CheckRecordValues).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps the limit to a few KB', () => {
+    expect(DUPLICATE_ENTRY_CHECK_MAX_VALUES_JSON_LENGTH).toBeLessThanOrEqual(32 * 1024);
+  });
+});
+
+// ─── The result ──────────────────────────────────────────────────────────────
+
+describe('CheckDuplicateEntry: the result', () => {
+  it('returns the detector result', async () => {
+    const result = await check('Accounts', '{"Name":"Acme"}');
+
+    expect(result).toEqual({
+      Status: 'Checked',
+      ErrorMessage: undefined,
+      Candidates: [{ RecordID: 'acct-7', DisplayName: 'Acme Corp', VectorScore: 0.93, Probability: 0.81 }],
+      ElapsedMs: 212,
+    });
+  });
+
+  it('passes NotConfigured through', async () => {
+    resolver.Checker.CheckRecordValues.mockResolvedValue({ Status: 'NotConfigured', Candidates: [], ElapsedMs: 3 });
+
+    const result = await check('Accounts', '{"Name":"Acme"}');
+
+    expect(result).toMatchObject({ Status: 'NotConfigured', Candidates: [] });
+  });
+
+  it('returns Failed, not a throw, when the check throws, and logs it', async () => {
+    resolver.Checker.CheckRecordValues.mockRejectedValue(new Error('vector index unreachable'));
+
+    const result = await check('Accounts', '{"Name":"Acme"}');
+
+    expect(result).toMatchObject({ Status: 'Failed', ErrorMessage: 'vector index unreachable', Candidates: [] });
+    expect(mockLogError).toHaveBeenCalledTimes(1);
+  });
+});

package/src/__tests__/EntityRecordNameResolver.fieldSecurity.test.ts

@@ -7,43 +7,22 @@ import type { DatabaseProviderBase, EntityInfo, UserInfo } from '@memberjunction
 import { EntityRecordNameResolver } from '../resolvers/EntityRecordNameResolver.js';
 
 /**
- * `GetEntityRecordName` must not hand back a name the caller cannot READ.
- *
- * This resolver predates field-level security and took no user context at all, which made it an
- * open side channel: the name never travelled through `MapFieldNamesToCodeNames`, the boundary
- * that strips denied fields, so a caller denied READ on an entity's name field could still obtain
- * that name from here.
- *
- * FLS turned the latent gap into a live bypass, and the shape of it is worth remembering: the
- * form-field FK control falls through to this query PRECISELY WHEN the joined display column is
- * denied. The fallback that exists to handle a denial was the thing that defeated it. Found in
- * manual Phase 5 testing — a Contract form showed its Client's name while the grid, correctly,
- * did not.
+ * `GetEntityRecordName` hands the acting user to the provider, which applies field- and row-level
+ * security for them, and reports a withheld name exactly as it reports a missing record. The
+ * field-level rule itself is covered by MJCore's DatabaseProviderBase record-name tests.
  */
 
-const DENIED_USER = { ID: 'u-1', Email: 'restricted@test' } as unknown as UserInfo;
+const ACTING_USER = { ID: 'u-1', Email: 'restricted@test' } as unknown as UserInfo;
 
-/** An entity whose name field is denied or allowed, per the flag. */
-function entityInfo(opts: { fls: boolean; deniedNames?: string[]; nameField?: string }): EntityInfo {
-    const nameFieldName = opts.nameField ?? 'Name';
-    return {
-        Name: 'Clients',
-        EnableFieldLevelSecurity: opts.fls,
-        Fields: [
-            { Name: 'ID', IsNameField: false },
-            { Name: nameFieldName, IsNameField: true },
-            { Name: 'Industry', IsNameField: false },
-        ],
-        GetDeniedReadFields: () => new Set(opts.deniedNames ?? []),
-    } as unknown as EntityInfo;
-}
+const ENTITY = { Name: 'Clients' } as unknown as EntityInfo;
 
-/** A provider that would happily return the name — the resolver must decide not to ask. */
-function providerWith(entity: EntityInfo, getName = vi.fn().mockResolvedValue('Acme Manufacturing')) {
+/** A provider whose lookup answers with `name` ('' when it withholds or finds nothing). */
+function providerAnswering(name: string) {
+    const getName = vi.fn().mockResolvedValue(name);
     return {
-        Entities: [entity],
-        GetEntityRecordName: getName,
-    } as unknown as DatabaseProviderBase & { GetEntityRecordName: typeof getName };
+        md: { Entities: [ENTITY], GetEntityRecordName: getName } as unknown as DatabaseProviderBase,
+        getName,
+    };
 }
 
 /** Exposes the inner method so the test does not need a GraphQL context. */
@@ -57,62 +36,38 @@ class Probe extends EntityRecordNameResolver {
 
 const KEY = new CompositeKey([{ FieldName: 'ID', Value: 'c-1' }]);
 
-describe('GetEntityRecordName — field-security gate', () => {
-    it('withholds the name when the name field is read-denied', async () => {
-        const getName = vi.fn().mockResolvedValue('Acme Manufacturing');
-        const md = providerWith(entityInfo({ fls: true, deniedNames: ['name'] }), getName);
+describe('GetEntityRecordName — security is applied for the acting user', () => {
+    it('passes the acting user to the provider lookup', async () => {
+        const { md, getName } = providerAnswering('Acme Manufacturing');
 
-        const result = await new Probe().Inner(md, 'Clients', KEY, DENIED_USER);
+        await new Probe().Inner(md, 'Clients', KEY, ACTING_USER);
 
-        expect(result.Success).toBe(false);
-        expect(result.RecordName).toBeUndefined();
-        // Not merely filtered after the fact — the lookup must not run at all. The provider's
-        // record-name cache is keyed by entity + primary key and NOT by user, so a name fetched
-        // here would be visible to any later caller.
-        expect(getName).not.toHaveBeenCalled();
+        expect(getName).toHaveBeenCalledWith('Clients', expect.anything(), ACTING_USER);
     });
 
-    it('returns the name when the user may read the name field', async () => {
-        const md = providerWith(entityInfo({ fls: true, deniedNames: ['industry'] }));
+    it('returns the name the provider allows', async () => {
+        const { md } = providerAnswering('Acme Manufacturing');
 
-        const result = await new Probe().Inner(md, 'Clients', KEY, DENIED_USER);
+        const result = await new Probe().Inner(md, 'Clients', KEY, ACTING_USER);
 
         expect(result.Success).toBe(true);
         expect(result.RecordName).toBe('Acme Manufacturing');
     });
 
-    it('is inert when the entity has field security switched off', async () => {
-        // Nearly every entity. A denial set that would otherwise match must not apply.
-        const md = providerWith(entityInfo({ fls: false, deniedNames: ['name'] }));
+    it('reports a withheld name as unsuccessful, with no name', async () => {
+        const { md } = providerAnswering('');
 
-        const result = await new Probe().Inner(md, 'Clients', KEY, DENIED_USER);
-
-        expect(result.Success).toBe(true);
-        expect(result.RecordName).toBe('Acme Manufacturing');
-    });
-
-    it('honours a designated name field that is not literally called "Name"', async () => {
-        const md = providerWith(entityInfo({ fls: true, nameField: 'Title', deniedNames: ['title'] }));
-
-        const result = await new Probe().Inner(md, 'Clients', KEY, DENIED_USER);
+        const result = await new Probe().Inner(md, 'Clients', KEY, ACTING_USER);
 
         expect(result.Success).toBe(false);
+        expect(result.RecordName).toBeUndefined();
     });
 
-    it('passes the acting user to the provider so row-level security has an identity', async () => {
-        const getName = vi.fn().mockResolvedValue('Acme Manufacturing');
-        const md = providerWith(entityInfo({ fls: true }), getName);
-
-        await new Probe().Inner(md, 'Clients', KEY, DENIED_USER);
+    it('does not disclose which of "missing" or "restricted" applies', async () => {
+        const { md } = providerAnswering('');
 
-        expect(getName).toHaveBeenCalledWith('Clients', expect.anything(), DENIED_USER);
-    });
+        const result = await new Probe().Inner(md, 'Clients', KEY, ACTING_USER);
 
-    it('does not disclose which of "missing" or "restricted" applies', async () => {
-        // The denial status must read the same as a genuine not-found, so the query cannot be
-        // used to probe for which entities carry restricted name fields.
-        const denied = await new Probe().Inner(
-            providerWith(entityInfo({ fls: true, deniedNames: ['name'] })), 'Clients', KEY, DENIED_USER);
-        expect(denied.Status).not.toMatch(/denied|permission|restricted|field.security/i);
+        expect(result.Status).not.toMatch(/denied|permission|restricted|field.security|RLS/i);
     });
 });

package/src/__tests__/HumanHandoffResolver.test.ts

@@ -0,0 +1,233 @@
+// type-graphql decorators on the resolver call Reflect.getMetadata, which only exists when this polyfill
+// is loaded first. Vitest does not bring it in automatically — this MUST precede the resolver import.
+import 'reflect-metadata';
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+
+const h = vi.hoisted(() => ({
+  configure: vi.fn(),
+  listOffersForUser: vi.fn(),
+  acceptOffer: vi.fn(),
+  declineOffer: vi.fn(),
+  notificationConfig: vi.fn(async () => undefined),
+  sendNotification: vi.fn(async () => ({ success: true, deliveryChannels: { inApp: true, email: false, sms: false } })),
+}));
+
+vi.mock('@memberjunction/livekit-room-server', () => ({
+  RoomHandoffEngine: {
+    Instance: {
+      Configure: h.configure,
+      ListOffersForUser: h.listOffersForUser,
+      AcceptOffer: h.acceptOffer,
+      DeclineOffer: h.declineOffer,
+    },
+  },
+  LiveKitSipService: class {},
+}));
+vi.mock('@memberjunction/notifications', () => ({
+  NotificationEngine: { Instance: { Config: h.notificationConfig, SendNotification: h.sendNotification } },
+}));
+
+import {
+  HumanHandoffResolver,
+  HandoffOfferChangeFilter,
+  NotificationHandoffNotifier,
+  PubSubHandoffPublisher,
+  SetHandoffOfferPublishHook,
+  ParseReplicatedHandoffOfferUpdate,
+  HANDOFF_OFFER_TOPIC,
+} from '../resolvers/HumanHandoffResolver';
+import { PubSubManager } from '../generic/PubSubManager.js';
+import type { AppContext } from '../types.js';
+
+/** Captured at module load: the resolver binds the engine's server-only collaborators then. */
+const wiredAtLoad = h.configure.mock.calls[0]?.[0] as { Presence: unknown; Publisher: unknown; Notifier: unknown };
+
+class TestableResolver extends HumanHandoffResolver {
+  public user: UserInfo | undefined = { ID: 'U1', Name: 'Dana', Email: 'dana@x.com' } as unknown as UserInfo;
+  protected override GetUserFromPayload(): UserInfo | undefined {
+    return this.user;
+  }
+}
+
+const ctx = {} as AppContext;
+
+const VIEW = {
+  OfferID: 'offer-1',
+  RoomName: 'call-1',
+  Mode: 'warm',
+  Summary: 'Wants a refund',
+  CallerLabel: 'Phone caller ****0123',
+  AgentName: 'Sage',
+  Status: 'Pending',
+  CreatedAt: '2026-10-03T10:00:00.000Z',
+  ExpiresAt: '2026-10-03T10:00:45.000Z',
+  InteractionID: 'int-123',
+};
+
+describe('HumanHandoffResolver', () => {
+  let resolver: TestableResolver;
+
+  beforeEach(() => {
+    resolver = new TestableResolver();
+    h.listOffersForUser.mockReset();
+    h.acceptOffer.mockReset();
+    h.declineOffer.mockReset();
+    h.sendNotification.mockClear();
+    h.notificationConfig.mockClear();
+  });
+
+  it('gives the handoff engine its server-only collaborators when the module loads', () => {
+    expect(wiredAtLoad.Presence).toBeDefined();
+    expect(wiredAtLoad.Publisher).toBeInstanceOf(PubSubHandoffPublisher);
+    expect(wiredAtLoad.Notifier).toBeInstanceOf(NotificationHandoffNotifier);
+  });
+
+  describe('MyHandoffOffers', () => {
+    it('lists the signed-in user\'s offers, and only asks the engine about that user', async () => {
+      h.listOffersForUser.mockReturnValue([VIEW]);
+      const offers = await resolver.MyHandoffOffers(ctx);
+      expect(h.listOffersForUser).toHaveBeenCalledWith('U1', resolver.user);
+      expect(offers).toEqual([VIEW]);
+    });
+
+    it('returns nothing when there is no signed-in user', async () => {
+      resolver.user = undefined;
+      expect(await resolver.MyHandoffOffers(ctx)).toEqual([]);
+      expect(h.listOffersForUser).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('AcceptHandoffOffer', () => {
+    it('accepts as the signed-in user (never a user id from the client) and returns the room to join', async () => {
+      h.acceptOffer.mockReturnValue({ Ok: true, Offer: { ...VIEW, Status: 'Accepted' } });
+      const result = await resolver.AcceptHandoffOffer('offer-1', ctx);
+      expect(h.acceptOffer).toHaveBeenCalledWith('offer-1', 'U1', resolver.user);
+      expect(result).toMatchObject({ Success: true, RoomName: 'call-1', Offer: { Status: 'Accepted' } });
+    });
+
+    it('passes the engine\'s refusal back without a room', async () => {
+      h.acceptOffer.mockReturnValue({ Ok: false, Reason: 'This conversation offer is no longer available.' });
+      expect(await resolver.AcceptHandoffOffer('offer-1', ctx)).toEqual({ Success: false, ErrorMessage: 'This conversation offer is no longer available.', RoomName: '' });
+    });
+
+    it('requires a signed-in user', async () => {
+      resolver.user = undefined;
+      const result = await resolver.AcceptHandoffOffer('offer-1', ctx);
+      expect(result.Success).toBe(false);
+      expect(h.acceptOffer).not.toHaveBeenCalled();
+    });
+
+    it('turns an engine failure into a plain failure', async () => {
+      h.acceptOffer.mockImplementation(() => {
+        throw new Error('boom');
+      });
+      expect(await resolver.AcceptHandoffOffer('offer-1', ctx)).toMatchObject({ Success: false, RoomName: '' });
+    });
+  });
+
+  describe('DeclineHandoffOffer', () => {
+    it('declines as the signed-in user', async () => {
+      h.declineOffer.mockReturnValue({ Ok: true });
+      expect(await resolver.DeclineHandoffOffer('offer-1', ctx)).toEqual({ Success: true });
+      expect(h.declineOffer).toHaveBeenCalledWith('offer-1', 'U1', resolver.user);
+    });
+
+    it('passes a refusal back, and requires a user', async () => {
+      h.declineOffer.mockReturnValue({ Ok: false, Reason: 'gone' });
+      expect(await resolver.DeclineHandoffOffer('offer-1', ctx)).toEqual({ Success: false, ErrorMessage: 'gone' });
+      resolver.user = undefined;
+      expect((await resolver.DeclineHandoffOffer('offer-1', ctx)).Success).toBe(false);
+    });
+  });
+
+  describe('HandoffOfferChanges (subscription)', () => {
+    it('shapes the payload for the client and drops the server-side delivery key', () => {
+      const change = resolver.HandoffOfferChanges({ UserID: 'U1', Kind: 'offered', Offer: VIEW as never });
+      expect(change).toEqual({ Kind: 'offered', Offer: VIEW });
+      expect(JSON.stringify(change)).not.toContain('U1');
+    });
+  });
+});
+
+describe('HandoffOfferChangeFilter', () => {
+  const payload = { UserID: 'AAAAAAAA-0000-0000-0000-000000000001', Kind: 'offered' as const, Offer: VIEW as never };
+  const context = (id?: string) => ({ userPayload: { userRecord: { ID: id } } });
+
+  it('delivers a change only to the person it belongs to, comparing ids case-insensitively', () => {
+    expect(HandoffOfferChangeFilter({ payload, context: context('aaaaaaaa-0000-0000-0000-000000000001') })).toBe(true);
+    expect(HandoffOfferChangeFilter({ payload, context: context('BBBBBBBB-0000-0000-0000-000000000002') })).toBe(false);
+  });
+
+  it('fails closed when either identity is missing', () => {
+    expect(HandoffOfferChangeFilter({ payload, context: undefined })).toBe(false);
+    expect(HandoffOfferChangeFilter({ payload, context: context(undefined) })).toBe(false);
+    expect(HandoffOfferChangeFilter({ payload: { ...payload, UserID: '' }, context: context('x') })).toBe(false);
+  });
+});
+
+describe('PubSubHandoffPublisher', () => {
+  it('publishes the change on the offer topic, keyed by the person it belongs to', () => {
+    const publish = vi.spyOn(PubSubManager.Instance, 'Publish').mockImplementation(() => undefined);
+    new PubSubHandoffPublisher().Publish({ UserID: 'U1', Kind: 'updated', Offer: VIEW as never });
+    expect(publish).toHaveBeenCalledWith(HANDOFF_OFFER_TOPIC, { UserID: 'U1', Kind: 'updated', Offer: VIEW });
+    publish.mockRestore();
+  });
+
+  it('forwards the change to the cluster hook if set', () => {
+    const hook = vi.fn();
+    SetHandoffOfferPublishHook(hook);
+    new PubSubHandoffPublisher().Publish({ UserID: 'U1', Kind: 'updated', Offer: VIEW as never });
+    expect(hook).toHaveBeenCalledWith(expect.objectContaining({ UserID: 'U1', Kind: 'updated', Offer: VIEW }));
+    SetHandoffOfferPublishHook(null);
+  });
+});
+
+describe('ParseReplicatedHandoffOfferUpdate', () => {
+  it('parses valid replicated offer payload', () => {
+    const raw = JSON.stringify({
+      UserID: 'U1',
+      Kind: 'updated',
+      Offer: VIEW,
+    });
+    const parsed = ParseReplicatedHandoffOfferUpdate(raw);
+    expect(parsed).toMatchObject({
+      UserID: 'U1',
+      Kind: 'updated',
+      Offer: { OfferID: 'offer-1' },
+    });
+  });
+
+  it('rejects invalid payloads cleanly', () => {
+    expect(ParseReplicatedHandoffOfferUpdate('invalid json')).toBeNull();
+    expect(ParseReplicatedHandoffOfferUpdate(JSON.stringify({ Kind: 'unknown' }))).toBeNull();
+    expect(ParseReplicatedHandoffOfferUpdate(JSON.stringify({ Kind: 'updated' }))).toBeNull();
+  });
+});
+
+describe('NotificationHandoffNotifier', () => {
+  const user = { ID: 'run-as' } as unknown as UserInfo;
+  const provider = {} as unknown as IMetadataProvider;
+
+  it('sends a notification to the person, routed to the handoff console, through the dedicated handoff offer type', async () => {
+    await new NotificationHandoffNotifier().NotifyOffer(VIEW as never, 'U1', user, provider);
+    expect(h.notificationConfig).toHaveBeenCalledWith(false, user, provider);
+    expect(h.sendNotification).toHaveBeenCalledWith(
+      expect.objectContaining({
+        userId: 'U1',
+        typeNameOrId: 'Conversation Handoff Offer',
+        title: expect.stringContaining('Phone caller ****0123'),
+        message: expect.stringContaining('Wants a refund'),
+        resourceConfiguration: { type: 'handoff-offer', offerId: 'offer-1', room: 'call-1' },
+      }),
+      user,
+    );
+  });
+
+  it('throws (so the engine logs it) when the notification engine reports a failure', async () => {
+    h.sendNotification.mockResolvedValueOnce({ success: false, errors: ['type not found'], deliveryChannels: { inApp: false, email: false, sms: false } } as never);
+    await expect(new NotificationHandoffNotifier().NotifyOffer(VIEW as never, 'U1', user, provider)).rejects.toThrow('type not found');
+  });
+});
+