pi-better-sandbox 0.1.0

package/files.ts

@@ -0,0 +1,211 @@
+/**
+ * Foreground file-mutation confinement for the built-in `write` and `edit`
+ * tools.
+ *
+ * These two tools never spawn a child process — they call `fs` in Pi's own
+ * process — so the argv wrapping that confines `bash` cannot reach them. The
+ * enforcement here is therefore an in-process containment check against the
+ * same compiled write policy the kernel backends are built from, run on the
+ * absolute path Pi itself resolved.
+ *
+ * Placement is the whole point. Pi's built-in `write`/`edit` implementations
+ * take `WriteOperations`/`EditOperations` and call them *inside*
+ * `withFileMutationQueue(absolutePath, ...)`, after their own abort checks. By
+ * replacing only those operations, every check below runs inside Pi's per-file
+ * mutation queue and inside its cancellation window, and no denied mutation can
+ * be re-targeted between the check and the syscall: the guard and the `fs` call
+ * are the same operation.
+ *
+ * Reads stay unrestricted. `edit`'s `readFile` is delegated untouched; only the
+ * operations that can change the host filesystem are guarded.
+ */
+
+import { constants } from "node:fs";
+import {
+    access as fsAccess,
+    mkdir as fsMkdir,
+    readFile as fsReadFile,
+    writeFile as fsWriteFile,
+} from "node:fs/promises";
+
+import type { EditOperations, WriteOperations } from "@earendil-works/pi-coding-agent";
+
+import {
+    type CompiledSandboxWritePolicy,
+    compileWritePolicy,
+    evaluateWriteAccess,
+    type SandboxSeams,
+    type SandboxWritePolicy,
+    type WriteAccessDecision,
+} from "./shared-sandbox-core.ts";
+import type { ForegroundSandboxController } from "./state.ts";
+
+/** The refusing half of a write decision. */
+export type DeniedWriteAccess = Extract<WriteAccessDecision, { allowed: false }>;
+
+/** What the refused operation would have done, so the message names it. */
+export type MutationKind = "write" | "directory";
+
+/**
+ * Thrown instead of mutating a path the foreground sandbox does not allow.
+ *
+ * It surfaces through Pi's normal tool-error path — the built-in `write` and
+ * `edit` implementations already let operation errors propagate — so the model
+ * sees an ordinary failed tool call and the host filesystem is untouched.
+ */
+export class ForegroundSandboxWriteDeniedError extends Error {
+    readonly decision: DeniedWriteAccess;
+    /** The compiled policy that refused the write. */
+    readonly policy: CompiledSandboxWritePolicy;
+
+    constructor(
+        decision: DeniedWriteAccess,
+        policy: CompiledSandboxWritePolicy,
+        kind: MutationKind = "write",
+    ) {
+        super(explainDenial(decision, policy, kind));
+        this.name = "ForegroundSandboxWriteDeniedError";
+        this.decision = decision;
+        this.policy = policy;
+    }
+}
+
+function explainDenial(
+    decision: DeniedWriteAccess,
+    policy: CompiledSandboxWritePolicy,
+    kind: MutationKind,
+): string {
+    const attempt = kind === "directory" ? "create directory" : "write";
+    const refused = `Foreground sandbox refused to ${attempt} ${decision.path}; nothing was changed on disk.`;
+    return decision.reason === "outside-writable-root"
+        ? `${refused} Writes are confined to ${policy.writableRoot}.`
+        : `${refused} ${decision.deniedBy} is a write-denied path.`;
+}
+
+/**
+ * Assert one mutation target is writable under the current effective policy.
+ *
+ * Throws `ForegroundSandboxBlockedError` when the sandbox is enabled but cannot
+ * be applied (no backend, unsafe launch root, no session yet), and
+ * `ForegroundSandboxWriteDeniedError` when the canonical target is outside the
+ * writable root or write-denied. Returns silently when a human explicitly
+ * disabled the sandbox, which is the only path to an unconfined mutation.
+ */
+export type ForegroundWriteGuard = (absolutePath: string, kind?: MutationKind) => string;
+
+/** Identity of a compiled policy, so it is recompiled on change and not per mutation. */
+function policyKey(policy: SandboxWritePolicy): string {
+    return JSON.stringify([policy.writableRoot, policy.denyWrite ?? [], policy.home]);
+}
+
+/**
+ * Build the guard the file operations run before every mutation.
+ *
+ * The launch decision is taken per mutation, so `/sandbox on` and `/sandbox off`
+ * take effect for mutations attempted after the toggle. The policy behind it is
+ * compiled once and reused until the policy itself changes.
+ *
+ * The canonical path comes back so callers mutate the path that was checked
+ * rather than the one they were handed. A path-based check can otherwise be
+ * raced by a symlink swapped in after the check and before the syscall; writing
+ * the already-resolved path removes that final-component race.
+ */
+export function createForegroundWriteGuard(
+    controller: ForegroundSandboxController,
+    seams: SandboxSeams = {},
+): ForegroundWriteGuard {
+    let compiledKey: string | undefined;
+    let compiled: CompiledSandboxWritePolicy | undefined;
+
+    return function assertWritable(absolutePath: string, kind: MutationKind = "write"): string {
+        // Throws when the sandbox is enabled but unusable: an unavailable or
+        // failed backend blocks the mutation instead of quietly delegating.
+        const plan = controller.requireLaunchPlan();
+        if (!plan.confined) return absolutePath;
+
+        const key = policyKey(plan.policy);
+        if (compiled === undefined || key !== compiledKey) {
+            compiled = compileWritePolicy(plan.policy, seams);
+            compiledKey = key;
+        }
+
+        const decision = evaluateWriteAccess(absolutePath, compiled, seams);
+        if (!decision.allowed) {
+            throw new ForegroundSandboxWriteDeniedError(decision, compiled, kind);
+        }
+        return decision.path;
+    };
+}
+
+/** Pi's own default local backends, which the guarded operations delegate to. */
+const localWriteOperations: WriteOperations = {
+    writeFile: (path, content) => fsWriteFile(path, content, "utf-8"),
+    mkdir: (dir) => fsMkdir(dir, { recursive: true }).then(() => {}),
+};
+
+const localEditOperations: EditOperations = {
+    readFile: (path) => fsReadFile(path),
+    writeFile: (path, content) => fsWriteFile(path, content, "utf-8"),
+    access: (path) => fsAccess(path, constants.R_OK | constants.W_OK),
+};
+
+export type SandboxedWriteOperationsOptions = SandboxSeams & {
+    /** The local filesystem backend to delegate allowed mutations to. */
+    localOperations?: WriteOperations;
+};
+
+export type SandboxedEditOperationsOptions = SandboxSeams & {
+    /** The local filesystem backend to delegate allowed mutations to. */
+    localOperations?: EditOperations;
+};
+
+/**
+ * Write operations that confine every mutation they perform.
+ *
+ * `mkdir` is guarded as well as `writeFile`: the built-in `write` tool creates
+ * parent directories before writing, so an unguarded `mkdir` would materialise
+ * host directories outside the project root before the write itself was
+ * refused.
+ */
+export function createSandboxedWriteOperations(
+    controller: ForegroundSandboxController,
+    options: SandboxedWriteOperationsOptions = {},
+): WriteOperations {
+    const assertWritable = createForegroundWriteGuard(controller, options);
+    const local = options.localOperations ?? localWriteOperations;
+
+    return {
+        async mkdir(dir) {
+            return local.mkdir(assertWritable(dir, "directory"));
+        },
+        async writeFile(absolutePath, content) {
+            return local.writeFile(assertWritable(absolutePath), content);
+        },
+    };
+}
+
+/**
+ * Edit operations that confine every mutation they perform.
+ *
+ * `access` is Pi's own pre-flight gate for `edit`, so guarding it refuses a
+ * denied target before the file is read or a diff is computed; `writeFile` is
+ * guarded because it is the mutation. `readFile` is delegated untouched — this
+ * sandbox never restricts reads.
+ */
+export function createSandboxedEditOperations(
+    controller: ForegroundSandboxController,
+    options: SandboxedEditOperationsOptions = {},
+): EditOperations {
+    const assertWritable = createForegroundWriteGuard(controller, options);
+    const local = options.localOperations ?? localEditOperations;
+
+    return {
+        readFile: (absolutePath) => local.readFile(absolutePath),
+        async access(absolutePath) {
+            return local.access(assertWritable(absolutePath));
+        },
+        async writeFile(absolutePath, content) {
+            return local.writeFile(assertWritable(absolutePath), content);
+        },
+    };
+}

