@memberjunction/server 5.51.3 → 5.51.4

package/src/index.ts

@@ -30,8 +30,10 @@ import { WebSocketServer } from 'ws';
 import { RealtimeProxyServer } from './realtimeProxy/RealtimeProxyServer.js';
 import buildApolloServer from './apolloServer/index.js';
 import { configInfo, configFilePath, dbDatabase, dbHost, dbPort, dbUsername, graphqlPort, graphqlRootPath, mj_core_schema, websiteRunFromPackage, RESTApiOptions } from './config.js';
+import { TranslateBracketsToPG } from './postgresqlCompat.js';
+import { BuildPostgreSQLConnectionConfig, DescribeReadOnlyLoginOverreach, PostgreSQLReadOnlyPool, ResolvePostgreSQLEndpoint, ResolvePostgreSQLReadOnlyCredentials, ToPGPoolConfig } from './postgresqlPoolSettings.js';
 import { default as jwt } from 'jsonwebtoken';
-import { contextFunction, createUnifiedAuthMiddleware, getUserPayload } from './context.js';
+import { contextFunction, CreateReadOnlyProvider, createUnifiedAuthMiddleware, getUserPayload } from './context.js';
 import { UserPayload } from './types.js';
 import { requireSystemUserDirective, publicDirective } from './directives/index.js';
 import { variablesLoggingMiddleware } from './logging/variablesLoggingMiddleware.js';
@@ -59,6 +61,8 @@ import { ScheduledJobsService } from './services/ScheduledJobsService.js';
 import { LocalCacheManager, StartupManager, TelemetryManager, TelemetryLevel, LogStatus, SetVerboseLogging } from '@memberjunction/core';
 import { getSystemUser } from './auth/index.js';
 import { GetAPIKeyEngine } from '@memberjunction/api-keys';
+import { ActionEngineServer } from '@memberjunction/actions';
+import { CreateAdhocSQLAuthorizer } from './resolvers/AdhocQueryResolver.js';
 import { RedisLocalStorageProvider } from '@memberjunction/redis-provider';
 import { GenericDatabaseProvider } from '@memberjunction/generic-database-provider';
 import { PubSubManager } from './generic/PubSubManager.js';
@@ -66,7 +70,7 @@ import { IntegrationProgressEmitter } from '@memberjunction/integration-progress
 import { PublishIntegrationProgress } from './resolvers/IntegrationProgressResolver.js';
 import { ClientToolRequestManager, AgentRunWatchdog } from '@memberjunction/ai-agents';
 import { SessionJanitor } from './agentSessions/index.js';
