workspace-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Uzay Altıner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# guard
+
+Decide whether a shell command or a file path would write outside a project
+root. It is the check you want in front of a coding agent you are not watching.
+
+`guard` answers one question and returns one bit. It does not run anything, it
+does not touch the filesystem beyond resolving symlinks, and it has no runtime
+dependencies — Node's standard library only.
+
+## Run it
+
+Requires Node 18 or newer. There is nothing to install and nothing to build.
+
+```
+node bin/guard.mjs check --root <dir> --command "<shell command>"
+node bin/guard.mjs check --root <dir> --path <file>
+node bin/guard.mjs --help
+```
+
+Once linked (`npm link`) the same commands are available as `guard`.
+
+Exit status is the verdict: `0` allowed, `1` denied, `2` the invocation itself
+was wrong. **`2` is never a verdict** — a caller that treats non-zero as "denied"
+will read its own typo as a threat, so branch on `0` and `1` explicitly.
+
+```
+$ node bin/guard.mjs check --root . --command "npm run build"
+allow: no write outside the root found
+
+$ node bin/guard.mjs check --root . --command "git push upstream main"
+deny: pushes to a remote other than origin: upstream
+
+$ node bin/guard.mjs check --root . --path ../../etc/hosts --json
+{"allowed":false,"reason":"escapes the root through \"..\": ../../etc/hosts -> /etc/hosts","root":".","subject":{"kind":"path","value":"../../etc/hosts"}}
+```
+
+`--json` prints one line: `allowed`, `reason`, the `root` as given, and the
+`subject` that was judged. `--cwd <dir>` sets where relative paths resolve from;
+it defaults to `--root`.
+
+It is also importable:
+
+```js
+import { checkCommand, checkPath } from "./src/guard.mjs";
+
+checkCommand("rm -rf build", { root: process.cwd() });
+// { allowed: false, reason: "deletes recursively and without prompting: rm -rf build" }
+```
+
+## Verify it works
+
+```
+npm test        # or: node --test test/
+```
+
+18 tests, no network, no fixtures to install. The suite is table-driven: every
+threat below has a case, and so does every ordinary command that must keep
+working. A guard that denies everything is not a guard, so the allow table is
+the half worth reading — an ordinary build, a write inside the root, a plain
+`git push origin <branch>`, a recursive delete of `build/`, and a copy that
+*reads* from outside the root while writing inside it are all allowed.
+
+To satisfy yourself by hand, without trusting the suite:
+
+```
+node bin/guard.mjs check --root . --path /etc/hosts     # prints deny, exits 1
+node bin/guard.mjs check --root . --path src/index.js   # prints allow, exits 0
+```
+
+## What it denies
+
+| Threat | Example |
+| --- | --- |
+| a path resolving outside the root | `/etc/hosts` |
+| escape through `..` | `../../etc/passwd` |
+| escape through a symlink leaving the root | `vendor/out.txt` where `vendor` → `/tmp` |
+| a link planted inside the root pointing out of it | `ln -s /tmp vendor` |
+| recursive forced deletion | `rm -rf build` |
+| running as another user | `sudo …`, `doas …` |
+| a download piped into a shell | `curl … \| sh` |
+| a force push | `git push --force`, `git push -uf origin main` |
+| a push to a remote that is not origin | `git push upstream main` |
+| a redirect whose target leaves the root | `npm test > /tmp/out.log` |
+| a write into the agent's own configuration | `cp hook.mjs ~/.claude/hooks/` |
+| git driven at a repository outside the root | `git -C /elsewhere push` |
+
+Destination-aware commands (`cp`, `mv`, `rsync`, `install`, `tee`, `touch`,
+`mkdir`, `dd`, `sed -i`, …) are judged on where they *write*, not on every path
+they mention, so reading a file from outside the root into the project is fine.
+
+## What it is not
+
+Not a sandbox. `guard` is a judgement, not an enforcement mechanism: it returns
+a verdict and something else has to act on it. Nothing stops a command it
+approved from doing something it did not model.
+
+Not a shell parser. Commands are split on `;`, `|`, `&&` and `||` and one layer
+of quotes is stripped — enough to judge the patterns above without choking on
+ordinary quoting, and not enough to survive an adversary who is actively
+obfuscating. It is built for a capable agent that may be careless, not for one
+that is hostile.
+
+Deliberately not covered: process substitution, `eval` of a constructed string,
+`$(…)` whose expansion is a path, and environment-variable indirection other
+than `$HOME`. These are all real, and each would need the verdict to depend on
+runtime state the tool does not have.
+
+## License
+
+MIT — the manifest declares it and [`LICENSE`](LICENSE) is the text.

