@xevy/heny-connect 0.1.0 → 0.3.0

package/lib/network-policy.mjs

@@ -0,0 +1,102 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+function ipv4Number(address) {
+  const parts = address.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return null;
+  return parts.reduce((value, part) => (value * 256) + part, 0) >>> 0;
+}
+
+function ipv4In(address, base, bits) {
+  const value = ipv4Number(address);
+  const start = ipv4Number(base);
+  if (value === null || start === null) return false;
+  if (bits === 0) return true;
+  const mask = (0xffffffff << (32 - bits)) >>> 0;
+  return (value & mask) === (start & mask);
+}
+
+function expandIpv6(address) {
+  let value = address.toLowerCase().split("%")[0];
+  if (value.includes(".")) {
+    const lastColon = value.lastIndexOf(":");
+    const v4 = ipv4Number(value.slice(lastColon + 1));
+    if (v4 === null) return null;
+    value = `${value.slice(0, lastColon)}:${((v4 >>> 16) & 0xffff).toString(16)}:${(v4 & 0xffff).toString(16)}`;
+  }
+  const halves = value.split("::");
+  if (halves.length > 2) return null;
+  const left = halves[0] ? halves[0].split(":") : [];
+  const right = halves[1] ? halves[1].split(":") : [];
+  const fill = 8 - left.length - right.length;
+  if (fill < 0 || (halves.length === 1 && fill !== 0)) return null;
+  const words = [...left, ...Array(fill).fill("0"), ...right];
+  if (words.length !== 8 || words.some((word) => !/^[0-9a-f]{1,4}$/.test(word))) return null;
+  return words.reduce((result, word) => (result << 16n) | BigInt(parseInt(word, 16)), 0n);
+}
+
+function ipv6In(address, base, bits) {
+  const value = expandIpv6(address);
+  const start = expandIpv6(base);
+  if (value === null || start === null) return false;
+  if (bits === 0) return true;
+  const shift = 128n - BigInt(bits);
+  return (value >> shift) === (start >> shift);
+}
+
+export function isBlockedAddress(address) {
+  const version = isIP(address);
+  if (version === 4) {
+    return [
+      ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8],
+      ["169.254.0.0", 16], ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.0.2.0", 24],
+      ["192.168.0.0", 16], ["198.18.0.0", 15], ["198.51.100.0", 24], ["203.0.113.0", 24],
+      ["224.0.0.0", 4], ["240.0.0.0", 4],
+    ].some(([base, bits]) => ipv4In(address, base, bits));
+  }
+  if (version === 6) {
+    const mapped = address.toLowerCase().match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped) return isBlockedAddress(mapped[1]);
+    if (ipv6In(address, "::ffff:0:0", 96)) {
+      const value = expandIpv6(address);
+      const low = Number(value & 0xffffffffn) >>> 0;
+      return isBlockedAddress(`${low >>> 24}.${(low >>> 16) & 255}.${(low >>> 8) & 255}.${low & 255}`);
+    }
+    return [
+      ["::", 96], ["::1", 128], ["64:ff9b::", 96], ["64:ff9b:1::", 48], ["100::", 64],
+      ["2001::", 32], ["2001:db8::", 32], ["2002::", 16], ["3fff::", 20], ["5f00::", 16],
+      ["fc00::", 7], ["fec0::", 10], ["fe80::", 10], ["ff00::", 8],
+    ].some(([base, bits]) => ipv6In(address, base, bits));
+  }
+  return true;
+}
+
+export function parsePublicUrl(value) {
+  let url;
+  try { url = new URL(value); } catch { throw Object.assign(new Error("Destination URL is invalid."), { code: "destination_invalid" }); }
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) {
+    throw Object.assign(new Error("Destination must use HTTP(S) without credentials."), { code: "destination_blocked" });
+  }
+  const port = Number(url.port || (url.protocol === "https:" ? 443 : 80));
+  if (![80, 443].includes(port)) throw Object.assign(new Error("Destination port is blocked."), { code: "destination_blocked" });
+  return url;
+}
+
+export async function resolvePublicHost(hostname, lookup = dnsLookup) {
+  const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  if (!host || host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host === "metadata.google.internal") {
+    throw Object.assign(new Error("Destination is blocked."), { code: "destination_blocked" });
+  }
+  const literal = isIP(host);
+  const answers = literal ? [{ address: host, family: literal }] : await lookup(host, { all: true, verbatim: true });
+  if (!answers.length || answers.some(({ address }) => isBlockedAddress(address))) {
+    throw Object.assign(new Error("Destination is blocked."), { code: "destination_blocked" });
+  }
+  return answers[0];
+}
+
+export async function resolvePublicUrl(value, lookup = dnsLookup) {
+  const url = parsePublicUrl(value);
+  const answer = await resolvePublicHost(url.hostname, lookup);
+  return { url, ...answer };
+}

