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

package/src/agentSessions/SessionManager.ts

@@ -7,8 +7,10 @@ import {
 } from '@memberjunction/core-entities';
 import { AIAgentPermissionHelper } from '@memberjunction/ai-engine-base';
 import { RealtimeClientSessionService, RealtimeChannelServerHost } from '@memberjunction/ai-agents';
+import type { BridgeDisconnectReason } from '@memberjunction/ai-bridge-base';
 import { GetHostInstanceID } from './HostInstance.js';
 import { WriteReturningVisitorRecap } from './ReturningVisitorRecap.js';
+import { SessionRunIDVerifier, SessionRunIDs } from './SessionRunIDVerifier.js';
 import { ResolveScopedAnonymousRunUser } from '../realtimeWidget/widgetGuestElevation.js';
 
 /** Entity names — centralised so the `MJ:`-prefix convention is applied in exactly one place. */
@@ -16,18 +18,6 @@ const SESSION_ENTITY = 'MJ: AI Agent Sessions';
 const SESSION_CHANNEL_ENTITY = 'MJ: AI Agent Session Channels';
 const CONVERSATION_ENTITY = 'MJ: Conversations';
 
-/**
- * Shape of the observability run ids a realtime voice session persists in `AIAgentSession.Config_`.
- * Read on {@link SessionManager.CloseSession} to finalize the co-agent runs. All fields optional —
- * a non-voice session (or one whose run creation was skipped) carries none of them.
- */
-interface SessionRunConfig {
-    coAgentRunID?: string;
-    promptRunID?: string;
-    /** The co-agent run's single system-prompt `MJ: AI Agent Run Steps` row id (its Timeline entry). */
-    coAgentRunStepID?: string;
-}
-
 /**
  * Inputs for {@link SessionManager.CreateSession}. `conversationID`/`lastSessionID`/`config`
  * are optional — when no `conversationID` is supplied a fresh Conversation is created and linked.
@@ -54,6 +44,24 @@ export interface CreateSessionInput {
  */
 export type SessionCloseReason = 'Explicit' | 'Janitor' | 'Shutdown' | 'Error';
 
+/**
+ * The {@link SessionCloseReason} for a session whose bridged agent has left (see
+ * {@link SessionManager.CloseSessionForEndedBridge}). The bridge's reason carries over where the session has the same one;
+ * `HostEnded` (everyone left the room, the call hung up) closes it as `Explicit`, people ending it, as phone calls close
+ * theirs.
+ */
+function sessionCloseReasonForBridgeEnd(reason: BridgeDisconnectReason): SessionCloseReason {
+    switch (reason) {
+        case 'Error':
+        case 'Janitor':
+        case 'Shutdown':
+            return reason;
+        case 'Explicit':
+        case 'HostEnded':
+            return 'Explicit';
+    }
+}
+
 /**
  * Thrown by {@link SessionManager.CreateSession} when the caller lacks `CanRun` on the target
  * agent. No session row is created — denial happens before any write. Distinct error type so the
@@ -126,6 +134,9 @@ export class SessionManager {
      */
     private readonly realtimeClientSessionService: RealtimeClientSessionService;
 
