@memberjunction/server 5.43.0 → 5.45.0

package/src/realtimeWidget/widgetGuestElevation.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Privileged-dispatch elevation for public web-widget guests (public-web-widget.md
+ * Phase 0). A widget guest's session JWT authorizes ONLY its own Conversation + Conversation
+ * Details (RLS-scoped). The agent itself runs under a TRUSTED SERVER PRINCIPAL — so a guest needs
+ * no grants to WRITE the AI run entities, and cannot run an arbitrary agent under the elevated
+ * principal: the pinned agent is resolved AUTHORITATIVELY from the widget instance named by the
+ * signed `mj_widget_id` claim, never from a client-supplied agent id.
+ *
+ * The companion read-side control is the `Widget Guest: Own Agent Runs` RLS filter (seeded in the
+ * Phase 0 migration), which confines a guest to reading only its own session's run rows — closing
+ * the cross-guest leak for the voice path, where runs are still written under the guest principal.
+ *
+ * @module @memberjunction/server/widget
+ */
+
+import { RunView, LogError, type UserInfo, type DatabaseProviderBase } from '@memberjunction/core';
+import type { MJConversationWidgetInstanceEntity } from '@memberjunction/core-entities';
+import { UserCache } from '@memberjunction/sqlserver-dataprovider';
+import type { UserPayload } from '../types.js';
+
+const WIDGET_ENTITY = 'MJ: Conversation Widget Instances';
+
+/**
+ * Resolved elevation context for a widget-guest agent run. Returned only when the request is a
+ * widget guest; the dispatch resolver runs the agent under {@link WidgetGuestRunContext.elevatedUser}
+ * with {@link WidgetGuestRunContext.pinnedAgentId} (authoritative), keeping ownership checks under
+ * the guest principal.
+ */
+export interface WidgetGuestRunContext {
+  /** The trusted server principal under which the agent run (and its run-entity writes) executes. */
+  elevatedUser: UserInfo;
+  /** The widget instance the guest session is bound to (authoritative config). */
+  widget: MJConversationWidgetInstanceEntity;
+  /** The authoritative pinned support agent id — overrides any client-supplied agent id (D5). */
+  pinnedAgentId: string;
+  /** The guest's per-session scope id (Conversation.ExternalID), used to validate conversation ownership. */
+  sessionScopeId?: string;
+}
+
+/**
+ * Returns elevation context when the request is a public web-widget guest, else `null` (the common
+ * case — every non-widget request). A widget guest is identified by the synthesized principal's
+ * `IsMagicLinkAnonymous` flag plus a `WidgetGuestContext.WidgetID` (sourced from the signed
+ * `mj_widget_id` claim by `buildMagicLinkSessionUser`). The widget instance is loaded under the
+ * SYSTEM principal so resolving the pinned agent does not depend on the guest's narrow grants.
+ *
+ * Never throws: a resolution failure (no system user, widget not found, read error) returns `null`,
+ * so the caller falls back to the normal (guest-principal) path rather than failing the request.
+ */
+export async function resolveWidgetGuestRunContext(
+  userPayload: UserPayload,
+  provider: DatabaseProviderBase,
+): Promise<WidgetGuestRunContext | null> {
+  const guest = userPayload?.userRecord as UserInfo | undefined;
+  const widgetId = guest?.WidgetGuestContext?.WidgetID;
+  if (!guest?.IsMagicLinkAnonymous || !widgetId) {
+    return null;
+  }
+
+  const elevatedUser = UserCache.Instance.GetSystemUser();
+  if (!elevatedUser) {
+    LogError('[Widget] Cannot elevate widget-guest agent run: no system user available.');
+    return null;
+  }
+
+  const widget = await loadWidgetById(widgetId, elevatedUser, provider);
+  if (!widget) {
+    LogError(`[Widget] Widget instance ${widgetId} (from token) not found; cannot elevate dispatch.`);
+    return null;
+  }
+
+  return {
+    elevatedUser,
+    widget,
+    pinnedAgentId: widget.PinnedAgentID,
+    sessionScopeId: guest.MagicLinkScope?.ResourceID,
+  };
+}
+
+/**
+ * Builds an elevated {@link UserPayload} that runs subsequent agent work as `elevatedUser` while
+ * preserving the guest's `sessionId` — so progress/streaming PubSub still routes to the guest's
+ * live websocket, but all AI run-entity writes happen under the trusted server principal.
+ */
+export function elevateUserPayload(userPayload: UserPayload, elevatedUser: UserInfo): UserPayload {
+  return {
+    ...userPayload,
+    email: elevatedUser.Email,
+    userRecord: elevatedUser,
+    isSystemUser: true,
+  };
+}
+
+/** Loads a single widget instance by id under the elevated principal (read-only). */
+async function loadWidgetById(
+  widgetId: string,
+  elevatedUser: UserInfo,
+  provider: DatabaseProviderBase,
+): Promise<MJConversationWidgetInstanceEntity | null> {
+  const rv = new RunView(provider);
+  const result = await rv.RunView<MJConversationWidgetInstanceEntity>(
+    {
+      EntityName: WIDGET_ENTITY,
+      ExtraFilter: `ID = '${widgetId.replace(/'/g, "''")}'`,
+      MaxRows: 1,
+      ResultType: 'entity_object',
+    },
+    elevatedUser,
+  );
+  if (!result.Success) {
+    LogError(`[Widget] Failed to load widget instance ${widgetId}: ${result.ErrorMessage}`);
+    return null;
+  }
+  return result.Results?.[0] ?? null;
+}

