@capybara-hq/device 0.1.0-rc.7 → 0.1.0-rc.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +106 -189
- package/dist/api.d.ts +5 -0
- package/dist/args.d.ts +8 -3
- package/dist/args.js +38 -19
- package/dist/cli.d.ts +7 -5
- package/dist/cli.js +20 -31
- package/dist/client.d.ts +0 -2
- package/dist/client.js +23 -12
- package/dist/command-log.d.ts +3 -5
- package/dist/commands/login.js +55 -1
- package/dist/commands/mode.d.ts +52 -0
- package/dist/commands/mode.js +108 -0
- package/dist/commands/policy.d.ts +11 -65
- package/dist/commands/policy.js +62 -249
- package/dist/commands/service.d.ts +4 -3
- package/dist/commands/service.js +30 -2
- package/dist/commands/start.d.ts +2 -2
- package/dist/commands/start.js +14 -6
- package/dist/commands/status.js +11 -3
- package/dist/exec/docker.d.ts +22 -30
- package/dist/exec/docker.js +81 -69
- package/dist/exec/fs-helper.d.ts +13 -8
- package/dist/exec/fs-helper.js +30 -12
- package/dist/exec/host.d.ts +8 -8
- package/dist/exec/host.js +9 -9
- package/dist/exec/os.d.ts +36 -69
- package/dist/exec/os.js +65 -159
- package/dist/exec/sandbox-messages.d.ts +14 -0
- package/dist/exec/sandbox-messages.js +21 -0
- package/dist/exec/shared.d.ts +21 -36
- package/dist/exec/shared.js +30 -164
- package/dist/exec/switch.d.ts +38 -55
- package/dist/exec/switch.js +58 -108
- package/dist/exec/types.d.ts +8 -18
- package/dist/index.d.ts +1 -1
- package/dist/network.d.ts +7 -7
- package/dist/network.js +11 -18
- package/dist/policy-store.d.ts +7 -8
- package/dist/policy-store.js +11 -15
- package/dist/policy.d.ts +25 -100
- package/dist/policy.js +44 -146
- package/dist/server-ops.d.ts +15 -35
- package/dist/server-ops.js +36 -117
- package/dist/service/launchd.d.ts +11 -1
- package/dist/service/launchd.js +14 -5
- package/dist/state.d.ts +15 -16
- package/dist/state.js +38 -36
- package/package.json +2 -2
- package/dist/proxy-guard.d.ts +0 -58
- package/dist/proxy-guard.js +0 -137
package/dist/exec/os.d.ts
CHANGED
|
@@ -1,7 +1,5 @@
|
|
|
1
1
|
import { type SandboxAskCallback, type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
|
|
2
|
-
import { type DeviceExecArgs, type ExecResult, type SandboxRoots
|
|
3
|
-
import { type TierFacts } from "../policy.js";
|
|
4
|
-
import { type ProxyGuardResult } from "../proxy-guard.js";
|
|
2
|
+
import { type DeviceExecArgs, type ExecResult, type SandboxRoots } from "@capybara-hq/plugin-sdk";
|
|
5
3
|
import type { Policy } from "../state.js";
|
|
6
4
|
import { type ReaperDeps } from "./reap.js";
|
|
7
5
|
import { type Executor } from "./types.js";
|
|
@@ -13,6 +11,8 @@ export declare function sandboxAvailability(): {
|
|
|
13
11
|
ok: false;
|
|
14
12
|
reason: string;
|
|
15
13
|
};
|
|
14
|
+
/** How to fix an unavailable OS sandbox (shared by the command refusal and the mode switch). */
|
|
15
|
+
export { SANDBOX_INSTALL_HINT, sandboxUnavailableMessage, sandboxUnavailableSwitchRefusal, } from "./sandbox-messages.js";
|
|
16
16
|
export interface OsExecutorOptions {
|
|
17
17
|
/** The device directory (from login). */
|
|
18
18
|
dir: string;
|
|
@@ -22,19 +22,16 @@ export interface OsExecutorOptions {
|
|
|
22
22
|
home?: string;
|
|
23
23
|
/** More paths commands may not read (this program's state directory). */
|
|
24
24
|
denyRead?: string[];
|
|
25
|
-
/** The localhost proxy guard (default: {@link detectLocalProxy}); injectable for tests. */
|
|
26
|
-
detectProxy?: () => Promise<ProxyGuardResult>;
|
|
27
|
-
/** Where the macOS short socket directory is made (default `/private/tmp`). */
|
|
28
|
-
socketBase?: string;
|
|
29
25
|
/** The reaper's process operations (default: the real ones); injectable for tests. */
|
|
30
26
|
reaper?: Partial<ReaperDeps>;
|
|
31
27
|
}
|
|
32
28
|
/**
|
|
33
|
-
* Runs every command inside `@anthropic-ai/sandbox-runtime` (macOS Seatbelt, Linux bubblewrap)
|
|
34
|
-
* writes only under the workspace and tmp roots, the secret
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
* {@link createOsExecutor}; the constructor alone
|
|
29
|
+
* Runs every command inside `@anthropic-ai/sandbox-runtime` (macOS Seatbelt, Linux bubblewrap),
|
|
30
|
+
* today's strict profile (spec §4.4): writes only under the workspace and tmp roots, the secret
|
|
31
|
+
* paths unreadable, no local binding or unix sockets, network only to the intersection of the
|
|
32
|
+
* device's allowlist and the kernel's. File operations in the workspace, tmp and skills roots run
|
|
33
|
+
* in a sandboxed helper too. Construct it with {@link createOsExecutor}; the constructor alone
|
|
34
|
+
* serves only `ensureRoot`.
|
|
38
35
|
*/
|
|
39
36
|
export declare class OsExecutor implements Executor {
|
|
40
37
|
private readonly opts;
|
|
@@ -50,82 +47,47 @@ export declare class OsExecutor implements Executor {
|
|
|
50
47
|
private readonly guard;
|
|
51
48
|
private readonly files;
|
|
52
49
|
/**
|
|
53
|
-
* The limits of the latest command. The ask callback has no command id; a device belongs
|
|
54
|
-
*
|
|
50
|
+
* The network limits of the latest command. The ask callback has no command id; a device belongs
|
|
51
|
+
* to one organization, so these stand for its allowlist when it explains a refusal.
|
|
55
52
|
*/
|
|
56
53
|
private lastLimits;
|
|
57
|
-
/** macOS: the short socket directory (TMPDIR in `dev` / `open`); undefined elsewhere. */
|
|
58
|
-
private socketDir;
|
|
59
|
-
/** The device's package caches (`<dir>/cache`). */
|
|
60
|
-
private readonly cacheDir;
|
|
61
|
-
/** The latest proxy guard result, and the policy object it was taken for. */
|
|
62
|
-
private proxy;
|
|
63
|
-
private guardedPolicy;
|
|
64
|
-
private guardedAt;
|
|
65
54
|
/** The configuration the sandbox runs with now, as JSON (see {@link applyConfig}). */
|
|
66
55
|
private installed;
|
|
67
|
-
/**
|
|
68
|
-
* Commands spawned while nothing narrowed them (policy `open`, their limits `open`) and still
|
|
69
|
-
* running. The ask callback allows any public name only while one runs.
|
|
70
|
-
*/
|
|
71
|
-
private readonly openCommands;
|
|
72
56
|
/**
|
|
73
57
|
* Background tasks launched on macOS that still run, by the command id of their launch, with
|
|
74
58
|
* the task's process group id (its sid). A task keeps its launch's network permissions (the
|
|
75
|
-
* per-command list
|
|
76
|
-
*
|
|
59
|
+
* per-command list) until its group is gone: it uses the launch's proxy credentials long after
|
|
60
|
+
* the launch returned. Checked on the prune tick.
|
|
77
61
|
*/
|
|
78
62
|
private readonly backgroundNet;
|
|
79
|
-
|
|
63
|
+
/** Whether the OS sandbox can run here; false means sandbox-mode operations are refused. */
|
|
64
|
+
readonly available: boolean;
|
|
65
|
+
/** Why the OS sandbox is unavailable (when {@link available} is false). */
|
|
66
|
+
readonly unavailableReason: string | undefined;
|
|
67
|
+
constructor(opts: OsExecutorOptions, state?: {
|
|
68
|
+
unavailable?: string;
|
|
69
|
+
});
|
|
70
|
+
/** Throws the actionable refusal when the OS sandbox is unavailable. */
|
|
71
|
+
private requireSandbox;
|
|
72
|
+
/** The sandbox configuration (no domains: those are per command). */
|
|
73
|
+
config(): SandboxRuntimeConfig;
|
|
80
74
|
/**
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
*/
|
|
84
|
-
tier(policy?: Policy): SandboxTier;
|
|
85
|
-
/** What the tier gives on this machine now (for the policy summary). */
|
|
86
|
-
tierFacts(policy?: Policy): TierFacts;
|
|
87
|
-
/** The latest proxy guard result. */
|
|
88
|
-
proxyGuard(): ProxyGuardResult;
|
|
89
|
-
/** The sandbox configuration for the policy at `tier` (no domains: those are per command). */
|
|
90
|
-
config(policy?: Policy, tier?: SandboxTier): SandboxRuntimeConfig;
|
|
91
|
-
/**
|
|
92
|
-
* Installs {@link config} when the policy or the tier changed it, so the change applies at the
|
|
93
|
-
* next command without a restart. The runtime reads its global configuration at each wrap.
|
|
75
|
+
* Installs {@link config} when it changed, so a policy change applies at the next command
|
|
76
|
+
* without a restart. The runtime reads its global configuration at each wrap.
|
|
94
77
|
*/
|
|
95
78
|
private applyConfig;
|
|
96
79
|
/** Records the configuration the sandbox was initialized with. */
|
|
97
80
|
markInstalled(config: SandboxRuntimeConfig): void;
|
|
98
|
-
/**
|
|
99
|
-
* macOS: makes the short socket directory (0700) at creation, and again before a `dev` / `open`
|
|
100
|
-
* command when it is gone (macOS prunes /tmp). A path taken by something else leaves the
|
|
101
|
-
* device without one: commands then use the tmp root.
|
|
102
|
-
*/
|
|
103
|
-
prepareSocketDir(): void;
|
|
104
|
-
/**
|
|
105
|
-
* Runs the localhost proxy guard at creation, when the policy was reloaded since the last run
|
|
106
|
-
* (the store returns a new object for each new version of policy.json), and when the last result
|
|
107
|
-
* is older than {@link PROXY_GUARD_TTL_MS} (a proxy started after this program). A guard that
|
|
108
|
-
* fails counts as a proxy found (fail safe; `localhost: allow` still overrides).
|
|
109
|
-
*/
|
|
110
|
-
refreshProxyGuard(policy: Policy): Promise<void>;
|
|
111
81
|
ensureRoot(): Promise<"ok" | "gone">;
|
|
112
82
|
/**
|
|
113
|
-
* The sandbox's ask callback, reached only for a host no list allows
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
*
|
|
117
|
-
* id, so a concurrent command of the same device may ride along meanwhile; the file helper never
|
|
118
|
-
* opens it. Otherwise it refuses, with a reason clients that print the proxy's status phrase
|
|
119
|
-
* show (spec §9.1).
|
|
83
|
+
* The sandbox's ask callback, reached only for a host no list allows: it refuses, with a reason
|
|
84
|
+
* clients that print the proxy's status phrase show (spec §9.1). Sandbox mode has no
|
|
85
|
+
* "any host" state (auto mode runs without the OS sandbox and has the machine's network), so
|
|
86
|
+
* this never allows.
|
|
120
87
|
*/
|
|
121
88
|
readonly askCallback: SandboxAskCallback;
|
|
122
89
|
/** The classified network refusals of one command (read before it unregisters). */
|
|
123
90
|
private blockedFor;
|
|
124
|
-
/**
|
|
125
|
-
* `<dir>/git-template`, an empty directory commands can read but not write (it is outside the
|
|
126
|
-
* roots), made on demand; undefined when it cannot be made.
|
|
127
|
-
*/
|
|
128
|
-
private gitTemplate;
|
|
129
91
|
/**
|
|
130
92
|
* The marker value of a tag's processes. An exec's processes carry `<this>.<exec id>` (see
|
|
131
93
|
* {@link execMarker}); {@link killTagged} matches both.
|
|
@@ -138,7 +100,7 @@ export declare class OsExecutor implements Executor {
|
|
|
138
100
|
* exported) and spawns it as the leader of a new process group.
|
|
139
101
|
*/
|
|
140
102
|
private spawnSandboxed;
|
|
141
|
-
/** Drops a command's network permissions (its per-command list
|
|
103
|
+
/** Drops a command's network permissions (its per-command list). */
|
|
142
104
|
private releaseNet;
|
|
143
105
|
/** Keeps a launched background task's network permissions while its group `sid` lives. */
|
|
144
106
|
private keepBackgroundNet;
|
|
@@ -179,5 +141,10 @@ export declare function launchedGroup(stdout: string, platform?: NodeJS.Platform
|
|
|
179
141
|
* The OS sandbox executor: checks the platform and dependencies, starts the sandbox's proxies
|
|
180
142
|
* once for this process, and kills what a previous run of this device left running.
|
|
181
143
|
* Network is denied unless a command's own list allows it.
|
|
144
|
+
*
|
|
145
|
+
* When the OS sandbox is unavailable (an unsupported platform or missing dependencies) this still
|
|
146
|
+
* returns an executor, marked unavailable, so `start` keeps serving: auto mode works, and every
|
|
147
|
+
* sandbox-mode command or file operation is refused with the actionable reason
|
|
148
|
+
* ({@link sandboxUnavailableMessage}) instead of running unsandboxed or stopping the device.
|
|
182
149
|
*/
|
|
183
150
|
export declare function createOsExecutor(opts: OsExecutorOptions): Promise<OsExecutor>;
|
package/dist/exec/os.js
CHANGED
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
import { spawn } from "node:child_process";
|
|
2
2
|
import { createHash, randomBytes } from "node:crypto";
|
|
3
|
-
import { existsSync,
|
|
3
|
+
import { existsSync, realpathSync } from "node:fs";
|
|
4
4
|
import { homedir, constants as osConstants } from "node:os";
|
|
5
|
-
import {
|
|
5
|
+
import { resolve } from "node:path";
|
|
6
6
|
import { SandboxManager, } from "@anthropic-ai/sandbox-runtime";
|
|
7
7
|
import { isBackgroundLaunch, } from "@capybara-hq/plugin-sdk";
|
|
8
|
-
import { blockedHosts, denyReason,
|
|
9
|
-
import {
|
|
10
|
-
import { detectLocalProxy, PROXY_GUARD_TTL_MS } from "../proxy-guard.js";
|
|
8
|
+
import { blockedHosts, denyReason, networkTrailer } from "../network.js";
|
|
9
|
+
import { effectiveEgress, grantedHosts, srtConfig } from "../policy.js";
|
|
11
10
|
import { FS_HELPER_SCRIPT } from "./fs-helper.js";
|
|
12
11
|
import { EXEC_MARKER, killMarked } from "./procs.js";
|
|
13
12
|
import { Reaper } from "./reap.js";
|
|
14
|
-
import {
|
|
13
|
+
import { sandboxUnavailableMessage } from "./sandbox-messages.js";
|
|
14
|
+
import { ENV_NAME_RE, HostFiles, isUnder, OutputCap, osRoots, PIPE_GRACE_MS, policyError, RootGuard, shellQuote, toolHomeEnv, } from "./shared.js";
|
|
15
15
|
import { DeviceOpError } from "./types.js";
|
|
16
16
|
export { osRoots, ROOT_MARKER, utf8Prefix } from "./shared.js";
|
|
17
17
|
/** A file operation in the sandboxed helper that takes longer than this is killed. */
|
|
@@ -40,6 +40,8 @@ export function sandboxAvailability() {
|
|
|
40
40
|
}
|
|
41
41
|
return { ok: true };
|
|
42
42
|
}
|
|
43
|
+
/** How to fix an unavailable OS sandbox (shared by the command refusal and the mode switch). */
|
|
44
|
+
export { SANDBOX_INSTALL_HINT, sandboxUnavailableMessage, sandboxUnavailableSwitchRefusal, } from "./sandbox-messages.js";
|
|
43
45
|
/** Sends SIGKILL to a process group; false when the group no longer exists. */
|
|
44
46
|
function killGroupId(pgid, signal = "SIGKILL") {
|
|
45
47
|
try {
|
|
@@ -60,11 +62,12 @@ function pidAlive(pid) {
|
|
|
60
62
|
}
|
|
61
63
|
}
|
|
62
64
|
/**
|
|
63
|
-
* Runs every command inside `@anthropic-ai/sandbox-runtime` (macOS Seatbelt, Linux bubblewrap)
|
|
64
|
-
* writes only under the workspace and tmp roots, the secret
|
|
65
|
-
*
|
|
66
|
-
*
|
|
67
|
-
* {@link createOsExecutor}; the constructor alone
|
|
65
|
+
* Runs every command inside `@anthropic-ai/sandbox-runtime` (macOS Seatbelt, Linux bubblewrap),
|
|
66
|
+
* today's strict profile (spec §4.4): writes only under the workspace and tmp roots, the secret
|
|
67
|
+
* paths unreadable, no local binding or unix sockets, network only to the intersection of the
|
|
68
|
+
* device's allowlist and the kernel's. File operations in the workspace, tmp and skills roots run
|
|
69
|
+
* in a sandboxed helper too. Construct it with {@link createOsExecutor}; the constructor alone
|
|
70
|
+
* serves only `ensureRoot`.
|
|
68
71
|
*/
|
|
69
72
|
export class OsExecutor {
|
|
70
73
|
opts;
|
|
@@ -80,79 +83,55 @@ export class OsExecutor {
|
|
|
80
83
|
guard;
|
|
81
84
|
files;
|
|
82
85
|
/**
|
|
83
|
-
* The limits of the latest command. The ask callback has no command id; a device belongs
|
|
84
|
-
*
|
|
86
|
+
* The network limits of the latest command. The ask callback has no command id; a device belongs
|
|
87
|
+
* to one organization, so these stand for its allowlist when it explains a refusal.
|
|
85
88
|
*/
|
|
86
89
|
lastLimits;
|
|
87
|
-
/** macOS: the short socket directory (TMPDIR in `dev` / `open`); undefined elsewhere. */
|
|
88
|
-
socketDir;
|
|
89
|
-
/** The device's package caches (`<dir>/cache`). */
|
|
90
|
-
cacheDir;
|
|
91
|
-
/** The latest proxy guard result, and the policy object it was taken for. */
|
|
92
|
-
proxy = { detected: false, reasons: [] };
|
|
93
|
-
guardedPolicy;
|
|
94
|
-
guardedAt = 0;
|
|
95
90
|
/** The configuration the sandbox runs with now, as JSON (see {@link applyConfig}). */
|
|
96
91
|
installed;
|
|
97
|
-
/**
|
|
98
|
-
* Commands spawned while nothing narrowed them (policy `open`, their limits `open`) and still
|
|
99
|
-
* running. The ask callback allows any public name only while one runs.
|
|
100
|
-
*/
|
|
101
|
-
openCommands = new Set();
|
|
102
92
|
/**
|
|
103
93
|
* Background tasks launched on macOS that still run, by the command id of their launch, with
|
|
104
94
|
* the task's process group id (its sid). A task keeps its launch's network permissions (the
|
|
105
|
-
* per-command list
|
|
106
|
-
*
|
|
95
|
+
* per-command list) until its group is gone: it uses the launch's proxy credentials long after
|
|
96
|
+
* the launch returned. Checked on the prune tick.
|
|
107
97
|
*/
|
|
108
98
|
backgroundNet = new Map();
|
|
109
|
-
|
|
99
|
+
/** Whether the OS sandbox can run here; false means sandbox-mode operations are refused. */
|
|
100
|
+
available;
|
|
101
|
+
/** Why the OS sandbox is unavailable (when {@link available} is false). */
|
|
102
|
+
unavailableReason;
|
|
103
|
+
constructor(opts, state = {}) {
|
|
110
104
|
this.opts = opts;
|
|
105
|
+
this.available = state.unavailable === undefined;
|
|
106
|
+
this.unavailableReason = state.unavailable;
|
|
111
107
|
this.reaper = new Reaper(opts.reaper);
|
|
112
108
|
const dir = resolve(opts.dir);
|
|
113
109
|
// The roots are reported as real paths, so what commands print matches what the kernel sends.
|
|
114
110
|
this.dir = existsSync(dir) ? realpathSync(dir) : dir;
|
|
115
111
|
this.roots = osRoots(this.dir);
|
|
116
112
|
this.guard = new RootGuard(this.dir, this.roots);
|
|
117
|
-
this.files = new HostFiles(this.roots);
|
|
113
|
+
this.files = new HostFiles(this.roots, "sandbox");
|
|
118
114
|
this.dirKey = createHash("sha256").update(this.dir).digest("hex").slice(0, 16);
|
|
119
|
-
this.cacheDir = cacheRoot(this.dir);
|
|
120
|
-
}
|
|
121
|
-
/**
|
|
122
|
-
* The tier of work that has no limits of its own (the file helper): the device's choice cut to
|
|
123
|
-
* the latest exec's ceiling, `strict` before any exec (no ceiling known yet).
|
|
124
|
-
*/
|
|
125
|
-
tier(policy = this.opts.policy()) {
|
|
126
|
-
return this.lastLimits === undefined ? "strict" : deviceTier(policy, this.lastLimits);
|
|
127
|
-
}
|
|
128
|
-
/** What the tier gives on this machine now (for the policy summary). */
|
|
129
|
-
tierFacts(policy = this.opts.policy()) {
|
|
130
|
-
return tierFacts(policy, this.lastLimits, {
|
|
131
|
-
proxyDetected: this.proxy.detected,
|
|
132
|
-
mode: "os",
|
|
133
|
-
});
|
|
134
115
|
}
|
|
135
|
-
/**
|
|
136
|
-
|
|
137
|
-
|
|
116
|
+
/** Throws the actionable refusal when the OS sandbox is unavailable. */
|
|
117
|
+
requireSandbox() {
|
|
118
|
+
if (!this.available) {
|
|
119
|
+
throw new DeviceOpError("error", sandboxUnavailableMessage(this.unavailableReason ?? ""));
|
|
120
|
+
}
|
|
138
121
|
}
|
|
139
|
-
/** The sandbox configuration
|
|
140
|
-
config(
|
|
141
|
-
return srtConfig(
|
|
142
|
-
tier,
|
|
122
|
+
/** The sandbox configuration (no domains: those are per command). */
|
|
123
|
+
config() {
|
|
124
|
+
return srtConfig(this.roots, [], {
|
|
143
125
|
...(this.opts.home !== undefined && { home: this.opts.home }),
|
|
144
126
|
...(this.opts.denyRead !== undefined && { denyRead: this.opts.denyRead }),
|
|
145
|
-
proxyDetected: this.proxy.detected,
|
|
146
|
-
...(this.socketDir !== undefined && { socketDir: this.socketDir }),
|
|
147
|
-
cacheDir: this.cacheDir,
|
|
148
127
|
});
|
|
149
128
|
}
|
|
150
129
|
/**
|
|
151
|
-
* Installs {@link config} when
|
|
152
|
-
*
|
|
130
|
+
* Installs {@link config} when it changed, so a policy change applies at the next command
|
|
131
|
+
* without a restart. The runtime reads its global configuration at each wrap.
|
|
153
132
|
*/
|
|
154
|
-
applyConfig(
|
|
155
|
-
const config = this.config(
|
|
133
|
+
applyConfig() {
|
|
134
|
+
const config = this.config();
|
|
156
135
|
const json = JSON.stringify(config);
|
|
157
136
|
if (json === this.installed)
|
|
158
137
|
return;
|
|
@@ -164,60 +143,17 @@ export class OsExecutor {
|
|
|
164
143
|
markInstalled(config) {
|
|
165
144
|
this.installed = JSON.stringify(config);
|
|
166
145
|
}
|
|
167
|
-
/**
|
|
168
|
-
* macOS: makes the short socket directory (0700) at creation, and again before a `dev` / `open`
|
|
169
|
-
* command when it is gone (macOS prunes /tmp). A path taken by something else leaves the
|
|
170
|
-
* device without one: commands then use the tmp root.
|
|
171
|
-
*/
|
|
172
|
-
prepareSocketDir() {
|
|
173
|
-
if (process.platform !== "darwin")
|
|
174
|
-
return;
|
|
175
|
-
this.socketDir = prepareSocketDir(socketDirPath(this.dirKey, this.opts.socketBase));
|
|
176
|
-
}
|
|
177
|
-
/**
|
|
178
|
-
* Runs the localhost proxy guard at creation, when the policy was reloaded since the last run
|
|
179
|
-
* (the store returns a new object for each new version of policy.json), and when the last result
|
|
180
|
-
* is older than {@link PROXY_GUARD_TTL_MS} (a proxy started after this program). A guard that
|
|
181
|
-
* fails counts as a proxy found (fail safe; `localhost: allow` still overrides).
|
|
182
|
-
*/
|
|
183
|
-
async refreshProxyGuard(policy) {
|
|
184
|
-
const now = Date.now();
|
|
185
|
-
if (policy === this.guardedPolicy && now - this.guardedAt < PROXY_GUARD_TTL_MS)
|
|
186
|
-
return;
|
|
187
|
-
this.guardedPolicy = policy;
|
|
188
|
-
this.guardedAt = now;
|
|
189
|
-
try {
|
|
190
|
-
this.proxy = await (this.opts.detectProxy ?? (() => detectLocalProxy()))();
|
|
191
|
-
}
|
|
192
|
-
catch (e) {
|
|
193
|
-
this.proxy = {
|
|
194
|
-
detected: true,
|
|
195
|
-
reasons: [`the localhost proxy guard failed: ${e.message}`],
|
|
196
|
-
};
|
|
197
|
-
}
|
|
198
|
-
}
|
|
199
146
|
async ensureRoot() {
|
|
200
147
|
return this.guard.ensure();
|
|
201
148
|
}
|
|
202
149
|
/**
|
|
203
|
-
* The sandbox's ask callback, reached only for a host no list allows
|
|
204
|
-
*
|
|
205
|
-
*
|
|
206
|
-
*
|
|
207
|
-
* id, so a concurrent command of the same device may ride along meanwhile; the file helper never
|
|
208
|
-
* opens it. Otherwise it refuses, with a reason clients that print the proxy's status phrase
|
|
209
|
-
* show (spec §9.1).
|
|
150
|
+
* The sandbox's ask callback, reached only for a host no list allows: it refuses, with a reason
|
|
151
|
+
* clients that print the proxy's status phrase show (spec §9.1). Sandbox mode has no
|
|
152
|
+
* "any host" state (auto mode runs without the OS sandbox and has the machine's network), so
|
|
153
|
+
* this never allows.
|
|
210
154
|
*/
|
|
211
155
|
askCallback = async ({ host }) => {
|
|
212
|
-
|
|
213
|
-
const limits = this.lastLimits;
|
|
214
|
-
if (this.openCommands.size > 0 &&
|
|
215
|
-
limits !== undefined &&
|
|
216
|
-
effectiveEgress(policy, limits).includes(ANY_HOST) &&
|
|
217
|
-
isPublicName(host)) {
|
|
218
|
-
return true;
|
|
219
|
-
}
|
|
220
|
-
return { allow: false, reason: denyReason(host, limits, policy) };
|
|
156
|
+
return { allow: false, reason: denyReason(host, this.lastLimits, this.opts.policy()) };
|
|
221
157
|
};
|
|
222
158
|
/** The classified network refusals of one command (read before it unregisters). */
|
|
223
159
|
blockedFor(commandId, limits, policy) {
|
|
@@ -226,20 +162,6 @@ export class OsExecutor {
|
|
|
226
162
|
.map((v) => v.line);
|
|
227
163
|
return blockedHosts(lines, limits, policy);
|
|
228
164
|
}
|
|
229
|
-
/**
|
|
230
|
-
* `<dir>/git-template`, an empty directory commands can read but not write (it is outside the
|
|
231
|
-
* roots), made on demand; undefined when it cannot be made.
|
|
232
|
-
*/
|
|
233
|
-
gitTemplate() {
|
|
234
|
-
const path = join(this.dir, "git-template");
|
|
235
|
-
try {
|
|
236
|
-
mkdirSync(path, { recursive: true, mode: 0o755 });
|
|
237
|
-
return lstatSync(path).isDirectory() ? path : undefined;
|
|
238
|
-
}
|
|
239
|
-
catch {
|
|
240
|
-
return undefined;
|
|
241
|
-
}
|
|
242
|
-
}
|
|
243
165
|
/**
|
|
244
166
|
* The marker value of a tag's processes. An exec's processes carry `<this>.<exec id>` (see
|
|
245
167
|
* {@link execMarker}); {@link killTagged} matches both.
|
|
@@ -257,14 +179,6 @@ export class OsExecutor {
|
|
|
257
179
|
*/
|
|
258
180
|
async spawnSandboxed(script, o) {
|
|
259
181
|
const exports = [];
|
|
260
|
-
const dev = o.tier !== "strict";
|
|
261
|
-
// Re-checked before every dev / open command (macOS prunes /tmp, and a path swapped for a
|
|
262
|
-
// link or another user's directory must not be used): prepareSocketDir never follows links.
|
|
263
|
-
if (dev && process.platform === "darwin")
|
|
264
|
-
this.prepareSocketDir();
|
|
265
|
-
// dev / open on macOS: the short socket directory, where unix sockets are allowed.
|
|
266
|
-
const tmp = dev && this.socketDir !== undefined ? this.socketDir : this.roots.tmp;
|
|
267
|
-
const gitTemplate = dev ? this.gitTemplate() : undefined;
|
|
268
182
|
const inner = {
|
|
269
183
|
// The user's PATH applies inside the sandbox only (the wrapper runs with OUTER_ENV).
|
|
270
184
|
PATH: process.env.PATH ?? "/usr/bin:/bin:/usr/sbin:/sbin",
|
|
@@ -273,18 +187,12 @@ export class OsExecutor {
|
|
|
273
187
|
TERM: "dumb",
|
|
274
188
|
HOME: this.roots.workspace,
|
|
275
189
|
...(process.env.USER !== undefined && { USER: process.env.USER }),
|
|
276
|
-
// Version managers (asdf, nvm, pyenv, ...) read their data under the real home
|
|
277
|
-
//
|
|
190
|
+
// Version managers (asdf, nvm, pyenv, ...) read their data under the real home: HOME is the
|
|
191
|
+
// workspace here. Read only; the request's values win.
|
|
278
192
|
...toolHomeEnv(this.opts.home ?? homedir()),
|
|
279
|
-
// dev / open: package caches under <dir>/cache; the command's own values win.
|
|
280
|
-
...(dev && cacheEnv(this.cacheDir, { create: true })),
|
|
281
|
-
// dev / open may write .git/config but never .git/hooks: init and clone copy no sample hooks.
|
|
282
|
-
...(dev && gitTemplate !== undefined && { GIT_TEMPLATE_DIR: gitTemplate }),
|
|
283
193
|
...o.env,
|
|
284
194
|
// The runtime points TMPDIR at its own /tmp/claude (denied by the config): use ours.
|
|
285
|
-
TMPDIR: tmp,
|
|
286
|
-
// Chromium on macOS ignores TMPDIR and reads this instead (its singleton socket).
|
|
287
|
-
...(process.platform === "darwin" && { MAC_CHROMIUM_TMPDIR: tmp }),
|
|
195
|
+
TMPDIR: this.roots.tmp,
|
|
288
196
|
[EXEC_MARKER]: o.marker,
|
|
289
197
|
};
|
|
290
198
|
for (const [k, v] of Object.entries(inner)) {
|
|
@@ -292,15 +200,13 @@ export class OsExecutor {
|
|
|
292
200
|
throw policyError(`invalid environment variable name ${JSON.stringify(k)}`);
|
|
293
201
|
exports.push(`export ${k}=${shellQuote(v)}`);
|
|
294
202
|
}
|
|
295
|
-
this.applyConfig(
|
|
203
|
+
this.applyConfig();
|
|
296
204
|
const commandId = randomBytes(16).toString("base64url");
|
|
297
205
|
const wrapped = await SandboxManager.wrapWithSandbox(`${exports.join("\n")}\n${script}`, "/bin/bash", undefined, o.signal, { commandId, commandText: script });
|
|
298
206
|
// The kernel may have cancelled while the wrap was prepared.
|
|
299
207
|
o.signal?.throwIfAborted();
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
if (listed.length > 0) {
|
|
303
|
-
SandboxManager.registerCommandNetworkLists(commandId, { allowedDomains: listed });
|
|
208
|
+
if (o.egress.length > 0) {
|
|
209
|
+
SandboxManager.registerCommandNetworkLists(commandId, { allowedDomains: o.egress });
|
|
304
210
|
}
|
|
305
211
|
let child;
|
|
306
212
|
try {
|
|
@@ -319,10 +225,9 @@ export class OsExecutor {
|
|
|
319
225
|
}
|
|
320
226
|
return { child, commandId };
|
|
321
227
|
}
|
|
322
|
-
/** Drops a command's network permissions (its per-command list
|
|
228
|
+
/** Drops a command's network permissions (its per-command list). */
|
|
323
229
|
releaseNet(commandId) {
|
|
324
230
|
this.backgroundNet.delete(commandId);
|
|
325
|
-
this.openCommands.delete(commandId);
|
|
326
231
|
SandboxManager.unregisterCommandNetworkLists(commandId);
|
|
327
232
|
}
|
|
328
233
|
/** Keeps a launched background task's network permissions while its group `sid` lives. */
|
|
@@ -384,15 +289,15 @@ export class OsExecutor {
|
|
|
384
289
|
}
|
|
385
290
|
async exec(args, signal) {
|
|
386
291
|
signal.throwIfAborted();
|
|
292
|
+
this.requireSandbox();
|
|
387
293
|
const cwd = await this.files.inside(args.cwd ?? this.roots.workspace, "cwd");
|
|
388
294
|
// Read once: the command's lists and the explanation of its refusals use the same policy.
|
|
389
295
|
const policy = this.opts.policy();
|
|
390
296
|
this.lastLimits = args.limits;
|
|
391
|
-
await this.refreshProxyGuard(policy);
|
|
392
297
|
// A granted host the command still could not reach is not the device's doing.
|
|
393
298
|
const judged = {
|
|
394
299
|
...policy,
|
|
395
|
-
allowedDomains: [...policy.allowedDomains, ...grantedHosts(
|
|
300
|
+
allowedDomains: [...policy.allowedDomains, ...grantedHosts(args.limits, args.grants)],
|
|
396
301
|
};
|
|
397
302
|
const egress = effectiveEgress(policy, args.limits, args.grants);
|
|
398
303
|
const marker = this.execMarker(args.tag);
|
|
@@ -403,12 +308,8 @@ export class OsExecutor {
|
|
|
403
308
|
...(args.env !== undefined && { env: args.env }),
|
|
404
309
|
marker,
|
|
405
310
|
egress,
|
|
406
|
-
policy,
|
|
407
|
-
tier: deviceTier(policy, args.limits),
|
|
408
311
|
signal,
|
|
409
312
|
});
|
|
410
|
-
if (egress.includes(ANY_HOST))
|
|
411
|
-
this.openCommands.add(commandId);
|
|
412
313
|
return new Promise((resolvePromise, reject) => {
|
|
413
314
|
const cap = new OutputCap(args.maxOutputBytes);
|
|
414
315
|
let timedOut = false;
|
|
@@ -519,6 +420,7 @@ export class OsExecutor {
|
|
|
519
420
|
process.execPath,
|
|
520
421
|
"-e",
|
|
521
422
|
FS_HELPER_SCRIPT,
|
|
423
|
+
"sandbox",
|
|
522
424
|
op,
|
|
523
425
|
path,
|
|
524
426
|
String(maxBytes),
|
|
@@ -531,8 +433,6 @@ export class OsExecutor {
|
|
|
531
433
|
cwd: this.roots.workspace,
|
|
532
434
|
marker: this.markerOf("fs-helper"),
|
|
533
435
|
egress: [],
|
|
534
|
-
policy: this.opts.policy(),
|
|
535
|
-
tier: this.tier(),
|
|
536
436
|
stdin: data !== undefined,
|
|
537
437
|
});
|
|
538
438
|
const chunks = [];
|
|
@@ -578,6 +478,7 @@ export class OsExecutor {
|
|
|
578
478
|
return res.r ?? null;
|
|
579
479
|
}
|
|
580
480
|
async readFile(path, maxBytes) {
|
|
481
|
+
this.requireSandbox();
|
|
581
482
|
const p = this.files.lexical(path);
|
|
582
483
|
if (isUnder(p, this.roots.skills))
|
|
583
484
|
return this.files.read(path, maxBytes);
|
|
@@ -585,12 +486,14 @@ export class OsExecutor {
|
|
|
585
486
|
return r === null ? null : { data: Buffer.from(r.b64, "base64"), truncated: r.truncated };
|
|
586
487
|
}
|
|
587
488
|
async writeFile(path, data) {
|
|
489
|
+
this.requireSandbox();
|
|
588
490
|
const p = this.files.lexical(path);
|
|
589
491
|
if (isUnder(p, this.roots.skills))
|
|
590
492
|
return this.files.write(path, data);
|
|
591
493
|
await this.helper("write", p, 0, data);
|
|
592
494
|
}
|
|
593
495
|
async stat(path) {
|
|
496
|
+
this.requireSandbox();
|
|
594
497
|
const p = this.files.lexical(path);
|
|
595
498
|
if (isUnder(p, this.roots.skills)) {
|
|
596
499
|
return this.files.stat(path);
|
|
@@ -627,7 +530,8 @@ export class OsExecutor {
|
|
|
627
530
|
if (this.pruneTimer !== undefined)
|
|
628
531
|
clearInterval(this.pruneTimer);
|
|
629
532
|
this.pruneTimer = undefined;
|
|
630
|
-
|
|
533
|
+
if (this.available)
|
|
534
|
+
await SandboxManager.reset();
|
|
631
535
|
}
|
|
632
536
|
}
|
|
633
537
|
/**
|
|
@@ -645,18 +549,20 @@ export function launchedGroup(stdout, platform = process.platform) {
|
|
|
645
549
|
* The OS sandbox executor: checks the platform and dependencies, starts the sandbox's proxies
|
|
646
550
|
* once for this process, and kills what a previous run of this device left running.
|
|
647
551
|
* Network is denied unless a command's own list allows it.
|
|
552
|
+
*
|
|
553
|
+
* When the OS sandbox is unavailable (an unsupported platform or missing dependencies) this still
|
|
554
|
+
* returns an executor, marked unavailable, so `start` keeps serving: auto mode works, and every
|
|
555
|
+
* sandbox-mode command or file operation is refused with the actionable reason
|
|
556
|
+
* ({@link sandboxUnavailableMessage}) instead of running unsandboxed or stopping the device.
|
|
648
557
|
*/
|
|
649
558
|
export async function createOsExecutor(opts) {
|
|
650
559
|
const available = sandboxAvailability();
|
|
651
560
|
if (!available.ok)
|
|
652
|
-
|
|
561
|
+
return new OsExecutor(opts, { unavailable: available.reason });
|
|
653
562
|
const executor = new OsExecutor(opts);
|
|
654
|
-
executor.prepareSocketDir();
|
|
655
|
-
const policy = opts.policy();
|
|
656
|
-
await executor.refreshProxyGuard(policy);
|
|
657
563
|
// The ask callback never allows: a destination outside the lists is refused, with a reason
|
|
658
564
|
// when this runtime carries one (an older runtime would read any answer object as an allow).
|
|
659
|
-
const config = executor.config(
|
|
565
|
+
const config = executor.config();
|
|
660
566
|
await SandboxManager.initialize(config, SandboxManager.askCallbackDenyReason === true ? executor.askCallback : undefined);
|
|
661
567
|
executor.markInstalled(config);
|
|
662
568
|
await executor.killLeftovers();
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The texts of an unavailable OS sandbox (spec 2026-11-14 direction): sandbox mode must refuse a
|
|
3
|
+
* command with a clear, actionable reason while auto mode keeps working. Pure strings, so the
|
|
4
|
+
* `mode` command can use them without loading the sandbox runtime.
|
|
5
|
+
*/
|
|
6
|
+
/** How to fix an unavailable OS sandbox (shared by the command refusal and the mode switch). */
|
|
7
|
+
export declare const SANDBOX_INSTALL_HINT = "install the sandbox dependencies (bubblewrap and socat on Linux) and restart capybara-device";
|
|
8
|
+
/**
|
|
9
|
+
* The refusal of every sandbox-mode operation when the OS sandbox is unavailable (device protocol
|
|
10
|
+
* error kind `error`): actionable, and never a silent fallback to running unsandboxed.
|
|
11
|
+
*/
|
|
12
|
+
export declare function sandboxUnavailableMessage(reason: string): string;
|
|
13
|
+
/** The refusal of `capybara-device mode sandbox` when the OS sandbox is unavailable. */
|
|
14
|
+
export declare function sandboxUnavailableSwitchRefusal(reason: string): string;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The texts of an unavailable OS sandbox (spec 2026-11-14 direction): sandbox mode must refuse a
|
|
3
|
+
* command with a clear, actionable reason while auto mode keeps working. Pure strings, so the
|
|
4
|
+
* `mode` command can use them without loading the sandbox runtime.
|
|
5
|
+
*/
|
|
6
|
+
/** How to fix an unavailable OS sandbox (shared by the command refusal and the mode switch). */
|
|
7
|
+
export const SANDBOX_INSTALL_HINT = "install the sandbox dependencies (bubblewrap and socat on Linux) and restart capybara-device";
|
|
8
|
+
/**
|
|
9
|
+
* The refusal of every sandbox-mode operation when the OS sandbox is unavailable (device protocol
|
|
10
|
+
* error kind `error`): actionable, and never a silent fallback to running unsandboxed.
|
|
11
|
+
*/
|
|
12
|
+
export function sandboxUnavailableMessage(reason) {
|
|
13
|
+
return (`The OS sandbox is unavailable on this machine (${reason}), so commands cannot run in sandbox ` +
|
|
14
|
+
"mode. Run `capybara-device mode auto` on this machine to use auto mode, or " +
|
|
15
|
+
`${SANDBOX_INSTALL_HINT}.`);
|
|
16
|
+
}
|
|
17
|
+
/** The refusal of `capybara-device mode sandbox` when the OS sandbox is unavailable. */
|
|
18
|
+
export function sandboxUnavailableSwitchRefusal(reason) {
|
|
19
|
+
return (`Nothing changed: the OS sandbox is unavailable on this machine (${reason}), so sandbox mode ` +
|
|
20
|
+
`could not run commands. Stay in auto mode, or ${SANDBOX_INSTALL_HINT} and try again.`);
|
|
21
|
+
}
|