sidebranch 0.2.0

package/src/daemon.js

@@ -0,0 +1,323 @@
+/**
+ * daemon.js — the sidecar HTTP server.
+ *
+ * Invariants (not configurable):
+ *   - Binds 127.0.0.1 only.
+ *   - Rejects any request whose peer socket is not loopback.
+ *   - Rejects any request whose Host header is not loopback (DNS rebinding).
+ *   - Rejects any request whose Origin is present and not loopback.
+ *   - Every /api/* request requires the session bearer token.
+ *   - Serves only embedded assets; no filesystem paths are derived from URLs.
+ *   - /handshake and the three assets are unauthenticated by necessity: they
+ *     bootstrap the token. Everything under /api/* requires it.
+ *   - Responds with strict security headers; the shell page carries a CSP.
+ */
+
+import http from "node:http";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  generateToken, tokenMatches,
+  isLoopbackAddress, isAllowedHostHeader, isAllowedOrigin,
+  isValidPort,
+} from "./security.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ASSETS = path.join(__dirname, "assets");
+
+/**
+ * The /api/* contract version, reported by GET /handshake.
+ *
+ * The npm package and the browser extension update on different clocks and
+ * will drift. Bump this ONLY when a change would break an older widget —
+ * adding a field to a response is not a break, changing or removing one is.
+ */
+export const API_VERSION = 1;
+
+const VERSION = JSON.parse(
+  await fs.readFile(new URL("../package.json", import.meta.url), "utf8")
+).version;
+
+export class Daemon {
+  constructor({ manager, port = 49400 }) {
+    this.manager = manager;
+    this.port = port;
+    // The shell frames panes from this origin, so panes are probed against it.
+    this.manager.daemonPort = port;
+    this.token = generateToken();
+    this.sseClients = new Set();
+    this.server = null;
+
+    this.manager.on("event", (ev) => this.broadcast(ev));
+  }
+
+  async start() {
+    // The widget ships as core + a boot that supplies credentials; the tag
+    // channel's boot is the one with placeholders in it. Concatenated here
+    // rather than at request time so a malformed asset fails at startup.
+    const [core, bootTag] = await Promise.all([
+      fs.readFile(path.join(ASSETS, "widget-core.js"), "utf8"),
+      fs.readFile(path.join(ASSETS, "boot-tag.js"), "utf8"),
+    ]);
+    this.widgetSrc = `${core}\n${bootTag}`;
+    this.shellSrc = await fs.readFile(path.join(ASSETS, "shell.html"), "utf8");
+    this.fontSrc = await fs.readFile(path.join(ASSETS, "geist-pixel.woff2"));
+
+    this.server = http.createServer((req, res) => {
+      this.handle(req, res).catch((err) => {
+        if (!res.headersSent) json(res, 500, { error: err.message, code: err.code ?? "EINTERNAL" });
+      });
+    });
+    // Refuse to ever listen on a non-loopback interface.
+    await new Promise((resolve, reject) => {
+      this.server.once("error", reject);
+      this.server.listen(this.port, "127.0.0.1", resolve);
+    });
+    return this;
+  }
+
+  async stop() {
+    for (const res of this.sseClients) res.end();
+    await new Promise((r) => this.server?.close(r));
+    await this.manager.shutdown();
+  }
+
+  broadcast(ev) {
+    const line = `data: ${JSON.stringify(ev)}\n\n`;
+    for (const res of this.sseClients) res.write(line);
+  }
+
+  /* ------------------------------ gatekeeping ----------------------------- */
+
+  gate(req, res) {
+    const peer = req.socket.remoteAddress;
+    if (!isLoopbackAddress(peer)) {
+      res.writeHead(403).end();
+      return false;
+    }
+    if (!isAllowedHostHeader(req.headers.host)) {
+      json(res, 403, { error: "Host not allowed", code: "EHOST" });
+      return false;
+    }
+    const origin = req.headers.origin;
+    if (!isAllowedOrigin(origin)) {
+      json(res, 403, { error: "Origin not allowed", code: "EORIGIN" });
+      return false;
+    }
+    // CORS: only ever reflect loopback origins. Everyone else gets nothing.
+    if (origin) {
+      res.setHeader("Access-Control-Allow-Origin", origin);
+      res.setHeader("Vary", "Origin");
+      res.setHeader("Access-Control-Allow-Headers", "authorization, content-type");
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+      res.setHeader("Access-Control-Max-Age", "600");
+    }
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("Referrer-Policy", "no-referrer");
+    res.setHeader("Cross-Origin-Resource-Policy", "same-site");
+    return true;
+  }
+
+  authed(req) {
+    const h = req.headers.authorization || "";
+    const m = /^Bearer\s+([a-f0-9]{64})$/i.exec(h);
+    return m ? tokenMatches(this.token, m[1]) : false;
+  }
+
+  /* -------------------------------- routing ------------------------------- */
+
+  async handle(req, res) {
+    if (!this.gate(req, res)) return;
+    if (req.method === "OPTIONS") return res.writeHead(204).end();
+
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const route = `${req.method} ${url.pathname}`;
+
+    // -- Assets (no token needed to fetch; tokens are *delivered* by these,
+    //    and delivery is safe because the gate above already guarantees a
+    //    loopback peer, loopback Host, and loopback-or-absent Origin). A
+    //    cross-origin remote page cannot read these responses: fetch() is
+    //    blocked by CORS above, and <script src> keeps the token inside the
+    //    widget's closure where the embedding page cannot reach it.
+    if (route === "GET /widget.js") return this.serveWidget(res);
+    if (route === "GET /shell") return this.serveShell(res);
+    // Unauthenticated for the same reason as the two above, plus a harder
+    // constraint: a browser's @font-face fetch can't carry an Authorization
+    // header at all, so this could never be gated by the bearer token even
+    // if we wanted it to be. Unlike widget.js/shell (no-store — they embed a
+    // token that rotates every run), this file never changes for a given
+    // version of the tool, so it's cached aggressively.
+    if (route === "GET /geist-pixel.woff2") return this.serveFont(res);
+    if (route === "GET /handshake") return this.serveHandshake(res);
+    if (route === "GET /healthz") return json(res, 200, { ok: true });
+
+    if (!url.pathname.startsWith("/api/")) return json(res, 404, { error: "Not found" });
+    if (!this.authed(req)) return json(res, 401, { error: "Missing or invalid token", code: "EAUTH" });
+
+    if (route === "GET /api/state") return json(res, 200, await this.manager.state());
+    if (route === "GET /api/events") return this.serveEvents(req, res);
+    const logMatch = req.method === "GET" && /^\/api\/pane\/([^/]+)\/log$/.exec(url.pathname);
+    if (logMatch) {
+      const info = this.manager.getPaneLog(logMatch[1]);
+      if (!info) return json(res, 404, { error: "Unknown pane", code: "EBADPANE" });
+      return json(res, 200, info);
+    }
+    if (route === "POST /api/fetch") {
+      await this.manager.fetch();
+      return json(res, 200, { ok: true });
+    }
+    if (route === "POST /api/pane") {
+      const body = await readJson(req);
+      const { pane, branch, discard } = body ?? {};
+      try {
+        const info = await this.manager.ensurePane(String(pane), String(branch), { discard: discard === true });
+        return json(res, 200, info);
+      } catch (err) {
+        const status = err.code === "EBADREF" || err.code === "EBADPANE" ? 400
+          : err.code === "EDIRTY" || err.code === "EBUSYTREE" ? 409 : 500;
+        return json(res, status, { error: err.message, code: err.code ?? "EINTERNAL" });
+      }
+    }
+    if (route === "POST /api/pane/stop") {
+      const { pane } = (await readJson(req)) ?? {};
+      await this.manager.stopPane(String(pane));
+      return json(res, 200, { ok: true });
+    }
+    if (route === "POST /api/pane/destroy") {
+      const { pane } = (await readJson(req)) ?? {};
+      await this.manager.destroyPane(String(pane));
+      return json(res, 200, { ok: true });
+    }
+    return json(res, 404, { error: "Not found" });
+  }
+
+  serveWidget(res) {
+    res.setHeader("Content-Type", "text/javascript; charset=utf-8");
+    res.setHeader("Cache-Control", "no-store");
+    if (!this.manager.config.widget) {
+      return res.end("/* sidebranch widget disabled via .sidebranch.json */\n");
+    }
+    const src = this.widgetSrc
+      .replaceAll("__SIDEBRANCH_TOKEN__", this.token)
+      .replaceAll("__SIDEBRANCH_PORT__", String(this.port));
+    res.end(src);
+  }
+
+  /**
+   * Credential bootstrap for callers that cannot consume a rendered template
+   * — i.e. the browser extension, whose content script ships `widget-core.js`
+   * in its own package because Manifest V3 forbids executing remotely-fetched
+   * code, and so has nowhere for a substituted token to arrive.
+   *
+   * This discloses nothing that `GET /widget.js` does not already disclose:
+   * any caller that clears the gate above can read the token straight out of
+   * the widget response body today. SECURITY.md's "token delivery is
+   * unauthenticated by necessity" covers both; this is the same disclosure
+   * with an honest shape instead of a string-substituted one.
+   *
+   * Deliberately NOT under /api/*, because the bearer check there is exactly
+   * what this endpoint exists to bootstrap.
+   */
+  serveHandshake(res) {
+    res.setHeader("Cache-Control", "no-store");
+    json(res, 200, {
+      token: this.token,
+      port: this.port,
+      // Honors `"widget": false` in .sidebranch.json, which the tag channel
+      // honors by serving a no-op body. The extension has to be told.
+      widget: this.manager.config.widget === true,
+      version: VERSION,
+      // Bumped only on a breaking change to the shapes below /api/*. The
+      // extension refuses to render on a mismatch rather than half-working
+      // against a daemon it doesn't understand.
+      apiVersion: API_VERSION,
+    });
+  }
+
+  serveShell(res) {
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.setHeader("Cache-Control", "no-store");
+    // The shell embeds iframes of pane dev servers (loopback http origins)
+    // and talks only to this daemon. CSP pins both facts.
+    res.setHeader(
+      "Content-Security-Policy",
+      [
+        "default-src 'none'",
+        "script-src 'unsafe-inline'",
+        "style-src 'unsafe-inline'",
+        "connect-src http://localhost:* http://127.0.0.1:*",
+        "frame-src http://localhost:* http://127.0.0.1:*",
+        "font-src http://localhost:* http://127.0.0.1:*",
+        "img-src data:",
+        "base-uri 'none'",
+        "form-action 'none'",
+      ].join("; ")
+    );
+    res.setHeader("X-Frame-Options", "DENY");
+    const src = this.shellSrc
+      .replaceAll("__SIDEBRANCH_TOKEN__", this.token)
+      .replaceAll("__SIDEBRANCH_PORT__", String(this.port));
+    res.end(src);
+  }
+
+  serveFont(res) {
+    res.setHeader("Content-Type", "font/woff2");
+    // No token, no per-run state in this file — safe to cache hard, unlike
+    // widget.js/shell above.
+    res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+    res.end(this.fontSrc);
+  }
+
+  serveEvents(req, res) {
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-store",
+      Connection: "keep-alive",
+    });
+    res.write(`data: ${JSON.stringify({ type: "hello", at: Date.now() })}\n\n`);
+    this.sseClients.add(res);
+    const ping = setInterval(() => res.write(": ping\n\n"), 20_000);
+    req.on("close", () => {
+      clearInterval(ping);
+      this.sseClients.delete(res);
+    });
+  }
+}
+
+/* --------------------------------- helpers -------------------------------- */
+
+function json(res, status, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(status, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Content-Length": Buffer.byteLength(body),
+    "Cache-Control": "no-store",
+  });
+  res.end(body);
+}
+
+function readJson(req, limit = 64 * 1024) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on("data", (c) => {
+      size += c.length;
+      if (size > limit) {
+        reject(Object.assign(new Error("Body too large"), { code: "EBODY" }));
+        req.destroy();
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on("end", () => {
+      if (chunks.length === 0) return resolve(null);
+      try { resolve(JSON.parse(Buffer.concat(chunks).toString("utf8"))); }
+      catch { reject(Object.assign(new Error("Invalid JSON body"), { code: "EBODY" })); }
+    });
+    req.on("error", reject);
+  });
+}
+
+export { isValidPort };

