harnery 0.40.0 → 0.42.0

package/dist/lib/pace/pace.js

@@ -0,0 +1,313 @@
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+/**
+ * Human-pace gate for page loads.
+ *
+ * Every Harnery surface that loads a web page (`browse`, `browse-ai`, `fetch`,
+ * and the headed browse-session verbs) reserves a slot here before the request
+ * goes out. Consecutive loads against the same registrable site are spaced by
+ * a random gap inside `[minMs, maxMs]`, the way a person reads one page before
+ * opening the next. Loads against different sites do not wait on each other.
+ * Loopback, private-network, single-label, and reserved-suffix hosts are exempt
+ * so local development and page QA keep running at machine speed.
+ *
+ * The ledger is a small machine-local JSON file (`~/.cache/harnery/pace.json`)
+ * shared by every process, so separate `harn fetch` calls in a shell loop are
+ * paced the same as one long `harn browse` session. A caller reserves the next
+ * slot before it sleeps, so concurrent processes queue behind each other
+ * instead of all firing at once.
+ *
+ * The gate is on by default. `HARNERY_PACE=off` disables it machine-wide and
+ * each command carries `--no-pace` for a single run.
+ */
+export const DEFAULT_PACE_MIN_MS = 3_000;
+export const DEFAULT_PACE_MAX_MS = 9_000;
+export const DEFAULT_PACE_LEDGER = resolve(homedir(), ".cache", "harnery", "pace.json");
+/** Entries idle this long drop out of the ledger on the next write. */
+const LEDGER_RETENTION_MS = 60 * 60 * 1_000;
+/** A lock older than this belongs to a dead process and is reclaimed. */
+const LOCK_STALE_MS = 5_000;
+/** Total time a reservation waits for the ledger lock before proceeding anyway. */
+const LOCK_WAIT_MS = 500;
+const LOCK_POLL_MS = 5;
+const OFF_VALUES = new Set(["off", "0", "false", "no", "none"]);
+/**
+ * Resolve the pace policy from the environment.
+ *
+ * - `HARNERY_PACE`: `off` (or `0`, `false`, `no`) disables the gate. Unset or
+ *   `human` keeps the default.
+ * - `HARNERY_PACE_MIN_MS` / `HARNERY_PACE_MAX_MS`: gap bounds in ms. Both must
+ *   be non-negative integers with min <= max.
+ * - `HARNERY_PACE_EXEMPT`: comma-separated host suffixes that never wait.
+ * - `HARNERY_PACE_LEDGER`: ledger path override.
+ */
+export function pacePolicyFromEnv(env = process.env) {
+    const mode = env.HARNERY_PACE?.trim().toLowerCase();
+    if (mode && mode !== "human" && !OFF_VALUES.has(mode)) {
+        throw new Error(`HARNERY_PACE must be "human" or "off" (got "${env.HARNERY_PACE}").`);
+    }
+    const minMs = readMs(env, "HARNERY_PACE_MIN_MS", DEFAULT_PACE_MIN_MS);
+    const maxMs = readMs(env, "HARNERY_PACE_MAX_MS", DEFAULT_PACE_MAX_MS);
+    if (minMs > maxMs) {
+        throw new Error(`HARNERY_PACE_MIN_MS (${minMs}) must not exceed HARNERY_PACE_MAX_MS (${maxMs}).`);
+    }
+    const exemptSuffixes = (env.HARNERY_PACE_EXEMPT ?? "")
+        .split(",")
+        .map((s) => normalizeHost(s))
+        .filter((s) => s !== null);
+    return {
+        enabled: !(mode && OFF_VALUES.has(mode)),
+        minMs,
+        maxMs,
+        exemptSuffixes,
+        ledgerPath: env.HARNERY_PACE_LEDGER?.trim() || DEFAULT_PACE_LEDGER,
+    };
+}
+function readMs(env, name, fallback) {
+    const raw = env[name]?.trim();
+    if (!raw)
+        return fallback;
+    if (!/^\d+$/.test(raw)) {
+        throw new Error(`${name} must be a non-negative integer number of milliseconds (got "${raw}").`);
+    }
+    return Number.parseInt(raw, 10);
+}
+/**
+ * Public suffixes that take two labels, so the registrable site is three
+ * labels deep (`news.bbc.co.uk` -> `bbc.co.uk`). A short curated list is
+ * enough here: the gate only needs sibling hosts of one site to share a key,
+ * and a miss degrades to per-hostname pacing, never to no pacing.
+ */
+const TWO_LABEL_SUFFIXES = new Set([
+    "co.uk",
+    "org.uk",
+    "ac.uk",
+    "gov.uk",
+    "com.au",
+    "net.au",
+    "org.au",
+    "co.nz",
+    "co.jp",
+    "co.kr",
+    "co.in",
+    "co.za",
+    "com.br",
+    "com.mx",
+    "com.ar",
+    "com.cn",
+    "com.tw",
+    "com.sg",
+    "com.tr",
+]);
+/** Reserved or local-only suffixes that are never paced. */
+const EXEMPT_SUFFIXES = ["localhost", "local", "test", "internal", "example", "invalid"];
+function normalizeHost(raw) {
+    const host = raw.trim().toLowerCase().replace(/\.+$/, "");
+    return host ? host : null;
+}
+function hasSuffix(host, suffix) {
+    return host === suffix || host.endsWith(`.${suffix}`);
+}
+function isExemptIpv4(host) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (!m)
+        return false;
+    const [a, b] = [Number(m[1]), Number(m[2])];
+    return (a === 127 ||
+        a === 10 ||
+        a === 0 ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 169 && b === 254));
+}
+function isExemptIpv6(host) {
+    const h = host.replace(/^\[|\]$/g, "");
+    return h === "::1" || h === "::" || /^f[cd]/.test(h) || /^fe[89ab]/.test(h);
+}
+/**
+ * Registrable site a URL belongs to for pacing purposes, or `null` when the
+ * URL is exempt: a non-HTTP scheme, a loopback or private address, a
+ * single-label or reserved-suffix host, or a configured exemption.
+ */
+export function paceSiteKey(url, exemptSuffixes = []) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return null;
+    const host = normalizeHost(parsed.hostname);
+    if (!host)
+        return null;
+    if (host.startsWith("[") || host.includes(":"))
+        return isExemptIpv6(host) ? null : host;
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host))
+        return isExemptIpv4(host) ? null : host;
+    for (const suffix of EXEMPT_SUFFIXES)
+        if (hasSuffix(host, suffix))
+            return null;
+    for (const suffix of exemptSuffixes)
+        if (hasSuffix(host, suffix))
+            return null;
+    const labels = host.split(".");
+    if (labels.length < 2)
+        return null;
+    const lastTwo = labels.slice(-2).join(".");
+    if (labels.length >= 3 && TWO_LABEL_SUFFIXES.has(lastTwo))
+        return labels.slice(-3).join(".");
+    return lastTwo;
+}
+/** Block the current thread for `ms`. Used by clients that drive a child process synchronously. */
+export function sleepSync(ms) {
+    if (ms <= 0)
+        return;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+export class PaceGate {
+    policy;
+    now;
+    random;
+    onWait;
+    constructor(policy, deps = {}) {
+        this.policy = policy;
+        this.now = deps.now ?? Date.now;
+        this.random = deps.random ?? Math.random;
+        this.onWait = deps.onWait;
+    }
+    /** A gate that never waits, for callers that opted out. */
+    static disabled() {
+        return new PaceGate({ ...pacePolicyFromEnv({}), enabled: false });
+    }
+    /**
+     * Reserve the next slot for `url` without sleeping. Returns how long the
+     * caller should wait before loading, or `null` when the URL is exempt or the
+     * gate is disabled. The reservation is recorded even when the wait is zero,
+     * so the next load of the same site owes a gap.
+     */
+    reserve(url) {
+        if (!this.policy.enabled)
+            return null;
+        const site = paceSiteKey(url, this.policy.exemptSuffixes);
+        if (!site)
+            return null;
+        const now = this.now();
+        const gap = this.policy.minMs + this.random() * (this.policy.maxMs - this.policy.minMs);
+        let readyAt = now;
+        withLedgerLock(this.policy.ledgerPath, this.now, () => {
+            const ledger = readLedger(this.policy.ledgerPath);
+            readyAt = Math.max(now, ledger.sites[site]?.nextAllowedAt ?? 0);
+            for (const [key, entry] of Object.entries(ledger.sites)) {
+                if (entry.nextAllowedAt < now - LEDGER_RETENTION_MS)
+                    delete ledger.sites[key];
+            }
+            ledger.sites[site] = { nextAllowedAt: Math.round(readyAt + gap), lastAt: readyAt };
+            writeLedger(this.policy.ledgerPath, ledger);
+        });
+        const wait = { site, waitMs: Math.max(0, Math.round(readyAt - now)) };
+        this.onWait?.(wait);
+        return wait;
+    }
+    /** Reserve a slot and wait it out asynchronously. */
+    async before(url) {
+        const wait = this.reserve(url);
+        if (wait && wait.waitMs > 0) {
+            await new Promise((done) => setTimeout(done, wait.waitMs));
+        }
+        return wait;
+    }
+    /** Reserve a slot and block the thread for it. For `spawnSync`-driven clients. */
+    beforeSync(url) {
+        const wait = this.reserve(url);
+        if (wait && wait.waitMs > 0)
+            sleepSync(wait.waitMs);
+        return wait;
+    }
+}
+/**
+ * Gate for a CLI command run. `null` when the run passed `--no-pace`;
+ * otherwise the environment policy, with every non-zero wait reported through
+ * `log` so the operator can see why a load took longer.
+ */
+export function commandPaceGate(optedIn, log) {
+    if (!optedIn)
+        return null;
+    return new PaceGate(pacePolicyFromEnv(), {
+        onWait: (wait) => {
+            if (wait.waitMs > 0)
+                log(describePaceWait(wait));
+        },
+    });
+}
+/** Describe a wait for a human-facing log line. */
+export function describePaceWait(wait) {
+    const seconds = (wait.waitMs / 1_000).toFixed(1);
+    return `paced ${seconds}s before ${wait.site} (human pace; --no-pace or HARNERY_PACE=off skips)`;
+}
+function readLedger(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed && parsed.version === 1 && parsed.sites && typeof parsed.sites === "object") {
+            const sites = {};
+            for (const [key, entry] of Object.entries(parsed.sites)) {
+                if (entry &&
+                    typeof entry.nextAllowedAt === "number" &&
+                    Number.isFinite(entry.nextAllowedAt) &&
+                    typeof entry.lastAt === "number" &&
+                    Number.isFinite(entry.lastAt)) {
+                    sites[key] = { nextAllowedAt: entry.nextAllowedAt, lastAt: entry.lastAt };
+                }
+            }
+            return { version: 1, sites };
+        }
+    }
+    catch {
+        // Missing or corrupt ledger: start fresh. A lost ledger costs one unpaced
+        // load per site, never a crash.
+    }
+    return { version: 1, sites: {} };
+}
+function writeLedger(path, ledger) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(ledger)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+}
+/**
+ * Serialize ledger read-modify-write across processes with an exclusive lock
+ * file. The lock is best-effort: a stale lock from a dead process is reclaimed,
+ * and a caller that cannot get the lock within `LOCK_WAIT_MS` proceeds without
+ * it rather than blocking a page load on a bookkeeping file.
+ */
+function withLedgerLock(path, now, fn) {
+    const lockPath = `${path}.lock`;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const start = now();
+    let held = false;
+    while (!held && now() - start < LOCK_WAIT_MS) {
+        try {
+            closeSync(openSync(lockPath, "wx", 0o600));
+            held = true;
+        }
+        catch {
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS)
+                    rmSync(lockPath, { force: true });
+            }
+            catch {
+                // Lock vanished between the failed open and the stat; retry.
+            }
+            sleepSync(LOCK_POLL_MS);
+        }
+    }
+    try {
+        fn();
+    }
+    finally {
+        if (held)
+            rmSync(lockPath, { force: true });
+    }
+}

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/forward-headers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Headers the tunnel gate sends to the upstream after the Host rewrite.
+ *
+ * The gate replaces Host so PHP (and other vhost-routed servers) see the
+ * configured review host. Callers that compare Origin to Host then fail,
+ * because the browser still sends the public tunnel hostname. Copy that
+ * original Host into X-Forwarded-Host, overwriting any client-supplied
+ * value, so the upstream can recover the hostname the browser used.
+ */
+export declare function applyUpstreamHeaders(headers: Headers, vhost: string): void;
+//# sourceMappingURL=forward-headers.d.ts.map

