@memberjunction/server 6.2.0-edge.5 → 6.2.0-edge.7

package/src/integration/ScopedFieldsForBuild.ts

@@ -0,0 +1,113 @@
+/**
+ * The FIELD rows a schema build materializes, for a connection with its own catalog.
+ *
+ * A schema build (ApplySchema, ApplyAll, ApplyAllBatch, the connector build, schema evolution)
+ * reconstructs the source schema from persisted catalog rows and hands it to SchemaBuilder. It used
+ * to read each object's fields from the engine's in-memory catalog. Once a connection's field rows
+ * are no longer held resident — they are warmed per object on demand, and the only site that warms
+ * them is the sync loop — that read answers `[]` for every object of the connection, and an object
+ * with no fields materializes nothing. Observed on a per-connection catalog (364 objects, 7,230
+ * active fields): the apply logged "Reusing 364 persisted IOs", then ran a migration with an empty
+ * table list in 4 ms — no CREATE, no ALTER, no error.
+ *
+ * So the build reads the connection's field rows itself: one read per {@link SCOPED_FIELDS_CHUNK}
+ * objects, plain rows, bypassing the query cache (an answer cached before discovery's persist is the
+ * empty set), and without the row cap (one object can carry thousands of fields). A failed read
+ * THROWS: an empty answer here is exactly what produced the zero-table apply.
+ *
+ * Outside a per-connection scope — or for a connection without its own catalog — this returns
+ * `null`, and the build reads the shared catalog from memory exactly as before.
+ */
+import { RunView, type UserInfo } from '@memberjunction/core';
+import type { MJIntegrationObjectFieldEntity } from '@memberjunction/core-entities';
+import {
+    IntegrationEngineBase,
+    ENTITY_COMPANY_INTEGRATION_OBJECT_FIELDS,
+    type CompanyIntegrationObjectFieldRow,
+} from '@memberjunction/integration-engine-base';
+import { CurrentCatalogCI } from '@memberjunction/integration-engine';
+
+/**
+ * What a schema build — and a refresh's re-key check — reads off a field row. The shared entity and
+ * the per-connection row both satisfy it.
+ */
+export type BuildFieldRow = Pick<
+    MJIntegrationObjectFieldEntity,
+    'Name' | 'DisplayName' | 'Description' | 'Type' | 'IsRequired' | 'AllowsNull' | 'Length' | 'Precision'
+    | 'Scale' | 'DefaultValue' | 'IsPrimaryKey' | 'IsUniqueKey' | 'IsReadOnly' | 'RelatedIntegrationObjectID' | 'Status'
+    | 'Sequence'
+>;
+
+/** A connection's field rows, keyed by lower-cased per-connection object id. */
+export type ScopedBuildFields = Map<string, CompanyIntegrationObjectFieldRow[]>;
+
+/** Objects per read. Each read is one `IN (…)` list, so this bounds the filter's length. */
+export const SCOPED_FIELDS_CHUNK = 200;
+
+/** A per-connection field row as the database returns it — before the legacy read names are derived. */
+type StoredFieldRow = Omit<CompanyIntegrationObjectFieldRow, 'IntegrationObjectID' | 'RelatedIntegrationObjectID'>;
+
+/**
+ * Loads the field rows of the connection in catalog scope for a schema build, or returns `null`
+ * when the build should read the shared catalog (no scope, or no per-connection catalog).
+ *
+ * @throws PER_CONNECTION_FIELDS_UNREADABLE when a read fails — never an empty answer.
+ */
+export async function LoadScopedFieldsForBuild(integrationID: string, user: UserInfo): Promise<ScopedBuildFields | null> {
+    const ciID = CurrentCatalogCI();
+    if (!ciID) return null;
+    const engine = IntegrationEngineBase.Instance;
+    if (!engine.HasCompanyIntegrationCatalog(ciID)) return null;
+
+    const objects = engine.GetActiveIntegrationObjects(integrationID);
+    const byObject: ScopedBuildFields = new Map();
+    const rv = new RunView();
+    for (let i = 0; i < objects.length; i += SCOPED_FIELDS_CHUNK) {
+        const chunk = objects.slice(i, i + SCOPED_FIELDS_CHUNK);
+        const ids = chunk.map(o => `'${String(o.ID).replace(/'/g, "''")}'`).join(',');
+        const res = await rv.RunView<StoredFieldRow>({
+            EntityName: ENTITY_COMPANY_INTEGRATION_OBJECT_FIELDS,
+            ExtraFilter: `CompanyIntegrationObjectID IN (${ids})`,
+            ResultType: 'simple',
+            BypassCache: true,
+            IgnoreMaxRows: true,
+        }, user);
+        if (!res?.Success) {
+            throw new Error(
+                `PER_CONNECTION_FIELDS_UNREADABLE: could not read the field rows of connection ${ciID} ` +
+                `(objects ${i + 1}-${i + chunk.length} of ${objects.length}): ${res?.ErrorMessage ?? 'unknown error'}. ` +
+                `Refusing to build a schema from an empty field list.`
+            );
+        }
+        for (const row of res.Results ?? []) addRow(byObject, row);
+    }
+    const rowCount = [...byObject.values()].reduce((n, rows) => n + rows.length, 0);
+    console.log(`[LoadScopedFieldsForBuild] connection ${ciID}: ${rowCount} field rows for ${byObject.size} of ${objects.length} active objects`);
+    return byObject;
+}
+
+/**
+ * The fields a build reads for one object: the connection's rows when they were loaded, the
+ * engine's catalog otherwise. With loaded rows the engine is not consulted at all, so a cold
+ * per-connection field cache cannot empty the build.
+ */
+export function FieldsForBuild(objectID: string, scoped: ScopedBuildFields | null | undefined, engine: IntegrationEngineBase): BuildFieldRow[] {
+    if (scoped) return scoped.get(String(objectID).trim().toLowerCase()) ?? [];
+    return engine.GetIntegrationObjectFields(objectID);
+}
+
+/**
+ * Files one stored row under its object, deriving the two legacy names the build reads
+ * (`IntegrationObjectID`, `RelatedIntegrationObjectID`) exactly as the engine's projection does.
+ */
+function addRow(byObject: ScopedBuildFields, row: StoredFieldRow): void {
+    const key = String(row.CompanyIntegrationObjectID).trim().toLowerCase();
+    const projected: CompanyIntegrationObjectFieldRow = {
+        ...row,
+        IntegrationObjectID: row.CompanyIntegrationObjectID,
+        RelatedIntegrationObjectID: row.RelatedCompanyIntegrationObjectID ?? null,
+    };
+    const bucket = byObject.get(key);
+    if (bucket) bucket.push(projected);
+    else byObject.set(key, [projected]);
+}

