@memberjunction/server 6.1.5 → 6.1.6

package/src/__tests__/multiTenancy.postgresRewrite.test.ts

@@ -0,0 +1,181 @@
+/**
+ * The tenant PreRunView hook checks the caller's ExtraFilter and builds
+ * `(<ExtraFilter>) AND (<tenant predicate>)`. On PostgreSQL the provider then rewrites the whole
+ * filter (identifier quoting, T-SQL date functions, boolean literals), and that rewrite can change
+ * the caller's part after the hook checked it. These tests run the real hook, the real PostgreSQL
+ * rewrite and the real view query builder, with only ExecuteSQL recorded, and pin that the tenant
+ * predicate stays a separate AND term whatever the rewrite does to the caller's term. The last
+ * block runs the same path with no hook and pins that the per-term rewrite keeps a SQL Server
+ * bracket name whole.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+    ClearAllDataHooks,
+    Metadata,
+    RegisterDataHook,
+    UserInfo,
+    type EntityInfo,
+    type IMetadataProvider,
+} from '@memberjunction/core';
+import { PostgreSQLDataProvider } from '@memberjunction/postgresql-dataprovider';
+import type { SQLParserDialect } from '@memberjunction/sql-dialect';
+import { IsBalancedSQLFragment, SplitTopLevelAndTerms } from '@memberjunction/sql-parser';
+import { createTenantPreRunViewHook } from '../multiTenancy/index.js';
+import type { MultiTenancyConfig } from '../config.js';
+
+const TENANT_TERM = `(("OrganizationID" = 't1'))`;
+
+/** The real PostgreSQL provider over one entity fixture, with every executed statement recorded. */
+class RecordingPostgreSQLProvider extends PostgreSQLDataProvider {
+    public readonly ExecutedSQL: string[] = [];
+
+    constructor(private readonly testEntities: EntityInfo[]) {
+        super();
+    }
+
+    public override get Entities(): EntityInfo[] {
+        return this.testEntities;
+    }
+
+    public override async ExecuteSQL<T>(sql: string): Promise<T[]> {
+        this.ExecutedSQL.push(sql);
+        return [];
+    }
+}
+
+/** A tenant-scoped entity with a boolean field, which the PostgreSQL rewrite coerces. */
+function customersEntity(): EntityInfo {
+    const field = (name: string, tsType: string) => ({ Name: name, CodeName: name, TSType: tsType, IsVirtual: false });
+    const fields = [field('ID', 'string'), field('Name', 'string'), field('OrganizationID', 'string'), field('IsActive', 'boolean')];
+    return {
+        ID: 'ENT-CUSTOMERS',
+        Name: 'Customers',
+        SchemaName: 'app',
+        BaseView: 'vwCustomers',
+        Fields: fields,
+        PrimaryKeys: [fields[0]],
+        FirstPrimaryKey: fields[0],
+        FieldByName: (n: string) => fields.find((f) => f.Name.toLowerCase() === n.trim().toLowerCase()),
+        DatetimeFields: [],
+        ExternalDataSourceID: null,
+        UserViewMaxRows: 0,
+        EnableFieldLevelSecurity: false,
+        AuditViewRuns: false,
+        GetUserPermisions: () => ({ CanRead: true }),
+        GetEffectiveRowFilterWhereClause: () => '',
+    } as unknown as EntityInfo;
+}
+
+function tenantConfig(): MultiTenancyConfig {
+    return {
+        enabled: true,
+        contextSource: 'header',
+        tenantHeader: 'x-tenant-id',
+        scopingStrategy: 'allowlist',
+        scopedEntities: ['Customers'],
+        autoExcludeCoreEntities: true,
+        defaultTenantColumn: 'OrganizationID',
+        entityColumnMappings: {},
+        adminRoles: ['Admin'],
+        writeProtection: 'strict',
+    };
+}
+
+/** The WHERE clause of the one statement the provider ran. */
+function whereOf(provider: RecordingPostgreSQLProvider): string {
+    expect(provider.ExecutedSQL).toHaveLength(1);
+    const sql = provider.ExecutedSQL[0];
+    return sql.substring(sql.indexOf(' WHERE ') + ' WHERE '.length);
+}
+
+/**
+ * Whether `term` is one of the top-level AND terms inside the one pair of parentheses around
+ * `where`. Only then does it narrow every row the query returns.
+ */
+function isTopLevelAndTerm(where: string, term: string, dialect: SQLParserDialect): boolean {
+    const inner = where.slice(1, -1);
+    const wrapped = where.startsWith('(') && where.endsWith(')') && IsBalancedSQLFragment(inner, dialect).IsBalanced;
+    return wrapped && (SplitTopLevelAndTerms(inner, dialect) ?? []).some((t) => t.trim() === term);
+}
+
+describe('Multi-tenancy on PostgreSQL — the provider rewrite cannot reach the tenant predicate', () => {
+    let provider: RecordingPostgreSQLProvider;
+    let savedProvider: IMetadataProvider;
+    let user: UserInfo;
+
+    beforeEach(() => {
+        provider = new RecordingPostgreSQLProvider([customersEntity()]);
+        savedProvider = Metadata.Provider;
+        Metadata.Provider = provider;
+        ClearAllDataHooks();
+        RegisterDataHook('PreRunView', createTenantPreRunViewHook(tenantConfig()));
+        user = new UserInfo(provider, { ID: 'U1', Email: 'u1@example.com' });
+        user.TenantContext = { TenantID: 't1', Source: 'header' };
+    });
+
+    afterEach(() => {
+        ClearAllDataHooks();
+        Metadata.Provider = savedProvider;
+    });
+
+    it('keeps the tenant predicate a separate AND term when the rewrite changes the caller term', async () => {
+        // The rewrite turns the caller's quoted text into boolean literals and changes where its
+        // parentheses close. Each term is rewritten and wrapped on its own, so that change stays
+        // inside the caller's term.
+        const result = await provider.RunView({ EntityName: 'Customers', ExtraFilter: `"IsActive" = '1) AND ("IsActive" = 1'` }, user);
+
+        expect(result.Success).toBe(true);
+        expect(whereOf(provider)).toBe(`((("IsActive" = TRUE) AND ("IsActive" = TRUE)) AND ${TENANT_TERM})`);
+    });
+
+    it('keeps the tenant predicate its own AND term after a quote the boolean rewrite drops, followed by a top-level OR', async () => {
+        // The rewrite drops the quote, so text the hook read inside a string literal becomes code
+        // with a top-level OR. The tenant predicate must still narrow every row.
+        const result = await provider.RunView({ EntityName: 'Customers', ExtraFilter: `"IsActive" = '1) OR (1=1) OR ("IsActive" = 1'` }, user);
+
+        expect(result.Success).toBe(true);
+        const where = whereOf(provider);
+        expect(isTopLevelAndTerm(where, TENANT_TERM, provider.Dialect), `tenant predicate is not a top-level AND term of ${where}`).toBe(true);
+        expect(where).toBe(`((("IsActive" = TRUE) OR (1=1) OR ("IsActive" = TRUE)) AND ${TENANT_TERM})`);
+    });
+
+    it('refuses a caller term that the rewrite leaves unbalanced, and runs no SQL', async () => {
+        const result = await provider.RunView({ EntityName: 'Customers', ExtraFilter: `"IsActive" = '1) AND (1 = 1'` }, user);
+
+        expect(provider.ExecutedSQL).toEqual([]);
+        expect(result.Success).toBe(false);
+        expect(result.ErrorMessage).toMatch(/ExtraFilter/);
+    });
+
+    it('leaves an ordinary filter and the tenant predicate as written, each in its own term', async () => {
+        const result = await provider.RunView({ EntityName: 'Customers', ExtraFilter: `"IsActive" = 1 OR "Name" = 'a'` }, user);
+
+        expect(result.Success).toBe(true);
+        expect(whereOf(provider)).toBe(`((("IsActive" = TRUE OR "Name" = 'a')) AND ${TENANT_TERM})`);
+    });
+});
+
+describe('PostgreSQL ExtraFilter rewrite with no PreRunView hook', () => {
+    let provider: RecordingPostgreSQLProvider;
+    let savedProvider: IMetadataProvider;
+
+    beforeEach(() => {
+        provider = new RecordingPostgreSQLProvider([customersEntity()]);
+        savedProvider = Metadata.Provider;
+        Metadata.Provider = provider;
+        ClearAllDataHooks();
+    });
+
+    afterEach(() => {
+        Metadata.Provider = savedProvider;
+    });
+
+    it('keeps a SQL Server bracket name that contains AND whole when it rewrites each AND term', async () => {
+        const user = new UserInfo(provider, { ID: 'U1', Email: 'u1@example.com' });
+
+        const result = await provider.RunView({ EntityName: 'Customers', ExtraFilter: '[Profit and Loss] > 0 AND [IsActive] = 1' }, user);
+
+        expect(result.Success).toBe(true);
+        expect(whereOf(provider)).toBe('(("Profit and Loss" > 0) AND ("IsActive" = TRUE))');
+    });
+});

