@corenel/sidecar 0.1.0 → 0.1.2

package/README.md

@@ -1,40 +1,40 @@
-# @corenel/sidecar
-
-A small local capability server for [Prompd](https://prompd.app). Run it next to the
-web app and the browser can reach your machine — most usefully, your **local LLMs**
-(Ollama, LM Studio, vLLM) **without CORS**, plus your filesystem and (opt-in) shell.
-
-It runs only while the command is open, binds to loopback by default, and pairs with
-a token the app reads once.
-
-## Use
-
-In Prompd, open **Connect a sidecar** and follow the steps, or run it directly:
-
-```bash
-npx @corenel/sidecar --allow-origin https://prompd.app
-```
-
-It prints a pairing token; paste that into the app. The `--allow-origin` flag must
-match the site you're connecting from (the app fills it in for you).
-
-## Options
-
-| Flag | Default | What |
-|------|---------|------|
-| `--allow-origin <url>` | _(none)_ | Browser origin allowed to connect. Required for a web page. Repeatable. |
-| `--port <n>` | `4858` | Port to listen on. |
-| `--root <dir>` | cwd | Root the file tools are confined to. |
-| `--allow-shell` | off | Enable the `shell_exec` tool (RCE on your machine — opt-in). |
-| `--host <addr>` | `127.0.0.1` | Bind address. Non-loopback is reachable off-box; keep the token secret. |
-| `--tls-cert <f>` `--tls-key <f>` | _(none)_ | Serve `wss://` (needed for a remote sidecar from an https page). |
-
-## Security
-
-- Loopback by default; a browser connection requires both the pairing token **and** an
-  allowed Origin.
-- The HTTP proxy (for local LLMs) only reaches **loopback** hosts — it can't be used as
-  an SSRF pivot to internal services.
-- `shell_exec` is off unless you pass `--allow-shell`.
-
-Licensed under Elastic-2.0.
+# @corenel/sidecar
+
+A small local capability server for [Prompd](https://prompd.app). Run it next to the
+web app and the browser can reach your machine — most usefully, your **local LLMs**
+(Ollama, LM Studio, vLLM) **without CORS**, plus your filesystem and (opt-in) shell.
+
+It runs only while the command is open, binds to loopback by default, and pairs with
+a token the app reads once.
+
+## Use
+
+In Prompd, open **Connect a sidecar** and follow the steps, or run it directly:
+
+```bash
+npx @corenel/sidecar --allow-origin https://prompd.app
+```
+
+It prints a pairing token; paste that into the app. The `--allow-origin` flag must
+match the site you're connecting from (the app fills it in for you).
+
+## Options
+
+| Flag | Default | What |
+|------|---------|------|
+| `--allow-origin <url>` | _(none)_ | Browser origin allowed to connect. Required for a web page. Repeatable. |
+| `--port <n>` | `4858` | Port to listen on. |
+| `--root <dir>` | cwd | Root the file tools are confined to. |
+| `--allow-shell` | off | Enable the `shell_exec` tool (RCE on your machine — opt-in). |
+| `--host <addr>` | `127.0.0.1` | Bind address. Non-loopback is reachable off-box; keep the token secret. |
+| `--tls-cert <f>` `--tls-key <f>` | _(none)_ | Serve `wss://` (needed for a remote sidecar from an https page). |
+
+## Security
+
+- Loopback by default; a browser connection requires both the pairing token **and** an
+  allowed Origin.
+- The HTTP proxy (for local LLMs) only reaches **loopback** hosts — it can't be used as
+  an SSRF pivot to internal services.
+- `shell_exec` is off unless you pass `--allow-shell`.
+
+Licensed under Elastic-2.0.

package/dist/cli.js

@@ -1,8 +1,10 @@
 #!/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";
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
+import { spawn as spawn4 } from "node:child_process";
 
 // src/server.ts
 import { WebSocketServer } from "ws";
@@ -76,16 +78,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 +127,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 +236,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 });
@@ -284,42 +318,47 @@ function withinRoot(root, abs) {
   const rel = relative(root, abs);
   return rel === "" || !rel.startsWith("..") && !isAbsolute(rel) && rel.split(sep)[0] !== "..";
 }
