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

package/src/__tests__/agent-run-data-guard.test.ts

@@ -0,0 +1,130 @@
+/**
+ * @fileoverview Which agent-run resolver callers may set a run's scope or agent-type params through the `data`
+ * argument (A12.15): the value the resolvers pass as `ExecuteAgentParams.TrustReservedRunData`.
+ *
+ * Pins who is trusted (the system user, an API key that holds the `agent:trusted` scope) and who is not (an
+ * interactive user, a key without that scope, and every widget-guest run even though it executes as the system
+ * user). What an untrusted run then loses is pinned where the rule is applied: `WithAgentRunDataTrustApplied` in
+ * ai-core-plus and `BaseAgent.Execute` in ai-agents.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { UserInfo } from '@memberjunction/core';
+import { UserCache } from '@memberjunction/generic-database-provider';
+
+const hoisted = vi.hoisted(() => ({ authorize: vi.fn() }));
+
+vi.mock('@memberjunction/api-keys', () => ({
+    GetAPIKeyEngine: () => ({ Authorize: hoisted.authorize }),
+}));
+
+import { IsTrustedAgentRunCaller, TRUSTED_RUN_DATA_SCOPE, type ClientAgentRunCaller } from '../resolvers/agent-run-data-guard.js';
+import { ElevateUserPayload } from '../realtimeWidget/widgetGuestElevation.js';
+import type { UserPayload } from '../types.js';
+
+function payload(fields: Partial<UserPayload>): UserPayload {
+    return { email: 'someone@example.com', userRecord: { ID: 'user-1' }, sessionId: 'session-1', ...fields };
+}
+
+const SYSTEM_USER = { ID: 'system-user', Email: 'system@example.com' } as UserInfo;
+
+/** A browser session (JWT): neither the system user nor an API key. */
+const INTERACTIVE = payload({ email: 'browser.user@example.com' });
+/** The system API key (x-mj-api-key), as context.ts builds it. */
+const SYSTEM_KEY = payload({ email: 'system@example.com', isSystemUser: true, apiKey: 'system-key' });
+/** An `mj_sk_*` user API key an administrator granted `agent:trusted`, as context.ts builds it. */
+const TRUSTED_KEY = payload({ email: 'integration@example.com', apiKeyId: 'key-1', apiKeyHash: 'hash-trusted' });
+/** An `mj_sk_*` key a user minted for themselves: it may run agents, nothing more. */
+const PLAIN_KEY = payload({ email: 'browser.user@example.com', apiKeyId: 'key-2', apiKeyHash: 'hash-plain' });
+/** A key holding `full_access`, which does not include `agent:trusted`. */
+const FULL_ACCESS_KEY = payload({ email: 'admin@example.com', apiKeyId: 'key-3', apiKeyHash: 'hash-full' });
+/** A public web-widget guest. */
+const WIDGET_GUEST = payload({ email: 'anonymous@magic-link.local' });
+
+/** Each key's `MJ: API Key Scopes` rows, by scope path. */
+const KEY_SCOPES: Record<string, string[]> = {
+    'hash-trusted': ['agent:execute', 'agent:trusted'],
+    'hash-plain': ['agent:execute'],
+    'hash-full': ['full_access'],
+};
+
+/** APIKeyEngine.Authorize as the scope evaluator answers it: allowed only by a matching key rule. */
+async function authorizeByKeyScopes(apiKeyHash: string, _app: string, scopePath: string) {
+    return KEY_SCOPES[apiKeyHash]?.includes(scopePath)
+        ? { Allowed: true, Reason: 'Key allows access', MatchedKeyRule: { ScopePath: scopePath }, EvaluatedRules: [] }
+        : { Allowed: false, Reason: 'No matching key scope rules', EvaluatedRules: [] };
+}
+
+function caller(userPayload: UserPayload, isWidgetGuestRun = false): ClientAgentRunCaller {
+    return { UserPayload: userPayload, IsWidgetGuestRun: isWidgetGuestRun, AgentID: 'agent-1' };
+}
+
+beforeEach(() => {
+    hoisted.authorize.mockReset().mockImplementation(authorizeByKeyScopes);
+    vi.spyOn(UserCache.Instance, 'GetSystemUser').mockReturnValue(SYSTEM_USER);
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+});
+
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+
+describe('IsTrustedAgentRunCaller', () => {
+    it('names the agent:trusted scope', () => {
+        expect(TRUSTED_RUN_DATA_SCOPE).toBe('agent:trusted');
+    });
+
+    it('trusts the system user', async () => {
+        expect(await IsTrustedAgentRunCaller(caller(SYSTEM_KEY))).toBe(true);
+    });
+
+    it('trusts an API key that holds agent:trusted, checked for the agent being run', async () => {
+        expect(await IsTrustedAgentRunCaller(caller(TRUSTED_KEY))).toBe(true);
+        expect(hoisted.authorize).toHaveBeenCalledWith(
+            'hash-trusted', 'MJAPI', 'agent:trusted', 'agent-1', SYSTEM_USER, expect.anything(), { skipLogging: true });
+    });
+
+    it('does not trust an API key without agent:trusted: it is treated like its user\'s browser session', async () => {
+        expect(await IsTrustedAgentRunCaller(caller(PLAIN_KEY))).toBe(false);
+        expect(await IsTrustedAgentRunCaller(caller(INTERACTIVE))).toBe(false);
+    });
+
+    it('does not trust a full_access key: the key must hold agent:trusted itself', async () => {
+        expect(await IsTrustedAgentRunCaller(caller(FULL_ACCESS_KEY))).toBe(false);
+    });
+
+    it('does not count an allow that matched no key rule (enforcement off, or a no-scopes default of allow)', async () => {
+        hoisted.authorize.mockResolvedValue({ Allowed: true, Reason: 'Enforcement disabled', EvaluatedRules: [] });
+
+        expect(await IsTrustedAgentRunCaller(caller(PLAIN_KEY))).toBe(false);
+    });
+
+    it('fails closed when the scope check cannot run', async () => {
+        hoisted.authorize.mockRejectedValue(new Error('engine not configured'));
+        expect(await IsTrustedAgentRunCaller(caller(TRUSTED_KEY))).toBe(false);
+
+        hoisted.authorize.mockImplementation(authorizeByKeyScopes);
+        vi.mocked(UserCache.Instance.GetSystemUser).mockReturnValue(undefined as unknown as UserInfo);
+        expect(await IsTrustedAgentRunCaller(caller(TRUSTED_KEY))).toBe(false);
+    });
+
+    it('does not trust an interactive (browser) user, and never asks the key engine', async () => {
+        expect(await IsTrustedAgentRunCaller(caller(INTERACTIVE))).toBe(false);
+        expect(hoisted.authorize).not.toHaveBeenCalled();
+    });
+
+    it('does not trust a widget-guest run even when the elevated principal is the system user', async () => {
+        const elevated = ElevateUserPayload(WIDGET_GUEST, SYSTEM_USER);
+        expect(elevated.isSystemUser).toBe(true); // the premise: elevation alone would look trusted
+
+        expect(await IsTrustedAgentRunCaller(caller(elevated, true))).toBe(false);
+    });
+
+    it('does not trust a widget-guest run on a trusted key either', async () => {
+        expect(await IsTrustedAgentRunCaller(caller(TRUSTED_KEY, true))).toBe(false);
+    });
+
+    it('treats an explicit isSystemUser:false, an empty key hash or a non-system api key as untrusted', async () => {
+        expect(await IsTrustedAgentRunCaller(caller(payload({ isSystemUser: false, apiKeyId: 'key-1', apiKeyHash: '' })))).toBe(false);
+        expect(await IsTrustedAgentRunCaller(caller(payload({ apiKey: 'not-the-system-key' })))).toBe(false);
+    });
+});

