harnery 0.41.0 → 0.43.0

package/src/lib/tunnel/current-address.ts

@@ -0,0 +1,158 @@
+// This machine's public addresses as Cloudflare sees them, and the allowlist
+// bookkeeping around them (`tunnel allow add --current`).
+//
+// The tunnel gate admits a visitor by the `CF-Connecting-IP` header, which is
+// the address Cloudflare saw. Asking Cloudflare's own trace endpoint therefore
+// returns the same address the gate will later compare, with no third party and
+// no guess about NAT. The IPv4 and IPv6 probes use address literals, so each
+// travels over the family it is named for and needs no DNS.
+//
+// Entries the refresh adds are recorded in `auto_allowed`. The next refresh
+// replaces exactly those, so a machine that changes network does not pile up
+// stale addresses, and an entry added by hand is never removed.
+
+import { ipv4Slash32, ipv6Slash64, normalizeAllowEntry } from "./allowlist.ts";
+import type { TunnelConfig } from "./state.ts";
+
+export const TRACE_URL_V4 = "https://1.1.1.1/cdn-cgi/trace";
+export const TRACE_URL_V6 = "https://[2606:4700:4700::1111]/cdn-cgi/trace";
+
+export interface DetectedAddresses {
+  v4?: string;
+  v6?: string;
+  /** One note per family that could not be read. */
+  failures: string[];
+}
+
+export interface DetectOptions {
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+  /** Tries per family; a transient failure on a flaky network should not drop an address. */
+  attempts?: number;
+}
+
+/** The `ip=` value of a Cloudflare trace body, or null. */
+export function parseTraceIp(body: string): string | null {
+  const m = body.match(/^ip=(\S+)\s*$/m);
+  return m ? (m[1] as string) : null;
+}
+
+async function probe(url: string, family: 4 | 6, opts: Required<DetectOptions>): Promise<string> {
+  let last = "no answer";
+  for (let attempt = 0; attempt < opts.attempts; attempt++) {
+    try {
+      const res = await opts.fetch(url, { signal: AbortSignal.timeout(opts.timeoutMs) });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const ip = parseTraceIp(await res.text());
+      if (!ip) throw new Error("the trace had no ip= line");
+      const entry = family === 4 ? ipv4Slash32(ip) : ipv6Slash64(ip);
+      if (!entry) throw new Error(`expected an IPv${family} address, got ${ip}`);
+      return ip;
+    } catch (error) {
+      last = error instanceof Error ? error.message : String(error);
+    }
+  }
+  throw new Error(last);
+}
+
+/** Both families in parallel. A family that fails is reported, not thrown. */
+export async function detectPublicAddresses(
+  options: DetectOptions = {},
+): Promise<DetectedAddresses> {
+  const opts: Required<DetectOptions> = {
+    fetch: options.fetch ?? fetch,
+    timeoutMs: options.timeoutMs ?? 4_000,
+    attempts: options.attempts ?? 2,
+  };
+  const [v4, v6] = await Promise.allSettled([
+    probe(TRACE_URL_V4, 4, opts),
+    probe(TRACE_URL_V6, 6, opts),
+  ]);
+  const out: DetectedAddresses = { failures: [] };
+  if (v4.status === "fulfilled") out.v4 = v4.value;
+  else out.failures.push(`IPv4: ${(v4.reason as Error).message}`);
+  if (v6.status === "fulfilled") out.v6 = v6.value;
+  else out.failures.push(`IPv6: ${(v6.reason as Error).message}`);
+  return out;
+}
+
+export interface CurrentAddressPlan {
+  config: TunnelConfig;
+  /** Entries newly present in the allowlist. */
+  added: string[];
+  /** Automatic entries from an earlier refresh that are now gone. */
+  removed: string[];
+  /** The automatic entries after this refresh (the detected, not already listed by hand). */
+  automatic: string[];
+  changed: boolean;
+  warnings: string[];
+}
+
+const sameEntry = (a: string, b: string) =>
+  (normalizeAllowEntry(a) ?? a) === (normalizeAllowEntry(b) ?? b);
+const includesEntry = (list: readonly string[], entry: string) =>
+  list.some((e) => sameEntry(e, entry));
+
+/**
+ * Fold freshly detected addresses into the allowlist.
+ *
+ * When nothing was detected the config comes back untouched with a warning:
+ * a failed lookup must never empty the list. When at least one family was
+ * detected, a family that was not is treated as absent from this network, so
+ * its old automatic entry goes. The entries for the detected families replace
+ * every previous automatic entry; manual entries are kept in place.
+ */
+export function planCurrentAddresses(
+  config: TunnelConfig,
+  detected: DetectedAddresses,
+): CurrentAddressPlan {
+  const previousAuto = config.auto_allowed ?? [];
+  const wanted: string[] = [];
+  if (detected.v4) {
+    const entry = ipv4Slash32(detected.v4);
+    if (entry) wanted.push(entry);
+  }
+  if (detected.v6) {
+    const entry = ipv6Slash64(detected.v6);
+    if (entry) wanted.push(entry);
+  }
+
+  if (wanted.length === 0) {
+    return {
+      config,
+      added: [],
+      removed: [],
+      automatic: previousAuto,
+      changed: false,
+      warnings: [
+        `Could not detect this machine's public address (${detected.failures.join("; ") || "no answer"}). ` +
+          `The allowlist is unchanged${previousAuto.length ? `; the previous automatic entries stay: ${previousAuto.join(", ")}` : ""}.`,
+      ],
+    };
+  }
+
+  const manual = config.allowed_ips.filter((e) => !includesEntry(previousAuto, e));
+  // An address already listed by hand stays manual, so a later refresh keeps it.
+  const automatic = wanted.filter((e) => !includesEntry(manual, e));
+  const allowed = [...manual, ...automatic];
+  const before = config.allowed_ips;
+  const added = allowed.filter((e) => !includesEntry(before, e));
+  const removed = before.filter((e) => !includesEntry(allowed, e));
+  const warnings: string[] = [];
+  const missing = [detected.v4 ? null : "IPv4", detected.v6 ? null : "IPv6"].filter(Boolean);
+  if (missing.length > 0) {
+    warnings.push(
+      `${missing.join(" and ")} was not detected, so this network is treated as having none` +
+        (detected.failures.length ? ` (${detected.failures.join("; ")})` : "") +
+        ".",
+    );
+  }
+  return {
+    config: { ...config, allowed_ips: allowed, auto_allowed: automatic },
+    added,
+    removed,
+    automatic,
+    changed: added.length > 0 || removed.length > 0,
+    warnings,
+  };
+}

