@memberjunction/server 5.44.0 → 5.45.1

package/src/generic/ResolverBase.ts

@@ -194,6 +194,34 @@ export class ResolverBase {
     return dataObjectArray;
   }
 
+  /**
+   * Loads a single external-data-source-backed entity record by primary key and returns it in
+   * GraphQL field-name (CodeName) shape, or null if not found.
+   *
+   * External entities (`Entity.ExternalDataSourceID` set) have no MJ base view or sproc — their
+   * data is proxied live from a remote system — so the generated single-record resolver cannot run
+   * `SELECT * FROM <baseView>`. Instead it loads through a BaseEntity object, whose `InnerLoad`
+   * the data provider dispatches to the external read router's `LoadExternalRecord` (a composite-key
+   * aware, quoted, parameter-bound single-record lookup), applying the same RLS gate and field
+   * post-processing (decryption / datetime normalization) as the MJ-DB path. The caller is
+   * responsible for the `CheckUserReadPermissions` gate beforehand.
+   */
+  protected async LoadExternalRecordByKey<T>(
+    entityName: string,
+    compositeKey: CompositeKey,
+    provider: DatabaseProviderBase,
+    userPayload: UserPayload,
+  ): Promise<T | null> {
+    const contextUser = this.GetUserFromPayload(userPayload);
+    const entityObject = await provider.GetEntityObject(entityName, contextUser);
+    const loaded = await entityObject.InnerLoad(compositeKey);
+    if (!loaded) {
+      return null;
+    }
+    const mapped = await this.MapFieldNamesToCodeNames(entityName, entityObject.GetAll(), contextUser);
+    return mapped as T;
+  }
+
   /**
    * Filters encrypted field values before sending to the API client.
    *

package/src/generic/RunViewResolver.ts

@@ -715,6 +715,7 @@ export class RunViewResolver extends ResolverBase {
     pubSub: PubSubEngine
   ) {
     try {
+      await this.CheckAPIKeyScopeAuthorization('view:run', input.ViewName, userPayload);
       const provider = GetReadOnlyProvider(providers, { allowFallbackToReadWrite: true });
       const rawData = await super.RunViewByNameGeneric(input, provider, userPayload, pubSub);
       if (rawData === null) 
@@ -746,6 +747,7 @@ export class RunViewResolver extends ResolverBase {
     pubSub: PubSubEngine
   ) {
     try {
+      await this.CheckAPIKeyScopeAuthorization('view:run', input.ViewID, userPayload);
       const provider = GetReadOnlyProvider(providers, { allowFallbackToReadWrite: true });
       const rawData = await super.RunViewByIDGeneric(input, provider, userPayload, pubSub);
       if (rawData === null) 
@@ -777,6 +779,7 @@ export class RunViewResolver extends ResolverBase {
     pubSub: PubSubEngine
   ) {
     try {
+      await this.CheckAPIKeyScopeAuthorization('view:run', input.EntityName, userPayload);
       const provider = GetReadOnlyProvider(providers, { allowFallbackToReadWrite: true });
       const rawData = await super.RunDynamicViewGeneric(input, provider, userPayload, pubSub);
       if (rawData === null) return null;
@@ -806,6 +809,7 @@ export class RunViewResolver extends ResolverBase {
     pubSub: PubSubEngine
   ) {
     try {
+      await this.CheckAPIKeyScopeAuthorization('view:batch', '*', userPayload);
       const provider = GetReadOnlyProvider(providers, { allowFallbackToReadWrite: true });
       // Note: RunViewsGeneric returns the core RunViewResult type, not the GraphQL type
       const rawData = await super.RunViewsGeneric(input, provider, userPayload);

package/src/index.ts

@@ -41,7 +41,13 @@ import { setupRESTEndpoints } from './rest/setupRESTEndpoints.js';
 import { createOAuthCallbackHandler } from './rest/OAuthCallbackHandler.js';
 import { createSignatureWebhookHandler } from './rest/SignatureWebhookHandler.js';
 import { createMediaStreamRouter } from './rest/MediaStreamHandler.js';
-import { createMagicLinkHandler, registerMagicLinkAuthProvider, MAGIC_LINK_MOUNT_PATH } from './auth/magicLink/index.js';
+import { createMagicLinkHandler, createMagicLinkJwksRouter, registerMagicLinkAuthProvider, MAGIC_LINK_MOUNT_PATH } from './auth/magicLink/index.js';
+import { createWidgetHandler, WIDGET_MOUNT_PATH } from './realtimeWidget/index.js';
+import { createTwilioTelephonyHandler, TWILIO_TELEPHONY_MOUNT_PATH, SetTwilioTelephonyService } from './telephony/index.js';
+import { createVonageTelephonyHandler, VONAGE_TELEPHONY_MOUNT_PATH, SetVonageTelephonyService } from './telephony/index.js';
+import { RingCentralTelephonyService, SetRingCentralTelephonyService } from './telephony/index.js';
+import { createTeamsMeetingsHandler, TEAMS_MEETINGS_MOUNT_PATH, SetTeamsMeetingsService, GetTeamsMeetingsService, StartCalendarScheduler } from './telephony/index.js';
+import { InstallMediaUpgradeDispatcher } from './telephony/index.js';
 
 import { resolve } from 'node:path';
 import { DataSourceInfo, raiseEvent } from './types.js';
@@ -132,8 +138,6 @@ export * from './generic/KeyInputOutputTypes.js';
 export * from './generic/DeleteOptionsInput.js';
 export * from './generic/RestoreContextInput.js';
 
-export * from './agents/skip-agent.js';
-export * from './agents/skip-sdk.js';
 
 export * from './resolvers/GeoResolver.js';
 export * from './resolvers/ColorResolver.js';
@@ -1004,6 +1008,7 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
   // ─── Magic-link routes (MJ-issued, app-scoped external access) ───────────
   // Public router (JWKS + redeem) mounts BEFORE the auth middleware; the
   // authenticated invite-creation router mounts AFTER it (see below).
+  let widgetAuthenticatedRouter: ReturnType<typeof createWidgetHandler>['authenticatedRouter'] | undefined;
   let magicLinkAuthenticatedRouter: ReturnType<typeof createMagicLinkHandler>['authenticatedRouter'] | undefined;
   if (configInfo.magicLink?.enabled) {
     const { publicRouter, authenticatedRouter } = createMagicLinkHandler(oauthPublicUrl, configInfo.magicLink);
@@ -1013,6 +1018,82 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     startupLog.LogIf('verbose', `[MagicLink] Public routes registered at ${MAGIC_LINK_MOUNT_PATH}/redeem and ${MAGIC_LINK_MOUNT_PATH}/jwks.json`);
   }
 
+  // ─── Public web widget: guest-session mint (PUBLIC, before auth mw) ───────
+  // Visitors hold no MJ JWT yet, so POST /widget/session is public. It reuses the
+  // magic-link RS256 key + `magic-link` auth provider (ensured idempotently inside
+  // createWidgetHandler), so it stands on its own even if magicLink.enabled is false.
+  if (configInfo.widget?.enabled) {
+    const { publicRouter: widgetRouter, authenticatedRouter: widgetAuthRouter } = createWidgetHandler(oauthPublicUrl, configInfo.widget);
+    widgetAuthenticatedRouter = widgetAuthRouter;
+    app.use(WIDGET_MOUNT_PATH, cors<cors.CorsRequest>(), widgetRouter);
+    // The widget reuses the magic-link RS256 key + auth provider to validate guest
+    // tokens, which validates by fetching the JWKS at MAGIC_LINK_MOUNT_PATH/jwks.json.
+    // When magic-link itself is disabled its public router (which serves JWKS) never
+    // mounts, so publish the key here — otherwise every guest token fails validation
+    // (the auth middleware can't fetch the public key) and the widget 401s.
+    if (!configInfo.magicLink?.enabled) {
+      app.use(MAGIC_LINK_MOUNT_PATH, cors<cors.CorsRequest>(), createMagicLinkJwksRouter());
+      startupLog.LogIf('verbose', `[Widget] Published reused signing key at ${MAGIC_LINK_MOUNT_PATH}/jwks.json (magic-link flow disabled)`);
+    }
+    startupLog.LogIf('verbose', `[Widget] Public routes registered at ${WIDGET_MOUNT_PATH}/session and ${WIDGET_MOUNT_PATH}/session/refresh`);
+  }
+
+  // ─── Telephony (Twilio) ingress: inbound voice webhook + Media-Streams WSS (PUBLIC) ──
+  // Carriers cannot present an MJ JWT — the X-Twilio-Signature HMAC is the gate. The
+  // public webhook router mounts BEFORE the auth middleware; the Media-Streams WSS attaches
+  // to the shared HTTP server. The outbound PlaceTwilioCall mutation reuses the same service.
+  if (configInfo.telephony?.enabled && configInfo.telephony.twilio) {
+    const twilioHandler = createTwilioTelephonyHandler(oauthPublicUrl, configInfo.telephony.twilio);
+    app.use(TWILIO_TELEPHONY_MOUNT_PATH, cors<cors.CorsRequest>(), twilioHandler.publicRouter);
+    twilioHandler.attachMediaStreamServer();
+    SetTwilioTelephonyService(twilioHandler.service);
+    startupLog.LogIf('verbose', `[Telephony] Twilio routes registered at ${TWILIO_TELEPHONY_MOUNT_PATH}/voice + Media-Streams WSS`);
+  }
+
+  // ─── Telephony (Vonage) ingress: inbound answer/event webhooks + media WSS (PUBLIC) ──
+  // Carriers cannot present an MJ JWT — the Vonage signed-request HMAC / webhook JWT is the gate.
+  // The public router mounts BEFORE the auth middleware; the media WSS attaches to the shared
+  // HTTP server. The outbound PlaceVonageCall mutation reuses the same service.
+  if (configInfo.telephony?.enabled && configInfo.telephony.vonage) {
+    const vonageHandler = createVonageTelephonyHandler(oauthPublicUrl, configInfo.telephony.vonage);
+    app.use(VONAGE_TELEPHONY_MOUNT_PATH, cors<cors.CorsRequest>(), vonageHandler.publicRouter);
+    vonageHandler.attachMediaStreamServer();
+    SetVonageTelephonyService(vonageHandler.service);
+    startupLog.LogIf('verbose', `[Telephony] Vonage routes registered at ${VONAGE_TELEPHONY_MOUNT_PATH}/answer + /event + media WSS`);
+  }
+
+  // ─── Telephony (RingCentral) ingress: SIP softphone registration (no HTTP webhook / media WSS) ──
+  // RingCentral's only bidirectional-audio transport is a registered SIP softphone — inbound calls arrive
+  // as SIP INVITEs on its own SIP/TLS connection, so there is no public webhook or media WSS to mount.
+  // start() registers the softphone fire-and-forget so SIP registration never blocks boot; the outbound
+  // PlaceRingCentralCall mutation reuses the same service via the runtime holder.
+  if (configInfo.telephony?.enabled && configInfo.telephony.ringcentral) {
+    const ringCentralService = new RingCentralTelephonyService(configInfo.telephony.ringcentral);
+    SetRingCentralTelephonyService(ringCentralService);
+    void ringCentralService.start();
+    startupLog.LogIf('verbose', `[Telephony] RingCentral SIP softphone starting (codec ${configInfo.telephony.ringcentral.codec ?? 'OPUS/16000'})`);
+  }
+
+  // ─── Teams meetings ingress: Graph change-notification webhook (PUBLIC) ──────────────
+  // Graph cannot present an MJ JWT — the subscription validationToken handshake + the per-
+  // notification clientState shared secret are the gate. The public webhook router mounts
+  // BEFORE the auth middleware. The ACS application-hosted-media audio plane is owned by the
+  // server's native ACS media adapter, which attaches transports to the shared registry
+  // (a media WSS is not needed here). The StartTeamsMeetingSession mutation reuses the same
+  // service via the runtime holder.
+  if (configInfo.telephony?.enabled && configInfo.telephony.teams?.enabled) {
+    const teamsHandler = createTeamsMeetingsHandler(configInfo.telephony.teams);
+    app.use(TEAMS_MEETINGS_MOUNT_PATH, cors<cors.CorsRequest>(), teamsHandler.publicRouter);
+    SetTeamsMeetingsService(teamsHandler.service);
+    startupLog.LogIf('verbose', `[Meetings] Teams routes registered at ${TEAMS_MEETINGS_MOUNT_PATH}/notifications`);
+  }
+
+  // Install the single path-routing WebSocket-upgrade dispatcher AFTER all media WSS routes have
+  // registered. ws 8.x has each {server}-bound WebSocketServer 400 paths it doesn't own, so the GraphQL
+  // socket and the telephony media sockets cannot coexist as separate {server} servers — this strips the
+  // auto-listeners and routes upgrades by path. No-op when no media routes registered (telephony off).
+  InstallMediaUpgradeDispatcher(httpServer, webSocketServer, graphqlRootPath);
+
   // ─── Global CORS (before auth so 401 responses include CORS headers) ─────
   // Without this, the browser blocks 401 responses from the auth middleware
   // because they lack Access-Control-Allow-Origin headers, preventing the
@@ -1073,6 +1154,14 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     startupLog.LogIf('verbose', `[MagicLink] Authenticated route registered at ${MAGIC_LINK_MOUNT_PATH}/create`);
   }
 
+  // ─── Widget authenticated route (RV4 resolve-identity) ────────────────────
+  // Mounts after the unified auth middleware so a verified visitor (post magic-link upgrade) can
+  // promote their anonymous returning-visitor trail to the verified record.
+  if (widgetAuthenticatedRouter) {
+    app.use(WIDGET_MOUNT_PATH, cors<cors.CorsRequest>(), widgetAuthenticatedRouter);
+    startupLog.LogIf('verbose', `[Widget] Authenticated route registered at ${WIDGET_MOUNT_PATH}/resolve-identity`);
+  }
+
   // ─── REST API endpoints (auth already handled by unified middleware) ─────
   const restApiConfig = {
     enabled: configInfo.restApiOptions?.enabled ?? false,
@@ -1193,6 +1282,23 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
       .catch(err => console.warn(`[SessionJanitor] Startup failed: ${err}`));
   }
 
+  // Launch the calendar / scheduled-bridge loop (M2): poll agent calendars for meeting invites and
+  // start due meeting bridges. Mirrors the SessionJanitor lifecycle (run-once + interval, timer
+  // unref'd). Gated on Teams meetings being enabled (the provider whose scheduled-join is wired) and
+  // reuses the SAME meetings service as the ingress; identities without configured calendar creds are
+  // skipped, so this is a harmless no-op until a Graph-backed identity + token are configured.
+  if (resumeUser && configInfo.telephony?.teams?.enabled) { // global-provider-ok: server-owned background poller under the server's provider + system user
+    const teamsMeetingsService = GetTeamsMeetingsService();
+    if (teamsMeetingsService) {
+      StartCalendarScheduler({
+        Provider: Metadata.Provider, // global-provider-ok: server-owned background poller under the server's single default provider + system user
+        ContextUser: resumeUser,
+        TeamsService: teamsMeetingsService,
+        TeamsConfig: configInfo.telephony.teams,
+      });
+    }
+  }
+
   // Set up graceful shutdown handlers
   const gracefulShutdown = async (signal: string) => {
     console.log(`\n${signal} received, shutting down gracefully...`);

package/src/integration/CustomColumnPromoter.ts

@@ -217,6 +217,12 @@ export class IntegrationCustomColumnPromoter {
         const overflowJson = await this.scanOverflow(entityName);
         if (overflowJson.length === 0) return null; // no customs captured
 
+        // U3 note (rkihm-BC review, #3061): this in-repo promotion path passes no `LockUntilFullSync`, so it
+        // does NOT yet enforce "hold promotion until a full sync since the last schema change." The lever
+        // exists on `PromotionPlanOptions`, but pulling it here requires this caller to know whether a full
+        // sync has completed post-rediscovery — DEFERRED and tracked as a follow-up. The engine ships the
+        // gate; wiring MJServer's own consumer to set it is a separate change. Until then, this path retains
+        // the pre-U3 behavior for a rediscover-then-incremental sequence.
         const passing = planPromotions(buildOverflowStats(overflowJson), {});
         if (passing.length === 0) return null;
 

package/src/realtimeWidget/WidgetRouter.ts

@@ -0,0 +1,204 @@
+/**
+ * @fileoverview Express wiring for the public web widget guest-session endpoints.
+ *
+ * Mirrors the magic-link public-router pattern: a single PUBLIC router
+ * (unauthenticated) mounted BEFORE the unified auth middleware. The widget reuses
+ * the magic-link RS256 key + the registered `magic-link` auth provider for token
+ * validation, so this module ensures both are initialized (idempotently) even when
+ * `magicLink.enabled` is false — the widget can stand on its own.
+ *
+ * @module @memberjunction/server/widget
+ */
+
+import { Router, json, type Request, type Response } from 'express';
+import { rateLimit } from 'express-rate-limit';
+import { LogStatus } from '@memberjunction/core';
+import { configInfo, type WidgetConfig } from '../config.js';
+import { MagicLinkKeyManager } from '../auth/magicLink/MagicLinkKeys.js';
+import { registerMagicLinkAuthProvider } from '../auth/magicLink/MagicLinkRouter.js';
+import { WidgetSessionService, type MintGuestSessionResult } from './WidgetSessionService.js';
+import { looksLikeBot } from './widgetCore.js';
+
+/** The mount path for the widget public router (`/widget`). */
+export const WIDGET_MOUNT_PATH = '/widget';
+
+/**
+ * Ensures the magic-link signing key is initialized and the `magic-link` auth
+ * provider is registered, so widget tokens (signed with that key) validate. Safe to
+ * call when magic-link is already enabled — both operations are idempotent.
+ */
+function ensureWidgetSigning(publicUrl: string, widgetConfig: WidgetConfig): void {
+  const mlConfig = configInfo.magicLink;
+  // The widget shares the magic-link audience so the same provider validates its
+  // tokens; surface a clear log if a deployment diverged them.
+  if (mlConfig?.audience && mlConfig.audience !== widgetConfig.audience) {
+    LogStatus(
+      `[Widget] WARNING: widget.audience ('${widgetConfig.audience}') != magicLink.audience ('${mlConfig.audience}'). ` +
+      `Widget tokens will not validate unless an auth provider is registered for the widget audience.`,
+    );
+  }
+  MagicLinkKeyManager.Instance.Initialize(mlConfig?.rsaPrivateKey);
+  // Register the magic-link provider against the magic-link config (its audience),
+  // which is what validates widget tokens. No-op if already registered.
+  if (mlConfig) {
+    registerMagicLinkAuthProvider(publicUrl, mlConfig);
+  }
+}
+
+/**
+ * Builds the widget routers. Mount `publicRouter` at WIDGET_MOUNT_PATH BEFORE the unified auth
+ * middleware (the mint/forget endpoints are public — visitors have no MJ JWT yet) and
+ * `authenticatedRouter` at the same path AFTER it (the RV4 resolve-identity endpoint needs the
+ * verified principal from `req.userPayload`).
+ */
+export function createWidgetHandler(publicUrl: string, config: WidgetConfig): { publicRouter: Router; authenticatedRouter: Router } {
+  ensureWidgetSigning(publicUrl, config);
+
+  const service = new WidgetSessionService(publicUrl, config);
+
+  // Per-instance DYNAMIC mint limiter (W6 hardening): keyed by (widgetKey + IP) so each widget
+  // deployment gets its own bucket and one abusive IP can't exhaust a shared instance's budget for
+  // everyone. The per-request `limit` is the widget instance's stored `RateLimitPerMinute` (cached,
+  // resolved from the parsed body), falling back to the deployment-wide default for an unknown key.
+  // `json()` runs FIRST so the key generator + limit can read `req.body.widgetKey`.
+  const mintLimiter = rateLimit({
+    windowMs: config.rateLimitWindowMs,
+    standardHeaders: 'draft-7',
+    legacyHeaders: false,
+    keyGenerator: (req: Request) => `${readWidgetKey(req)}:${req.ip ?? 'noip'}`,
+    limit: async (req: Request) => service.ResolvePerInstanceRateLimit(readWidgetKey(req)),
+    message: { success: false, errorCode: 'rate_limited', error: 'Too many widget session requests. Try again later.' },
+  });
+
+  const publicRouter = Router();
+
+  publicRouter.post('/session', json(), mintLimiter, async (req: Request, res: Response) => {
+    await handleMint(service, req, res, false);
+  });
+
+  publicRouter.post('/session/refresh', json(), mintLimiter, async (req: Request, res: Response) => {
+    await handleMint(service, req, res, true);
+  });
+
+  // W5 magic-link upgrade ("Verify it's you"): emails a verification link scoped to the widget's app.
+  // Same dynamic limiter as mint — it issues an email invite, a comparable cost/abuse surface.
+  publicRouter.post('/upgrade', json(), mintLimiter, async (req: Request, res: Response) => {
+    await handleUpgrade(service, req, res);
+  });
+
+  // RV5 "forget me": archive the visitor's memory + clear the VisitorKey linkage. Public — the visitor
+  // proves possession of the durable key (not an identity). Same dynamic limiter as mint.
+  publicRouter.post('/forget', json(), mintLimiter, async (req: Request, res: Response) => {
+    await handleForget(service, req, res);
+  });
+
+  // RV4 resolve-identity: promote the visitor's anonymous trail to the verified record. AUTHENTICATED —
+  // it reads the verified principal's email from req.userPayload, so it mounts after the auth middleware.
+  const authenticatedRouter = Router();
+  authenticatedRouter.post('/resolve-identity', json(), mintLimiter, async (req: Request, res: Response) => {
+    await handleResolveIdentity(service, req, res);
+  });
+
+  return { publicRouter, authenticatedRouter };
+}
+
+/** Reads the `widgetKey` from a parsed JSON body, or '' when absent (used to key the dynamic limiter). */
+function readWidgetKey(req: Request): string {
+  const body = (req.body ?? {}) as { widgetKey?: string };
+  return typeof body.widgetKey === 'string' ? body.widgetKey.trim() : '';
+}
+
+/** Handles "forget me" (RV5) — parses the body, calls the service, maps the status. */
+async function handleForget(service: WidgetSessionService, req: Request, res: Response): Promise<void> {
+  const body = (req.body ?? {}) as { widgetKey?: string; visitorKey?: string };
+  const widgetKey = typeof body.widgetKey === 'string' ? body.widgetKey : '';
+  const visitorKey = typeof body.visitorKey === 'string' ? body.visitorKey : '';
+  if (!widgetKey) {
+    res.status(400).json({ success: false, errorCode: 'not_found', error: 'widgetKey is required.' });
+    return;
+  }
+  const result = await service.ForgetVisitor({ widgetKey, visitorKey, origin: req.get('origin') ?? undefined });
+  res.status(result.success ? 200 : result.errorCode === 'server_error' ? 500 : 403).json(result);
+}
+
+/**
+ * Handles RV4 resolve-identity — reads the verified email from the authenticated principal
+ * (`req.userPayload.userRecord`), parses the body, calls the service, maps the status.
+ */
+async function handleResolveIdentity(service: WidgetSessionService, req: Request, res: Response): Promise<void> {
+  const verifiedUser = req.userPayload?.userRecord;
+  if (!verifiedUser?.Email) {
+    res.status(401).json({ success: false, errorCode: 'server_error', error: 'Authentication required.' });
+    return;
+  }
+  const body = (req.body ?? {}) as { widgetKey?: string; visitorKey?: string };
+  const widgetKey = typeof body.widgetKey === 'string' ? body.widgetKey : '';
+  const visitorKey = typeof body.visitorKey === 'string' ? body.visitorKey : '';
+  if (!widgetKey) {
+    res.status(400).json({ success: false, errorCode: 'not_found', error: 'widgetKey is required.' });
+    return;
+  }
+  const result = await service.ResolveVisitorIdentity({
+    widgetKey,
+    visitorKey,
+    verifiedEmail: verifiedUser.Email,
+    origin: req.get('origin') ?? undefined,
+  });
+  res.status(result.success ? 200 : result.errorCode === 'server_error' ? 500 : 403).json(result);
+}
+
+/** Handles the magic-link upgrade request — parses the body, calls the service, maps the status. */
+async function handleUpgrade(service: WidgetSessionService, req: Request, res: Response): Promise<void> {
+  const body = (req.body ?? {}) as { widgetKey?: string; email?: string };
+  const widgetKey = typeof body.widgetKey === 'string' ? body.widgetKey : '';
+  const email = typeof body.email === 'string' ? body.email : '';
+  if (!widgetKey) {
+    res.status(400).json({ success: false, errorCode: 'not_found', error: 'widgetKey is required.' });
+    return;
+  }
+  const result = await service.RequestUpgrade({ widgetKey, email, origin: req.get('origin') ?? undefined });
+  // 400 for a bad email (client can fix it); 403 for any policy rejection (uniform, non-enumerable); 500 for faults.
+  const status = result.success ? 200 : result.errorCode === 'invalid_email' ? 400 : result.errorCode === 'server_error' ? 500 : 403;
+  res.status(status).json(result);
+}
+
+/** Shared mint/refresh handler — parses the request, calls the service, maps the status. */
+async function handleMint(service: WidgetSessionService, req: Request, res: Response, refresh: boolean): Promise<void> {
+  const body = (req.body ?? {}) as { widgetKey?: string; hostAssertion?: string; visitorKey?: string };
+  const widgetKey = typeof body.widgetKey === 'string' ? body.widgetKey : '';
+  if (!widgetKey) {
+    res.status(400).json({ success: false, errorCode: 'not_found', error: 'widgetKey is required.' });
+    return;
+  }
+
+  // W6 hardening: coarse bot/automation rejection before any DB lookup or token mint. Returns the same
+  // 403 as a policy rejection so a probe can't distinguish "bot-blocked" from "bad key/origin".
+  if (looksLikeBot(req.get('user-agent'))) {
+    res.status(403).json({ success: false, errorCode: 'origin_not_allowed', error: 'Widget mint rejected.' });
+    return;
+  }
+
+  const origin = req.get('origin') ?? undefined;
+  const input = {
+    widgetKey,
+    origin,
+    hostAssertion: typeof body.hostAssertion === 'string' ? body.hostAssertion : undefined,
+    visitorKey: typeof body.visitorKey === 'string' ? body.visitorKey : undefined,
+    audit: { ipAddress: req.ip, userAgent: req.get('user-agent') ?? undefined, origin },
+  };
+  const result = refresh ? await service.RefreshGuestSession(input) : await service.MintGuestSession(input);
+  res.status(statusForResult(result)).json(result);
+}
+
+/**
+ * Maps a mint result to an HTTP status. All client-side rejections (unknown key,
+ * disabled widget, disallowed origin, modality off) return 403 — deliberately
+ * uniform so a probe cannot distinguish "no such widget" from "wrong origin" and
+ * enumerate valid keys. Only true server faults return 500.
+ */
+function statusForResult(result: MintGuestSessionResult): number {
+  if (result.success) {
+    return 200;
+  }
+  return result.errorCode === 'server_error' ? 500 : 403;
+}