@capybara-hq/device 0.1.0-rc.8 → 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 (46) hide show
  1. package/README.md +90 -179
  2. package/dist/api.d.ts +5 -0
  3. package/dist/args.d.ts +7 -2
  4. package/dist/args.js +33 -16
  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 +9 -10
  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/start.d.ts +2 -2
  16. package/dist/commands/start.js +14 -6
  17. package/dist/commands/status.js +11 -3
  18. package/dist/exec/docker.d.ts +22 -30
  19. package/dist/exec/docker.js +81 -69
  20. package/dist/exec/fs-helper.d.ts +13 -8
  21. package/dist/exec/fs-helper.js +30 -12
  22. package/dist/exec/host.d.ts +8 -8
  23. package/dist/exec/host.js +9 -9
  24. package/dist/exec/os.d.ts +36 -69
  25. package/dist/exec/os.js +65 -159
  26. package/dist/exec/sandbox-messages.d.ts +14 -0
  27. package/dist/exec/sandbox-messages.js +21 -0
  28. package/dist/exec/shared.d.ts +21 -36
  29. package/dist/exec/shared.js +30 -164
  30. package/dist/exec/switch.d.ts +38 -55
  31. package/dist/exec/switch.js +58 -108
  32. package/dist/exec/types.d.ts +8 -18
  33. package/dist/index.d.ts +1 -1
  34. package/dist/network.d.ts +7 -7
  35. package/dist/network.js +11 -18
  36. package/dist/policy-store.d.ts +7 -8
  37. package/dist/policy-store.js +11 -15
  38. package/dist/policy.d.ts +25 -100
  39. package/dist/policy.js +44 -146
  40. package/dist/server-ops.d.ts +15 -35
  41. package/dist/server-ops.js +36 -117
  42. package/dist/state.d.ts +15 -16
  43. package/dist/state.js +38 -36
  44. package/package.json +2 -2
  45. package/dist/proxy-guard.d.ts +0 -58
  46. package/dist/proxy-guard.js +0 -137
package/dist/policy.d.ts CHANGED
@@ -1,10 +1,11 @@
1
- import { type DeviceExecGrants, type SandboxLimits, type SandboxRoots, type SandboxTier } from "@capybara-hq/plugin-sdk";
2
- import type { Policy } from "./state.js";
1
+ import { type DeviceExecGrants, type SandboxLimits, type SandboxRoots } from "@capybara-hq/plugin-sdk";
2
+ import type { Policy, SandboxMode } from "./state.js";
3
3
  /**
4
- * Paths no command may read (spec §13.6, extended by ruling R19): SSH keys, cloud CLI
4
+ * Paths no sandboxed command may read (spec §13.6, extended by ruling R19): SSH keys, cloud CLI
5
5
  * credentials, container and Kubernetes credentials, netrc, GnuPG, git / npm / PyPI tokens, the
6
6
  * macOS keychains, and the browser profile directories (Chrome, Firefox, Chromium, Safari, Brave,
7
- * Edge, Arc). Relative to `~`.
7
+ * Edge, Arc). Relative to `~`. Auto mode runs as the owner and does not apply them: command review
8
+ * in the kernel does (spec §5.2).
8
9
  */
9
10
  export declare const DENIED_SECRET_PATHS: readonly string[];
10
11
  /** {@link DENIED_SECRET_PATHS} with `~` expanded to `home`. */
@@ -16,122 +17,46 @@ export declare function deniedSecretPaths(home?: string): string[];
16
17
  export declare function implicitWritePaths(home?: string): string[];
17
18
  /** True when the allowlist entry `pattern` admits every host `host` names (`host` may be a wildcard). */
18
19
  export declare function covers(pattern: string, host: string): boolean;
20
+ /** The limits fields that decide the mode and the sandbox-mode network. */
21
+ export type ModeLimits = Pick<SandboxLimits, "mode" | "network">;
19
22
  /**
20
- * The entry {@link effectiveEgress} returns when a command may reach any public host (the device
21
- * is `open` and so is the org). sandbox-runtime 0.0.81 matches `*` as any host but refuses it in a
22
- * per-command list, so the OS executor never registers it: its ask callback allows instead.
23
+ * The mode a command runs in (spec §4.1): the device's own choice cut to the kernel's ceiling. A
24
+ * sandbox-mode machine never runs auto because the organization allows it; an auto-mode machine in
25
+ * an organization that forbids auto runs in the sandbox (and its summary says so).
23
26
  */