-import { CACHE_INVALIDATION_TOPIC } from './generic/CacheInvalidationResolver.js';
+import { CACHE_INVALIDATION_TOPIC, MayBroadcastRecordData, ConfigureRecordDataBroadcast } from './generic/CacheInvalidationResolver.js';
 import { ConnectorFactory, IntegrationEngine, IntegrationSyncOptions } from '@memberjunction/integration-engine';
 import { CronExpressionHelper } from '@memberjunction/scheduling-engine';
 import {
@@ -265,25 +269,13 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     startupLog.BeginPhase('Connecting to database');
     startupLog.LogIf('verbose', 'Database type: PostgreSQL');
     const pg = await import('pg');
-    const { PostgreSQLDataProvider, PostgreSQLProviderConfigData } = await import('@memberjunction/postgresql-dataprovider');
+    const { PostgreSQLDataProvider, PostgreSQLProviderConfigData, MJPostgresTypes } = await import('@memberjunction/postgresql-dataprovider');
 
-    const pgHost = process.env.PG_HOST || process.env.DB_HOST || 'localhost';
-    const pgPort = parseInt(process.env.PG_PORT || process.env.DB_PORT || '5432', 10);
-    const pgUser = process.env.PG_USERNAME || process.env.DB_USERNAME || 'postgres';
-    const pgPass = process.env.PG_PASSWORD || process.env.DB_PASSWORD || '';
-    const pgDatabase = process.env.PG_DATABASE || process.env.DB_DATABASE || '';
-
-    const pgPool = new pg.default.Pool({
-      host: pgHost,
-      port: pgPort,
-      user: pgUser,
-      password: pgPass,
-      database: pgDatabase,
-      max: configInfo.databaseSettings.connectionPool?.max ?? 50,
-      min: configInfo.databaseSettings.connectionPool?.min ?? 5,
-      idleTimeoutMillis: configInfo.databaseSettings.connectionPool?.idleTimeoutMillis ?? 30000,
-      connectionTimeoutMillis: configInfo.databaseSettings.connectionPool?.acquireTimeoutMillis ?? 30000,
-    });
+    const pgEndpoint = ResolvePostgreSQLEndpoint();
+    const { Host: pgHost, Port: pgPort, User: pgUser, Database: pgDatabase } = pgEndpoint;
+    // Every API pool carries the statement and idle-in-transaction timeouts from connection #1.
+    const pgConnectionConfig = BuildPostgreSQLConnectionConfig(pgEndpoint, configInfo.databaseSettings, 'api');
+    const pgPool = new pg.default.Pool(ToPGPoolConfig(pgConnectionConfig));
 
     // Verify connection
     const testClient = await pgPool.connect();
@@ -291,6 +283,28 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     testClient.release();
     startupLog.LogIf('verbose', `PostgreSQL pool connected to ${pgHost}:${pgPort}/${pgDatabase}`);
 
+    // A read-only pool opened with the read-only login, as SQL Server has. Read-only per-request
+    // providers (TestQuerySQL and other caller-supplied SQL) share it instead of the primary pool.
+    const pgReadOnlyCredentials = ResolvePostgreSQLReadOnlyCredentials(configInfo);
+    if (pgReadOnlyCredentials) {
+      // A pool a provider runs on must carry the provider's type parsers, so BIGINT and NUMERIC
+      // come back as numbers here as they do on the provider's own pool.
+      const readOnlyPgPool = new pg.default.Pool({
+        ...ToPGPoolConfig(BuildPostgreSQLConnectionConfig({ ...pgEndpoint, ...pgReadOnlyCredentials }, configInfo.databaseSettings, 'read-only')),
+        types: MJPostgresTypes,
+      });
+      const readOnlyTestClient = await readOnlyPgPool.connect();
+      try {
+        for (const warning of await DescribeReadOnlyLoginOverreach(readOnlyTestClient, mj_core_schema)) {
+          LogStatus(`WARNING: ${warning}`);
+        }
+      } finally {
+        readOnlyTestClient.release();
+      }
+      PostgreSQLReadOnlyPool.Instance.Pool = readOnlyPgPool;
+      startupLog.LogIf('verbose', 'Read-only PostgreSQL pool has been initialized.');
+    }
+
     // Create a DataSourceInfo with a MSSQL-compatible wrapper around pg.Pool
     // This allows existing code (types, util, context) to work without changes
     const mssqlCompatPool = createMSSQLCompatPool(pgPool);
@@ -304,15 +318,6 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     }));
 
     // Set up the PostgreSQL provider