-function confine(root, p) {
-  const abs = resolve(root, p);
-  if (!withinRoot(root, abs)) throw new Error(`path escapes the sidecar root: ${p}`);
+function activeRoot(roots, rootArg) {
+  const r = typeof rootArg === "string" ? rootArg : "";
+  return roots.includes(r) ? r : roots[0];
+}
+function confine(roots, rootArg, p) {
+  const abs = resolve(activeRoot(roots, rootArg), p);
+  if (!roots.some((root) => withinRoot(root, abs))) throw new Error(`path escapes the sidecar roots: ${p}`);
   return abs;
 }
-async function assertRealWithinRoot(root, abs) {
-  const realRoot = await fs.realpath(root);
+async function assertRealWithinRoot(roots, abs) {
+  const realRoots = await Promise.all(roots.map((r) => fs.realpath(r)));
   let probe = abs;
   for (; ; ) {
     try {
       const real = await fs.realpath(probe);
-      if (!withinRoot(realRoot, real)) throw new Error(`path escapes the sidecar root via symlink: ${abs}`);
+      if (!realRoots.some((rr) => withinRoot(rr, real))) throw new Error(`path escapes the sidecar roots via symlink: ${abs}`);
       return;
     } catch (e) {
       if (e instanceof Error && e.message.includes("via symlink")) throw e;
       const parent = dirname(probe);
-      if (parent === probe) throw new Error(`cannot resolve path under the sidecar root: ${abs}`);
+      if (parent === probe) throw new Error(`cannot resolve path under the sidecar roots: ${abs}`);
       probe = parent;
     }
   }
 }
+var ROOT_PARAM = { type: "string", description: "which pre-approved root to resolve the path against (its absolute path; defaults to the primary root)" };
 var MAX_READ_BYTES = 16 * 1024 * 1024;
-function nodeFsTools(root) {
+function nodeFsTools(roots) {
   return [
     {
       name: "fs_read_file",
-      description: "Read a UTF-8 text file from the sidecar machine, relative to its root.",
+      description: "Read a UTF-8 text file from the sidecar machine, relative to a pre-approved root.",
       parameters: {
         type: "object",
-        properties: { path: { type: "string", description: "path relative to the sidecar root" } },
+        properties: { path: { type: "string", description: "path relative to the chosen root" }, root: ROOT_PARAM },
         required: ["path"]
       },
       namespace: "fs",
       async run(args) {
-        const abs = confine(root, String(args.path ?? ""));
-        await assertRealWithinRoot(root, abs);
+        const abs = confine(roots, args.root, String(args.path ?? ""));
+        await assertRealWithinRoot(roots, abs);
         const st = await fs.stat(abs);
         if (st.size > MAX_READ_BYTES) {
           throw new Error(`file too large to read (${st.size} bytes; max ${MAX_READ_BYTES})`);
@@ -329,36 +368,56 @@ function nodeFsTools(root) {
     },
     {
       name: "fs_write_file",
-      description: "Write a UTF-8 text file on the sidecar machine, relative to its root.",
+      description: "Write a UTF-8 text file on the sidecar machine, relative to a pre-approved root.",
       parameters: {
         type: "object",
         properties: {
-          path: { type: "string", description: "path relative to the sidecar root" },
-          content: { type: "string" }
+          path: { type: "string", description: "path relative to the chosen root" },
+          content: { type: "string" },
+          root: ROOT_PARAM
         },
         required: ["path", "content"]
       },
       namespace: "fs",
       mutates: true,
       async run(args) {
-        const abs = confine(root, String(args.path ?? ""));
+        const abs = confine(roots, args.root, String(args.path ?? ""));
         await fs.mkdir(dirname(abs), { recursive: true });
-        await assertRealWithinRoot(root, abs);
+        await assertRealWithinRoot(roots, abs);
         await fs.writeFile(abs, String(args.content ?? ""), "utf8");
         return `wrote ${args.path}`;
       }
     },
+    {
+      name: "fs_read_bytes",
+      description: "Read a file from the sidecar machine as base64 (for previewing media/binary the text read would mangle), relative to a pre-approved root.",
+      parameters: {
+        type: "object",
+        properties: { path: { type: "string", description: "path relative to the chosen root" }, root: ROOT_PARAM },
+        required: ["path"]
+      },
+      namespace: "fs",
+      async run(args) {
+        const abs = confine(roots, args.root, String(args.path ?? ""));
+        await assertRealWithinRoot(roots, abs);
+        const st = await fs.stat(abs);
+        if (st.size > MAX_READ_BYTES) {
+          throw new Error(`file too large to read (${st.size} bytes; max ${MAX_READ_BYTES})`);
+        }
+        return (await fs.readFile(abs)).toString("base64");
+      }
+    },
     {
       name: "fs_list_dir",
-      description: "List the entries of a directory on the sidecar machine, relative to its root.",
+      description: "List the entries of a directory on the sidecar machine, relative to a pre-approved root.",
       parameters: {
         type: "object",
-        properties: { path: { type: "string", description: 'directory relative to the sidecar root (default ".")' } }
+        properties: { path: { type: "string", description: 'directory relative to the chosen root (default ".")' }, root: ROOT_PARAM }
       },
       namespace: "fs",
       async run(args) {
-        const abs = confine(root, String(args.path ?? "."));
-        await assertRealWithinRoot(root, abs);
+        const abs = confine(roots, args.root, String(args.path ?? "."));
+        await assertRealWithinRoot(roots, abs);
         const entries = await fs.readdir(abs, { withFileTypes: true });
         return entries.map((e) => e.isDirectory() ? `${e.name}/` : e.name).join("\n");
       }
@@ -368,15 +427,16 @@ function nodeFsTools(root) {
 var DEFAULT_TIMEOUT_MS = 6e4;
 var MAX_TIMEOUT_MS = 3e5;
 var MAX_OUTPUT = 1e5;
-function nodeShellTool(root) {
+function nodeShellTool(roots) {
   return {
     name: "shell_exec",
-    description: "Run a shell command on the sidecar machine (commands a browser cannot spawn). Runs in the sidecar root by default; returns the exit status plus combined stdout/stderr.",
+    description: "Run a shell command on the sidecar machine (commands a browser cannot spawn). Runs in a pre-approved root by default; returns the exit status plus combined stdout/stderr.",
     parameters: {
       type: "object",
       properties: {
         command: { type: "string", description: "the shell command line to run" },
-        cwd: { type: "string", description: 'working directory relative to the sidecar root (default ".")' },
+        cwd: { type: "string", description: 'working directory relative to the chosen root (default ".")' },
+        root: ROOT_PARAM,
         timeout_ms: { type: "number", description: `max run time in ms (default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS})` }
       },
       required: ["command"]
@@ -387,8 +447,8 @@ function nodeShellTool(root) {
     async run(args) {
       const command = String(args.command ?? "").trim();
       if (!command) return "Error: no command given";
-      const cwd = confine(root, String(args.cwd ?? "."));
-      await assertRealWithinRoot(root, cwd);
+      const cwd = confine(roots, args.root, String(args.cwd ?? "."));
+      await assertRealWithinRoot(roots, cwd);
       const timeout = Math.min(Math.max(Number(args.timeout_ms) || DEFAULT_TIMEOUT_MS, 1), MAX_TIMEOUT_MS);
       return runShell(command, cwd, timeout);
     }
@@ -502,26 +562,294 @@ 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", "--protocol", "http2", "--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", roots: [], allowOrigins: [], allowShell: false, allowLan: false, selfSigned: false, open: false, appUrl: "https://prompd.app" };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--port") out.port = Number(argv[++i]);
     else if (a === "--host") out.host = argv[++i];
-    else if (a === "--root") out.root = resolve2(argv[++i]);
+    else if (a === "--root") out.roots.push(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];
+    else if (a === "--open") out.open = true;
+    else if (a === "--app-url") out.appUrl = argv[++i];
   }
   return out;
 }
 var isIp2 = (s) => /^\d{1,3}(?:\.\d{1,3}){3}$/.test(s);
+function openBrowser(url) {
+  const p = process.platform;
+  const cmd = p === "darwin" ? "open" : p === "win32" ? "cmd" : "xdg-open";
+  const args = p === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn4(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+  }
+}
 var DEFAULT_ALLOWED_ORIGINS = ["https://prompd.app", "https://www.prompd.app", "https://prmd.ai", "https://www.prmd.ai"];
 async function main() {
   const args = parseArgs(process.argv.slice(2));
+  if (args.roots.length === 0) args.roots = [process.cwd()];
+  args.roots = [...new Set(args.roots)];
+  for (const r of args.roots) {
+    let ok = false;
+    try {
+      ok = statSync(r).isDirectory();
+    } catch {
+      ok = false;
+    }
+    if (!ok) throw new Error(`--root is not a directory: ${r}`);
+  }
   const token = await loadOrCreateToken();
   if (args.tlsCert && !args.tlsKey || !args.tlsCert && args.tlsKey) {
     throw new Error("TLS needs both --tls-cert and --tls-key");
@@ -534,15 +862,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)] : []],
+    tools: [...nodeFsTools(args.roots), ...args.allowShell ? [nodeShellTool(args.roots)] : []],
     allowedOrigins,
-    tls
+    tls,
+    // Advertised in the handshake so the host can show the available working
+    // directories and let the user pick one (confined to the union of roots).
+    info: { root: args.roots[0], roots: args.roots, 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];
@@ -550,19 +904,29 @@ async function main() {
   process.stdout.write(
     [
       `corenel sidecar listening on ${scheme}://${handle.host}:${handle.port}`,
-      `  root:  ${args.root}`,
+      args.roots.length === 1 ? `  root:  ${args.roots[0]}` : `  roots: ${args.roots.join("\n         ")}   (${args.roots.length} approved; pick the active one in the app)`,
       `  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,
       ""
     ].filter((l) => l !== null).join("\n")
   );
+  if (args.open) {
+    const loopback = `${handle.secure ? "wss" : "ws"}://127.0.0.1:${handle.port}`;
+    const target = `${args.appUrl.replace(/\/$/, "")}/studio#sidecar=${encodeURIComponent(loopback)}&token=${encodeURIComponent(token)}`;
+    process.stdout.write(`  opening ${args.appUrl} (auto-pairing)\u2026
+`);
+    openBrowser(target);
+  }
   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,41 +1,41 @@
-{
-  "name": "@corenel/sidecar",
-  "version": "0.1.0",
-  "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.",
-  "keywords": ["prompd", "corenel", "sidecar", "ollama", "local-llm", "cors"],
-  "bin": {
-    "corenel-sidecar": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "node build.mjs",
-    "prepublishOnly": "node build.mjs",
-    "start": "tsx src/cli.ts",
-    "typecheck": "tsc --noEmit",
-    "verify": "tsx src/verify.ts"
-  },
-  "dependencies": {
-    "selfsigned": "^2.4.1",
-    "ws": "^8.18.0"
-  },
-  "devDependencies": {
-    "@corenel/protocol": "workspace:*",
-    "@corenel/harness": "workspace:*",
-    "@types/node": "^24.13.1",
-    "@types/ws": "^8.5.13",
-    "esbuild": "^0.21.5",
-    "tsx": "^4.19.2",
-    "typescript": "^5.9.3"
-  }
-}
+{
+  "name": "@corenel/sidecar",
+  "version": "0.1.2",
+  "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.",
+  "keywords": ["prompd", "corenel", "sidecar", "ollama", "local-llm", "cors"],
+  "bin": {
+    "corenel-sidecar": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepublishOnly": "node build.mjs",
+    "start": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "verify": "tsx src/verify.ts"
+  },
+  "dependencies": {
+    "selfsigned": "^2.4.1",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@corenel/protocol": "workspace:*",
+    "@corenel/harness": "workspace:*",
+    "@types/node": "^24.13.1",
+    "@types/ws": "^8.5.13",
+    "esbuild": "^0.21.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3"
+  }
+}