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

package/src/__tests__/ViewOperationsHandler.clauseScreen.test.ts

@@ -0,0 +1,157 @@
+/**
+ * The REST view routes (`POST /views/:entityName`, `POST /views/batch`, `GET /entities/:entityName`)
+ * hand client `ExtraFilter` / `OrderBy` / `OverrideExcludeFilter` text to `RunView` through
+ * `ViewOperationsHandler`. These tests pin that the text passes the same base-view AST screen as
+ * the GraphQL RunView resolvers before any view runs. Payloads are harmless (stacked `SELECT`s);
+ * the point is only whether they reach `RunView`.
+ *
+ * `@memberjunction/core`'s `Metadata` and `RunView` are replaced at the module boundary, as in
+ * ViewOperationsHandler.test.ts; the screen itself runs unmodified.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const { mockRunViewFn, mockRunViewsFn, mockEntityList } = vi.hoisted(() => ({
+    mockRunViewFn: vi.fn(),
+    mockRunViewsFn: vi.fn(),
+    mockEntityList: [] as Array<{
+        Name: string;
+        SchemaName: string;
+        BaseView: string;
+        GetUserPermisions: (u: unknown) => { CanRead: boolean };
+        GetEffectiveRowFilterWhereClause: () => string;
+        GetDeniedReadFields: () => Set<string>;
+    }>,
+}));
+
+vi.mock('@memberjunction/core', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/core')>();
+    class MockMetadata {
+        public get Entities() {
+            return mockEntityList;
+        }
+    }
+    class MockRunView {
+        public RunView(params: unknown, contextUser?: unknown): Promise<unknown> {
+            return mockRunViewFn(params, contextUser);
+        }
+        public RunViews(params: unknown[], contextUser?: unknown): Promise<unknown> {
+            return mockRunViewsFn(params, contextUser);
+        }
+    }
+    return { ...actual, Metadata: MockMetadata, RunView: MockRunView, LogError: vi.fn() };
+});
+
+import type { BaseEntity, PlatformSQL, RunViewParams, UserInfo } from '@memberjunction/core';
+import { ViewOperationsHandler } from '../rest/ViewOperationsHandler.js';
+
+const BRACKET_STACKED =
+    "1 = (SELECT 1 AS [a'])) ; SELECT 1 AS [x] ; SELECT * FROM sales.vwCustomers WHERE (1 = (SELECT 1 AS [b'])";
+
+const USER = { ID: 'user-1', Name: 'Reader' } as unknown as UserInfo;
+const OK_RESULT = { Success: true, Results: [{ ID: '1' }] };
+
+beforeEach(() => {
+    vi.clearAllMocks();
+    mockEntityList.length = 0;
+    const unscoped = { GetEffectiveRowFilterWhereClause: () => '', GetDeniedReadFields: () => new Set<string>() };
+    mockEntityList.push(
+        { Name: 'Customers', SchemaName: 'sales', BaseView: 'vwCustomers', GetUserPermisions: () => ({ CanRead: true }), ...unscoped },
+        { Name: 'Ledger', SchemaName: 'sales', BaseView: 'vwLedger', GetUserPermisions: () => ({ CanRead: false }), ...unscoped },
+        {
+            Name: 'Orders',
+            SchemaName: 'sales',
+            BaseView: 'vwOrders',
+            GetUserPermisions: () => ({ CanRead: true }),
+            GetEffectiveRowFilterWhereClause: () => "(OwnerID = 'user-1')",
+            GetDeniedReadFields: () => new Set<string>(),
+        },
+    );
+    mockRunViewFn.mockResolvedValue(OK_RESULT);
+    mockRunViewsFn.mockResolvedValue([OK_RESULT]);
+});
+
+describe('ViewOperationsHandler — REST clause screen', () => {
+    it('RunView refuses a stacked statement hidden behind a bracket identifier, before RunView', async () => {
+        const outcome = await ViewOperationsHandler.RunView({ EntityName: 'Customers', ExtraFilter: BRACKET_STACKED }, USER);
+
+        expect(mockRunViewFn).not.toHaveBeenCalled();
+        expect(outcome.success).toBe(false);
+        expect(outcome.error).toMatch(/Invalid ExtraFilter: multiple statements/);
+    });
+
+    it('RunView screens OrderBy and OverrideExcludeFilter too', async () => {
+        const cases: RunViewParams[] = [
+            { EntityName: 'Customers', OrderBy: "[a'] ; SELECT 1 AS [x] ; SELECT 1 AS [b']" },
+            { EntityName: 'Customers', OverrideExcludeFilter: BRACKET_STACKED },
+        ];
+        for (const params of cases) {
+            const outcome = await ViewOperationsHandler.RunView(params, USER);
+            expect(outcome.success).toBe(false);
+        }
+        expect(mockRunViewFn).not.toHaveBeenCalled();
+    });
+
+    it('RunView refuses a subquery against a base table or an entity the caller cannot read', async () => {
+        for (const filter of [
+            `EXISTS (SELECT 1 FROM __mj.[User] WHERE [Type] = 'Owner')`,
+            `ID IN (SELECT CustomerID FROM sales.vwLedger)`,
+        ]) {
+            const outcome = await ViewOperationsHandler.RunView({ EntityName: 'Customers', ExtraFilter: filter }, USER);
+            expect(outcome.success).toBe(false);
+        }
+        expect(mockRunViewFn).not.toHaveBeenCalled();
+    });
+
+    it('RunView refuses a subquery over an entity that is row-level-security filtered for the caller', async () => {
+        const outcome = await ViewOperationsHandler.RunView({ EntityName: 'Customers', ExtraFilter: `ID IN (SELECT CustomerID FROM sales.vwOrders)` }, USER);
+
+        expect(mockRunViewFn).not.toHaveBeenCalled();
+        expect(outcome.success).toBe(false);
+        expect(outcome.error).toMatch(/'Orders' is row-level-security filtered for you/);
+    });
+
+    it('RunView screens every variant of a platform-specific filter', async () => {
+        const filter: PlatformSQL = { default: `Name = 'x'`, sqlserver: BRACKET_STACKED };
+
+        const outcome = await ViewOperationsHandler.RunView({ EntityName: 'Customers', ExtraFilter: filter }, USER);
+
+        expect(mockRunViewFn).not.toHaveBeenCalled();
+        expect(outcome.success).toBe(false);
+    });
+
+    it('RunViews refuses the whole batch when one entry carries a payload', async () => {
+        const outcome = await ViewOperationsHandler.RunViews(
+            [{ EntityName: 'Customers' }, { EntityName: 'Customers', ExtraFilter: BRACKET_STACKED }],
+            USER,
+        );
+
+        expect(mockRunViewsFn).not.toHaveBeenCalled();
+        expect(outcome.success).toBe(false);
+    });
+
+    it('ListEntities refuses a payload in the query-string filter', async () => {
+        await expect(
+            ViewOperationsHandler.ListEntities({ EntityName: 'Customers', ExtraFilter: BRACKET_STACKED }, USER),
+        ).rejects.toThrow(/multiple statements/);
+        expect(mockRunViewFn).not.toHaveBeenCalled();
+    });
+
+    it('refuses a ViewEntity that was not loaded as an entity (its ID would be spliced into SQL)', async () => {
+        const forged = { ID: '0) ; SELECT 1 AS [x] ; SELECT 1 WHERE (1=1', EntityID: 'any' } as unknown as BaseEntity;
+
+        const outcome = await ViewOperationsHandler.RunView({ EntityName: 'Customers', ViewEntity: forged, ExcludeDataFromAllPriorViewRuns: true }, USER);
+
+        expect(mockRunViewFn).not.toHaveBeenCalled();
+        expect(outcome.success).toBe(false);
+        expect(outcome.error).toMatch(/ViewEntity is not accepted over REST/);
+    });
+
+    it('passes a filter that only reads entity base views through to RunView', async () => {
+        const filter = `Name = 'O''Brien' AND ID IN (SELECT ID FROM sales.vwCustomers WHERE Region = 'West')`;
+
+        const outcome = await ViewOperationsHandler.RunView({ EntityName: 'Customers', ExtraFilter: filter, OrderBy: '[Name] DESC' }, USER);
+
+        expect(outcome.success).toBe(true);
+        expect((mockRunViewFn.mock.calls[0][0] as RunViewParams).ExtraFilter).toBe(filter);
+    });
+});

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);
+    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__/cacheInvalidationRecordData.test.ts

@@ -5,6 +5,8 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import {
   ConfigureRecordDataBroadcast,
   MayBroadcastRecordData,
+  ReadIsRowFiltered,
+  ShapeCacheInvalidationEvent,
 } from '../generic/CacheInvalidationResolver.js';
 
 /**
@@ -175,3 +177,65 @@ describe('cacheInvalidationFilter', () => {
     expect(filter({ payload: { ...event(''), entityName: '' } as never, context: session({ ID: 'u1' }) })).toBe(false);
   });
 });
+
+/**
+ * Row-level narrowing (MJ#5241): a subscriber who reads the entity only through a row-level security filter learns that a
+ * row changed, not which one; a subscriber with an unfiltered read keeps the key; a subscriber with no read is the entity-level
+ * filter's business and gets nothing here to shape.
+ */
+describe('ReadIsRowFiltered and ShapeCacheInvalidationEvent', () => {
+  const FILTERED_ROLE = 'role-participant';
+  const OPEN_ROLE = 'role-staff';
+  const entity = {
+    Permissions: [
+      { RoleID: FILTERED_ROLE, CanRead: true, Type: 'Allow', ReadRLSFilterID: 'filter-1' },
+      { RoleID: OPEN_ROLE, CanRead: true, Type: 'Allow', ReadRLSFilterID: null },
+      { RoleID: 'role-denied', CanRead: true, Type: 'Deny', ReadRLSFilterID: null },
+    ],
+  };
+  const payload = {
+    entityName: 'Spaces',
+    primaryKeyValues: 'ID|abc',
+    action: 'save',
+    sourceServerId: 'srv',
+    timestamp: new Date('2026-10-07T00:00:00Z'),
+    originSessionId: 'sess',
+    recordData: '{"Name":"x"}',
+  };
+
+  it('is row-filtered when every read the user holds carries a filter', () => {
+    expect(ReadIsRowFiltered(entity, { UserRoles: [{ RoleID: FILTERED_ROLE }] })).toBe(true);
+  });
+
+  it('is not row-filtered when any read the user holds is unfiltered, whichever role brings it', () => {
+    expect(ReadIsRowFiltered(entity, { UserRoles: [{ RoleID: OPEN_ROLE }] })).toBe(false);
+    expect(ReadIsRowFiltered(entity, { UserRoles: [{ RoleID: FILTERED_ROLE }, { RoleID: OPEN_ROLE }] })).toBe(false);
+  });
+
+  it('is not row-filtered when the user holds no read at all (the entity-level filter owns that case), and a Deny row grants nothing', () => {
+    expect(ReadIsRowFiltered(entity, { UserRoles: [{ RoleID: 'role-stranger' }] })).toBe(false);
+    expect(ReadIsRowFiltered(entity, { UserRoles: [{ RoleID: 'role-denied' }] })).toBe(false);
+    expect(ReadIsRowFiltered(entity, { UserRoles: null })).toBe(false);
+  });
+
+  it('matches role ids without regard to case or whitespace', () => {
+    expect(ReadIsRowFiltered(entity, { UserRoles: [{ RoleID: ` ${FILTERED_ROLE.toUpperCase()} ` }] })).toBe(true);
+  });
+
+  it('withholds the key and the row from a row-filtered subscriber, and keeps the rest of the event', () => {
+    const shaped = ShapeCacheInvalidationEvent(payload, { UserRoles: [{ RoleID: FILTERED_ROLE }] }, entity);
+    expect(shaped.PrimaryKeyValues).toBeUndefined();
+    expect(shaped.RecordData).toBeUndefined();
+    expect(shaped.EntityName).toBe('Spaces');
+    expect(shaped.Action).toBe('save');
+    expect(shaped.SourceServerID).toBe('srv');
+    expect(shaped.OriginSessionID).toBe('sess');
+  });
+
+  it('delivers the event whole to an unfiltered reader, and when the entity or the user is unknown', () => {
+    expect(ShapeCacheInvalidationEvent(payload, { UserRoles: [{ RoleID: OPEN_ROLE }] }, entity).PrimaryKeyValues).toBe('ID|abc');
+    expect(ShapeCacheInvalidationEvent(payload, { UserRoles: [{ RoleID: OPEN_ROLE }] }, entity).RecordData).toBe('{"Name":"x"}');
+    expect(ShapeCacheInvalidationEvent(payload, { UserRoles: [{ RoleID: FILTERED_ROLE }] }, null).PrimaryKeyValues).toBe('ID|abc');
+    expect(ShapeCacheInvalidationEvent(payload, undefined, entity).PrimaryKeyValues).toBe('ID|abc');
+  });
+});