@corenel/sidecar 0.1.0 → 0.1.1

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire as __cr } from 'node:module'; const require = __cr(import.meta.url);
 
 // src/cli.ts
 import { resolve as resolve2 } from "node:path";
@@ -76,16 +77,19 @@ var SidecarServer = class {
   }
   onHello(m) {
     if (m.protocol !== SIDECAR_PROTOCOL) {
+      this.opts.log?.(`denied: unsupported protocol ${m.protocol}`);
       this.ch.send({ t: "denied", reason: `protocol ${m.protocol} unsupported` });
       return;
     }
     if (!safeEqual(m.token ?? "", this.opts.token)) {
+      this.opts.log?.("denied: invalid token");
       this.ch.send({ t: "denied", reason: "invalid token" });
       return;
     }
     this.authed = true;
+    this.opts.log?.(`paired \u2014 ${this.tools.size} ${this.tools.size === 1 ? "tool" : "tools"} advertised`);
     const tools = [...this.tools.values()].map(({ run: _run, ...decl }) => decl);
-    this.ch.send({ t: "welcome", tools, features: ["http-proxy"] });
+    this.ch.send({ t: "welcome", tools, features: ["http-proxy"], ...this.opts.info ? { info: this.opts.info } : {} });
   }
   /** Proxy a host HTTP request server-side. Restricted to LOOPBACK targets — the
    * sidecar must never be usable as an SSRF pivot to internal/metadata hosts. The
@@ -122,13 +126,16 @@ var SidecarServer = class {
   async onInvoke(m) {
     const tool = this.tools.get(m.name);
     if (!tool) {
+      this.opts.log?.(`invoke ${m.name}: unknown tool`);
       this.ch.send({ t: "invoke-result", id: m.id, ok: false, error: `unknown tool ${m.name}` });
       return;
     }
+    this.opts.log?.(`invoke ${m.name}`);
     try {
       const result = await tool.run(m.args, this.makeContext());
       this.ch.send({ t: "invoke-result", id: m.id, ok: true, result });
     } catch (e) {
+      this.opts.log?.(`invoke ${m.name} failed: ${errMessage(e)}`);
       this.ch.send({ t: "invoke-result", id: m.id, ok: false, error: errMessage(e) });
     }
   }
@@ -228,16 +235,42 @@ function wsChannel(ws) {
   };
 }
 
+// src/lanOrigin.ts
+function isPrivateLanOrigin(origin) {
+  let host;
+  try {
+    host = new URL(origin).hostname;
+  } catch {
+    return false;
+  }
+  const h = host.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+  if (h === "localhost" || h.endsWith(".localhost")) return true;
+  if (h.includes(":")) return h === "::1" || /^f[cd]/.test(h) || /^fe[89ab]/.test(h);
+  const m = h.match(/^(\d{1,3})\.(\d{1,3})\.\d{1,3}\.\d{1,3}$/);
+  if (!m) return false;
+  const a = Number(m[1]);
+  const b = Number(m[2]);
+  return a === 127 || a === 10 || a === 192 && b === 168 || a === 172 && b >= 16 && b <= 31 || a === 169 && b === 254;
+}
+
 // src/server.ts
 function startSidecar(opts) {
   const host = opts.host ?? "127.0.0.1";
   const allowed = new Set(opts.allowedOrigins ?? []);
-  const verifyClient = ({ origin }) => {
-    if (!origin) return true;
-    return allowed.has(origin);
+  const verifyClient = (info) => {
+    const origin = info.origin;
+    const ip = info.req.socket?.remoteAddress || "?";
+    const lan = !!origin && !!opts.allowLan && isPrivateLanOrigin(origin);
+    const ok = !origin || allowed.has(origin) || lan;
+    opts.log?.(ok ? `upgrade allowed \u2014 origin ${origin || "(native client)"}${lan ? " (LAN)" : ""} (${ip})` : `upgrade REFUSED \u2014 origin ${origin} not in allowlist [${[...allowed].join(", ") || "(none)"}]${opts.allowLan ? "" : " (pass --allow-lan to accept any LAN origin)"} (${ip})`);
+    return ok;
   };
-  const onConnection = (ws, _req) => {
-    new SidecarServer({ channel: wsChannel(ws), token: opts.token, tools: opts.tools });
+  const onConnection = (ws, req) => {
+    const origin = req.headers.origin || "(native client)";
+    const ip = req.socket.remoteAddress || "?";
+    opts.log?.(`client connected \u2014 ${origin} (${ip})`);
+    ws.on("close", () => opts.log?.(`client disconnected \u2014 ${origin}`));
+    new SidecarServer({ channel: wsChannel(ws), token: opts.token, tools: opts.tools, info: opts.info, log: opts.log });
   };
   if (opts.tls) {
     const httpsServer = createHttpsServer({ cert: opts.tls.cert, key: opts.tls.key });
@@ -502,9 +535,252 @@ async function loadOrCreateSelfSigned(extraHosts = []) {
   return { cert: pems.cert, key: pems.private, sans };
 }
 
+// src/tunnel/registry.ts
+var providers = /* @__PURE__ */ new Map();
+function registerTunnel(p) {
+  providers.set(p.id, p);
+}
+function getTunnel(id) {
+  const direct = providers.get(id);
+  if (direct) return direct;
+  for (const p of providers.values()) if (p.aliases?.includes(id)) return p;
+  return void 0;
+}
+function tunnelIds() {
+  return [...providers.keys()];
+}
+
+// src/tunnel/zrok.ts
+import { spawn as spawn2 } from "node:child_process";
+function extractShareUrl(s) {
+  const full = s.match(/https?:\/\/[A-Za-z0-9.-]+(?::\d+)?(?:\/[^\s"'\\]*)?/);
+  if (full) return full[0];
+  const ep = s.match(/endpoints:(?:\\[nrt]|\s)*([A-Za-z0-9][A-Za-z0-9.-]*\.[A-Za-z]{2,}(?:\/[^\s"'\\]*)?)/);
+  return ep ? `https://${ep[1]}` : null;
+}
+var START_TIMEOUT_MS = 25e3;
+function shareArgs(port, name) {
+  const a = ["share", "public", "--headless", "--backend-mode", "proxy"];
+  if (name) a.push("-n", `public:${name}`);
+  a.push(`http://localhost:${port}`);
+  return a;
+}
+var tail = (s, n = 6) => s.trim().split("\n").slice(-n).join("\n");
+function zrokBins() {
+  const env = process.env.ZROK_BIN?.trim();
+  return env ? [env] : ["zrok", "zrok2"];
+}
+function stopChild(child) {
+  return new Promise((res) => {
+    if (child.exitCode !== null || child.signalCode) {
+      res();
+      return;
+    }
+    const hard = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+      }
+      res();
+    }, 2e3);
+    child.once("exit", () => {
+      clearTimeout(hard);
+      res();
+    });
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      clearTimeout(hard);
+      res();
+    }
+  });
+}
+function reserveName(bin, name) {
+  return new Promise((res, rej) => {
+    const child = spawn2(bin, ["create", "name", name], { stdio: ["ignore", "ignore", "ignore"] });
+    let settled = false;
+    const done = (fn) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(t);
+      fn();
+    };
+    child.on("error", (e) => done(() => e?.code === "ENOENT" ? rej(e) : res()));
+    child.on("exit", () => done(() => res()));
+    const t = setTimeout(() => done(() => {
+      try {
+        child.kill();
+      } catch {
+      }
+      res();
+    }), 15e3);
+  });
+}
+async function startWith(bin, port, name) {
+  if (name) await reserveName(bin, name);
+  return new Promise((resolveHandle, reject) => {
+    const child = spawn2(bin, shareArgs(port, name), { stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    let settled = false;
+    const finish = (fn) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn();
+    };
+    const onData = (b) => {
+      out += b.toString();
+      const url = extractShareUrl(out);
+      if (url) finish(() => resolveHandle({ url, stop: () => stopChild(child) }));
+    };
+    child.stdout?.on("data", onData);
+    child.stderr?.on("data", onData);
+    child.on("error", (e) => finish(() => reject(e)));
+    child.on("exit", (code) => finish(() => reject(new Error(
+      `${bin} exited (code ${code}) before a share URL appeared \u2014 is the environment enabled? Run \`${bin} enable <token>\` once.
+${tail(out)}`
+    ))));
+    const timer = setTimeout(() => finish(() => {
+      void stopChild(child);
+      reject(new Error(`${bin} produced no share URL within ${START_TIMEOUT_MS / 1e3}s.
+${tail(out)}`));
+    }), START_TIMEOUT_MS);
+  });
+}
+var zrokProvider = {
+  id: "zrok",
+  description: "zrok public share (needs the zrok CLI [`zrok`/`zrok2`] installed + `enable <token>` run once \u2014 https://zrok.io)",
+  start({ port, name }) {
+    const bins = zrokBins();
+    const tryAt = (i) => {
+      if (i >= bins.length) {
+        return Promise.reject(new Error(
+          `zrok not found (tried: ${bins.join(", ")}). Install the zrok CLI (https://docs.zrok.io) and run its \`enable <token>\` once, or set ZROK_BIN to the binary name/path.`
+        ));
+      }
+      return startWith(bins[i], port, name).catch((e) => {
+        if (e?.code === "ENOENT") return tryAt(i + 1);
+        throw e;
+      });
+    };
+    return tryAt(0);
+  }
+};
+
+// src/tunnel/cloudflared.ts
+import { spawn as spawn3 } from "node:child_process";
+function extractTunnelUrl(s) {
+  const m = s.match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/i);
+  return m ? m[0] : null;
+}
+var START_TIMEOUT_MS2 = 25e3;
+function tunnelArgs(port, host = "localhost") {
+  return ["tunnel", "--no-autoupdate", "--url", `http://${host}:${port}`];
+}
+var tail2 = (s, n = 6) => s.trim().split("\n").slice(-n).join("\n");
+function cloudflaredBins() {
+  const env = process.env.CLOUDFLARED_BIN?.trim();
+  return env ? [env] : ["cloudflared"];
+}
+function stopChild2(child) {
+  return new Promise((res) => {
+    if (child.exitCode !== null || child.signalCode) {
+      res();
+      return;
+    }
+    const hard = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+      }
+      res();
+    }, 2e3);
+    child.once("exit", () => {
+      clearTimeout(hard);
+      res();
+    });
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      clearTimeout(hard);
+      res();
+    }
+  });
+}
+function startWith2(bin, port, host, log) {
+  return new Promise((resolveHandle, reject) => {
+    const child = spawn3(bin, tunnelArgs(port, host), { stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    let settled = false;
+    let tailBuf = "";
+    const finish = (fn) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn();
+    };
+    const onData = (b) => {
+      const text = b.toString();
+      if (!settled) {
+        out += text;
+        const url = extractTunnelUrl(out);
+        if (url) finish(() => resolveHandle({ url, stop: () => stopChild2(child) }));
+        return;
+      }
+      tailBuf += text;
+      let nl;
+      while ((nl = tailBuf.indexOf("\n")) >= 0) {
+        const line = tailBuf.slice(0, nl).replace(/\r$/, "").trim();
+        tailBuf = tailBuf.slice(nl + 1);
+        if (line) log?.(`cloudflared: ${line}`);
+      }
+    };
+    child.stdout?.on("data", onData);
+    child.stderr?.on("data", onData);
+    child.on("error", (e) => finish(() => reject(e)));
+    child.on("exit", (code) => {
+      if (settled) {
+        log?.(`cloudflared exited (code ${code}) \u2014 the tunnel is down`);
+        return;
+      }
+      finish(() => reject(new Error(`${bin} exited (code ${code}) before a tunnel URL appeared.
+${tail2(out)}`)));
+    });
+    const timer = setTimeout(() => finish(() => {
+      void stopChild2(child);
+      reject(new Error(`${bin} produced no tunnel URL within ${START_TIMEOUT_MS2 / 1e3}s.
+${tail2(out)}`));
+    }), START_TIMEOUT_MS2);
+  });
+}
+var cloudflaredProvider = {
+  id: "cloudflared",
+  aliases: ["cloudflare"],
+  description: "Cloudflare quick tunnel (needs the `cloudflared` CLI installed \u2014 https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/ \u2014 no account, no interstitial; URL is ephemeral)",
+  start({ port, host, log }) {
+    const bins = cloudflaredBins();
+    const tryAt = (i) => {
+      if (i >= bins.length) {
+        return Promise.reject(new Error(
+          `cloudflared not found (tried: ${bins.join(", ")}). Install the cloudflared CLI (https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/), or set CLOUDFLARED_BIN to the binary name/path.`
+        ));
+      }
+      return startWith2(bins[i], port, host || "localhost", log).catch((e) => {
+        if (e?.code === "ENOENT") return tryAt(i + 1);
+        throw e;
+      });
+    };
+    return tryAt(0);
+  }
+};
+
+// src/tunnel/index.ts
+registerTunnel(cloudflaredProvider);
+registerTunnel(zrokProvider);
+
 // src/cli.ts
 function parseArgs(argv) {
-  const out = { port: 4858, host: "127.0.0.1", root: process.cwd(), allowOrigins: [], allowShell: false, selfSigned: false };
+  const out = { port: 4858, host: "127.0.0.1", root: process.cwd(), allowOrigins: [], allowShell: false, allowLan: false, selfSigned: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--port") out.port = Number(argv[++i]);
@@ -512,9 +788,12 @@ function parseArgs(argv) {
     else if (a === "--root") out.root = resolve2(argv[++i]);
     else if (a === "--allow-origin") out.allowOrigins.push(argv[++i]);
     else if (a === "--allow-shell") out.allowShell = true;
+    else if (a === "--allow-lan") out.allowLan = true;
     else if (a === "--tls-cert") out.tlsCert = resolve2(argv[++i]);
     else if (a === "--tls-key") out.tlsKey = resolve2(argv[++i]);
     else if (a === "--self-signed") out.selfSigned = true;
+    else if (a === "--tunnel") out.tunnel = argv[++i];
+    else if (a === "--tunnel-name") out.tunnelName = argv[++i];
   }
   return out;
 }
@@ -534,15 +813,41 @@ async function main() {
     tls = { cert: ss.cert, key: ss.key };
     selfSigned = true;
   }
+  const tunnelProvider = args.tunnel ? getTunnel(args.tunnel) : void 0;
+  if (args.tunnel && !tunnelProvider) {
+    throw new Error(`unknown --tunnel "${args.tunnel}". Available: ${tunnelIds().join(", ") || "(none)"}`);
+  }
+  if (tunnelProvider) {
+    args.host = "127.0.0.1";
+    tls = void 0;
+    selfSigned = false;
+  }
   const allowedOrigins = [.../* @__PURE__ */ new Set([...DEFAULT_ALLOWED_ORIGINS, ...args.allowOrigins])];
+  const slog = (line) => {
+    process.stdout.write(`  [${(/* @__PURE__ */ new Date()).toTimeString().slice(0, 8)}] ${line}
+`);
+  };
   const handle = await startSidecar({
     port: args.port,
     host: args.host,
     token,
     tools: [...nodeFsTools(args.root), ...args.allowShell ? [nodeShellTool(args.root)] : []],
     allowedOrigins,
-    tls
+    tls,
+    // Advertised in the handshake so the host can show the working directory when
+    // browsing this sidecar as a file source.
+    info: { root: args.root, platform: process.platform },
+    log: slog,
+    allowLan: args.allowLan
   });
+  let tunnel = null;
+  let tunnelWss = null;
+  if (tunnelProvider) {
+    process.stdout.write(`starting ${tunnelProvider.id} tunnel${args.tunnelName ? ` (reserved name "${args.tunnelName}")` : ""}\u2026
+`);
+    tunnel = await tunnelProvider.start({ port: handle.port, host: handle.host, name: args.tunnelName, log: slog });
+    tunnelWss = tunnel.url.replace(/^http/, "ws");
+  }
   const scheme = handle.secure ? "wss" : "ws";
   const exposed = handle.host !== "127.0.0.1" && handle.host !== "localhost";
   const connectHosts = handle.host === "0.0.0.0" ? lanIPv4s().length ? lanIPv4s() : ["127.0.0.1"] : [handle.host];
@@ -553,8 +858,8 @@ async function main() {
       `  root:  ${args.root}`,
       `  tools: fs_read/write/list${args.allowShell ? " + shell_exec" : "  (shell off; pass --allow-shell to enable)"}`,
       `  token: ${token}  (also at ${tokenPath()})`,
-      `  connect at: ${connectUrls.join("  ")}`,
-      `  origins: ${allowedOrigins.join(", ")}${args.allowOrigins.length ? "" : "  (canonical defaults; pass --allow-origin to add dev/self-hosted)"}`,
+      tunnelWss ? `  connect at: ${tunnelWss}   (public ${args.tunnel} tunnel${args.tunnelName ? ", stable" : ""} \u2014 pair from any device with this URL + the token)` : `  connect at: ${connectUrls.join("  ")}`,
+      `  origins: ${allowedOrigins.join(", ")}${args.allowLan ? "  + any private-LAN origin (--allow-lan)" : args.allowOrigins.length ? "" : "  (canonical defaults; pass --allow-origin to add dev/self-hosted)"}`,
       selfSigned ? `  cert: self-signed (in ~/.corenel) \u2014 trust it once: open ${connectUrls.map((u) => u.replace(/^wss/, "https")).join("  or  ")} in this browser and accept the warning, then pair.` : null,
       exposed ? `  WARNING: bound to ${handle.host} (not loopback) \u2014 reachable off-box. The pairing token + Origin allowlist are the only protection; keep the token secret.` : null,
       !handle.secure && exposed ? `  NOTE: a browser on an https page cannot connect to ws:// \u2014 serve wss:// with --self-signed (or --tls-cert/--tls-key) for LAN pairing.` : null,
@@ -562,7 +867,10 @@ async function main() {
     ].filter((l) => l !== null).join("\n")
   );
   const shutdown = () => {
-    void handle.close().then(() => process.exit(0));
+    const closeServer = () => handle.close().then(() => process.exit(0));
+    if (tunnel) void tunnel.stop().catch(() => {
+    }).then(closeServer);
+    else void closeServer();
   };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corenel/sidecar",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "license": "Elastic-2.0",
   "description": "Prompd sidecar — a local capability server. Run it next to Prompd (prompd.app) so the browser app can reach your machine: local LLMs (Ollama/LM Studio/vLLM) without CORS, your filesystem, and (opt-in) shell.",