24
- export declare const ANY_HOST = "*";
25
- /** The tier fields of an exec's limits: the org's ceiling and its default. */
26
- export type TierLimits = Pick<SandboxLimits, "tier" | "defaultTier">;
27
+ export declare function effectiveMode(policy: Pick<Policy, "mode">, limits: Pick<SandboxLimits, "mode">): SandboxMode;
28
+ /** The granted hosts that apply to one command, within the kernel's network limits. */
29
+ export declare function grantedHosts(limits: Pick<SandboxLimits, "network">, grants: Pick<DeviceExecGrants, "hosts"> | undefined): string[];
27
30
  /**
28
- * The tier this device runs a command at (spec §4.4): the owner's choice, or the org's default
29
- * when there is none (`strict` when the kernel sent no default either), cut to the ceiling the
30
- * kernel sends in `limits.tier`.
31
+ * The domains one sandbox-mode command may reach (spec §4.1, §4.4): the intersection of the
32
+ * device's own `allowedDomains` and the kernel's allowlist (`limits.network`), plus the command's
33
+ * grants. An empty list allows nothing. Auto mode ignores both lists: the command has the machine's
34
+ * own network, so this returns no list there (the OS sandbox is not running).
31
35
  */
32
- export declare function deviceTier(policy: Pick<Policy, "tier">, limits: TierLimits): SandboxTier;
33
- /**
34
- * The tier before any exec was seen (no ceiling known yet): the owner's choice, else `dev`, the
35
- * default of every org unless changed. Used for the sandbox's first configuration only; the next
36
- * command applies its own limits.
37
- */
38
- export declare function provisionalTier(policy: Pick<Policy, "tier">): SandboxTier;
39
- /** What a tier really gives on this machine (the device page and `policy show`). */
40
- export interface TierFacts {
41
- effectiveTier: SandboxTier;
42
- /** Whether sandboxed commands may listen on and reach localhost. */
43
- localhost: "on" | "off-proxy-detected" | "off";
44
- /** Unix sockets: within the device's directories, every socket with the host's masked, none. */
45
- unixSockets: "roots" | "all-masked" | "off";
46
- }
47
- /**
48
- * The facts of the device's tier (spec §5.2.3, §7.3). `limits` undefined means no exec was seen
49
- * yet: the owner's choice, else `dev`, uncapped. `isolation: none` is reported separately (these
50
- * describe the sandboxed tier).
51
- *
52
- * - Docker mode: the container has its own loopback and sockets in every tier.
53
- * - OS mode, Linux: the sandbox has its own network namespace, so its loopback always works (not
54
- * reachable from the host); unix sockets stay blocked (srt cannot limit them by path there).
55
- * - OS mode, macOS: `strict` has neither; `dev` / `open` get unix sockets under the device's
56
- * directories and localhost unless a local forwarding proxy was detected and the owner did not
57
- * set `localhost: allow`.
58
- */
59
- export declare function tierFacts(policy: Policy, limits: TierLimits | undefined, opts: {
60
- platform?: NodeJS.Platform;
61
- proxyDetected: boolean;
62
- mode: "os" | "docker";
63
- }): TierFacts;
64
- type Limits = Pick<SandboxLimits, "egress" | "allowHosts">;
65
- /**
66
- * The granted hosts that apply to one command: none unless the local `remoteGrants` is `owner`;
67
- * only valid exact hosts (no wildcards, addresses or internal names), lowercased and deduped; and
68
- * only those the org's egress admits (any host when it is `open`, none when it is `none`).
69
- */
70
- export declare function grantedHosts(policy: Pick<Policy, "remoteGrants">, limits: Limits, grants: Pick<DeviceExecGrants, "hosts"> | undefined): string[];
71
- /** The limits {@link effectiveEgress} reads: the ceiling's network and tiers, and the dev hosts. */
72
- export type EgressLimits = Pick<SandboxLimits, "egress" | "allowHosts" | "tier" | "defaultTier" | "devHosts">;
73
- /**
74
- * The hosts the device itself admits at `tier` (before the ceiling): its `allowedDomains`, plus
75
- * the dev hosts in `dev`. Undefined for `open`: the device admits every host.
76
- */
77
- export declare function deviceHosts(policy: Pick<Policy, "allowedDomains">, tier: SandboxTier, devHosts: readonly string[]): string[] | undefined;
78
- /**
79
- * The domains one command may reach (spec §4.2), with `t` = {@link deviceTier} and the ceiling's
80
- * hosts (`limits.allowHosts`, or any host when `limits.egress` is `open`):
81
- * - `strict`: ceiling ∩ `allowedDomains` (an empty list allows nothing but the grants);
82
- * - `dev`: ceiling ∩ (`allowedDomains` ∪ `limits.devHosts`);
83
- * - `open`: the ceiling itself ({@link ANY_HOST} when it is `open`);
84
- * plus the command's grants ({@link grantedHosts}). The cloud can only narrow the local policy.
85
- */
86
- export declare function effectiveEgress(policy: Pick<Policy, "allowedDomains" | "tier" | "remoteGrants">, limits: EgressLimits, grants?: Pick<DeviceExecGrants, "hosts">): string[];
87
- /** The sandbox-runtime configuration of one device. */
36
+ export declare function effectiveEgress(policy: Pick<Policy, "allowedDomains" | "mode">, limits: ModeLimits, grants?: Pick<DeviceExecGrants, "hosts">): string[];
37
+ /** The sandbox-runtime configuration of a sandbox-mode device. */
88
38
  export interface SrtConfig {
89
39
  filesystem: {
90
40
  denyRead: string[];
91
41
  allowWrite: string[];
92
42
  denyWrite: string[];
93
- /** Whether commands may write `.git/config` (`dev` / `open`); `.git/hooks` never. */
94
- allowGitConfig: boolean;
95
43
  };
96
44
  network: {
97
45
  allowedDomains: string[];
98
46
  deniedDomains: string[];
99
- /** macOS: bind and accept on local ports, connect to any port on localhost. */
100
- allowLocalBinding: boolean;
101
- /** macOS only: the paths under which unix sockets may be bound and connected to. */
102
- allowUnixSockets?: string[];
103
47
  };
104
48
  }