package/src/daemonfile.js

@@ -0,0 +1,156 @@
+/**
+ * daemonfile.js — the record of "is a daemon running for this repo?".
+ *
+ * Until this existed, nothing tracked live daemons: `clean` could remove the
+ * worktree out from under a running dev server, `start` could launch a second
+ * daemon fighting the first over the same panes, and there was no `stop` at
+ * all. One small JSON file per project answers all three.
+ *
+ * The file lives beside the panes it describes, in `projectDataDir(repo)`, so
+ * it is scoped per repo exactly like the worktrees are — two projects each
+ * running a daemon is normal and must keep working.
+ *
+ * A PID on disk is a claim, not a fact: the process may have been SIGKILLed
+ * without cleanup, and the OS may since have recycled its pid onto something
+ * else entirely. So `readRecord()` never trusts the file alone — it proves
+ * liveness two ways (the pid exists, *and* something answers /healthz on the
+ * recorded port) and reports which of those hold. Acting on a stale record is
+ * how a tool ends up killing an unrelated process.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { projectDataDir } from "./config.js";
+import { isValidPort } from "./security.js";
+
+const FILENAME = "daemon.json";
+
+export function daemonFilePath(repoRoot) {
+  return path.join(projectDataDir(repoRoot), FILENAME);
+}
+
+/** Record this process as the daemon for `repoRoot`. */
+export async function writeRecord(repoRoot, { port }) {
+  const file = daemonFilePath(repoRoot);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const record = {
+    pid: process.pid,
+    port,
+    repo: repoRoot,
+    startedAt: Date.now(),
+    version: 1,
+  };
+  // Write-then-rename so a crash mid-write can't leave a truncated file that
+  // every later command has to defend against parsing.
+  const tmp = `${file}.${process.pid}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(record, null, 2) + "\n");
+  await fs.rename(tmp, file);
+  return record;
+}
+
+/** Remove the record, if it is ours. Never throws. */
+export async function clearRecord(repoRoot, { onlyIfPid = null } = {}) {
+  const file = daemonFilePath(repoRoot);
+  try {
+    if (onlyIfPid !== null) {
+      const raw = JSON.parse(await fs.readFile(file, "utf8"));
+      if (raw?.pid !== onlyIfPid) return false;
+    }
+    await fs.unlink(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the record and establish how much of it is still true.
+ *
+ * Returns null when there is no record at all. Otherwise:
+ *   { pid, port, startedAt, pidAlive, healthy, running }
+ *
+ * `running` is the only field callers should branch on for "is a sidebranch
+ * daemon serving this repo right now". It requires *both* proofs: a live pid
+ * rules out a record left behind by a killed process, and a /healthz answer
+ * rules out a recycled pid belonging to some unrelated program. Either alone
+ * is a way to mistake a stranger's process for our own.
+ */
+export async function readRecord(repoRoot) {
+  let raw;
+  try {
+    raw = JSON.parse(await fs.readFile(daemonFilePath(repoRoot), "utf8"));
+  } catch {
+    return null; // absent, unreadable, or corrupt — all mean "no daemon"
+  }
+  if (!Number.isInteger(raw?.pid) || raw.pid <= 0 || !isValidPort(raw?.port)) return null;
+
+  const pidAlive = isPidAlive(raw.pid);
+  const healthy = pidAlive ? await probeHealth(raw.port) : false;
+  return {
+    pid: raw.pid,
+    port: raw.port,
+    startedAt: typeof raw.startedAt === "number" ? raw.startedAt : null,
+    pidAlive,
+    healthy,
+    running: pidAlive && healthy,
+  };
+}
+
+/** Signal 0 tests for existence and permission without delivering a signal. */
+export function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means it exists but belongs to another user — still alive, and
+    // definitely not ours to signal.
+    return err.code === "EPERM";
+  }
+}
+
+/**
+ * Ask the recorded port whether a sidebranch daemon answers there.
+ *
+ * `/healthz` is unauthenticated and passes the loopback gate from this
+ * process, so this needs no token. A non-sidebranch server on that port
+ * answers something that isn't `{ok:true}`, which is exactly the case this
+ * is here to catch.
+ */
+export async function probeHealth(port, { timeoutMs = 1500 } = {}) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/healthz`, { signal: ac.signal });
+    if (!res.ok) return false;
+    const body = await res.json();
+    return body?.ok === true;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * SIGTERM the daemon and wait for it to actually go away.
+ *
+ * Deliberately never escalates to SIGKILL: the daemon's SIGTERM handler is
+ * what shuts down pane dev servers cleanly, and killing it outright would
+ * orphan those children — the exact mess this file exists to prevent. If it
+ * won't exit, say so and let the user decide.
+ */
+export async function stopDaemon(record, { timeoutMs = 10_000, pollMs = 100 } = {}) {
+  try {
+    process.kill(record.pid, "SIGTERM");
+  } catch (err) {
+    if (err.code === "ESRCH") return { ok: true, alreadyGone: true };
+    throw err;
+  }
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isPidAlive(record.pid)) return { ok: true, alreadyGone: false };
+    await new Promise((r) => setTimeout(r, pollMs));
+  }
+  return { ok: false, alreadyGone: false };
+}