package/index.ts

@@ -0,0 +1,233 @@
+/**
+ * pi-better-sandbox - a default-on write sandbox for foreground tool execution.
+ *
+ * Installing this package loads an extension; it ships no launcher, so users
+ * keep starting Pi with plain `pi`. While enabled, the built-in `bash` tool and
+ * user-entered `!` / `!!` commands run under macOS Seatbelt or Linux Bubblewrap
+ * with one writable root — the canonical directory Pi was launched from — and
+ * the packaged write-denied paths carved back out of it. The built-in `write`
+ * and `edit` tools mutate files in Pi's own process rather than in a child, so
+ * no argv wrapping can reach them; they are held to the same policy by an
+ * in-process containment check instead. Reads and network are untouched.
+ *
+ * This is a tool-execution sandbox. Pi's own process, `pi.exec` calls, and
+ * unrelated third-party extension code are not confined by it.
+ */
+
+import {
+    createBashToolDefinition,
+    createEditToolDefinition,
+    createWriteToolDefinition,
+    SettingsManager,
+    type ExtensionAPI,
+    type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+import {
+    createSandboxCommandHandler,
+    SANDBOX_COMMAND_DESCRIPTION,
+    SANDBOX_COMMAND_NAME,
+    sandboxArgumentCompletions,
+} from "./commands.ts";
+import { DenyRuleManager } from "./deny-rules.ts";
+import {
+    FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL,
+    publishForegroundSandboxPolicy,
+} from "./events.ts";
+import {
+    createSandboxedEditOperations,
+    createSandboxedWriteOperations,
+} from "./files.ts";
+import { createSandboxedBashOperations } from "./shell.ts";
+import { footerTone, formatFooterStatus } from "./status.ts";
+import { ForegroundSandboxController, type ForegroundSandboxStatus } from "./state.ts";
+
+const FOOTER_KEY = "sandbox";
+
+export default function piBetterSandbox(pi: ExtensionAPI): void {
+    const controller = new ForegroundSandboxController();
+
+    // Pi's shell setting is only readable once a session directory is known, so
+    // it is resolved lazily and re-read on every session start.
+    let shellPath: string | undefined;
+    const operations = createSandboxedBashOperations(controller, { shellPath: () => shellPath });
+
+    // Overriding the built-in bash tool by name. Only `operations` changes:
+    // Pi's own definition still owns the schema, streaming, timeout,
+    // cancellation, truncation, session environment, result details, and both
+    // renderers, so every bash contract stays the built-in one.
+    pi.registerTool(createBashToolDefinition(process.cwd(), { operations }));
+
+    // The same backend for user-entered ! and !! commands.
+    pi.on("user_bash", () => ({ operations }));
+
+    // Overriding the built-in write and edit tools the same way: only their
+    // file operations change, so Pi's own definitions keep the parameter
+    // schemas, prompt guidance, call rendering, write previews, edit diffs,
+    // result details, file-mutation queue, and cancellation checks. The guarded
+    // operations run inside that queue, which is where the enforcement belongs.
+    const writeOperations = createSandboxedWriteOperations(controller);
+    const editOperations = createSandboxedEditOperations(controller);
+
+    // `cwd` is what these tools resolve a relative `path` against, so it has to
+    // be the directory Pi itself resolves against. Registration is re-run when
+    // a session reports a different cwd (`pi --cwd ...`), which Pi supports and
+    // refreshes in the same session.
+    let fileToolCwd: string | undefined;
+    const registerFileTools = (cwd: string): void => {
+        if (fileToolCwd === cwd) return;
+        fileToolCwd = cwd;
+        pi.registerTool(createWriteToolDefinition(cwd, { operations: writeOperations }));
+        pi.registerTool(createEditToolDefinition(cwd, { operations: editOperations }));
+    };
+    registerFileTools(process.cwd());
+
+    let paintFooter: ((status: ForegroundSandboxStatus) => void) | undefined;
+
+    const announce = (status: ForegroundSandboxStatus): void => {
+        publishForegroundSandboxPolicy(pi.events, status);
+        paintFooter?.(status);
+    };
+
+    // A consumer that loaded after the last publication can ask for the current
+    // policy instead of waiting for the next change.
+    pi.events.on(FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL, () => {
+        publishForegroundSandboxPolicy(pi.events, controller.status());
+    });
+
+    // The one validation and persistence path for write-deny rules, shared by
+    // `/sandbox deny ...` and the `/sandbox rules` page.
+    const denyRules = new DenyRuleManager({ controller, onStateChange: announce });
+
+    pi.on("session_start", (_event, ctx: ExtensionContext) => {
+        shellPath = resolveShellPath(ctx.cwd);
+        registerFileTools(ctx.cwd);
+        paintFooter = (status) => {
+            ctx.ui.setStatus(
+                FOOTER_KEY,
+                formatFooterStatus(status, (tone, text) => ctx.ui.theme.fg(tone, text)),
+            );
+        };
+
+        // Every session start re-captures the project root and re-arms
+        // protection, so an earlier /sandbox off never survives into a new,
+        // resumed, forked, or reloaded session.
+        controller.beginSession(ctx.cwd);
+
+        // Then the rules are re-read and re-resolved, because the same global
+        // template set means different absolute paths in a different project.
+        // Loading is what announces the session's first policy, so consumers and
+        // the footer never see the pre-rule state.
+        const report = denyRules.load();
+        const status = report.status;
+
+        if (report.overrideProblem !== undefined) {
+            ctx.ui.notify(report.overrideProblem, "warning");
+        }
+        for (const rule of report.inert) {
+            ctx.ui.notify(
+                `Write-deny rule ${rule.template} is not applied in this project: ${rule.reason}`,
+                "warning",
+            );
+        }
+        if (status.state !== "enabled") {
+            ctx.ui.notify(
+                `Foreground sandbox ${status.state}: ${status.reason}`,
+                status.state === "disabled" ? "info" : "warning",
+            );
+        }
+    });
+
+    pi.on("session_shutdown", () => {
+        controller.dispose();
+    });
+
+    pi.registerCommand(SANDBOX_COMMAND_NAME, {
+        description: SANDBOX_COMMAND_DESCRIPTION,
+        getArgumentCompletions: sandboxArgumentCompletions,
+        handler: createSandboxCommandHandler({ controller, denyRules, onStateChange: announce }),
+    });
+}
+
+function resolveShellPath(cwd: string): string | undefined {
+    try {
+        return SettingsManager.create(cwd).getShellPath();
+    } catch {
+        // A malformed or unreadable settings file must not decide whether the
+        // sandbox runs; fall back to Pi's own shell resolution.
+        return undefined;
+    }
+}
+
+export { footerTone, formatFooterStatus, formatSandboxReport } from "./status.ts";
+export {
+    FOREGROUND_SANDBOX_REMEDY,
+    ForegroundSandboxBlockedError,
+    ForegroundSandboxController,
+    type ForegroundSandboxLaunchPlan,
+    type ForegroundSandboxSeams,
+    type ForegroundSandboxState,
+    type ForegroundSandboxStatus,
+} from "./state.ts";
+export {
+    FOREGROUND_SANDBOX_POLICY_CHANNEL,
+    FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL,
+    type ForegroundSandboxPolicyEvent,
+    freezePolicy,
+    publishForegroundSandboxPolicy,
+    requestForegroundSandboxPolicy,
+    subscribeForegroundSandboxPolicy,
+} from "./events.ts";
+export {
+    clearDenyRuleOverride,
+    DENY_RULES_FILE_NAME,
+    DENY_RULES_FORMAT_VERSION,
+    type DenyRule,
+    DenyRuleError,
+    type DenyRuleErrorKind,
+    DenyRuleManager,
+    type DenyRuleManagerDeps,
+    type DenyRuleReport,
+    denyRuleOverridePath,
+    type DenyRuleSeams,
+    type DenyRuleStoreSeams,
+    describeDenyRules,
+    formatDenyRuleReport,
+    type InertDenyRule,
+    normalizeDenyRuleTemplate,
+    partitionDenyRules,
+    planDenyRuleAddition,
+    planDenyRuleRemoval,
+    readDenyRuleOverride,
+    writeDenyRuleOverride,
+} from "./deny-rules.ts";
+export { openSandboxRulesPage, RULES_PAGE_NO_UI_REJECTION } from "./rules-page.ts";
+export {
+    describeUnsafeProjectRoot,
+    PACKAGED_DENY_WRITE_TEMPLATES,
+    resolveDenyWriteTemplate,
+    resolveDenyWriteTemplates,
+    unsafeProjectRoots,
+} from "./policy.ts";
+export {
+    createForegroundWriteGuard,
+    createSandboxedEditOperations,
+    createSandboxedWriteOperations,
+    type DeniedWriteAccess,
+    ForegroundSandboxWriteDeniedError,
+    type ForegroundWriteGuard,
+    type MutationKind,
+    type SandboxedEditOperationsOptions,
+    type SandboxedWriteOperationsOptions,
+} from "./files.ts";
+export {
+    buildSandboxedShellCommand,
+    createSandboxedBashOperations,
+    quoteForPosixShell,
+} from "./shell.ts";
+export {
+    createSandboxCommandHandler,
+    SANDBOX_COMMAND_DESCRIPTION,
+    SANDBOX_COMMAND_NAME,
+    sandboxArgumentCompletions,
+} from "./commands.ts";

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pi-better-sandbox",
+  "version": "0.1.0",
+  "description": "Pi extension that confines foreground shell execution to the project directory with a kernel-enforced write sandbox.",
+  "license": "MIT",
+  "type": "module",
+  "main": "index.ts",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "sandbox",
+    "seatbelt",
+    "bubblewrap"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1aboveio/pi-better-harness.git",
+    "directory": "packages/pi-better-sandbox"
+  },
+  "bugs": {
+    "url": "https://github.com/1aboveio/pi-better-harness/issues"
+  },
+  "homepage": "https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-sandbox#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "pretypecheck": "node ../../scripts/sync-shared-sandbox-core.mjs",
+    "pretest": "node ../../scripts/sync-shared-sandbox-core.mjs",
+    "prepack": "node ../../scripts/sync-shared-sandbox-core.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts",
+    "verify": "npm run typecheck && npm test"
+  },
+  "files": [
+    "*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.82.0",
+    "@earendil-works/pi-tui": "^0.82.0",
+    "@types/node": "^25.0.0",
+    "tsx": "^4.22.3",
+    "typebox": "^1.1.39",
+    "typescript": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/policy.ts

@@ -0,0 +1,102 @@
+/**
+ * Foreground write policy: which directory is writable, and which concrete
+ * paths stay non-writable inside it.
+ *
+ * The mechanism (backends, profiles, argv wrapping) lives in `sandbox-core`.
+ * This module owns the product decisions layered on top of it: the packaged
+ * deny defaults, how a rule template resolves against a project, and which
+ * launch directories are too broad to confine usefully.
+ */
+
+import { homedir } from "node:os";
+import { isAbsolute, resolve, sep } from "node:path";
+
+import { canonicalizePath, type SandboxSeams } from "./shared-sandbox-core.ts";
+
+/**
+ * Paths that stay non-writable inside every project root, shipped in source.
+ *
+ * Entries are `PROJECT_ROOT`-relative templates, so the same relative path is
+ * denied in every project. Persisting and editing this set is not this module's
+ * job — it hands out the packaged defaults and resolves whatever set it is
+ * given.
+ */
+export const PACKAGED_DENY_WRITE_TEMPLATES: readonly string[] = Object.freeze([
+    ".git/hooks",
+    ".env",
+    ".env.local",
+]);
+
+/** Seams for resolving a policy without touching the real home or filesystem. */
+export type PolicySeams = SandboxSeams & {
+    /** Defaults to `os.homedir()`. */
+    home?: () => string;
+};
+
+function homeOf(seams: PolicySeams): string {
+    return (seams.home ?? homedir)();
+}
+
+/**
+ * Resolve one deny-write template against a project root.
+ *
+ * `~` resolves against the user's home, an absolute entry is taken as written,
+ * and everything else resolves against `PROJECT_ROOT`. The result is
+ * canonicalized so a symlinked alias cannot slip past the same rule.
+ */
+export function resolveDenyWriteTemplate(
+    template: string,
+    projectRoot: string,
+    seams: PolicySeams = {},
+): string {
+    const trimmed = template.trim();
+    if (trimmed === "") throw new Error("A write-denied path may not be empty.");
+
+    const home = homeOf(seams);
+    let expanded = trimmed;
+    if (trimmed === "~") expanded = home;
+    else if (trimmed.startsWith(`~${sep}`)) expanded = resolve(home, trimmed.slice(2));
+
+    const absolute = isAbsolute(expanded) ? expanded : resolve(projectRoot, expanded);
+    return canonicalizePath(absolute, seams);
+}
+
+/** Resolve a whole deny-write template set against a project root. */
+export function resolveDenyWriteTemplates(
+    templates: readonly string[],
+    projectRoot: string,
+    seams: PolicySeams = {},
+): string[] {
+    return [
+        ...new Set(templates.map((template) => resolveDenyWriteTemplate(template, projectRoot, seams))),
+    ].sort();
+}
+
+/**
+ * Launch directories that must never become the writable root.
+ *
+ * Confining writes to `/` or to the whole home directory would present the
+ * sandbox as active while protecting nothing, so those launches fail closed
+ * instead.
+ */
+export function unsafeProjectRoots(seams: PolicySeams = {}): string[] {
+    const roots = [resolve(sep), homeOf(seams)];
+    return [...new Set(roots.map((root) => canonicalizePath(root, seams)))];
+}
+
+/**
+ * Explain why a canonical project root is too broad to confine, or return
+ * `undefined` when it is a usable writable root.
+ */
+export function describeUnsafeProjectRoot(
+    projectRoot: string,
+    seams: PolicySeams = {},
+): string | undefined {
+    if (!unsafeProjectRoots(seams).includes(projectRoot)) return undefined;
+    return [
+        `The sandbox will not treat ${projectRoot} as a writable project root:`,
+        "it is broad enough that confining writes to it would protect nothing.",
+        "Relaunch pi from the directory you are actually working in, or disable",
+        "the foreground sandbox on purpose with /sandbox off.",
+    ].join(" ");
+}