105
- /** What {@link srtConfig} needs besides the policy and the roots. */
49
+ /** What {@link srtConfig} needs besides the egress list. */
106
50
  export interface SrtConfigOptions {
107
- /** The tier the commands run at (default `strict`). */
108
- tier?: SandboxTier;
109
51
  /** The home whose secret paths are denied (default: the user's home). */
110
52
  home?: string;
111
53
  /** More paths commands may not read (this program's state directory). */
112
54
  denyRead?: string[];
113
- platform?: NodeJS.Platform;
114
- /** The proxy guard found a local forwarding proxy (macOS `dev` / `open` then skip localhost). */
115
- proxyDetected?: boolean;
116
- /** macOS: the short socket directory (`TMPDIR` in `dev` / `open`). */
117
- socketDir?: string;
118
- /** The device's package caches (`<dir>/cache`), writable in `dev` / `open`. */
119
- cacheDir?: string;
120
55
  }
121
56
  /**
122
- * The sandbox-runtime configuration (spec §5.1, §5.2.3): writes only under the workspace and tmp
123
- * roots (the runtime's implicit write paths denied), skills read only, the secret paths (plus
124
- * `opts.denyRead`, such as this program's own state directory) unreadable, and network limited to
125
- * `egress`.
126
- *
127
- * `strict` stops there: no local binding, no unix sockets. `dev` and `open` also write the
128
- * package caches and (macOS) the short socket directory; on macOS they may listen on and reach
129
- * localhost unless the proxy guard found a local forwarding proxy (`localhost: allow` overrides)
130
- * and use unix sockets under the tmp root, the workspace and the socket directory. On Linux unix
131
- * sockets stay blocked (srt can only allow all of them there, the host daemons' included) and the
132
- * sandbox's own network namespace gives it a loopback anyway. `allowAllUnixSockets` is never set.
133
- * `dev` and `open` may write `.git/config` (so git can init, clone, set remotes and config);
134
- * `.git/hooks` stays unwritable at every tier ({@link gitWriteDenies}).
57
+ * The sandbox-runtime configuration of sandbox mode (spec §4.1, §4.4): today's strict profile
58
+ * only. Writes only under the workspace and tmp roots (the runtime's implicit write paths
59
+ * denied), skills read only, the secret paths (plus `opts.denyRead`, such as this program's own
60
+ * state directory) unreadable, and network limited to `egress`. No local binding, no unix sockets.
135
61
  */