package/src/__tests__/agentVisionConsentAudit.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+
+const h = vi.hoisted(() => ({
+  systemUser: { ID: 'SYS', Name: 'System' } as { ID: string; Name: string } | undefined,
+  logError: vi.fn(),
+}));
+
+vi.mock('@memberjunction/core', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return { ...actual, LogError: h.logError };
+});
+
+vi.mock('@memberjunction/generic-database-provider', () => ({
+  UserCache: { Instance: { GetSystemUser: () => h.systemUser } },
+}));
+
+import { WriteAgentVisionConsentAudit, REALTIME_AGENT_VISION_CONSENT_AUDIT_TYPE } from '../resolvers/agentVisionConsentAudit';
+
+/** A fake `MJ: Audit Logs` row that records what is set on it. */
+class FakeAuditRow {
+  public UserID = '';
+  public AuditLogTypeID = '';
+  public Status = '';
+  public EntityID: string | null = null;
+  public RecordID: string | null = null;
+  public Description: string | null = null;
+  public Details: string | null = null;
+  public IsNew = false;
+  constructor(private readonly saveResult: boolean) {}
+  NewRecord() {
+    this.IsNew = true;
+  }
+  async Save() {
+    return this.saveResult;
+  }
+  get LatestResult() {
+    return { CompleteMessage: 'save failed' };
+  }
+}
+
+const user = { ID: 'U1', Name: 'Test User' } as unknown as UserInfo;
+
+/** A provider with the consent audit type seeded (unless told otherwise), handing out one fake row. */
+function fakeProvider(o: { seeded?: boolean; saveResult?: boolean; getThrows?: boolean } = {}) {
+  const row = new FakeAuditRow(o.saveResult ?? true);
+  const getEntityObject = vi.fn(async () => {
+    if (o.getThrows) {
+      throw new Error('database unavailable');
+    }
+    return row;
+  });
+  const provider = {
+    AuditLogTypes: o.seeded === false ? [] : [{ ID: 'TYPE-1', Name: REALTIME_AGENT_VISION_CONSENT_AUDIT_TYPE }],
+    EntityByName: (name: string) => (name === 'MJ: Users' ? { ID: 'USERS-ENTITY' } : undefined),
+    GetEntityObject: getEntityObject,
+  } as unknown as IMetadataProvider;
+  return { provider, row, getEntityObject };
+}
+
+describe('WriteAgentVisionConsentAudit', () => {
+  beforeEach(() => {
+    h.logError.mockClear();
+    h.systemUser = { ID: 'SYS', Name: 'System' };
+  });
+
+  it('records an applied choice, saved by the system user, about the person', async () => {
+    const { provider, row, getEntityObject } = fakeProvider();
+    await WriteAgentVisionConsentAudit({ User: user, RoomName: 'room-1', Allow: true, Applied: true }, provider);
+    expect(getEntityObject).toHaveBeenCalledWith('MJ: Audit Logs', h.systemUser);
+    expect(row).toMatchObject({
+      IsNew: true,
+      UserID: 'U1',
+      AuditLogTypeID: 'TYPE-1',
+      Status: 'Success',
+      EntityID: 'USERS-ENTITY',
+      RecordID: 'U1',
+      Description: 'Let agents see their camera and shared screen in room room-1.',
+    });
+    expect(JSON.parse(row.Details ?? '')).toEqual({ roomName: 'room-1', allow: true, error: null });
+    expect(h.logError).not.toHaveBeenCalled();
+  });
+
+  it('records a refused change as Failed, with the reason', async () => {
+    const { provider, row } = fakeProvider();
+    await WriteAgentVisionConsentAudit({ User: user, RoomName: 'room-1', Allow: false, Applied: false, ErrorMessage: 'not in the room' }, provider);
+    expect(row.Status).toBe('Failed');
+    expect(row.Description).toBe('Stopped letting agents see their camera and shared screen in room room-1 (not applied).');
+    expect(JSON.parse(row.Details ?? '')).toEqual({ roomName: 'room-1', allow: false, error: 'not in the room' });
+  });
+
+  it('logs the choice instead when the audit log type is not seeded', async () => {
+    const { provider, getEntityObject } = fakeProvider({ seeded: false });
+    await WriteAgentVisionConsentAudit({ User: user, RoomName: 'room-1', Allow: true, Applied: true }, provider);
+    expect(getEntityObject).not.toHaveBeenCalled();
+    expect(h.logError).toHaveBeenCalledWith(expect.stringMatching(/is not seeded.*user U1: Let agents see their camera and shared screen in room room-1\./));
+  });
+
+  it('logs the choice instead when there is no system user or no provider', async () => {
+    h.systemUser = undefined;
+    const { provider, getEntityObject } = fakeProvider();
+    await WriteAgentVisionConsentAudit({ User: user, RoomName: 'room-1', Allow: true, Applied: true }, provider);
+    await WriteAgentVisionConsentAudit({ User: user, RoomName: 'room-1', Allow: true, Applied: true }, null);
+    expect(getEntityObject).not.toHaveBeenCalled();
+    expect(h.logError.mock.calls.map((c) => String(c[0]).match(/\((.*?)\)/)?.[1])).toEqual(['no system user', 'no provider']);
+  });
+
+  it('logs a row that does not save, and never throws when the write fails', async () => {
+    await WriteAgentVisionConsentAudit({ User: user, RoomName: 'room-1', Allow: true, Applied: true }, fakeProvider({ saveResult: false }).provider);
+    await expect(
+      WriteAgentVisionConsentAudit({ User: user, RoomName: 'room-1', Allow: true, Applied: true }, fakeProvider({ getThrows: true }).provider),
+    ).resolves.toBeUndefined();
+    expect(h.logError.mock.calls.map((c) => String(c[0]))).toEqual([
+      'Agent vision consent audit row not saved for user U1: save failed',
+      'Agent vision consent audit write threw for user U1: database unavailable',
+    ]);
+  });
+});

