@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.
Files changed (50) hide show
  1. package/README.md +106 -189
  2. package/dist/api.d.ts +5 -0
  3. package/dist/args.d.ts +8 -3
  4. package/dist/args.js +38 -19
  5. package/dist/cli.d.ts +7 -5
  6. package/dist/cli.js +20 -31
  7. package/dist/client.d.ts +0 -2
  8. package/dist/client.js +23 -12
  9. package/dist/command-log.d.ts +3 -5
  10. package/dist/commands/login.js +55 -1
  11. package/dist/commands/mode.d.ts +52 -0
  12. package/dist/commands/mode.js +108 -0
  13. package/dist/commands/policy.d.ts +11 -65
  14. package/dist/commands/policy.js +62 -249
  15. package/dist/commands/service.d.ts +4 -3
  16. package/dist/commands/service.js +30 -2
  17. package/dist/commands/start.d.ts +2 -2
  18. package/dist/commands/start.js +14 -6
  19. package/dist/commands/status.js +11 -3
  20. package/dist/exec/docker.d.ts +22 -30
  21. package/dist/exec/docker.js +81 -69
  22. package/dist/exec/fs-helper.d.ts +13 -8
  23. package/dist/exec/fs-helper.js +30 -12
  24. package/dist/exec/host.d.ts +8 -8
  25. package/dist/exec/host.js +9 -9
  26. package/dist/exec/os.d.ts +36 -69
  27. package/dist/exec/os.js +65 -159
  28. package/dist/exec/sandbox-messages.d.ts +14 -0
  29. package/dist/exec/sandbox-messages.js +21 -0
  30. package/dist/exec/shared.d.ts +21 -36
  31. package/dist/exec/shared.js +30 -164
  32. package/dist/exec/switch.d.ts +38 -55
  33. package/dist/exec/switch.js +58 -108
  34. package/dist/exec/types.d.ts +8 -18
  35. package/dist/index.d.ts +1 -1
  36. package/dist/network.d.ts +7 -7
  37. package/dist/network.js +11 -18
  38. package/dist/policy-store.d.ts +7 -8
  39. package/dist/policy-store.js +11 -15
  40. package/dist/policy.d.ts +25 -100
  41. package/dist/policy.js +44 -146
  42. package/dist/server-ops.d.ts +15 -35
  43. package/dist/server-ops.js +36 -117
  44. package/dist/service/launchd.d.ts +11 -1
  45. package/dist/service/launchd.js +14 -5
  46. package/dist/state.d.ts +15 -16
  47. package/dist/state.js +38 -36
  48. package/package.json +2 -2
  49. package/dist/proxy-guard.d.ts +0 -58
  50. package/dist/proxy-guard.js +0 -137
@@ -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 { ANY_HOST, deviceTier, effectiveEgress, provisionalTier, tierFacts, } 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";
@@ -26,31 +27,6 @@ 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
- /**
30
- * The container's `--shm-size` for a tier (spec §5.2): `strict` keeps Docker's default (64 MiB);
31
- * `dev` and `open` get a quarter of the memory ceiling up to 1 GiB (at least the default), or
32
- * 1 GiB without a ceiling, so browsers have room.
33
- */
34
- export function shmSize(tier, memoryMb) {
35
- if (tier === "strict")
36
- return undefined;
37
- if (memoryMb === null)
38
- return "1g";
39
- return `${Math.max(64, Math.min(1024, Math.floor(memoryMb / 4)))}m`;
40
- }
41
- /**
42
- * Whether a command gets the default bridge (spec §5.2 table). Docker mode has no domain filter,
43
- * and the bridge reaches the host and the intranet, so only an explicit choice opens it: the
44
- * device's own allowed domains within the ceiling (as `strict` computes them; the dev hosts do
45
- * not count), or tier `open` with a ceiling that allows any host (an allowlist ceiling at `open`
46
- * counts only its explicit local domains, like the lower tiers).
47
- */
48
- export function bridgeNetwork(policy, limits) {
49
- if (deviceTier(policy, limits) === "open" && effectiveEgress(policy, limits).includes(ANY_HOST)) {
50
- return true;
51
- }
52
- return effectiveEgress({ ...policy, tier: "strict" }, limits).length > 0;
53
- }
54
30
  /** Container name of a device. */
