harnery 0.40.0 → 0.42.0

package/src/lib/pace/pace.ts

@@ -0,0 +1,370 @@
+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;
+
+export interface PacePolicy {
+  /** False turns the gate into a no-op. Default true. */
+  enabled: boolean;
+  /** Shortest gap between two loads of the same site, in ms. */
+  minMs: number;
+  /** Longest gap between two loads of the same site, in ms. */
+  maxMs: number;
+  /** Extra exempt host suffixes (`example.test` matches itself and `*.example.test`). */
+  exemptSuffixes: string[];
+  /** Path of the shared reservation ledger. */
+  ledgerPath: string;
+}
+
+export interface PaceWait {
+  /** Registrable site the reservation was made against. */
+  site: string;
+  /** Milliseconds the caller waited (0 when the slot was free). */
+  waitMs: number;
+}
+
+export interface PaceGateDeps {
+  now?: () => number;
+  random?: () => number;
+  /** Called after a reservation, whether or not it waited. */
+  onWait?: (wait: PaceWait) => void;
+}
+
+interface LedgerEntry {
+  /** Epoch ms before which the next load of this site must not start. */
+  nextAllowedAt: number;
+  /** Epoch ms the most recent reservation was granted for. */
+  lastAt: number;
+}
+
+interface Ledger {
+  version: 1;
+  sites: Record<string, LedgerEntry>;
+}
+
+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: NodeJS.ProcessEnv = process.env): PacePolicy {
+  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 is string => s !== null);
+  return {
+    enabled: !(mode && OFF_VALUES.has(mode)),
+    minMs,
+    maxMs,
+    exemptSuffixes,
+    ledgerPath: env.HARNERY_PACE_LEDGER?.trim() || DEFAULT_PACE_LEDGER,
+  };
+}
+
+function readMs(env: NodeJS.ProcessEnv, name: string, fallback: number): number {
+  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: string): string | null {
+  const host = raw.trim().toLowerCase().replace(/\.+$/, "");
+  return host ? host : null;
+}
+
+function hasSuffix(host: string, suffix: string): boolean {
+  return host === suffix || host.endsWith(`.${suffix}`);
+}
+
+function isExemptIpv4(host: string): boolean {
+  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: string): boolean {
+  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: string, exemptSuffixes: readonly string[] = []): string | null {
+  let parsed: URL;
+  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: number): void {
+  if (ms <= 0) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+export class PaceGate {
+  private readonly now: () => number;
+  private readonly random: () => number;
+  private readonly onWait: ((wait: PaceWait) => void) | undefined;
+
+  constructor(
+    readonly policy: PacePolicy,
+    deps: PaceGateDeps = {},
+  ) {
+    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(): PaceGate {
+    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: string): PaceWait | null {
+    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: string): Promise<PaceWait | null> {
+    const wait = this.reserve(url);
+    if (wait && wait.waitMs > 0) {
+      await new Promise<void>((done) => setTimeout(done, wait.waitMs));
+    }
+    return wait;
+  }
+
+  /** Reserve a slot and block the thread for it. For `spawnSync`-driven clients. */
+  beforeSync(url: string): PaceWait | null {
+    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: boolean, log: (message: string) => void): PaceGate | null {
+  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: PaceWait): string {
+  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: string): Ledger {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<Ledger>;
+    if (parsed && parsed.version === 1 && parsed.sites && typeof parsed.sites === "object") {
+      const sites: Record<string, LedgerEntry> = {};
+      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: string, ledger: Ledger): void {
+  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: string, now: () => number, fn: () => void): void {
+  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/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/forward-headers.ts

@@ -0,0 +1,16 @@
+/**
+ * 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: Headers, vhost: string): void {
+  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/src/lib/tunnel/gate.ts

@@ -1,15 +1,20 @@
 // 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.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
@@ -32,6 +37,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}`;
@@ -39,6 +45,7 @@ const UPSTREAM_WS = `ws://${TARGET}`;
 
 interface WsData {
   path: string;
+  originalHost: string;
 }
 
 function requestDetails(req: Request, url: URL) {
@@ -93,17 +100,35 @@ 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, { 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: RequestInit = {
       method: req.method,
@@ -156,11 +181,14 @@ const server = Bun.serve<WsData, never>({
   },
   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 } : {}),
+        },
       } as unknown as undefined);
       upstream.binaryType = "arraybuffer";
       (ws as unknown as { upstream?: WebSocket }).upstream = upstream;
@@ -184,4 +212,5 @@ 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(`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/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/state.ts

@@ -11,6 +11,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { resolve } from "node:path";
+import { isPathAllowed } from "./path-scope.ts";
 
 // 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.
@@ -81,14 +82,25 @@ 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;
 }
 
-/** 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: TunnelState, fallbackName: string): TunnelState {
-  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(): TunnelConfig {
@@ -169,7 +181,7 @@ export function isTunnelStateLive(
   return typeof providerPid === "number" && processAlive(providerPid);
 }
 
-function tunnelTargetPort(state: TunnelState): number | null {
+export function tunnelTargetPort(state: TunnelState): number | null {
   const value = /^[a-z][a-z\d+.-]*:\/\//i.test(state.target)
     ? state.target
     : `http://${state.target}`;
@@ -209,6 +221,11 @@ export function findLiveTunnelForOrigin(
   );
 }
 
+/** True when the tunnel's path scope forwards every one of `paths`. */
+export function tunnelServesPaths(state: TunnelState, paths: readonly string[]): boolean {
+  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.

package/src/lib/webview/index.ts

@@ -0,0 +1,13 @@
+export {
+  type BunWebViewRuntime,
+  buildWebViewBackend,
+  parseWebViewTypeStep,
+  parseWebViewViewport,
+  type RunWebViewOptions,
+  runWebView,
+  type WebViewBackend,
+  type WebViewConsoleEvent,
+  type WebViewResult,
+  type WebViewTypeStep,
+  WebViewUnavailableError,
+} from "./webview.ts";