@memberjunction/server 5.44.0 → 5.45.0

package/src/realtimeWidget/host-identity.ts

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview Host-passed identity (D1 strategy `host-identity`). When a widget is
+ * embedded in an already-authenticated host portal, the host signs a short-lived
+ * assertion (its own RS256 key) describing the visitor; the widget posts it to
+ * `POST /widget/session`, which verifies it against the host's registered public key
+ * and folds the host-provided identity into the minted guest claims. The minted token
+ * is still validated by the same `magic-link` AuthProviderFactory path + synthesized by
+ * `buildMagicLinkSessionUser` — host-identity is a MINT-TIME strategy, not a second
+ * session-validation provider (it converges on the one pathway, per D1).
+ *
+ * Pure + unit-testable: verification takes the PEM as an argument.
+ *
+ * @module @memberjunction/server/widget
+ */
+
+import type jwt from 'jsonwebtoken';
+import { HostIdentityProvider, type HostAssertionError } from '@memberjunction/auth-providers';
+
+export type { HostAssertionError };
+
+/** The visitor identity a host asserts. Standard OIDC-ish claims so synthesis is uniform. */
+export interface HostAssertedIdentity {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    /** The host's opaque user id for this visitor (audit correlation; not an MJ user id). */
+    hostUserId?: string;
+}
+
+/** Result of verifying a host assertion. `identity` is present iff `ok` is true. */
+export interface HostAssertionResult {
+    ok: boolean;
+    identity?: HostAssertedIdentity;
+    errorCode?: HostAssertionError;
+}
+
+/**
+ * The single shared {@link HostIdentityProvider} instance the mint path verifies through. The base
+ * `BaseAuthProvider` constructor builds a (never-contacted) JWKS client; host-identity verifies against
+ * static per-widget PEM keys, so we pass a placeholder `jwksUri`. Built once — verification is stateless.
+ */
+const hostIdentityProvider = new HostIdentityProvider({
+    name: 'host-identity',
+    type: 'host-identity',
+    issuer: 'host-identity',
+    audience: 'host-identity',
+    jwksUri: 'https://host-identity.local/unused',
+});
+
+/**
+ * Verifies a host-signed RS256 assertion against the host's registered public key (PEM) and extracts the
+ * asserted visitor identity. Thin adapter over {@link HostIdentityProvider.VerifyHostAssertion} (the single
+ * implementation, registered in the AuthProviderFactory) preserving this module's result shape. Never throws.
+ */
+export function verifyHostAssertion(
+    assertion: string | undefined,
+    hostPublicKeyPem: string | undefined,
+    expectedAudience: string,
+): HostAssertionResult {
+    const result = hostIdentityProvider.VerifyHostAssertion(assertion, hostPublicKeyPem, expectedAudience);
+    if (!result.ok || !result.userInfo?.email) {
+        return { ok: false, errorCode: result.errorCode };
+    }
+    return {
+        ok: true,
+        identity: {
+            email: result.userInfo.email,
+            firstName: result.userInfo.firstName,
+            lastName: result.userInfo.lastName,
+            hostUserId: result.hostUserId,
+        },
+    };
+}
+
+/** Pulls the visitor identity from a verified host-assertion payload (delegates to the provider). */
+export function extractHostIdentity(payload: jwt.JwtPayload): HostAssertedIdentity {
+    const info = hostIdentityProvider.extractUserInfo(payload);
+    return {
+        email: info.email ?? '',
+        firstName: info.firstName,
+        lastName: info.lastName,
+        hostUserId: typeof payload.sub === 'string' ? payload.sub : undefined,
+    };
+}

