@memberjunction/server 6.2.0-edge.4 → 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,
@@ -1212,6 +1274,8 @@ export class RunViewResolver extends ResolverBase {
     @Ctx() { providers, userPayload }: AppContext
   ): Promise<RunViewsWithCacheCheckOutput> {
     try {
+      // Same scope as RunViews: this is the transport RunViews uses for a CacheLocal batch.
+      await this.CheckAPIKeyScopeAuthorization('view:batch', '*', userPayload);
       const provider = GetReadOnlyProvider(providers, { allowFallbackToReadWrite: true });
 
       // Cast provider to SQLServerDataProvider to access RunViewsWithCacheCheck method
@@ -1220,6 +1284,21 @@ export class RunViewResolver extends ResolverBase {
         throw new Error('Provider does not support RunViewsWithCacheCheck');
       }
 
+      // SECURITY: same GraphQL-boundary clause screen as RunViews, before the provider runs.
+      const user = this.GetUserFromPayload(userPayload);
+      for (const item of input) {
+        this.screenClientViewClauses(
+          {
+            extraFilter: item.params.ExtraFilter,
+            orderBy: item.params.OrderBy,
+            userSearchString: item.params.UserSearchString,
+            overrideExcludeFilter: item.params.OverrideExcludeFilter,
+          },
+          provider,
+          user,
+        );
+      }
+
       // Convert GraphQL input types to core types
       const coreParams: RunViewWithCacheCheckParams[] = input.map(item => ({
         params: {
@@ -1247,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
@@ -1255,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;
+}

package/src/globalCors.ts

@@ -0,0 +1,71 @@
+import cors from 'cors';
+import type { RequestHandler } from 'express';
+import { IsPathUnderServerExtensionRoot, SkipForServerExtensionRoots } from '@memberjunction/server-extensions-core';
+import type { CorsConfig } from './config.js';
+
+/**
+ * The `cors` section of the MJServer config that the global CORS middleware reads: `allowedOrigins`
+ * (`['*']` by default — every origin, without credentials), `allowCredentials` (ignored, always
+ * false, under the wildcard) and `maxAge` (preflight cache lifetime in seconds, 86400 by default).
+ * Partial, because tests and hosts may pass only the keys they care about.
+ */
+export type GlobalCorsSettings = Partial<CorsConfig>;
+
+/**
+ * Builds MJServer's global CORS middleware, mounted before auth so 401 responses carry CORS
+ * headers (without them the browser hides the error code and the client never refreshes its token).
+ *
+ * `extensionOwnedRoots` are the RootPaths of server extensions that declare `OwnsCORS: true`
+ * (see `GetCorsOwningServerExtensionRoots`). The global middleware skips requests under those
+ * roots entirely, so it neither reflects an origin onto the extension's responses nor answers
+ * its preflights; the extension's own CORS handling runs instead.
+ */
+export function CreateGlobalCorsMiddleware(
+    settings: GlobalCorsSettings | undefined,
+    extensionOwnedRoots: readonly string[] = [],
+): RequestHandler {
+    const corsAllowed = settings?.allowedOrigins ?? ['*'];
+    const corsWildcard = corsAllowed.includes('*');
+    // SECURITY: never combine credentials with a wildcard/reflect-any-origin policy. When
+    // allowedOrigins is ['*'] the origin callback reflects the caller's Origin, and pairing that
+    // with Access-Control-Allow-Credentials: true lets any site a signed-in user visits make
+    // credentialed cross-origin reads. MJ's primary auth is a Bearer token (not auto-sent
+    // cross-origin), so dropping credentials under the wildcard default is safe; deployments that
+    // genuinely need credentialed CORS must configure an explicit allowedOrigins list.
+    const globalCors = cors<cors.CorsRequest>({
+        origin: (origin, callback) => {
+            // Allow all origins when ['*'] (default/backward-compatible),
+            // or when no Origin header (server-to-server calls).
+            if (corsWildcard || !origin || corsAllowed.includes(origin)) {
+                callback(null, true);
+            } else {
+                callback(new Error(`Origin ${origin} not allowed by CORS`));
+            }
+        },
+        credentials: corsWildcard ? false : (settings?.allowCredentials ?? true),
+        maxAge: settings?.maxAge ?? 86400,
+    }) as RequestHandler;
+    return SkipForServerExtensionRoots(globalCors, extensionOwnedRoots);
+}
+
+/**
+ * Terminates a preflight under an extension-owned root that no extension answered.
+ *
+ * Mount it after every server extension (both phases) and before the core routes. Without it, an
+ * unanswered `OPTIONS` request falls through to the next CORS-enabled mount — the GraphQL endpoint
+ * at `/` by default, whose `cors()` approves every origin with `Access-Control-Allow-Origin: *` —
+ * so an extension that owns its CORS but forgets an `OPTIONS` handler would be opened to every
+ * origin rather than closed. The answer is a bare 404 with no CORS headers, which the browser
+ * treats as a refused preflight.
+ *
+ * @param extensionOwnedRoots - RootPaths of extensions that declare `OwnsCORS: true`
+ */
+export function CreateExtensionOwnedPreflightFallback(extensionOwnedRoots: readonly string[]): RequestHandler {
+    return (req, res, next) => {
+        if (req.method === 'OPTIONS' && IsPathUnderServerExtensionRoot(req.path, extensionOwnedRoots)) {
+            res.status(404).end();
+            return;
+        }
+        next();
+    };
+}