@memberjunction/server 5.48.0 → 5.49.0

package/src/resolvers/QueryResolver.ts

@@ -202,7 +202,6 @@ export class RunQueryResolver extends ResolverBase {
     const provider = GetReadOnlyProvider(context.providers, {allowFallbackToReadWrite: true});
     const md = provider as unknown as IMetadataProvider;
     const rq = new RunQuery(provider as unknown as IRunQueryProvider);
-    console.log('GetQueryData called with:', { QueryID, Parameters, MaxRows, StartRow, ForceAuditLog, AuditLogDescription });
     const result = await rq.RunQuery(
       {
         QueryID: QueryID,
@@ -216,12 +215,7 @@ export class RunQueryResolver extends ResolverBase {
         Enrichment: Enrichment
       },
       context.userPayload.userRecord);
-    console.log('RunQuery result:', { 
-      Success: result.Success, 
-      ErrorMessage: result.ErrorMessage,
-      AppliedParameters: result.AppliedParameters 
-    });
-    
+
     // If QueryName is not populated by the provider, use efficient lookup
     let queryName = result.QueryName;
     if (!queryName) {

package/src/resolvers/RSUResolver.ts

@@ -77,6 +77,14 @@ export class RSUPipelineStepGQL {
 
     @Field(() => String)
     Message: string;
+
+    /** U11 — 1-based position within the pipeline's expected step sequence (determinate stepper). */
+    @Field(() => Int, { nullable: true })
+    StepIndex?: number;
+
+    /** U11 — expected total steps for the run. */
+    @Field(() => Int, { nullable: true })
+    StepTotal?: number;
 }
 
 @ObjectType()
@@ -158,6 +166,18 @@ export class RSUStatusGQL {
 
     @Field(() => String, { nullable: true })
     LastRunResult?: string | null;
+
+    /** U11 — name of the currently-executing pipeline step (null when idle). */
+    @Field(() => String, { nullable: true })
+    CurrentStepName?: string | null;
+
+    /** U11 — 1-based index of the current step (null when idle). Powers a determinate stepper. */
+    @Field(() => Int, { nullable: true })
+    CurrentStepIndex?: number | null;
+
+    /** U11 — expected total steps for the in-flight run (null when idle). */
+    @Field(() => Int, { nullable: true })
+    StepTotal?: number | null;
 }
 
 @ObjectType()
@@ -188,6 +208,10 @@ export class RSUResolver {
             OutOfSyncSince: status.OutOfSyncSince,
             LastRunAt: status.LastRunAt,
             LastRunResult: status.LastRunResult,
+            // U11 — live determinate step progress
+            CurrentStepName: status.CurrentStepName ?? null,
+            CurrentStepIndex: status.CurrentStepIndex ?? null,
+            StepTotal: status.StepTotal ?? null,
         };
     }
 
@@ -261,6 +285,8 @@ export class RSUResolver {
                 Status: s.Status,
                 DurationMs: s.DurationMs,
                 Message: s.Message,
+                StepIndex: s.StepIndex,
+                StepTotal: s.StepTotal,
             })),
             ErrorMessage: result.ErrorMessage,
             ErrorStep: result.ErrorStep,
@@ -307,6 +333,8 @@ export class RSUResolver {
                     Status: s.Status,
                     DurationMs: s.DurationMs,
                     Message: s.Message,
+                    StepIndex: s.StepIndex,
+                    StepTotal: s.StepTotal,
                 })),
                 ErrorMessage: result.ErrorMessage,
                 ErrorStep: result.ErrorStep,

package/src/resolvers/RunAIAgentResolver.ts

@@ -1,7 +1,7 @@
 import { Resolver, Mutation, Query, Arg, Ctx, ObjectType, Field, PubSub, PubSubEngine, Subscription, Root, ResolverFilterData, ID, Int } from 'type-graphql';
 import { AppContext, UserPayload } from '../types.js';
 import { DatabaseProviderBase, LogError, LogStatus, Metadata, RunView, UserInfo, IMetadataProvider } from '@memberjunction/core';
