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

package/src/config.ts

@@ -5,6 +5,15 @@ 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';
+import {
+  AgentRunWatchdogDefaultsFromEnv,
+  AgentRunWatchdogSchema,
+  AgentSessionsDefaultsFromEnv,
+  AgentSessionsSchema,
+  ConversationDetailReconcilerDefaultsFromEnv,
+  ConversationDetailReconcilerSchema,
+} from './backgroundSweepConfigUnits.js';
 
 const explorer = cosmiconfigSync('mj', { searchStrategy: 'global' });
 
@@ -316,6 +325,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({
@@ -466,6 +514,13 @@ const magicLinkSchema = z.object({
    * returns the token as JSON. Append `?format=json` to force JSON regardless.
    */
   explorerUrl: z.string().optional(),
+  /**
+   * Explicit frontend origins permitted for per-invite `RedirectUrl` targets (in addition to
+   * `explorerUrl` and concrete non-wildcard entries in `cors.allowedOrigins`). Wildcard `'*'`
+   * entries are always ignored so deployments using the default `cors.allowedOrigins: ['*']`
+   * never expose an open redirect carrying session tokens.
+   */
+  allowedRedirectOrigins: z.array(z.string()).optional(),
 }).passthrough();
 
 /**
@@ -831,6 +886,44 @@ const identityVerificationSchema = z.object({
   }).optional().default({}),
 }).passthrough();
 
+/**
+ * Remote browsers a TEXT conversation opens (`<mj-conversation-chat-area [AllowRemoteBrowser]>`), whose
+ * agents drive them through the `browser_*` tools. Realtime calls' browsers are not affected.
+ *
+ * Off by default: until `enabled` is true, every remote-browser operation on a conversation is refused,
+ * since each browser is a server Chromium process or a billed hosted session.
+ */
+const conversationBrowserSchema = z.object({
+  /** Master switch. When false, no conversation can open a browser. */
+  enabled: zodBooleanWithTransforms().default(false),
+  /** Also let anonymous principals (public widget guests, anonymous magic links) open one. */
+  allowAnonymous: zodBooleanWithTransforms().default(false),
+  /** Most conversation browsers one user (or one anonymous guest) may hold at once. Default 2. */
+  maxPerUser: z.coerce.number().int().positive().optional().default(2),
+  /**
+   * Most conversation browsers all anonymous guests together may hold at once, since a guest can start a
+   * new guest scope cheaply (limited only by the per-IP rate limit). Applies only with `allowAnonymous`. Default 4.
+   */
+  maxAnonymousTotal: z.coerce.number().int().positive().optional().default(4),
+  /**
+   * Minutes unused after which a conversation browser is ended (a reloaded or closed tab never ends its own).
+   * Used means an agent or the user acts on it, or its open drawer polls for a snapshot; a drawer showing a
+   * pushed screencast with nothing else happening counts as unused. Default 15.
+   */
+  idleMinutes: z.coerce.number().positive().optional().default(15),
+  /**
+   * Private hosts a conversation browser may still reach, as `host` or `host:port` (e.g. `localhost:4200`).
+   * Every other loopback, link-local or private-network HOSTNAME is refused (private IPv4 and IPv6 ranges,
+   * `localhost`, names under `.local`, `.localdomain`, `.internal`, `.intranet`, `.lan`, `.corp`, `.home`,
+   * `.home.arpa`, `.private` and `.svc`, and the Docker, Kubernetes and cloud-metadata names), including where
+   * a main-frame redirect lands, and in popups the page opens. This is a best-effort hostname check. Gets through: a public name that resolves to a
+   * private address, WebSockets, service-worker fetches, an iframe whose source redirects to a private
+   * host, redirects of the page's own requests, and the redirect request itself (only where it lands is
+   * refused). For real isolation, run the browsers under network egress rules. Default none.
+   */
+  allowedPrivateHosts: z.array(z.string()).optional().default([]),
+}).passthrough();
+
 const realtimeSchema = z.object({
   /** Master switch. When false, the WebRTC SDP broker router is not mounted. Defaults to true. */
   enabled: zodBooleanWithTransforms().default(true),
@@ -841,11 +934,21 @@ const realtimeSchema = z.object({
    * is assembled anyway as `Partial` (gaps become silence). Defaults to 90.
    */
   recordingAssemblyGraceSeconds: z.coerce.number().positive().optional().default(90),
+  /** Remote browsers that text conversations open (off by default). */
+  conversationBrowser: conversationBrowserSchema.optional().default({}),
+}).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({}),
@@ -856,6 +959,9 @@ const configInfoSchema = z.object({
   authProviders: z.array(authProviderSchema).optional(),
   componentRegistries: z.array(componentRegistrySchema).optional(),
   scheduledJobs: scheduledJobsSchema.optional().default({}),
+  agentSessions: AgentSessionsSchema.optional().default({}),
+  agentRunWatchdog: AgentRunWatchdogSchema.optional().default({}),
+  conversationDetailReconciler: ConversationDetailReconcilerSchema.optional().default({}),
   integrationSyncWorker: integrationSyncWorkerSchema.optional().default({}),
   workQueue: WorkQueueSchema.optional().default({}),
   telemetry: telemetrySchema.optional().default({}),
@@ -905,13 +1011,24 @@ 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>;
 export type TelephonyConfig = z.infer<typeof telephonySchema>;
 export type RealtimeConfig = z.infer<typeof realtimeSchema>;
+export type ConversationBrowserConfig = z.infer<typeof conversationBrowserSchema>;
 export type IdentityVerificationConfig = z.infer<typeof identityVerificationSchema>;
 export type TwilioTelephonyConfig = z.infer<typeof twilioTelephonySchema>;
 export type VonageTelephonyConfig = z.infer<typeof vonageTelephonySchema>;
@@ -976,6 +1093,7 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
   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: {
@@ -1055,6 +1173,16 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
     staleLockCleanupInterval: 300000
   },
 
+  // Background sweeps that query the database on a timer (session janitor, bridge and conversation-
+  // detail reconcilers, agent-run watchdog). Defaults are the values MJAPI always used; each has an
+  // env override (MJ_SESSION_JANITOR_*, MJ_BRIDGE_RECONCILER_*, MJ_CONVERSATION_DETAIL_RECONCILER_*,
+  // MJ_AGENT_RUN_WATCHDOG_SWEEP_INTERVAL_MS), read here rather than in the schema because this object
+  // is the merge base (see the telemetry note below). A bad value fails startup, naming the variable.
+  // guides/SERVERLESS_DATABASE_AUTO_PAUSE_GUIDE.md lists every switch.
+  agentSessions: AgentSessionsDefaultsFromEnv(process.env),
+  conversationDetailReconciler: ConversationDetailReconcilerDefaultsFromEnv(process.env),
+  agentRunWatchdog: AgentRunWatchdogDefaultsFromEnv(process.env),
+
   // Integration sync worker defaults (off — syncs run inline unless a worker is enabled)
   integrationSyncWorker: {
     enabled: false,
@@ -1187,6 +1315,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

@@ -7,6 +7,7 @@ import { AuthenticationError, AuthorizationError } from 'type-graphql';
 import sql from 'mssql';
 import { GetSigningKeys, GetSystemUser, GetValidationOptions, VerifyUserRecord, ExtractUserInfoFromPayload } from './auth/index.js';
 import { CloneUserForSessionContext } from './auth/sessionUserClone.js';
+import { EmailsMatch, ResolveUserLookupEmail, type LoginEmailResolution } from './auth/loginEmailResolution.js';
 import { GetAPIKeyActingContextResolver } from './auth/actingContextResolver.js';
 import { TokenExpiredError, AuthProviderFactory } from '@memberjunction/auth-providers';
 import { AuthCache } from './cache.js';
@@ -15,13 +16,15 @@ import { BuildPostgreSQLConnectionConfig, PostgreSQLReadOnlyPool, ResolvePostgre
 import { BuildBoundaryLogPayload } from './logging/boundaryLogPayload.js';
 import { StartupLogger } from './logging/StartupLogger.js';
 import { DataSourceInfo, UserPayload } from './types.js';
+import { ReadRequestOrigin } from './requestOrigin.js';
 import { GetReadOnlyDataSource, GetReadWriteDataSource } from './util.js';
 import { v4 as uuidv4 } from 'uuid';
 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 { PostgreSQLDataProvider, PostgreSQLProviderConfigData } from '@memberjunction/postgresql-dataprovider';
+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';
@@ -145,6 +148,28 @@ async function writeSessionAudit(args: {
   }
 }
 
+/**
+ * Logs a session whose User record is not the identity its token carries, and returns whether that
+ * is the case. Runs once per issued token (inside the session-audit dedup). A `USER_EMAIL_MAP`
+ * rewrite is reported as such; any other difference means the lookup reached another person's
+ * record. Anonymous magic-link sessions run as a synthetic principal by design and are skipped.
+ */
+function reportIdentityMismatch(loginEmail: LoginEmailResolution, sessionUser: UserInfo): boolean {
+  if (sessionUser.IsMagicLinkAnonymous || EmailsMatch(loginEmail.TokenEmail, sessionUser.Email)) {
+    return false;
+  }
+  if (loginEmail.Remapped) {
+    console.warn(
+      `[Auth] USER_EMAIL_MAP remapped login '${loginEmail.TokenEmail}' to '${loginEmail.LookupEmail}'; the session runs as user ${sessionUser.ID} (${sessionUser.Email})`,
+    );
+  } else {
+    console.warn(
+      `[Auth] Login identity '${loginEmail.TokenEmail ?? ''}' resolved to user ${sessionUser.ID} with a different email (${sessionUser.Email}); check the User records for this address`,
+    );
+  }
+  return true;
+}
+
 /** Best-effort failure audit: decodes the attempted identity, dedupes, attributes to the system user. */
 async function auditLoginFailure(
   bearerToken: string | undefined,
@@ -204,12 +229,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 +309,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 +451,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 +517,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 +533,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,12 +548,13 @@ export const GetUserPayload = async (
       }
 
       await verifyAsync(issuer, token);
-      AuthCache.set(token, true);
+      AuthCache.set(token, payload);
     }
 
     // Use provider to extract user information
     const userInfo = ExtractUserInfoFromPayload(payload);
-    const email = userInfo.email ? ((userEmailMap ?? {})[userInfo.email] ?? userInfo.email) : userInfo.preferredUsername;
+    const loginEmail = ResolveUserLookupEmail(userInfo, userEmailMap);
+    const email = loginEmail.LookupEmail;
     
     const userRecord = await VerifyUserRecord(
       email, 
@@ -540,11 +576,12 @@ 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.
     if (markSessionAuditSeen(sessionAuditKey('sess', payload))) {
+      const identityMismatch = reportIdentityMismatch(loginEmail, sessionUser);
       void writeSessionAudit({
         user: sessionUser,
         auditTypeName: SESSION_AUDIT_TYPE,
@@ -552,7 +589,16 @@ export const GetUserPayload = async (
         payload,
         requestContext,
         requestDomain,
-        description: `Session established via ${payload.iss ?? 'unknown provider'}`,
+        description: identityMismatch
+          ? `Session established via ${payload.iss ?? 'unknown provider'}: token identity '${loginEmail.TokenEmail ?? ''}' runs as user '${sessionUser.Email}'`
+          : `Session established via ${payload.iss ?? 'unknown provider'}`,
+        extraDetails: {
+          tokenEmail: loginEmail.TokenEmail ?? null,
+          lookupEmail: loginEmail.LookupEmail ?? null,
+          resolvedUserEmail: sessionUser.Email ?? null,
+          remappedByUserEmailMap: loginEmail.Remapped,
+          identityMismatch,
+        },
       });
     }
 
@@ -626,6 +672,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 +688,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 +713,7 @@ function extractAuthInputs(req: IncomingMessage): {
     systemApiKey,
     userApiKey,
     requestContext,
+    timeZone: readTimeZoneHeader(req),
   };
 }
 
@@ -681,7 +738,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 +756,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;
@@ -782,6 +842,7 @@ export const ContextFunction =
       userPayload,
       providers,
       ClientIp: expressReq.ip,
+      RequestOrigin: ReadRequestOrigin(req.headers.origin),
     };
   };
 
@@ -836,8 +897,6 @@ export async function CreateReadOnlyProvider(dataSources: DataSourceInfo[]): Pro
  * from the primary provider to avoid pool exhaustion.
  */
 async function createPostgresProvider(): Promise<DatabaseProviderBase> {
-  const { PostgreSQLDataProvider, PostgreSQLProviderConfigData } = await import('@memberjunction/postgresql-dataprovider');
-
   const pgProvider = new PostgreSQLDataProvider();
   const pgConfig = new PostgreSQLProviderConfigData(
     BuildPostgreSQLConnectionConfig(ResolvePostgreSQLEndpoint(), configInfo.databaseSettings, 'api'),
@@ -872,8 +931,6 @@ async function tryCreateReadOnlyPostgresProvider(): Promise<DatabaseProviderBase
   }
 
   try {
-    const { PostgreSQLDataProvider, PostgreSQLProviderConfigData } = await import('@memberjunction/postgresql-dataprovider');
-
     const roProvider = new PostgreSQLDataProvider();
     const roConfig = new PostgreSQLProviderConfigData(
       BuildPostgreSQLConnectionConfig({ ...ResolvePostgreSQLEndpoint(), ...credentials }, configInfo.databaseSettings, 'read-only'),

package/src/coreRoutes.ts

@@ -19,18 +19,20 @@ 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 { CreateMagicLinkHandler, CreateMagicLinkJwksRouter, MagicLinkService, 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. */
+/** Routers (and host services) the public mounts create for post-auth mounting and extension sharing. */
 export interface CoreAuthenticatedRouters {
     OAuth?: Router;
     MagicLink?: Router;
+    MagicLinkService?: MagicLinkService;
     Widget?: Router;
 }
 
@@ -61,12 +63,28 @@ export function MountPublicCoreRoutes(app: Application, publicUrl: string, log:
         log.LogIf('verbose', `[Realtime] WebRTC SDP broker registered at ${ApiRoute(REALTIME_SDP_EXCHANGE_PATH)}`);
     }
 
-    routers.MagicLink = mountMagicLinkPublic(app, publicUrl, log);
+    const magicLink = mountMagicLinkPublic(app, publicUrl, log);
+    routers.MagicLink = magicLink?.authenticatedRouter;
+    routers.MagicLinkService = magicLink?.service;
     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;
@@ -84,16 +102,20 @@ function mountOAuthCallback(app: Application, publicUrl: string, log: RouteLog):
     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 {
+/** Public magic-link router (JWKS + redeem). The invite-creation router + service are returned for post-auth / extensions. */
+function mountMagicLinkPublic(
+    app: Application,
+    publicUrl: string,
+    log: RouteLog,
+): { authenticatedRouter: Router; service: MagicLinkService } | undefined {
     if (!configInfo.magicLink?.enabled) {
         return undefined;
     }
-    const { publicRouter, authenticatedRouter } = CreateMagicLinkHandler(publicUrl, configInfo.magicLink);
+    const { publicRouter, authenticatedRouter, service } = 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;
+    return { authenticatedRouter, service };
 }
 
 /**