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

package/src/generic/RunViewResolver.ts

@@ -1,7 +1,8 @@
 import { Arg, Ctx, Field, InputType, Int, ObjectType, PubSubEngine, Query, Resolver } from 'type-graphql';
 import { AppContext } from '../types.js';
-import { ResolverBase } from './ResolverBase.js';
-import { LogError, LogStatus, EntityInfo, FieldSecurityError, RunViewWithCacheCheckResult, RunViewsWithCacheCheckResponse, RunViewWithCacheCheckParams, AggregateResult, CompositeKey } from '@memberjunction/core';
+import { ResolverBase, type RunViewResultWithResolvedView } from './ResolverBase.js';
+import { LogError, LogStatus, EntityInfo, FieldSecurityError, RunViewWithCacheCheckResult, RunViewsWithCacheCheckResponse, RunViewWithCacheCheckParams, AggregateResult, CompositeKey, ViewPropertyValues } from '@memberjunction/core';
+import { GraphQLJSONObject } from 'graphql-type-json';
 
 import { ReplaceByteArraysWithBase64, UUIDsEqual } from '@memberjunction/global';
 import { RequireSystemUser } from '../directives/RequireSystemUser.js';
@@ -207,6 +208,20 @@ export class RunViewByIDInput {
       'Optional, when true the binary fields of the entity (varbinary / bytea columns) are returned, as base64 strings. They are omitted by default because they are usually large and lists rarely read them. A binary field named explicitly in Fields is always returned.',
   })
   IncludeBinaryFields?: boolean;
+
+  @Field(() => String, {
+    nullable: true,
+    description:
+      'Optional registered Alternate Base View logical Name (from EntityAlternateBaseView.Name) for this entity. When set, overrides both a saved UserView DisplayState.alternateBaseView pin and the entity default BaseView. Pass an empty string ("") to force the entity default BaseView over a saved UserView pin.',
+  })
+  AlternateBaseView?: string;
+
+  @Field(() => GraphQLJSONObject, {
+    nullable: true,
+    description:
+      "Optional values for the view's declared properties, keyed by property name ({ \"Chapter\": \"<id>\" }). A list is accepted only for a property whose operator is IN; null means no value. A name the view does not declare, a value of the wrong type, a value for a property that only the server may set, or a required property left without a value refuses the run with an error naming the property.",
+  })
+  Properties?: ViewPropertyValues;
 }
 
 @InputType()
@@ -335,6 +350,20 @@ export class RunViewByNameInput {
       'Optional, when true the binary fields of the entity (varbinary / bytea columns) are returned, as base64 strings. They are omitted by default because they are usually large and lists rarely read them. A binary field named explicitly in Fields is always returned.',
   })
   IncludeBinaryFields?: boolean;
+
+  @Field(() => String, {
+    nullable: true,
+    description:
+      'Optional registered Alternate Base View logical Name (from EntityAlternateBaseView.Name) for this entity. When set, overrides both a saved UserView DisplayState.alternateBaseView pin and the entity default BaseView. Pass an empty string ("") to force the entity default BaseView over a saved UserView pin.',
+  })
+  AlternateBaseView?: string;
+
+  @Field(() => GraphQLJSONObject, {
+    nullable: true,
+    description:
+      "Optional values for the view's declared properties, keyed by property name ({ \"Chapter\": \"<id>\" }). A list is accepted only for a property whose operator is IN; null means no value. A name the view does not declare, a value of the wrong type, a value for a property that only the server may set, or a required property left without a value refuses the run with an error naming the property.",
+  })
+  Properties?: ViewPropertyValues;
 }
 
 @InputType()
@@ -449,6 +478,13 @@ export class RunDynamicViewInput {
       'Optional, when true the binary fields of the entity (varbinary / bytea columns) are returned, as base64 strings. They are omitted by default because they are usually large and lists rarely read them. A binary field named explicitly in Fields is always returned.',
   })
   IncludeBinaryFields?: boolean;
+
+  @Field(() => String, {
+    nullable: true,
+    description:
+      'Optional registered Alternate Base View logical Name (from EntityAlternateBaseView.Name) for this entity. When set, routes the dynamic view read through the named alternate base view instead of the entity default BaseView.',
+  })
+  AlternateBaseView?: string;
 }
 
 @InputType()
@@ -592,6 +628,20 @@ export class RunViewGenericInput {
       'Optional, when true the binary fields of the entity (varbinary / bytea columns) are returned, as base64 strings. They are omitted by default because they are usually large and lists rarely read them. A binary field named explicitly in Fields is always returned.',
   })
   IncludeBinaryFields?: boolean;