-    const pgConnectionConfig = {
-      Host: pgHost,
-      Port: pgPort,
-      Database: pgDatabase,
-      User: pgUser,
-      Password: pgPass,
-      MaxConnections: configInfo.databaseSettings.connectionPool?.max ?? 50,
-      MinConnections: configInfo.databaseSettings.connectionPool?.min ?? 5,
-    };
     const pgConfigData = new PostgreSQLProviderConfigData(
       pgConnectionConfig,
       mj_core_schema,
@@ -342,7 +347,7 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
       if (poolAny._pgPool) {
         const thePgPool = poolAny._pgPool as import('pg').Pool;
         // Translate SQL Server bracket syntax to PostgreSQL double-quote syntax
-        const pgQuery = translateBracketsToPG(query);
+        const pgQuery = TranslateBracketsToPG(query);
         const result = await thePgPool.query(pgQuery);
         return result.rows;
       }
@@ -361,21 +366,21 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     const pgCodegenPass = process.env.CODEGEN_DB_PASSWORD;
     if (pgCodegenUser && pgCodegenPass) {
       try {
-        const codegenPgPool = new pg.default.Pool({
-          host: pgHost,
-          port: pgPort,
-          user: pgCodegenUser,
-          password: pgCodegenPass,
-          database: pgDatabase,
-          max: 10,
-        });
+        // CodeGen and DDL work runs long statements across every entity, so this pool gets the
+        // long CodeGen timeout rather than the API one, as the SQL Server CodeGen pool does.
+        const codegenPgConnectionConfig = BuildPostgreSQLConnectionConfig(
+          { ...pgEndpoint, User: pgCodegenUser, Password: pgCodegenPass },
+          configInfo.databaseSettings,
+          'codegen',
+        );
+        const codegenPgPool = new pg.default.Pool(ToPGPoolConfig(codegenPgConnectionConfig));
         const codegenTestClient = await codegenPgPool.connect();
         await codegenTestClient.query('SELECT 1');
         codegenTestClient.release();
 
         const { RuntimeSchemaManager } = await import('@memberjunction/schema-engine');
         const codegenPgConfigData = new PostgreSQLProviderConfigData(
-          { Host: pgHost, Port: pgPort, Database: pgDatabase, User: pgCodegenUser, Password: pgCodegenPass },
+          codegenPgConnectionConfig,
           mj_core_schema,
           cacheRefreshInterval / 1000, // ms → seconds
         );
@@ -673,6 +678,11 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
   // This must happen before any request handler calls GetAPIKeyEngine()
   GetAPIKeyEngine();
 
+  // Actions that run caller-supplied SQL (Run Ad-hoc Query) run only on the read-only login, with
+  // ExecuteAdhocQuery's table check and timeout limit.
+  ActionEngineServer.Instance.SetReadOnlyProviderFactory(() => CreateReadOnlyProvider(dataSources));
+  ActionEngineServer.Instance.SetAdhocSQLAuthorizer(CreateAdhocSQLAuthorizer(configInfo.databaseSettings.requestTimeout));
+
   setupComplete$.next(true);
   raiseEvent('setupComplete', dataSources, null,  this);
 
@@ -827,6 +837,11 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     })
   );
 
+  // Hand the resolver its allowlist before anything can publish. It cannot read configInfo itself:
+  // config.ts loads and validates at module scope, so importing it there would pull full config
+  // validation into every import chain that touches the resolver, unit tests included.
+  ConfigureRecordDataBroadcast(configInfo.cacheSettings?.recordDataBroadcastEntities);
+
   // Global listener: broadcast CACHE_INVALIDATION to all browser clients whenever
   // ANY BaseEntity save/delete occurs on this server — regardless of whether it
   // originated from a GraphQL mutation or internal server-side code (agents, actions,
@@ -836,14 +851,21 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     if (event.event === MJEventType.ComponentEvent && event.eventCode === BaseEntity.BaseEventCode) {
       const beEvent = event.args as BaseEntityEvent;
       if (beEvent.type === 'save' || beEvent.type === 'delete') {
+        const entityName = beEvent.baseEntity.EntityInfo.Name;
         PubSubManager.Instance.Publish(CACHE_INVALIDATION_TOPIC, {
-          entityName: beEvent.baseEntity.EntityInfo.Name,
+          entityName,
           primaryKeyValues: JSON.stringify(beEvent.baseEntity.PrimaryKey.KeyValuePairs),
           action: beEvent.type,
           sourceServerId: MJGlobal.Instance.ProcessUUID,
           timestamp: new Date(),
           originSessionId: null,
-          recordData: beEvent.type === 'save' ? JSON.stringify(beEvent.baseEntity.GetAll()) : undefined,
+          // Opt-in only: this event reaches every connected client unfiltered, and this listener
+          // fires for server-internal saves too (agents, actions, orchestrator), which are exactly
+          // the ones no browser session asked for.
+          recordData:
+            beEvent.type === 'save' && MayBroadcastRecordData(entityName)
+              ? JSON.stringify(beEvent.baseEntity.GetAll())
+              : undefined,
         });
       }
     }
@@ -1754,12 +1776,3 @@ async function refreshUserCacheFromPG(pgPool: import('pg').Pool, coreSchema: str
     (cache as unknown as Record<string, unknown>)['_users'] = userInfos;
   }
 }
