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

package/src/isolatedProvider.ts

@@ -0,0 +1,22 @@
+import { DatabaseProviderBase, Metadata } from '@memberjunction/core';
+
+/**
+ * A fresh Read-Write provider with its OWN transaction state, sharing the server's connection pool.
+ *
+ * A provider's ambient transaction (`BeginTransaction` / `CommitTransaction` / `RollbackTransaction`)
+ * is a field on the provider INSTANCE. Two units of work that open transactions on one instance nest
+ * into each other, and every write anyone else makes through that instance while one is open lands
+ * inside it (MJ#2140; `entityTransactionScope.ts`). The process-global `Metadata.Provider` is shared
+ * by every request, scheduled job and background service, so transactional work must never run on
+ * it: one transaction left open there silently swallows every later global-provider write until the
+ * process restarts.
+ *
+ * GraphQL resolvers already get a per-request provider from `AppContext.providers`. Code that runs
+ * outside one, such as the auth flow before the context exists, calls this.
+ *
+ * Cheap: it is the global provider's `CreateIndependentInstance()` (SQL Server and PostgreSQL), which
+ * reuses the already-loaded metadata and the shared pool.
+ */
+export async function CreateIsolatedProvider(): Promise<DatabaseProviderBase> {
+  return (Metadata.Provider as DatabaseProviderBase).CreateIndependentInstance(); // global-provider-ok: borrows only its pool and metadata, never its transaction state
+}

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/realtimeProxy/RealtimeProxyServer.ts

@@ -2,7 +2,27 @@ import type { IncomingMessage } from 'node:http';
 import type { Duplex } from 'node:stream';
 import { WebSocket as WsClient, WebSocketServer, type RawData } from 'ws';
 import { BaseSingleton, ShutdownRegistry, type IShutdownable } from '@memberjunction/global';
-import { RealtimeProxyRegistry, REALTIME_PROXY_PATH, type RealtimeProxyTicketEntry } from '@memberjunction/ai';
+import {
+    RealtimeProxyRegistry,
+    REALTIME_PROXY_PATH,
+    REALTIME_RELAY_PATH,
+    type IRealtimeRelayPolicy,
+    type RealtimeProxyTicketEntry,
+} from '@memberjunction/ai';
+import {
+    RealtimeRelayTunnel,
+    RelayTicketPrefix,
+    REALTIME_RELAY_LIMITS,
+    REALTIME_RELAY_MAX_CLIENT_FRAME_BYTES,
+    type RealtimeRelayLimits,
+    type RealtimeRelayTunnelHost,
+} from './RealtimeRelayTunnel.js';
+
+/** The optional Origin allowlist both paths apply: comma-separated origins. */
+const ALLOWED_ORIGINS_ENV = 'MJ_REALTIME_PROXY_ALLOWED_ORIGINS';
+
+/** The longest part of a refused Origin header a log line quotes. */
+const MAX_LOGGED_ORIGIN_CHARS = 200;
 
 /**
  * MJAPI's realtime websocket **proxy** — the transport half of the self-hosted realtime provider story.
@@ -18,6 +38,11 @@ import { RealtimeProxyRegistry, REALTIME_PROXY_PATH, type RealtimeProxyTicketEnt
  * wire vocabulary) and knows nothing about any specific provider — it is a pure authenticated byte tunnel,
  * reusable by any future self-hosted realtime provider that mints a ticket.
  *
+ * It also serves the realtime **relay** at `{REALTIME_RELAY_PATH}/<ticket>/…` (any suffix: a provider's
+ * browser SDK appends its own path): one ticket per realtime session, a frame policy from the provider driver
+ * between the legs (see {@link RealtimeRelayTunnel}), one live upstream per session (a resume replaces the
+ * older connection). The Origin allowlist applies to both paths.
+ *
  * A {@link BaseSingleton} + {@link IShutdownable}: it tracks live tunnels and closes them on graceful
  * shutdown (drained by MJServer's `ShutdownRegistry` before `httpServer.close()`).
  */
@@ -27,9 +52,23 @@ export class RealtimeProxyServer extends BaseSingleton<RealtimeProxyServer> impl
     /** `noServer` so THIS server never binds its own upgrade listener — MJServer routes upgrades to it by path. */
     private readonly wss = new WebSocketServer({ noServer: true });
 
+    /** The relay's upgrade server: the same routing, plus the client frame cap, enforced while a frame is read. */
+    private readonly relayWss = new WebSocketServer({ noServer: true, maxPayload: REALTIME_RELAY_MAX_CLIENT_FRAME_BYTES });
+
     /** Live browser↔upstream tunnels, tracked for shutdown teardown. */
     private readonly tunnels = new Set<RealtimeProxyTunnel>();
 
