@memberjunction/server 6.1.0-edge.5 → 6.1.0-edge.7

package/src/generic/refusalExtensions.ts

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview The `extensions` object every write-refusal `GraphQLError` in `ResolverBase` carries.
+ *
+ * A save refused by `Validate()` / `ValidateAsync()` leaves its reasons — one `ValidationErrorInfo`
+ * per field — in `LatestResult.Errors`. Until now the resolver threw only `CompleteMessage`, the
+ * flattened prose, so the client got readable text but lost the *structure*: which field each
+ * sentence belonged to. That is why a server-side `ValidateAsync()` refusal could only ever toast,
+ * while the same rule written in a synchronous `Validate()` painted the offending field red — the
+ * client runs sync validation locally and never needed the wire to tell it the field.
+ *
+ * `RefusalExtensions` keeps the message exactly as before and ADDS `validationErrors`, the
+ * `Errors` array flattened by `SerializeValidationErrors` (so a class instance never has to survive
+ * JSON), plus `messageIncludesValidationErrors: true` — the server stating that the message it threw
+ * is `CompleteMessage`, so the client can keep its own `CompleteMessage` from repeating the text
+ * without assuming anything about what the server put in `message`. `GraphQLDataProvider.Save()` rehydrates it into `LatestResult.Errors` on the client, and the
+ * form paints fields from there — the same path the sync branch already uses.
+ *
+ * Kept out of `ResolverBase.ts` so it is unit-testable without booting the resolver's dependency
+ * graph, and so the three resolvers (create / update / delete) share one definition of the shape.
+ */
+import type { BaseEntityResult } from '@memberjunction/core';
+import { SerializeValidationErrors, type SerializedValidationError } from '@memberjunction/global';
+
+/** Error codes the write resolvers use; kept distinct so a client can tell the operations apart. */
+export type WriteRefusalCode = 'CREATE_ENTITY_ERROR' | 'SAVE_ENTITY_ERROR' | 'DELETE_ENTITY_ERROR';
+
+/** The `extensions` payload of a write-refusal `GraphQLError`. */
+export type WriteRefusalExtensions = {
+    code: WriteRefusalCode;
+    entityName: string;
+    /**
+     * Present only when the refusal carried structured errors. Absent (not an empty array) otherwise,
+     * so a client can distinguish "validation said no" from "the database said no".
+     */
+    validationErrors?: SerializedValidationError[];
+    /**
+     * Present (and `true`) alongside `validationErrors`: a statement by THIS producer that the
+     * error's `message` is `LatestResult.CompleteMessage`, i.e. it already renders every entry of
+     * `validationErrors`. The client sets `BaseEntityResult.MessageIncludesErrors` from this — a
+     * fact the server asserts on the wire — rather than assuming what the server put in `message`.
+     * A server that does not send it gets the client's pre-existing behaviour (the text may repeat).
+     */
+    messageIncludesValidationErrors?: true;
+};
+
+/**
+ * Builds the `extensions` for a refused create / update / delete.
+ *
+ * @param code - Which operation was refused.
+ * @param entityName - The entity the operation targeted.
+ * @param result - The entity's `LatestResult` after the failed call, if any.
+ * @returns `{ code, entityName }`, plus `validationErrors` when `result.Errors` had anything to carry.
+ */
+export function RefusalExtensions(code: WriteRefusalCode, entityName: string, result: BaseEntityResult | null | undefined): WriteRefusalExtensions {
+    const validationErrors = SerializeValidationErrors(result?.Errors);
+    return validationErrors.length > 0
+        ? { code, entityName, validationErrors, messageIncludesValidationErrors: true }
+        : { code, entityName };
+}

package/src/index.ts

@@ -44,14 +44,10 @@ import { setupRESTEndpoints } from './rest/setupRESTEndpoints.js';
 import { createOAuthCallbackHandler } from './rest/OAuthCallbackHandler.js';
 import { createSignatureWebhookHandler } from './rest/SignatureWebhookHandler.js';
 import { createMediaStreamRouter } from './rest/MediaStreamHandler.js';
+import { createRealtimeSdpBrokerRouter } from './rest/RealtimeSdpBrokerHandler.js';
+import { REALTIME_SDP_EXCHANGE_PATH } from '@memberjunction/ai';
 import { createMagicLinkHandler, createMagicLinkJwksRouter, registerMagicLinkAuthProvider, MAGIC_LINK_MOUNT_PATH } from './auth/magicLink/index.js';
 import { createWidgetHandler, WIDGET_MOUNT_PATH } from './realtimeWidget/index.js';