package/src/__tests__/apiRootBoot.test.ts

@@ -0,0 +1,202 @@
+/**
+ * Boot test for the API-root rule (MJ #5674): mounts every core route through the same functions
+ * `serve()` calls, on a bare Express app, and checks where they landed.
+ *
+ * - `MJAPI_BASE_PATH=/api` → every registered path starts with `/api/`, and a real request to
+ *   `/healthcheck` (origin root) 404s.
+ * - `MJAPI_BASE_PATH=/` → the paths are byte-identical to the root-mounted ones MJAPI always used, whatever
+ *   `GRAPHQL_ROOT_PATH` is (it is only Apollo's path).
+ *
+ * The router factories are stubbed (they need keys, DB, providers); the MOUNT code is real.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import express, { type Application, type Router } from 'express';
+import type { AddressInfo } from 'node:net';
+import type { ServerExtensionLoader } from '@memberjunction/server-extensions-core';
+
+const mockConfig = vi.hoisted(() => ({
+    configInfo: {
+        graphqlRootPath: '/',
+        apiBasePath: '/',
+        publicUrl: '',
+        baseUrl: 'http://localhost',
+        graphqlPort: 4000,
+        cors: {},
+        realtime: { enabled: true, identityVerification: { enabled: true } },
+        magicLink: { enabled: true },
+        widget: { enabled: true },
+    } as Record<string, unknown>,
+}));
+vi.mock('../config.js', () => mockConfig);
+
+// vi.mock factories are hoisted above the imports, so the stubs must be hoisted with them.
+const { stubRouter, stubHandler } = await vi.hoisted(async () => {
+    const { Router: makeRouter } = await import('express');
+    const router = (): Router => makeRouter();
+    return { stubRouter: router, stubHandler: () => ({ publicRouter: router(), authenticatedRouter: router() }) };
+});
+vi.mock('../rest/OAuthCallbackHandler.js', () => ({
+    CreateOAuthCallbackHandler: () => ({ callbackRouter: stubRouter(), authenticatedRouter: stubRouter() }),
+}));
+vi.mock('../rest/SignatureWebhookHandler.js', () => ({ CreateSignatureWebhookHandler: stubRouter }));
+vi.mock('../rest/MediaStreamHandler.js', () => ({ CreateMediaStreamRouter: stubRouter }));
+vi.mock('../rest/RealtimeSdpBrokerHandler.js', () => ({ CreateRealtimeSdpBrokerRouter: stubRouter }));
+vi.mock('../auth/AuthProviderCatalogRouter.js', () => ({ CreateAuthProviderCatalogRouter: stubRouter, AUTH_CATALOG_MOUNT_PATH: '/auth' }));
+vi.mock('../auth/magicLink/index.js', () => ({
+    CreateMagicLinkHandler: stubHandler,
+    CreateMagicLinkJwksRouter: stubRouter,
+    RegisterMagicLinkAuthProvider: () => undefined,
+    MAGIC_LINK_MOUNT_PATH: '/magic-link',
+}));
+vi.mock('../realtimeWidget/index.js', () => ({ CreateWidgetHandler: stubHandler, WIDGET_MOUNT_PATH: '/widget' }));
+vi.mock('../realtimeSessions/index.js', () => ({
+    CreateRealtimeVerifyRouter: stubRouter,
+    REALTIME_VERIFY_MOUNT_PATH: '/realtime/verify',
+    RealtimeSessionVerificationService: { Instance: { IsEnabled: true } },
+}));
+vi.mock('@memberjunction/ai', () => ({ REALTIME_SDP_EXCHANGE_PATH: '/realtime/sdp-exchange' }));
+
+import {
+    MountHealthcheckRoute,
+    MountPublicCoreRoutes,
+    MountExtensionHealthRoute,
+    MountAuthCatalogRoute,
+    MountAuthenticatedCoreRoutes,
+} from '../coreRoutes.js';
+import { ApiRoute } from '../apiRoot.js';
+import { CoreReservedServerExtensionRoots } from '../serverExtensionReservedRoots.js';
+
+const MOUNT_METHODS = ['use', 'get', 'post', 'put', 'patch', 'delete', 'all'] as const;
+const log = { LogIf: () => undefined };
+const loader = { HealthCheckAll: async () => [] } as unknown as ServerExtensionLoader;
+
+/** Builds an app the way serve() does and returns it plus every path it registered, in order. */
+function bootCoreRoutes(): { app: Application; paths: string[] } {
+    const app = express();
+    const paths: string[] = [];
+    for (const method of MOUNT_METHODS) {
+        const original = app[method].bind(app) as (...args: unknown[]) => Application;
+        (app as unknown as Record<string, unknown>)[method] = (...args: unknown[]) => {
+            if (typeof args[0] === 'string') paths.push(args[0]);
+            return original(...args);
+        };
+    }
+    MountHealthcheckRoute(app);
+    const routers = MountPublicCoreRoutes(app, 'http://localhost:4000/', log);
+    MountExtensionHealthRoute(app, loader);
+    MountAuthCatalogRoute(app, log);
+    MountAuthenticatedCoreRoutes(app, routers, log);
+    return { app, paths };
+}
+
+async function statusOf(app: Application, path: string): Promise<number> {
+    const server = app.listen(0);
+    try {
+        await new Promise<void>((resolve) => server.once('listening', () => resolve()));
+        const { port } = server.address() as AddressInfo;
+        const res = await fetch(`http://127.0.0.1:${port}${path}`);
+        return res.status;
+    } finally {
+        server.close();
+    }
+}
+
+const ROOT_MOUNTS_BEFORE_5674 = [
+    '/healthcheck',
+    '/oauth',
+    '/esignature',
+    '/media',
+    '/realtime/sdp-exchange',
+    '/magic-link',
+    '/widget',
+    '/realtime/verify',
+    '/health/extensions',
+    '/auth',
+    '/oauth',
+    '/magic-link',
+    '/widget',
+];
+
+describe('core routes under MJAPI_BASE_PATH=/api', () => {
+    beforeEach(() => {
+        mockConfig.configInfo.apiBasePath = '/api';
+        mockConfig.configInfo.magicLink = { enabled: true };
+    });
+
+    it('registers every route under /api/', () => {
+        const { paths } = bootCoreRoutes();
+        expect(paths.length).toBe(ROOT_MOUNTS_BEFORE_5674.length);
+        for (const path of paths) {
+            expect(path, `${path} is outside MJAPI_BASE_PATH`).toMatch(/^\/api\//);
+        }
+    });
+
+    it('also mounts the widget JWKS fallback under /api/ when magic-link is off', () => {
+        mockConfig.configInfo.magicLink = { enabled: false };
+        const { paths } = bootCoreRoutes();
+        expect(paths).toContain('/api/magic-link');
+        expect(paths.every((p) => p.startsWith('/api/'))).toBe(true);
+    });
+
+    it('answers at /api/healthcheck and 404s at the origin root', async () => {
+        const { app } = bootCoreRoutes();
+        expect(await statusOf(app, '/api/healthcheck')).toBe(200);
+        expect(await statusOf(app, '/healthcheck')).toBe(404);
+    });
+
+    it('reserves every mounted prefix for extensions (relative to MJAPI_BASE_PATH)', () => {
+        const reserved = CoreReservedServerExtensionRoots();
+        for (const path of bootCoreRoutes().paths) {
+            const relative = path.slice('/api'.length);
+            const covered = reserved.some((r) => relative === r || relative.startsWith(`${r}/`));
+            expect(covered, `core mount ${path} is not in CoreReservedServerExtensionRoots()`).toBe(true);
+        }
+    });
+});
+
+describe('backward compatibility at MJAPI_BASE_PATH=/', () => {
+    beforeEach(() => {
+        mockConfig.configInfo.apiBasePath = '/';
+        mockConfig.configInfo.graphqlRootPath = '/';
+        mockConfig.configInfo.publicUrl = '';
+        mockConfig.configInfo.magicLink = { enabled: true };
+    });
+
+    it('mounts byte-identical paths', () => {
+        expect(bootCoreRoutes().paths).toEqual(ROOT_MOUNTS_BEFORE_5674);
+    });
+
+    it('ignores GRAPHQL_ROOT_PATH: it is only where Apollo listens', () => {
+        mockConfig.configInfo.graphqlRootPath = '/api/';
+        expect(bootCoreRoutes().paths).toEqual(ROOT_MOUNTS_BEFORE_5674);
+    });
+
+    it('builds byte-identical URLs', () => {
+        expect(ApiRoute('/magic-link/redeem')).toBe('/magic-link/redeem');
+        expect(ApiRoute('/media/upload-stage')).toBe('/media/upload-stage');
+        expect(ApiRoute('/media/abc?token=t', { absolute: true })).toBe('http://localhost:4000/media/abc?token=t');
+        mockConfig.configInfo.publicUrl = 'https://api.example.com';
+        expect(ApiRoute('/media/abc', { absolute: true })).toBe('https://api.example.com/media/abc');
+    });
+});
+
+describe('ApiRoute under a base path', () => {
+    it('prefixes paths and appends to MJAPI_PUBLIC_URL without doubling the root', () => {
+        mockConfig.configInfo.apiBasePath = '/api/';
+        mockConfig.configInfo.publicUrl = 'https://example.com/api/';
+        expect(ApiRoute('/media')).toBe('/api/media');
+        expect(ApiRoute('/media/abc', { absolute: true })).toBe('https://example.com/api/media/abc');
+    });
+
+    it('falls back to baseUrl:port + MJAPI_BASE_PATH when MJAPI_PUBLIC_URL is unset', () => {
+        mockConfig.configInfo.apiBasePath = '/api/';
+        mockConfig.configInfo.graphqlRootPath = '/';
+        mockConfig.configInfo.publicUrl = '';
+        expect(ApiRoute('/magic-link/redeem', { absolute: true })).toBe('http://localhost:4000/api/magic-link/redeem');
+    });
+
+    it('rejects a subpath without a leading slash', () => {
+        expect(() => ApiRoute('media')).toThrow(/must start with '\/'/);
+        expect(() => ApiRoute('media', { absolute: true })).toThrow(/must start with '\/'/);
+    });
+});

package/src/__tests__/avatarInputValidation.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect } from 'vitest';
+import {
+  ValidateAvatarInput,
+  AVATAR_MAX_IMAGE_BYTES,
+  AVATAR_MAX_URL_LENGTH,
+  AVATAR_MAX_ICON_CLASS_LENGTH,
+} from '../resolvers/avatarInputValidation.js';
+
+/** A valid base64 data URI whose payload decodes to exactly `bytes` bytes. */
+function dataUri(bytes: number, type = 'png'): string {
+  return `data:image/${type};base64,${Buffer.alloc(bytes, 7).toString('base64')}`;
+}
+
+function expectRefused(imageURL: string | null, iconClass: string | null = null): string {
+  const result = ValidateAvatarInput(imageURL, iconClass);
+  expect(result.Valid).toBe(false);
+  expect(result.ErrorMessage).toBeTruthy();
+  return result.ErrorMessage!;
+}
+
+describe('ValidateAvatarInput', () => {
+  describe('clearing', () => {
+    it('accepts both null as a revert to default', () => {
+      expect(ValidateAvatarInput(null, null)).toEqual({ Valid: true, ImageURL: null, IconClass: null });
+    });
+
+    it('treats undefined and empty strings as clear', () => {
+      expect(ValidateAvatarInput(undefined, undefined)).toEqual({ Valid: true, ImageURL: null, IconClass: null });
+      expect(ValidateAvatarInput('', '')).toEqual({ Valid: true, ImageURL: null, IconClass: null });
+    });
+  });
+
+  describe('data URIs', () => {
+    it.each(['png', 'jpeg', 'jpg', 'gif', 'webp'])('accepts image/%s', (type) => {
+      const uri = dataUri(10, type);
+      expect(ValidateAvatarInput(uri, null)).toEqual({ Valid: true, ImageURL: uri, IconClass: null });
+    });
+
+    it('accepts every padding variant', () => {
+      for (const bytes of [3, 4, 5]) {
+        expect(ValidateAvatarInput(dataUri(bytes), null).Valid).toBe(true);
+      }
+    });
+
+    it('accepts a decoded payload of exactly the cap', () => {
+      expect(ValidateAvatarInput(dataUri(AVATAR_MAX_IMAGE_BYTES), null).Valid).toBe(true);
+    });
+
+    it('refuses a decoded payload one byte over the cap', () => {
+      expect(expectRefused(dataUri(AVATAR_MAX_IMAGE_BYTES + 1))).toContain('200KB');
+    });
+
+    it('refuses an oversized data URI on length alone, even one the pattern would reject anyway', () => {
+      const huge = `data:image/png;base64,${'A'.repeat(2 * 1024 * 1024)}!`;
+      expect(expectRefused(huge)).toContain('200KB');
+    });
+
+    it('accepts the longest prefix with a payload of exactly the cap', () => {
+      expect(ValidateAvatarInput(dataUri(AVATAR_MAX_IMAGE_BYTES, 'jpeg'), null).Valid).toBe(true);
+    });
+
+    it('refuses SVG, which can carry script', () => {
+      expectRefused(`data:image/svg+xml;base64,${Buffer.from('<svg onload="alert(1)"/>').toString('base64')}`);
+    });
+
+    it.each([
+      'data:text/html;base64,PHNjcmlwdD4=',
+      'data:application/octet-stream;base64,AAAA',
+      'data:image/png,rawdata',
+      'data:image/png;base64,',
+      'data:image/png;base64,AAA',
+      'data:image/png;base64,AA=A',
+      'data:image/png;base64,AA AA',
+      'data:image/png;base64,AA*A',
+      'data:image/PNG;base64,AAAA',
+      `${dataUri(10)}\n`,
+    ])('refuses %j', (value) => {
+      expectRefused(value);
+    });
+  });
+
+  describe('http(s) URLs', () => {
+    it.each(['https://example.com/me.png', 'http://example.com/a/b?c=d#e', 'HTTPS://EXAMPLE.COM/x.png'])('accepts %s', (url) => {
+      expect(ValidateAvatarInput(url, null)).toEqual({ Valid: true, ImageURL: url, IconClass: null });
+    });
+
+    it('accepts a URL of exactly the length cap', () => {
+      const base = 'https://example.com/';
+      const url = base + 'a'.repeat(AVATAR_MAX_URL_LENGTH - base.length);
+      expect(url).toHaveLength(AVATAR_MAX_URL_LENGTH);
+      expect(ValidateAvatarInput(url, null).Valid).toBe(true);
+    });
+
+    it('refuses a URL one character over the length cap', () => {
+      const base = 'https://example.com/';
+      expectRefused(base + 'a'.repeat(AVATAR_MAX_URL_LENGTH - base.length + 1));
+    });
+
+    it.each([
+      'javascript:alert(1)',
+      'JavaScript:alert(document.cookie)',
+      'vbscript:msgbox(1)',
+      'file:///etc/passwd',
+      'ftp://example.com/me.png',
+      'blob:https://example.com/abc',
+      '//example.com/me.png',
+      '/assets/user.png',
+      'me.png',
+      'https://exa mple.com/me.png',
+      ' https://example.com/me.png',
+      'https://example.com/me.png\t',
+      'https://',
+      'http:example.com',
+    ])('refuses %j', (value) => {
+      expectRefused(value);
+    });
+  });
+
+  describe('icon classes', () => {
+    it.each(['fa-solid fa-user', 'fa-regular fa-circle-user', 'fa-user', 'fa-solid fa-user-astronaut fa-2x'])('accepts %j', (icon) => {
+      expect(ValidateAvatarInput(null, icon)).toEqual({ Valid: true, ImageURL: null, IconClass: icon });
+    });
+
+    it('accepts an icon class of exactly the length cap', () => {
+      const icon = 'fa-' + 'a'.repeat(AVATAR_MAX_ICON_CLASS_LENGTH - 3);
+      expect(ValidateAvatarInput(null, icon).Valid).toBe(true);
+    });
+
+    it('refuses an icon class one character over the length cap', () => {
+      expectRefused(null, 'fa-' + 'a'.repeat(AVATAR_MAX_ICON_CLASS_LENGTH - 2));
+    });
+
+    it.each([
+      'solid user',
+      'fa-',
+      'fa-solid fa-User',
+      'FA-SOLID FA-USER',
+      'fa-solid fa-user" onmouseover="alert(1)',
+      'fa-solid fa-user<script>',
+      'fa-solid;fa-user',
+      'fa_solid fa_user',
+      'fa-solid\tfa-user',
+      'fa-solid\nfa-user',
+    ])('refuses %j', (icon) => {
+      expectRefused(null, icon);
+    });
+  });
+
+  describe('both values', () => {
+    it('accepts a valid image and a valid icon together', () => {
+      const uri = dataUri(10);
+      expect(ValidateAvatarInput(uri, 'fa-solid fa-user')).toEqual({ Valid: true, ImageURL: uri, IconClass: 'fa-solid fa-user' });
+    });
+
+    it('refuses the whole request when either value is bad, and returns no values to store', () => {
+      expect(ValidateAvatarInput('javascript:alert(1)', 'fa-solid fa-user')).toMatchObject({ Valid: false, ImageURL: null, IconClass: null });
+      expect(ValidateAvatarInput(dataUri(10), 'bad icon')).toMatchObject({ Valid: false, ImageURL: null, IconClass: null });
+    });
+  });
+});