package/dist/lib/tunnel/forward-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forward-headers.d.ts","sourceRoot":"","sources":["../../../src/lib/tunnel/forward-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAM1E"}

package/dist/lib/tunnel/forward-headers.js

@@ -0,0 +1,17 @@
+/**
+ * Headers the tunnel gate sends to the upstream after the Host rewrite.
+ *
+ * The gate replaces Host so PHP (and other vhost-routed servers) see the
+ * configured review host. Callers that compare Origin to Host then fail,
+ * because the browser still sends the public tunnel hostname. Copy that
+ * original Host into X-Forwarded-Host, overwriting any client-supplied
+ * value, so the upstream can recover the hostname the browser used.
+ */
+export function applyUpstreamHeaders(headers, vhost) {
+    const originalHost = headers.get("host") ?? "";
+    headers.set("host", vhost);
+    if (originalHost)
+        headers.set("x-forwarded-host", originalHost);
+    headers.set("accept-encoding", "identity");
+    headers.delete("connection");
+}

package/dist/lib/tunnel/gate.js

@@ -1,14 +1,19 @@
 // Reverse-proxy worker spawned by `tunnel up`. Listens on 127.0.0.1:<port>
 // and forwards HTTP + WebSocket requests to an upstream with a Host header
-// rewrite and Content-Encoding 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.
+// rewrite, the original Host copied to X-Forwarded-Host, and Content-Encoding
+// 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. 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 { 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
@@ -27,6 +32,7 @@ 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}`;
@@ -77,16 +83,30 @@ 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 } })) {
+            if (server.upgrade(req, {
+                data: { path: url.pathname + url.search, originalHost: req.headers.get("host") ?? "" },
+            })) {
                 return undefined;
             }
             return new Response("WS upgrade failed\n", { status: 500 });
         }
         const headers = new Headers(req.headers);
-        headers.set("host", VHOST);
-        headers.set("accept-encoding", "identity");
-        headers.delete("connection");
+        applyUpstreamHeaders(headers, VHOST);
         const init = {
             method: req.method,
             headers,
@@ -135,11 +155,14 @@ const server = Bun.serve({
     },
     websocket: {
         open(ws) {
-            const { path } = ws.data;
+            const { path, originalHost } = ws.data;
             // Bun's WebSocket constructor accepts a `headers` option at runtime
             // even though the standard lib.dom.d.ts WebSocket type doesn't.
             const upstream = new WebSocket(UPSTREAM_WS + path, {
-                headers: { host: VHOST },
+                headers: {
+                    host: VHOST,
+                    ...(originalHost ? { "x-forwarded-host": originalHost } : {}),
+                },
             });
             upstream.binaryType = "arraybuffer";
             ws.upstream = upstream;
@@ -163,4 +186,5 @@ 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(`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

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/state.d.ts

