@xnng/browser-relay 1.6.0

package/server/hub-server.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+import { createServer } from "node:http";
+import { webcrypto } from "node:crypto";
+import { sendRpc } from "../hub/src/rpc.js";
+if (!globalThis.crypto) globalThis.crypto = webcrypto;
+import { WebSocket, WebSocketServer } from "ws";
+import {
+  bearerToken,
+  deriveRouteId,
+  errorPayload,
+  jsonHeaders,
+  REMOTE_RPC_TIMEOUT_MS,
+  safeEqualString,
+  sha256Hex,
+} from "./remote-protocol.js";
+
+const HUB_HOST = process.env.BROWSER_RELAY_HUB_HOST || "127.0.0.1";
+const HUB_PORT = Number.parseInt(process.env.BROWSER_RELAY_HUB_PORT || "18796", 10);
+const MAX_BODY_SIZE = 128 * 1024;
+const DEVICE_AUTH_TIMEOUT_MS = Number.parseInt(process.env.BROWSER_RELAY_DEVICE_AUTH_TIMEOUT_MS || "5000", 10);
+
+const devices = new Map(); // routeId -> { secretHash, ws, hello, connectedAt, lastSeen, pending }
+
+function log(event, data = {}) {
+  console.log(JSON.stringify({ timestamp: new Date().toISOString(), event, ...data }));
+}
+
+function jsonResponse(res, status, body, extraHeaders = {}) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, { ...jsonHeaders(extraHeaders), "Content-Length": Buffer.byteLength(payload) });
+  res.end(payload);
+}
+
+async function readBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > MAX_BODY_SIZE) throw Object.assign(new Error("Request body too large"), { status: 413, code: "request_body_too_large" });
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8");
+  if (!raw.trim()) return {};
+  try { return JSON.parse(raw); }
+  catch { throw Object.assign(new Error("Invalid JSON in request body"), { status: 400, code: "invalid_json" }); }
+}
+
+function getDevice(routeId) {
+  let device = devices.get(routeId);
+  if (!device) {
+    device = { secretHash: null, ws: null, hello: null, connectedAt: null, lastSeen: null, pending: new Map() };
+    devices.set(routeId, device);
+  }
+  return device;
+}
+
+function authorizeDevice(routeId, secret, { claim = false } = {}) {
+  if (!routeId || !secret) return { ok: false, status: 401, code: "invalid_remote_device", message: "Invalid or missing remote device credentials" };
+  if (!safeEqualString(routeId, deriveRouteId(secret))) {
+    return { ok: false, status: 401, code: "invalid_remote_device", message: "Invalid or revoked remote device id" };
+  }
+  const device = getDevice(routeId);
+  const secretHash = sha256Hex(secret);
+  if (!device.secretHash) {
+    if (claim) {
+      device.secretHash = secretHash;
+      return { ok: true, device, claimed: true };
+    }
+    return { ok: false, status: 409, code: "remote_device_offline", message: "Remote Browser Relay device is offline" };
+  }
+  if (!safeEqualString(device.secretHash, secretHash)) {
+    return { ok: false, status: 401, code: "invalid_remote_device", message: "Invalid or revoked remote device id" };
+  }
+  return { ok: true, device, claimed: false };
+}
+
+function rejectUpgrade(socket, status, message) {
+  const body = JSON.stringify(errorPayload(status === 401 ? "invalid_remote_device" : "upgrade_failed", message, { status }));
+  socket.write(`HTTP/1.1 ${status} ${message}\r\nContent-Type: application/json\r\nContent-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+  socket.destroy();
+}
+
+function clearPending(device, payload) {
+  for (const [id, pending] of device.pending) {
+    clearTimeout(pending.timer);
+    pending.reject(payload);
+    device.pending.delete(id);
+  }
+}
+
+function handleDeviceMessage(routeId, device, ws, raw) {
+  let msg;
+  try { msg = JSON.parse(String(raw)); }
+  catch { return; }
+  if (device.ws !== ws) return;
+  device.lastSeen = new Date().toISOString();
+
+  if (msg.type === "device.hello") {
+    device.hello = msg;
+    return;
+  }
+
+  if (msg.type === "rpc.response" && msg.id) {
+    const pending = device.pending.get(msg.id);
+    if (!pending) return;
+    clearTimeout(pending.timer);
+    device.pending.delete(msg.id);
+    pending.resolve(msg);
+  }
+}
+
+function sendRpcToDevice(device, request, signal) {
+  if (!device.ws || device.ws.readyState !== WebSocket.OPEN) {
+    throw errorPayload("remote_device_offline", "Remote Browser Relay device is offline", { status: 409, retryable: true });
+  }
+  return sendRpc(device.ws,device.pending,request,{signal,timeoutMs:REMOTE_RPC_TIMEOUT_MS});
+}
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+  try {
+    if (req.method === "GET" && (url.pathname === "/" || url.pathname === "/v1/health")) {
+      return jsonResponse(res, 200, { ok: true, service: "browser-relay-hub", devices: devices.size });
+    }
+
+    if (req.method === "GET" && url.pathname.startsWith("/v1/status/")) {
+      const routeId = decodeURIComponent(url.pathname.slice("/v1/status/".length));
+      const secret = bearerToken(req.headers);
+      const auth = authorizeDevice(routeId, secret);
+      if (!auth.ok) return jsonResponse(res, auth.status, errorPayload(auth.code, auth.message, { status: auth.status }));
+      const device = auth.device;
+      return jsonResponse(res, 200, {
+        ok: true,
+        routeId,
+        connected: !!device.ws && device.ws.readyState === WebSocket.OPEN,
+        connectedAt: device.connectedAt,
+        lastSeen: device.lastSeen,
+        hello: device.hello,
+      });
+    }
+
+    if (req.method === "POST" && url.pathname === "/v1/rpc") {
+      const body = await readBody(req);
+      const routeId = String(body.routeId || "");
+      const secret = bearerToken(req.headers);
+      const auth = authorizeDevice(routeId, secret);
+      if (!auth.ok) return jsonResponse(res, auth.status, errorPayload(auth.code, auth.message, { status: auth.status }));
+      if (!body.method || !body.path) {
+        return jsonResponse(res, 400, errorPayload("invalid_request", "method and path are required", { status: 400 }));
+      }
+
+      const controller=new AbortController();
+      const abort=()=>{if(!res.writableFinished)controller.abort();};
+      res.once('close',abort);
+      if(req.aborted || res.destroyed)controller.abort();
+      try {
+        const response = await sendRpcToDevice(auth.device, body,controller.signal);
+        const status = Number(response.status) || 200;
+        const responseBody = response.body ?? null;
+        const headers = response.headers && typeof response.headers === "object" ? response.headers : {};
+        if (typeof responseBody === "string") {
+          res.writeHead(status, { "Content-Type": headers["content-type"] || headers["Content-Type"] || "text/plain" });
+          res.end(responseBody);
+        } else {
+          jsonResponse(res, status, responseBody, headers);
+        }
+      } catch (err) {
+        const payload = err && typeof err === "object" && "code" in err
+          ? err
+          : errorPayload("remote_rpc_failed", err instanceof Error ? err.message : String(err), { status: 502, retryable: true });
+        if(!res.destroyed)jsonResponse(res, payload.status || 502, payload);
+      } finally {res.removeListener('close',abort);}
+      return;
+    }
+
+    jsonResponse(res, 404, errorPayload("endpoint_not_found", `Unknown hub endpoint: ${url.pathname}`, { status: 404 }));
+  } catch (err) {
+    const status = err.status || 500;
+    const code = err.code || "internal_error";
+    jsonResponse(res, status, errorPayload(code, err instanceof Error ? err.message : String(err), { status }));
+  }
+});
+
+const wss = new WebSocketServer({ noServer: true });
+
+server.on("upgrade", (req, socket, head) => {
+  const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+  if (url.pathname !== "/v1/device/connect") return rejectUpgrade(socket, 404, "Not Found");
+  const routeId = url.searchParams.get("routeId") || "";
+  if (!routeId) return rejectUpgrade(socket, 401, "Unauthorized");
+  const legacySecret = url.searchParams.get("token") || bearerToken(req.headers);
+
+  wss.handleUpgrade(req, socket, head, (ws) => {
+    wss.emit("connection", ws, req, routeId, legacySecret);
+  });
+});
+
+wss.on("connection", (ws, req, routeId, legacySecret) => {
+  let authenticated = false;
+  let device = null;
+  const authTimer = setTimeout(() => {
+    if (!authenticated) ws.close(4008, "authentication timeout");
+  }, DEVICE_AUTH_TIMEOUT_MS);
+
+  const authenticate = (secret, { legacy = false } = {}) => {
+    if (authenticated) return true;
+    const auth = authorizeDevice(routeId, secret, { claim: true });
+    if (!auth.ok) {
+      clearTimeout(authTimer);
+      ws.close(4003, "authentication failed");
+      return false;
+    }
+    device = auth.device;
+    if (device.ws && device.ws.readyState === WebSocket.OPEN && device.ws !== ws) {
+      try { device.ws.close(4001, "superseded"); } catch {}
+    }
+    device.ws = ws;
+    device.connectedAt = new Date().toISOString();
+    device.lastSeen = device.connectedAt;
+    authenticated = true;
+    clearTimeout(authTimer);
+    ws.send(JSON.stringify({ type: "device.authenticated" }));
+    log("device.connect", { routeId, claimed: auth.claimed, legacy, remote: req.socket.remoteAddress || "unknown" });
+    return true;
+  };
+
+  if (legacySecret) authenticate(legacySecret, { legacy: true });
+
+  ws.on("message", (raw) => {
+    let msg;
+    try { msg = JSON.parse(String(raw)); } catch { return; }
+    if (!authenticated) {
+      if (msg.type === "device.auth" && typeof msg.secret === "string") authenticate(msg.secret);
+      else {
+        clearTimeout(authTimer);
+        ws.close(4003, "authenticate first");
+      }
+      return;
+    }
+    if (msg.type === "device.auth") return;
+    handleDeviceMessage(routeId, device, ws, raw);
+  });
+  ws.on("close", (code) => {
+    clearTimeout(authTimer);
+    if (!authenticated || device?.ws !== ws) return;
+    device.ws = null;
+    device.lastSeen = new Date().toISOString();
+    clearPending(device, errorPayload("remote_device_offline", "Remote Browser Relay device disconnected", { status: 409, retryable: true }));
+    log("device.disconnect", { routeId, code });
+  });
+  ws.on("error", () => {});
+});
+
+server.listen(HUB_PORT, HUB_HOST, () => {
+  console.log(`Browser Relay Hub listening on http://${HUB_HOST}:${HUB_PORT}`);
+  console.log(`Device WSS: ws://${HUB_HOST}:${HUB_PORT}/v1/device/connect?routeId=...`);
+  console.log(`RPC:        http://${HUB_HOST}:${HUB_PORT}/v1/rpc`);
+});

