@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/shared.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import type
|
|
1
|
+
import { type SandboxRoots } from "@capybara-hq/plugin-sdk";
|
|
2
|
+
import type { SandboxMode } from "../state.js";
|
|
2
3
|
import { DeviceOpError } from "./types.js";
|
|
3
4
|
/** The file that marks a directory as a device directory this program has used. */
|
|
4
5
|
export declare const ROOT_MARKER = ".capybara-device";
|
|
@@ -7,25 +8,11 @@ export declare const PIPE_GRACE_MS = 200;
|
|
|
7
8
|
export declare const ENV_NAME_RE: RegExp;
|
|
8
9
|
/** The roots of a device directory: `<dir>/workspace`, `<dir>/skills`, `<dir>/tmp`. */
|
|
9
10
|
export declare function osRoots(dir: string): SandboxRoots;
|
|
10
|
-
/** The device's package caches: `<dir>/cache`, outside the workspace (spec §5.2.1). */
|
|
11
|
-
export declare function cacheRoot(dir: string): string;
|
|
12
|
-
/**
|
|
13
|
-
* The cache variables of `dev` / `open` (spec §5.2.1), each pointing at a folder of `root`
|
|
14
|
-
* (`MAVEN_OPTS` as `-Dmaven.repo.local=<folder>`). With `create` (on the host, before a
|
|
15
|
-
* sandboxed command), the root is made a real directory first ({@link ensureCacheRoot}) and the
|
|
16
|
-
* folders are made on demand; a folder that cannot be made leaves its variable out, and a root
|
|
17
|
-
* that cannot be made, or that was swapped while the folders were made, leaves every variable
|
|
18
|
-
* out, so a broken cache never stops the next command. A command's
|
|
19
|
-
* own value wins: callers apply the request's environment after these.
|
|
20
|
-
*/
|
|
21
|
-
export declare function cacheEnv(root: string, opts?: {
|
|
22
|
-
create?: boolean;
|
|
23
|
-
}): Record<string, string>;
|
|
24
11
|
/**
|
|
25
12
|
* The data directories of version managers, relative to the home: the OS sandbox sets HOME to the
|
|
26
13
|
* workspace, so their shims would look there and fail ("unknown command: python3. Perhaps you
|
|
27
14
|
* have to reshim?"). mise's follow XDG_DATA_HOME / XDG_CONFIG_HOME when the device's environment
|
|
28
|
-
* sets them.
|
|
15
|
+
* sets them.
|
|
29
16
|
*/
|
|
30
17
|
export declare const TOOL_HOME_DIRS: readonly (readonly [string, string])[];
|
|
31
18
|
/**
|
|
@@ -37,20 +24,6 @@ export declare const TOOL_HOME_DIRS: readonly (readonly [string, string])[];
|
|
|
37
24
|
* home.
|
|
38
25
|
*/
|
|
39
26
|
export declare function toolHomeEnv(home: string, env?: Record<string, string | undefined>): Record<string, string>;
|
|
40
|
-
/**
|
|
41
|
-
* The short socket directory of a device on macOS (spec §5.2.3): `<base>/cap-<first 8 hex of the
|
|
42
|
-
* device's key>`, short enough for Chromium's singleton socket (unix socket paths stop at 104
|
|
43
|
-
* bytes). `base` is `/private/tmp` outside tests.
|
|
44
|
-
*/
|
|
45
|
-
export declare function socketDirPath(dirKey: string, base?: string): string;
|
|
46
|
-
/**
|
|
47
|
-
* Creates the socket directory (mode 0700), or checks an existing one is a real directory of this
|
|
48
|
-
* user and makes it 0700 again. The check and the mode change go through one descriptor opened
|
|
49
|
-
* without following links, so a link swapped in meanwhile (the shared /tmp is sticky, not
|
|
50
|
-
* private) is refused, never followed. Returns undefined when the path is taken by something else
|
|
51
|
-
* (another user's directory, a file or a link): commands then use the tmp root.
|
|
52
|
-
*/
|
|
53
|
-
export declare function prepareSocketDir(path: string, uid?: number | undefined): string | undefined;
|
|
54
27
|
/**
|
|
55
28
|
* The longest prefix of `b` that does not end inside a UTF-8 sequence (a cut buffer's tail is
|
|
56
29
|
* dropped instead of decoding to U+FFFD).
|
|
@@ -89,17 +62,29 @@ export declare class RootGuard {
|
|
|
89
62
|
ensure(): "ok" | "gone";
|
|
90
63
|
}
|
|
91
64
|
/**
|
|
92
|
-
* Host-side file access
|
|
93
|
-
*
|
|
65
|
+
* Host-side file access. In sandbox mode `path`s are confined to the three roots (real paths,
|
|
66
|
+
* symlinks resolved, refused when they leave a root); in auto mode any clean absolute path is
|
|
67
|
+
* accepted (shape checks only: absolute, no `..` segments, no control characters). Used for the
|
|
68
|
+
* skills root (commands can only read it, so nothing can race it) and by the host executor.
|
|
94
69
|
*/
|
|
95
70
|
export declare class HostFiles {
|
|
96
71
|
private readonly roots;
|
|
97
|
-
|
|
98
|
-
|
|
72
|
+
private readonly mode;
|
|
73
|
+
constructor(roots: SandboxRoots, mode: SandboxMode);
|
|
74
|
+
/**
|
|
75
|
+
* `path` made absolute and normalized; in sandbox mode refused unless it is lexically under a
|
|
76
|
+
* root, in auto mode accepted when its shape is clean.
|
|
77
|
+
*/
|
|
99
78
|
lexical(path: string): string;
|
|
100
|
-
/**
|
|
79
|
+
/**
|
|
80
|
+
* The real path of an existing `path` (null when missing); in sandbox mode refused unless under
|
|
81
|
+
* a root after resolving links.
|
|
82
|
+
*/
|
|
101
83
|
existing(path: string): Promise<string | null>;
|
|
102
|
-
/**
|
|
84
|
+
/**
|
|
85
|
+
* The real path of an existing `path` (symlinks resolved); in sandbox mode refused unless under
|
|
86
|
+
* a root.
|
|
87
|
+
*/
|
|
103
88
|
inside(path: string, what: string): Promise<string>;
|
|
104
89
|
private checkReal;
|
|
105
90
|
private rootList;
|
package/dist/exec/shared.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { constants, existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
|
|
2
2
|
import { lstat, mkdir, open, realpath } from "node:fs/promises";
|
|
3
3
|
import { basename, dirname, isAbsolute, join, resolve } from "node:path";
|
|
4
|
+
import { validateSandboxPathShape } from "@capybara-hq/plugin-sdk";
|
|
4
5
|
import { DeviceOpError } from "./types.js";
|
|
5
6
|
/** The file that marks a directory as a device directory this program has used. */
|
|
6
7
|
export const ROOT_MARKER = ".capybara-device";
|
|
@@ -11,122 +12,11 @@ export const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
|
11
12
|
export function osRoots(dir) {
|
|
12
13
|
return { workspace: join(dir, "workspace"), skills: join(dir, "skills"), tmp: join(dir, "tmp") };
|
|
13
14
|
}
|
|
14
|
-
/** The device's package caches: `<dir>/cache`, outside the workspace (spec §5.2.1). */
|
|
15
|
-
export function cacheRoot(dir) {
|
|
16
|
-
return join(dir, "cache");
|
|
17
|
-
}
|
|
18
|
-
/**
|
|
19
|
-
* Each cache variable of `dev` / `open` and its folder under the cache root. No pnpm store entry:
|
|
20
|
-
* pnpm 10 takes it only from `npm_config_store_dir`, and npm prints a warning about that unknown
|
|
21
|
-
* key on every command; pnpm keeps its store at its default under HOME (the workspace).
|
|
22
|
-
*/
|
|
23
|
-
const CACHE_DIRS = [
|
|
24
|
-
["XDG_CACHE_HOME", "xdg"],
|
|
25
|
-
["npm_config_cache", "npm"],
|
|
26
|
-
["PIP_CACHE_DIR", "pip"],
|
|
27
|
-
["UV_CACHE_DIR", "uv"],
|
|
28
|
-
["CARGO_HOME", "cargo"],
|
|
29
|
-
["GOMODCACHE", "go-mod"],
|
|
30
|
-
["GOCACHE", "go-build"],
|
|
31
|
-
["GRADLE_USER_HOME", "gradle"],
|
|
32
|
-
["MAVEN_OPTS", "maven"],
|
|
33
|
-
["PLAYWRIGHT_BROWSERS_PATH", "ms-playwright"],
|
|
34
|
-
["COREPACK_HOME", "corepack"],
|
|
35
|
-
];
|
|
36
|
-
/** The device and inode of a real directory (never through a link); undefined otherwise. */
|
|
37
|
-
function realDirId(path) {
|
|
38
|
-
try {
|
|
39
|
-
const st = lstatSync(path);
|
|
40
|
-
return st.isDirectory() ? `${st.dev}:${st.ino}` : undefined;
|
|
41
|
-
}
|
|
42
|
-
catch {
|
|
43
|
-
return undefined;
|
|
44
|
-
}
|
|
45
|
-
}
|
|
46
|
-
/**
|
|
47
|
-
* Makes the cache root a real directory and returns its identity. Sandboxed commands may write
|
|
48
|
-
* the root (it is under `<dir>/cache`), so they can replace it with a link to a host folder: a
|
|
49
|
-
* link, a file or anything else in its place is unlinked (never followed) and the root made
|
|
50
|
-
* again, mode 0700. Its real path must then be its parent's real path plus its name (nothing in
|
|
51
|
-
* between resolves elsewhere). Undefined when it cannot be made a real directory.
|
|
52
|
-
*/
|
|
53
|
-
function ensureCacheRoot(root) {
|
|
54
|
-
try {
|
|
55
|
-
const st = lstatSync(root);
|
|
56
|
-
// unlink, not rm: rm skips a link whose target is missing, and never recurse into a target.
|
|
57
|
-
if (!st.isDirectory())
|
|
58
|
-
unlinkSync(root);
|
|
59
|
-
}
|
|
60
|
-
catch (e) {
|
|
61
|
-
if (e.code !== "ENOENT")
|
|
62
|
-
return undefined;
|
|
63
|
-
}
|
|
64
|
-
try {
|
|
65
|
-
mkdirSync(root, { mode: 0o700 });
|
|
66
|
-
}
|
|
67
|
-
catch (e) {
|
|
68
|
-
if (e.code !== "EEXIST")
|
|
69
|
-
return undefined;
|
|
70
|
-
}
|
|
71
|
-
try {
|
|
72
|
-
if (realpathSync(root) !== join(realpathSync(dirname(root)), basename(root)))
|
|
73
|
-
return undefined;
|
|
74
|
-
}
|
|
75
|
-
catch {
|
|
76
|
-
return undefined;
|
|
77
|
-
}
|
|
78
|
-
return realDirId(root);
|
|
79
|
-
}
|
|
80
|
-
/**
|
|
81
|
-
* Makes one cache folder under a verified root: an existing real directory is used, a missing
|
|
82
|
-
* one is made (not recursively, so nothing is made through a link). A file or a link a command
|
|
83
|
-
* put in its place is left alone (never removed, never followed): its variable is left out.
|
|
84
|
-
*/
|
|
85
|
-
function ensureCacheFolder(path) {
|
|
86
|
-
if (realDirId(path) !== undefined)
|
|
87
|
-
return true;
|
|
88
|
-
try {
|
|
89
|
-
mkdirSync(path, { mode: 0o700 });
|
|
90
|
-
}
|
|
91
|
-
catch {
|
|
92
|
-
return false;
|
|
93
|
-
}
|
|
94
|
-
return realDirId(path) !== undefined;
|
|
95
|
-
}
|
|
96
|
-
/**
|
|
97
|
-
* The cache variables of `dev` / `open` (spec §5.2.1), each pointing at a folder of `root`
|
|
98
|
-
* (`MAVEN_OPTS` as `-Dmaven.repo.local=<folder>`). With `create` (on the host, before a
|
|
99
|
-
* sandboxed command), the root is made a real directory first ({@link ensureCacheRoot}) and the
|
|
100
|
-
* folders are made on demand; a folder that cannot be made leaves its variable out, and a root
|
|
101
|
-
* that cannot be made, or that was swapped while the folders were made, leaves every variable
|
|
102
|
-
* out, so a broken cache never stops the next command. A command's
|
|
103
|
-
* own value wins: callers apply the request's environment after these.
|
|
104
|
-
*/
|
|
105
|
-
export function cacheEnv(root, opts = {}) {
|
|
106
|
-
const create = opts.create === true;
|
|
107
|
-
const rootId = create ? ensureCacheRoot(root) : undefined;
|
|
108
|
-
if (create && rootId === undefined)
|
|
109
|
-
return {};
|
|
110
|
-
const out = {};
|
|
111
|
-
for (const [name, sub] of CACHE_DIRS) {
|
|
112
|
-
const path = join(root, sub);
|
|
113
|
-
if (create && !ensureCacheFolder(path))
|
|
114
|
-
continue;
|
|
115
|
-
out[name] = name === "MAVEN_OPTS" ? `-Dmaven.repo.local=${path}` : path;
|
|
116
|
-
}
|
|
117
|
-
// A concurrent command may have swapped the root meanwhile: then trust none of the folders.
|
|
118
|
-
// Accepted narrow race: a swap between ensureCacheRoot and a folder's mkdir makes that one
|
|
119
|
-
// fixed-name folder (mode 0700, empty) in the link's target. Nothing is removed or followed
|
|
120
|
-
// further, and this recheck of the root's device and inode drops every variable.
|
|
121
|
-
if (create && realDirId(root) !== rootId)
|
|
122
|
-
return {};
|
|
123
|
-
return out;
|
|
124
|
-
}
|
|
125
15
|
/**
|
|
126
16
|
* The data directories of version managers, relative to the home: the OS sandbox sets HOME to the
|
|
127
17
|
* workspace, so their shims would look there and fail ("unknown command: python3. Perhaps you
|
|
128
18
|
* have to reshim?"). mise's follow XDG_DATA_HOME / XDG_CONFIG_HOME when the device's environment
|
|
129
|
-
* sets them.
|
|
19
|
+
* sets them.
|
|
130
20
|
*/
|
|
131
21
|
export const TOOL_HOME_DIRS = [
|
|
132
22
|
["ASDF_DATA_DIR", ".asdf"],
|
|
@@ -178,51 +68,6 @@ export function toolHomeEnv(home, env = process.env) {
|
|
|
178
68
|
}
|
|
179
69
|
return out;
|
|
180
70
|
}
|
|
181
|
-
/**
|
|
182
|
-
* The short socket directory of a device on macOS (spec §5.2.3): `<base>/cap-<first 8 hex of the
|
|
183
|
-
* device's key>`, short enough for Chromium's singleton socket (unix socket paths stop at 104
|
|
184
|
-
* bytes). `base` is `/private/tmp` outside tests.
|
|
185
|
-
*/
|
|
186
|
-
export function socketDirPath(dirKey, base = "/private/tmp") {
|
|
187
|
-
return join(base, `cap-${dirKey.slice(0, 8)}`);
|
|
188
|
-
}
|
|
189
|
-
/**
|
|
190
|
-
* Creates the socket directory (mode 0700), or checks an existing one is a real directory of this
|
|
191
|
-
* user and makes it 0700 again. The check and the mode change go through one descriptor opened
|
|
192
|
-
* without following links, so a link swapped in meanwhile (the shared /tmp is sticky, not
|
|
193
|
-
* private) is refused, never followed. Returns undefined when the path is taken by something else
|
|
194
|
-
* (another user's directory, a file or a link): commands then use the tmp root.
|
|
195
|
-
*/
|
|
196
|
-
export function prepareSocketDir(path, uid = process.getuid?.()) {
|
|
197
|
-
try {
|
|
198
|
-
mkdirSync(path, { mode: 0o700 });
|
|
199
|
-
}
|
|
200
|
-
catch (e) {
|
|
201
|
-
if (e.code !== "EEXIST")
|
|
202
|
-
return undefined;
|
|
203
|
-
}
|
|
204
|
-
let fd;
|
|
205
|
-
try {
|
|
206
|
-
fd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
|
|
207
|
-
}
|
|
208
|
-
catch {
|
|
209
|
-
return undefined;
|
|
210
|
-
}
|
|
211
|
-
try {
|
|
212
|
-
const st = fstatSync(fd);
|
|
213
|
-
if (!st.isDirectory() || (uid !== undefined && st.uid !== uid))
|
|
214
|
-
return undefined;
|
|
215
|
-
if ((st.mode & 0o777) !== 0o700)
|
|
216
|
-
fchmodSync(fd, 0o700);
|
|
217
|
-
return path;
|
|
218
|
-
}
|
|
219
|
-
catch {
|
|
220
|
-
return undefined;
|
|
221
|
-
}
|
|
222
|
-
finally {
|
|
223
|
-
closeSync(fd);
|
|
224
|
-
}
|
|
225
|
-
}
|
|
226
71
|
/**
|
|
227
72
|
* The longest prefix of `b` that does not end inside a UTF-8 sequence (a cut buffer's tail is
|
|
228
73
|
* dropped instead of decoding to U+FFFD).
|
|
@@ -325,16 +170,29 @@ export class RootGuard {
|
|
|
325
170
|
}
|
|
326
171
|
}
|
|
327
172
|
/**
|
|
328
|
-
* Host-side file access
|
|
329
|
-
*
|
|
173
|
+
* Host-side file access. In sandbox mode `path`s are confined to the three roots (real paths,
|
|
174
|
+
* symlinks resolved, refused when they leave a root); in auto mode any clean absolute path is
|
|
175
|
+
* accepted (shape checks only: absolute, no `..` segments, no control characters). Used for the
|
|
176
|
+
* skills root (commands can only read it, so nothing can race it) and by the host executor.
|
|
330
177
|
*/
|
|
331
178
|
export class HostFiles {
|
|
332
179
|
roots;
|
|
333
|
-
|
|
180
|
+
mode;
|
|
181
|
+
constructor(roots, mode) {
|
|
334
182
|
this.roots = roots;
|
|
183
|
+
this.mode = mode;
|
|
335
184
|
}
|
|
336
|
-
/**
|
|
185
|
+
/**
|
|
186
|
+
* `path` made absolute and normalized; in sandbox mode refused unless it is lexically under a
|
|
187
|
+
* root, in auto mode accepted when its shape is clean.
|
|
188
|
+
*/
|
|
337
189
|
lexical(path) {
|
|
190
|
+
if (this.mode === "auto") {
|
|
191
|
+
const errors = validateSandboxPathShape(path);
|
|
192
|
+
if (errors.length > 0)
|
|
193
|
+
throw policyError(`${path}: ${errors.join("; ")}`);
|
|
194
|
+
return resolve(path);
|
|
195
|
+
}
|
|
338
196
|
if (!isAbsolute(path))
|
|
339
197
|
throw policyError(`${path} is not an absolute path`);
|
|
340
198
|
const p = resolve(path);
|
|
@@ -343,7 +201,10 @@ export class HostFiles {
|
|
|
343
201
|
}
|
|
344
202
|
return p;
|
|
345
203
|
}
|
|
346
|
-
/**
|
|
204
|
+
/**
|
|
205
|
+
* The real path of an existing `path` (null when missing); in sandbox mode refused unless under
|
|
206
|
+
* a root after resolving links.
|
|
207
|
+
*/
|
|
347
208
|
async existing(path) {
|
|
348
209
|
const p = this.lexical(path);
|
|
349
210
|
let real;
|
|
@@ -357,7 +218,10 @@ export class HostFiles {
|
|
|
357
218
|
}
|
|
358
219
|
return this.checkReal(path, real);
|
|
359
220
|
}
|
|
360
|
-
/**
|
|
221
|
+
/**
|
|
222
|
+
* The real path of an existing `path` (symlinks resolved); in sandbox mode refused unless under
|
|
223
|
+
* a root.
|
|
224
|
+
*/
|
|
361
225
|
async inside(path, what) {
|
|
362
226
|
const p = this.lexical(path);
|
|
363
227
|
let real;
|
|
@@ -372,6 +236,8 @@ export class HostFiles {
|
|
|
372
236
|
return this.checkReal(path, real);
|
|
373
237
|
}
|
|
374
238
|
async checkReal(path, real) {
|
|
239
|
+
if (this.mode === "auto")
|
|
240
|
+
return real;
|
|
375
241
|
const roots = await Promise.all(this.rootList().map((r) => realpath(r).catch(() => r)));
|
|
376
242
|
if (!roots.some((r) => isUnder(real, r))) {
|
|
377
243
|
throw policyError(`${path} resolves to ${real}, outside the device's roots`);
|
package/dist/exec/switch.d.ts
CHANGED
|
@@ -1,51 +1,27 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { type TierLimits } from "../policy.js";
|
|
3
|
-
import type { ProxyGuardResult } from "../proxy-guard.js";
|
|
1
|
+
import type { DeviceExecArgs, ExecResult, SandboxLimits, SandboxRoots } from "@capybara-hq/plugin-sdk";
|
|
4
2
|
import type { Policy } from "../state.js";
|
|
5
|
-
import { type
|
|
6
|
-
export type {
|
|
3
|
+
import { type ExecMode, type Executor } from "./types.js";
|
|
4
|
+
export type { ExecMode } from "./types.js";
|
|
7
5
|
/**
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
* Decides how one command runs (spec §5.4). Without a sandbox only when the local policy says
|
|
15
|
-
* `isolation: "none"` with its own tier `open` ({@link policyUnsandboxed}), the device runs in OS
|
|
16
|
-
* mode, the kernel allows it for this command (`limits.allowUnsandboxed`: the platform and the
|
|
17
|
-
* org allow it and an unattended run has its grant; absent counts as not allowed), and the
|
|
18
|
-
* command's tier (that choice cut to the org's ceiling) is `open`. When the policy says `none`
|
|
19
|
-
* but any of those does not hold, the command is refused, never run in the sandbox silently: the
|
|
20
|
-
* owner asked for no sandbox. The device enforces the kernel's decision itself, because the
|
|
21
|
-
* kernel knows the local policy only from the last hello or policy op (spec §4.3); its refusal is
|
|
22
|
-
* {@link UNSANDBOXED_NOT_ALLOWED_MESSAGE}, which the kernel maps to its own error. Docker mode
|
|
23
|
-
* ignores `isolation` (its container is the isolation).
|
|
24
|
-
*/
|
|
25
|
-
export declare function execIsolation(policy: Pick<Policy, "tier" | "isolation">, limits: ExecLimits, mode: Executor["mode"]): ExecIsolation;
|
|
26
|
-
/** What {@link execIsolation} reads of an exec's limits. */
|
|
27
|
-
export type ExecLimits = TierLimits & Pick<SandboxLimits, "allowUnsandboxed">;
|
|
28
|
-
/** The refusal of a command the policy asks to run without a sandbox below tier `open`. */
|
|
29
|
-
export declare function unsandboxedRefusal(policy: Pick<Policy, "tier">, tier: SandboxTier): string;
|
|
30
|
-
/**
|
|
31
|
-
* How long the latest command's limits decide file operations. The kernel judges the org's
|
|
32
|
-
* settings at each exec, and file operations carry no limits, so an unsandboxed decision older
|
|
33
|
-
* than this no longer counts: file operations fall back to the sandboxed helper, which reads and
|
|
34
|
-
* writes the same roots (only slower), until the next command decides again. A minute covers a
|
|
35
|
-
* turn's file operations around its commands while bounding how long an org's change (or a lower
|
|
36
|
-
* ceiling) takes to reach a device that runs no more commands.
|
|
6
|
+
* How long the latest command's limits decide file operations. The kernel judges the mode at each
|
|
7
|
+
* exec, and file operations carry no limits, so a decision older than this no longer counts: file
|
|
8
|
+
* operations fall back to the sandboxed helper (the safe default for an organization whose ceiling
|
|
9
|
+
* is sandbox), until the next command decides again. A minute covers a turn's file operations
|
|
10
|
+
* around its commands while bounding how long an organization's change takes to reach a device
|
|
11
|
+
* that runs no more commands.
|
|
37
12
|
*/
|
|
38
13
|
export declare const FILE_OPS_DECISION_TTL_MS = 60000;
|
|
39
|
-
/** The refusal of an
|
|
14
|
+
/** The refusal of an auto-mode command whose sandbox was turned back on before it started. */
|
|
40
15
|
export declare const SANDBOX_BACK_ON: string;
|
|
41
16
|
/**
|
|
42
|
-
* The OS-mode executor the program serves: each command runs in the
|
|
43
|
-
* {@link
|
|
44
|
-
* applies at
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
17
|
+
* The OS-mode executor the program serves: each command runs in the sandbox or, in auto mode,
|
|
18
|
+
* directly on the machine ({@link effectiveMode}). The policy is read per operation, so a change
|
|
19
|
+
* applies at the next command. File operations use the host executor's direct IO (any absolute
|
|
20
|
+
* path in auto mode, the roots in the sandbox) only while the latest command's decision is fresh;
|
|
21
|
+
* before any command, or once its limits are stale, the sandboxed helper runs (file operations
|
|
22
|
+
* never pass command review, so the org's ceiling may not be exceeded). When the policy turns the
|
|
23
|
+
* sandbox back on, every auto-mode command still running (and what it left in the background) is
|
|
24
|
+
* killed, and one still starting is refused right before its spawn; while auto mode is on, the
|
|
49
25
|
* policy is also checked every second so that happens without waiting for the next operation.
|
|
50
26
|
* Kills reach both executors' commands.
|
|
51
27
|
*/
|
|
@@ -57,38 +33,47 @@ export declare class SwitchingExecutor implements Executor {
|
|
|
57
33
|
private readonly onSwitch?;
|
|
58
34
|
readonly mode: "os";
|
|
59
35
|
readonly roots: SandboxRoots;
|
|
60
|
-
/** The policy
|
|
61
|
-
private
|
|
36
|
+
/** The policy said auto mode when last checked. */
|
|
37
|
+
private auto;
|
|
38
|
+
/**
|
|
39
|
+
* Whether the OS sandbox can run here. When it cannot, sandbox-mode operations go to the
|
|
40
|
+
* sandboxed executor and are refused there with the reason; auto mode keeps working.
|
|
41
|
+
*/
|
|
42
|
+
private readonly sandboxReady;
|
|
62
43
|
private watch;
|
|
63
44
|
/** The latest command's limits and when they came (file operations follow their decision). */
|
|
64
45
|
private lastLimits;
|
|
65
46
|
private lastLimitsAt;
|
|
66
47
|
constructor(sandboxed: Executor,
|
|
67
48
|
/** Runs commands without a sandbox (the `HostExecutor`). */
|
|
68
|
-
host: Executor, policy: () => Policy, onSwitch?: ((
|
|
49
|
+
host: Executor, policy: () => Policy, onSwitch?: ((mode: "auto" | "sandbox") => void) | undefined);
|
|
69
50
|
/**
|
|
70
|
-
* Rereads the policy; on a change fires `onSwitch` and, when the sandbox came back on, kills
|
|
71
|
-
*
|
|
51
|
+
* Rereads the policy; on a change fires `onSwitch` and, when the sandbox came back on, kills the
|
|
52
|
+
* auto-mode commands. Returns whether the policy says auto mode now.
|
|
72
53
|
*/
|
|
73
54
|
sync(policy?: Policy): Promise<boolean>;
|
|
74
55
|
/**
|
|
75
56
|
* Records an exec's limits, refused ones included, so file operations follow the latest
|
|
76
57
|
* decision (see {@link FILE_OPS_DECISION_TTL_MS}).
|
|
77
58
|
*/
|
|
78
|
-
noteLimits(limits:
|
|
59
|
+
noteLimits(limits: Pick<SandboxLimits, "mode">): void;
|
|
79
60
|
/**
|
|
80
|
-
* The executor for file operations now
|
|
81
|
-
*
|
|
61
|
+
* The executor for file operations now. File operations carry no limits and never pass command
|
|
62
|
+
* review, so they only follow an exec's decision when it is fresh: the sandboxed helper before
|
|
63
|
+
* any exec and once those limits are stale (the safe default for an organization whose ceiling
|
|
64
|
+
* is sandbox), else `effectiveMode(policy, limits)`. On a machine without the OS sandbox, auto
|
|
65
|
+
* mode still works: without a fresh sandbox decision the host runs them (a sandbox decision is
|
|
66
|
+
* refused by the sandboxed executor with the reason).
|
|
82
67
|
*/
|
|
83
68
|
private files;
|
|
84
69
|
exec(args: DeviceExecArgs, signal: AbortSignal): Promise<ExecResult>;
|
|
85
70
|
/**
|
|
86
71
|
* Runs one command as `how` decided (the caller logs the same decision). The policy it was
|
|
87
|
-
* decided on is synced first, so a sandbox turned back on stops the
|
|
88
|
-
*
|
|
72
|
+
* decided on is synced first, so a sandbox turned back on stops the auto-mode commands. An
|
|
73
|
+
* auto-mode command is decided again on the policy then, right before its spawn: one whose
|
|
89
74
|
* sandbox came back on while it was starting is refused ({@link SANDBOX_BACK_ON}).
|
|
90
75
|
*/
|
|
91
|
-
execDecided(args: DeviceExecArgs, signal: AbortSignal, how:
|
|
76
|
+
execDecided(args: DeviceExecArgs, signal: AbortSignal, how: ExecMode, policy?: Policy): Promise<ExecResult>;
|
|
92
77
|
readFile(path: string, maxBytes: number): Promise<{
|
|
93
78
|
data: Uint8Array;
|
|
94
79
|
truncated: boolean;
|
|
@@ -101,8 +86,6 @@ export declare class SwitchingExecutor implements Executor {
|
|
|
101
86
|
killTagged(tags: string[]): Promise<void>;
|
|
102
87
|
killAll(): Promise<void>;
|
|
103
88
|
ensureRoot(): Promise<"ok" | "gone">;
|
|
104
|
-
/** The sandboxed executor's latest localhost proxy guard result (see `Executor`). */
|
|
105
|
-
proxyGuard(): ProxyGuardResult;
|
|
106
89
|
/** Stops watching the policy. */
|
|
107
90
|
dispose(): void;
|
|
108
91
|
}
|