harnery 0.41.0 → 0.43.0

package/dist/lib/tunnel/current-address.js

@@ -0,0 +1,123 @@
+// 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.js";
+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";
+/** The `ip=` value of a Cloudflare trace body, or null. */
+export function parseTraceIp(body) {
+    const m = body.match(/^ip=(\S+)\s*$/m);
+    return m ? m[1] : null;
+}
+async function probe(url, family, opts) {
+    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 = {}) {
+    const opts = {
+        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 = { failures: [] };
+    if (v4.status === "fulfilled")
+        out.v4 = v4.value;
+    else
+        out.failures.push(`IPv4: ${v4.reason.message}`);
+    if (v6.status === "fulfilled")
+        out.v6 = v6.value;
+    else
+        out.failures.push(`IPv6: ${v6.reason.message}`);
+    return out;
+}
+const sameEntry = (a, b) => (normalizeAllowEntry(a) ?? a) === (normalizeAllowEntry(b) ?? b);
+const includesEntry = (list, entry) => 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, detected) {
+    const previousAuto = config.auto_allowed ?? [];
+    const wanted = [];
+    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 = [];
+    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/dist/lib/tunnel/error-page.d.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;

package/dist/lib/tunnel/error-page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-page.d.ts","sourceRoot":"","sources":["../../../src/lib/tunnel/error-page.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,eAAe,GAAG,sBAAsB,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA6BD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAwE7E"}
+{"version":3,"file":"error-page.d.ts","sourceRoot":"","sources":["../../../src/lib/tunnel/error-page.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,eAAe,GAAG,aAAa,GAAG,sBAAsB,CAAC;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA6BD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAwF7E"}

package/dist/lib/tunnel/error-page.js

@@ -25,14 +25,25 @@ function diagnosticText(options) {
     return lines.join("\n");
 }
 export function renderTunnelErrorPage(options) {
-    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");
     return `<!doctype html>

package/dist/lib/tunnel/gate.js

@@ -4,13 +4,17 @@
 // 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.js";
 import { renderTunnelErrorPage } from "./error-page";
 import { applyUpstreamHeaders } from "./forward-headers";
+import { ALLOW_PATHS_ENV, isPathAllowed, parseAllowPathsEnv } from "./path-scope.js";
 // `--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
 // `tunnel down` scope its stray-process sweep to a single instance via
@@ -21,14 +25,13 @@ 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");
 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}`;
 const UPSTREAM_WS = `ws://${TARGET}`;
@@ -62,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.
@@ -79,6 +82,20 @@ const server = Bun.serve({
                 });
             }
         }
+        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, {
                 data: { path: url.pathname + url.search, originalHost: req.headers.get("host") ?? "" },
@@ -168,4 +185,13 @@ const server = Bun.serve({
 // 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/dist/lib/tunnel/path-scope.d.ts

@@ -0,0 +1,22 @@
+/** Env var that carries the scope from `tunnel up` to the detached gate. */
+export declare 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 declare function normalizeAllowPath(raw: string): string;
+/** Normalize and de-duplicate a list of `--allow-path` values. */
+export declare function normalizeAllowPaths(raw: readonly string[]): string[];
+/** Parse the gate's env value (comma-separated, already normalized by `up`). */
+export declare function parseAllowPathsEnv(value: string | undefined): string[];
+/**
+ * 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 declare function isPathAllowed(pathname: string, allowPaths: readonly string[]): boolean;
+//# sourceMappingURL=path-scope.d.ts.map

package/dist/lib/tunnel/path-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-scope.d.ts","sourceRoot":"","sources":["../../../src/lib/tunnel/path-scope.ts"],"names":[],"mappings":"AAQA,4EAA4E;AAC5E,eAAO,MAAM,eAAe,+BAA+B,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAmBtD;AAED,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAEpE;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAOtE;AAQD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAMtF"}

package/dist/lib/tunnel/path-scope.js

@@ -0,0 +1,62 @@
+// 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) {
+    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) {
+    return [...new Set(raw.map(normalizeAllowPath))];
+}
+/** Parse the gate's env value (comma-separated, already normalized by `up`). */
+export function parseAllowPathsEnv(value) {
+    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, allowPaths) {
+    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/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";
@@ -21,6 +40,8 @@ export interface TunnelState {
     target: string;
     vhost: string;
     gate_port: number;
+    /** URL path prefixes the gate forwards; every other path is refused. */
+    allow_paths: string[];
     tailscale_mode?: TailscaleMode;
     tailscale_path?: string;
     tailscale_https_port?: number;
@@ -39,6 +60,7 @@ export declare function isProcessAlive(pid: number): boolean;
 export type ProcessAliveCheck = (pid: number) => boolean;
 /** True when both the local gate and its provider-side process are live. */
 export declare function isTunnelStateLive(state: TunnelState, processAlive?: ProcessAliveCheck): boolean;
+export declare function tunnelTargetPort(state: TunnelState): number | null;
 /**
  * Newest live tunnel that serves `vhost` on the requested local web port.
  *
@@ -51,9 +73,17 @@ export declare function isTunnelStateLive(state: TunnelState, processAlive?: Pro
  * actually serves the caller's origin.
  */
 export declare function findLiveTunnelForOrigin(port: number, vhost: string, root?: string, processAlive?: ProcessAliveCheck): TunnelState | null;
+/** 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":"AAwBA,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,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAOD,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;;;;;;;;;;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;;;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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"}