+    /** Live relay connections, tracked for shutdown teardown. */
+    private readonly relays = new Set<RealtimeRelayTunnel>();
+
+    /** The granted connection each relay session uses now: one live upstream per session. */
+    private readonly liveRelays = new Map<string, RealtimeRelayTunnel>();
+
+    private readonly relayHost: RealtimeRelayTunnelHost = {
+        OnGranted: (tunnel) => this.relayGranted(tunnel),
+        OnClosed: (tunnel) => this.relayClosed(tunnel),
+    };
+
     private registered = false;
 
     protected constructor() {
@@ -41,32 +80,107 @@ export class RealtimeProxyServer extends BaseSingleton<RealtimeProxyServer> impl
         return super.getInstance<RealtimeProxyServer>();
     }
 
+    /** The relay's deadlines, ping interval and pre-open buffer ({@link REALTIME_RELAY_LIMITS}); a subclass may tune them. */
+    protected get RelayLimits(): RealtimeRelayLimits {
+        return REALTIME_RELAY_LIMITS;
+    }
+
     /**
-     * Routes an HTTP `upgrade` for {@link REALTIME_PROXY_PATH} to the proxy. Returns `true` when it OWNS
-     * (handled/rejected) the request, `false` when the path is not the proxy's — so the caller leaves the
-     * socket for the GraphQL websocket server's own upgrade listener. NEVER destroys a socket it doesn't own.
+     * Routes an HTTP `upgrade` for {@link REALTIME_PROXY_PATH} (ticket in the query) or {@link REALTIME_RELAY_PATH}
+     * (ticket in the path, any suffix). Returns `true` when it OWNS (handled/rejected) the request, `false` when
+     * the path is neither — so the caller leaves the socket for the GraphQL websocket server's own upgrade
+     * listener. NEVER destroys a socket it doesn't own.
      */
     public TryHandleUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer): boolean {
         const url = RealtimeProxyServer.parseUrl(request.url);
-        if (!url || url.pathname !== REALTIME_PROXY_PATH) {
-            return false; // not ours — leave it for the GraphQL WS server
+        if (url?.pathname === REALTIME_PROXY_PATH) {
+            this.handleProxyUpgrade(request, socket, head, url);
+            return true;
         }
+        if (url && RealtimeProxyServer.isRelayPath(url.pathname)) {
+            this.handleRelayUpgrade(request, socket, head, url.pathname);
+            return true;
+        }
+        return false; // not ours — leave it for the GraphQL WS server
+    }
+
+    /** `/realtime-proxy?ticket=<id>`: consumes the single-use ticket and opens a byte tunnel. */
+    private handleProxyUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, url: URL): void {
         this.ensureRegistered();
         // Optional Origin allowlist (MJ_REALTIME_PROXY_ALLOWED_ORIGINS: comma-separated origins).
         // Unset ⇒ prior behavior (the single-use short-TTL ticket remains the primary guard);
         // set ⇒ a browser page on a foreign origin cannot ride a leaked ticket id.
         if (!RealtimeProxyServer.originAllowed(request.headers?.origin)) {
-            RealtimeProxyServer.rejectUpgrade(socket, 403, 'Forbidden');
-            return true;
+            RealtimeProxyServer.refuseOrigin(socket, '[RealtimeProxy]', request.headers?.origin);
+            return;
         }
         const ticketId = url.searchParams.get('ticket') ?? '';
         const entry = RealtimeProxyRegistry.Instance.Consume(ticketId);
         if (!entry) {
             RealtimeProxyServer.rejectUpgrade(socket, 401, 'Unauthorized');
-            return true;
+            return;
         }
         this.wss.handleUpgrade(request, socket, head, (browserWs) => this.openTunnel(browserWs, entry));
-        return true;
+    }
+
+    /**
+     * `/realtime/relay/<ticket>/…`: the same Origin allowlist (403, logged with the origin), then 401 unless the relay
+     * session can still take a connection. Whether it opens fresh or resumes is decided on the connection's first frame.
+     * A query string is ignored: the ticket is read from the path only.
+     */
+    private handleRelayUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, pathname: string): void {
+        this.ensureRegistered();
+        if (!RealtimeProxyServer.originAllowed(request.headers?.origin)) {
+            RealtimeProxyServer.refuseOrigin(socket, '[RealtimeRelay]', request.headers?.origin);
+            return;
+        }
+        const sessionId = RealtimeProxyServer.relayTicketFrom(pathname);
+        const session = sessionId ? RealtimeProxyRegistry.Instance.FindRelaySession(sessionId) : null;
+        if (!session) {
+            console.warn(`[RealtimeRelay] relay ${RelayTicketPrefix(sessionId)}: upgrade refused (unknown, ended or used up)`);
+            RealtimeProxyServer.rejectUpgrade(socket, 401, 'Unauthorized');
+            return;
+        }
+        this.relayWss.handleUpgrade(request, socket, head, (browserWs) => this.openRelay(browserWs, sessionId, session.Policy));
+    }
+
+    /** Whether a path is the relay's: `/realtime/relay` itself or anything below it. */
+    private static isRelayPath(pathname: string): boolean {
+        return pathname === REALTIME_RELAY_PATH || pathname.startsWith(`${REALTIME_RELAY_PATH}/`);
+    }
+
+    /** The ticket id in a relay path: the segment right after `/realtime/relay/`; whatever follows is the SDK's. */
+    private static relayTicketFrom(pathname: string): string {
+        const segment = pathname.slice(REALTIME_RELAY_PATH.length + 1).split('/')[0] ?? '';
+        try {
+            return decodeURIComponent(segment);
+        } catch {
+            return ''; // malformed escape — no ticket
+        }
+    }
+
+    /** Starts one relay connection; the session's policy reads its first frame. */
+    private openRelay(browserWs: WsClient, sessionId: string, policy: IRealtimeRelayPolicy): void {
+        const tunnel = new RealtimeRelayTunnel(browserWs, sessionId, policy, this.RelayLimits, this.relayHost);
+        this.relays.add(tunnel);
+        tunnel.Start();
+    }
+
+    /** A relay connection was granted: it becomes the session's live one, and the older one closes. */
+    private relayGranted(tunnel: RealtimeRelayTunnel): void {
+        const previous = this.liveRelays.get(tunnel.SessionID);
+        this.liveRelays.set(tunnel.SessionID, tunnel);
+        if (previous && previous !== tunnel) {
+            previous.Close(1000, 'Replaced by a resumed connection');
+        }
+    }
+
+    /** A relay connection closed: forget it, and the session's live slot when it held it. */
+    private relayClosed(tunnel: RealtimeRelayTunnel): void {
+        this.relays.delete(tunnel);
+        if (this.liveRelays.get(tunnel.SessionID) === tunnel) {
+            this.liveRelays.delete(tunnel.SessionID);
+        }
     }
 
     /**
@@ -79,7 +193,7 @@ export class RealtimeProxyServer extends BaseSingleton<RealtimeProxyServer> impl
      * @returns True when allowed (or no allowlist is configured).
      */
     private static originAllowed(origin: string | undefined): boolean {
-        const raw = process.env['MJ_REALTIME_PROXY_ALLOWED_ORIGINS'];
+        const raw = process.env[ALLOWED_ORIGINS_ENV];
         if (!raw || raw.trim().length === 0) {
             return true; // no allowlist configured — prior behavior
         }
@@ -106,16 +220,23 @@ export class RealtimeProxyServer extends BaseSingleton<RealtimeProxyServer> impl
         }
     }
 
