@capybara-hq/device 0.1.0-rc.18 → 0.1.0-rc.19

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 (72) hide show
  1. package/README.md +65 -33
  2. package/dist/api.d.ts +3 -3
  3. package/dist/args.d.ts +8 -3
  4. package/dist/args.js +27 -14
  5. package/dist/cli.js +1 -1
  6. package/dist/client.js +1 -1
  7. package/dist/commands/ceiling.d.ts +3 -2
  8. package/dist/commands/ceiling.js +39 -21
  9. package/dist/commands/login.d.ts +15 -11
  10. package/dist/commands/login.js +46 -33
  11. package/dist/commands/policy.js +16 -10
  12. package/dist/commands/start.d.ts +11 -3
  13. package/dist/commands/start.js +25 -9
  14. package/dist/commands/status.js +10 -6
  15. package/dist/exec/docker-operations.d.ts +14 -2
  16. package/dist/exec/docker-operations.js +32 -5
  17. package/dist/exec/linux-agent.d.ts +13 -3
  18. package/dist/exec/linux-agent.js +450 -43
  19. package/dist/exec/linux-operation-backend.d.ts +27 -6
  20. package/dist/exec/linux-operation-backend.js +30 -9
  21. package/dist/exec/linux-operation-worker.d.ts +51 -3
  22. package/dist/exec/linux-operation-worker.js +55 -3
  23. package/dist/exec/linux-runtime.d.ts +3 -2
  24. package/dist/exec/linux-runtime.js +4 -2
  25. package/dist/exec/mac-operation-backend.d.ts +7 -2
  26. package/dist/exec/mac-operation-backend.js +18 -10
  27. package/dist/exec/mac-write-policy.d.ts +2 -0
  28. package/dist/exec/mac-write-policy.js +1 -1
  29. package/dist/exec/operation-types.d.ts +35 -5
  30. package/dist/exec/operation-types.js +73 -23
  31. package/dist/exec/operation-worker.d.ts +80 -1
  32. package/dist/exec/operation-worker.js +197 -14
  33. package/dist/exec/protected-targets.d.ts +16 -0
  34. package/dist/exec/protected-targets.js +53 -0
  35. package/dist/exec/shared.d.ts +7 -3
  36. package/dist/exec/shared.js +7 -5
  37. package/dist/node_modules/@anthropic-ai/sandbox-runtime/CAPYBARA-MODIFICATIONS.patch +343 -7
  38. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/resolved-address-guard.js +220 -6
  39. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-config.js +17 -0
  40. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-manager.js +11 -0
  41. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.d.ts +77 -46
  42. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +206 -83
  43. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +3 -2
  44. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +3 -2
  45. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/network-classes.d.ts +98 -0
  46. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/network-classes.js +291 -0
  47. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-linux-runtime-source.js +460 -28
  48. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-native-runtime-source.js +143 -3
  49. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.d.ts +36 -4
  50. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.js +21 -4
  51. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-runtime-source.js +2 -2
  52. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-write-denies.d.ts +87 -8
  53. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-write-denies.js +249 -10
  54. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox.d.ts +11 -22
  55. package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
  56. package/dist/owner-report.d.ts +1 -1
  57. package/dist/owner-report.js +5 -4
  58. package/dist/policy-store.d.ts +2 -1
  59. package/dist/policy-store.js +2 -1
  60. package/dist/policy.d.ts +23 -14
  61. package/dist/policy.js +28 -21
  62. package/dist/runtime-manifest.json +1 -1
  63. package/dist/server-ops.d.ts +30 -5
  64. package/dist/server-ops.js +105 -85
  65. package/dist/staged-connect.d.ts +1 -1
  66. package/dist/staged-connect.js +1 -1
  67. package/dist/staged-device.d.ts +1 -1
  68. package/dist/staged-device.js +7 -5
  69. package/dist/staged-session.d.ts +1 -1
  70. package/dist/state.d.ts +41 -21
  71. package/dist/state.js +102 -45
  72. package/package.json +2 -2
@@ -1,3 +1,4 @@
1
+ import { type LinuxFaultInjection } from "./linux-operation-worker.js";
1
2
  import { type LinuxAgentTransport, type LinuxProbe } from "./linux-runtime.js";
2
3
  import { type MacBackendDependencies, type MacOperationBackend, type MacOperationBackendOptions } from "./mac-operation-backend.js";
3
4
  import { type LocalOperationGrant } from "./operation-types.js";