package/server/install.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir, platform } from "node:os";
+import { execSync } from "node:child_process";
+import { installWindowsTask } from "./windows-service.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const RELAY_DIR = dirname(__dirname);
+const EXTENSION_DIR = join(RELAY_DIR, "extension");
+const CLI_PATH = join(__dirname, "cli.js");
+const WINDOWS_SERVICE_ENTRY_PATH = join(__dirname, "windows-service-entry.js");
+const NODE_PATH = process.execPath;
+const LAUNCHD_LABEL = "org.browser-relay.service";
+
+function log(msg) {
+  console.log(`[browser-relay] ${msg}`);
+}
+
+function xmlEscape(s) {
+  return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function installDarwin() {
+  const plistDst = join(homedir(), `Library/LaunchAgents/${LAUNCHD_LABEL}.plist`);
+
+  // Call node + cli.js directly by absolute path — avoids bin shim path
+  // discovery (npm bin -g was removed in npm 9+) and launchd's minimal PATH
+  // (shebang #!/usr/bin/env node can't find node outside /usr/bin).
+  const plistContent = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(NODE_PATH)}</string>
+    <string>${xmlEscape(CLI_PATH)}</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>BROWSER_RELAY_HOST</key>
+    <string>127.0.0.1</string>
+    <key>BROWSER_RELAY_PORT</key>
+    <string>18795</string>
+    <key>PATH</key>
+    <string>${xmlEscape(dirname(NODE_PATH))}:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>StandardOutPath</key>
+  <string>/tmp/browser-relay.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/browser-relay.error.log</string>
+  </dict>
+</plist>`;
+
+  mkdirSync(dirname(plistDst), { recursive: true });
+  writeFileSync(plistDst, plistContent);
+
+  // Use bootstrap/bootout — `launchctl load/unload` is the legacy API and
+  // often silently fails or returns EBADEXEC on macOS 13+. bootout first for
+  // idempotency; ignore "service not found" errors.
+  const domain = `gui/${process.getuid()}`;
+  try { execSync(`launchctl bootout ${domain} "${plistDst}" 2>/dev/null`); } catch {}
+  try {
+    execSync(`launchctl bootstrap ${domain} "${plistDst}"`);
+    log(`Registered with launchd (node=${NODE_PATH}).`);
+    return true;
+  } catch (e) {
+    log(`launchctl bootstrap failed: ${e.message}. Check /tmp/browser-relay.error.log`);
+    return false;
+  }
+}
+
+function installLinux() {
+  const serviceDst = join(homedir(), ".config/systemd/user/browser-relay.service");
+
+  // Same approach as macOS: invoke node + cli.js by absolute path so we don't
+  // depend on PATH discovery or the npm bin shim.
+  const serviceContent = `[Unit]
+Description=Browser Relay Server
+After=network.target
+
+[Service]
+ExecStart=${NODE_PATH} ${CLI_PATH}
+Environment=BROWSER_RELAY_HOST=127.0.0.1
+Environment=BROWSER_RELAY_PORT=18795
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`;
+
+  mkdirSync(dirname(serviceDst), { recursive: true });
+  writeFileSync(serviceDst, serviceContent);
+
+  try {
+    execSync("systemctl --user daemon-reload");
+    execSync("systemctl --user enable browser-relay");
+    execSync("systemctl --user start browser-relay");
+    log(`Registered with systemd (node=${NODE_PATH}).`);
+    return true;
+  } catch (e) {
+    const msg = (e instanceof Error ? e.message : String(e)).split("\n")[0];
+    log(`systemd registration skipped (${msg}). Run manually: ${NODE_PATH} ${CLI_PATH}`);
+    return false;
+  }
+}
+
+function installWin32() {
+  const result = installWindowsTask({
+    nodePath: NODE_PATH,
+    serviceEntryPath: WINDOWS_SERVICE_ENTRY_PATH,
+    cliPath: CLI_PATH,
+  });
+  log(`Registered with Windows Task Scheduler for the current user (node=${NODE_PATH}).`);
+  log(`Logs: ${result.paths.stdoutLog}`);
+  return true;
+}
+
+// Agents keep their own copy of the skill (installed via npx skills add).
+// On upgrade, find copies that no longer match the shipped skill and remind
+// the user to re-run the install command — the copies belong to the agent
+// tools, so we never overwrite them ourselves.
+const AGENT_SKILL_ROOTS = [
+  ".agents/skills",
+  ".claude/skills",
+  ".codex/skills",
+  ".cursor/skills",
+  ".windsurf/skills",
+  ".gemini/skills",
+  ".copilot/skills",
+  ".config/opencode/skills",
+];
+
+function checkInstalledSkills() {
+  let shipped;
+  try { shipped = readFileSync(join(RELAY_DIR, "skills/browser-relay/SKILL.md"), "utf-8"); } catch { return; }
+  const stale = [];
+  for (const root of AGENT_SKILL_ROOTS) {
+    const dir = join(homedir(), root, "browser-relay");
+    try {
+      if (readFileSync(join(dir, "SKILL.md"), "utf-8") !== shipped) stale.push(dir);
+    } catch { /* skill not installed for this agent */ }
+  }
+  if (!stale.length) return;
+  log("");
+  log("⚠ Installed agent skill is out of date:");
+  for (const dir of stale) log(`   ${dir}`);
+  log("   Run 'browser-relay skill help', then reinstall for codex, claude-code, or universal.");
+}
+
+async function waitForRelay(expectedVersion) {
+  for (let i = 0; i < 20; i++) {
+    try {
+      const response = await fetch("http://127.0.0.1:18795/api/debug", {
+        signal: AbortSignal.timeout(1000),
+      });
+      if (response.ok) {
+        const data = await response.json();
+        if (data && data.version === expectedVersion && typeof data.connected === "boolean") return true;
+      }
+    } catch {}
+    if (i < 19) await new Promise((resolveDelay) => setTimeout(resolveDelay, 500));
+  }
+  return false;
+}
+
+export async function installService(options = {}) {
+  const explicit = options.explicit === true;
+  const strict = options.strict === true;
+  // Only register a background service on global installs. `npm i` (local) is
+  // typically a developer adding the package as a dependency — they don't want
+  // a daemon hijacking their machine.
+  const isGlobal = process.env.npm_config_global === "true";
+  if (!explicit && !isGlobal) {
+    log("Local install — skipping background service registration.");
+    log(`Install globally to enable auto-start: npm install -g @xnng/browser-relay`);
+    log(`Or run manually: ${NODE_PATH} ${CLI_PATH}`);
+    log("");
+    log(`📦 Chrome Extension: ${EXTENSION_DIR}`);
+    log(`📖 Agent Skill:      ${join(RELAY_DIR, "skills/browser-relay/SKILL.md")}`);
+    return { installed: false, skipped: true };
+  }
+
+  log("Setting up Browser Relay...");
+
+  const sys = platform();
+
+  let registered = false;
+  if (sys === "darwin") {
+    registered = installDarwin();
+  } else if (sys === "linux") {
+    registered = installLinux();
+  } else if (sys === "win32") {
+    registered = installWin32();
+  } else {
+    log(`Unsupported platform: ${sys}. Run 'browser-relay' manually.`);
+    if (strict) throw new Error(`Background service is not supported on ${sys}`);
+    return { installed: false, skipped: true };
+  }
+
+  if (!registered) {
+    if (strict) throw new Error("Background service registration failed");
+  } else {
+    const pkg = JSON.parse(readFileSync(join(RELAY_DIR, "package.json"), "utf-8"));
+    const healthy = await waitForRelay(pkg.version);
+    if (healthy) {
+      log("✅ Relay is running on http://127.0.0.1:18795");
+    } else {
+      const message = "Relay did not become healthy with the installed version. Run: browser-relay status";
+      log(`⚠️  ${message}`);
+      if (strict) throw new Error(message);
+    }
+  }
+
+  checkInstalledSkills();
+
+  log("");
+  log("📦 Chrome Extension:");
+  log(`   ${EXTENSION_DIR}`);
+  log("   Load at: chrome://extensions -> Developer mode -> Load unpacked");
+  log("   Already loaded? It reloads itself on its next relay reconnect (~30s).");
+  log("");
+  log("📖 Agent Skill:");
+  log(`   ${join(RELAY_DIR, "skills/browser-relay/SKILL.md")}`);
+  return { installed: registered, skipped: false };
+}
+
+// Postinstall must never fail npm install — wrap everything.
+const isDirect = process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+if (isDirect) {
+  try {
+    await installService();
+  } catch (e) {
+    log(`postinstall warning: ${e instanceof Error ? e.message : String(e)}`);
+    log(`Run manually: ${NODE_PATH} ${CLI_PATH}`);
+  }
+}