package/bin/guard.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { run } from "../src/cli.mjs";
+
+const { version } = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
+const { code, out, err } = run(process.argv.slice(2), { version });
+if (out) process.stdout.write(out);
+if (err) process.stderr.write(err);
+process.exit(code);

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "workspace-guard",
+  "version": "0.1.0",
+  "description": "Guardrail for running a coding agent unattended: decides whether a shell command or file path would write outside a project root, before you let it run.",
+  "keywords": [
+    "agent",
+    "coding-agent",
+    "claude",
+    "sandbox",
+    "confinement",
+    "guardrails",
+    "unattended"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "guard": "bin/guard.mjs"
+  },
+  "exports": {
+    ".": "./src/guard.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,86 @@
+import { checkCommand, checkPath, GuardUsageError } from "./guard.mjs";
+
+export const USAGE = `guard — decide whether a shell command or a file path would write outside a project root.
+
+Usage:
+  guard check --root <dir> --command "<shell command>"
+  guard check --root <dir> --path <file>
+
+Options:
+  --root <dir>       the project directory the work is confined to (required)
+  --command "<cmd>"  a shell command to judge
+  --path <file>      a file path to judge
+  --cwd <dir>        directory relative paths are resolved from (default: --root)
+  --json             print the decision as JSON on one line
+  -h, --help         print this message
+  -v, --version      print the version
+
+Exit status:
+  0  allowed
+  1  denied
+  2  the invocation itself was wrong (exit code 2 is never a verdict)
+
+Examples:
+  guard check --root . --command "npm test"
+  guard check --root . --command "rm -rf /" ; echo $?
+  guard check --root . --path ../../etc/hosts --json
+`;
+
+const TAKES_VALUE = new Set(["--root", "--command", "--path", "--cwd"]);
+
+export function parseArgs(argv) {
+  const opts = { json: false };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") return { help: true };
+    if (arg === "-v" || arg === "--version") return { version: true };
+    if (arg === "--json") opts.json = true;
+    else if (TAKES_VALUE.has(arg)) {
+      if (i + 1 >= argv.length) throw new GuardUsageError(`${arg} needs a value`);
+      opts[arg.slice(2)] = argv[++i];
+    } else if (arg.startsWith("--") && arg.includes("=")) {
+      const [name, ...value] = arg.split("=");
+      if (!TAKES_VALUE.has(name)) throw new GuardUsageError(`unknown option: ${name}`);
+      opts[name.slice(2)] = value.join("=");
+    } else if (arg.startsWith("-")) throw new GuardUsageError(`unknown option: ${arg}`);
+    else positional.push(arg);
+  }
+  return { ...opts, positional };
+}
+
+export function run(argv, { version = "0.0.0" } = {}) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    if (err instanceof GuardUsageError) return { code: 2, err: `guard: ${err.message}\n\n${USAGE}` };
+    throw err;
+  }
+  if (args.help) return { code: 0, out: USAGE };
+  if (args.version) return { code: 0, out: `${version}\n` };
+  if (argv.length === 0) return { code: 2, err: USAGE };
+
+  const [command] = args.positional;
+  if (command !== "check") return { code: 2, err: `guard: unknown command: ${command ?? "(none)"}\n\n${USAGE}` };
+
+  try {
+    if ((args.command === undefined) === (args.path === undefined))
+      throw new GuardUsageError("give exactly one of --command or --path");
+    const subject = args.command !== undefined
+      ? { kind: "command", value: args.command }
+      : { kind: "path", value: args.path };
+    const opts = { root: args.root, cwd: args.cwd };
+    const result = subject.kind === "command"
+      ? checkCommand(subject.value, opts)
+      : checkPath(subject.value, opts);
+
+    const out = args.json
+      ? JSON.stringify({ ...result, root: args.root, subject }) + "\n"
+      : `${result.allowed ? "allow" : "deny"}: ${result.reason}\n`;
+    return { code: result.allowed ? 0 : 1, out };
+  } catch (err) {
+    if (err instanceof GuardUsageError) return { code: 2, err: `guard: ${err.message}\n\n${USAGE}` };
+    return { code: 2, err: `guard: ${err.message}\n` };
+  }
+}

