universal-opencode-sandbox 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Jacobs
+
+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,113 @@
-# Temporary Holding Version
+# universal-opencode-sandbox
 
-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.
+A [OpenCode](https://opencode.ai) 2.x plugin that runs every agent shell command inside an
+OS-level sandbox enforced by [Microsoft MXC](https://github.com/microsoft/mxc). One
+plugin, all three desktop platforms:
+
+| Platform | Mechanism | Requirement |
+|----------|-----------|-------------|
+| macOS 15+ (Apple Silicon) | Seatbelt | none beyond this plugin |
+| Linux | bubblewrap | `bwrap` >= 0.5.0 installed, unprivileged user namespaces |
+| Windows 11 | ProcessContainer | native process-container support (probed automatically) |
+
+Commands keep OpenCode's own streaming output, timeout and background behavior: the
+plugin swaps the command string for an invocation of the bundled MXC executor with a
+per-call policy file, so the sandboxed process is spawned by the executor while the
+shell tool watches it like any other command.
+
+## Install
+
+Requires OpenCode 2.x (the `@opencode/plugin` 2.x contract).
+
+```jsonc title="opencode.jsonc"
+{
+  "plugins": ["universal-opencode-sandbox"],
+}
+```
+
+The sandbox is on by default once the plugin is installed, in its strictest useful
+mode: the workspace is writable (and the system temp directory), everything else is
+read-only, the network is denied, and a command the sandbox cannot run is blocked
+rather than run unconfined.
+
+## Configure
+
+Policy is read only from places a sandboxed command cannot reach, so a repository
+can never enable, loosen or tighten your sandbox. OpenCode plugin options are ignored
+on purpose: they can be set from a repository's own config.
+
+`~/.config/universal-opencode-sandbox/config.json` (respecting `XDG_CONFIG_HOME`):
+
+```jsonc
+{
+  "enabled": true,
+  // "enforce" (default) blocks a command when the sandbox cannot run it;
+  // "permissive" runs it unsandboxed with a warning.
+  "mode": "enforce",
+  "filesystem": {
+    // "read-only" (default) denies every write; "workspace-write" allows writes to
+    // the workspace, the temp directory, and writable_roots.
+    "mode": "workspace-write",
+    "writable_roots": [],
+    // Paths the sandboxed command can neither read nor write, e.g. credentials.
+    "denied_paths": ["~/.ssh", "~/.aws"]
+  },
+  // "deny" (default) blocks all network access for sandboxed commands.
+  "network": "deny",
+  // What happens when a tool call asks to skip the sandbox (shell input
+  // "sandbox: false"): "deny" (default) blocks it, "allow" runs it unsandboxed.
+  "unsandboxed": "deny",
+  // Per-project overrides, keyed by the workspace's absolute path. Every field is
+  // optional and can only make the policy stricter, never looser.
+  "projects": {
+    "/home/me/src/scratch": { "network": "allow" }
+  }
+}
+```
+
+`UNIVERSAL_SANDBOX_CONFIG` (a JSON string) tightens the same fields per invocation.
+
+## What is enforced
+
+- **Filesystem**: in `workspace-write` mode, writes are allowed in the workspace and
+  the temp directory only. In `read-only` mode no write is allowed at all.
+- **Protected paths**: `opencode.json`, `opencode.jsonc`, `.opencode`, `.claude` and
+  `.agents` in the workspace can never be written or planted by a sandboxed command,
+  so a command cannot install a config or plugin that would run unsandboxed after a
+  restart. Per platform: macOS enforces this for existing and not-yet-existing paths;
+  Linux enforces it for paths that exist (bwrap cannot bind a missing read-only
+  source, and the deny fallback has an upstream bug, microsoft/mxc#1780); Windows
+  denies the paths outright.
+- **Network**: denied by default. On Windows the backend currently cannot enforce a
+  network-deny policy (verified against Windows 11 and MXC 1.1.0), so with
+  `network: "deny"` (the default) sandboxed commands fail closed there with an
+  explanation; set `network: "allow"` for filesystem-only containment on Windows.
+- **Fail-closed**: an unsupported platform, a missing backend (install `bubblewrap` on
+  Linux), or a missing executor blocks the command in `enforce` mode instead of
+  running it unconfined. `mode: "permissive"` trades that guarantee for convenience.
+
+## Known limitations
+
+- With the sandbox enabled, OpenCode's per-command shell permission rules see the
+  sandbox wrapper invocation, not the inner command. The OS sandbox is the real
+  boundary here; command-pattern rules are weaker than it anyway (and trivially
+  bypassed by an adversarial agent). If you rely on `deny` rules for specific
+  commands, prefer this plugin's `denied_paths` and filesystem policy.
+- Intel macOS is unsupported: the MXC npm package ships no darwin-x64 runtime yet.
+- MXC release builds on Windows emit required Microsoft diagnostic telemetry; see the
+  [MXC documentation](https://github.com/microsoft/mxc).
+- MXC's process streams do not deliver under Bun (microsoft/mxc#1782). This plugin is
+  unaffected: the executor is a native binary whose output the shell tool captures.
+
+## Verification
+
+Tested against the real backends on macOS (Seatbelt), Debian 13 with bubblewrap 0.12
+and Windows 11 (ProcessContainer): output and exit codes stream through, writes inside
+the workspace succeed, writes outside are denied, protected config files cannot be
+planted, and network egress is blocked (except the documented Windows gap). Also
+verified end to end inside a real OpenCode 2.2.7 session: an agent's shell command
+writes inside the workspace and is denied outside it.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from "@opencode/plugin";
+declare const _default: Plugin.Plugin;
+export default _default;

package/dist/index.js

@@ -0,0 +1,274 @@
+// src/index.ts
+import fs3 from "node:fs";
+import os3 from "node:os";
+import path3 from "node:path";
+import { Plugin } from "@opencode/plugin";
+
+// src/policy.ts
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+var configDirectory = () => path.join(process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config"), "universal-opencode-sandbox");
+var configPath = () => path.join(configDirectory(), "config.json");
+function resolvePolicy(workspace, environment = process.env, globalFile = configPath()) {
+  let merged = { writableRoots: [], deniedPaths: [] };
+  const global = readConfig(globalFile);
+  if (global)
+    merged = tighten(merged, global);
+  const project = global?.projects?.[workspace];
+  if (project)
+    merged = tighten(merged, project);
+  const injected = environment.UNIVERSAL_SANDBOX_CONFIG;
+  if (injected) {
+    try {
+      merged = tighten(merged, JSON.parse(injected));
+    } catch {}
+  }
+  return {
+    enabled: merged.enabled ?? true,
+    mode: merged.mode ?? "enforce",
+    filesystem: {
+      mode: merged.filesystemMode ?? "read-only",
+      writableRoots: [...new Set(merged.writableRoots)],
+      deniedPaths: [...new Set(merged.deniedPaths)]
+    },
+    network: merged.network ?? "deny",
+    unsandboxed: merged.unsandboxed ?? "deny"
+  };
+}
+function readConfig(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return;
+  }
+}
+function tighten(merged, raw) {
+  if (Array.isArray(raw.filesystem?.writable_roots)) {
+    for (const root of raw.filesystem.writable_roots)
+      if (typeof root === "string")
+        merged.writableRoots.push(root);
+  }
+  if (Array.isArray(raw.filesystem?.denied_paths)) {
+    for (const item of raw.filesystem.denied_paths)
+      if (typeof item === "string")
+        merged.deniedPaths.push(item);
+  }
+  return {
+    enabled: raw.enabled === undefined ? merged.enabled : raw.enabled === false ? false : merged.enabled === false ? false : true,
+    mode: strictest(merged.mode, raw.mode, "enforce", "permissive"),
+    filesystemMode: strictest(merged.filesystemMode, raw.filesystem?.mode, "read-only", "workspace-write"),
+    network: strictest(merged.network, raw.network, "deny", "allow"),
+    unsandboxed: strictest(merged.unsandboxed, raw.unsandboxed, "deny", "allow"),
+    writableRoots: merged.writableRoots,
+    deniedPaths: merged.deniedPaths
+  };
+}
+function strictest(current, incoming, strict, loose) {
+  if (current === strict || incoming === strict)
+    return strict;
+  if (incoming === loose)
+    return loose;
+  return current;
+}
+function expandHome(item, home = os.homedir()) {
+  return item === "~" ? home : item.startsWith("~/") ? path.join(home, item.slice(2)) : item;
+}
+
+// src/wire.ts
+import { randomBytes } from "node:crypto";
+import fs2 from "node:fs";
+import os2 from "node:os";
+import path2 from "node:path";
+import { fileURLToPath } from "node:url";
+var PROTECTED = ["opencode.json", "opencode.jsonc", ".opencode", ".claude", ".agents"];
+function wireRequest(input, platform = process.platform) {
+  const workspace = real(input.workspace);
+  const cwd = real(input.cwd);
+  const writable = [
+    workspace,
+    ...(input.tmpRoots ?? [os2.tmpdir()]).map(real),
+    ...input.policy.filesystem.writableRoots.map((root) => real(expandHome(root)))
+  ];
+  const protectedPaths = PROTECTED.map((item) => path2.join(workspace, item));
+  const deniedPaths = input.policy.filesystem.deniedPaths.map((item) => real(expandHome(item)));
+  let filesystem;
+  if (input.policy.filesystem.mode !== "workspace-write") {
+    filesystem = { readwritePaths: [], readonlyPaths: [input.workspace], deniedPaths: existing(deniedPaths, platform) };
+  } else if (platform === "win32") {
+    filesystem = { readwritePaths: writable, readonlyPaths: [], deniedPaths: [...protectedPaths, ...deniedPaths] };
+  } else if (platform === "linux") {
+    filesystem = {
+      readwritePaths: writable,
+      readonlyPaths: protectedPaths.filter((item) => exists(item)),
+      deniedPaths: existing(deniedPaths, platform)
+    };
+  } else {
+    filesystem = { readwritePaths: writable, readonlyPaths: protectedPaths, deniedPaths };
+  }
+  const request = {
+    version: "1.0.0",
+    containerId: randomBytes(16).toString("hex"),
+    containment: platform === "darwin" ? "seatbelt" : platform === "win32" ? "processcontainer" : "bubblewrap",
+    ...platform === "darwin" ? { seatbelt: {} } : {},
+    ...platform === "win32" ? {
+      processContainer: {
+        capabilities: input.policy.network === "allow" ? ["internetClient"] : [],
+        ui: { isolation: "container", desktopSystemControl: false, systemSettings: "none", ime: false },
+        filesystem: undefined,
+        network: undefined
+      }
+    } : {},
+    lifecycle: { destroyOnExit: true, preservePolicy: false },
+    process: {
+      commandLine: input.command,
+      timeout: input.timeout,
+      cwd,
+      inheritDefaultEnv: true
+    },
+    filesystem,
+    ...input.policy.network === "deny" ? { network: { egress: { default: "deny" }, ingress: { default: "deny", hostLoopback: "deny" } } } : { network: { egress: { default: "allow" } } }
+  };
+  return request;
+}
+function exists(item) {
+  try {
+    fs2.statSync(item);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function real(item) {
+  try {
+    return fs2.realpathSync(item);
+  } catch {
+    return item;
+  }
+}
+function existing(paths, platform) {
+  return platform === "linux" ? paths.filter(exists) : paths;
+}
+function unsupportedNetwork(platform, network) {
+  return platform === "win32" && network === "deny";
+}
+function resolveExecutor(platform = process.platform, arch = process.arch) {
+  const name = platform === "darwin" ? "mxc-exec-mac" : platform === "win32" ? "wxc-exec.exe" : platform === "linux" ? "lxc-exec" : undefined;
+  if (!name)
+    return `no MXC executor exists for ${platform}`;
+  const sdk = path2.dirname(fileURLToPath(import.meta.resolve("@microsoft/mxc-sdk/package.json")));
+  const executor = path2.join(sdk, "bin", arch === "arm64" ? "arm64" : "x64", name);
+  if (!fs2.existsSync(executor)) {
+    return platform === "darwin" && arch === "x64" ? "the installed @microsoft/mxc-sdk ships no Intel macOS executor yet" : `the MXC executor is missing from the @microsoft/mxc-sdk package: ${executor}`;
+  }
+  return executor;
+}
+function quote(value, platform = process.platform) {
+  if (platform === "win32")
+    return windowsArgument(value);
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function windowsArgument(value) {
+  if (!/[\s"]/.test(value))
+    return value;
+  let quoted = '"';
+  let backslashes = 0;
+  for (const character of value) {
+    if (character === "\\") {
+      backslashes++;
+      continue;
+    }
+    if (character === '"') {
+      quoted += "\\".repeat(backslashes * 2 + 1) + '"';
+      backslashes = 0;
+      continue;
+    }
+    quoted += "\\".repeat(backslashes) + character;
+    backslashes = 0;
+  }
+  return quoted + "\\".repeat(backslashes * 2) + '"';
+}
+
+// src/index.ts
+var BLOCKED = "universal-opencode-sandbox unavailable; command blocked";
+var src_default = Plugin.define({
+  id: "universal-opencode-sandbox",
+  setup: async (context) => {
+    const policy = resolvePolicy(context.location.directory);
+    if (!policy.enabled)
+      return;
+    const log = (level, message) => console[level](`[universal-opencode-sandbox] ${message}`);
+    const enforce = policy.mode === "enforce";
+    const executor = resolveExecutor();
+    const gap = unsupportedNetwork(process.platform, policy.network);
+    const unavailable = !fs3.existsSync(executor);
+    const reason = unavailable ? executor : gap ? 'the sandbox backend on Windows cannot enforce network denial yet; set network "allow" in the sandbox config to run sandboxed with filesystem containment only' : undefined;
+    if (reason !== undefined) {
+      log(enforce ? "error" : "warn", `${reason}; ${enforce ? 'shell commands will be blocked (set mode "permissive" to run unsandboxed)' : "commands will run without a sandbox"}`);
+    }
+    const inFlight = new Map;
+    const requestDirectory = path3.join(os3.tmpdir(), "universal-opencode-sandbox");
+    fs3.mkdirSync(requestDirectory, { recursive: true });
+    const cleanup = (callID) => {
+      const pending = inFlight.get(callID);
+      if (pending === undefined)
+        return;
+      inFlight.delete(callID);
+      fs3.rmSync(pending.file, { force: true });
+    };
+    const before = await context.tool.hook("execute.before", async (event) => {
+      if (event.tool !== "shell")
+        return;
+      const input = event.input ?? {};
+      const command = input.command;
+      if (typeof command !== "string" || command === "" || inFlight.has(event.id))
+        return;
+      if (input.sandbox === false) {
+        if (policy.unsandboxed === "deny") {
+          log("warn", `tool call asked to skip the sandbox; blocked (set unsandboxed "allow" to permit this)`);
+          throw new Error("universal-opencode-sandbox: running this command unsandboxed is not allowed");
+        }
+        return;
+      }
+      if (unavailable || gap) {
+        if (enforce)
+          throw new Error(`${BLOCKED}: ${reason}`);
+        return;
+      }
+      try {
+        const request = wireRequest({
+          command,
+          workspace: context.location.directory,
+          cwd: typeof input.workdir === "string" ? input.workdir : context.location.directory,
+          timeout: input.background === true ? 0 : input.timeout || 120000,
+          policy
+        });
+        const file = path3.join(requestDirectory, `${event.id}.json`);
+        fs3.writeFileSync(file, JSON.stringify(request), { mode: 384 });
+        inFlight.set(event.id, { file, command, sessionID: event.sessionID });
+        input.command = `${quote(executor)} ${quote(file)}`;
+      } catch (error) {
+        if (enforce)
+          throw new Error(`${BLOCKED}: ${error instanceof Error ? error.message : String(error)}`);
+        log("warn", `failed to wrap the command; running unsandboxed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    });
+    const after = await context.tool.hook("execute.after", async (event) => {
+      const pending = inFlight.get(event.id);
+      if (pending === undefined)
+        return;
+      if (event.input && typeof event.input === "object")
+        event.input.command = pending.command;
+      cleanup(event.id);
+    });
+    return async () => {
+      await before.dispose();
+      await after.dispose();
+      for (const callID of [...inFlight.keys()])
+        cleanup(callID);
+    };
+  }
+});
+export {
+  src_default as default
+};

package/dist/policy.d.ts

@@ -0,0 +1,22 @@
+export interface Policy {
+    readonly enabled: boolean;
+    /** "enforce" blocks a command when the sandbox cannot run it; "permissive" runs it unsandboxed with a warning. */
+    readonly mode: "enforce" | "permissive";
+    readonly filesystem: {
+        readonly mode: "read-only" | "workspace-write";
+        readonly writableRoots: string[];
+        /** Paths the sandboxed command can neither read nor write, resolved against the home directory. */
+        readonly deniedPaths: string[];
+    };
+    readonly network: "deny" | "allow";
+    /** What happens when a tool call asks to skip the sandbox (shell input "sandbox: false"). */
+    readonly unsandboxed: "deny" | "allow";
+}
+export declare const defaultPolicy: Policy;
+/**
+ * Resolves the sandbox policy for a workspace: the global config file, tightened by the
+ * matching per-project override, tightened by UNIVERSAL_SANDBOX_CONFIG. Security fields
+ * only ever get stricter across explicit values; roots and denied paths accumulate.
+ */
+export declare function resolvePolicy(workspace: string, environment?: NodeJS.ProcessEnv, globalFile?: string): Policy;
+export declare function expandHome(item: string, home?: string): string;

package/dist/wire.d.ts

@@ -0,0 +1,54 @@
+import { type Policy } from "./policy.js";
+/** Workspace paths a sandboxed command must never plant or overwrite. */
+export declare const PROTECTED: readonly ["opencode.json", "opencode.jsonc", ".opencode", ".claude", ".agents"];
+export interface WireRequest {
+    version: "1.0.0";
+    containerId: string;
+    containment: "seatbelt" | "bubblewrap" | "processcontainer";
+    seatbelt?: Record<string, never>;
+    processContainer?: {
+        capabilities: string[];
+        ui: Record<string, unknown>;
+        filesystem: undefined;
+        network: undefined;
+    };
+    lifecycle: {
+        destroyOnExit: boolean;
+        preservePolicy: boolean;
+    };
+    process: {
+        commandLine: string;
+        timeout: number;
+        cwd?: string;
+        inheritDefaultEnv?: boolean;
+    };
+    filesystem: {
+        readwritePaths: string[];
+        readonlyPaths: string[];
+        deniedPaths: string[];
+    };
+    network?: {
+        egress?: unknown;
+        ingress?: unknown;
+    };
+}
+export interface WireInput {
+    readonly command: string;
+    readonly workspace: string;
+    readonly cwd: string;
+    readonly timeout: number;
+    readonly policy: Policy;
+    readonly tmpRoots?: string[];
+}
+/** Maps a policy and one command onto the wire request, platform-aware. */
+export declare function wireRequest(input: WireInput, platform?: NodeJS.Platform): WireRequest;
+/**
+ * A network-deny policy the Windows backend accepts but does not enforce (verified
+ * against Windows 11 and MXC 1.1.0: direct egress still works). Callers fail closed
+ * instead of running a command with network access the user denied.
+ */
+export declare function unsupportedNetwork(platform: NodeJS.Platform, network: "deny" | "allow"): boolean;
+/** Resolves the bundled MXC executor binary for this platform and architecture. */
+export declare function resolveExecutor(platform?: NodeJS.Platform, arch?: string): string;
+/** Quotes one argument for the platform's command-line parser. */
+export declare function quote(value: string, platform?: NodeJS.Platform): string;

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "universal-opencode-sandbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Universal OS-level sandbox for OpenCode agent shell commands on macOS, Linux and Windows, enforced by Microsoft MXC",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir dist --target node --format esm --external @microsoft/mxc-sdk --external @opencode/plugin && bun x tsc -p tsconfig.declarations.json",
+    "dev": "bun run --watch src/index.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "sandbox",
+    "security",
+    "mxc",
+    "seatbelt",
+    "bubblewrap",
+    "processcontainer",
+    "agent-safety"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/benjaminfrombe/universal-opencode-sandbox.git"
+  },
+  "homepage": "https://github.com/benjaminfrombe/universal-opencode-sandbox#readme",
+  "bugs": {
+    "url": "https://github.com/benjaminfrombe/universal-opencode-sandbox/issues"
+  },
+  "dependencies": {
+    "@microsoft/mxc-sdk": "^1.1.0"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": ">=2.0.0"
+  },
+  "devDependencies": {
+    "@opencode/plugin": "^2.3.0",
+    "@types/bun": "^1.3.9",
+    "typescript": "^5.9.0"
+  }
+}