@melihmucuk/leash 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Melih Mucuk
+
+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,322 @@
+# Leash 🔒
+
+[![npm version](https://img.shields.io/npm/v/@melihmucuk/leash.svg)](https://www.npmjs.com/package/@melihmucuk/leash)
+
+**Security guardrails for AI coding agents.** Sandboxes file system access, blocks dangerous commands outside project directory, prevents destructive git operations, catches agent hallucinations before they cause damage.
+
+## Why Leash?
+
+AI agents can hallucinate dangerous commands. Leash sandboxes them:
+
+- Blocks `rm`, `mv`, `cp`, `chmod` outside working directory
+- Protects sensitive files (`.env`, `.git`) even inside project
+- Blocks `git reset --hard`, `push --force`, `clean -f`
+- Resolves symlinks to prevent directory escapes
+- Analyzes command chains (`&&`, `||`, `;`, `|`)
+
+![Claude Code](assets/claude-code.png)
+
+## Quick Start
+
+```bash
+npm install -g @melihmucuk/leash
+leash --setup <platform>
+```
+
+| Platform | Command |
+|----------|---------|
+| OpenCode | `leash --setup opencode` |
+| Pi Coding Agent | `leash --setup pi` |
+| Claude Code | `leash --setup claude-code` |
+| Factory Droid | `leash --setup factory` |
+
+Restart your agent. Done!
+
+```bash
+# Update anytime
+npm update -g @melihmucuk/leash
+
+# Remove from a platform
+leash --remove <platform>
+```
+
+<details>
+<summary><b>Manual Setup</b></summary>
+
+If you prefer manual configuration, use `leash --path <platform>` to get the path and add it to your config file.
+
+**Pi Coding Agent** - [docs](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/hooks.md)
+
+Add to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "hooks": ["<path from leash --path pi>"]
+}
+```
+
+**OpenCode** - [docs](https://opencode.ai/docs/plugins/)
+
+Add to `~/.config/opencode/config.json`:
+
+```json
+{
+  "plugins": ["<path from leash --path opencode>"]
+}
+```
+
+**Claude Code** - [docs](https://code.claude.com/docs/en/hooks-guide)
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node <path from leash --path claude-code>"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Factory Droid** - [docs](https://docs.factory.ai/cli/configuration/hooks-guide)
+
+Add to `~/.factory/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Execute|Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node <path from leash --path factory>"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+</details>
+
+## What Gets Blocked
+
+```bash
+# Dangerous commands outside working directory
+rm -rf ~/Documents                # ❌ Delete outside working dir
+mv ~/.bashrc /tmp/                # ❌ Move from outside
+echo "data" > ~/file.txt          # ❌ Redirect to home
+
+# Protected files (blocked even inside project)
+rm .env                           # ❌ Protected file
+echo "SECRET=x" > .env.local      # ❌ Protected file
+rm -rf .git                       # ❌ Protected directory
+
+# Dangerous git commands (blocked everywhere)
+git reset --hard                  # ❌ Destroys uncommitted changes
+git push --force                  # ❌ Destroys remote history
+git clean -fd                     # ❌ Removes untracked files
+
+# File operations via Write/Edit tools
+~/.bashrc                         # ❌ Home directory file
+../../../etc/hosts                # ❌ Path traversal
+.env                              # ❌ Protected file
+```
+
+## What's Allowed
+
+```bash
+rm -rf ./node_modules             # ✅ Working directory
+rm -rf /tmp/build-cache           # ✅ Temp directory
+rm .env.example                   # ✅ Example files allowed
+git commit -m "message"           # ✅ Safe git commands
+git push origin main              # ✅ Normal push (no --force)
+```
+
+<details>
+
+<summary><b>Detailed Examples</b></summary>
+
+### Dangerous Commands
+
+```bash
+rm -rf ~/Documents           # ❌ Delete outside working dir
+mv ~/.bashrc /tmp/           # ❌ Move from outside
+cp ./secrets ~/leaked        # ❌ Copy to outside
+chmod 777 /etc/hosts         # ❌ Permission change outside
+chown user ~/file            # ❌ Ownership change outside
+ln -s ./file ~/link          # ❌ Symlink to outside
+dd if=/dev/zero of=~/file    # ❌ Write outside
+truncate -s 0 ~/file         # ❌ Truncate outside
+```
+
+### Dangerous Git Commands
+
+```bash
+git checkout -- .            # ❌ Discards uncommitted changes
+git restore src/file.ts      # ❌ Discards uncommitted changes
+git reset --hard             # ❌ Destroys all uncommitted changes
+git reset --hard HEAD~1      # ❌ Destroys commits and changes
+git reset --merge            # ❌ Can lose uncommitted changes
+git clean -f                 # ❌ Removes untracked files permanently
+git clean -fd                # ❌ Removes untracked files and directories
+git push --force             # ❌ Destroys remote history
+git push -f origin main      # ❌ Destroys remote history
+git branch -D feature        # ❌ Force-deletes branch without merge check
+git stash drop               # ❌ Permanently deletes stashed changes
+git stash clear              # ❌ Deletes ALL stashed changes
+```
+
+### Redirects
+
+```bash
+echo "data" > ~/file.txt     # ❌ Redirect to home
+echo "log" >> ~/app.log      # ❌ Append to home
+cat secrets > "/tmp/../~/x"  # ❌ Path traversal in redirect
+```
+
+### Command Chains
+
+```bash
+echo ok && rm ~/file         # ❌ Dangerous command after &&
+false || rm -rf ~/           # ❌ Dangerous command after ||
+ls; rm ~/file                # ❌ Dangerous command after ;
+cat x | rm ~/file            # ❌ Dangerous command in pipe
+cd ~/Downloads && rm file    # ❌ cd outside + dangerous command
+cd .. && cd .. && rm target  # ❌ cd hops escaping working dir
+```
+
+### Wrapper Commands
+
+```bash
+sudo rm -rf ~/dir            # ❌ sudo + dangerous command
+env rm ~/file                # ❌ env + dangerous command
+command rm ~/file            # ❌ command + dangerous command
+```
+
+### Compound Patterns
+
+```bash
+find ~ -name "*.tmp" -delete          # ❌ find -delete outside
+find ~ -exec rm {} \;                 # ❌ find -exec rm outside
+find ~/logs | xargs rm                # ❌ xargs rm outside
+find ~ | xargs -I{} mv {} /tmp        # ❌ xargs mv outside
+rsync -av --delete ~/src/ ~/dst/      # ❌ rsync --delete outside
+```
+
+### Protected Files (blocked even inside project)
+
+```bash
+rm .env                      # ❌ Environment file
+rm .env.local                # ❌ Environment file
+rm .env.production           # ❌ Environment file
+echo "x" > .env              # ❌ Write to env file
+rm -rf .git                  # ❌ Git directory
+echo "x" > .git/config       # ❌ Write to git directory
+find . -name ".env" -delete  # ❌ Delete protected via find
+```
+
+Note: `.env.example` is allowed (template files are safe).
+
+### File Operations (Write/Edit tools)
+
+```bash
+/etc/passwd                  # ❌ System file
+~/.bashrc                    # ❌ Home directory file
+/home/user/.ssh/id_rsa       # ❌ Absolute path outside
+../../../etc/hosts           # ❌ Path traversal
+.env                         # ❌ Protected file
+.git/config                  # ❌ Protected directory
+```
+
+### What's Allowed (Full List)
+
+```bash
+# Working directory operations
+rm -rf ./node_modules
+mv ./old.ts ./new.ts
+cp ./src/config.json ./dist/
+find . -name "*.bak" -delete
+find ./logs | xargs rm
+
+# Temp directory operations
+rm -rf /tmp/build-cache
+echo "data" > /tmp/output.txt
+rsync -av --delete ./src/ /tmp/backup/
+
+# Device paths
+echo "x" > /dev/null
+truncate -s 0 /dev/null
+
+# Read from anywhere (safe)
+cp /etc/hosts ./local-hosts
+cat /etc/passwd
+
+# Safe git commands
+git status
+git add .
+git commit -m "message"
+git push origin main
+git checkout main
+git checkout -b feature/new
+git branch -d merged-branch      # lowercase -d is safe
+git reset --soft HEAD~1          # soft reset is safe
+git restore --staged .           # unstaging is safe
+git stash
+git stash pop
+```
+
+</details>
+
+## Performance
+
+Near-zero latency impact on your workflow:
+
+| Platform    | Latency per tool call | Notes                                    |
+| ----------- | --------------------- | ---------------------------------------- |
+| OpenCode    | **~20µs**             | In-process plugin, near-zero overhead    |
+| Pi          | **~20µs**             | In-process hook, near-zero overhead      |
+| Claude Code | **~31ms**             | External process (~30ms Node.js startup) |
+| Factory     | **~31ms**             | External process (~30ms Node.js startup) |
+
+For context: LLM API calls typically take 2-10+ seconds. Even the slower external process hook adds less than 0.3% to total response time.
+
+## Limitations
+
+Leash is a **defense-in-depth** layer, not a complete sandbox. It cannot protect against:
+
+- Kernel exploits or privilege escalation
+- Network-based attacks (downloading and executing scripts)
+- Commands not routed through the intercepted tools
+
+For maximum security, combine Leash with container isolation (Docker), user permission restrictions, or read-only filesystem mounts.
+
+## Development
+
+```bash
+cd ~/leash
+npm install
+npm run build
+```
+
+## Contributing
+
+Contributions are welcome! Areas where help is needed:
+
+- [ ] Plugin for AMP Code
+
+---
+
+_Keep your AI agents on a leash._

package/bin/leash.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import { homedir } from "os";
+import { fileURLToPath } from "url";
+import { PLATFORMS, setupPlatform, removePlatform } from "./lib.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function getDistPath() {
+  return join(__dirname, "..", "dist");
+}
+
+function getConfigPath(platformKey) {
+  const platform = PLATFORMS[platformKey];
+  return platform ? join(homedir(), platform.configPath) : null;
+}
+
+function getLeashPath(platformKey) {
+  const platform = PLATFORMS[platformKey];
+  return platform ? join(getDistPath(), platform.distPath) : null;
+}
+
+function setup(platformKey) {
+  const configPath = getConfigPath(platformKey);
+  const leashPath = getLeashPath(platformKey);
+
+  if (!configPath || !leashPath) {
+    console.error(`Unknown platform: ${platformKey}`);
+    console.error(`Available: ${Object.keys(PLATFORMS).join(", ")}`);
+    process.exit(1);
+  }
+
+  if (!existsSync(leashPath)) {
+    console.error(`Leash not found at: ${leashPath}`);
+    process.exit(1);
+  }
+
+  const result = setupPlatform(platformKey, configPath, leashPath);
+
+  if (result.error) {
+    console.error(result.error);
+    process.exit(1);
+  }
+
+  if (result.skipped) {
+    console.log(`[ok] Leash already installed for ${result.platform}`);
+    return;
+  }
+
+  console.log(`[ok] Config: ${result.configPath}`);
+  console.log(`[ok] Leash installed for ${result.platform}`);
+  console.log(`[ok] Restart ${result.platform} to apply changes`);
+}
+
+function remove(platformKey) {
+  const configPath = getConfigPath(platformKey);
+
+  if (!configPath) {
+    console.error(`Unknown platform: ${platformKey}`);
+    console.error(`Available: ${Object.keys(PLATFORMS).join(", ")}`);
+    process.exit(1);
+  }
+
+  const result = removePlatform(platformKey, configPath);
+
+  if (result.error) {
+    console.error(result.error);
+    process.exit(1);
+  }
+
+  if (result.notFound) {
+    console.log(`[ok] No config found for ${result.platform}`);
+    return;
+  }
+
+  if (result.notInstalled) {
+    console.log(`[ok] Leash not found in ${result.platform} config`);
+    return;
+  }
+
+  console.log(`[ok] Leash removed from ${result.platform}`);
+  console.log(`[ok] Restart ${result.platform} to apply changes`);
+}
+
+function showPath(platformKey) {
+  const leashPath = getLeashPath(platformKey);
+
+  if (!leashPath) {
+    console.error(`Unknown platform: ${platformKey}`);
+    console.error(`Available: ${Object.keys(PLATFORMS).join(", ")}`);
+    process.exit(1);
+  }
+
+  console.log(leashPath);
+}
+
+function showHelp() {
+  console.log(`
+leash - Security guardrails for AI coding agents
+
+Usage:
+  leash --setup <platform>    Install leash for a platform
+  leash --remove <platform>   Remove leash from a platform
+  leash --path <platform>     Show leash path for a platform
+  leash --help                Show this help
+
+Platforms:
+  opencode      OpenCode
+  pi            Pi Coding Agent
+  claude-code   Claude Code
+  factory       Factory Droid
+
+Examples:
+  leash --setup opencode
+  leash --remove claude-code
+  leash --path pi
+`);
+}
+
+const args = process.argv.slice(2);
+const command = args[0];
+const platform = args[1];
+
+switch (command) {
+  case "--setup":
+  case "-s":
+    if (!platform) {
+      console.error("Missing platform argument");
+      showHelp();
+      process.exit(1);
+    }
+    setup(platform);
+    break;
+  case "--remove":
+  case "-r":
+    if (!platform) {
+      console.error("Missing platform argument");
+      showHelp();
+      process.exit(1);
+    }
+    remove(platform);
+    break;
+  case "--path":
+  case "-p":
+    if (!platform) {
+      console.error("Missing platform argument");
+      showHelp();
+      process.exit(1);
+    }
+    showPath(platform);
+    break;
+  case "--help":
+  case "-h":
+  case undefined:
+    showHelp();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    showHelp();
+    process.exit(1);
+}

