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

package/src/resolvers/TestQuerySQLResolver.ts

@@ -151,6 +151,7 @@ export class TestQuerySQLResolver extends ResolverBase {
 
             return {
                 Success: result.Success,
+                // fls-guard: query rows; the SQL is refused before it runs if it reads a field the caller is denied
                 Results: result.Results ? JSON.stringify(result.Results) : undefined,
                 RowCount: result.RowCount,
                 ExecutionTime: result.ExecutionTime,

package/src/resolvers/TransactionGroupResolver.ts

@@ -1,9 +1,10 @@
 import { Arg, Ctx, Field, InputType, Int, Mutation, ObjectType, registerEnumType } from 'type-graphql';
 import { AppContext } from '../types.js';
-import { CompositeKey, EntityInfo, IMetadataProvider, KeyValuePair, LogError, Metadata, TransactionVariable, TransactionGroupBase, BaseEntity, EntityDeleteOptions, EntitySaveOptions } from '@memberjunction/core';
+import { AssertClientInputWritableForUser, CompositeKey, EntityInfo, IMetadataProvider, KeyValuePair, LogError, Metadata, RecordChangeMetadataSource, TransactionVariable, TransactionGroupBase, BaseEntity, UserInfo } from '@memberjunction/core';
 import { SafeJSONParse, ValuesEqual } from '@memberjunction/global';
 import { GetReadWriteProvider } from '../util.js';
 import { ResolverBase } from '../generic/ResolverBase.js';
+import { ProjectValuesForCaller } from '../generic/fieldSecurityTransport.js';
 
 export enum TransactionVariableType {
     Define = "Define",
@@ -148,16 +149,18 @@ export class TransactionResolver extends ResolverBase {
             // BEFORE any Save()/Delete() runs below: a 'Use' variable sets its field at Submit(), after
             // every server-side write check has passed, so an entity whose check depends on a field's
             // final value must be able to see that a variable will set it.
+            const user: UserInfo = context.userPayload.userRecord;
             for (const item of group.Items) {
-                entityObjects.push(await md.GetEntityObject(item.EntityName, context.userPayload.userRecord));
+                entityObjects.push(await md.GetEntityObject(item.EntityName, user));
             }
+            this.AssertNetworkInputWritable(group, entityObjects, user);
             this.AddNetworkVariables(group, entityObjects, tg);
 
             for (const [index, item] of group.Items.entries()) {
                 const entity = entityObjects[index];
 
                 // get the values from the payload
-                const itemValues = SafeJSONParse(item.EntityObjectJSON);
+                const itemValues = SafeJSONParse<Record<string, unknown>>(item.EntityObjectJSON) ?? {};
                 // build a primary key for the item
                 const pkey = new CompositeKey(entity.PrimaryKeys.map(pk => {
                     const kv = new KeyValuePair();
@@ -171,8 +174,10 @@ export class TransactionResolver extends ResolverBase {
                         if (item.OperationType === "Update") {
                             await entity.InnerLoad(pkey);
                             if (typeof entity.GetDataObject === 'function') {
+                                // fls-guard: pre-update snapshot; projected before the delta is built
                                 preUpdateValues.set(index, await entity.GetDataObject());
                             } else if (typeof entity.GetAll === 'function') {
+                                // fls-guard: pre-update snapshot; projected before the delta is built
                                 preUpdateValues.set(index, { ...(entity.GetAll() as Record<string, unknown>) });
                             }
                         }
@@ -197,6 +202,7 @@ export class TransactionResolver extends ResolverBase {
                         // Awaiting costs nothing here — DataObjectParams defaults
                         // includeRelatedEntityData to false, which guards the method's only awaited
                         // work, so with no params this is GetAll() plus a filter loop.
+                        // fls-guard: projected in PrepareReturnValue
                         objectValues.push(await entity.GetDataObject());
                         entity.TransactionGroup = tg;
                         if (!await entity.Delete()) {
@@ -221,17 +227,17 @@ export class TransactionResolver extends ResolverBase {
                     `TransactionResolver::ExecuteTransactionGroup --- ${refusals.length} of ${group.Items.length} ` +
                     `item(s) were refused, so the group was not submitted:\n${refusals.join('\n')}`
                 );
-                return await this.PrepareReturnValue(false, entityObjects, objectValues, group, preUpdateValues);
+                return await this.PrepareReturnValue(false, entityObjects, objectValues, group, preUpdateValues, md, user);
             }
 
             // after all that, we are ready to roll, so let's run the TG
             if (await tg.Submit()) {
                 // success!
-                return await this.PrepareReturnValue(true, entityObjects, objectValues, group, preUpdateValues);
+                return await this.PrepareReturnValue(true, entityObjects, objectValues, group, preUpdateValues, md, user);
             }
             else {
                 // failure, send back the results
-                return await this.PrepareReturnValue(false, entityObjects, objectValues, group, preUpdateValues);
+                return await this.PrepareReturnValue(false, entityObjects, objectValues, group, preUpdateValues, md, user);
             }
         } 
         catch (err) {
@@ -240,6 +246,32 @@ export class TransactionResolver extends ResolverBase {
         }
     }
 
+    /**
+     * Field-level security gate on everything the client sent, run before any item is applied.
+     *
+     * Each create or update payload must name only fields the caller may read, and so must every transaction
+     * variable: a `Define` on a denied field would copy its value into another item's readable
+     * field at `Submit()`, and a `Use` would write it. A key that names no field is refused with
+     * the same message as a denied one (see `AssertClientInputWritableForUser`). Callers denied
+     * nothing on an entity are not affected. A delete payload is not gated: only its primary key
+     * is read, and the record is loaded from the database.
+     */
+    protected AssertNetworkInputWritable(group: TransactionInputType, entityObjects: BaseEntity[], user: UserInfo): void {
+        for (const [index, item] of group.Items.entries()) {
+            if (item.OperationType === TransactionOperationType.Delete) {
+                continue;
+            }
+            const values = SafeJSONParse<Record<string, unknown>>(item.EntityObjectJSON);
+            AssertClientInputWritableForUser(entityObjects[index]?.EntityInfo, values, user);
+        }
+        for (const networkVar of group.Variables ?? []) {
+            const target = entityObjects[networkVar.ItemIndex];
+            if (target && networkVar.FieldName) {
+                AssertClientInputWritableForUser(target.EntityInfo, { [networkVar.FieldName]: null }, user);
+            }
+        }
+    }
+
     /**
      * Adds the network payload's variables to the group, mapping each one's item index to the entity
      * object built for that item.
@@ -261,13 +293,18 @@ export class TransactionResolver extends ResolverBase {
         entityObjects: BaseEntity[],
         objectValues: unknown[],
         group: TransactionInputType,
-        preUpdateValues?: Map<number, Record<string, unknown>>
+        preUpdateValues?: Map<number, Record<string, unknown>>,
+        provider?: RecordChangeMetadataSource,
+        user?: UserInfo
     ): Promise<TransactionOutputType> {
         const jsonResults = [];
         for (let i = 0; i < group.Items.length; i++) {
             const item = group.Items[i];
+            const project = (values: Record<string, unknown>) =>
+                ProjectValuesForCaller(entityObjects[i]?.EntityInfo, values, user, provider);
             if (item.OperationType === 'Delete') {
-                jsonResults.push(JSON.stringify(objectValues[i]));
+                const deleted = objectValues[i];
+                jsonResults.push(JSON.stringify(deleted && typeof deleted === 'object' ? project(deleted as Record<string, unknown>) : deleted));
             }
             else if (item.OperationType === 'Update') {
                 jsonResults.push(
@@ -276,13 +313,15 @@ export class TransactionResolver extends ResolverBase {
                         objectValues[i],
                         preUpdateValues?.get(i),
                         group,
-                        i
+                        i,
+                        project
                     )
                 );
             }
             else {
-                // create, return what is in the database
-                jsonResults.push(await entityObjects[i].GetDataObjectJSON());
+                // create, return what is in the database, as the caller may read it
+                // fls-guard: projected by project()
+                jsonResults.push(JSON.stringify(project(await entityObjects[i].GetDataObject())));
             }
         }
 
@@ -303,20 +342,32 @@ export class TransactionResolver extends ResolverBase {
      * - Any field whose post-save value differs from its pre-update DB snapshot (`preSaveValues`),
      *   capturing virtual fields, triggers, or server-side `BeforeSave()` mutations automatically
      *   while omitting unchanged columns.
+     *
+     * Both rows are projected for the caller BEFORE they are compared. Comparing a full-width
+     * post-save row against a snapshot taken from a narrowed load would count every denied value
+     * as changed, and the delta would then deliver exactly the values the caller may not read.
      */
     private async serializeUpdateReturnValue(
         entity: BaseEntity,
         sentValues: unknown,
         preSaveValues: Record<string, unknown> | undefined,
         group: TransactionInputType,
-        itemIndex: number
+        itemIndex: number,
+        project: (values: Record<string, unknown>) => Record<string, unknown>
     ): Promise<string> {
-        const fullDataObj: Record<string, unknown> | null = typeof entity.GetDataObject === 'function'
+        const rawDataObj: Record<string, unknown> | null = typeof entity.GetDataObject === 'function'
+            // fls-guard: projected by project() below
             ? (await entity.GetDataObject() as Record<string, unknown>)
+            // fls-guard: projected by project() below
             : SafeJSONParse<Record<string, unknown>>(await entity.GetDataObjectJSON());
-        if (!fullDataObj || typeof fullDataObj !== 'object' || !sentValues || typeof sentValues !== 'object') {
-            return await entity.GetDataObjectJSON();
+        if (!rawDataObj || typeof rawDataObj !== 'object') {
+            return JSON.stringify(rawDataObj);
+        }
+        const fullDataObj = project(rawDataObj);
+        if (!sentValues || typeof sentValues !== 'object') {
+            return JSON.stringify(fullDataObj);
         }
+        preSaveValues = preSaveValues ? project(preSaveValues) : preSaveValues;
 
         const sentRecord = sentValues as Record<string, unknown>;
         const includeKeys = new Set<string>([

package/src/resolvers/UserViewResolver.ts

@@ -5,6 +5,7 @@ import { MJUserView_, MJUserViewResolverBase } from '../generated/generated.js';
 import { UserResolver } from './UserResolver.js';
 import { MJUserViewEntity, MJUserViewEntityExtended } from '@memberjunction/core-entities';
 import { GetReadOnlyProvider, GetReadWriteProvider } from '../util.js';
+import { ProjectEntityObjectForCaller } from '../generic/fieldSecurityTransport.js';
 
 @Resolver(MJUserView_)
 export class UserViewResolver extends MJUserViewResolverBase {
@@ -63,7 +64,7 @@ export class UserViewResolver extends MJUserViewResolverBase {
     await viewEntity.UpdateWhereClause(true); // force regeneration regardless of dirty state — that is the whole point of this endpoint
 
     if (await viewEntity.Save()) {
-      return viewEntity.GetAll();
+      return ProjectEntityObjectForCaller(viewEntity, u, p);
     } else {
       throw new Error('Failed to update where clause');
     }

package/src/resolvers/__tests__/MergeRecordsResolver.test.ts

@@ -90,4 +90,47 @@ describe('RecordDependencyResolver', () => {
     expect(result[0].IsSoftLink).toBeUndefined();
     expect(result[0].EntityIDFieldName).toBeUndefined();
   });
+
+  it('forwards contextUser and options to provider and maps FieldDisplayName', async () => {
+    const mockDep: RecordDependency = {
+      EntityName: 'Users',
+      RelatedEntityName: 'MJ: Task Links',
+      FieldName: 'RecordID',
+      FieldDisplayName: 'Linked Record',
+      PrimaryKey: new CompositeKey([new KeyValuePair('ID', 'TL-200')]),
+      IsSoftLink: true,
+      EntityIDFieldName: 'EntityID',
+    };
+
+    const getRecordDepsSpy = vi.fn().mockResolvedValue([mockDep]);
+    const mockProvider = {
+      GetRecordDependencies: getRecordDepsSpy,
+    } as unknown as IMetadataProvider;
+
+    vi.mocked(GetReadOnlyProvider).mockReturnValue(mockProvider as never);
+
+    const resolver = new RecordDependencyResolver();
+    const mockUser = { ID: 'u-1', Email: 'test@example.com' };
+    const mockContext = {
+      dataSource: {},
+      userPayload: { userRecord: mockUser },
+      providers: [],
+    } as unknown as AppContext;
+    const mockPubSub = {} as PubSubEngine;
+    const options = { LinkType: 'soft' as const, IncludeSystemEntities: false };
+
+    const result = await resolver.GetRecordDependencies(
+      'Users',
+      { KeyValuePairs: [{ FieldName: 'ID', Value: 'USER-1' }] },
+      mockContext,
+      mockPubSub,
+      options
+    );
+
+    expect(getRecordDepsSpy).toHaveBeenCalledTimes(1);
+    expect(getRecordDepsSpy.mock.calls[0][0]).toBe('Users');
+    expect(getRecordDepsSpy.mock.calls[0][2]).toBe(mockUser);
+    expect(getRecordDepsSpy.mock.calls[0][3]).toEqual(options);
+    expect(result[0].FieldDisplayName).toBe('Linked Record');
+  });
 });

package/src/rest/EntityCRUDHandler.ts

@@ -1,7 +1,8 @@
 import { 
-    BaseEntity, CompositeKey, EntityDeleteOptions, EntityPermissionType, 
+    AssertClientInputWritableForUser, BaseEntity, CompositeKey, EntityDeleteOptions, EntityPermissionType, 
     EntitySaveOptions, LogError, Metadata, UserInfo 
 } from '@memberjunction/core';
+import { ProjectValuesForCaller } from '../generic/fieldSecurityTransport.js';
 
 /**
  * Entity CRUD Implementation Functions for REST endpoints
@@ -42,6 +43,9 @@ export class EntityCRUDHandler {
                 delete data.options;
             }
             
+            // Field-level security: refuse a key the caller may not read, or that names no field
+            AssertClientInputWritableForUser(entity.EntityInfo, data, user);
+
             // Set values on the entity
             for (const key in data) {
                 entity.Set(key, data[key]);
@@ -70,7 +74,7 @@ export class EntityCRUDHandler {
             }
             
             // Get entity data for response
-            const entityData = await entity.GetDataObject();
+            const entityData = await this.responseData(entity, user, md);
             return { success: true, entity: entityData };
         } catch (error: any) {
             LogError(error);
@@ -114,7 +118,7 @@ export class EntityCRUDHandler {
             }
             
             // Get entity data for response
-            const entityData = await entity.GetDataObject();
+            const entityData = await this.responseData(entity, user, md);
             return { success: true, entity: entityData };
         } catch (error: any) {
             LogError(error);
@@ -171,6 +175,9 @@ export class EntityCRUDHandler {
                 delete data.options;
             }
             
+            // Field-level security: refuse a key the caller may not read, or that names no field
+            AssertClientInputWritableForUser(entity.EntityInfo, data, user);
+
             // Update entity with new values
             for (const key in data) {
                 entity.Set(key, data[key]);
@@ -179,7 +186,7 @@ export class EntityCRUDHandler {
             // Check if entity is dirty
             if (!entity.Dirty && !options.IgnoreDirtyState) {
                 // Nothing changed, return success
-                const entityData = await entity.GetDataObject();
+                const entityData = await this.responseData(entity, user, md);
                 return { success: true, entity: entityData };
             }
             
@@ -206,7 +213,7 @@ export class EntityCRUDHandler {
             }
             
             // Get entity data for response
-            const entityData = await entity.GetDataObject();
+            const entityData = await this.responseData(entity, user, md);
             return { success: true, entity: entityData };
         } catch (error: any) {
             LogError(error);
@@ -273,6 +280,16 @@ export class EntityCRUDHandler {
         return this.DeleteEntity(entityName, id, options, user);
     }
     
+    /**
+     * The record's field values for the response, reduced to what `user` may READ. An entity
+     * object built for a restricted user holds no denied value already; this is the backstop for
+     * one that does.
+     */
+    private static async responseData(entity: BaseEntity, user: UserInfo, md: Metadata): Promise<Record<string, unknown>> {
+        // fls-guard: projected by ProjectValuesForCaller
+        return ProjectValuesForCaller(entity.EntityInfo, await entity.GetDataObject() as Record<string, unknown>, user, md);
+    }
+
     /**
      * Build the record key from the `:id` path segment. A single-column key (any column name) is
      * the bare value; a composite key is the URL-encoded `Field1|Value1||Field2|Value2` segment.

package/src/rest/RESTEndpointHandler.ts

@@ -2,7 +2,7 @@ import express from 'express';
 import {
     BaseEntity, CompositeKey, EntityDeleteOptions, EntityInfo,
     EntityPermissionType, EntitySaveOptions, LogError, Metadata,
-    RunView, RunViewParams, UserInfo
+    RunView, RunViewParams, StripServerOnlyRunViewParams, UserInfo
 } from '@memberjunction/core';
 import { EntityCRUDHandler } from './EntityCRUDHandler.js';
 import { ViewOperationsHandler } from './ViewOperationsHandler.js';
@@ -499,10 +499,11 @@ export class RESTEndpointHandler {
             
             const user = req['mjUser'];
             
-            // Create RunViewParams from the request body
+            // Create RunViewParams from the request body, without the fields only server code sets;
+            // the time zone comes from the x-mj-timezone header, as on the GraphQL path
             const params: RunViewParams = {
-                EntityName: entityName,
-                ...viewParams
+                ...StripServerOnlyRunViewParams({ ...viewParams, EntityName: entityName }),
+                TimeZone: req.userPayload?.TimeZone
             };
             
             const result = await ViewOperationsHandler.runView(params, user);
@@ -533,7 +534,9 @@ export class RESTEndpointHandler {
             
             // Filter out any views for entities that aren't allowed
             // using our enhanced entity filtering with wildcards and schema support
-            const filteredParams = params.filter(p => this.isEntityAllowed(p.EntityName));
+            const filteredParams = params
+                .filter(p => this.isEntityAllowed(p.EntityName))
+                .map(p => ({ ...StripServerOnlyRunViewParams(p), TimeZone: req.userPayload?.TimeZone }));
             
             // If all requested entities were filtered out, return an error
             if (filteredParams.length === 0 && params.length > 0) {

package/src/rest/RealtimeRecordingHandler.ts

@@ -34,7 +34,7 @@ import {
     LoadOwnedRealtimeSession, RealtimeSessionNotFoundError, RealtimeSessionOwnershipError,
 } from '../realtimeSessions/ownedRealtimeSession.js';
 import type { IRecordingAssemblyScheduler } from '../realtimeSessions/RecordingAssemblyScheduler.js';
-import { AuthorizeSessionAccess, LoadSessionConversationExternalID } from '../realtimeSessions/sessionAccess.js';
+import { AuthorizeSessionAccess, LoadSessionConversationScope } from '../realtimeSessions/sessionAccess.js';
 
 /** Where {@link CreateRealtimeRecordingRouter} is mounted (under the reserved `/realtime` root). */
 export const REALTIME_RECORDING_MOUNT_PATH = '/realtime/recording';
@@ -76,8 +76,8 @@ export interface RealtimeRecordingRouterDeps {
     /** The authenticated caller, or null (answered 401). */
     ResolveCaller(req: Request): RealtimeRecordingCaller | null;
     LoadOwnedSession: typeof LoadOwnedRealtimeSession;
-    /** The session conversation's per-session scope id, for the anonymous-guest half of the access decision. */
-    LoadConversationExternalID: typeof LoadSessionConversationExternalID;
+    /** The session conversation's scope id and whether the caller could read it: the scope half of the access decision. */
+    LoadConversationScope: typeof LoadSessionConversationScope;
     /** The ledger for one request; `contextUser` is the caller (used for logging by the procs). */
     CreateLedger(provider: DatabaseProviderBase, contextUser: UserInfo): IRealtimeRecordingLedger;
     Scheduler: IRecordingAssemblyScheduler;
@@ -258,16 +258,19 @@ async function handleTerminal(deps: RealtimeRecordingRouterDeps, req: Request, r
 
 /**
  * Loads the session through the shared ownership gate, then applies the per-session scope rule of
- * {@link AuthorizeSessionAccess}. The gate alone checks `UserID`, which every anonymous widget guest shares
- * (they all authenticate as the one Anonymous user); without the scope rule one guest could write shards to
- * another guest's recording, and a different-bytes shard would mark it Failed. The owner half of the
- * decision repeats the gate's check on purpose: the decision is one rule, applied whole. Named users carry
- * no scope and are unaffected.
+ * {@link AuthorizeSessionAccess}. The production gate (`LoadOwnedRealtimeSession`) already applies the same
+ * rule, so this is a deliberate second check at the HTTP boundary: `LoadOwnedSession` is an injected dependency,
+ * and without the scope rule one anonymous guest could write shards to another guest's recording (every guest
+ * shares the one Anonymous user), and a different-bytes shard would mark it Failed. It costs one extra
+ * conversation read per request. Named users without a scope are unaffected.
  */
 async function loadAuthorizedSession(deps: RealtimeRecordingRouterDeps, sessionID: string, caller: RealtimeRecordingCaller): Promise<MJAIAgentSessionEntity> {
     const session = await deps.LoadOwnedSession(sessionID, caller.ContextUser, caller.Provider);
-    const externalID = await deps.LoadConversationExternalID(session, caller.ContextUser, caller.Provider);
-    const decision = AuthorizeSessionAccess({ SessionUserID: session.UserID, ConversationExternalID: externalID }, caller.ContextUser);
+    const conversation = await deps.LoadConversationScope(session, caller.ContextUser, caller.Provider);
+    const decision = AuthorizeSessionAccess(
+        { SessionUserID: session.UserID, ConversationExternalID: conversation.ExternalID, ConversationReadable: conversation.Readable },
+        caller.ContextUser,
+    );
     if (decision.Allowed === false) {
         LogError(`RealtimeRecordingHandler: refused user ${caller.ContextUser.ID} on session ${sessionID}: ${decision.Reason}`);
         throw new RecordingRequestError(403, 'Not authorized for this realtime session');

package/src/rest/ViewOperationsHandler.ts

@@ -1,8 +1,9 @@
 import { 
-    BaseEntity, LogError, Metadata, RunView, RunViewParams, 
+    BaseEntity, EntityInfo, LogError, Metadata, RunView, RunViewParams, 
     RunViewResult, UserInfo, type IRunViewProvider 
 } from '@memberjunction/core';
 import { ClientClauseScreen } from '@memberjunction/generic-database-provider';
+import { ProjectRowsForCaller } from '../generic/fieldSecurityTransport.js';
 
 /**
  * View Operations Implementation for REST endpoints
@@ -40,7 +41,7 @@ export class ViewOperationsHandler {
             // Execute the view
             const result = await runView.RunView(params, user);
             
-            return { success: true, result };
+            return { success: true, result: this.projectResult(result, entity, user, md) };
         } catch (error) {
             LogError(error);
             return { success: false, error: (error as Error)?.message || 'Unknown error' };
@@ -60,6 +61,7 @@ export class ViewOperationsHandler {
             // Validate and sanitize each set of parameters against the provider that runs the views
             const md = new Metadata(); // global-provider-ok: REST endpoint — no per-request provider injection in REST middleware yet
             const runView = new RunView();
+            const entities: EntityInfo[] = [];
             for (const params of paramsArray) {
                 // Validate entity exists
                 const entity = md.Entities.find(e => e.Name === params.EntityName);
@@ -81,12 +83,14 @@ export class ViewOperationsHandler {
                 
                 // Sanitize parameters
                 this.sanitizeRunViewParams(params, md, runView.ProviderToUse, user);
+                entities.push(entity);
             }
             
             // Execute the views
             const results = await runView.RunViews(paramsArray, user);
             
-            return { success: true, results };
+            const projected = results?.map((r, i) => this.projectResult(r, entities[i], user, md));
+            return { success: true, results: projected?.some((r, i) => r !== results[i]) ? projected : results };
         } catch (error) {
             LogError(error);
             return { success: false, error: (error as Error)?.message || 'Unknown error' };
@@ -120,7 +124,7 @@ export class ViewOperationsHandler {
             this.sanitizeRunViewParams(params, md, runView.ProviderToUse, user);
             
             // Execute the view
-            return await runView.RunView(params, user);
+            return this.projectResult(await runView.RunView(params, user), entity, user, md);
         } catch (error) {
             LogError(error);
             throw error;
@@ -193,6 +197,19 @@ export class ViewOperationsHandler {
         return this.GetEntityViews(entityName, user);
     }
     
+    /**
+     * The result with its rows reduced to what `user` may READ. The provider already narrows the
+     * rows it reads for a restricted caller; this is the backstop for any that arrive wider. The
+     * same result object comes back when no row needed changing.
+     */
+    private static projectResult(result: RunViewResult, entity: EntityInfo, user: UserInfo, md: Metadata): RunViewResult {
+        if (!result?.Results?.length) {
+            return result;
+        }
+        const rows = ProjectRowsForCaller(entity, result.Results as Record<string, unknown>[], user, md);
+        return rows === result.Results ? result : { ...result, Results: rows };
+    }
+
     /**
      * Sanitize and validate RunViewParams. Client filter and sort text passes the same clause
      * screen as the GraphQL RunView resolvers, parsed in the dialect of `provider`, the provider
@@ -231,8 +248,9 @@ export class ViewOperationsHandler {
             params.StartRow = Number.isFinite(parsed) ? Math.max(0, Math.floor(parsed as number)) : undefined;
         }
         
-        // Default ResultType if not provided
-        if (!params.ResultType) {
+        // Plain rows only on the wire. An entity object serializes its internal state rather than
+        // its projected field values, so a caller may not ask for one; a count carries no row.
+        if (params.ResultType !== 'count_only') {
             params.ResultType = 'simple';
         }
 

package/src/serverRoleConfigUnits.ts

@@ -0,0 +1,48 @@
+/**
+ * Supported MJServer horizontal scaling roles (`MJ_SERVER_ROLE`).
+ * - `'all'` (default): Monolithic mode — serves HTTP/GraphQL/WebSocket traffic AND runs all background worker loops.
+ * - `'api'`: Stateless API/WebSocket edge — serves HTTP/GraphQL/WebSocket traffic ONLY; skips background schedulers,
+ *   queue dispatchers, and janitors so event-loop responsiveness is isolated from heavy background jobs.
+ * - `'worker'`: Background worker replica — runs `ScheduledJobsService`, `IntegrationSyncWorkerService`,
+ *   `StartTaskGraphDispatcher`, `StartWorkQueueHost`, `SessionJanitor`, and orphan reconcilers while keeping
+ *   only lightweight healthcheck/metrics HTTP endpoints active.
+ */
+export type ServerRole = 'all' | 'api' | 'worker';
+
+const VALID_SERVER_ROLES: ReadonlySet<string> = new Set<ServerRole>(['all', 'api', 'worker']);
+
+/**
+ * Resolves the server role from `MJ_SERVER_ROLE` or `mj.config.cjs`'s `serverRole`.
+ * Defaults to `'all'` when unset or blank. Throws on unrecognized values so deployment typos
+ * fail fast at startup instead of silently running the wrong workload profile.
+ */
+export function ResolveServerRole(rawValue?: string | null): ServerRole {
+    const trimmed = rawValue?.trim().toLowerCase();
+    if (!trimmed) {
+        return 'all';
+    }
+    if (VALID_SERVER_ROLES.has(trimmed)) {
+        return trimmed as ServerRole;
+    }
+    throw new Error(
+        `Invalid MJ_SERVER_ROLE "${rawValue}". Expected one of: 'all', 'api', 'worker'.`
+    );
+}
+
+/**
+ * Returns `true` when this server instance should start background worker loops
+ * (`ScheduledJobsService`, `IntegrationSyncWorkerService`, `StartTaskGraphDispatcher`,
+ * `StartWorkQueueHost`, `SessionJanitor`, `StartBridgeOrphanReconciliation`, and
+ * `OrphanDetailReconciler`).
+ */
+export function ShouldRunBackgroundWorkers(role: ServerRole): boolean {
+    return role === 'all' || role === 'worker';
+}
+
+/**
+ * Returns `true` when this server instance is designated to serve interactive
+ * API / GraphQL / WebSocket client traffic.
+ */
+export function ShouldServeInteractiveTraffic(role: ServerRole): boolean {
+    return role === 'all' || role === 'api';
+}