-
-/**
- * Translates SQL Server bracket-quoted identifiers to PostgreSQL double-quoted identifiers.
- * Converts [schema].[table] to "schema"."table" and handles common T-SQL patterns.
- */
-function translateBracketsToPG(sql: string): string {
-  // Replace [identifier] with "identifier"
-  return sql.replace(/\[([^\]]+)\]/g, '"$1"');
-}

package/src/multiTenancy/index.ts

@@ -9,7 +9,9 @@
 
 import type { RequestHandler } from 'express';
 import type { PreRunViewHook, PreSaveHook } from '@memberjunction/core';
-import { Metadata, type UserInfo, type TenantContext } from '@memberjunction/core';
+import { DatabaseProviderBase, Metadata, type UserInfo, type TenantContext } from '@memberjunction/core';
+import { PostgreSQLDialect, SQLServerDialect, type SQLParserDialect } from '@memberjunction/sql-dialect';
+import { IsBalancedSQLFragment } from '@memberjunction/sql-parser';
 import type { MultiTenancyConfig } from '../config.js';
 import type { UserPayload } from '../types.js';
 
@@ -99,6 +101,25 @@ function isAdminUser(user: UserInfo, adminRoles: string[]): boolean {
   );
 }
 
+/** Dialects to read an ExtraFilter with when the active provider's dialect cannot be resolved. */
+const ALL_FILTER_DIALECTS: SQLParserDialect[] = [new SQLServerDialect(), new PostgreSQLDialect()];
+
+/**
+ * Throws unless the caller's ExtraFilter stays inside the parentheses the tenant predicate is
+ * ANDed after. A filter such as `1=1) OR (1=1` would close them early and leave the tenant
+ * predicate on one side of an OR the caller controls.
+ */
+function assertExtraFilterBalanced(extraFilter: string): void {
+  const provider = Metadata.Provider; // global-provider-ok: same rationale as isEntityScoped above — hooks carry no per-request provider
+  const dialects = provider instanceof DatabaseProviderBase ? [provider.Dialect] : ALL_FILTER_DIALECTS;
+  for (const dialect of dialects) {
+    const check = IsBalancedSQLFragment(extraFilter, dialect);
+    if (!check.IsBalanced) {
+      throw new Error(`[MultiTenancy] Invalid ExtraFilter: ${check.Reason}`);
+    }
+  }
+}
+
 /**
  * Creates a PreRunViewHook that auto-injects tenant WHERE clauses
  * into RunView queries for scoped entities.
@@ -124,7 +145,8 @@ export function createTenantPreRunViewHook(config: MultiTenancyConfig): PreRunVi
 
     // Inject the tenant filter
     if (params.ExtraFilter && typeof params.ExtraFilter === 'string' && params.ExtraFilter.trim().length > 0) {
-      params.ExtraFilter = `(${params.ExtraFilter}) AND ${tenantFilter}`;
+      assertExtraFilterBalanced(params.ExtraFilter);
+      params.ExtraFilter = `(${params.ExtraFilter}) AND (${tenantFilter})`;
     } else {
       params.ExtraFilter = tenantFilter;
     }

package/src/postgresqlCompat.ts

@@ -0,0 +1,21 @@
+import { LexSQL } from '@memberjunction/sql-parser';
+import { SQLServerDialect } from '@memberjunction/sql-dialect';
+
+const sqlServer = new SQLServerDialect();
+
+/**
+ * Translates SQL Server bracket-quoted identifiers (`[Name]`) to PostgreSQL double-quoted ones
+ * (`"Name"`), for SQL written in SQL Server syntax that runs on PostgreSQL. Only identifiers
+ * change: brackets inside string literals and comments are left as written. A `]]` in a name
+ * becomes `]`, and a `"` in a name is doubled.
+ */
+export function TranslateBracketsToPG(sql: string): string {
+    return LexSQL(sql, sqlServer)
+        .map(t => t.Kind === 'identifier' && t.Text.startsWith('[') ? toDoubleQuoted(t.Text) : t.Text)
+        .join('');
+}
+
+function toDoubleQuoted(bracketed: string): string {
+    const name = bracketed.slice(1, bracketed.endsWith(']') ? -1 : undefined).replace(/]]/g, ']');
+    return `"${name.replace(/"/g, '""')}"`;
+}

package/src/postgresqlPoolSettings.ts