@@ -21,6 +21,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 +41,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,6 +54,8 @@ 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.

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":"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"}

package/dist/lib/tunnel/state.js

@@ -3,6 +3,7 @@
 import { execSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
 import { 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()) {
@@ -46,9 +47,18 @@ function nameFromStateFile(file) {
 const DEFAULT_CONFIG = {
     allowed_ips: [],
 };
-/** Normalize a parsed state blob; supply `name` for pre-multi-instance files. */
+/**
+ * Normalize a parsed state blob; supply `name` for pre-multi-instance files.
+ * A state written before path scopes existed reads as an empty scope, which
+ * the gate treats as "refuse every path".
+ */
 function normalizeState(raw, fallbackName) {
-    return { ...raw, name: raw.name ?? fallbackName, provider: raw.provider ?? "cloudflare" };
+    return {
+        ...raw,
+        name: raw.name ?? fallbackName,
+        provider: raw.provider ?? "cloudflare",
+        allow_paths: Array.isArray(raw.allow_paths) ? raw.allow_paths : [],
+    };
 }
 export function readConfig() {
     const p = cachePath("tunnel", CONFIG_FILE);
@@ -122,7 +132,7 @@ export function isTunnelStateLive(state, processAlive = isProcessAlive) {
     const providerPid = state.cloudflared_pid ?? state.provider_pid;
     return typeof providerPid === "number" && processAlive(providerPid);
 }
-function tunnelTargetPort(state) {
+export function tunnelTargetPort(state) {
     const value = /^[a-z][a-z\d+.-]*:\/\//i.test(state.target)
         ? state.target
         : `http://${state.target}`;
@@ -152,6 +162,10 @@ export function findLiveTunnelForOrigin(port, vhost, root = process.cwd(), proce
         state.vhost === vhost &&
         isTunnelStateLive(state, processAlive)) ?? null);
 }
+/** True when the tunnel's path scope forwards every one of `paths`. */
+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.