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

package/src/agentSessions/SessionManager.ts

@@ -7,27 +7,18 @@ 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';
+import { RecordingAssemblyScheduler } from '../realtimeSessions/RecordingAssemblyScheduler.js';
 
 /** Entity names — centralised so the `MJ:`-prefix convention is applied in exactly one place. */
 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 +45,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 +135,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
@@ -201,6 +213,13 @@ export class SessionManager {
         if (!closed) {
             return false;
         }
+        if (session.RecordingStartedAt) {
+            // A client-direct recording is assembled only after the grace period while its call is open
+            // (a hidden tab must not rewrite recording.wav on every switch; see RealtimeRecordingHandler).
+            // The call has ended now, so assemble it right away. The ledger's claim arbitrates instances,
+            // and a recording with nothing to assemble (none, or server-bridged) is simply not claimable.
+            RecordingAssemblyScheduler.Instance.ScheduleAssembly(agentSessionID, 0, false);
+        }
         await this.disconnectChannels(agentSessionID, contextUser, provider, preloadedChannels);
         await this.finalizeObservabilityRuns(session, contextUser, provider);
         await this.notifyChannelPluginsSessionClosed(agentSessionID, closeReason);
@@ -211,6 +230,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 +341,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 +350,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 +359,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`
@@ -438,7 +538,11 @@ export class SessionManager {
         return session;
     }
 
-    /** Loads a session entity by ID, returning null when it cannot be loaded. */
+    /**
+     * Loads a session entity by ID, returning null when it cannot be loaded. The server entity
+     * (`MJAIAgentSessionEntityServer`) keeps the lifecycle saves that follow from writing back the
+     * recording ledger's columns (#5294).
+     */
     private async loadSession(
         agentSessionID: string,
         contextUser: UserInfo,
@@ -565,6 +669,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/apiRoot.ts

@@ -0,0 +1,78 @@
+/**
+ * MJAPI's base path: the single prefix every route MJAPI serves is mounted under (MJ #5674).
+ *
+ * MJAPI does not know where a proxy exposes it. Behind a proxy that forwards a prefix WITHOUT stripping it
+ * (CloudFront `/api/*` → MJAPI), MJAPI must listen under that prefix, so the host sets
+ * `MJAPI_BASE_PATH=/api`. Behind a stripping proxy, or with no proxy, it stays `/`. Every mount and every
+ * URL handed to a browser, an email or a webhook provider goes through {@link ApiRoute}, so one setting moves
+ * them all. CI enforces this (`check:api-root` and `__tests__/apiRootBoot.test.ts`).
+ *
+ * `GRAPHQL_ROOT_PATH` is a separate thing: only where Apollo listens. Do not derive routes from it.
+ *
+ * At the default base path `/` every value here is byte-identical to the root-mounted paths MJAPI always used.
+ */
+import { TrimTrailingSlashes } from '@memberjunction/global';
+import { configInfo } from './config.js';
+
+/** Options for {@link ApiRoute}. */
+export interface ApiRouteOptions {
+    /** Return the public absolute URL (`MJAPI_PUBLIC_URL` + subpath) instead of the server mount path. */
+    absolute?: boolean; // case-violation-ok-legacy-back-compat: the `{ absolute: true }` option shape is the documented #5674 contract
+}
+
+/**
+ * Normalizes a base-path value to a prefix with no trailing slash: `''` for `/`, `'/api'` for `/api/` or
+ * `/api`. Throws on a value that does not start with `/`, since Express would mount it nowhere.
+ */
+export function NormalizeApiRootPath(rootPath: string | undefined): string {
+    const trimmed = (rootPath ?? '').trim();
+    if (trimmed && !trimmed.startsWith('/')) {
+        throw new Error(`MJAPI_BASE_PATH must start with '/', got '${trimmed}'`);
+    }
+    return TrimTrailingSlashes(trimmed);
+}
+
+function assertSubpath(subpath: string): void {
+    if (typeof subpath !== 'string' || !subpath.startsWith('/')) {
+        throw new Error(`ApiRoute subpath must start with '/', got '${String(subpath)}'`);
+    }
+}
+
+/** Joins a base path and a subpath relative to it. Pure, so tests can drive any base path. */
+export function JoinApiRoute(apiRootPath: string, subpath: string): string {
+    assertSubpath(subpath);
+    return `${NormalizeApiRootPath(apiRootPath)}${subpath}`;
+}
+
+/** The running server's base path (`MJAPI_BASE_PATH`, no trailing slash; `''` at `/`). */
+export function ApiRootPath(): string {
+    return NormalizeApiRootPath(configInfo.apiBasePath);
+}
+
+/**
+ * The server's configured public URL, derived exactly as it always has been: `MJAPI_PUBLIC_URL`, else
+ * `baseUrl:graphqlPort` + `graphqlRootPath`. Unchanged and untrimmed on purpose: it is the magic-link JWT
+ * issuer and the `publicUrl` handed to OAuth and server extensions, and changing it would invalidate issued
+ * tokens. Build URLs with `ApiRoute(subpath, { absolute: true })`, not from this.
+ */
+export function ConfiguredPublicUrl(): string {
+    return configInfo.publicUrl || `${configInfo.baseUrl}:${configInfo.graphqlPort}${configInfo.graphqlRootPath || ''}`;
+}
+
+/**
+ * The path (or, with `{ absolute: true }`, the public URL) of a route under MJAPI's base path.
+ *
+ * `subpath` is relative to the base path and must start with `/`.
+ * - `ApiRoute('/media')` → `/media` at base `/`, `/api/media` at `MJAPI_BASE_PATH=/api`.
+ * - `ApiRoute('/media/abc', { absolute: true })` → `${MJAPI_PUBLIC_URL}/media/abc`. `MJAPI_PUBLIC_URL` is
+ *   wherever the world reaches MJAPI (prefix included), so the base path is never added to it. Without it,
+ *   the local fallback is `baseUrl:graphqlPort` + the base path.
+ */
+export function ApiRoute(subpath: string, options?: ApiRouteOptions): string {
+    if (!options?.absolute) {
+        return JoinApiRoute(ApiRootPath(), subpath);
+    }
+    assertSubpath(subpath);
+    const base = configInfo.publicUrl || `${configInfo.baseUrl}:${configInfo.graphqlPort}${ApiRootPath()}`;
+    return `${TrimTrailingSlashes(base)}${subpath}`;
+}

package/src/auth/AuthProviderCatalogRouter.ts

@@ -12,6 +12,7 @@ import { Router, type Request, type Response } from 'express';
 import { rateLimit } from 'express-rate-limit';
 import { LogError, type PublicAuthProviderCatalog } from '@memberjunction/core';
 import { AuthProviderEngine } from './AuthProviderEngine.js';
+import { EMPTY_PUBLIC_LOGIN_SCREEN, LoginScreenEngine } from './LoginScreenEngine.js';
 
 /** Mount path for the public catalog router. */
 export const AUTH_CATALOG_MOUNT_PATH = '/auth';
@@ -72,6 +73,31 @@ export function CreateAuthProviderCatalogRouter(): Router {
     }
   });
 
