@dylanpiercey/work 0.1.1 → 0.2.0

package/README.md

@@ -90,6 +90,31 @@ the same tailnet. `work setup --tailscale` does it without asking and
 as it is. A serve config already pointing at work only has its name
 allowed, and `work doctor` says which of these holds.
 
+**Direct connections.** Behind a proxy, a tunnel or a relay, terminals
+move to a direct WebRTC connection to this machine when it is measurably
+faster than the path through the proxy (Settings → Terminal → Direct
+connection: Auto by default, Always, or Off, one setting for every device). Pages,
+the API and sign-in still go through your proxy; the direct path is set up
+over the app's authenticated events socket, carries terminal traffic
+alone, encrypted (DTLS), to UDP port `WORK_RTC_PORT` (by default the app's
+port number), and ends when that login does. That port is held by a helper
+process of work's own, only while direct connections are in use: it
+starts at the first one and exits ten minutes after the last. Proxy-side inspection or
+logging does not see terminal traffic that goes direct: turn the feature
+off (per device in Settings, or `WORK_RTC=off` for the machine) where it
+must. On the LAN the direct path needs nothing more; from another network
+(a phone on cellular) the UDP port has to be reachable through your router.
+Settings → Terminal can allow work to open it on the router when needed
+(UPnP, off by default): only after a device failed to connect without it,
+leased, and given back once unused. A host firewall has to let the port
+in too: `work doctor` says when one likely drops it (firewalld's
+FedoraServer zone does, for one), with the command that admits it, and
+`work setup` offers to add that rule, named `work` so it is removed as one
+(`--firewall` adds it without asking, `--no-firewall` skips the question).
+macOS's firewall admits programs rather than ports, so there it is the
+node the service runs that `work doctor` checks and `work setup` lets in. `WORK_RTC_STUN` names the STUN servers that find this machine's
+public address (Cloudflare's by default; empty for none).
+
 **Opening workspace ports remotely.** The port chips in the sidebar link to
 `http://<host>:<port>`, which only works where the machine is reachable
 directly — under a tailnet name too, since `tailscale serve` has no
@@ -159,6 +184,9 @@ targeting that branch.
 | `WORK_PORT_HOSTS`         | `sub`                 | Port-chip hostname shape: `sub` / `dash` (see above) |
 | `WORK_USER` / `WORK_HOST` | current user/host     | Branch-name prefix parts                             |
 | `WORK_BRANCH_PREFIX`      | `<user>-<host>`       | Whole branch-name prefix, overriding the parts       |
+| `WORK_RTC`                | on                    | `off` turns direct connections off (see Access)      |
+| `WORK_RTC_PORT`           | the app port          | UDP port of direct connections                       |
+| `WORK_RTC_STUN`           | Cloudflare's STUN     | Their STUN servers, comma-separated (empty: none)    |
 
 The usage panel (and `work usage`) reads plan/quota windows straight from each
 agent CLI's own credentials on disk — Claude, Codex, Cursor, Grok, and Copilot

package/bin/work.mjs

@@ -3,7 +3,10 @@
 //
 //   work setup    install missing tools, sign in, install/refresh the background service
 //                 (--tailscale serves work on the tailnet with `tailscale serve`, which
-//                 it otherwise offers when Tailscale is logged in; --no-tailscale skips that)
+//                 it otherwise offers when Tailscale is logged in; --no-tailscale skips that;
+//                 --firewall adds a `work` rule for direct connections' UDP port to a host
+//                 firewall that likely drops it, or on macOS lets the service's node in,
+//                 which it otherwise offers; --no-firewall skips that)
 //   work doctor   report machine readiness (--json, --fix to install what's missing)
 //   work start    run the server in the foreground
 //   work update   upgrade the npm package and refresh the service
@@ -36,9 +39,15 @@ import {
   formatDoctor,
   setupPath,
   tailscaleProbe,
+  tilde,
   which,
 } from "../lib/setup/doctor.mjs";
 import { allowHost, stateText } from "../lib/setup/tailscale.mjs";
+import {
+  applyPlan,
+  firewallProbe,
+  serviceNode,
+} from "../lib/setup/firewall.mjs";
 import { installTool, repairGhHelpers } from "../lib/setup/install.mjs";
 import { bridgeCommands, bridgeIfNeeded } from "../lib/setup/bridge.mjs";
 import { dialHost, listenStream } from "../lib/setup/listen.mjs";
@@ -654,6 +663,7 @@ async function setup() {
   // Before the service is written: a tailnet name to answer goes into the
   // WORK_ALLOWED_HOSTS it carries.
   const tailnet = await tailscale(d.tailscale);
+  await firewall();
 
   const running = installService();
   const port = serviceEnv().PORT;
@@ -745,7 +755,11 @@ async function update() {
   sh("work", [
     "setup",
     ...(yes ? ["--yes"] : []),
-    ...args.filter((a) => a === "--tailscale" || a === "--no-tailscale"),
+    ...args.filter((a) =>
+      ["--tailscale", "--no-tailscale", "--firewall", "--no-firewall"].includes(
+        a,
+      ),
+    ),
   ]);
 }
 
@@ -756,23 +770,175 @@ async function doctorCmd() {
     await fix(d);
     d = await doctor(doctorOpts());
   }
+  const installs = await workInstalls();
   if (args.includes("--json")) {
-    console.log(JSON.stringify(d, null, 2));
+    console.log(JSON.stringify({ ...d, work: installs }, null, 2));
   } else {
     console.log(formatDoctor(d));
     const access = accessNote();
     if (access) warn(access);
+    for (const note of installNotes(installs)) warn(note);
   }
   // exitCode, not exit(): a pipe on macOS is written asynchronously, and
   // exiting at once can cut the JSON short for whatever reads it.
   if (!d.ready) process.exitCode = 1;
 }
 
+/**
+ * This `work`, every other one on PATH (the first is what `work` runs),
+ * each with its version, and the version the running service reports
+ * (null when none answers). A package manager's global left behind — a
+ * Homebrew node's under mise's — shadows the one kept up to date, and the
+ * doctor it runs is then old code describing a machine it no longer knows.
+ */
+async function workInstalls() {
+  const self = realpathOr(fileURLToPath(import.meta.url));
+  const onPath = [];
+  const seen = new Set();
+  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
+    if (!dir) continue;
+    const file = path.join(dir, "work");
+    let real;
+    try {
+      if (!fs.statSync(file).isFile()) continue;
+      real = fs.realpathSync(file);
+    } catch {
+      continue;
+    }
+    if (seen.has(real)) continue;
+    seen.add(real);
+    onPath.push({ path: file, real, version: installVersion(real, file) });
+  }
+  let service = null;
+  try {
+    const res = await fetch(`${serverUrl()}/api/boot`, {
+      signal: AbortSignal.timeout(2000),
+    });
+    if (res.ok) service = (await res.json()).version ?? null;
+  } catch {}
+  return { self: { path: self, version: pkg.version }, onPath, service };
+}
+
+function realpathOr(file) {
+  try {
+    return fs.realpathSync(file);
+  } catch {
+    return file;
+  }
+}
+
+/** An install's version: an npm global's bin links into the package, whose
+ * package.json says; a shim (mise's) is asked. */
+function installVersion(real, file) {
+  let dir = path.dirname(real);
+  for (let i = 0; i < 3; i++) {
+    try {
+      const p = JSON.parse(fs.readFileSync(path.join(dir, "package.json")));
+      if (p.name === "@dylanpiercey/work") return p.version ?? null;
+    } catch {}
+    dir = path.dirname(dir);
+  }
+  const out = spawnSync(file, ["version"], { encoding: "utf8", timeout: 5000 });
+  return /^\d+\.\d+\.\d+\S*/.exec((out.stdout || "").trim())?.[0] ?? null;
+}
+
+/** How to remove an install: the npm beside the node whose global it is. */
+function removeHint(real) {
+  const m =
+    /^(.*)\/lib\/node_modules\/@dylanpiercey\/work\/bin\/work\.mjs$/.exec(real);
+  return m
+    ? `${m[1]}/bin/npm uninstall -g @dylanpiercey/work`
+    : `remove ${real}`;
+}
+
+function newest(versions) {
+  const parts = (v) => (v || "0").split(/[.-]/).map((n) => Number(n) || 0);
+  return versions.reduce((a, b) => {
+    const [x, y] = [parts(a), parts(b)];
+    for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i] ? a : b;
+    return a;
+  }, null);
+}
+
+/** The doctor's warnings about which `work` this is. */
+function installNotes({ self, onPath, service }) {
+  const notes = [];
+  if (service && service !== self.version) {
+    const theirs = onPath.find((w) => w.version === service);
+    notes.push(
+      `this work is ${self.version} (${tilde(self.path)}), but the running service is ${service}, so what this doctor says is an older or newer release's${theirs ? `: the service's is ${tilde(theirs.path)}` : ""}`,
+    );
+  }
+  if (onPath.length > 1) {
+    // A stray is one at another release than the service's (or, with no
+    // service answering, than the newest here).
+    const current = service ?? newest(onPath.map((w) => w.version));
+    const lines = onPath.map(
+      (w, i) =>
+        `  ${tilde(w.path)} → ${w.version ?? "unknown version"}${i === 0 ? "  (what \`work\` runs)" : ""}${w.version === current ? "" : `\n      remove: ${removeHint(w.real)}`}`,
+    );
+    notes.push(`more than one work is on PATH:\n${lines.join("\n")}`);
+  }
+  return notes;
+}
+
 /** What the doctor's Tailscale probe checks against: the port and allowed
  * names the service runs with (or will, after `work setup`). */
 function doctorOpts() {
   const env = serviceEnv();
-  return { port: env.PORT, allowedHosts: env.WORK_ALLOWED_HOSTS || "" };
+  return {
+    port: env.PORT,
+    allowedHosts: env.WORK_ALLOWED_HOSTS || "",
+    rtcPort: env.WORK_RTC_PORT || "",
+    listen: env.WORK_LISTEN,
+    rtc: env.WORK_RTC || "",
+    firewall: serviceFirewall(),
+  };
+}
+
+/**
+ * The host firewall as the service meets it. macOS's admits programs, so
+ * the node that counts is the one the service runs, which need not be this
+ * shell's: asked of the running server first (`GET /api/direct`, its own
+ * reading), else read here for the node its definition runs
+ * (`serviceNode`), else for this one's, which the result says
+ * (`nodeFrom`). `fresh` skips the server's few minutes of keeping it.
+ */
+async function serviceFirewall({ fresh = false } = {}) {
+  const env = serviceEnv();
+  try {
+    const res = await fetch(
+      `${serverUrl()}/api/direct${fresh ? "?fresh=1" : ""}`,
+      { signal: AbortSignal.timeout(3000) },
+    );
+    const live = res.ok ? await res.json() : null;
+    if (live && "firewall" in live)
+      return (
+        live.firewall && {
+          ...live.firewall,
+          node: live.firewall.node ?? live.node,
+          nodeFrom: "service",
+        }
+      );
+  } catch {}
+  let definition = null;
+  try {
+    definition = fs.readFileSync(serviceFile(), "utf8");
+  } catch {}
+  const fromUnit =
+    definition &&
+    serviceNode(definition, { PATH: installedServiceEnv().PATH || "" });
+  const node = fromUnit || process.execPath;
+  const f = await firewallProbe({
+    rtcPort: env.WORK_RTC_PORT,
+    appPort: env.PORT,
+    listen: env.WORK_LISTEN,
+    rtc: env.WORK_RTC,
+    node,
+  });
+  return (
+    f && { ...f, node: f.node ?? node, nodeFrom: fromUnit ? "unit" : "shell" }
+  );
 }
 
 /** Said when the service listens beyond this machine with nothing declared
@@ -984,6 +1150,9 @@ function serviceEnv() {
     "WORK_ALLOWED_HOSTS",
     "WORK_LISTEN",
     "WORK_TRUSTED_PROXIES",
+    "WORK_RTC",
+    "WORK_RTC_PORT",
+    "WORK_RTC_STUN",
   ]) {
     // `in` rather than a truthy check, so `WORK_ALLOWED_HOSTS= work setup`
     // can deliberately clear a setting the installed service still carries.
@@ -1440,6 +1609,77 @@ local Tailscale daemon to port ${port}.${ts.https === false ? "\nHTTPS certifica
   return allowTailnet(after.serve) ? servedAt(after.serve.url) : null;
 }
 
+/**
+ * A rule in the host firewall for direct connections' UDP port (and the
+ * app's TCP port too when the service listens beyond this machine), named
+ * `work` so it is found and removed as one: a firewalld service enabled in
+ * the active zone, or ufw rules with that comment (lib/setup/firewall.mjs);
+ * on macOS, whose firewall admits programs, the service's node let in
+ * (`serviceFirewall`; "Block all incoming connections" is only said).
+ * Added with sudo, and only on an explicit yes, the prompt's or
+ * `--firewall`: `--yes` is how the installer, `work update` and the app's
+ * own update run setup unattended, and none of them asked for it. What it
+ * runs is printed as it runs.
+ */
+async function firewall() {
+  if (args.includes("--no-firewall")) return;
+  const asked = args.includes("--firewall");
+  const env = serviceEnv();
+  const f = await serviceFirewall();
+  if (!f) {
+    if (asked && env.WORK_RTC !== "off")
+      log("no active host firewall: nothing to add");
+    return;
+  }
+  if (f.admits) {
+    if (asked) log(`${f.what} already admits UDP ${f.port}`);
+    return;
+  }
+  const drops = `${f.what} ${f.exact ? "drops" : "likely drops"} UDP ${f.port}${f.why ? ` (${f.why})` : ""}, which direct connections from your other devices use`;
+  if (!f.plan.length) {
+    if (asked || !yes) warn(`${drops}: ${f.fix}`);
+    return;
+  }
+  // macOS's firewall admits a program: the service's node, as found.
+  const adds =
+    f.kind === "macos" ? `let ${f.node} in` : "add a rule named `work`";
+  if (f.kind === "macos" && f.nodeFrom === "shell")
+    warn(
+      `neither a running service nor its definition said which node it runs: this is for this shell's, ${f.node}`,
+    );
+  const input = yes || asked ? null : terminal();
+  try {
+    if (!asked) {
+      if (!input) {
+        log(`${drops}: \`work setup --firewall\` can ${adds}`);
+        return;
+      }
+      console.log(`
+${drops}.
+\`work setup\` can ${adds} for it, with sudo:
+  ${f.plan.map((cmd) => cmd.join(" ")).join("\n  ")}`);
+      if (!(await confirm(input, "Add it? [y/N] "))) {
+        log(
+          "left the firewall as it was (work setup --firewall adds it later; --no-firewall skips this question)",
+        );
+        return;
+      }
+    }
+  } finally {
+    if (input && input !== process.stdin) input.destroy();
+  }
+  const applied = applyPlan(f.plan, log);
+  if (!applied.ok) {
+    warn(
+      `\`${applied.failed?.join(" ")}\` failed, so the rule may be part-made: run the rest of\n  ${f.plan.map((c) => c.join(" ")).join("\n  ")}`,
+    );
+    return;
+  }
+  const after = await serviceFirewall({ fresh: true });
+  if (after?.admits) log(`${after.what} admits UDP ${after.port}`);
+  else warn(`${f.what} still looks shut to UDP ${f.port}: see work doctor`);
+}
+
 function servedAt(url) {
   log(`Tailscale serves work at ${url} (tailnet only)`);
   return url;

package/dist/_BO3_WJb5.js

@@ -0,0 +1,169 @@
+var glyphBadgeNum = "_y _x";
+var usageInk = {
+	ok: "_z",
+	mid: "_A",
+	warm: "_B",
+	hot: "_C"
+};
+var usageFill = {
+	ok: "_D",
+	mid: "_E",
+	warm: "_F",
+	hot: "_G"
+};
+var prTone = {
+	open: "_H",
+	draft: "_I",
+	merged: "_J",
+	closed: "_K"
+};
+var phaseIcon = {
+	working: "_X _W",
+	waiting: "_Y _W",
+	idle: "_Z _W",
+	off: "_0 _W"
+};
+var btnSm = "_7 _r";
+var btnLg = "_8 _r";
+var tone = {
+	accent: "_bb",
+	ok: "_bc",
+	warn: "_bd",
+	danger: "_be",
+	merged: "_bf",
+	closed: "_bg"
+};
+var inputLg = "_bk _bj";
+var iconBtnXs = "_bo _m";
+var iconBtnRow = "_bp _m";
+var iconBtnLg = "_bq _m";
+var chipBtn = "_br _m";
+var tocDot = "_cS _U";
+//#endregion
+//#region src/styles/tokens.css.ts
+var color = {
+	ok: "light-dark(#1a7f37, #57d364)",
+	okStrong: "light-dark(#116329, #7ee787)",
+	warn: "light-dark(#bf8700, #d4a72c)",
+	warnStrong: "light-dark(#8a5a00, #f0b84a)",
+	merged: "light-dark(#8250df, #a371f7)",
+	closed: "light-dark(#cf222e, #f85149)",
+	onAccent: "#fff",
+	onDanger: "#fff",
+	accentDefault: "light-dark(#4f5bd5, #6470e6)",
+	bg: "var(--bg)",
+	panel: "var(--panel)",
+	border: "var(--border)",
+	text: "var(--text)",
+	dim: "var(--dim)",
+	accent: "var(--accent)",
+	accentFill: "var(--accent-fill)",
+	accentText: "var(--accent-text)",
+	danger: "var(--danger)",
+	fieldBorder: "var(--field-border)",
+	raised: "color-mix(in srgb, var(--panel) 94%, var(--text))",
+	raisedHover: "color-mix(in srgb, var(--panel) 90%, var(--text))",
+	onScrim: "#fff"
+};
+var sans = "Inter, ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", sans-serif";
+var iconSize = {
+	sm: 12,
+	md: 14,
+	lg: 16,
+	xl: 18
+};
+var toastKind = {
+	error: "_bJ",
+	warn: "_bK",
+	info: "_bL"
+};
+var toastTitle = {
+	error: "_bM",
+	warn: "_bN",
+	info: "_bO"
+};
+//#endregion
+//#region src/tags/settings-agents.css.ts
+var agentRow = "_d4 _dK";
+var list$3 = "_dO _du _dJ _dM";
+var metaChip = "_d2 _bi _bh";
+var sectionCount = "_dr _9 __";
+var usageNote = "_j2 _bh";
+var pop$2 = "_hR _bw";
+var spinner = "_hU _bm _2";
+var toolLead = "_gv _dX";
+var name$4 = "_gZ _dX";
+var desc$1 = "_g0 _dY";
+//#endregion
+//#region src/tags/lsp-add-dialog.css.ts
+var addDlg = "_ka _bV";
+var key$1 = "_kD _kB";
+var addTile = "_kF _kB";
+var field$2 = "_kQ _bj";
+var keyField = "_kR _kQ _bj";
+var labelField = "_kS _kQ _bj";
+var detailsToggle = "_hz _P";
+var themeSeg = "_fS _bA";
+var checkList = "_hd _ds";
+//#endregion
+//#region src/tags/prompt-dialog.css.ts
+var promptDlg = "_bZ _bV";
+var item$1 = "_b4 _m";
+var glance = "_eU _m";
+//#endregion
+//#region src/tags/side-nav.css.ts
+var iconBtn = "_cY _m";
+var settingsDot = "_cZ _bz";
+var notifyBtn = "_c4 _m";
+//#endregion
+//#region src/styles/session-pop.css.ts
+var sessionPop = "_c6 _bw";
+var sessionPopBtn = "_c7 _4";
+var wsBtn = "_gJ _4";
+var rowIcon = "_gL _bo _m";
+var prChip = "_lr _v _ll";
+var readyChip = "_ls _v";
+var prDot = "_lu _lt";
+//#endregion
+//#region src/tags/port-chip.css.ts
+var port = "_nm _v _ll";
+var open = "_k0 _4";
+var action = "_k4 _br _m";
+var toggle = "_e6 _P";
+var fold = "_e7 _dL";
+var item = "_jO _4";
+var menu = "_mj _c6 _bw";
+var menuItem = "_ml _4";
+var findBtn$1 = "_iX _h0 _bp _m";
+var tool = "_h0 _bp _m";
+var pop$1 = "_lh _c6 _bw";
+var fileFilter = "_nq _o";
+var findInput = "_ew _o";
+var keybarIconBtn = "_eF _br _m";
+var repoTitle = "_lZ _L";
+var input = "_b9 _o";
+var group = "_cb _P";
+var hint$1 = "_lQ _9 _M";
+var sheetDir = "_mI _by";
+var upBtn = "_ih _bp _m";
+var findBtn = "_il _h0 _bp _m";
+var goBtn = "_im _h0 _bp _m";
+var note = "_lk _bh";
+//#endregion
+//#region src/tags/manage-workspace.css.ts
+var procCmd = "_gi _dX";
+var factCopy = "_gp _br _m";
+var resultRow = "_kk _4";
+var resultBranch = "_kl _d2 _bi _bh _bo _m";
+var urlAction = "_km _d2 _bi _bh _d3";
+var curRow = "_e1 _dR";
+//#endregion
+//#region src/tags/join-dialog.css.ts
+var dlg = "_k7 _bV";
+var hint = "_k8 _bh";
+var kbtn = "_cu _bq _m";
+var repeat = "_cx _cw";
+var dpadUser = "_cA _cw";
+var dpadEsc = "_cB _cw";
+//#endregion
+export { field$2 as $, item as A, tone as At, wsBtn as B, keybarIconBtn as C, glyphBadgeNum as Ct, findBtn$1 as D, inputLg as Dt, tool as E, iconBtnXs as Et, port as F, settingsDot as G, sessionPopBtn as H, prChip as I, promptDlg as J, glance as K, prDot as L, toggle as M, usageInk as Mt, action as N, menu as O, phaseIcon as Ot, open as P, addTile as Q, readyChip as R, findInput as S, chipBtn as St, pop$1 as T, iconBtnRow as Tt, iconBtn as U, sessionPop as V, notifyBtn as W, themeSeg as X, checkList as Y, detailsToggle as Z, sheetDir as _, iconSize as _t, dlg as a, name$4 as at, input as b, btnLg as bt, resultBranch as c, spinner as ct, factCopy as d, list$3 as dt, key$1 as et, procCmd as f, metaChip as ft, upBtn as g, color as gt, goBtn as h, toastTitle as ht, repeat as i, desc$1 as it, fold as j, usageFill as jt, menuItem as k, prTone as kt, resultRow as l, usageNote as lt, findBtn as m, toastKind as mt, dpadUser as n, labelField as nt, hint as o, toolLead as ot, note as p, agentRow as pt, item$1 as q, kbtn as r, addDlg as rt, curRow as s, pop$2 as st, dpadEsc as t, keyField as tt, urlAction as u, sectionCount as ut, hint$1 as v, sans as vt, fileFilter as w, iconBtnLg as wt, repoTitle as x, btnSm as xt, group as y, tocDot as yt, rowIcon as z };