-import { createTwilioTelephonyHandler, TWILIO_TELEPHONY_MOUNT_PATH, SetTwilioTelephonyService } from './telephony/index.js';
-import { createVonageTelephonyHandler, VONAGE_TELEPHONY_MOUNT_PATH, SetVonageTelephonyService } from './telephony/index.js';
-import { RingCentralTelephonyService, SetRingCentralTelephonyService } from './telephony/index.js';
-import { createTeamsMeetingsHandler, TEAMS_MEETINGS_MOUNT_PATH, SetTeamsMeetingsService, GetTeamsMeetingsService, StartCalendarScheduler } from './telephony/index.js';
-import { InstallMediaUpgradeDispatcher, IsGraphQLWsPath } from './telephony/index.js';
-
 import { resolve } from 'node:path';
 import { DataSourceInfo, raiseEvent } from './types.js';
 
@@ -81,7 +77,7 @@ import {
   MJCompanyIntegrationFieldMapEntity,
   MJScheduledJobEntity,
 } from '@memberjunction/core-entities';
-import { ServerExtensionLoader, ServerExtensionConfig, mergeServerExtensionConfigs, prepareServerExtensionConfigs, describeServerExtensionMount } from '@memberjunction/server-extensions-core';
+import { ServerExtensionLoader, ServerExtensionConfig, mergeServerExtensionConfigs, prepareServerExtensionConfigs, describeServerExtensionMount, InstallMediaUpgradeDispatcher, IsGraphQLWsPath } from '@memberjunction/server-extensions-core';
 import { coreReservedServerExtensionRoots } from './serverExtensionReservedRoots.js';
 import { MetadataCacheRefreshIntervalSeconds } from './providerConfigUnits.js';
 
@@ -113,8 +109,16 @@ export * from 'type-graphql';
 export { Int, Float, ID } from 'type-graphql';
 export { NewUserBase } from './auth/newUsers.js';
 export { configInfo, DEFAULT_SERVER_CONFIG } from './config.js';
-export { ServerExtensionLoader, BaseServerExtension } from '@memberjunction/server-extensions-core';
-export type { ServerExtensionConfig, ExtensionInitResult, ExtensionHealthResult } from '@memberjunction/server-extensions-core';
+export { ServerExtensionLoader, BaseServerExtension, DefaultServerExtensionServiceRegistry } from '@memberjunction/server-extensions-core';
+export type {
+    ServerExtensionConfig,
+    ServerExtensionPhase,
+    ServerExtensionServiceRegistry,
+    ServerExtensionInitContext,
+    ExtensionInitResult,
+    ExtensionHealthResult,
+    LoadExtensionsOptions,
+} from '@memberjunction/server-extensions-core';
 export * from './directives/index.js';
 export { NoLog, hasNoLogParameter, getNoLogFields } from './logging/NoLog.js';
 export * from './entitySubclasses/MJEntityPermissionEntityServer.server.js';
@@ -127,12 +131,31 @@ export {
 } from './auth/index.js';
 export * from './auth/APIKeyScopeAuth.js';
 export * from './auth/actingContextResolver.js';
+// The context-user ladder (#4209). Public because `auth/exampleNewUserSubClass.ts` — the template
+// integrators are told to copy into their OWN package — resolves through it, and `package.json`
+// publishes only "."; without this the example compiles here and cannot be reused anywhere else.
+// `ReportedMisconfigurationCount` / `MAX_REPORTED_MISCONFIGURATIONS` are deliberately NOT here:
+// they exist so the LRU's bound is assertable, the tests import them from the module directly, and
+// a published export is a maintenance commitment no caller asked for.
+export { ResolveConfiguredPrincipal, resolvePrincipalFrom } from './auth/principals.js';
+export type { ResolvablePrincipal, PrincipalResolution, PrincipalResolutionReason } from './auth/principals.js';
 export { CloneUserForSessionContext } from './auth/sessionUserClone.js';
 
+let _currentExtensionLoader: ServerExtensionLoader | null = null;
+
+/**
+ * Returns the active ServerExtensionLoader instance for the running server.
+ * Returns null if the server has not been started yet.
+ */
+export function GetServerExtensionLoader(): ServerExtensionLoader | null {
+    return _currentExtensionLoader;
+}
+
 export * from './generic/PushStatusResolver.js';
 export * from './generic/PubSubManager.js';
 export * from './generic/CacheInvalidationResolver.js';
 export * from './generic/ResolverBase.js';
+export * from './generic/refusalExtensions.js';
 export * from './generic/RunViewResolver.js';
 export * from './resolvers/RunTemplateResolver.js';
 export * from './resolvers/RunAIPromptResolver.js';
@@ -1158,6 +1181,15 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     startupLog.LogIf('verbose', '[OAuth] Callback route registered at /oauth/callback');
   }
 