+
+  @Field(() => String, {
+    nullable: true,
+    description:
+      'Optional registered Alternate Base View logical Name (from EntityAlternateBaseView.Name) for this entity. When set, overrides both a saved UserView DisplayState.alternateBaseView pin and the entity default BaseView. Pass an empty string ("") to force the entity default BaseView over a saved UserView pin.',
+  })
+  AlternateBaseView?: string;
+
+  @Field(() => GraphQLJSONObject, {
+    nullable: true,
+    description:
+      "Optional values for the view's declared properties, keyed by property name ({ \"Chapter\": \"<id>\" }). A list is accepted only for a property whose operator is IN; null means no value. A name the view does not declare, a value of the wrong type, a value for a property that only the server may set, or a required property left without a value refuses the run with an error naming the property.",
+  })
+  Properties?: ViewPropertyValues;
 }
 
 //****************************************************************************
@@ -605,6 +655,12 @@ export class RunViewCacheStatusInput {
 
   @Field(() => Int, { description: 'The number of rows in cached results' })
   rowCount: number;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
+
+  @Field(() => String, {
+    nullable: true,
+    description: "A hash of the client's field-security key for this view ('' when the user is denied nothing). When it differs from the server's for the same user, the server answers stale with fresh rows. Omitted by older clients.",
+  })
+  fieldSecurityKey?: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name, matching its siblings
 }
 
 @InputType()