package/src/realtimeWidget/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Public web widget guest-session module barrel.
+ * @module @memberjunction/server/widget
+ */
+export * from './widgetCore.js';
+export {
+  verifyHostAssertion,
+  extractHostIdentity,
+  type HostAssertedIdentity,
+  type HostAssertionResult,
+  type HostAssertionError,
+} from './host-identity.js';
+export { WidgetSessionService } from './WidgetSessionService.js';
+export type { MintGuestSessionInput, MintGuestSessionResult, WidgetMintAuditContext } from './WidgetSessionService.js';
+export { createWidgetHandler, WIDGET_MOUNT_PATH } from './WidgetRouter.js';

package/src/realtimeWidget/visitorIdentity.ts

@@ -0,0 +1,258 @@
+/**
+ * @fileoverview Returning-visitor identity resolution + merge (RV4) and "forget me" (RV5).
+ *
+ * A widget visitor starts anonymous: their memory (recap notes) is filed under the polymorphic pair
+ * `(MJ: Conversations entity, conversation.ID)` and chained across visits by the durable `VisitorKey`
+ * cookie (RV1/RV2). When the visitor later proves who they are — magic-link "verify it's you", or a
+ * host-asserted identity — RV4 promotes that anonymous trail to a real, deployment-configurable record:
+ *
+ *   1. resolve the verified email → a polymorphic `(entityId, recordId)` pair (NOT assumed to be a
+ *      User — {@link resolveIdentityByEmail} honors the per-deployment `widget.identityResolution`
+ *      target so a CRM `Persons` row works as well as the core `Users` row),
+ *   2. stamp the existing `LinkedEntityID/LinkedRecordID` on every conversation that shares the visitor's key
+ *      in this application (back-fill), and
+ *   3. re-key the visitor's anonymous recap notes onto the resolved pair (merge), so the existing
+ *      memory injector (which already filters by the PrimaryScope pair) now pulls the prior context
+ *      via the resolved identity rather than the cookie chain.
+ *
+ * "Forget me" (RV5) is the inverse: archive the visitor's auto-generated memory and clear the
+ * `VisitorKey` linkage so neither the cookie nor a resolved pair resolves their trail anymore.
+ *
+ * Everything here is BEST-EFFORT and multi-provider-safe (it takes the request/session
+ * `IMetadataProvider`, never the global `Metadata`). A failure never blocks the auth flow.
+ *
+ * @module @memberjunction/server/widget
+ */
+
+import { RunView, UserInfo, LogError, LogStatus, type IMetadataProvider } from '@memberjunction/core';
+import type { MJConversationEntity, MJAIAgentNoteEntity } from '@memberjunction/core-entities';
+
+const CONVERSATIONS_ENTITY = 'MJ: Conversations';
+const AGENT_NOTES_ENTITY = 'MJ: AI Agent Notes';
+
+/** A resolved polymorphic identity: the entity the visitor maps to, and that record's id. */
+export interface ResolvedVisitorIdentity {
+  entityId: string;
+  recordId: string;
+}
+
+/** The deployment-configurable resolution target (defaults to the core `Users` entity keyed by `Email`). */
+export interface IdentityResolutionTarget {
+  entityName?: string;
+  emailField?: string;
+}
+
+/**
+ * Resolves a verified email to a polymorphic `(entityId, recordId)` pair via the deployment-configured
+ * target (default: the `Users` entity keyed by `Email`). Returns undefined when no record matches — the
+ * visitor simply stays anonymous. Never throws; email is escaped for the filter literal.
+ */
+export async function resolveIdentityByEmail(
+  email: string,
+  contextUser: UserInfo,
+  provider: IMetadataProvider,
+  target?: IdentityResolutionTarget,
+): Promise<ResolvedVisitorIdentity | undefined> {
+  try {
+    const trimmed = (email ?? '').trim();
+    if (!trimmed) {
+      return undefined;
+    }
+    const entityName = target?.entityName?.trim() || 'Users';
+    const emailField = target?.emailField?.trim() || 'Email';
+    const entityId = provider.EntityByName(entityName)?.ID;
+    if (!entityId) {
+      LogError(`[VisitorIdentity] identity-resolution entity '${entityName}' not found in metadata.`);
+      return undefined;
+    }
+    const rv = new RunView();
+    const result = await rv.RunView<{ ID: string }>(
+      {
+        EntityName: entityName,
+        ExtraFilter: `${emailField} = '${trimmed.replace(/'/g, "''")}'`,
+        Fields: ['ID'],
+        MaxRows: 1,
+        ResultType: 'simple',
+      },
+      contextUser,
+    );
+    if (!result.Success) {
+      LogError(`[VisitorIdentity] identity lookup failed for '${entityName}.${emailField}': ${result.ErrorMessage}`);
+      return undefined;
+    }
+    const recordId = result.Results?.[0]?.ID;
+    return recordId ? { entityId, recordId } : undefined;
+  } catch (e) {
+    LogError(`[VisitorIdentity] resolveIdentityByEmail failed: ${e instanceof Error ? e.message : String(e)}`);
+    return undefined;
+  }
+}
+
+/** Loads every conversation sharing a VisitorKey within one application (entity objects, for mutation). */
+async function loadVisitorConversations(
+  visitorKey: string,
+  applicationId: string,
+  contextUser: UserInfo,
+): Promise<MJConversationEntity[]> {
+  const rv = new RunView();
+  // visitorKey is validated base64url by the caller; applicationId is a server-trusted UUID.
+  const result = await rv.RunView<MJConversationEntity>(
+    {
+      EntityName: CONVERSATIONS_ENTITY,
+      ExtraFilter: `VisitorKey = '${visitorKey}' AND ApplicationID = '${applicationId.replace(/'/g, "''")}'`,
+      ResultType: 'entity_object',
+    },
+    contextUser,
+  );
+  if (!result.Success) {
+    LogError(`[VisitorIdentity] failed to load visitor conversations: ${result.ErrorMessage}`);
+    return [];
+  }
+  return result.Results ?? [];
+}
+
+/**
+ * Promotes a visitor's anonymous trail to a resolved identity (RV4): stamps the resolved pair on every
+ * conversation sharing the visitor's key in this application, then re-keys the visitor's anonymous
+ * recap notes (those filed under `(MJ: Conversations, conversationId)`) onto the resolved pair. Idempotent
+ * and best-effort — already-resolved conversations are skipped; per-record save failures are logged, not thrown.
+ *
+ * @returns the number of conversations stamped (0 when nothing matched the key).
+ */
+export async function mergeVisitorIdentity(args: {
+  visitorKey: string;
+  applicationId: string;
+  identity: ResolvedVisitorIdentity;
+  contextUser: UserInfo;
+  provider: IMetadataProvider;
+}): Promise<number> {
+  try {
+    const conversations = await loadVisitorConversations(args.visitorKey, args.applicationId, args.contextUser);
+    if (conversations.length === 0) {
+      return 0;
+    }
+    const conversationsEntityId = args.provider.EntityByName(CONVERSATIONS_ENTITY)?.ID;
+
+    let stamped = 0;
+    for (const convo of conversations) {
+      if (convo.LinkedEntityID === args.identity.entityId && convo.LinkedRecordID === args.identity.recordId) {
+        continue; // already resolved to this identity
+      }
+      convo.LinkedEntityID = args.identity.entityId;
+      convo.LinkedRecordID = args.identity.recordId;
+      if (await convo.Save()) {
+        stamped++;
+      } else {
+        LogError(`[VisitorIdentity] failed to stamp resolved identity on conversation ${convo.ID}: ${convo.LatestResult?.CompleteMessage ?? 'unknown'}`);
+      }
+    }
+
+    if (conversationsEntityId) {
+      await rekeyAnonymousNotes(conversations.map((c) => c.ID), conversationsEntityId, args.identity, args.contextUser, args.provider);
+    }
+
+    LogStatus(`[VisitorIdentity] merged visitor ${args.visitorKey} → ${args.identity.entityId}/${args.identity.recordId} across ${stamped} conversation(s)`);
+    return stamped;
+  } catch (e) {
+    LogError(`[VisitorIdentity] mergeVisitorIdentity failed: ${e instanceof Error ? e.message : String(e)}`);
+    return 0;
+  }
+}
+
+/** Re-keys notes scoped to `(Conversations entity, conversationId)` onto the resolved pair. */
+async function rekeyAnonymousNotes(
+  conversationIds: string[],
+  conversationsEntityId: string,
+  identity: ResolvedVisitorIdentity,
+  contextUser: UserInfo,
+  provider: IMetadataProvider,
+): Promise<void> {
+  if (conversationIds.length === 0) {
+    return;
+  }
+  const inList = conversationIds.map((id) => `'${id.replace(/'/g, "''")}'`).join(', ');
+  const rv = new RunView();
+  const result = await rv.RunView<MJAIAgentNoteEntity>(
+    {
+      EntityName: AGENT_NOTES_ENTITY,
+      ExtraFilter: `PrimaryScopeEntityID = '${conversationsEntityId}' AND PrimaryScopeRecordID IN (${inList})`,
+      ResultType: 'entity_object',
+    },
+    contextUser,
+  );
+  if (!result.Success) {
+    LogError(`[VisitorIdentity] failed to load anonymous notes for re-key: ${result.ErrorMessage}`);
+    return;
+  }
+  for (const note of result.Results ?? []) {
+    note.PrimaryScopeEntityID = identity.entityId;
+    note.PrimaryScopeRecordID = identity.recordId;
+    if (!(await note.Save())) {
+      LogError(`[VisitorIdentity] failed to re-key note ${note.ID}: ${note.LatestResult?.CompleteMessage ?? 'unknown'}`);
+    }
+  }
+}
+
+/**
+ * "Forget me" (RV5): archives the visitor's auto-generated memory and severs the cookie linkage.
+ * Archives every auto-generated note whose `SourceConversationID` is one of the visitor's conversations
+ * (so it reaps recaps whether they're still anonymous-scoped or already merged onto a resolved record —
+ * without touching unrelated memory on a shared resolved record), then clears `VisitorKey` on those
+ * conversations so neither the cookie nor a resolved pair re-resolves the trail. Best-effort.
+ *
+ * @returns a summary of what was archived/cleared.
+ */
+export async function forgetVisitor(args: {
+  visitorKey: string;
+  applicationId: string;
+  contextUser: UserInfo;
+  provider: IMetadataProvider;
+}): Promise<{ notesArchived: number; conversationsCleared: number }> {
+  let notesArchived = 0;
+  let conversationsCleared = 0;
+  try {
+    const conversations = await loadVisitorConversations(args.visitorKey, args.applicationId, args.contextUser);
+    if (conversations.length === 0) {
+      return { notesArchived, conversationsCleared };
+    }
+    const inList = conversations.map((c) => `'${c.ID.replace(/'/g, "''")}'`).join(', ');
+
+    // Archive the visitor's auto-generated recaps, keyed by source conversation (scope-agnostic).
+    const rv = new RunView();
+    const notes = await rv.RunView<MJAIAgentNoteEntity>(
+      {
+        EntityName: AGENT_NOTES_ENTITY,
+        ExtraFilter: `IsAutoGenerated = 1 AND SourceConversationID IN (${inList}) AND Status != 'Archived'`,
+        ResultType: 'entity_object',
+      },
+      args.contextUser,
+    );
+    if (notes.Success) {
+      for (const note of notes.Results ?? []) {
+        note.Status = 'Archived';
+        if (await note.Save()) {
+          notesArchived++;
+        } else {
+          LogError(`[VisitorIdentity] failed to archive note ${note.ID}: ${note.LatestResult?.CompleteMessage ?? 'unknown'}`);
+        }
+      }
+    } else {
+      LogError(`[VisitorIdentity] failed to load notes for forget: ${notes.ErrorMessage}`);
+    }
+
+    // Sever the cookie linkage: clear VisitorKey so the key no longer resolves these conversations.
+    for (const convo of conversations) {
+      convo.VisitorKey = null;
+      if (await convo.Save()) {
+        conversationsCleared++;
+      } else {
+        LogError(`[VisitorIdentity] failed to clear VisitorKey on conversation ${convo.ID}: ${convo.LatestResult?.CompleteMessage ?? 'unknown'}`);
+      }
+    }
+
+    LogStatus(`[VisitorIdentity] forgot visitor ${args.visitorKey}: archived ${notesArchived} note(s), cleared ${conversationsCleared} conversation link(s)`);
+  } catch (e) {
+    LogError(`[VisitorIdentity] forgetVisitor failed: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  return { notesArchived, conversationsCleared };
+}

package/src/realtimeWidget/widgetCore.ts

@@ -0,0 +1,231 @@
+/**
+ * @fileoverview Pure functional core for the public web widget guest-session
+ * mint — no DB, no MJ runtime, no Express. Deterministic given inputs (modulo
+ * the session-id randomness it delegates to magicLinkCore) and unit-testable
+ * with plain assertions. Mirrors the magic-link `magicLinkCore.ts` split.
+ *
+ * The widget reuses the magic-link RS256 mint + `anonymous-embed` synthesis. This
+ * module owns only the widget-specific pure logic: origin-allowlist enforcement,
+ * widget-instance eligibility, and assembling the guest claims (anonymous + the
+ * additive `mj_widget_id` claim) on top of magic-link's `buildSessionClaims`.
+ *
+ * @module @memberjunction/server/widget
+ */
+
+import { buildSessionClaims } from '../auth/magicLink/magicLinkCore.js';
+import type { MagicLinkJWTClaims } from '../auth/magicLink/types.js';
+
+/**
+ * The magic-link resource-scope `resourceType` used for a widget guest session. Pairs with the
+ * opaque session id as `resourceId` so the synthesized principal's MagicLinkScope.ResourceID is
+ * the session id — the discriminator the Widget Guest RLS filters key on for per-session isolation.
+ */
+export const WIDGET_SESSION_RESOURCE_TYPE = 'Widget Session';
+
+/** Why a guest-session mint was rejected. Drives the HTTP status in the router. */
+export type WidgetMintErrorCode =
+    | 'not_found'
+    | 'disabled'
+    | 'origin_not_allowed'
+    | 'modality_not_enabled'
+    | 'host_assertion_invalid'
+    | 'upgrade_not_enabled'
+    | 'invalid_email'
+    | 'server_error';
+
+/** The minimal widget-instance shape the pure validators need (a subset of the entity). */
+export interface WidgetInstanceEligibilityInput {
+  Status: string;
+  AllowedOrigins: string | null;
+  Modality: string;
+}
+
+/**
+ * Parses the widget's `AllowedOrigins` column into a normalized origin list.
+ * Accepts a JSON array (preferred, e.g. `["https://a.com","https://b.com"]`) or a
+ * comma-separated string (tolerated). Returns an empty array for null/blank/garbage
+ * — which makes the allowlist FAIL-CLOSED (no origin is allowed) by construction.
+ */
+export function parseAllowedOrigins(allowedOrigins: string | null | undefined): string[] {
+  const raw = allowedOrigins?.trim();
+  if (!raw) {
+    return [];
+  }
+  let list: unknown;
+  try {
+    list = JSON.parse(raw);
+  } catch {
+    // Not JSON — tolerate a CSV form.
+    return raw.split(',').map((s) => normalizeOrigin(s)).filter((s): s is string => !!s);
+  }
+  if (!Array.isArray(list)) {
+    return [];
+  }
+  return list.filter((s): s is string => typeof s === 'string').map(normalizeOrigin).filter((s): s is string => !!s);
+}
+
+/** Lowercases + trims an origin and strips a trailing slash for stable comparison. */
+function normalizeOrigin(origin: string): string {
+  return origin.trim().toLowerCase().replace(/\/+$/, '');
+}
+
+/**
+ * Parses the widget's `EnabledChannels` column into a clean list of channel names (Phase 2). Accepts a
+ * JSON array (preferred, e.g. `["Whiteboard"]`) or a comma-separated string (tolerated). Returns an
+ * empty array for null/blank/garbage — the backwards-compatible default (no channels attached).
+ */
+export function parseEnabledChannels(enabledChannels: string | null | undefined): string[] {
+  const raw = enabledChannels?.trim();
+  if (!raw) {
+    return [];
+  }
+  const clean = (list: unknown[]): string[] =>
+    list.filter((s): s is string => typeof s === 'string').map((s) => s.trim()).filter((s) => s.length > 0);
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? clean(parsed) : [];
+  } catch {
+    return clean(raw.split(','));
+  }
+}
+
+/**
+ * FAIL-CLOSED origin check. The request's `Origin` header must exactly match one of
+ * the widget's allowed origins (after normalization). A missing request origin, or
+ * an empty allowlist, is rejected — a public mint endpoint must never accept "*".
+ */
+export function isOriginAllowed(requestOrigin: string | null | undefined, allowedOrigins: readonly string[]): boolean {
+  if (!requestOrigin || allowedOrigins.length === 0) {
+    return false;
+  }
+  const candidate = normalizeOrigin(requestOrigin);
+  return allowedOrigins.some((o) => o === candidate);
+}
+
+/** True when the requested modality (or the widget's default render) is enabled by the instance. */
+export function isModalityEnabled(widgetModality: string, requested: 'Text' | 'Voice'): boolean {
+  const m = widgetModality.trim().toLowerCase();
+  if (m === 'both') {
+    return true;
+  }
+  return m === requested.toLowerCase();
+}
+
+/**
+ * Pure eligibility check for a mint: the widget must be Active and the request's
+ * origin must be on the allowlist. Returns an error code on the first failure so the
+ * router can map it to a precise HTTP status. Modality is checked separately by the
+ * voice path (W4) since a text mint is always permitted for an enabled widget.
+ */
+export function evaluateWidgetMint(
+  widget: WidgetInstanceEligibilityInput,
+  requestOrigin: string | null | undefined,
+): { ok: boolean; errorCode?: WidgetMintErrorCode } {
+  if (widget.Status.trim().toLowerCase() !== 'active') {
+    return { ok: false, errorCode: 'disabled' };
+  }
+  if (!isOriginAllowed(requestOrigin, parseAllowedOrigins(widget.AllowedOrigins))) {
+    return { ok: false, errorCode: 'origin_not_allowed' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Known automated-client User-Agent substrings (lowercased). A public mint endpoint is a cheap
+ * target for crawlers and scripted abuse; this catches the obvious non-browser callers. It is a
+ * coarse FIRST line of defense (W6 "basic behavioural and user-agent checks"), NOT a CAPTCHA — the
+ * real boundaries remain the origin allowlist, rate limits, the restricted guest role, and short
+ * token TTLs. Legitimate headless integrations should embed via host-identity, not the public mint.
+ */
+const BOT_USER_AGENT_MARKERS = [
+  'bot', 'crawler', 'spider', 'scrape', 'curl', 'wget', 'python-requests',
+  'httpclient', 'okhttp', 'java/', 'go-http-client', 'libwww', 'headlesschrome', 'phantomjs',
+];
+
+/**
+ * Coarse bot heuristic for the public mint route. Returns `true` when the request should be treated as
+ * an automated client: a missing/blank User-Agent (real browsers always send one) or a UA containing a
+ * known automation marker. Deliberately conservative to avoid false positives on real browsers; pair
+ * with the origin allowlist + rate limits, which are the hard controls.
+ */
+export function looksLikeBot(userAgent: string | null | undefined): boolean {
+  const ua = (userAgent ?? '').trim().toLowerCase();
+  if (!ua) {
+    return true;
+  }
+  return BOT_USER_AGENT_MARKERS.some((marker) => ua.includes(marker));
+}
+
+/**
+ * Builds the guest-session JWT claims for a widget visitor. Reuses magic-link's
+ * `buildSessionClaims` (anonymous mode → the shared Anonymous principal + claims-based
+ * role synthesis) and layers on the additive `mj_widget_id` claim so the synthesized
+ * principal is locked to one widget instance. The role name carried here is the
+ * widget's restricted guest role (D5 backstop).
+ */
+export function buildWidgetGuestClaims(args: {
+  issuer: string;
+  audience: string;
+  widgetId: string;
+  sessionId: string;
+  anonymousEmail: string;
+  applicationId: string;
+  guestRoleName: string;
+  nowSeconds: number;
+  ttlSeconds: number;
+  /**
+   * Host-asserted identity for a `host-identity` session. Its email/name are carried as
+   * INFORMATIONAL claims only — the principal-resolving `email`/`sub` remain the shared
+   * Anonymous principal, so a host can never escalate a guest into a real account.
+   */
+  hostIdentity?: { email: string; firstName?: string; lastName?: string };
+  /**
+   * Returning-visitor anchor + linked identity (RV1/RV2/RV4) carried as claims so the VOICE path
+   * (server-created conversation) stamps the same fields the text path stamps client-side. Set only
+   * when the widget remembers returning visitors. Omitted ⇒ no returning-visitor claims (default off).
+   */
+  returningVisitor?: {
+    visitorKey?: string;
+    lastConversationId?: string;
+    linkedEntityId?: string;
+    linkedRecordId?: string;
+  };
+}): MagicLinkJWTClaims {
+  const claims = buildSessionClaims({
+    issuer: args.issuer,
+    audience: args.audience,
+    // No invite row for a direct-mint guest; the opaque session id stands in as the
+    // subject discriminator (sub = `magic-link|<sessionId>`) and scope-entry id.
+    inviteId: args.sessionId,
+    // ALWAYS the Anonymous principal email — never the host-provided one (that would let
+    // the auth middleware resolve to a real user and leak its permissions).
+    email: args.anonymousEmail,
+    applicationId: args.applicationId,
+    roleName: args.guestRoleName,
+    anonymous: true,
+    sessionId: args.sessionId,
+    // Per-session resource scope → MagicLinkScope.ResourceID on the synthesized principal.
+    // This is what the Widget Guest RLS filters key on ({{ScopeResourceID}}) to isolate one
+    // anonymous guest's conversations from another's despite the shared Anonymous UserID.
+    // It rides the SIGNED token, so a guest cannot forge another session's scope.
+    resourceType: WIDGET_SESSION_RESOURCE_TYPE,
+    resourceId: args.sessionId,
+    nowSeconds: args.nowSeconds,
+    ttlSeconds: args.ttlSeconds,
+  });
+  // Additive widget claim — lets the synthesized principal be bound to one widget.
+  claims.mj_widget_id = args.widgetId;
+  if (args.hostIdentity) {
+    claims.given_name = args.hostIdentity.firstName ?? claims.given_name;
+    claims.family_name = args.hostIdentity.lastName ?? claims.family_name;
+    claims.name = [args.hostIdentity.firstName, args.hostIdentity.lastName].filter(Boolean).join(' ') || claims.name;
+    claims.mj_host_email = args.hostIdentity.email;
+  }
+  if (args.returningVisitor) {
+    claims.mj_visitor_key = args.returningVisitor.visitorKey;
+    claims.mj_last_conversation_id = args.returningVisitor.lastConversationId;
+    claims.mj_linked_entity_id = args.returningVisitor.linkedEntityId;
+    claims.mj_linked_record_id = args.returningVisitor.linkedRecordId;
+  }
+  return claims;
+}