@memberjunction/server 5.44.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/QuerySystemUserResolver.ts

@@ -1,7 +1,6 @@
 import { Arg, Ctx, Field, InputType, Mutation, ObjectType, registerEnumType, Resolver, PubSub, PubSubEngine } from 'type-graphql';
 import { AppContext } from '../types.js';
 import { LogError, UserInfo, CompositeKey, DatabaseProviderBase, LogStatus } from '@memberjunction/core';
-import { RequireSystemUser } from '../directives/RequireSystemUser.js';
 import { MJQueryCategoryEntity, MJQueryPermissionEntity, MJQueryFieldEntity, MJQueryParameterEntity, MJQueryEntityEntity, QueryEngine } from '@memberjunction/core-entities';
 import { MJQueryResolver, MJQuery_, MJQueryField_, MJQueryParameter_, MJQueryEntity_, MJQueryPermission_ } from '../generated/generated.js';
 import { GetReadWriteProvider } from '../util.js';
@@ -229,19 +228,21 @@ export class DeleteQueryResultType {
 @Resolver()
 export class MJQueryResolverExtended extends MJQueryResolver {
     /**
-     * Creates a new query with the provided attributes. This mutation is restricted to system users only.
+     * Creates a new query with the provided attributes. Requires `query:create` scope for API key users;
+     * entity-level create permission on MJ: Queries for all users.
      * @param input - CreateQuerySystemUserInput containing all the query attributes
      * @param context - Application context containing user information
      * @returns CreateQueryResultType with success status and query data
      */
-    @RequireSystemUser()
     @Mutation(() => QueryMutationResultType)
-    async CreateQuerySystemUser(
+    async CreateQueryExtended(
         @Arg('input', () => CreateQuerySystemUserInput) input: CreateQuerySystemUserInput,
         @Ctx() context: AppContext,
         @PubSub() pubSub: PubSubEngine
     ): Promise<QueryMutationResultType> {
         try {
+            await this.CheckAPIKeyScopeAuthorization('query:create', '*', context.userPayload);
+
             // Handle CategoryPath if provided
             let finalCategoryID = input.CategoryID;
             const provider = GetReadWriteProvider(context.providers);
@@ -443,19 +444,21 @@ export class MJQueryResolverExtended extends MJQueryResolver {
     }
 
     /**
-     * Updates an existing query with the provided attributes. This mutation is restricted to system users only.
+     * Updates an existing query with the provided attributes. Requires `query:update` scope for API key users;
+     * entity-level update permission on MJ: Queries for all users.
      * @param input - UpdateQuerySystemUserInput containing the query ID and fields to update
      * @param context - Application context containing user information
      * @returns UpdateQueryResultType with success status and updated query data including related entities
      */
-    @RequireSystemUser()
     @Mutation(() => QueryMutationResultType)
-    async UpdateQuerySystemUser(
+    async UpdateQueryExtended(
         @Arg('input', () => UpdateQuerySystemUserInput) input: UpdateQuerySystemUserInput,
         @Ctx() context: AppContext,
         @PubSub() pubSub: PubSubEngine
     ): Promise<QueryMutationResultType> {
         try {
+            await this.CheckAPIKeyScopeAuthorization('query:update', input.ID, context.userPayload);
+
             // Load the existing query using MJQueryEntityServer
             const provider = GetReadWriteProvider(context.providers);
             const queryEntity = await provider.GetEntityObject<MJQueryEntityServer>('MJ: Queries', context.userPayload.userRecord);
@@ -547,21 +550,22 @@ export class MJQueryResolverExtended extends MJQueryResolver {
     }
 
     /**
-     * Deletes a query by ID. This mutation is restricted to system users only.
+     * Deletes a query by ID. Requires `query:delete` scope for API key users;
+     * entity-level delete permission on MJ: Queries is enforced by the entity framework.
      * @param ID - The ID of the query to delete
      * @param options - Delete options controlling action execution
      * @param context - Application context containing user information
      * @returns DeleteQueryResultType with success status and deleted query data
      */
-    @RequireSystemUser()
     @Mutation(() => DeleteQueryResultType)
-    async DeleteQuerySystemResolver(
+    async DeleteQueryExtended(
         @Arg('ID', () => String) ID: string,
         @Arg('options', () => DeleteOptionsInput, { nullable: true }) options: DeleteOptionsInput | null,
         @Ctx() context: AppContext,
         @PubSub() pubSub: PubSubEngine
     ): Promise<DeleteQueryResultType> {
         try {
+            await this.CheckAPIKeyScopeAuthorization('query:delete', ID, context.userPayload);
             // Validate ID is not null/undefined/empty
             if (!ID || ID.trim() === '') {
                 return {

package/src/resolvers/RealtimeClientSessionResolver.ts

@@ -60,6 +60,7 @@ import { ResolverBase } from '../generic/ResolverBase.js';
 import { PUSH_STATUS_UPDATES_TOPIC } from '../generic/PushStatusResolver.js';
 import { GetReadWriteProvider } from '../util.js';
 import { SessionManager } from '../agentSessions/index.js';
+import { resolveWidgetGuestRunContext } from '../realtimeWidget/widgetGuestElevation.js';
 
 /**
  * Progress steps worth narrating to the realtime model — mirrors the normal agent-run path's filter
@@ -161,6 +162,13 @@ interface RealtimeSessionConfig {
      * rather than starting fresh. Re-stored if the resumed run pauses again.
      */
     pendingFeedbackRunID?: string;
+    /**
+     * Absolute server-authoritative deadline (ISO 8601) past which this session is hard-closed by the
+     * {@link SessionJanitor}, independent of idle activity. Stamped at session start for abuse-sensitive
+     * deployments (a public web-widget voice guest's `VoiceMaxSessionMinutes`); absent for uncapped
+     * sessions. Preserved across config rewrites so the cap survives run-id / feedback updates.
+     */
+    maxSessionDeadlineIso?: string;
     /**
      * The application the session runs in (sourced the app cascade layer + RelevantAgents). Persisted
      * for observability / continuity; absent when the session carries no app context.
@@ -412,7 +420,15 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         // silent ignore). Plain starts and within-pairing target selection are never gated here.
         await this.assertRuntimeOverridesAuthorized(coAgentID, configOverridesJson, preferredModelId, contextUser, provider);
 
+        // PUBLIC WEB-WIDGET VOICE CAP (public-web-widget.md W4): when the caller is a widget guest,
+        // resolve the deployment's hard duration ceiling and stamp an absolute deadline on the session.
+        // The SessionJanitor force-closes (finalizing runs) past the deadline — a server-authoritative
+        // bound that does not depend on the client honoring its own abuse guard or the ephemeral token TTL.
+        const maxSessionSeconds = await this.resolveWidgetVoiceCapSeconds(userPayload, providers);
         const config: RealtimeSessionConfig = { targetAgentID: effectiveTargetId };
+        if (maxSessionSeconds) {
+            config.maxSessionDeadlineIso = new Date(Date.now() + maxSessionSeconds * 1000).toISOString();
+        }
         // Per-session media-kit override: stored on the session config so the server-side MediaChannelServer
         // resolves it (over the agent default) at start. Validate the id here — a malformed value is
         // dropped (logged), never interpolated; the session still starts and falls back to the agent kit.
@@ -449,7 +465,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         const priorTranscript = await this.loadPriorTranscript(lastSessionId, contextUser, provider);
         const result = await this.prepareClientSessionOrClose(
             session, coAgentID, effectiveTargetId, contextUser, provider, preferredModelId, clientTools, priorTranscript,
-            configOverridesJson, applicationId, this.parseAppContext(appContextJson),
+            configOverridesJson, maxSessionSeconds, applicationId, this.parseAppContext(appContextJson),
         );
         // Best-effort restore of the PRIOR session's persisted channel states (e.g. the whiteboard
         // board). Strictly tolerant — any problem yields a null field, never a failed start.
@@ -562,6 +578,8 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             promptRunID: config.promptRunID,
             coAgentRunStepID: config.coAgentRunStepID,
             pendingFeedbackRunID: pausedRunID,
+            // Preserve the server-authoritative voice deadline across config rewrites.
+            maxSessionDeadlineIso: config.maxSessionDeadlineIso,
             applicationID: config.applicationID,
             allowedAgents: config.allowedAgents,
         };
@@ -1535,6 +1553,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         clientTools?: RealtimeToolDefinition[],
         priorTranscript?: string,
         configOverridesJson?: string,
+        maxSessionSeconds?: number,
         applicationId?: string,
         appContext?: AppContextSnapshot,
     ): Promise<StartRealtimeClientSessionResult> {
@@ -1544,6 +1563,9 @@ export class RealtimeClientSessionResolver extends ResolverBase {
                 TargetAgentID: targetAgentId,
                 AgentSessionID: session.ID,
                 ConversationID: session.ConversationID ?? undefined,
+                // Server-authoritative voice duration cap (widget guests) — bounds the driver session
+                // where supported; the janitor enforces the session deadline regardless.
+                MaxSessionSeconds: maxSessionSeconds,
                 // MVP: conversation history is not yet hydrated into ChatMessage[]; the co-agent
                 // companion prompt runs without prior turns. A later phase loads the session's
                 // Conversation into ChatMessage[] for richer context.
@@ -1608,8 +1630,16 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         applicationID?: string,
         allowedAgents?: RealtimeAllowedAgent[],
     ): Promise<void> {
+        // Preserve any server-authoritative voice deadline stamped at session start (this rebuilds the
+        // full config, so read the existing value forward rather than dropping it).
+        const existing = this.tryReadSessionConfig(session);
         const config: RealtimeSessionConfig = {
-            targetAgentID, coAgentRunID, promptRunID, coAgentRunStepID, applicationID,
+            targetAgentID,
+            coAgentRunID,
+            promptRunID,
+            coAgentRunStepID,
+            maxSessionDeadlineIso: existing?.maxSessionDeadlineIso,
+            applicationID,
             allowedAgents: allowedAgents && allowedAgents.length > 0 ? allowedAgents : undefined,
         };
         session.Config_ = JSON.stringify(config);
@@ -2335,6 +2365,8 @@ export class RealtimeClientSessionResolver extends ResolverBase {
                         coAgentRunStepID: typeof parsed.coAgentRunStepID === 'string' ? parsed.coAgentRunStepID : undefined,
                         pendingFeedbackRunID:
                             typeof parsed.pendingFeedbackRunID === 'string' ? parsed.pendingFeedbackRunID : undefined,
+                        maxSessionDeadlineIso:
+                            typeof parsed.maxSessionDeadlineIso === 'string' ? parsed.maxSessionDeadlineIso : undefined,
                         applicationID: typeof parsed.applicationID === 'string' ? parsed.applicationID : undefined,
                         allowedAgents: Array.isArray(parsed.allowedAgents) ? parsed.allowedAgents : undefined,
                     };
@@ -2346,6 +2378,31 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         throw new Error(`Realtime session ${session.ID} has no target agent configured`);
     }
 
+    /** Like {@link readSessionConfig} but returns `undefined` instead of throwing (for best-effort reads). */
+    private tryReadSessionConfig(session: MJAIAgentSessionEntity): RealtimeSessionConfig | undefined {
+        try {
+            return this.readSessionConfig(session);
+        } catch {
+            return undefined;
+        }
+    }
+
+    /**
+     * Resolves the server-authoritative voice duration cap (seconds) for a session start, or `undefined`
+     * when no cap applies (the common, uncapped case). A cap applies only when the caller is a public
+     * web-widget guest with a configured `VoiceMaxSessionMinutes` on its widget instance (the same value
+     * surfaced to the client guard at mint). Never throws — a resolution failure yields no cap rather
+     * than blocking the start.
+     */
+    private async resolveWidgetVoiceCapSeconds(
+        userPayload: UserPayload,
+        providers: AppContext['providers'],
+    ): Promise<number | undefined> {
+        const elevation = await resolveWidgetGuestRunContext(userPayload, GetReadWriteProvider(providers));
+        const minutes = elevation?.widget.VoiceMaxSessionMinutes;
+        return minutes && minutes > 0 ? minutes * 60 : undefined;
+    }
+
     /**
      * Persists a single transcript turn as a `Conversation Detail` stamped with the session's
      * conversation, the mapped role, the turn text, the session id, and the owning user.

package/src/resolvers/RingCentralTelephonyResolver.ts

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview GraphQL surface for OUTBOUND RingCentral telephony: `PlaceRingCentralCall` rings a real
+ * phone from an agent identity and connects the pinned agent. Thin — it authorizes the caller, then
+ * delegates to the startup-constructed {@link RingCentralTelephonyService} (which owns the bridge
+ * orchestration + the shared media registry). Inbound calls arrive via the public
+ * `POST /telephony/ringcentral/webhook` notification, not GraphQL.
+ *
+ * @module @memberjunction/server
+ */
+
+import { Resolver, Mutation, Arg, Ctx, ObjectType, Field } from 'type-graphql';
+import { LogError, IMetadataProvider } from '@memberjunction/core';
+import { AppContext } from '../types.js';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import { GetReadWriteProvider } from '../util.js';
+import { GetRingCentralTelephonyService } from '../telephony/ringcentral-runtime.js';
+
+/** Result of an outbound RingCentral place-call attempt. */
+@ObjectType()
+export class PlaceRingCentralCallResult {
+    @Field(() => Boolean)
+    Success: boolean;
+
+    @Field(() => String, { nullable: true })
+    ErrorMessage?: string;
+
+    /** The placed RingCentral telephony session id (the bridge's external connection id). */
+    @Field(() => String)
+    SessionId: string;
+}
+
+@Resolver()
+export class RingCentralTelephonyResolver extends ResolverBase {
+    /**
+     * Places an outbound call from the given agent identity (its phone number is the caller-id) to a
+     * destination number, connecting the pinned agent over the realtime bridge. Returns the telephony
+     * session id.
+     */
+    @Mutation(() => PlaceRingCentralCallResult)
+    async PlaceRingCentralCall(
+        @Arg('agentIdentityId', () => String) agentIdentityId: string,
+        @Arg('toNumber', () => String) toNumber: string,
+        @Ctx() context: AppContext = {} as AppContext,
+    ): Promise<PlaceRingCentralCallResult> {
+        const failure = (msg: string): PlaceRingCentralCallResult => ({ Success: false, ErrorMessage: msg, SessionId: '' });
+        try {
+            const user = this.GetUserFromPayload(context.userPayload);
+            if (!user) {
+                return failure('Unable to determine current user.');
+            }
+            const service = GetRingCentralTelephonyService();
+            if (!service) {
+                return failure('RingCentral telephony is not configured on this server.');
+            }
+            const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+            const sessionId = await service.PlaceOutboundCall(agentIdentityId, toNumber, user, provider);
+            return { Success: true, SessionId: sessionId };
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            LogError(`PlaceRingCentralCall failed: ${msg}`);
+            return failure(msg);
+        }
+    }
+}

package/src/resolvers/RunAIAgentResolver.ts

@@ -12,6 +12,7 @@ import { PUSH_STATUS_UPDATES_TOPIC } from '../generic/PushStatusResolver.js';
 import { startLivenessPulse } from '../generic/FireAndForgetHeartbeat.js';
 import { RequireSystemUser } from '../directives/RequireSystemUser.js';
 import { GetReadWriteProvider } from '../util.js';
+import { resolveWidgetGuestRunContext, elevateUserPayload } from '../realtimeWidget/widgetGuestElevation.js';
 import { SafeJSONParse, UUIDsEqual } from '@memberjunction/global';
 import { GetAttachmentService } from '@memberjunction/aiengine';
 import { NotificationEngine } from '@memberjunction/notifications';
@@ -974,6 +975,17 @@ export class RunAIAgentResolver extends ResolverBase {
             };
         }
 
+        // PUBLIC WEB-WIDGET PRIVILEGED DISPATCH (public-web-widget.md Phase 0): when the request is a
+        // widget guest, the agent runs under a TRUSTED SERVER PRINCIPAL and the agent id is taken
+        // AUTHORITATIVELY from the widget instance (never the client-supplied arg) — so a guest needs
+        // no grants to WRITE the AI run entities and cannot run an arbitrary agent under elevation.
+        // Conversation OWNERSHIP is still enforced under the guest principal below: the guest loads its
+        // own ConversationDetail through the Widget Guest RLS filters, so a detail id from another
+        // session resolves to "not found" before any elevated work happens.
+        const widgetElevation = await resolveWidgetGuestRunContext(userPayload, p);
+        const effectiveAgentId = widgetElevation ? widgetElevation.pinnedAgentId : agentId;
+        const effectiveUserPayload = widgetElevation ? elevateUserPayload(userPayload, widgetElevation.elevatedUser) : userPayload;
+
         try {
             // LATENCY OPTIMIZATION (Opt #2 + #3): Load ConversationDetail once here to extract
             // conversationId, then pass it downstream. Previously this record was loaded multiple
@@ -1004,13 +1016,13 @@ export class RunAIAgentResolver extends ResolverBase {
                 // Fire-and-forget mode: start execution in background, return immediately.
                 // The client will receive the result via WebSocket PubSub completion event.
                 this.executeAgentInBackground(
-                    p, dataSource, agentId, userPayload, messagesJson, sessionId, pubSub,
+                    p, dataSource, effectiveAgentId, effectiveUserPayload, messagesJson, sessionId, pubSub,
                     data, payload, lastRunId, autoPopulateLastRunPayload, configurationId,
                     conversationDetailId, createArtifacts || false, createNotification || false,
                     sourceArtifactId, sourceArtifactVersionId, conversationId, planMode, requestedSkillIDs
                 );
 
-                LogStatus(`🔥 Fire-and-forget: Agent ${agentId} execution started in background for session ${sessionId}`);
+                LogStatus(`🔥 Fire-and-forget: Agent ${effectiveAgentId} execution started in background for session ${sessionId}`);
 
                 return {
                     success: true,
@@ -1022,8 +1034,8 @@ export class RunAIAgentResolver extends ResolverBase {
             return this.executeAIAgent(
                 p,
                 dataSource,
-                agentId,
-                userPayload,
+                effectiveAgentId,
+                effectiveUserPayload,
                 messagesJson,
                 sessionId,
                 pubSub,

package/src/resolvers/SearchKnowledgeResolver.ts

@@ -213,6 +213,7 @@ export class SearchKnowledgeResolver extends ResolverBase {
     ): Promise<SearchKnowledgeResult> {
         const startTime = Date.now();
         try {
+            await this.CheckAPIKeyScopeAuthorization('search:execute', '*', userPayload);
             const currentUser = this.GetUserFromPayload(userPayload);
             if (!currentUser) {
                 return this.errorResult('Unable to determine current user', startTime);
@@ -400,6 +401,7 @@ export class SearchKnowledgeResolver extends ResolverBase {
     ): Promise<SearchKnowledgeResult> {
         const startTime = Date.now();
         try {
+            await this.CheckAPIKeyScopeAuthorization('search:execute', '*', userPayload);
             const currentUser = this.GetUserFromPayload(userPayload);
             if (!currentUser) {
                 return this.errorResult('Unable to determine current user', startTime);