@@ -8,8 +9,8 @@ export type LocalOperationBackend = MacOperationBackend;
8
9
  export interface LinuxBackendDependencies {
9
10
  /** How agents start: on this host (default) or in the device's local container. */
10
11
  transport?: LinuxAgentTransport;
11
- /** The environment a command starts from; see {@link hostBaseEnv}. */
12
- baseEnv?: (full: boolean) => Record<string, string>;
12
+ /** The environment a command starts from; see {@link hostCommandEnv}. */
13
+ baseEnv?: (escalated: boolean) => Record<string, string>;
13
14
  /** Where restricted commands find version managers (default: this process's home and env). */
14
15
  toolHome?: {
15
16
  home: string;
@@ -31,11 +32,30 @@ export interface LinuxBackendDependencies {
31
32
  * addresses, as a conformance fixture's local endpoints need. Production never sets it.
32
33
  */
33
34
  allowPrivateProxyTargets?: boolean;
35
+ /** Test seam (trusted construction only): see the worker's `fakeIpDnsTest`. */
36
+ fakeIpDnsTest?: {
37
+ endpoints: string[];
38
+ caPem: string;
39
+ };
40
+ /** Test seam (trusted construction only): see the worker's `faultInjection`. */
41
+ faultInjection?: LinuxFaultInjection;
34
42
  /** Called with a reap failure of a lost supervisor's session (default: ignored). */
35
43
  onReapError?: (error: unknown) => void;
36
44
  }
37
- /** A host command's starting environment: Full keeps this process's, restricted a fixed set. */
38
- export declare function hostBaseEnv(full: boolean): Record<string, string>;
45
+ /**
46
+ * A host command's starting environment (approval-only profiles design, "Fixed denies and the
47
+ * minimal environment"): every sandboxed command, whatever its profile, starts from a fixed set
48
+ * (the worker adds HOME, TMPDIR, the tool homes, the proxy and the call's own variables). An
49
+ * escalated call runs as the owner: this process's environment without the device's own
50
+ * variables (every `CAPYBARA_*`; the device credential lives in its state directory, never in
51
+ * the environment).
52
+ */
53
+ export declare function hostCommandEnv(escalated: boolean): Record<string, string>;
54
+ /**
55
+ * A host device's files lock (see the worker's `filesLock`): in its state directory, which every
56
+ * restricted grant is denied (`restrictedDeniedReadRoots`) and the launcher refuses inside a root.
57
+ */
58
+ export declare function hostFilesLock(stateDir: string): string;
39
59
  /**
40
60
  * Landlock only grants: it cannot hide an owner-denied path (a secret directory, the device's
41
61
  * state) inside a granted root, so such an exec grant is refused rather than widened. Native work
@@ -46,8 +66,9 @@ export declare function checkLinuxRestrictedGrant(grant: LocalOperationGrant, ki
46
66
  /**
47
67
  * The Linux local operation backend (permission activation W2-S): the same functions as the macOS
48
68
  * backend on the SDK's restricted Linux runtime. Restricted exec runs through the launcher on
49
- * pinned root descriptors (Landlock, the seccomp broker), with network none or an allowlist served
50
- * by an operation-owned proxy; native work uses the SDK helper on the same kind of pinned
69
+ * pinned root descriptors (Landlock, the seccomp broker), with network none, an allowlist or the
70
+ * open public network served by an operation-owned proxy (a loopback listener the command opens is
71
+ * reachable from outside the sandbox only); native work uses the SDK helper on the same kind of pinned
51
72
  * descriptors; Full access runs as the OS user without restricted filters. Background work,
52
73
  * retained output and exact cancellation share the macOS supervisor. Restricted support is what
53
74
  * the launcher's probe reports (an unsupported kernel, ABI or architecture fails closed while Full
@@ -1,18 +1,33 @@
1
1
  import { homedir } from "node:os";
2
+ import { join } from "node:path";
2
3
  import { SandboxScopeDeniedError } from "@capybara-hq/plugin-sdk";
3
- import { DEVICE_PROCESS_TOKEN, linuxOperationWorker } from "./linux-operation-worker.js";
4
+ import { DEVICE_PROCESS_TOKEN, linuxOperationWorker, } from "./linux-operation-worker.js";
4
5
  import { hostLinuxTransport, probeLinuxRuntime, reapLinuxSession, } from "./linux-runtime.js";
5
6
  import { createLocalOperationBackend, createMacOperationBackend, } from "./mac-operation-backend.js";
6
7
  import { within } from "./operation-types.js";
7
- /** A host command's starting environment: Full keeps this process's, restricted a fixed set. */
8
- export function hostBaseEnv(full) {
9
- if (full)
10
- return Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined));
8
+ /**
9
+ * A host command's starting environment (approval-only profiles design, "Fixed denies and the
10
+ * minimal environment"): every sandboxed command, whatever its profile, starts from a fixed set
11
+ * (the worker adds HOME, TMPDIR, the tool homes, the proxy and the call's own variables). An
12
+ * escalated call runs as the owner: this process's environment without the device's own
13
+ * variables (every `CAPYBARA_*`; the device credential lives in its state directory, never in
14
+ * the environment).
15
+ */
16
+ export function hostCommandEnv(escalated) {
17
+ if (escalated)
18
+ return Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined && !e[0].startsWith("CAPYBARA_")));
11
19
  return {
12
20
  PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
13
21
  LANG: process.env.LANG ?? "C.UTF-8",
14
22
  };
