auto-permission-system 0.0.0-stage → 2.20.0

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Entries below [1.0.0] are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from [Conventional Commits](https://www.conventionalcommits.org/) — do not edit by hand.
+
+# [2.0.0](https://github.com/Navin009/auto-permission-system/compare/v1.2.0...v2.0.0) (2026-10-02)
+
+
+* fix(policy)!: an untrusted project sandbox.json may only tighten the policy ([94deb76](https://github.com/Navin009/auto-permission-system/commit/94deb763cbaf47c908a7a746cc59a469979f92d9))
+
+
+### Bug Fixes
+
+* **policy:** explain an untrusted project file in plain words and remember "no" ([0a38470](https://github.com/Navin009/auto-permission-system/commit/0a38470788df9b6eb91a334b48c61cee4f726e9c))
+* **sandbox:** attribute Layer 1 blocks to the right path and never offer / as a grant ([c8c89be](https://github.com/Navin009/auto-permission-system/commit/c8c89bec61a3b7077c71173e36bae343a345ddcd))
+* **sandbox:** make file-name deny patterns match anywhere in the project for bash ([fdd8f22](https://github.com/Navin009/auto-permission-system/commit/fdd8f22fe97f2a3c6c7615b798bea578bbc25f05))
+
+
+### Features
+
+* **guard:** ask before reading outside the project; a named path runs once ([49e089a](https://github.com/Navin009/auto-permission-system/commit/49e089affa8bf98d9f02163f4b8c9d56e9882516))
+* **guard:** pre-select "no" in the ask-tier prompt and add session grants ([b1e5530](https://github.com/Navin009/auto-permission-system/commit/b1e553030e133f2749ad6214bcf7ac13f6f0695d))
+
+
+### BREAKING CHANGES
+
+* existing project .pi/sandbox.json files are untrusted
+after upgrading. Their deny rules still apply; their allow lists,
+overrides and enabled flag apply after one /security trust per project.
+
+Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
+
+# [1.2.0](https://github.com/Navin009/auto-permission-system/compare/v1.1.0...v1.2.0) (2026-10-01)
+
+
+### Bug Fixes
+
+* **deps:** bump @anthropic-ai/sandbox-runtime to ^0.0.78 ([de536c8](https://github.com/Navin009/auto-permission-system/commit/de536c83962d6203700696ae27543d0b9d5dc512))
+* **guard:** enforce the read policy on grep, find and ls ([3b8d992](https://github.com/Navin009/auto-permission-system/commit/3b8d992ebbcd02d87bbe99f7f190fbe8a019d6cf))
+* **guard:** make the absolute-deny tier deny on its own ([bad9249](https://github.com/Navin009/auto-permission-system/commit/bad9249aa5374bc9dde5989bd189a12c5405e9af)), closes [hi#risk](https://github.com/hi/issues/risk)
+
+
+### Features
+
+* **guard:** two-step select instead of typing "i understand" ([a4b1430](https://github.com/Navin009/auto-permission-system/commit/a4b14304398d5197e7b6d5fa025b9e5726769c0e))
+
+# [1.1.0](https://github.com/Navin009/auto-permission-system/compare/v1.0.0...v1.1.0) (2026-07-19)
+
+
+### Features
+
+* add CLAUDE.md for documentation on pi-secure-it extension and conventions ([b5e6487](https://github.com/Navin009/auto-permission-system/commit/b5e6487c7334be0bc42a7af7dff96a6aaa3a5dcf))
+
+# 1.0.0 (2026-07-19)
+
+
+### Features
+
+* Implement CI/CD workflows with semantic-release, updated dependencies ([f53b39a](https://github.com/Navin009/auto-permission-system/commit/f53b39a8be162d22a1cddca123ae3c00b7dca70a))
+* Update CI configuration and add test script to package.json ([bc43b09](https://github.com/Navin009/auto-permission-system/commit/bc43b09f69a4ef849d39c045c3dd609d316e7728))
+
+## [1.0.0] - 2026-07-15
+
+### Added
+- **Layer 1** — OS-level bash sandbox via `@anthropic-ai/sandbox-runtime` (`sandbox-exec` on macOS, `bubblewrap` on Linux). Blocks filesystem writes outside `allowWrite`, reads of `denyRead`, and network outside `allowedDomains`.
+- **Layer 2** — In-process tool guard hooking `read`, `write`, `edit`, `fetch_content`, `web_search`, `get_search_content`. Applies the same policy file as Layer 1.
+- **Layer 3** — Subagent posture: stricter network policy when `ctx.hasUI === false` (subagents, `-p` mode, JSON mode). Configurable via `subagent.network`: `allow` (default) | `deny` | `research-only`.
+- **Ask-tier prompts** — Interactive per-call allow/deny dialog with four persistence tiers: this-once, always-for-current-project (file), always-for-current-project (folder), always-for-all-projects (file), always-for-all-projects (folder). Persists to `.pi/sandbox.json` or `~/.pi/agent/extensions/sandbox.json`.
+- **Absolute-deny tier** — Credential material (`~/.ssh`, `~/.gnupg`, `~/.aws`, `*.pem`, `*.key`) requires typing `"i understand"` verbatim; "always" is never available for this tier.
+- **`/security` command** — Shows active policy, project-local overrides, and last 10 audit events.
+- **`/sandbox` command** — Shows current bash sandbox config. `/sandbox reload` live-reloads after manual edits to `sandbox.json`.
+- **Audit log** — Append-only JSONL at `~/.pi/agent/audit.log`. One entry per blocked/allowed/always decision.
+- **`sandbox.example.json`** — Documented reference config showing all available fields.
+- **Skill** — `skills/pi-secure-it/SKILL.md` explains the security model and how to configure it.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Hannes
+Copyright (c) 2026 Navin009 (fork modifications)
+
+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

@@ -1,3 +1,259 @@
-# Temporary Holding Version
+# auto-permission-system
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/auto-permission-system.svg)](https://www.npmjs.com/package/auto-permission-system)
+[![npm downloads](https://img.shields.io/npm/dm/auto-permission-system.svg)](https://www.npmjs.com/package/auto-permission-system)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Pi package](https://img.shields.io/badge/pi--package-gallery-blueviolet)](https://pi.dev/packages)
+[![CI](https://github.com/Navin009/auto-permission-system/actions/workflows/ci.yml/badge.svg)](https://github.com/Navin009/auto-permission-system/actions/workflows/ci.yml)
+
+**A security sandbox, permission system and tool guard for the [Pi coding agent](https://pi.dev).**
+It puts allow/deny rules, interactive ask prompts, secret detection and an audit log around every tool the agent can call — file reads and writes, shell commands, searches and network access — so the agent can work in your repository without reaching your credentials or the wider internet by accident.
+
+Enforcement happens in three layers:
+
+- **Layer 1** — OS-level bash sandbox (`sandbox-exec` on macOS, `bubblewrap` on Linux) that blocks filesystem writes outside an allow-list, reads of sensitive paths, reads outside the project when `outsideProject.read` gates them, and network egress to unlisted domains.
+- **Layer 2** — In-process tool guard applying the same policy to the tools the OS sandbox can't reach: `read`, `grep`, `find`, `ls`, `write`, `edit`, `fetch_content`, `web_search`, `get_search_content`. `grep` output lines from denied files beneath an allowed search root are removed before the model sees them.
+- **Layer 3** — Subagent posture: optionally drop or restrict network access when running headless (`-p`, JSON mode, subagents).
+
+When a tool call is blocked you get an interactive prompt — no need to leave pi and hand-edit config files. Choose *this once*, *always for this project*, or *always for all projects* (file or parent-folder granularity). Decisions are persisted and audited.
+
+## Contents
+
+- [Install](#install)
+- [Requirements](#requirements)
+- [Configuration](#configuration)
+- [Commands](#commands)
+- [Escape hatches](#escape-hatches)
+- [FAQ](#faq)
+- [Audit log](#audit-log)
+- [Development](#development)
+- [Releasing](#releasing)
+- [License](#license)
+
+## Install
+
+`auto-permission-system` is a [Pi package](https://pi.dev/packages), so it installs with `pi install` from npm or git:
+
+```bash
+# From npm (recommended)
+pi install npm:auto-permission-system
+
+# From git
+pi install git:github.com/Navin009/auto-permission-system
+
+# Try it for one run, without installing
+pi -e npm:auto-permission-system
+```
+
+Browse it on the [Pi package gallery](https://pi.dev/packages). Installing from npm pins the released version; `pi update --extensions` reconciles to the latest.
+
+## Requirements
+
+- macOS or Linux
+- macOS: `sandbox-exec` is built in
+- Linux: `bubblewrap`, `socat`
+
+## Configuration
+
+Policy files are merged in order:
+
+| File | Scope |
+| ---- | ----- |
+| `sandbox.default.json` (shipped in this package) | Baseline — used when no other file overrides it |
+| `~/.pi/agent/extensions/sandbox.json` | Global (all projects) |
+| `<cwd>/.pi/sandbox.json` | Project-local (auto-written by ask-tier prompts) |
+
+A higher layer only states what it changes; absent keys keep the layer below. A **trusted** project may loosen the baseline; an **untrusted** project (ADR-013) may only tighten it. You do **not** need a global file: the shipped default already turns on the project boundary (`outsideProject.read: "ask"`), the credential `modelDenyRead` list and the full `denyRead` / `denyWrite` lists. Copy `sandbox.example.json` only when you want to start customising.
+
+### Key fields
+
+```jsonc
+{
+  "enabled": true,                      // set false to disable Layer 2 without --yolo
+  "mode": "default",                   // "default" (rules) | "advanced-secure" (secret detection, ADR-018)
+  "network": {
+    "allowedDomains": [                 // domains fetch_content / get_search_content may reach
+      "github.com", "*.github.com",
+      "registry.npmjs.org"
+    ],
+    "deniedDomains": []                 // explicit block-list (checked before allowedDomains)
+  },
+  "filesystem": {
+    "denyRead": ["~/.ssh", "~/.aws", "~/.pi/agent"],  // Layer 1 + Layer 2: no read at all
+    "askRead": [".env", ".env.*"],    // Layer 1 + Layer 2: ask before reading, not hard-denied (ADR-019)
+    "modelDenyRead": ["~/.netrc"],      // Layer 2 only: model's read tool blocked; subprocesses ok
+    "allowWrite": [".", "/tmp"],        // Layer 2: writes only inside these roots
+    "denyWrite": [".env", "*.pem"]     // Layer 1 + Layer 2: write always blocked
+  },
+  "subagent": {
+    "network": "allow"                  // "allow" | "deny" | "research-only"
+  },
+  "commands": {
+    "ask": ["printenv", "env", "/proc/*/environ"]  // bash: ask before these (they can print env tokens)
+  }
+}
+```
+
+### Project policy files and trust
+
+A folder can have its own `.pi/sandbox.json`. It comes with the folder, for example with a repository that you clone. So auto-permission-system does not trust it automatically (ADR-013).
+
+- **Block rules in the file always apply.** They are added to your rules.
+- **Changes that make your security weaker do not apply** until you trust the file. Examples: turn off auto-permission-system, let bash write to `/`, allow more websites.
+- auto-permission-system shows a warning that lists these changes in plain words.
+- **Did you write the file?** Type `/security trust`. auto-permission-system shows the changes and asks you. If you say "No", it does not warn again until the file changes.
+- Trust is for the file as it is now. If the file changes, auto-permission-system asks again.
+- Most folders have no `.pi/sandbox.json`, so you see nothing. Your own "always for CURRENT project" answers keep the file trusted.
+- `/security untrust` removes the trust. `/security` shows the status.
+
+### Outside the project
+
+Reads outside the working directory can ask before they run (ADR-012):
+
+```jsonc
+"filesystem": {
+  "outsideProject": {
+    "read": "ask",                       // "allow" (default) | "ask" | "deny"
+    "allowRead": ["~/repos", "~/.cargo/registry"]
+  }
+}
+```
+
+Never asked about: the project itself, your `allowWrite` roots, pi's own package (docs, examples) and `allowRead`. `~/.pi/agent` is **not** exempt as a whole: it is in the default `denyRead` (it holds `mcp.json`, which can carry API keys, plus sessions and caches), while `auth.json` stays absolute-denied — add specific paths such as `~/.pi/agent/install` to `outsideProject.allowRead` when a tool must read them without asking. Both layers enforce the boundary. Layer 2 prompts. Layer 1 fences the home directory for `bash` (ADR-014); because the OS layer cannot prompt mid-command, `"ask"` pre-flights the command (ADR-015) — a read-like command that plainly names an outside path (`ls`, `cat`, `find`, `grep`, …) prompts **before** it runs, with `yes — this once` (run without saving) and the persistent `always` options, so **allow returns the complete real output and deny runs nothing** (an explicit refusal, never a silently trimmed listing). Reads the pre-flight can't see (variable expansion, nested shells, scripts) still hit the fence and stay masked. In an interactive session a read runs without a prompt when **you named its full path** (`/…` or `~/…`) in one of your own messages; only messages you typed count, never tool output or the agent's text. Otherwise you get the ask-tier prompt, including `yes — for this session`. Headless runs block (set `allowRead` for paths a harness needs). Writes outside the project are governed by `allowWrite` as before.
+
+### Ask-tier prompt
+
+`no — block` is pre-selected, so Enter alone blocks. Besides `yes — this once` and the persistent `always` options there is `yes — for this session` (this file, its folder, or this domain), kept in memory until the session ends and never saved (ADR-010).
+
+Every prompt waits **10 seconds** by default. If you do not answer, it resolves to the safe default: **block / deny**.
+
+### File-name patterns
+
+An entry without `/` or `~` (`.env`, `*.key`) is a file name. pi's own tools (Layer 2) match it anywhere on disk; bash (Layer 1) matches it anywhere under the project directory, so `packages/api/.env` is covered too. Use a full path (`~/other/.env`) to cover a file outside the project for bash.
+
+### Permission modes
+
+`mode` selects how much pi inspects, on top of the rules:
+
+- **`default`** (shipped) — rules only: sandbox.json paths, domains, and commands. Nothing inspects file contents.
+- **`advanced-secure`** (recommended) — adds secret/credential detection:
+  - **File reads:** a filename that looks like a credential store asks before the read.
+  - **MCP calls:** `mcp__<server>__<tool>` calls are classified; a risky (mutating/destructive) call asks before it runs.
+  - **Tool/command/file output:** before any output reaches the model, a secret-like hit shows `⚠ Sensitive information detected`, the file, and each detected line as `lineNo: text`, and the question **Should the AI be allowed to see it?** with two choices — **No, keep private** or **Yes, allow**. A bare `key` counts only when the value looks machine-generated: `key=<random>` asks, while `key=value`, `key=subagent.network`, and code such as `const key = x` stay clean. No, keep private withholds the output and tells the model plainly that the output was withheld because it may contain sensitive information, so the model does not mistake it for a failure or an empty result. Esc or timeout keeps it private.
+
+Detection can only **add** asks or blocks; it never loosens a rule. The mode is layered like every other key: an untrusted project may opt *in* to `advanced-secure`, but only a trusted project (or the global file) may turn it off.
+
+Change it with `/permission-mode`; `default` / `advanced-secure` are saved to the global `sandbox.json` and reflected in the footer's single sandbox chip: `Sandbox: 🧠 N domains, M paths` for `advanced-secure`, `Sandbox: 🔒 N domains, M paths` for `default`.
+
+The third choice, **YOLO**, turns every layer off. It is a persisted mode like the others — `setPolicyMode()` writes `mode: "yolo"` to the global `sandbox.json`, so the next session starts that way too. The chip reads `⚠️ YOLO — all security layers disabled`, and it is one pick in the same menu. Pick `Default` or `Advanced Secure` to turn the layers back on (ADR-020).
+
+### Commands that print secrets
+
+Bash commands that dump the environment can print the API tokens pi runs on. `commands.ask` lists them, and Layer 1 asks before running one (`Block` / `Allow once`); deny runs nothing (ADR-017). An entry without `/` is a command name (matched on the head of each `;`/`&&`/`|` segment); an entry with a path is globbed against every path token, so any reader of the per-process environ file is caught. The shipped default is `["printenv", "env", "/proc/*/environ"]`.
+
+### Sensitive reads ask by default
+
+`askRead` lists paths that **prompt** instead of being hard-denied (ADR-019). The shipped default asks for `.env` and `.env.*`, in both layers: the model's `read` tool asks, and the bash pre-flight asks before a command that plainly reads the file. No answer (Esc or the 10s timeout) blocks, and headless runs block. `denyRead` still wins over `askRead`, so put a path in `denyRead` to hard-deny it. The credential tier (`~/.ssh`, `~/.aws`, `*.pem`, `*.key`, `~/.gnupg`, `auth.json`) stays hard.
+
+### Absolute-deny tier
+
+Access to `~/.ssh`, `~/.gnupg`, `~/.aws`, `*.pem`, `*.key` and pi's own `~/.pi/agent/auth.json` is always a high-risk block. Allowing one call takes two menus, each with "block" pre-selected: pick *allow this ONE call*, then confirm with *Yes*. Pressing Enter twice blocks. The "always" option is never offered (ADR-009).
+
+### A policy file that does not parse
+
+`sandbox.json` is strict JSON: no comments, no trailing commas. If a file does not parse, both layers skip it and use the built-in defaults for it. Layer 2 then shows an error at session start and writes `policy-parse-error` to the audit log. The "always" prompts refuse to write to a file they cannot parse, so a hand-written policy is never replaced.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/security` | Show Layer 2 policy, project-local overrides, last 10 audit events |
+| `/sandbox` | Show Layer 1 (bash sandbox) config |
+| `/sandbox reload` | Live-reload sandbox after manual edits to `sandbox.json` |
+| `/permission-mode` | Choose the permission mode: Default (rules), Advanced Secure (secret detection), or YOLO (all layers off). Saved to the global `sandbox.json`. |
+
+## Escape hatches
+
+```bash
+pi --yolo          # disables ALL layers globally (visible warning banner)
+pi --no-sandbox    # alias for --yolo
+```
+
+Mid-session, `/permission-mode` → **YOLO** disables every layer in place (no restart); it is saved to the global `sandbox.json` like the other modes, and choosing Default or Advanced Secure brings the layers back (ADR-020). `pi --yolo` remains a per-run flag and writes nothing.
+
+## Audit log
+
+Every block/allow/always decision is appended to `~/.pi/agent/audit.log` as a JSON line:
+
+```jsonc
+{
+  "ts": "2026-07-15T10:00:00.000Z",
+  "layer": 2,
+  "tool": "write",
+  "subject": "/Users/you/project/secret.pem",
+  "reason": "denyWrite matched \"*.pem\"",
+  "decision": "no",
+  "cwd": "/Users/you/project"
+}
+```
+
+## FAQ
+
+### How do I allow the agent to reach a new domain?
+Add it to `network.allowedDomains` in a policy file (global `~/.pi/agent/extensions/sandbox.json` or project `<cwd>/.pi/sandbox.json`), or just run the tool once and pick an **always** option in the ask prompt — that writes the domain to the project file for you.
+
+### How do I allow writes to another folder?
+Add the folder to `filesystem.allowWrite`. Relative paths (`.`, `/tmp`) resolve from the project root.
+
+### Why was my tool call or command blocked?
+Run `/security` to see the active Layer 2 policy and the last 10 audit events; run `/sandbox` for the Layer 1 bash sandbox config. The audit log at `~/.pi/agent/audit.log` records the rule that matched (`reason`).
+
+### How do I turn the sandbox off temporarily?
+`pi --yolo` (alias `--no-sandbox`) for a single run, or `/permission-mode` → **YOLO** mid-session. YOLO is persisted like the other modes; pick Default or Advanced Secure to re-enable the layers.
+
+### Why does `.env` (or my SSH key) get flagged while other files do not?
+`.env` and `.env.*` are in the shipped `askRead` list, so reads **prompt** by default. The absolute-deny tier (`~/.ssh`, `~/.gnupg`, `~/.aws`, `*.pem`, `*.key`, pi's `auth.json`) always needs a two-step confirmation. Add paths to `denyRead` to hard-deny, or to `askRead` to prompt instead of block.
+
+### How is this different from just using `--yolo`?
+`--yolo` removes every guard for one run. `auto-permission-system` is the guard: it decides what runs, prompts when it is unsure, and records the decision. Use `/permission-mode` to switch between **Default** (rules only), **Advanced Secure** (rules + secret/credential detection, recommended) and **YOLO**.
+
+### Does it work on Windows?
+No. Layer 1 needs `sandbox-exec` (macOS, built in) or `bubblewrap` + `socat` (Linux). Layer 2 is platform-independent.
+
+### Where do the prompts persist my answers?
+Project answers go to `<cwd>/.pi/sandbox.json`; global answers go to `~/.pi/agent/extensions/sandbox.json`. Session-only grants live in memory and are never written to disk.
+
+## Development
+
+```bash
+git clone https://github.com/Navin009/auto-permission-system
+cd auto-permission-system
+npm install          # installs typescript for typecheck
+npm run typecheck    # type-checks against pi's bundled .d.ts files
+pi -e .              # load extension for the current session only
+```
+
+## Releasing
+
+Releases are fully automated with [semantic-release](https://semantic-release.gitbook.io/), driven by [Conventional Commits](https://www.conventionalcommits.org/) on `main`:
+
+- `fix: ...` → patch release
+- `feat: ...` → minor release
+- `feat!: ...` or a `BREAKING CHANGE:` footer → major release
+- `chore:`, `docs:`, `refactor:`, `test:`, `ci:` etc. → no release by themselves
+
+Commit messages on pull requests are checked by `commitlint` (`.github/workflows/commitlint.yml`). On every push to `main`, `.github/workflows/release.yml` runs `semantic-release`, which:
+
+1. Determines the next version from commits since the last release.
+2. Generates release notes and prepends them to `CHANGELOG.md`.
+3. Creates the `vX.Y.Z` git tag and GitHub release.
+4. Bumps `package.json` and commits `CHANGELOG.md`/`package.json` back to `main` (`chore(release): ... [skip ci]`).
+5. Publishes to npm (`npm publish --provenance`) — **only when the repository variable `NPM_PUBLISH` is `true`**.
+
+npm publishing is opt-in (`npmPublish: process.env.NPM_PUBLISH === 'true'` in `.releaserc.cjs`, wired through `.github/workflows/release.yml`), and the GitHub plugin runs before the npm plugin so a failing registry publish can never stop the GitHub Release from being created.
+
+See **[PUBLISHING.md](https://github.com/Navin009/auto-permission-system/blob/main/PUBLISHING.md)** for the full first-publish and npm Trusted Publishing checklist, and for how the package becomes searchable on the [Pi package gallery](https://pi.dev/packages). Nothing is needed locally beyond writing conventional commit messages — just merge to `main`.
+
+## License
+
+MIT