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

package/src/auth/actionAuthorization.ts

@@ -0,0 +1,116 @@
+import { AuthorizationInfo, AuthorizationRoleInfo, AuthorizationRoleType, IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { FilterByUUIDs, IndexByUUID, NormalizeUUID, UUIDMap, UUIDsEqual } from '@memberjunction/global';
+
+/** The outcome of {@link EvaluateActionRunAuthorization}. */
+export interface ActionRunAuthorization {
+    /** True when the user may run the action. */
+    Allowed: boolean;
+    /** Why the run is allowed or refused. */
+    Reason: string;
+}
+
+/** One provider's authorization tree and the role grants on it. */
+export type AuthorizationMetadata = Pick<IMetadataProvider, 'Authorizations' | 'AuthorizationRoles'>;
+
+/**
+ * True when the user is an Owner, MJ's superuser type. The column is nchar, so the stored value is
+ * padded.
+ */
+export function IsOwner(user: UserInfo): boolean {
+    return user.Type?.trim().toLowerCase() === 'owner';
+}
+
+/**
+ * Decides whether a user may run an action through a public entry point such as the `RunAction`
+ * mutation. It fails closed:
+ *
+ * - An Owner may run any action.
+ * - An action with `MJ: Action Authorizations` rows runs for a user who holds at least one of the
+ *   linked authorizations. A linked authorization counts only when it is active and none of the
+ *   user's roles is denied it; the user may then hold it directly or through an ancestor.
+ * - An action with no such rows runs for any user when its class authorizes its caller itself
+ *   (`BaseAction.AuthorizesCaller`), so the action's own check decides. Otherwise it runs for
+ *   Owners only.
+ *
+ * The authorizations, their parents and their role grants are read only from `metadata`, never
+ * from the global provider. Pass the provider the `MJ: Action Authorizations` rows were read from.
+ *
+ * Refuse scope-limited sessions before calling this; see `IsScopeLimitedPrincipal`.
+ *
+ * @param user the caller
+ * @param actionAuthorizationIDs the AuthorizationID of each `MJ: Action Authorizations` row for the action
+ * @param metadata the provider whose authorizations and role grants decide
+ * @param actionAuthorizesCaller true when the action's class authorizes its caller itself
+ * @returns whether the run is allowed, and why
+ */
+export function EvaluateActionRunAuthorization(
+    user: UserInfo,
+    actionAuthorizationIDs: readonly string[],
+    metadata: AuthorizationMetadata,
+    actionAuthorizesCaller: boolean
+): ActionRunAuthorization {
+    if (IsOwner(user)) {
+        return { Allowed: true, Reason: 'The user is an Owner.' };
+    }
+    if (actionAuthorizationIDs.length === 0) {
+        return actionAuthorizesCaller
+            ? { Allowed: true, Reason: 'The action authorizes its caller itself.' }
+            : { Allowed: false, Reason: 'No Action Authorization grants this action to any role, and the action does not authorize its caller itself; only an Owner may run it.' };
+    }
+    const authorizationsByID = IndexByUUID(metadata.Authorizations);
+    const userGrants = grantsToUserRoles(user, metadata.AuthorizationRoles);
+    const granted = actionAuthorizationIDs
+        .map((id) => authorizationsByID.Get(id))
+        .filter((auth): auth is AuthorizationInfo => auth !== undefined)
+        .find((auth) => holdsLinkedAuthorization(auth, authorizationsByID, userGrants));
+    return granted
+        ? { Allowed: true, Reason: `The user holds the "${granted.Name}" authorization.` }
+        : { Allowed: false, Reason: 'None of your roles holds an authorization this action requires.' };
+}
+
+/** The role grants that name one of the user's roles. */
+function grantsToUserRoles(user: UserInfo, grants: readonly AuthorizationRoleInfo[]): AuthorizationRoleInfo[] {
+    const userRoleIDs = (user.UserRoles ?? []).map((userRole) => userRole.RoleID);
+    return FilterByUUIDs(grants, userRoleIDs, (grant) => grant.RoleID);
+}
+
+/**
+ * True when the user holds a linked authorization: it is active, none of the user's roles is denied
+ * it, and the user holds it directly or through an ancestor. The first two are checked on the linked
+ * authorization itself, because the ancestor walk would otherwise grant it through the parent.
+ */
+function holdsLinkedAuthorization(auth: AuthorizationInfo, authorizationsByID: UUIDMap<AuthorizationInfo>, userGrants: readonly AuthorizationRoleInfo[]): boolean {
+    if (!auth.IsActive || grantTypes(auth, userGrants).includes(AuthorizationRoleType.Deny)) {
+        return false;
+    }
+    return holdsDirectlyOrThroughAncestor(auth, authorizationsByID, userGrants);
+}
+
+/**
+ * True when the user holds the authorization or one of its ancestors, following `ParentID` within
+ * `authorizationsByID`. This is the walk `AuthorizationEvaluator.UserCanExecuteWithAncestors` does,
+ * with the role grants taken from the same provider as the authorizations.
+ */
+function holdsDirectlyOrThroughAncestor(auth: AuthorizationInfo, authorizationsByID: UUIDMap<AuthorizationInfo>, userGrants: readonly AuthorizationRoleInfo[]): boolean {
+    const visited = new Set<string>();
+    let node: AuthorizationInfo | undefined = auth;
+    while (node && !visited.has(NormalizeUUID(node.ID))) {
+        if (holdsDirectly(node, userGrants)) {
+            return true;
+        }
+        visited.add(NormalizeUUID(node.ID));
+        node = node.ParentID ? authorizationsByID.Get(node.ParentID) : undefined;
+    }
+    return false;
+}
+
+/** True when the authorization is active and the user's roles have an Allow and no Deny on it. */
+function holdsDirectly(auth: AuthorizationInfo, userGrants: readonly AuthorizationRoleInfo[]): boolean {
+    const types = grantTypes(auth, userGrants);
+    return auth.IsActive && types.includes(AuthorizationRoleType.Allow) && !types.includes(AuthorizationRoleType.Deny);
+}
+
+/** Allow or Deny, for each of the user's role grants on the authorization. */
+function grantTypes(auth: AuthorizationInfo, userGrants: readonly AuthorizationRoleInfo[]): AuthorizationRoleType[] {
+    return userGrants.filter((grant) => UUIDsEqual(grant.AuthorizationID, auth.ID)).map((grant) => grant.AuthorizationType());
+}

package/src/auth/index.ts

@@ -13,6 +13,7 @@ export * from './APIKeyScopeAuth.js';
 export * from './scopeLimitedPrincipal.js';
 export * from './actingContextResolver.js';
 export * from './AuthProviderEngine.js';
+export * from './LoginScreenEngine.js';
 export * from './AuthProviderCatalogRouter.js';
 export { InitializeAuthProviders, initializeAuthProviders, InitializeAuthProvidersFromMetadata, initializeAuthProvidersFromMetadata, RefreshAuthProviders, refreshAuthProviders, ValidateAuthProvidersRegistered, validateAuthProvidersRegistered } from './initializeProviders.js';
 
@@ -253,14 +254,9 @@ export const VerifyUserRecord = async (
 ): Promise<UserInfo | undefined> => {
   if (!email) return undefined;
 
-  let user = UserCache.Instance.Users.find((u) => {
-    if (!u.Email || u.Email.trim() === '') {
-      // this condition should never occur. If it doesn throw a console error including the user id
-      // DB requires non-null but this is just an extra check and we could in theory have a blank string in the DB
-      console.error(`SYSTEM METADATA ISSUE: User ${u.ID} has no email address`);
-      return false;
-    } else return u.Email.toLowerCase().trim() === email.toLowerCase().trim();
-  });
+  // FindUser, not Users.find: a user this process has not loaded yet (created seconds ago on
+  // another server) is looked up in the database instead of being treated as nonexistent.
+  let user = await UserCache.Instance.FindUser({ Email: email });
 
   if (!user) {
     // NOTE: `requestDomain` (parsed from the spoofable `Origin` header) is deliberately NOT part of

package/src/auth/magicLink/MagicLinkRouter.ts

@@ -17,6 +17,7 @@ import { MagicLinkKeyManager } from './MagicLinkKeys.js';
 import { MagicLinkService } from './MagicLinkService.js';
 import { BuildRedeemLandingHtml } from './redeemLanding.js';
 import type { CreateMagicLinkInviteParams, RedeemMagicLinkResult } from './types.js';
+import { ApiRoute } from '../../apiRoot.js';
 
 /** The mount path for both routers (`/magic-link`). */
 export const MAGIC_LINK_MOUNT_PATH = '/magic-link';
@@ -107,13 +108,13 @@ export function CreateMagicLinkHandler(publicUrl: string, config: MagicLinkConfi
     }
     // API callers must POST — GET never redeems.
     if (req.query.format === 'json') {
-      res.status(405).json({ success: false, error: 'Redemption requires POST.', method: 'POST', path: `${MAGIC_LINK_MOUNT_PATH}/redeem` });
+      res.status(405).json({ success: false, error: 'Redemption requires POST.', method: 'POST', path: ApiRoute(`${MAGIC_LINK_MOUNT_PATH}/redeem`) });
       return;
     }
     res
       .status(200)
       .type('html')
-      .send(BuildRedeemLandingHtml(token, `${MAGIC_LINK_MOUNT_PATH}/redeem`));
+      .send(BuildRedeemLandingHtml(token, ApiRoute(`${MAGIC_LINK_MOUNT_PATH}/redeem`)));
   });
 
   // POST /redeem performs the actual (side-effectful) redemption. Token arrives

package/src/auth/magicLink/MagicLinkService.ts

@@ -34,6 +34,7 @@ import { ResolveConfiguredPrincipal } from '../principals.js';
 import { CommunicationEngine } from '@memberjunction/communication-engine';
 import { Message } from '@memberjunction/communication-types';
 import { configInfo, type MagicLinkConfig } from '../../config.js';
+import { CreateIsolatedProvider } from '../../isolatedProvider.js';
 import { MagicLinkKeyManager } from './MagicLinkKeys.js';
 import { GenerateRawToken, GenerateSessionId, HashToken, EvaluateInvite, BuildSessionClaims, BuildConsumeInvitePostgresSQL, CanIssueInvites, IsRoleGrantable, MAGIC_LINK_TOKEN_PREFIX } from './magicLinkCore.js';
 import type {
@@ -521,9 +522,11 @@ export class MagicLinkService {
   /** Creates a new user with exactly the restricted role + single app, transactionally. */
   private async createScopedUser(invite: MJMagicLinkInviteEntity, role: RoleInfo, contextUser: UserInfo): Promise<ProvisionResult> {
     // Single provider for BOTH the transaction and the entity writes, so the
-    // BeginTransaction/Save/Commit are provably on the same connection.
-    // global-provider-ok: redemption runs in the pre-auth flow, no per-request provider yet.
-    const provider = Metadata.Provider as DatabaseProviderBase; // global-provider-ok: server-side magic-link service; runs under the server's single default provider
+    // BeginTransaction/Save/Commit are provably on the same connection. Redemption runs
+    // pre-auth, with no per-request provider yet, and the global Metadata.Provider is shared
+    // by every concurrent request: a transaction opened there nests into anyone else's and
+    // swallows their writes. So it gets its own (see CreateIsolatedProvider).
+    const provider = await CreateIsolatedProvider();
     const email = invite.Email;
     // The invite does not persist a name; provision a sensible default. (The
     // create-invite params accept first/last name but there is no column to

package/src/auth/newUsers.ts

@@ -1,7 +1,9 @@
-import { ApplicationInfo, DatabaseProviderBase, EntitySaveOptions, LogError, LogStatus, Metadata, RunView, RunViewResult, UserInfo } from "@memberjunction/core";
+import { ApplicationInfo, CompositeKey, EntitySaveOptions, IMetadataProvider, LogError, LogStatus, RunView, RunViewResult, UserInfo } from "@memberjunction/core";
+import { RecordCloneEngine } from "@memberjunction/record-cloning";
 import { RegisterClass } from "@memberjunction/global";
 import { ResolveConfiguredPrincipal } from "./principals.js";
 import { configInfo } from "../config.js";
+import { CreateIsolatedProvider } from "../isolatedProvider.js";
 import { MJUserEntity, MJUserRoleEntity, MJUserApplicationEntity, MJUserApplicationEntityEntity, MJApplicationEntityType, MJApplicationEntityEntityType, UserInfoEngine } from "@memberjunction/core-entities";
 
 export class NewUserBase {
@@ -16,8 +18,21 @@ export class NewUserBase {
                 return null;
             }
 
-            const md: Metadata = new Metadata(); // global-provider-ok: new-user creation runs in the JWT auth flow, before AppContext.providers is built
-            const user = await md.GetEntityObject<MJUserEntity>('MJ: Users', contextUser) // To-Do - change this to be a different defined user for the user creation process
+            // Everything here, metadata lookups, entity objects and the transaction, goes through ONE
+            // isolated provider. This runs in the JWT auth flow, before AppContext.providers exists, and
+            // the global Metadata.Provider is shared by every concurrent request: a transaction opened
+            // there nests into anyone else's and swallows their writes (see CreateIsolatedProvider).
+            const provider = await CreateIsolatedProvider();
+
+            // A configured template user is copied whole; a plain user is created only if it can't be.
+            const template = configInfo?.userHandling?.newUserTemplate;
+            if (template?.email) {
+                const fromTemplate = await this.createFromTemplate(provider, contextUser, template.email, template.preset, firstName, lastName, email, linkedRecordType, linkedEntityId, linkedEntityRecordId);
+                if (fromTemplate) return fromTemplate;
+                LogError(`Could not create ${email} from template user ${template.email}; creating a plain user instead`);
+            }
+
+            const user = await provider.GetEntityObject<MJUserEntity>('MJ: Users', contextUser) // To-Do - change this to be a different defined user for the user creation process
             user.NewRecord();
             user.Name = email;
             user.IsActive = true;
@@ -38,7 +53,6 @@ export class NewUserBase {
             // Create the user and all of its role/application/app-entity records atomically.
             // If any Save fails partway through, the whole provisioning rolls back so we never
             // leave a half-created user with partial roles/applications behind.
-            const provider = Metadata.Provider as DatabaseProviderBase; // global-provider-ok: new-user creation runs in the JWT auth flow, before AppContext.providers is built
             await provider.BeginTransaction();
             try {
                 if (!await user.Save()) {
@@ -48,13 +62,13 @@ export class NewUserBase {
                 if(configInfo.userHandling && configInfo.userHandling.newUserRoles){
                     LogStatus(`User ${user.Email} created, assigning roles`);
                     for (const role of configInfo.userHandling.newUserRoles) {
-                        const userRole = md.Roles.find(r => r.Name === role);
+                        const userRole = provider.Roles.find(r => r.Name === role);
                         if (!userRole) {
                             LogError(`Role ${role} not found in the database, cannot assign to new user ${user.Name}`);
                             continue;
                         }
 
-                        const userRoleEntity: MJUserRoleEntity = await md.GetEntityObject<MJUserRoleEntity>('MJ: User Roles', contextUser);
+                        const userRoleEntity: MJUserRoleEntity = await provider.GetEntityObject<MJUserRoleEntity>('MJ: User Roles', contextUser);
                         userRoleEntity.NewRecord();
                         userRoleEntity.UserID = user.ID;
                         userRoleEntity.RoleID = userRole.ID;
@@ -73,7 +87,7 @@ export class NewUserBase {
                     if (configInfo.userHandling.UserApplications && configInfo.userHandling.UserApplications.length > 0) {
                         for (const appName of configInfo.userHandling.UserApplications) {
                             const toLowerCase: string = appName.trim().toLocaleLowerCase();
-                            const application: ApplicationInfo | undefined = md.Applications.find(a => a.Name.trim().toLocaleLowerCase() === toLowerCase);
+                            const application: ApplicationInfo | undefined = provider.Applications.find(a => a.Name.trim().toLocaleLowerCase() === toLowerCase);
                             if (application) {
                                 applicationsToCreate.push(application);
                             } else {
@@ -85,12 +99,12 @@ export class NewUserBase {
                         // Bug F2: use the shared selector, which filters to Active apps flagged
                         // DefaultForNewUser (in DefaultSequence order). This path previously omitted the
                         // Status = 'Active' check, so an inactive default app could be provisioned here.
-                        applicationsToCreate = UserInfoEngine.GetDefaultApplicationsForNewUser(md);
+                        applicationsToCreate = UserInfoEngine.GetDefaultApplicationsForNewUser(provider);
                         LogStatus(`Found ${applicationsToCreate.length} active applications with DefaultForNewUser=true`);
                     }
 
                     for (const [appIndex, application] of applicationsToCreate.entries()) {
-                        const userApplication: MJUserApplicationEntity = await md.GetEntityObject<MJUserApplicationEntity>('MJ: User Applications', contextUser);
+                        const userApplication: MJUserApplicationEntity = await provider.GetEntityObject<MJUserApplicationEntity>('MJ: User Applications', contextUser);
                         userApplication.NewRecord();
                         userApplication.UserID = user.ID;
                         userApplication.ApplicationID = application.ID;
@@ -102,7 +116,7 @@ export class NewUserBase {
                         }
                         LogStatus(`Created User Application ${application.Name} for new user ${user.Name}`);
 
-                        const rv: RunView = new RunView();
+                        const rv: RunView = RunView.FromMetadataProvider(provider);
                         // Boolean literal goes through the active provider's dialect:
                         //   SQL Server emits `= 1`, PostgreSQL emits `= TRUE`.
                         // This keeps the filter server-side (no client-side `.filter()`
@@ -125,7 +139,7 @@ export class NewUserBase {
                         LogStatus(`Creating ${defaultForNewUserEntities.length} User Application Entities for User Application ${application.Name} for new user ${user.Name}`);
 
                         for(const [index, appEntity] of defaultForNewUserEntities.entries()){
-                            const userAppEntity: MJUserApplicationEntityEntity = await md.GetEntityObject<MJUserApplicationEntityEntity>('MJ: User Application Entities', contextUser);
+                            const userAppEntity: MJUserApplicationEntityEntity = await provider.GetEntityObject<MJUserApplicationEntityEntity>('MJ: User Application Entities', contextUser);
                             userAppEntity.NewRecord();
                             userAppEntity.UserApplicationID = userApplication.ID;
                             userAppEntity.EntityID = appEntity.EntityID;
@@ -153,4 +167,78 @@ export class NewUserBase {
             return undefined;
         }
     }
+
+    /**
+     * Creates the new user as a copy of the template user `templateEmail`, through the `MJ: Users`
+     * clone `preset`: its roles, apps, views, settings, dashboards and conversations come with it, owned
+     * by the new user. The clone engine creates users inactive for review; a user signing in is active.
+     *
+     * @returns the new user, or null when the template is missing, isn't flagged IsTemplate, or the copy
+     *          fails (the reason is logged and the caller falls back to a plain user).
+     */
+    protected async createFromTemplate(
+        provider: IMetadataProvider,
+        contextUser: UserInfo,
+        templateEmail: string,
+        preset: string,
+        firstName: string,
+        lastName: string,
+        email: string,
+        linkedRecordType: string,
+        linkedEntityId?: string,
+        linkedEntityRecordId?: string
+    ): Promise<MJUserEntity | null> {
+        const lookup = await RunView.FromMetadataProvider(provider).RunView<{ ID: string; IsTemplate: boolean }>(
+            {
+                EntityName: 'MJ: Users',
+                ExtraFilter: `Email = '${templateEmail.replace(/'/g, "''")}'`,
+                Fields: ['ID', 'IsTemplate'],
+                ResultType: 'simple',
+                MaxRows: 1,
+            },
+            contextUser
+        );
+        const templateUser = lookup.Success ? lookup.Results[0] : undefined;
+        if (!templateUser) {
+            LogError(`userHandling.newUserTemplate: no user has the email ${templateEmail}`);
+            return null;
+        }
+        if (!templateUser.IsTemplate) {
+            LogError(`userHandling.newUserTemplate: ${templateEmail} is not marked as a template user (IsTemplate)`);
+            return null;
+        }
+
+        const result = await new RecordCloneEngine(provider).Clone(
+            {
+                EntityName: 'MJ: Users',
+                SourceRecordKey: CompositeKey.FromID(templateUser.ID),
+                Preset: preset,
+                PromptedValues: { Email: email, FirstName: firstName, LastName: lastName },
+                Options: { Reason: `New user ${email} created at first sign-in from template ${templateEmail}` },
+            },
+            contextUser
+        );
+        const newKey = result.Roots?.[0]?.TargetKey.KeyValuePairs.find((kvp) => kvp.FieldName === 'ID')?.Value;
+        if (!result.Success || !newKey) {
+            const reasons = result.Warnings.filter((w) => w.Severity === 'Error').map((w) => w.Message);
+            LogError(`userHandling.newUserTemplate: copying ${templateEmail} failed: ${result.ErrorMessage || reasons.join('; ') || result.ResultCode}`);
+            return null;
+        }
+
+        const user = await provider.GetEntityObject<MJUserEntity>('MJ: Users', contextUser);
+        if (!(await user.Load(String(newKey)))) {
+            LogError(`userHandling.newUserTemplate: the copy of ${templateEmail} for ${email} could not be loaded`);
+            return null;
+        }
+        user.IsActive = true;
+        user.LinkedRecordType = linkedRecordType;
+        if (linkedEntityId) user.LinkedEntityID = linkedEntityId;
+        if (linkedEntityRecordId) user.LinkedEntityRecordID = linkedEntityRecordId;
+        if (!(await user.Save())) {
+            LogError(`userHandling.newUserTemplate: could not activate ${email}: ${user.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            return null;
+        }
+        LogStatus(`Created user ${email} from template ${templateEmail} (${result.RecordsCloned ?? result.Created?.length ?? 0} records copied)`);
+        return user;
+    }
 }

package/src/config.ts

@@ -38,6 +38,19 @@ const userHandlingInfoSchema = z.object({
   contextUserForNewUserCreation: z.string().optional().default(''),
   CreateUserApplicationRecords: z.boolean().optional().default(false),
   UserApplications: z.array(z.string()).optional().default([]),
+  /**
+   * Build each auto-created user as a copy of a template user (`User.IsTemplate`), so new people start
+   * with its pinned apps, views, settings, dashboards and conversations. `email` names the template;
+   * `preset` is the `MJ: Users` clone preset to apply (default `template`). The copy takes the roles
+   * and apps of the template, so `newUserRoles`, `CreateUserApplicationRecords` and `UserApplications`
+   * apply only when the template can't be used, in which case a plain user is created as before.
+   */
+  newUserTemplate: z
+    .object({
+      email: z.string(),
+      preset: z.string().optional().default('template'),
+    })
+    .optional(),
 });
 
 const databaseSettingsInfoSchema = z.object({
@@ -213,10 +226,19 @@ const telemetrySchema = z.object({
   level: z.enum(['minimal', 'standard', 'verbose', 'debug']).optional().default('standard'),
 });
 
-const serverExtensionSchema = z.object({
-  Enabled: z.boolean().default(true),
+/**
+ * A host `mj.config.cjs` `serverExtensions[]` entry. Only `DriverClass` is required: an entry whose
+ * DriverClass an Open App package already publishes is an OVERLAY (MergeServerExtensionConfigs) and
+ * may set just the fields it overrides — `{ DriverClass: 'X', OwnsCORS: false }` — without repeating
+ * `RootPath`. `Enabled` has no schema default for the same reason: a defaulted `true` would silently
+ * re-enable an extension the package ships disabled. Whether the MERGED entry is complete (a valid
+ * `RootPath`; `Enabled` defaults to true) is validated after the merge, by prepareServerExtensionConfigs,
+ * which reports an incomplete host-only entry instead of mounting it.
+ */
+export const ServerExtensionSchema = z.object({
+  Enabled: z.boolean().optional(),
   DriverClass: z.string(),
-  RootPath: z.string(),
+  RootPath: z.string().optional(),
   Settings: z.record(z.unknown()).default({})
 }).passthrough();
 
@@ -225,6 +247,14 @@ const cacheSettingsSchema = z.object({
   maxMemoryMB: z.number().optional().default(150),
   /** Maximum percentage of total cache memory that any single entity can occupy. Default: 50. Set to 0 to disable. */
   maxPercentOfCachePerEntity: z.number().optional().default(50),
+  /**
+   * Ceiling on any ONE cache entry. 'auto' (the default) derives it from maxMemoryMB, so the
+   * largest entity the server caches scales with the memory the cache was given; a number is an
+   * explicit stricter percentage of maxMemoryMB; 0 removes the ceiling. Leave it on 'auto' unless
+   * a specific entry must be kept out of the cache — an entry declined by the ceiling is re-read
+   * from the database on every call, and the server logs which maxMemoryMB would admit it.
+   */
+  maxEntryPercentOfCache: z.union([z.number(), z.literal('auto')]).optional().default('auto'),
   /** Default TTL in seconds. 0 = no TTL, rely on event-based invalidation. Default: 0. */
   defaultTTLSeconds: z.number().optional().default(0),
   /** Interval in seconds for periodic eviction sweep. 0 = disabled. Default: 300 (5 minutes). */
@@ -254,6 +284,38 @@ const cacheSettingsSchema = z.object({
    * every signed-in user may read every row of every entity.
    */
   recordDataBroadcastEntities: z.array(z.string()).optional().default([]),
+  /**
+   * Expiry, in seconds, of entries in the shared Redis cache (used when REDIS_URL is set). The
+   * REDIS_TTL_SECONDS environment variable overrides it. 0 stores entries without expiry. When
+   * neither is set, the Redis provider's default applies (one hour).
+   */
+  sharedCacheTTLSeconds: z.number().int().nonnegative().optional(),
+  /**
+   * How often, in seconds, loaded engines compare their rows with the database and reload what
+   * changed without an MJ event (direct SQL, other applications). With a shared cache one server
+   * does it per interval. 0 = disabled. Default: 300 (5 minutes).
+   */
+  engineSweepIntervalSeconds: z.number().int().nonnegative().optional().default(300),
+  /**
+   * How often, in seconds, the user cache compares two row counts and the newest update timestamp
+   * with the database and reloads only when they differ. The cache already refreshes on MJ writes
+   * (locally and, with a shared cache, on other servers); this covers changes made outside MJ.
+   * 0 = disabled. Default: 300 (5 minutes).
+   */
+  userCacheCheckIntervalSeconds: z.number().int().nonnegative().optional().default(300),
+  /**
+   * How often to compare this process's metadata with the database, in seconds (0 disables).
+   * Costs nothing unless an entity the metadata is built from declares
+   * `TrustServerCacheCompletely = false`; see `ProviderBase.SweepMetadataAgainstDatabase`.
+   */
+  metadataSweepIntervalSeconds: z.number().int().nonnegative().optional().default(300),
+  /**
+   * How long, in seconds, a server holds the shared warm-up turn while it loads its engines, so
+   * servers starting together load one at a time and the rest find the cache warm. The lease is
+   * renewed while the load runs; this value is both its expiry and how long another server waits
+   * for it. 0 disables the turn-taking. Default: 30.
+   */
+  startupWarmupLeaseSeconds: z.number().int().nonnegative().optional().default(30),
 });
 
 const loggingSettingsSchema = z.object({
@@ -271,6 +333,15 @@ const loggingSettingsSchema = z.object({
   }).optional().default({}),
 });
 
+const aiPromptRunsSchema = z.object({
+  /**
+   * Server default for which template inputs prompt runs store in AIPromptRun.Messages:
+   * 'None' (key sizes only), 'Referenced' (keys the templates read) or 'Full'.
+   * AIPrompt.TemplateDataCapture and AIPromptParams.TemplateDataCapture override it.
+   */
+  templateDataCapture: z.enum(['None', 'Referenced', 'Full']).optional(),
+});
+
 const corsSchema = z.object({
   /** Allowed origins for CORS. Default ['*'] preserves backward-compatible "allow all" behavior. */
   allowedOrigins: z.array(z.string()).default(['*']),
@@ -684,9 +755,92 @@ const telephonySchema = z.object({
   teams: teamsMeetingsSchema.optional(),
 }).passthrough();
 
+/**
+ * Mid-session identity verification for realtime sessions (see `src/realtimeSessions/README.md`).
+ *
+ * A person talking to an agent proves they control an email address WITHOUT leaving the conversation:
+ * the server emails a one-time link plus a short code, records the verification on the session, extends
+ * the session's limits, and tells the live session through a session event. The session's principal is
+ * never changed.
+ *
+ * Off by default: nothing is emailed and `/realtime/verify` is not mounted until `enabled` is true AND a
+ * `communicationProvider` is configured. Policy set here is the BASE layer; the config cascade
+ * (`channels.config.IdentityVerification`) snapshotted onto each session at mint overrides it per knob.
+ */
+const identityVerificationSchema = z.object({
+  /** Master switch. When false the verify routes are not mounted and the GraphQL operations refuse. */
+  enabled: zodBooleanWithTransforms().default(false),
+  /** CommunicationEngine provider that delivers the verification email (e.g. 'SendGrid', 'Microsoft Graph'). Required to send. */
+  communicationProvider: z.string().optional(),
+  /** From address of the verification email. */
+  fromAddress: z.string().optional(),
+  /**
+   * Server-only secret the typed verification code is HMAC'd under before it is stored on the session
+   * (at least 16 characters; 32+ random characters recommended). REQUIRED: without it verification is
+   * unavailable, because a session's owner can read their own session row and a bare hash of a six-digit
+   * code can be reversed offline. Never exposed to clients. Rotating it voids pending verifications only.
+   */
+  hmacSecret: z.string().optional().default(process.env.MJ_REALTIME_VERIFICATION_SECRET || ''),
+  /**
+   * `send` (default) delivers the email. `dry-run` builds and logs the message through the communication
+   * provider WITHOUT delivering it — for rehearsal and integration environments, where a test reads the
+   * emailed link and code from the `MJ: Communication Logs` row. Never use `dry-run` in production: the
+   * Communication Log then holds live credentials and no one is emailed.
+   */
+  deliveryMode: z.enum(['send', 'dry-run']).optional().default('send'),
+  /**
+   * Base URL the emailed link is built from (`<publicBaseUrl>/realtime/verify/<token>`). Defaults to the
+   * server's `publicUrl`, or `baseUrl:graphqlPort` when that is unset — the same derivation magic links use.
+   */
+  publicBaseUrl: z.string().optional(),
+  /**
+   * The internal user the server acts as to read/write the session, send the email and write the audit
+   * row, matched against `User.Name` then `User.Email` (falls back to the system user, then the lowest-ID
+   * active Owner). The verify link is public, so it has no caller identity of its own.
+   */
+  contextUserForVerification: z.string().optional(),
+  /** Base policy layer; each knob here is overridden by the per-session cascade layer. */
+  policy: z.object({
+    requireBusinessDomain: z.boolean().optional(),
+    blockedDomains: z.array(z.string()).optional(),
+    consumerDomains: z.array(z.string()).optional(),
+    linkTtlMinutes: z.coerce.number().optional(),
+    maxSendsPerSession: z.coerce.number().optional(),
+    maxCodeAttempts: z.coerce.number().optional(),
+    unverifiedMaxSeconds: z.coerce.number().optional(),
+    verifiedMaxSeconds: z.coerce.number().optional(),
+  }).optional().default({}),
+  /** Send-side and attempt-side limits (per instance, in memory; per-session limits are persisted and exact). */
+  rateLimits: z.object({
+    /** Window (ms) for the three send limits. Default 1 hour. */
+    sendWindowMs: z.coerce.number().optional().default(3_600_000),
+    /** Verification emails per client IP per window. Default 10. 0 disables. */
+    perIpSends: z.coerce.number().optional().default(10),
+    /** Verification emails per recipient domain per window. Default 30. 0 disables. */
+    perEmailDomainSends: z.coerce.number().optional().default(30),
+    /** Verification emails per recipient address per window — stops the feature being used to mail-bomb one inbox. Default 3. 0 disables. */
+    perEmailSends: z.coerce.number().optional().default(3),
+    /** Window (ms) for code attempts. Default 10 minutes. */
+    codeAttemptWindowMs: z.coerce.number().optional().default(600_000),
+    /** Code submissions per session per window. Default 10. 0 disables. */
+    perSessionCodeAttempts: z.coerce.number().optional().default(10),
+    /** Window (ms) of the public `/realtime/verify` route limiter. Default 60s. */
+    redeemWindowMs: z.coerce.number().optional().default(60_000),
+    /** `/realtime/verify` requests per IP per window. Default 30. */
+    redeemPerIp: z.coerce.number().optional().default(30),
+  }).optional().default({}),
+}).passthrough();
+
 const realtimeSchema = z.object({
   /** Master switch. When false, the WebRTC SDP broker router is not mounted. Defaults to true. */
   enabled: zodBooleanWithTransforms().default(true),
+  /** Mid-session identity verification (off by default). */
+  identityVerification: identityVerificationSchema.optional().default({}),
+  /**
+   * Seconds a client-direct call's recording waits for missing shards after its terminal signal before it
+   * is assembled anyway as `Partial` (gaps become silence). Defaults to 90.
+   */
+  recordingAssemblyGraceSeconds: z.coerce.number().positive().optional().default(90),
 }).passthrough();
 
 const configInfoSchema = z.object({
@@ -707,9 +861,10 @@ const configInfoSchema = z.object({
   telemetry: telemetrySchema.optional().default({}),
   queryDialects: queryDialectSchema.optional().default({}),
   multiTenancy: multiTenancySchema.optional().default({}),
-  serverExtensions: z.array(serverExtensionSchema).optional().default([]),
+  serverExtensions: z.array(ServerExtensionSchema).optional().default([]),
   cacheSettings: cacheSettingsSchema.optional().default({}),
   loggingSettings: loggingSettingsSchema.optional().default({}),
+  aiPromptRuns: aiPromptRunsSchema.optional(),
   feedbackSettings: feedbackSettingsSchema.optional().default({}),
   cors: corsSchema.optional().default({}),
   rateLimiting: rateLimitSchema.optional().default({}),
@@ -737,6 +892,12 @@ const configInfoSchema = z.object({
   ___codeGenAPIPort: z.coerce.number().optional().default(3999),
   ___codeGenAPISubmissionDelay: z.coerce.number().optional().default(5000),
   graphqlRootPath: z.string().optional().default('/'),
+  /**
+   * Path prefix MJAPI mounts every route it serves under (core routes and server extensions), on its own
+   * listener. `/` unless a proxy forwards a prefix WITHOUT stripping it (e.g. CloudFront `/api/*` → MJAPI):
+   * then set `MJAPI_BASE_PATH=/api`. Independent of `graphqlRootPath`, which is only Apollo's path. MJ #5674.
+   */
+  apiBasePath: z.string().optional().default('/'),
   enableIntrospection: z.coerce.boolean().optional().default(false),
   websiteRunFromPackage: z.coerce.number().optional(),
   userEmailMap: z
@@ -751,6 +912,7 @@ export type MagicLinkConfig = z.infer<typeof magicLinkSchema>;
 export type WidgetConfig = z.infer<typeof widgetSchema>;
 export type TelephonyConfig = z.infer<typeof telephonySchema>;
 export type RealtimeConfig = z.infer<typeof realtimeSchema>;
+export type IdentityVerificationConfig = z.infer<typeof identityVerificationSchema>;
 export type TwilioTelephonyConfig = z.infer<typeof twilioTelephonySchema>;
 export type VonageTelephonyConfig = z.infer<typeof vonageTelephonySchema>;
 export type RingCentralTelephonyConfig = z.infer<typeof ringcentralTelephonySchema>;
@@ -769,9 +931,10 @@ export type { WorkQueueConfig } from './services/workQueueConfig.js';
 export type TelemetryConfig = z.infer<typeof telemetrySchema>;
 export type QueryDialectConfig = z.infer<typeof queryDialectSchema>;
 export type MultiTenancyConfig = z.infer<typeof multiTenancySchema>;
-export type ServerExtensionConfig = z.infer<typeof serverExtensionSchema>;
+export type ServerExtensionConfig = z.infer<typeof ServerExtensionSchema>;
 export type CacheSettingsConfig = z.infer<typeof cacheSettingsSchema>;
 export type LoggingSettingsConfig = z.infer<typeof loggingSettingsSchema>;
+export type AIPromptRunsConfig = z.infer<typeof aiPromptRunsSchema>;
 export type FeedbackGithubSettingsConfig = z.infer<typeof feedbackGithubSettingsSchema>;
 export type FeedbackSettingsConfig = z.infer<typeof feedbackSettingsSchema>;
 export type CorsConfig = z.infer<typeof corsSchema>;
@@ -807,6 +970,7 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
   // GraphQL server settings (environment-driven with defaults)
   graphqlPort: process.env.GRAPHQL_PORT ? parseInt(process.env.GRAPHQL_PORT, 10) : 4000,
   graphqlRootPath: process.env.GRAPHQL_ROOT_PATH ?? '/',
+  apiBasePath: process.env.MJAPI_BASE_PATH ?? '/',
   baseUrl: process.env.GRAPHQL_BASE_URL ?? 'http://localhost',
   publicUrl: process.env.MJAPI_PUBLIC_URL,
   enableIntrospection: process.env.ENABLE_INTROSPECTION === 'true',
@@ -923,9 +1087,11 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
   cacheSettings: {
     maxMemoryMB: 150,
     maxPercentOfCachePerEntity: 50,
+    maxEntryPercentOfCache: 'auto',
     defaultTTLSeconds: 0,
     evictionSweepIntervalSeconds: 300,
     verboseLogging: false,
+    engineSweepIntervalSeconds: 300,
   },
 
   // Logging settings defaults — variables logging is always off unless the operator