@memberjunction/server 6.2.0-edge.4 → 6.2.0-edge.6

package/src/realtimeSessions/sessionAccess.ts

@@ -9,13 +9,17 @@
  * ## The two ownership rules
  *
  * 1. **Owner.** The session's `UserID` must be the caller's user.
- * 2. **Scope.** A *named* user is fully identified by (1). An **anonymous widget guest** is not:
- *    every guest authenticates as the one shared Anonymous user, so (1) alone would let any guest
- *    address any other guest's session. What separates guests is the signed per-session scope in
- *    their token (`MagicLinkScope.ResourceID`), which `SessionManager` stamps onto the session's
- *    Conversation as `ExternalID`. So a principal that carries a scope must match it, and an
- *    anonymous principal that carries NO scope is refused outright — it cannot be told apart from
- *    every other anonymous principal.
+ * 2. **Scope.** A *named* user is fully identified by (1). An **anonymous visitor** (widget guest or
+ *    anonymous magic-link invitee) is not: every one authenticates as the one shared Anonymous user, so
+ *    (1) alone would let any visitor address any other visitor's session. What separates them is the
+ *    scope identity {@link ResolveSessionScopeIdentity} reads off the signed token — the resource scope
+ *    (`MagicLinkScope.ResourceID`) when the token carries one, else the per-token `mj_sid`
+ *    (`AnonymousVisitorID`). `SessionManager` stamps that same value onto the session's Conversation as
+ *    `ExternalID`, so a principal with a scope identity must match it, and an anonymous principal with
+ *    none is refused outright — it cannot be told apart from every other anonymous principal.
+ *    One allowance: a NAMED principal with a resource scope may also use its own session whose
+ *    conversation carries no stamp at all, when it could read that conversation (see the comment in
+ *    {@link AuthorizeSessionAccess}).
  *
  * The decision is deliberately pure (no I/O) so it can be applied identically to a freshly loaded
  * row at subscribe time and to the owner/scope snapshot carried inside each published event.
@@ -41,14 +45,22 @@ export interface SessionAccessSubject {
      * could not be loaded.
      */
     ConversationExternalID: string | null | undefined;
+    /**
+     * True when the conversation was loaded under the CALLER's identity (so its row-level security allowed
+     * the read). Only consulted for a named principal with a resource scope on a conversation that carries
+     * no `ExternalID`; omitted means unknown and is treated as unreadable (fail closed).
+     */
+    ConversationReadable?: boolean;
 }
 
 /** What the decision needs to know about the caller (a subset of `UserInfo`). */
 export interface SessionAccessPrincipal {
     /** The caller's user id. */
     ID: string;
-    /** True for the shared-Anonymous-user principal of a public-widget guest. */
+    /** True for the shared-Anonymous-user principal of a public-widget guest or anonymous magic-link invitee. */
     IsMagicLinkAnonymous?: boolean;
+    /** Per-visitor session identity (`mj_sid`) for an anonymous principal. */
+    AnonymousVisitorID?: string;
     /** The signed per-session scope carried by the caller's token, when any. */
     MagicLinkScope?: { ResourceID?: string } | undefined;
 }
