@memberjunction/server 5.44.0 → 5.45.1

package/src/auth/magicLink/magicLinkCore.ts

@@ -106,35 +106,63 @@ export function evaluateInvite(invite: InviteEvaluationInput, nowMs: number): {
   return { ok: true };
 }
 
+/** SQL dialect for {@link buildConsumeInviteSQL}. */
+export type ConsumeInviteDialect = 'sqlserver' | 'postgresql';
+
+/** SQL Server table identifier — bracket-quoted `[schema].[table]` (word chars only). */
+const QUALIFIED_TABLE_PATTERN = /^\[\w+\]\.\[\w+\]$/;
+/** PostgreSQL table identifier — `schema.table` (word chars only); auto-quoted downstream. */
+const QUALIFIED_TABLE_PATTERN_PG = /^\w+\.\w+$/;
+
 /**
- * Builds the atomic compare-and-swap UPDATE that consumes one use of an invite.
+ * Builds the atomic compare-and-swap UPDATE that consumes one use of an invite,
+ * in the given SQL dialect.
  *
  * The WHERE clause re-checks every eligibility condition at the DB level, so the
  * increment and the guard are a single atomic operation: concurrent redemptions
- * of a single-use link race on the row and exactly one matches (the matched row
- * is returned via OUTPUT). This is what actually enforces single-use — the
- * JS-side `evaluateInvite` is only a friendly pre-check.
+ * of a single-use link race on the row and exactly one matches. This is what
+ * actually enforces single-use — the JS-side `evaluateInvite` is only a friendly
+ * pre-check. The matched row's ID is returned to the caller (via `OUTPUT` on SQL
+ * Server, `RETURNING` on PostgreSQL) so it can detect a win (exactly one row).
+ *
+ * The invite ID MUST be bound as a parameter by the caller (`@p0` on SQL Server,
+ * `$1` on PostgreSQL) — it is never interpolated into the string, so this builder
+ * is injection-safe regardless of the ID's contents.
  *
- * The invite ID MUST be bound as parameter `@p0` by the caller — it is never
- * interpolated into the string, so this builder is injection-safe regardless of
- * the ID's contents.
+ * **SQL Server** — `OUTPUT` goes `INTO` a table variable (not a bare OUTPUT):
+ * SQL Server forbids a bare OUTPUT clause on a table that has enabled triggers,
+ * and CodeGen adds an `__mj_UpdatedAt` trigger to every MJ table. The trailing
+ * SELECT returns the matched row(s) regardless of trigger behavior.
  *
- * OUTPUT goes `INTO` a table variable (not a bare OUTPUT): SQL Server forbids a
- * bare OUTPUT clause on a table that has enabled triggers, and CodeGen adds an
- * `__mj_UpdatedAt` trigger to every MJ table. The trailing SELECT returns exactly
- * the matched row(s) so the caller can detect a win (exactly one row) regardless
- * of trigger behavior.
+ * **PostgreSQL** — the `UPDATE … WHERE` guard IS itself the atomic single-use
+ * gate: the row is locked for the UPDATE's duration, so concurrent redemptions
+ * serialize and only the first matching `Status='Active' AND UseCount < MaxUses`
+ * wins; `RETURNING` yields the row iff the guard matched (equivalent to the SS
+ * `OUTPUT`-into-table win-detect). PascalCase identifiers are auto-quoted by
+ * `PostgreSQLDataProvider.ExecuteSQL`, so the table is passed unquoted (`schema.table`).
  *
- * `qualifiedTable` is asserted to be a bracket-quoted `[schema].[table]` (word
- * chars only) before interpolation. The caller derives it from `EntityInfo`
- * (never user input), so this is defense-in-depth: even a future careless caller
- * cannot turn this into an injection vector — a non-conforming table throws.
+ * `qualifiedTable` is asserted to match the dialect's whitelist pattern before
+ * interpolation. The caller derives it from `EntityInfo` (never user input), so
+ * this is defense-in-depth: even a future careless caller cannot turn this into
+ * an injection vector — a non-conforming table throws.
  *
- * @param qualifiedTable  bracket-quoted `[schema].[table]` for MagicLinkInvite
+ * @param qualifiedTable  `[schema].[table]` (sqlserver) or `schema.table` (postgresql) for MagicLinkInvite
+ * @param dialect         target SQL dialect (defaults to `'sqlserver'`)
  */