+  // ─── Core HTTP Routes (Static Core Infrastructure) ─────────────────────────
+  // IMPORTANT ARCHITECTURAL NOTE:
+  // The route mounts below are strictly reserved for core framework infrastructure (OAuth, eSignature,
+  // media streaming, realtime WebRTC broker, magic-link, widgets).
+  // ALL new custom routes, external webhooks, vendor adapters, and application integrations MUST be
+  // implemented as Server Extensions (subclasses of BaseServerExtension in @memberjunction/server-extensions-core)
+  // mounted via ServerExtensionLoader — NEVER hardcoded as ad-hoc app.use() in serve().
+  // See guides/SERVER_EXTENSIONS_GUIDE.md for complete patterns and best practices.
+
   // ─── eSignature webhook (unauthenticated, registered BEFORE auth) ─────
   // Called by external signature providers (DocuSign Connect, etc.) without an MJ bearer token.
   // The provider DRIVER verifies the payload signature/HMAC; MJ auth does not apply here.
@@ -1171,6 +1203,12 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
   app.use('/media', cors<cors.CorsRequest>(), createMediaStreamRouter());
   startupLog.LogIf('verbose', '[Media] Streaming route registered at /media/:fileId');
 
+  // ─── Realtime WebRTC SDP broker (ticket-gated, registered BEFORE auth) ───────
+  if (configInfo.realtime?.enabled) {
+    app.use(REALTIME_SDP_EXCHANGE_PATH, cors<cors.CorsRequest>(), createRealtimeSdpBrokerRouter());
+    startupLog.LogIf('verbose', `[Realtime] WebRTC SDP broker registered at ${REALTIME_SDP_EXCHANGE_PATH}`);
+  }
+
   // ─── Magic-link routes (MJ-issued, app-scoped external access) ───────────
   // Public router (JWKS + redeem) mounts BEFORE the auth middleware; the
   // authenticated invite-creation router mounts AFTER it (see below).
@@ -1204,110 +1242,111 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     startupLog.LogIf('verbose', `[Widget] Public routes registered at ${WIDGET_MOUNT_PATH}/session and ${WIDGET_MOUNT_PATH}/session/refresh`);
   }
 
-  // ─── Telephony (Twilio) ingress: inbound voice webhook + Media-Streams WSS (PUBLIC) ──
-  // Carriers cannot present an MJ JWT — the X-Twilio-Signature HMAC is the gate. The
-  // public webhook router mounts BEFORE the auth middleware; the Media-Streams WSS attaches
-  // to the shared HTTP server. The outbound PlaceTwilioCall mutation reuses the same service.
-  if (configInfo.telephony?.enabled && configInfo.telephony.twilio) {
-    const twilioHandler = createTwilioTelephonyHandler(oauthPublicUrl, configInfo.telephony.twilio);
-    app.use(TWILIO_TELEPHONY_MOUNT_PATH, cors<cors.CorsRequest>(), twilioHandler.publicRouter);
-    twilioHandler.attachMediaStreamServer();
-    SetTwilioTelephonyService(twilioHandler.service);
-    startupLog.LogIf('verbose', `[Telephony] Twilio routes registered at ${TWILIO_TELEPHONY_MOUNT_PATH}/voice + Media-Streams WSS`);
-  }
+  // ─── Server extensions loader & shared service registry ───────────────────
+  const extensionLoader = new ServerExtensionLoader();
+  _currentExtensionLoader = extensionLoader;
 
