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

package/src/agentSessions/SessionManager.ts

@@ -12,6 +12,7 @@ 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';
@@ -212,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);
@@ -530,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,

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;
+  }
+}

package/src/auth/index.ts

@@ -13,6 +13,7 @@ export * from './APIKeyScopeAuth.js';
 export * from './scopeLimitedPrincipal.js';
 export * from './actingContextResolver.js';
 export * from './AuthProviderEngine.js';
+export * from './LoginScreenEngine.js';
 export * from './AuthProviderCatalogRouter.js';
 export { InitializeAuthProviders, initializeAuthProviders, InitializeAuthProvidersFromMetadata, initializeAuthProvidersFromMetadata, RefreshAuthProviders, refreshAuthProviders, ValidateAuthProvidersRegistered, validateAuthProvidersRegistered } from './initializeProviders.js';
 

package/src/auth/magicLink/MagicLinkRouter.ts

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

package/src/config.ts

@@ -226,10 +226,19 @@ const telemetrySchema = z.object({
   level: z.enum(['minimal', 'standard', 'verbose', 'debug']).optional().default('standard'),
 });
 
-const serverExtensionSchema = z.object({
-  Enabled: z.boolean().default(true),
+/**
+ * A host `mj.config.cjs` `serverExtensions[]` entry. Only `DriverClass` is required: an entry whose
+ * DriverClass an Open App package already publishes is an OVERLAY (MergeServerExtensionConfigs) and
+ * may set just the fields it overrides — `{ DriverClass: 'X', OwnsCORS: false }` — without repeating
+ * `RootPath`. `Enabled` has no schema default for the same reason: a defaulted `true` would silently
+ * re-enable an extension the package ships disabled. Whether the MERGED entry is complete (a valid
+ * `RootPath`; `Enabled` defaults to true) is validated after the merge, by prepareServerExtensionConfigs,
+ * which reports an incomplete host-only entry instead of mounting it.
+ */
+export const ServerExtensionSchema = z.object({
+  Enabled: z.boolean().optional(),
   DriverClass: z.string(),
-  RootPath: z.string(),
+  RootPath: z.string().optional(),
   Settings: z.record(z.unknown()).default({})
 }).passthrough();
 
@@ -238,6 +247,14 @@ const cacheSettingsSchema = z.object({
   maxMemoryMB: z.number().optional().default(150),
   /** Maximum percentage of total cache memory that any single entity can occupy. Default: 50. Set to 0 to disable. */
   maxPercentOfCachePerEntity: z.number().optional().default(50),
+  /**
+   * Ceiling on any ONE cache entry. 'auto' (the default) derives it from maxMemoryMB, so the
+   * largest entity the server caches scales with the memory the cache was given; a number is an
+   * explicit stricter percentage of maxMemoryMB; 0 removes the ceiling. Leave it on 'auto' unless
+   * a specific entry must be kept out of the cache — an entry declined by the ceiling is re-read
+   * from the database on every call, and the server logs which maxMemoryMB would admit it.
+   */
+  maxEntryPercentOfCache: z.union([z.number(), z.literal('auto')]).optional().default('auto'),
   /** Default TTL in seconds. 0 = no TTL, rely on event-based invalidation. Default: 0. */
   defaultTTLSeconds: z.number().optional().default(0),
   /** Interval in seconds for periodic eviction sweep. 0 = disabled. Default: 300 (5 minutes). */
@@ -316,6 +333,15 @@ const loggingSettingsSchema = z.object({
   }).optional().default({}),
 });
 
+const aiPromptRunsSchema = z.object({
+  /**
+   * Server default for which template inputs prompt runs store in AIPromptRun.Messages:
+   * 'None' (key sizes only), 'Referenced' (keys the templates read) or 'Full'.
+   * AIPrompt.TemplateDataCapture and AIPromptParams.TemplateDataCapture override it.
+   */
+  templateDataCapture: z.enum(['None', 'Referenced', 'Full']).optional(),
+});
+
 const corsSchema = z.object({
   /** Allowed origins for CORS. Default ['*'] preserves backward-compatible "allow all" behavior. */
   allowedOrigins: z.array(z.string()).default(['*']),
@@ -810,6 +836,11 @@ const realtimeSchema = z.object({
   enabled: zodBooleanWithTransforms().default(true),
   /** Mid-session identity verification (off by default). */
   identityVerification: identityVerificationSchema.optional().default({}),
+  /**
+   * Seconds a client-direct call's recording waits for missing shards after its terminal signal before it
+   * is assembled anyway as `Partial` (gaps become silence). Defaults to 90.
+   */
+  recordingAssemblyGraceSeconds: z.coerce.number().positive().optional().default(90),
 }).passthrough();
 
 const configInfoSchema = z.object({
@@ -830,9 +861,10 @@ const configInfoSchema = z.object({
   telemetry: telemetrySchema.optional().default({}),
   queryDialects: queryDialectSchema.optional().default({}),
   multiTenancy: multiTenancySchema.optional().default({}),
-  serverExtensions: z.array(serverExtensionSchema).optional().default([]),
+  serverExtensions: z.array(ServerExtensionSchema).optional().default([]),
   cacheSettings: cacheSettingsSchema.optional().default({}),
   loggingSettings: loggingSettingsSchema.optional().default({}),
+  aiPromptRuns: aiPromptRunsSchema.optional(),
   feedbackSettings: feedbackSettingsSchema.optional().default({}),
   cors: corsSchema.optional().default({}),
   rateLimiting: rateLimitSchema.optional().default({}),
@@ -860,6 +892,12 @@ const configInfoSchema = z.object({
   ___codeGenAPIPort: z.coerce.number().optional().default(3999),
   ___codeGenAPISubmissionDelay: z.coerce.number().optional().default(5000),
   graphqlRootPath: z.string().optional().default('/'),
+  /**
+   * Path prefix MJAPI mounts every route it serves under (core routes and server extensions), on its own
+   * listener. `/` unless a proxy forwards a prefix WITHOUT stripping it (e.g. CloudFront `/api/*` → MJAPI):
+   * then set `MJAPI_BASE_PATH=/api`. Independent of `graphqlRootPath`, which is only Apollo's path. MJ #5674.
+   */
+  apiBasePath: z.string().optional().default('/'),
   enableIntrospection: z.coerce.boolean().optional().default(false),
   websiteRunFromPackage: z.coerce.number().optional(),
   userEmailMap: z
@@ -893,9 +931,10 @@ export type { WorkQueueConfig } from './services/workQueueConfig.js';
 export type TelemetryConfig = z.infer<typeof telemetrySchema>;
 export type QueryDialectConfig = z.infer<typeof queryDialectSchema>;
 export type MultiTenancyConfig = z.infer<typeof multiTenancySchema>;
-export type ServerExtensionConfig = z.infer<typeof serverExtensionSchema>;
+export type ServerExtensionConfig = z.infer<typeof ServerExtensionSchema>;
 export type CacheSettingsConfig = z.infer<typeof cacheSettingsSchema>;
 export type LoggingSettingsConfig = z.infer<typeof loggingSettingsSchema>;
+export type AIPromptRunsConfig = z.infer<typeof aiPromptRunsSchema>;
 export type FeedbackGithubSettingsConfig = z.infer<typeof feedbackGithubSettingsSchema>;
 export type FeedbackSettingsConfig = z.infer<typeof feedbackSettingsSchema>;
 export type CorsConfig = z.infer<typeof corsSchema>;
@@ -931,6 +970,7 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
   // GraphQL server settings (environment-driven with defaults)
   graphqlPort: process.env.GRAPHQL_PORT ? parseInt(process.env.GRAPHQL_PORT, 10) : 4000,
   graphqlRootPath: process.env.GRAPHQL_ROOT_PATH ?? '/',
+  apiBasePath: process.env.MJAPI_BASE_PATH ?? '/',
   baseUrl: process.env.GRAPHQL_BASE_URL ?? 'http://localhost',
   publicUrl: process.env.MJAPI_PUBLIC_URL,
   enableIntrospection: process.env.ENABLE_INTROSPECTION === 'true',
@@ -1047,6 +1087,7 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
   cacheSettings: {
     maxMemoryMB: 150,
     maxPercentOfCachePerEntity: 50,
+    maxEntryPercentOfCache: 'auto',
     defaultTTLSeconds: 0,
     evictionSweepIntervalSeconds: 300,
     verboseLogging: false,

package/src/coreRoutes.ts

@@ -0,0 +1,166 @@
+/**
+ * Core HTTP routes MJServer mounts itself, every one under MJAPI's base path (`MJAPI_BASE_PATH`) via {@link ApiRoute}.
+ *
+ * Extracted from `serve()` so `__tests__/apiRootBoot.test.ts` can mount them on a bare Express app with
+ * `MJAPI_BASE_PATH=/api` and check every registered path. `serve()` still decides the ORDER (relative
+ * to compression, the auth middleware, server extensions and Apollo); these functions only mount.
+ *
+ * ALL new custom routes, webhooks and integrations belong in Server Extensions
+ * (guides/SERVER_EXTENSIONS_GUIDE.md), not here.
+ */
+import cors from 'cors';
+import { default as BodyParser } from 'body-parser';
+import type { Application, Router } from 'express';
+import { REALTIME_SDP_EXCHANGE_PATH } from '@memberjunction/ai';
+import type { ServerExtensionLoader } from '@memberjunction/server-extensions-core';
+import { configInfo } from './config.js';
+import { ApiRoute } from './apiRoot.js';
+import { CreateOAuthCallbackHandler } from './rest/OAuthCallbackHandler.js';
+import { CreateSignatureWebhookHandler } from './rest/SignatureWebhookHandler.js';
+import { CreateMediaStreamRouter } from './rest/MediaStreamHandler.js';
+import { CreateRealtimeSdpBrokerRouter } from './rest/RealtimeSdpBrokerHandler.js';
+import { CreateMagicLinkHandler, CreateMagicLinkJwksRouter, RegisterMagicLinkAuthProvider, MAGIC_LINK_MOUNT_PATH } from './auth/magicLink/index.js';
+import { CreateWidgetHandler, WIDGET_MOUNT_PATH } from './realtimeWidget/index.js';
+import { CreateRealtimeVerifyRouter, REALTIME_VERIFY_MOUNT_PATH, RealtimeSessionVerificationService } from './realtimeSessions/index.js';
+import { CreateAuthProviderCatalogRouter, AUTH_CATALOG_MOUNT_PATH } from './auth/AuthProviderCatalogRouter.js';
+import type { StartupLogger } from './logging/StartupLogger.js';
+
+type RouteLog = Pick<StartupLogger, 'LogIf'>;
+
+/** Routers the public mounts create that must be mounted again after the auth middleware. */
+export interface CoreAuthenticatedRouters {
+    OAuth?: Router;
+    MagicLink?: Router;
+    Widget?: Router;
+}
+
+/** `/healthcheck` — mounted first so platform probes never meet the auth middleware. */
+export function MountHealthcheckRoute(app: Application): void {
+    app.get(ApiRoute('/healthcheck'), cors<cors.CorsRequest>(), (_req, res) => {
+        res.status(200).json({ status: 'ok' });
+    });
+}
+
+/**
+ * The unauthenticated core routes (OAuth callback, eSignature webhook, media streaming, realtime SDP
+ * broker, magic-link, widget, realtime verify). Each verifies its own capability (signature, token,
+ * ticket), so they mount BEFORE the auth middleware. Returns the routers that belong after it.
+ */
+export function MountPublicCoreRoutes(app: Application, publicUrl: string, log: RouteLog): CoreAuthenticatedRouters {
+    const routers: CoreAuthenticatedRouters = { OAuth: mountOAuthCallback(app, publicUrl, log) };
+
+    app.use(ApiRoute('/esignature'), cors<cors.CorsRequest>(), CreateSignatureWebhookHandler());
+    log.LogIf('verbose', `[eSignature] Webhook route registered at ${ApiRoute('/esignature')}/webhook/:driverKey`);
+
+    // The `?token=` query param is the capability; an <audio>/<video> element can't send Authorization headers.
+    app.use(ApiRoute('/media'), cors<cors.CorsRequest>(), CreateMediaStreamRouter());
+    log.LogIf('verbose', `[Media] Streaming route registered at ${ApiRoute('/media')}/:fileId`);
+
+    if (configInfo.realtime?.enabled) {
+        app.use(ApiRoute(REALTIME_SDP_EXCHANGE_PATH), cors<cors.CorsRequest>(), CreateRealtimeSdpBrokerRouter());
+        log.LogIf('verbose', `[Realtime] WebRTC SDP broker registered at ${ApiRoute(REALTIME_SDP_EXCHANGE_PATH)}`);
+    }
+
+    routers.MagicLink = mountMagicLinkPublic(app, publicUrl, log);
+    routers.Widget = mountWidgetPublic(app, publicUrl, log);
+    mountRealtimeVerify(app, log);
+    return routers;
+}
+
+function mountOAuthCallback(app: Application, publicUrl: string, log: RouteLog): Router | undefined {
+    if (!publicUrl) {
+        return undefined;
+    }
+    const { callbackRouter, authenticatedRouter } = CreateOAuthCallbackHandler({
+        publicUrl,
+        successRedirectUrl: ApiRoute('/oauth/success', { absolute: true }),
+        errorRedirectUrl: ApiRoute('/oauth/error', { absolute: true }),
+        // Constrains where a caller-supplied frontendReturnUrl may point (open-redirect guard).
+        allowedFrontendOrigins: configInfo.cors?.allowedOrigins ?? ['*'],
+    });
+    // The callback is unauthenticated (called by the external auth server).
+    app.use(ApiRoute('/oauth'), cors<cors.CorsRequest>(), callbackRouter);
+    log.LogIf('verbose', `[OAuth] Callback route registered at ${ApiRoute('/oauth')}/callback`);
+    return authenticatedRouter;
+}
+
+/** Public magic-link router (JWKS + redeem). The invite-creation router is returned for after auth. */
+function mountMagicLinkPublic(app: Application, publicUrl: string, log: RouteLog): Router | undefined {
+    if (!configInfo.magicLink?.enabled) {
+        return undefined;
+    }
+    const { publicRouter, authenticatedRouter } = CreateMagicLinkHandler(publicUrl, configInfo.magicLink);
+    RegisterMagicLinkAuthProvider(publicUrl, configInfo.magicLink);
+    app.use(ApiRoute(MAGIC_LINK_MOUNT_PATH), cors<cors.CorsRequest>(), publicRouter);
+    log.LogIf('verbose', `[MagicLink] Public routes registered at ${ApiRoute(MAGIC_LINK_MOUNT_PATH)}/redeem and ${ApiRoute(MAGIC_LINK_MOUNT_PATH)}/jwks.json`);
+    return authenticatedRouter;
+}
+
+/**
+ * Public widget guest-session mint. It reuses the magic-link RS256 key, so when magic-link itself is
+ * disabled the JWKS is published here — otherwise every guest token fails validation and the widget 401s.
+ */
+function mountWidgetPublic(app: Application, publicUrl: string, log: RouteLog): Router | undefined {
+    if (!configInfo.widget?.enabled) {
+        return undefined;
+    }
+    const { publicRouter, authenticatedRouter } = CreateWidgetHandler(publicUrl, configInfo.widget);
+    app.use(ApiRoute(WIDGET_MOUNT_PATH), cors<cors.CorsRequest>(), publicRouter);
+    if (!configInfo.magicLink?.enabled) {
+        app.use(ApiRoute(MAGIC_LINK_MOUNT_PATH), cors<cors.CorsRequest>(), CreateMagicLinkJwksRouter());
+        log.LogIf('verbose', `[Widget] Published reused signing key at ${ApiRoute(MAGIC_LINK_MOUNT_PATH)}/jwks.json (magic-link flow disabled)`);
+    }
+    log.LogIf('verbose', `[Widget] Public routes registered at ${ApiRoute(WIDGET_MOUNT_PATH)}/session and ${ApiRoute(WIDGET_MOUNT_PATH)}/session/refresh`);
+    return authenticatedRouter;
+}
+
+/**
+ * Realtime identity-verification links. The emailed single-use token is the capability. Mounted only when
+ * verification can send mail AND protect its codes (realtime.identityVerification config).
+ */
+function mountRealtimeVerify(app: Application, log: RouteLog): void {
+    const verification = RealtimeSessionVerificationService.Instance;
+    if (configInfo.realtime?.identityVerification?.enabled && !verification.IsEnabled) {
+        console.warn('[RealtimeVerify] realtime.identityVerification.enabled is true but verification is unavailable: it needs a communicationProvider and an hmacSecret of at least 16 characters.');
+    }
+    if (!verification.IsEnabled) {
+        return;
+    }
+    app.use(ApiRoute(REALTIME_VERIFY_MOUNT_PATH), cors<cors.CorsRequest>(), CreateRealtimeVerifyRouter());
+    log.LogIf('verbose', `[RealtimeVerify] Public routes registered at ${ApiRoute(REALTIME_VERIFY_MOUNT_PATH)}/:token (GET) and ${ApiRoute(REALTIME_VERIFY_MOUNT_PATH)} (POST)`);
+}
+
+/** `/health/extensions` — always mounted; an empty array when no extensions loaded. */
+export function MountExtensionHealthRoute(app: Application, loader: ServerExtensionLoader): void {
+    app.get(ApiRoute('/health/extensions'), async (_req, res) => {
+        const results = await loader.HealthCheckAll();
+        const allHealthy = results.length === 0 || results.every((r) => r.Healthy);
+        res.status(allHealthy ? 200 : 503).json({ extensions: results });
+    });
+}
+
+/**
+ * Public authentication-provider catalog. The browser needs it BEFORE it holds a token; it publishes only
+ * the non-secret allow-list (AuthProviderEngine.GetPublicCatalog).
+ */
+export function MountAuthCatalogRoute(app: Application, log: RouteLog): void {
+    app.use(ApiRoute(AUTH_CATALOG_MOUNT_PATH), cors<cors.CorsRequest>(), CreateAuthProviderCatalogRouter());
+    log.LogIf('verbose', `[Auth] Public provider catalog and login screen registered at ${ApiRoute(AUTH_CATALOG_MOUNT_PATH)}/providers and ${ApiRoute(AUTH_CATALOG_MOUNT_PATH)}/login-screen`);
+}
+
+/** The routers {@link MountPublicCoreRoutes} returned, mounted AFTER the unified auth middleware. */
+export function MountAuthenticatedCoreRoutes(app: Application, routers: CoreAuthenticatedRouters, log: RouteLog): void {
+    if (routers.OAuth) {
+        app.use(ApiRoute('/oauth'), cors<cors.CorsRequest>(), BodyParser.json(), routers.OAuth);
+        log.LogIf('verbose', `[OAuth] Authenticated routes registered at ${ApiRoute('/oauth')}/status, /initiate and /exchange`);
+    }
+    if (routers.MagicLink) {
+        app.use(ApiRoute(MAGIC_LINK_MOUNT_PATH), cors<cors.CorsRequest>(), routers.MagicLink);
+        log.LogIf('verbose', `[MagicLink] Authenticated route registered at ${ApiRoute(MAGIC_LINK_MOUNT_PATH)}/create`);
+    }
+    // A verified visitor (post magic-link upgrade) promotes their anonymous trail here.
+    if (routers.Widget) {
+        app.use(ApiRoute(WIDGET_MOUNT_PATH), cors<cors.CorsRequest>(), routers.Widget);
+        log.LogIf('verbose', `[Widget] Authenticated route registered at ${ApiRoute(WIDGET_MOUNT_PATH)}/resolve-identity`);
+    }
+}