@dylanpiercey/work 0.1.0 → 0.2.0

package/lib/setup/firewall.mjs

@@ -0,0 +1,598 @@
+// The host firewall in front of direct connections' UDP port
+// (src/server/rtc): what `work doctor` says about it, the rule `work setup`
+// offers to add, and what a page whose direct path never connected is
+// told. Read without root: firewalld's daemon says which zones are active
+// and which services it knows, and a zone's own definition is world-readable
+// where it was never changed (its shipped copy); ufw's switch and default
+// policy are in world-readable files; macOS's socketfilterfw and codesign
+// answer any user. What root alone can read — a zone as changed, ufw's
+// rules — makes the answer "likely", not "does". macOS's firewall admits
+// programs, not ports, so its answer is for one node: the one the service
+// runs (`node`), which the CLI asks the running server for, or reads from
+// the service's definition (`serviceNode`). Plain node, no dependencies.
+import { execFile, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+/** The name work's own rule goes by: a firewalld service, a ufw comment. */
+export const RULE = "work";
+
+const SOCKETFILTERFW = "usr/libexec/ApplicationFirewall/socketfilterfw";
+const CODESIGN = "usr/bin/codesign";
+
+/**
+ * The active host firewall and whether it admits UDP `rtcPort`, or null
+ * when none is active (or direct connections are off, `rtc` = "off").
+ * `appPort` joins the rule when `listen` is beyond this machine, since the
+ * app's own TCP port then has to be reachable too. `node` is the program
+ * macOS's firewall is asked about (this process's by default: the server
+ * asking for itself). `root` is where /etc and /usr are read from, and
+ * `platform` the system taken for this one (a test's stand-ins).
+ */
+export async function firewallProbe({
+  rtcPort,
+  appPort,
+  listen = "127.0.0.1",
+  rtc,
+  node = process.execPath,
+  root = "/",
+  platform = process.platform,
+} = {}) {
+  if (rtc === "off") return null;
+  const port = Number(rtcPort) || Number(appPort) || 7171;
+  const tcp = loopback(listen) ? null : Number(appPort) || port;
+  const at = (p) => path.join(root, p);
+  if (platform === "darwin") return macos(port, node, at);
+  return (await firewalld(port, tcp, at)) ?? ufw(port, tcp, at);
+}
+
+async function firewalld(port, tcp, at) {
+  const bin = findBin("firewall-cmd");
+  if (!bin) return null;
+  const active = await run(bin, ["--get-active-zones"]);
+  // Not running: the daemon did not answer.
+  if (!active.ok || !active.stdout.trim()) return null;
+  const zones = active.stdout
+    .split("\n")
+    .filter((line) => line && !/^\s/.test(line))
+    .map((line) => line.trim().split(/\s+/)[0]);
+  const byDefault = /^(\S+)\s+\(default\)/m.exec(active.stdout)?.[1];
+  const zone = byDefault && zones.includes(byDefault) ? byDefault : zones[0];
+  const services = await run(bin, ["--get-services"]);
+  const ruled = services.ok && services.stdout.split(/\s+/).includes(RULE);
+  // The zone as changed is root's to read; its shipped definition is what
+  // it is unless someone changed it.
+  const changed = readXml(at(`etc/firewalld/zones/${zone}.xml`));
+  const def = changed ?? readXml(at(`usr/lib/firewalld/zones/${zone}.xml`));
+  const exact = changed !== null;
+  const admits = ruled || (def !== null && zoneAdmits(def, port, at));
+  const likely = !admits;
+  const plan = [
+    ...(ruled
+      ? []
+      : [
+          sudo("firewall-cmd", "--permanent", `--new-service=${RULE}`),
+          sudo(
+            "firewall-cmd",
+            "--permanent",
+            `--service=${RULE}`,
+            `--set-short=${RULE}`,
+          ),
+        ]),
+    sudo(
+      "firewall-cmd",
+      "--permanent",
+      `--service=${RULE}`,
+      `--add-port=${port}/udp`,
+    ),
+    ...(tcp
+      ? [
+          sudo(
+            "firewall-cmd",
+            "--permanent",
+            `--service=${RULE}`,
+            `--add-port=${tcp}/tcp`,
+          ),
+        ]
+      : []),
+    sudo(
+      "firewall-cmd",
+      "--permanent",
+      `--zone=${zone}`,
+      `--add-service=${RULE}`,
+    ),
+    sudo("firewall-cmd", "--reload"),
+  ];
+  return result({
+    kind: "firewalld",
+    what: `firewalld (zone ${zone})`,
+    zone,
+    port,
+    admits,
+    likely,
+    exact,
+    ruled,
+    why: admits || exact ? null : "by the zone's definition as shipped",
+    plan: admits ? [] : plan,
+  });
+}
+
+function ufw(port, tcp, at) {
+  let conf = "";
+  try {
+    conf = fs.readFileSync(at("etc/ufw/ufw.conf"), "utf8");
+  } catch {
+    return null;
+  }
+  if (!/^\s*ENABLED\s*=\s*yes/m.test(conf)) return null;
+  let policy = "DROP";
+  try {
+    policy =
+      /^\s*DEFAULT_INPUT_POLICY\s*=\s*"?(\w+)/m.exec(
+        fs.readFileSync(at("etc/default/ufw"), "utf8"),
+      )?.[1] ?? policy;
+  } catch {}
+  // Its rules are root's to read, usually; where they are not, they say.
+  let rules = null;
+  try {
+    rules = fs.readFileSync(at("etc/ufw/user.rules"), "utf8");
+  } catch {}
+  const ruled =
+    !!rules &&
+    new RegExp(`### tuple ### allow udp ${port} \\S+ \\S+ \\S+ in\\b`).test(
+      rules,
+    );
+  const admits = policy === "ACCEPT" || ruled;
+  const plan = [
+    sudo("ufw", "allow", `${port}/udp`, "comment", RULE),
+    ...(tcp ? [sudo("ufw", "allow", `${tcp}/tcp`, "comment", RULE)] : []),
+  ];
+  return result({
+    kind: "ufw",
+    what: "ufw",
+    port,
+    admits,
+    likely: !admits,
+    exact: rules !== null,
+    ruled,
+    why:
+      admits || rules !== null
+        ? null
+        : `by its default input policy, ${policy}`,
+    plan: admits ? [] : plan,
+  });
+}
+
+/** macOS's application firewall filters by program, not port: what counts
+ * is whether the node the server runs (`node`) may take connections. All
+ * of it reads without root — the switch, "Block all incoming
+ * connections", whether signed software is let in by itself, node's own
+ * entry, and node's signature — and each parser takes what it can
+ * recognise and leaves the rest unknown (`macosVerdict`), since the
+ * wording has changed across releases. */
+async function macos(port, node, at) {
+  const bin = at(SOCKETFILTERFW);
+  if (!fs.existsSync(bin)) return null;
+  const real = realpath(node);
+  const said = (r) => `${r.stdout}\n${r.stderr}`;
+  const [state, blockAll, signed, blocked, apps, sign] = await Promise.all(
+    [
+      ["--getglobalstate"],
+      ["--getblockall"],
+      ["--getallowsigned"],
+      ["--getappblocked", real],
+      ["--listapps"],
+    ]
+      .map((a) => run(bin, a).then(said))
+      .concat(run(at(CODESIGN), ["-dv", real]).then(said)),
+  );
+  const v = macosVerdict({
+    state,
+    blockAll,
+    signed,
+    blocked,
+    apps,
+    sign,
+    paths: [...new Set([node, real])],
+  });
+  if (!v) return null;
+  const sfw = (...a) => sudo(bin, ...a);
+  const plan =
+    v.needs === "unblock"
+      ? [sfw("--unblockapp", real)]
+      : v.needs === "add"
+        ? [sfw("--add", real), sfw("--unblockapp", real)]
+        : [];
+  return result({
+    kind: "macos",
+    what: "the macOS firewall",
+    port,
+    admits: v.admits,
+    likely: !v.admits,
+    exact: v.exact,
+    ruled: false,
+    why: v.why,
+    node: real,
+    plan,
+    fix: v.needs === "blockall" ? BLOCK_ALL_FIX : undefined,
+  });
+}
+
+const BLOCK_ALL_FIX =
+  "turn off “Block all incoming connections” (System Settings → Network → Firewall → Options); no rule for one program opens anything while it is on";
+
+/**
+ * The macOS firewall's verdict on node from what socketfilterfw and
+ * codesign said (their stdout and stderr, as text): null when the firewall
+ * is off or its state could not be read. `needs` names the fix: `blockall`
+ * (a setting only the user should change), `unblock` (node is listed and
+ * blocked), `add` (node is not listed).
+ */
+export function macosVerdict({
+  state,
+  blockAll,
+  signed,
+  blocked,
+  apps,
+  sign,
+  paths,
+}) {
+  if (globalOn(state) !== true) return null;
+  if (blockAllOn(blockAll) ?? /State\s*=\s*2\b/.test(state))
+    return {
+      admits: false,
+      exact: true,
+      why: "“Block all incoming connections” is on",
+      needs: "blockall",
+    };
+  const entry = listedAs(apps, paths) ?? appBlocked(blocked);
+  if (entry === "block")
+    return {
+      admits: false,
+      exact: true,
+      why: "node is blocked in it",
+      needs: "unblock",
+    };
+  if (entry === "allow")
+    return {
+      admits: true,
+      exact: true,
+      why: "node is allowed in it",
+      needs: null,
+    };
+  const signature = signatureOf(sign);
+  const auto = allowSigned(signed);
+  if (
+    (signature === "developer-id" && auto.downloaded) ||
+    (signature === "apple" && auto.builtIn)
+  )
+    return {
+      admits: true,
+      exact: false,
+      why: `node is not listed, but it is ${signature === "apple" ? "Apple" : "Developer ID"}-signed and signed ${signature === "apple" ? "built-in" : "downloaded"} software is let in`,
+      needs: null,
+    };
+  return {
+    admits: false,
+    exact: false,
+    why: `node is not listed, and ${
+      signature === "developer-id" || signature === "apple"
+        ? "signed software is not let in by itself"
+        : signature === "adhoc"
+          ? "an ad-hoc-signed program is not let in by itself"
+          : signature === "unsigned"
+            ? "an unsigned program is not let in by itself"
+            : signature
+              ? "a program not Developer ID-signed is not let in by itself"
+              : "its signature could not be read"
+    }, so its connections are dropped or asked about on the Mac's screen`,
+    needs: "add",
+  };
+}
+
+/** `--getglobalstate`: "Firewall is enabled. (State = 1)", "Firewall is
+ * disabled. (State = 0)"; 2 is on with everything blocked. */
+export function globalOn(text = "") {
+  const n = /State\s*=\s*(\d)/i.exec(text);
+  if (n) return n[1] !== "0";
+  if (/\bdisabled\b|\boff\b/i.test(text)) return false;
+  if (/\benabled\b|\bon\b/i.test(text)) return true;
+  return null;
+}
+
+/** `--getblockall`: "Block all ENABLED!" / "Block all DISABLED!", or
+ * "Firewall has block all state set to enabled." / "… disabled." */
+export function blockAllOn(text = "") {
+  if (!/block\s*all/i.test(text)) return null;
+  if (/\bdisabled\b|\boff\b/i.test(text)) return false;
+  if (/\benabled\b|\bon\b/i.test(text)) return true;
+  return null;
+}
+
+/** `--getallowsigned`: "Automatically allow built-in signed software
+ * ENABLED." and "Automatically allow downloaded signed software
+ * ENABLED." (older: "… allow signed built-in software …", or one "… allow
+ * signed software …" switch for both). */
+export function allowSigned(text = "") {
+  const out = { builtIn: null, downloaded: null };
+  for (const line of text.split("\n")) {
+    if (!/signed/i.test(line)) continue;
+    const on = /\bdisabled\b|\boff\b/i.test(line)
+      ? false
+      : /\benabled\b|\bon\b/i.test(line)
+        ? true
+        : null;
+    if (on === null) continue;
+    if (/download/i.test(line)) out.downloaded = on;
+    else if (/built-?\s?in/i.test(line)) out.builtIn = on;
+    else out.builtIn = out.downloaded = on;
+  }
+  return out;
+}
+
+/** `--listapps`: "ALF: total number of apps = 2", then per app "1 :
+ * /path" and, on its next line or after the path, "( Allow incoming
+ * connections )" or "( Block incoming connections )". */
+export function listedAs(text = "", paths = []) {
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^\s*\d+\s*:\s*(.+?)\s*(?:\(([^)]*)\))?\s*$/.exec(lines[i]);
+    if (!m || !paths.includes(m[1].trim())) continue;
+    for (const said of [m[2] ?? "", ...lines.slice(i + 1, i + 4)]) {
+      if (/^\s*\d+\s*:/.test(said)) break;
+      if (/\bblock/i.test(said)) return "block";
+      if (/\b(allow|permit)/i.test(said)) return "allow";
+    }
+  }
+  return null;
+}
+
+/** `--getappblocked <path>`: "… is permitted" / "… is blocked", or that it
+ * is not part of the firewall (not listed). */
+export function appBlocked(text = "") {
+  if (
+    /not part of|isn['’]?t part|not (?:a )?(?:listed|found|in the)|no such|does not exist/i.test(
+      text,
+    )
+  )
+    return null;
+  if (/\bpermitted\b|\ballowed\b|\bunblocked\b|\bnot blocked\b/i.test(text))
+    return "allow";
+  if (/\bblocked\b/i.test(text)) return "block";
+  return null;
+}
+
+/** `codesign -dv <path>` (on stderr): "Authority=Developer ID
+ * Application: …", Apple's own ("Authority=Software Signing"),
+ * "Signature=adhoc", or "code object is not signed at all". */
+export function signatureOf(text = "") {
+  if (/not signed at all/i.test(text)) return "unsigned";
+  if (/^Authority=Developer ID Application\b/im.test(text))
+    return "developer-id";
+  if (
+    /^Authority=(Software Signing|Apple Code Signing|Apple Mac OS Application Signing)\b/im.test(
+      text,
+    )
+  )
+    return "apple";
+  if (/^Signature=adhoc\b|\badhoc\b/im.test(text)) return "adhoc";
+  if (/^Authority=/im.test(text)) return "other";
+  return null;
+}
+
+function result(r) {
+  return {
+    ...r,
+    fix: r.fix ?? (r.plan.length ? r.plan.map(shell).join(" && ") : null),
+  };
+}
+
+/** Whether a firewalld zone definition lets UDP `port` in: by its target,
+ * a port range of its own, or a service it names (a readable one). */
+function zoneAdmits(xml, port, at) {
+  if (/<zone[^>]*\btarget="ACCEPT"/.test(xml)) return true;
+  if (portsAdmit(xml, port)) return true;
+  for (const [, name] of xml.matchAll(/<service\s+name="([^"]+)"/g)) {
+    const svc =
+      readXml(at(`etc/firewalld/services/${name}.xml`)) ??
+      readXml(at(`usr/lib/firewalld/services/${name}.xml`));
+    if (svc && portsAdmit(svc, port)) return true;
+  }
+  return false;
+}
+
+function portsAdmit(xml, port) {
+  for (const [tag] of xml.matchAll(/<port\b[^>]*>/g)) {
+    const proto = /protocol="(\w+)"/.exec(tag)?.[1];
+    const range = /port="(\d+)(?:-(\d+))?"/.exec(tag);
+    if (proto !== "udp" || !range) continue;
+    const lo = Number(range[1]);
+    const hi = Number(range[2] ?? range[1]);
+    if (port >= lo && port <= hi) return true;
+  }
+  return false;
+}
+
+/** Run a probe's plan, each command printed (`log`) as it runs and its
+ * sudo prompt on this terminal; stops at the first that fails. */
+export function applyPlan(plan, log) {
+  for (const cmd of plan) {
+    log(cmd.join(" "));
+    const done = spawnSync(cmd[0], cmd.slice(1), { stdio: "inherit" });
+    if (done.status !== 0) return { ok: false, failed: cmd };
+  }
+  return { ok: true };
+}
+
+/** `work doctor`'s line, or null with nothing to say. Never a failure of
+ * readiness: work runs either way, and only devices on the network lose
+ * the direct path. macOS's answer is for one node, so the line says when
+ * it had to be this shell's (`nodeFrom`, set by the CLI). */
+export function firewallLine(f) {
+  if (!f) return null;
+  const head = "firewall".padEnd(11);
+  const why = f.ruled
+    ? ` (work's rule, \`${RULE}\`)`
+    : f.why
+      ? ` (${f.why})`
+      : "";
+  const whose =
+    f.kind === "macos" && f.nodeFrom === "shell"
+      ? `; read for this shell's node, ${f.node}, as neither a running service nor its definition said which it runs`
+      : "";
+  if (f.admits)
+    return `${head}✓ ${f.what} admits UDP ${f.port}${why}, which direct connections use${whose}`;
+  const how = !f.plan.length
+    ? f.fix
+    : f.kind === "macos"
+      ? `work setup --firewall lets node in, running: ${f.fix}`
+      : `work setup --firewall adds a rule named \`${RULE}\`, running: ${f.fix}`;
+  return `${head}– ${f.what} ${f.exact ? "drops" : "likely drops"} UDP ${f.port}${why}, which direct connections from other devices use: ${how}${whose}`;
+}
+
+/**
+ * The node a service definition runs (`text`: the launchd plist or systemd
+ * unit `work setup` writes): its program when that is node; else, for a
+ * script (the CLI, or a checkout's run-local.sh, after any wrapper such as
+ * caffeinate), the node its shebang names or the first on the PATH the
+ * definition gives it. A version manager's shim on that PATH is passed
+ * over: it is not the program the firewall sees. Null when the definition
+ * names no program.
+ */
+export function serviceNode(text, { PATH = "" } = {}) {
+  const argv = programOf(text);
+  if (!argv.length) return null;
+  const onPath = () => {
+    for (const dir of PATH.split(path.delimiter)) {
+      if (!dir) continue;
+      const file = path.join(dir, "node");
+      if (isNode(realpath(file)) && executable(file)) return file;
+    }
+    return null;
+  };
+  for (const arg of argv) {
+    if (isNode(arg)) return arg;
+    const line = shebang(arg);
+    // A wrapper's flag, or a program with no shebang (caffeinate).
+    if (!line) continue;
+    const [interp, first] = line.split(/\s+/);
+    if (isNode(interp)) return interp;
+    if (
+      path.basename(interp) === "env" &&
+      first &&
+      isNode(first) &&
+      first.includes("/")
+    )
+      return first;
+    return onPath();
+  }
+  return onPath();
+}
+
+function programOf(text) {
+  const plist =
+    /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(text);
+  if (plist)
+    return [...plist[1].matchAll(/<string>([^<]*)<\/string>/g)].map(([, v]) =>
+      v.replace(/&(amp|lt|gt|quot|apos);/g, (_, n) => XML[n]),
+    );
+  const exec = /^ExecStart=[-@+!:]*(.*)$/m.exec(text);
+  if (!exec) return [];
+  return [...exec[1].matchAll(/"([^"]*)"|(\S+)/g)].map(([, q, b]) => q ?? b);
+}
+
+const XML = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+
+function isNode(file) {
+  return /^node(?:\d+)?$/.test(path.basename(file));
+}
+
+function shebang(file) {
+  let fd;
+  try {
+    fd = fs.openSync(file, "r");
+    const buf = Buffer.alloc(256);
+    const head = buf.subarray(0, fs.readSync(fd, buf, 0, 256, 0)).toString();
+    return head.startsWith("#!") ? head.slice(2).split("\n")[0].trim() : null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function executable(file) {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function realpath(file) {
+  try {
+    return fs.realpathSync(file);
+  } catch {
+    return file;
+  }
+}
+
+function sudo(...args) {
+  return ["sudo", ...args];
+}
+
+function shell(argv) {
+  return argv
+    .map((a) =>
+      /^[\w@%+=:,./-]+$/.test(a) ? a : `'${a.replace(/'/g, "'\\''")}'`,
+    )
+    .join(" ");
+}
+
+function loopback(listen) {
+  return (
+    !listen ||
+    listen === "::1" ||
+    /^127\./.test(listen) ||
+    listen === "localhost"
+  );
+}
+
+function readXml(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/** A program on PATH, or in the sbin directories a user's PATH can leave
+ * out. */
+function findBin(name) {
+  const dirs = [
+    ...(process.env.PATH || "").split(path.delimiter),
+    "/usr/sbin",
+    "/sbin",
+  ];
+  for (const dir of dirs) {
+    if (!dir) continue;
+    const full = path.join(dir, name);
+    try {
+      if (fs.statSync(full).isFile()) return full;
+    } catch {}
+  }
+  return null;
+}
+
+function run(cmd, args) {
+  return new Promise((resolve) =>
+    execFile(cmd, args, { timeout: 5000 }, (err, stdout, stderr) =>
+      resolve({
+        ok: !err,
+        stdout: String(stdout || ""),
+        stderr: String(stderr || ""),
+      }),
+    ),
+  );
+}

package/lib/setup/tailscale.d.mts

@@ -0,0 +1,53 @@
+export const SERVE_SINCE: string;
+export function parseVersion(text: string | undefined): string | null;
+export interface TailscaleServe {
+  /** What a browser opens: `https://<name>/`. */
+  url: string;
+  host: string;
+  /** Funnel publishes it to the internet. */
+  funnel: boolean;
+}
+export interface TailscaleProbe {
+  installed: boolean;
+  path?: string;
+  /** The CLI's version (`1.76.1`). */
+  version?: string | null;
+  /** The CLI takes `tailscale serve --bg <port>` (SERVE_SINCE). */
+  serveCli?: boolean;
+  /** tailscaled's BackendState (`Running`, `NeedsLogin`, `Stopped`, …);
+   * null when it did not answer. */
+  state?: string | null;
+  /** Logged in and connected, with a MagicDNS name. */
+  running?: boolean;
+  /** This machine's MagicDNS name, `<machine>.<tailnet>.ts.net`. */
+  name?: string | null;
+  /** HTTPS certificates are on for the tailnet; null when unknown. */
+  https?: boolean | null;
+  /** work's port, as probed. */
+  port?: string;
+  /** Where the serve config serves work's port, and whether work answers
+   * that name (WORK_ALLOWED_HOSTS). */
+  serve?: (TailscaleServe & { allowed: boolean }) | null;
+  /** What `https://<name>/` serves when it is not work. */
+  rootTaken?: string | null;
+}
+export function serveOf(
+  config: unknown,
+  port: string | number,
+): TailscaleServe | null;
+export function allowHost(
+  value: string | undefined,
+  name: string,
+  allow?: boolean,
+): string;
+export function readTailscale(
+  raw: {
+    path: string;
+    version: string;
+    status: Record<string, any> | null;
+    serve: Record<string, any> | null;
+  },
+  opts: { port: string | number; allowedHosts?: string },
+): TailscaleProbe;
+export function stateText(t: TailscaleProbe): string;
+export function tailscaleLine(t: TailscaleProbe): string;