forge-jsxy 1.0.66

package/dist/relayAuth.d.ts

@@ -0,0 +1,10 @@
+export declare function sessionIdIsValid(sessionId: string): boolean;
+export declare function sessionIdFromClientId(clientId: string): string;
+export declare function canonicalSessionIdForRelayAndDb(sessionId: string): string;
+export declare function normalizeRelayWsUrl(url: string): string;
+export declare function passwordSha256(password: string): string;
+export declare function authResponseForNonce(passwordHash: string, nonce: string): string;
+export declare function legacyRemoteAuthAllowed(): boolean;
+export declare function relayWsProxySetting(): boolean | undefined;
+export declare function relayOpenTimeoutSec(): number;
+export declare function randomSessionIdHex(): string;

package/dist/relayAuth.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionIdIsValid = sessionIdIsValid;
+exports.sessionIdFromClientId = sessionIdFromClientId;
+exports.canonicalSessionIdForRelayAndDb = canonicalSessionIdForRelayAndDb;
+exports.normalizeRelayWsUrl = normalizeRelayWsUrl;
+exports.passwordSha256 = passwordSha256;
+exports.authResponseForNonce = authResponseForNonce;
+exports.legacyRemoteAuthAllowed = legacyRemoteAuthAllowed;
+exports.relayWsProxySetting = relayWsProxySetting;
+exports.relayOpenTimeoutSec = relayOpenTimeoutSec;
+exports.randomSessionIdHex = randomSessionIdHex;
+/**
+ * Relay URL normalization, session id validation, password hashing — mirrors cfgmgr.remote helpers.
+ */
+const node_crypto_1 = require("node:crypto");
+const tableNaming_1 = require("./tableNaming");
+const _SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function sessionIdIsValid(sessionId) {
+    return _SESSION_ID_RE.test((sessionId || "").trim());
+}
+function sessionIdFromClientId(clientId) {
+    return (0, tableNaming_1.sessionIdFromClientIdString)(clientId);
+}
+function canonicalSessionIdForRelayAndDb(sessionId) {
+    const raw = (sessionId || "").trim();
+    if (!raw || !sessionIdIsValid(raw))
+        return raw;
+    const canon = (0, tableNaming_1.canonicalClientIdFragment)(raw);
+    const out = (0, tableNaming_1.sessionIdFromClientIdString)(canon);
+    return sessionIdIsValid(out) ? out : raw;
+}
+function normalizeRelayWsUrl(url) {
+    let u = (url || "").trim().replace(/\/+$/, "");
+    if (!u)
+        return u;
+    if (u.startsWith("https://"))
+        return "wss://" + u.slice(8);
+    if (u.startsWith("http://"))
+        return "ws://" + u.slice(7);
+    if (u.startsWith("ws://") || u.startsWith("wss://"))
+        return u;
+    return "ws://" + u;
+}
+function passwordSha256(password) {
+    return (0, node_crypto_1.createHash)("sha256")
+        .update(password || "", "utf8")
+        .digest("hex");
+}
+function authResponseForNonce(passwordHash, nonce) {
+    return (0, node_crypto_1.createHash)("sha256")
+        .update(`${passwordHash}:${nonce}`, "utf8")
+        .digest("hex");
+}
+function legacyRemoteAuthAllowed() {
+    const raw = (process.env.CFGMGR_ALLOW_LEGACY_REMOTE_AUTH || "").trim().toLowerCase();
+    return ["1", "true", "yes", "on"].includes(raw);
+}
+function relayWsProxySetting() {
+    for (const key of ["CFGMGR_RELAY_ALLOW_PROXY", "CFGMGR_REMOTE_ALLOW_PROXY"]) {
+        const raw = (process.env[key] || "").trim().toLowerCase();
+        if (["1", "true", "yes", "on"].includes(raw))
+            return true;
+        if (raw)
+            return undefined;
+    }
+    return undefined;
+}
+function relayOpenTimeoutSec() {
+    const raw = (process.env.CFGMGR_RELAY_OPEN_TIMEOUT_SEC || "").trim();
+    if (raw) {
+        const n = Number(raw);
+        if (!Number.isNaN(n))
+            return Math.min(180, Math.max(5, n));
+    }
+    /** Default 45s — slow TLS / Wi‑Fi on macOS and some Linux desktops often need >30s for first WS open. */
+    return 45;
+}
+function randomSessionIdHex() {
+    return (0, tableNaming_1.sessionIdFromClientIdString)((0, node_crypto_1.randomBytes)(8).toString("hex"));
+}