55
31
  export function containerName(deviceId) {
56
32
  return `capybara-device-${deviceId}`;
@@ -116,32 +92,47 @@ done; done; exit 0`;
116
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';
117
93
  /** The pids limit of a container (as the cloud sandbox). */
118
94
  const PIDS_LIMIT = 1024;
119
- /** The shared prologue of the file scripts: `under` checks a real path against the three roots. */
120
- const FILE_PROLOGUE = `under() { case "$1" in /workspace|/workspace/*|/tmp|/tmp/*) return 0;; esac; return 1; }
121
- `;
122
95
  // Exit codes of the file scripts.
96
+ const E_MODE = 9;
123
97
  const E_MISSING = 10;
124
98
  const E_OUTSIDE = 11;
125
99
  const E_NOT_FILE = 12;
126
100
  const E_FAIL = 13;
127
101
  const E_DANGLING = 14;
128
- const READ_SCRIPT = `${FILE_PROLOGUE}r=$(realpath -e -- "$1" 2>/dev/null) || exit ${E_MISSING}
129
- 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}
130
121
  [ -d "$r" ] && exit ${E_MISSING}
131
122
  [ -f "$r" ] || exit ${E_NOT_FILE}
132
- head -c "$2" -- "$r"`;
133
- const STAT_SCRIPT = `${FILE_PROLOGUE}r=$(realpath -e -- "$1" 2>/dev/null) || exit ${E_MISSING}
134
- 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}
135
126
  if [ -d "$r" ]; then printf '%s d' "$(stat -c %s -- "$r")"; else printf '%s f' "$(stat -c %s -- "$r")"; fi`;
136
- const WRITE_SCRIPT = `${FILE_PROLOGUE}p=$1; d=$(dirname -- "$p"); a=$d
127
+ const WRITE_SCRIPT = `${FILE_PROLOGUE}d=$(dirname -- "$p"); a=$d
137
128
  while [ ! -e "$a" ] && [ "$a" != / ]; do a=$(dirname -- "$a"); done
138
129
  ra=$(realpath -e -- "$a" 2>/dev/null) || exit ${E_FAIL}
139
- under "$ra" || exit ${E_OUTSIDE}
130
+ allowed "$ra" || exit ${E_OUTSIDE}
140
131
  mkdir -p -- "$d" || exit ${E_FAIL}
141
132
  rp=$(realpath -e -- "$d" 2>/dev/null) || exit ${E_FAIL}
142
- under "$rp" || exit ${E_OUTSIDE}
133
+ allowed "$rp" || exit ${E_OUTSIDE}
143
134
  f="$rp/$(basename -- "$p")"
144
- 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
145
136
  if [ -e "$f" ] && [ ! -f "$f" ]; then exit ${E_NOT_FILE}; fi
146
137
  cat > "$f" || exit ${E_FAIL}`;
147
138
  /**
@@ -150,10 +141,10 @@ cat > "$f" || exit ${E_FAIL}`;
150
141
  * /workspace, /skills and /tmp. Workspace and tmp files are read and written inside the container
151
142
  * (as the `sandbox` user, so a link a command plants resolves in the container and never on the
152
143
  * host); the skills directory, which commands cannot write, is accessed from the host with the
153
- * same real-path checks as the OS executor. Network: none unless {@link bridgeNetwork} says
154
- * otherwise, then the default bridge (Docker mode has no domain allowlist). Tiers `dev` and
155
- * `open` get a larger `/dev/shm` ({@link shmSize}); a change of the container's flags recreates it
156
- * at the next command that finds it idle.
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.
157
148
  */
158
149
  export class DockerExecutor {
159
150
  opts;
@@ -175,8 +166,10 @@ export class DockerExecutor {
175
166
  queue = [];
176
167
  pumping = false;
177
168
  dirty = false;
178
- /** The limits of the latest command: they decide the tier the container is made for. */
169
+ /** The limits of the latest command: the kernel's mode ceiling for file operations. */
179
170
  lastLimits;
171
+ /** When {@link lastLimits} came (file operations follow it only inside the window). */
172
+ lastLimitsAt = 0;
180
173
  /** The spec hash of the container in use (set when it is created or reused). */
181
174
  spec;
182
175
  constructor(opts) {
@@ -185,7 +178,7 @@ export class DockerExecutor {
185
178
  this.dir = existsSync(dir) ? realpathSync(dir) : dir;
186
179
  this.hostRoots = osRoots(this.dir);
187
180
  this.guard = new RootGuard(this.dir, this.hostRoots);
188
- this.hostFiles = new HostFiles(this.hostRoots);
181
+ this.hostFiles = new HostFiles(this.hostRoots, "sandbox");
189
182
  this.name = containerName(opts.deviceId);
190
183
  this.dirKey = createHash("sha256").update(this.dir).digest("hex").slice(0, 16);
191
184
  }
@@ -213,20 +206,22 @@ export class DockerExecutor {
213
206
  { source: this.hostRoots.tmp, dest: ROOTS.tmp, rw: true },
214
207
  ];
215
208
  }
216
- /** The tier commands run at now (the owner's choice, else `dev`, before any command). */
217
- tier(policy = this.opts.policy()) {
218
- return this.lastLimits === undefined
219
- ? provisionalTier(policy)
220
- : deviceTier(policy, this.lastLimits);
221
- }
222
- /** What the tier gives in this mode (for the policy summary). */
223
- tierFacts(policy = this.opts.policy()) {
224
- return tierFacts(policy, this.lastLimits, { proxyDetected: false, mode: "docker" });
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);
225
221
  }
226
222
  /** Every `docker run` flag of the container except its name and spec label. */
227
223
  runArgs() {
228
224
  const policy = this.opts.policy();
229
- const shm = shmSize(this.tier(policy), policy.memoryMb);
230
225
  return [
231
226
  "--init",
232
227
  "--read-only",
@@ -250,7 +245,6 @@ export class DockerExecutor {
250
245
  ...(policy.memoryMb !== null
251
246
  ? ["--memory", `${policy.memoryMb}m`, "--memory-swap", `${policy.memoryMb}m`]
252
247
  : []),
253
- ...(shm !== undefined ? ["--shm-size", shm] : []),
254
248
  "--entrypoint",
255
249
  "sleep",
256
250
  SANDBOX_IMAGE,
@@ -277,7 +271,7 @@ export class DockerExecutor {
277
271
  /**
278
272
  * Creates the container, or reuses the existing one when it matches; call inside `serial`.
279
273
  * A file operation (`anySpec`) reuses any container that sees the directory: it needs no
280
- * particular flags, and before the first command the tier is not known yet. The next command
274
+ * particular flags, and before the first command the policy is not known yet. The next command
281
275
  * that finds it idle recreates it if its flags differ.
282
276
  */
283
277
  async ensureContainer(opts = {}) {
@@ -402,7 +396,7 @@ export class DockerExecutor {
402
396
  let served;
403
397
  try {
404
398
  served = await this.serial(async () => {
405
- // The policy or the tier changed the container's flags (shm, cpu, memory): recreate
399
+ // The policy or the mode changed the container's flags (shm, cpu, memory): recreate
406
400
  // it once nothing runs in it.
407
401
  if (this.ready && this.inflight === 0 && this.spec !== this.specHash()) {
408
402
  this.ready = false;
@@ -452,7 +446,8 @@ export class DockerExecutor {
452
446
  }
453
447
  async exec(args, signal) {
454
448
  signal.throwIfAborted();
455
- 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);
456
451
  const env = {
457
452
  HOME: ROOTS.workspace,
458
453
  TERM: "dumb",
@@ -465,7 +460,9 @@ export class DockerExecutor {
465
460
  throw policyError(`invalid environment variable name ${JSON.stringify(k)}`);
466
461
  }
467
462
  this.lastLimits = args.limits;
468
- const open = bridgeNetwork(this.opts.policy(), 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";
469
466
  await this.acquire(open, signal);
470
467
  try {
471
468
  signal.throwIfAborted();
@@ -596,8 +593,17 @@ export class DockerExecutor {
596
593
  child.once("close", () => finish());
597
594
  });
598
595
  }
599
- /** `path` made absolute and normalized; refused unless lexically under a root. */
600
- 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
+ }
601
607
  if (!path.startsWith("/"))
602
608
  throw policyError(`${path} is not an absolute path`);
603
609
  const p = resolve(path);
@@ -615,7 +621,7 @@ export class DockerExecutor {
615
621
  return isUnder(p, ROOTS.skills);
616
622
  }
617
623
  /** Runs one file script in the container; `null` for a missing file. */
618
- async fileOp(script, path, arg2, input) {
624
+ async fileOp(script, mode, path, arg2, input) {
619
625
  // A file operation does not need the network; it runs on whichever state the container has.
620
626
  await this.serial(() => this.ensureContainer({ anySpec: true }));
621
627
  const r = await docker([
@@ -630,6 +636,7 @@ export class DockerExecutor {
630
636
  "-c",
631
637
  script,
632
638
  "capybara-file",
639
+ mode,
633
640
  path,
634
641
  arg2,
635
642
  ], {
@@ -642,6 +649,8 @@ export class DockerExecutor {
642
649
  switch (r.code) {
643
650
  case 0:
644
651
  return r;
652
+ case E_MODE:
653
+ throw new DeviceOpError("policy", `missing or unknown mode for ${path}`);
645
654
  case E_MISSING:
646
655
  return null;
647
656
  case E_OUTSIDE:
@@ -656,10 +665,11 @@ export class DockerExecutor {
656
665
  }
657
666
  }
658
667
  async readFile(path, maxBytes) {
659
- const p = this.containerPath(path);
668
+ const mode = this.modeNow();
669
+ const p = this.containerPath(path, mode);
660
670
  if (this.inSkills(p))
661
671
  return this.hostFiles.read(this.skillsHostPath(p), maxBytes);
662
- const r = await this.fileOp(READ_SCRIPT, p, String(maxBytes + 1));
672
+ const r = await this.fileOp(READ_SCRIPT, mode, p, String(maxBytes + 1));
663
673
  if (r === null)
664
674
  return null;
665
675
  return {
@@ -668,16 +678,18 @@ export class DockerExecutor {
668
678
  };
669
679
  }
670
680
  async writeFile(path, data) {
671
- const p = this.containerPath(path);
681
+ const mode = this.modeNow();
682
+ const p = this.containerPath(path, mode);
672
683
  if (this.inSkills(p))
673
684
  return this.hostFiles.write(this.skillsHostPath(p), data);
674
- await this.fileOp(WRITE_SCRIPT, p, "", data);
685
+ await this.fileOp(WRITE_SCRIPT, mode, p, "", data);
675
686
  }
676
687
  async stat(path) {
677
- const p = this.containerPath(path);
688
+ const mode = this.modeNow();
689
+ const p = this.containerPath(path, mode);
678
690
  if (this.inSkills(p))
679
691
  return this.hostFiles.stat(this.skillsHostPath(p));
680
- const r = await this.fileOp(STAT_SCRIPT, p, "");
692
+ const r = await this.fileOp(STAT_SCRIPT, mode, p, "");
681
693
  if (r === null)
682
694
  return null;
683
695
  const [size, kind] = r.stdout.toString("utf8").split(" ");
@@ -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 device'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
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);
@@ -7,16 +7,16 @@ export interface HostExecutorOptions {
7
7
  env?: NodeJS.ProcessEnv;
8
8
  }
9
9
  /**
10
- * Runs commands without a sandbox (spec §5.4): `/bin/bash -c` directly on this machine as the
10
+ * Runs commands without a sandbox (spec §4.1): `/bin/bash -c` directly on this machine as the
11
11
  * user, with this program's own environment plus the request's, so commands see the real `HOME`,
12
- * `PATH`, credentials, Docker and network. Only the device owner turns it on, locally
13
- * (`isolation: "none"` with tier `open`, OS mode); the program picks this executor per command
14
- * (see `exec/switch.ts`).
12
+ * `PATH`, credentials, Docker and network. That is auto mode; the program picks this executor per
13
+ * command (see `exec/switch.ts`) when no sandbox is in force.
15
14
  *
16
- * What stays the same as the OS sandbox: the working directory is checked inside the device's
17
- * roots, file operations are confined to the roots (direct host IO), and every command leads its
18
- * own process group and carries {@link EXEC_MARKER}, so timeouts, aborts, `killTagged` and
19
- * `killAll` reach it and what it leaves running.
15
+ * What stays the same as the OS sandbox: the working directory defaults to the device's workspace,
16
+ * every command leads its own process group and carries {@link EXEC_MARKER}, so timeouts, aborts,
17
+ * `killTagged` and `killAll` reach it and what it leaves running. File operations reach any
18
+ * absolute path on the machine (the kernel's `Read` / `Write` / `Edit` / `Glob` / `Grep` do, and
19
+ * the deployment reviews writes outside the workspace, spec §5.1).
20
20
  */
21
21
  export declare class HostExecutor implements Executor {
22
22
  private readonly opts;
package/dist/exec/host.js CHANGED
@@ -6,16 +6,16 @@ import { dirKeyOf, GroupTracker } from "./groups.js";
6
6
  import { EXEC_MARKER, killMarked } from "./procs.js";
7
7
  import { ENV_NAME_RE, HostFiles, OutputCap, osRoots, PIPE_GRACE_MS, policyError, RootGuard, } from "./shared.js";
8
8
  /**
9
- * Runs commands without a sandbox (spec §5.4): `/bin/bash -c` directly on this machine as the
9
+ * Runs commands without a sandbox (spec §4.1): `/bin/bash -c` directly on this machine as the
10
10
  * user, with this program's own environment plus the request's, so commands see the real `HOME`,
11
- * `PATH`, credentials, Docker and network. Only the device owner turns it on, locally
12
- * (`isolation: "none"` with tier `open`, OS mode); the program picks this executor per command
13
- * (see `exec/switch.ts`).
11
+ * `PATH`, credentials, Docker and network. That is auto mode; the program picks this executor per
12
+ * command (see `exec/switch.ts`) when no sandbox is in force.
14
13
  *
15
- * What stays the same as the OS sandbox: the working directory is checked inside the device's
16
- * roots, file operations are confined to the roots (direct host IO), and every command leads its
17
- * own process group and carries {@link EXEC_MARKER}, so timeouts, aborts, `killTagged` and
18
- * `killAll` reach it and what it leaves running.
14
+ * What stays the same as the OS sandbox: the working directory defaults to the device's workspace,
15
+ * every command leads its own process group and carries {@link EXEC_MARKER}, so timeouts, aborts,
16
+ * `killTagged` and `killAll` reach it and what it leaves running. File operations reach any
17
+ * absolute path on the machine (the kernel's `Read` / `Write` / `Edit` / `Glob` / `Grep` do, and
18
+ * the deployment reviews writes outside the workspace, spec §5.1).
19
19
  */
20
20
  export class HostExecutor {
21
21
  opts;
@@ -33,7 +33,7 @@ export class HostExecutor {
33
33
  this.dir = existsSync(dir) ? realpathSync(dir) : dir;
34
34
  this.roots = osRoots(this.dir);
35
35
  this.guard = new RootGuard(this.dir, this.roots);
36
- this.files = new HostFiles(this.roots);
36
+ this.files = new HostFiles(this.roots, "auto");
37
37
  this.dirKey = dirKeyOf(this.dir);
38
38
  }
39
39
  async ensureRoot() {