@capybara-hq/device 0.1.0-rc.0 → 0.1.0-rc.10

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.
Files changed (64) hide show
  1. package/README.md +187 -44
  2. package/dist/api.d.ts +6 -1
  3. package/dist/args.d.ts +14 -3
  4. package/dist/args.js +74 -10
  5. package/dist/cli.d.ts +14 -2
  6. package/dist/cli.js +59 -10
  7. package/dist/client.d.ts +14 -3
  8. package/dist/client.js +92 -18
  9. package/dist/command-log.d.ts +8 -0
  10. package/dist/commands/drain.d.ts +13 -0
  11. package/dist/commands/drain.js +28 -0
  12. package/dist/commands/login.js +68 -11
  13. package/dist/commands/mode.d.ts +52 -0
  14. package/dist/commands/mode.js +108 -0
  15. package/dist/commands/policy.d.ts +13 -4
  16. package/dist/commands/policy.js +162 -33
  17. package/dist/commands/service.d.ts +18 -3
  18. package/dist/commands/service.js +175 -9
  19. package/dist/commands/start.d.ts +14 -3
  20. package/dist/commands/start.js +37 -5
  21. package/dist/commands/status.js +12 -4
  22. package/dist/commands/stop.d.ts +9 -2
  23. package/dist/commands/stop.js +13 -2
  24. package/dist/exec/docker.d.ts +41 -13
  25. package/dist/exec/docker.js +123 -57
  26. package/dist/exec/fs-helper.d.ts +13 -8
  27. package/dist/exec/fs-helper.js +31 -13
  28. package/dist/exec/groups.d.ts +42 -0
  29. package/dist/exec/groups.js +100 -0
  30. package/dist/exec/host.d.ts +53 -0
  31. package/dist/exec/host.js +183 -0
  32. package/dist/exec/os.d.ts +85 -15
  33. package/dist/exec/os.js +208 -36
  34. package/dist/exec/reap.d.ts +41 -0
  35. package/dist/exec/reap.js +89 -0
  36. package/dist/exec/sandbox-messages.d.ts +14 -0
  37. package/dist/exec/sandbox-messages.js +21 -0
  38. package/dist/exec/shared.d.ts +42 -13
  39. package/dist/exec/shared.js +94 -16
  40. package/dist/exec/switch.d.ts +91 -0
  41. package/dist/exec/switch.js +164 -0
  42. package/dist/exec/types.d.ts +28 -4
  43. package/dist/index.d.ts +1 -1
  44. package/dist/network.d.ts +45 -0
  45. package/dist/network.js +154 -0
  46. package/dist/pid.d.ts +13 -1
  47. package/dist/pid.js +54 -7
  48. package/dist/policy-ops.d.ts +47 -0
  49. package/dist/policy-ops.js +90 -0
  50. package/dist/policy-store.d.ts +43 -0
  51. package/dist/policy-store.js +94 -0
  52. package/dist/policy.d.ts +36 -16
  53. package/dist/policy.js +77 -19
  54. package/dist/public-suffix.d.ts +6 -0
  55. package/dist/public-suffix.js +79 -0
  56. package/dist/server-ops.d.ts +46 -7
  57. package/dist/server-ops.js +285 -29
  58. package/dist/service/installed.d.ts +5 -0
  59. package/dist/service/installed.js +14 -0
  60. package/dist/service/launchd.d.ts +11 -1
  61. package/dist/service/launchd.js +14 -5
  62. package/dist/state.d.ts +50 -6
  63. package/dist/state.js +195 -16
  64. package/package.json +3 -3
@@ -1,5 +1,16 @@
1
+ import { homedir } from "node:os";
2
+ import { hasLoginService } from "../service/installed.js";
1
3
  import { signalRunning } from "./signal.js";
