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

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__/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, '127.0.0.1');
+    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__/buildMagicLinkSessionUser.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, vi } from 'vitest';
+import { UserInfo } from '@memberjunction/core';
+import type jwt from 'jsonwebtoken';
+
+vi.mock('../config.js', () => ({
+  userEmailMap: {},
+  apiKey: 'test-api-key',
+  mj_core_schema: '__mj',
+  configInfo: {},
+}));
+vi.mock('../auth/index.js', () => ({
+  GetSigningKeys: vi.fn(),
+  GetSystemUser: vi.fn(),
+  GetValidationOptions: vi.fn(),
+  VerifyUserRecord: vi.fn(),
+  ExtractUserInfoFromPayload: vi.fn(),
+}));
+vi.mock('../util.js', () => ({
+  GetReadOnlyDataSource: vi.fn(),
+  GetReadWriteDataSource: vi.fn(),
+}));
+
+import { BuildMagicLinkSessionUser } from '../context.js';
+
+const uuid = (a: string, b: string) =>
+  [a.repeat(8), b.repeat(4), '4' + b.repeat(3), '8' + b.repeat(3), b.repeat(12)].join('-');
+const ANON_USER_ID = uuid('A', '0');
+const NAMED_USER_ID = uuid('B', '1');
+
+function makeUserRecord(id: string, email: string): UserInfo {
+  return new UserInfo(null, {
+    ID: id,
+    Name: 'Session Test User',
+    Email: email,
+    IsActive: true,
+    Type: 'User',
+    UserRoles: [],
+  });
+}
+
+describe('BuildMagicLinkSessionUser', () => {
+  it('sets AnonymousVisitorID from mj_sid for an anonymous magic-link token', () => {
+    const baseUser = makeUserRecord(ANON_USER_ID, 'anonymous@magic-link.local');
+    const payload: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_anon: true,
+      mj_sid: 'sid-visitor-123',
+      mj_scopes: [{ inviteId: 'inv-1', appId: 'app-1', role: 'Widget Guest', resourceId: 'res-shared' }],
+    };
+
+    const result = BuildMagicLinkSessionUser(baseUser, payload);
+
+    expect(result).not.toBe(baseUser);
+    expect(result.IsMagicLinkAnonymous).toBe(true);
+    expect(result.AnonymousVisitorID).toBe('sid-visitor-123');
+    expect(result.MagicLinkScope?.ResourceID).toBe('res-shared');
+    expect(baseUser.AnonymousVisitorID).toBeUndefined();
+  });
+
+  it('rejects an anonymous magic-link token without mj_sid', () => {
+    const baseUser = makeUserRecord(ANON_USER_ID, 'anonymous@magic-link.local');
+    const missingSid: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_anon: true,
+      mj_scopes: [{ inviteId: 'inv-1', appId: 'app-1', role: 'Widget Guest', resourceId: 'res-shared' }],
+    };
+    const blankSid: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_anon: true,
+      mj_sid: '   ',
+    };
+
+    expect(() => BuildMagicLinkSessionUser(baseUser, missingSid)).toThrow(/mj_sid/);
+    expect(() => BuildMagicLinkSessionUser(baseUser, blankSid)).toThrow(/mj_sid/);
+  });
+
+  it('leaves AnonymousVisitorID undefined for a named magic-link token (with or without resource scope)', () => {
+    const baseUser = makeUserRecord(NAMED_USER_ID, 'named@example.com');
+    const unscopedNamed: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_scopes: [{ inviteId: 'inv-named', appId: 'app-1', role: 'UI' }],
+    };
+    const scopedNamed: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_scopes: [{ inviteId: 'inv-named-2', appId: 'app-1', role: 'UI', resourceId: 'res-named-1', resourceType: 'Report' }],
+    };
+
+    const unscopedResult = BuildMagicLinkSessionUser(baseUser, unscopedNamed);
+    expect(unscopedResult.AnonymousVisitorID).toBeUndefined();
+
+    const scopedResult = BuildMagicLinkSessionUser(baseUser, scopedNamed);
+    expect(scopedResult.IsMagicLinkAnonymous).toBe(false);
+    expect(scopedResult.MagicLinkScope?.ResourceID).toBe('res-named-1');
+    expect(scopedResult.AnonymousVisitorID).toBeUndefined();
+  });
+});