package/src/integration/TargetConfigGuard.ts

@@ -0,0 +1,71 @@
+/**
+ * Refuses a schema build whose selected objects produced no target table.
+ *
+ * `buildTargetConfigs` drops a selected object that is not in the source schema, has no fields or
+ * has no primary key, and logs each drop — but every execution caller then built and ran a migration
+ * anyway. With nothing accepted that migration is a header-only file: RSU wrote it, opened and merged
+ * a PR, ran CodeGen, redeployed Explorer, and the sync "completed" over zero entity maps, every signal
+ * green. Seen 2026-10-29 on a PropFuel connection: three selections requested, three dropped as
+ * notInSchema, three empty migrations committed.
+ *
+ * A caller that asked for tables and gets none has failed, and should hear so with the names it asked
+ * for and why each was dropped — in the error itself, because an API or UI caller cannot read the
+ * server log line that used to be the only place the reasons appeared. Preview is deliberately not
+ * gated: an empty preview is an honest answer.
+ */
+import type { TargetTableConfig } from '@memberjunction/integration-schema-builder';
+
+/** Why `buildTargetConfigs` left each selected object out. */
+export interface TargetConfigDrops {
+    NotInSchema: string[];
+    NoFields: string[];
+    NoPrimaryKey: string[];
+}
+
+/** How many names one list in the error shows before summarising the rest — the summary log's cap. */
+export const TARGET_CONFIG_NAME_SAMPLE = 5;
+
+/** An empty set of drop lists, for `buildTargetConfigs` to fill. */
+export function NewTargetConfigDrops(): TargetConfigDrops {
+    return { NotInSchema: [], NoFields: [], NoPrimaryKey: [] };
+}
+
+/** `a, b, c, d, e and 163 more` — so a large selection cannot make a multi-KB error. */
+export function SampleNames(names: ReadonlyArray<string>): string {
+    const head = names.slice(0, TARGET_CONFIG_NAME_SAMPLE).join(', ');
+    const rest = names.length - TARGET_CONFIG_NAME_SAMPLE;
+    return rest > 0 ? `${head} and ${rest} more` : head;
+}
+
+/**
+ * Throws `NO_TARGET_TABLES` when objects were selected and none produced a target table.
+ *
+ * @param drops why each object was dropped; without it the error lists the three possible reasons.
+ * @param alreadyCommitted what the caller had already written before the build, for a caller that
+ *   cannot honestly say "Nothing was applied" (schema evolution persists the catalog and disables the
+ *   removed objects' maps first).
+ */
+export function AssertTargetConfigs(
+    objects: ReadonlyArray<{ SourceObjectName: string }>,
+    targetConfigs: ReadonlyArray<TargetTableConfig>,
+    sourceType: string,
+    drops?: TargetConfigDrops,
+    alreadyCommitted?: string,
+): void {
+    if (objects.length === 0 || targetConfigs.length > 0) return;
+    const reasons = drops ? describeDrops(drops) : '';
+    throw new Error(
+        `NO_TARGET_TABLES: none of the ${objects.length} selected object(s) for ${sourceType} produced a target table ` +
+        `(${SampleNames(objects.map(o => o.SourceObjectName))}). ` +
+        (reasons || 'Each was dropped as not in the source schema, without fields, or without a primary key.') +
+        ` ${alreadyCommitted ?? 'Nothing was applied.'} Re-run discovery for this connection and apply again.`
+    );
+}
+
+function describeDrops(drops: TargetConfigDrops): string {
+    const parts: string[] = [];
+    if (drops.NotInSchema.length > 0) parts.push(`not in the source schema: ${SampleNames(drops.NotInSchema)}`);
+    if (drops.NoFields.length > 0) parts.push(`no fields: ${SampleNames(drops.NoFields)}`);
+    if (drops.NoPrimaryKey.length > 0) parts.push(`no primary key: ${SampleNames(drops.NoPrimaryKey)}`);
+    return parts.length > 0 ? `Dropped as ${parts.join('; ')}.` : '';
+}