package/src/guard.mjs

@@ -0,0 +1,189 @@
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, resolve } from "node:path";
+
+export class GuardUsageError extends Error {}
+
+const allow = (reason) => ({ allowed: true, reason });
+const deny = (reason) => ({ allowed: false, reason });
+
+const SHELL_DENY = [
+  [/(^|[\s;&|(])sudo(\s|$)/, "runs as another user via sudo"],
+  [/(^|[\s;&|(])doas(\s|$)/, "runs as another user via doas"],
+  [/\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(ba|z|da|k)?sh(\s|$)/, "pipes a download into a shell"],
+];
+
+const DEST_LAST = new Set(["cp", "mv", "rsync", "install", "scp"]);
+const DEST_ALL = new Set(["tee", "touch", "mkdir", "rmdir", "truncate", "chmod", "chown"]);
+
+function longestExistingReal(p) {
+  let cur = p;
+  while (!existsSync(cur)) {
+    const up = dirname(cur);
+    if (up === cur) return cur;
+    cur = up;
+  }
+  try {
+    return realpathSync(cur) + p.slice(cur.length);
+  } catch {
+    return p;
+  }
+}
+
+const inside = (p, root) => p === root || p.startsWith(root + "/");
+
+function expandHome(raw, home) {
+  if (raw === "~" || raw.startsWith("~/")) return home + raw.slice(1);
+  const m = /^\$\{?HOME\}?(?=\/|$)/.exec(raw);
+  return m ? home + raw.slice(m[0].length) : raw;
+}
+
+export function resolveRoots({ root, cwd, home } = {}) {
+  if (!root) throw new GuardUsageError("a root directory is required");
+  const home_ = home ?? homedir();
+  const lexicalRoot = resolve(root);
+  const realRoot = longestExistingReal(lexicalRoot);
+  const base = cwd ? resolve(cwd) : lexicalRoot;
+  return { lexicalRoot, realRoot, base, home: home_, claude: resolve(home_, ".claude") };
+}
+
+// Two resolutions of the same path: the lexical one collapses `..` without
+// touching the disk, the real one follows symlinks on the longest existing
+// prefix. A path that is lexically inside the root but really outside it
+// escaped through a link, and saying so is the difference between a reason a
+// person can act on and "denied".
+function locate(raw, roots) {
+  const expanded = expandHome(String(raw), roots.home);
+  const lexical = isAbsolute(expanded) ? resolve(expanded) : resolve(roots.base, expanded);
+  return { expanded, lexical, real: longestExistingReal(lexical) };
+}
+
+function verdict(raw, roots) {
+  const { expanded, lexical, real } = locate(raw, roots);
+
+  if (inside(lexical, roots.claude) || inside(real, roots.claude))
+    return `writes into the agent's own configuration: ${raw}`;
+
+  if (!inside(lexical, roots.lexicalRoot)) {
+    if (expanded.split("/").includes("..")) return `escapes the root through "..": ${raw} -> ${lexical}`;
+    return `resolves outside the root: ${raw} -> ${lexical}`;
+  }
+  if (!inside(real, roots.realRoot)) return `escapes the root through a symlink: ${raw} -> ${real}`;
+  return null;
+}
+
+// Not a shell parser. It splits on the separators that start a new command and
+// strips one layer of quotes, which is enough to judge the deny patterns
+// without choking on ordinary quoting.
+const splitSegments = (cmd) => cmd.split(/&&|\|\||[;|]/).map((s) => s.trim()).filter(Boolean);
+
+const tokenize = (segment) =>
+  (segment.match(/(?:"[^"]*"|'[^']*'|\S+)/g) ?? []).map((t) => t.replace(/^["']|["']$/g, ""));
+
+const isFlag = (t) => t.startsWith("-");
+const hasShortFlag = (tok, letter) => /^-[a-zA-Z]+$/.test(tok) && tok.slice(1).includes(letter);
+const isRecursive = (t) => t === "--recursive" || hasShortFlag(t, "r") || hasShortFlag(t, "R");
+const isForce = (t) => t.startsWith("--force") || hasShortFlag(t, "f");
+const looksLikePath = (t) => !isFlag(t) && (t.includes("/") || t.includes("~") || t.includes("."));
+
+function checkRm(tokens, roots) {
+  const flags = tokens.filter(isFlag);
+  const targets = tokens.filter((t) => !isFlag(t));
+  for (const t of targets) {
+    const bad = verdict(t, roots);
+    if (bad) return bad;
+  }
+  if (flags.some(isRecursive) && flags.some(isForce))
+    return `deletes recursively and without prompting: rm ${tokens.join(" ")}`;
+  return null;
+}
+
+// `ln -s <outside> <inside>` is judged on its source, not its destination: it
+// plants a link inside the root whose target is not, which is how the next
+// command walks out.
+function checkLn(tokens, roots) {
+  const positional = tokens.filter((t) => !isFlag(t));
+  for (const t of positional) {
+    const bad = verdict(t, roots);
+    if (bad) return bad;
+  }
+  return null;
+}
+
+function checkGit(tokens, roots) {
+  const cIdx = tokens.indexOf("-C");
+  if (cIdx !== -1 && tokens[cIdx + 1]) {
+    const { lexical } = locate(tokens[cIdx + 1], roots);
+    if (!inside(lexical, roots.lexicalRoot))
+      return `operates on a repository outside the root: ${tokens[cIdx + 1]}`;
+  }
+  const pushIdx = tokens.indexOf("push");
+  if (pushIdx === -1) return null;
+  const args = tokens.slice(pushIdx + 1);
+  if (args.some(isForce)) return `force-pushes, which discards commits on the remote: ${tokens.join(" ")}`;
+  const positional = args.filter((t) => !isFlag(t));
+  if (positional.length && positional[0] !== "origin")
+    return `pushes to a remote other than origin: ${positional[0]}`;
+  return null;
+}
+
+function checkDestinations(head, tokens, roots) {
+  const positional = tokens.filter((t) => !isFlag(t));
+  if (DEST_LAST.has(head)) {
+    const dest = positional.at(-1);
+    return dest && looksLikePath(dest) ? verdict(dest, roots) : null;
+  }
+  for (const t of positional) {
+    if (looksLikePath(t)) {
+      const bad = verdict(t, roots);
+      if (bad) return bad;
+    }
+  }
+  return null;
+}
+
+function checkRedirects(cmd, roots) {
+  for (const m of cmd.matchAll(/>{1,2}\s*("([^"]+)"|'([^']+)'|(\S+))/g)) {
+    const target = m[2] ?? m[3] ?? m[4];
+    if (target.startsWith("/dev/") || target.startsWith("&")) continue;
+    const bad = verdict(target, roots);
+    if (bad) return `redirect target ${bad}`;
+  }
+  return null;
+}
+
+export function checkCommand(command, options) {
+  const roots = resolveRoots(options);
+  const cmd = String(command ?? "");
+  if (!cmd.trim()) throw new GuardUsageError("a command is required");
+
+  for (const [re, why] of SHELL_DENY) if (re.test(cmd)) return deny(why);
+
+  for (const segment of splitSegments(cmd)) {
+    const tokens = tokenize(segment);
+    if (!tokens.length) continue;
+    const head = tokens.at(0);
+    const rest = tokens.slice(1);
+
+    let bad = null;
+    if (head === "git") bad = checkGit(rest, roots);
+    else if (head === "rm") bad = checkRm(rest, roots);
+    else if (head === "ln") bad = checkLn(rest, roots);
+    else if (head === "dd") bad = checkDestinations("dd", rest.filter((t) => t.startsWith("of=")).map((t) => t.slice(3)), roots);
+    else if (head === "sed" && rest.includes("-i")) bad = checkDestinations("sed", rest, roots);
+    else if (DEST_LAST.has(head) || DEST_ALL.has(head)) bad = checkDestinations(head, rest, roots);
+    if (bad) return deny(bad);
+  }
+
+  const redirect = checkRedirects(cmd, roots);
+  if (redirect) return deny(redirect);
+
+  return allow("no write outside the root found");
+}
+
+export function checkPath(path, options) {
+  const roots = resolveRoots(options);
+  if (path === undefined || path === null || String(path) === "") throw new GuardUsageError("a path is required");
+  const bad = verdict(path, roots);
+  return bad ? deny(bad) : allow(`stays inside the root: ${locate(path, roots).real}`);
+}