15
23
  }
24
+ /**
25
+ * A host device's files lock (see the worker's `filesLock`): in its state directory, which every
26
+ * restricted grant is denied (`restrictedDeniedReadRoots`) and the launcher refuses inside a root.
27
+ */
28
+ export function hostFilesLock(stateDir) {
29
+ return join(stateDir, "operation-files.lock");
30
+ }
16
31
  /**
17
32
  * Landlock only grants: it cannot hide an owner-denied path (a secret directory, the device's
18
33
  * state) inside a granted root, so such an exec grant is refused rather than widened. Native work
@@ -30,8 +45,9 @@ export function checkLinuxRestrictedGrant(grant, kind) {
30
45
  /**
31
46
  * The Linux local operation backend (permission activation W2-S): the same functions as the macOS
32
47
  * backend on the SDK's restricted Linux runtime. Restricted exec runs through the launcher on
33
- * pinned root descriptors (Landlock, the seccomp broker), with network none or an allowlist served
34
- * by an operation-owned proxy; native work uses the SDK helper on the same kind of pinned
48
+ * pinned root descriptors (Landlock, the seccomp broker), with network none, an allowlist or the
49
+ * open public network served by an operation-owned proxy (a loopback listener the command opens is
50
+ * reachable from outside the sandbox only); native work uses the SDK helper on the same kind of pinned
35
51
  * descriptors; Full access runs as the OS user without restricted filters. Background work,
36
52
  * retained output and exact cancellation share the macOS supervisor. Restricted support is what
37
53
  * the launcher's probe reports (an unsupported kernel, ABI or architecture fails closed while Full
@@ -50,9 +66,12 @@ export async function createLinuxOperationBackend(options, dependencies = {}) {
50
66
  const startWorker = dependencies.startWorker ??
51
67
  linuxOperationWorker({
52
68
  transport,
53
- baseEnv: dependencies.baseEnv ?? hostBaseEnv,
69
+ filesLock: hostFilesLock(options.stateDir),
70
+ baseEnv: dependencies.baseEnv ?? hostCommandEnv,
54
71
  toolHome: dependencies.toolHome ?? { home: homedir(), env: process.env },
55
72
  ...(dependencies.allowPrivateProxyTargets ? { allowPrivateProxyTargets: true } : {}),
73
+ ...(dependencies.fakeIpDnsTest ? { fakeIpDnsTest: dependencies.fakeIpDnsTest } : {}),
74
+ ...(dependencies.faultInjection ? { faultInjection: dependencies.faultInjection } : {}),
56
75
  ...(dependencies.acquireRuntime ? { acquireRuntime: dependencies.acquireRuntime } : {}),
57
76
  });
58
77
  return createLocalOperationBackend(options, {
@@ -61,7 +80,9 @@ export async function createLinuxOperationBackend(options, dependencies = {}) {
61
80
  }, {
62
81
  restricted: unavailableReason === undefined,
63
82
  ...(unavailableReason ? { unavailableReason } : {}),
64
- fullAccess: probe.agentAvailable !== false,
83
+ // the operation's forwarder enforces the open public network on the resolved address
84
+ openPublic: true,
85
+ outsideSandbox: probe.agentAvailable !== false,
65
86
  background: probe.agentAvailable !== false,
66
87
  pending: unavailableReason ?? "Restricted Linux execution is unavailable",
67
88
  startWorker,
@@ -5,10 +5,20 @@ export declare const DEVICE_PROCESS_TOKEN: `${string}-${string}-${string}-${stri
5
5
  export interface LinuxWorkerOptions {
6
6
  transport: LinuxAgentTransport;
7
7
  /**
8
- * The environment a command starts from: Full gets the OS user's own environment (on the host,
9
- * this process's; in the container, the image's), restricted only a fixed outer set.
8
+ * The device's files lock, as the agent sees it: one file per device, outside every sandbox
9
+ * (on a host, in the device's state directory, which restricted work is denied; in the device's
10
+ * container, on its private /dev/shm, which no Landlock rule grants). Every restricted
11
+ * operation's broker, and the agent's own restricted native writes, hold it shared from a
12
+ * write's check to its effect; the broker holds it exclusively for a directory move into a
13
+ * guarded place, so no operation's move can slip between another operation's check and write.
10
14
  */
