@empir3/empir3-bridge 0.3.21

package/src/pair-claim.ts

@@ -0,0 +1,218 @@
+/**
+ * pair-claim.ts — redeem a PRE-AUTHORIZED Empir3 pairing code on first run.
+ *
+ * The standard pairing flow (server.ts `startPairPoll`) has the BRIDGE create a
+ * session and the user approve it in a browser at `/connect-bridge?code=`. This
+ * module is the inverse, used by the install one-liner:
+ *
+ *     Empir3Setup.exe --pair <code>
+ *
+ * In that flow the user is ALREADY logged into Empir3 (they got the install link
+ * from Vincent in chat), so Empir3 pre-authorizes a pairing session for them and
+ * bakes the `code` into the command. The bridge just CLAIMS it on first boot —
+ * no second login, no browser round-trip.
+ *
+ * Deliberately self-contained:
+ *   - It runs in the bootstrapper / first-run context BEFORE the daemon
+ *     (server.ts) is listening. Importing server.ts would boot the whole bridge
+ *     and bind ports, so this module re-implements the small slice it needs.
+ *   - It writes `bridge-auth.json` in the EXACT shape and location server.ts
+ *     reads (see server.ts `saveBridgeAuth` / `AUTH_FILE` / `BridgeAuth`). Keep
+ *     these in sync if the auth schema changes.
+ *
+ * Contract with Empir3 (must match `startPairPoll` in server.ts):
+ *   GET <server>/api/auth/pairing-sessions/<code>
+ *     200 { status: 'pending' }                         → keep polling
+ *     200 { status: 'claimed', token, userId, email,
+ *           name, role, channelId, serverUrl, wsUrl }   → write auth, done
+ *     404                                                → expired / unknown code
+ *
+ * Never hangs the install: bounded poll, then a graceful give-up so first-run
+ * falls through to the normal (interactive) pairing path.
+ */
+
+import { mkdirSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { request as httpRequest } from 'http';
+import { request as httpsRequest } from 'https';
+
+const DEFAULT_EMPIR3_SERVER = 'https://app.empir3.com';
+const LOCAL_DEV_EMPIR3_SERVER = 'http://localhost:3005';
+
+// Mirror server.ts: %APPDATA%\Empir3 on Windows, ~/.empir3/Empir3 elsewhere.
+const SETTINGS_DIR = join(process.env.APPDATA || join(homedir(), '.empir3'), 'Empir3');
+const AUTH_FILE = join(SETTINGS_DIR, 'bridge-auth.json');
+
+export interface ClaimResult {
+  ok: boolean;
+  status: 'claimed' | 'expired' | 'timed_out' | 'invalid' | 'error';
+  reason?: string;
+  user?: { id?: string; email?: string };
+  authFile?: string;
+}
+
+type ClaimOptions = {
+  serverUrl?: string;
+  tries?: number;
+  intervalMs?: number;
+  log?: (msg: string) => void;
+};
+
+// ─── server-url helpers (minimal mirror of server.ts) ───────────────────────
+
+function normalizeServer(input?: string | null): string {
+  const raw = String(input || '').trim();
+  if (!raw) return DEFAULT_EMPIR3_SERVER;
+  const withProtocol = /^https?:\/\//i.test(raw)
+    ? raw
+    : (/^(localhost|127\.0\.0\.1|\[::1\])(?::|\/|$)/i.test(raw) ? `http://${raw}` : `https://${raw}`);
+  try {
+    const u = new URL(withProtocol);
+    u.pathname = u.pathname.replace(/\/+$/, '');
+    if (u.pathname === '/') u.pathname = '';
+    u.search = '';
+    u.hash = '';
+    return u.toString().replace(/\/+$/, '');
+  } catch {
+    return DEFAULT_EMPIR3_SERVER;
+  }
+}
+
+function classifyServer(serverUrl?: string | null): 'production' | 'local-dev' | 'custom' {
+  const normalized = normalizeServer(serverUrl);
+  let host = '';
+  try { host = new URL(normalized).host.toLowerCase(); } catch { /* keep '' */ }
+  if (normalized === DEFAULT_EMPIR3_SERVER || host === 'app.empir3.com') return 'production';
+  if (normalized === LOCAL_DEV_EMPIR3_SERVER || host === 'localhost:3005' || host === '127.0.0.1:3005') return 'local-dev';
+  return 'custom';
+}
+
+function defaultWsUrl(serverUrl: string): string {
+  try {
+    const u = new URL(normalizeServer(serverUrl));
+    u.protocol = u.protocol === 'http:' ? 'ws:' : 'wss:';
+    u.pathname = '/ws';
+    u.search = '';
+    u.hash = '';
+    return u.toString();
+  } catch {
+    return 'wss://app.empir3.com/ws';
+  }
+}
+
+function normalizeWsUrl(wsUrl: string | undefined | null, serverUrl: string): string {
+  const fallback = defaultWsUrl(serverUrl);
+  if (!wsUrl) return fallback;
+  try {
+    const u = new URL(wsUrl);
+    if (u.pathname.replace(/\/+$/, '') === '/relay') return fallback;
+    return u.toString();
+  } catch {
+    return fallback;
+  }
+}
+
+function getJson(urlStr: string, timeoutMs: number): Promise<{ status: number; body: any }> {
+  return new Promise((resolvePromise, reject) => {
+    let u: URL;
+    try { u = new URL(urlStr); } catch (e) { reject(e); return; }
+    const lib = u.protocol === 'https:' ? httpsRequest : httpRequest;
+    const req = lib({
+      hostname: u.hostname,
+      port: u.port || (u.protocol === 'https:' ? 443 : 80),
+      path: u.pathname + (u.search || ''),
+      method: 'GET',
+      headers: { 'User-Agent': 'empir3-bridge-pair', Accept: 'application/json' },
+    }, (response) => {
+      let chunks = '';
+      response.on('data', (c) => { chunks += c; });
+      response.on('end', () => {
+        let parsed: any = null;
+        try { parsed = JSON.parse(chunks); } catch { /* leave null */ }
+        resolvePromise({ status: response.statusCode || 0, body: parsed });
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(timeoutMs, () => req.destroy(new Error('request timed out')));
+    req.end();
+  });
+}
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+/** A pairing code is opaque but should look sane before we put it in a URL. */
+function looksLikeCode(code: string): boolean {
+  return /^[A-Za-z0-9._-]{6,128}$/.test(code);
+}
+
+/**
+ * Claim a pre-authorized pairing code and persist bridge-auth.json.
+ *
+ * Bounded: at most `tries` polls (default 10) spaced `intervalMs` (default
+ * 1500ms) apart — ~15s worst case. A pre-authorized session normally returns
+ * `claimed` on the first poll; the loop only exists to absorb a brief
+ * server-side propagation delay. Returns a structured result; never throws for
+ * an expected outcome (expired / timeout / bad code).
+ */
+export async function claimPairingCode(code: string, opts: ClaimOptions = {}): Promise<ClaimResult> {
+  const log = opts.log || (() => {});
+  const trimmed = String(code || '').trim();
+  if (!looksLikeCode(trimmed)) {
+    return { ok: false, status: 'invalid', reason: 'pairing code missing or malformed' };
+  }
+
+  const serverUrl = normalizeServer(opts.serverUrl || process.env.EMPIR3_SERVER || DEFAULT_EMPIR3_SERVER);
+  const tries = Math.max(1, opts.tries ?? 10);
+  const intervalMs = Math.max(250, opts.intervalMs ?? 1500);
+  const sessionUrl = `${serverUrl}/api/auth/pairing-sessions/${encodeURIComponent(trimmed)}`;
+
+  let lastReason = 'no response';
+  for (let attempt = 1; attempt <= tries; attempt++) {
+    try {
+      const r = await getJson(sessionUrl, 5000);
+
+      if (r.status === 404) {
+        log(`pairing code expired or unknown (404) after ${attempt} attempt(s)`);
+        return { ok: false, status: 'expired', reason: 'code expired or unknown' };
+      }
+
+      const status = r.body?.status;
+
+      if (status === 'claimed' && r.body?.token) {
+        const sUrl = normalizeServer(r.body.serverUrl || serverUrl);
+        const auth = {
+          legacyToken: r.body.token as string,
+          user: {
+            id: r.body.userId,
+            email: r.body.email,
+            name: r.body.name,
+            role: r.body.role,
+          },
+          channelId: r.body.channelId || null,
+          serverUrl: sUrl,
+          wsUrl: normalizeWsUrl(r.body.wsUrl || r.body.relayUrl, sUrl),
+          environment: classifyServer(sUrl),
+        };
+        mkdirSync(SETTINGS_DIR, { recursive: true });
+        writeFileSync(AUTH_FILE, JSON.stringify(auth, null, 2));
+        log(`paired as ${auth.user.email || auth.user.id || 'unknown user'} → ${AUTH_FILE}`);
+        return { ok: true, status: 'claimed', user: { id: auth.user.id, email: auth.user.email }, authFile: AUTH_FILE };
+      }
+
+      if (status === 'pending') {
+        lastReason = 'session still pending authorization';
+      } else {
+        lastReason = r.body?.error || `unexpected response (HTTP ${r.status}${status ? `, status=${status}` : ''})`;
+      }
+      log(`attempt ${attempt}/${tries}: ${lastReason}`);
+    } catch (e: any) {
+      lastReason = e?.message || String(e);
+      log(`attempt ${attempt}/${tries} errored: ${lastReason}`);
+    }
+
+    if (attempt < tries) await sleep(intervalMs);
+  }
+
+  return { ok: false, status: 'timed_out', reason: lastReason };
+}

package/src/payload-daemon.ts

@@ -0,0 +1,168 @@
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { randomBytes } from 'crypto';
+import { execSync } from 'child_process';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const PAYLOAD_DIR = process.env.EMPIR3_BRIDGE_PAYLOAD_DIR || __dirname;
+const BRIDGE_BUNDLE = join(PAYLOAD_DIR, 'bundle-bridge.js');
+const SERVER_BUNDLE = join(PAYLOAD_DIR, 'bundle-server.js');
+
+// ── Single-instance guard ───────────────────────────────────────────
+// This daemon binds the bridge + wrapper ports in-process. Only ONE bridge
+// can own them, so any predecessor still holding a port must be reaped before
+// we bind — otherwise a second daemon launched while a stale/wedged one is
+// still up collides (EADDRINUSE, zombie Chrome, "CDP direct timeout"). A new
+// daemon launch always means "replace whatever is there", so we reap then bind.
+// (Callers only launch a fresh daemon when they want one — the MCP server
+// reuses a daemon that already answers /api/status instead of relaunching.)
+
+/** PIDs LISTENING on a TCP port (Windows). */
+function listenerPids(port: number): number[] {
+  if (process.platform !== 'win32') return [];
+  try {
+    const out = execSync('netstat -ano -p tcp', { encoding: 'utf-8' });
+    const pids = new Set<number>();
+    for (const line of out.split('\n')) {
+      const parts = line.trim().split(/\s+/);
+      // Proto  LocalAddress  ForeignAddress  State  PID
+      if (parts.length >= 5 && /^LISTENING$/i.test(parts[3]) && parts[1].endsWith(`:${port}`)) {
+        const pid = Number(parts[4]);
+        if (pid > 0) pids.add(pid);
+      }
+    }
+    return [...pids];
+  } catch {
+    return [];
+  }
+}
+
+/** Image name for a PID (e.g. "node.exe"), lowercased. */
+function processName(pid: number): string {
+  try {
+    const out = execSync(`tasklist /FI "PID eq ${pid}" /FO CSV /NH`, { encoding: 'utf-8' });
+    const m = out.match(/^"([^"]+)"/);
+    return m ? m[1].toLowerCase() : '';
+  } catch {
+    return '';
+  }
+}
+
+function killPid(pid: number): void {
+  try { execSync(`taskkill /PID ${pid} /F /T`, { stdio: 'ignore' }); } catch {}
+}
+
+/**
+ * Reap any predecessor bridge holding our ports so we can bind a fresh one.
+ * Only kills node.exe (a bridge daemon) and chrome.exe (its driven Chrome) —
+ * never an unrelated app that merely happens to use the port.
+ */
+function reapPredecessors(bridgePort: number, wrapperPort: number, cdpPort: number): void {
+  if (process.platform !== 'win32') return;
+  const pids = new Set<number>([
+    ...listenerPids(bridgePort),
+    ...listenerPids(wrapperPort),
+    ...listenerPids(cdpPort),
+  ]);
+  pids.delete(process.pid);
+  let reaped = 0;
+  for (const pid of pids) {
+    const name = processName(pid);
+    if (name === 'node.exe' || name === 'chrome.exe') {
+      console.log(`[empir3-bridge] reaping predecessor ${name} PID ${pid} (held bridge port)`);
+      killPid(pid);
+      reaped++;
+    } else if (name) {
+      console.log(`[empir3-bridge] port held by ${name} PID ${pid} — leaving it alone`);
+    }
+  }
+  if (reaped > 0) {
+    // Give the OS a moment to release the ports (TIME_WAIT) before we bind.
+    const until = Date.now() + 1500;
+    while (Date.now() < until) { /* brief spin so binding doesn't race the kill */ }
+  }
+}
+
+function ensureBridgeNonce(): string {
+  const nonce = process.env.EMPIR3_BRIDGE_NONCE || randomBytes(8).toString('hex');
+  process.env.EMPIR3_BRIDGE_NONCE = nonce;
+
+  try {
+    const dir = join(homedir(), '.empir3-bridge');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'nonce'), nonce, 'utf-8');
+  } catch (e: any) {
+    console.warn(`[empir3-bridge] failed to write bridge nonce: ${e?.message || e}`);
+  }
+
+  return nonce;
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function waitFor(
+  url: string,
+  label: string,
+  maxWaitMs: number,
+  isReady: (body: any) => boolean = () => true,
+): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < maxWaitMs) {
+    try {
+      const res = await fetch(url);
+      if (res.ok) {
+        const text = await res.text();
+        let body: any = null;
+        try { body = text ? JSON.parse(text) : null; } catch {}
+        if (isReady(body)) return;
+      }
+    } catch {}
+    await wait(500);
+  }
+  throw new Error(`${label} did not become ready at ${url}`);
+}
+
+function loadBundle(script: string, label: string): void {
+  if (!existsSync(script)) {
+    throw new Error(`Missing ${label} bundle: ${script}`);
+  }
+  console.log(`[empir3-bridge] loading ${label}: ${script}`);
+  require(script);
+}
+
+export async function start() {
+  const bridgePort = Number(process.env.EMPIR3_BRIDGE_PORT || process.env.EMPIR3_BRIDGE_HTTP_PORT || 9867);
+  const wrapperPort = Number(process.env.EMPIR3_PW_PORT || process.env.PW_PORT || 3006);
+  const cdpPort = Number(process.env.CDP_PORT || 9222);
+  process.env.EMPIR3_BRIDGE_PORT = String(bridgePort);
+  process.env.BRIDGE_PORT = String(bridgePort);
+  process.env.PW_PORT = String(wrapperPort);
+  const nonce = ensureBridgeNonce();
+
+  console.log(`[empir3-bridge] starting payload runtime v${process.env.EMPIR3_BRIDGE_PAYLOAD_VERSION || 'dev'} nonce=${nonce.slice(0, 6)}...`);
+
+  // Replace any stale/wedged predecessor holding our ports before we bind.
+  reapPredecessors(bridgePort, wrapperPort, cdpPort);
+
+  loadBundle(BRIDGE_BUNDLE, 'cdp bridge');
+  await waitFor(
+    `http://127.0.0.1:${bridgePort}/health`,
+    'CDP bridge HTTP server',
+    30_000,
+    (body) => body?.port === bridgePort && typeof body?.status === 'string',
+  );
+
+  loadBundle(SERVER_BUNDLE, 'http wrapper');
+  await waitFor(`http://127.0.0.1:${wrapperPort}/api/status`, 'HTTP wrapper', 30_000);
+
+  await new Promise<void>(() => {});
+}
+
+if (require.main === module) {
+  start().catch((e) => {
+    console.error('[empir3-bridge] payload runtime failed:', e?.stack || e?.message || e);
+    process.exit(1);
+  });
+}