package/src/resolvers/ComponentRegistryResolver.ts

@@ -3,6 +3,7 @@ import { UserInfo, LogError, LogStatus } from '@memberjunction/core';
 import { UUIDsEqual, MJLruCache } from '@memberjunction/global';
 import { UserCache } from '@memberjunction/sqlserver-dataprovider';
 import { MJComponentRegistryEntity, ComponentMetadataEngine } from '@memberjunction/core-entities';
+import { CredentialEngine } from '@memberjunction/credentials';
 import { ComponentSpec } from '@memberjunction/interactive-component-types';
 import {
     ComponentRegistryClient,
@@ -249,7 +250,7 @@ export class ComponentRegistryExtendedResolver {
             }
 
             // --- Tier 2: Fetch from external registry ---
-            const registryClient = this.createClientForRegistry(registry);
+            const registryClient = await this.createClientForRegistry(registry, user);
 
             const response = await registryClient.getComponentWithHash({
                 registry: registry.Name,
@@ -329,7 +330,7 @@ export class ComponentRegistryExtendedResolver {
                     throw new Error(`Registry not found: ${params.registryId}`);
                 }
                 
-                const client = this.createClientForRegistry(registry);
+                const client = await this.createClientForRegistry(registry, user);
                 
                 const result = await client.searchComponents({
                     namespace: params.namespace,
@@ -356,7 +357,7 @@ export class ComponentRegistryExtendedResolver {
                 try {
                     await this.checkUserAccess(user, registry.ID);
                     
-                    const client = this.createClientForRegistry(registry);
+                    const client = await this.createClientForRegistry(registry, user);
                     const result = await client.searchComponents({
                         namespace: params.namespace,
                         query: params.query,
@@ -413,8 +414,8 @@ export class ComponentRegistryExtendedResolver {
             await this.checkUserAccess(user, registry.ID);
             
             // Create client on-demand
-            const client = this.createClientForRegistry(registry);
-            
+            const client = await this.createClientForRegistry(registry, user);
+
             const tree = await client.resolveDependencies(componentId);
             return tree as ComponentDependencyTreeType;
         } catch (error) {
@@ -499,17 +500,22 @@ export class ComponentRegistryExtendedResolver {
      * Create a client for a registry on-demand
      * Checks configuration first, then falls back to default settings
      */
-    private createClientForRegistry(registry: MJComponentRegistryEntity): ComponentRegistryClient {
+    private async createClientForRegistry(registry: MJComponentRegistryEntity, user?: UserInfo): Promise<ComponentRegistryClient> {
         // Check if there's a configuration for this registry
         const config = configInfo.componentRegistries?.find(r =>
             UUIDsEqual(r.id, registry.ID) || r.name === registry.Name
         );
 
-        // Get API key from environment or config
+        // Get API key from environment or config, falling back to the encrypted
+        // credential store (a credential named "Component Registry: <RegistryName>").
+        // The credential-store path lets an installer provision the key once, without
+        // an env var or a plaintext entry in mj.config.cjs. Env/config still win so
+        // existing deployments are unchanged.
         const apiKey = process.env[`REGISTRY_API_KEY_${registry.ID.replace(/-/g, '_').toUpperCase()}`] ||
                       process.env[`REGISTRY_API_KEY_${registry.Name?.replace(/-/g, '_').toUpperCase()}`] ||
-                      config?.apiKey;
-        
+                      config?.apiKey ||
+                      await this.resolveRegistryApiKeyFromCredentialStore(registry, user);
+
         // Get the registry URI (with possible override)
         const baseUrl = this.getRegistryUri(registry);
         
@@ -531,6 +537,26 @@ export class ComponentRegistryExtendedResolver {
         });
     }
 
+    /**
+     * Resolves a registry's API key from the encrypted credential store, using the
+     * convention credential name "Component Registry: <RegistryName>". Returns undefined
+     * when no such credential exists (e.g. public registries that need no key) or the
+     * store is unavailable — callers treat the missing key as "unauthenticated".
+     */
+    private async resolveRegistryApiKeyFromCredentialStore(registry: MJComponentRegistryEntity, user?: UserInfo): Promise<string | undefined> {
+        try {
+            await CredentialEngine.Instance.Config(false, user);
+            const resolved = await CredentialEngine.Instance.getCredential<{ apiKey: string }>(
+                `Component Registry: ${registry.Name}`,
+                { contextUser: user, subsystem: 'ComponentRegistry' }
+            );
+            return resolved?.values?.apiKey || undefined;
+        } catch {
+            // Credential not found or store unavailable — fall through to no key.
+            return undefined;
+        }
+    }
+
     /**
      * Map search result to GraphQL type
      */
@@ -585,7 +611,7 @@ export class ComponentRegistryExtendedResolver {
 
             // Create client using the same pattern as GetRegistryComponent
             // This respects REGISTRY_URI_OVERRIDE_* and REGISTRY_API_KEY_* environment variables
-            const registryClient = this.createClientForRegistry(registry);
+            const registryClient = await this.createClientForRegistry(registry, user);
 
             const sdkParams: SDKComponentFeedbackParams = {
                 componentName: feedback.componentName,

package/src/resolvers/EntityPermissionResolver.ts

@@ -2,7 +2,6 @@ import { Arg, Ctx, Field, ObjectType, Query, Resolver } from 'type-graphql';
 import { LogError } from '@memberjunction/core';
 import { AppContext } from '../types.js';
 import { ResolverBase } from '../generic/ResolverBase.js';
-import { RequireSystemUser } from '../directives/RequireSystemUser.js';
 import { GetReadOnlyProvider } from '../util.js';
 import { UserCache } from '@memberjunction/sqlserver-dataprovider';
 
@@ -30,7 +29,6 @@ class CheckEntityPermissionsResult {
 @Resolver()
 export class EntityPermissionResolver extends ResolverBase {
 
-    @RequireSystemUser()
     @Query(() => CheckEntityPermissionsResult)
     async CheckEntityPermissionsSystemUser(
         @Arg('EntityNames', () => [String]) entityNames: string[],
@@ -38,6 +36,7 @@ export class EntityPermissionResolver extends ResolverBase {
         @Ctx() context: AppContext
     ): Promise<CheckEntityPermissionsResult> {
         try {
+            await this.CheckAPIKeyScopeAuthorization('view:run', '*', context.userPayload);
             const user = UserCache.Instance.Users.find(
                 u => u.Email.toLowerCase().trim() === userEmail.toLowerCase().trim()
             );

package/src/resolvers/FileResolver.ts

@@ -1,6 +1,7 @@
-import { EntityPermissionType, FieldValueCollection, EntitySaveOptions } from '@memberjunction/core';
+import { EntityPermissionType, FieldValueCollection, EntitySaveOptions, LogError, UserInfo } from '@memberjunction/core';
 import { NormalizeUUID } from '@memberjunction/global';
 import { MJFileEntity, MJFileStorageProviderEntity, MJFileStorageAccountEntity } from '@memberjunction/core-entities';
+import { readRealtimeRecordingFile } from '@memberjunction/ai-agents';
 import {
   AppContext,
   Arg,
@@ -8,6 +9,7 @@ import {
   DeleteOptionsInput,
   Field,
   FieldResolver,
+  Float,
   InputType,
   Int,
   Mutation,
@@ -37,6 +39,9 @@ import {
 import { CreateMJFileInput, MJFileResolver as FileResolverBase, MJFile_, UpdateMJFileInput } from '../generated/generated.js';
 import { FieldMapper } from '@memberjunction/graphql-dataprovider';
 import { GetReadOnlyProvider } from '../util.js';
+import { configInfo } from '../config.js';
+import { MediaAccessKeyManager } from '../rest/MediaAccessKeys.js';
+import { deriveSidecarPath, parsePeaksSidecar } from './peaksSidecar.js';
 
 @InputType()
 export class CreateUploadURLInput {
@@ -312,8 +317,161 @@ export class SearchAcrossAccountsPayload {
   failedAccounts: number;
 }
 
+/**
+ * Result of {@link FileResolver.GetFileContents} — the bytes of an `MJ: Files` record returned as
+ * base64, read server-side through authenticated MJStorage (never a public pre-signed link).
+ */
+@ObjectType()
+export class FileContentsResult {
+  @Field(() => Boolean)
+  Success: boolean;
+
+  @Field(() => String, { nullable: true })
+  Base64?: string;
+
+  @Field(() => String, { nullable: true })
+  MimeType?: string;
+
+  @Field(() => String, { nullable: true })
+  ErrorMessage?: string;
+}
+
+/**
+ * Result of {@link FileResolver.CreateMediaAccessToken} — a short-lived signed token plus the
+ * authenticated streaming URL the browser hands to a `<audio>`/`<video>` element. The token is
+ * minted only after a per-user permission check on the `MJ: Files` row; the `/media/:fileId`
+ * route re-verifies it (signature + expiry + file match) on each Range request.
+ */
+@ObjectType()
+export class MediaAccessTokenResult {
+  @Field(() => Boolean)
+  Success: boolean;
+
+  @Field(() => String, { nullable: true })
+  Token?: string;
+
+  @Field(() => String, { nullable: true })
+  Url?: string;
+
+  @Field(() => Date, { nullable: true })
+  ExpiresAt?: Date;
+
+  /**
+   * The file's MIME type (from the already-loaded `MJ: Files` row). Lets the wrapper choose
+   * `<audio>` vs `<video>` WITHOUT re-downloading any bytes; the stream itself sets Content-Type.
+   */
+  @Field(() => String, { nullable: true })
+  MimeType?: string;
+
+  /**
+   * Optional precomputed waveform peaks (normalized `0..1`, one per rendered bar) read from a
+   * `peaks.json` sidecar that sits beside the file in storage. When present, the player renders the
+   * real waveform instantly with NO client-side fetch/decode of the audio. Best-effort: a missing or
+   * malformed sidecar simply omits this field — it never blocks token minting or fails the mutation.
+   */
+  @Field(() => [Float], { nullable: true })
+  Peaks?: number[];
+
+  @Field(() => String, { nullable: true })
+  ErrorMessage?: string;
+}
+
 @Resolver(MJFile_)
 export class FileResolver extends FileResolverBase {
+  /**
+   * Resolves the server's public base URL the same way callbacks/magic-link do:
+   * `publicUrl` if configured (e.g. an ngrok URL), else `baseUrl:graphqlPort`. Trailing
+   * slash stripped so callers can append `/media/...`.
+   */
+  private resolvePublicBaseUrl(): string {
+    const base = configInfo.publicUrl || `${configInfo.baseUrl}:${configInfo.graphqlPort}${configInfo.graphqlRootPath || ''}`;
+    return base.replace(/\/+$/, '');
+  }
+
+  /**
+   * Mints a short-lived signed media-access token for an `MJ: Files` record and returns the
+   * authenticated streaming URL (`<publicBase>/media/<fileId>?token=<token>`). Permission-gated
+   * IDENTICALLY to {@link GetFileContents}: the file is loaded under the CALLING USER's context, so
+   * MJ row-level security determines access. The returned token is the capability — the streaming
+   * route re-verifies it without re-checking row-level access. Never throws to the client.
+   *
+   * @param fileId The `MJ: Files` id to grant streaming access to.
+   * @returns `{ Success, Token?, Url?, ExpiresAt?, ErrorMessage? }`.
+   */
+  @Mutation(() => MediaAccessTokenResult)
+  async CreateMediaAccessToken(@Arg('fileId', () => String) fileId: string, @Ctx() context: AppContext): Promise<MediaAccessTokenResult> {
+    try {
+      const provider = GetReadOnlyProvider(context.providers, { allowFallbackToReadWrite: true });
+      const contextUser = this.GetUserFromPayload(context.userPayload);
+
+      // Permission gate: load the file under the USER's context. A failed load means the file
+      // does not exist OR the user lacks read access under MJ row-level security.
+      const fileEntity = await provider.GetEntityObject<MJFileEntity>('MJ: Files', contextUser);
+      const loaded = await fileEntity.Load(fileId);
+      if (!loaded) {
+        return { Success: false, ErrorMessage: 'You do not have access to this file or it does not exist.' };
+      }
+
+      // Access authorized — mint the capability token.
+      const { Token, ExpiresAt } = MediaAccessKeyManager.Instance.Sign(fileId, contextUser.ID);
+      const url = `${this.resolvePublicBaseUrl()}/media/${encodeURIComponent(fileId)}?token=${encodeURIComponent(Token)}`;
+
+      // Best-effort: surface precomputed waveform peaks from a peaks.json sidecar beside the file, so
+      // the player renders the real waveform instantly without fetching/decoding the audio. Never
+      // blocks token minting — any failure just omits Peaks.
+      const peaks = await this.tryReadPeaksSidecar(fileEntity, contextUser);
+
+      return { Success: true, Token, Url: url, ExpiresAt, MimeType: fileEntity.ContentType ?? undefined, Peaks: peaks };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      LogError(`CreateMediaAccessToken failed (file ${fileId}): ${message}`);
+      return { Success: false, ErrorMessage: message };
+    }
+  }
+
+  /**
+   * Best-effort read of a `peaks.json` waveform sidecar that sits in the SAME storage folder as the
+   * given file (a JSON array of normalized `0..1` numbers, written at capture time). Derives the
+   * folder from the file's `ProviderKey` (strips the final path segment), reads `<folder>/peaks.json`
+   * via the file's own storage driver, parses + validates it, and returns sanitized peaks. Returns
+   * `undefined` on ANY failure (no ProviderKey, no sidecar, parse error, garbage) — the caller treats
+   * peaks as a pure optimization and must never let a sidecar problem affect token minting.
+   *
+   * @param file The already-loaded (under the user's context) `MJ: Files` row.
+   * @param contextUser The calling user — used to resolve the storage driver.
+   * @returns Sanitized `0..1` peaks (length-capped), or `undefined`.
+   */
+  private async tryReadPeaksSidecar(file: MJFileEntity, contextUser: UserInfo): Promise<number[] | undefined> {
+    try {
+      // The sidecar lives next to the recording: replace the final path segment with peaks.json.
+      const sidecarPath = deriveSidecarPath(file.ProviderKey);
+      if (!sidecarPath) {
+        return undefined;
+      }
+
+      // Resolve the file's storage account → driver (mirror of readRealtimeRecordingFile's pattern).
+      await FileStorageEngine.Instance.Config(false, contextUser);
+      let accounts = FileStorageEngine.Instance.GetAccountsByProviderID(file.ProviderID);
+      if (accounts.length === 0) {
+        await FileStorageEngine.Instance.Config(true, contextUser);
+        accounts = FileStorageEngine.Instance.GetAccountsByProviderID(file.ProviderID);
+      }
+      const account = accounts[0];
+      if (!account) {
+        return undefined;
+      }
+      const driver = await FileStorageEngine.Instance.GetDriver(account.ID, contextUser);
+      const bytes = await driver.GetObject({ fullPath: sidecarPath });
+      if (!bytes || bytes.length === 0) {
+        return undefined;
+      }
+      return parsePeaksSidecar(bytes);
+    } catch {
+      // No sidecar / unreadable / parse failure — peaks are optional, never surface the error.
+      return undefined;
+    }
+  }
+
   /**
    * Builds UserContextOptions for storage operations that may require OAuth authentication.
    * This passes the current user's ID and context to allow the storage utilities to
@@ -431,6 +589,46 @@ export class FileResolver extends FileResolverBase {
     return url;
   }
 
+  /**
+   * Returns an `MJ: Files` record's bytes as base64, read server-side through authenticated MJStorage
+   * (`GetObject`) — NOT a public pre-signed link. Permission-gated: the file is first loaded under the
+   * calling user's context, so MJ row-level security determines access. Never throws to the client.
+   *
+   * @param fileId The `MJ: Files` id whose bytes to return.
+   * @returns `{ Success, Base64?, MimeType?, ErrorMessage? }`.
+   */
+  @Query(() => FileContentsResult)
+  async GetFileContents(@Arg('fileId', () => String) fileId: string, @Ctx() context: AppContext): Promise<FileContentsResult> {
+    try {
+      const provider = GetReadOnlyProvider(context.providers, { allowFallbackToReadWrite: true });
+      const contextUser = this.GetUserFromPayload(context.userPayload);
+
+      // Permission gate FIRST: load the file record under the USER's context. A failed load means the
+      // file does not exist OR the user lacks read access under MJ row-level security.
+      const fileEntity = await provider.GetEntityObject<MJFileEntity>('MJ: Files', contextUser);
+      const loaded = await fileEntity.Load(fileId);
+      if (!loaded) {
+        return { Success: false, ErrorMessage: 'You do not have access to this file or it does not exist.' };
+      }
+
+      // Read the bytes via authenticated MJStorage (server-side GetObject on the file's own account).
+      const result = await readRealtimeRecordingFile(fileId, contextUser, provider);
+      if (!result) {
+        return { Success: false, ErrorMessage: 'The file could not be read from storage.' };
+      }
+
+      return {
+        Success: true,
+        Base64: result.Bytes.toString('base64'),
+        MimeType: result.MimeType ?? fileEntity.ContentType ?? undefined,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      LogError(`GetFileContents failed (file ${fileId}): ${message}`);
+      return { Success: false, ErrorMessage: message };
+    }
+  }
+
   @Mutation(() => MJFile_)
   async UpdateFile(@Arg('input', () => UpdateMJFileInput) input: UpdateMJFileInput, @Ctx() context: AppContext, @PubSub() pubSub: PubSubEngine) {
     // if the name is changing, rename the target object as well

package/src/resolvers/QueryResolver.ts

@@ -1,5 +1,5 @@
 import { Arg, Ctx, ObjectType, Query, Resolver, Field, Int, InputType } from 'type-graphql';
-import { RunQuery, IRunQueryProvider, IMetadataProvider, RunQueryParams, LogError, RunQueryWithCacheCheckParams, RunQueriesWithCacheCheckResponse, RunQueryWithCacheCheckResult } from '@memberjunction/core';
+import { RunQuery, IRunQueryProvider, IMetadataProvider, RunQueryParams, LogError, RunQueryWithCacheCheckParams, RunQueriesWithCacheCheckResponse, RunQueryWithCacheCheckResult, RunQueryEnrichment } from '@memberjunction/core';
 import { AppContext } from '../types.js';
 import { RequireSystemUser } from '../directives/RequireSystemUser.js';
 import { GraphQLJSONObject } from 'graphql-type-json';
@@ -40,6 +40,9 @@ export class RunQueryInput {
 
   @Field(() => String, { nullable: true, description: 'Description to use in audit log' })
   AuditLogDescription?: string;
+
+  @Field(() => GraphQLJSONObject, { nullable: true, description: 'Optional runtime-only directive to post-process result rows through a registered query result enricher ({ EnricherKey, Config })' })
+  Enrichment?: RunQueryEnrichment;
 }
 
 @ObjectType()
@@ -191,7 +194,8 @@ export class RunQueryResolver extends ResolverBase {
                      @Arg('MaxRows', () => Int, {nullable: true}) MaxRows?: number,
                      @Arg('StartRow', () => Int, {nullable: true}) StartRow?: number,
                      @Arg('ForceAuditLog', () => Boolean, {nullable: true}) ForceAuditLog?: boolean,
-                     @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string): Promise<RunQueryResultType> {
+                     @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string,
+                     @Arg('Enrichment', () => GraphQLJSONObject, {nullable: true}) Enrichment?: RunQueryEnrichment): Promise<RunQueryResultType> {
     // Check API key scope authorization for query execution
     await this.CheckAPIKeyScopeAuthorization('query:run', QueryID, context.userPayload);
 
@@ -200,7 +204,7 @@ export class RunQueryResolver extends ResolverBase {
     const rq = new RunQuery(provider as unknown as IRunQueryProvider);
     console.log('GetQueryData called with:', { QueryID, Parameters, MaxRows, StartRow, ForceAuditLog, AuditLogDescription });
     const result = await rq.RunQuery(
-      { 
+      {
         QueryID: QueryID,
         CategoryID: CategoryID,
         CategoryPath: CategoryPath,
@@ -208,8 +212,9 @@ export class RunQueryResolver extends ResolverBase {
         MaxRows: MaxRows,
         StartRow: StartRow,
         ForceAuditLog: ForceAuditLog,
-        AuditLogDescription: AuditLogDescription
-      }, 
+        AuditLogDescription: AuditLogDescription,
+        Enrichment: Enrichment
+      },
       context.userPayload.userRecord);
     console.log('RunQuery result:', { 
       Success: result.Success, 
@@ -256,22 +261,24 @@ export class RunQueryResolver extends ResolverBase {
                            @Arg('MaxRows', () => Int, {nullable: true}) MaxRows?: number,
                            @Arg('StartRow', () => Int, {nullable: true}) StartRow?: number,
                            @Arg('ForceAuditLog', () => Boolean, {nullable: true}) ForceAuditLog?: boolean,
-                           @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string): Promise<RunQueryResultType> {
+                           @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string,
+                           @Arg('Enrichment', () => GraphQLJSONObject, {nullable: true}) Enrichment?: RunQueryEnrichment): Promise<RunQueryResultType> {
     // Check API key scope authorization for query execution
     await this.CheckAPIKeyScopeAuthorization('query:run', QueryName, context.userPayload);
 
     const provider = GetReadOnlyProvider(context.providers, {allowFallbackToReadWrite: true});
     const rq = new RunQuery(provider as unknown as IRunQueryProvider);
     const result = await rq.RunQuery(
-      { 
-        QueryName: QueryName, 
+      {
+        QueryName: QueryName,
         CategoryID: CategoryID,
         CategoryPath: CategoryPath,
         Parameters: Parameters,
         MaxRows: MaxRows,
         StartRow: StartRow,
         ForceAuditLog: ForceAuditLog,
-        AuditLogDescription: AuditLogDescription
+        AuditLogDescription: AuditLogDescription,
+        Enrichment: Enrichment
       },
       context.userPayload.userRecord);
       
@@ -302,13 +309,14 @@ export class RunQueryResolver extends ResolverBase {
                                @Arg('MaxRows', () => Int, {nullable: true}) MaxRows?: number,
                                @Arg('StartRow', () => Int, {nullable: true}) StartRow?: number,
                                @Arg('ForceAuditLog', () => Boolean, {nullable: true}) ForceAuditLog?: boolean,
-                               @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string): Promise<RunQueryResultType> {
+                               @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string,
+                               @Arg('Enrichment', () => GraphQLJSONObject, {nullable: true}) Enrichment?: RunQueryEnrichment): Promise<RunQueryResultType> {
     const provider = GetReadOnlyProvider(context.providers, {allowFallbackToReadWrite: true});
     const md = provider as unknown as IMetadataProvider;
     const rq = new RunQuery(provider as unknown as IRunQueryProvider);
 
     const result = await rq.RunQuery(
-      { 
+      {
         QueryID: QueryID,
         CategoryID: CategoryID,
         CategoryPath: CategoryPath,
@@ -316,8 +324,9 @@ export class RunQueryResolver extends ResolverBase {
         MaxRows: MaxRows,
         StartRow: StartRow,
         ForceAuditLog: ForceAuditLog,
-        AuditLogDescription: AuditLogDescription
-      }, 
+        AuditLogDescription: AuditLogDescription,
+        Enrichment: Enrichment
+      },
       context.userPayload.userRecord);
     
     // If QueryName is not populated by the provider, use efficient lookup
@@ -360,12 +369,13 @@ export class RunQueryResolver extends ResolverBase {
                                      @Arg('MaxRows', () => Int, {nullable: true}) MaxRows?: number,
                                      @Arg('StartRow', () => Int, {nullable: true}) StartRow?: number,
                                      @Arg('ForceAuditLog', () => Boolean, {nullable: true}) ForceAuditLog?: boolean,
-                                     @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string): Promise<RunQueryResultType> {
+                                     @Arg('AuditLogDescription', () => String, {nullable: true}) AuditLogDescription?: string,
+                                     @Arg('Enrichment', () => GraphQLJSONObject, {nullable: true}) Enrichment?: RunQueryEnrichment): Promise<RunQueryResultType> {
     const provider = GetReadOnlyProvider(context.providers, {allowFallbackToReadWrite: true});
     const rq = new RunQuery(provider as unknown as IRunQueryProvider);
 
     const result = await rq.RunQuery(
-      { 
+      {
         QueryName: QueryName,
         CategoryID: CategoryID,
         CategoryPath: CategoryPath,
@@ -373,8 +383,9 @@ export class RunQueryResolver extends ResolverBase {
         MaxRows: MaxRows,
         StartRow: StartRow,
         ForceAuditLog: ForceAuditLog,
-        AuditLogDescription: AuditLogDescription
-      }, 
+        AuditLogDescription: AuditLogDescription,
+        Enrichment: Enrichment
+      },
       context.userPayload.userRecord);
     
     return {
@@ -420,7 +431,8 @@ export class RunQueryResolver extends ResolverBase {
       MaxRows: i.MaxRows,
       StartRow: i.StartRow,
       ForceAuditLog: i.ForceAuditLog,
-      AuditLogDescription: i.AuditLogDescription
+      AuditLogDescription: i.AuditLogDescription,
+      Enrichment: i.Enrichment
     }));
 
     // Execute all queries in parallel using the batch method
@@ -469,7 +481,8 @@ export class RunQueryResolver extends ResolverBase {
       MaxRows: i.MaxRows,
       StartRow: i.StartRow,
       ForceAuditLog: i.ForceAuditLog,
-      AuditLogDescription: i.AuditLogDescription
+      AuditLogDescription: i.AuditLogDescription,
+      Enrichment: i.Enrichment
     }));
 
     // Execute all queries in parallel using the batch method
@@ -532,6 +545,7 @@ export class RunQueryResolver extends ResolverBase {
           StartRow: item.params.StartRow,
           ForceAuditLog: item.params.ForceAuditLog,
           AuditLogDescription: item.params.AuditLogDescription,
+          Enrichment: item.params.Enrichment,
         },
         cacheStatus: item.cacheStatus ? {
           maxUpdatedAt: item.cacheStatus.maxUpdatedAt,