136
- export declare function srtConfig(policy: Policy, roots: SandboxRoots, egress: string[], opts?: SrtConfigOptions): SrtConfig;
137
- export {};
62
+ export declare function srtConfig(roots: SandboxRoots, egress: string[], opts?: SrtConfigOptions): SrtConfig;
package/dist/policy.js CHANGED
@@ -1,11 +1,12 @@
1
1
  import { homedir } from "node:os";
2
2
  import { join } from "node:path";
3
- import { minTier, validateAllowHost, } from "@capybara-hq/plugin-sdk";
3
+ import { validateAllowHost, } from "@capybara-hq/plugin-sdk";
4
4
  /**
5
- * Paths no command may read (spec §13.6, extended by ruling R19): SSH keys, cloud CLI
5
+ * Paths no sandboxed command may read (spec §13.6, extended by ruling R19): SSH keys, cloud CLI
6
6
  * credentials, container and Kubernetes credentials, netrc, GnuPG, git / npm / PyPI tokens, the
7
7
  * macOS keychains, and the browser profile directories (Chrome, Firefox, Chromium, Safari, Brave,
8
- * Edge, Arc). Relative to `~`.
8
+ * Edge, Arc). Relative to `~`. Auto mode runs as the owner and does not apply them: command review
9
+ * in the kernel does (spec §5.2).
9
10
  */
