@corenel/sidecar 0.1.0

package/README.md

@@ -0,0 +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.

package/dist/cli.js

@@ -0,0 +1,574 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { resolve as resolve2 } from "node:path";
+import { readFileSync } from "node:fs";
+
+// src/server.ts
+import { WebSocketServer } from "ws";
+import { createServer as createHttpsServer } from "node:https";
+
+// ../protocol/sidecar.ts
+var SIDECAR_PROTOCOL = 1;
+function isLoopbackHost(host) {
+  const h = host.toLowerCase().replace(/^\[/, "").replace(/\]$/, "");
+  return h === "localhost" || h.endsWith(".localhost") || h === "::1" || /^127\./.test(h);
+}
+function errMessage(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+
+// ../harness/sidecar/server.ts
+function bytesToB64(bytes) {
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin);
+}
+function safeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+var SidecarServer = class {
+  ch;
+  opts;
+  tools = /* @__PURE__ */ new Map();
+  authed = false;
+  hostSeq = 0;
+  hostPending = /* @__PURE__ */ new Map();
+  constructor(opts) {
+    this.opts = opts;
+    this.ch = opts.channel;
+    for (const t of opts.tools) this.tools.set(t.name, t);
+    this.ch.onMessage((m) => this.onMessage(m));
+  }
+  onMessage(m) {
+    switch (m.t) {
+      case "hello":
+        this.onHello(m);
+        return;
+      case "invoke":
+        if (!this.authed) {
+          this.ch.send({ t: "invoke-result", id: m.id, ok: false, error: "not authenticated" });
+          return;
+        }
+        void this.onInvoke(m);
+        return;
+      case "host-call-result": {
+        const p = this.hostPending.get(m.id);
+        if (!p) return;
+        this.hostPending.delete(m.id);
+        if (m.ok) p.resolve(m.result);
+        else p.reject(new Error(m.error || "host call failed"));
+        return;
+      }
+      case "http-req":
+        if (!this.authed) {
+          this.ch.send({ t: "http-err", id: m.id, error: "not authenticated" });
+          return;
+        }
+        void this.onHttpReq(m);
+        return;
+      default:
+        return;
+    }
+  }
+  onHello(m) {
+    if (m.protocol !== SIDECAR_PROTOCOL) {
+      this.ch.send({ t: "denied", reason: `protocol ${m.protocol} unsupported` });
+      return;
+    }
+    if (!safeEqual(m.token ?? "", this.opts.token)) {
+      this.ch.send({ t: "denied", reason: "invalid token" });
+      return;
+    }
+    this.authed = true;
+    const tools = [...this.tools.values()].map(({ run: _run, ...decl }) => decl);
+    this.ch.send({ t: "welcome", tools, features: ["http-proxy"] });
+  }
+  /** 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
+   * response streams back (http-res -> http-chunk* -> http-end). */
+  async onHttpReq(m) {
+    try {
+      let u;
+      try {
+        u = new URL(m.url);
+      } catch {
+        throw new Error(`invalid URL: ${m.url}`);
+      }
+      if (u.protocol !== "http:" && u.protocol !== "https:") throw new Error("http(s) URLs only");
+      if (!isLoopbackHost(u.hostname)) throw new Error(`the sidecar proxy only reaches loopback hosts, not "${u.hostname}"`);
+      const res = await fetch(m.url, { method: m.method, headers: m.headers, body: m.body });
+      const headers = {};
+      res.headers.forEach((v, k) => {
+        headers[k] = v;
+      });
+      this.ch.send({ t: "http-res", id: m.id, status: res.status, statusText: res.statusText, headers });
+      if (res.body) {
+        const reader = res.body.getReader();
+        for (; ; ) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          if (value && value.length) this.ch.send({ t: "http-chunk", id: m.id, b64: bytesToB64(value) });
+        }
+      }
+      this.ch.send({ t: "http-end", id: m.id });
+    } catch (e) {
+      this.ch.send({ t: "http-err", id: m.id, error: errMessage(e) });
+    }
+  }
+  async onInvoke(m) {
+    const tool = this.tools.get(m.name);
+    if (!tool) {
+      this.ch.send({ t: "invoke-result", id: m.id, ok: false, error: `unknown tool ${m.name}` });
+      return;
+    }
+    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.ch.send({ t: "invoke-result", id: m.id, ok: false, error: errMessage(e) });
+    }
+  }
+  /** A ToolContext whose capabilities proxy back to the host (persist-nothing).
+   * The stores, the host's file workspace, and the user prompts (confirm/ask) all
+   * round-trip over the channel. confirm/ask default to allow/dismiss when the
+   * host wired no handler — the host already gated the tool call before dispatch,
+   * so an unwired secondary prompt must not deadlock the tool. */
+  makeContext() {
+    return {
+      signal: new AbortController().signal,
+      memory: this.memory,
+      kv: this.kv,
+      search: this.search,
+      sessions: this.sessions,
+      files: this.files,
+      confirm: this.confirm,
+      ask: this.ask
+    };
+  }
+  hostCall(provider, method, args) {
+    const id = ++this.hostSeq;
+    return new Promise((resolve3, reject) => {
+      this.hostPending.set(id, { resolve: resolve3, reject });
+      this.ch.send({ t: "host-call", id, provider, method, args });
+    });
+  }
+  memory = {
+    save: (text, tags) => this.hostCall("memory", "save", [text, tags]),
+    recall: (query, limit) => this.hostCall("memory", "recall", [query, limit]),
+    list: (limit) => this.hostCall("memory", "list", [limit]),
+    forget: (id) => this.hostCall("memory", "forget", [id])
+  };
+  kv = {
+    get: (key) => this.hostCall("kv", "get", [key]),
+    set: (key, value) => this.hostCall("kv", "set", [key, value]),
+    delete: (key) => this.hostCall("kv", "delete", [key]),
+    keys: (prefix) => this.hostCall("kv", "keys", [prefix])
+  };
+  search = {
+    searchPackages: (query) => this.hostCall("search", "searchPackages", [query])
+  };
+  sessions = {
+    create: (title, surface) => this.hostCall("sessions", "create", [title, surface]),
+    get: (id) => this.hostCall("sessions", "get", [id]),
+    list: (surface) => this.hostCall("sessions", "list", [surface]),
+    save: (session) => this.hostCall("sessions", "save", [session]),
+    rename: (id, title) => this.hostCall("sessions", "rename", [id, title]),
+    delete: (id) => this.hostCall("sessions", "delete", [id])
+  };
+  /** The host's file workspace, proxied. Metadata is a default — the methods are
+   * what a sidecar tool uses; onChange is a no-op (the host UI owns refresh). */
+  files = {
+    kind: "directory",
+    label: "host workspace",
+    isLocalDisk: false,
+    writable: true,
+    list: (dir) => this.hostCall("files", "list", [dir]),
+    read: (path) => this.hostCall("files", "read", [path]),
+    stat: (path) => this.hostCall("files", "stat", [path]),
+    write: (path, content) => this.hostCall("files", "write", [path, content]),
+    create: (path, content) => this.hostCall("files", "create", [path, content]),
+    remove: (path) => this.hostCall("files", "remove", [path]),
+    rename: (from, to) => this.hostCall("files", "rename", [from, to]),
+    search: (query) => this.hostCall("files", "search", [query]),
+    onChange: () => () => {
+    }
+  };
+  confirm = (req) => this.hostCall("confirm", "confirm", [req]).then((v) => v, () => true);
+  ask = (questions) => this.hostCall("ask", "ask", [questions]).then((v) => v, () => null);
+};
+
+// src/wsChannel.ts
+function wsChannel(ws) {
+  let handler = null;
+  ws.on("message", (data) => {
+    if (!handler) return;
+    try {
+      const text = typeof data === "string" ? data : String(data);
+      handler(JSON.parse(text));
+    } catch {
+    }
+  });
+  return {
+    send(msg) {
+      if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(msg));
+    },
+    onMessage(h) {
+      handler = h;
+    },
+    close() {
+      try {
+        ws.close();
+      } catch {
+      }
+    }
+  };
+}
+
+// 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 onConnection = (ws, _req) => {
+    new SidecarServer({ channel: wsChannel(ws), token: opts.token, tools: opts.tools });
+  };
+  if (opts.tls) {
+    const httpsServer = createHttpsServer({ cert: opts.tls.cert, key: opts.tls.key });
+    const wss2 = new WebSocketServer({ server: httpsServer, verifyClient });
+    wss2.on("connection", onConnection);
+    return new Promise((resolveHandle, reject) => {
+      httpsServer.on("error", reject);
+      httpsServer.listen(opts.port, host, () => {
+        const addr = httpsServer.address();
+        const boundPort = typeof addr === "object" && addr ? addr.port : opts.port;
+        opts.onListening?.({ host, port: boundPort, secure: true });
+        resolveHandle({
+          host,
+          port: boundPort,
+          secure: true,
+          close: () => new Promise((res) => wss2.close(() => httpsServer.close(() => res())))
+        });
+      });
+    });
+  }
+  const wss = new WebSocketServer({ host, port: opts.port, verifyClient });
+  wss.on("connection", onConnection);
+  return new Promise((resolveHandle, reject) => {
+    wss.on("error", reject);
+    wss.on("listening", () => {
+      const addr = wss.address();
+      const boundPort = typeof addr === "object" && addr ? addr.port : opts.port;
+      opts.onListening?.({ host, port: boundPort, secure: false });
+      resolveHandle({
+        host,
+        port: boundPort,
+        secure: false,
+        close: () => new Promise((res) => wss.close(() => res()))
+      });
+    });
+  });
+}
+
+// src/tools.ts
+import { promises as fs } from "node:fs";
+import { spawn } from "node:child_process";
+import { resolve, relative, isAbsolute, sep, dirname } from "node:path";
+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}`);
+  return abs;
+}
+async function assertRealWithinRoot(root, abs) {
+  const realRoot = await fs.realpath(root);
+  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}`);
+      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}`);
+      probe = parent;
+    }
+  }
+}
+var MAX_READ_BYTES = 16 * 1024 * 1024;
+function nodeFsTools(root) {
+  return [
+    {
+      name: "fs_read_file",
+      description: "Read a UTF-8 text file from the sidecar machine, relative to its root.",
+      parameters: {
+        type: "object",
+        properties: { path: { type: "string", description: "path relative to the sidecar root" } },
+        required: ["path"]
+      },
+      namespace: "fs",
+      async run(args) {
+        const abs = confine(root, String(args.path ?? ""));
+        await assertRealWithinRoot(root, 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, "utf8");
+      }
+    },
+    {
+      name: "fs_write_file",
+      description: "Write a UTF-8 text file on the sidecar machine, relative to its root.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "path relative to the sidecar root" },
+          content: { type: "string" }
+        },
+        required: ["path", "content"]
+      },
+      namespace: "fs",
+      mutates: true,
+      async run(args) {
+        const abs = confine(root, String(args.path ?? ""));
+        await fs.mkdir(dirname(abs), { recursive: true });
+        await assertRealWithinRoot(root, abs);
+        await fs.writeFile(abs, String(args.content ?? ""), "utf8");
+        return `wrote ${args.path}`;
+      }
+    },
+    {
+      name: "fs_list_dir",
+      description: "List the entries of a directory on the sidecar machine, relative to its root.",
+      parameters: {
+        type: "object",
+        properties: { path: { type: "string", description: 'directory relative to the sidecar root (default ".")' } }
+      },
+      namespace: "fs",
+      async run(args) {
+        const abs = confine(root, String(args.path ?? "."));
+        await assertRealWithinRoot(root, abs);
+        const entries = await fs.readdir(abs, { withFileTypes: true });
+        return entries.map((e) => e.isDirectory() ? `${e.name}/` : e.name).join("\n");
+      }
+    }
+  ];
+}
+var DEFAULT_TIMEOUT_MS = 6e4;
+var MAX_TIMEOUT_MS = 3e5;
+var MAX_OUTPUT = 1e5;
+function nodeShellTool(root) {
+  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.",
+    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 ".")' },
+        timeout_ms: { type: "number", description: `max run time in ms (default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS})` }
+      },
+      required: ["command"]
+    },
+    namespace: "shell",
+    mutates: true,
+    permission: "ask",
+    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 timeout = Math.min(Math.max(Number(args.timeout_ms) || DEFAULT_TIMEOUT_MS, 1), MAX_TIMEOUT_MS);
+      return runShell(command, cwd, timeout);
+    }
+  };
+}
+function runShell(command, cwd, timeout) {
+  return new Promise((resolveOut) => {
+    const isWin = process.platform === "win32";
+    const [shell, shellArgs] = isWin ? ["cmd.exe", ["/d", "/s", "/c", command]] : ["/bin/sh", ["-c", command]];
+    const child = spawn(shell, shellArgs, { cwd, windowsHide: true });
+    let out = "";
+    let truncated = false;
+    let timedOut = false;
+    const append = (chunk) => {
+      if (truncated) return;
+      out += chunk.toString("utf8");
+      if (out.length > MAX_OUTPUT) {
+        out = out.slice(0, MAX_OUTPUT);
+        truncated = true;
+      }
+    };
+    child.stdout.on("data", append);
+    child.stderr.on("data", append);
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeout);
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      resolveOut(`Error: failed to start command: ${e instanceof Error ? e.message : String(e)}`);
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      const status = timedOut ? `timed out after ${timeout}ms (killed)` : `exit ${code ?? "null"}${signal ? ` (signal ${signal})` : ""}`;
+      const body = out.trim() || "(no output)";
+      resolveOut(`${status}
+${truncated ? "[output truncated]\n" : ""}${body}`);
+    });
+  });
+}
+
+// src/token.ts
+import { promises as fs2 } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function corenelDir() {
+  return join(homedir(), ".corenel");
+}
+function tokenPath() {
+  return join(corenelDir(), "daemon.token");
+}
+async function loadOrCreateToken() {
+  const path = tokenPath();
+  try {
+    const existing = (await fs2.readFile(path, "utf8")).trim();
+    if (existing) return existing;
+  } catch {
+  }
+  await fs2.mkdir(corenelDir(), { recursive: true });
+  const token = randomBytes(32).toString("hex");
+  await fs2.writeFile(path, token + "\n", { mode: 384 });
+  try {
+    await fs2.chmod(path, 384);
+  } catch {
+  }
+  return token;
+}
+
+// src/cert.ts
+import { promises as fs3 } from "node:fs";
+import { networkInterfaces } from "node:os";
+import { join as join2 } from "node:path";
+import selfsigned from "selfsigned";
+function lanIPv4s() {
+  const out = [];
+  for (const ifaces of Object.values(networkInterfaces())) {
+    for (const ni of ifaces ?? []) {
+      if (ni.family === "IPv4" && !ni.internal) out.push(ni.address);
+    }
+  }
+  return [...new Set(out)];
+}
+var certPath = () => join2(corenelDir(), "sidecar.crt");
+var keyPath = () => join2(corenelDir(), "sidecar.key");
+var sansPath = () => join2(corenelDir(), "sidecar.sans.json");
+function isIp(s) {
+  return /^\d{1,3}(?:\.\d{1,3}){3}$/.test(s) || s.includes(":");
+}
+async function loadOrCreateSelfSigned(extraHosts = []) {
+  const sans = [...new Set(["localhost", "127.0.0.1", "::1", ...lanIPv4s(), ...extraHosts].filter(Boolean))];
+  try {
+    const have = JSON.parse(await fs3.readFile(sansPath(), "utf8"));
+    if (Array.isArray(have) && sans.every((s) => have.includes(s))) {
+      const [cert, key] = await Promise.all([fs3.readFile(certPath(), "utf8"), fs3.readFile(keyPath(), "utf8")]);
+      return { cert, key, sans: have };
+    }
+  } catch {
+  }
+  const altNames = sans.map((h) => isIp(h) ? { type: 7, ip: h } : { type: 2, value: h });
+  const pems = selfsigned.generate([{ name: "commonName", value: sans[0] }], {
+    days: 3650,
+    keySize: 2048,
+    algorithm: "sha256",
+    extensions: [{ name: "subjectAltName", altNames }]
+  });
+  await fs3.mkdir(corenelDir(), { recursive: true });
+  await fs3.writeFile(certPath(), pems.cert, { mode: 384 });
+  await fs3.writeFile(keyPath(), pems.private, { mode: 384 });
+  await fs3.writeFile(sansPath(), JSON.stringify(sans));
+  return { cert: pems.cert, key: pems.private, sans };
+}
+
+// src/cli.ts
+function parseArgs(argv) {
+  const out = { port: 4858, host: "127.0.0.1", root: process.cwd(), allowOrigins: [], allowShell: false, selfSigned: false };
+  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 === "--allow-origin") out.allowOrigins.push(argv[++i]);
+    else if (a === "--allow-shell") out.allowShell = 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;
+  }
+  return out;
+}
+var isIp2 = (s) => /^\d{1,3}(?:\.\d{1,3}){3}$/.test(s);
+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));
+  const token = await loadOrCreateToken();
+  if (args.tlsCert && !args.tlsKey || !args.tlsCert && args.tlsKey) {
+    throw new Error("TLS needs both --tls-cert and --tls-key");
+  }
+  let tls = args.tlsCert && args.tlsKey ? { cert: readFileSync(args.tlsCert, "utf8"), key: readFileSync(args.tlsKey, "utf8") } : void 0;
+  let selfSigned = false;
+  if (!tls && args.selfSigned) {
+    const extra = isIp2(args.host) && args.host !== "127.0.0.1" ? [args.host] : [];
+    const ss = await loadOrCreateSelfSigned(extra);
+    tls = { cert: ss.cert, key: ss.key };
+    selfSigned = true;
+  }
+  const allowedOrigins = [.../* @__PURE__ */ new Set([...DEFAULT_ALLOWED_ORIGINS, ...args.allowOrigins])];
+  const handle = await startSidecar({
+    port: args.port,
+    host: args.host,
+    token,
+    tools: [...nodeFsTools(args.root), ...args.allowShell ? [nodeShellTool(args.root)] : []],
+    allowedOrigins,
+    tls
+  });
+  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];
+  const connectUrls = connectHosts.map((h) => `${scheme}://${h}:${handle.port}`);
+  process.stdout.write(
+    [
+      `corenel sidecar listening on ${scheme}://${handle.host}:${handle.port}`,
+      `  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)"}`,
+      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")
+  );
+  const shutdown = () => {
+    void handle.close().then(() => process.exit(0));
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+main().catch((e) => {
+  process.stderr.write(`corenel-sidecar: ${e instanceof Error ? e.message : String(e)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +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"
+  }
+}