@memberjunction/server 5.44.0 → 5.45.0

package/dist/realtimeWidget/visitorIdentity.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @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 { UserInfo, type IMetadataProvider } from '@memberjunction/core';
+/** 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 declare function resolveIdentityByEmail(email: string, contextUser: UserInfo, provider: IMetadataProvider, target?: IdentityResolutionTarget): Promise<ResolvedVisitorIdentity | undefined>;
+/**
+ * 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 declare function mergeVisitorIdentity(args: {
+    visitorKey: string;
+    applicationId: string;
+    identity: ResolvedVisitorIdentity;
+    contextUser: UserInfo;
+    provider: IMetadataProvider;
+}): Promise<number>;
+/**
+ * "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 declare function forgetVisitor(args: {
+    visitorKey: string;
+    applicationId: string;
+    contextUser: UserInfo;
+    provider: IMetadataProvider;
+}): Promise<{
+    notesArchived: number;
+    conversationsCleared: number;
+}>;
+//# sourceMappingURL=visitorIdentity.d.ts.map

package/dist/realtimeWidget/visitorIdentity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visitorIdentity.d.ts","sourceRoot":"","sources":["../../src/realtimeWidget/visitorIdentity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAW,QAAQ,EAAuB,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAMtG,6FAA6F;AAC7F,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,4GAA4G;AAC5G,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,QAAQ,EACrB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,CAAC,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAAC,CAkC9C;AAyBD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,uBAAuB,CAAC;IAClC,WAAW,EAAE,QAAQ,CAAC;IACtB,QAAQ,EAAE,iBAAiB,CAAC;CAC7B,GAAG,OAAO,CAAC,MAAM,CAAC,CAgClB;AAoCD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,QAAQ,CAAC;IACtB,QAAQ,EAAE,iBAAiB,CAAC;CAC7B,GAAG,OAAO,CAAC;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,oBAAoB,EAAE,MAAM,CAAA;CAAE,CAAC,CAgDnE"}

package/dist/realtimeWidget/visitorIdentity.js

@@ -0,0 +1,202 @@
+/**
+ * @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, LogError, LogStatus } from '@memberjunction/core';
+const CONVERSATIONS_ENTITY = 'MJ: Conversations';
+const AGENT_NOTES_ENTITY = 'MJ: AI Agent Notes';
+/**
+ * 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, contextUser, provider, target) {
+    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({
+            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, applicationId, contextUser) {
+    const rv = new RunView();
+    // visitorKey is validated base64url by the caller; applicationId is a server-trusted UUID.
+    const result = await rv.RunView({
+        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) {
+    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, conversationsEntityId, identity, contextUser, provider) {
+    if (conversationIds.length === 0) {
+        return;
+    }
+    const inList = conversationIds.map((id) => `'${id.replace(/'/g, "''")}'`).join(', ');
+    const rv = new RunView();
+    const result = await rv.RunView({
+        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) {
+    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({
+            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 };
+}
+//# sourceMappingURL=visitorIdentity.js.map

package/dist/realtimeWidget/visitorIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visitorIdentity.js","sourceRoot":"","sources":["../../src/realtimeWidget/visitorIdentity.ts"],"names":[],"mappings":"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"}

package/dist/realtimeWidget/widgetCore.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @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 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 declare 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 declare function parseAllowedOrigins(allowedOrigins: string | null | undefined): string[];
+/**
+ * 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 declare function parseEnabledChannels(enabledChannels: string | null | undefined): string[];
+/**
+ * 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 declare function isOriginAllowed(requestOrigin: string | null | undefined, allowedOrigins: readonly string[]): boolean;
+/** True when the requested modality (or the widget's default render) is enabled by the instance. */
+export declare function isModalityEnabled(widgetModality: string, requested: 'Text' | 'Voice'): boolean;
+/**
+ * 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 declare function evaluateWidgetMint(widget: WidgetInstanceEligibilityInput, requestOrigin: string | null | undefined): {
+    ok: boolean;
+    errorCode?: WidgetMintErrorCode;
+};
+/**
+ * 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 declare function looksLikeBot(userAgent: string | null | undefined): boolean;
+/**
+ * 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 declare 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;
+//# sourceMappingURL=widgetCore.d.ts.map

package/dist/realtimeWidget/widgetCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widgetCore.d.ts","sourceRoot":"","sources":["../../src/realtimeWidget/widgetCore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D,mFAAmF;AACnF,MAAM,MAAM,mBAAmB,GACzB,WAAW,GACX,UAAU,GACV,oBAAoB,GACpB,sBAAsB,GACtB,wBAAwB,GACxB,qBAAqB,GACrB,eAAe,GACf,cAAc,CAAC;AAErB,2FAA2F;AAC3F,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CAgBvF;AAOD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CAazF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAMpH;AAED,oGAAoG;AACpG,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAM9F;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,8BAA8B,EACtC,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACvC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,mBAAmB,CAAA;CAAE,CAQlD;AAcD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAM1E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,YAAY,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE;;;;OAIG;IACH,gBAAgB,CAAC,EAAE;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH,GAAG,kBAAkB,CAsCrB"}

package/dist/realtimeWidget/widgetCore.js

@@ -0,0 +1,173 @@
+/**
+ * @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';
+/**
+ * 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';
+/**
+ * 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) {
+    const raw = allowedOrigins?.trim();
+    if (!raw) {
+        return [];
+    }
+    let list;
+    try {
+        list = JSON.parse(raw);
+    }
+    catch {
+        // Not JSON — tolerate a CSV form.
+        return raw.split(',').map((s) => normalizeOrigin(s)).filter((s) => !!s);
+    }
+    if (!Array.isArray(list)) {
+        return [];
+    }
+    return list.filter((s) => typeof s === 'string').map(normalizeOrigin).filter((s) => !!s);
+}
+/** Lowercases + trims an origin and strips a trailing slash for stable comparison. */
+function normalizeOrigin(origin) {
+    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) {
+    const raw = enabledChannels?.trim();
+    if (!raw) {
+        return [];
+    }
+    const clean = (list) => list.filter((s) => 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, allowedOrigins) {
+    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, requested) {
+    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, requestOrigin) {
+    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) {
+    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) {
+    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;
+}
+//# sourceMappingURL=widgetCore.js.map

package/dist/realtimeWidget/widgetCore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widgetCore.js","sourceRoot":"","sources":["../../src/realtimeWidget/widgetCore.ts"],"names":[],"mappings":"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"}

package/dist/realtimeWidget/widgetGuestElevation.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Privileged-dispatch elevation for public web-widget guests (public-web-widget.md
+ * Phase 0). A widget guest's session JWT authorizes ONLY its own Conversation + Conversation
+ * Details (RLS-scoped). The agent itself runs under a TRUSTED SERVER PRINCIPAL — so a guest needs
+ * no grants to WRITE the AI run entities, and cannot run an arbitrary agent under the elevated
+ * principal: the pinned agent is resolved AUTHORITATIVELY from the widget instance named by the
+ * signed `mj_widget_id` claim, never from a client-supplied agent id.
+ *
+ * The companion read-side control is the `Widget Guest: Own Agent Runs` RLS filter (seeded in the
+ * Phase 0 migration), which confines a guest to reading only its own session's run rows — closing
+ * the cross-guest leak for the voice path, where runs are still written under the guest principal.
+ *
+ * @module @memberjunction/server/widget
+ */
+import { type UserInfo, type DatabaseProviderBase } from '@memberjunction/core';
+import type { MJConversationWidgetInstanceEntity } from '@memberjunction/core-entities';
+import type { UserPayload } from '../types.js';
+/**
+ * Resolved elevation context for a widget-guest agent run. Returned only when the request is a
+ * widget guest; the dispatch resolver runs the agent under {@link WidgetGuestRunContext.elevatedUser}
+ * with {@link WidgetGuestRunContext.pinnedAgentId} (authoritative), keeping ownership checks under
+ * the guest principal.
+ */
+export interface WidgetGuestRunContext {
+    /** The trusted server principal under which the agent run (and its run-entity writes) executes. */
+    elevatedUser: UserInfo;
+    /** The widget instance the guest session is bound to (authoritative config). */
+    widget: MJConversationWidgetInstanceEntity;
+    /** The authoritative pinned support agent id — overrides any client-supplied agent id (D5). */
+    pinnedAgentId: string;
+    /** The guest's per-session scope id (Conversation.ExternalID), used to validate conversation ownership. */
+    sessionScopeId?: string;
+}
+/**
+ * Returns elevation context when the request is a public web-widget guest, else `null` (the common
+ * case — every non-widget request). A widget guest is identified by the synthesized principal's
+ * `IsMagicLinkAnonymous` flag plus a `WidgetGuestContext.WidgetID` (sourced from the signed
+ * `mj_widget_id` claim by `buildMagicLinkSessionUser`). The widget instance is loaded under the
+ * SYSTEM principal so resolving the pinned agent does not depend on the guest's narrow grants.
+ *
+ * Never throws: a resolution failure (no system user, widget not found, read error) returns `null`,
+ * so the caller falls back to the normal (guest-principal) path rather than failing the request.
+ */
+export declare function resolveWidgetGuestRunContext(userPayload: UserPayload, provider: DatabaseProviderBase): Promise<WidgetGuestRunContext | null>;
+/**
+ * Builds an elevated {@link UserPayload} that runs subsequent agent work as `elevatedUser` while
+ * preserving the guest's `sessionId` — so progress/streaming PubSub still routes to the guest's
+ * live websocket, but all AI run-entity writes happen under the trusted server principal.
+ */
+export declare function elevateUserPayload(userPayload: UserPayload, elevatedUser: UserInfo): UserPayload;
+//# sourceMappingURL=widgetGuestElevation.d.ts.map

package/dist/realtimeWidget/widgetGuestElevation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widgetGuestElevation.d.ts","sourceRoot":"","sources":["../../src/realtimeWidget/widgetGuestElevation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAqB,KAAK,QAAQ,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACnG,OAAO,KAAK,EAAE,kCAAkC,EAAE,MAAM,+BAA+B,CAAC;AAExF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI/C;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,mGAAmG;IACnG,YAAY,EAAE,QAAQ,CAAC;IACvB,gFAAgF;IAChF,MAAM,EAAE,kCAAkC,CAAC;IAC3C,+FAA+F;IAC/F,aAAa,EAAE,MAAM,CAAC;IACtB,2GAA2G;IAC3G,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAsB,4BAA4B,CAChD,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAyBvC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,GAAG,WAAW,CAOhG"}