-import { MJConversationDetailEntity, MJConversationDetailAttachmentEntity, MJConversationDetailArtifactEntity, MJArtifactVersionEntity, MJAIAgentRequestEntity, ArtifactMetadataEngine } from '@memberjunction/core-entities';
+import { MJConversationDetailEntity, MJConversationDetailAttachmentEntity, MJConversationDetailArtifactEntity, MJArtifactVersionEntity, MJAIAgentRequestEntity, ArtifactMetadataEngine, ConversationEngine } from '@memberjunction/core-entities';
 import { RouteArtifact } from './artifact-routing.js';
 import { AgentRunner, ArtifactToolManager } from '@memberjunction/ai-agents';
 import { MJAIAgentEntityExtended, MJAIAgentRunEntityExtended, ExecuteAgentResult, ConversationUtility, AttachmentData, AgentExecutionStreamingCallback } from '@memberjunction/ai-core-plus';
@@ -1018,7 +1018,10 @@ export class RunAIAgentResolver extends ResolverBase {
                 conversationId,
                 currentUser,
                 maxHistoryMessages || 20,
-                p
+                p,
+                // The UI creates the agent-response placeholder row ('⏳ ...') before invoking
+                // this mutation — exclude it so the model never sees an empty assistant turn.
+                [conversationDetailId]
             );
 
             // Convert to JSON string for the existing executeAIAgent method