11
- baseEnv(full: boolean): Record<string, string>;
15
+ filesLock: string;
16
+ /**
17
+ * The environment a command starts from: an escalated call (outside the sandbox) gets the OS
18
+ * user's own environment without the device's own variables (on the host, this process's minus
19
+ * every `CAPYBARA_*`; in the container, the image's), a sandboxed one only a fixed outer set.
20
+ */
21
+ baseEnv(escalated: boolean): Record<string, string>;
12
22
  /**
13
23
  * The OS user's real home and the device process's own environment: a restricted command gets
14
24
  * their version manager variables and reads those directories ({@link restrictedToolHomes}).
@@ -32,7 +42,45 @@ export interface LinuxWorkerOptions {
32
42
  * addresses, as a conformance fixture's local endpoints need.
33
43
  */
34
44
  allowPrivateProxyTargets?: boolean;
45
+ /**
46
+ * Test seam (trusted construction only): the encrypted DNS a fake-IP answer is re-resolved
47
+ * through (a fixture's DoH endpoint and the certificate it presents) instead of the SDK's
48
+ * `SANDBOX_FAKE_IP_DNS` endpoints, which a test network cannot reach.
49
+ */
50
+ fakeIpDnsTest?: {
51
+ endpoints: string[];
52
+ caPem: string;
53
+ };
54
+ /**
55
+ * Extra addresses the forwarder closes besides its own host's: a local-Docker device's agents
56
+ * run in a container, whose own addresses are not the host's, so the host's interface addresses
57
+ * (a public one included) are closed explicitly. Read at each operation start.
58
+ */
59
+ closedAddresses?: () => string[];
60
+ /**
61
+ * Test seam (trusted construction only): faults the launcher injects, so a test can drive a
62
+ * path no real kernel produces on demand (`stagedMove: "fail"`: a guarded directory move whose
63
+ * final rename and move back both fail, which quarantines it and ends the operation;
64
+ * `pauseBeforeMkdir`: a mkdir of that name pauses between its check and its effect).
65
+ */
66
+ faultInjection?: LinuxFaultInjection;
35
67
  }
68
+ /** The launcher's test-only faults; see {@link LinuxWorkerOptions.faultInjection}. */
69
+ export interface LinuxFaultInjection {
70
+ stagedMove?: "fail";
71
+ pauseBeforeMkdir?: string;
72
+ }
73
+ /**
74
+ * The anchored write denies of the protected home locations: each
75
+ * {@link SANDBOX_MANDATORY_WRITE_DENIES} entry under `home` reached through a symbolic link, and
76
+ * each {@link SANDBOX_HOME_WRITE_DENIES} entry (`~/bin`) always, with the target of its link,
77
+ * resolved with the workers' shared {@link protectedChain}: every link on the chain (also with its
78
+ * parent in on-disk form) and each final target. They go to the launcher as absolute denies,
79
+ * resolved once at operation start; the write policy then refuses moving an ancestor of one away,
80
+ * so no hop can be swapped within the operation. A link changed outside the sandbox is seen by the
81
+ * next operation; a dangling link is followed to the location it names.
82
+ */
83
+ export declare function protectedWriteTargets(home: string): string[];
36
84
  /**
37
85
  * Starts Linux operations through the trusted agent (on the host or in the device's container),
38
86
  * with the same handle semantics as the macOS worker: `ready` once the exact owned identity is
@@ -1,7 +1,9 @@
1
1
  import { randomUUID } from "node:crypto";
2
- import { SandboxPermissionUnsupportedError, SandboxScopeDeniedError, } from "@capybara-hq/plugin-sdk";
2
+ import { basename, dirname, join } from "node:path";
3
+ import { SANDBOX_HOME_WRITE_DENIES, SANDBOX_MANDATORY_WRITE_DENIES, SandboxPermissionUnsupportedError, SandboxScopeDeniedError, } from "@capybara-hq/plugin-sdk";
3
4
  import { agentLine, reapLinuxSession, } from "./linux-runtime.js";
4
5
  import { createCancellationAttempt, } from "./operation-worker.js";
6
+ import { onDisk, protectedChain } from "./protected-targets.js";
5
7
  import { acquireSealedRuntime } from "./runtime-source.js";
6
8
  import { ENV_NAME_RE, OutputCap, restrictedToolHomes, shellQuote } from "./shared.js";
7
9
  /** This device process: a later one reaps sessions recorded under another token. */