package/src/lib/tunnel/error-page.ts

@@ -1,5 +1,5 @@
 export interface TunnelErrorPageOptions {
-  kind: "access-denied" | "upstream-unavailable";
+  kind: "access-denied" | "path-denied" | "upstream-unavailable";
   incidentId: string;
   timestamp: string;
   tunnelName: string;
@@ -40,14 +40,30 @@ function diagnosticText(options: TunnelErrorPageOptions): string {
 }
 
 export function renderTunnelErrorPage(options: TunnelErrorPageOptions): string {
-  const denied = options.kind === "access-denied";
-  const title = denied ? "This device is not allowed yet" : "The preview is temporarily offline";
-  const summary = denied
-    ? "The tunnel is running, but this device's public IP is not on its access list."
-    : "The public tunnel and access check are working, but the local preview server is not responding.";
-  const nextStep = denied
-    ? "Copy the diagnostic below and send it to the person running the tunnel. It includes the public IP that needs to be allowed."
-    : "Copy the diagnostic below and send it to the person running the tunnel. The incident ID can be matched to the server log.";
+  const copy = {
+    "access-denied": {
+      title: "This device is not allowed yet",
+      summary: "The tunnel is running, but this device's public IP is not on its access list.",
+      nextStep:
+        "Copy the diagnostic below and send it to the person running the tunnel. It includes the public IP that needs to be allowed.",
+    },
+    "path-denied": {
+      title: "This page is not shared",
+      summary:
+        "The tunnel is running, but it shares only part of the site, and this address is outside it.",
+      nextStep:
+        "If you expected to see this page, copy the diagnostic below and send it to the person running the tunnel.",
+    },
+    "upstream-unavailable": {
+      title: "The preview is temporarily offline",
+      summary:
+        "The public tunnel and access check are working, but the local preview server is not responding.",
+      nextStep:
+        "Copy the diagnostic below and send it to the person running the tunnel. The incident ID can be matched to the server log.",
+    },
+  }[options.kind];
+  const { title, summary, nextStep } = copy;
+  const denied = options.kind !== "upstream-unavailable";
   const diagnostic = diagnosticText(options);
   const safeDiagnosticForScript = JSON.stringify(diagnostic).replaceAll("<", "\\u003c");
 

package/src/lib/tunnel/gate.ts

@@ -4,14 +4,18 @@
 // stripped (Bun's fetch auto-decompresses the body but retains the encoding
 // header, which breaks browser decoding downstream). Cloudflare provider mode
 // checks CF-Connecting-IP against an allowlist; trusted local proxy mode lets
-// the local exposer own access.
+// the local exposer own access. In every mode the gate then refuses any path
+// outside the tunnel's path scope (see path-scope.ts); an empty scope refuses
+// everything.
 //
 // 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.ts";
 import { renderTunnelErrorPage } from "./error-page";
 import { applyUpstreamHeaders } from "./forward-headers";
+import { ALLOW_PATHS_ENV, isPathAllowed, parseAllowPathsEnv } from "./path-scope.ts";
 
 // `--port`/`--name` are also passed on argv (not just env) so the gate's port
 // and instance name show up in its process command line. That's what lets
@@ -24,16 +28,13 @@ 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");
 const ACCESS = process.env.HARNERY_TUNNEL_ACCESS ?? "cloudflare-allowlist";
+const ALLOW_PATHS = parseAllowPathsEnv(process.env[ALLOW_PATHS_ENV]);
 const NAME = argvFlag("--name") ?? "default";
 
 const UPSTREAM_HTTP = `http://${TARGET}`;
@@ -77,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.
@@ -96,6 +97,22 @@ const server = Bun.serve<WsData, never>({
       }
     }
 
+    if (!isPathAllowed(url.pathname, ALLOW_PATHS)) {
+      const details = requestDetails(req, url);
+      console.log(
+        // lint-ok-emission: detached worker, see file note above
+        `path-deny: incident=${details.incidentId} ip=${details.clientIp || "(missing-cf-connecting-ip)"} ray=${details.cloudflareRay || "(missing)"} ${req.method} ${details.path}`,
+      );
+      return new Response(renderTunnelErrorPage({ ...details, kind: "path-denied" }), {
+        status: 403,
+        headers: {
+          "cache-control": "no-store",
+          "content-type": "text/html; charset=utf-8",
+          "x-harnery-tunnel-incident": details.incidentId,
+        },
+      });
+    }
+
     if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
       if (
         server.upgrade(req, {
@@ -192,4 +209,16 @@ const server = Bun.serve<WsData, never>({
 // captured into .cache/tunnel/gate.log by the spawning command.
 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(`allow: ${[...ALLOW].join(", ") || "(empty, not used outside allowlist mode)"}`); // 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(
+  // 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/path-scope.ts

@@ -0,0 +1,73 @@
+// Path scope for the tunnel gate: the URL path prefixes a tunnel publishes.
+//
+// A tunnel forwards to a whole local app, but the person starting it usually
+// means to share one surface of that app. The gate therefore refuses every
+// request whose path is outside the scope the operator named at `tunnel up`,
+// and an empty scope refuses everything. `/` is the explicit way to publish
+// the whole upstream.
+
+/** Env var that carries the scope from `tunnel up` to the detached gate. */
+export const ALLOW_PATHS_ENV = "HARNERY_TUNNEL_ALLOW_PATHS";
+
+/**
+ * Normalize one `--allow-path` value to a canonical prefix: a leading slash,
+ * no trailing slash (except `/` itself), no query or fragment, and no dot,
+ * empty, or percent-encoded segment. Throws on anything the gate could not
+ * match unambiguously, so a typo fails at `tunnel up` instead of publishing
+ * more or less than intended.
+ */
+export function normalizeAllowPath(raw: string): string {
+  const value = raw.trim();
+  if (!value.startsWith("/")) {
+    throw new Error(`allow-path must start with "/": ${JSON.stringify(raw)}`);
+  }
+  if (/[?#%\\]/.test(value)) {
+    throw new Error(
+      `allow-path must be a plain path prefix without ?, #, %, or \\: ${JSON.stringify(raw)}`,
+    );
+  }
+  if (value === "/") return "/";
+  const trimmed = value.replace(/\/+$/, "");
+  const segments = trimmed.slice(1).split("/");
+  if (segments.some((s) => s === "" || s === "." || s === "..")) {
+    throw new Error(
+      `allow-path must not contain empty, "." or ".." segments: ${JSON.stringify(raw)}`,
+    );
+  }
+  return trimmed;
+}
+
+/** Normalize and de-duplicate a list of `--allow-path` values. */
+export function normalizeAllowPaths(raw: readonly string[]): string[] {
+  return [...new Set(raw.map(normalizeAllowPath))];
+}
+
+/** Parse the gate's env value (comma-separated, already normalized by `up`). */
+export function parseAllowPathsEnv(value: string | undefined): string[] {
+  return normalizeAllowPaths(
+    (value ?? "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+  );
+}
+
+// Encoded slash, backslash, dot, or percent. A request path carrying one of
+// these can be decoded differently by the gate and the upstream router (for
+// example `/share%2F..%2Fprivate`), so the gate refuses it outright rather than
+// guess which reading the upstream will use.
+const AMBIGUOUS_PATH = /%(2f|5c|2e|25)|\\/i;
+
+/**
+ * True when `pathname` (a WHATWG-parsed URL pathname, so `.` and `..` segments
+ * are already resolved) falls inside one of the allowed prefixes. A prefix
+ * matches itself and anything below it on a segment boundary: `/share` allows
+ * `/share` and `/share/x`, never `/shared`.
+ */
+export function isPathAllowed(pathname: string, allowPaths: readonly string[]): boolean {
+  if (allowPaths.length === 0) return false;
+  if (!pathname.startsWith("/") || AMBIGUOUS_PATH.test(pathname)) return false;
+  return allowPaths.some(
+    (prefix) => prefix === "/" || pathname === prefix || pathname.startsWith(`${prefix}/`),
+  );
+}

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);
+}