@@ -1337,58 +1340,89 @@ export class RunAIAgentResolver extends ResolverBase {
      * passes conversationId down.
      *
      * Opt #8: Switched from ResultType 'entity_object' to 'simple' with explicit Fields.
-     * The history query only needs ID, Role, and Message from each ConversationDetail record.
-     * Using 'entity_object' created full BaseEntity instances with getters/setters, dirty tracking,
-     * and validation — none of which are needed for read-only history assembly. The 'simple' result
-     * type returns plain JS objects, reducing per-record overhead (~30ms total savings).
+     * The history query only needs the window-assembly fields (ConversationWindowFields:
+     * ID, Sequence, Role, Message, SummaryOfEarlierConversation) from each
+     * ConversationDetail record. Using 'entity_object' created full BaseEntity instances
+     * with getters/setters, dirty tracking, and validation — none of which are needed for
+     * read-only history assembly. The 'simple' result type returns plain JS objects,
+     * reducing per-record overhead (~30ms total savings).
      */
     private async loadConversationHistoryWithAttachments(
         conversationId: string,
         contextUser: UserInfo,
         maxMessages: number,
-        provider: IMetadataProvider
+        provider: IMetadataProvider,
+        excludeDetailIds?: string[]
     ): Promise<ChatMessage[]> {
-        const rv = RunView.FromMetadataProvider(provider);
-        const attachmentService = GetAttachmentService();
-
-        // Load recent conversation details (messages) for this conversation.
-        // Only fetch the three fields we actually use — ID for attachment lookups,
-        // Role for message routing, Message for content.
-        const detailsResult = await rv.RunView<{ ID: string; Role: string; Message: string }>({
-            EntityName: 'MJ: Conversation Details',
-            ExtraFilter: `ConversationID='${conversationId}'`,
-            OrderBy: '__mj_CreatedAt DESC',
-            MaxRows: maxMessages,
-            Fields: ['ID', 'Role', 'Message'],
-            ResultType: 'simple'
-        }, contextUser);
-
-        if (!detailsResult.Success || !detailsResult.Results) {
-            throw new Error('Failed to load conversation history');
-        }
-
-        // Reverse to get chronological order (oldest first)
-        const details = detailsResult.Results.reverse();
-
-        // Get all message IDs for batch loading artifacts
-        const messageIds = details.map(d => d.ID);
+        // Context windowing (summary boundary + raw tail, or legacy last-N when no
+        // summary exists) shares ONE fold implementation with all other callers —
+        // ConversationEngine.AssembleContextWindow — and the ROWS come from the
+        // single-sourced fresh-per-request loader (same one the compaction pass uses).
+        // Three deliberate properties vs. the engine's cached GetAgentContextWindow:
+        //   1. Entity RLS applies (the engine path loads via a stored query with no
+        //      row-level security — wrong for guest/widget-scoped users), and the
+        //      process-global per-conversation cache — keyed by conversation, not user —
+        //      can't leak the first toucher's row visibility to later callers.
+        //   2. No server-side population of the engine's unbounded detail cache, and no
+        //      cross-server staleness (a warm cache misses rows written by other nodes).
+        //   3. Load failure THROWS → the mutation fails, instead of silently running
+        //      the agent against zero history.
+        const rows = await ConversationEngine.LoadWindowRowsFresh(conversationId, contextUser, provider);
+        const window = ConversationEngine.AssembleContextWindow(rows, {
+            maxTailMessages: maxMessages,
+            excludeDetailIds
+        });
 
-        // Batch load input artifacts for these messages. Since the backfill migration
+        // Batch load input artifacts for the windowed messages. Since the backfill migration
         // (V202605271400__Backfill_Attachment_Artifacts) converted all legacy
         // ConversationDetailAttachment rows to artifact pairs, the artifact junction
-        // is the single source of truth — no separate attachment query needed.
+        // is the single source of truth — no separate attachment query needed. The synthetic
+        // summary message has no detail row and needs no enrichment.
+        const messageIds = window
+            .map(m => m.metadata?.conversationDetailId)
+            .filter((id): id is string => !!id);
         const inputArtifactsByDetailId = await this.loadInputArtifactsBatch(messageIds, contextUser, provider);
 
         // Build ChatMessage array with attachments and input artifacts
         const messages: ChatMessage[] = [];
 
-        for (const detail of details) {
-            const role = this.mapDetailRoleToMessageRole(detail.Role);
-            const validAttachments: AttachmentData[] = [];
+        for (const windowMessage of window) {
+            const detailId = windowMessage.metadata?.conversationDetailId;
+            const baseText = typeof windowMessage.content === 'string' ? windowMessage.content : '';
+            const inputArtifacts = detailId ? (inputArtifactsByDetailId.get(detailId) || []) : [];
+            const validAttachments = await this.buildAttachmentsForArtifacts(inputArtifacts, contextUser, provider);
+
+            // Build message content (with or without attachments)
+            let content: ChatMessageContent;
+            if (validAttachments.length > 0) {
+                // Use ConversationUtility to build multimodal content blocks
+                content = await ConversationUtility.BuildChatMessageContent(baseText, validAttachments);
+            } else {
+                content = baseText;
+            }
+
+            messages.push({
+                role: windowMessage.role,
+                content,
+                metadata: windowMessage.metadata
+            });
+        }
+
+        return messages;
+    }
+
+    /**
+     * Converts a message's input artifact versions into inline attachment payloads,
+     * honoring each artifact's delivery routing (inline vs. tools-only) via RouteArtifact.
+     */
+    private async buildAttachmentsForArtifacts(
+        inputArtifacts: MJArtifactVersionEntity[],
+        contextUser: UserInfo,
+        provider: IMetadataProvider
+    ): Promise<AttachmentData[]> {
+        const validAttachments: AttachmentData[] = [];
 
-            // Get input artifacts for this message — routing via RouteArtifact.
-            const inputArtifacts = inputArtifactsByDetailId.get(detail.ID) || [];
-            for (const artifactVersion of inputArtifacts) {
+        for (const artifactVersion of inputArtifacts) {
                 const artifactMime = artifactVersion.MimeType || '';
                 const fileName = artifactVersion.FileName ?? '';
                 const ext = fileName.includes('.') ? fileName.split('.').pop() : undefined;
@@ -1477,37 +1511,7 @@ export class RunAIAgentResolver extends ResolverBase {
                 }
             }
 
-            // Build message content (with or without attachments)
-            let content: ChatMessageContent;
-
-            if (validAttachments.length > 0) {
-                // Use ConversationUtility to build multimodal content blocks
-                content = await ConversationUtility.BuildChatMessageContent(
-                    detail.Message || '',
-                    validAttachments
-                );
-            } else {
-                content = detail.Message || '';
-            }
-
-            messages.push({
-                role,
-                content
-            });
-        }
-
-        return messages;
-    }
-
-    /**
-     * Map ConversationDetail Role to ChatMessage role
-     */
-    private mapDetailRoleToMessageRole(role: string): 'user' | 'assistant' | 'system' {
-        const roleLower = (role || '').toLowerCase();
-        if (roleLower === 'user') return 'user';
-        if (roleLower === 'assistant' || roleLower === 'agent' || roleLower === 'ai') return 'assistant';
-        if (roleLower === 'system') return 'system';
-        return 'user'; // Default to user
+        return validAttachments;
     }
 
     /**

package/src/resolvers/TransactionGroupResolver.ts

@@ -3,6 +3,7 @@ import { AppContext } from '../types.js';
 import { CompositeKey, IMetadataProvider, KeyValuePair, LogError, Metadata, TransactionVariable, BaseEntity, EntityDeleteOptions, EntitySaveOptions } from '@memberjunction/core';
 import { SafeJSONParse } from '@memberjunction/global';
 import { GetReadWriteProvider } from '../util.js';
+import { ResolverBase } from '../generic/ResolverBase.js';
 
 export enum TransactionVariableType {
     Define = "Define",
@@ -77,13 +78,46 @@ export class TransactionOutputType {
 
 
 
-export class TransactionResolver {
+export class TransactionResolver extends ResolverBase {
+    /**
+     * Maps a TransactionGroup item's operation type onto the SAME API-key scope path the singular
+     * CRUD mutations enforce (ResolverBase.CreateRecord/UpdateRecord/DeleteRecord), so the
+     * transaction path cannot be used to sidestep a key's scope ceiling.
+     */
+    protected GetScopePathForOperation(operationType: TransactionOperationType): string {
+        switch (operationType) {
+            case TransactionOperationType.Create:
+                return 'entity:create';
+            case TransactionOperationType.Update:
+                return 'entity:update';
+            case TransactionOperationType.Delete:
+                return 'entity:delete';
+        }
+    }
+
     @Mutation(() => TransactionOutputType)
     async ExecuteTransactionGroup(
     @Arg('group', () => TransactionInputType ) group: TransactionInputType,
     @Ctx() context: AppContext
     ) {
-        try { 
+        // SECURITY (bug-register B1 / catalog SEC1): route every transaction item through the same
+        // API-key scope gate the singular CRUD resolvers use, BEFORE any entity work happens.
+        // Without this pre-pass, a restricted API key (e.g. view:run-only) could Create/Update/
+        // Delete over the wire by wrapping the mutation in a TransactionGroup — the scope ceiling
+        // was simply never consulted on this path. No-op for OAuth/JWT sessions (no apiKeyHash),
+        // and full_access keys short-circuit inside CheckAPIKeyScopeAuthorization, so legitimate
+        // callers are unaffected; only keys that would already be denied on the singular CRUD
+        // mutations are now equally denied here. Deliberately OUTSIDE the try below so the
+        // AuthorizationError propagates to the client unwrapped.
+        for (const item of group.Items) {
+            await this.CheckAPIKeyScopeAuthorization(
+                this.GetScopePathForOperation(item.OperationType),
+                item.EntityName,
+                context.userPayload
+            );
+        }
+
+        try {
             // we have received the transaction group information via the network, now we need to reconstruct our TransactionGroup object and run it
             const md = (GetReadWriteProvider(context.providers, { allowFallbackToReadOnly: true }) as unknown as IMetadataProvider) ?? new Metadata();
             const tg = await md.CreateTransactionGroup();

package/src/resolvers/__tests__/GetDataResolver.tokens.test.ts

@@ -0,0 +1,138 @@
+// type-graphql decorators on the resolver class call Reflect.getMetadata, which only
+// exists when this polyfill is loaded first (mirrors RealtimeBridgeResolver.test.ts).
+import 'reflect-metadata';
+
+import { describe, it, expect, vi } from 'vitest';
+
+// This test exercises only the plain, exported token-lifecycle functions at the
+// bottom of GetDataResolver.ts — NOT the `GetData`/`GetAllEntities` resolver
+// methods. Those methods (and the module-level `import ... from '../index.js'`)
+// pull in MJServer's entire bootstrap graph (SQL Server provider, Apollo server,
+// env-driven config validation), which is both heavy and requires live DB env
+// vars to even import. Mock those heavy imports out so this file stays a true,
+// isolated unit test of the token-tracking logic (mirrors the mocking convention
+// in RealtimeBridgeResolver.test.ts).
+vi.mock('../../index.js', () => ({ getDbType: vi.fn() }));
+vi.mock('@memberjunction/generic-database-provider', () => ({
+  QueryCompositionEngine: vi.fn(() => ({ HasCompositionTokens: vi.fn(() => false) })),
+}));
+vi.mock('../../util.js', () => ({ GetReadOnlyDataSource: vi.fn(), GetReadOnlyProvider: vi.fn() }));
+vi.mock('../../auth/index.js', () => ({ getSystemUser: vi.fn() }));
+vi.mock('mssql', () => ({ default: { Request: vi.fn() } }));
+
+import {
+  registerAccessToken,
+  deleteAccessToken,
+  tokenExists,
+  isTokenValid,
+  recordTokenUse,
+  pruneExpiredTokens,
+  getAccessTokenCount,
+} from '../GetDataResolver.js';
+
+// ---------------------------------------------------------------------------
+// Regression coverage for a memory leak (Memory Leak Audit Round 7, Critical):
+// `__accessTokens` (module-level array backing GetDataResolver's short-lived
+// access tokens) grew forever — nothing ever removed an expired token,
+// `deleteAccessToken()` has no production caller, and `isTokenValid()` only
+// checked expiry without pruning. `registerAccessToken()` now sweeps expired
+// tokens (via `pruneExpiredTokens()`) on every call, so the array self-bounds to
+// roughly "tokens registered within one lifespan window" instead of growing with
+// total lifetime registrations.
+//
+// Each test uses a unique token (uuidv4-backed default, or an explicit unique
+// string) so state from other tests sharing the same module-level array doesn't
+// interfere with assertions.
+// ---------------------------------------------------------------------------
+
+let seq = 0;
+const uniqueToken = () => `test-token-${Date.now()}-${++seq}`;
+
+describe('GetDataResolver access-token lifecycle', () => {
+  it('registerAccessToken() creates a token that is valid and exists', () => {
+    const token = uniqueToken();
+    const created = registerAccessToken(token, 60_000);
+    expect(created.Token).toBe(token);
+    expect(tokenExists(token)).toBe(true);
+    expect(isTokenValid(token)).toBe(true);
+  });
+
+  it('registerAccessToken() throws when the same custom token is registered twice', () => {
+    const token = uniqueToken();
+    registerAccessToken(token, 60_000);
+    expect(() => registerAccessToken(token, 60_000)).toThrow(/already exists/);
+  });
+
+  it('isTokenValid() is false for an unknown token and for an expired one', () => {
+    expect(isTokenValid('never-registered-token')).toBe(false);
+
+    const token = uniqueToken();
+    registerAccessToken(token, -1); // already expired (ExpiresAt in the past)
+    expect(isTokenValid(token)).toBe(false);
+  });
+
+  it('deleteAccessToken() removes a token and throws for an unknown one', () => {
+    const token = uniqueToken();
+    registerAccessToken(token, 60_000);
+    expect(tokenExists(token)).toBe(true);
+
+    deleteAccessToken(token);
+    expect(tokenExists(token)).toBe(false);
+    expect(() => deleteAccessToken(token)).toThrow(/does not exist/);
+  });
+
+  it('recordTokenUse() appends to TokenUses and throws for an unknown token', () => {
+    const token = uniqueToken();
+    registerAccessToken(token, 60_000);
+
+    expect(() => recordTokenUse(token, { some: 'payload' })).not.toThrow();
+    expect(() => recordTokenUse('never-registered-token', {})).toThrow(/does not exist/);
+  });
+
+  it('pruneExpiredTokens() removes only tokens whose ExpiresAt has passed', () => {
+    const expiredToken = uniqueToken();
+    const liveToken = uniqueToken();
+    registerAccessToken(expiredToken, -1); // already expired
+    registerAccessToken(liveToken, 60_000); // still valid
+
+    pruneExpiredTokens();
+
+    expect(tokenExists(expiredToken)).toBe(false);
+    expect(tokenExists(liveToken)).toBe(true);
+  });
+
+  it('pruneExpiredTokens() accepts an injected "now" for deterministic testing', () => {
+    const token = uniqueToken();
+    const registeredAt = new Date('2026-01-01T00:00:00Z');
+    registerAccessToken(token, 5 * 60 * 1000); // 5-minute lifespan from real "now"
+
+    // Simulate a check far in the future — token should count as expired at that instant.
+    const farFuture = new Date(registeredAt.getTime() + 365 * 24 * 60 * 60 * 1000);
+    pruneExpiredTokens(farFuture);
+
+    expect(tokenExists(token)).toBe(false);
+  });
+
+  it('the core Round 7 regression: registering many expired tokens does not grow the array without bound', () => {
+    const before = getAccessTokenCount();
+
+    // Simulate 50 short-lived tokens that all expire immediately (e.g. a burst
+    // of external calls with a near-zero lifespan, or tokens whose consumer
+    // never came back before expiry — the exact shape of the leak this fix
+    // addresses).
+    for (let i = 0; i < 50; i++) {
+      registerAccessToken(`${uniqueToken()}-burst-${i}`, -1);
+    }
+
+    // Register one more, healthy token — its registerAccessToken() call sweeps
+    // all 50 expired ones out, so the count should NOT have grown by 51; it
+    // should only reflect whatever was live before plus this one new token.
+    const survivorToken = uniqueToken();
+    registerAccessToken(survivorToken, 60_000);
+
+    // The 50 expired burst tokens must be gone — the array self-bounded rather
+    // than accumulating every registration for the life of the process.
+    expect(getAccessTokenCount()).toBeLessThan(before + 51);
+    expect(tokenExists(survivorToken)).toBe(true);
+  });
+});

package/src/resolvers/adhoc-query-helpers.ts

@@ -0,0 +1,50 @@
+/**
+ * Pure, dependency-free helpers for {@link AdhocQueryResolver}. Kept in their own
+ * module (no type-graphql / mssql imports) so the total-row-count boundary logic is
+ * unit-testable without standing up the GraphQL resolver or a database.
+ */
+
+/**
+ * Determines the exact total row count from the page alone, when it can be known
+ * without a separate `COUNT(*)`:
+ *
+ * - **Not paging** (`maxRows == null`): the query ran uncapped, so every row came
+ *   back — the total is just the number returned.
+ * - **Short page** (`pageLength < maxRows`): a page shorter than the page size means
+ *   there are no rows beyond it, so the total is `startRow + pageLength` exactly.
+ * - **Full page** (`pageLength >= maxRows`): more rows may exist — returns `null` to
+ *   signal that a `COUNT(*)` is required to know the true total.
+ */
+export function exactTotalFromPage(
+    startRow: number,
+    pageLength: number,
+    maxRows: number | null,
+): number | null {
+    if (maxRows == null) {
+        return pageLength;
+    }
+    if (pageLength < maxRows) {
+        return startRow + pageLength;
+    }
+    return null;
+}
+
+/**
+ * Reads the total row count from a `COUNT(*)` recordset (`[{ TotalRowCount }]`),
+ * falling back to `fallback` when the count is absent, non-numeric, or negative — so
+ * an unexpected count shape never yields a misleading total. `fallback` should be a
+ * safe lower bound (e.g. `startRow + rowsReturned`).
+ */
+export function resolveAdhocTotalRowCount(
+    countRows: ReadonlyArray<{ TotalRowCount?: unknown }> | null | undefined,
+    fallback: number,
+): number {
+    const raw = countRows?.[0]?.TotalRowCount;
+    if (raw != null) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n >= 0) {
+            return Math.floor(n);
+        }
+    }
+    return fallback;
+}

package/src/rest/OAuthCallbackHandler.ts

@@ -98,7 +98,8 @@ export class OAuthCallbackHandler {
      * Renders a success page after OAuth authorization completes.
      */
     private handleSuccessPage(req: express.Request, res: express.Response): void {
-        const { state, connectionId } = req.query;
+        const { connectionId } = req.query;
+        const safeConnectionId = connectionId ? this.escapeHtml(String(connectionId)) : '';
         res.status(200).send(`
 <!DOCTYPE html>
 <html lang="en">
@@ -120,7 +121,7 @@ export class OAuthCallbackHandler {
         <div class="icon">✅</div>
         <h1>Authorization Successful</h1>
         <p>Your MCP server connection has been authorized. You can close this window and return to MemberJunction.</p>
-        ${connectionId ? `<div class="details">Connection ID: ${connectionId}</div>` : ''}
+        ${safeConnectionId ? `<div class="details">Connection ID: ${safeConnectionId}</div>` : ''}
     </div>
 </body>
 </html>
@@ -132,8 +133,8 @@ export class OAuthCallbackHandler {
      */
     private handleErrorPage(req: express.Request, res: express.Response): void {
         const { error, error_description } = req.query;
-        const errorCode = error ? String(error) : 'unknown_error';
-        const errorMessage = error_description ? String(error_description) : 'An error occurred during authorization.';
+        const errorCode = this.escapeHtml(error ? String(error) : 'unknown_error');
+        const errorMessage = this.escapeHtml(error_description ? String(error_description) : 'An error occurred during authorization.');
 
         res.status(200).send(`
 <!DOCTYPE html>
@@ -542,6 +543,23 @@ export class OAuthCallbackHandler {
     // Helper Methods
     // ========================================
 
+    /**
+     * Escapes HTML-special characters in a string so untrusted (e.g. query-string-derived)
+     * values can be safely interpolated into an HTML response without introducing
+     * reflected-XSS. Escapes `&`, `<`, `>`, `"`, and `'`.
+     *
+     * @param value - The raw string to escape
+     * @returns The HTML-escaped string
+     */
+    private escapeHtml(value: string): string {
+        return value
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&#39;');
+    }
+
     /**
      * Gets the system user from cache.
      */

package/src/telephony/media-upgrade-router.ts

@@ -28,6 +28,23 @@ export function RegisterMediaUpgradeRoute(path: string, wss: WebSocketServer): v
     mediaRoutes.set(path, wss);
 }
 
+/**
+ * Whether an upgrade request's pathname should be routed to the GraphQL subscriptions socket.
+ *
+ * `GRAPHQL_ROOT_PATH` defaults to `/` (see `config.ts` / the docker README). On the HTTP side that
+ * default is invisible — Express's `app.use(graphqlRootPath, ...)` mounts with PREFIX matching, so a
+ * request to `/graphql` lands on the GraphQL middleware even when the configured root is the bare `/`.
+ * A WebSocket upgrade has no such prefix-matching fallback: it needs an exact pathname match. With no
+ * override, a stock install's default root (`/`) never matches the shipped MJExplorer client's hardcoded
+ * `GRAPHQL_WS_URI` (`ws://<host>/graphql`), so every subscription upgrade gets silently rejected — surfaces
+ * client-side as "WebSocket handshake: Unexpected response code: 400". Accept the conventional `/graphql`
+ * suffix as an alias of the bare root so a stock install works out of the box; a non-default `graphqlPath`
+ * (e.g. `/api`) keeps requiring an exact match, unchanged.
+ */
+export function IsGraphQLWsPath(pathname: string, graphqlPath: string): boolean {
+    return pathname === graphqlPath || (graphqlPath === '/' && pathname === '/graphql');
+}
+
 /**
  * Installs the single path-routing `upgrade` dispatcher. No-op when no media routes are registered, so
  * the GraphQL server keeps its own listener untouched. Otherwise it removes the auto-attached listeners
@@ -48,7 +65,7 @@ export function InstallMediaUpgradeDispatcher(httpServer: HttpServer, graphqlWss
     };
     httpServer.on('upgrade', (req: IncomingMessage, socket: Duplex, head: Buffer) => {
         const pathname = (req.url ?? '').split('?')[0];
-        if (pathname === graphqlPath) {
+        if (IsGraphQLWsPath(pathname, graphqlPath)) {
             dispatch(graphqlWss, req, socket, head);
             return;
         }