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

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
@@ -58,6 +59,16 @@ export interface MagicLinkJWTClaims {
   mj_anon?: boolean;  // case-violation-ok-legacy-back-compat: snake_case mirrors an external payload — the remote spelling is the contract, not MJ convention
   /** Opaque per-session id — correlates one anonymous session's activity across audit rows without a real user. */
   mj_sid?: string;  // case-violation-ok-legacy-back-compat: snake_case mirrors an external payload — the remote spelling is the contract, not MJ convention
+  /**
+   * When `mj_sid` was first minted (epoch seconds). Set on widget guest tokens and copied unchanged by every
+   * refresh, so the server can refuse to renew a session past its hard end (`MAX_GUEST_SESSION_SECONDS`).
+   */
+  mj_sid_iat?: number;  // case-violation-ok-legacy-back-compat: snake_case mirrors an external payload — the remote spelling is the contract, not MJ convention
+  /**
+   * Confirmation (RFC 7800 / RFC 9449): the RFC 7638 thumbprint of the key the widget registered at mint.
+   * Refreshing a widget guest token requires a proof signed by that key, so a copied token cannot be renewed.
+   */
+  cnf?: { jkt: string };  // case-violation-ok-legacy-back-compat: the claim name is fixed by RFC 7800, part of the wire shape
   /**
    * Public web widget instance id (additive — set only for widget guest sessions
    * minted by WidgetSessionService). Binds the synthesized guest principal to one
@@ -103,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. */
@@ -123,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/auth/sessionUserClone.ts

@@ -7,7 +7,7 @@
  * concurrent session of the same user THE INSTANT it is written; this is
  * same-moment cross-request aliasing, not a cache-staleness problem. The
  * magic-link path has always cloned for exactly this reason (see
- * buildMagicLinkSessionUser in context.ts); this helper makes that rule a
+ * BuildMagicLinkSessionUser in context.ts); this helper makes that rule a
  * single shared primitive so every per-session stamp goes through the same
  * clone.
  *
@@ -30,7 +30,7 @@ import { Metadata, UserInfo } from '@memberjunction/core';
  * state on the clone; never stamp the input itself.
  */
 export function CloneUserForSessionContext(user: UserInfo): UserInfo {
-  const md = Metadata.Provider; // global-provider-ok: server-side session construction under the server's single default provider, same as buildMagicLinkSessionUser
+  const md = Metadata.Provider; // global-provider-ok: server-side session construction under the server's single default provider, same as BuildMagicLinkSessionUser
   const clone = new UserInfo(md, {
     ...user,
     _UserRoles: undefined,
@@ -44,6 +44,7 @@ export function CloneUserForSessionContext(user: UserInfo): UserInfo {
   clone.ReturningVisitorContext = user.ReturningVisitorContext;
   clone.WidgetGuestContext = user.WidgetGuestContext;
   clone.IsMagicLinkAnonymous = user.IsMagicLinkAnonymous;
+  clone.AnonymousVisitorID = user.AnonymousVisitorID;
   clone.APIKeyActingContext = user.APIKeyActingContext;
   clone.APIKeyRowFilters = user.APIKeyRowFilters;
   return clone;

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