@@ -796,7 +852,7 @@ export class RunViewResolver extends ResolverBase {
       await this.CheckAPIKeyScopeAuthorization('view:run', input.ViewName, userPayload);
       const provider = GetReadOnlyProvider(providers, { allowFallbackToReadWrite: true });
       const rawData = await super.RunViewByNameGeneric(input, provider, userPayload, pubSub);
-      if (rawData === null) {
+      if (!rawData) {
         return {
           Results: [],
           Success: false,
@@ -807,9 +863,10 @@ export class RunViewResolver extends ResolverBase {
         };
       }
 
-      const viewInfo = super.safeFirstArrayElement<MJUserViewEntityExtended>(await super.findBy<MJUserViewEntityExtended>(provider, "MJ: User Views", { Name: input.ViewName }, userPayload.userRecord));
-      const entity = provider.EntityByID(viewInfo.EntityID);
-      const returnData = this.processRawData(rawData.Results, viewInfo.EntityID, entity);
+      const viewInfo = (rawData as RunViewResultWithResolvedView)._resolvedViewEntity
+        ?? await this.resolveUserViewByName(input.ViewName, provider, userPayload.userRecord);
+      const entity = viewInfo ? provider.EntityByID(viewInfo.EntityID) : undefined;
+      const returnData = this.processRawData(rawData.Results, viewInfo?.EntityID ?? null, entity);
       return {
         Results: returnData,
         UserViewRunID: rawData?.UserViewRunID,
@@ -817,6 +874,7 @@ export class RunViewResolver extends ResolverBase {
         TotalRowCount: rawData?.TotalRowCount,
         ExecutionTime: rawData?.ExecutionTime,
         Success: rawData?.Success,
+        ErrorMessage: rawData?.ErrorMessage,
         AggregateResults: this.processAggregateResults(rawData?.AggregateResults),
         AggregateExecutionTime: rawData?.AggregateExecutionTime,
       };
@@ -845,7 +903,7 @@ export class RunViewResolver extends ResolverBase {
       await this.CheckAPIKeyScopeAuthorization('view:run', input.ViewID, userPayload);
       const provider = GetReadOnlyProvider(providers, { allowFallbackToReadWrite: true });
       const rawData = await super.RunViewByIDGeneric(input, provider, userPayload, pubSub);
-      if (rawData === null) {
+      if (!rawData) {
         return {
           Results: [],
           Success: false,
@@ -856,9 +914,10 @@ export class RunViewResolver extends ResolverBase {
         };
       }
 
-      const viewInfo = super.safeFirstArrayElement<MJUserViewEntityExtended>(await super.findBy<MJUserViewEntityExtended>(provider, "MJ: User Views", { ID: input.ViewID }, userPayload.userRecord));
-      const entity = provider.EntityByID(viewInfo.EntityID);
-      const returnData = this.processRawData(rawData.Results, viewInfo.EntityID, entity);
+      const viewInfo = (rawData as RunViewResultWithResolvedView)._resolvedViewEntity
+        ?? await this.resolveUserViewByID(input.ViewID, provider, userPayload.userRecord);
+      const entity = viewInfo ? provider.EntityByID(viewInfo.EntityID) : undefined;
+      const returnData = this.processRawData(rawData.Results, viewInfo?.EntityID ?? null, entity);
       return {
         Results: returnData,
         UserViewRunID: rawData?.UserViewRunID,
@@ -866,6 +925,7 @@ export class RunViewResolver extends ResolverBase {
         TotalRowCount: rawData?.TotalRowCount,
         ExecutionTime: rawData?.ExecutionTime,
         Success: rawData?.Success,
+        ErrorMessage: rawData?.ErrorMessage,
         AggregateResults: this.processAggregateResults(rawData?.AggregateResults),
         AggregateExecutionTime: rawData?.AggregateExecutionTime,
       };
@@ -1011,8 +1071,9 @@ export class RunViewResolver extends ResolverBase {
         };
       }
 
-      const entity = provider.EntityByName(input.ViewName);
-      const entityId = entity ? entity.ID : null;
+      const viewInfo = (rawData as RunViewResultWithResolvedView)._resolvedViewEntity;
+      const entity = viewInfo ? provider.EntityByID(viewInfo.EntityID) : provider.EntityByName(input.ViewName);
+      const entityId = viewInfo?.EntityID ?? (entity ? entity.ID : null);
       const returnData = this.processRawData(rawData.Results, entityId, entity);
       return {
         Results: returnData,
@@ -1058,9 +1119,10 @@ export class RunViewResolver extends ResolverBase {
         };
       }
 
-      const viewInfo = super.safeFirstArrayElement<MJUserViewEntityExtended>(await super.findBy<MJUserViewEntityExtended>(provider, "MJ: User Views", { ID: input.ViewID }, userPayload.userRecord));
-      const entity = provider.EntityByID(viewInfo.EntityID);
-      const returnData = this.processRawData(rawData.Results, viewInfo.EntityID, entity);
+      const viewInfo = (rawData as RunViewResultWithResolvedView)._resolvedViewEntity
+        ?? await this.resolveUserViewByID(input.ViewID, provider, userPayload.userRecord);
+      const entity = viewInfo ? provider.EntityByID(viewInfo.EntityID) : undefined;
+      const returnData = this.processRawData(rawData.Results, viewInfo?.EntityID ?? null, entity);
       return {
         Results: returnData,
         UserViewRunID: rawData?.UserViewRunID,
@@ -1264,6 +1326,7 @@ export class RunViewResolver extends ResolverBase {
           // DataSource must be forwarded on this transport too (same as the InternalRunView/RunViews maps):
           // otherwise a CacheLocal batch's DataSource:'Materialized' request silently reads the live view.
           DataSource: item.params.DataSource,
+          AlternateBaseView: item.params.AlternateBaseView,
           IncludeBinaryFields: item.params.IncludeBinaryFields,
           // BypassCache likewise — the input type (RunDynamicViewInput) has always declared it, and its
           // own description promises "the pre-check cache lookup is skipped". Dropping it here left the
@@ -1272,10 +1335,12 @@ export class RunViewResolver extends ResolverBase {
           AfterKey: item.params.AfterKey
             ? CompositeKey.FromKeyValuePairs(item.params.AfterKey.KeyValuePairs)
             : undefined,
+          TimeZone: userPayload?.TimeZone,
         },
         cacheStatus: item.cacheStatus ? {
           maxUpdatedAt: item.cacheStatus.maxUpdatedAt,
           rowCount: item.cacheStatus.rowCount,
+          fieldSecurityKey: item.cacheStatus.fieldSecurityKey ?? undefined,
         } : undefined,
       }));
 

package/src/generic/actionOutputFieldSecurity.ts

@@ -0,0 +1,75 @@
+import { BaseEntity, EntityInfo, RecordChangeMetadataSource, UserInfo } from '@memberjunction/core';
+import type { ActionParam } from '@memberjunction/actions-base';
+import { ProjectEntityObjectForCaller, ProjectValuesForCaller } from './fieldSecurityTransport.js';
+
+/**
+ * The parameters of an entity action that carry a plain copy of the bound record's field values
+ * (the `'Entity Object Data'` value type), and the entity those values belong to.
+ */
+export interface EntityObjectDataBinding {
+  EntityInfo: EntityInfo;
+  /** Parameter names, lowercased and trimmed. */
+  ParamNames: ReadonlySet<string>;
+}
+
+/**
+ * Action parameters as they may be sent back to `user`, with every value whose entity is KNOWN
+ * projected to the fields `user` may read:
+ *
+ * - an entity object (or an array holding them) becomes its projected field values, as an entity
+ *   object is serialized by its internal state otherwise; one whose entity `user` may not read at
+ *   all becomes `null`, since field projection narrows what a reader of the entity sees and must
+ *   not hand a non-reader the fields it is not denied;
+ * - a parameter named in `binding` holds the bound record's values, projected for its entity.
+ *
+ * Any other value is returned as it is: without knowing which entity a plain object belongs to,
+ * removing keys from it would be a guess. Returns the original array when nothing changed.
+ */
+export function ProjectActionParamsForCaller(
+  params: ActionParam[] | null | undefined,
+  user: UserInfo | null | undefined,
+  provider?: RecordChangeMetadataSource,
+  binding?: EntityObjectDataBinding
+): ActionParam[] | null | undefined {
+  if (!params?.length) {
+    return params;
+  }
+  const projected = params.map((p) => projectParam(p, user, provider, binding));
+  return projected.some((p, i) => p !== params[i]) ? projected : params;
+}
+
+function projectParam(
+  param: ActionParam,
+  user: UserInfo | null | undefined,
+  provider: RecordChangeMetadataSource | undefined,
+  binding: EntityObjectDataBinding | undefined
+): ActionParam {
+  const value: unknown = param?.Value;
+  if (value instanceof BaseEntity) {
+    return { ...param, Value: projectEntityObject(value, user, provider) };
+  }
+  if (Array.isArray(value) && value.some((item) => item instanceof BaseEntity)) {
+    const items = value.map((item: unknown) => (item instanceof BaseEntity ? projectEntityObject(item, user, provider) : item));
+    return { ...param, Value: items };
+  }
+  if (binding && isPlainRecord(value) && binding.ParamNames.has(String(param.Name ?? '').trim().toLowerCase())) {
+    return { ...param, Value: ProjectValuesForCaller(binding.EntityInfo, value, user, provider) };
+  }
+  return param;
+}
+
+/** An entity object's values projected for `user`, or null when `user` may not read its entity at all. */
+function projectEntityObject(
+  entity: BaseEntity,
+  user: UserInfo | null | undefined,
+  provider: RecordChangeMetadataSource | undefined
+): Record<string, unknown> | null {
+  if (user && !entity.EntityInfo?.GetUserPermisions(user)?.CanRead) {
+    return null;
+  }
+  return ProjectEntityObjectForCaller(entity, user, provider);
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date);
+}

package/src/generic/fieldSecurityTransport.ts

@@ -0,0 +1,62 @@
+import {
+  EntityInfo,
+  Metadata,
+  ProjectEntityValueRowsForUser,
+  ProjectEntityValuesForUser,
+  RecordChangeMetadataSource,
+  UserInfo,
+} from '@memberjunction/core';
+
+/**
+ * The members of an entity object the output projection reads. `BaseEntity` satisfies it; so does
+ * any test double that carries an `EntityInfo` and a `GetAll()`.
+ */
+export interface ProjectableEntityObject {
+  readonly EntityInfo?: EntityInfo | null;
+  GetAll(): Record<string, unknown>;
+}
+
+/**
+ * Field values of `entity`, reduced to what `user` may READ, for a transport that sends them to
+ * that user.
+ *
+ * An entity object built for a restricted user already holds no denied value, so for those this
+ * is a no-op returning the `GetAll()` copy unchanged. It is the backstop for objects that were not
+ * built for the recipient: a system-identity load, an object a long-running process shares across
+ * callers, or one built before its user was known.
+ *
+ * @param provider Metadata source for the Record Changes payload projection. Defaults to the
+ *   global provider, which is only consulted when the entity is `MJ: Record Changes`.
+ */
+export function ProjectEntityObjectForCaller(
+  entity: ProjectableEntityObject,
+  user: UserInfo | null | undefined,
+  provider?: RecordChangeMetadataSource
+): Record<string, unknown> {
+  // fls-guard: projected by ProjectEntityValuesForUser below
+  const values = entity.GetAll();
+  return ProjectEntityValuesForUser(provider ?? new Metadata(), entity.EntityInfo, values, user) ?? values;
+}
+
+/**
+ * Plain field values of `entityInfo`, reduced to what `user` may READ. See
+ * {@link ProjectEntityObjectForCaller}; this is the form for values that are already plain objects.
+ */
+export function ProjectValuesForCaller<T extends object>(
+  entityInfo: EntityInfo | null | undefined,
+  values: T,
+  user: UserInfo | null | undefined,
+  provider?: RecordChangeMetadataSource
+): T {
+  return ProjectEntityValuesForUser(provider ?? new Metadata(), entityInfo, values, user) ?? values;
+}
+
+/** Array form of {@link ProjectValuesForCaller}: the denied set is computed once for the whole set. */
+export function ProjectRowsForCaller<T extends object>(
+  entityInfo: EntityInfo | null | undefined,
+  rows: T[],
+  user: UserInfo | null | undefined,
+  provider?: RecordChangeMetadataSource
+): T[] {
+  return ProjectEntityValueRowsForUser(provider ?? new Metadata(), entityInfo, rows, user) ?? rows;
+}