sidebranch 0.2.0

package/src/processes.js

@@ -0,0 +1,250 @@
+/**
+ * processes.js — spawn and supervise one dev server per review worktree.
+ *
+ * Framework-agnostic contract: a dev server is (command, cwd, port, env) plus
+ * a readiness probe. We inject the allocated port as the PORT env var and
+ * substitute a literal {port} placeholder in the command for tools that
+ * only take a flag (e.g. "vite --port {port}", "python3 -m http.server {port}").
+ * Config-supplied `env` is layered on top of the inherited environment (so a
+ * project can point a pane at a shared emulator, unset a stale credential
+ * path, etc.) but cannot override the vars sidebranch owns — PORT above all.
+ * We never parse dev-server output — readiness is confirmed by probing the
+ * port, because some servers silently pick a different port than asked.
+ */
+
+import net from "node:net";
+import http from "node:http";
+import { spawn } from "node:child_process";
+
+import { splitCommand, tailText } from "./install.js";
+import { isValidPort } from "./security.js";
+
+/** Find a free port on loopback, preferring sequential ports from `base`. */
+export async function allocatePort(base = 4410, taken = new Set()) {
+  for (let p = base; p < base + 500; p++) {
+    if (taken.has(p)) continue;
+    if (await portIsFree(p)) return p;
+  }
+  throw new Error("No free ports available in range");
+}
+
+export function portIsFree(port) {
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.unref();
+    srv.once("error", () => resolve(false));
+    srv.listen({ port, host: "127.0.0.1", exclusive: true }, () => {
+      srv.close(() => resolve(true));
+    });
+  });
+}
+
+/**
+ * Probe an HTTP endpoint until it answers or timeout.
+ * Any HTTP status counts as "up" by default — a 404 or 500 still proves the
+ * server is accepting connections; which statuses count is configurable.
+ */
+export function waitForReady({ port, path: probePath = "/", statuses = null, timeoutMs = 120_000, intervalMs = 400, signal }) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve, reject) => {
+    const attempt = () => {
+      if (signal?.aborted) return reject(new Error("aborted"));
+      const req = http.get(
+        { host: "127.0.0.1", port, path: probePath, timeout: 3000 },
+        (res) => {
+          res.resume();
+          const ok = statuses ? statuses.includes(res.statusCode) : true;
+          if (ok) return resolve(res.statusCode);
+          retry();
+        }
+      );
+      req.on("timeout", () => { req.destroy(); retry(); });
+      req.on("error", retry);
+    };
+    const retry = () => {
+      if (Date.now() > deadline) return reject(new Error(`Server on :${port} not ready after ${timeoutMs / 1000}s`));
+      setTimeout(attempt, intervalMs);
+    };
+    attempt();
+  });
+}
+
+/**
+ * Ask a pane's dev server whether it will allow itself to be embedded.
+ *
+ * `/shell` frames panes from a *different* origin — the daemon is on 49400,
+ * panes are on 4410+ — and same-origin is per-port, so any app that sends
+ * `X-Frame-Options: SAMEORIGIN` (or a `frame-ancestors` that excludes the
+ * daemon) refuses to render there. The browser reports that only as a console
+ * message inside the frame, which the shell cannot read cross-origin, so
+ * without this probe the compare view is simply, silently blank.
+ *
+ * Best-effort by construction: `frame-ancestors` is a source-list grammar and
+ * this does not implement it. It answers "will this obviously refuse?", which
+ * is enough to replace a blank rectangle with a sentence naming the header.
+ * Never throws — an unreachable server is not a framing verdict.
+ */
+export function probeFraming({ port, path: probePath = "/", daemonPort }) {
+  return new Promise((resolve) => {
+    const done = (v) => resolve(v);
+    const req = http.get(
+      { host: "127.0.0.1", port, path: probePath, timeout: 3000 },
+      (res) => {
+        res.resume();
+        done(readFramingHeaders(res.headers, daemonPort));
+      }
+    );
+    req.on("timeout", () => { req.destroy(); done(null); });
+    req.on("error", () => done(null));
+  });
+}
+
+export function readFramingHeaders(headers, daemonPort) {
+  const xfo = String(headers["x-frame-options"] ?? "").trim().toLowerCase();
+  if (xfo === "deny" || xfo === "sameorigin") {
+    return { blocked: true, header: "X-Frame-Options", value: xfo.toUpperCase() };
+  }
+  const csp = String(headers["content-security-policy"] ?? "");
+  const directive = /(?:^|;)\s*frame-ancestors\s+([^;]+)/i.exec(csp);
+  if (!directive) return { blocked: false, header: null, value: null };
+  const sources = directive[1].trim().toLowerCase().split(/\s+/);
+  const permits = sources.some((src) => (
+    src === "*" ||
+    src === `http://localhost:${daemonPort}` ||
+    src === `http://127.0.0.1:${daemonPort}` ||
+    src === "http://localhost:*" ||
+    src === "http://127.0.0.1:*"
+  ));
+  return permits
+    ? { blocked: false, header: null, value: null }
+    : { blocked: true, header: "Content-Security-Policy", value: `frame-ancestors ${directive[1].trim()}` };
+}
+
+export class DevServer {
+  constructor({ command, cwd, port, env = {}, readyPath = "/", readyStatuses = null, daemonPort = null }) {
+    if (!isValidPort(port)) throw new Error(`Invalid port ${port}`);
+    this.command = command;
+    this.cwd = cwd;
+    this.port = port;
+    this.env = env;
+    this.readyPath = readyPath;
+    this.readyStatuses = readyStatuses;
+    this.daemonPort = daemonPort;
+    this.child = null;
+    this.state = "stopped"; // stopped | starting | ready | crashed
+    this.logRing = [];
+    this.exitInfo = null;
+    // null until the readiness probe has had a chance to look — "unknown",
+    // which the shell renders as "embed it and see", not as "blocked".
+    this.framing = null;
+  }
+
+  log(line) {
+    this.logRing.push(line);
+    if (this.logRing.length > 400) this.logRing.shift();
+  }
+
+  async start() {
+    const argv = splitCommand(this.command).map((a) =>
+      a.replaceAll("{port}", String(this.port))
+    );
+    if (argv.length === 0) throw new Error("Empty dev command");
+    this.state = "starting";
+    this.exitInfo = null;
+    this.child = spawn(argv[0], argv.slice(1), {
+      cwd: this.cwd,
+      env: {
+        ...process.env,
+        ...this.env,               // config `env` — overrides inherited values
+        //                            (already stripped of PORT et al. in config)
+        PORT: String(this.port),   // sidebranch-owned; always wins over config
+        BROWSER: "none",           // stop CRA/next from opening tabs
+        FORCE_COLOR: "0",
+        SIDEBRANCH: "1",
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: false,
+      detached: process.platform !== "win32", // own process group → clean kill of child trees
+      windowsHide: true,
+    });
+    const forward = (buf) => this.log(buf.toString());
+    this.child.stdout.on("data", forward);
+    this.child.stderr.on("data", forward);
+
+    // spawn() reports failures (e.g. command not found) via an 'error' event,
+    // not 'exit'. ChildProcess is an EventEmitter, so a truly unhandled
+    // 'error' event throws and takes down the whole daemon process — every
+    // pane, not just this one. Handling it here turns that into an ordinary
+    // rejected start() (surfaced to the API caller as a pane error) and
+    // aborts the readiness probe immediately instead of waiting out its
+    // full timeout.
+    const abortReady = new AbortController();
+    let startupError = null;
+    this.child.on("error", (err) => {
+      startupError = err;
+      this.exitInfo = { code: null, sig: null };
+      this.state = "crashed";
+      this.child = null;
+      abortReady.abort();
+    });
+    this.child.on("exit", (code, sig) => {
+      this.exitInfo = { code, sig };
+      if (this.state !== "stopped") this.state = "crashed";
+      this.child = null;
+      abortReady.abort();
+    });
+
+    try {
+      await waitForReady({
+        port: this.port,
+        path: this.readyPath,
+        statuses: this.readyStatuses,
+        signal: abortReady.signal,
+      });
+    } catch (err) {
+      if (this.state === "crashed") {
+        const reason = startupError
+          ? startupError.message
+          : `exited during startup${this.exitInfo?.code != null ? ` (exit code ${this.exitInfo.code})` : ""}`;
+        const tail = tailText(this.logRing);
+        throw new Error(`Dev server ${reason}${tail ? `: ${tail}` : ""}`);
+      }
+      throw err;
+    }
+    if (this.state === "crashed") throw new Error("Dev server exited during startup");
+    // One extra request, once per server start, on a server we have just
+    // proven is answering. Failure here is not a startup failure.
+    this.framing = await probeFraming({
+      port: this.port,
+      path: this.readyPath,
+      daemonPort: this.daemonPort,
+    });
+    this.state = "ready";
+    return this;
+  }
+
+  async stop() {
+    this.state = "stopped";
+    const child = this.child;
+    if (!child) return;
+    await new Promise((resolve) => {
+      child.once("exit", resolve);
+      try {
+        if (process.platform !== "win32") process.kill(-child.pid, "SIGTERM");
+        else child.kill("SIGTERM");
+      } catch { resolve(); }
+      setTimeout(() => {
+        try {
+          if (process.platform !== "win32") process.kill(-child.pid, "SIGKILL");
+          else child.kill("SIGKILL");
+        } catch { /* already gone */ }
+      }, 5000).unref();
+    });
+    this.child = null;
+  }
+
+  async restart() {
+    await this.stop();
+    return this.start();
+  }
+}

package/src/proxy.js

@@ -0,0 +1,136 @@
+/**
+ * proxy.js — per-pane "view port": a pass-through proxy the shell frames
+ * instead of the pane's own port, identical except that the two framing
+ * headers are deleted. Nothing else is parsed, buffered, or rewritten.
+ *
+ * Rules (see SECURITY.md):
+ *   - Binds 127.0.0.1 only; peer and Host are checked like the daemon's gate.
+ *   - `Sec-Fetch-Site: cross-site` is rejected, so remote pages can't frame a
+ *     pane through it — the protection the stripped header was providing.
+ *   - The target is fixed at construction (its own pane). No request-derived
+ *     routing, so it can never be used to reach anything else.
+ *   - What was removed is declared in `Sidebranch-Removed-Headers`.
+ */
+
+import http from "node:http";
+import net from "node:net";
+import { isLoopbackAddress, isAllowedHostHeader } from "./security.js";
+
+// Hop-by-hop headers are per-connection; forwarding them corrupts framing of
+// the next hop's stream (double chunking, stale keep-alive promises).
+const HOP_BY_HOP = ["connection", "keep-alive", "transfer-encoding", "te", "trailer", "proxy-authorization", "proxy-authenticate"];
+
+/** Returns { headers, removed[] } — a copy with the framing headers gone. */
+export function stripFramingHeaders(headers) {
+  const out = { ...headers };
+  const removed = [];
+  if (out["x-frame-options"] !== undefined) {
+    delete out["x-frame-options"];
+    removed.push("x-frame-options");
+  }
+  const csp = out["content-security-policy"];
+  if (csp !== undefined) {
+    const strip = (v) => {
+      const kept = String(v).split(";").filter((d) => !/^\s*frame-ancestors\s/i.test(d) && d.trim() !== "");
+      return kept.join(";").trim();
+    };
+    const values = Array.isArray(csp) ? csp : [csp];
+    const stripped = values.map(strip);
+    if (stripped.join() !== values.join()) {
+      removed.push("content-security-policy frame-ancestors");
+      const kept = stripped.filter((v) => v !== "");
+      if (kept.length === 0) delete out["content-security-policy"];
+      else out["content-security-policy"] = Array.isArray(csp) ? kept : kept[0];
+    }
+  }
+  return { headers: out, removed };
+}
+
+export class FrameProxy {
+  constructor({ port, targetPort }) {
+    this.port = port;
+    this.targetPort = targetPort;
+    this.server = null;
+    this.sockets = new Set();
+  }
+
+  gate(req, res) {
+    if (!isLoopbackAddress(req.socket.remoteAddress)) { res.writeHead(403).end(); return false; }
+    if (!isAllowedHostHeader(req.headers.host)) { res.writeHead(403).end("Host not allowed\n"); return false; }
+    if (String(req.headers["sec-fetch-site"] || "").toLowerCase() === "cross-site") {
+      res.writeHead(403).end("Cross-site requests are not allowed\n");
+      return false;
+    }
+    return true;
+  }
+
+  handle(req, res) {
+    if (!this.gate(req, res)) return;
+    const headers = { ...req.headers };
+    for (const h of HOP_BY_HOP) delete headers[h];
+    const upstream = http.request({
+      host: "127.0.0.1",
+      port: this.targetPort,
+      method: req.method,
+      path: req.url,
+      headers,
+      // No keep-alive pool: pooled sockets outlive stop() and pin the event
+      // loop; on loopback a fresh connection per request costs nothing.
+      agent: false,
+    }, (up) => {
+      const { headers: outHeaders, removed } = stripFramingHeaders(up.headers);
+      for (const h of HOP_BY_HOP) delete outHeaders[h];
+      if (removed.length) outHeaders["sidebranch-removed-headers"] = removed.join(", ");
+      res.writeHead(up.statusCode, up.statusMessage, outHeaders);
+      up.pipe(res);
+    });
+    upstream.on("error", () => {
+      if (!res.headersSent) res.writeHead(502, { "Content-Type": "text/plain" });
+      res.end(`Pane server on :${this.targetPort} is not answering\n`);
+    });
+    req.pipe(upstream);
+  }
+
+  // Raw splice for websockets (HMR). The gate applies here too — upgrades are
+  // where Host checks classically get forgotten.
+  upgrade(req, socket, head) {
+    const deny = (msg) => socket.end(`HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n${msg}\n`);
+    if (!isLoopbackAddress(req.socket.remoteAddress)) return deny("Forbidden");
+    if (!isAllowedHostHeader(req.headers.host)) return deny("Host not allowed");
+    if (String(req.headers["sec-fetch-site"] || "").toLowerCase() === "cross-site") return deny("Cross-site requests are not allowed");
+
+    const target = net.connect(this.targetPort, "127.0.0.1", () => {
+      const lines = [`${req.method} ${req.url} HTTP/1.1`];
+      for (let i = 0; i < req.rawHeaders.length; i += 2) lines.push(`${req.rawHeaders[i]}: ${req.rawHeaders[i + 1]}`);
+      target.write(lines.join("\r\n") + "\r\n\r\n");
+      if (head?.length) target.write(head);
+      socket.pipe(target).pipe(socket);
+    });
+    // Either side going away takes the other with it. 'end' is in the list
+    // because http.Server sockets allow half-open: a peer's FIN alone never
+    // produces 'close', and a half-closed websocket is a dead websocket.
+    const drop = () => { socket.destroy(); target.destroy(); };
+    for (const s of [socket, target]) { s.on("error", drop); s.on("close", drop); s.on("end", drop); }
+  }
+
+  async start() {
+    this.server = http.createServer((req, res) => this.handle(req, res));
+    this.server.on("upgrade", (req, socket, head) => this.upgrade(req, socket, head));
+    // Long-lived SSE/HMR streams must not be reaped by the default 300s cap.
+    this.server.requestTimeout = 0;
+    this.server.on("connection", (s) => {
+      this.sockets.add(s);
+      s.on("close", () => this.sockets.delete(s));
+    });
+    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 s of this.sockets) s.destroy();
+    await new Promise((r) => this.server?.close(r));
+  }
+}