+    /** Checks the run ids read from a session's owner-editable `Config_` before they are used. */
+    private readonly runIDVerifier = new SessionRunIDVerifier();
+
     /**
      * @param realtimeClientSessionService The shared {@link RealtimeClientSessionService} instance to
      *   finalize observability runs through. Pass the SAME instance your resolver/service used to create
@@ -211,6 +222,68 @@ export class SessionManager {
         return true;
     }
 
+    /**
+     * Closes a session that was created for one bridged agent (a bot in a meeting room) once that agent's bridge has
+     * ended, whatever ended it: the agent was stopped, the meeting was ended, everyone left, the model session was lost.
+     * Without this the session stays `Active` until the janitor's staleness sweep closes it, 15 minutes or more later.
+     *
+     * The close is {@link CloseSession}, the one the janitor runs, with the bridge's reason: `Explicit` for a stop, an
+     * ended meeting or an emptied room (`HostEnded`), otherwise the bridge's own (`Error`, `Janitor`, `Shutdown`). A
+     * session already closed (by the janitor, or by its user) keeps its reason.
+     *
+     * Never throws: it runs as the bridge's end-of-session bookkeeping. A failure is logged and leaves the session to the
+     * janitor, as before.
+     *
+     * @param agentSessionID The session created for the bridged agent.
+     * @param reason Why the bridge ended.
+     * @param contextUser The user the session was created for.
+     * @param provider The metadata provider the session was created through.
+     * @returns `true` when the session is (or already was) closed.
+     */
+    public async CloseSessionForEndedBridge(
+        agentSessionID: string,
+        reason: BridgeDisconnectReason,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<boolean> {
+        try {
+            return await this.CloseSession(agentSessionID, contextUser, provider, sessionCloseReasonForBridgeEnd(reason));
+        } catch (e) {
+            LogError(
+                `SessionManager.CloseSessionForEndedBridge could not close agent session ${agentSessionID} after its bridge ended ` +
+                    `(${reason}); the janitor will: ${e instanceof Error ? e.message : String(e)}`,
+            );
+            return false;
+        }
+    }
+
+    /**
+     * Closes a session that was created for one agent's time in a room when that agent failed to start: its model session
+     * could not open, the bot's token could not be minted, the bridge did not start. The agent never joined, so no
+     * end-of-session hook will close the session; without this it stays `Active` until the janitor's staleness sweep.
+     *
+     * The close is {@link CloseSession} with reason `Error`. A session already closed keeps its reason.
+     *
+     * Never throws: it runs while the caller handles the failed start, whose error is the one the caller reports. A failure
+     * is logged and leaves the session to the janitor.
+     *
+     * @param agentSessionID The session created for the agent.
+     * @param contextUser The user the session was created for.
+     * @param provider The metadata provider the session was created through.
+     * @returns `true` when the session is (or already was) closed.
+     */
+    public async CloseSessionForFailedStart(agentSessionID: string, contextUser: UserInfo, provider: IMetadataProvider): Promise<boolean> {
+        try {
+            return await this.CloseSession(agentSessionID, contextUser, provider, 'Error');
+        } catch (e) {
+            LogError(
+                `SessionManager.CloseSessionForFailedStart could not close agent session ${agentSessionID} after its agent failed ` +
+                    `to start; the janitor will: ${e instanceof Error ? e.message : String(e)}`,
+            );
+            return false;
+        }
+    }
+
     /**
      * Notifies the server-side channel-plugin host that a session started, so it can resolve the
      * ACTIVE `MJ: AI Agent Channels` rows' `ServerPluginClass` plugins (one fresh instance per
@@ -260,7 +333,8 @@ export class SessionManager {
 
     /**
      * Finalizes the co-agent observability runs a realtime voice session stored in its `Config_`
-     * (see `RealtimeClientSessionResolver`). No-op when the config carries no run ids. Tolerant: a
+     * (see `RealtimeClientSessionResolver`). Only run ids that are records of the session are
+     * finalized, because the owner can edit `Config_`. No-op when none remain. Tolerant: a
      * malformed config or a finalize failure is swallowed so it can never break session close.
      */
     private async finalizeObservabilityRuns(
@@ -268,8 +342,8 @@ export class SessionManager {
         contextUser: UserInfo,
         provider: IMetadataProvider,
     ): Promise<void> {
-        const config = this.parseSessionRunConfig(session.Config_);
-        if (!config.coAgentRunID && !config.promptRunID && !config.coAgentRunStepID) {
+        const claimed = this.parseSessionRunConfig(session.Config_);
+        if (!claimed.CoAgentRunID && !claimed.PromptRunID && !claimed.CoAgentRunStepID) {
             return;
         }
         try {
@@ -277,36 +351,54 @@ export class SessionManager {
             // for a scoped anonymous session, so an owner-initiated (or error) close must finalize
             // under it too — the caller's role holds no grants on the AI run entities. Janitor and
             // shutdown sweeps already close as the system user and pass through unchanged.
+            const runUser = ResolveScopedAnonymousRunUser(contextUser);
+            const runIDs = await this.runIDVerifier.Verify(session.ID, claimed, runUser, provider);
+            if (!runIDs.CoAgentRunID && !runIDs.PromptRunID && !runIDs.CoAgentRunStepID) {
+                return;
+            }
             await this.realtimeClientSessionService.FinalizeCoAgentRun(
-                config.coAgentRunID ?? null,
-                config.promptRunID ?? null,
-                ResolveScopedAnonymousRunUser(contextUser),
+                runIDs.CoAgentRunID ?? null,
+                runIDs.PromptRunID ?? null,
+                runUser,
                 provider,
                 true,
-                config.coAgentRunStepID ?? null,
+                runIDs.CoAgentRunStepID ?? null,
             );
         } catch (e) {
             LogError(`SessionManager.finalizeObservabilityRuns failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
 
-    /** Parses the session's `Config_` for observability run ids; returns an empty config on any error. */
-    private parseSessionRunConfig(raw: string | null): SessionRunConfig {
+    /** Parses the session's `Config_` for observability run ids; returns none on any error. */
+    private parseSessionRunConfig(raw: string | null): SessionRunIDs {
         if (!raw) {
             return {};
         }
         try {
-            const parsed = JSON.parse(raw) as Partial<SessionRunConfig>;
+            const parsed = JSON.parse(raw) as { coAgentRunID?: unknown; promptRunID?: unknown; coAgentRunStepID?: unknown };
             return {
-                coAgentRunID: typeof parsed.coAgentRunID === 'string' ? parsed.coAgentRunID : undefined,
-                promptRunID: typeof parsed.promptRunID === 'string' ? parsed.promptRunID : undefined,
-                coAgentRunStepID: typeof parsed.coAgentRunStepID === 'string' ? parsed.coAgentRunStepID : undefined,
+                CoAgentRunID: typeof parsed.coAgentRunID === 'string' ? parsed.coAgentRunID : undefined,
+                PromptRunID: typeof parsed.promptRunID === 'string' ? parsed.promptRunID : undefined,
+                CoAgentRunStepID: typeof parsed.coAgentRunStepID === 'string' ? parsed.coAgentRunStepID : undefined,
             };
         } catch {
             return {};
         }
     }
 
+    /** The session's co-agent run id from its `Config_`, when it is a run of the session. */
+    private async verifiedCoAgentRunID(
+        session: MJAIAgentSessionEntity,
+        runUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<string | undefined> {
+        const { CoAgentRunID } = this.parseSessionRunConfig(session.Config_);
+        if (!CoAgentRunID) {
+            return undefined;
+        }
+        return (await this.runIDVerifier.Verify(session.ID, { CoAgentRunID }, runUser, provider)).CoAgentRunID;
+    }
+
     /**
      * Record activity on a session. Coalesces persisted writes so at most one `LastActiveAt` update
      * lands per session per {@link HEARTBEAT_MIN_WRITE_INTERVAL_MS}; intervening calls return `true`
@@ -565,6 +657,14 @@ export class SessionManager {
         const saved = await this.saveOrLog(session, 'Heartbeat');
         if (saved) {
             this.heartbeatLastWrite.Set(agentSessionID.toLowerCase(), Date.now());
+            // A live session keeps its co-agent run live too — on whichever instance gets its heartbeats —
+            // or the agent-run watchdog force-fails the run mid-call. Same elevation as the finalize path.
+            const runUser = ResolveScopedAnonymousRunUser(contextUser);
+            this.realtimeClientSessionService.KeepCoAgentRunAlive(
+                await this.verifiedCoAgentRunID(session, runUser, provider),
+                provider,
+                runUser,
+            );
         }
         return saved;
     }

package/src/agentSessions/SessionRunIDVerifier.ts

@@ -0,0 +1,171 @@
+/**
+ * @fileoverview Checks the run ids a realtime session keeps in its `Config` before server code
+ * acts on them.
+ *
+ * @module @memberjunction/server
+ */
+import { IMetadataProvider, LogError, RunView, RunViewParams, UserInfo } from '@memberjunction/core';
+import { EscapeSQLString, IsValidUUID, UUIDsEqual } from '@memberjunction/global';
+import { UserCache } from '@memberjunction/generic-database-provider';
+
+const AGENT_RUN_ENTITY = 'MJ: AI Agent Runs';
+const AGENT_RUN_STEP_ENTITY = 'MJ: AI Agent Run Steps';
+
+/**
+ * The run ids a realtime voice session keeps in its `Config` JSON. Server code reads and writes the
+ * records they point at, often as an elevated user.
+ */
+export interface SessionRunIDs {
+    /** The co-agent observability run (`MJ: AI Agent Runs`). */
+    CoAgentRunID?: string;
+    /** The co-agent prompt run (`MJ: AI Prompt Runs`), linked through the co-agent run's prompt step. */
+    PromptRunID?: string;
+    /** The co-agent run's system-prompt step (`MJ: AI Agent Run Steps`). */
+    CoAgentRunStepID?: string;
+    /** A delegated run (`MJ: AI Agent Runs`) that paused for the user's answer. */
+    PendingFeedbackRunID?: string;
+}
+
+/** A row of the run-step lookup. */
+interface RunStepRow {
+    ID: string;
+    StepType: string;
+    TargetLogID: string | null;
+}
+
+/** A row of either lookup; the run lookup returns only `ID`. */
+type LookupRow = Partial<RunStepRow> & { ID: string };
+
+/**
+ * Keeps the run ids from a session's `Config` that are records of that session.
+ *
+ * The session owner can edit `Config`, so its run ids are claims. A run id is kept when it is the
+ * UUID of an `MJ: AI Agent Runs` row whose `AgentSessionID` is the session. The step id and the
+ * prompt run id are kept when they belong to that co-agent run: the step's `AgentRunID` is the
+ * co-agent run, and the prompt run is the `TargetLogID` of one of its `Prompt` steps.
+ *
+ * The lookups run as the system user when one is cached, else as the acting user. They are pinned
+ * to the session's id and return nothing to the caller, and row-level security can hide a session's
+ * own runs from its owner (a web-widget guest's delegated runs carry no `ConversationID`, which the
+ * guest's run filter keys on).
+ *
+ * Each call reads the database again (`BypassCache`) and keeps no result, because the links can
+ * change after a lookup: a run's `AgentSessionID` and a step's `AgentRunID` and `TargetLogID` are
+ * updatable.
+ */
+export class SessionRunIDVerifier {
+    /**
+     * Returns the subset of `claimed` that belongs to the session now. Never throws: when a lookup
+     * fails, nothing is kept.
+     *
+     * @param sessionID The `MJ: AI Agent Sessions` id the claims were read from. The caller must have
+     *   checked that the session is the caller's own.
+     * @param claimed The run ids read from the session's `Config`.
+     * @param contextUser The acting user; the lookups run as it only when no system user is cached.
+     * @param provider The request-scoped metadata provider.
+     * @returns The claims that are records of the session.
+     */
+    public async Verify(
+        sessionID: string,
+        claimed: SessionRunIDs,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<SessionRunIDs> {
+        const candidates = this.keepUUIDs(claimed);
+        if (!candidates.CoAgentRunID && !candidates.PendingFeedbackRunID) {
+            return {};
+        }
+        return (await this.lookUpOwned(sessionID.trim(), candidates, contextUser, provider)) ?? {};
+    }
+
+    /** Drops every claim that is not a UUID. The prompt run and step need a co-agent run to hang off. */
+    private keepUUIDs(claimed: SessionRunIDs): SessionRunIDs {
+        const coAgentRunID = this.uuidOrUndefined(claimed.CoAgentRunID);
+        return {
+            CoAgentRunID: coAgentRunID,
+            PromptRunID: coAgentRunID ? this.uuidOrUndefined(claimed.PromptRunID) : undefined,
+            CoAgentRunStepID: coAgentRunID ? this.uuidOrUndefined(claimed.CoAgentRunStepID) : undefined,
+            PendingFeedbackRunID: this.uuidOrUndefined(claimed.PendingFeedbackRunID),
+        };
+    }
+
+    private uuidOrUndefined(value: string | undefined): string | undefined {
+        return value && IsValidUUID(value) ? value.trim() : undefined;
+    }
+
+    /** Runs the lookups; `null` when one of them fails. */
+    private async lookUpOwned(
+        sessionID: string,
+        candidates: SessionRunIDs,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<SessionRunIDs | null> {
+        const stepsQuery = this.stepsQuery(candidates);
+        const queries = stepsQuery ? [this.runsQuery(sessionID, candidates), stepsQuery] : [this.runsQuery(sessionID, candidates)];
+        try {
+            const lookupUser = UserCache.Instance.GetSystemUser() ?? contextUser;
+            const [runs, steps] = await RunView.FromMetadataProvider(provider).RunViews<LookupRow>(queries, lookupUser);
+            const failed = [runs, steps].find((result) => result && !result.Success);
+            if (!runs || failed) {
+                LogError(`SessionRunIDVerifier: run lookup failed for session ${sessionID}: ${failed?.ErrorMessage ?? 'no result'}`);
+                return null;
+            }
+            return this.pickOwned(candidates, runs.Results, steps?.Results ?? []);
+        } catch (error) {
+            LogError(`SessionRunIDVerifier: run lookup failed for session ${sessionID}: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+
+    /** The claimed runs that carry this session's id. */
+    private runsQuery(sessionID: string, candidates: SessionRunIDs): RunViewParams {
+        const ids = [candidates.CoAgentRunID, candidates.PendingFeedbackRunID]
+            .filter((id): id is string => !!id)
+            .map((id) => `'${EscapeSQLString(id)}'`);
+        return {
+            EntityName: AGENT_RUN_ENTITY,
+            ExtraFilter: `AgentSessionID='${EscapeSQLString(sessionID)}' AND ID IN (${ids.join(', ')})`,
+            Fields: ['ID'],
+            ResultType: 'simple',
+            BypassCache: true,
+        };
+    }
+
+    /** The claimed co-agent run's steps that match the claimed step or prompt run; `null` when neither is claimed. */
+    private stepsQuery(candidates: SessionRunIDs): RunViewParams | null {
+        const matches: string[] = [];
+        if (candidates.CoAgentRunStepID) {
+            matches.push(`ID='${EscapeSQLString(candidates.CoAgentRunStepID)}'`);
+        }
+        if (candidates.PromptRunID) {
+            matches.push(`TargetLogID='${EscapeSQLString(candidates.PromptRunID)}'`);
+        }
+        if (!candidates.CoAgentRunID || matches.length === 0) {
+            return null;
+        }
+        return {
+            EntityName: AGENT_RUN_STEP_ENTITY,
+            ExtraFilter: `AgentRunID='${EscapeSQLString(candidates.CoAgentRunID)}' AND (${matches.join(' OR ')})`,
+            Fields: ['ID', 'StepType', 'TargetLogID'],
+            ResultType: 'simple',
+            BypassCache: true,
+        };
+    }
+
+    private pickOwned(candidates: SessionRunIDs, runs: LookupRow[], steps: LookupRow[]): SessionRunIDs {
+        const isOwnedRun = (id: string | undefined): boolean => !!id && runs.some((row) => UUIDsEqual(row.ID, id));
+        const coAgentRunID = isOwnedRun(candidates.CoAgentRunID) ? candidates.CoAgentRunID : undefined;
+        const ownedSteps = coAgentRunID ? steps : [];
+        const stepID = candidates.CoAgentRunStepID;
+        const promptRunID = candidates.PromptRunID;
+        return {
+            CoAgentRunID: coAgentRunID,
+            CoAgentRunStepID: stepID && ownedSteps.some((row) => UUIDsEqual(row.ID, stepID)) ? stepID : undefined,
+            PromptRunID:
+                promptRunID && ownedSteps.some((row) => row.StepType === 'Prompt' && UUIDsEqual(row.TargetLogID, promptRunID))
+                    ? promptRunID
+                    : undefined,
+            PendingFeedbackRunID: isOwnedRun(candidates.PendingFeedbackRunID) ? candidates.PendingFeedbackRunID : undefined,
+        };
+    }
+}

package/src/agentSessions/index.ts

@@ -2,12 +2,14 @@
  * @fileoverview AI Agent Session lifecycle substrate (server-side, record + janitor layer).
  *
  * Exposes the session-record lifecycle manager, the orphan-reconciliation janitor, and the
- * per-process host identity helpers. The audio/media (WebRTC) transport and the long-lived
- * realtime agent run are deliberately **not** part of this layer — they arrive in P5.
+ * host-instance identity (`hostname:port:pid:bootId`) the janitor matches sessions by, which the
+ * realtime bridge engine is given for its bridge rows too (`BindBridgeEngineHostInstance`). The
+ * audio/media (WebRTC) transport and the long-lived realtime agent run are deliberately **not**
+ * part of this layer — they arrive in P5.
  *
  * @module @memberjunction/server
  */
-import { LoadWhiteboardChannelServer, LoadMeetingControlsChannelServer, LoadMediaChannelServer, LoadClientContextChannelServer } from '@memberjunction/ai-agents';
+import { LoadWhiteboardChannelServer, LoadMeetingControlsChannelServer, LoadMediaChannelServer, LoadClientContextChannelServer, LoadClientOnlyChannelServer, LoadIdentityVerificationChannelServer, LoadInteractiveComponentChannelServer } from '@memberjunction/ai-agents';
 import { LoadRemoteBrowserChannel } from '@memberjunction/remote-browser-server';
 import { LoadSelfHostRemoteBrowser } from '@memberjunction/remote-browser-selfhost';
 import { BindRemoteBrowserGoalEngine } from './remoteBrowserGoalEngine.js';
@@ -19,6 +21,9 @@ LoadWhiteboardChannelServer();
 LoadMeetingControlsChannelServer();
 LoadMediaChannelServer();
 LoadClientContextChannelServer();
+LoadClientOnlyChannelServer();
+LoadIdentityVerificationChannelServer();
+LoadInteractiveComponentChannelServer();
 // Remote Browser native channel (client-direct): the lifecycle-only server channel plugin + the
 // Self-Hosted Chrome backend driver (whose default runner launches a local headless Chromium via
 // Playwright — pulled in transitively through the SelfHost package, documented and acceptable).
@@ -30,5 +35,7 @@ BindRemoteBrowserGoalEngine();
 
 export * from './remoteBrowserGoalEngine.js';
 export * from './HostInstance.js';
+export * from './BridgeHostInstance.js';
 export * from './SessionManager.js';
 export * from './SessionJanitor.js';
+export * from './SessionRunIDVerifier.js';

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

@@ -253,14 +253,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/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