harnery 0.41.0 → 0.42.0

package/src/lib/guarded-remove.ts

@@ -0,0 +1,376 @@
+import { spawnSync } from "node:child_process";
+import { lstatSync, readdirSync, readlinkSync, realpathSync, rmSync, type Stats } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, parse, relative, resolve, sep } from "node:path";
+
+export interface RemoveOptions {
+  root: string;
+  recursive?: boolean;
+  yes?: boolean;
+  dryRun?: boolean;
+  /**
+   * Protected paths (Git metadata, credentials, Harnery state, SSH or GnuPG
+   * keys, a bare repository) the caller names for removal, one exact path
+   * each. A protected path that is not named is still refused.
+   */
+  allowProtected?: string[];
+  /** Directories whose own Git metadata and Harnery state may never be allowed (the live workspace). */
+  liveRoots?: string[];
+}
+
+export interface RemovalLink {
+  path: string;
+  /** What the link points to. It is removed as a link and never followed. */
+  target: string;
+}
+
+export interface RemovalReport {
+  schema: "harnery.removal/v1";
+  applied: boolean;
+  root: string;
+  targets: string[];
+  entries: number;
+  bytes: number;
+  /** Protected paths removed because the caller named them with allowProtected. */
+  protected: string[];
+  /** Symbolic links inside recursive targets, removed as links. */
+  links: RemovalLink[];
+}
+
+const protectedNames = new Set([".git", ".harnery", ".credentials", ".ssh", ".gnupg"]);
+const MAX_ENTRIES = 10_000;
+
+/** Permanent removal is deliberately limited to inspected, untracked local outputs. */
+export function guardedRemove(
+  paths: string[],
+  options: RemoveOptions,
+  checkClaims: (targets: string[]) => void = () => {},
+): RemovalReport {
+  const cwd = realpathSync(process.cwd());
+  const root = checkedPath(options.root, new Set(), true);
+  const allowed = allowedProtected(options.allowProtected ?? [], root, options.liveRoots ?? []);
+  const rootStat = lstatSync(root);
+  const rootFingerprint = fingerprint(rootStat);
+  if (!rootStat.isDirectory()) throw new Error("--root must be a directory");
+  if (root === parse(root).root || root === realpathSync(homedir()))
+    throw new Error("--root cannot be a filesystem root or home directory");
+  if (paths.length === 0 || paths.length > 100) throw new Error("Supply 1-100 explicit targets");
+  const targets = paths.map((path) => checkedPath(path, allowed));
+  const snapshots = new Map<string, string>();
+  const removedProtected = new Set<string>();
+  const links: RemovalLink[] = [];
+  const gitDirs = new Set<string>();
+  let bytes = 0;
+  const devices = new Set<number>();
+
+  for (const target of targets) {
+    const home = realpathSync(homedir());
+    if (target === home || strictlyInside(target, home))
+      throw new Error(`Cannot remove the home directory or its ancestor: ${target}`);
+    const systemRoots =
+      process.platform === "win32"
+        ? [
+            process.env.SystemRoot,
+            process.env.ProgramFiles,
+            process.env["ProgramFiles(x86)"],
+          ].filter((value): value is string => Boolean(value))
+        : [
+            "/etc",
+            "/usr",
+            "/boot",
+            "/dev",
+            "/proc",
+            "/sys",
+            "/bin",
+            "/sbin",
+            "/lib",
+            "/lib64",
+            "/run",
+          ];
+    if (
+      systemRoots.some(
+        (system) =>
+          target === resolve(system) ||
+          strictlyInside(resolve(system), target) ||
+          strictlyInside(target, resolve(system)),
+      )
+    )
+      throw new Error(`System files are protected: ${target}`);
+    if (!strictlyInside(root, target))
+      throw new Error(`Target must be strictly inside --root: ${target}`);
+    if (target === cwd || strictlyInside(target, cwd))
+      throw new Error(`Cannot remove the working directory or its ancestor: ${target}`);
+    if (
+      targets.some((other) => other !== target && strictlyInside(other, target)) ||
+      targets.filter((other) => other === target).length > 1
+    )
+      throw new Error("Targets must not duplicate or contain one another");
+    const stat = lstatSync(target);
+    if (stat.dev !== rootStat.dev) throw new Error(`Target crosses a mount boundary: ${target}`);
+    if (stat.isDirectory() && !options.recursive)
+      throw new Error(`Directory removal requires --recursive: ${target}`);
+    const device = stat.dev;
+    devices.add(device);
+    const pending = [target];
+    while (pending.length) {
+      const path = pending.pop()!;
+      const info = lstatSync(path);
+      if (basename(path) === ARTIFACT_RECORD && insideArtifactWorkspace(path, null))
+        throw new Error(`An artifact's record is managed by the artifact commands: ${path}`);
+      if (protectedNames.has(basename(path).toLowerCase())) {
+        if (!allowed.has(path)) throw new Error(protectedMessage(path));
+        removedProtected.add(path);
+      }
+      if (info.isSymbolicLink()) {
+        // A link inside the tree is removed as a link; its target is never
+        // read, followed, or counted. (The target itself and its ancestors
+        // were already refused if they were links, in checkedPath.)
+        if (path === target) throw new Error(`Path contains a symlink: ${path}`);
+        if (snapshots.size >= MAX_ENTRIES)
+          throw new Error(
+            `Removal exceeds the ${MAX_ENTRIES}-entry limit; use the owning cleanup command`,
+          );
+        snapshots.set(path, fingerprint(info));
+        links.push({ path, target: readlinkSync(path) });
+        continue;
+      }
+      if (info.dev !== device || (!info.isDirectory() && !info.isFile()))
+        throw new Error(`Mount boundary or special file cannot be removed: ${path}`);
+      if (snapshots.size >= MAX_ENTRIES)
+        throw new Error(
+          `Removal exceeds the ${MAX_ENTRIES}-entry limit; use the owning cleanup command`,
+        );
+      snapshots.set(path, fingerprint(info));
+      if (info.isFile()) bytes += info.size;
+      else {
+        const names = readdirSync(path);
+        if (
+          names.includes("HEAD") &&
+          names.includes("objects") &&
+          names.includes("config") &&
+          !insideAllowed(path, allowed)
+        )
+          throw new Error(
+            `Repository metadata cannot be removed: ${path}. To remove it on purpose, name it with --allow-protected ${path}`,
+          );
+        if (allowed.has(path)) removedProtected.add(path);
+        if (isRepositoryMetadata(path)) gitDirs.add(path);
+        for (const name of names) pending.push(resolve(path, name));
+      }
+    }
+    assertUntracked(target);
+  }
+  if (devices.size > 1) throw new Error("Targets must be on one filesystem");
+  for (const path of allowed)
+    if (!removedProtected.has(path))
+      throw new Error(`--allow-protected names a path no target removes: ${path}`);
+  for (const dir of gitDirs) assertNoUnpushedHistory(dir);
+  checkClaims(targets);
+  const report: RemovalReport = {
+    schema: "harnery.removal/v1",
+    applied: false,
+    root,
+    targets,
+    entries: snapshots.size,
+    bytes,
+    protected: [...removedProtected].sort(),
+    links,
+  };
+  if (!options.yes || options.dryRun) return report;
+
+  // Recheck the entire batch before its first mutation. Filesystem changes after
+  // these checks remain possible; this is a guard, not a transactional filesystem.
+  if (
+    checkedPath(options.root, new Set(), true) !== root ||
+    fingerprint(lstatSync(root)) !== rootFingerprint
+  )
+    throw new Error("Allowed root changed during inspection");
+  for (const target of targets) {
+    checkedPath(target, allowed);
+    assertUntracked(target);
+  }
+  for (const dir of gitDirs) assertNoUnpushedHistory(dir);
+  checkClaims(targets);
+  for (const [path, previous] of snapshots) {
+    if (fingerprint(lstatSync(path)) !== previous)
+      throw new Error(`Target changed during inspection: ${path}`);
+  }
+  for (const target of targets)
+    rmSync(target, { recursive: Boolean(options.recursive), force: false });
+  return { ...report, applied: true };
+}
+
+/** The metadata file the artifact commands keep in each artifact workspace. */
+const ARTIFACT_RECORD = ".harnery-artifact.json";
+
+/**
+ * True when `path` lies strictly inside one artifact workspace,
+ * <dir>/.harnery/artifacts/<id>/..., under the `.harnery` component `state`
+ * (any `.harnery` when null). Artifact workspaces hold local outputs, so their
+ * contents may be removed; the workspace itself, its record file, and the rest
+ * of Harnery state stay protected and follow the artifact commands. `orSelf`
+ * accepts the workspace directory itself (used for --root, which is never removed).
+ */
+function insideArtifactWorkspace(path: string, state: string | null, orSelf = false): boolean {
+  const parts = path.split(sep);
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i]!.toLowerCase() !== ".harnery") continue;
+    if (state !== null && parts.slice(0, i + 1).join(sep) !== state) continue;
+    // .harnery / artifacts / <id> / <something>
+    return (
+      parts[i + 1] === "artifacts" && Boolean(parts[i + 2]) && parts.length >= i + (orSelf ? 3 : 4)
+    );
+  }
+  return false;
+}
+
+function protectedMessage(path: string): string {
+  return `Protected state cannot be removed: ${path}. To remove it on purpose, name it with --allow-protected ${path}`;
+}
+
+function insideAllowed(path: string, allowed: ReadonlySet<string>): boolean {
+  for (const entry of allowed) if (path === entry || strictlyInside(entry, path)) return true;
+  return false;
+}
+
+/**
+ * Resolves the caller's --allow-protected paths. Each must be one exact
+ * protected path strictly inside the root, reached without symlinks, and
+ * never the Git metadata or Harnery state of a live workspace root.
+ */
+function allowedProtected(paths: string[], root: string, liveRoots: string[]): Set<string> {
+  const allowed = new Set<string>();
+  const live = liveRoots.map((dir) => resolve(dir));
+  for (const input of paths) {
+    if (!input?.trim() || /[\0\r\n*?[\]$]/.test(input))
+      throw new Error("Use a nonempty explicit --allow-protected path without wildcards");
+    const path = resolve(input);
+    let cursor = dirname(path);
+    while (true) {
+      if (lstatSync(cursor).isSymbolicLink())
+        throw new Error(`--allow-protected path contains a symlink: ${cursor}`);
+      const parent = dirname(cursor);
+      if (parent === cursor) break;
+      cursor = parent;
+    }
+    const info = lstatSync(path);
+    if (info.isSymbolicLink()) throw new Error(`--allow-protected path is a symlink: ${path}`);
+    if (!strictlyInside(root, path))
+      throw new Error(`--allow-protected path must be strictly inside --root: ${path}`);
+    const named = protectedNames.has(basename(path).toLowerCase());
+    if (!named && !(info.isDirectory() && isRepositoryMetadata(path)))
+      throw new Error(`--allow-protected must name a protected path itself: ${path}`);
+    for (const dir of live) {
+      const own = [".git", ".harnery"].map((name) => resolve(dir, name));
+      if (
+        path === dir ||
+        strictlyInside(path, dir) ||
+        own.some((state) => path === state || strictlyInside(state, path))
+      )
+        throw new Error(`The live workspace's own state cannot be allowed: ${path}`);
+    }
+    allowed.add(realpathSync(path));
+  }
+  return allowed;
+}
+
+function isRepositoryMetadata(dir: string): boolean {
+  const names = readdirSync(dir);
+  return names.includes("HEAD") && names.includes("objects") && names.includes("config");
+}
+
+/**
+ * Removing a repository's metadata loses any commit that exists nowhere
+ * else. An allowed Git directory must have no branch or tag commit missing
+ * from its remotes; anything that cannot be checked is refused.
+ */
+function assertNoUnpushedHistory(gitDir: string): void {
+  const result = spawnSync(
+    "git",
+    [
+      "--git-dir",
+      gitDir,
+      "rev-list",
+      "--max-count=1",
+      "--branches",
+      "--tags",
+      "--not",
+      "--remotes",
+    ],
+    {
+      encoding: "utf8",
+      timeout: 10_000,
+      env: { ...process.env, LC_ALL: "C", GIT_DIR: undefined, GIT_WORK_TREE: undefined },
+    },
+  );
+  if (result.error || result.status !== 0)
+    throw new Error(`Cannot confirm ${gitDir} holds no unpushed history`);
+  if (result.stdout.trim()) throw new Error(`Repository has commits not on any remote: ${gitDir}`);
+}
+
+function strictlyInside(parent: string, child: string): boolean {
+  const rel = relative(parent, child);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+function checkedPath(
+  input: string,
+  allowed: ReadonlySet<string> = new Set(),
+  isRoot = false,
+): string {
+  if (!input?.trim() || /[\0\r\n*?[\]$]/.test(input))
+    throw new Error("Use a nonempty explicit path without wildcards or unresolved variables");
+  const path = resolve(input);
+  let cursor = path;
+  while (true) {
+    if (
+      protectedNames.has(basename(cursor).toLowerCase()) &&
+      !allowed.has(cursor) &&
+      !insideArtifactWorkspace(path, cursor, isRoot)
+    )
+      throw new Error(
+        cursor === path ? protectedMessage(path) : `Protected state contains this path: ${cursor}`,
+      );
+    const info = lstatSync(cursor);
+    if (info.isSymbolicLink()) throw new Error(`Path contains a symlink: ${cursor}`);
+    const parent = dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return realpathSync(path);
+}
+
+function fingerprint(stat: Stats): string {
+  return [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
+}
+
+function assertUntracked(target: string): void {
+  const git = (args: string[]) =>
+    spawnSync("git", ["-C", dirname(target), ...args], {
+      encoding: "utf8",
+      timeout: 10_000,
+      maxBuffer: 4 * 1024 * 1024,
+      env: {
+        ...process.env,
+        LC_ALL: "C",
+        GIT_LITERAL_PATHSPECS: "1",
+        GIT_DIR: undefined,
+        GIT_WORK_TREE: undefined,
+        GIT_INDEX_FILE: undefined,
+      },
+    });
+  const detected = git(["rev-parse", "--show-toplevel"]);
+  if (detected.error) throw new Error(`Cannot check Git ownership: ${detected.error.message}`);
+  if (detected.status !== 0) {
+    if (detected.status === 128 && detected.stderr.startsWith("fatal: not a git repository"))
+      return;
+    throw new Error(`Cannot check Git ownership: ${detected.stderr.trim()}`);
+  }
+  const repo = detected.stdout.trim();
+  const tracked = git(["ls-files", "--cached", "-z", "--full-name", "--", target]);
+  if (tracked.error || tracked.status !== 0) throw new Error(`Cannot inspect Git index in ${repo}`);
+  if (tracked.stdout.length)
+    throw new Error(
+      `Tracked files are protected; use git rm for intentional source removal: ${target}`,
+    );
+}

package/src/lib/instructions/templates.ts

@@ -89,8 +89,7 @@ export function renderInstructionsBlock(
   return `## harnery coordination
 
 This project runs [harnery](https://harnery.com) for multi-agent coordination.
-You share this checkout with other agents; the surfaces below keep you oriented
-and out of each other's way, and let you dispatch a team of your own when a job
+You share this checkout with other agents; the surfaces below keep you oriented and out of each other's way, and let you dispatch a team of your own when a job
 is bigger than one session. Run \`${b} <command> --help\` for any command's full
 surface. ${deeper}
 
@@ -103,8 +102,7 @@ widely-shared files.
 **Task lifecycle.** Beside the activity peers already see, declare whether your
 objective is still open: \`${b} agents lifecycle blocked --reason "<why>"\` when
 it cannot proceed, \`${b} agents lifecycle done\` when it is complete, and
-\`${b} agents lifecycle active\` to reopen. \`done\` requires a current task and
-a passing Git finalization check (dirty or unpushed work refuses, and nothing is
+\`${b} agents lifecycle active\` to reopen. \`done\` requires a current task and a passing Git finalization check (dirty or unpushed work refuses, and nothing is
 written). Ordinary \`set-task\` calls never change lifecycle, and a transition
 that re-mints the session title tells you the new name to copy. ${endPointer}
 
@@ -129,8 +127,7 @@ It reclaims an abandoned namesake (no live process) and refuses only when anothe
 live process still holds the name; never hand-edit Harnery's history, heartbeat,
 or derived identity cache.
 
-**Declare intent on shell commands.** Every command you run is captured to the
-coordination ledger (\`.harnery/ledgers/v3/\`). Lead a shell command with a
+**Declare intent on shell commands.** Every command you run is captured to the coordination ledger (\`.harnery/ledgers/v3/\`). Lead a shell command with a
 \`# intent: <why>\` comment (or set the tool's description) so the recorded event
 carries a reason instead of \`(no intent)\`; the [tool-intent
 guide](https://harnery.com/guides/tool-intent/) owns the details.
@@ -154,6 +151,10 @@ After review, use \`${b} artifacts discard <id> --reason "<why no longer needed>
 Do not create a repo-root temp directory; \`${b} artifacts clean\` previews
 expired cleanup and requires \`--yes\` to delete anything.
 
+**Removing local outputs.** Use \`${b} rm --root <directory> <paths...>\` instead of shell \`rm\`, which skips resolved-path, Git ownership, and peer-claim checks. Preview
+is the default; \`--yes\` deletes permanently and \`--recursive\` permits directories.
+Use \`git rm\` for tracked source and the artifact commands for managed evidence.
+
 **Local file links.** When the operator should open a local repo file, mint the
 URL with \`${b} files url <repo-relative-path>\` instead of guessing it. HTML opens
 as a real page with working scripts and relative assets; other files open in the
@@ -164,8 +165,7 @@ can't resolve from the repo, file it instead. \`${b} decision file "<question>"\
 records it and lets you proceed on a stated default; \`${b} decision search "<terms>"\`
 surfaces prior decisions, so check for precedent before re-deciding. ${decidePointer}
 
-**Councils.** For a hard or contested decision, convene a council of agents.
-\`${b} council create "<objective>"\` runs structured rounds toward a decision. ${councilPointer}`;
+**Councils.** For a hard or contested decision, convene a council of agents. \`${b} council create "<objective>"\` runs structured rounds toward a decision. ${councilPointer}`;
 }
 
 // ── Skills ──────────────────────────────────────────────────────────────────

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

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

package/src/lib/tunnel/gate.ts

@@ -4,7 +4,9 @@
 // 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
@@ -12,6 +14,7 @@
 
 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
@@ -34,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}`;
@@ -96,6 +100,22 @@ const server = Bun.serve<WsData, never>({
       }
     }
 
+    if (!isPathAllowed(url.pathname, ALLOW_PATHS)) {
+      const details = requestDetails(req, url);
+      console.log(
+        // lint-ok-emission: detached worker, see file note above
+        `path-deny: incident=${details.incidentId} ip=${details.clientIp || "(missing-cf-connecting-ip)"} ray=${details.cloudflareRay || "(missing)"} ${req.method} ${details.path}`,
+      );
+      return new Response(renderTunnelErrorPage({ ...details, kind: "path-denied" }), {
+        status: 403,
+        headers: {
+          "cache-control": "no-store",
+          "content-type": "text/html; charset=utf-8",
+          "x-harnery-tunnel-incident": details.incidentId,
+        },
+      });
+    }
+
     if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
       if (
         server.upgrade(req, {
@@ -192,4 +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.