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

package/src/resolvers/TaskGraphFrameResolver.ts

@@ -19,6 +19,7 @@ import { Arg, Field, ID, ObjectType, PubSubEngine, Resolver, ResolverFilterData,
 import { LogError } from '@memberjunction/core';
 import { UUIDsEqual } from '@memberjunction/global';
 import type { TaskGraphFrame, TaskGraphObserver } from '@memberjunction/task-graph';
+import { PublishStatusUpdate } from '../generic/PushStatusResolver.js';
 
 export const TASK_GRAPH_FRAMES_TOPIC = 'TASK_GRAPH_FRAMES';
 
@@ -173,7 +174,10 @@ export function taskGraphFrameFilter(data: {
  * the same reason.
  */
 export class TaskGraphFrameBroadcaster implements TaskGraphObserver {
-  constructor(private readonly pubSub: PubSubEngine) {}
+  constructor(
+    private readonly pubSub: PubSubEngine,
+    private readonly bridgeToPushStatus: boolean = false,
+  ) {}
 
   public OnFrame(frame: TaskGraphFrame): void {
     try {
@@ -187,6 +191,34 @@ export class TaskGraphFrameBroadcaster implements TaskGraphObserver {
         TASK_GRAPH_FRAMES_TOPIC,
         { ...frame, ownerUserId: frame.OwnerUserID } satisfies TaskGraphFramePayload,
       );
+
+      if (
+        this.bridgeToPushStatus &&
+        (frame.Kind === 'TaskStarted' ||
+          frame.Kind === 'TaskCompleted' ||
+          frame.Kind === 'TaskFailed' ||
+          frame.Kind === 'NodeProgress' ||
+          frame.Kind === 'GraphSettled')
+      ) {
+        const defaultMsg = frame.TaskName
+          ? `${frame.TaskName}: ${frame.Status ?? frame.Kind}`
+          : `Workflow: ${frame.Status ?? frame.Kind}`;
+        PublishStatusUpdate(this.pubSub, {
+          sessionId: '*',
+          ownerUserId: frame.OwnerUserID,
+          message: JSON.stringify({
+            resolver: 'TaskOrchestrator',
+            type: 'TaskGraphFrame',
+            status: 'ok',
+            data: {
+              ...frame,
+              taskName: frame.TaskName,
+              message: frame.ProgressMessage || defaultMsg,
+              percentComplete: frame.ProgressPercent,
+            },
+          }),
+        });
+      }
     } catch (e) {
       LogError(`[TaskGraphFrameBroadcaster] Could not publish ${frame.Kind} (ignored): ${e instanceof Error ? e.message : String(e)}`);
     }

package/src/resolvers/TestQuerySQLResolver.ts

@@ -1,9 +1,12 @@
 import { Arg, Ctx, Field, InputType, Int, ObjectType, Query, Resolver } from 'type-graphql';
 import { GraphQLJSONObject } from 'graphql-type-json';
 import { RunQuery, IRunQueryProvider, LogError, LogStatus, QueryExecutionSpec } from '@memberjunction/core';
+import type { DatabaseProviderBase, UserInfo } from '@memberjunction/core';
+import { RenderPipeline } from '@memberjunction/generic-database-provider';
 import { AppContext } from '../types.js';
 import { GetReadOnlyProvider } from '../util.js';
 import { ResolverBase } from '../generic/ResolverBase.js';
+import { IsScopeLimitedPrincipal } from '../auth/scopeLimitedPrincipal.js';
 
 /**
  * GraphQL input type for inline dependency queries.
@@ -88,6 +91,14 @@ export class TestQuerySQLResult {
  *
  * Security:
  * - Requires `query:test` scope for API key users (no-op for JWT auth)
+ * - Refuses scope-limited principals (see {@link IsScopeLimitedPrincipal}). Raw SQL bypasses
+ *   RunView, entity permissions and row-level security, so the RLS scope tokens that confine a
+ *   magic-link session are never applied on this path — there is no narrower filter to fall back
+ *   to, only refusal.
+ * - Authorizes the RENDERED SQL: every table reference must be an entity base view the caller
+ *   reads unscoped (CanRead, no row-level filter, no denied fields). Entities with row/field
+ *   policy for this user are refused — raw SQL cannot apply that policy, so those reads belong
+ *   on RunView. Same screen as {@link AdhocQueryResolver.ExecuteAdhocQuery}.
  * - Uses read-only database connection (no mutation possible)
  * - Enforces MaxRows limit (default 100) to prevent unbounded queries
  *
@@ -104,15 +115,24 @@ export class TestQuerySQLResolver extends ResolverBase {
     ): Promise<TestQuerySQLResult> {
         try {
             await this.CheckAPIKeyScopeAuthorization('query:test', '*', context.userPayload);
+            // SECURITY: refuse principals whose read authority is narrower than their role grant.
+            // Transient test SQL does not go through RunView, entity permissions or row-level
+            // security, so the RLS scope tokens that confine a magic-link session are never
+            // substituted. There is no filter to narrow, so the only correct answer for such a
+            // principal is no — the same refusal ExecuteAdhocQuery applies.
+            if (IsScopeLimitedPrincipal(context.userPayload?.userRecord)) {
+                return this.buildErrorResult('Ad-hoc SQL execution is not permitted for scope-limited sessions.');
+            }
             // Use read-only provider for security — no mutation possible
             const provider = GetReadOnlyProvider(context.providers, { allowFallbackToReadWrite: false });
             if (!provider) {
-                return {
-                    Success: false,
-                    RowCount: 0,
-                    ExecutionTime: 0,
-                    ErrorMessage: 'Read-only data source is not available. TestQuerySQL requires a read-only connection for security.',
-                };
+                return this.buildErrorResult('Read-only data source is not available. TestQuerySQL requires a read-only connection for security.');
+            }
+
+            const contextUser = context.userPayload?.userRecord;
+            const refusal = this.AuthorizeRenderedTestSQL(input, provider, contextUser);
+            if (refusal) {
+                return this.buildErrorResult(refusal);
             }
 
             const rq = new RunQuery(provider as unknown as IRunQueryProvider);
@@ -127,7 +147,7 @@ export class TestQuerySQLResolver extends ResolverBase {
 
             LogStatus(`TestQuerySQL: Executing transient query (MaxRows=${spec.MaxRows}, UsesTemplate=${spec.UsesTemplate ?? false}, Dependencies=${spec.Dependencies?.length ?? 0})`);
 
-            const result = await rq.ExecuteFromSpec(spec, context.userPayload.userRecord);
+            const result = await rq.ExecuteFromSpec(spec, contextUser);
 
             return {
                 Success: result.Success,
@@ -141,12 +161,47 @@ export class TestQuerySQLResolver extends ResolverBase {
         } catch (err) {
             LogError(err);
             const errorMessage = err instanceof Error ? err.message : String(err);
-            return {
-                Success: false,
-                RowCount: 0,
-                ExecutionTime: 0,
-                ErrorMessage: `TestQuerySQL failed: ${errorMessage}`,
-            };
+            return this.buildErrorResult(`TestQuerySQL failed: ${errorMessage}`);
         }
     }
+
+    /**
+     * SECURITY: authorizes the READ itself, against the SQL that will actually run — the same
+     * screen `AdhocQueryResolver.AuthorizeRenderedSQL` applies to ad-hoc SQL. Rendering comes
+     * first because composition (`{{query:"..."}}`), inline dependencies and Nunjucks templates
+     * can introduce table references the raw input never named, so the render here uses the same
+     * Parameters / UsesTemplate / Dependencies the execution spec will. Every table reference in
+     * the rendered SQL must be an entity base view the caller can read UNSCOPED — CanRead with no
+     * row-level filter and no denied fields — because raw SQL applies neither (see
+     * `assertFullQueryUsesReadableEntityViews`). The provider renders the same input the same way
+     * and only wraps it in server-built MaxRows capping, so the rendered SQL is the full set of
+     * reads. Returns the refusal message, or null.
+     */
+    public AuthorizeRenderedTestSQL(input: TestQuerySQLInput, provider: DatabaseProviderBase, contextUser: UserInfo | undefined): string | null {
+        try {
+            const rendered = RenderPipeline.Run(input.SQL, {
+                Platform: provider.PlatformKey,
+                ContextUser: contextUser,
+                Parameters: input.Parameters,
+                UsesTemplate: input.UsesTemplate,
+                Dependencies: input.Dependencies,
+                OriginalSQL: input.SQL,
+                RequireReadStatement: true,
+            });
+            this.assertFullQueryUsesReadableEntityViews(rendered.Trace.AfterTemplates, provider, contextUser, 'transient test SQL');
+            return null;
+        } catch (err) {
+            return err instanceof Error ? err.message : String(err);
+        }
+    }
+
+    /** Builds a failed TestQuerySQLResult carrying the given message. */
+    private buildErrorResult(errorMessage: string): TestQuerySQLResult {
+        return {
+            Success: false,
+            RowCount: 0,
+            ExecutionTime: 0,
+            ErrorMessage: errorMessage,
+        };
+    }
 }

package/src/resolvers/TransactionGroupResolver.ts

@@ -1,7 +1,7 @@
 import { Arg, Ctx, Field, InputType, Int, Mutation, ObjectType, registerEnumType } from 'type-graphql';
 import { AppContext } from '../types.js';
-import { CompositeKey, IMetadataProvider, KeyValuePair, LogError, Metadata, TransactionVariable, BaseEntity, EntityDeleteOptions, EntitySaveOptions } from '@memberjunction/core';
-import { SafeJSONParse } from '@memberjunction/global';
+import { CompositeKey, EntityInfo, IMetadataProvider, KeyValuePair, LogError, Metadata, TransactionVariable, TransactionGroupBase, BaseEntity, EntityDeleteOptions, EntitySaveOptions } from '@memberjunction/core';
+import { SafeJSONParse, ValuesEqual } from '@memberjunction/global';
 import { GetReadWriteProvider } from '../util.js';
 import { ResolverBase } from '../generic/ResolverBase.js';
 
@@ -142,11 +142,19 @@ export class TransactionResolver extends ResolverBase {
             // rows were all refused arrive at Submit() empty, take its legitimate "nothing to do"
             // branch, and report success for writes that never happened.
             const refusals: string[] = [];
+            const preUpdateValues = new Map<number, Record<string, unknown>>();
+
+            // instantiate an entity object for every item first, so the group's variables are known
+            // 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.
+            for (const item of group.Items) {
+                entityObjects.push(await md.GetEntityObject(item.EntityName, context.userPayload.userRecord));
+            }
+            this.AddNetworkVariables(group, entityObjects, tg);
 
             for (const [index, item] of group.Items.entries()) {
-                // instantiate a new entity object for the item
-                const entity = await md.GetEntityObject(item.EntityName, context.userPayload.userRecord);
-                entityObjects.push(entity); // save for later for mapping variables if needed
+                const entity = entityObjects[index];
 
                 // get the values from the payload
                 const itemValues = SafeJSONParse(item.EntityObjectJSON);
@@ -162,6 +170,11 @@ export class TransactionResolver extends ResolverBase {
                     case "Create":
                         if (item.OperationType === "Update") {
                             await entity.InnerLoad(pkey);
+                            if (typeof entity.GetDataObject === 'function') {
+                                preUpdateValues.set(index, await entity.GetDataObject());
+                            } else if (typeof entity.GetAll === 'function') {
+                                preUpdateValues.set(index, { ...(entity.GetAll() as Record<string, unknown>) });
+                            }
                         }
                         objectValues.push(itemValues);
                         entity.SetMany(itemValues, true);
@@ -208,32 +221,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);
-            }
-
-            // now, we need to set the variables
-            if (group.Variables && group.Variables.length > 0) {
-                for (const networkVar of group.Variables) {
-                    // for each variable, add it to the transaction group and map the index from the network payload to the specific entity object loaded up above
-                    if (networkVar.ItemIndex >= 0 && networkVar.ItemIndex < entityObjects.length) {
-                        const entityObject = entityObjects[networkVar.ItemIndex];
-                        const newVar = new TransactionVariable(networkVar.Name, entityObject, networkVar.FieldName, networkVar.Type);
-                        tg.AddVariable(newVar);
-                    }
-                    else {
-                        throw new Error(`TransactionResolver::ExecuteTransactionGroup --- Error\n\n' + 'Invalid ItemIndex ${networkVar.ItemIndex} in TransactionVariable "${JSON.stringify(networkVar)}"`);
-                    }
-                }
+                return await this.PrepareReturnValue(false, entityObjects, objectValues, group, preUpdateValues);
             }
 
             // 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);
+                return await this.PrepareReturnValue(true, entityObjects, objectValues, group, preUpdateValues);
             }
             else {
                 // failure, send back the results
-                return await this.PrepareReturnValue(false, entityObjects, objectValues, group);
+                return await this.PrepareReturnValue(false, entityObjects, objectValues, group, preUpdateValues);
             }
         } 
         catch (err) {
@@ -242,15 +240,48 @@ export class TransactionResolver extends ResolverBase {
         }
     }
 
-    protected async PrepareReturnValue(success: boolean, entityObjects: BaseEntity[], objectValues: any[], group: TransactionInputType): Promise<TransactionOutputType> {
+    /**
+     * Adds the network payload's variables to the group, mapping each one's item index to the entity
+     * object built for that item.
+     */
+    protected AddNetworkVariables(group: TransactionInputType, entityObjects: BaseEntity[], tg: TransactionGroupBase): void {
+        for (const networkVar of group.Variables ?? []) {
+            if (networkVar.ItemIndex >= 0 && networkVar.ItemIndex < entityObjects.length) {
+                const entityObject = entityObjects[networkVar.ItemIndex];
+                tg.AddVariable(new TransactionVariable(networkVar.Name, entityObject, networkVar.FieldName, networkVar.Type));
+            }
+            else {
+                throw new Error(`TransactionResolver::ExecuteTransactionGroup --- Error\n\n' + 'Invalid ItemIndex ${networkVar.ItemIndex} in TransactionVariable "${JSON.stringify(networkVar)}"`);
+            }
+        }
+    }
+
+    protected async PrepareReturnValue(
+        success: boolean,
+        entityObjects: BaseEntity[],
+        objectValues: unknown[],
+        group: TransactionInputType,
+        preUpdateValues?: Map<number, Record<string, unknown>>
+    ): Promise<TransactionOutputType> {
         const jsonResults = [];
         for (let i = 0; i < group.Items.length; i++) {
             const item = group.Items[i];
-            if (item.OperationType==='Delete') {
+            if (item.OperationType === 'Delete') {
                 jsonResults.push(JSON.stringify(objectValues[i]));
             }
+            else if (item.OperationType === 'Update') {
+                jsonResults.push(
+                    await this.serializeUpdateReturnValue(
+                        entityObjects[i],
+                        objectValues[i],
+                        preUpdateValues?.get(i),
+                        group,
+                        i
+                    )
+                );
+            }
             else {
-                // create or update, return what is in the database
+                // create, return what is in the database
                 jsonResults.push(await entityObjects[i].GetDataObjectJSON());
             }
         }
@@ -261,6 +292,79 @@ export class TransactionResolver extends ResolverBase {
             ResultsJSON: jsonResults
         }
     }
- 
+
+    /**
+     * Serializes a delta return payload for an `Update` transaction group item containing:
+     * - Primary key fields
+     * - All keys sent by the client in `sentValues` (`objectValues[i]`)
+     * - Any `TransactionVariable` fields targeting this item
+     * - `__mj_CreatedAt` and `__mj_UpdatedAt`
+     * - Virtual fields when any foreign key field was in `sentValues`
+     * - 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.
+     */
+    private async serializeUpdateReturnValue(
+        entity: BaseEntity,
+        sentValues: unknown,
+        preSaveValues: Record<string, unknown> | undefined,
+        group: TransactionInputType,
+        itemIndex: number
+    ): Promise<string> {
+        const fullDataObj: Record<string, unknown> | null = typeof entity.GetDataObject === 'function'
+            ? (await entity.GetDataObject() as Record<string, unknown>)
+            : SafeJSONParse<Record<string, unknown>>(await entity.GetDataObjectJSON());
+        if (!fullDataObj || typeof fullDataObj !== 'object' || !sentValues || typeof sentValues !== 'object') {
+            return await entity.GetDataObjectJSON();
+        }
+
+        const sentRecord = sentValues as Record<string, unknown>;
+        const includeKeys = new Set<string>([
+            EntityInfo.CreatedAtFieldName,
+            EntityInfo.UpdatedAtFieldName,
+        ]);
+
+        for (const pk of entity.PrimaryKeys ?? []) {
+            if (pk?.Name) {
+                includeKeys.add(pk.Name);
+            }
+        }
+        for (const key of Object.keys(sentRecord)) {
+            includeKeys.add(key);
+        }
+        for (const v of group.Variables ?? []) {
+            if (v.ItemIndex === itemIndex && v.FieldName) {
+                includeKeys.add(v.FieldName);
+            }
+        }
+        if (Array.isArray(entity.Fields)) {
+            for (const f of entity.Fields) {
+                if (
+                    f.EntityFieldInfo?.IsSpecialDateField ||
+                    Boolean(f.EntityFieldInfo?.IsVirtual) ||
+                    Boolean(f.EntityFieldInfo?.IsComputed) ||
+                    f.ReadOnly
+                ) {
+                    includeKeys.add(f.Name);
+                }
+            }
+        }
+        if (preSaveValues) {
+            for (const key of Object.keys(fullDataObj)) {
+                if (!ValuesEqual(fullDataObj[key], preSaveValues[key])) {
+                    includeKeys.add(key);
+                }
+            }
+        }
+
+        const deltaObj: Record<string, unknown> = {};
+        for (const key of Object.keys(fullDataObj)) {
+            if (includeKeys.has(key)) {
+                deltaObj[key] = fullDataObj[key];
+            }
+        }
+        return JSON.stringify(deltaObj);
+    }
+
 }
  

package/src/resolvers/__tests__/GetDataResolver.validation.test.ts

@@ -0,0 +1,95 @@
+// type-graphql decorators on the resolver class need the reflect-metadata polyfill.
+import 'reflect-metadata';
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { MockInstance } from 'vitest';
+import { SQLExpressionValidator } from '@memberjunction/global';
+
+const { executedSQL } = vi.hoisted(() => ({ executedSQL: [] as string[] }));
+
+// GetData's server bootstrap, provider, auth and driver imports are replaced so the resolver runs
+// offline. The fake driver records every text it is asked to run.
+vi.mock('../../index.js', () => ({ GetDbType: () => 'sqlserver' }));
+vi.mock('@memberjunction/generic-database-provider', () => ({
+  QueryCompositionEngine: class {
+    HasCompositionTokens(): boolean {
+      return false;
+    }
+  },
+}));
+vi.mock('../../util.js', () => ({ GetReadOnlyDataSource: () => ({}), GetReadOnlyProvider: () => null }));
+vi.mock('../../auth/index.js', () => ({ GetSystemUser: async () => ({}) }));
+vi.mock('mssql', () => ({
+  default: {
+    Request: class {
+      async query(text: string): Promise<{ recordset: Array<Record<string, unknown>> }> {
+        executedSQL.push(text);
+        return { recordset: [] };
+      }
+    },
+  },
+}));
+
+import { GetDataResolver, GetDataInputType, GetDataOutputType, RegisterAccessToken } from '../GetDataResolver.js';
+import type { AppContext } from '../../types.js';
+
+const CONTEXT = { dataSources: [] } as unknown as AppContext;
+
+let tokenSeq = 0;
+
+/** Calls GetData with a fresh valid token. */
+async function runGetData(queries: string[]): Promise<GetDataOutputType> {
+  const token = `getdata-validation-${Date.now()}-${++tokenSeq}`;
+  RegisterAccessToken(token, 60_000);
+  const input = Object.assign(new GetDataInputType(), { Token: token, Queries: queries });
+  return new GetDataResolver().GetData(input, CONTEXT);
+}
+
+/** The text of every call to the validator's `validate` method. */
+function validatedTexts(spy: MockInstance<SQLExpressionValidator['validate']>): string[] {
+  return spy.mock.calls.map(([text]) => text);
+}
+
+describe('GetData runs exactly the SQL it validated', () => {
+  beforeEach(() => {
+    executedSQL.length = 0;
+  });
+
+  it('validates and runs the same text when the query contains backslash sequences', async () => {
+    const query = String.raw`SELECT Name FROM __mj.vwFiles WHERE Path = 'C:\new\temp'`;
+    const validateSpy = vi.spyOn(SQLExpressionValidator.Instance, 'validate');
+
+    const output = await runGetData([query]);
+
+    expect(output.ErrorMessages).toEqual([null]);
+    expect(executedSQL).toEqual(validatedTexts(validateSpy));
+    expect(executedSQL).toEqual([query]);
+    expect(validateSpy).toHaveBeenCalledWith(query, { context: 'full_query', Dialect: 'sqlserver' });
+  });
+
+  it('runs the trimmed text that the validator reads', async () => {
+    const validateSpy = vi.spyOn(SQLExpressionValidator.Instance, 'validate');
+
+    const output = await runGetData(['\n  SELECT 1 AS One  \n']);
+
+    expect(output.ErrorMessages).toEqual([null]);
+    expect(executedSQL).toEqual(['SELECT 1 AS One']);
+    expect(validatedTexts(validateSpy)).toEqual(executedSQL);
+  });
+
+  it('refuses a query whose text, as written, does not open with SELECT or WITH', async () => {
+    const output = await runGetData(["-- note\\n SELECT 1\nPRINT 'hello'"]);
+
+    expect(executedSQL).toEqual([]);
+    expect(output.Success).toBe(false);
+    expect(output.ErrorMessages[0]).toMatch(/must start with SELECT or WITH/);
+  });
+
+  it('does not run a refused query and still runs the others', async () => {
+    const output = await runGetData(['SELECT 1; SELECT 2', 'SELECT 1 AS One']);
+
+    expect(executedSQL).toEqual(['SELECT 1 AS One']);
+    expect(output.ErrorMessages[0]).toMatch(/Semicolons are not allowed/);
+    expect(output.ErrorMessages[1]).toBeNull();
+  });
+});

package/src/resolvers/agent-run-data-guard.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Decides which callers of the agent-run resolvers may set a run's scope or agent-type parameters
+ * through the free-form `data` argument.
+ *
+ * `BaseAgent` and `AgentRunner` read a few `ExecuteAgentParams.data` keys (`RESERVED_AGENT_RUN_DATA_KEYS` in
+ * `@memberjunction/ai-core-plus`) as fallbacks that change what a run is, not just what its prompt says:
+ *  - `PrimaryScopeEntityName`, `PrimaryScopeRecordID`, `SecondaryScopes` decide the run's scope: which
+ *    notes and examples memory is injected, the pre-execution RAG search context, the scoped prompt parts
+ *    and run settings, the scope columns written on the `MJ: AI Agent Runs` row, and what sub-agents
+ *    inherit. On a widget-guest run an explicit scope also beats the returning-visitor scope.
+ *  - `__agentTypePromptParams` is the highest-precedence agent-type parameter layer. It can turn on the
+ *    Loop type's `enableTaskGraphs` capability, and switch decisions on or off.
+ *
+ * The rule lives with the run, not here: `BaseAgent.Execute` drops those keys from every run's `data` unless the
+ * params set `ExecuteAgentParams.TrustReservedRunData`. The resolvers set that marker for the callers
+ * {@link IsTrustedAgentRunCaller} accepts — the system user, and an `mj_sk_*` API key that holds the
+ * {@link TRUSTED_RUN_DATA_SCOPE} scope — and never for a browser or a widget guest. Any user who may create API
+ * keys can mint one for themselves, so a key alone is not enough: an administrator grants the scope. Explorer never
+ * sends these keys. Everything else in `data` (template data, `conversationId`, `appContext`, `clientTools`, ...)
+ * reaches the run unchanged either way.
+ *
+ * @module @memberjunction/server/resolvers
+ */
+import { LogError } from '@memberjunction/core';
+import { GetAPIKeyEngine } from '@memberjunction/api-keys';
+import { UserCache } from '@memberjunction/generic-database-provider';
+import type { UserPayload } from '../types.js';
+
+/**
+ * The API-key scope (`MJ: API Scopes.FullPath`) that makes an `mj_sk_*` key a trusted integration for reserved run
+ * data. Checked against the agent being run, so a key can be trusted for some agents only. `full_access` does not
+ * imply it: the key must hold this scope itself.
+ */
+export const TRUSTED_RUN_DATA_SCOPE = 'agent:trusted';
+
+/** Who sent a run's `data`, as far as {@link IsTrustedAgentRunCaller} needs to know. */
+export interface ClientAgentRunCaller {
+    /**
+     * The request's authenticated payload, BEFORE any widget-guest elevation. `isSystemUser` is set only by
+     * the system API key (and by widget elevation, which {@link IsWidgetGuestRun} overrides); `apiKeyHash`
+     * only by an `mj_sk_*` user API key.
+     */
+    UserPayload: Pick<UserPayload, 'email' | 'isSystemUser' | 'apiKeyHash'>;
+    /** True when the run executes under the widget-guest elevated principal. Such a run is never trusted. */
+    IsWidgetGuestRun: boolean;
+    /** The agent the caller asked to run: the resource the {@link TRUSTED_RUN_DATA_SCOPE} check is made against. */
+    AgentID: string;
+}
+
+/**
+ * Whether a caller may set the reserved run-data keys — the value the agent-run resolvers pass as
+ * `ExecuteAgentParams.TrustReservedRunData`: the system user, or an API key that holds
+ * {@link TRUSTED_RUN_DATA_SCOPE} for this agent, and never a widget-guest run, whatever principal it was elevated to.
+ * A key without the scope is treated like the browser session of the user it belongs to.
+ *
+ * @param caller - Who sent the run's `data`.
+ * @returns `true` when the run may read the reserved keys from `data`.
+ */
+export async function IsTrustedAgentRunCaller(caller: ClientAgentRunCaller): Promise<boolean> {
+    if (caller.IsWidgetGuestRun) {
+        return false;
+    }
+    if (caller.UserPayload.isSystemUser === true) {
+        return true;
+    }
+    const apiKeyHash = caller.UserPayload.apiKeyHash;
+    return apiKeyHash ? keyHoldsTrustedRunDataScope(apiKeyHash, caller.AgentID) : false;
+}
+
+/**
+ * Whether the key explicitly holds {@link TRUSTED_RUN_DATA_SCOPE} for the agent. A key-level rule must match: an
+ * allow that comes from scope enforcement being switched off, or from `defaultBehaviorNoScopes: 'allow'`, matches
+ * no rule and does not count. Any failure counts as not held.
+ */
+async function keyHoldsTrustedRunDataScope(apiKeyHash: string, agentID: string): Promise<boolean> {
+    try {
+        const systemUser = UserCache.Instance.GetSystemUser();
+        if (!systemUser) {
+            return false;
+        }
+        // A probe, not an access decision (the run goes ahead either way), so it is not written to the usage log.
+        const result = await GetAPIKeyEngine().Authorize(apiKeyHash, 'MJAPI', TRUSTED_RUN_DATA_SCOPE, agentID, systemUser,
+            { endpoint: '/graphql', method: 'POST' }, { skipLogging: true });
+        return result.Allowed && result.MatchedKeyRule != null;
+    } catch (e) {
+        LogError(`IsTrustedAgentRunCaller: the ${TRUSTED_RUN_DATA_SCOPE} check failed; the run is not trusted: ${e}`);
+        return false;
+    }
+}