@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/docker.js
CHANGED
|
@@ -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 {
|
|
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
|
-
|
|
129
|
-
|
|
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 "$
|
|
133
|
-
const STAT_SCRIPT = `${FILE_PROLOGUE}r=$(realpath -e -- "$
|
|
134
|
-
|
|
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}
|
|
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
|
-
|
|
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
|
-
|
|
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};
|
|
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.
|
|
154
|
-
*
|
|
155
|
-
*
|
|
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:
|
|
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
|
-
/**
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
/**
|
|
600
|
-
|
|
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
|
|
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
|
|
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
|
|
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(" ");
|
package/dist/exec/fs-helper.d.ts
CHANGED
|
@@ -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
|
|
4
|
-
*
|
|
5
|
-
*
|
|
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
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
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 (!
|
|
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";
|
package/dist/exec/fs-helper.js
CHANGED
|
@@ -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
|
|
4
|
-
*
|
|
5
|
-
*
|
|
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
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
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 (!
|
|
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 || !
|
|
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 (!
|
|
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 (!
|
|
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);
|
package/dist/exec/host.d.ts
CHANGED
|
@@ -7,16 +7,16 @@ export interface HostExecutorOptions {
|
|
|
7
7
|
env?: NodeJS.ProcessEnv;
|
|
8
8
|
}
|
|
9
9
|
/**
|
|
10
|
-
* Runs commands without a sandbox (spec §
|
|
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.
|
|
13
|
-
* (
|
|
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
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
* `
|
|
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 §
|
|
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.
|
|
12
|
-
* (
|
|
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
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
* `
|
|
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() {
|