@minionry/minion 0.7.36

package/dist/server/services/platform.js

@@ -0,0 +1,656 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { arch, hostname, type } from 'node:os';
+import { basename } from 'node:path';
+import { AnalyticsEvents, trackEvent } from './analytics.js';
+import { buildE2eeRequiredBrowserError, mustRefuseWhenCleartext } from './browser-frame-policy.js';
+import { getClientId } from './client-id.js';
+import { dropGroupKeyWrapContext, handleE2eeKeyRequest, handleE2eeMembershipChange, } from './e2ee-group-key.js';
+import { CLI_VERSION, getCredentials } from './platform-credentials.js';
+import { E2eeContentCodec } from './platform-e2ee.js';
+import { E2EE_CAPABILITIES, encodeForRelay, isV1Envelope, readPairedEnvelopeAck, unwrapEnvelopeV1, } from './platform-envelope.js';
+import { HeartbeatMonitor } from './platform-heartbeat.js';
+import { classifyClose, ReconnectPolicy } from './platform-reconnect.js';
+import { TokenLifecycle } from './platform-token-lifecycle.js';
+import { resolveCliEnvironment, resolvePlatformUrl } from './platform-url.js';
+import { captureException } from './sentry.js';
+import { getMaxUploadBytes } from './settings.js';
+import { debugLog } from './websocket/debug-log.js';
+import { applyFileShareSync, replaceFileShareRegistry } from './websocket/file-share-handlers.js';
+import { FILE_TRANSFER_CAPABILITY } from './websocket/file-transfer-http.js';
+const browserTrace = debugLog('relay');
+export function getMachineIdentifier() {
+    const machineHostname = hostname();
+    const nodeVersion = process.version;
+    const osType = type().toLowerCase();
+    const cpuArch = arch();
+    return `${machineHostname} @ node-${nodeVersion} ${osType} (${cpuArch})`;
+}
+const TURN_FETCH_TIMEOUT_MS = 5000;
+export async function fetchTurnCredentials(platformUrl) {
+    const creds = getCredentials();
+    if (!creds?.token)
+        return null;
+    const base = platformUrl ?? resolvePlatformUrl();
+    try {
+        const response = await fetch(`${base}/api/turn`, {
+            headers: { 'Authorization': `Bearer ${creds.token}` },
+            signal: AbortSignal.timeout(TURN_FETCH_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            console.warn(`[Platform] TURN credential fetch failed (${response.status}) — falling back to STUN-only`);
+            return null;
+        }
+        const data = (await response.json());
+        if (typeof data.ttl !== 'number' || !Array.isArray(data.iceServers)) {
+            console.warn('[Platform] TURN credential fetch returned a malformed payload — falling back to STUN-only');
+            return null;
+        }
+        return { ttl: data.ttl, iceServers: data.iceServers };
+    }
+    catch (err) {
+        console.warn(`[Platform] TURN credential fetch error (${err instanceof Error ? err.message : String(err)}) — falling back to STUN-only`);
+        return null;
+    }
+}
+let WebSocketImpl;
+if (typeof WebSocket !== 'undefined') {
+    WebSocketImpl = WebSocket;
+}
+else {
+    try {
+        const { default: WS } = await import('ws');
+        WebSocketImpl = WS;
+    }
+    catch {
+        throw new Error('WebSocket not available: install the "ws" package or use Node.js 21+');
+    }
+}
+const DEFAULT_PLATFORM_URL = resolvePlatformUrl();
+const PROTOCOL_VERSION = 1;
+const PROTOCOL_UPGRADE_RECONNECT_DELAY_MS = 60 * 60 * 1000;
+const HEARTBEAT_INTERVAL_MS = 25_000;
+const MAX_MISSED_PONGS = 2;
+const CONNECT_TIMEOUT_MS = 10_000;
+const HANDSHAKE_ERROR_CLOSE_GRACE_MS = 500;
+const HEARTBEAT_TIMEOUT_CLOSE_CODE = 4006;
+const DIAL_TIMEOUT_CLOSE_CODE = 4011;
+const CREDENTIALS_POLL_MS = 15_000;
+const OUTBOUND_QUEUE_LIMIT = 100;
+const MAX_OUTBOUND_FRAME_BYTES = 16 * 1024 * 1024;
+const NEVER_QUEUED_TYPES = new Set(['pong', 'terminalOutput', 'sdkGrantState', 'shuttingDown']);
+export class PlatformConnection {
+    ws = null;
+    socketEpoch = 0;
+    reconnectTimeout = null;
+    reconnectPolicy = new ReconnectPolicy();
+    isIntentionallyClosed = false;
+    superseded = false;
+    credentialsWatch = null;
+    presentedToken = null;
+    workingDirectory;
+    platformUrl;
+    callbacks;
+    connectionId = null;
+    isConnected = false;
+    heartbeat;
+    protocolUpgradeRequired = false;
+    envelopeNegotiated = false;
+    spaceVisibility;
+    e2ee;
+    startedAt;
+    tokens;
+    outboundQueue = [];
+    outboundDropped = 0;
+    browserFrameRefusalWarned = false;
+    browserFrameRefusals = 0;
+    constructor(workingDirectory, callbacks = {}, platformUrl) {
+        this.workingDirectory = workingDirectory;
+        this.platformUrl = platformUrl || DEFAULT_PLATFORM_URL;
+        this.callbacks = callbacks;
+        this.startedAt = new Date().toISOString();
+        this.tokens = new TokenLifecycle({
+            platformUrl: this.platformUrl,
+            send: (msg) => this.send(msg),
+            getConnectionId: () => this.connectionId,
+        });
+        this.e2ee = new E2eeContentCodec({
+            orchestraKey: getClientId(),
+            getVisibility: () => this.spaceVisibility,
+            sendControlEnvelope: (envelope) => this.sendEnvelopeRaw(envelope),
+        });
+        this.heartbeat = new HeartbeatMonitor({
+            intervalMs: HEARTBEAT_INTERVAL_MS,
+            maxMissed: MAX_MISSED_PONGS,
+            sendPing: () => this.sendPing(),
+            onDead: (missed) => this.onHeartbeatDead(missed),
+        });
+    }
+    sendPing() {
+        if (!this.ws || !this.isConnected)
+            return;
+        try {
+            this.ws.send(JSON.stringify({ type: 'ping' }));
+        }
+        catch {
+        }
+    }
+    onHeartbeatDead(missed) {
+        const ws = this.ws;
+        if (!ws)
+            return;
+        console.log(`[Platform] ${missed} pings unanswered — forcing reconnect`);
+        this.forceClose(ws, this.socketEpoch, HEARTBEAT_TIMEOUT_CLOSE_CODE, 'heartbeat_timeout');
+    }
+    connect() {
+        if (this.superseded)
+            return;
+        this.isIntentionallyClosed = false;
+        this.protocolUpgradeRequired = false;
+        this.envelopeNegotiated = false;
+        this.spaceVisibility = undefined;
+        this.e2ee.onSocketReset();
+        this.browserFrameRefusalWarned = false;
+        this.browserFrameRefusals = 0;
+        const authToken = getCredentials()?.token;
+        if (!authToken) {
+            if (!this.credentialsWatch) {
+                console.error('\n❌ Not logged in. Run `minion login` first — this server connects as soon as you do.\n');
+                this.callbacks.onError?.('Not logged in - run `minion login` first');
+            }
+            this.awaitCredentials(null);
+            return;
+        }
+        this.stopCredentialsWatch();
+        this.presentedToken = authToken;
+        this.detachSocket();
+        const epoch = ++this.socketEpoch;
+        const wsUrl = this.buildConnectionUrl();
+        let ws;
+        try {
+            ws = new WebSocketImpl(wsUrl);
+        }
+        catch (err) {
+            console.error('Failed to create WebSocket connection:', err);
+            captureException(err instanceof Error ? err : new Error(String(err)), { context: 'platform.connect' });
+            this.callbacks.onError?.('Failed to connect to platform');
+            this.scheduleReconnect();
+            return;
+        }
+        this.ws = ws;
+        const connectionTimeout = this.startConnectionTimeout(ws, epoch);
+        this.attachSocketHandlers(ws, authToken, connectionTimeout, epoch);
+        this.tokens.maybeVerifyInParallel();
+    }
+    buildConnectionUrl() {
+        const params = new URLSearchParams({
+            name: basename(this.workingDirectory),
+            workingDirectory: this.workingDirectory,
+            machineHostname: hostname(),
+            clientId: getClientId(),
+            machineId: getMachineIdentifier(),
+            nodeVersion: process.version,
+            osType: type().toLowerCase(),
+            cpuArch: arch(),
+            cliVersion: CLI_VERSION,
+            capabilities: JSON.stringify({
+                ...E2EE_CAPABILITIES,
+                fileTransfer: FILE_TRANSFER_CAPABILITY,
+                maxUploadBytes: getMaxUploadBytes(),
+            }),
+            startedAt: this.startedAt,
+            protocolVersion: String(PROTOCOL_VERSION),
+            environment: resolveCliEnvironment(),
+        });
+        return `${this.platformUrl.replace(/^http/, 'ws')}/ws/client?${params}`;
+    }
+    startConnectionTimeout(ws, epoch) {
+        return setTimeout(() => {
+            if (epoch !== this.socketEpoch)
+                return;
+            const state = ws.readyState;
+            if (state === WebSocketImpl.CONNECTING || state === undefined) {
+                console.error('\n❌ Connection timeout: the relay did not answer the handshake — retrying.\n');
+                this.callbacks.onError?.('Connection timeout - retrying');
+                this.forceClose(ws, epoch, DIAL_TIMEOUT_CLOSE_CODE, 'dial_timeout');
+            }
+        }, CONNECT_TIMEOUT_MS);
+    }
+    attachSocketHandlers(ws, authToken, connectionTimeout, epoch) {
+        let closeSettled = false;
+        const settleClose = (event) => {
+            if (closeSettled)
+                return;
+            closeSettled = true;
+            clearTimeout(connectionTimeout);
+            if (epoch !== this.socketEpoch) {
+                console.log(`[Platform] Ignoring close on a retired socket (code ${event.code})`);
+                return;
+            }
+            this.handleSocketClose(event);
+        };
+        ws.onopen = () => {
+            if (epoch !== this.socketEpoch) {
+                try {
+                    ws.close();
+                }
+                catch {   }
+                return;
+            }
+            clearTimeout(connectionTimeout);
+            ws.send(JSON.stringify({ type: 'auth', token: authToken }));
+            this.tokens.maybeRefresh();
+            this.tokens.startPeriodicCheck();
+            trackEvent(AnalyticsEvents.PLATFORM_CONNECTED);
+        };
+        ws.onmessage = (event) => {
+            if (epoch !== this.socketEpoch)
+                return;
+            try {
+                this.handleMessage(JSON.parse(event.data.toString()));
+            }
+            catch (err) {
+                console.error('Failed to parse platform message:', err);
+            }
+        };
+        ws.onclose = (event) => settleClose(event);
+        ws.onerror = () => {
+            clearTimeout(connectionTimeout);
+            setTimeout(() => {
+                settleClose({ code: 1012, reason: 'handshake failed' });
+            }, HANDSHAKE_ERROR_CLOSE_GRACE_MS);
+        };
+        const wsWithEmitter = ws;
+        if (typeof wsWithEmitter.on === 'function') {
+            wsWithEmitter.on('unexpected-response', (...args) => {
+                if (epoch !== this.socketEpoch)
+                    return;
+                const response = args[1];
+                if (response?.statusCode === 426) {
+                    this.protocolUpgradeRequired = true;
+                }
+            });
+        }
+    }
+    detachSocket() {
+        const ws = this.ws;
+        if (!ws)
+            return;
+        this.ws = null;
+        try {
+            ws.onopen = null;
+            ws.onmessage = null;
+            ws.onclose = null;
+            ws.onerror = null;
+        }
+        catch {   }
+        try {
+            if (ws.readyState === WebSocketImpl.CONNECTING || ws.readyState === WebSocketImpl.OPEN) {
+                ws.close();
+            }
+        }
+        catch {   }
+    }
+    forceClose(ws, epoch, code, reason) {
+        if (epoch !== this.socketEpoch)
+            return;
+        this.socketEpoch++;
+        this.ws = null;
+        try {
+            ws.onopen = null;
+            ws.onmessage = null;
+            ws.onclose = null;
+            ws.onerror = null;
+        }
+        catch {   }
+        const terminate = ws.terminate;
+        try {
+            if (typeof terminate === 'function')
+                terminate.call(ws);
+            else
+                ws.close();
+        }
+        catch {   }
+        this.handleSocketClose({ code, reason });
+    }
+    handleSocketClose(event) {
+        this.heartbeat.stop();
+        this.tokens.stopPeriodicCheck();
+        this.isConnected = false;
+        this.reconnectPolicy.noteDisconnected();
+        if (this.isIntentionallyClosed)
+            return;
+        const disposition = classifyClose(event.code, event.reason, {
+            protocolUpgradeRequired: this.protocolUpgradeRequired,
+        });
+        switch (disposition) {
+            case 'protocol_too_old':
+                this.handleProtocolUpgradeRequired();
+                return;
+            case 'superseded':
+                this.handleSuperseded(event);
+                return;
+            case 'auth_failed':
+                console.error('\n❌ Authentication failed. Your device token may be invalid or expired.');
+                console.error('   Run `minion login --force` to re-authenticate — this server reconnects as soon as you do.\n');
+                this.tokens.notifyAuthExpired();
+                this.callbacks.onError?.('Authentication failed - run `minion login --force`');
+                this.awaitCredentials(this.presentedToken);
+                return;
+            default:
+                console.log(`Disconnected (code ${event.code}${event.reason ? `: ${event.reason}` : ''}, attempt ${this.reconnectPolicy.attempt + 1}), reconnecting...`);
+                this.callbacks.onDisconnected?.();
+                trackEvent(AnalyticsEvents.PLATFORM_DISCONNECTED);
+                this.scheduleReconnect();
+        }
+    }
+    handleSuperseded(event) {
+        this.superseded = true;
+        this.connectionId = null;
+        this.stopCredentialsWatch();
+        console.error('\n❌ Another minion instance has taken over this Space (a newer `minion` was started in this directory).\n' +
+            '   This instance is shutting down; the new one is serving the Space.\n');
+        this.callbacks.onDisconnected?.();
+        trackEvent(AnalyticsEvents.PLATFORM_DISCONNECTED);
+        this.callbacks.onSuperseded?.({ reason: event.reason || 'superseded' });
+    }
+    handleProtocolUpgradeRequired() {
+        const message = 'Minionry CLI is out of date for this orchestra. Run `minion` again to upgrade and reconnect.';
+        console.error(`\n❌ ${message}\n`);
+        this.callbacks.onError?.(message);
+        this.callbacks.onDisconnected?.();
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+        }
+        this.reconnectTimeout = setTimeout(() => {
+            this.reconnectTimeout = null;
+            this.connect();
+        }, PROTOCOL_UPGRADE_RECONNECT_DELAY_MS);
+    }
+    handleMessage(message) {
+        this.heartbeat.noteInbound();
+        if (isV1Envelope(message)) {
+            if (message.enc !== false) {
+                this.e2ee.handleSealedInbound(message, (legacy) => {
+                    this.callbacks.onRelayedMessage?.(legacy);
+                });
+                return;
+            }
+            message = unwrapEnvelopeV1(message);
+        }
+        switch (message.type) {
+            case 'paired': {
+                this.isConnected = true;
+                this.reconnectPolicy.notePaired();
+                this.connectionId = message.connectionId;
+                this.envelopeNegotiated = readPairedEnvelopeAck(message);
+                const e2ee = message.e2ee;
+                this.spaceVisibility =
+                    e2ee && typeof e2ee.visibility === 'string' ? e2ee.visibility : undefined;
+                replaceFileShareRegistry(message.fileShares, this.workingDirectory);
+                this.heartbeat.start();
+                this.callbacks.onConnected?.(message.connectionId);
+                break;
+            }
+            case 'web_connected':
+                this.callbacks.onWebConnected?.();
+                trackEvent(AnalyticsEvents.WEB_CLIENT_CONNECTED);
+                this.flushOutboundQueue();
+                break;
+            case 'web_disconnected':
+                this.callbacks.onWebDisconnected?.();
+                trackEvent(AnalyticsEvents.WEB_CLIENT_DISCONNECTED);
+                break;
+            case 'web_viewer_connected':
+                this.handleViewerConnected(message);
+                break;
+            case 'web_viewer_disconnected':
+                if (typeof message.viewerId === 'string') {
+                    this.e2ee.onViewerDisconnected(message.viewerId);
+                    dropGroupKeyWrapContext(getClientId(), message.viewerId);
+                    browserTrace('viewer.disconnected', `viewer=${message.viewerId.slice(0, 8)} ${this.describeSealingInputs()}`);
+                    this.callbacks.onViewerDisconnected?.(message.viewerId);
+                }
+                break;
+            case 'ping':
+                this.send({ type: 'pong' });
+                break;
+            case 'pong':
+                break;
+            case 'e2ee_key_request':
+                void handleE2eeKeyRequest(message, {
+                    orchestraKey: getClientId(),
+                    visibility: this.spaceVisibility,
+                    sendEnvelope: (envelope) => this.sendEnvelopeRaw(envelope),
+                }).then(() => {
+                    this.e2ee.onKeyRequestSettled(message);
+                    browserTrace('viewer.keyRequest', `viewer=${typeof message._viewer === 'string' ? message._viewer.slice(0, 8) : '-'} ${this.describeSealingInputs()}`);
+                });
+                break;
+            case 'e2ee_membership':
+                if (message.change === 'visibility_changed' && typeof message.visibility === 'string') {
+                    this.spaceVisibility = message.visibility;
+                }
+                void handleE2eeMembershipChange(message, {
+                    orchestraKey: getClientId(),
+                    visibility: this.spaceVisibility,
+                    sendEnvelope: (envelope) => this.sendEnvelopeRaw(envelope),
+                }).then(() => this.e2ee.onGroupKeyRotated());
+                break;
+            case 'fileTransferRequest':
+                this.callbacks.onFileTransferRequest?.(message);
+                break;
+            case 'fileShareSync':
+                applyFileShareSync(message, this.workingDirectory);
+                break;
+            default:
+                this.e2ee.dispatchInboundContent(message, (legacy) => {
+                    this.callbacks.onRelayedMessage?.(legacy);
+                });
+                break;
+        }
+    }
+    handleViewerConnected(message) {
+        if (typeof message.viewerId !== 'string')
+            return;
+        if (message.isFileShare !== true) {
+            this.e2ee.onViewerConnected(message.viewerId, message);
+        }
+        browserTrace('viewer.connected', `viewer=${message.viewerId.slice(0, 8)} fileShare=${message.isFileShare === true} advertisedE2ee=${JSON.stringify(message.e2ee ?? null)} ${this.describeSealingInputs()}`);
+        this.callbacks.onViewerConnected?.(message.viewerId);
+    }
+    sendEnvelopeRaw(envelope) {
+        if (this.ws && this.ws.readyState === WebSocketImpl.OPEN) {
+            this.ws.send(JSON.stringify(envelope));
+        }
+    }
+    awaitCredentials(rejectedToken) {
+        if (this.credentialsWatch)
+            return;
+        const timer = setInterval(() => {
+            if (this.isIntentionallyClosed || this.superseded) {
+                this.stopCredentialsWatch();
+                return;
+            }
+            const token = getCredentials()?.token;
+            if (!token || token === rejectedToken)
+                return;
+            this.stopCredentialsWatch();
+            console.log('[Platform] New credentials found — connecting');
+            this.connect();
+        }, CREDENTIALS_POLL_MS);
+        timer.unref();
+        this.credentialsWatch = timer;
+    }
+    stopCredentialsWatch() {
+        if (this.credentialsWatch) {
+            clearInterval(this.credentialsWatch);
+            this.credentialsWatch = null;
+        }
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimeout)
+            return;
+        if (this.superseded)
+            return;
+        const delay = this.reconnectPolicy.nextDelayMs();
+        this.reconnectTimeout = setTimeout(() => {
+            this.reconnectTimeout = null;
+            this.connect();
+        }, delay);
+    }
+    send(message) {
+        if (this.refuseCleartextBrowserFrame(message))
+            return;
+        if (!this.ws || this.ws.readyState !== WebSocketImpl.OPEN) {
+            this.queueWhileDisconnected(message);
+            return;
+        }
+        if (!this.envelopeNegotiated) {
+            this.writeFrame(JSON.stringify(message), message);
+            return;
+        }
+        this.e2ee.sendOutbound(encodeForRelay(message), (frame) => {
+            if (this.ws && this.ws.readyState === WebSocketImpl.OPEN) {
+                this.writeFrame(frame, message);
+            }
+        });
+    }
+    refuseCleartextBrowserFrame(message) {
+        const record = message;
+        const type = record?.type;
+        if (typeof type !== 'string' || !mustRefuseWhenCleartext(type))
+            return false;
+        if (this.isSealingContent()) {
+            if (this.browserFrameRefusals > 0) {
+                browserTrace.info('contentGate.resumed', `type=${type} after ${this.browserFrameRefusals} refused frame(s)`);
+                this.browserFrameRefusals = 0;
+            }
+            this.browserFrameRefusalWarned = false;
+            return false;
+        }
+        this.browserFrameRefusals++;
+        const sealing = this.describeSealingInputs();
+        if (!this.browserFrameRefusalWarned) {
+            this.browserFrameRefusalWarned = true;
+            console.warn(`[Platform] Refusing outbound browser content frame(s) — E2EE sealing is inactive (public Space or a downgraded session); further refusals muted until sealing resumes (first=${type} ${sealing})`);
+        }
+        browserTrace('contentGate.refused', `type=${type} n=${this.browserFrameRefusals} ${sealing}`);
+        this.sendBrowserFrameRefusalNotice(type, record?.tabId, record?._target);
+        return true;
+    }
+    describeSealingInputs() {
+        const d = this.e2ee.getDiagnostics();
+        return `envelope=${this.envelopeNegotiated} visibility=${this.spaceVisibility ?? 'unknown'} key=${d.keyAvailable} capableViewers=${d.capableViewers}/${d.viewers}`;
+    }
+    sendBrowserFrameRefusalNotice(type, tabId, target) {
+        if (!this.ws || this.ws.readyState !== WebSocketImpl.OPEN)
+            return;
+        const notice = { ...buildE2eeRequiredBrowserError(type) };
+        if (typeof tabId === 'string')
+            notice.tabId = tabId;
+        if (typeof target === 'string')
+            notice._target = target;
+        try {
+            this.ws.send(JSON.stringify(notice));
+        }
+        catch {
+        }
+    }
+    writeFrame(frame, original) {
+        const bytes = Buffer.byteLength(frame, 'utf8');
+        if (bytes <= MAX_OUTBOUND_FRAME_BYTES) {
+            this.ws?.send(frame);
+            return;
+        }
+        const source = original;
+        const type = typeof source?.type === 'string' ? source.type : 'unknown';
+        console.error(`[Platform] Refusing oversized outbound frame type=${type} bytes=${bytes} (cap ${MAX_OUTBOUND_FRAME_BYTES}) — sending it would drop the relay connection`);
+        captureException(new Error(`Oversized outbound relay frame: ${type} (${bytes} bytes)`), {
+            context: 'platform.writeFrame',
+        });
+        this.sendOversizeNotice(type, source?.tabId);
+    }
+    sendOversizeNotice(type, tabId) {
+        if (!this.ws || this.ws.readyState !== WebSocketImpl.OPEN)
+            return;
+        const limitMb = Math.floor(MAX_OUTBOUND_FRAME_BYTES / (1024 * 1024));
+        const notice = {
+            type: 'error',
+            data: {
+                message: `Response too large to send over the relay (${type} exceeds the ${limitMb} MB frame limit). Try a narrower request, or clear this session's history.`,
+            },
+        };
+        if (typeof tabId === 'string')
+            notice.tabId = tabId;
+        try {
+            this.ws.send(JSON.stringify(notice));
+        }
+        catch {
+        }
+    }
+    queueWhileDisconnected(message) {
+        const frame = message;
+        const type = typeof frame?.type === 'string' ? frame.type : undefined;
+        if (type === undefined || typeof frame?.seq === 'number' || NEVER_QUEUED_TYPES.has(type)) {
+            return;
+        }
+        if (this.outboundQueue.length >= OUTBOUND_QUEUE_LIMIT) {
+            this.outboundQueue.shift();
+            this.outboundDropped++;
+        }
+        this.outboundQueue.push(message);
+    }
+    flushOutboundQueue() {
+        if (this.outboundDropped > 0) {
+            console.log(`[Platform] ${this.outboundDropped} queued outbound frame${this.outboundDropped === 1 ? '' : 's'} dropped over the ${OUTBOUND_QUEUE_LIMIT}-frame cap`);
+            this.outboundDropped = 0;
+        }
+        if (this.outboundQueue.length === 0)
+            return;
+        const queued = this.outboundQueue;
+        this.outboundQueue = [];
+        console.log(`[Platform] Flushing ${queued.length} outbound message${queued.length === 1 ? '' : 's'} queued during the outage`);
+        for (const message of queued) {
+            this.send(message);
+        }
+    }
+    isEnvelopeNegotiated() {
+        return this.envelopeNegotiated;
+    }
+    isSealingContent() {
+        return this.envelopeNegotiated && this.e2ee.isSealingActive();
+    }
+    whenE2eeIdle() {
+        return this.e2ee.whenIdle();
+    }
+    getE2eeDiagnostics() {
+        return this.e2ee.getDiagnostics();
+    }
+    isConnectedToPlatform() {
+        return this.isConnected && this.ws?.readyState === WebSocketImpl.OPEN;
+    }
+    isSuperseded() {
+        return this.superseded;
+    }
+    getOutboundBufferedAmount() {
+        return this.ws?.bufferedAmount ?? 0;
+    }
+    disconnect() {
+        this.isIntentionallyClosed = true;
+        this.heartbeat.stop();
+        this.tokens.stopPeriodicCheck();
+        this.stopCredentialsWatch();
+        this.outboundQueue = [];
+        this.outboundDropped = 0;
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
+        this.socketEpoch++;
+        this.detachSocket();
+        this.isConnected = false;
+        this.connectionId = null;
+        this.envelopeNegotiated = false;
+    }
+}

package/dist/server/services/runtime-info.js

@@ -0,0 +1,9 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+let currentPort;
+export function setCurrentMinionryPort(port) {
+    currentPort = port;
+}
+export function getCurrentMinionryPort() {
+    return currentPort;
+}