-const QUALIFIED_TABLE_PATTERN = /^\[\w+\]\.\[\w+\]$/;
-
-export function buildConsumeInviteSQL(qualifiedTable: string): string {
+export function buildConsumeInviteSQL(qualifiedTable: string, dialect: ConsumeInviteDialect = 'sqlserver'): string {
+  if (dialect === 'postgresql') {
+    if (!QUALIFIED_TABLE_PATTERN_PG.test(qualifiedTable)) {
+      throw new Error(`buildConsumeInviteSQL: refusing to build SQL for non-whitelisted table identifier '${qualifiedTable}'.`);
+    }
+    return (
+      `UPDATE ${qualifiedTable} ` +
+      `SET UseCount = UseCount + 1, ` +
+      `ConsumedAt = COALESCE(ConsumedAt, (now() AT TIME ZONE 'utc')), ` +
+      `Status = CASE WHEN UseCount + 1 >= MaxUses THEN 'Consumed' ELSE Status END ` +
+      `WHERE ID = $1 AND Status = 'Active' AND UseCount < MaxUses AND ExpiresAt > (now() AT TIME ZONE 'utc') ` +
+      `RETURNING ID;`
+    );
+  }
   if (!QUALIFIED_TABLE_PATTERN.test(qualifiedTable)) {
     throw new Error(`buildConsumeInviteSQL: refusing to build SQL for non-whitelisted table identifier '${qualifiedTable}'.`);
   }

package/src/auth/magicLink/types.ts

@@ -58,6 +58,32 @@ export interface MagicLinkJWTClaims {
   mj_anon?: boolean;
   /** Opaque per-session id — correlates one anonymous session's activity across audit rows without a real user. */
   mj_sid?: string;
+  /**
+   * Public web widget instance id (additive — set only for widget guest sessions
+   * minted by WidgetSessionService). Binds the synthesized guest principal to one
+   * widget instance so its pinned agent / guest role can be locked down. Absent on
+   * ordinary magic-link sessions.
+   */
+  mj_widget_id?: string;
+  /**
+   * Host-asserted visitor email for a widget `host-identity` session (additive). The
+   * authoritative `email`/`sub` still resolve the constrained shared Anonymous principal;
+   * this carries WHO the host says the visitor is, for the agent to look up their account —
+   * without granting that account's permissions. Absent on anonymous/ordinary sessions.
+   */
+  mj_host_email?: string;
+  /**
+   * Returning-visitor anchor for a widget guest session (additive, RV1). Carried so the VOICE path —
+   * whose conversation is created server-side — can stamp the same Conversation.VisitorKey the text
+   * path stamps client-side. Present only when the widget remembers returning visitors.
+   */
+  mj_visitor_key?: string;
+  /** The prior conversation this visit chains from (RV2), for the voice path to stamp Conversation.LastConversationID. */
+  mj_last_conversation_id?: string;
+  /** Resolved polymorphic identity entity id (RV4), for the voice path to stamp the existing Conversation.LinkedEntityID / AIAgentSession.LinkedEntityID. */
+  mj_linked_entity_id?: string;
+  /** Resolved polymorphic identity record id (RV4), for the voice path to stamp the existing Conversation.LinkedRecordID / AIAgentSession.LinkedRecordID. */
+  mj_linked_record_id?: string;
   /** Marks the session as magic-link so the Explorer can confine the UI. */
   mj_magic_link: true;
 }

package/src/config.ts

@@ -68,23 +68,6 @@ const zodBooleanWithTransforms = () => {
           })
 }
 
