harnery 0.41.0 → 0.42.0

package/dist/lib/guarded-remove.js

@@ -0,0 +1,310 @@
+import { spawnSync } from "node:child_process";
+import { lstatSync, readdirSync, readlinkSync, realpathSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, parse, relative, resolve, sep } from "node:path";
+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, options, checkClaims = () => { }) {
+    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();
+    const removedProtected = new Set();
+    const links = [];
+    const gitDirs = new Set();
+    let bytes = 0;
+    const devices = new Set();
+    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) => 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 = {
+        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, state, orSelf = false) {
+    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) {
+    return `Protected state cannot be removed: ${path}. To remove it on purpose, name it with --allow-protected ${path}`;
+}
+function insideAllowed(path, allowed) {
+    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, root, liveRoots) {
+    const allowed = new Set();
+    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) {
+    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) {
+    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, child) {
+    const rel = relative(parent, child);
+    return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+function checkedPath(input, allowed = new Set(), isRoot = false) {
+    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) {
+    return [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
+}
+function assertUntracked(target) {
+    const git = (args) => 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/dist/lib/instructions/templates.js

@@ -67,8 +67,7 @@ export function renderInstructionsBlock(binName, skills = { decide: true, counci
     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}
 
@@ -81,8 +80,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}
 
@@ -107,8 +105,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.
@@ -132,6 +129,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
@@ -142,8 +143,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}`;
 }
 function decideBody(b) {
     return `The decision docket is a persistent queue for decisions you would otherwise

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,16 @@
 // 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 { 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
@@ -29,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}`;
@@ -79,6 +83,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 +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.