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

package/src/config.ts

@@ -5,6 +5,7 @@ import { LogError, LogStatus, LogStatusEx } from '@memberjunction/core';
 import { mergeConfigs, parseBooleanEnv } from '@memberjunction/config';
 import { TelemetryEnabledDefault } from './telemetryConfigUnits.js';
 import { RealtimeEnabledDefault } from './realtimeConfigUnits.js';
+import { ResolveServerRole, type ServerRole } from './serverRoleConfigUnits.js';
 
 const explorer = cosmiconfigSync('mj', { searchStrategy: 'global' });
 
@@ -226,10 +227,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 +248,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). */
@@ -299,6 +317,45 @@ const cacheSettingsSchema = z.object({
    * for it. 0 disables the turn-taking. Default: 30.
    */
   startupWarmupLeaseSeconds: z.number().int().nonnegative().optional().default(30),
+  /**
+   * Pluggable cache invalidation broadcast topology configuration.
+   * Defaults to `'SequencedRoleBucket'` (Topology 1 Monotonic Sequence Ring Buffer + Topology 2
+   * Role-Fingerprint $O(\text{Roles})$ evaluation & shaping memoizer).
+   */
+  broadcast: z
+    .object({
+      provider: z.string().optional().default('SequencedRoleBucket'),
+      ringBufferSize: z.number().int().positive().optional().default(5000),
+      excludedEntities: z.array(z.string()).optional().default([]),
+      azureWebPubSub: z
+        .object({
+          endpoint: z.string().optional(),
+          hubName: z.string().optional(),
+          accessKey: z.string().optional(),
+          tokenTtlMinutes: z.number().positive().optional(),
+        })
+        .optional(),
+      awsIoTCore: z
+        .object({
+          endpoint: z.string().optional(),
+          region: z.string().optional(),
+          topicPrefix: z.string().optional(),
+          accessKeyId: z.string().optional(),
+          secretAccessKey: z.string().optional(),
+          tokenTtlSeconds: z.number().positive().optional(),
+        })
+        .optional(),
+      gcpPubSub: z
+        .object({
+          projectId: z.string().optional(),
+          topicPrefix: z.string().optional(),
+          gatewayUrl: z.string().optional(),
+          signingSecret: z.string().optional(),
+          tokenTtlSeconds: z.number().positive().optional(),
+        })
+        .optional(),
+    })
+    .optional(),
 });
 
 const loggingSettingsSchema = z.object({
@@ -316,6 +373,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,11 +876,24 @@ 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 devAuthSchema = z.object({
+  /** Master switch for local-only development JWT auth (`MJ_DEV_AUTH_ENABLED=true`). Forbidden when NODE_ENV=production. */
+  enabled: zodBooleanWithTransforms().default(false),
+  /** Optional default email for `/auth/dev-login` when no email is specified in the request body. */
+  defaultEmail: z.string().optional(),
 }).passthrough();
 
 const configInfoSchema = z.object({
   userHandling: userHandlingInfoSchema,
   magicLink: magicLinkSchema.optional().default({}),
+  devAuth: devAuthSchema.optional().default({}),
   widget: widgetSchema.optional().default({}),
   telephony: telephonySchema.optional().default({}),
   realtime: realtimeSchema.optional().default({}),
@@ -830,9 +909,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 +940,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
@@ -867,8 +953,18 @@ const configInfoSchema = z.object({
     .transform((val) => z.record(z.string()).parse(JSON.parse(val)))
     .optional(),
   mjCoreSchema: z.string(),
+  /**
+   * Server execution role for horizontal scaling:
+   * - `'all'` (default): runs both interactive HTTP/GraphQL/WebSocket handlers and background worker loops.
+   * - `'api'`: runs interactive HTTP/GraphQL/WebSocket handlers only; background worker loops are skipped.
+   * - `'worker'`: runs background worker loops (`ScheduledJobsService`, `IntegrationSyncWorkerService`,
+   *   `StartTaskGraphDispatcher`, `StartWorkQueueHost`, `SessionJanitor`, reconcilers).
+   */
+  serverRole: z.enum(['all', 'api', 'worker']).optional().default('all'),
 });
 
+export type { ServerRole };
+
 export type UserHandlingInfo = z.infer<typeof userHandlingInfoSchema>;
 export type MagicLinkConfig = z.infer<typeof magicLinkSchema>;
 export type WidgetConfig = z.infer<typeof widgetSchema>;
@@ -893,9 +989,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,11 +1028,13 @@ 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',
   apiKey: process.env.MJ_API_KEY,
   websiteRunFromPackage: process.env.WEBSITE_RUN_FROM_PACKAGE ? parseInt(process.env.WEBSITE_RUN_FROM_PACKAGE, 10) : undefined,
+  serverRole: ResolveServerRole(process.env.MJ_SERVER_ROLE),
 
   // User handling defaults
   userHandling: {
@@ -1047,6 +1146,7 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
   cacheSettings: {
     maxMemoryMB: 150,
     maxPercentOfCachePerEntity: 50,
+    maxEntryPercentOfCache: 'auto',
     defaultTTLSeconds: 0,
     evictionSweepIntervalSeconds: 300,
     verboseLogging: false,
@@ -1146,6 +1246,16 @@ export function LoadConfig() {
     LogError('Error parsing config file', null, JSON.stringify(configParsing.error.issues, null, 2));
     throw new Error('Configuration validation failed');
   }
+
+  const rawDevAuthEnv = process.env.MJ_DEV_AUTH_ENABLED?.trim().toLowerCase();
+  const isDevAuthEnabled =
+    rawDevAuthEnv === 'true' || rawDevAuthEnv === '1' || configParsing.data.devAuth?.enabled === true;
+  if (isDevAuthEnabled && process.env.NODE_ENV?.trim().toLowerCase() === 'production') {
+    throw new Error(
+      '[SECURITY] Local dev auth (MJ_DEV_AUTH_ENABLED) is strictly forbidden when NODE_ENV=production. Refusing to start.'
+    );
+  }
+
   return configParsing.data;
 }
 

package/src/context.ts

@@ -21,7 +21,7 @@ import e from 'express';
 import type { RequestHandler, Request, Response, NextFunction } from 'express';
 import { DatabaseProviderBase, UserInfo, type IMetadataProvider, type MagicLinkScope, type ReturningVisitorContext, type WidgetGuestContext } from '@memberjunction/core';
 import { SQLServerDataProvider, SQLServerProviderConfigData } from '@memberjunction/sqlserver-dataprovider';
-import { Metadata } from '@memberjunction/core';
+import { Metadata, IsValidTimeZone, TIME_ZONE_HEADER } from '@memberjunction/core';
 import { IdentityClaimEngineServer } from '@memberjunction/core-entities-server';
 import { UUIDsEqual } from '@memberjunction/global';
 import { UserCache, resolveDbPlatformFromEnv } from '@memberjunction/generic-database-provider';
@@ -204,12 +204,17 @@ async function auditLoginFailure(
 // userRecord may be a SHARED cached instance (e.g. multiple recruiters on one per-company
 // link) — mutating it would leak one session's scope to another. Non-magic-link sessions,
 // and named sessions with no resource scope, are returned untouched.
-function buildMagicLinkSessionUser(userRecord: UserInfo, payload: jwt.JwtPayload): UserInfo {
+export function BuildMagicLinkSessionUser(userRecord: UserInfo, payload: jwt.JwtPayload): UserInfo {
   if (payload['mj_magic_link'] !== true) {
     return userRecord;
   }
   const md = Metadata.Provider; // global-provider-ok: server-side magic-link session built under the server's single default provider
   const isAnon = payload['mj_anon'] === true;
+  const rawSid = payload['mj_sid'];
+  const mjSid = typeof rawSid === 'string' ? rawSid.trim() : '';
+  if (isAnon && !mjSid) {
+    throw new AuthenticationError('Anonymous magic-link session token is missing required mj_sid claim');
+  }
   const scopes = payload['mj_scopes'];
 
   // Per-session resource scope (single-resource share; multi-resource union is a follow-on).
@@ -279,6 +284,7 @@ function buildMagicLinkSessionUser(userRecord: UserInfo, payload: jwt.JwtPayload
     // Mark the session so the CurrentUser field resolver serves these synthesized roles
     // (the shared Anonymous principal holds none in the DB). See UserInfo.IsMagicLinkAnonymous.
     sessionUser.IsMagicLinkAnonymous = true;
+    sessionUser.AnonymousVisitorID = mjSid;
   }
   return sessionUser;
 }
@@ -420,7 +426,7 @@ export const GetUserPayload = async (
         // very often the SHARED UserCache instance, and stamping it in place
         // leaks one session's row-filter bindings / acting context to every
         // concurrent session of the same user (same pattern as
-        // buildMagicLinkSessionUser — see sessionUserClone.ts).
+        // BuildMagicLinkSessionUser — see sessionUserClone.ts).
         const userRecord = CloneUserForSessionContext(resolvedUser);
 
         // Row-filter bindings for this key, rebuilt PER REQUEST from the
@@ -486,7 +492,11 @@ export const GetUserPayload = async (
       throw new AuthenticationError('Missing token');
     }
 
-    const payload = jwt.decode(token);
+    const cachedAuth = AuthCache.get(token);
+    const payload =
+      cachedAuth && typeof cachedAuth === 'object'
+        ? cachedAuth
+        : jwt.decode(token);
     if (!payload || typeof payload === 'string') {
       throw new AuthenticationError('Invalid token payload');
     }
@@ -498,7 +508,7 @@ export const GetUserPayload = async (
       throw new TokenExpiredError(expiryDate);
     }
 
-    if (!AuthCache.has(token)) {
+    if (!cachedAuth) {
       const issuer = payload.iss;
       if (!issuer) {
         console.warn('No issuer claim on token');
@@ -513,7 +523,7 @@ export const GetUserPayload = async (
       }
 
       await verifyAsync(issuer, token);
-      AuthCache.set(token, true);
+      AuthCache.set(token, payload);
     }
 
     // Use provider to extract user information
@@ -540,7 +550,7 @@ export const GetUserPayload = async (
     // Anonymous principal with an in-memory UserInfo carrying the claimed role(s), so
     // the session enforces exactly the link's granted scope (no DB accretion). No-op
     // for everything else.
-    const sessionUser = buildMagicLinkSessionUser(userRecord, payload);
+    const sessionUser = BuildMagicLinkSessionUser(userRecord, payload);
 
     // Session-established audit — once per issued token (deduped), fire-and-forget so
     // it never adds latency to the request. The dedup mark is set synchronously here.
@@ -626,6 +636,15 @@ function parseRequestHostname(origin: string | undefined): string | undefined {
   }
 }
 
+/**
+ * The caller's IANA time zone from the `x-mj-timezone` header, or undefined when the header is
+ * absent, repeated, or names no zone this runtime knows (callers then use UTC).
+ */
+function readTimeZoneHeader(req: IncomingMessage): string | undefined {
+  const value = req.headers[TIME_ZONE_HEADER];
+  return typeof value === 'string' && IsValidTimeZone(value) ? value : undefined;
+}
+
 function extractAuthInputs(req: IncomingMessage): {
   bearerToken: string;
   sessionId: string;
@@ -633,6 +652,7 @@ function extractAuthInputs(req: IncomingMessage): {
   systemApiKey: string;
   userApiKey: string;
   requestContext: RequestContext;
+  timeZone: string | undefined;
 } {
   const sessionIdRaw = req.headers['x-session-id'];
   const requestDomain = parseRequestHostname(req.headers.origin);
@@ -657,6 +677,7 @@ function extractAuthInputs(req: IncomingMessage): {
     systemApiKey,
     userApiKey,
     requestContext,
+    timeZone: readTimeZoneHeader(req),
   };
 }
 
@@ -681,7 +702,7 @@ export function CreateUnifiedAuthMiddleware(
     }
 
     try {
-      const { bearerToken, sessionId, requestDomain, systemApiKey, userApiKey, requestContext } =
+      const { bearerToken, sessionId, requestDomain, systemApiKey, userApiKey, requestContext, timeZone } =
         extractAuthInputs(req);
 
       const userPayload = await GetUserPayload(
@@ -699,6 +720,9 @@ export function CreateUnifiedAuthMiddleware(
         res.status(401).json({ error: 'Invalid token' });
         return;
       }
+      if (timeZone) {
+        userPayload.TimeZone = timeZone;
+      }
 
       // Attach to request for downstream consumers
       req.userPayload = userPayload;

package/src/coreRoutes.ts

@@ -0,0 +1,181 @@
+/**
+ * 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 { AssertLocalDevAuthAllowed, IsLocalDevAuthEnabled, RegisterLocalDevAuthProvider } from './auth/localDevAuth.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);
+    mountLocalDevAuthPublic(app, publicUrl, log);
+    mountRealtimeVerify(app, log);
+    return routers;
+}
+
+function mountLocalDevAuthPublic(app: Application, publicUrl: string, log: RouteLog): void {
+    AssertLocalDevAuthAllowed();
+    if (!IsLocalDevAuthEnabled()) {
+        return;
+    }
+    RegisterLocalDevAuthProvider(publicUrl);
+    if (!configInfo.magicLink?.enabled && !configInfo.widget?.enabled) {
+        app.use(ApiRoute(MAGIC_LINK_MOUNT_PATH), cors<cors.CorsRequest>(), CreateMagicLinkJwksRouter());
+        log.LogIf('verbose', `[LocalDevAuth] Published RS256 signing key at ${ApiRoute(MAGIC_LINK_MOUNT_PATH)}/jwks.json`);
+    }
+    log.LogIf('verbose', `[LocalDevAuth] Local dev auth routes enabled at ${ApiRoute(AUTH_CATALOG_MOUNT_PATH)}/dev-login (localhost only)`);
+}
+
+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`);
+    }
+}