@@ -10,6 +12,37 @@ export const DEVICE_PROCESS_TOKEN = randomUUID();
10
12
  const FRAME = 65536;
11
13
  /** How long an agent may take to end what it owns after a cancel before it is killed. */
12
14
  const CANCEL_SETTLE_MS = 15_000;
15
+ /**
16
+ * The anchored write denies of the protected home locations: each
17
+ * {@link SANDBOX_MANDATORY_WRITE_DENIES} entry under `home` reached through a symbolic link, and
18
+ * each {@link SANDBOX_HOME_WRITE_DENIES} entry (`~/bin`) always, with the target of its link,
19
+ * resolved with the workers' shared {@link protectedChain}: every link on the chain (also with its
20
+ * parent in on-disk form) and each final target. They go to the launcher as absolute denies,
21
+ * resolved once at operation start; the write policy then refuses moving an ancestor of one away,
22
+ * so no hop can be swapped within the operation. A link changed outside the sandbox is seen by the
23
+ * next operation; a dangling link is followed to the location it names.
24
+ */
25
+ export function protectedWriteTargets(home) {
26
+ const out = new Set();
27
+ const add = (location, always) => {
28
+ const chain = protectedChain(location);
29
+ if (always)
30
+ out.add(location);
31
+ if (!always && !chain.links.length)
32
+ return;
33
+ out.add(chain.target);
34
+ for (const link of chain.links) {
35
+ out.add(link);
36
+ out.add(join(onDisk(dirname(link)), basename(link)));
37
+ }
38
+ };
39
+ for (const entry of SANDBOX_MANDATORY_WRITE_DENIES)
40
+ add(join(home, ...entry), false);
41
+ // the home-anchored entries (`~/bin`) exist nowhere else in the policy: always denied here
42
+ for (const entry of SANDBOX_HOME_WRITE_DENIES)
43
+ add(join(home, ...entry), true);
44
+ return [...out];
45
+ }
13
46
  function refusal(event) {
14
47
  const message = String(event.message ?? "The operation agent refused the operation");
15
48
  switch (event.code) {
@@ -62,6 +95,10 @@ export function linuxOperationWorker(options) {
62
95
  const toolHomes = request.kind === "exec" && !request.grant.full && options.toolHome
63
96
  ? restrictedToolHomes(options.toolHome.home, options.toolHome.env, request.grant.deniedReadRoots)
64
97
  : undefined;
98
+ // only on the host: a command in the device's container has the image's home
99
+ const writeDenies = !request.grant.full && options.toolHome
100
+ ? protectedWriteTargets(options.toolHome.home)
101
+ : [];
65
102
  const roots = request.grant.full
66
103
  ? {}
67
104
  : {
@@ -69,6 +106,7 @@ export function linuxOperationWorker(options) {
69
106
  ...new Set([...request.grant.readRoots, ...(toolHomes?.readRoots ?? [])]),
70
107
  ],
71
108
  writeRoots: [...request.grant.writeRoots],
109
+ ...(writeDenies.length ? { writeDenies } : {}),
72
110
  };
73
111
  let body;
74
112
  let cap;
@@ -78,6 +116,8 @@ export function linuxOperationWorker(options) {
78
116
  full: request.grant.full,
79
117
  ...roots,
80
118
  ...(request.grant.full ? {} : { denied: [...request.grant.deniedReadRoots] }),
119
+ ...(options.faultInjection ? { faultInjection: options.faultInjection } : {}),
120
+ filesLock: options.filesLock,
81
121
  native: request.native,
82
122
  };
83
123
  }
@@ -99,14 +139,24 @@ export function linuxOperationWorker(options) {
99
139
  op: "exec",
100
140
  full: request.grant.full,
101
141
  ...roots,
142
+ // the escalated call's own network; the open public network through the forwarder
143
+ // (the closed address classes refused); or exactly the granted hosts
102
144
  network: {
103
- kind: request.grant.full ? "environment" : "allowlist",
104
- hosts: [...request.grant.hosts],
145
+ kind: request.grant.full
146
+ ? "environment"
147
+ : request.grant.openNetwork
148
+ ? "open"
149
+ : "allowlist",
150
+ hosts: request.grant.openNetwork ? [] : [...request.grant.hosts],
105
151
  },
106
152
  // single read-only files (a global version pin); the agent grants each exactly
107
153
  ...(toolHomes?.readFiles.length ? { readFiles: toolHomes.readFiles } : {}),
108
154
  // background output is one merged stream; its stderr is the launcher's diagnostics
109
155
  ...(options.allowPrivateProxyTargets ? { allowPrivate: true } : {}),
156
+ ...(options.fakeIpDnsTest ? { dohTest: options.fakeIpDnsTest } : {}),
157
+ ...(options.closedAddresses ? { closedAddresses: options.closedAddresses() } : {}),
158
+ ...(options.faultInjection ? { faultInjection: options.faultInjection } : {}),
159
+ filesLock: options.filesLock,
110
160
  command: request.managedOutput
111
161
  ? `exec /bin/bash -c ${shellQuote(args.command)} 2>&1`
112
162
  : args.command,
@@ -241,6 +291,8 @@ export function linuxOperationWorker(options) {
241
291
  }
242
292
  return response?.result ?? null;
243
293
  }
294
+ if (typeof result.fatal === "string")
295
+ throw new Error(`The restricted launcher ended the operation: ${result.fatal}`);
244
296
  if (result.supervisorLost === true && !cancelled)
245
297
  throw new Error("The restricted launcher was lost; its owned session was ended");
246
298
  const timedOut = result.timedOut === true;
@@ -75,6 +75,7 @@ export declare function reapLinuxSession(transport: LinuxAgentTransport, session
75
75
  * A functional self-check of restricted execution on `root` (an existing directory the device
76
76
  * user owns): a restricted command must list it and create and remove a file in it. Landlock
77
77
  * rules attach to inodes, and some file systems (Docker Desktop's file sharing, for one) do not
78
- * keep them, which would deny every restricted operation there. Returns why it failed, or null.
78
+ * keep them, which would deny every restricted operation there. `filesLock` is the device's files
79
+ * lock, which every restricted launch takes. Returns why it failed, or null.
79
80
  */
80
- export declare function checkRestrictedRoot(transport: LinuxAgentTransport, root: string, env: Record<string, string>): Promise<string | null>;
81
+ export declare function checkRestrictedRoot(transport: LinuxAgentTransport, root: string, env: Record<string, string>, filesLock: string): Promise<string | null>;
@@ -155,9 +155,10 @@ export async function reapLinuxSession(transport, session, options = {}) {
155
155
  * A functional self-check of restricted execution on `root` (an existing directory the device
156
156
  * user owns): a restricted command must list it and create and remove a file in it. Landlock
157
157
  * rules attach to inodes, and some file systems (Docker Desktop's file sharing, for one) do not
158
- * keep them, which would deny every restricted operation there. Returns why it failed, or null.
158
+ * keep them, which would deny every restricted operation there. `filesLock` is the device's files
159
+ * lock, which every restricted launch takes. Returns why it failed, or null.
159
160
  */
160
- export async function checkRestrictedRoot(transport, root, env) {
161
+ export async function checkRestrictedRoot(transport, root, env, filesLock) {
161
162
  const name = `.capybara-restricted-check-${randomUUID()}`;
162
163
  try {
163
164
  const event = await agentRequest(transport, {
@@ -170,6 +171,7 @@ export async function checkRestrictedRoot(transport, root, env) {
170
171
  cwd: root,
171
172
  env,
172
173
  timeoutMs: 20_000,
174
+ filesLock,
173
175
  }, "exit", 60_000, true);
174
176
  return event.exitCode === 0
175
177
  ? null
@@ -83,8 +83,13 @@ export interface LocalBackendHost {
83
83
  restricted: boolean;
84
84
  /** Why restricted operations are unavailable, when they are. */
85
85
  unavailableReason?: string;
86
- /** Full access and background work run on this platform. */
87
- fullAccess: boolean;
86
+ /**
87
+ * Restricted operations enforce the open public network (the closed address classes refused on
88
+ * the resolved address); reported only while restricted operations run.
89
+ */
90
+ openPublic?: boolean;
91
+ /** Escalated calls (outside the sandbox) and background work run on this platform. */
92
+ outsideSandbox: boolean;
88
93
  background: boolean;
89
94
  /** The message a refused restricted operation carries. */
90
95
  pending: string;
@@ -3,7 +3,7 @@ import { resolve } from "node:path";
3
3
  import { parseSandboxBrowseScope, parseSandboxOperationScope, parseSandboxPreparationScope, SandboxPermissionUnsupportedError, SandboxScopeDeniedError, validateSandboxPathShape, } from "@capybara-hq/plugin-sdk";
4
4
  import { implicitWritePaths } from "../policy.js";
5
5
  import { MacOperationSupervisor, } from "./operation-supervisor.js";
6
- import { checkRoots, digest, freezeAuthority, intersectOperation, within, } from "./operation-types.js";
6
+ import { checkRoots, digest, freezeAuthority, grantStillHolds, intersectOperation, within, } from "./operation-types.js";
7
7
  import { timed } from "./transfer-timing.js";
8
8
  const PENDING = "Restricted macOS per-instance validation and coordinated policy/background activation are pending";
9
9
  export async function createMacOperationBackend(options, dependencies = {}) {
@@ -21,8 +21,10 @@ export async function createMacOperationBackend(options, dependencies = {}) {
21
21
  : "Restricted Linux/local-Docker validation remains pending"),
22
22
  }
23
23
  : {}),
24
- fullAccess: platform === "darwin",
24
+ outsideSandbox: platform === "darwin",
25
25
  background: platform === "darwin",
26
+ // the macOS worker's proxy decides the open network on the resolved address (operation-worker)
27
+ openPublic: platform === "darwin",
26
28
  pending: (!restricted && dependencies.unavailableReason) || PENDING,
27
29
  ...(dependencies.startWorker ? { startWorker: dependencies.startWorker } : {}),
28
30
  ...(restricted && dependencies.restrictedProof ? { proof: dependencies.restrictedProof } : {}),
@@ -307,14 +309,24 @@ export async function createLocalOperationBackend(options, dependencies, host) {
307
309
  signal.throwIfAborted();
308
310
  // a transiently failed proof is retried before it is reported (rate-limited, bounded)
309
311
  await host.proof?.refresh();
310
- const c = await read();
312
+ // the owner policy is still read (and checked) here; its outside-sandbox switch is consent,
313
+ // reported in the owner report, never runtime support
314
+ await read();
311
315
  const restricted = restrictedNow();
316
+ // an operation boundary: the sandbox network (the open public internet decided on the
317
+ // resolved address, or the allowlist with per-operation hosts) only with restricted support
312
318
  return {
313
- version: 1,
319
+ version: 2,
320
+ boundary: "operation",
314
321
  restricted: restricted
315
322
  ? { filesystem: true, network: true, native: true, concurrentScopes: true }
316
323
  : null,
317
- fullAccess: host.fullAccess && c.fullAccess,
324
+ network: {
325
+ openPublic: restricted && host.openPublic === true,
326
+ allowlist: restricted,
327
+ perOperationHosts: restricted,
328
+ },
329
+ outsideSandbox: host.outsideSandbox,
318
330
  background: host.background,
319
331
  ...(!restricted
320
332
  ? { unavailableReason: host.proof?.failure() ?? host.unavailableReason ?? host.pending }
@@ -374,11 +386,7 @@ export async function createLocalOperationBackend(options, dependencies, host) {
374
386
  const next = "profile" in record.scope
375
387
  ? intersectOperation(record.scope, ceiling, record.authority, record.kind === "native")
376
388
  : auxiliaryGrant(record.scope, ceiling);
377
- return record.grant.full
378
- ? next.full
379
- : record.grant.hosts.every((h) => next.hosts.includes(h)) &&
380
- record.grant.deniedReadRoots.every((r) => next.deniedReadRoots.includes(r)) &&
381
- next.deniedReadRoots.every((r) => record.grant.deniedReadRoots.includes(r));
389
+ return grantStillHolds(record.grant, next);
382
390
  }
383
391
  catch {
384
392
  return false;
@@ -4,6 +4,8 @@ export interface MacWriteRegexRule {
4
4
  operations: ("file-write*" | "file-write-unlink" | "file-write-create")[];
5
5
  regex: string;
6
6
  }
7
+ /** A literal name as a regex, every letter matched in either case (APFS is case-insensitive). */
8
+ export declare function ci(name: string): string;
7
9
  /**
8
10
  * The shared SDK write policy as ordered SBPL regex rules for one write root (or, with "", any
9
11
  * path), appended after every other write rule; Seatbelt is last-match-wins, so a later rule
@@ -3,7 +3,7 @@ import { basename, dirname, join } from "node:path";
3
3
  import { SANDBOX_GIT_ALLOWED_DIRECTORIES, SANDBOX_GIT_ALLOWED_FILES, SANDBOX_GIT_DENIED_INTERNALS, SANDBOX_MANDATORY_WRITE_DENIES, } from "@capybara-hq/plugin-sdk";
4
4
  const META = /[\\^$.|?*+()[\]{}]/g;
5
5
  /** A literal name as a regex, every letter matched in either case (APFS is case-insensitive). */
6
- function ci(name) {
6
+ export function ci(name) {
7
7
  let out = "";
8
8
  for (const ch of name) {
9
9
  const lower = ch.toLowerCase();
@@ -1,16 +1,23 @@
1
- import { type DeviceExecGrants, type SandboxLimits, type SandboxOperationScope, type SandboxRoots } from "@capybara-hq/plugin-sdk";
1
+ import { type DeviceExecGrants, type DeviceNetworkMode, type SandboxLimits, type SandboxOperationScope, type SandboxRoots } from "@capybara-hq/plugin-sdk";
2
+ /**
3
+ * The owner ceiling as this program enforces it: the fields of the protocol's
4
+ * `DeviceOwnerCeiling` (the device sandbox for every profile) plus the local facts the
5
+ * intersection needs (roots, denied read roots, preparation roots).
6
+ */
2
7
  export interface DeviceOwnerCeiling {
3
8
  readonly revision: string;
4
- readonly fullAccess: boolean;
9
+ /** Whether a call may be granted escalation outside the sandbox (device + environment). */
10
+ readonly outsideSandbox: boolean;
11
+ /** The sandbox network: the open public internet or the {@link allowedDomains} allowlist. */
12
+ readonly network: DeviceNetworkMode;
13
+ readonly allowedDomains: readonly string[];
5
14
  readonly roots: Readonly<SandboxRoots>;
6
15
  readonly restrictedProjectReach: "workspace" | "os-user";
7
- readonly restrictedAllowedDomains: readonly string[];
8
16
  readonly restrictedDeniedReadRoots: readonly string[];
9
17
  readonly preparation: Readonly<{
10
18
  skillsRoot: string;
11
19
  attachmentsBase: string;
12
20
  }>;
13
- readonly fullNetwork: "environment";
14
21
  }
15
22
  export interface LocalExecAuthority {
16
23
  readonly operationId: string;
@@ -18,7 +25,14 @@ export interface LocalExecAuthority {
18
25
  readonly grants?: DeviceExecGrants;
19
26
  }
20
27
  export interface LocalOperationGrant {
28
+ /** Only an escalated call (device + environment): it runs outside the sandbox. */
21
29
  readonly full: boolean;
30
+ /**
31
+ * A sandboxed command may reach the open public internet (the address classes the design closes
32
+ * stay closed). Absent or false: exactly {@link hosts}, so a grant that does not say otherwise
33
+ * fails closed. Never set on a {@link full} grant, which has the escalated call's own network.
34
+ */
35
+ readonly openNetwork?: boolean;
22
36
  readonly readRoots: readonly string[];
23
37
  readonly writeRoots: readonly string[];
24
38
  readonly hosts: readonly string[];
@@ -36,7 +50,7 @@ export declare function readStrictOwnerCeiling(input: {
36
50
  }): Promise<DeviceOwnerCeiling>;
37
51
  /**
38
52
  * {@link readStrictOwnerCeiling}, synchronously (the owner report issues it under the policy lock).
39
- * Only a version-2 policy file is authority: an old format is refused until it is converted.
53
+ * Only a version-3 policy file is authority: an old format is refused until it is converted.
40
54
  */
41
55
  export declare function readStrictOwnerCeilingSync(input: {
42
56
  stateDir: string;
@@ -52,4 +66,20 @@ export declare function readStrictOwnerCeilingSync(input: {
52
66
  export declare function withCanonicalForms(paths: readonly string[]): string[];
53
67
  export declare function checkRoots(read: readonly string[], write: readonly string[], ceiling: DeviceOwnerCeiling, preparation?: boolean): void;
54
68
  export declare function freezeAuthority(a: LocalExecAuthority): LocalExecAuthority;
69
+ /** The refusal of an escalated call the owner ceiling does not allow. */
70
+ export declare const OUTSIDE_SANDBOX_REFUSAL: string;
71
+ /**
72
+ * One operation's scope intersected with the owner ceiling now (approval-only profiles design).
73
+ * Every profile's ordinary call is sandboxed: scoped roots, the owner's denied read roots and the
74
+ * sandbox network. Only an escalated call (`filesystem: device` with `network: environment`) runs
75
+ * outside the sandbox, and only while the owner ceiling allows `outsideSandbox`. The profile in the
76
+ * scope is audit only: it never widens anything here.
77
+ */
55
78
  export declare function intersectOperation(scope: SandboxOperationScope, ceiling: DeviceOwnerCeiling, authority?: LocalExecAuthority, native?: boolean): LocalOperationGrant;
79
+ /**
80
+ * Whether a live operation's grant still holds against the grant the fresh owner ceiling gives the
81
+ * same scope (owner reconcile): a full grant only while the next one is full; a sandboxed grant
82
+ * only while every host, the open network if it had one, and exactly the same denied read roots
83
+ * remain. Anything narrower revokes the operation.
84
+ */
85
+ export declare function grantStillHolds(grant: LocalOperationGrant, next: LocalOperationGrant): boolean;