harnery 0.42.0 → 0.44.0

package/src/lib/tunnel/gate.ts

@@ -12,6 +12,7 @@
 // available; stdout/stderr is captured into .cache/tunnel/gate.log by the
 // spawner.
 
+import { allowlistMatches, compileAllowlist } from "./allowlist.ts";
 import { renderTunnelErrorPage } from "./error-page";
 import { applyUpstreamHeaders } from "./forward-headers";
 import { ALLOW_PATHS_ENV, isPathAllowed, parseAllowPathsEnv } from "./path-scope.ts";
@@ -27,12 +28,8 @@ function argvFlag(flag: string): string | undefined {
   return i !== -1 ? process.argv[i + 1] : undefined;
 }
 
-const ALLOW = new Set(
-  (process.env.HARNERY_TUNNEL_ALLOW ?? "")
-    .split(",")
-    .map((s) => s.trim())
-    .filter(Boolean),
-);
+// Entries are exact addresses or CIDR ranges (`203.0.113.0/24`, `2601:db8:1:2::/64`).
+const ALLOW = compileAllowlist((process.env.HARNERY_TUNNEL_ALLOW ?? "").split(","));
 const TARGET = process.env.HARNERY_TUNNEL_TARGET ?? "127.0.0.1:8001";
 const VHOST = process.env.HARNERY_TUNNEL_VHOST ?? "localhost";
 const PORT = Number(process.env.HARNERY_TUNNEL_PORT ?? argvFlag("--port") ?? "9001");