package/bin/lib.js

@@ -0,0 +1,156 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { dirname } from "path";
+
+export const PLATFORMS = {
+  opencode: {
+    name: "OpenCode",
+    configPath: ".config/opencode/config.json",
+    distPath: "opencode/leash.js",
+    setup: (config, leashPath) => {
+      config.plugins = config.plugins || [];
+      if (config.plugins.some((p) => p.includes("leash"))) {
+        return { skipped: true };
+      }
+      config.plugins.push(leashPath);
+      return { skipped: false };
+    },
+    remove: (config) => {
+      if (!config.plugins) return false;
+      const before = config.plugins.length;
+      config.plugins = config.plugins.filter((p) => !p.includes("leash"));
+      return config.plugins.length < before;
+    },
+  },
+  pi: {
+    name: "Pi",
+    configPath: ".pi/agent/settings.json",
+    distPath: "pi/leash.js",
+    setup: (config, leashPath) => {
+      config.hooks = config.hooks || [];
+      if (config.hooks.some((h) => h.includes("leash"))) {
+        return { skipped: true };
+      }
+      config.hooks.push(leashPath);
+      return { skipped: false };
+    },
+    remove: (config) => {
+      if (!config.hooks) return false;
+      const before = config.hooks.length;
+      config.hooks = config.hooks.filter((h) => !h.includes("leash"));
+      return config.hooks.length < before;
+    },
+  },
+  "claude-code": {
+    name: "Claude Code",
+    configPath: ".claude/settings.json",
+    distPath: "claude-code/leash.js",
+    setup: (config, leashPath) => {
+      config.hooks = config.hooks || {};
+      config.hooks.PreToolUse = config.hooks.PreToolUse || [];
+      const exists = config.hooks.PreToolUse.some((entry) =>
+        entry.hooks?.some((h) => h.command?.includes("leash"))
+      );
+      if (exists) {
+        return { skipped: true };
+      }
+      config.hooks.PreToolUse.push({
+        matcher: "Bash|Write|Edit",
+        hooks: [{ type: "command", command: `node ${leashPath}` }],
+      });
+      return { skipped: false };
+    },
+    remove: (config) => {
+      if (!config.hooks?.PreToolUse) return false;
+      const before = config.hooks.PreToolUse.length;
+      config.hooks.PreToolUse = config.hooks.PreToolUse.filter(
+        (entry) => !entry.hooks?.some((h) => h.command?.includes("leash"))
+      );
+      return config.hooks.PreToolUse.length < before;
+    },
+  },
+  factory: {
+    name: "Factory",
+    configPath: ".factory/settings.json",
+    distPath: "factory/leash.js",
+    setup: (config, leashPath) => {
+      config.hooks = config.hooks || {};
+      config.hooks.PreToolUse = config.hooks.PreToolUse || [];
+      const exists = config.hooks.PreToolUse.some((entry) =>
+        entry.hooks?.some((h) => h.command?.includes("leash"))
+      );
+      if (exists) {
+        return { skipped: true };
+      }
+      config.hooks.PreToolUse.push({
+        matcher: "Execute|Write|Edit",
+        hooks: [{ type: "command", command: `node ${leashPath}` }],
+      });
+      return { skipped: false };
+    },
+    remove: (config) => {
+      if (!config.hooks?.PreToolUse) return false;
+      const before = config.hooks.PreToolUse.length;
+      config.hooks.PreToolUse = config.hooks.PreToolUse.filter(
+        (entry) => !entry.hooks?.some((h) => h.command?.includes("leash"))
+      );
+      return config.hooks.PreToolUse.length < before;
+    },
+  },
+};
+
+export function readConfig(configPath) {
+  if (!existsSync(configPath)) {
+    return {};
+  }
+  try {
+    return JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(configPath, config) {
+  const dir = dirname(configPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+export function setupPlatform(platformKey, configPath, leashPath) {
+  const platform = PLATFORMS[platformKey];
+  if (!platform) {
+    return { error: `Unknown platform: ${platformKey}` };
+  }
+
+  const config = readConfig(configPath);
+  const result = platform.setup(config, leashPath);
+
+  if (result.skipped) {
+    return { skipped: true, platform: platform.name };
+  }
+
+  writeConfig(configPath, config);
+  return { success: true, platform: platform.name, configPath };
+}
+
+export function removePlatform(platformKey, configPath) {
+  const platform = PLATFORMS[platformKey];
+  if (!platform) {
+    return { error: `Unknown platform: ${platformKey}` };
+  }
+
+  if (!existsSync(configPath)) {
+    return { notFound: true, platform: platform.name };
+  }
+
+  const config = readConfig(configPath);
+  const removed = platform.remove(config);
+
+  if (!removed) {
+    return { notInstalled: true, platform: platform.name };
+  }
+
+  writeConfig(configPath, config);
+  return { success: true, platform: platform.name };
+}