harnery 0.42.0 → 0.43.0

package/dist/lib/tunnel/gate.js

@@ -11,6 +11,7 @@
 // Runs detached, outside the CLI command framework; no command context is
 // available; stdout/stderr is captured into .cache/tunnel/gate.log by the
 // spawner.
+import { allowlistMatches, compileAllowlist } from "./allowlist.js";
 import { renderTunnelErrorPage } from "./error-page";
 import { applyUpstreamHeaders } from "./forward-headers";
 import { ALLOW_PATHS_ENV, isPathAllowed, parseAllowPathsEnv } from "./path-scope.js";
@@ -24,10 +25,8 @@ function argvFlag(flag) {
     const i = process.argv.indexOf(flag);
     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");
@@ -66,7 +65,7 @@ const server = Bun.serve({
         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.
@@ -187,4 +186,12 @@ const server = Bun.serve({
 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/dist/lib/tunnel/processes.d.ts

@@ -0,0 +1,39 @@
+type Run = (command: string, args: string[]) => {
+    status: number | null;
+    stdout: string;
+    missing: boolean;
+};
+export interface ProcessRow {
+    pid: number;
+    command: string;
+}
+/** Parse `ps -axo pid=,command=` output (also the shape the PowerShell probe emits). */
+export declare function parseProcessRows(output: string): ProcessRow[];
+/** Every process with a command line, or null when the platform gives no way to list them. */
+export declare function listProcesses(platform?: NodeJS.Platform, run?: Run): ProcessRow[] | 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 declare function findPidsByCommandLine(pattern: string, platform?: NodeJS.Platform, run?: Run): number[];
+/** Ports from `ss -tlnH`: `LISTEN 0 4096 127.0.0.1:9001 0.0.0.0:*`. */
+export declare function parseSsPorts(output: string): number[];
+/** Ports from `lsof -nP -iTCP -sTCP:LISTEN` rows ending `127.0.0.1:58055 (LISTEN)`. */
+export declare function parseLsofPorts(output: string): number[];
+/** Ports from `netstat -ano -p TCP` rows: `TCP 0.0.0.0:9001 0.0.0.0:0 LISTENING 4`. */
+export declare function parseNetstatPorts(output: string): number[];
+/**
+ * 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 declare function listeningPorts(platform?: NodeJS.Platform, run?: Run): Set<number> | null;
+/** True when something accepts a TCP connection on 127.0.0.1:<port>. */
+export declare function connectProbe(port: number, timeoutMs?: number): Promise<boolean>;
+/** Whether `port` has a listener, by the platform tool when there is one, else by connecting. */
+export declare function portListening(port: number): Promise<boolean>;
+export {};
+//# sourceMappingURL=processes.d.ts.map

package/dist/lib/tunnel/processes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processes.d.ts","sourceRoot":"","sources":["../../../src/lib/tunnel/processes.ts"],"names":[],"mappings":"AAWA,KAAK,GAAG,GAAG,CACT,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAQjE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wFAAwF;AACxF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,CAO7D;AAMD,8FAA8F;AAC9F,wBAAgB,aAAa,CAC3B,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,GAAG,GAAE,GAAa,GACjB,UAAU,EAAE,GAAG,IAAI,CAWrB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,GAAG,GAAE,GAAa,GACjB,MAAM,EAAE,CAiBV;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAErD;AAED,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAEvD;AAED,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAI1D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,GAAG,GAAE,GAAa,GACjB,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAepB;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAW5E;AAED,iGAAiG;AACjG,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGlE"}

package/dist/lib/tunnel/processes.js

@@ -0,0 +1,121 @@
+// 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";
+const runTool = (command, args) => {
+    const r = spawnSync(command, args, { encoding: "utf-8", windowsHide: true, timeout: 15_000 });
+    const missing = r.error?.code === "ENOENT";
+    return { status: r.status, stdout: typeof r.stdout === "string" ? r.stdout : "", missing };
+};
+/** Parse `ps -axo pid=,command=` output (also the shape the PowerShell probe emits). */
+export function parseProcessRows(output) {
+    const rows = [];
+    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] });
+    }
+    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 = process.platform, run = runTool) {
+    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, platform = process.platform, run = runTool) {
+    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) {
+    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) {
+    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) {
+    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 = process.platform, run = runTool) {
+    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, timeoutMs = 400) {
+    return new Promise((resolve) => {
+        const socket = connect({ port, host: "127.0.0.1" });
+        const done = (result) => {
+            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) {
+    const ports = listeningPorts();
+    return ports ? ports.has(port) : connectProbe(port);
+}

package/dist/lib/tunnel/state.d.ts

@@ -1,10 +1,29 @@
+/** Overrides the directory that holds tunnel state and config (a host keeps it out of `.cache/`). */
+export declare const TUNNEL_DIR_ENV = "HARNERY_TUNNEL_DIR";
+/** Explicit cloudflared binary, for a host that ships a managed copy. */
+export declare 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 declare function tunnelDir(root?: string, env?: NodeJS.ProcessEnv): string;
 /** The default instance name when `--name` is omitted. */
 export declare const DEFAULT_INSTANCE = "default";
 export declare function gateLogFile(name: string): string;
 export declare function cfdLogFile(name: string): string;
 export declare function providerLogFile(name: string, provider: TunnelProvider): string;
 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";
 export type TailscaleMode = "serve" | "funnel";
@@ -57,8 +76,14 @@ export declare function findLiveTunnelForOrigin(port: number, vhost: string, roo
 /** True when the tunnel's path scope forwards every one of `paths`. */
 export declare function tunnelServesPaths(state: TunnelState, paths: readonly string[]): boolean;
 /**
- * Ensure cloudflared is on PATH or installed at ~/.local/bin/cloudflared.
- * Auto-downloads on Linux; throws on other platforms with brew hint.
+ * 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 declare function ensureCloudflared(): string;
+export declare function ensureCloudflared(env?: NodeJS.ProcessEnv, configuredPath?: string | undefined): string;
 //# sourceMappingURL=state.d.ts.map

package/dist/lib/tunnel/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/lib/tunnel/state.ts"],"names":[],"mappings":"AAyBA,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAW1C,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,MAAM,CAG9E;AAgBD,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,WAAW,CAAC;AACxD,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,cAAc,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAgBD,wBAAgB,UAAU,IAAI,YAAY,CAWzC;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAEnD;AAED,wBAAgB,SAAS,CACvB,IAAI,GAAE,MAAyB,EAC/B,IAAI,GAAE,MAAsB,GAC3B,WAAW,GAAG,IAAI,CAQpB;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,GAAE,MAAsB,GAAG,IAAI,CAEjF;AAED,wBAAgB,UAAU,CAAC,IAAI,GAAE,MAAyB,EAAE,IAAI,GAAE,MAAsB,GAAG,IAAI,CAG9F;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,MAAsB,GAAG,WAAW,EAAE,CAWtE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOnD;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;AAEzD,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,YAAY,GAAE,iBAAkC,GAC/C,OAAO,CAKT;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAWlE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,MAAsB,EAC5B,YAAY,GAAE,iBAAkC,GAC/C,WAAW,GAAG,IAAI,CASpB;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAEvF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAuB1C"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/lib/tunnel/state.ts"],"names":[],"mappings":"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"}

package/dist/lib/tunnel/state.js

@@ -1,13 +1,25 @@
 // 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 { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
-import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { accessSync, chmodSync, constants, existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join, resolve } from "node:path";
 import { isPathAllowed } from "./path-scope.js";
-// 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, filename, root = process.cwd()) {
-    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 = process.cwd(), env = process.env) {
+    const override = env[TUNNEL_DIR_ENV]?.trim();
+    return override ? resolve(override) : resolve(root, ".cache", "tunnel");
+}
+function cachePath(filename, root = process.cwd()) {
+    const dir = tunnelDir(root);
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
     return resolve(dir, filename);
@@ -61,23 +73,27 @@ function normalizeState(raw, fallbackName) {
     };
 }
 export function readConfig() {
-    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"));
+        const parsed = JSON.parse(readFileSync(p, "utf-8"));
+        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) {
-    writeFileSync(cachePath("tunnel", CONFIG_FILE), JSON.stringify(cfg, null, 2));
+    writeFileSync(cachePath(CONFIG_FILE), JSON.stringify(cfg, null, 2));
 }
 export function readState(name = DEFAULT_INSTANCE, root = process.cwd()) {
-    const p = cachePath("tunnel", stateFile(name), root);
+    const p = cachePath(stateFile(name), root);
     if (!existsSync(p))
         return null;
     try {
@@ -88,10 +104,10 @@ export function readState(name = DEFAULT_INSTANCE, root = process.cwd()) {
     }
 }
 export function writeState(state, root = process.cwd()) {
-    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 = DEFAULT_INSTANCE, root = process.cwd()) {
-    const p = cachePath("tunnel", stateFile(name), root);
+    const p = cachePath(stateFile(name), root);
     if (existsSync(p))
         unlinkSync(p);
 }
@@ -100,7 +116,7 @@ export function clearState(name = DEFAULT_INSTANCE, root = process.cwd()) {
  * `state*.json` under `.cache/tunnel/`; tolerates missing/corrupt files.
  */
 export function listStates(root = process.cwd()) {
-    const dir = resolve(root, ".cache", "tunnel");
+    const dir = tunnelDir(root);
     if (!existsSync(dir))
         return [];
     const out = [];
@@ -166,26 +182,81 @@ export function findLiveTunnelForOrigin(port, vhost, root = process.cwd(), proce
 export function tunnelServesPaths(state, paths) {
     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() {
+function isRunnableFile(path) {
     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;
+    }
+}
+/** First `name` on PATH (honoring `.exe` on Windows), or null. Needs no shell. */
+function findOnPath(name, env = process.env) {
+    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 = process.env, configuredPath = readConfig().cloudflared_path) {
+    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],
+    ]) {
+        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 local = `${process.env.HOME}/.local/bin/cloudflared`;
-    if (existsSync(local))
+    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") {
-        throw new Error("cloudflared not installed. On macOS: `brew install cloudflared`. " +
+    const asset = process.platform === "linux"
+        ? { x64: "cloudflared-linux-amd64", arm64: "cloudflared-linux-arm64" }[process.arch]
+        : undefined;
+    if (!asset) {
+        throw new Error("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}`, { stdio: "inherit" });
+    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;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",
@@ -266,6 +266,7 @@
     "test:web": "cd web && bun install && bun test",
     "test:integration": "bash tests/integration/run.sh",
     "smoke": "node scripts/smoke-test.mjs",
+    "check:local": "node scripts/check-local.mjs",
     "docs:dev": "bun run --cwd docs dev",
     "docs:build": "bun run --cwd docs build",
     "brand:showcase": "node scripts/build-brand-showcase.mjs",

package/src/commander.ts

@@ -280,6 +280,38 @@ export async function registerHarneryLogStorageCommands(
   return parent;
 }
 
+export interface HarneryTunnelCommandOptions {
+  emit?: EmitContext;
+  context?: HarneryProgramContext;
+}
+
+/**
+ * Mount `tunnel` under `parent`, for a host whose own program does not come
+ * from `createHarneryProgram` (a host CLI that exposes the tunnel as one of its
+ * command families).
+ */
+export async function registerHarneryTunnelCommand(
+  parent: Command,
+  options: HarneryTunnelCommandOptions = {},
+): Promise<Command> {
+  const { registerTunnelCommand } = await import("./commands/tunnel.ts");
+  registerTunnelCommand(parent, options.emit ?? defaultEmit, options.context);
+  return parent;
+}
+
+export type { RefreshCurrentOptions, RefreshCurrentResult } from "./commands/tunnel.ts";
+
+/**
+ * `tunnel allow add --current` as a function: allow this machine's public
+ * addresses and optionally reload running gates, keeping their URLs.
+ */
+export async function refreshTunnelCurrentAddress(
+  options: import("./commands/tunnel.ts").RefreshCurrentOptions,
+): Promise<import("./commands/tunnel.ts").RefreshCurrentResult> {
+  const { refreshCurrentAddress } = await import("./commands/tunnel.ts");
+  return refreshCurrentAddress(options);
+}
+
 export function createHarneryProgram(opts: HarneryContextOpts = {}): Command {
   const program = new Command();
   const emit = opts.emit ?? defaultEmit;