-const askSkipInfoSchema = z.object({
-  url: z.string().optional(), // Base URL for Skip API
-  apiKey: z.string().optional(),
-  orgID: z.string().optional(),
-  organizationInfo: z.string().optional(),
-  entitiesToSend: z
-    .object({
-      excludeSchemas: z.array(z.string()).optional(),
-      includeEntitiesFromExcludedSchemas: z.array(z.string()).optional(),
-    })
-    .optional(),
-  chatURL: z.string().optional(),
-  learningCycleRunUponStartup: zodBooleanWithTransforms(),
-  learningCycleEnabled: zodBooleanWithTransforms(),
-  learningCycleURL: z.string().optional(),
-  learningCycleIntervalInMinutes: z.coerce.number().optional(),
-});
 
 const sqlLoggingOptionsSchema = z.object({
   formatAsMigration: z.boolean().optional().default(false),
@@ -330,13 +313,178 @@ const magicLinkSchema = z.object({
   explorerUrl: z.string().optional(),
 }).passthrough();
 
+/**
+ * Public web widget config (plans/realtime/bridges-and-widget/public-web-widget.md).
+ * The widget REUSES the magic-link RS256 key + `anonymous-embed` synthesis, so it
+ * shares the magic-link `audience`/issuer/JWKS by default — the same auth provider
+ * validates both. When `enabled`, the server ensures the magic-link key manager is
+ * initialized and the provider registered even if `magicLink.enabled` is false.
+ */
+const widgetSchema = z.object({
+  /** Master switch. When false, the /widget routes are not mounted. */
+  enabled: zodBooleanWithTransforms().default(false),
+  /**
+   * Which signing mechanism the widget reuses. Only `magic-link` is supported today
+   * (shares MagicLinkKeyManager + the magic-link auth provider). Recorded so a future
+   * dedicated widget key is a config flip, not a code change.
+   */
+  signingReuse: z.enum(['magic-link']).optional().default('magic-link'),
+  /**
+   * Audience claim for minted guest JWTs. MUST equal the magic-link audience so the
+   * auto-registered `magic-link` auth provider validates widget tokens.
+   */
+  audience: z.string().optional().default('mj-magic-link'),
+  /** Email of the shared Anonymous principal used in guest claims (resolves the synthesized guest user). */
+  anonymousEmail: z.string().optional().default('anonymous@magic-link.local'),
+  /** Fallback session-token TTL (minutes) when a widget instance does not set its own. */
+  defaultSessionTtlMinutes: z.coerce.number().optional().default(15),
+  /** Fallback mint rate-limit (per IP per window) when a widget instance does not set its own. */
+  defaultRateLimitPerMinute: z.coerce.number().optional().default(30),
+  /** Rate-limit window (ms) for the public /widget/session endpoints. Default 60s. */
+  rateLimitWindowMs: z.coerce.number().optional().default(60_000),
+  /** Server-wide default hard ceiling (minutes) on a voice session when an instance omits one (W4). */
+  voiceDefaultMaxSessionMinutes: z.coerce.number().optional().default(10),
+  /** Email/name of the internal user whose context READS widget config at mint time (falls back to system/Owner). */
+  contextUserForLookup: z.string().optional(),
+  /**
+   * Host-identity public keys (PEM), keyed by widget PublicKey, for the `host-identity` auth
+   * strategy (D1). The host signs a short-lived RS256 assertion; the mint verifies it against
+   * the key here. INTERIM location — production should store the host key per widget instance
+   * (a HostPublicKey column on WidgetInstance, pending a migration). When a widget's strategy is
+   * HostIdentity and no key is configured here, host mints fail closed.
+   */
+  hostPublicKeys: z.record(z.string(), z.string()).optional().default({}),
+  /**
+   * Returning-visitor identity-resolution target (RV4). When a visitor verifies (magic-link upgrade)
+   * or a host asserts their identity, their email is resolved to a record `(entityName, recordId)`
+   * and prior anonymous memory is merged onto that polymorphic pair. Deployment-configurable so the
+   * resolved record need NOT be an MJ User — point it at any entity that carries the visitor's email
+   * (e.g. a CRM `Persons` table). Defaults to the core `Users` entity keyed by `Email`.
+   */
+  identityResolution: z.object({
+    entityName: z.string().optional().default('Users'),
+    emailField: z.string().optional().default('Email'),
+  }).optional(),
+}).passthrough();
+
+/**
+ * Telephony bridge config (plans/realtime/bridges-and-widget/telephony-vendor-bindings.md).
+ * Holds the per-vendor credentials + public stream URL the MJAPI telephony ingress wires onto
+ * the already-stubbed native SDK seams. Credentials resolve here from `mj.config.cjs` / env —
+ * never inlined in code. When `twilio` is omitted, the Twilio telephony routes are not mounted.
+ */
+const twilioTelephonySchema = z.object({
+  /** Twilio Account SID (`AC…`). */
+  accountSid: z.string(),
+  /** Account auth token — REST auth (when no API key pair) AND the HMAC key for X-Twilio-Signature verification. */
+  authToken: z.string().optional(),
+  /** API Key SID (`SK…`) — preferred over the auth token for REST auth when paired with apiKeySecret. */
+  apiKeySid: z.string().optional(),
+  /** API Key secret — paired with apiKeySid. */
+  apiKeySecret: z.string().optional(),
+  /** The publicly reachable `wss://…/telephony/twilio/media` URL Twilio's <Connect><Stream> connects to. */
+  streamPublicUrl: z.string(),
+  /** Optional shared secret gating the public webhook/WSS endpoints (defense-in-depth beyond signature verification). */
+  webhookSigningSecret: z.string().optional(),
+  /** Optional status-callback URL Twilio posts call lifecycle events to. */
+  statusCallbackUrl: z.string().optional(),
+}).passthrough();
+
+/**
+ * Vonage Voice + WebSocket-media telephony binding. Voice-API auth is application-scoped
+ * (application id + RSA private key) with an optional account API key pair for key-scoped ops;
+ * signatureSecret is the HMAC key for signed-request `sig` AND HS256 webhook-JWT verification.
+ * When `vonage` is omitted, the Vonage telephony routes are not mounted.
+ */
+const vonageTelephonySchema = z.object({
+  /** Vonage Application ID (UUID) — the JWT-auth identity for the Voice API. */
+  applicationId: z.string().optional(),
+  /** The application's RSA private key (PEM) used to sign Voice-API JWTs. */
+  privateKey: z.string().optional(),
+  /** Account API key — used for key-scoped operations when no application credential pair is supplied. */
+  apiKey: z.string().optional(),
+  /** Account API secret — paired with apiKey. */
+  apiSecret: z.string().optional(),
+  /** The publicly reachable `wss://…/telephony/vonage/media` URL the call's connect NCCO opens. */
+  mediaPublicUrl: z.string(),
+  /** Vonage account signature secret — HMAC key for signed-request `sig` AND HS256 webhook-JWT verification. */
+  signatureSecret: z.string().optional(),
+  /** Optional event-webhook URL Vonage posts call lifecycle events to (passed on outbound createCall). */
+  eventUrl: z.string().optional(),
+}).passthrough();
+
+/**
+ * RingCentral telephony binding: **SIP device credentials** for the headless softphone (the
+ * `ringcentral-softphone` SIP/RTP path — the only RingCentral product that carries bidirectional call
+ * audio; the WebSocket "Call Streaming" product is receive-only). These come from a RingCentral
+ * "Other Phone" (BYO-device) registration's SIP info, resolved here from `mj.config.cjs` / env — never
+ * inlined. When `ringcentral` is omitted, the RingCentral softphone is not started.
+ *
+ * Unlike Twilio/Vonage, there is NO public HTTP webhook or media WSS: the softphone is an outbound SIP
+ * registration that receives inbound INVITEs directly over its own SIP/TLS connection. So this block has
+ * no signing secret or public URL — just the SIP device creds + codec.
+ */
+const ringcentralTelephonySchema = z.object({
+  /** SIP domain (e.g. `sip.ringcentral.com`). */
+  sipDomain: z.string(),
+  /** SIP outbound proxy (`host:port`, e.g. `sip10.ringcentral.com:5096`). */
+  sipOutboundProxy: z.string(),
+  /** SIP auth username (the device's phone number / extension). */
+  sipUsername: z.string(),
+  /** SIP auth password (resolved upstream — never inlined). */
+  sipPassword: z.string(),
+  /** SIP authorization id (the device's RingCentral authorization id). */
+  sipAuthorizationId: z.string(),
+  /** Codec to negotiate. Defaults to `OPUS/16000` (clean wideband PCM16 — the least-friction realtime path). */
+  codec: z.enum(['OPUS/16000', 'OPUS/48000/2', 'PCMU/8000']).optional(),
+  /** Skip TLS cert validation (sandbox/test only — never in production). */
+  ignoreTlsCertErrors: zodBooleanWithTransforms().optional().default(false),
+}).passthrough();
+
+/**
+ * Teams meetings bridge config (plans/realtime/bridges-and-widget/meeting-vendor-bindings-teams-slack.md M1).
+ * Holds the bot credentials + Graph webhook shared secret + ACS audio rate the MJAPI meetings ingress wires
+ * onto the Teams binding seams. Credentials resolve here from `mj.config.cjs` / env — never inlined in code.
+ * When `teams` is omitted (or disabled), the Teams meetings routes are not mounted.
+ */
+const teamsMeetingsSchema = z.object({
+  /** Master switch for the Teams meetings ingress. */
+  enabled: zodBooleanWithTransforms().default(false),
+  /** The bot's Azure AD application (client) id (resolved upstream; carried for diagnostics). */
+  appId: z.string().optional(),
+  /** The Azure tenant id the bot operates in. */
+  tenantId: z.string().optional(),
+  /** A pre-resolved OAuth bearer / application token for the bot's Graph calls (resolved upstream — never inline). */
+  botAccessToken: z.string().optional(),
+  /** The shared secret set as `clientState` on the Graph subscription; gates the change-notification webhook. */
+  notificationClientState: z.string().optional(),
+  /** The ACS application-hosted-media PCM sample rate (Hz) the audio plane negotiates. Defaults to 16000. */
+  acsSampleRate: z.coerce.number().optional().default(16000),
+  /** The realtime model's PCM16 sample rate (Hz) the binding resamples to/from. Defaults to 16000. */
+  modelSampleRate: z.coerce.number().optional().default(16000),
+}).passthrough();
+
+const telephonySchema = z.object({
+  /** Master switch. When false (or when no vendor block is present), telephony routes are not mounted. */
+  enabled: zodBooleanWithTransforms().default(false),
+  /** Twilio Programmable Voice + Media Streams binding. */
+  twilio: twilioTelephonySchema.optional(),
+  /** Vonage Voice + WebSocket-media binding. */
+  vonage: vonageTelephonySchema.optional(),
+  /** RingCentral Call Control + media-stream binding. */
+  ringcentral: ringcentralTelephonySchema.optional(),
+  /** Microsoft Teams meetings (Graph cloud-communications + ACS application-hosted media) binding. */
+  teams: teamsMeetingsSchema.optional(),
+}).passthrough();
+
 const configInfoSchema = z.object({
   userHandling: userHandlingInfoSchema,
   magicLink: magicLinkSchema.optional().default({}),
+  widget: widgetSchema.optional().default({}),
+  telephony: telephonySchema.optional().default({}),
   databaseSettings: databaseSettingsInfoSchema,
   viewingSystem: viewingSystemInfoSchema.optional(),
   restApiOptions: restApiOptionsSchema.optional().default({}),
-  askSkip: askSkipInfoSchema.optional(),
   sqlLogging: sqlLoggingSchema.optional(),
   authProviders: z.array(authProviderSchema).optional(),
   componentRegistries: z.array(componentRegistrySchema).optional(),
@@ -384,10 +532,15 @@ const configInfoSchema = z.object({
 
 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 TwilioTelephonyConfig = z.infer<typeof twilioTelephonySchema>;
+export type VonageTelephonyConfig = z.infer<typeof vonageTelephonySchema>;
+export type RingCentralTelephonyConfig = z.infer<typeof ringcentralTelephonySchema>;
+export type TeamsMeetingsConfig = z.infer<typeof teamsMeetingsSchema>;
 export type DatabaseSettingsInfo = z.infer<typeof databaseSettingsInfoSchema>;
 export type ViewingSystemSettingsInfo = z.infer<typeof viewingSystemInfoSchema>;
 export type RESTApiOptions = z.infer<typeof restApiOptionsSchema>;
-export type AskSkipInfo = z.infer<typeof askSkipInfoSchema>;
 export type SqlLoggingOptions = z.infer<typeof sqlLoggingOptionsSchema>;
 export type SqlLoggingInfo = z.infer<typeof sqlLoggingSchema>;
 export type AuthProviderConfig = z.infer<typeof authProviderSchema>;
@@ -477,25 +630,6 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
     enabled: false,
   },
 
-  // Ask Skip configuration (environment-driven)
-  askSkip: {
-    url: process.env.ASK_SKIP_URL,
-    chatURL: process.env.ASK_SKIP_CHAT_URL,
-    learningCycleURL: process.env.ASK_SKIP_LEARNING_URL,
-    learningCycleIntervalInMinutes: process.env.ASK_SKIP_LEARNING_CYCLE_INTERVAL_IN_MINUTES
-      ? parseInt(process.env.ASK_SKIP_LEARNING_CYCLE_INTERVAL_IN_MINUTES, 10)
-      : undefined,
-    learningCycleEnabled: process.env.ASK_SKIP_RUN_LEARNING_CYCLES === 'true',
-    learningCycleRunUponStartup: process.env.ASK_SKIP_RUN_LEARNING_CYCLES_UPON_STARTUP === 'true',
-    orgID: process.env.ASK_SKIP_ORGANIZATION_ID,
-    apiKey: process.env.ASK_SKIP_API_KEY,
-    organizationInfo: process.env.ASK_SKIP_ORGANIZATION_INFO,
-    entitiesToSend: {
-      excludeSchemas: [],
-      includeEntitiesFromExcludedSchemas: [],
-    },
-  },
-
   // SQL logging defaults
   sqlLogging: {
     enabled: true,

package/src/context.ts

@@ -15,7 +15,7 @@ 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 MagicLinkScope } from '@memberjunction/core';
+import { DatabaseProviderBase, UserInfo, type MagicLinkScope, type ReturningVisitorContext, type WidgetGuestContext } from '@memberjunction/core';
 import { SQLServerDataProvider, SQLServerProviderConfigData, UserCache } from '@memberjunction/sqlserver-dataprovider';
 import { Metadata } from '@memberjunction/core';
 import { UUIDsEqual } from '@memberjunction/global';
@@ -242,8 +242,17 @@ function buildMagicLinkSessionUser(userRecord: UserInfo, payload: jwt.JwtPayload
     }
   }
 
-  // Named session with no resource scope → no per-request state needed, use the cached user.
-  if (!isAnon && !scope) {
+  // Returning-visitor context (RV1/RV2/RV4): carried on a widget guest token so the voice path
+  // (server-created conversation) stamps the same returning-visitor anchor + resolved identity.
+  const visitorContext = extractReturningVisitorContext(payload);
+
+  // Widget-instance identity (mj_widget_id): present on every public web-widget guest token. The
+  // privileged agent-dispatch path reads it to resolve the AUTHORITATIVE pinned agent for the guest
+  // (so a guest can never run an arbitrary agent under the elevated server principal).
+  const widgetGuestContext = extractWidgetGuestContext(payload);
+
+  // Named session with no resource scope and no widget/visitor context → no per-request state needed.
+  if (!isAnon && !scope && !visitorContext && !widgetGuestContext) {
     return userRecord;
   }
 
@@ -255,6 +264,12 @@ function buildMagicLinkSessionUser(userRecord: UserInfo, payload: jwt.JwtPayload
   if (scope) {
     sessionUser.MagicLinkScope = scope;
   }
+  if (visitorContext) {
+    sessionUser.ReturningVisitorContext = visitorContext;
+  }
+  if (widgetGuestContext) {
+    sessionUser.WidgetGuestContext = widgetGuestContext;
+  }
   if (isAnon) {
     // Mark the session so the CurrentUser field resolver serves these synthesized roles
     // (the shared Anonymous principal holds none in the DB). See UserInfo.IsMagicLinkAnonymous.
@@ -263,6 +278,38 @@ function buildMagicLinkSessionUser(userRecord: UserInfo, payload: jwt.JwtPayload
   return sessionUser;
 }
 
+/**
+ * Extracts the returning-visitor context (RV1/RV2/RV4) from a widget guest token's claims, or
+ * undefined when the token carries no VisitorKey (the default, remembering-off case). Used so the
+ * voice path can stamp the conversation with the same anchor/identity the text path stamps client-side.
+ */
+function extractReturningVisitorContext(payload: jwt.JwtPayload): ReturningVisitorContext | undefined {
+  const visitorKey = payload['mj_visitor_key'];
+  if (typeof visitorKey !== 'string' || !visitorKey) {
+    return undefined;
+  }
+  const str = (v: unknown): string | undefined => (typeof v === 'string' && v ? v : undefined);
+  return {
+    VisitorKey: visitorKey,
+    LastConversationID: str(payload['mj_last_conversation_id']),
+    LinkedEntityID: str(payload['mj_linked_entity_id']),
+    LinkedRecordID: str(payload['mj_linked_record_id']),
+  };
+}
+
+/**
+ * Extracts the widget-instance identity (`mj_widget_id`) from a public web-widget guest token, or
+ * undefined when the token carries none (every non-widget session). Carried so the privileged
+ * agent-dispatch path can resolve the authoritative pinned agent for the guest from the trusted token.
+ */
+function extractWidgetGuestContext(payload: jwt.JwtPayload): WidgetGuestContext | undefined {
+  const widgetId = payload['mj_widget_id'];
+  if (typeof widgetId !== 'string' || !widgetId) {
+    return undefined;
+  }
+  return { WidgetID: widgetId };
+}
+
 const verifyAsync = async (issuer: string, token: string): Promise<jwt.JwtPayload> =>
   new Promise((resolve, reject) => {
     const options = getValidationOptions(issuer);