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

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { DEFAULT_WORK_QUEUE_CONFIG, WorkQueueSchema } from './services/workQueueConfig.js';
 import { cosmiconfigSync } from 'cosmiconfig';
 import { LogError, LogStatus, LogStatusEx } from '@memberjunction/core';
 import { mergeConfigs, parseBooleanEnv } from '@memberjunction/config';
@@ -37,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({
@@ -253,6 +267,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({
@@ -470,10 +516,20 @@ const twilioTelephonySchema = z.object({
   apiKeySecret: z.string().optional(),
   /** The publicly reachable `wss://…/telephony/twilio/media` URL Twilio's <Connect><Stream> connects to. */
   streamPublicUrl: z.string(),
-  /** Optional shared secret gating the public webhook/WSS endpoints (defense-in-depth beyond signature verification). */
+  /**
+   * Reserved; currently unused. The Media-Streams websocket is authenticated by a per-call token MJ mints and
+   * embeds in the TwiML (`<Parameter name="mjToken">`), and webhooks by `X-Twilio-Signature`.
+   */
   webhookSigningSecret: z.string().optional(),
-  /** Optional status-callback URL Twilio posts call lifecycle events to. */
+  /**
+   * URL Twilio posts outbound-call lifecycle events to. Defaults to `<public URL>/telephony/twilio/status`, the
+   * route that ends the bridge session when a call is busy / unanswered / failed / completed.
+   */
   statusCallbackUrl: z.string().optional(),
+  /** URL Twilio posts the async answering-machine verdict to. Defaults to `<public URL>/telephony/twilio/amd`. */
+  amdStatusCallbackUrl: z.string().optional(),
+  /** What to do when a machine or fax answers an outbound call: `hangup` (default) ends it, `continue` only logs the verdict. */
+  onMachine: z.enum(['hangup', 'continue']).optional(),
 }).passthrough();
 
 /**
@@ -495,8 +551,14 @@ const vonageTelephonySchema = z.object({
   mediaPublicUrl: z.string(),
   /** Vonage account signature secret — HMAC key for signed-request `sig` AND HS256 webhook-JWT verification. */
   signatureSecret: z.string().optional(),
-  /** Optional event-webhook URL Vonage posts call lifecycle events to (passed on outbound createCall). */
+  /**
+   * Event-webhook URL Vonage posts call lifecycle events to (passed on outbound createCall). Defaults to
+   * `<public URL>/telephony/vonage/event`, the route that ends the bridge session when a call is busy /
+   * unanswered / failed / completed.
+   */
   eventUrl: z.string().optional(),
+  /** What to do when a machine answers an outbound call — Vonage's `machine_detection`: `hangup` (default) or `continue`. */
+  onMachine: z.enum(['hangup', 'continue']).optional(),
 }).passthrough();
 
 /**
@@ -550,22 +612,204 @@ const teamsMeetingsSchema = z.object({
   modelSampleRate: z.coerce.number().optional().default(16000),
 }).passthrough();
 
+/**
+ * LiveKit SIP binding: phone calls carried by a SIP trunk and landed in a LiveKit room (every conversation lives in a room;
+ * the carrier is only the pipe). LiveKit credentials default to the `LIVEKIT_URL` / `LIVEKIT_API_KEY` /
+ * `LIVEKIT_API_SECRET` env vars the Meet room already uses. When `livekitSip` is omitted, the LiveKit SIP webhook is not mounted.
+ * Point a LiveKit project webhook at `<public URL>/telephony/livekit-sip/webhook` (the signature is verified with the API secret).
+ */
+const livekitSipTelephonySchema = z.object({
+  /** LiveKit server URL (`wss://…`). Defaults to `LIVEKIT_URL`. */
+  serverUrl: z.string().optional(),
+  /** LiveKit API key. Defaults to `LIVEKIT_API_KEY`. */
+  apiKey: z.string().optional(),
+  /** LiveKit API secret (resolved upstream — never inlined). Defaults to `LIVEKIT_API_SECRET`. */
+  apiSecret: z.string().optional(),
+  /** Inbound calls land in a room whose name starts with this. Defaults to `call-`. */
+  roomPrefix: z.string().optional(),
+  /** The numbers (E.164) this deployment answers. Each routes to the agent identity registered for it (on the LiveKit provider). */
+  numbers: z.array(z.string()).optional(),
+  /** The LiveKit inbound trunk id, when created by hand. */
+  inboundTrunkId: z.string().optional(),
+  /** The LiveKit OUTBOUND trunk used to dial out (outbound calls, fallback legs, transfers to a number). Dialing out is off without it. */
+  outboundTrunkId: z.string().optional(),
+  /** The caller ID presented on calls dialed out through the outbound trunk. */
+  outboundFromNumber: z.string().optional(),
+  /** Create the inbound trunk and dispatch rule at startup when missing (idempotent). Defaults to false. */
+  autoProvision: zodBooleanWithTransforms().optional().default(false),
+  /** Source addresses the inbound trunk accepts calls from (the carrier's SIP signalling addresses). Used when provisioning. */
+  allowedAddresses: z.array(z.string()).optional(),
+  /** The carrier behind the trunk, for configuration checks only (no carrier API is called). */
+  carrier: z
+    .object({
+      type: z.literal('twilio-elastic-sip'),
+      /** The LiveKit SIP URI the Twilio trunk's origination URI points at, e.g. `sip:<project>.sip.livekit.cloud`. */
+      originationUri: z.string().optional(),
+      /** The trunk's Termination SIP URI on Twilio (`<name>.pstn.twilio.com`). Needed only when dialing out. */
+      terminationUri: z.string().optional(),
+      /** How Twilio authenticates LiveKit's outbound requests. */
+      terminationAuth: z.enum(['credential-list', 'ip-acl']).optional(),
+      /** The Twilio numbers associated with the trunk (E.164). */
+      numbers: z.array(z.string()).optional(),
+    })
+    .optional(),
+}).passthrough();
+
+/**
+ * Outbound-call policy applied to every `PlaceTwilioCall` / `PlaceVonageCall` / `PlaceRingCentralCall`
+ * mutation, on top of the caller's right to run the agent. Defaults are deliberately conservative.
+ * The rate limiter is in-memory and therefore PER PROCESS: with N MJAPI instances a user can place up to
+ * N × `maxCallsPerUserPerHour` calls.
+ */
+const outboundTelephonySchema = z.object({
+  /** Destination prefixes a call may go to (E.164, e.g. `+1`). An empty list refuses every destination. Defaults to `['+1']`. */
+  allowedPrefixes: z.array(z.string()).optional().default(['+1']),
+  /**
+   * Destination prefixes that are always refused, even when an allowed prefix matches. Deliberately has NO default
+   * here: when omitted, `@memberjunction/telephony-adapters` applies its own `DEFAULT_BLOCKED_PREFIXES` (NANP
+   * premium-rate plus the Caribbean +1 countries abused for toll fraud), so the list lives in exactly one place.
+   * Setting this REPLACES that list.
+   */
+  blockedPrefixes: z.array(z.string()).optional(),
+  /** Max outbound calls one user may place per rolling hour (per process). Defaults to 20. */
+  maxCallsPerUserPerHour: z.coerce.number().int().positive().optional().default(20),
+}).passthrough();
+
 const telephonySchema = z.object({
   /** Master switch. When false (or when no vendor block is present), telephony routes are not mounted. */
   enabled: zodBooleanWithTransforms().default(false),
+  /**
+   * Email of the user INBOUND calls run as. A caller is an anonymous member of the public, so the call needs a
+   * principal to create its agent session and run the agent. Point this at a DEDICATED LEAST-PRIVILEGE user.
+   * There is deliberately no fallback: if unset, unknown, inactive, or the system user, inbound calls are
+   * rejected with a polite message and the rejection is logged. Applies to Twilio, Vonage and RingCentral.
+   */
+  inboundRunAsUserEmail: z.string().optional(),
+  /** Maximum length of one phone call, in seconds. The bridge session is stopped (and the call hung up) at the cap. Defaults to 1800. */
+  maxCallSeconds: z.coerce.number().int().positive().optional().default(1800),
+  /**
+   * Most phone calls (every carrier together, both directions) the server carries at once. Past it an inbound
+   * caller hears "all agents are busy" and an outbound request is refused. Keep it at or below the realtime
+   * model plan's concurrent-session limit. Defaults to 25.
+   */
+  maxConcurrentCalls: z.coerce.number().int().positive().optional().default(25),
+  /** Outbound destination policy + per-user rate limit (see {@link outboundTelephonySchema}). */
+  outbound: outboundTelephonySchema.optional().default({}),
+  /**
+   * The places the agent may hand a live call to, by name (the agent names a target, never a number, an email or an agent
+   * id). `kind` is `number` (the default; a phone number), `user` (a person at an Explorer console, who may accept or
+   * decline; `userEmail`, optional `fallbackNumber` the room dials if they do not take it) or `agent` (another MJ AI agent,
+   * by `agentName`). `user` and `agent` targets work on calls that live in a LiveKit room; a carrier call can only transfer to
+   * a `number`. Every number is validated at startup against the outbound allow/block lists; an invalid entry is dropped
+   * and logged. Empty (the default) means the agent cannot hand calls over at all.
+   */
+  transferTargets: z
+    .array(
+      z.object({
+        name: z.string().min(1),
+        kind: z.enum(['number', 'user', 'agent']).optional(),
+        number: z.string().optional(),
+        userEmail: z.string().optional(),
+        fallbackNumber: z.string().optional(),
+        agentName: z.string().optional(),
+        description: z.string().optional(),
+      }),
+    )
+    .optional()
+    .default([]),
   /** Twilio Programmable Voice + Media Streams binding. */
   twilio: twilioTelephonySchema.optional(),
   /** Vonage Voice + WebSocket-media binding. */
   vonage: vonageTelephonySchema.optional(),
   /** RingCentral Call Control + media-stream binding. */
   ringcentral: ringcentralTelephonySchema.optional(),
+  /** LiveKit SIP binding: phone calls carried by a SIP trunk, landed in a LiveKit room. */
+  livekitSip: livekitSipTelephonySchema.optional(),
   /** Microsoft Teams meetings (Graph cloud-communications + ACS application-hosted media) binding. */
   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({}),
 }).passthrough();
 
 const configInfoSchema = z.object({
@@ -582,6 +826,7 @@ const configInfoSchema = z.object({
   componentRegistries: z.array(componentRegistrySchema).optional(),
   scheduledJobs: scheduledJobsSchema.optional().default({}),
   integrationSyncWorker: integrationSyncWorkerSchema.optional().default({}),
+  workQueue: WorkQueueSchema.optional().default({}),
   telemetry: telemetrySchema.optional().default({}),
   queryDialects: queryDialectSchema.optional().default({}),
   multiTenancy: multiTenancySchema.optional().default({}),
@@ -629,9 +874,11 @@ 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>;
+export type LiveKitSipTelephonyConfig = z.infer<typeof livekitSipTelephonySchema>;
 export type TeamsMeetingsConfig = z.infer<typeof teamsMeetingsSchema>;
 export type DatabaseSettingsInfo = z.infer<typeof databaseSettingsInfoSchema>;
 export type ViewingSystemSettingsInfo = z.infer<typeof viewingSystemInfoSchema>;
@@ -642,6 +889,7 @@ export type AuthProviderConfig = z.infer<typeof authProviderSchema>;
 export type ComponentRegistryConfig = z.infer<typeof componentRegistrySchema>;
 export type ScheduledJobsConfig = z.infer<typeof scheduledJobsSchema>;
 export type IntegrationSyncWorkerConfig = z.infer<typeof integrationSyncWorkerSchema>;
+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>;
@@ -775,6 +1023,9 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
     maxConcurrentRuns: 3
   },
 
+  // Work queue host defaults (off until an instance opts in)
+  workQueue: DEFAULT_WORK_QUEUE_CONFIG,
+
   // Realtime WebRTC SDP broker defaults (on by default; can be disabled via MJ_REALTIME_ENABLED=false)
   realtime: {
     enabled: RealtimeEnabledDefault(process.env.MJ_REALTIME_ENABLED),
@@ -799,6 +1050,7 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
     defaultTTLSeconds: 0,
     evictionSweepIntervalSeconds: 300,
     verboseLogging: false,
+    engineSweepIntervalSeconds: 300,
   },
 
   // Logging settings defaults — variables logging is always off unless the operator

package/src/context.ts

@@ -10,7 +10,8 @@ import { CloneUserForSessionContext } from './auth/sessionUserClone.js';
 import { GetAPIKeyActingContextResolver } from './auth/actingContextResolver.js';
 import { TokenExpiredError, AuthProviderFactory } from '@memberjunction/auth-providers';
 import { AuthCache } from './cache.js';
-import { userEmailMap, apiKey, mj_core_schema } from './config.js';
+import { userEmailMap, apiKey, mj_core_schema, configInfo } from './config.js';
+import { BuildPostgreSQLConnectionConfig, PostgreSQLReadOnlyPool, ResolvePostgreSQLEndpoint, ResolvePostgreSQLReadOnlyCredentials } from './postgresqlPoolSettings.js';
 import { BuildBoundaryLogPayload } from './logging/boundaryLogPayload.js';
 import { StartupLogger } from './logging/StartupLogger.js';
 import { DataSourceInfo, UserPayload } from './types.js';
@@ -780,6 +781,7 @@ export const ContextFunction =
       dataSources,
       userPayload,
       providers,
+      ClientIp: expressReq.ip,
     };
   };
 
@@ -810,36 +812,35 @@ async function createPerRequestProviders(
     { provider: p, type: 'Read-Write' }
   ];
 
-  if (isPostgres) {
-    const rp = await tryCreateReadOnlyPostgresProvider();
-    if (rp) {
-      providers.push({ provider: rp, type: 'Read-Only' });
-    }
-  } else {
-    const rp = await tryCreateReadOnlyProvider(dataSources);
-    if (rp) {
-      providers.push({ provider: rp, type: 'Read-Only' });
-    }
+  const rp = await CreateReadOnlyProvider(dataSources);
+  if (rp) {
+    providers.push({ provider: rp, type: 'Read-Only' });
   }
 
   return providers;
 }
 
+/**
+ * Opens a provider on the read-only database login, for the current platform. Resolves null when no
+ * read-only login is configured; it never falls back to the read-write pool.
+ * @param dataSources the data sources MJAPI opened at startup
+ */
+export async function CreateReadOnlyProvider(dataSources: DataSourceInfo[]): Promise<DatabaseProviderBase | null> {
+  return resolveDbPlatformFromEnv() === 'postgresql'
+    ? tryCreateReadOnlyPostgresProvider()
+    : tryCreateReadOnlyProvider(dataSources);
+}
+
 /**
  * Creates a PostgreSQL per-request provider, sharing the connection pool
  * from the primary provider to avoid pool exhaustion.
  */
 async function createPostgresProvider(): Promise<DatabaseProviderBase> {
   const { PostgreSQLDataProvider, PostgreSQLProviderConfigData } = await import('@memberjunction/postgresql-dataprovider');
-  const pgHost = process.env.PG_HOST || process.env.DB_HOST || 'localhost';
-  const pgPort = parseInt(process.env.PG_PORT || process.env.DB_PORT || '5432', 10);
-  const pgUser = process.env.PG_USERNAME || process.env.DB_USERNAME || 'postgres';
-  const pgPass = process.env.PG_PASSWORD || process.env.DB_PASSWORD || '';
-  const pgDatabase = process.env.PG_DATABASE || process.env.DB_DATABASE || '';
 
   const pgProvider = new PostgreSQLDataProvider();
   const pgConfig = new PostgreSQLProviderConfigData(
-    { Host: pgHost, Port: pgPort, Database: pgDatabase, User: pgUser, Password: pgPass },
+    BuildPostgreSQLConnectionConfig(ResolvePostgreSQLEndpoint(), configInfo.databaseSettings, 'api'),
     mj_core_schema,
     0,
     undefined,
@@ -859,39 +860,30 @@ async function createPostgresProvider(): Promise<DatabaseProviderBase> {
 }
 
 /**
- * Attempts to create a read-only PostgreSQL provider using DB_READ_ONLY_USERNAME/PASSWORD.
- * Shares the connection pool from the primary provider. Returns null if no read-only credentials are configured.
+ * Creates a read-only PostgreSQL per-request provider on the read-only pool MJAPI opened at
+ * startup with the read-only login. Returns null when no read-only login is configured, so the
+ * caller never falls back to the read-write pool.
  */
 async function tryCreateReadOnlyPostgresProvider(): Promise<DatabaseProviderBase | null> {
-  const roUser = process.env.PG_READ_ONLY_USERNAME || process.env.DB_READ_ONLY_USERNAME;
-  const roPass = process.env.PG_READ_ONLY_PASSWORD || process.env.DB_READ_ONLY_PASSWORD;
-  if (!roUser || !roPass) {
+  const readOnlyPool = PostgreSQLReadOnlyPool.Instance.Pool;
+  const credentials = ResolvePostgreSQLReadOnlyCredentials(configInfo);
+  if (!readOnlyPool || !credentials) {
     return null;
   }
 
   try {
     const { PostgreSQLDataProvider, PostgreSQLProviderConfigData } = await import('@memberjunction/postgresql-dataprovider');
-    const pgHost = process.env.PG_HOST || process.env.DB_HOST || 'localhost';
-    const pgPort = parseInt(process.env.PG_PORT || process.env.DB_PORT || '5432', 10);
-    const pgDatabase = process.env.PG_DATABASE || process.env.DB_DATABASE || '';
 
     const roProvider = new PostgreSQLDataProvider();
     const roConfig = new PostgreSQLProviderConfigData(
-      { Host: pgHost, Port: pgPort, Database: pgDatabase, User: roUser, Password: roPass },
+      BuildPostgreSQLConnectionConfig({ ...ResolvePostgreSQLEndpoint(), ...credentials }, configInfo.databaseSettings, 'read-only'),
       mj_core_schema,
       0,
       undefined,
       undefined,
       false,
     );
-
-    const primaryProvider = Metadata.Provider as unknown as { DatabaseConnection?: import('pg').Pool }; // global-provider-ok: bootstrap (share primary provider's PG pool with the read-only provider)
-    if (primaryProvider?.DatabaseConnection) {
-      await roProvider.ConfigWithSharedPool(roConfig, primaryProvider.DatabaseConnection);
-    } else {
-      await roProvider.Config(roConfig);
-    }
-
+    await roProvider.ConfigWithSharedPool(roConfig, readOnlyPool);
     return roProvider;
   } catch (_err) {
     return null;