harnery 0.42.0 → 0.43.0

package/src/core/hooks/shell-waiter.ts

@@ -1,3 +1,5 @@
+import { basename, shellCommandFromTool, tokenize } from "./shell-tokens.ts";
+
 /** Recognize inline waiters; this is not a proof of arbitrary shell termination. */
 const REASON =
   "Inline shell waiter blocked: polling loops and delayed log-only checks can outlive the job " +
@@ -6,82 +8,6 @@ const REASON =
   "nonzero timeout exit, and producer-exit/failure detection. Do not create another waiter " +
   "to check progress or infer completion from a broad pgrep -f pattern.";
 
-interface Token {
-  value: string;
-  quoted: boolean;
-  operator?: boolean;
-}
-
-/** Keep quoted arguments opaque, including examples and heredoc bodies. */
-function tokenize(source: string): Token[] {
-  const out: Token[] = [];
-  const heredocs: { end: string; tabs: boolean }[] = [];
-  for (let i = 0; i < source.length; ) {
-    const ch = source[i]!;
-    if (ch === "\\" && source[i + 1] === "\n") {
-      i += 2;
-      continue;
-    }
-    if (ch === "\n") {
-      out.push({ value: ";", quoted: false, operator: true });
-      i++;
-      for (const doc of heredocs.splice(0)) {
-        while (i < source.length) {
-          const end = source.indexOf("\n", i);
-          const stop = end === -1 ? source.length : end;
-          const line = source.slice(i, stop);
-          i = end === -1 ? source.length : end + 1;
-          if ((doc.tabs ? line.replace(/^\t+/, "") : line) === doc.end) break;
-        }
-      }
-      continue;
-    }
-    if (/\s/.test(ch)) {
-      i++;
-      continue;
-    }
-    if (ch === "#") {
-      const end = source.indexOf("\n", i);
-      i = end === -1 ? source.length : end;
-      continue;
-    }
-    if (";|&(){}<>".includes(ch)) {
-      const op = source.slice(i).match(/^(?:<<-?|>>|&&|\|\||[;|&(){}<>])/)![0];
-      out.push({ value: op, quoted: false, operator: true });
-      i += op.length;
-      continue;
-    }
-    let value = "";
-    let quoted = false;
-    while (i < source.length && !/[\s;|&(){}<>]/.test(source[i]!)) {
-      const next = source[i++]!;
-      if (next === "'" || next === '"' || next === "`") {
-        quoted = true;
-        while (i < source.length && source[i] !== next) {
-          if (source[i] === "\\" && next !== "'" && i + 1 < source.length) i++;
-          value += source[i++]!;
-        }
-        if (source[i] === next) i++;
-      } else if (next === "\\" && i < source.length) {
-        const escaped = source[i++]!;
-        if (escaped !== "\n") value += escaped;
-      } else {
-        value += next;
-      }
-    }
-    const previous = out.at(-1)?.value;
-    if (previous === "<<" || previous === "<<-") {
-      heredocs.push({ end: value, tabs: previous === "<<-" });
-    }
-    out.push({ value, quoted });
-  }
-  return out;
-}
-
-function basename(value: string): string {
-  return value.split(/[\\/]/).at(-1) ?? value;
-}
-
 function isWaiter(source: string, depth = 0): boolean {
   if (depth > 8) return false;
   const tokens = tokenize(source);
@@ -148,19 +74,6 @@ function isWaiter(source: string, depth = 0): boolean {
 }
 
 export function shellWaiterReason(toolName: unknown, toolInput: unknown): string | null {
-  if (typeof toolName !== "string") return null;
-  const name = toolName.toLowerCase().replace(/^functions\./, "");
-  if (!["bash", "shell", "shell_command", "exec_command"].includes(name)) return null;
-  let input = toolInput;
-  if (typeof input === "string") {
-    try {
-      input = JSON.parse(input);
-    } catch {
-      return null;
-    }
-  }
-  if (!input || typeof input !== "object") return null;
-  const args = input as Record<string, unknown>;
-  const command = args.command ?? args.cmd;
-  return typeof command === "string" && isWaiter(command) ? REASON : null;
+  const command = shellCommandFromTool(toolName, toolInput);
+  return command !== null && isWaiter(command) ? REASON : null;
 }

package/src/core/storage/process-log.ts

@@ -38,6 +38,13 @@ export interface RotatingProcessOptions {
   env?: Readonly<Record<string, string | undefined>>;
   max_bytes?: number;
   backups?: number;
+  /**
+   * How to start the log wrapper, as an argv prefix that takes the JSON
+   * specification as its final argument and ends in `runProcessLogWorker`. The
+   * default runs this module's own file, which does not exist inside a
+   * single-file host bundle; such a host supplies a hidden task of its own.
+   */
+  worker?: { command: string; arguments: string[] };
 }
 
 const DEFAULT_PROCESS_LOG_BYTES = 5 * 1024 * 1024;
@@ -136,7 +143,14 @@ export function spawnRotatingProcess(options: RotatingProcessOptions): ChildProc
     command: options.command,
     arguments: options.arguments ?? [],
   });