package/src/logging/variablesLoggingMiddleware.ts

@@ -1,7 +1,7 @@
-import type { MiddlewareFn } from 'type-graphql';
+import type { MiddlewareFn, ResolverData } from 'type-graphql';
 import { getMetadataStorage } from 'type-graphql';
-import { getNamedType } from 'graphql';
-import type { GraphQLArgument } from 'graphql';
+import { defaultFieldResolver, getNamedType } from 'graphql';
+import type { GraphQLArgument, GraphQLField, GraphQLObjectType, GraphQLSchema } from 'graphql';
 import { configInfo } from '../config.js';
 import type { AppContext } from '../types.js';
 import { RedactArg } from './secretRedactor.js';
@@ -191,6 +191,62 @@ export const VariablesLoggingMiddleware: MiddlewareFn<AppContext> = async (actio
 /** @deprecated Use {@link VariablesLoggingMiddleware}. */
 export const variablesLoggingMiddleware: MiddlewareFn<AppContext> = VariablesLoggingMiddleware;
 
+/**
+ * Attaches {@link VariablesLoggingMiddleware} ONLY to root `Query`, `Mutation`, and `Subscription`
+ * fields on the compiled GraphQLSchema instead of registering it via TypeGraphQL `globalMiddlewares`.
+ *
+ * Registering a global middleware in TypeGraphQL wraps every scalar and child field resolver across
+ * all 300+ `@ObjectType` entities in an async middleware chain, allocating $O(\text{Rows} \times \text{Fields})$
+ * Promises per query even when `logVariables` is false or `info.path.prev !== undefined`.
+ * Wrapping only the root operation fields reduces middleware invocations from ~15,000 per 500-row
+ * `RunView` response down to 1.
+ */
+export function ApplyRootVariablesLoggingMiddleware(
+  schema: GraphQLSchema,
+  middleware: MiddlewareFn<AppContext> = VariablesLoggingMiddleware
+): GraphQLSchema {
+  const rootTypes: Array<GraphQLObjectType | null | undefined> = [
+    schema.getQueryType(),
+    schema.getMutationType(),
+    schema.getSubscriptionType(),
+  ];
+
+  for (const rootType of rootTypes) {
+    if (!rootType) continue;
+    const fields = rootType.getFields();
+    for (const field of Object.values(fields) as Array<GraphQLField<unknown, AppContext>>) {
+      if (field.resolve) {
+        const originalResolve = field.resolve;
+        field.resolve = (root, args, context, info) => {
+          const action: ResolverData<AppContext> = {
+            root,
+            args: args as Record<string, unknown>,
+            context,
+            info,
+          };
+          return middleware(action, async () => originalResolve(root, args, context, info));
+        };
+      }
+      if (field.subscribe) {
+        const originalSubscribe = field.subscribe;
+        field.subscribe = (root, args, context, info) => {
+          const action: ResolverData<AppContext> = {
+            root,
+            args: args as Record<string, unknown>,
+            context,
+            info,
+          };
+          return middleware(action, async () =>
+            originalSubscribe ? originalSubscribe(root, args, context, info) : defaultFieldResolver(root, args, context, info)
+          );
+        };
+      }
+    }
+  }
+
+  return schema;
+}
+
 /**
  * Heuristic: an arg is "custom" (i.e. needs `@NoLog` discipline because metadata can't redact it)
  * when its GraphQL input type is not a known `Create<X>Input` / `Update<X>Input` for an entity

package/src/realtimeSessions/README.md

@@ -64,9 +64,13 @@ The principal comes from the **server-authenticated** context (`userPayload.user
 argument. An id argument only selects *which of the caller's own sessions*.
 
 A caller may use a session when `AIAgentSession.UserID` equals their user (`UUIDsEqual`). Widget guests all
-share one Anonymous user, so for an anonymous/magic-link principal that is **not enough**: the guest's
-signed per-session scope (`MagicLinkScope.ResourceID`) must equal the session's conversation `ExternalID`.
-An anonymous principal with no scope is refused outright.
+share one Anonymous user, so for an anonymous/magic-link principal that is **not enough**: the session's
+conversation `ExternalID` must equal the principal's scope identity (`ResolveSessionScopeIdentity`): the
+signed `MagicLinkScope.ResourceID` when the token carries one, else the anonymous visitor's `mj_sid`.
+`SessionManager` stamps that same value when it creates the conversation. An anonymous principal with
+neither is refused outright. A *named* user with a resource scope must match too, which keeps one person's
+different links apart; but it may also use its own session on a conversation that carries no stamp (one
+started from the Conversations app) when its own row-level security let it read that conversation.
 
 - Refusals are uniform ("session not found") whether the session is missing or simply not yours, so ids
   cannot be probed.

package/src/realtimeSessions/SessionVerificationPortsBase.ts

@@ -54,6 +54,7 @@ function toSnapshot(loaded: LoadedSessionForAccess): SessionSnapshot {
         AgentSessionID: Session.ID,
         OwnerUserID: Session.UserID,
         ConversationExternalID: loaded.ConversationExternalID,
+        ConversationReadable: loaded.ConversationReadable,
         Status: Session.Status,
         ConfigRaw: Session.Config_,
         // `__mj_CreatedAt` is the row's creation instant — i.e. the session start. It is read-only and

package/src/realtimeSessions/ownedRealtimeSession.ts

@@ -8,6 +8,7 @@
 import { IMetadataProvider, LogError, UserInfo } from '@memberjunction/core';
 import { UUIDsEqual } from '@memberjunction/global';
 import type { MJAIAgentSessionEntity } from '@memberjunction/core-entities';
+import { AuthorizeLoadedSession } from './sessionAccess.js';
 
 const SESSION_ENTITY = 'MJ: AI Agent Sessions';
 
@@ -19,7 +20,7 @@ export class RealtimeSessionNotFoundError extends Error {
     }
 }
 
-/** The session exists but belongs to another user. */
+/** The session exists but the caller may not use it: another user owns it, or (for a scoped or anonymous caller) its conversation carries another scope identity. */
 export class RealtimeSessionOwnershipError extends Error {
     constructor(public readonly AgentSessionID: string) {
         super('Not authorized: you do not own this realtime session');
@@ -28,13 +29,15 @@ export class RealtimeSessionOwnershipError extends Error {
 }
 
 /**
- * Loads a session under the caller's identity and enforces ownership (`UserID === contextUser.ID`). It
- * deliberately does NOT reject `Closed` sessions: the final channel-state flush and the recording terminal
- * signal legitimately arrive after the session closed. A scoped-anonymous widget guest owns the session it
- * minted, so the same check covers it; loading as the caller also applies the entity's row-level security.
+ * Loads a session under the caller's identity and enforces ownership: `UserID === contextUser.ID`, then the
+ * scope rule of {@link AuthorizeSessionAccess} (every anonymous visitor shares one Anonymous user, so the
+ * session's conversation `ExternalID` must equal the caller's scope identity). It deliberately does NOT
+ * reject `Closed` sessions: the final channel-state flush and the recording terminal signal legitimately
+ * arrive after the session closed. Loading as the caller also applies the entity's row-level security.
  *
  * @throws RealtimeSessionNotFoundError when the row does not load
- * @throws RealtimeSessionOwnershipError when the caller is not the owner (logged with both user ids)
+ * @throws RealtimeSessionOwnershipError when another user owns the session (logged with both user ids) or
+ *   the scope rule refuses the caller (logged with the refusal reason)
  */
 export async function LoadOwnedRealtimeSession(
     agentSessionId: string,
@@ -51,5 +54,12 @@ export async function LoadOwnedRealtimeSession(
         );
         throw new RealtimeSessionOwnershipError(agentSessionId);
     }
+    const access = await AuthorizeLoadedSession(session, contextUser, provider);
+    if (!access.Allowed) {
+        LogError(
+            `LoadOwnedRealtimeSession: session access refused (${access.Reason}) — user ${contextUser.ID} attempted to operate on session ${agentSessionId}`,
+        );
+        throw new RealtimeSessionOwnershipError(agentSessionId);
+    }
     return session;
 }

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,31 +163,169 @@ export async function LoadSessionForAccess(
     if (!(await session.Load(agentSessionId))) {
         return null;
     }
-    return { Session: session, ConversationExternalID: await LoadSessionConversationExternalID(session, contextUser, provider) };
+    const conversation = await LoadSessionConversationScope(session, contextUser, provider);
+    return { Session: session, ConversationExternalID: conversation.ExternalID, ConversationReadable: conversation.Readable };
+}
+
+/** 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 `ExternalID` (the anonymous scope id) under `contextUser`;
- * null when there is no conversation or it cannot be read (logged). For callers that loaded the session
- * through another gate and only need the scope half of {@link AuthorizeSessionAccess}'s subject.
+ * 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 LoadSessionConversationExternalID(
+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 };
+}
+
+/**
+ * Decides whether `contextUser` may address an already-loaded `session`: the {@link AuthorizeSessionAccess}
+ * decision, reading the session's conversation only when that decision needs it.
+ *
+ * {@link AuthorizeSessionAccess} decides a principal without a scope identity — a named user with no magic-link
+ * scope, the usual signed-in caller — from the owner check alone, and refuses a non-owner before it looks at
+ * anything else, so neither needs the conversation read. This function and that one encode the same rule on
+ * purpose and live together for that reason: change the rule there, change the read here. The
+ * `AuthorizeLoadedSession` table test in `sessionAccess.test.ts` fails if the two ever disagree.
+ *
+ * @param session - the session, loaded through the caller's own gate
+ * @param contextUser - the authenticated caller; the conversation, when read, is read as this user (RLS applies)
+ * @param provider - the request-scoped provider
+ */
+export async function AuthorizeLoadedSession(
+    session: MJAIAgentSessionEntity,
+    contextUser: UserInfo,
+    provider: IMetadataProvider,
+): Promise<SessionAccessDecision> {
+    const ownsSession = !!contextUser?.ID && !!session.UserID && UUIDsEqual(session.UserID, contextUser.ID);
+    if (!ownsSession || !ResolveSessionScopeIdentity(contextUser)) {
+        return AuthorizeSessionAccess({ SessionUserID: session.UserID, ConversationExternalID: null, ConversationReadable: false }, contextUser);
+    }
+    const conversation = await LoadSessionConversationScope(session, contextUser, provider);
+    return AuthorizeSessionAccess(
+        { SessionUserID: session.UserID, ConversationExternalID: conversation.ExternalID, ConversationReadable: conversation.Readable },
+        contextUser,
+    );
+}
+
+/**
+ * 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) {