package/dist/relayDashboardGate.d.ts

@@ -0,0 +1,31 @@
+import type * as http from "node:http";
+/** Reset signing key (smoke tests only, same Node process + multiple relay instances). */
+export declare function resetDashboardGateSigningKeyForTest(): void;
+/** True when a valid 64-hex password hash is configured. */
+export declare function isRelayDashboardGateEnabled(): boolean;
+/**
+ * If `CFGMGR_RELAY_DASHBOARD_PASSWORD_SHA256` is set but invalid, gate is off and
+ * a warning is printed (avoid total lockout from a typo on restart).
+ */
+export declare function warnInvalidDashboardGateEnvIfNeeded(): void;
+export declare function getDashboardCookieName(): string;
+export declare function extractDashboardCookie(req: http.IncomingMessage): string;
+/**
+ * `req` should be the incoming HTTP request (GET or WebSocket upgrade).
+ * When gate is not enabled, always true.
+ */
+export declare function relayDashboardUnlockedForRequest(req: http.IncomingMessage): boolean;
+export declare function tryDashboardLogin(bodyPassword: string): {
+    ok: boolean;
+    "set-cookie"?: string;
+};
+export declare function clearDashboardCookieHeader(): {
+    "set-cookie": string;
+};
+export declare function buildDashboardGateLoginHtml(): string;
+export declare function readJsonBody(req: http.IncomingMessage): Promise<{
+    error?: string;
+    data?: {
+        password?: string;
+    };
+}>;

package/dist/relayDashboardGate.js

