A local-first multi-agent app development platform, built on PenguinHarness
/**
* @adelie/sandbox-bwrap — a bubblewrap sandbox backend.
*
* A PLUGIN PACKAGE, not part of the platform: a Project asks for it on the Plugins page
* and the harness resolves it from the installation (see the server's plugin/loader.ts).
* It compiles against the `@adelie/core/plugin` surface (types, plus the
* decorators its bundle carries) and has no runtime dependency on the harness — and
* none on the DSH ecosystem either:
* it talks to `bwrap` directly and implements every dimension of the sandbox interface,
* including the two DSH's vocabulary does not cover.
*
* The bwrap profile is built in order, because bwrap applies mounts in order and a
* later mount shadows an earlier one:
*
* --ro-bind / / --dev /dev --proc /proc --die-with-parent the read-only world
* [writable temp] --tmpfs /tmp --bind <tmpdir> <same> a private, writable /tmp
* [workspace-write] --bind <workspaceRoot> <same> --bind <writableRoot> <same>…
* [network: none] --unshare-net no network namespace
* [mask-paths] --tmpfs <dir> | --ro-bind /dev/null <file> shadowing the above
* -- <the caller's argv>
*
* Masking is why order matters: the entries must come after the read-only bind of `/`
* that would otherwise expose them. A path that does not exist is skipped — there is
* nothing to hide, and materializing an empty directory there would change the
* filesystem view rather than restrict it.
*
* Known limitation, verified live: `--unshare-net` gives the process an empty network
* namespace (its /proc/net/dev holds only `lo`, and nothing resolves or connects), but
* `/sys` still arrives through the read-only bind of `/`, so `/sys/class/net` keeps
* listing the HOST's interfaces. Network ACCESS is enforced; host network topology
* remains readable as stale metadata. Mask it explicitly with `maskPaths` if that
* matters for a deployment.
*/
import { execFile, spawnSync } from "node:child_process";
import { accessSync, constants, statSync } from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { tmpdir } from "node:os";
import { Bind, Component, Interface, Use } from "@adelie/core/plugin";
import type {
ConfinedArgv,
Plugin,
SandboxPolicy,
SandboxProvider,
SandboxProviderSource,
} from "@adelie/core/plugin";
/** Default probe budget; a probe that hangs must not hang the first spawn forever. */
const PROBE_TIMEOUT_MS = 5_000;
/** This backend's own settings, as it reads them from its group. */
export interface BwrapSettings {
/** The bwrap program: a path or a command on PATH. */
runner: string;
/** How long the first check that the runner works may take. */
probeTimeoutMs: number;
}
/**
* The bwrap this plugin SHIPS for the host it is running on, or "" when it carries none.
*
* A deployment must not depend on the distribution having bubblewrap — most do not install it,
* and an operator who has to run `apt install bubblewrap` before the sandbox works is an
* operator whose sandbox is off. The binary lives beside the built module
* (`vendor/<platform>-<arch>/bin/bwrap`, see scripts/vendor-bwrap.mjs) and finds its own
* libcap through an `$ORIGIN/../lib` rpath, which is what lets a backend that only rewrites an
* argv use it: there is no environment to set.
*/
export function vendoredRunner(
platform: NodeJS.Platform = process.platform,
arch: string = process.arch,
runnable: (p: string) => boolean = executable,
): string {
const candidate = fileURLToPath(
new URL(`../vendor/${platform}-${arch}/bin/bwrap`, import.meta.url),
);
return runnable(candidate) ? candidate : "";
}
/** Present AND executable: a package installer may drop the exec bit, and then it is not ours to run. */
function executable(target: string): boolean {
try {
accessSync(target, constants.X_OK);
return true;
} catch {
return false;
}
}
/** Its group's stored document (defaults merged) as settings; anything unusable falls back. */
export function bwrapSettingsOf(
doc: Record<string, unknown>,
vendored: string = vendoredRunner(),
): BwrapSettings {
const runner = typeof doc.runner === "string" ? doc.runner.trim() : "";
const seconds = doc.probeTimeoutSeconds;
return {
// What a deployment names wins; then the one shipped here; and only then a host's own.
runner: runner !== "" ? runner : vendored !== "" ? vendored : "bwrap",
probeTimeoutMs:
typeof seconds === "number" && Number.isFinite(seconds) && seconds > 0
? seconds * 1000
: PROBE_TIMEOUT_MS,
};
}
/** Test seams: inject the probe verdict, and the settings the provider reads at each confine. */
export interface PenguinBwrapInternals {
probe?: (timeoutMs: number, runner: string) => boolean;
runner?: string;
settings?: () => BwrapSettings;
}
/**
* What this backend requires of plugin configuration: to read the group it declares. The
* interface is the consumer's own, so the package depends on no harness type.
*/
@Interface()
export abstract class BwrapConfigReader {
abstract get(name: string): Record<string, unknown>;
}
/** The settings group this backend declares (its contribution id), drawn inside the Sandbox card. */
export const BWRAP_GROUP = "sandbox-bwrap";
/**
* The writable roots a policy grants, canonical and deduplicated: the workspace and the
* policy's further roots (the Session's scratchpad) under `workspace-write`, and the temp
* areas whenever the policy makes temp writable (either mode).
*/
export function writableRoots(policy: SandboxPolicy): string[] {
const roots = [
...(policy.mode === "workspace-write"
? [policy.workspaceRoot, ...(policy.writableRoots ?? [])]
: []),
...(policy.writableTemp === true ? ["/tmp", tmpdir()] : []),
].map((root) => path.resolve(root));
return [...new Set(roots)];
}
/** The bwrap profile arguments for one policy (everything before `--` and the caller's argv). */
export function bwrapProfileArgs(policy: SandboxPolicy): string[] {
// Full access binds the root read-WRITE: the filesystem is unrestricted, and only the other
// dimensions below (a network cut, a masked path) still apply — which is the whole reason a
// full-access policy reached a backend at all.
const rootBind = policy.mode === "danger-full-access" ? "--bind" : "--ro-bind";
const args = [rootBind, "/", "/", "--dev", "/dev", "--proc", "/proc", "--die-with-parent"];
const roots = writableRoots(policy);
if (policy.writableTemp === true) args.push("--tmpfs", "/tmp");
for (const root of roots) {
if (root === "/tmp") continue; // already a writable tmpfs above
args.push("--bind", root, root);
}
if (policy.network === "local") {
// An empty network namespace also loses the host's loopback, so "localhost only" has no
// spelling here. The service never routes it here (no network-local dimension); refuse
// rather than read it as an open network.
throw new Error("penguin-bwrap cannot confine to the local network (localhost only)");
}
if (policy.network === "none") args.push("--unshare-net");
for (const target of policy.maskPaths ?? []) {
const resolved = path.resolve(target);
let isDirectory: boolean;
try {
isDirectory = statSync(resolved).isDirectory();
} catch {
continue; // nothing there to hide
}
if (isDirectory) args.push("--tmpfs", resolved);
else args.push("--ro-bind", "/dev/null", resolved);
}
return args;
}
/** Functional probe: can bwrap actually create the base profile on this host? */
/** The argv that checks bwrap can build the base profile at all. */
const BASE_PROFILE_PROBE = [
"--ro-bind",
"/",
"/",
"--dev",
"/dev",
"--proc",
"/proc",
"--die-with-parent",
"--",
"true",
];
function defaultProbe(timeoutMs: number, runner: string): boolean {
const probe = spawnSync(runner, BASE_PROFILE_PROBE, { timeout: timeoutMs, stdio: "ignore" });
return probe.status === 0;
}
/**
* The base-profile probe, without blocking the process: what the load-time check runs. Null when
* bwrap accepted the profile, else what it said (`setting up uid map: Permission denied` where
* user namespaces are refused), or the spawn error when it did not start.
*/
function probeAsync(timeoutMs: number, runner: string): Promise<string | null> {
return new Promise((resolve) => {
execFile(runner, BASE_PROFILE_PROBE, { timeout: timeoutMs }, (err, _stdout, stderr) => {
if (err === null) resolve(null);
else resolve(String(stderr).trim().split("\n")[0] || err.message);
});
});
}
/**
* Loads the backend, checking first that it can serve on this host — and rejecting, with the
* reason, when it cannot: it runs on Linux only, and needs a bwrap that accepts the base profile.
* A backend mounted without being able to serve would be routed policies and fail every command;
* one that declined without a reason would leave nobody able to tell why. The sandbox service
* records the rejection and the settings page shows it, and loads it again after the next save
* of the sandbox card. The confine-time probe stays, for a runner changed while mounted.
*/
export async function loadPenguinBwrapProvider(
internals: PenguinBwrapInternals & { platform?: NodeJS.Platform } = {},
): Promise<SandboxProvider | null> {
const platform = internals.platform ?? process.platform;
// Not this host's backend: a decline, not a failure — the deployment installed it for
// its Linux machines, and saying so on every Windows card would be noise.
if (platform !== "linux") return null;
const { runner, probeTimeoutMs } = internals.settings?.() ?? {
runner: internals.runner ?? (vendoredRunner() || "bwrap"),
probeTimeoutMs: PROBE_TIMEOUT_MS,
};
const refusal = internals.probe
? internals.probe(probeTimeoutMs, runner)
? null
: "the probe failed"
: await probeAsync(probeTimeoutMs, runner);
if (refusal !== null) {
// Two distributions, two switches: Debian gates unprivileged user namespaces with a sysctl,
// Ubuntu 23.10 and later lets only AppArmor-profiled programs create them (24.04's default).
// Neither is needed for the sandbox to work: sandbox-dsh confines files through Landlock.
throw new Error(
`'${runner}' is missing or refuses the base profile (${refusal}). Are unprivileged user namespaces allowed on this host? Debian: \`sysctl kernel.unprivileged_userns_clone\`; Ubuntu 23.10 and later: \`sysctl kernel.apparmor_restrict_unprivileged_userns\`. @adelie/sandbox-dsh confines file writes without them, through Landlock. Optional: a one-time root step lets bubblewrap run here, adding network isolation and masked paths — see "Sandbox on Ubuntu" in the CLI quickstart`,
);
}
return createPenguinBwrapProvider(internals);
}
/**
* The backend. It reads its settings at each confine, so an edit applies to the next spawn;
* the probe runs lazily (the first confine with a given runner) and is cached per runner: an
* unavailable bwrap throws — fail-closed — rather than degrading to a weaker profile, because
* the dimensions routed here (network, mask-paths) have no weaker form.
*/
export function createPenguinBwrapProvider(internals: PenguinBwrapInternals = {}): SandboxProvider {
const probe = internals.probe ?? defaultProbe;
const settings =
internals.settings ??
(() => ({
runner: internals.runner ?? (vendoredRunner() || "bwrap"),
probeTimeoutMs: PROBE_TIMEOUT_MS,
}));
const usable = new Map<string, boolean>();
return {
dimensions: ["fs-write", "network", "mask-paths", "closed-temp"],
mechanism: "bubblewrap",
confine(argv, policy): ConfinedArgv {
const { runner, probeTimeoutMs } = settings();
if (!usable.has(runner)) usable.set(runner, probe(probeTimeoutMs, runner));
if (!usable.get(runner)) {
throw new Error(
`penguin-bwrap cannot confine on this host: '${runner}' is missing or refuses the ` +
"base profile; refusing to run the command unconfined. Install bubblewrap, or " +
"drop the network / mask-paths requirements so another backend can serve the policy.",
);
}
return {
argv: [runner, ...bwrapProfileArgs(policy), "--", ...argv],
// bwrap enforces the whole profile it accepts: mounts, and the network
// namespace when asked. Nothing here is best-effort.
enforcement: "full",
// The kernel's dialect under these mounts: a write to the read-only world is
// EROFS, a write into a masked tmpfs (or through the /dev/null file mask) is
// EACCES/EPERM.
denialSignatures: ["read-only file system", "permission denied", "operation not permitted"],
runnerFailureRules: [{ fatalSignatures: [`${runner}: `] }],
};
},
};
}
/**
* The plugin's one module: a provider on the sandbox slot, the code half of the
* contribution the decorator declares (its manifest is generated into ifaces.json from
* here). Created per App, so a hot swap gets a fresh provider.
*/
@Component({
contributes: {
"SandboxModule.providers": [
{
id: "sandbox-bwrap.provider",
name: "penguin-bwrap",
dimensions: ["fs-write", "network", "mask-paths", "closed-temp"],
},
],
"PluginConfigProvider.groups": [
{
id: "sandbox-bwrap",
parent: "sandbox",
title: "Bubblewrap",
properties: {
runner: {
type: "string",
title: "bwrap program",
titleZh: "bwrap 程序",
description:
"A path or a command on PATH; empty uses the bubblewrap this plugin ships, falling back to one on PATH where it carries none for this host.",
descriptionZh:
"路径或 PATH 上的命令名;留空则使用本插件自带的 bubblewrap,若没有适配本机的自带版本,再回退到 PATH 上的。",
placeholder: "bwrap",
},
probeTimeoutSeconds: {
type: "number",
title: "Probe timeout (seconds)",
titleZh: "探测超时(秒)",
description:
"How long the first check that bwrap works may take before it counts as unusable (1–30).",
descriptionZh: "首次检查 bwrap 是否可用时最多等待多久(1–30),超时即视为不可用。",
default: 5,
// The confine-time probe blocks the server while it runs; a hanging runner must
// not stall it for longer than this.
minimum: 1,
maximum: 30,
},
},
},
],
},
})
export class SandboxBwrap {
@Use() private readonly config!: BwrapConfigReader;
@Bind("sandbox-bwrap.provider") provider!: SandboxProviderSource;
setup() {
const config = this.config;
// A loader, not a load: after a save of the sandbox card the service calls it again if the
// check failed, so a corrected program mounts the backend without a restart.
this.provider = () =>
loadPenguinBwrapProvider({
settings: () => bwrapSettingsOf(config.get(BWRAP_GROUP)),
});
}
}
const plugin: Plugin = { modules: [SandboxBwrap] };
export default plugin;