package/lib/state.mjs

@@ -0,0 +1,54 @@
+import { spawnSync } from "node:child_process";
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+
+export const CONNECT_HOME = process.env.HENY_CONNECT_HOME || (platform() === "win32" && process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, "Heny Connect") : homedir());
+export const STATE_FILE = join(CONNECT_HOME, ".heny-connect.json");
+export const STATUS_FILE = join(CONNECT_HOME, "worker-status.json");
+export const PAUSE_FILE = join(CONNECT_HOME, "paused");
+export const STOP_FILE = join(CONNECT_HOME, "stopping");
+export const LOCK_FILE = join(CONNECT_HOME, "worker.lock");
+
+export async function protectConnectHome() {
+  await mkdir(CONNECT_HOME, { recursive: true });
+  if (platform() === "win32") {
+    const script = [
+      "$target=$env:HENY_ACL_TARGET",
+      "$acl=New-Object System.Security.AccessControl.DirectorySecurity",
+      "$acl.SetAccessRuleProtection($true,$false)",
+      "$inherit=[System.Security.AccessControl.InheritanceFlags]'ContainerInherit,ObjectInherit'",
+      "$prop=[System.Security.AccessControl.PropagationFlags]::None",
+      "$allow=[System.Security.AccessControl.AccessControlType]::Allow",
+      "$full=[System.Security.AccessControl.FileSystemRights]::FullControl",
+      "$user=[System.Security.Principal.WindowsIdentity]::GetCurrent().User",
+      "$system=[System.Security.Principal.SecurityIdentifier]::new('S-1-5-18')",
+      "$acl.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new($user,$full,$inherit,$prop,$allow))",
+      "$acl.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new($system,$full,$inherit,$prop,$allow))",
+      "Set-Acl -LiteralPath $target -AclObject $acl",
+    ].join(";");
+    const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script], { windowsHide: true, stdio: "ignore", env: { ...process.env, HENY_ACL_TARGET: CONNECT_HOME } });
+    if (result.status !== 0) throw Object.assign(new Error("Heny Connect could not protect its local state."), { code: "acl_failed" });
+  }
+}
+
+export async function loadState() {
+  try { return JSON.parse(await readFile(STATE_FILE, "utf8")); } catch { return null; }
+}
+
+export async function saveState(state) {
+  await protectConnectHome();
+  const temporary = `${STATE_FILE}.tmp`;
+  await writeFile(temporary, JSON.stringify(state, null, 2), { mode: 0o600 });
+  await rename(temporary, STATE_FILE);
+  await chmod(STATE_FILE, 0o600).catch(() => undefined);
+}
+
+export async function clearState() {
+  await unlink(STATE_FILE).catch(() => undefined);
+}
+
+export async function writeStatus(status) {
+  await mkdir(CONNECT_HOME, { recursive: true });
+  await writeFile(STATUS_FILE, JSON.stringify({ ...status, updatedAt: new Date().toISOString() }), { mode: 0o600 });
+}

package/lib/validating-proxy.mjs