2
- /** `stop`: SIGTERM to the running program. */
3
- export function stop(stateDir, out, err, kill) {
4
+ /**
5
+ * `stop`: SIGTERM to the running program. A machine that runs the program as a login service is
6
+ * stopped through it instead: launchd's `KeepAlive` (and systemd's restart) would start a signalled
7
+ * program straight back up, so `service stop` (which unloads the service) is the honest path.
8
+ */
9
+ export function stop(stateDir, out, err, kill, service) {
10
+ const where = service ?? { home: homedir(), platform: process.platform };
11
+ if (hasLoginService(where.home, where.platform)) {
12
+ err("capybara-device runs as a login service on this machine. Stop it with: capybara-device service stop");
13
+ return 1;
14
+ }
4
15
  return signalRunning(stateDir, "SIGTERM", "Stopping capybara-device.", out, err, kill);
5
16
  }
@@ -5,13 +5,13 @@ import { type Executor } from "./types.js";
5
5
  export declare const SANDBOX_IMAGE_TAG = "0.1.0-rc.5";
6
6
  export declare const SANDBOX_IMAGE = "ghcr.io/capybara-hq/capybara-sandbox:0.1.0-rc.5";
7
7
  /**
8
- * The user commands run as. On Linux the bind-mounted environment directory belongs to the host user,
8
+ * The user commands run as. On Linux the bind-mounted device directory belongs to the host user,
9
9
  * so the container runs as that uid:gid (never root: a root host user falls back to the image's user).
10
10
  * Docker Desktop (macOS) maps file ownership itself, so the image's user is used there.
11
11
  */
12
12
  export declare function containerUser(platform?: NodeJS.Platform, uid?: number | undefined, gid?: number | undefined): string;
13
- /** Container name of an environment. */
14
- export declare function containerName(environmentId: string): string;
13
+ /** Container name of a device. */
14
+ export declare function containerName(deviceId: string): string;
15
15
  /** Whether the docker CLI can reach a daemon, and why not. */
16
16
  export declare function dockerAvailability(): Promise<{
17
17
  ok: true;
@@ -20,19 +20,25 @@ export declare function dockerAvailability(): Promise<{
20
20
  reason: string;
21
21
  }>;
22
22
  export interface DockerExecutorOptions {
23
- /** The environment directory (from login). */
23
+ /** The device directory (from login). */
24
24
  dir: string;
25
- environmentId: string;
26
- policy: Policy;
25
+ deviceId: string;
26
+ /**
27
+ * The local policy now. The network decision reads it at each command; cpu and memory apply
28
+ * when the container is next created (at the next command that finds it idle).
29
+ */
30
+ policy: () => Policy;
27
31
  }
28
32
  /**
29
33
  * Runs every command with `docker exec` in one long-lived container of the published sandbox
30
- * image: the environment directory's workspace, skills (read only) and tmp are mounted at
34
+ * image: the device directory's workspace, skills (read only) and tmp are mounted at
31
35
  * /workspace, /skills and /tmp. Workspace and tmp files are read and written inside the container
32
36
  * (as the `sandbox` user, so a link a command plants resolves in the container and never on the
33
37
  * host); the skills directory, which commands cannot write, is accessed from the host with the
34
- * same real-path checks as the OS executor. Network: none unless the effective egress is
35
- * non-empty, then the default bridge (Docker mode has no domain allowlist).
38
+ * same real-path checks as the OS executor. Auto mode: the container on its default bridge, and
39
+ * file operations reach any absolute path in the container. Sandbox mode: no network attached and
40
+ * file operations stay in the mounted roots. Docker mode has no per-domain filter. A change of the
41
+ * container's flags recreates it at the next command that finds it idle.
36
42
  */
37
43
  export declare class DockerExecutor implements Executor {
38
44
  private readonly opts;
@@ -43,7 +49,7 @@ export declare class DockerExecutor implements Executor {
43
49
  private readonly hostRoots;
44
50
  private readonly guard;
45
51
  private readonly hostFiles;
46
- /** Marks every process of this environment's commands: `<dirKey>.<tag>`. */
52
+ /** Marks every process of this device's commands: `<dirKey>.<tag>`. */
47
53
  private readonly dirKey;
48
54
  private readonly running;
49
55
  private chain;
@@ -54,19 +60,38 @@ export declare class DockerExecutor implements Executor {
54
60
  private readonly queue;
55
61
  private pumping;
56
62
  private dirty;
63
+ /** The limits of the latest command: the kernel's mode ceiling for file operations. */
64
+ private lastLimits;
65
+ /** When {@link lastLimits} came (file operations follow it only inside the window). */
66
+ private lastLimitsAt;
67
+ /** The spec hash of the container in use (set when it is created or reused). */
68
+ private spec;
57
69
  constructor(opts: DockerExecutorOptions);
58
70
  ensureRoot(): Promise<"ok" | "gone">;
59
71
  markerOf(tag: string): string;
60
72
  private serial;
61
73
  private inspect;
62
74
  private wanted;
75
+ /**
76
+ * The mode file operations use now. File operations carry no limits and never pass command
77
+ * review, so they use the sandboxed result before any exec and once the latest decision is stale
78
+ * (the safe default for an organization whose ceiling is sandbox), else
79
+ * `effectiveMode(policy, limits)`.
80
+ */
81
+ private modeNow;
63
82
  /** Every `docker run` flag of the container except its name and spec label. */
64
83
  private runArgs;
65
84
  /** A hash of the run flags: a container made with other flags is recreated. */
66
85
  private specHash;
86
+ private hashOf;
67
87
  private matches;
68
88
  private mustDocker;
69
- /** Creates the container, or reuses the existing one when it matches; call inside `serial`. */
89
+ /**
90
+ * Creates the container, or reuses the existing one when it matches; call inside `serial`.
91
+ * A file operation (`anySpec`) reuses any container that sees the directory: it needs no
92
+ * particular flags, and before the first command the policy is not known yet. The next command
93
+ * that finds it idle recreates it if its flags differ.
94
+ */
70
95
  private ensureContainer;
71
96
  /**
72
97
  * Whether a reused container's mounts still show this directory's roots: after the directory was
@@ -89,7 +114,10 @@ export declare class DockerExecutor implements Executor {
89
114
  private noteFailure;
90
115
  exec(args: DeviceExecArgs, signal: AbortSignal): Promise<ExecResult>;
91
116
  private run;
92
- /** `path` made absolute and normalized; refused unless lexically under a root. */
117
+ /**
118
+ * `path` made absolute and normalized. Auto mode accepts any clean absolute path (the container
119
+ * is the boundary); sandbox mode refuses anything outside the mounted roots.
120
+ */
93
121
  private containerPath;
94
122
  /** The host path of a /skills path (the skills directory is mounted read only). */
95
123
  private skillsHostPath;
@@ -111,7 +139,7 @@ export declare class DockerExecutor implements Executor {
111
139
  private killMarker;
112
140
  killTagged(tags: string[]): Promise<void>;
113
141
  killAll(): Promise<void>;
114
- /** Kills every process carrying this environment's marker (also a previous run's). */
142
+ /** Kills every process carrying this device's marker (also a previous run's). */
115
143
  killLeftovers(): Promise<void>;
116
144
  /** Kills every running command; the container stays for the next start. */
117
145
  dispose(): Promise<void>;
@@ -2,10 +2,11 @@ import { spawn } from "node:child_process";
2
2
  import { createHash, randomBytes } from "node:crypto";
3
3
  import { existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
4
4
  import { join, resolve } from "node:path";
5
- import { DEFAULT_SANDBOX_ROOTS, } from "@capybara-hq/plugin-sdk";
6
- import { effectiveEgress } from "../policy.js";
5
+ import { DEFAULT_SANDBOX_ROOTS, validateSandboxPathShape, } from "@capybara-hq/plugin-sdk";
6
+ import { effectiveMode } from "../policy.js";
7
7
  import { EXEC_MARKER } from "./procs.js";
8
8
  import { ENV_NAME_RE, HostFiles, isUnder, OutputCap, osRoots, PIPE_GRACE_MS, policyError, RootGuard, } from "./shared.js";
9
+ import { FILE_OPS_DECISION_TTL_MS } from "./switch.js";
9
10
  import { DeviceOpError } from "./types.js";
10
11
  /** The version of the published sandbox images this program runs commands in. */
11
12
  export const SANDBOX_IMAGE_TAG = "0.1.0-rc.5";
@@ -13,7 +14,7 @@ export const SANDBOX_IMAGE = `ghcr.io/capybara-hq/capybara-sandbox:${SANDBOX_IMA
13
14
  /** The image's `sandbox` user. */
14
15
  const IMAGE_USER = "1000:1000";
15
16
  /**
16
- * The user commands run as. On Linux the bind-mounted environment directory belongs to the host user,
17
+ * The user commands run as. On Linux the bind-mounted device directory belongs to the host user,
17
18
  * so the container runs as that uid:gid (never root: a root host user falls back to the image's user).
18
19
  * Docker Desktop (macOS) maps file ownership itself, so the image's user is used there.
19
20
  */
@@ -26,11 +27,11 @@ const SPEC_LABEL = "capybara.device.spec";
26
27
  /** A file operation in the container that takes longer than this is killed. */
27
28
  const FILE_OP_TIMEOUT_S = 30;
28
29
  const ROOTS = DEFAULT_SANDBOX_ROOTS;
29
- /** Container name of an environment. */
30
- export function containerName(environmentId) {
31
- return `capybara-device-${environmentId}`;
30
+ /** Container name of a device. */
31
+ export function containerName(deviceId) {
32
+ return `capybara-device-${deviceId}`;
32
33
  }
33
- /** Runs `docker <args>` to completion (not a command of the environment). */
34
+ /** Runs `docker <args>` to completion (not a command of the device). */
34
35
  function docker(args, o = {}) {
35
36
  return new Promise((resolvePromise, reject) => {
36
37
  const child = spawn("docker", args, { stdio: [o.input ? "pipe" : "ignore", "pipe", "pipe"] });
@@ -91,42 +92,59 @@ done; done; exit 0`;
91
92
  const EXEC_WRAPPER = 'read -r n; /bin/bash -c "$1" </dev/null; s=$?; printf \'\\nCAPYBARA-DONE:%s:%d:END\\n\' "$n" "$s" >&2; exit $s';
92
93
  /** The pids limit of a container (as the cloud sandbox). */
93
94
  const PIDS_LIMIT = 1024;
94
- /** The shared prologue of the file scripts: `under` checks a real path against the three roots. */
95
- const FILE_PROLOGUE = `under() { case "$1" in /workspace|/workspace/*|/tmp|/tmp/*) return 0;; esac; return 1; }
96
- `;
97
95
  // Exit codes of the file scripts.
96
+ const E_MODE = 9;
98
97
  const E_MISSING = 10;
99
98
  const E_OUTSIDE = 11;
100
99
  const E_NOT_FILE = 12;
101
100
  const E_FAIL = 13;
102
101
  const E_DANGLING = 14;
103
- const READ_SCRIPT = `${FILE_PROLOGUE}r=$(realpath -e -- "$1" 2>/dev/null) || exit ${E_MISSING}
104
- under "$r" || exit ${E_OUTSIDE}
102
+ /**
103
+ * The shared prologue of the file scripts: `$1` is the mode, `$2` the path, `$3` the extra
104
+ * argument. In sandbox mode `allowed` checks a real path against the mounted roots; in auto mode
105
+ * any absolute path in the container is allowed (the host checks its shape already).
106
+ */
107
+ const FILE_PROLOGUE = `mode=$1; p=$2; arg=$3
108
+ allowed() {
109
+ if [ "$mode" = "auto" ]; then
110
+ case "$1" in /*) ;; *) return 1;; esac
111
+ case "/$1/" in *"/../"*) return 1;; esac
112
+ return 0
113
+ fi
114
+ case "$1" in /workspace|/workspace/*|/tmp|/tmp/*) return 0;; esac
115
+ return 1
116
+ }
117
+ if [ "$mode" != "auto" ] && [ "$mode" != "sandbox" ]; then exit ${E_MODE}; fi
118
+ `;
119
+ const READ_SCRIPT = `${FILE_PROLOGUE}r=$(realpath -e -- "$p" 2>/dev/null) || exit ${E_MISSING}
120
+ allowed "$r" || exit ${E_OUTSIDE}
105
121
  [ -d "$r" ] && exit ${E_MISSING}
106
122
  [ -f "$r" ] || exit ${E_NOT_FILE}
107
- head -c "$2" -- "$r"`;
108
- const STAT_SCRIPT = `${FILE_PROLOGUE}r=$(realpath -e -- "$1" 2>/dev/null) || exit ${E_MISSING}
109
- under "$r" || exit ${E_OUTSIDE}
123
+ head -c "$arg" -- "$r"`;
124
+ const STAT_SCRIPT = `${FILE_PROLOGUE}r=$(realpath -e -- "$p" 2>/dev/null) || exit ${E_MISSING}
125
+ allowed "$r" || exit ${E_OUTSIDE}
110
126
  if [ -d "$r" ]; then printf '%s d' "$(stat -c %s -- "$r")"; else printf '%s f' "$(stat -c %s -- "$r")"; fi`;
111
- const WRITE_SCRIPT = `${FILE_PROLOGUE}p=$1; d=$(dirname -- "$p"); a=$d
127
+ const WRITE_SCRIPT = `${FILE_PROLOGUE}d=$(dirname -- "$p"); a=$d
112
128
  while [ ! -e "$a" ] && [ "$a" != / ]; do a=$(dirname -- "$a"); done
113
129
  ra=$(realpath -e -- "$a" 2>/dev/null) || exit ${E_FAIL}
114
- under "$ra" || exit ${E_OUTSIDE}
130
+ allowed "$ra" || exit ${E_OUTSIDE}
115
131
  mkdir -p -- "$d" || exit ${E_FAIL}
116
132
  rp=$(realpath -e -- "$d" 2>/dev/null) || exit ${E_FAIL}
117
- under "$rp" || exit ${E_OUTSIDE}
133
+ allowed "$rp" || exit ${E_OUTSIDE}
118
134
  f="$rp/$(basename -- "$p")"
119
- if [ -L "$f" ]; then r=$(realpath -e -- "$f" 2>/dev/null) || exit ${E_DANGLING}; under "$r" || exit ${E_OUTSIDE}; f=$r; fi
135
+ if [ -L "$f" ]; then r=$(realpath -e -- "$f" 2>/dev/null) || exit ${E_DANGLING}; allowed "$r" || exit ${E_OUTSIDE}; f=$r; fi
120
136
  if [ -e "$f" ] && [ ! -f "$f" ]; then exit ${E_NOT_FILE}; fi
121
137
  cat > "$f" || exit ${E_FAIL}`;
122
138
  /**
123
139
  * Runs every command with `docker exec` in one long-lived container of the published sandbox
124
- * image: the environment directory's workspace, skills (read only) and tmp are mounted at
140
+ * image: the device directory's workspace, skills (read only) and tmp are mounted at
125
141
  * /workspace, /skills and /tmp. Workspace and tmp files are read and written inside the container
126
142
  * (as the `sandbox` user, so a link a command plants resolves in the container and never on the
127
143
  * host); the skills directory, which commands cannot write, is accessed from the host with the
128
- * same real-path checks as the OS executor. Network: none unless the effective egress is
129
- * non-empty, then the default bridge (Docker mode has no domain allowlist).
144
+ * same real-path checks as the OS executor. Auto mode: the container on its default bridge, and
145
+ * file operations reach any absolute path in the container. Sandbox mode: no network attached and
146
+ * file operations stay in the mounted roots. Docker mode has no per-domain filter. A change of the
147
+ * container's flags recreates it at the next command that finds it idle.
130
148
  */
131
149
  export class DockerExecutor {
132
150
  opts;
@@ -137,7 +155,7 @@ export class DockerExecutor {
137
155
  hostRoots;
138
156
  guard;
139
157
  hostFiles;
140
- /** Marks every process of this environment's commands: `<dirKey>.<tag>`. */
158
+ /** Marks every process of this device's commands: `<dirKey>.<tag>`. */
141
159
  dirKey;
142
160
  running = new Set();
143
161
  chain = Promise.resolve();
@@ -148,14 +166,20 @@ export class DockerExecutor {
148
166
  queue = [];
149
167
  pumping = false;
150
168
  dirty = false;
169
+ /** The limits of the latest command: the kernel's mode ceiling for file operations. */
170
+ lastLimits;
171
+ /** When {@link lastLimits} came (file operations follow it only inside the window). */
172
+ lastLimitsAt = 0;
173
+ /** The spec hash of the container in use (set when it is created or reused). */
174
+ spec;
151
175
  constructor(opts) {
152
176
  this.opts = opts;
153
177
  const dir = resolve(opts.dir);
154
178
  this.dir = existsSync(dir) ? realpathSync(dir) : dir;
155
179
  this.hostRoots = osRoots(this.dir);
156
180
  this.guard = new RootGuard(this.dir, this.hostRoots);
157
- this.hostFiles = new HostFiles(this.hostRoots);
158
- this.name = containerName(opts.environmentId);
181
+ this.hostFiles = new HostFiles(this.hostRoots, "sandbox");
182
+ this.name = containerName(opts.deviceId);
159
183
  this.dirKey = createHash("sha256").update(this.dir).digest("hex").slice(0, 16);
160
184
  }
161
185
  async ensureRoot() {
@@ -182,9 +206,22 @@ export class DockerExecutor {
182
206
  { source: this.hostRoots.tmp, dest: ROOTS.tmp, rw: true },
183
207
  ];
184
208
  }
209
+ /**
210
+ * The mode file operations use now. File operations carry no limits and never pass command
211
+ * review, so they use the sandboxed result before any exec and once the latest decision is stale
212
+ * (the safe default for an organization whose ceiling is sandbox), else
213
+ * `effectiveMode(policy, limits)`.
214
+ */
215
+ modeNow(policy = this.opts.policy()) {
216
+ if (policy.mode === "sandbox" || this.lastLimits === undefined)
217
+ return "sandbox";
218
+ if (Date.now() - this.lastLimitsAt > FILE_OPS_DECISION_TTL_MS)
219
+ return "sandbox";
220
+ return effectiveMode(policy, this.lastLimits);
221
+ }
185
222
  /** Every `docker run` flag of the container except its name and spec label. */
186
223
  runArgs() {
187
- const { policy } = this.opts;
224
+ const policy = this.opts.policy();
188
225
  return [
189
226
  "--init",
190
227
  "--read-only",
@@ -199,7 +236,7 @@ export class DockerExecutor {
199
236
  "--workdir",
200
237
  ROOTS.workspace,
201
238
  "--label",
202
- `capybara.device.environment=${this.opts.environmentId}`,
239
+ `capybara.device.id=${this.opts.deviceId}`,
203
240
  ...this.wanted().flatMap((m) => [
204
241
  "--mount",
205
242
  `type=bind,source=${m.source},target=${m.dest}${m.rw ? "" : ",readonly"}`,
@@ -216,7 +253,10 @@ export class DockerExecutor {
216
253
  }
217
254
  /** A hash of the run flags: a container made with other flags is recreated. */
218
255
  specHash() {
219
- return createHash("sha256").update(JSON.stringify(this.runArgs())).digest("hex").slice(0, 16);
256
+ return this.hashOf(this.runArgs());
257
+ }
258
+ hashOf(runArgs) {
259
+ return createHash("sha256").update(JSON.stringify(runArgs)).digest("hex").slice(0, 16);
220
260
  }
221
261
  matches(c) {
222
262
  return c.Config.Labels?.[SPEC_LABEL] === this.specHash();
@@ -228,34 +268,35 @@ export class DockerExecutor {
228
268
  }
229
269
  return r;
230
270
  }
231
- /** Creates the container, or reuses the existing one when it matches; call inside `serial`. */
232
- async ensureContainer() {
271
+ /**
272
+ * Creates the container, or reuses the existing one when it matches; call inside `serial`.
273
+ * A file operation (`anySpec`) reuses any container that sees the directory: it needs no
274
+ * particular flags, and before the first command the policy is not known yet. The next command
275
+ * that finds it idle recreates it if its flags differ.
276
+ */
277
+ async ensureContainer(opts = {}) {
233
278
  if (this.ready)
234
279
  return;
235
280
  if (!existsSync(this.dir)) {
236
- throw new DeviceOpError("error", "the environment directory is gone");
281
+ throw new DeviceOpError("error", "the device directory is gone");
237
282
  }
238
283
  for (const r of Object.values(this.hostRoots)) {
239
284
  if (r.includes(",")) {
240
- throw new DeviceOpError("error", `the environment directory ${this.dir} contains a comma`);
285
+ throw new DeviceOpError("error", `the device directory ${this.dir} contains a comma`);
241
286
  }
242
287
  mkdirSync(r, { recursive: true });
243
288
  }
244
289
  let c = await this.inspect();
245
- if (c !== null && (!this.matches(c) || !(await this.seesHostRoots(c)))) {
290
+ if (c !== null &&
291
+ ((opts.anySpec !== true && !this.matches(c)) || !(await this.seesHostRoots(c)))) {
246
292
  await this.mustDocker(["rm", "-f", this.name], "removing the old container");
247
293
  c = null;
248
294
  }
249
295
  if (c === null) {
250
- await this.mustDocker([
251
- "run",
252
- "-d",
253
- "--name",
254
- this.name,
255
- "--label",
256
- `${SPEC_LABEL}=${this.specHash()}`,
257
- ...this.runArgs(),
258
- ], "creating the container");
296
+ const runArgs = this.runArgs();
297
+ const spec = this.hashOf(runArgs);
298
+ await this.mustDocker(["run", "-d", "--name", this.name, "--label", `${SPEC_LABEL}=${spec}`, ...runArgs], "creating the container");
299
+ this.spec = spec;
259
300
  // Created on the default bridge (a container created with `none` cannot join it later).
260
301
  this.netOpen = true;
261
302
  }
@@ -263,6 +304,7 @@ export class DockerExecutor {
263
304
  if (!c.State.Running)
264
305
  await this.mustDocker(["start", this.name], "starting the container");
265
306
  this.netOpen = "bridge" in (await this.inspectNetworks());
307
+ this.spec = c.Config.Labels?.[SPEC_LABEL];
266
308
  }
267
309
  this.ready = true;
268
310
  }
@@ -354,6 +396,11 @@ export class DockerExecutor {
354
396
  let served;
355
397
  try {
356
398
  served = await this.serial(async () => {
399
+ // The policy or the mode changed the container's flags (shm, cpu, memory): recreate
400
+ // it once nothing runs in it.
401
+ if (this.ready && this.inflight === 0 && this.spec !== this.specHash()) {
402
+ this.ready = false;
403
+ }
357
404
  await this.ensureContainer();
358
405
  if (w.dead)
359
406
  return true;
@@ -399,7 +446,8 @@ export class DockerExecutor {
399
446
  }
400
447
  async exec(args, signal) {
401
448
  signal.throwIfAborted();
402
- const cwd = this.containerPath(args.cwd ?? ROOTS.workspace);
449
+ const mode = effectiveMode(this.opts.policy(), args.limits);
450
+ const cwd = this.containerPath(args.cwd ?? ROOTS.workspace, mode);
403
451
  const env = {
404
452
  HOME: ROOTS.workspace,
405
453
  TERM: "dumb",
@@ -411,7 +459,10 @@ export class DockerExecutor {
411
459
  if (!ENV_NAME_RE.test(k))
412
460
  throw policyError(`invalid environment variable name ${JSON.stringify(k)}`);
413
461
  }
414
- const open = effectiveEgress(this.opts.policy, args.limits).length > 0;
462
+ this.lastLimits = args.limits;
463
+ this.lastLimitsAt = Date.now();
464
+ // Auto: the container on its default bridge. Sandbox: no network at all (spec P-D7).
465
+ const open = effectiveMode(this.opts.policy(), args.limits) === "auto";
415
466
  await this.acquire(open, signal);
416
467
  try {
417
468
  signal.throwIfAborted();
@@ -542,14 +593,23 @@ export class DockerExecutor {
542
593
  child.once("close", () => finish());
543
594
  });
544
595
  }
545
- /** `path` made absolute and normalized; refused unless lexically under a root. */
546
- containerPath(path) {
596
+ /**
597
+ * `path` made absolute and normalized. Auto mode accepts any clean absolute path (the container
598
+ * is the boundary); sandbox mode refuses anything outside the mounted roots.
599
+ */
600
+ containerPath(path, mode) {
601
+ if (mode === "auto") {
602
+ const errors = validateSandboxPathShape(path);
603
+ if (errors.length > 0)
604
+ throw policyError(`${path}: ${errors.join("; ")}`);
605
+ return resolve(path);
606
+ }
547
607
  if (!path.startsWith("/"))
548
608
  throw policyError(`${path} is not an absolute path`);
549
609
  const p = resolve(path);
550
610
  const roots = Object.values(ROOTS);
551
611
  if (!roots.some((r) => isUnder(p, r))) {
552
- throw policyError(`${path} is outside the environment's roots (${roots.join(", ")})`);
612
+ throw policyError(`${path} is outside the device's roots (${roots.join(", ")})`);
553
613
  }
554
614
  return p;
555
615
  }
@@ -561,9 +621,9 @@ export class DockerExecutor {
561
621
  return isUnder(p, ROOTS.skills);
562
622
  }
563
623
  /** Runs one file script in the container; `null` for a missing file. */
564
- async fileOp(script, path, arg2, input) {
624
+ async fileOp(script, mode, path, arg2, input) {
565
625
  // A file operation does not need the network; it runs on whichever state the container has.
566
- await this.serial(() => this.ensureContainer());
626
+ await this.serial(() => this.ensureContainer({ anySpec: true }));
567
627
  const r = await docker([
568
628
  "exec",
569
629
  ...(input !== undefined ? ["-i"] : []),
@@ -576,6 +636,7 @@ export class DockerExecutor {
576
636
  "-c",
577
637
  script,
578
638
  "capybara-file",
639
+ mode,
579
640
  path,
580
641
  arg2,
581
642
  ], {
@@ -588,10 +649,12 @@ export class DockerExecutor {
588
649
  switch (r.code) {
589
650
  case 0:
590
651
  return r;
652
+ case E_MODE:
653
+ throw new DeviceOpError("policy", `missing or unknown mode for ${path}`);
591
654
  case E_MISSING:
592
655
  return null;
593
656
  case E_OUTSIDE:
594
- throw policyError(`${path} resolves outside the environment's roots`);
657
+ throw policyError(`${path} resolves outside the device's roots`);
595
658
  case E_NOT_FILE:
596
659
  throw policyError(`${path} is not a regular file`);
597
660
  case E_DANGLING:
@@ -602,10 +665,11 @@ export class DockerExecutor {
602
665
  }
603
666
  }
604
667
  async readFile(path, maxBytes) {
605
- const p = this.containerPath(path);
668
+ const mode = this.modeNow();
669
+ const p = this.containerPath(path, mode);
606
670
  if (this.inSkills(p))
607
671
  return this.hostFiles.read(this.skillsHostPath(p), maxBytes);
608
- const r = await this.fileOp(READ_SCRIPT, p, String(maxBytes + 1));
672
+ const r = await this.fileOp(READ_SCRIPT, mode, p, String(maxBytes + 1));
609
673
  if (r === null)
610
674
  return null;
611
675
  return {
@@ -614,16 +678,18 @@ export class DockerExecutor {
614
678
  };
615
679
  }
616
680
  async writeFile(path, data) {
617
- const p = this.containerPath(path);
681
+ const mode = this.modeNow();
682
+ const p = this.containerPath(path, mode);
618
683
  if (this.inSkills(p))
619
684
  return this.hostFiles.write(this.skillsHostPath(p), data);
620
- await this.fileOp(WRITE_SCRIPT, p, "", data);
685
+ await this.fileOp(WRITE_SCRIPT, mode, p, "", data);
621
686
  }
622
687
  async stat(path) {
623
- const p = this.containerPath(path);
688
+ const mode = this.modeNow();
689
+ const p = this.containerPath(path, mode);
624
690
  if (this.inSkills(p))
625
691
  return this.hostFiles.stat(this.skillsHostPath(p));
626
- const r = await this.fileOp(STAT_SCRIPT, p, "");
692
+ const r = await this.fileOp(STAT_SCRIPT, mode, p, "");
627
693
  if (r === null)
628
694
  return null;
629
695
  const [size, kind] = r.stdout.toString("utf8").split(" ");
@@ -653,7 +719,7 @@ export class DockerExecutor {
653
719
  r.killed = true;
654
720
  await this.killLeftovers();
655
721
  }
656
- /** Kills every process carrying this environment's marker (also a previous run's). */
722
+ /** Kills every process carrying this device's marker (also a previous run's). */
657
723
  async killLeftovers() {
658
724
  await this.killScript("", `${this.dirKey}.`);
659
725
  }
@@ -1,12 +1,17 @@
1
1
  /**
2
2
  * The file-operation helper the OS executor runs **inside the sandbox** (`node -e`), so a
3
- * kernel-side read or write in the workspace or tmp root never touches the host file system with
4
- * the program's own privileges: a parent directory swapped for a symlink mid-operation reaches
5
- * only what any sandboxed command could reach anyway.
3
+ * kernel-side read or write never touches the host file system with the program's own privileges:
4
+ * a parent directory swapped for a symlink mid-operation reaches only what any sandboxed command
5
+ * could reach anyway.
6
6
  *
7
- * argv: `<op> <path> <maxBytes> <root>...` with op `read` | `stat` | `write` (data on stdin).
8
- * stdout: one JSON object, `{ "r": <result> }` or `{ "e": "policy" | "error", "m": <message> }`.
9
- * read → `null` | `{ b64, truncated }`; stat → `null` | `{ size, isDir }`; write → `null`.
10
- * Non-regular files (FIFOs, sockets, devices) are refused without blocking (`O_NONBLOCK`).
7
+ * argv: `<mode> <op> <path> <maxBytes> <root>...`, mode `auto` | `sandbox`, op `read` | `stat` |
8
+ * `write` (data on stdin). A missing or unknown mode is refused. In sandbox mode the roots are
9
+ * enforced; in auto mode any clean absolute path is accepted (shape checks: absolute, no `..`
10
+ * segments, no control characters). The `auto` branch is required by this contract but has no
11
+ * production caller today: the OS executor runs the helper in sandbox mode only, and auto mode
12
+ * reads and writes directly through `HostExecutor`. stdout: one JSON object, `{ "r": <result> }`
13
+ * or `{ "e": "policy" | "error", "m": <message> }`. read → `null` | `{ b64, truncated }`; stat →
14
+ * `null` | `{ size, isDir }`; write → `null`. Non-regular files (FIFOs, sockets, devices) are
15
+ * refused without blocking (`O_NONBLOCK`).
11
16
  */
12
- export declare const FS_HELPER_SCRIPT = "\n(() => {\n const fs = require(\"fs\");\n const path = require(\"path\");\n const C = fs.constants;\n const [op, p, maxS, ...roots] = process.argv.slice(1);\n const out = (o) => process.stdout.write(JSON.stringify(o));\n const realRoots = roots.map((r) => { try { return fs.realpathSync(r); } catch { return r; } });\n const under = (r) => realRoots.some((x) => r === x || r.startsWith(x + \"/\"));\n const missing = (e) => e && (e.code === \"ENOENT\" || e.code === \"ENOTDIR\");\n const real = (q) => { try { return fs.realpathSync(q); } catch (e) { if (missing(e)) return null; throw e; } };\n const outside = (r) => out({ e: \"policy\", m: p + \" resolves to \" + r + \", outside the environment's roots\" });\n try {\n if (op === \"read\" || op === \"stat\") {\n const r = real(p);\n if (r === null) return out({ r: null });\n if (!under(r)) return outside(r);\n const fd = fs.openSync(r, C.O_RDONLY | C.O_NONBLOCK | C.O_NOFOLLOW);\n try {\n const st = fs.fstatSync(fd);\n if (op === \"stat\") return out({ r: { size: st.size, isDir: st.isDirectory() } });\n if (st.isDirectory()) return out({ r: null });\n if (!st.isFile()) return out({ e: \"policy\", m: p + \" is not a regular file\" });\n const max = Number(maxS);\n const want = Math.min(st.size, max);\n const buf = Buffer.alloc(want);\n let off = 0;\n while (off < want) {\n const n = fs.readSync(fd, buf, off, want - off, off);\n if (n === 0) break;\n off += n;\n }\n return out({ r: { b64: buf.subarray(0, off).toString(\"base64\"), truncated: st.size > max } });\n } finally {\n fs.closeSync(fd);\n }\n }\n if (op === \"write\") {\n const data = fs.readFileSync(0);\n const parent = path.dirname(p);\n let anc = parent;\n while (real(anc) === null && anc !== path.dirname(anc)) anc = path.dirname(anc);\n const ra = real(anc);\n if (ra === null || !under(ra)) return outside(ra);\n fs.mkdirSync(parent, { recursive: true });\n const rp = real(parent);\n if (rp === null) return out({ e: \"error\", m: \"cannot create \" + parent });\n if (!under(rp)) return outside(rp);\n let file = path.join(rp, path.basename(p));\n let st = null;\n try { st = fs.lstatSync(file); } catch (e) { if (!missing(e)) throw e; }\n if (st && st.isSymbolicLink()) {\n const r = real(file);\n if (r === null) return out({ e: \"policy\", m: p + \" is a dangling symbolic link\" });\n if (!under(r)) return outside(r);\n file = r;\n }\n const fd = fs.openSync(file, C.O_WRONLY | C.O_CREAT | C.O_NONBLOCK | C.O_NOFOLLOW, 0o644);\n try {\n if (!fs.fstatSync(fd).isFile()) return out({ e: \"policy\", m: p + \" is not a regular file\" });\n fs.ftruncateSync(fd, 0);\n let off = 0;\n while (off < data.length) off += fs.writeSync(fd, data, off, data.length - off, off);\n } finally {\n fs.closeSync(fd);\n }\n return out({ r: null });\n }\n out({ e: \"error\", m: \"unknown helper op \" + op });\n } catch (e) {\n out({ e: \"error\", m: String((e && e.message) || e) });\n }\n})();\n";
17
+ export declare const FS_HELPER_SCRIPT = "\n(() => {\n const fs = require(\"fs\");\n const path = require(\"path\");\n const C = fs.constants;\n const [mode, op, p, maxS, ...roots] = process.argv.slice(1);\n const out = (o) => process.stdout.write(JSON.stringify(o));\n const realRoots = roots.map((r) => { try { return fs.realpathSync(r); } catch { return r; } });\n const under = (r) => realRoots.some((x) => r === x || r.startsWith(x + \"/\"));\n const missing = (e) => e && (e.code === \"ENOENT\" || e.code === \"ENOTDIR\");\n const real = (q) => { try { return fs.realpathSync(q); } catch (e) { if (missing(e)) return null; throw e; } };\n const outside = (r) => out({ e: \"policy\", m: p + \" resolves to \" + r + \", outside the device's roots\" });\n // auto mode: any clean absolute path; sandbox mode: one of the roots.\n const shapeOk = () => {\n if (typeof p !== \"string\" || !path.isAbsolute(p)) return false;\n if (/[\\u0000-\\u001f\\u007f]/.test(p)) return false;\n return !p.split(\"/\").some((s) => s === \"..\");\n };\n const allowed = (r) => mode === \"auto\" ? true : under(r);\n try {\n if (mode !== \"auto\" && mode !== \"sandbox\") {\n return out({ e: \"policy\", m: \"missing or unknown mode\" });\n }\n if (mode === \"auto\" && !shapeOk()) {\n return out({ e: \"policy\", m: p + \" is not a clean absolute path\" });\n }\n if (op === \"read\" || op === \"stat\") {\n const r = real(p);\n if (r === null) return out({ r: null });\n if (!allowed(r)) return outside(r);\n const fd = fs.openSync(r, C.O_RDONLY | C.O_NONBLOCK | C.O_NOFOLLOW);\n try {\n const st = fs.fstatSync(fd);\n if (op === \"stat\") return out({ r: { size: st.size, isDir: st.isDirectory() } });\n if (st.isDirectory()) return out({ r: null });\n if (!st.isFile()) return out({ e: \"policy\", m: p + \" is not a regular file\" });\n const max = Number(maxS);\n const want = Math.min(st.size, max);\n const buf = Buffer.alloc(want);\n let off = 0;\n while (off < want) {\n const n = fs.readSync(fd, buf, off, want - off, off);\n if (n === 0) break;\n off += n;\n }\n return out({ r: { b64: buf.subarray(0, off).toString(\"base64\"), truncated: st.size > max } });\n } finally {\n fs.closeSync(fd);\n }\n }\n if (op === \"write\") {\n const data = fs.readFileSync(0);\n const parent = path.dirname(p);\n let anc = parent;\n while (real(anc) === null && anc !== path.dirname(anc)) anc = path.dirname(anc);\n const ra = real(anc);\n if (ra === null || !allowed(ra)) return outside(ra);\n fs.mkdirSync(parent, { recursive: true });\n const rp = real(parent);\n if (rp === null) return out({ e: \"error\", m: \"cannot create \" + parent });\n if (!allowed(rp)) return outside(rp);\n let file = path.join(rp, path.basename(p));\n let st = null;\n try { st = fs.lstatSync(file); } catch (e) { if (!missing(e)) throw e; }\n if (st && st.isSymbolicLink()) {\n const r = real(file);\n if (r === null) return out({ e: \"policy\", m: p + \" is a dangling symbolic link\" });\n if (!allowed(r)) return outside(r);\n file = r;\n }\n const fd = fs.openSync(file, C.O_WRONLY | C.O_CREAT | C.O_NONBLOCK | C.O_NOFOLLOW, 0o644);\n try {\n if (!fs.fstatSync(fd).isFile()) return out({ e: \"policy\", m: p + \" is not a regular file\" });\n fs.ftruncateSync(fd, 0);\n let off = 0;\n while (off < data.length) off += fs.writeSync(fd, data, off, data.length - off, off);\n } finally {\n fs.closeSync(fd);\n }\n return out({ r: null });\n }\n out({ e: \"error\", m: \"unknown helper op \" + op });\n } catch (e) {\n out({ e: \"error\", m: String((e && e.message) || e) });\n }\n})();\n";
@@ -1,31 +1,49 @@
1
1
  /**
2
2
  * The file-operation helper the OS executor runs **inside the sandbox** (`node -e`), so a
3
- * kernel-side read or write in the workspace or tmp root never touches the host file system with
4
- * the program's own privileges: a parent directory swapped for a symlink mid-operation reaches
5
- * only what any sandboxed command could reach anyway.
3
+ * kernel-side read or write never touches the host file system with the program's own privileges:
4
+ * a parent directory swapped for a symlink mid-operation reaches only what any sandboxed command
5
+ * could reach anyway.
6
6
  *
7
- * argv: `<op> <path> <maxBytes> <root>...` with op `read` | `stat` | `write` (data on stdin).
8
- * stdout: one JSON object, `{ "r": <result> }` or `{ "e": "policy" | "error", "m": <message> }`.
9
- * read → `null` | `{ b64, truncated }`; stat → `null` | `{ size, isDir }`; write → `null`.
10
- * Non-regular files (FIFOs, sockets, devices) are refused without blocking (`O_NONBLOCK`).
7
+ * argv: `<mode> <op> <path> <maxBytes> <root>...`, mode `auto` | `sandbox`, op `read` | `stat` |
8
+ * `write` (data on stdin). A missing or unknown mode is refused. In sandbox mode the roots are
9
+ * enforced; in auto mode any clean absolute path is accepted (shape checks: absolute, no `..`
10
+ * segments, no control characters). The `auto` branch is required by this contract but has no
11
+ * production caller today: the OS executor runs the helper in sandbox mode only, and auto mode
12
+ * reads and writes directly through `HostExecutor`. stdout: one JSON object, `{ "r": <result> }`
13
+ * or `{ "e": "policy" | "error", "m": <message> }`. read → `null` | `{ b64, truncated }`; stat →
14
+ * `null` | `{ size, isDir }`; write → `null`. Non-regular files (FIFOs, sockets, devices) are
15
+ * refused without blocking (`O_NONBLOCK`).
11
16
  */
12
17
  export const FS_HELPER_SCRIPT = `
13
18
  (() => {
14
19
  const fs = require("fs");
15
20
  const path = require("path");
16
21
  const C = fs.constants;
17
- const [op, p, maxS, ...roots] = process.argv.slice(1);
22
+ const [mode, op, p, maxS, ...roots] = process.argv.slice(1);
18
23
  const out = (o) => process.stdout.write(JSON.stringify(o));
19
24
  const realRoots = roots.map((r) => { try { return fs.realpathSync(r); } catch { return r; } });
20
25
  const under = (r) => realRoots.some((x) => r === x || r.startsWith(x + "/"));
21
26
  const missing = (e) => e && (e.code === "ENOENT" || e.code === "ENOTDIR");
22
27
  const real = (q) => { try { return fs.realpathSync(q); } catch (e) { if (missing(e)) return null; throw e; } };
23
- const outside = (r) => out({ e: "policy", m: p + " resolves to " + r + ", outside the environment's roots" });
28
+ const outside = (r) => out({ e: "policy", m: p + " resolves to " + r + ", outside the device's roots" });
29
+ // auto mode: any clean absolute path; sandbox mode: one of the roots.
30
+ const shapeOk = () => {
31
+ if (typeof p !== "string" || !path.isAbsolute(p)) return false;
32
+ if (/[\\u0000-\\u001f\\u007f]/.test(p)) return false;
33
+ return !p.split("/").some((s) => s === "..");
34
+ };
35
+ const allowed = (r) => mode === "auto" ? true : under(r);
24
36
  try {
37
+ if (mode !== "auto" && mode !== "sandbox") {
38
+ return out({ e: "policy", m: "missing or unknown mode" });
39
+ }
40
+ if (mode === "auto" && !shapeOk()) {
41
+ return out({ e: "policy", m: p + " is not a clean absolute path" });
42
+ }
25
43
  if (op === "read" || op === "stat") {
26
44
  const r = real(p);
27
45
  if (r === null) return out({ r: null });
28
- if (!under(r)) return outside(r);
46
+ if (!allowed(r)) return outside(r);
29
47
  const fd = fs.openSync(r, C.O_RDONLY | C.O_NONBLOCK | C.O_NOFOLLOW);
30
48
  try {
31
49
  const st = fs.fstatSync(fd);
@@ -52,18 +70,18 @@ export const FS_HELPER_SCRIPT = `
52
70
  let anc = parent;
53
71
  while (real(anc) === null && anc !== path.dirname(anc)) anc = path.dirname(anc);
54
72
  const ra = real(anc);
55
- if (ra === null || !under(ra)) return outside(ra);
73
+ if (ra === null || !allowed(ra)) return outside(ra);
56
74
  fs.mkdirSync(parent, { recursive: true });
57
75
  const rp = real(parent);
58
76
  if (rp === null) return out({ e: "error", m: "cannot create " + parent });
59
- if (!under(rp)) return outside(rp);
77
+ if (!allowed(rp)) return outside(rp);
60
78
  let file = path.join(rp, path.basename(p));
61
79
  let st = null;
62
80
  try { st = fs.lstatSync(file); } catch (e) { if (!missing(e)) throw e; }
63
81
  if (st && st.isSymbolicLink()) {
64
82
  const r = real(file);
65
83
  if (r === null) return out({ e: "policy", m: p + " is a dangling symbolic link" });
66
- if (!under(r)) return outside(r);
84
+ if (!allowed(r)) return outside(r);
67
85
  file = r;
68
86
  }
69
87
  const fd = fs.openSync(file, C.O_WRONLY | C.O_CREAT | C.O_NONBLOCK | C.O_NOFOLLOW, 0o644);