@@ -57,7 +69,29 @@ export interface SessionAccessPrincipal {
 export type SessionAccessRefusal = 'not_owner' | 'scope_missing' | 'scope_mismatch';
 
 /** Outcome of {@link AuthorizeSessionAccess}. */
-export type SessionAccessDecision = { Allowed: true } | { Allowed: false; Reason: SessionAccessRefusal };
+export type SessionAccessDecision =
+    | { Allowed: true; Reason?: undefined }
+    | { Allowed: false; Reason: SessionAccessRefusal };
+
+/**
+ * The scope identity a session is keyed on for `principal` — the one value `SessionManager` stamps as
+ * the session conversation's `ExternalID` and {@link AuthorizeSessionAccess} compares against it.
+ *
+ * - The token's resource scope (`MagicLinkScope.ResourceID`) when it carries one. A widget guest's
+ *   resource scope IS its `mj_sid`; an anonymous magic-link invite with a `ResourceID` (e.g. a Caliber
+ *   Invite Scope, one per subject) shares that scope across its redemptions by design, and the
+ *   `{{ScopeResourceID}}` RLS filters key on the same value, so the visitor can read its own rows.
+ * - Otherwise, for an anonymous principal, the per-token `mj_sid` (`AnonymousVisitorID`), which tells two
+ *   redemptions of an unscoped multi-use invite apart.
+ * - Otherwise `undefined` (a named user without a resource scope).
+ */
+export function ResolveSessionScopeIdentity(principal: SessionAccessPrincipal): string | undefined {
+    const resourceId = principal.MagicLinkScope?.ResourceID;
+    if (resourceId) {
+        return resourceId;
+    }
+    return principal.IsMagicLinkAnonymous ? principal.AnonymousVisitorID || undefined : undefined;
+}
 
 /**
  * Decides whether `principal` may address the session described by `subject`.
@@ -74,14 +108,26 @@ export function AuthorizeSessionAccess(
     if (!principal?.ID || !subject.SessionUserID || !UUIDsEqual(subject.SessionUserID, principal.ID)) {
         return { Allowed: false, Reason: 'not_owner' };
     }
-    const scopeId = principal.MagicLinkScope?.ResourceID;
+    const scopeId = ResolveSessionScopeIdentity(principal);
     if (!scopeId) {
-        // An anonymous principal without a per-session scope is indistinguishable from every other
-        // anonymous principal: owning "the Anonymous user's" session proves nothing.
+        // A named user without a scope is identified by the owner check alone; an anonymous principal
+        // without one cannot be told apart from any other anonymous principal.
         return principal.IsMagicLinkAnonymous ? { Allowed: false, Reason: 'scope_missing' } : { Allowed: true };
     }
     // Scope ids are opaque base64url strings (case-significant), so compare exactly — not UUIDsEqual.
-    return subject.ConversationExternalID === scopeId ? { Allowed: true } : { Allowed: false, Reason: 'scope_mismatch' };
+    if (subject.ConversationExternalID === scopeId) {
+        return { Allowed: true };
+    }
+    // A named user is identified by the owner check; its scope only keeps one link's sessions apart from
+    // the same person's other links (magic links resolve the user by email, so one person can hold several).
+    // A conversation with no stamp belongs to no link (one started from the Conversations app), so the owner
+    // may use it when its own row-level security let it read the conversation. `ExternalID` is not stamped
+    // here because other features own that column on their conversations (meeting room names, for example).
+    // An anonymous visitor gets no such allowance: the stamp is the only thing that identifies it.
+    if (!principal.IsMagicLinkAnonymous && subject.ConversationExternalID === null && subject.ConversationReadable === true) {
+        return { Allowed: true };
+    }
+    return { Allowed: false, Reason: 'scope_mismatch' };
 }
 
 /** A session row together with the one fact about its conversation the decision needs. */
@@ -90,6 +136,8 @@ export interface LoadedSessionForAccess {
     Session: MJAIAgentSessionEntity;
     /** The session's conversation `ExternalID` (anonymous scope id), or null. */
     ConversationExternalID: string | null;
+    /** Whether the caller could read the session's conversation (false when there is none). */
+    ConversationReadable: boolean;
 }
 
 /**
@@ -115,27 +163,139 @@ export async function LoadSessionForAccess(
     if (!(await session.Load(agentSessionId))) {
         return null;
     }
-    return { Session: session, ConversationExternalID: await loadConversationExternalID(session, contextUser, provider) };
+    const conversation = await LoadSessionConversationScope(session, contextUser, provider);
+    return { Session: session, ConversationExternalID: conversation.ExternalID, ConversationReadable: conversation.Readable };
 }
 
-/** Reads the session conversation's `ExternalID`; null when there is no conversation or it cannot be read. */
-async function loadConversationExternalID(
+/** What the caller could learn about a session's conversation: the scope half of {@link SessionAccessSubject}. */
+export interface SessionConversationScope {
+    /** The conversation's `ExternalID` (the anonymous scope id), or null when it has none or was not read. */
+    ExternalID: string | null;
+    /** Whether the caller could read the conversation (false when the session has none). */
+    Readable: boolean;
+}
+
+/** {@link SessionConversationScope} plus the conversation's owner, for a conversation addressed without a session. */
+export interface ConversationScope extends SessionConversationScope {
+    /** `Conversation.UserID`, or null when the conversation was not read. */
+    UserID: string | null;
+}
+
+/**
+ * Reads an already-loaded session's conversation under `contextUser` (so its row-level security applies).
+ * A missing conversation, a refused read and a failed read (logged) all report `Readable: false`. For
+ * callers that loaded the session through another gate and only need the scope half of
+ * {@link AuthorizeSessionAccess}'s subject.
+ */
+export async function LoadSessionConversationScope(
     session: MJAIAgentSessionEntity,
     contextUser: UserInfo,
     provider: IMetadataProvider,
-): Promise<string | null> {
+): Promise<SessionConversationScope> {
     if (!session.ConversationID) {
-        return null;
+        return { ExternalID: null, Readable: false };
+    }
+    const { ExternalID, Readable } = await LoadConversationScope(session.ConversationID, contextUser, provider);
+    return { ExternalID, Readable };
+}
+
+/**
+ * Reads a conversation's owner and scope id under `contextUser` (so its row-level security applies), for a
+ * caller that addresses the conversation directly rather than through a session — a text agent turn, for
+ * example, whose only handle is a message in it. Together with the caller's principal this is exactly the
+ * subject {@link AuthorizeSessionAccess} decides on: `SessionUserID` is the conversation's owner, since the
+ * session a conversation belongs to is owned by the same user.
+ *
+ * An empty id, a missing conversation, a refused read and a failed read (logged) all report
+ * `Readable: false` with no owner, which {@link AuthorizeSessionAccess} then refuses for any scoped caller.
+ */
+export async function LoadConversationScope(
+    conversationId: string | null | undefined,
+    contextUser: UserInfo,
+    provider: IMetadataProvider,
+): Promise<ConversationScope> {
+    const unreadable: ConversationScope = { UserID: null, ExternalID: null, Readable: false };
+    if (!conversationId) {
+        return unreadable;
     }
     try {
         const conversation = await provider.GetEntityObject<MJConversationEntity>(CONVERSATION_ENTITY, contextUser);
-        if (!(await conversation.Load(session.ConversationID))) {
-            return null;
+        if (!(await conversation.Load(conversationId))) {
+            return unreadable;
         }
-        return conversation.ExternalID ?? null;
+        return { UserID: conversation.UserID ?? null, ExternalID: conversation.ExternalID ?? null, Readable: true };
     } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        LogError(`LoadSessionForAccess: could not read conversation ${session.ConversationID} of session ${session.ID}: ${message}`);
-        return null;
+        LogError(`LoadConversationScope: could not read conversation ${conversationId} for user ${contextUser?.ID}: ${message}`);
+        return unreadable;
     }
 }
+
+/**
+ * Who may run a conversation turn (a text agent turn, addressed by a message in the conversation) in
+ * `conversationId`, decided the same way as session access.
+ *
+ * A NAMED principal is allowed without a read: its entity permissions and row filters already decided
+ * whether it could load the message, and a named user is fully identified by its `UserID`. An ANONYMOUS
+ * principal is not (see the module doc), so the conversation is read as the caller and
+ * {@link AuthorizeSessionAccess} compares its scope id with the conversation's stamp — the same
+ * decision #5997 applies to the realtime gates, so the text and voice paths agree on ownership.
+ * An unreadable conversation refuses (`not_owner`, there is no owner to match).
+ */
+export async function AuthorizeConversationTurn(
+    conversationId: string,
+    principal: UserInfo,
+    provider: IMetadataProvider,
+): Promise<SessionAccessDecision> {
+    if (!principal?.IsMagicLinkAnonymous) {
+        return { Allowed: true };
+    }
+    const scope = await LoadConversationScope(conversationId, principal, provider);
+    return AuthorizeSessionAccess(
+        { SessionUserID: scope.UserID ?? '', ConversationExternalID: scope.ExternalID, ConversationReadable: scope.Readable },
+        principal,
+    );
+}
+
+/**
+ * Whether an anonymous caller owns any of a LiveKit room's agent sessions — the check MJServer registers with
+ * `RoomAuthorizationService.SetAnonymousSessionOwnerCheck` (`@memberjunction/livekit-room-server` cannot import
+ * this package). Each session is loaded as the caller (its row-level security applies) and decided by
+ * {@link AuthorizeSessionAccess}, the same decision every realtime gate makes, so a room admits exactly the visitor
+ * whose scope id its session's conversation carries (MJ#6044). Nothing to read, or no provider: refused.
+ */
+export async function AuthorizeAnonymousRoomSessions(
+    agentSessionIds: string[],
+    user: UserInfo,
+    provider: IMetadataProvider | undefined,
+): Promise<boolean> {
+    if (agentSessionIds.length === 0 || !provider) {
+        return false;
+    }
+    for (const agentSessionId of agentSessionIds) {
+        const loaded = await LoadSessionForAccess(agentSessionId, user, provider);
+        if (!loaded) {
+            continue;
+        }
+        const decision = AuthorizeSessionAccess(
+            { SessionUserID: loaded.Session.UserID, ConversationExternalID: loaded.ConversationExternalID, ConversationReadable: loaded.ConversationReadable },
+            user,
+        );
+        if (decision.Allowed) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * The session conversation's `ExternalID` alone; null when there is none or it cannot be read.
+ * Prefer {@link LoadSessionConversationScope}, which also says whether the read succeeded.
+ */
+export async function LoadSessionConversationExternalID(
+    session: MJAIAgentSessionEntity,
+    contextUser: UserInfo,
+    provider: IMetadataProvider,
+): Promise<string | null> {
+    return (await LoadSessionConversationScope(session, contextUser, provider)).ExternalID;
+}

package/src/realtimeSessions/sessionConfigStamps.ts

@@ -113,7 +113,7 @@ export async function LoadInheritedVerifiedIdentity(
         return undefined;
     }
     const decision = AuthorizeSessionAccess(
-        { SessionUserID: prior.Session.UserID, ConversationExternalID: prior.ConversationExternalID },
+        { SessionUserID: prior.Session.UserID, ConversationExternalID: prior.ConversationExternalID, ConversationReadable: prior.ConversationReadable },
         contextUser,
     );
     if (decision.Allowed === false) {

package/src/realtimeSessions/subscriptionAuthorization.ts

@@ -61,7 +61,9 @@ export function RealtimeSessionEventsFilter(data: {
         return false;
     }
     const decision = AuthorizeSessionAccess(
-        { SessionUserID: payload.OwnerUserID, ConversationExternalID: payload.ScopeKey },
+        // Readability is per caller and was proven when this subscription opened (it only receives events for
+        // that one session); the snapshot carries just the stamp, so a null ScopeKey stays usable by that owner.
+        { SessionUserID: payload.OwnerUserID, ConversationExternalID: payload.ScopeKey, ConversationReadable: true },
         connectionPrincipal(context),
     );
     return decision.Allowed;
@@ -105,7 +107,7 @@ export async function AuthorizeRealtimeSessionSubscription(
         throw new Error(REFUSAL_MESSAGE);
     }
     const decision = AuthorizeSessionAccess(
-        { SessionUserID: loaded.Session.UserID, ConversationExternalID: loaded.ConversationExternalID },
+        { SessionUserID: loaded.Session.UserID, ConversationExternalID: loaded.ConversationExternalID, ConversationReadable: loaded.ConversationReadable },
         principal,
     );
     if (decision.Allowed === false) {

package/src/realtimeSessions/verificationWorkflow.ts

@@ -90,6 +90,8 @@ export interface SessionSnapshot {
     OwnerUserID: string;
     /** `Conversation.ExternalID` (anonymous scope id), or null. */
     ConversationExternalID: string | null;
+    /** Whether the caller could read the session's conversation. */
+    ConversationReadable: boolean;
     Status: 'Active' | 'Idle' | 'Closed';
     /** `AIAgentSession.Config` as stored. */
     ConfigRaw: string | null;
@@ -660,7 +662,7 @@ export class RealtimeSessionVerificationWorkflow {
             return notFound;
         }
         const decision = AuthorizeSessionAccess(
-            { SessionUserID: session.OwnerUserID, ConversationExternalID: session.ConversationExternalID },
+            { SessionUserID: session.OwnerUserID, ConversationExternalID: session.ConversationExternalID, ConversationReadable: session.ConversationReadable },
             caller.ContextUser,
         );
         if (decision.Allowed === false) {

package/src/realtimeWidget/WidgetRouter.ts

@@ -13,10 +13,11 @@
 import { Router, json, type Request, type Response } from 'express';
 import { rateLimit, ipKeyGenerator } from 'express-rate-limit';
 import { LogStatus } from '@memberjunction/core';
+import type { ProofPublicJwk } from '@memberjunction/global';
 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 { WidgetSessionService, WIDGET_REFRESH_PATH, type MintGuestSessionResult } from './WidgetSessionService.js';
 import { LooksLikeBot } from './widgetCore.js';
 
 /** The mount path for the widget public router (`/widget`). */
@@ -54,7 +55,9 @@ function ensureWidgetSigning(publicUrl: string, widgetConfig: WidgetConfig): voi
 export function CreateWidgetHandler(publicUrl: string, config: WidgetConfig): { publicRouter: Router; authenticatedRouter: Router } {
   ensureWidgetSigning(publicUrl, config);
 
-  const service = new WidgetSessionService(publicUrl, config);
+  // A widget may hand an anonymous guest only a scope-isolated role (MJ#6043); the opt-in list is the one
+  // magic-link invites already use, so an admin declares "safe for anonymous visitors" in one place.
+  const service = new WidgetSessionService(publicUrl, config, { GrantableRoleNames: configInfo.magicLink?.grantableRoleNames ?? [] });
 
   // 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
@@ -80,7 +83,7 @@ export function CreateWidgetHandler(publicUrl: string, config: WidgetConfig): {
     await handleMint(service, req, res, false);
   });
 
-  publicRouter.post('/session/refresh', json(), mintLimiter, async (req: Request, res: Response) => {
+  publicRouter.post(WIDGET_REFRESH_PATH, json(), mintLimiter, async (req: Request, res: Response) => {
     await handleMint(service, req, res, true);
   });
 
@@ -171,14 +174,26 @@ async function handleUpgrade(service: WidgetSessionService, req: Request, res: R
   res.status(status).json(result);
 }
 
+/** Extracts a raw JWT from an `Authorization: Bearer <token>` header, or undefined when absent/malformed. */
+function extractBearerToken(authHeader: string | undefined): string | undefined {
+  if (!authHeader) {
+    return undefined;
+  }
+  const match = /^Bearer\s+(\S+)$/i.exec(authHeader.trim());
+  const token = match?.[1]?.trim();
+  return token && token.length > 0 ? token : undefined;
+}
+
 /** 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 body = (req.body ?? {}) as { widgetKey?: string; hostAssertion?: string; visitorKey?: string; proofKey?: unknown };
   const widgetKey = typeof body.widgetKey === 'string' ? body.widgetKey : '';
   if (!widgetKey) {
     res.status(400).json({ success: false, errorCode: 'not_found', error: 'widgetKey is required.' });
     return;
   }
+  // The service validates the key's shape (ToProofPublicJwk) and refuses anything that is not a public P-256 JWK.
+  const proofKey = body.proofKey === undefined ? undefined : (body.proofKey as ProofPublicJwk);
 
   // 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".
@@ -193,6 +208,9 @@ async function handleMint(service: WidgetSessionService, req: Request, res: Resp
     origin,
     hostAssertion: typeof body.hostAssertion === 'string' ? body.hostAssertion : undefined,
     visitorKey: typeof body.visitorKey === 'string' ? body.visitorKey : undefined,
+    BearerToken: refresh ? extractBearerToken(req.get('authorization')) : undefined,
+    Proof: refresh ? req.get('dpop') : undefined,
+    ProofKey: refresh ? undefined : proofKey,
     audit: { ipAddress: req.ip, userAgent: req.get('user-agent') ?? undefined, origin },
   };
   const result = refresh ? await service.RefreshGuestSession(input) : await service.MintGuestSession(input);