@@ -0,0 +1,70 @@
+import http from "node:http";
+import net from "node:net";
+import { resolvePublicHost, resolvePublicUrl } from "./network-policy.mjs";
+
+function safeDestroy(stream) {
+  try { stream.destroy(); } catch {}
+}
+
+export async function createValidatingProxy(options = {}) {
+  const lookup = options.lookup;
+  const server = http.createServer(async (request, response) => {
+    try {
+      const { url, address, family } = await resolvePublicUrl(request.url, lookup);
+      const headers = { ...request.headers, host: url.host };
+      delete headers["proxy-connection"];
+      const upstream = http.request({
+        host: address,
+        family,
+        port: Number(url.port || 80),
+        method: request.method,
+        path: `${url.pathname}${url.search}`,
+        headers,
+      }, (incoming) => {
+        response.writeHead(incoming.statusCode || 502, incoming.statusMessage, incoming.headers);
+        incoming.pipe(response);
+      });
+      upstream.on("error", () => {
+        if (!response.headersSent) response.writeHead(502);
+        response.end();
+      });
+      request.pipe(upstream);
+    } catch {
+      response.writeHead(403, { "content-type": "text/plain", connection: "close" });
+      response.end("Destination blocked");
+    }
+  });
+
+  server.on("connect", async (request, client, head) => {
+    try {
+      const authority = request.url || "";
+      const match = authority.match(/^\[([^\]]+)]:(\d+)$/) || authority.match(/^([^:]+):(\d+)$/);
+      if (!match) throw new Error("Invalid authority");
+      const host = match[1];
+      const port = Number(match[2]);
+      if (port !== 443 && port !== 80) throw new Error("Port blocked");
+      const { address, family } = await resolvePublicHost(host, lookup);
+      const upstream = net.connect({ host: address, family, port }, () => {
+        client.write("HTTP/1.1 200 Connection Established\r\nProxy-Agent: Heny\r\n\r\n");
+        if (head.length) upstream.write(head);
+        client.pipe(upstream);
+        upstream.pipe(client);
+      });
+      upstream.on("error", () => safeDestroy(client));
+      client.on("error", () => safeDestroy(upstream));
+    } catch {
+      client.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+      safeDestroy(client);
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  return {
+    port: address.port,
+    close: () => new Promise((resolve) => server.close(resolve)),
+  };
+}

package/lib/worker.mjs

@@ -0,0 +1,241 @@
+import { open, readFile, unlink } from "node:fs/promises";
+import { BrowserController } from "./browser-controller.mjs";
+import { clearState, CONNECT_HOME, LOCK_FILE, PAUSE_FILE, STOP_FILE, writeStatus } from "./state.mjs";
+
+export const CAPABILITIES = ["browser.navigate", "browser.read", "browser.screenshot"];
+const LEASE_MS = 10_000;
+const POLL_MS = 2_000;
+const HEARTBEAT_MS = 30_000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const settleWithin = (promise, milliseconds) => new Promise((resolve) => {
+  const timer = setTimeout(resolve, milliseconds);
+  timer.unref?.();
+  Promise.resolve(promise).then((value) => { clearTimeout(timer); resolve(value); }, () => { clearTimeout(timer); resolve(undefined); });
+});
+
+const attemptWithin = (promise, milliseconds) => new Promise((resolve) => {
+  const timer = setTimeout(() => resolve({ acknowledged: false }), milliseconds);
+  Promise.resolve(promise).then(
+    (value) => { clearTimeout(timer); resolve({ acknowledged: true, value }); },
+    (error) => { clearTimeout(timer); resolve({ acknowledged: false, error }); },
+  );
+});
+
+async function completeWithRetry(api, command, claimToken, status, result, error, cutoff) {
+  while (Date.now() < cutoff) {
+    const remaining = cutoff - Date.now();
+    const outcome = await attemptWithin(api.complete(command, claimToken, status, result, error), Math.min(2_000, remaining));
+    if (outcome.acknowledged) return true;
+    if (outcome.error?.status === 401) throw outcome.error;
+    if (outcome.error && [400, 409].includes(outcome.error.status)) return false;
+    const delay = Math.min(250, Math.max(0, cutoff - Date.now()));
+    if (delay) await sleep(delay);
+  }
+  return false;
+}
+
+function sanitizedCode(error) {
+  const value = typeof error?.code === "string" ? error.code : "worker_error";
+  return /^[a-z0-9_]{1,40}$/.test(value) ? value : "worker_error";
+}
+
+async function paused() {
+  try { await readFile(PAUSE_FILE); return true; } catch { return false; }
+}
+
+async function shutdownRequested() {
+  try { await readFile(STOP_FILE); return true; } catch { return false; }
+}
+
+async function acquireLock() {
+  try {
+    const file = await open(LOCK_FILE, "wx", 0o600);
+    await file.writeFile(String(process.pid));
+    return async () => { await file.close(); await unlink(LOCK_FILE).catch(() => undefined); };
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    let pid = 0;
+    try { pid = Number(await readFile(LOCK_FILE, "utf8")); process.kill(pid, 0); } catch {
+      await unlink(LOCK_FILE).catch(() => undefined);
+      return acquireLock();
+    }
+    throw Object.assign(new Error("Heny Connect is already running."), { code: "worker_running" });
+  }
+}
+
+export class DeviceApi {
+  constructor(state) { this.state = state; }
+
+  async request(path, body = {}) {
+    const response = await fetch(new URL(path, this.state.server), {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${this.state.token}` },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(20_000),
+    });
+    if (response.status === 401) {
+      await clearState();
+      throw Object.assign(new Error("Registration was revoked. Pair this computer again."), { code: "device_revoked", status: 401 });
+    }
+    if (response.status === 204) return null;
+    let parsed = null;
+    try { parsed = await response.json(); } catch {}
+    if (!response.ok) throw Object.assign(new Error(parsed?.error?.message || `Server answered HTTP ${response.status}`), { code: parsed?.error?.code || "server_error", status: response.status });
+    return parsed;
+  }
+
+  heartbeat(state, browserReady, current) {
+    return this.request("/api/devices/heartbeat", {
+      state,
+      browserReady,
+      capabilities: CAPABILITIES,
+      ...(current ? { currentCommandId: current.id, currentAction: current.action } : {}),
+      detailCode: current ? "command_running" : state,
+    });
+  }
+
+  claim() { return this.request("/api/devices/commands/claim"); }
+  lease(command, claimToken) { return this.request(`/api/devices/commands/${command.id}/lease`, { claimToken, attempt: command.attempt }); }
+  complete(command, claimToken, status, result, error) {
+    return this.request(`/api/devices/commands/${command.id}/complete`, {
+      claimToken,
+      attempt: command.attempt,
+      status,
+      ...(result !== undefined ? { result } : {}),
+      ...(error ? { error } : {}),
+    });
+  }
+}
+
+export async function runWorker(state, options = {}) {
+  await unlink(STOP_FILE).catch(() => undefined);
+  const releaseLock = await acquireLock();
+  const api = options.api || new DeviceApi(state);
+  const browser = options.browser || new BrowserController({ home: CONNECT_HOME });
+  let active = null;
+  let stopped = false;
+  let nextHeartbeat = 0;
+  let pauseDeadline = 0;
+  const stop = () => { stopped = true; active?.controller.abort(); void browser.stop().catch(() => undefined); };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+  options.signal?.addEventListener("abort", stop, { once: true });
+  let watchBusy = false;
+  let pauseHandled = false;
+  const localWatch = setInterval(() => {
+    if (watchBusy) return;
+    watchBusy = true;
+    void Promise.all([paused(), shutdownRequested()]).then(async ([isPaused, shutdown]) => {
+      if (shutdown) stopped = true;
+      if (isPaused || shutdown) {
+        active?.controller.abort();
+        if (!pauseHandled) {
+          pauseHandled = true;
+          await browser.stop().catch(() => undefined);
+          await writeStatus({ state: isPaused ? "paused" : "offline", currentCommandId: null, currentAction: null }).catch(() => undefined);
+        }
+      } else {
+        pauseHandled = false;
+      }
+    }).finally(() => { watchBusy = false; });
+  }, 250);
+
+  async function report(workerState, browserReady, current) {
+    await writeStatus({ state: workerState, currentCommandId: current?.id ?? null, currentAction: current?.action ?? null });
+    await api.heartbeat(workerState, browserReady, current);
+    nextHeartbeat = Date.now() + HEARTBEAT_MS;
+  }
+
+  try {
+    await writeStatus({ state: "browser_starting", currentCommandId: null, currentAction: null });
+    await api.heartbeat("browser_starting", false).catch(() => undefined);
+    while (!stopped) {
+      if (await shutdownRequested()) { stopped = true; break; }
+      if (await paused()) {
+        active?.controller.abort();
+        await browser.stop();
+        const reportBudget = pauseDeadline ? Math.max(0, pauseDeadline - Date.now()) : 5_000;
+        await settleWithin(report("paused", false), reportBudget);
+        pauseDeadline = 0;
+        while (!stopped && await paused()) {
+          if (await shutdownRequested()) { stopped = true; break; }
+          await sleep(250);
+        }
+        if (stopped) break;
+        await writeStatus({ state: "browser_starting", currentCommandId: null, currentAction: null });
+        await api.heartbeat("browser_starting", false).catch(() => undefined);
+      }
+      try {
+        await browser.start();
+        if (stopped) break;
+        if (await paused()) continue;
+        if (Date.now() >= nextHeartbeat) await report("available", true);
+        if (stopped) break;
+        if (await paused()) continue;
+        const claimed = await api.claim();
+        if (!claimed) { await sleep(options.pollMs ?? POLL_MS); continue; }
+        const { command, claimToken } = claimed;
+        const controller = new AbortController();
+        active = { command, claimToken, controller };
+        if (await paused()) controller.abort();
+        else await report("working", true, command);
+        const deadlineMs = Math.max(1, new Date(command.deadlineAt).getTime() - Date.now());
+        const deadline = setTimeout(() => controller.abort(), deadlineMs);
+        const pauseWatch = setInterval(() => { void Promise.all([paused(), shutdownRequested()]).then(([isPaused, shutdown]) => { if (shutdown) stopped = true; if (isPaused || shutdown) controller.abort(); }); }, 250);
+        const leaseWatch = setInterval(() => {
+          void api.lease(command, claimToken).then((lease) => { if (lease?.cancelRequested) controller.abort(); }).catch(() => controller.abort());
+        }, options.leaseMs ?? LEASE_MS);
+        try {
+          let status = "succeeded";
+          let result;
+          let completionError;
+          try {
+            result = await browser.execute(command.action, command.payload, { signal: controller.signal, timeoutMs: deadlineMs });
+          } catch (error) {
+            const cancelled = controller.signal.aborted;
+            status = cancelled ? "cancelled" : "failed";
+            completionError = { code: cancelled ? "command_cancelled" : sanitizedCode(error), message: cancelled ? "Command cancelled." : "The browser action failed." };
+          }
+          const locallyPaused = status === "cancelled" && await paused();
+          if (locallyPaused) {
+            pauseDeadline = Date.now() + (await shutdownRequested() ? 3_000 : 5_000);
+            await browser.stop().catch(() => undefined);
+            await writeStatus({ state: "paused", currentCommandId: null, currentAction: null }).catch(() => undefined);
+          }
+          const commandDeadline = new Date(command.deadlineAt).getTime();
+          const completionCutoff = locallyPaused ? Math.min(commandDeadline, pauseDeadline) : commandDeadline;
+          const acknowledged = await completeWithRetry(api, command, claimToken, status, result, completionError, completionCutoff);
+          if (!acknowledged && !locallyPaused) throw Object.assign(new Error("Command completion was not acknowledged."), { code: "completion_unconfirmed" });
+          const outcome = acknowledged ? status : "cancellation unconfirmed";
+          console.log(`${new Date().toISOString()} command ${command.id} ${command.action} ${outcome}`);
+        } finally {
+          clearTimeout(deadline);
+          clearInterval(pauseWatch);
+          clearInterval(leaseWatch);
+          active = null;
+        }
+        if (!await paused()) await report("available", true);
+      } catch (error) {
+        if (error.status === 401) throw error;
+        if (stopped) break;
+        if (await paused()) continue;
+        await browser.stop().catch(() => undefined);
+        await writeStatus({ state: "error", detailCode: sanitizedCode(error), currentCommandId: null, currentAction: null });
+        await api.heartbeat("error", false).catch(() => undefined);
+        console.error(`${new Date().toISOString()} worker error ${sanitizedCode(error)}`);
+        await sleep(5_000);
+      }
+    }
+  } finally {
+    clearInterval(localWatch);
+    active?.controller.abort();
+    await browser.stop().catch(() => undefined);
+    await settleWithin(api.heartbeat("offline", false), 5_000);
+    await writeStatus({ state: "offline", currentCommandId: null, currentAction: null }).catch(() => undefined);
+    await unlink(STOP_FILE).catch(() => undefined);
+    await releaseLock();
+    process.off("SIGINT", stop);
+    process.off("SIGTERM", stop);
+    options.signal?.removeEventListener("abort", stop);
+  }
+}

package/package.json

@@ -1,20 +1,22 @@
 {
   "name": "@xevy/heny-connect",
-  "version": "0.1.0",
-  "description": "Pair a computer with Heny and keep its device presence online.",
+  "version": "0.3.0",
+  "description": "Run Heny's isolated, permission-bounded desktop browser worker.",
   "type": "module",
   "bin": {
     "heny-connect": "bin/heny-connect.mjs"
   },
   "files": [
     "bin",
+    "lib",
+    "windows",
     "README.md"
   ],
   "scripts": {
     "test": "node --test test/*.node-test.mjs"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"