@@ -81,7 +78,7 @@ const server = Bun.serve<WsData, never>({
     const url = new URL(req.url);
     if (ACCESS === "cloudflare-allowlist") {
       const ip = req.headers.get("cf-connecting-ip") ?? "";
-      if (!ALLOW.has(ip)) {
+      if (!allowlistMatches(ALLOW, ip)) {
         const details = requestDetails(req, url);
         // Log denials so operators can whitelist a phone/laptop that just
         // hit 403 without asking the human to dig up their public IP.
@@ -213,4 +210,15 @@ const server = Bun.serve<WsData, never>({
 console.log(`harn-tunnel-gate :${server.port} -> ${UPSTREAM_HTTP} (Host: ${VHOST})`); // lint-ok-emission: detached worker, see file note above
 console.log(`access: ${ACCESS}`); // lint-ok-emission: detached worker, see file note above
 console.log(`paths: ${ALLOW_PATHS.join(", ") || "(empty, every path refused)"}`); // lint-ok-emission: detached worker, see file note above
-console.log(`allow: ${[...ALLOW].join(", ") || "(empty, not used outside allowlist mode)"}`); // lint-ok-emission: detached worker, see file note above
+console.log(
+  // lint-ok-emission: detached worker, see file note above
+  `allow: ${
+    process.env.HARNERY_TUNNEL_ALLOW?.split(",")
+      .filter((s) => s.trim())
+      .join(", ") || "(empty, not used outside allowlist mode)"
+  }`,
+);
+if (ALLOW.invalid.length > 0) {
+  // lint-ok-emission: detached worker, see file note above
+  console.log(`allow: ignoring unreadable entries: ${ALLOW.invalid.join(", ")}`);
+}

package/src/lib/tunnel/processes.ts

@@ -0,0 +1,149 @@
+// Process and port discovery for the tunnel commands, per platform.
+//
+// Linux and macOS have `pgrep`/`ps`; Linux has `ss`; both have `lsof`. Windows
+// has none of these, so it uses PowerShell for command lines and `netstat` for
+// listening sockets. Every probe is best effort: a missing tool yields "no
+// answer" (null or an empty list), never a thrown error, and the callers fall
+// back to checks that need no tool (a TCP connect probe, a PID check).
+
+import { spawnSync } from "node:child_process";
+import { connect } from "node:net";
+
+type Run = (
+  command: string,
+  args: string[],
+) => { status: number | null; stdout: string; missing: boolean };
+
+const runTool: Run = (command, args) => {
+  const r = spawnSync(command, args, { encoding: "utf-8", windowsHide: true, timeout: 15_000 });
+  const missing = (r.error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
+  return { status: r.status, stdout: typeof r.stdout === "string" ? r.stdout : "", missing };
+};
+
+export interface ProcessRow {
+  pid: number;
+  command: string;
+}
+
+/** Parse `ps -axo pid=,command=` output (also the shape the PowerShell probe emits). */
+export function parseProcessRows(output: string): ProcessRow[] {
+  const rows: ProcessRow[] = [];
+  for (const line of output.split(/\r?\n/)) {
+    const m = line.match(/^\s*(\d+)\s+(.*\S)\s*$/);
+    if (m) rows.push({ pid: Number(m[1]), command: m[2] as string });
+  }
+  return rows;
+}
+
+const POWERSHELL_PROCESS_LIST =
+  "Get-CimInstance Win32_Process | Where-Object { $_.CommandLine } | " +
+  'ForEach-Object { "$($_.ProcessId) $($_.CommandLine)" }';
+
+/** Every process with a command line, or null when the platform gives no way to list them. */
+export function listProcesses(
+  platform: NodeJS.Platform = process.platform,
+  run: Run = runTool,
+): ProcessRow[] | null {
+  if (platform === "win32") {
+    for (const shell of ["powershell.exe", "pwsh.exe", "pwsh"]) {
+      const r = run(shell, ["-NoProfile", "-NonInteractive", "-Command", POWERSHELL_PROCESS_LIST]);
+      if (r.missing) continue;
+      if (r.status === 0) return parseProcessRows(r.stdout);
+    }
+    return null;
+  }
+  const ps = run("ps", ["-axo", "pid=,command="]);
+  return ps.status === 0 ? parseProcessRows(ps.stdout) : null;
+}
+
+/**
+ * PIDs whose command line matches `pattern`, an extended regular expression
+ * (the intersection of `pgrep -f` and JavaScript syntax). Returns [] when
+ * nothing matches or no listing tool works.
+ */
+export function findPidsByCommandLine(
+  pattern: string,
+  platform: NodeJS.Platform = process.platform,
+  run: Run = runTool,
+): number[] {
+  if (platform !== "win32") {
+    // `--` ends options: the provider pattern starts with `--url`, which pgrep
+    // would otherwise reject as an unknown flag and report as "no match".
+    const r = run("pgrep", ["-f", "--", pattern]);
+    if (!r.missing) {
+      if (r.status !== 0) return [];
+      return r.stdout
+        .split("\n")
+        .map((line) => Number(line.trim()))
+        .filter((pid) => Number.isInteger(pid) && pid > 0);
+    }
+  }
+  const rows = listProcesses(platform, run);
+  if (!rows) return [];
+  const re = new RegExp(pattern);
+  return rows.filter((row) => re.test(row.command)).map((row) => row.pid);
+}
+
+/** Ports from `ss -tlnH`: `LISTEN 0 4096 127.0.0.1:9001 0.0.0.0:*`. */
+export function parseSsPorts(output: string): number[] {
+  return [...output.matchAll(/:(\d+)\s/g)].map((m) => Number(m[1]));
+}
+
+/** Ports from `lsof -nP -iTCP -sTCP:LISTEN` rows ending `127.0.0.1:58055 (LISTEN)`. */
+export function parseLsofPorts(output: string): number[] {
+  return [...output.matchAll(/:(\d+) \(LISTEN\)\s*$/gm)].map((m) => Number(m[1]));
+}
+
+/** Ports from `netstat -ano -p TCP` rows: `TCP 0.0.0.0:9001 0.0.0.0:0 LISTENING 4`. */
+export function parseNetstatPorts(output: string): number[] {
+  return [...output.matchAll(/^\s*TCP\s+\S*:(\d+)\s+\S+\s+LISTENING\b/gim)].map((m) =>
+    Number(m[1]),
+  );
+}
+
+/**
+ * Ports with a LISTEN socket, or null when no discovery tool answered.
+ *
+ * Null is not "no ports": reporting every port as free would let a caller hand
+ * out an occupied port, so callers that need a real answer use `portListening`,
+ * which falls back to connecting.
+ */
+export function listeningPorts(
+  platform: NodeJS.Platform = process.platform,
+  run: Run = runTool,
+): Set<number> | null {
+  if (platform === "win32") {
+    const r = run("netstat", ["-ano", "-p", "TCP"]);
+    return !r.missing && r.status === 0 ? new Set(parseNetstatPorts(r.stdout)) : null;
+  }
+  if (platform === "linux") {
+    const ss = run("ss", ["-tlnH"]);
+    if (!ss.missing && ss.status === 0) return new Set(parseSsPorts(ss.stdout));
+  }
+  // macOS and BSD, or Linux without iproute2. lsof reports a failure when any
+  // single process is unreadable while stdout still holds usable rows, so
+  // judge it on the output.
+  const lsof = run("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN"]);
+  if (!lsof.missing && lsof.stdout.trim()) return new Set(parseLsofPorts(lsof.stdout));
+  return null;
+}
+
+/** True when something accepts a TCP connection on 127.0.0.1:<port>. */
+export function connectProbe(port: number, timeoutMs = 400): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = connect({ port, host: "127.0.0.1" });
+    const done = (result: boolean) => {
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setTimeout(timeoutMs, () => done(false));
+    socket.once("connect", () => done(true));
+    socket.once("error", () => done(false));
+  });
+}
+
+/** Whether `port` has a listener, by the platform tool when there is one, else by connecting. */
+export async function portListening(port: number): Promise<boolean> {
+  const ports = listeningPorts();
+  return ports ? ports.has(port) : connectProbe(port);
+}

package/src/lib/tunnel/state.ts

@@ -1,22 +1,43 @@
 // Tunnel config + state persistence + provider helpers. Commands default to
 // <cwd>/.cache/tunnel/; gitignored, so the allowlist is per-machine.
 
-import { execSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import {
+  accessSync,
+  chmodSync,
+  constants,
   existsSync,
   mkdirSync,
   readdirSync,
   readFileSync,
+  statSync,
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { delimiter, join, resolve } from "node:path";
 import { isPathAllowed } from "./path-scope.ts";
 
-// Tunnel state lives under <root>/.cache/tunnel/. Root defaults to cwd for the
-// command surface and can be supplied by callers that already resolved a repo.
-function cachePath(tool: string, filename: string, root: string = process.cwd()): string {
-  const dir = resolve(root, ".cache", tool);
+/** Overrides the directory that holds tunnel state and config (a host keeps it out of `.cache/`). */
+export const TUNNEL_DIR_ENV = "HARNERY_TUNNEL_DIR";
+/** Explicit cloudflared binary, for a host that ships a managed copy. */
+export const CLOUDFLARED_ENV = "HARNERY_CLOUDFLARED";
+
+/**
+ * Where tunnel state lives: `$HARNERY_TUNNEL_DIR` when set, else
+ * `<root>/.cache/tunnel/`. Root defaults to cwd for the command surface and can
+ * be supplied by callers that already resolved a repo.
+ */
+export function tunnelDir(
+  root: string = process.cwd(),
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const override = env[TUNNEL_DIR_ENV]?.trim();
+  return override ? resolve(override) : resolve(root, ".cache", "tunnel");
+}
+
+function cachePath(filename: string, root: string = process.cwd()): string {
+  const dir = tunnelDir(root);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   return resolve(dir, filename);
 }
@@ -63,7 +84,16 @@ const DEFAULT_CONFIG: TunnelConfig = {
 };
 
 export interface TunnelConfig {
+  /** Exact addresses and CIDR ranges the gate admits (Cloudflare provider). */
   allowed_ips: string[];
+  /**
+   * Entries `allow add --current` added for this machine's own public
+   * addresses. They are a subset of `allowed_ips`; the next refresh replaces
+   * exactly these and never touches an entry added by hand.
+   */
+  auto_allowed?: string[];
+  /** Explicit cloudflared binary; `$HARNERY_CLOUDFLARED` wins over this. */
+  cloudflared_path?: string;
 }
 
 export type TunnelProvider = "cloudflare" | "tailscale";
@@ -104,27 +134,31 @@ function normalizeState(raw: TunnelState, fallbackName: string): TunnelState {
 }
 
 export function readConfig(): TunnelConfig {
-  const p = cachePath("tunnel", CONFIG_FILE);
+  const p = cachePath(CONFIG_FILE);
   if (!existsSync(p)) {
     writeConfig(DEFAULT_CONFIG);
     return { ...DEFAULT_CONFIG, allowed_ips: [...DEFAULT_CONFIG.allowed_ips] };
   }
   try {
-    return JSON.parse(readFileSync(p, "utf-8")) as TunnelConfig;
+    const parsed = JSON.parse(readFileSync(p, "utf-8")) as Partial<TunnelConfig>;
+    return {
+      ...parsed,
+      allowed_ips: Array.isArray(parsed.allowed_ips) ? parsed.allowed_ips : [],
+    };
   } catch {
     return { ...DEFAULT_CONFIG, allowed_ips: [...DEFAULT_CONFIG.allowed_ips] };
   }
 }
 
 export function writeConfig(cfg: TunnelConfig): void {
-  writeFileSync(cachePath("tunnel", CONFIG_FILE), JSON.stringify(cfg, null, 2));
+  writeFileSync(cachePath(CONFIG_FILE), JSON.stringify(cfg, null, 2));
 }
 
 export function readState(
   name: string = DEFAULT_INSTANCE,
   root: string = process.cwd(),
 ): TunnelState | null {
-  const p = cachePath("tunnel", stateFile(name), root);
+  const p = cachePath(stateFile(name), root);
   if (!existsSync(p)) return null;
   try {
     return normalizeState(JSON.parse(readFileSync(p, "utf-8")) as TunnelState, name);
@@ -134,11 +168,11 @@ export function readState(
 }
 
 export function writeState(state: TunnelState, root: string = process.cwd()): void {
-  writeFileSync(cachePath("tunnel", stateFile(state.name), root), JSON.stringify(state, null, 2));
+  writeFileSync(cachePath(stateFile(state.name), root), JSON.stringify(state, null, 2));
 }
 
 export function clearState(name: string = DEFAULT_INSTANCE, root: string = process.cwd()): void {
-  const p = cachePath("tunnel", stateFile(name), root);
+  const p = cachePath(stateFile(name), root);
   if (existsSync(p)) unlinkSync(p);
 }
 
@@ -147,7 +181,7 @@ export function clearState(name: string = DEFAULT_INSTANCE, root: string = proce
  * `state*.json` under `.cache/tunnel/`; tolerates missing/corrupt files.
  */
 export function listStates(root: string = process.cwd()): TunnelState[] {
-  const dir = resolve(root, ".cache", "tunnel");
+  const dir = tunnelDir(root);
   if (!existsSync(dir)) return [];
   const out: TunnelState[] = [];
   for (const file of readdirSync(dir)) {
@@ -226,31 +260,93 @@ export function tunnelServesPaths(state: TunnelState, paths: readonly string[]):
   return paths.every((path) => isPathAllowed(path, state.allow_paths));
 }
 
-/**
- * Ensure cloudflared is on PATH or installed at ~/.local/bin/cloudflared.
- * Auto-downloads on Linux; throws on other platforms with brew hint.
- */
-export function ensureCloudflared(): string {
+function isRunnableFile(path: string): boolean {
   try {
-    execSync("command -v cloudflared", { stdio: "ignore" });
-    return "cloudflared";
+    if (!statSync(path).isFile()) return false;
+    if (process.platform === "win32") return true;
+    accessSync(path, constants.X_OK);
+    return true;
   } catch {
-    /* not on PATH; fall through */
+    return false;
   }
-  const local = `${process.env.HOME}/.local/bin/cloudflared`;
-  if (existsSync(local)) return local;
+}
+
+/** First `name` on PATH (honoring `.exe` on Windows), or null. Needs no shell. */
+function findOnPath(name: string, env: NodeJS.ProcessEnv = process.env): string | null {
+  const names = process.platform === "win32" ? [`${name}.exe`, name] : [name];
+  for (const dir of (env.PATH ?? env.Path ?? "").split(delimiter)) {
+    if (!dir) continue;
+    for (const candidate of names) {
+      const full = join(dir, candidate);
+      if (isRunnableFile(full)) return full;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the cloudflared binary:
+ *   1. `$HARNERY_CLOUDFLARED`, then `cloudflared_path` in the tunnel config: an
+ *      explicit choice, so a missing or non-runnable file is an error, never a
+ *      silent fall-through to some other copy.
+ *   2. `cloudflared` on PATH.
+ *   3. `~/.local/bin/cloudflared`.
+ *   4. Linux x86-64 and arm64: download the latest release to (3).
+ * Elsewhere it throws with install guidance.
+ */
+export function ensureCloudflared(
+  env: NodeJS.ProcessEnv = process.env,
+  configuredPath: string | undefined = readConfig().cloudflared_path,
+): string {
+  const explicit = env[CLOUDFLARED_ENV]?.trim();
+  const fromConfig = configuredPath?.trim();
+  for (const [source, path] of [
+    [CLOUDFLARED_ENV, explicit],
+    ["cloudflared_path in the tunnel config", fromConfig],
+  ] as const) {
+    if (!path) continue;
+    if (isRunnableFile(path)) return path;
+    throw new Error(
+      `cloudflared is set by ${source} to ${path}, but that file is missing or not runnable.`,
+    );
+  }
+
+  const onPath = findOnPath("cloudflared", env);
+  if (onPath) return onPath;
+  const exe = process.platform === "win32" ? "cloudflared.exe" : "cloudflared";
+  const local = join(homedir(), ".local", "bin", exe);
+  if (isRunnableFile(local)) return local;
 
-  if (process.platform !== "linux") {
+  const asset =
+    process.platform === "linux"
+      ? (
+          { x64: "cloudflared-linux-amd64", arm64: "cloudflared-linux-arm64" } as Record<
+            string,
+            string
+          >
+        )[process.arch]
+      : undefined;
+  if (!asset) {
     throw new Error(
-      "cloudflared not installed. On macOS: `brew install cloudflared`. " +
+      "cloudflared not installed. Install it (macOS: `brew install cloudflared`; Windows: " +
+        "`winget install Cloudflare.cloudflared`), or point `$HARNERY_CLOUDFLARED` at a binary. " +
         "On Linux it auto-installs to ~/.local/bin/cloudflared.",
     );
   }
 
   process.stderr.write("Installing cloudflared to ~/.local/bin/...\n"); // lint-ok-emission: sync setup phase before structured output; pairs with the inherited stdio of the curl below
-  execSync(
-    `curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o ${local} && chmod +x ${local}`,
+  mkdirSync(join(homedir(), ".local", "bin"), { recursive: true });
+  const download = spawnSync(
+    "curl",
+    [
+      "-fsSL",
+      `https://github.com/cloudflare/cloudflared/releases/latest/download/${asset}`,
+      "-o",
+      local,
+    ],
     { stdio: "inherit" },
   );
+  if (download.status !== 0) throw new Error("Downloading cloudflared failed; install it by hand.");
+  chmodSync(local, 0o755);
   return local;
 }