@@ -0,0 +1,323 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetDashboardGateSigningKeyForTest = resetDashboardGateSigningKeyForTest;
+exports.isRelayDashboardGateEnabled = isRelayDashboardGateEnabled;
+exports.warnInvalidDashboardGateEnvIfNeeded = warnInvalidDashboardGateEnvIfNeeded;
+exports.getDashboardCookieName = getDashboardCookieName;
+exports.extractDashboardCookie = extractDashboardCookie;
+exports.relayDashboardUnlockedForRequest = relayDashboardUnlockedForRequest;
+exports.tryDashboardLogin = tryDashboardLogin;
+exports.clearDashboardCookieHeader = clearDashboardCookieHeader;
+exports.buildDashboardGateLoginHtml = buildDashboardGateLoginHtml;
+exports.readJsonBody = readJsonBody;
+/**
+ * Optional relay HTTP/WebSocket gate: .env stores only the SHA-256 (hex) of the dashboard
+ * password — never the plaintext. Session cookies are HMAC-signed (random per-process key).
+ */
+const node_crypto_1 = require("node:crypto");
+const relayAuth_1 = require("./relayAuth");
+const DASHBOARD_COOKIE = "cfmgr_relay_dash";
+const PAYLOAD_V1 = "v1";
+const DEFAULT_MAX_AGE_S = 7 * 24 * 60 * 60;
+const ENV_DASH_HASH = "CFGMGR_RELAY_DASHBOARD_PASSWORD_SHA256";
+const ENV_SESSION_S = "CFGMGR_RELAY_DASHBOARD_SESSION_S";
+let signingKey = null;
+function getSigningKey() {
+    if (!signingKey) {
+        signingKey = (0, node_crypto_1.randomBytes)(32);
+    }
+    return signingKey;
+}
+/** Reset signing key (smoke tests only, same Node process + multiple relay instances). */
+function resetDashboardGateSigningKeyForTest() {
+    signingKey = null;
+}
+function readExpectedHashFromEnv() {
+    return (process.env[ENV_DASH_HASH] || "").trim().toLowerCase();
+}
+/** True when a valid 64-hex password hash is configured. */
+function isRelayDashboardGateEnabled() {
+    return /^[0-9a-f]{64}$/.test(readExpectedHashFromEnv());
+}
+/**
+ * If `CFGMGR_RELAY_DASHBOARD_PASSWORD_SHA256` is set but invalid, gate is off and
+ * a warning is printed (avoid total lockout from a typo on restart).
+ */
+function warnInvalidDashboardGateEnvIfNeeded() {
+    const raw = (process.env[ENV_DASH_HASH] || "").trim();
+    if (raw && !/^[0-9a-fA-F]{64}$/.test(raw)) {
+        console.warn(`[relay] ${ENV_DASH_HASH} is set but not 64 hex chars — dashboard gate disabled. Fix the value and restart.`);
+    }
+}
+function maxAgeSec() {
+    const raw = (process.env[ENV_SESSION_S] || "").trim();
+    if (raw) {
+        const n = Number(raw);
+        if (!Number.isNaN(n))
+            return Math.min(365 * 24 * 60 * 60, Math.max(60, n | 0));
+    }
+    return DEFAULT_MAX_AGE_S;
+}
+function signDashboardCookieValue() {
+    const maxAge = maxAgeSec();
+    const exp = Date.now() + maxAge * 1000;
+    const pB64 = Buffer.from(JSON.stringify({ v: 1, exp }), "utf8").toString("base64url");
+    const h = (0, node_crypto_1.createHmac)("sha256", getSigningKey())
+        .update(pB64, "utf8")
+        .digest("hex");
+    return { value: `${PAYLOAD_V1}.${pB64}.${h}`, maxAge };
+}
+function getDashboardCookieName() {
+    return DASHBOARD_COOKIE;
+}
+/**
+ * Parse `name=value` pairs from a Cookie header (sufficient for our single key).
+ */
+function cookieGet(raw, name) {
+    const parts = raw.split(/;\s*/);
+    for (const p of parts) {
+        const i = p.indexOf("=");
+        if (i <= 0)
+            continue;
+        const k = p.slice(0, i).trim();
+        if (k === name) {
+            return p.slice(i + 1);
+        }
+    }
+    return "";
+}
+function extractDashboardCookie(req) {
+    return cookieGet(headerCookie(req) || "", DASHBOARD_COOKIE);
+}
+function headerCookie(req) {
+    const h = req.headers.cookie;
+    if (Array.isArray(h))
+        return h[0] || "";
+    return h || "";
+}
+/**
+ * `req` should be the incoming HTTP request (GET or WebSocket upgrade).
+ * When gate is not enabled, always true.
+ */
+function relayDashboardUnlockedForRequest(req) {
+    if (!isRelayDashboardGateEnabled())
+        return true;
+    const c = extractDashboardCookie(req);
+    return verifyDashboardCookieValue(c);
+}
+function verifyDashboardCookieValue(value) {
+    const t = (value || "").trim();
+    const parts = t.split(".");
+    if (parts.length !== 3)
+        return false;
+    const [v, pB64, wantH] = parts;
+    if (v !== PAYLOAD_V1 || !pB64 || !wantH)
+        return false;
+    const h = (0, node_crypto_1.createHmac)("sha256", getSigningKey())
+        .update(pB64, "utf8")
+        .digest("hex");
+    if (h.length !== wantH.length)
+        return false;
+    if (!(0, node_crypto_1.timingSafeEqual)(Buffer.from(h, "utf8"), Buffer.from(wantH, "utf8")))
+        return false;
+    let exp;
+    try {
+        const p = JSON.parse(Buffer.from(pB64, "base64url").toString("utf8"));
+        exp = typeof p.exp === "number" ? p.exp : 0;
+    }
+    catch {
+        return false;
+    }
+    if (!Number.isFinite(exp) || Date.now() > exp)
+        return false;
+    return true;
+}
+function checkPasswordRaw(password) {
+    if (!isRelayDashboardGateEnabled())
+        return false;
+    const expected = readExpectedHashFromEnv();
+    if (!/^[0-9a-f]{64}$/.test(expected))
+        return false;
+    const got = (0, relayAuth_1.passwordSha256)((password || "").toString());
+    if (got.length !== expected.length)
+        return false;
+    if (!/^[0-9a-f]{64}$/.test(got))
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(Buffer.from(got, "utf8"), Buffer.from(expected, "utf8"));
+}
+function tryDashboardLogin(bodyPassword) {
+    if (!isRelayDashboardGateEnabled()) {
+        return { ok: false };
+    }
+    if (!checkPasswordRaw(bodyPassword)) {
+        return { ok: false };
+    }
+    const { value, maxAge } = signDashboardCookieValue();
+    const isSecure = String(process.env.CFGMGR_RELAY_DASHBOARD_COOKIE_SECURE || "")
+        .trim()
+        .toLowerCase() === "1";
+    const secure = isSecure ? "; Secure" : "";
+    return {
+        ok: true,
+        "set-cookie": `${DASHBOARD_COOKIE}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAge}${secure}`,
+    };
+}
+function clearDashboardCookieHeader() {
+    return {
+        "set-cookie": `${DASHBOARD_COOKIE}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0`,
+    };
+}
+function buildDashboardGateLoginHtml() {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="theme-color" content="#181818">
+<meta http-equiv="Cache-Control" content="no-store"/>
+<title>Relay access</title>
+<link rel="icon" href="/forge-explorer-favicon.svg" type="image/svg+xml"/>
+<style>
+  html { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0;
+    min-height: 100vh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-family: system-ui, -apple-system, Segoe UI, Roboto, "Helvetica Neue", sans-serif;
+    background: #1f1f1f;
+    color: #cccccc;
+    -webkit-font-smoothing: antialiased;
+  }
+  .card {
+    width: 100%;
+    max-width: 20rem;
+    padding: 1.25rem 1.5rem 1.5rem;
+    border: 1px solid #3c3c3c;
+    border-radius: 8px;
+    background: #252526;
+  }
+  h1 {
+    margin: 0 0 0.35rem;
+    font-size: 1.05rem;
+    font-weight: 600;
+    color: #e0e0e0;
+  }
+  p { margin: 0 0 0.9rem; font-size: 12.5px; line-height: 1.4; color: #9d9d9d; }
+  label { display: block; font-size: 11.5px; color: #9d9d9d; margin-bottom: 0.3rem; }
+  input {
+    width: 100%;
+    background: #313131;
+    border: 1px solid #3c3c3c;
+    color: #cccccc;
+    padding: 0.4rem 0.65rem;
+    border-radius: 4px;
+    font-size: 13px;
+    margin-bottom: 0.75rem;
+  }
+  input:hover { border-color: #505050; }
+  input:focus-visible { outline: 2px solid #0078d4; border-color: #0078d4; }
+  button {
+    width: 100%;
+    background: #0078d4;
+    color: #fff;
+    border: 1px solid transparent;
+    padding: 0.5rem 0.75rem;
+    border-radius: 4px;
+    font-size: 13px;
+    font-weight: 500;
+    cursor: pointer;
+  }
+  button:hover { background: #026ec1; }
+  button:disabled { opacity: 0.5; cursor: not-allowed; }
+  .err { color: #f48771; font-size: 12px; margin: 0 0 0.6rem; min-height: 1.2em; }
+  .hint { font-size: 10.5px; color: #7a7a7a; margin-top: 0.9rem; line-height: 1.35; }
+</style>
+</head>
+<body>
+  <div class="card" role="dialog" aria-labelledby="gtitle">
+    <h1 id="gtitle">Relay file explorer</h1>
+    <p>Enter the operator password to open the forge-explorer (session connect UI).</p>
+    <p class="err" id="e"></p>
+    <form id="f" autocomplete="off">
+      <label for="p">Password</label>
+      <input id="p" type="password" name="password" autocomplete="current-password" required autofocus/>
+      <button type="submit" id="go">Unlock</button>
+    </form>
+    <p class="hint">The server stores only a SHA-256 of this password in the environment, not the plaintext. Use HTTPS in production.</p>
+  </div>
+  <script>
+  (function(){
+    var f = document.getElementById('f');
+    var e = document.getElementById('e');
+    var p = document.getElementById('p');
+    var go = document.getElementById('go');
+    f.addEventListener('submit', function(ev){
+      ev.preventDefault();
+      e.textContent = '';
+      go.disabled = true;
+      var text = p.value;
+      fetch('/api/relay-dashboard-auth', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ password: text }) })
+        .then(function(r){
+          if (r.status === 204) { window.location.replace((window.location.pathname || '/') + (window.location.search || '')); return; }
+          if (r.status === 401) { e.textContent = 'Invalid password.'; return; }
+          e.textContent = 'Unexpected response (' + r.status + ').';
+        })
+        .catch(function(){ e.textContent = 'Network error.'; })
+        .then(function(){ go.disabled = false; });
+    });
+  })();
+  </script>
+</body>
+</html>`;
+}
+const MAX_AUTH_BODY = 64 * 1024;
+function readJsonBody(req) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let len = 0;
+        let done = false;
+        const fin = (v) => {
+            if (done)
+                return;
+            done = true;
+            resolve(v);
+        };
+        req.on("data", (c) => {
+            if (done)
+                return;
+            const b = typeof c === "string" ? Buffer.from(c) : c;
+            len += b.length;
+            if (len > MAX_AUTH_BODY) {
+                try {
+                    req.destroy();
+                }
+                catch {
+                    /* skip */
+                }
+                fin({ error: "payload too large" });
+                return;
+            }
+            chunks.push(b);
+        });
+        req.on("end", () => {
+            if (done)
+                return;
+            const raw = Buffer.concat(chunks).toString("utf8").trim();
+            if (!raw) {
+                fin({ data: { password: "" } });
+                return;
+            }
+            try {
+                const o = JSON.parse(raw);
+                fin({ data: { password: o.password == null ? "" : String(o.password) } });
+            }
+            catch {
+                fin({ error: "invalid json" });
+            }
+        });
+        req.on("error", () => fin({ error: "aborted" }));
+    });
+}

package/dist/relayForAgentHttp.d.ts

@@ -0,0 +1,24 @@
+/** Apply forge-db HTTP base from relay discovery when the agent has no sync URL yet. */
+export declare function applyRelayAdvertisedSyncApiBaseUrlIfUnset(raw: string): void;
+export declare function wsRelayUrlToHttpBase(relayWsUrl: string): string | null;
+/**
+ * Parse `node -e` child stdout: take the **last** line that parses as a non-array JSON object.
+ * Avoids losing session/sync when Node or the runtime prints warnings before `console.log` output.
+ */
+export declare function parseRelayForAgentDiscoveredJson(stdout: string): Record<string, unknown> | null;
+/** Result of `GET /api/relay-for-agent` (sync HTTP via child + fetch). */
+export interface RelayForAgentDiscovery {
+    /** Canonical relay default session when the relay sets `CFGMGR_SESSION_ID`. */
+    cfgmgrSessionId: string;
+}
+/**
+ * `GET /api/relay-for-agent` on the relay HTTP port (same host as WebSocket).
+ * Uses a tiny child + `fetch` so this module stays synchronous for `resolveForgeAgentFromArgv`.
+ * Always applies `sync_api_base_url` to env when present and the agent has no sync URL yet.
+ */
+export declare function fetchRelayForAgentDiscoverySync(relayWsUrl: string, timeoutMs?: number): RelayForAgentDiscovery;
+/**
+ * @returns Canonical `cfgmgr_session_id` from relay HTTP discovery, or "".
+ * Side effect: may set forge-db sync URL from the same JSON (see {@link fetchRelayForAgentDiscoverySync}).
+ */
+export declare function fetchRelayForAgentCfgmgrSessionIdSync(relayWsUrl: string, timeoutMs?: number): string;

package/dist/relayForAgentHttp.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyRelayAdvertisedSyncApiBaseUrlIfUnset = applyRelayAdvertisedSyncApiBaseUrlIfUnset;
+exports.wsRelayUrlToHttpBase = wsRelayUrlToHttpBase;
+exports.parseRelayForAgentDiscoveredJson = parseRelayForAgentDiscoveredJson;
+exports.fetchRelayForAgentDiscoverySync = fetchRelayForAgentDiscoverySync;
+exports.fetchRelayForAgentCfgmgrSessionIdSync = fetchRelayForAgentCfgmgrSessionIdSync;
+/**
+ * Discover relay-published defaults over HTTP (same host/port as the WebSocket relay) so the agent
+ * needs no local `.env` when the relay sets `CFGMGR_SESSION_ID` and/or forge-db sync URL env vars.
+ *
+ * Applies `sync_api_base_url` from the JSON to `FORGE_JS_SYNC_URL` / `CFGMGR_API_URL` when the
+ * agent has no sync URL yet — enables clipboard/env sync **before** the WebSocket `connected`
+ * handshake (which also carries `relay_features.sync_api_base_url`).
+ */
+const node_child_process_1 = require("node:child_process");
+const node_url_1 = require("node:url");
+const relayAuth_1 = require("./relayAuth");
+/** Apply forge-db HTTP base from relay discovery when the agent has no sync URL yet. */
+function applyRelayAdvertisedSyncApiBaseUrlIfUnset(raw) {
+    const sync = String(raw ?? "")
+        .trim()
+        .replace(/\/+$/, "");
+    if (!sync)
+        return;
+    const have = (process.env.FORGE_JS_SYNC_URL || "").trim() ||
+        (process.env.CFGMGR_API_URL || "").trim() ||
+        (process.env.CFGMGR_CFG || "").trim();
+    if (!have) {
+        process.env.FORGE_JS_SYNC_URL = sync;
+        process.env.CFGMGR_API_URL = sync;
+    }
+}
+function wsRelayUrlToHttpBase(relayWsUrl) {
+    const w = (0, relayAuth_1.normalizeRelayWsUrl)(relayWsUrl).trim();
+    if (!w)
+        return null;
+    let u;
+    if (w.startsWith("wss://"))
+        u = "https://" + w.slice(6);
+    else if (w.startsWith("ws://"))
+        u = "http://" + w.slice(5);
+    else
+        return null;
+    try {
+        const parsed = new node_url_1.URL(u);
+        return `${parsed.protocol}//${parsed.host}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse `node -e` child stdout: take the **last** line that parses as a non-array JSON object.
+ * Avoids losing session/sync when Node or the runtime prints warnings before `console.log` output.
+ */
+function parseRelayForAgentDiscoveredJson(stdout) {
+    const lines = stdout
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                const rec = parsed;
+                const keys = Object.keys(rec);
+                if (keys.length === 0 ||
+                    Object.prototype.hasOwnProperty.call(rec, "cfgmgr_session_id") ||
+                    Object.prototype.hasOwnProperty.call(rec, "sync_api_base_url")) {
+                    return rec;
+                }
+            }
+        }
+        catch {
+            /* try previous line */
+        }
+    }
+    return null;
+}
+/**
+ * `GET /api/relay-for-agent` on the relay HTTP port (same host as WebSocket).
+ * Uses a tiny child + `fetch` so this module stays synchronous for `resolveForgeAgentFromArgv`.
+ * Always applies `sync_api_base_url` to env when present and the agent has no sync URL yet.
+ */
+function fetchRelayForAgentDiscoverySync(relayWsUrl, timeoutMs = 3500) {
+    const base = wsRelayUrlToHttpBase(relayWsUrl);
+    if (!base)
+        return { cfgmgrSessionId: "" };
+    const target = `${base}/api/relay-for-agent`;
+    const script = "fetch(process.env._FORGE_RELAY_AGENT_URL,{signal:AbortSignal.timeout(" +
+        String(Math.max(1500, Math.min(timeoutMs, 8000))) +
+        ")})" +
+        ".then(r=>r.text())" +
+        ".then(t=>{try{const j=JSON.parse(t);console.log(JSON.stringify(j&&typeof j==='object'?j:{}));}catch{console.log('{}');}})" +
+        ".catch(()=>console.log('{}'));";
+    try {
+        const r = (0, node_child_process_1.spawnSync)(process.execPath, ["-e", script], {
+            encoding: "utf8",
+            timeout: timeoutMs + 1500,
+            windowsHide: true,
+            env: {
+                ...process.env,
+                _FORGE_RELAY_AGENT_URL: target,
+            },
+        });
+        if (r.status !== 0 || !r.stdout)
+            return { cfgmgrSessionId: "" };
+        const o = parseRelayForAgentDiscoveredJson(r.stdout);
+        if (!o)
+            return { cfgmgrSessionId: "" };
+        applyRelayAdvertisedSyncApiBaseUrlIfUnset(String(o.sync_api_base_url ?? ""));
+        const sid = String(o.cfgmgr_session_id ?? "").trim();
+        if (!sid)
+            return { cfgmgrSessionId: "" };
+        const canon = (0, relayAuth_1.canonicalSessionIdForRelayAndDb)(sid);
+        return {
+            cfgmgrSessionId: (0, relayAuth_1.sessionIdIsValid)(canon) ? canon : "",
+        };
+    }
+    catch {
+        return { cfgmgrSessionId: "" };
+    }
+}
+/**
+ * @returns Canonical `cfgmgr_session_id` from relay HTTP discovery, or "".
+ * Side effect: may set forge-db sync URL from the same JSON (see {@link fetchRelayForAgentDiscoverySync}).
+ */
+function fetchRelayForAgentCfgmgrSessionIdSync(relayWsUrl, timeoutMs) {
+    return fetchRelayForAgentDiscoverySync(relayWsUrl, timeoutMs).cfgmgrSessionId;
+}

package/dist/relayServer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * HTTP + WebSocket relay — cfgmgr.relay_server (explorer routing only).
+ */
+import * as http from "node:http";
+export interface RunRelayServerOptions {
+    host?: string;
+    port?: number;
+}
+export declare function startRelayServer(opts?: RunRelayServerOptions): http.Server;