-  // ─── Telephony (Vonage) ingress: inbound answer/event webhooks + media WSS (PUBLIC) ──
-  // Carriers cannot present an MJ JWT — the Vonage signed-request HMAC / webhook JWT is the gate.
-  // The public router mounts BEFORE the auth middleware; the media WSS attaches to the shared
-  // HTTP server. The outbound PlaceVonageCall mutation reuses the same service.
-  if (configInfo.telephony?.enabled && configInfo.telephony.vonage) {
-    const vonageHandler = createVonageTelephonyHandler(oauthPublicUrl, configInfo.telephony.vonage);
-    app.use(VONAGE_TELEPHONY_MOUNT_PATH, cors<cors.CorsRequest>(), vonageHandler.publicRouter);
-    vonageHandler.attachMediaStreamServer();
-    SetVonageTelephonyService(vonageHandler.service);
-    startupLog.LogIf('verbose', `[Telephony] Vonage routes registered at ${VONAGE_TELEPHONY_MOUNT_PATH}/answer + /event + media WSS`);
+  // Open App packages publish their extensions; host mj.config.cjs overlays by DriverClass
+  // Backwards-compatibility shim: synthesize ServerExtensionConfig entries from legacy configInfo.telephony
+  const telephonyExtensionConfigs: ServerExtensionConfig[] = [];
+  if (configInfo.telephony?.enabled) {
+    if (configInfo.telephony.twilio) {
+      telephonyExtensionConfigs.push({
+        Enabled: true,
+        DriverClass: 'TwilioTelephonyExtension',
+        RootPath: '/telephony/twilio',
+        Phase: 'pre-auth',
+        Settings: configInfo.telephony.twilio as unknown as Record<string, unknown>,
+      });
+    }
+    if (configInfo.telephony.vonage) {
+      telephonyExtensionConfigs.push({
+        Enabled: true,
+        DriverClass: 'VonageTelephonyExtension',
+        RootPath: '/telephony/vonage',
+        Phase: 'pre-auth',
+        Settings: configInfo.telephony.vonage as unknown as Record<string, unknown>,
+      });
+    }
+    if (configInfo.telephony.ringcentral) {
+      telephonyExtensionConfigs.push({
+        Enabled: true,
+        DriverClass: 'RingCentralTelephonyExtension',
+        RootPath: '/telephony/ringcentral',
+        Phase: 'pre-auth',
+        Settings: configInfo.telephony.ringcentral as unknown as Record<string, unknown>,
+      });
+    }
+    if (configInfo.telephony.teams?.enabled) {
+      telephonyExtensionConfigs.push({
+        Enabled: true,
+        DriverClass: 'TeamsMeetingsExtension',
+        RootPath: '/meetings/teams',
+        Phase: 'pre-auth',
+        Settings: configInfo.telephony.teams as unknown as Record<string, unknown>,
+      });
+    }
   }
 
-  // ─── Telephony (RingCentral) ingress: SIP softphone registration (no HTTP webhook / media WSS) ──
-  // RingCentral's only bidirectional-audio transport is a registered SIP softphone — inbound calls arrive
-  // as SIP INVITEs on its own SIP/TLS connection, so there is no public webhook or media WSS to mount.
-  // start() registers the softphone fire-and-forget so SIP registration never blocks boot; the outbound
-  // PlaceRingCentralCall mutation reuses the same service via the runtime holder.
-  if (configInfo.telephony?.enabled && configInfo.telephony.ringcentral) {
-    const ringCentralService = new RingCentralTelephonyService(configInfo.telephony.ringcentral);
-    SetRingCentralTelephonyService(ringCentralService);
-    void ringCentralService.start();
-    startupLog.LogIf('verbose', `[Telephony] RingCentral SIP softphone starting (codec ${configInfo.telephony.ringcentral.codec ?? 'OPUS/16000'})`);
-  }
+  const rawHostExtensions = (configInfo.serverExtensions ?? []) as ServerExtensionConfig[];
+  const mergedHostExtensions = mergeServerExtensionConfigs(telephonyExtensionConfigs, rawHostExtensions);
 
-  // ─── Teams meetings ingress: Graph change-notification webhook (PUBLIC) ──────────────
-  // Graph cannot present an MJ JWT — the subscription validationToken handshake + the per-
-  // notification clientState shared secret are the gate. The public webhook router mounts
-  // BEFORE the auth middleware. The ACS application-hosted-media audio plane is owned by the
-  // server's native ACS media adapter, which attaches transports to the shared registry
-  // (a media WSS is not needed here). The StartTeamsMeetingSession mutation reuses the same
-  // service via the runtime holder.
-  if (configInfo.telephony?.enabled && configInfo.telephony.teams?.enabled) {
-    const teamsHandler = createTeamsMeetingsHandler(configInfo.telephony.teams);
-    app.use(TEAMS_MEETINGS_MOUNT_PATH, cors<cors.CorsRequest>(), teamsHandler.publicRouter);
-    SetTeamsMeetingsService(teamsHandler.service);
-    startupLog.LogIf('verbose', `[Meetings] Teams routes registered at ${TEAMS_MEETINGS_MOUNT_PATH}/notifications`);
+  // Open App packages publish their extensions; host mj.config.cjs overlays by DriverClass
+  // (and remains the only source for host-only extensions such as Slack/Teams).
+  // extraReservedRoots is derived from the mounts registered above plus graphqlRootPath
+  // so a new pre-auth app.use(...) in serve() must also be added to
+  // coreReservedServerExtensionRoots() — otherwise an Open App can claim it.
+  const extensionConfigs = prepareServerExtensionConfigs(
+    mergeServerExtensionConfigs(
+      options?.serverExtensions ?? [],
+      mergedHostExtensions,
+    ),
+    {
+      onInvalid: (message) => LogError(message),
+      onOverlap: (message) => LogStatus(message),
+      extraReservedRoots: coreReservedServerExtensionRoots(graphqlRootPath),
+    },
+  );
+  for (const cfg of extensionConfigs) {
+    LogStatus(`Server extension ${describeServerExtensionMount(cfg)}`);
   }
 
-  // Install the single path-routing WebSocket-upgrade dispatcher AFTER all media WSS routes have
-  // registered. ws 8.x has each {server}-bound WebSocketServer 400 paths it doesn't own, so the GraphQL
-  // socket and the telephony media sockets cannot coexist as separate {server} servers — this strips the
-  // auto-listeners and routes upgrades by path. No-op when no media routes registered (telephony off).
-  InstallMediaUpgradeDispatcher(httpServer, webSocketServer, graphqlRootPath);
-
   // ─── Global CORS (before auth so 401 responses include CORS headers) ─────
   // Without this, the browser blocks 401 responses from the auth middleware
   // because they lack Access-Control-Allow-Origin headers, preventing the
   // client from reading the error code and triggering token refresh.
   const corsAllowed = configInfo.cors?.allowedOrigins ?? ['*'];
+  const corsWildcard = corsAllowed.includes('*');
+  // SECURITY: never combine credentials with a wildcard/reflect-any-origin policy. When
+  // allowedOrigins is ['*'] the origin callback reflects the caller's Origin, and pairing that
+  // with Access-Control-Allow-Credentials: true lets any site a signed-in user visits make
+  // credentialed cross-origin reads. MJ's primary auth is a Bearer token (not auto-sent
+  // cross-origin), so dropping credentials under the wildcard default is safe; deployments that
+  // genuinely need credentialed CORS must configure an explicit allowedOrigins list.
   app.use(cors<cors.CorsRequest>({
     origin: (origin, callback) => {
       // Allow all origins when ['*'] (default/backward-compatible),
       // or when no Origin header (server-to-server calls).
-      if (corsAllowed.includes('*') || !origin || corsAllowed.includes(origin)) {
+      if (corsWildcard || !origin || corsAllowed.includes(origin)) {
         callback(null, true);
       } else {
         callback(new Error(`Origin ${origin} not allowed by CORS`));
       }
     },
-    credentials: configInfo.cors?.allowCredentials ?? true,
+    credentials: corsWildcard ? false : (configInfo.cors?.allowCredentials ?? true),
     maxAge: configInfo.cors?.maxAge ?? 86400,
   }));
 
-  // ─── Server extensions (before auth — extensions handle their own auth) ─────
+  // ─── Pre-auth server extensions (before auth — extensions handle their own auth) ─────
   // Slack uses HMAC signature verification, Teams uses Bot Framework JWT validation.
   // These must be registered before the unified auth middleware so webhook
   // requests aren't rejected for lacking an MJ bearer token.
-  const extensionLoader = new ServerExtensionLoader();
-  // Open App packages publish their extensions; host mj.config.cjs overlays by DriverClass
-  // (and remains the only source for host-only extensions such as Slack/Teams).
-  // extraReservedRoots is derived from the mounts registered above plus graphqlRootPath
-  // so a new pre-auth app.use(...) in serve() must also be added to
-  // coreReservedServerExtensionRoots() — otherwise an Open App can claim it.
-  const extensionConfigs = prepareServerExtensionConfigs(
-    mergeServerExtensionConfigs(
-      options?.serverExtensions ?? [],
-      (configInfo.serverExtensions ?? []) as ServerExtensionConfig[],
-    ),
-    {
-      onInvalid: (message) => LogError(message),
-      onOverlap: (message) => LogStatus(message),
-      extraReservedRoots: coreReservedServerExtensionRoots(graphqlRootPath),
-    },
-  );
-  // These routes mount BEFORE createUnifiedAuthMiddleware. Name every one so an
-  // operator who installed an Open App for its entities can see the pre-auth HTTP
-  // surface and suppress it with host serverExtensions[].Enabled = false.
-  for (const cfg of extensionConfigs) {
-    LogStatus(`Server extension ${describeServerExtensionMount(cfg)}`);
-  }
   if (extensionConfigs.length > 0) {
-    await extensionLoader.LoadExtensions(app, extensionConfigs);
+    await extensionLoader.LoadExtensions(app, extensionConfigs, {
+      phase: 'pre-auth',
+      httpServer,
+      publicUrl: oauthPublicUrl,
+    });
   }
 
   // Extension health endpoint (always available, returns empty array if no extensions)
@@ -1357,6 +1396,34 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     startupLog.LogIf('verbose', `[Widget] Authenticated route registered at ${WIDGET_MOUNT_PATH}/resolve-identity`);
   }
 
+  // ─── Post-auth server extensions ──────────────────────────────────────────
+  // Extensions declaring Phase: 'post-auth' mount after the unified auth middleware
+  // and are protected by JWT authentication by default.
+  if (extensionConfigs.length > 0) {
+    await extensionLoader.LoadExtensions(app, extensionConfigs, {
+      phase: 'post-auth',
+      httpServer,
+      publicUrl: oauthPublicUrl,
+    });
+  }
+
+  // ─── Cross-extension lifecycle hook: OnAllExtensionsMounted ───────────────
+  // Called after all extensions across both pre-auth and post-auth phases are mounted.
+  // Extensions can wire themselves to services registered by other extensions or core.
+  await extensionLoader.NotifyAllExtensionsMounted({
+    httpServer,
+    publicUrl: oauthPublicUrl,
+  });
+
+  // Install the single path-routing WebSocket-upgrade dispatcher AFTER all extensions across both
+  // pre-auth and post-auth phases have mounted and registered their media WSS routes. ws 8.x has each
+  // {server}-bound WebSocketServer 400 paths it doesn't own, so the GraphQL socket and the telephony
+  // media sockets cannot coexist as separate {server} servers — this strips the auto-listeners and
+  // routes upgrades by path. No-op when no media routes registered (telephony off).
+  InstallMediaUpgradeDispatcher(httpServer, webSocketServer, graphqlRootPath, (req, socket, head) => {
+    return RealtimeProxyServer.Instance.TryHandleUpgrade(req, socket, head);
+  });
+
   // ─── REST API endpoints (auth already handled by unified middleware) ─────
   const restApiConfig = {
     enabled: configInfo.restApiOptions?.enabled ?? false,
@@ -1522,22 +1589,6 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
       .catch(err => console.warn(`[TaskGraphDispatcher] Startup failed: ${err}`));
   }
 
-  // Launch the calendar / scheduled-bridge loop (M2): poll agent calendars for meeting invites and
-  // start due meeting bridges. Mirrors the SessionJanitor lifecycle (run-once + interval, timer
-  // unref'd). Gated on Teams meetings being enabled (the provider whose scheduled-join is wired) and
-  // reuses the SAME meetings service as the ingress; identities without configured calendar creds are
-  // skipped, so this is a harmless no-op until a Graph-backed identity + token are configured.
-  if (resumeUser && configInfo.telephony?.teams?.enabled) { // global-provider-ok: server-owned background poller under the server's provider + system user
-    const teamsMeetingsService = GetTeamsMeetingsService();
-    if (teamsMeetingsService) {
-      StartCalendarScheduler({
-        Provider: Metadata.Provider, // global-provider-ok: server-owned background poller under the server's single default provider + system user
-        ContextUser: resumeUser,
-        TeamsService: teamsMeetingsService,
-        TeamsConfig: configInfo.telephony.teams,
-      });
-    }
-  }
 
   // Set up graceful shutdown handlers
   const gracefulShutdown = async (signal: string) => {
@@ -1547,6 +1598,7 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     if (extensionLoader.ExtensionCount > 0) {
       try {
         await extensionLoader.ShutdownAll();
+        _currentExtensionLoader = null;
         console.log('✅ Server extensions shut down');
       } catch (error) {
         console.error('❌ Error shutting down server extensions:', error);

package/src/realtimeWidget/WidgetSessionService.ts

@@ -17,7 +17,7 @@
 import { Metadata, RunView, UserInfo, LogError, LogStatus } from '@memberjunction/core';
 import { MJLruCache, UUIDsEqual } from '@memberjunction/global';
 import type { MJConversationWidgetInstanceEntity, MJConversationEntity } from '@memberjunction/core-entities';
-import { UserCache } from '@memberjunction/generic-database-provider';
+import { ResolveConfiguredPrincipal } from '../auth/principals.js';
 import { MagicLinkKeyManager } from '../auth/magicLink/MagicLinkKeys.js';
 import { generateSessionId } from '../auth/magicLink/magicLinkCore.js';
 import { MagicLinkService } from '../auth/magicLink/MagicLinkService.js';
@@ -694,19 +694,7 @@ export class WidgetSessionService {
 
   /** Resolves the server-side context user used to READ widget config (not the guest principal). */
   private resolveLookupUser(): UserInfo | null {
-    const candidate = this.config.contextUserForLookup;
-    if (candidate) {
-      const byName = UserCache.Instance.UserByName(candidate);
-      if (byName) {
-        return byName;
-      }
-      LogError(`[Widget] Configured lookup user '${candidate}' not found; falling back to system/Owner.`);
-    }
-    return (
-      UserCache.Instance.GetSystemUser() ??
-      UserCache.Users.find((u) => u.IsActive && u.Type?.trim().toLowerCase() === 'owner') ??
-      null
-    );
+    return ResolveConfiguredPrincipal(this.config.contextUserForLookup, 'Widget');
   }
 
   /**

package/src/realtimeWidget/visitorIdentity.ts

@@ -24,7 +24,7 @@
  * @module @memberjunction/server/widget
  */
 
-import { RunView, UserInfo, LogError, LogStatus, type IMetadataProvider } from '@memberjunction/core';
+import { CompositeKey, RunView, UserInfo, LogError, LogStatus, type IMetadataProvider } from '@memberjunction/core';
 import type { MJConversationEntity, MJAIAgentNoteEntity } from '@memberjunction/core-entities';
 
 const CONVERSATIONS_ENTITY = 'MJ: Conversations';
@@ -60,17 +60,24 @@ export async function resolveIdentityByEmail(
     }
     const entityName = target?.entityName?.trim() || 'Users';
     const emailField = target?.emailField?.trim() || 'Email';
-    const entityId = provider.EntityByName(entityName)?.ID;
-    if (!entityId) {
+    const entityInfo = provider.EntityByName(entityName);
+    if (!entityInfo) {
       LogError(`[VisitorIdentity] identity-resolution entity '${entityName}' not found in metadata.`);
       return undefined;
     }
+    const entityId = entityInfo.ID;
+    // The identity entity is configurable, so its key column(s) can have any name — and may be
+    // composite. Select every key column and carry the record id in the compact record-id form
+    // (the bare value for a single-column key, "F1|v1||F2|v2" for a composite one) that
+    // CompositeKey.FromURLSegment reads back, so LinkedRecordID / PrimaryScopeRecordID round-trip
+    // for any key shape instead of being truncated to the first column.
+    const pkNames = entityInfo.PrimaryKeys.map(pk => pk.Name);
     const rv = new RunView();
-    const result = await rv.RunView<{ ID: string }>(
+    const result = await rv.RunView<Record<string, unknown>>(
       {
         EntityName: entityName,
         ExtraFilter: `${emailField} = '${trimmed.replace(/'/g, "''")}'`,
-        Fields: ['ID'],
+        Fields: pkNames,
         MaxRows: 1,
         ResultType: 'simple',
       },
@@ -80,7 +87,15 @@ export async function resolveIdentityByEmail(
       LogError(`[VisitorIdentity] identity lookup failed for '${entityName}.${emailField}': ${result.ErrorMessage}`);
       return undefined;
     }
-    const recordId = result.Results?.[0]?.ID;
+    const row = result.Results?.[0];
+    if (!row) {
+      return undefined;
+    }
+    const key = CompositeKey.FromEntityRecord(entityInfo, row);
+    if (key.KeyValuePairs.length === 0 || key.KeyValuePairs.some(kv => kv.Value == null)) {
+      return undefined;
+    }
+    const recordId = key.ToCompactURLSegment();
     return recordId ? { entityId, recordId } : undefined;
   } catch (e) {
     LogError(`[VisitorIdentity] resolveIdentityByEmail failed: ${e instanceof Error ? e.message : String(e)}`);

package/src/resolvers/EntityRecordNameResolver.ts

@@ -1,7 +1,8 @@
-import { Metadata, CompositeKey, DatabaseProviderBase } from '@memberjunction/core';
+import { CompositeKey, DatabaseProviderBase, EntityInfo, LogDebug, UserInfo } from '@memberjunction/core';
 import { Arg, Ctx, Field, InputType, ObjectType, Query, Resolver } from 'type-graphql';
-import { AppContext } from '../types.js';
+import { AppContext, UserPayload } from '../types.js';
 import { CompositeKeyInputType, CompositeKeyOutputType } from '../generic/KeyInputOutputTypes.js';
+import { ResolverBase } from '../generic/ResolverBase.js';
 import { GetReadOnlyProvider } from '../util.js';
 
 @InputType()
@@ -31,8 +32,27 @@ export class EntityRecordNameResult {
   RecordName?: string;
 }
 
+/**
+ * Resolves a record's display NAME from its primary key — the lookup behind every foreign-key
+ * link, breadcrumb and picker label in the UI.
+ *
+ * **This is a read of entity data and is gated like one.** It historically took no user context
+ * at all, which made it an open side channel: a caller denied READ on an entity's name field
+ * could still obtain that name here, because the name never travelled through the resolver that
+ * strips denied fields. Field-level security turned that latent gap into a live bypass — the
+ * form-field FK control falls through to this query precisely WHEN the joined display column is
+ * denied, so the one case the fallback exists for was the case that leaked.
+ *
+ * Two gates now apply, matching what the generated single-record resolvers do:
+ *   1. entity-level read permission ({@link ResolverBase.CheckUserReadPermissions});
+ *   2. field-level read permission on the entity's own name field.
+ *
+ * A field-level denial answers `Success: false` with no name rather than throwing. Callers
+ * already treat "no name" as "show the primary key", which is the intended degradation — and it
+ * keeps this query from becoming a probe that distinguishes "restricted" from "missing".
+ */
 @Resolver(EntityRecordNameResult)
-export class EntityRecordNameResolver {
+export class EntityRecordNameResolver extends ResolverBase {
   @Query(() => EntityRecordNameResult)
   async GetEntityRecordName(
     @Arg('EntityName', () => String) EntityName: string,
@@ -40,28 +60,53 @@ export class EntityRecordNameResolver {
     @Ctx() { providers, userPayload }: AppContext
   ): Promise<EntityRecordNameResult> {
     const md = GetReadOnlyProvider(providers, {allowFallbackToReadWrite: true});
+    this.CheckUserReadPermissions(EntityName, userPayload, md);
 
-    return await this.InnerGetEntityRecordName(md, EntityName, primaryKey);
+    return await this.InnerGetEntityRecordName(md, EntityName, primaryKey, userPayload);
   }
 
   @Query(() => [EntityRecordNameResult])
   async GetEntityRecordNames(
     @Arg('info', () => [EntityRecordNameInput]) info: EntityRecordNameInput[],
-    @Ctx() {providers}: AppContext
+    @Ctx() {providers, userPayload}: AppContext
   ): Promise<EntityRecordNameResult[]> {
     const result: EntityRecordNameResult[] = [];
     const md = GetReadOnlyProvider(providers, {allowFallbackToReadWrite: true});
     for (const i of info) {
-      result.push(await this.InnerGetEntityRecordName(md, i.EntityName, i.CompositeKey));
+      // Per item, because the batch spans entities: one denied entity must not fail the whole
+      // batch, and must not be answered from another entity's grant either.
+      this.CheckUserReadPermissions(i.EntityName, userPayload, md);
+      result.push(await this.InnerGetEntityRecordName(md, i.EntityName, i.CompositeKey, userPayload));
     }
     return result;
   }
 
-  async InnerGetEntityRecordName(md: DatabaseProviderBase, EntityName: string, primaryKey: CompositeKeyInputType): Promise<EntityRecordNameResult> {
+  async InnerGetEntityRecordName(
+    md: DatabaseProviderBase,
+    EntityName: string,
+    primaryKey: CompositeKeyInputType,
+    userPayload?: UserPayload
+  ): Promise<EntityRecordNameResult> {
     const pk = new CompositeKey(primaryKey.KeyValuePairs);
     const e = md.Entities.find((e) => e.Name === EntityName);
     if (e) {
-      const recordName = await md.GetEntityRecordName(e.Name, pk);
+      const contextUser = userPayload ? this.GetUserFromPayload(userPayload) : undefined;
+      if (this.IsNameFieldDeniedToUser(e, contextUser)) {
+        LogDebug(
+          `[FieldSecurity] Suppressed GetEntityRecordName for '${EntityName}': ` +
+          `the name field is not readable by this user`
+        );
+        return {
+          Success: false,
+          Status: `Name for record, or record ${pk.ToString()} itself not found, could be an access issue`,
+          CompositeKey: pk,
+          EntityName,
+        };
+      }
+      // Pass the acting user through: the provider signature accepts it, and omitting it ran the
+      // underlying lookup with no identity at all — so row-level security had nothing to filter on
+      // either. The field-level gate above is the column half; this is the row half.
+      const recordName = await md.GetEntityRecordName(e.Name, pk, contextUser);
       if (recordName) return { Success: true, Status: 'OK', CompositeKey: pk, RecordName: recordName, EntityName };
       else
         return {
@@ -72,6 +117,27 @@ export class EntityRecordNameResolver {
         };
     } else return { Success: false, Status: `Entity ${EntityName} not found`, CompositeKey: pk, EntityName };
   }
+
+  /**
+   * Whether field security withholds this entity's NAME field from the user.
+   *
+   * Resolves the name field the same way the provider's own lookup does — the designated
+   * `IsNameField`, else a field literally called `Name` — so the check cannot drift from the
+   * value it is guarding. Fails OPEN only where field security does not apply at all (flag off,
+   * no user, no name field), matching every other FLS gate.
+   */
+  protected IsNameFieldDeniedToUser(entity: EntityInfo, contextUser?: UserInfo): boolean {
+    if (!entity?.EnableFieldLevelSecurity || !contextUser) {
+      return false;
+    }
+    const nameField =
+      entity.Fields?.find(f => f.IsNameField) ??
+      entity.Fields?.find(f => f.Name?.trim().toLowerCase() === 'name');
+    if (!nameField) {
+      return false;
+    }
+    return entity.GetDeniedReadFields(contextUser).has(nameField.Name.trim().toLowerCase());
+  }
 }
 
 export default EntityRecordNameResolver;

package/src/resolvers/FileCategoryResolver.ts

@@ -14,9 +14,8 @@ export class FileCategoryResolver extends FileCategoryResolverBase {
     @Arg('options___', () => DeleteOptionsInput) options: DeleteOptionsInput,
     @Ctx() { providers, userPayload }: AppContext
   ) {
-    const key = new CompositeKey();
-    key.LoadFromSingleKeyValuePair('ID', ID);
-    const p = GetReadWriteProvider(providers);    
+    const key = CompositeKey.FromID(ID); // first-pk-ok: this mutation deletes from MJ: File Categories (core entity keyed by ID) — see the GetEntityObject below
+    const p = GetReadWriteProvider(providers);
 
     if (!(await this.BeforeDelete(p, key))) {
       return null;