@@ -0,0 +1,213 @@
+/**
+ * Connection settings for MJAPI's PostgreSQL pools, derived from the same `databaseSettings`
+ * values SQL Server reads, with the same defaults.
+ *
+ * | Setting                              | SQL Server                       | PostgreSQL                                   |
+ * |--------------------------------------|----------------------------------|----------------------------------------------|
+ * | `requestTimeout`                     | driver request timeout           | `statement_timeout` on every backend         |
+ * | `connectionPool.max` / `min`         | pool size                        | pool size                                    |
+ * | `connectionPool.idleTimeoutMillis`   | idle connection eviction         | idle connection eviction                     |
+ * | `connectionPool.acquireTimeoutMillis`| wait for a pooled connection     | `connectionTimeoutMillis` (see below)        |
+ * | `connectionTimeout`                  | time to open a connection        | not used                                     |
+ *
+ * Where the two cannot match exactly:
+ * - The `pg` pool has one timeout covering both waiting for a free slot and opening a connection.
+ *   It is fed from `acquireTimeoutMillis`; `connectionTimeout` is not used on PostgreSQL.
+ * - SQL Server's `requestTimeout` is a client-side timer over the whole request, including reading
+ *   rows. PostgreSQL's `statement_timeout` is server-side execution time per statement, so a query
+ *   that executes quickly and returns its rows slowly is not cut off on PostgreSQL.
+ * - `idle_in_transaction_session_timeout` has no SQL Server counterpart. It is derived as twice the
+ *   statement timeout, so a transaction left open by an abandoned request is ended and its locks
+ *   released.
+ * - MJAPI opens a raw compatibility pool and a provider pool, each up to `connectionPool.max`, plus
+ *   a CodeGen pool of 10 and, when a read-only login is configured, a read-only pool of at most 10,
+ *   where SQL Server opens one pool (and a read-only one). PostgreSQL's default `max_connections`
+ *   is 100, so the read-only and CodeGen pools are kept small.
+ */
+import type { PGConnectionConfig } from '@memberjunction/postgresql-dataprovider';
+import type { Pool, PoolConfig } from 'pg';
+import { BaseSingleton } from '@memberjunction/global';
+import type { DatabaseSettingsInfo } from './config.js';
+
+/** Statement timeout for the CodeGen/DDL pool, matching the SQL Server CodeGen pool. */
+export const CODEGEN_STATEMENT_TIMEOUT_MS = 600000;
+
+/** Pool size for the CodeGen/DDL pool. */
+const CODEGEN_MAX_CONNECTIONS = 10;
+
+/** Largest pool size for the read-only pool, which serves only caller-supplied SQL. */
+const READ_ONLY_MAX_CONNECTIONS = 10;
+
+/**
+ * Which pool the settings are for: API traffic, the read-only pool for caller-supplied SQL, or
+ * CodeGen and DDL work.
+ */
+export type PostgreSQLPoolPurpose = 'api' | 'read-only' | 'codegen';
+
+/** Where a PostgreSQL pool connects and as whom. */
+export interface PostgreSQLEndpoint {
+    Host: string;
+    Port: number;
+    Database: string;
+    User: string;
+    Password: string;
+}
+
+/** Reads the PostgreSQL endpoint from `PG_*` environment variables, then `DB_*` ones. */
+export function ResolvePostgreSQLEndpoint(env: NodeJS.ProcessEnv = process.env): PostgreSQLEndpoint {
+    return {
+        Host: env.PG_HOST || env.DB_HOST || 'localhost',
+        Port: parseInt(env.PG_PORT || env.DB_PORT || '5432', 10),
+        Database: env.PG_DATABASE || env.DB_DATABASE || '',
+        User: env.PG_USERNAME || env.DB_USERNAME || 'postgres',
+        Password: env.PG_PASSWORD || env.DB_PASSWORD || ''
+    };
+}
+
+/** The idle-in-transaction limit for a given statement timeout; 0 means none. */
+export function IdleInTransactionTimeoutFor(statementTimeoutMs: number): number {
+    return statementTimeoutMs > 0 ? statementTimeoutMs * 2 : 0;
+}
+
+/** Builds the provider connection config for one of MJAPI's PostgreSQL pools. */
+export function BuildPostgreSQLConnectionConfig(
+    endpoint: PostgreSQLEndpoint,
+    settings: DatabaseSettingsInfo,
+    purpose: PostgreSQLPoolPurpose
+): PGConnectionConfig {
+    const pool = settings.connectionPool;
+    if (purpose === 'codegen') {
+        return {
+            ...endpoint,
+            MaxConnections: CODEGEN_MAX_CONNECTIONS,
+            StatementTimeoutMs: CODEGEN_STATEMENT_TIMEOUT_MS,
+            IdleInTransactionSessionTimeoutMs: 0
+        };
+    }
+    const statementTimeoutMs = Math.max(0, settings.requestTimeout);
+    const apiMax = pool?.max ?? 50;
+    const apiMin = pool?.min ?? 5;
+    const readOnly = purpose === 'read-only';
+    return {
+        ...endpoint,
+        MaxConnections: readOnly ? Math.min(READ_ONLY_MAX_CONNECTIONS, apiMax) : apiMax,
+        MinConnections: readOnly ? 0 : apiMin,
+        IdleTimeoutMillis: pool?.idleTimeoutMillis ?? 30000,
+        ConnectionTimeoutMillis: pool?.acquireTimeoutMillis ?? 30000,
+        StatementTimeoutMs: statementTimeoutMs,
+        IdleInTransactionSessionTimeoutMs: IdleInTransactionTimeoutFor(statementTimeoutMs)
+    };
+}
+
+/**
+ * Maps a provider connection config onto `pg.Pool` options, for the pools MJAPI creates directly
+ * rather than through the provider. Timeouts that are unset or 0 are left out.
+ */
+export function ToPGPoolConfig(config: PGConnectionConfig): PoolConfig {
+    const pool: PoolConfig = {
+        host: config.Host,
+        port: config.Port,
+        database: config.Database,
+        user: config.User,
+        password: config.Password,
+        max: config.MaxConnections
+    };
+    if (config.MinConnections !== undefined) pool.min = config.MinConnections;
+    if (config.IdleTimeoutMillis !== undefined) pool.idleTimeoutMillis = config.IdleTimeoutMillis;
+    if (config.ConnectionTimeoutMillis !== undefined) pool.connectionTimeoutMillis = config.ConnectionTimeoutMillis;
+    if (config.StatementTimeoutMs) pool.statement_timeout = config.StatementTimeoutMs;
+    if (config.IdleInTransactionSessionTimeoutMs) pool.idle_in_transaction_session_timeout = config.IdleInTransactionSessionTimeoutMs;
+    return pool;
+}
+
+/** Credentials for a read-only database login. */
+export interface ReadOnlyCredentials {
+    User: string;
+    Password: string;
+}
+
+/**
+ * The read-only login for PostgreSQL: the `dbReadOnlyUsername` / `dbReadOnlyPassword` settings
+ * SQL Server uses (which default from `DB_READ_ONLY_USERNAME` / `DB_READ_ONLY_PASSWORD`), then
+ * `PG_READ_ONLY_USERNAME` / `PG_READ_ONLY_PASSWORD`. `null` when neither pair is complete.
+ */
+export function ResolvePostgreSQLReadOnlyCredentials(
+    configured: { dbReadOnlyUsername?: string; dbReadOnlyPassword?: string },
+    env: NodeJS.ProcessEnv = process.env
+): ReadOnlyCredentials | null {
+    if (configured.dbReadOnlyUsername && configured.dbReadOnlyPassword) {
+        return { User: configured.dbReadOnlyUsername, Password: configured.dbReadOnlyPassword };
+    }
+    if (env.PG_READ_ONLY_USERNAME && env.PG_READ_ONLY_PASSWORD) {
+        return { User: env.PG_READ_ONLY_USERNAME, Password: env.PG_READ_ONLY_PASSWORD };
+    }
+    return null;
+}
+
+/**
+ * Holds MJAPI's PostgreSQL read-only pool, opened once at startup with the read-only login.
+ * Per-request read-only providers share it, so they connect as the read-only user rather than
+ * through the read-write pool.
+ */
+export class PostgreSQLReadOnlyPool extends BaseSingleton<PostgreSQLReadOnlyPool> {
+    private _pool: Pool | null = null;
+
+    /** Use {@link PostgreSQLReadOnlyPool.Instance}. */
+    public constructor() {
+        super();
+    }
+
+    public static get Instance(): PostgreSQLReadOnlyPool {
+        return PostgreSQLReadOnlyPool.getInstance<PostgreSQLReadOnlyPool>();
+    }
+
+    /** The read-only pool, or `null` when no read-only login is configured. */
+    public get Pool(): Pool | null {
+        return this._pool;
+    }
+
+    public set Pool(pool: Pool | null) {
+        this._pool = pool;
+    }
+}
+
+/** What {@link DescribeReadOnlyLoginOverreach} reads about the read-only login. */
+export interface ReadOnlyLoginGrants {
+    ReadsServerFiles: boolean;
+    ReadableBaseTables: number;
+}
+
+/** The one method {@link DescribeReadOnlyLoginOverreach} needs from a connection; a `pg` client has it. */
+export interface ReadOnlyLoginCheckClient {
+    query(sql: string, params: unknown[]): Promise<{ rows: ReadOnlyLoginGrants[] }>;  // case-violation-ok-legacy-back-compat: mirrors the pg client's query method, which a pg client must satisfy as-is
+}
+
+/**
+ * What the PostgreSQL read-only login can do beyond reading entity base views, as warnings to log at
+ * startup. Ad-hoc SQL and `TestQuerySQL` run as this login, and SQL can reach data through functions
+ * that no check of its table references sees (`query_to_xml`, file readers), so the login's own
+ * grants are the only complete limit. It should hold `SELECT` on the entity base views and nothing
+ * else: not on the base tables, and not membership of `pg_read_server_files`. Empty when the login
+ * is that narrow.
+ *
+ * @param client - A connection opened as the read-only login.
+ * @param coreSchema - The MJ core schema, whose base tables the login should not read.
+ */
+export async function DescribeReadOnlyLoginOverreach(client: ReadOnlyLoginCheckClient, coreSchema: string): Promise<string[]> {
+    const result = await client.query(
+        `SELECT pg_has_role(current_user, 'pg_read_server_files', 'MEMBER') AS "ReadsServerFiles",
+                (SELECT count(*)::int FROM pg_catalog.pg_tables t
+                  WHERE t.schemaname = $1
+                    AND has_table_privilege(current_user, quote_ident(t.schemaname) || '.' || quote_ident(t.tablename), 'SELECT')) AS "ReadableBaseTables"`,
+        [coreSchema],
+    );
+    const row = result.rows[0];
+    const warnings: string[] = [];
+    if (row?.ReadableBaseTables > 0) {
+        warnings.push(`The PostgreSQL read-only login can read ${row.ReadableBaseTables} base table(s) in schema "${coreSchema}". Ad-hoc SQL and TestQuerySQL run as this login; grant it SELECT on the entity base views only.`);
+    }
+    if (row?.ReadsServerFiles) {
+        warnings.push('The PostgreSQL read-only login is a member of pg_read_server_files, so SQL run as it can read files on the database server. Revoke that membership.');
+    }
+    return warnings;
+}

package/src/realtimeWidget/widgetGuestElevation.ts

@@ -85,8 +85,8 @@ export async function resolveWidgetGuestRunContext(
  * A scoped anonymous session (`IsMagicLinkAnonymous` + `MagicLinkScope.ResourceID`) holds only the
  * narrow relay grants its invite's role carries — deliberately NOT the AI run entities, whose rows
  * leak the rendered system prompt. Unlike {@link resolveWidgetGuestRunContext} no widget instance is
- * required: on the realtime path the agent authority is already server-side (the session config's
- * `targetAgentID`, `CanRun`-gated at session start), so there is no client-supplied agent id to pin.
+ * required: the realtime target is the session config's `targetAgentID`, which the owner can edit, so
+ * the relay re-checks `CanRun` on it for the CALLER before this elevation.
  *
  * PUBLIC WEB-WIDGET guests are deliberately EXCLUDED (returned unchanged): their seeded role writes
  * run rows under the guest principal, which the `Widget Guest: Own Agent Runs` RLS read filter