10
11
  export const DENIED_SECRET_PATHS = Object.freeze([
11
12
  "~/.ssh",
@@ -59,199 +60,96 @@ export function covers(pattern, host) {
59
60
  return pattern.startsWith("*.") && host.endsWith(pattern.slice(1));
60
61
  }
61
62
  /**
62
- * The entry {@link effectiveEgress} returns when a command may reach any public host (the device
63
- * is `open` and so is the org). sandbox-runtime 0.0.81 matches `*` as any host but refuses it in a
64
- * per-command list, so the OS executor never registers it: its ask callback allows instead.
63
+ * The mode a command runs in (spec §4.1): the device's own choice cut to the kernel's ceiling. A
64
+ * sandbox-mode machine never runs auto because the organization allows it; an auto-mode machine in
65
+ * an organization that forbids auto runs in the sandbox (and its summary says so).
65
66
  */
66
- export const ANY_HOST = "*";
67
- /**
68
- * The tier this device runs a command at (spec §4.4): the owner's choice, or the org's default
69
- * when there is none (`strict` when the kernel sent no default either), cut to the ceiling the
70
- * kernel sends in `limits.tier`.
71
- */
72
- export function deviceTier(policy, limits) {
73
- return minTier(policy.tier ?? limits.defaultTier ?? "strict", limits.tier);
74
- }
75
- /**
76
- * The tier before any exec was seen (no ceiling known yet): the owner's choice, else `dev`, the
77
- * default of every org unless changed. Used for the sandbox's first configuration only; the next
78
- * command applies its own limits.
79
- */
80
- export function provisionalTier(policy) {
81
- return policy.tier ?? "dev";
82
- }
83
- /**
84
- * The facts of the device's tier (spec §5.2.3, §7.3). `limits` undefined means no exec was seen
85
- * yet: the owner's choice, else `dev`, uncapped. `isolation: none` is reported separately (these
86
- * describe the sandboxed tier).
87
- *
88
- * - Docker mode: the container has its own loopback and sockets in every tier.
89
- * - OS mode, Linux: the sandbox has its own network namespace, so its loopback always works (not
90
- * reachable from the host); unix sockets stay blocked (srt cannot limit them by path there).
91
- * - OS mode, macOS: `strict` has neither; `dev` / `open` get unix sockets under the device's
92
- * directories and localhost unless a local forwarding proxy was detected and the owner did not
93
- * set `localhost: allow`.
94
- */
95
- export function tierFacts(policy, limits, opts) {
96
- const effectiveTier = limits === undefined ? provisionalTier(policy) : deviceTier(policy, limits);
97
- if (opts.mode === "docker")
98
- return { effectiveTier, localhost: "on", unixSockets: "all-masked" };
99
- const platform = opts.platform ?? process.platform;
100
- if (platform !== "darwin")
101
- return { effectiveTier, localhost: "on", unixSockets: "off" };
102
- if (effectiveTier === "strict")
103
- return { effectiveTier, localhost: "off", unixSockets: "off" };
104
- return {
105
- effectiveTier,
106
- localhost: localBinding(policy, opts.proxyDetected) ? "on" : "off-proxy-detected",
107
- unixSockets: "roots",
108
- };
109
- }
110
- /** macOS `dev` / `open`: local binding, unless a local proxy was found and not overridden. */
111
- function localBinding(policy, proxyDetected) {
112
- return policy.localhost === "allow" || !proxyDetected;
67
+ export function effectiveMode(policy, limits) {
68
+ return policy.mode === "sandbox" || limits.mode === "sandbox" ? "sandbox" : "auto";
113
69
  }
114
- /**
115
- * The granted hosts that apply to one command: none unless the local `remoteGrants` is `owner`;
116
- * only valid exact hosts (no wildcards, addresses or internal names), lowercased and deduped; and
117
- * only those the org's egress admits (any host when it is `open`, none when it is `none`).
118
- */
119
- export function grantedHosts(policy, limits, grants) {
120
- if (grants === undefined || policy.remoteGrants !== "owner")
121
- return [];
122
- if (limits.egress === "none")
70
+ /** The granted hosts that apply to one command, within the kernel's network limits. */
71
+ export function grantedHosts(limits, grants) {
72
+ if (grants === undefined)
123
73
  return [];
124
74
  const out = new Set();
125
75
  for (const raw of grants.hosts) {
126
76
  if (typeof raw !== "string")
127
77
  continue;
128
78
  const host = raw.toLowerCase();
129
- if (host.startsWith("*.") || validateAllowHost(host).length > 0)
79
+ // Only valid exact public hosts (no wildcards, addresses or internal names).
80
+ if (validateAllowHost(host).length > 0)
130
81
  continue;
131
- if (limits.egress === "open" || limits.allowHosts.some((p) => covers(p.toLowerCase(), host))) {
82
+ if (limits.network.kind === "open-public" ||
83
+ limits.network.hosts.some((p) => covers(p.toLowerCase(), host))) {
132
84
  out.add(host);
133
85
  }
134
86
  }
135
87
  return [...out];
136
88
  }
137
89
  /**
138
- * The hosts the device itself admits at `tier` (before the ceiling): its `allowedDomains`, plus
139
- * the dev hosts in `dev`. Undefined for `open`: the device admits every host.
140
- */
141
- export function deviceHosts(policy, tier, devHosts) {
142
- if (tier === "open")
143
- return undefined;
144
- const local = policy.allowedDomains.map((d) => d.toLowerCase());
145
- if (tier === "dev")
146
- for (const d of devHosts)
147
- local.push(d.toLowerCase());
148
- return [...new Set(local)];
149
- }
150
- /**
151
- * The domains one command may reach (spec §4.2), with `t` = {@link deviceTier} and the ceiling's
152
- * hosts (`limits.allowHosts`, or any host when `limits.egress` is `open`):
153
- * - `strict`: ceiling ∩ `allowedDomains` (an empty list allows nothing but the grants);
154
- * - `dev`: ceiling ∩ (`allowedDomains` ∪ `limits.devHosts`);
155
- * - `open`: the ceiling itself ({@link ANY_HOST} when it is `open`);
156
- * plus the command's grants ({@link grantedHosts}). The cloud can only narrow the local policy.
90
+ * The domains one sandbox-mode command may reach (spec §4.1, §4.4): the intersection of the
91
+ * device's own `allowedDomains` and the kernel's allowlist (`limits.network`), plus the command's
92
+ * grants. An empty list allows nothing. Auto mode ignores both lists: the command has the machine's
93
+ * own network, so this returns no list there (the OS sandbox is not running).
157
94
  */
158
95
  export function effectiveEgress(policy, limits, grants) {
159
- if (limits.egress === "none")
96
+ if (effectiveMode(policy, limits) === "auto")
160
97
  return [];
161
- const local = deviceHosts(policy, deviceTier(policy, limits), limits.devHosts ?? []);
162
- if (local === undefined) {
163
- if (limits.egress === "open")
164
- return [ANY_HOST];
165
- return [...new Set(limits.allowHosts.map((h) => h.toLowerCase()))];
166
- }
167
98
  const out = new Set();
168
- if (limits.egress === "open") {
169
- for (const d of local)
170
- out.add(d);
171
- }
172
- else {
173
- for (const raw of limits.allowHosts) {
174
- const host = raw.toLowerCase();
175
- for (const p of local) {
176
- // The intersection of two entries is the narrower one, if either contains the other.
177
- if (covers(p, host))
178
- out.add(host);
179
- else if (covers(host, p))
180
- out.add(p);
181
- }
99
+ const local = policy.allowedDomains.map((d) => d.toLowerCase());
100
+ // `open-public` is for cloud instances only; a local sandbox-mode device is stricter and keeps
101
+ // its own allowlist.
102
+ const orgHosts = limits.network.kind === "allowlist" ? limits.network.hosts.map((h) => h.toLowerCase()) : local;
103
+ for (const host of orgHosts) {
104
+ for (const p of local) {
105
+ // The intersection of two entries is the narrower one, if either contains the other.
106
+ if (covers(p, host))
107
+ out.add(host);
108
+ else if (covers(host, p))
109
+ out.add(p);
182
110
  }
183
111
  }
184
- for (const h of grantedHosts(policy, limits, grants))
112
+ for (const h of grantedHosts(limits, grants))
185
113
  out.add(h);
186
114
  return [...out];
187
115
  }
188
116
  /** Characters the sandbox runtime reads as a glob in a path entry. */
189
117
  const GLOB_CHARS = /[*?[\]{}]/;
190
118
  /**
191
- * Write denies for git under each writable root (spec §5.2.1): `.git/hooks` at every tier (a hook
192
- * is code that runs unsandboxed when the owner later runs git there), `.git/config` at `strict`.
119
+ * Write denies for git under each writable root (spec §5.2.1): `.git/hooks` and `.git/config`
120
+ * (a hook or `core.sshCommand` set by a command would run when the owner later runs git there).
193
121
  * The runtime has the same mandatory denies, but anchored at this program's own working directory,
194
122
  * which may not contain the roots. A root whose path reads as a glob gets none (it cannot be
195
123
  * anchored literally); the runtime's own denies still apply when it lies under the working
196
124
  * directory.
197
125
  */
198
- function gitWriteDenies(writable, gitConfig) {
126
+ function gitWriteDenies(writable) {
199
127
  const out = [];
200
128
  for (const root of writable) {
201
129
  if (GLOB_CHARS.test(root))
202
130
  continue;
203
131
  out.push(`${root}/.git/hooks/**`, `${root}/**/.git/hooks/**`);
204
- if (!gitConfig)
205
- out.push(`${root}/.git/config`, `${root}/**/.git/config`);
132
+ out.push(`${root}/.git/config`, `${root}/**/.git/config`);
206
133
  }
207
134
  return out;
208
135
  }
209
136
  /**
210
- * The sandbox-runtime configuration (spec §5.1, §5.2.3): writes only under the workspace and tmp
211
- * roots (the runtime's implicit write paths denied), skills read only, the secret paths (plus
212
- * `opts.denyRead`, such as this program's own state directory) unreadable, and network limited to
213
- * `egress`.
214
- *
215
- * `strict` stops there: no local binding, no unix sockets. `dev` and `open` also write the
216
- * package caches and (macOS) the short socket directory; on macOS they may listen on and reach
217
- * localhost unless the proxy guard found a local forwarding proxy (`localhost: allow` overrides)
218
- * and use unix sockets under the tmp root, the workspace and the socket directory. On Linux unix
219
- * sockets stay blocked (srt can only allow all of them there, the host daemons' included) and the
220
- * sandbox's own network namespace gives it a loopback anyway. `allowAllUnixSockets` is never set.
221
- * `dev` and `open` may write `.git/config` (so git can init, clone, set remotes and config);
222
- * `.git/hooks` stays unwritable at every tier ({@link gitWriteDenies}).
137
+ * The sandbox-runtime configuration of sandbox mode (spec §4.1, §4.4): today's strict profile
138
+ * only. Writes only under the workspace and tmp roots (the runtime's implicit write paths
139
+ * denied), skills read only, the secret paths (plus `opts.denyRead`, such as this program's own
140
+ * state directory) unreadable, and network limited to `egress`. No local binding, no unix sockets.
223
141
  */
224
- export function srtConfig(policy, roots, egress, opts = {}) {
225
- const platform = opts.platform ?? process.platform;
226
- const tier = opts.tier ?? "strict";
227
- const darwin = platform === "darwin";
228
- const dev = tier !== "strict";
229
- const socketDir = darwin && dev ? opts.socketDir : undefined;
230
- const allowWrite = [
231
- roots.workspace,
232
- roots.tmp,
233
- ...(socketDir !== undefined ? [socketDir] : []),
234
- ...(dev && opts.cacheDir !== undefined ? [opts.cacheDir] : []),
235
- ];
142
+ export function srtConfig(roots, egress, opts = {}) {
143
+ const allowWrite = [roots.workspace, roots.tmp];
236
144
  return {
237
145
  filesystem: {
238
146
  denyRead: [...deniedSecretPaths(opts.home), ...(opts.denyRead ?? [])],
239
147
  allowWrite,
240
- denyWrite: [roots.skills, ...implicitWritePaths(), ...gitWriteDenies(allowWrite, dev)],
241
- allowGitConfig: dev,
148
+ denyWrite: [roots.skills, ...implicitWritePaths(opts.home), ...gitWriteDenies(allowWrite)],
242
149
  },
243
150
  network: {
244
151
  allowedDomains: [...egress],
245
152
  deniedDomains: [],
246
- allowLocalBinding: darwin && dev && localBinding(policy, opts.proxyDetected === true),
247
- ...(darwin &&
248
- dev && {
249
- allowUnixSockets: [
250
- roots.tmp,
251
- roots.workspace,
252
- ...(socketDir !== undefined ? [socketDir] : []),
253
- ],
254
- }),
255
153
  },
256
154
  };
257
155
  }
@@ -1,13 +1,12 @@
1
- import { type DeviceLocalPolicySummary, type DeviceRes, type KernelReq } from "@capybara-hq/plugin-sdk";
1
+ import { type DeviceLocalPolicySummary, type DeviceRes, type KernelReq, type SandboxLimits } from "@capybara-hq/plugin-sdk";
2
2
  import type { CommandLogEntry } from "./command-log.js";
3
- import { type ExecIsolation, type Executor } from "./exec/types.js";
4
- import { type TierLimits } from "./policy.js";
3
+ import { type ExecMode, type Executor } from "./exec/types.js";
5
4
  import type { PolicyStore } from "./policy-store.js";
6
5
  import { type Policy } from "./state.js";
7
6
  /** What this program has seen across requests (one per program run, kept over reconnects). */
8
7
  export interface SeenState {
9
- /** The tier limits of the latest exec: the org's ceiling and default, for the summary. */
10
- limits?: TierLimits;
8
+ /** The mode of the latest exec's limits (the kernel's ceiling), for the summary. */
9
+ limits?: Pick<SandboxLimits, "mode">;
11
10
  }
12
11
  /** What a request may need beyond the executor. */
13
12
  export interface OpContext {
@@ -18,52 +17,33 @@ export interface OpContext {
18
17
  policy?: PolicyStore;
19
18
  /** Updated by every exec; read by the policy op's summary. */
20
19
  seen?: SeenState;
21
- /** The platform the summary describes (default: this process's). */
22
- platform?: NodeJS.Platform;
23
20
  }
24
- /** The refusal of a `policy` op adding hosts under `remoteGrants: "off"`. */
25
- export declare const REMOTE_GRANTS_OFF_MESSAGE: string;
26
- /** The refusal of a `policy` op raising the tier under `remoteGrants: "off"`. */
27
- export declare const REMOTE_TIER_OFF_MESSAGE: string;
28
- /**
29
- * The refusal of a `policy` op that tries to turn the sandbox off: whatever `remoteGrants` says,
30
- * only the person on the machine does that (spec §5.4).
31
- */
32
- export declare const ISOLATION_REMOTE_MESSAGE: string;
33
- /**
34
- * The refusal of a widening `policy` op in Docker mode: the container has either no network or the
35
- * whole internet, so one allowed domain would open everything.
36
- */
37
- export declare const DOCKER_WIDENING_MESSAGE: string;
21
+ /** The refusal of a `policy` op that tries to turn auto mode on from the deployment. */
22
+ export declare const MODE_ON_DEVICE_MESSAGE = "The device's mode can only be changed on the machine: run `capybara-device mode auto`.";
38
23
  /** The local-log line for a finished request; `detail` is its audit line, `run` how an exec ran. */
39
- export declare function logEntryFor(req: KernelReq, res: DeviceRes, now: Date, detail?: string, run?: Pick<ExecIsolation, "tier" | "isolation">): CommandLogEntry;
24
+ export declare function logEntryFor(req: KernelReq, res: DeviceRes, now: Date, detail?: string, run?: ExecMode): CommandLogEntry;
40
25
  /** What the summary describes besides the policy file. */
41
26
  export interface SummaryFacts {
42
27
  mode: Executor["mode"];
43
- /** The latest exec's tier limits; undefined before the first exec. */
44
- limits?: TierLimits | undefined;
45
- /** The localhost proxy guard found a local forwarding proxy (OS mode). */
46
- proxyDetected?: boolean;
47
- platform?: NodeJS.Platform;
28
+ /** The latest exec's mode ceiling; undefined before the first exec. */
29
+ limits?: Pick<SandboxLimits, "mode"> | undefined;
48
30
  }
49
31
  /**
50
- * The summary the kernel keeps of a local policy (hello, `policy` op result): the owner's tier,
51
- * what it gives on this machine with the latest ceiling seen ({@link tierFacts}), and the
52
- * isolation. Docker mode always reports `sandbox` (it ignores `isolation`).
32
+ * The summary the kernel keeps of a local policy (hello, `policy` op result): the effective mode
33
+ * (the owner's choice cut to the latest ceiling seen) and the device's sandbox-mode allowlist.
53
34
  */
54
35
  export declare function policySummary(p: Policy, facts: SummaryFacts): DeviceLocalPolicySummary;
55
36
  /** The summary facts of a request context. */
56
37
  export declare function summaryFacts(executor: Executor, ctx: OpContext): SummaryFacts;
57
38
  /**
58
- * Runs one request and returns the answer plus its local audit line and, for an exec, its tier
59
- * and isolation (for the local command log). A vanished device
60
- * directory answers `fs_gone` for every operation except `stop`, `policy` and `policyStatus`.
61
- * Never throws.
39
+ * Runs one request and returns the answer plus its local audit line and, for an exec, its mode
40
+ * (for the local command log). A vanished device directory answers `fs_gone` for every operation
41
+ * except `stop`, `policy` and `policyStatus`. Never throws.
62
42
  */
63
43
  export declare function serveOp(executor: Executor, req: KernelReq, signal: AbortSignal, ctx?: OpContext): Promise<{
64
44
  res: DeviceRes;
65
45
  detail?: string;
66
- run?: ExecIsolation;
46
+ run?: ExecMode;
67
47
  }>;
68
48
  /** {@link serveOp} without the audit line. */
69
49
  export declare function runOp(executor: Executor, req: KernelReq, signal: AbortSignal, ctx?: OpContext): Promise<DeviceRes>;