-    /** Closes every live tunnel and the proxy server. Idempotent; never throws. */
+    /** Closes every live tunnel and relay connection (1001), and both upgrade servers. Idempotent; never throws. */
     public Shutdown(): void {
         for (const tunnel of [...this.tunnels]) {
             tunnel.Close();
         }
         this.tunnels.clear();
-        try {
-            this.wss.close();
-        } catch {
-            /* already closing */
+        for (const relay of [...this.relays]) {
+            relay.Close(1001, 'Server shutting down');
+        }
+        this.relays.clear();
+        this.liveRelays.clear();
+        for (const server of [this.wss, this.relayWss]) {
+            try {
+                server.close();
+            } catch {
+                /* already closing */
+            }
         }
     }
 
@@ -131,6 +252,17 @@ export class RealtimeProxyServer extends BaseSingleton<RealtimeProxyServer> impl
         }
     }
 
+    /**
+     * Refuses an upgrade whose Origin is not on the allowlist: 403, and one log line naming the origin (printable
+     * characters only, shortened), so a browser page on an origin the allowlist lacks shows in MJAPI's log. The line
+     * never quotes the request's path or query: they carry the ticket.
+     */
+    private static refuseOrigin(socket: Duplex, logPrefix: string, origin: string | undefined): void {
+        const shown = (origin ?? '').replace(/[^\x20-\x7E]/g, '?').slice(0, MAX_LOGGED_ORIGIN_CHARS);
+        console.warn(`${logPrefix} upgrade refused (403): origin "${shown}" is not in ${ALLOWED_ORIGINS_ENV}`);
+        RealtimeProxyServer.rejectUpgrade(socket, 403, 'Forbidden');
+    }
+
     /** Writes a minimal HTTP error response and destroys the socket (used for a rejected upgrade). */
     private static rejectUpgrade(socket: Duplex, code: number, reason: string): void {
         try {