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

package/src/auth/magicLink/MagicLinkService.ts

@@ -37,9 +37,12 @@ import { configInfo, type MagicLinkConfig } from '../../config.js';
 import { CreateIsolatedProvider } from '../../isolatedProvider.js';
 import { MagicLinkKeyManager } from './MagicLinkKeys.js';
 import { GenerateRawToken, GenerateSessionId, HashToken, EvaluateInvite, BuildSessionClaims, BuildConsumeInvitePostgresSQL, CanIssueInvites, IsRoleGrantable, MAGIC_LINK_TOKEN_PREFIX } from './magicLinkCore.js';
+import type { IServerExtensionMagicLinkService } from '@memberjunction/server-extensions-core';
 import type {
   CreateMagicLinkInviteParams,
   CreateMagicLinkInviteResult,
+  ManageMagicLinkInviteResult,
+  MagicLinkJWTClaims,
   RedeemMagicLinkResult,
   RedeemAuditContext,
 } from './types.js';
@@ -75,11 +78,53 @@ interface ProvisionResult {
   error?: string;
 }
 
+/**
+ * Validates that a candidate `redirectUrl` is a well-formed `http:` or `https:` URL whose
+ * origin matches at least one concrete normalized entry in `allowedOrigins`.
+ * Wildcard `'*'` entries are explicitly ignored/rejected so session tokens can never be
+ * redirected to unvalidated origins.
+ */
+export function IsMagicLinkRedirectUrlAllowed(redirectUrl: string, allowedOrigins: readonly string[]): boolean {
+  const trimmed = redirectUrl.trim();
+  if (!trimmed) {
+    return false;
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return false;
+  }
+  const normalizedTargetOrigin = parsed.origin.toLowerCase();
+  for (const rawAllowed of allowedOrigins) {
+    const candidate = (rawAllowed ?? '').trim();
+    if (!candidate || candidate === '*') {
+      continue;
+    }
+    try {
+      const allowedUrl = new URL(candidate);
+      if (allowedUrl.origin.toLowerCase() === normalizedTargetOrigin) {
+        return true;
+      }
+    } catch {
+      if (candidate.replace(/\/$/, '').toLowerCase() === normalizedTargetOrigin) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
 /**
  * Magic-link service. One instance per server, constructed with the resolved
- * public URL and the validated config.
+ * public URL and the validated config. Implements {@link IServerExtensionMagicLinkService}
+ * so `BaseServerExtension` implementations can mint, revoke, extend, and verify invites
+ * via `context.services.GetMagicLinkService?.()`.
  */
-export class MagicLinkService {
+export class MagicLinkService implements IServerExtensionMagicLinkService {
   constructor(
     private readonly publicUrl: string,
     private readonly config: MagicLinkConfig,
@@ -87,7 +132,7 @@ export class MagicLinkService {
 
   /**
    * Creates a single-use, app-scoped invite, persists its hashed token, and
-   * (when a communication provider is configured) emails the link.
+   * (when a communication provider is configured and `params.SendEmail !== false`) emails the link.
    *
    * @param params  invite parameters
    * @param creatingUser  the authenticated internal user issuing the invite
@@ -110,6 +155,15 @@ export class MagicLinkService {
         return { success: false, errorCode: 'forbidden', error: 'Not authorized to issue magic-link invites.' };
       }
 
+      const validatedRedirectUrl = params.RedirectUrl?.trim() ? params.RedirectUrl.trim() : undefined;
+      if (validatedRedirectUrl && !IsMagicLinkRedirectUrlAllowed(validatedRedirectUrl, this.allowedRedirectOrigins())) {
+        return {
+          success: false,
+          errorCode: 'invalid_redirect_url',
+          error: `RedirectUrl '${validatedRedirectUrl}' is not permitted by the server's allowed frontend origins.`,
+        };
+      }
+
       const roleId = params.RoleId ?? this.resolveRestrictedRoleId(md);
       if (!roleId) {
         return { success: false, error: `Restricted role '${this.config.restrictedRoleName}' not found and no roleId supplied.` };
@@ -136,12 +190,13 @@ export class MagicLinkService {
       }
 
       const rawToken = GenerateRawToken();
+      const tokenHash = HashToken(rawToken);
       const expiresInHours = params.ExpiresInHours ?? this.config.defaultExpiresInHours;
       const expiresAt = new Date(Date.now() + expiresInHours * 3600 * 1000);
 
       const invite = await md.GetEntityObject<MJMagicLinkInviteEntity>(INVITE_ENTITY, creatingUser);
       invite.NewRecord();
-      invite.TokenHash = HashToken(rawToken);
+      invite.TokenHash = tokenHash;
       invite.Email = params.email;
       invite.ApplicationID = params.ApplicationId;
       invite.RoleID = roleId;
@@ -161,10 +216,22 @@ export class MagicLinkService {
       // multi-scope reads. Best-effort so a child-row hiccup never fails issuance.
       await this.writeInviteScopeChildRows(invite.ID, params.ApplicationId, roleId, creatingUser, md);
 
-      const redemptionUrl = this.buildRedemptionUrl(rawToken);
+      let redirectBindingToken: string | undefined;
+      if (validatedRedirectUrl) {
+        if (!MagicLinkKeyManager.Instance.IsInitialized) {
+          MagicLinkKeyManager.Instance.Initialize(this.config.rsaPrivateKey);
+        }
+        redirectBindingToken = MagicLinkKeyManager.Instance.SignRedirectBinding(
+          tokenHash,
+          validatedRedirectUrl,
+          Math.floor(expiresAt.getTime() / 1000),
+        );
+      }
+
+      const redemptionUrl = this.buildRedemptionUrl(rawToken, redirectBindingToken);
 
       let emailSent = false;
-      if (this.config.communicationProvider) {
+      if (params.SendEmail !== false && this.config.communicationProvider) {
         emailSent = await this.sendInviteEmail(params.email, redemptionUrl, app.Name, creatingUser);
       }
 
@@ -172,7 +239,7 @@ export class MagicLinkService {
         success: true,
         inviteId: invite.ID,
         redemptionUrl,
-        // Surface the raw token only when we couldn't deliver it ourselves.
+        // Surface the raw token only when we couldn't (or were asked not to) deliver it ourselves.
         rawToken: emailSent ? undefined : rawToken,
         emailSent,
         expiresAt: expiresAt.toISOString(),
@@ -183,6 +250,158 @@ export class MagicLinkService {
     }
   }
 
+  /**
+   * Revokes an existing invite so subsequent redemptions fail with `'revoked'`.
+   * Requires the acting user to hold invite-issuance authority (`CanIssueInvites`).
+   */
+  public async RevokeInvite(
+    inviteId: string,
+    actingUser: UserInfo,
+    provider?: IMetadataProvider,
+  ): Promise<ManageMagicLinkInviteResult> {
+    try {
+      const callerRoleNames = (actingUser.UserRoles ?? []).map((r) => r.Role).filter((n): n is string => !!n);
+      if (!CanIssueInvites(actingUser.Type, callerRoleNames, this.config.inviteIssuerRoleNames)) {
+        return { success: false, errorCode: 'forbidden', error: 'Not authorized to revoke magic-link invites.' };
+      }
+      if (!inviteId?.trim()) {
+        return { success: false, errorCode: 'not_found', error: 'Invite ID is required.' };
+      }
+
+      const md = provider ?? Metadata.Provider;
+      const invite = await md.GetEntityObject<MJMagicLinkInviteEntity>(INVITE_ENTITY, actingUser);
+      const loaded = await invite.Load(inviteId.trim());
+      if (!loaded) {
+        return { success: false, errorCode: 'not_found', error: `Invite '${inviteId}' not found.` };
+      }
+
+      if (invite.Status === 'Revoked') {
+        return {
+          success: true,
+          inviteId: invite.ID,
+          status: invite.Status,
+          expiresAt: invite.ExpiresAt.toISOString(),
+        };
+      }
+
+      invite.Status = 'Revoked';
+      if (!(await invite.Save())) {
+        return {
+          success: false,
+          errorCode: 'server_error',
+          error: `Failed to revoke invite: ${invite.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+        };
+      }
+
+      return {
+        success: true,
+        inviteId: invite.ID,
+        status: invite.Status,
+        expiresAt: invite.ExpiresAt.toISOString(),
+      };
+    } catch (e) {
+      LogError(e);
+      return { success: false, errorCode: 'server_error', error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  /**
+   * Updates the expiration timestamp of an existing non-revoked, non-consumed invite.
+   * Requires the acting user to hold invite-issuance authority (`CanIssueInvites`).
+   */
+  public async UpdateInviteExpiry(
+    inviteId: string,
+    expiresAt: Date,
+    actingUser: UserInfo,
+    provider?: IMetadataProvider,
+  ): Promise<ManageMagicLinkInviteResult> {
+    try {
+      const callerRoleNames = (actingUser.UserRoles ?? []).map((r) => r.Role).filter((n): n is string => !!n);
+      if (!CanIssueInvites(actingUser.Type, callerRoleNames, this.config.inviteIssuerRoleNames)) {
+        return { success: false, errorCode: 'forbidden', error: 'Not authorized to update magic-link invites.' };
+      }
+      if (!(expiresAt instanceof Date) || Number.isNaN(expiresAt.getTime())) {
+        return { success: false, errorCode: 'invalid_expiry', error: 'expiresAt must be a valid Date.' };
+      }
+      if (!inviteId?.trim()) {
+        return { success: false, errorCode: 'not_found', error: 'Invite ID is required.' };
+      }
+
+      const md = provider ?? Metadata.Provider;
+      const invite = await md.GetEntityObject<MJMagicLinkInviteEntity>(INVITE_ENTITY, actingUser);
+      const loaded = await invite.Load(inviteId.trim());
+      if (!loaded) {
+        return { success: false, errorCode: 'not_found', error: `Invite '${inviteId}' not found.` };
+      }
+
+      if (invite.Status === 'Revoked' || invite.Status === 'Consumed') {
+        return {
+          success: false,
+          errorCode: 'invalid_state',
+          error: `Cannot update expiry on invite '${invite.ID}' because its status is '${invite.Status}'.`,
+        };
+      }
+
+      const nowMs = Date.now();
+      invite.ExpiresAt = expiresAt;
+      if (invite.Status === 'Expired' && expiresAt.getTime() > nowMs && invite.UseCount < invite.MaxUses) {
+        invite.Status = 'Active';
+      } else if (invite.Status === 'Active' && expiresAt.getTime() <= nowMs) {
+        invite.Status = 'Expired';
+      }
+
+      if (!(await invite.Save())) {
+        return {
+          success: false,
+          errorCode: 'server_error',
+          error: `Failed to update invite expiry: ${invite.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+        };
+      }
+
+      return {
+        success: true,
+        inviteId: invite.ID,
+        status: invite.Status,
+        expiresAt: invite.ExpiresAt.toISOString(),
+      };
+    } catch (e) {
+      LogError(e);
+      return { success: false, errorCode: 'server_error', error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  /**
+   * Verifies a magic-link session JWT against this service's configured issuer and audience.
+   */
+  public VerifySessionToken(token: string): MagicLinkJWTClaims | null {
+    if (!token || !MagicLinkKeyManager.Instance.IsInitialized) {
+      return null;
+    }
+    return MagicLinkKeyManager.Instance.VerifySessionToken(token, {
+      issuer: this.publicUrl,
+      audience: this.config.audience,
+    });
+  }
+
+  /**
+   * Verifies a signed redirect binding (`rt`) against the raw invite token's hash AND the host's
+   * allowed frontend origins. Returns the verified redirect URL, or `undefined` if absent/invalid.
+   */
+  public ResolveVerifiedRedirectUrl(rawToken: string, redirectBindingToken: string | undefined): string | undefined {
+    if (!rawToken || !redirectBindingToken || !MagicLinkKeyManager.Instance.IsInitialized) {
+      return undefined;
+    }
+    const tokenHash = HashToken(rawToken);
+    const boundUrl = MagicLinkKeyManager.Instance.VerifyRedirectBinding(redirectBindingToken, tokenHash);
+    if (!boundUrl) {
+      return undefined;
+    }
+    if (!IsMagicLinkRedirectUrlAllowed(boundUrl, this.allowedRedirectOrigins())) {
+      return undefined;
+    }
+    return boundUrl;
+  }
+
   /**
    * Redeems a raw token: validates the invite, atomically consumes one use,
    * provisions/links the user with the restricted role + app, and mints a
@@ -420,10 +639,31 @@ export class MagicLinkService {
     return role?.ID;
   }
 
-  /** Builds the shareable redemption URL. */
-  private buildRedemptionUrl(rawToken: string): string {
+  /** Builds the shareable redemption URL (including `&rt=...` when a per-invite RedirectUrl was signed). */
+  private buildRedemptionUrl(rawToken: string, redirectBindingToken?: string): string {
     const base = this.publicUrl.replace(/\/$/, '');
-    return `${base}/magic-link/redeem?token=${encodeURIComponent(rawToken)}`;
+    const rtParam = redirectBindingToken ? `&rt=${encodeURIComponent(redirectBindingToken)}` : '';
+    return `${base}/magic-link/redeem?token=${encodeURIComponent(rawToken)}${rtParam}`;
+  }
+
+  /**
+   * Collects concrete frontend origins a caller-supplied per-invite `RedirectUrl` is permitted
+   * to target (`explorerUrl`, `magicLink.allowedRedirectOrigins`, and non-wildcard `cors.allowedOrigins`).
+   */
+  private allowedRedirectOrigins(): string[] {
+    const origins: string[] = [];
+    const candidates: readonly (string | undefined)[] = [
+      this.config.explorerUrl ?? configInfo.magicLink?.explorerUrl,
+      ...(this.config.allowedRedirectOrigins ?? configInfo.magicLink?.allowedRedirectOrigins ?? []),
+      ...(configInfo.cors?.allowedOrigins ?? []),
+    ];
+    for (const raw of candidates) {
+      const trimmed = raw?.trim();
+      if (trimmed && trimmed !== '*') {
+        origins.push(trimmed);
+      }
+    }
+    return origins;
   }
 
   /**

package/src/auth/magicLink/index.ts

@@ -8,7 +8,7 @@ export {
   type InviteEvaluationInput,
 } from './magicLinkCore.js';
 export { MagicLinkKeyManager } from './MagicLinkKeys.js';
-export { MagicLinkService } from './MagicLinkService.js';
+export { MagicLinkService, IsMagicLinkRedirectUrlAllowed } from './MagicLinkService.js';
 export {
   CreateMagicLinkHandler, createMagicLinkHandler,
   CreateMagicLinkJwksRouter, createMagicLinkJwksRouter,

package/src/auth/magicLink/redeemLanding.ts

@@ -32,9 +32,12 @@ export function escapeHtml(s: string): string {
  * @param token       the raw magic-link token (embedded in a hidden field)
  * @param actionPath  the same-origin path the form POSTs to (e.g. `/magic-link/redeem`)
  */
-export function BuildRedeemLandingHtml(token: string, actionPath: string): string {
+export function BuildRedeemLandingHtml(token: string, actionPath: string, redirectBindingToken?: string): string {
   const t = EscapeHtml(token);
   const action = EscapeHtml(actionPath);
+  const rtInput = redirectBindingToken
+    ? `\n      <input type="hidden" name="rt" value="${EscapeHtml(redirectBindingToken)}">`
+    : '';
   // Hardcoded colors are intentional here — this is a standalone server-rendered
   // HTML response, not Angular component CSS, so the design-token rule doesn't apply.
   return `<!doctype html>
@@ -58,7 +61,7 @@ export function BuildRedeemLandingHtml(token: string, actionPath: string): strin
     <h1>Sign in to continue</h1>
     <p>Click below to securely sign in with your invitation link.</p>
     <form method="POST" action="${action}">
-      <input type="hidden" name="token" value="${t}">
+      <input type="hidden" name="token" value="${t}">${rtInput}
       <button type="submit">Continue to sign in</button>
     </form>
   </div>
@@ -67,6 +70,6 @@ export function BuildRedeemLandingHtml(token: string, actionPath: string): strin
 }
 
 /** @deprecated Use {@link BuildRedeemLandingHtml}. */
-export function buildRedeemLandingHtml(token: string, actionPath: string): string {
-  return BuildRedeemLandingHtml(token, actionPath);
+export function buildRedeemLandingHtml(token: string, actionPath: string, redirectBindingToken?: string): string {
+  return BuildRedeemLandingHtml(token, actionPath, redirectBindingToken);
 }

package/src/auth/magicLink/types.ts

@@ -2,6 +2,7 @@
  * @fileoverview Types for the MemberJunction magic-link feature.
  * @module @memberjunction/server/auth/magicLink
  */
+import type { MJMagicLinkInviteEntity } from '@memberjunction/core-entities';
 
 /**
  * One unit of scope a magic-link session holds. The union of these across all links
@@ -113,6 +114,19 @@ export interface CreateMagicLinkInviteParams {
   /** Optional given/family name to seed the provisioned user. */
   firstName?: string;  // case-violation-ok-legacy-back-compat: optional, and the old name is also read off a value the checker cannot type; renaming it stays assignable and silently yields undefined
   lastName?: string;  // case-violation-ok-legacy-back-compat: optional, and the old name is also read off a value the checker cannot type; renaming it stays assignable and silently yields undefined
+  /**
+   * Optional per-invite post-redemption redirect URL. Must match an explicit allowed frontend
+   * origin (`magicLink.explorerUrl`, `magicLink.allowedRedirectOrigins`, or non-wildcard
+   * `cors.allowedOrigins`; wildcard `'*'` is always rejected). Cryptographically bound to the
+   * invite's token hash via RS256 so it cannot be tampered with or swapped across invites.
+   */
+  RedirectUrl?: string;
+  /**
+   * When `false`, skips MJServer's default invite email delivery and returns `rawToken` +
+   * `redemptionUrl` so the caller (e.g. a `BaseServerExtension`) can send its own branded message.
+   * Defaults to `true` when a communication provider is configured.
+   */
+  SendEmail?: boolean;
 }
 
 /** Result of creating an invite. */
@@ -133,11 +147,22 @@ export interface CreateMagicLinkInviteResult {
   expiresAt?: string;  // case-violation-ok-legacy-back-compat: the type crosses a serialization boundary (JSON / HTTP body), so this member name is part of a wire or on-disk shape
   error?: string;  // case-violation-ok-legacy-back-compat: the type crosses a serialization boundary (JSON / HTTP body), so this member name is part of a wire or on-disk shape
   /**
-   * Set when the request was rejected for authorization reasons:
+   * Set when the request was rejected for authorization or validation reasons:
    * `forbidden` — caller may not issue invites; `invalid_role` — the requested
-   * role is not grantable via magic-link. Drives the HTTP status in the router.
+   * role is not grantable via magic-link; `invalid_redirect_url` — `RedirectUrl`
+   * failed HTTP(S) or origin allowlist validation. Drives the HTTP status in the router.
    */
-  errorCode?: 'forbidden' | 'invalid_role';  // case-violation-ok-legacy-back-compat: the type crosses a serialization boundary (JSON / HTTP body), so this member name is part of a wire or on-disk shape
+  errorCode?: 'forbidden' | 'invalid_role' | 'invalid_redirect_url';  // case-violation-ok-legacy-back-compat: the type crosses a serialization boundary (JSON / HTTP body), so this member name is part of a wire or on-disk shape
+}
+
+/** Result of revoking or updating expiry on an existing invite. */
+export interface ManageMagicLinkInviteResult {
+  success: boolean;  // case-violation-ok-legacy-back-compat: matches MagicLink result wire conventions
+  inviteId?: string;  // case-violation-ok-legacy-back-compat: matches MagicLink result wire conventions
+  status?: MJMagicLinkInviteEntity['Status'];  // case-violation-ok-legacy-back-compat: matches MagicLink result wire conventions
+  expiresAt?: string;  // case-violation-ok-legacy-back-compat: matches MagicLink result wire conventions
+  error?: string;  // case-violation-ok-legacy-back-compat: matches MagicLink result wire conventions
+  errorCode?: 'forbidden' | 'not_found' | 'invalid_state' | 'invalid_expiry' | 'server_error';  // case-violation-ok-legacy-back-compat: matches MagicLink result wire conventions
 }
 
 /** Why a redemption failed. */

package/src/auth/newUsers.ts

@@ -195,6 +195,7 @@ export class NewUserBase {
                 Fields: ['ID', 'IsTemplate'],
                 ResultType: 'simple',
                 MaxRows: 1,
+                SkipTotalRowCount: true,
             },
             contextUser
         );

package/src/backgroundSweepConfigUnits.ts

@@ -0,0 +1,213 @@
+import { z } from 'zod';
+
+/**
+ * Settings for the in-process background sweeps that keep an idle MJAPI talking to its database:
+ * the AI Agent Session janitor, the realtime bridge orphan reconciler, the human-handoff offer
+ * expiry sweep, the orphaned conversation detail reconciler and the agent-run watchdog. Each used to start unconditionally on a fixed
+ * interval, so a serverless database (Azure SQL serverless, for one) could never auto-pause. Every
+ * switch is described, with what turning it off costs, in the Serverless Database Auto-Pause guide
+ * (`guides/SERVERLESS_DATABASE_AUTO_PAUSE_GUIDE.md`).
+ *
+ * Like the telemetry and realtime units, the schemas and env-var readers live here rather than in
+ * config.ts so they are unit-testable without config.ts's full dependency graph. The env readers
+ * feed `DEFAULT_SERVER_CONFIG` (the base of the merge), so `mj.config.cjs` still wins over them.
+ */
+
+/** Shipped janitor defaults (the values MJAPI has always used). */
+export const DEFAULT_SESSION_JANITOR_SETTINGS = {
+    enabled: true,
+    sweepIntervalMs: 60_000,
+    closeThresholdMinutes: 15,
+} as const;
+
+/** Shipped realtime bridge orphan reconciler defaults (the values MJAPI has always used). */
+export const DEFAULT_BRIDGE_RECONCILER_SETTINGS = {
+    enabled: true,
+    sweepIntervalMs: 600_000,
+} as const;
+
+/** Shipped human-handoff offer expiry sweep defaults (the values MJAPI has always used). */
+export const DEFAULT_HANDOFF_OFFER_SWEEP_SETTINGS = {
+    enabled: true,
+    sweepIntervalMs: 15_000,
+} as const;
+
+/** Shipped orphaned conversation detail reconciler defaults (the values MJAPI has always used). */
+export const DEFAULT_CONVERSATION_DETAIL_RECONCILER_SETTINGS = {
+    enabled: true,
+    sweepIntervalMs: 300_000,
+} as const;
+
+/** Shipped watchdog defaults (the values MJAPI has always used). */
+export const DEFAULT_AGENT_RUN_WATCHDOG_SETTINGS = {
+    sweepIntervalMs: 300_000,
+    heartbeatIntervalMs: 30_000,
+    staleThresholdMinutes: 5,
+} as const;
+
+/**
+ * `agentSessions.janitor` (env `MJ_SESSION_JANITOR_ENABLED`, `MJ_SESSION_JANITOR_SWEEP_INTERVAL_MS`).
+ * `enabled: false` turns off the periodic tick (stale-session and max-duration close sweeps, then
+ * realtime recording recovery); the one-time startup recovery and the graceful-shutdown drain still
+ * run, so this instance's own orphaned sessions are closed on restart. See the Serverless Database
+ * Auto-Pause guide.
+ */
+export const SessionJanitorSchema = z.object({
+    enabled: z.boolean().optional().default(DEFAULT_SESSION_JANITOR_SETTINGS.enabled),
+    sweepIntervalMs: z.coerce.number().positive().optional().default(DEFAULT_SESSION_JANITOR_SETTINGS.sweepIntervalMs),
+    closeThresholdMinutes: z.coerce.number().positive().optional().default(DEFAULT_SESSION_JANITOR_SETTINGS.closeThresholdMinutes),
+});
+
+/**
+ * `agentSessions.bridgeReconciler` (env `MJ_BRIDGE_RECONCILER_ENABLED`,
+ * `MJ_BRIDGE_RECONCILER_SWEEP_INTERVAL_MS`): closes the realtime bridges an earlier boot of this
+ * instance left open. `enabled: false` keeps the one pass at startup and schedules no repeat. See
+ * the Serverless Database Auto-Pause guide.
+ */
+export const BridgeReconcilerSchema = z.object({
+    enabled: z.boolean().optional().default(DEFAULT_BRIDGE_RECONCILER_SETTINGS.enabled),
+    sweepIntervalMs: z.coerce.number().positive().optional().default(DEFAULT_BRIDGE_RECONCILER_SETTINGS.sweepIntervalMs),
+});
+
+/**
+ * `agentSessions.handoffOfferExpiry` (env `MJ_HANDOFF_OFFER_EXPIRY_ENABLED`,
+ * `MJ_HANDOFF_OFFER_EXPIRY_SWEEP_INTERVAL_MS`): marks agent-to-person handoff offers (`MJ: Interaction
+ * Offers`) `Expired` once past their deadline and tells the person's browser. `enabled: false` stops
+ * the periodic read; overdue offers still read as expired everywhere, but their rows stay `Pending`
+ * and no expiry notice is pushed. See the Serverless Database Auto-Pause guide.
+ */
+export const HandoffOfferSweepSchema = z.object({
+    enabled: z.boolean().optional().default(DEFAULT_HANDOFF_OFFER_SWEEP_SETTINGS.enabled),
+    sweepIntervalMs: z.coerce.number().positive().optional().default(DEFAULT_HANDOFF_OFFER_SWEEP_SETTINGS.sweepIntervalMs),
+});
+
+/** `agentSessions`: settings for AI Agent Sessions (realtime/voice and other long-lived agent sessions). */
+export const AgentSessionsSchema = z.object({
+    janitor: SessionJanitorSchema.optional().default({}),
+    bridgeReconciler: BridgeReconcilerSchema.optional().default({}),
+    handoffOfferExpiry: HandoffOfferSweepSchema.optional().default({}),
+});
+
+/**
+ * `conversationDetailReconciler` (env `MJ_CONVERSATION_DETAIL_RECONCILER_ENABLED`,
+ * `MJ_CONVERSATION_DETAIL_RECONCILER_SWEEP_INTERVAL_MS`): closes conversation details a run that
+ * already ended left `In-Progress`. `enabled: false` keeps the one pass at startup and schedules no
+ * repeat. See the Serverless Database Auto-Pause guide.
+ */
+export const ConversationDetailReconcilerSchema = z.object({
+    enabled: z.boolean().optional().default(DEFAULT_CONVERSATION_DETAIL_RECONCILER_SETTINGS.enabled),
+    sweepIntervalMs: z.coerce.number().positive().optional().default(DEFAULT_CONVERSATION_DETAIL_RECONCILER_SETTINGS.sweepIntervalMs),
+});
+
+/**
+ * `agentRunWatchdog` (env `MJ_AGENT_RUN_WATCHDOG_SWEEP_INTERVAL_MS`). The heartbeat runs only while
+ * this process has an agent run in flight; once any run has been tracked, the stale-run sweep keeps
+ * running every `sweepIntervalMs` so it also closes runs other, crashed instances left `Running`.
+ * `sweepIntervalMs: 0` turns the periodic sweep off; the startup sweep still runs. See the
+ * Serverless Database Auto-Pause guide.
+ */
+export const AgentRunWatchdogSchema = z.object({
+    sweepIntervalMs: z.coerce.number().nonnegative().optional().default(DEFAULT_AGENT_RUN_WATCHDOG_SETTINGS.sweepIntervalMs),
+    heartbeatIntervalMs: z.coerce.number().positive().optional().default(DEFAULT_AGENT_RUN_WATCHDOG_SETTINGS.heartbeatIntervalMs),
+    staleThresholdMinutes: z.coerce.number().positive().optional().default(DEFAULT_AGENT_RUN_WATCHDOG_SETTINGS.staleThresholdMinutes),
+});
+
+export type SessionJanitorSettings = z.infer<typeof SessionJanitorSchema>;
+export type BridgeReconcilerSettings = z.infer<typeof BridgeReconcilerSchema>;
+export type HandoffOfferSweepSettings = z.infer<typeof HandoffOfferSweepSchema>;
+export type AgentSessionsSettings = z.infer<typeof AgentSessionsSchema>;
+export type ConversationDetailReconcilerSettings = z.infer<typeof ConversationDetailReconcilerSchema>;
+export type AgentRunWatchdogSettings = z.infer<typeof AgentRunWatchdogSchema>;
+
+const TRUE_VALUES: ReadonlySet<string> = new Set(['true', '1', 'yes', 'y', 'on', 't']);
+const FALSE_VALUES: ReadonlySet<string> = new Set(['false', '0', 'no', 'n', 'off', 'f']);
+
+/**
+ * Reads an on/off switch from an env var, returning `fallback` when it is unset or blank (so an
+ * empty variable exported by a deployment script cannot silently flip it). Accepts
+ * `true/false`, `1/0`, `yes/no`, `y/n`, `on/off`, `t/f` in any case; throws, naming the variable,
+ * on anything else, so a typo fails at startup instead of silently turning a sweep off.
+ *
+ * @param name The variable's name, for the error message.
+ * @param rawEnvValue The variable's raw value.
+ * @param fallback The value when the variable is unset or blank.
+ */
+export function EnabledFromEnv(name: string, rawEnvValue: string | undefined | null, fallback: boolean): boolean {
+    const normalized = rawEnvValue?.trim().toLowerCase();
+    if (!normalized) {
+        return fallback;
+    }
+    if (TRUE_VALUES.has(normalized)) {
+        return true;
+    }
+    if (FALSE_VALUES.has(normalized)) {
+        return false;
+    }
+    throw new Error(`Invalid ${name} "${rawEnvValue}". Expected true or false.`);
+}
+
+/**
+ * Reads a millisecond interval from an env var, returning `fallback` when it is unset or blank.
+ * Throws, naming the variable, on anything that is not a finite number in range, so a deployment
+ * typo fails at startup instead of silently running the default (or a zero-delay timer).
+ *
+ * @param name The variable's name, for the error message.
+ * @param rawEnvValue The variable's raw value.
+ * @param fallback The value when the variable is unset or blank.
+ * @param allowZero Whether `0` is accepted (it means "off" for the settings that allow it).
+ */
+export function IntervalMsFromEnv(name: string, rawEnvValue: string | undefined | null, fallback: number, allowZero: boolean): number {
+    const trimmed = rawEnvValue?.trim();
+    if (!trimmed) {
+        return fallback;
+    }
+    const value = Number(trimmed);
+    const inRange = allowZero ? value >= 0 : value > 0;
+    if (!Number.isFinite(value) || !inRange) {
+        const rule = allowZero ? 'a number of milliseconds, 0 or greater' : 'a number of milliseconds greater than 0';
+        throw new Error(`Invalid ${name} "${rawEnvValue}". Expected ${rule}.`);
+    }
+    return value;
+}
+
+/** The env vars each background sweep reads, keyed by what they set. */
+type SweepEnv = Readonly<Record<string, string | undefined>>;
+
+/** `enabled` + `sweepIntervalMs` for one sweep, read from `<prefix>_ENABLED` and `<prefix>_SWEEP_INTERVAL_MS`. */
+function enabledSweepFromEnv(env: SweepEnv, prefix: string, defaults: { enabled: boolean; sweepIntervalMs: number }): { enabled: boolean; sweepIntervalMs: number } {
+    return {
+        enabled: EnabledFromEnv(`${prefix}_ENABLED`, env[`${prefix}_ENABLED`], defaults.enabled),
+        sweepIntervalMs: IntervalMsFromEnv(`${prefix}_SWEEP_INTERVAL_MS`, env[`${prefix}_SWEEP_INTERVAL_MS`], defaults.sweepIntervalMs, false),
+    };
+}
+
+/** The `agentSessions` block of `DEFAULT_SERVER_CONFIG`, from the environment and the shipped defaults. */
+export function AgentSessionsDefaultsFromEnv(env: SweepEnv): AgentSessionsSettings {
+    return {
+        janitor: {
+            ...enabledSweepFromEnv(env, 'MJ_SESSION_JANITOR', DEFAULT_SESSION_JANITOR_SETTINGS),
+            closeThresholdMinutes: DEFAULT_SESSION_JANITOR_SETTINGS.closeThresholdMinutes,
+        },
+        bridgeReconciler: enabledSweepFromEnv(env, 'MJ_BRIDGE_RECONCILER', DEFAULT_BRIDGE_RECONCILER_SETTINGS),
+        handoffOfferExpiry: enabledSweepFromEnv(env, 'MJ_HANDOFF_OFFER_EXPIRY', DEFAULT_HANDOFF_OFFER_SWEEP_SETTINGS),
+    };
+}
+
+/** The `conversationDetailReconciler` block of `DEFAULT_SERVER_CONFIG`. */
+export function ConversationDetailReconcilerDefaultsFromEnv(env: SweepEnv): ConversationDetailReconcilerSettings {
+    return enabledSweepFromEnv(env, 'MJ_CONVERSATION_DETAIL_RECONCILER', DEFAULT_CONVERSATION_DETAIL_RECONCILER_SETTINGS);
+}
+
+/** The `agentRunWatchdog` block of `DEFAULT_SERVER_CONFIG`. */
+export function AgentRunWatchdogDefaultsFromEnv(env: SweepEnv): AgentRunWatchdogSettings {
+    return {
+        sweepIntervalMs: IntervalMsFromEnv(
+            'MJ_AGENT_RUN_WATCHDOG_SWEEP_INTERVAL_MS',
+            env.MJ_AGENT_RUN_WATCHDOG_SWEEP_INTERVAL_MS,
+            DEFAULT_AGENT_RUN_WATCHDOG_SETTINGS.sweepIntervalMs,
+            true
+        ),
+        heartbeatIntervalMs: DEFAULT_AGENT_RUN_WATCHDOG_SETTINGS.heartbeatIntervalMs,
+        staleThresholdMinutes: DEFAULT_AGENT_RUN_WATCHDOG_SETTINGS.staleThresholdMinutes,
+    };
+}