package/src/__tests__/multiTenancy.security.test.ts

@@ -518,6 +518,57 @@ describe('Multi-Tenancy Security Edge Cases', () => {
     });
   });
 
+  // ─── Client ExtraFilter containment ───────────────────────────────────
+
+  describe('client ExtraFilter must stay inside its parentheses', () => {
+    // The hook builds `(<ExtraFilter>) AND (<tenant>)`. A filter that closes a parenthesis it did
+    // not open turns that into `(1=1) OR (1=1) AND (<tenant>)`: AND binds tighter than OR, so the
+    // tenant predicate would narrow only one side of an OR the caller controls.
+    const escapes = [
+      '1=1) OR (1=1',
+      "Name = 'a') OR (Name = 'b'",
+      '1=1)) OR ((1=1',
+    ];
+
+    it.each(escapes)('refuses the ExtraFilter %j instead of ANDing the tenant predicate onto it', (extraFilter) => {
+      const hook = createTenantPreRunViewHook(makeConfig());
+      const params = { EntityName: 'Customers', ExtraFilter: extraFilter } as RunViewParams;
+
+      expect(() => hook(params, makeUser('tenant-abc'))).toThrow(/parenthesis/);
+    });
+
+    it('refuses an ExtraFilter that ends inside an unterminated string literal', () => {
+      const hook = createTenantPreRunViewHook(makeConfig());
+      const params = { EntityName: 'Customers', ExtraFilter: "Name = 'a" } as RunViewParams;
+
+      expect(() => hook(params, makeUser('tenant-abc'))).toThrow(/unterminated/);
+    });
+
+    it('refuses an ExtraFilter that contains a comment', () => {
+      const hook = createTenantPreRunViewHook(makeConfig());
+      const params = { EntityName: 'Customers', ExtraFilter: "Name = 'a' -- note\n" } as RunViewParams;
+
+      expect(() => hook(params, makeUser('tenant-abc'))).toThrow(/comment/);
+    });
+
+    it('applies the PostgreSQL rules too when the provider dialect is unknown', () => {
+      // The mocked Metadata.Provider here is not a database provider, so the hook reads the filter
+      // with every supported dialect.
+      const hook = createTenantPreRunViewHook(makeConfig());
+      const params = { EntityName: 'Customers', ExtraFilter: 'Name = $$x$$' } as RunViewParams;
+
+      expect(() => hook(params, makeUser('tenant-abc'))).toThrow(/dollar/);
+    });
+
+    it('keeps a balanced ExtraFilter and the tenant predicate as separate parenthesized terms', () => {
+      const hook = createTenantPreRunViewHook(makeConfig());
+      const params = { EntityName: 'Customers', ExtraFilter: "Name = 'a) OR (b' OR Name = 'c'" } as RunViewParams;
+
+      const result = hook(params, makeUser('tenant-abc')) as RunViewParams;
+      expect(result.ExtraFilter).toBe("(Name = 'a) OR (b' OR Name = 'c') AND ([OrganizationID] = 'tenant-abc')");
+    });
+  });
+
   // ─── PreSave security edge cases ──────────────────────────────────────
 
   describe('PreSave security', () => {

package/src/__tests__/multiTenancy.test.ts

@@ -87,7 +87,7 @@ describe('Multi-Tenancy Hooks', () => {
 
       const result = hook(params, user);
       expect((result as RunViewParams).ExtraFilter).toBe(
-        "(Status = 'Active') AND [OrganizationID] = 'tenant-abc'"
+        "(Status = 'Active') AND ([OrganizationID] = 'tenant-abc')"
       );
     });
 

package/src/__tests__/newUsers.test.ts

@@ -30,6 +30,8 @@ const {
     mockBeginTransaction,
     mockCommitTransaction,
     mockRollbackTransaction,
+    mockGlobalProviderCalls,
+    mockCreateIsolatedProvider,
     mockGetDefaultApplicationsForNewUser,
     mockRolesArray,
     mockApplicationsArray,
@@ -69,6 +71,10 @@ const {
         mockBeginTransaction: vi.fn(),
         mockCommitTransaction: vi.fn(),
         mockRollbackTransaction: vi.fn(),
+        // Every call new-user creation makes on the SHARED Metadata.Provider. Must stay empty: a
+        // transaction there nests into every concurrent request's (see CreateIsolatedProvider).
+        mockGlobalProviderCalls: [] as string[],
+        mockCreateIsolatedProvider: vi.fn(),
         mockGetDefaultApplicationsForNewUser: vi.fn(),
         mockRolesArray: [] as Array<{ ID: string; Name: string }>,
         mockApplicationsArray: [] as Array<{ ID: string; Name: string }>,
@@ -79,6 +85,9 @@ const {
 
 vi.mock('../config.js', () => ({ configInfo: mockConfig }));
 
+// The provider new-user creation must use: its own instance, so its transaction is its own.
+vi.mock('../isolatedProvider.js', () => ({ CreateIsolatedProvider: mockCreateIsolatedProvider }));
+
 vi.mock('@memberjunction/generic-database-provider', () => {
     const instance = {
         get Users() {
@@ -104,10 +113,11 @@ vi.mock('@memberjunction/generic-database-provider', () => {
 
 vi.mock('@memberjunction/core', async (importOriginal) => {
     const actual = await importOriginal<typeof import('@memberjunction/core')>();
-    const provider = {
-        BeginTransaction: mockBeginTransaction,
-        CommitTransaction: mockCommitTransaction,
-        RollbackTransaction: mockRollbackTransaction,
+    // The shared global provider: records any use instead of doing anything.
+    const globalProvider = {
+        BeginTransaction: async () => { mockGlobalProviderCalls.push('BeginTransaction'); },
+        CommitTransaction: async () => { mockGlobalProviderCalls.push('CommitTransaction'); },
+        RollbackTransaction: async () => { mockGlobalProviderCalls.push('RollbackTransaction'); },
         Dialect: { BooleanLiteral: (value: boolean) => (value ? '1' : '0') },
     };
     class MockMetadata {
@@ -118,9 +128,10 @@ vi.mock('@memberjunction/core', async (importOriginal) => {
             return mockApplicationsArray;
         }
         public GetEntityObject(entityName: string, contextUser?: UserInfo): Promise<unknown> {
+            mockGlobalProviderCalls.push(`GetEntityObject:${entityName}`);
             return mockGetEntityObject(entityName, contextUser);
         }
-        static Provider = provider;
+        static Provider = globalProvider;
     }
     class MockUserInfo {
         constructor(_provider: unknown, initData: Record<string, unknown>) {
@@ -128,6 +139,9 @@ vi.mock('@memberjunction/core', async (importOriginal) => {
         }
     }
     class MockRunView {
+        public static FromMetadataProvider(_provider: unknown): MockRunView {
+            return new MockRunView();
+        }
         public RunView(params: unknown, contextUser?: UserInfo): Promise<unknown> {
             return mockRunViewFn(params, contextUser);
         }
@@ -294,6 +308,21 @@ beforeEach(() => {
     });
     mockRunViewFn.mockResolvedValue({ Success: true, Results: [] });
     mockGetDefaultApplicationsForNewUser.mockReturnValue([]);
+
+    mockGlobalProviderCalls.length = 0;
+    mockCreateIsolatedProvider.mockImplementation(async () => ({
+        BeginTransaction: mockBeginTransaction,
+        CommitTransaction: mockCommitTransaction,
+        RollbackTransaction: mockRollbackTransaction,
+        Dialect: { BooleanLiteral: (value: boolean) => (value ? '1' : '0') },
+        get Roles() {
+            return mockRolesArray;
+        },
+        get Applications() {
+            return mockApplicationsArray;
+        },
+        GetEntityObject: (entityName: string, contextUser?: UserInfo) => mockGetEntityObject(entityName, contextUser),
+    }));
 });
 
 // ─── NewUserBase.createNewUser ──────────────────────────────────────────────
@@ -302,6 +331,34 @@ describe('NewUserBase.createNewUser', () => {
     const create = (first = 'Ada', last = 'Lovelace', email = 'ada@example.com') =>
         new NewUserBase().createNewUser(first, last, email);
 
+    describe('provider isolation', () => {
+        it('runs the whole provisioning on its own provider, never the shared Metadata.Provider', async () => {
+            mockConfig.userHandling.CreateUserApplicationRecords = true;
+            mockConfig.userHandling.UserApplications = ['CRM'];
+            mockRunViewFn.mockResolvedValue({ Success: true, Results: [{ EntityID: 'ent-1', Entity: 'Accounts' }] });
+
+            const user = await create();
+
+            expect(user).toBeTruthy();
+            expect(mockCreateIsolatedProvider).toHaveBeenCalledTimes(1);
+            expect(mockBeginTransaction).toHaveBeenCalledTimes(1);
+            expect(mockCommitTransaction).toHaveBeenCalledTimes(1);
+            // User, role, application and application-entity records all came from the isolated one.
+            expect(getEntityObjectCalls.map((c) => c.entityName)).toEqual([
+                'MJ: Users', 'MJ: User Roles', 'MJ: User Applications', 'MJ: User Application Entities',
+            ]);
+            expect(mockGlobalProviderCalls).toEqual([]);
+        });
+
+        it('rolls back on the isolated provider too, never the shared one', async () => {
+            saveBehavior['MJ: Users'] = () => false;
+
+            expect(await create()).toBeNull();
+            expect(mockRollbackTransaction).toHaveBeenCalledTimes(1);
+            expect(mockGlobalProviderCalls).toEqual([]);
+        });
+    });
+
     describe('context-user resolution', () => {
         it('uses the configured contextUserForNewUserCreation for every entity it creates', async () => {
             const user = await create();

package/src/agentSessions/SessionManager.ts

@@ -9,6 +9,7 @@ import { AIAgentPermissionHelper } from '@memberjunction/ai-engine-base';
 import { RealtimeClientSessionService, RealtimeChannelServerHost } from '@memberjunction/ai-agents';
 import { GetHostInstanceID } from './HostInstance.js';
 import { writeReturningVisitorRecap } from './ReturningVisitorRecap.js';
+import { SessionRunIDVerifier, SessionRunIDs } from './SessionRunIDVerifier.js';
 import { ResolveScopedAnonymousRunUser } from '../realtimeWidget/widgetGuestElevation.js';
 
 /** Entity names — centralised so the `MJ:`-prefix convention is applied in exactly one place. */
@@ -16,18 +17,6 @@ const SESSION_ENTITY = 'MJ: AI Agent Sessions';
 const SESSION_CHANNEL_ENTITY = 'MJ: AI Agent Session Channels';
 const CONVERSATION_ENTITY = 'MJ: Conversations';
 
-/**
- * Shape of the observability run ids a realtime voice session persists in `AIAgentSession.Config_`.
- * Read on {@link SessionManager.CloseSession} to finalize the co-agent runs. All fields optional —
- * a non-voice session (or one whose run creation was skipped) carries none of them.
- */
-interface SessionRunConfig {
-    coAgentRunID?: string;
-    promptRunID?: string;
-    /** The co-agent run's single system-prompt `MJ: AI Agent Run Steps` row id (its Timeline entry). */
-    coAgentRunStepID?: string;
-}
-
 /**
  * Inputs for {@link SessionManager.CreateSession}. `conversationID`/`lastSessionID`/`config`
  * are optional — when no `conversationID` is supplied a fresh Conversation is created and linked.
@@ -126,6 +115,9 @@ export class SessionManager {
      */
     private readonly realtimeClientSessionService: RealtimeClientSessionService;
 
+    /** Checks the run ids read from a session's owner-editable `Config_` before they are used. */
+    private readonly runIDVerifier = new SessionRunIDVerifier();
+
     /**
      * @param realtimeClientSessionService The shared {@link RealtimeClientSessionService} instance to
      *   finalize observability runs through. Pass the SAME instance your resolver/service used to create
@@ -260,7 +252,8 @@ export class SessionManager {
 
     /**
      * Finalizes the co-agent observability runs a realtime voice session stored in its `Config_`
-     * (see `RealtimeClientSessionResolver`). No-op when the config carries no run ids. Tolerant: a
+     * (see `RealtimeClientSessionResolver`). Only run ids that are records of the session are
+     * finalized, because the owner can edit `Config_`. No-op when none remain. Tolerant: a
      * malformed config or a finalize failure is swallowed so it can never break session close.
      */
     private async finalizeObservabilityRuns(
@@ -268,8 +261,8 @@ export class SessionManager {
         contextUser: UserInfo,
         provider: IMetadataProvider,
     ): Promise<void> {
-        const config = this.parseSessionRunConfig(session.Config_);
-        if (!config.coAgentRunID && !config.promptRunID && !config.coAgentRunStepID) {
+        const claimed = this.parseSessionRunConfig(session.Config_);
+        if (!claimed.CoAgentRunID && !claimed.PromptRunID && !claimed.CoAgentRunStepID) {
             return;
         }
         try {
@@ -277,30 +270,35 @@ export class SessionManager {
             // for a scoped anonymous session, so an owner-initiated (or error) close must finalize
             // under it too — the caller's role holds no grants on the AI run entities. Janitor and
             // shutdown sweeps already close as the system user and pass through unchanged.
+            const runUser = ResolveScopedAnonymousRunUser(contextUser);
+            const runIDs = await this.runIDVerifier.Verify(session.ID, claimed, runUser, provider);
+            if (!runIDs.CoAgentRunID && !runIDs.PromptRunID && !runIDs.CoAgentRunStepID) {
+                return;
+            }
             await this.realtimeClientSessionService.FinalizeCoAgentRun(
-                config.coAgentRunID ?? null,
-                config.promptRunID ?? null,
-                ResolveScopedAnonymousRunUser(contextUser),
+                runIDs.CoAgentRunID ?? null,
+                runIDs.PromptRunID ?? null,
+                runUser,
                 provider,
                 true,
-                config.coAgentRunStepID ?? null,
+                runIDs.CoAgentRunStepID ?? null,
             );
         } catch (e) {
             LogError(`SessionManager.finalizeObservabilityRuns failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
 
-    /** Parses the session's `Config_` for observability run ids; returns an empty config on any error. */
-    private parseSessionRunConfig(raw: string | null): SessionRunConfig {
+    /** Parses the session's `Config_` for observability run ids; returns none on any error. */
+    private parseSessionRunConfig(raw: string | null): SessionRunIDs {
         if (!raw) {
             return {};
         }
         try {
-            const parsed = JSON.parse(raw) as Partial<SessionRunConfig>;
+            const parsed = JSON.parse(raw) as { coAgentRunID?: unknown; promptRunID?: unknown; coAgentRunStepID?: unknown };
             return {
-                coAgentRunID: typeof parsed.coAgentRunID === 'string' ? parsed.coAgentRunID : undefined,
-                promptRunID: typeof parsed.promptRunID === 'string' ? parsed.promptRunID : undefined,
-                coAgentRunStepID: typeof parsed.coAgentRunStepID === 'string' ? parsed.coAgentRunStepID : undefined,
+                CoAgentRunID: typeof parsed.coAgentRunID === 'string' ? parsed.coAgentRunID : undefined,
+                PromptRunID: typeof parsed.promptRunID === 'string' ? parsed.promptRunID : undefined,
+                CoAgentRunStepID: typeof parsed.coAgentRunStepID === 'string' ? parsed.coAgentRunStepID : undefined,
             };
         } catch {
             return {};

package/src/agentSessions/SessionRunIDVerifier.ts

@@ -0,0 +1,171 @@
+/**
+ * @fileoverview Checks the run ids a realtime session keeps in its `Config` before server code
+ * acts on them.
+ *
+ * @module @memberjunction/server
+ */
+import { IMetadataProvider, LogError, RunView, RunViewParams, UserInfo } from '@memberjunction/core';
+import { EscapeSQLString, IsValidUUID, UUIDsEqual } from '@memberjunction/global';
+import { UserCache } from '@memberjunction/generic-database-provider';
+
+const AGENT_RUN_ENTITY = 'MJ: AI Agent Runs';
+const AGENT_RUN_STEP_ENTITY = 'MJ: AI Agent Run Steps';
+
+/**
+ * The run ids a realtime voice session keeps in its `Config` JSON. Server code reads and writes the
+ * records they point at, often as an elevated user.
+ */
+export interface SessionRunIDs {
+    /** The co-agent observability run (`MJ: AI Agent Runs`). */
+    CoAgentRunID?: string;
+    /** The co-agent prompt run (`MJ: AI Prompt Runs`), linked through the co-agent run's prompt step. */
+    PromptRunID?: string;
+    /** The co-agent run's system-prompt step (`MJ: AI Agent Run Steps`). */
+    CoAgentRunStepID?: string;
+    /** A delegated run (`MJ: AI Agent Runs`) that paused for the user's answer. */
+    PendingFeedbackRunID?: string;
+}
+
+/** A row of the run-step lookup. */
+interface RunStepRow {
+    ID: string;
+    StepType: string;
+    TargetLogID: string | null;
+}
+
+/** A row of either lookup; the run lookup returns only `ID`. */
+type LookupRow = Partial<RunStepRow> & { ID: string };
+
+/**
+ * Keeps the run ids from a session's `Config` that are records of that session.
+ *
+ * The session owner can edit `Config`, so its run ids are claims. A run id is kept when it is the
+ * UUID of an `MJ: AI Agent Runs` row whose `AgentSessionID` is the session. The step id and the
+ * prompt run id are kept when they belong to that co-agent run: the step's `AgentRunID` is the
+ * co-agent run, and the prompt run is the `TargetLogID` of one of its `Prompt` steps.
+ *
+ * The lookups run as the system user when one is cached, else as the acting user. They are pinned
+ * to the session's id and return nothing to the caller, and row-level security can hide a session's
+ * own runs from its owner (a web-widget guest's delegated runs carry no `ConversationID`, which the
+ * guest's run filter keys on).
+ *
+ * Each call reads the database again (`BypassCache`) and keeps no result, because the links can
+ * change after a lookup: a run's `AgentSessionID` and a step's `AgentRunID` and `TargetLogID` are
+ * updatable.
+ */
+export class SessionRunIDVerifier {
+    /**
+     * Returns the subset of `claimed` that belongs to the session now. Never throws: when a lookup
+     * fails, nothing is kept.
+     *
+     * @param sessionID The `MJ: AI Agent Sessions` id the claims were read from. The caller must have
+     *   checked that the session is the caller's own.
+     * @param claimed The run ids read from the session's `Config`.
+     * @param contextUser The acting user; the lookups run as it only when no system user is cached.
+     * @param provider The request-scoped metadata provider.
+     * @returns The claims that are records of the session.
+     */
+    public async Verify(
+        sessionID: string,
+        claimed: SessionRunIDs,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<SessionRunIDs> {
+        const candidates = this.keepUUIDs(claimed);
+        if (!candidates.CoAgentRunID && !candidates.PendingFeedbackRunID) {
+            return {};
+        }
+        return (await this.lookUpOwned(sessionID.trim(), candidates, contextUser, provider)) ?? {};
+    }
+
+    /** Drops every claim that is not a UUID. The prompt run and step need a co-agent run to hang off. */
+    private keepUUIDs(claimed: SessionRunIDs): SessionRunIDs {
+        const coAgentRunID = this.uuidOrUndefined(claimed.CoAgentRunID);
+        return {
+            CoAgentRunID: coAgentRunID,
+            PromptRunID: coAgentRunID ? this.uuidOrUndefined(claimed.PromptRunID) : undefined,
+            CoAgentRunStepID: coAgentRunID ? this.uuidOrUndefined(claimed.CoAgentRunStepID) : undefined,
+            PendingFeedbackRunID: this.uuidOrUndefined(claimed.PendingFeedbackRunID),
+        };
+    }
+
+    private uuidOrUndefined(value: string | undefined): string | undefined {
+        return value && IsValidUUID(value) ? value.trim() : undefined;
+    }
+
+    /** Runs the lookups; `null` when one of them fails. */
+    private async lookUpOwned(
+        sessionID: string,
+        candidates: SessionRunIDs,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<SessionRunIDs | null> {
+        const stepsQuery = this.stepsQuery(candidates);
+        const queries = stepsQuery ? [this.runsQuery(sessionID, candidates), stepsQuery] : [this.runsQuery(sessionID, candidates)];
+        try {
+            const lookupUser = UserCache.Instance.GetSystemUser() ?? contextUser;
+            const [runs, steps] = await RunView.FromMetadataProvider(provider).RunViews<LookupRow>(queries, lookupUser);
+            const failed = [runs, steps].find((result) => result && !result.Success);
+            if (!runs || failed) {
+                LogError(`SessionRunIDVerifier: run lookup failed for session ${sessionID}: ${failed?.ErrorMessage ?? 'no result'}`);
+                return null;
+            }
+            return this.pickOwned(candidates, runs.Results, steps?.Results ?? []);
+        } catch (error) {
+            LogError(`SessionRunIDVerifier: run lookup failed for session ${sessionID}: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+
+    /** The claimed runs that carry this session's id. */
+    private runsQuery(sessionID: string, candidates: SessionRunIDs): RunViewParams {
+        const ids = [candidates.CoAgentRunID, candidates.PendingFeedbackRunID]
+            .filter((id): id is string => !!id)
+            .map((id) => `'${EscapeSQLString(id)}'`);
+        return {
+            EntityName: AGENT_RUN_ENTITY,
+            ExtraFilter: `AgentSessionID='${EscapeSQLString(sessionID)}' AND ID IN (${ids.join(', ')})`,
+            Fields: ['ID'],
+            ResultType: 'simple',
+            BypassCache: true,
+        };
+    }
+
+    /** The claimed co-agent run's steps that match the claimed step or prompt run; `null` when neither is claimed. */
+    private stepsQuery(candidates: SessionRunIDs): RunViewParams | null {
+        const matches: string[] = [];
+        if (candidates.CoAgentRunStepID) {
+            matches.push(`ID='${EscapeSQLString(candidates.CoAgentRunStepID)}'`);
+        }
+        if (candidates.PromptRunID) {
+            matches.push(`TargetLogID='${EscapeSQLString(candidates.PromptRunID)}'`);
+        }
+        if (!candidates.CoAgentRunID || matches.length === 0) {
+            return null;
+        }
+        return {
+            EntityName: AGENT_RUN_STEP_ENTITY,
+            ExtraFilter: `AgentRunID='${EscapeSQLString(candidates.CoAgentRunID)}' AND (${matches.join(' OR ')})`,
+            Fields: ['ID', 'StepType', 'TargetLogID'],
+            ResultType: 'simple',
+            BypassCache: true,
+        };
+    }
+
+    private pickOwned(candidates: SessionRunIDs, runs: LookupRow[], steps: LookupRow[]): SessionRunIDs {
+        const isOwnedRun = (id: string | undefined): boolean => !!id && runs.some((row) => UUIDsEqual(row.ID, id));
+        const coAgentRunID = isOwnedRun(candidates.CoAgentRunID) ? candidates.CoAgentRunID : undefined;
+        const ownedSteps = coAgentRunID ? steps : [];
+        const stepID = candidates.CoAgentRunStepID;
+        const promptRunID = candidates.PromptRunID;
+        return {
+            CoAgentRunID: coAgentRunID,
+            CoAgentRunStepID: stepID && ownedSteps.some((row) => UUIDsEqual(row.ID, stepID)) ? stepID : undefined,
+            PromptRunID:
+                promptRunID && ownedSteps.some((row) => row.StepType === 'Prompt' && UUIDsEqual(row.TargetLogID, promptRunID))
+                    ? promptRunID
+                    : undefined,
+            PendingFeedbackRunID: isOwnedRun(candidates.PendingFeedbackRunID) ? candidates.PendingFeedbackRunID : undefined,
+        };
+    }
+}

package/src/agentSessions/index.ts

@@ -32,3 +32,4 @@ export * from './remoteBrowserGoalEngine.js';
 export * from './HostInstance.js';
 export * from './SessionManager.js';
 export * from './SessionJanitor.js';
+export * from './SessionRunIDVerifier.js';