+  /**
+   * `GET /auth/login-screen`: the default theme's PUBLISHED sign-in page, logos and seeds, for the login
+   * screen to draw before anyone signs in. Its own rate-limit budget (a 429 must answer in this route's
+   * shape), the catalog's cache window, and the same failure rule: empty, never an error.
+   */
+  const loginScreenLimiter = rateLimit({
+    windowMs: DEFAULT_RATE_LIMIT_WINDOW_MS,
+    limit: DEFAULT_RATE_LIMIT_MAX,
+    standardHeaders: 'draft-7',
+    legacyHeaders: false,
+    message: EMPTY_PUBLIC_LOGIN_SCREEN
+  });
+
+  router.get('/login-screen', loginScreenLimiter, (_req: Request, res: Response) => {
+    try {
+      const body = LoginScreenEngine.Instance.GetPublicLoginScreen();
+      res.set('Cache-Control', `public, max-age=${CACHE_MAX_AGE_SECONDS}`);
+      res.status(200).json(body);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      LogError(`[Auth] Failed to serve the public login screen: ${message}`);
+      res.status(200).json(EMPTY_PUBLIC_LOGIN_SCREEN);
+    }
+  });
+
   return router;
 }
 

package/src/auth/LoginScreenEngine.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview Caches the default theme for the public login-screen route.
+ *
+ * @module @memberjunction/server/auth
+ */
+import { BaseEngine, BaseEnginePropertyConfig, RegisterForStartup, UserInfo, type IMetadataProvider } from '@memberjunction/core';
+import { MJThemeEntity } from '@memberjunction/core-entities';
+import { PublicLoginScreenFromTheme, type PublicLoginScreen } from '@memberjunction/theme-engine';
+
+/** What the route serves when there is no default theme, or it cannot be read. */
+export const EMPTY_PUBLIC_LOGIN_SCREEN: Readonly<PublicLoginScreen> = { ThemeName: null, Design: null, Seeds: null, Logos: {} };
+
+/**
+ * Holds the default Active theme, so `GET /auth/login-screen` answers every anonymous page load from
+ * memory. Saving a theme refreshes it, so a publish in Login Studio reaches the login screen without a
+ * restart. Severity `warn`: a failed load must not stop the server; the route then serves the stock page.
+ */
+@RegisterForStartup({
+  priority: 20,
+  severity: 'warn',
+  deferred: false,
+  description: 'Caches the default theme that GET /auth/login-screen serves to the login screen'
+})
+export class LoginScreenEngine extends BaseEngine<LoginScreenEngine> {
+  private _defaultThemes: MJThemeEntity[] = [];
+
+  public static get Instance(): LoginScreenEngine {
+    return super.getInstance<LoginScreenEngine>();
+  }
+
+  public async Config(forceRefresh?: boolean, contextUser?: UserInfo, provider?: IMetadataProvider): Promise<void> {
+    const configs: Partial<BaseEnginePropertyConfig>[] = [
+      {
+        PropertyName: '_defaultThemes',
+        EntityName: 'MJ: Themes',
+        // One default is enforced by the app, not the schema; the most recently changed one wins (as in Login Studio).
+        Filter: `IsDefault = 1 AND Status = 'Active'`,
+        OrderBy: '__mj_UpdatedAt DESC',
+        CacheLocal: true
+      }
+    ];
+    await this.Load(configs, provider, forceRefresh, contextUser);
+  }
+
+  /** The default theme's public projection: its PUBLISHED design (never the draft), seeds and logos made safe. */
+  public GetPublicLoginScreen(): PublicLoginScreen {
+    const theme = this.GetConfigData<MJThemeEntity>('_defaultThemes')[0];
+    return theme ? PublicLoginScreenFromTheme(theme) : EMPTY_PUBLIC_LOGIN_SCREEN;
+  }
+}