package/src/security.js

@@ -0,0 +1,123 @@
+/**
+ * security.js — the trust boundary of sidebranch.
+ *
+ * Threat model (see SECURITY.md for the full write-up):
+ *   1. A malicious *remote* website loaded in the user's browser tries to
+ *      reach the daemon (CSRF-style requests to http://localhost:49400,
+ *      or DNS-rebinding where evil.com resolves to 127.0.0.1).
+ *   2. The widget <script> tag accidentally ships to production, where it
+ *      runs on end users' machines pointed at *their* localhost.
+ *   3. Command injection through branch names or config values.
+ *   4. A non-loopback network peer connecting to the daemon.
+ *
+ * Defenses, layered (each is sufficient on its own for its attack):
+ *   - The daemon binds 127.0.0.1 only, and additionally verifies the peer
+ *     socket address of every request (defense in depth vs. proxies).
+ *   - Every request's Host header must be a loopback host. This defeats
+ *     DNS rebinding, where the socket is loopback but Host is attacker-owned.
+ *   - Every state-changing or state-revealing API call requires a bearer
+ *     token that is only ever embedded in assets served to loopback pages.
+ *   - CORS is only granted to loopback origins; all other origins get no
+ *     CORS headers at all, so their reads fail in the browser.
+ *   - The widget self-disables unless the *page* it runs on is loopback,
+ *     so a production deployment of the snippet is inert by construction.
+ *   - All git/process invocations use execFile/spawn with argument arrays
+ *     (never a shell), and ref names are validated before use.
+ */
+
+import crypto from "node:crypto";
+import net from "node:net";
+
+const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+
+/** True if an IP address literal is a loopback address. */
+export function isLoopbackAddress(addr) {
+  if (!addr) return false;
+  // Node reports IPv4-mapped IPv6 like ::ffff:127.0.0.1
+  const v4 = addr.startsWith("::ffff:") ? addr.slice(7) : addr;
+  if (net.isIPv4(v4)) return v4.startsWith("127.");
+  if (net.isIPv6(addr)) return addr === "::1";
+  return false;
+}
+
+/** True if a URL hostname (no port) refers to loopback. */
+export function isLoopbackHostname(hostname) {
+  if (!hostname) return false;
+  const h = hostname.toLowerCase();
+  if (LOOPBACK_HOSTNAMES.has(h)) return true;
+  if (net.isIPv4(h)) return h.startsWith("127.");
+  return false;
+}
+
+/**
+ * Validate a Host header value ("localhost:49400", "127.0.0.1:49400").
+ * Rejects anything that is not an explicit loopback host — this is the
+ * DNS-rebinding defense and must never be relaxed.
+ */
+export function isAllowedHostHeader(hostHeader) {
+  if (!hostHeader) return false;
+  try {
+    // URL parsing handles [::1]:49400 bracket syntax for us.
+    const { hostname } = new URL(`http://${hostHeader}`);
+    return isLoopbackHostname(hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate an Origin header. Only http(s) pages served from loopback may
+ * talk to the daemon. Requests with no Origin (curl, same-origin GETs)
+ * are allowed at this layer; the token layer still gates everything.
+ */
+export function isAllowedOrigin(origin) {
+  if (origin === undefined || origin === null || origin === "") return true;
+  if (origin === "null") return false; // sandboxed iframes / file:// pages
+  try {
+    const u = new URL(origin);
+    if (u.protocol !== "http:" && u.protocol !== "https:") return false;
+    return isLoopbackHostname(u.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/** Generate a session token. Rotates on every daemon start. */
+export function generateToken() {
+  return crypto.randomBytes(32).toString("hex");
+}
+
+/** Constant-time token comparison. */
+export function tokenMatches(expected, presented) {
+  if (typeof presented !== "string" || typeof expected !== "string") return false;
+  const a = Buffer.from(expected);
+  const b = Buffer.from(presented);
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+
+/**
+ * Conservative branch/ref name validation, applied *in addition to*
+ * `git check-ref-format` (see gitops.js). Belt and suspenders: even if a
+ * name passes git's rules, we refuse anything that could read as an
+ * option (leading "-"), contain shell-significant bytes, or traverse paths.
+ */
+const REF_SEGMENT = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
+export function isSafeRefName(name) {
+  if (typeof name !== "string") return false;
+  if (name.length === 0 || name.length > 250) return false;
+  if (name.startsWith("-")) return false;
+  if (name.includes("..") || name.includes("@{")) return false;
+  if (/[\s~^:?*\[\\\x00-\x1f\x7f'"`$;&|<>(){}!#%]/.test(name)) return false;
+  return name.split("/").every((seg) => seg.length > 0 && REF_SEGMENT.test(seg));
+}
+
+/** Validate a slug used for worktree directory names. */
+export function isSafeSlug(s) {
+  return typeof s === "string" && /^[a-z0-9][a-z0-9-]{0,80}$/.test(s);
+}
+
+/** Validate a TCP port number from untrusted input. */
+export function isValidPort(p) {
+  return Number.isInteger(p) && p >= 1 && p <= 65535;
+}