-  return spawn("bun", [fileURLToPath(import.meta.url), "--run", specification], {
+  // Run the wrapper with the Bun that is running this code: a host may carry a
+  // managed Bun that is not on PATH.
+  const bun = typeof process.versions.bun === "string" ? process.execPath : "bun";
+  const launcher = options.worker ?? {
+    command: bun,
+    arguments: [fileURLToPath(import.meta.url), "--run"],
+  };
+  return spawn(launcher.command, [...launcher.arguments, specification], {
     detached: true,
     stdio: "ignore",
     env: { ...(options.env ?? process.env) } as NodeJS.ProcessEnv,
@@ -162,7 +176,8 @@ export function runRotatingProcessSync(options: RotatingProcessOptions): number
   return result.status;
 }
 
-async function runProcessLogWorker(raw: string | undefined): Promise<void> {
+/** The wrapper's body: run the specified command and rotate its output into the log. */
+export async function runProcessLogWorker(raw: string | undefined): Promise<void> {
   const parsed = JSON.parse(raw ?? "null") as RotatingProcessOptions | null;
   if (!parsed || typeof parsed.command !== "string" || !Array.isArray(parsed.arguments)) {
     throw new Error("invalid process log worker specification");

package/src/lib/tunnel/allowlist.ts

@@ -0,0 +1,208 @@
+// Address allowlist for the tunnel gate: exact addresses and CIDR ranges, IPv4
+// and IPv6. Pure functions with no I/O, shared by the gate worker (matching)
+// and the `tunnel allow` commands (validation + canonical spelling).
+//
+// An IPv6 phone and laptop on one Wi-Fi network have different addresses but
+// share a /64 prefix, so a range entry such as `2601:db8:1:2::/64` admits both.
+// An entry without a prefix length is a single address (/32 or /128).
+//
+// IPv4-mapped IPv6 addresses (`::ffff:203.0.113.8`) are IPv4 addresses reached
+// through a dual-stack socket, so they parse and match as IPv4.
+
+import { isIPv4, isIPv6 } from "node:net";
+
+export type IpFamily = 4 | 6;
+
+export interface ParsedIp {
+  family: IpFamily;
+  value: bigint;
+}
+
+export interface AllowEntry extends ParsedIp {
+  /** Prefix length in bits (32 or 128 for a single address). */
+  prefix: number;
+}
+
+const FULL_BITS: Record<IpFamily, number> = { 4: 32, 6: 128 };
+
+function parseIpv4(text: string): bigint | null {
+  if (!isIPv4(text)) return null;
+  let value = 0n;
+  for (const part of text.split(".")) value = (value << 8n) | BigInt(Number(part));
+  return value;
+}
+
+function parseIpv6(text: string): bigint | null {
+  if (!isIPv6(text)) return null;
+  let rest = text;
+  // A trailing dotted quad (`::ffff:1.2.3.4`, `64:ff9b::1.2.3.4`) is two groups.
+  const dotted = rest.match(/^(.*:)(\d+\.\d+\.\d+\.\d+)$/);
+  if (dotted) {
+    const v4 = parseIpv4(dotted[2] as string);
+    if (v4 === null) return null;
+    rest = `${dotted[1]}${(v4 >> 16n).toString(16)}:${(v4 & 0xffffn).toString(16)}`;
+  }
+  const halves = rest.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? (halves[0] as string).split(":") : [];
+  const tail = halves.length === 2 && halves[1] ? (halves[1] as string).split(":") : [];
+  const missing = 8 - head.length - tail.length;
+  if (halves.length === 1 ? missing !== 0 : missing < 1) return null;
+  const groups = [
+    ...head,
+    ...Array.from({ length: halves.length === 2 ? missing : 0 }, () => "0"),
+    ...tail,
+  ];
+  if (groups.length !== 8) return null;
+  let value = 0n;
+  for (const group of groups) {
+    if (!/^[0-9a-f]{1,4}$/i.test(group)) return null;
+    value = (value << 16n) | BigInt(Number.parseInt(group, 16));
+  }
+  return value;
+}
+
+/**
+ * Parse one address. Returns null for anything that is not an IP literal. A
+ * zone id (`fe80::1%en0`) is dropped, and an IPv4-mapped IPv6 address is
+ * reported as the IPv4 address it carries.
+ */
+export function parseIp(raw: string): ParsedIp | null {
+  let text = raw.trim();
+  if (text.startsWith("[") && text.endsWith("]")) text = text.slice(1, -1);
+  const zone = text.indexOf("%");
+  if (zone !== -1) text = text.slice(0, zone);
+  if (!text) return null;
+  const v4 = parseIpv4(text);
+  if (v4 !== null) return { family: 4, value: v4 };
+  const v6 = parseIpv6(text);
+  if (v6 === null) return null;
+  if (v6 >> 32n === 0xffffn) return { family: 4, value: v6 & 0xffffffffn };
+  return { family: 6, value: v6 };
+}
+
+function maskFor(family: IpFamily, prefix: number): bigint {
+  const bits = BigInt(FULL_BITS[family]);
+  const host = bits - BigInt(prefix);
+  return ((1n << bits) - 1n) ^ ((1n << host) - 1n);
+}
+
+/**
+ * Parse an allowlist entry: `203.0.113.8`, `203.0.113.0/24`, `2601:db8::1`, or
+ * `2601:db8:1:2::/64`. Host bits below the prefix are cleared, so
+ * `203.0.113.77/24` means the network `203.0.113.0/24`. Returns null when the
+ * entry is not a valid address or its prefix length is out of range.
+ */
+export function parseAllowEntry(raw: string): AllowEntry | null {
+  const text = raw.trim();
+  const slash = text.indexOf("/");
+  const address = parseIp(slash === -1 ? text : text.slice(0, slash));
+  if (!address) return null;
+  let prefix = FULL_BITS[address.family];
+  if (slash !== -1) {
+    const lengthText = text.slice(slash + 1);
+    if (!/^\d{1,3}$/.test(lengthText)) return null;
+    prefix = Number(lengthText);
+    // A prefix on an IPv4-mapped IPv6 entry counts from the IPv6 start, so
+    // `::ffff:1.2.3.0/120` is the IPv4 /24. Anything shorter is not an IPv4 range.
+    if (address.family === 4 && /:/.test(text.slice(0, slash))) {
+      if (prefix < 96 || prefix > 128) return null;
+      prefix -= 96;
+    }
+    if (prefix > FULL_BITS[address.family]) return null;
+  }
+  return { ...address, prefix, value: address.value & maskFor(address.family, prefix) };
+}
+
+function compress(groups: number[]): string {
+  // RFC 5952: collapse the longest run of two or more zero groups (first wins).
+  let bestStart = -1;
+  let bestLen = 0;
+  for (let i = 0; i < 8; ) {
+    if (groups[i] !== 0) {
+      i++;
+      continue;
+    }
+    let j = i;
+    while (j < 8 && groups[j] === 0) j++;
+    if (j - i > bestLen) {
+      bestStart = i;
+      bestLen = j - i;
+    }
+    i = j;
+  }
+  if (bestLen < 2) return groups.map((g) => g.toString(16)).join(":");
+  const left = groups.slice(0, bestStart).map((g) => g.toString(16));
+  const right = groups.slice(bestStart + bestLen).map((g) => g.toString(16));
+  return `${left.join(":")}::${right.join(":")}`;
+}
+
+/** Canonical text of an address (dotted quad, or compressed lowercase IPv6). */
+export function formatIp(ip: ParsedIp): string {
+  if (ip.family === 4) {
+    return [24n, 16n, 8n, 0n].map((shift) => Number((ip.value >> shift) & 0xffn)).join(".");
+  }
+  const groups: number[] = [];
+  for (let i = 7; i >= 0; i--) groups.push(Number((ip.value >> BigInt(i * 16)) & 0xffffn));
+  return compress(groups);
+}
+
+/** Canonical text of an entry; a single address carries no `/len` suffix. */
+export function formatAllowEntry(entry: AllowEntry): string {
+  const address = formatIp(entry);
+  return entry.prefix === FULL_BITS[entry.family] ? address : `${address}/${entry.prefix}`;
+}
+
+/**
+ * Canonical spelling of an allowlist entry, or null when invalid. Two spellings
+ * of one address or range (`2601:DB8:0:0::1`, `2601:db8::1`) normalize equal.
+ */
+export function normalizeAllowEntry(raw: string): string | null {
+  const entry = parseAllowEntry(raw);
+  return entry ? formatAllowEntry(entry) : null;
+}
+
+export interface Allowlist {
+  entries: AllowEntry[];
+  /** Entries that could not be parsed; they never match anything. */
+  invalid: string[];
+}
+
+export function compileAllowlist(rawEntries: readonly string[]): Allowlist {
+  const entries: AllowEntry[] = [];
+  const invalid: string[] = [];
+  for (const raw of rawEntries) {
+    const text = raw.trim();
+    if (!text) continue;
+    const entry = parseAllowEntry(text);
+    if (entry) entries.push(entry);
+    else invalid.push(text);
+  }
+  return { entries, invalid };
+}
+
+/** True when `ip` lies inside any entry. A missing or malformed address never matches. */
+export function allowlistMatches(list: Allowlist, ip: string): boolean {
+  const address = parseIp(ip);
+  if (!address) return false;
+  for (const entry of list.entries) {
+    if (entry.family !== address.family) continue;
+    const mask = maskFor(entry.family, entry.prefix);
+    if ((address.value & mask) === entry.value) return true;
+  }
+  return false;
+}
+
+/** The IPv6 /64 network prefix of an address, as a canonical `…/64` entry. */
+export function ipv6Slash64(address: string): string | null {
+  const ip = parseIp(address);
+  if (!ip || ip.family !== 6) return null;
+  return formatAllowEntry({ ...ip, prefix: 64, value: ip.value & maskFor(6, 64) });
+}
+
+/** A single IPv4 address as a `/32` entry. */
+export function ipv4Slash32(address: string): string | null {
+  const ip = parseIp(address);
+  if (!ip || ip.family !== 4) return null;
+  return `${formatIp(ip)}/32`;
+}

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/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(", ")}`);
+}