@ssweens/pi-leash 0.12.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.12.0] - 2026-05-14
+### Added
+- Sudo password caching (opt-in, in-memory, 5-minute TTL by default). The sudo password dialog now renders a Tab-toggleable `[ ] Remember password for N min (in-memory only)` checkbox. When checked, the password is cached in module memory for `sudoMode.cacheTtl` (default 300_000 ms) so consecutive sudo invocations skip the password re-entry step. The approval dialog (allow/deny) still runs every time — only the password step is bypassed when the cache is warm.
+- New config under `permissionGate.sudoMode`:
+  - `cacheEnabled` (default `true`) — when `false` the checkbox is hidden and the cache lookup short-circuits.
+  - `cacheTtl` (default `300000` ms) — how long a remembered password lives in memory.
+- Cache is cleared on TTL expiry (timer is `unref()`'d so it never keeps the loop alive), on `incorrect password` stderr (with an explicit notification that the cached password was rejected), on `session_shutdown`, and on process `exit` / `SIGINT` / `SIGTERM`. Passwords are never written to disk, logs, or telemetry.
+
+### Changed
+- Dropped `@changesets/cli` workflow in favor of manual version + CHANGELOG management to match the rest of the @ssweens pi-packages repo. The `changeset` / `version` scripts are gone; `release` is now a plain `npm publish` shortcut.
+
+### Notes
+- First public npm release. Prior 0.1.0–0.11.0 versions existed only in the source repo and were not published.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ssweens
+
+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,221 @@
+# Pi Leash
+
+Security hooks for Pi to reduce accidental destructive actions and secret-file access.
+
+Forked from [`@aliou/pi-guardrails`](https://github.com/aliou/pi-guardrails) (MIT) with added **sudo mode** for secure password handling and an opt-in in-memory password cache. See [Credits & Attribution](#credits--attribution) below for details.
+
+## Install
+
+```bash
+pi install npm:@ssweens/pi-leash
+```
+
+Or from git:
+
+```bash
+pi install git:github.com/ssweens/pi-leash
+```
+
+## What it does
+
+- **policies**: named file-protection rules with per-rule protection levels.
+- **permission-gate**: detects dangerous bash commands and asks for confirmation.
+- **optional command explainer**: can call a small LLM to explain a dangerous command inline in the confirmation dialog.
+- **sudo mode** (opt-in): securely handles sudo commands by prompting for passwords and executing with `sudo -S`.
+
+## Configuration
+
+Pi Leash reads from:
+
+**`~/.pi/agent/settings/pi-leash.json`**
+
+Create this file to customize settings. All fields are optional — sensible defaults are used when not specified.
+
+### Example config
+
+```json
+{
+  "enabled": true,
+  "features": {
+    "policies": true,
+    "permissionGate": true
+  },
+  "permissionGate": {
+    "sudoMode": {
+      "enabled": true,
+      "timeout": 30000,
+      "preserveEnv": false
+    }
+  }
+}
+```
+
+## Current schema
+
+```json
+{
+  "enabled": true,
+  "features": {
+    "policies": true,
+    "permissionGate": true
+  },
+  "policies": {
+    "rules": [
+      {
+        "id": "secret-files",
+        "description": "Files containing secrets",
+        "patterns": [
+          { "pattern": ".env" },
+          { "pattern": ".env.local" },
+          { "pattern": ".env.production" },
+          { "pattern": ".env.prod" },
+          { "pattern": ".dev.vars" }
+        ],
+        "allowedPatterns": [
+          { "pattern": ".env.example" },
+          { "pattern": ".env.sample" },
+          { "pattern": ".env.test" },
+          { "pattern": "*.example.env" },
+          { "pattern": "*.sample.env" },
+          { "pattern": "*.test.env" }
+        ],
+        "protection": "noAccess",
+        "onlyIfExists": true
+      }
+    ]
+  },
+  "permissionGate": {
+    "patterns": [
+      { "pattern": "rm -rf", "description": "recursive force delete" },
+      { "pattern": "sudo", "description": "superuser command" },
+      { "pattern": "git checkout", "description": "branch switch or discard uncommitted changes" }
+    ],
+    "requireConfirmation": true,
+    "allowedPatterns": [],
+    "autoDenyPatterns": [],
+    "explainCommands": false,
+    "explainModel": null,
+    "explainTimeout": 5000,
+    "sudoMode": {
+      "enabled": false,
+      "timeout": 30000,
+      "preserveEnv": false
+    }
+  }
+}
+```
+
+All fields optional. Missing fields use defaults.
+
+## Policies
+
+Each rule has:
+
+- `id`: stable identifier
+- `patterns`: files to match (glob by default, regex if `regex: true`). Patterns with `/` match full path; patterns without `/` match basename only.
+- `allowedPatterns`: exceptions
+- `protection`:
+  - `noAccess`: block `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`
+  - `readOnly`: block `write`, `edit`, `bash`
+  - `none`: no protection
+- `onlyIfExists` (default true)
+- `blockMessage` with `{file}` placeholder
+- `enabled` (default true)
+
+When multiple rules match, strongest protection wins: `noAccess > readOnly > none`.
+
+## Permission gate
+
+Detects dangerous bash commands and prompts user confirmation.
+
+Built-in dangerous patterns are matched structurally (AST-based):
+
+- `rm -rf`
+- `sudo`
+- `dd if=`
+- `mkfs.`
+- `chmod -R 777`
+- `chown -R`
+- `git checkout`
+
+You can add custom dangerous patterns via `permissionGate.patterns`.
+
+### Explain commands (opt-in)
+
+If enabled, guardrails calls an LLM before showing the confirmation dialog and displays a short explanation.
+
+Config fields:
+
+- `permissionGate.explainCommands` (boolean)
+- `permissionGate.explainModel` (`provider/model-id`)
+- `permissionGate.explainTimeout` (ms)
+
+Failures/timeouts degrade gracefully: dialog still shows without explanation.
+
+### Sudo mode (opt-in)
+
+When enabled, sudo commands prompt for the sudo password and execute securely using `sudo -S`. The password is masked during input and cleared from memory immediately after execution.
+
+Config fields:
+
+- `permissionGate.sudoMode.enabled` (boolean) - Enable sudo mode
+- `permissionGate.sudoMode.timeout` (number, ms) - Command timeout (default: 30000)
+- `permissionGate.sudoMode.preserveEnv` (boolean) - Preserve environment with `sudo -E` (default: false)
+
+**Example config:**
+```json
+{
+  "permissionGate": {
+    "sudoMode": {
+      "enabled": true,
+      "timeout": 60000,
+      "preserveEnv": false
+    }
+  }
+}
+```
+
+**Security notes:**
+- Passwords are never logged or stored to disk
+- Password input is masked (••••)
+- Password buffer is overwritten with asterisks after use
+- Uses `sudo -S` for secure stdin-based password delivery
+- Failed authentication shows an error notification
+
+## Events
+
+Pi Leash emits events for other extensions:
+
+### `leash:blocked`
+
+```ts
+interface LeashBlockedEvent {
+  feature: "policies" | "permissionGate";
+  toolName: string;
+  input: Record<string, unknown>;
+  reason: string;
+  userDenied?: boolean;
+}
+```
+
+### `leash:dangerous`
+
+```ts
+interface LeashDangerousEvent {
+  command: string;
+  description: string;
+  pattern: string;
+}
+```
+
+## Credits & Attribution
+
+Pi Leash is a fork of [`@aliou/pi-guardrails`](https://github.com/aliou/pi-guardrails) by [@aliou](https://github.com/aliou), used under the terms of the MIT License. The original package provided the file-protection policy engine, the dangerous-command permission gate, and the optional command-explainer integration that this fork inherits.
+
+This fork adds:
+- Secure sudo mode with masked password input and `sudo -S` execution.
+- Opt-in in-memory sudo password caching with a per-prompt `Remember for N min` toggle.
+- Self-contained shell parser: the `@aliou/sh` parser used by structural command matching is vendored into `src/vendor/aliou-sh` (also MIT, see [`NOTICE.md`](src/vendor/aliou-sh/NOTICE.md)) so local path installs do not depend on external module resolution.
+- Various stability fixes to the sudo approval flow, dialog key handling, and dangerous-pattern detection.
+
+Both pi-leash and the upstream `@aliou/pi-guardrails` are MIT-licensed. See [`LICENSE`](LICENSE) for the full text.

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@ssweens/pi-leash",
+  "version": "0.12.0",
+  "license": "MIT",
+  "type": "module",
+  "private": false,
+  "author": "ssweens (forked from @aliou/pi-guardrails)",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "leash",
+    "guardrails",
+    "security",
+    "sudo",
+    "permissions"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ssweens/pi-leash"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "peerDependencies": {
+    "@mariozechner/pi-agent-core": ">=0.52.7",
+    "@mariozechner/pi-ai": ">=0.52.7",
+    "@mariozechner/pi-coding-agent": ">=0.52.7",
+    "@mariozechner/pi-tui": ">=0.51.0"
+  },
+  "devDependencies": {
+    "@aliou/biome-plugins": "^0.3.2",
+    "@biomejs/biome": "^2.3.13",
+    "@mariozechner/pi-agent-core": "0.52.7",
+    "@mariozechner/pi-ai": "0.52.7",
+    "@mariozechner/pi-coding-agent": "0.52.7",
+    "@sinclair/typebox": "^0.34.48",
+    "@types/node": "^25.0.10",
+    "husky": "^9.1.7",
+    "typescript": "^5.9.3"
+  },
+  "pnpm": {
+    "overrides": {
+      "@mariozechner/pi-ai": "$@mariozechner/pi-coding-agent",
+      "@mariozechner/pi-tui": "$@mariozechner/pi-coding-agent"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "format": "biome check --write",
+    "check:lockfile": "pnpm install --frozen-lockfile --ignore-scripts",
+    "prepare": "[ -d .git ] && husky || true",
+    "release": "npm publish"
+  },
+  "packageManager": "pnpm@10.26.1",
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-agent-core": {
+      "optional": true
+    },
+    "@mariozechner/pi-ai": {
+      "optional": true
+    },
+    "@mariozechner/pi-coding-agent": {
+      "optional": true
+    },
+    "@mariozechner/pi-tui": {
+      "optional": true
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,285 @@
+/**
+ * Configuration schema for the Pi Leash extension.
+ *
+ * Reads from ~/.pi/agent/settings/pi-leash.json (if present).
+ * All fields are optional — sensible defaults are used when not specified.
+ *
+ * Example config:
+ * {
+ *   "enabled": true,
+ *   "features": {
+ *     "policies": true,
+ *     "permissionGate": true
+ *   },
+ *   "permissionGate": {
+ *     "sudoMode": {
+ *       "enabled": true,
+ *       "timeout": 30000
+ *     }
+ *   }
+ * }
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+
+export function getConfigPath(): string {
+  return join(getAgentDir(), "settings", "pi-leash.json");
+}
+
+/**
+ * A pattern with explicit matching mode.
+ * Default: glob for files, substring for commands.
+ * regex: true means full regex matching.
+ */
+export interface PatternConfig {
+  pattern: string;
+  regex?: boolean;
+}
+
+/**
+ * Permission gate pattern. When regex is false (default), the pattern
+ * is matched as substring against the raw command string.
+ * When regex is true, uses full regex against the raw string.
+ */
+export interface DangerousPattern extends PatternConfig {
+  description: string;
+}
+
+/**
+ * Protection level for a policy rule.
+ */
+export type Protection = "none" | "readOnly" | "noAccess";
+
+/**
+ * A named policy rule. Matches files by patterns and enforces a protection level.
+ */
+export interface PolicyRule {
+  /** Stable identifier used for deduplication across scopes. */
+  id: string;
+  /** Optional display name for settings/UI. */
+  name?: string;
+  /** Human-readable description. */
+  description?: string;
+  /** File patterns to protect. */
+  patterns: PatternConfig[];
+  /** Optional exceptions. */
+  allowedPatterns?: PatternConfig[];
+  /** Protection level. */
+  protection: Protection;
+  /** Block only when file exists on disk. Default true. */
+  onlyIfExists?: boolean;
+  /** Message shown when blocked; supports {file} placeholder. */
+  blockMessage?: string;
+  /** Per-rule toggle. Default true. */
+  enabled?: boolean;
+}
+
+/**
+ * User-facing guardrails configuration.
+ * All fields are optional - defaults are applied.
+ */
+export interface GuardrailsConfig {
+  /** Enable/disable guardrails entirely. Default: true */
+  enabled?: boolean;
+  /** Feature toggles */
+  features?: {
+    /** Enable file protection policies. Default: true */
+    policies?: boolean;
+    /** Enable permission gate for dangerous commands. Default: true */
+    permissionGate?: boolean;
+  };
+  /** File protection policies */
+  policies?: {
+    /** Custom rules to add to the default secret-files rule */
+    rules?: PolicyRule[];
+  };
+  /** Permission gate configuration */
+  permissionGate?: {
+    /** Additional dangerous patterns to watch for */
+    patterns?: DangerousPattern[];
+    /** Require confirmation before executing dangerous commands. Default: true */
+    requireConfirmation?: boolean;
+    /** Patterns that bypass the permission gate */
+    allowedPatterns?: PatternConfig[];
+    /** Patterns that are automatically denied */
+    autoDenyPatterns?: PatternConfig[];
+    /** Use LLM to explain commands before confirmation. Default: false */
+    explainCommands?: boolean;
+    /** Model to use for explanations (format: provider/model-id) */
+    explainModel?: string;
+    /** Timeout for explanation requests. Default: 5000 */
+    explainTimeout?: number;
+    /** Sudo mode configuration */
+    sudoMode?: {
+      /** Enable sudo password prompts and execution. Default: false */
+      enabled?: boolean;
+      /** Command timeout in milliseconds. Default: 30000 */
+      timeout?: number;
+      /** Preserve environment with sudo -E. Default: false */
+      preserveEnv?: boolean;
+      /**
+       * Show a "Remember password for N minutes" toggle in the sudo password
+       * dialog. When the user opts in, the password is cached in-memory only
+       * (never written to disk) for `cacheTtl` milliseconds so subsequent
+       * sudo prompts skip the password step. The approval dialog still runs
+       * every time. Default: true.
+       */
+      cacheEnabled?: boolean;
+      /** Cache TTL in milliseconds. Default: 300000 (5 minutes). */
+      cacheTtl?: number;
+    };
+  };
+}
+
+/**
+ * Resolved configuration with all defaults applied.
+ */
+export interface ResolvedConfig {
+  enabled: boolean;
+  features: {
+    policies: boolean;
+    permissionGate: boolean;
+  };
+  policies: {
+    rules: PolicyRule[];
+  };
+  permissionGate: {
+    patterns: DangerousPattern[];
+    useBuiltinMatchers: boolean;
+    requireConfirmation: boolean;
+    allowedPatterns: PatternConfig[];
+    autoDenyPatterns: PatternConfig[];
+    explainCommands: boolean;
+    explainModel: string | null;
+    explainTimeout: number;
+    sudoMode: {
+      enabled: boolean;
+      timeout: number;
+      preserveEnv: boolean;
+      cacheEnabled: boolean;
+      cacheTtl: number;
+    };
+  };
+}
+
+const DEFAULT_SECRET_FILES_RULE: PolicyRule = {
+  id: "secret-files",
+  description: "Files containing secrets",
+  patterns: [
+    { pattern: ".env" },
+    { pattern: ".env.local" },
+    { pattern: ".env.production" },
+    { pattern: ".env.prod" },
+    { pattern: ".dev.vars" },
+  ],
+  allowedPatterns: [
+    { pattern: "*.example.env" },
+    { pattern: "*.sample.env" },
+    { pattern: "*.test.env" },
+    { pattern: ".env.example" },
+    { pattern: ".env.sample" },
+    { pattern: ".env.test" },
+  ],
+  protection: "noAccess",
+  onlyIfExists: true,
+  blockMessage:
+    "Accessing {file} is not allowed. This file contains secrets. " +
+    "Explain to the user why you want to access this file, and if changes are needed ask the user to make them.",
+  enabled: true,
+};
+
+const DEFAULT_DANGEROUS_PATTERNS: DangerousPattern[] = [
+  { pattern: "rm -rf", description: "recursive force delete" },
+  { pattern: "sudo", description: "superuser command" },
+  { pattern: "dd if=", description: "disk write operation" },
+  { pattern: "mkfs.", description: "filesystem format" },
+  { pattern: "chmod -R 777", description: "insecure recursive permissions" },
+  { pattern: "chown -R", description: "recursive ownership change" },
+  {
+    pattern: "git checkout",
+    description: "branch switch or discard uncommitted changes",
+  },
+];
+
+function mergeConfig(userConfig: GuardrailsConfig): ResolvedConfig {
+  // Build policies: default secret-files rule + user rules
+  const policies: ResolvedConfig["policies"] = {
+    rules: [DEFAULT_SECRET_FILES_RULE, ...(userConfig.policies?.rules ?? [])],
+  };
+
+  // Build permission gate settings
+  const pg = userConfig.permissionGate ?? {};
+  const permissionGate: ResolvedConfig["permissionGate"] = {
+    patterns: [...DEFAULT_DANGEROUS_PATTERNS, ...(pg.patterns ?? [])],
+    useBuiltinMatchers: true,
+    requireConfirmation: pg.requireConfirmation ?? true,
+    allowedPatterns: pg.allowedPatterns ?? [],
+    autoDenyPatterns: pg.autoDenyPatterns ?? [],
+    explainCommands: pg.explainCommands ?? false,
+    explainModel: pg.explainModel ?? null,
+    explainTimeout: pg.explainTimeout ?? 5000,
+    sudoMode: {
+      enabled: pg.sudoMode?.enabled ?? false,
+      timeout: pg.sudoMode?.timeout ?? 30000,
+      preserveEnv: pg.sudoMode?.preserveEnv ?? false,
+      cacheEnabled: pg.sudoMode?.cacheEnabled ?? true,
+      cacheTtl: pg.sudoMode?.cacheTtl ?? 300000,
+    },
+  };
+
+  return {
+    enabled: userConfig.enabled ?? true,
+    features: {
+      policies: userConfig.features?.policies ?? true,
+      permissionGate: userConfig.features?.permissionGate ?? true,
+    },
+    policies,
+    permissionGate,
+  };
+}
+
+let _cachedConfig: ResolvedConfig | null = null;
+
+/**
+ * Load and merge configuration from global settings.
+ * Caches the result for the session.
+ */
+export function loadConfig(): ResolvedConfig {
+  if (_cachedConfig !== null) {
+    return _cachedConfig;
+  }
+
+  const configPath = getConfigPath();
+  let userConfig: GuardrailsConfig = {};
+
+  if (existsSync(configPath)) {
+    try {
+      userConfig = JSON.parse(
+        readFileSync(configPath, "utf-8"),
+      ) as GuardrailsConfig;
+    } catch (err) {
+      console.warn(`[pi-leash] Failed to parse ${configPath}: ${err}`);
+    }
+  }
+
+  _cachedConfig = mergeConfig(userConfig);
+  return _cachedConfig;
+}
+
+/**
+ * Clear the cached configuration.
+ * Call this if the config file changes during a session.
+ */
+export function clearConfigCache(): void {
+  _cachedConfig = null;
+}
+
+/**
+ * Get the current configuration (cached).
+ * Same as loadConfig() but semantically clearer when you know it's already loaded.
+ */
+export function getConfig(): ResolvedConfig {
+  return loadConfig();
+}

package/src/hooks/index.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ResolvedConfig } from "../config";
+import { setupPermissionGateHook } from "./permission-gate";
+import { setupPoliciesHook } from "./policies";
+
+export function setupLeashHooks(pi: ExtensionAPI, config: ResolvedConfig) {
+  setupPoliciesHook(pi, config);
+  setupPermissionGateHook(pi, config);
+}