@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
@@ -2,20 +2,21 @@
2
2
  * The device protocol: the WebSocket frames between the kernel and a `capybara-device` program
3
3
  * (a connected machine that serves as a device). Pure types and hand-written guards.
4
4
  *
5
- * Protocol 3 (the scope-bearing operations, `parseDeviceFrame`) is defined in the second half of
6
- * this file. Protocol 2's frames keep a `Legacy` prefix where a protocol 3 name replaced them
7
- * (`LegacyDeviceHello`, `parseLegacyDeviceFrame`, ...); protocol 3 reuses their value guards, and
5
+ * Protocol 4 (the scope-bearing operations, `parseDeviceFrame`) is defined in the second half of
6
+ * this file. Protocol 2's frames keep a `Legacy` prefix where a newer name replaced them
7
+ * (`LegacyDeviceHello`, `parseLegacyDeviceFrame`, ...); protocol 4 reuses their value guards, and
8
8
  * they go with the legacy device surface.
9
9
  */
10
10
  import { isDeviceProjectName, MAX_DEVICE_PROJECT_NAME_LENGTH, MAX_DEVICE_SCAN_DEPTH, MAX_DEVICE_SCAN_RESULTS, validateAllowHost, validateSandboxPathShape, } from "./sandbox.js";
11
11
  import { parseSandboxBrowseScope, parseSandboxExecutionRef, parseSandboxOperationRef, parseSandboxOperationScope, parseSandboxPreparationScope, } from "./sandbox-operation.js";
12
12
  /** The protocol version carried in `X-Capybara-Device-Protocol` and the hello frame. */
13
- export const DEVICE_PROTOCOL_VERSION = 3;
13
+ export const DEVICE_PROTOCOL_VERSION = 4;
14
14
  /**
15
- * Protocol 2's version, which a deployment speaking {@link DEVICE_PROTOCOL_VERSION} refuses (426
16
- * on the header, a protocol close on the hello). Kept only for the legacy device surface.
15
+ * Protocol 3's version, which a deployment speaking {@link DEVICE_PROTOCOL_VERSION} refuses (426
16
+ * on the header, a protocol close on the hello): its owner report and runtime support describe the
17
+ * removed Full access ceiling, so a protocol 3 program must be updated.
17
18
  */
18
- export const LEGACY_DEVICE_PROTOCOL_VERSION = 2;
19
+ export const LEGACY_DEVICE_PROTOCOL_VERSION = 3;
19
20
  const DEVICE_OPS = [
20
21
  "create",
21
22
  "exec",
@@ -34,15 +35,19 @@ const DEVICE_FEATURES = [
34
35
  "networkReport",
35
36
  "policyOp",
36
37
  "policyOpId",
37
- "mode",
38
38
  "projects",
39
39
  ];
40
40
  /** The most entries a `list` op may ask for and its result may carry. */
41
41
  export const MAX_DEVICE_LIST_ENTRIES = 1000;
42
42
  /** The most blocked hosts an exec result reports; the parser cuts longer lists. */
43
43
  export const MAX_NETWORK_BLOCKED_HOSTS = 20;
44
- /** The most hosts a `policy` op's `add` / `remove` or an exec's `grants` may carry. */
44
+ /** The most hosts a `policy` op's `remove` or an exec's `grants` may carry. */
45
45
  const MAX_POLICY_HOSTS = 100;
46
+ /**
47
+ * Why a `policy` op naming hosts to `add` is refused: the deployment may only narrow a local
48
+ * device's sandbox; its owner widens it on the machine.
49
+ */
50
+ export const POLICY_ADD_REFUSED = "The deployment may not add hosts to a device's sandbox allowlist: widening happens only on the machine (capybara-device policy add allowedDomains <host>)";
46
51
  /** The longest `opId` a `policy` / `policyStatus` op may carry. */
47
52
  export const MAX_POLICY_OP_ID_LENGTH = 128;
48
53
  /** The most entries a hello's `recentOps` carries; the parser keeps the newest. */
@@ -100,9 +105,13 @@ function strArray(o, k, label = k) {
100
105
  }
101
106
  return v;
102
107
  }
108
+ /**
109
+ * The exec `limits`: resources and the outer network (no mode: protocol 4 removed it). Unknown
110
+ * keys are refused, so a stale `mode` (or any field the device would ignore) is never accepted.
111
+ */
103
112
  function parseLimits(v) {
104
- const o = obj(v, 'field "limits"');
105
- const network = obj(o.network, 'field "network"');
113
+ const o = strictRecord(v, ["cpu", "memoryMb", "diskMb", "network"], 'field "limits"');
114
+ const network = strictRecord(o.network, ["kind", "hosts"], 'field "network"');
106
115
  const kind = oneOf(network, "kind", ["open-public", "allowlist"]);
107
116
  const hosts = strArray(network, "hosts", "network.hosts");
108
117
  for (const h of hosts) {
@@ -115,7 +124,6 @@ function parseLimits(v) {
115
124
  cpu: num(o, "cpu"),
116
125
  memoryMb: num(o, "memoryMb"),
117
126
  diskMb: num(o, "diskMb"),
118
- mode: oneOf(o, "mode", ["auto", "sandbox"]),
119
127
  network: { kind, hosts },
120
128
  };
121
129
  }
@@ -187,10 +195,6 @@ function absolutePath(v, what) {
187
195
  throw new DeviceProtocolError(`${what}: ${problems.join("; ")}`);
188
196
  return v;
189
197
  }
190
- /** A request's ceiling (`limits` of `list` / `scan`): only its mode. */
191
- function parseCeiling(v) {
192
- return { mode: oneOf(obj(v, 'field "limits"'), "mode", ["auto", "sandbox"]) };
193
- }
194
198
  /** A `list` result: null, or at most {@link MAX_DEVICE_LIST_ENTRIES} named entries. */
195
199
  function parseListResult(result) {
196
200
  if (result === null)
@@ -227,10 +231,7 @@ function parseScanResult(v) {
227
231
  }
228
232
  function parsePolicySummary(v) {
229
233
  const o = obj(v, 'field "policy"');
230
- return {
231
- mode: oneOf(o, "mode", ["auto", "sandbox"]),
232
- allowedDomains: strArray(o, "allowedDomains"),
233
- };
234
+ return { allowedDomains: strArray(o, "allowedDomains") };
234
235
  }
235
236
  /**
236
237
  * Whether `v` is a valid policy op id: non-empty, no `:`, at most
@@ -406,7 +407,6 @@ function validateArgs(op, a) {
406
407
  }
407
408
  case "readFile": {
408
409
  str(a, "path");
409
- parseCeiling(a.limits);
410
410
  const m = a.maxBytes;
411
411
  if (typeof m !== "number" || !Number.isInteger(m) || m < 0) {
412
412
  throw new DeviceProtocolError('field "maxBytes" must be a non-negative integer');
@@ -419,7 +419,6 @@ function validateArgs(op, a) {
419
419
  return;
420
420
  case "stat":
421
421
  str(a, "path");
422
- parseCeiling(a.limits);
423
422
  return;
424
423
  case "killTagged":
425
424
  strArray(a, "tags");
@@ -439,12 +438,11 @@ function validateArgs(op, a) {
439
438
  case "policy": {
440
439
  opId(a);
441
440
  if (a.add !== undefined)
442
- hostArray(a, "add");
441
+ throw new DeviceProtocolError(POLICY_ADD_REFUSED);
442
+ if (a.mode !== undefined)
443
+ throw new DeviceProtocolError('field "mode" is not part of device protocol 4; narrow with "ownerCeiling" instead');
443
444
  if (a.remove !== undefined)
444
445
  hostArray(a, "remove");
445
- if (a.mode !== undefined && a.mode !== "sandbox") {
446
- throw new DeviceProtocolError('field "mode" may only be "sandbox"');
447
- }
448
446
  const src = obj(a.source, 'field "source"');
449
447
  nonEmptyStr(src, "accountId");
450
448
  str(src, "accountName");
@@ -464,12 +462,10 @@ function validateArgs(op, a) {
464
462
  if (limit > MAX_DEVICE_LIST_ENTRIES) {
465
463
  throw new DeviceProtocolError(`field "limit" must be at most ${MAX_DEVICE_LIST_ENTRIES}`);
466
464
  }
467
- parseCeiling(a.limits);
468
465
  return;
469
466
  }
470
467
  case "scan":
471
468
  absolutePath(a.base, 'field "base"');
472
- parseCeiling(a.limits);
473
469
  return;
474
470
  }
475
471
  }
@@ -598,54 +594,171 @@ function freeze(value) {
598
594
  }
599
595
  return value;
600
596
  }
601
- function support(value) {
602
- const o = object(value);
603
- keys(o, ["version", "restricted", "fullAccess", "background", "unavailableReason"]);
604
- if (o.version !== 1 || typeof o.fullAccess !== "boolean" || typeof o.background !== "boolean")
605
- throw new DeviceProtocolError("Invalid runtime permission report");
597
+ /**
598
+ * A strict copy of a wire object for the protocol 4 shapes: a plain object of own data properties
599
+ * only (no accessor is ever invoked, so a value cannot change between check and use), each key in
600
+ * `allowed`. Nested values are copied by the caller's own checks.
601
+ */
602
+ function strictRecord(value, allowed, what) {
603
+ if (typeof value !== "object" || value === null || Array.isArray(value))
604
+ throw new DeviceProtocolError(`Invalid ${what}: expected an object`);
605
+ const proto = Object.getPrototypeOf(value);
606
+ if (proto !== Object.prototype && proto !== null)
607
+ throw new DeviceProtocolError(`Invalid ${what}: expected a plain object`);
608
+ const out = Object.create(null);
609
+ for (const key of Reflect.ownKeys(value)) {
610
+ if (typeof key !== "string" || !allowed.includes(key))
611
+ throw new DeviceProtocolError(`Invalid ${what}: unknown field ${String(key)}`);
612
+ const d = Object.getOwnPropertyDescriptor(value, key);
613
+ if (!d || !("value" in d))
614
+ throw new DeviceProtocolError(`Invalid ${what}: accessor fields are not allowed`);
615
+ if (d.value !== undefined)
616
+ out[key] = d.value;
617
+ }
618
+ return out;
619
+ }
620
+ function strictHosts(value, what) {
621
+ if (!Array.isArray(value))
622
+ throw new DeviceProtocolError(`Invalid ${what}: expected at most 100 hosts`);
623
+ // one read of the length: a proxy or a getter cannot grow the list between check and copy
624
+ const length = value.length;
625
+ if (length > 100)
626
+ throw new DeviceProtocolError(`Invalid ${what}: expected at most 100 hosts`);
627
+ const hosts = [];
628
+ for (let i = 0; i < length; i++) {
629
+ const d = Object.getOwnPropertyDescriptor(value, i);
630
+ const h = d && "value" in d ? d.value : undefined;
631
+ if (typeof h !== "string" || validateAllowHost(h).length)
632
+ throw new DeviceProtocolError(`Invalid ${what}: expected hostnames or *.domain patterns`);
633
+ hosts.push(h);
634
+ }
635
+ return hosts;
636
+ }
637
+ function strictBoolean(o, key, what) {
638
+ const v = o[key];
639
+ if (typeof v !== "boolean")
640
+ throw new DeviceProtocolError(`Invalid ${what}: ${key} must be a boolean`);
641
+ return v;
642
+ }
643
+ /**
644
+ * Strictly parses a runtime permission report, version 2 (the protocol 4 `permissionSupport`, also
645
+ * the shape a cloud provider reports), and returns a frozen copy; throws {@link DeviceProtocolError}.
646
+ * Restricted support is all four claims or `null`; per-operation hosts need the allowlist; an
647
+ * operation boundary without restricted support claims no sandbox network at all. An
648
+ * instance boundary is the whole instance: it claims no restricted per-operation scope, no
649
+ * outside-sandbox escalation and no per-operation hosts (a host joins the device's list instead).
650
+ */
651
+ export function parseSandboxPermissionSupport(value) {
652
+ const what = "runtime permission report";
653
+ const o = strictRecord(value, [
654
+ "version",
655
+ "boundary",
656
+ "restricted",
657
+ "network",
658
+ "outsideSandbox",
659
+ "background",
660
+ "unavailableReason",
661
+ ], what);
662
+ if (o.version !== 2)
663
+ throw new DeviceProtocolError(`Invalid ${what}: expected version 2`);
664
+ if (o.boundary !== "operation" && o.boundary !== "instance")
665
+ throw new DeviceProtocolError(`Invalid ${what}: boundary must be operation or instance`);
666
+ let restricted = null;
606
667
  if (o.restricted !== null) {
607
- const r = object(o.restricted);
608
- keys(r, ["filesystem", "network", "native", "concurrentScopes"]);
609
- for (const k of ["filesystem", "network", "native", "concurrentScopes"])
610
- if (r[k] !== true)
611
- throw new DeviceProtocolError("Incomplete restricted runtime report");
668
+ const claims = ["filesystem", "network", "native", "concurrentScopes"];
669
+ const r = strictRecord(o.restricted, claims, `${what} restricted claims`);
670
+ if (claims.some((k) => r[k] !== true))
671
+ throw new DeviceProtocolError(`Invalid ${what}: restricted support needs all four claims`);
672
+ restricted = { filesystem: true, network: true, native: true, concurrentScopes: true };
612
673
  }
674
+ const n = strictRecord(o.network, ["openPublic", "allowlist", "perOperationHosts"], `${what} network`);
675
+ const network = {
676
+ openPublic: strictBoolean(n, "openPublic", what),
677
+ allowlist: strictBoolean(n, "allowlist", what),
678
+ perOperationHosts: strictBoolean(n, "perOperationHosts", what),
679
+ };
680
+ if (o.boundary === "operation" &&
681
+ restricted === null &&
682
+ (network.openPublic || network.allowlist || network.perOperationHosts))
683
+ throw new DeviceProtocolError(`Invalid ${what}: without restricted support an operation boundary has no sandbox network`);
684
+ if (network.perOperationHosts && !network.allowlist)
685
+ throw new DeviceProtocolError(`Invalid ${what}: per-operation hosts need the allowlist`);
686
+ const outsideSandbox = strictBoolean(o, "outsideSandbox", what);
687
+ const background = strictBoolean(o, "background", what);
688
+ if (o.boundary === "instance" &&
689
+ (restricted !== null || outsideSandbox || network.perOperationHosts))
690
+ throw new DeviceProtocolError(`Invalid ${what}: an instance boundary claims no restricted scope, outside escalation or per-operation hosts`);
613
691
  if (o.unavailableReason !== undefined)
614
692
  string(o.unavailableReason, 4096);
615
- return o;
693
+ return freeze({
694
+ version: 2,
695
+ boundary: o.boundary,
696
+ restricted,
697
+ network,
698
+ outsideSandbox,
699
+ background,
700
+ ...(o.unavailableReason !== undefined
701
+ ? { unavailableReason: o.unavailableReason }
702
+ : {}),
703
+ });
616
704
  }
617
- /** Strictly parses one authenticated owner-ceiling report (B2); throws {@link DeviceProtocolError}. */
705
+ /**
706
+ * Strictly parses one authenticated owner-ceiling report of protocol 4 and returns a frozen copy;
707
+ * throws {@link DeviceProtocolError}. Unknown fields (the protocol 3 `fullAccess` and
708
+ * `restrictedAllowedDomains` among them) are refused.
709
+ */
618
710
  export function parseOwnerCeilingReport(value) {
619
- return freeze(structuredClone(owner(value)));
620
- }
621
- function narrowing(value) {
622
- const o = object(value);
623
- keys(o, ["fullAccess", "restrictedProjectReach"]);
624
- if ((o.fullAccess !== undefined && o.fullAccess !== false) ||
625
- (o.restrictedProjectReach !== undefined && o.restrictedProjectReach !== "workspace"))
626
- throw new DeviceProtocolError("The deployment may only narrow the owner ceiling");
627
- return o;
628
- }
629
- function owner(value) {
630
- const o = object(value);
631
- keys(o, [
711
+ const what = "owner ceiling report";
712
+ const o = strictRecord(value, [
632
713
  "version",
633
714
  "sequence",
634
715
  "revision",
635
- "fullAccess",
716
+ "outsideSandbox",
717
+ "network",
718
+ "allowedDomains",
636
719
  "restrictedProjectReach",
637
- "restrictedAllowedDomains",
638
- ]);
639
- integer(o.sequence);
640
- if (o.version !== 2 || !["workspace", "os-user"].includes(String(o.restrictedProjectReach)))
641
- throw new DeviceProtocolError("Invalid owner ceiling report version or project reach");
642
- string(o.revision, 512);
643
- if (typeof o.fullAccess !== "boolean" ||
644
- !Array.isArray(o.restrictedAllowedDomains) ||
645
- o.restrictedAllowedDomains.length > 100 ||
646
- o.restrictedAllowedDomains.some((h) => typeof h !== "string" || validateAllowHost(h).length))
647
- throw new DeviceProtocolError("Invalid owner ceiling");
648
- return o;
720
+ ], what);
721
+ if (o.version !== 3)
722
+ throw new DeviceProtocolError(`Invalid ${what}: expected version 3`);
723
+ if (o.network !== "open" && o.network !== "allowlist")
724
+ throw new DeviceProtocolError(`Invalid ${what}: network must be open or allowlist`);
725
+ if (o.restrictedProjectReach !== "workspace" && o.restrictedProjectReach !== "os-user")
726
+ throw new DeviceProtocolError(`Invalid ${what}: project reach must be workspace or os-user`);
727
+ return freeze({
728
+ version: 3,
729
+ sequence: integer(o.sequence),
730
+ revision: string(o.revision, 512),
731
+ outsideSandbox: strictBoolean(o, "outsideSandbox", what),
732
+ network: o.network,
733
+ allowedDomains: strictHosts(o.allowedDomains, `${what} allowedDomains`),
734
+ restrictedProjectReach: o.restrictedProjectReach,
735
+ });
736
+ }
737
+ /**
738
+ * Strictly parses an owner-ceiling narrowing of protocol 4 and returns a frozen copy; throws
739
+ * {@link DeviceProtocolError}. Every field can only narrow: `outsideSandbox` only to `false`,
740
+ * `network` only to `allowlist`, the project reach only to `workspace`, and hosts only removed.
741
+ * There is no way to name a host to add or a list to replace.
742
+ */
743
+ export function parseOwnerCeilingNarrowing(value) {
744
+ const what = "owner ceiling narrowing";
745
+ const o = strictRecord(value, ["outsideSandbox", "network", "removeAllowedDomains", "restrictedProjectReach"], what);
746
+ if ((Object.hasOwn(o, "outsideSandbox") && o.outsideSandbox !== false) ||
747
+ (Object.hasOwn(o, "network") && o.network !== "allowlist") ||
748
+ (Object.hasOwn(o, "restrictedProjectReach") && o.restrictedProjectReach !== "workspace"))
749
+ throw new DeviceProtocolError("The deployment may only narrow the owner ceiling");
750
+ return freeze({
751
+ ...(Object.hasOwn(o, "outsideSandbox") ? { outsideSandbox: false } : {}),
752
+ ...(Object.hasOwn(o, "network") ? { network: "allowlist" } : {}),
753
+ ...(Object.hasOwn(o, "removeAllowedDomains")
754
+ ? {
755
+ removeAllowedDomains: strictHosts(o.removeAllowedDomains, `${what} removeAllowedDomains`),
756
+ }
757
+ : {}),
758
+ ...(Object.hasOwn(o, "restrictedProjectReach")
759
+ ? { restrictedProjectReach: "workspace" }
760
+ : {}),
761
+ });
649
762
  }
650
763
  const GENERATION = /^[0-9]{1,16}$/;
651
764
  const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
@@ -682,7 +795,7 @@ function request(o) {
682
795
  const id = string(o.id), op = string(o.op), a = object(o.args), deadlineMs = integer(o.deadlineMs, 1);
683
796
  if (legacy.includes(op)) {
684
797
  if (op === "policy" && a.ownerCeiling !== undefined)
685
- narrowing(a.ownerCeiling);
798
+ a.ownerCeiling = parseOwnerCeilingNarrowing(a.ownerCeiling);
686
799
  const parsed = parseLegacyDeviceFrame(JSON.stringify(o), "kernel");
687
800
  if (parsed.type !== "req")
688
801
  throw new DeviceProtocolError("Expected request");
@@ -752,9 +865,7 @@ function request(o) {
752
865
  delete validated.retainUntilMs;
753
866
  }
754
867
  }
755
- else if (native !== "writeFile")
756
- validated.limits = { mode: "sandbox" };
757
- // Reuse v2's pure value guards; inserted mode is never returned or used as authority.
868
+ // Reuse the legacy pure value guards on the native fields.
758
869
  parseLegacyDeviceFrame(JSON.stringify({ type: "req", id, op: native, args: validated, deadlineMs }), "kernel");
759
870
  if (native === "writeFile" && (typeof a.dataB64 !== "string" || !isBase64(a.dataB64)))
760
871
  throw new DeviceProtocolError("Invalid base64 payload");
@@ -781,7 +892,7 @@ function isBase64(value) {
781
892
  }
782
893
  return true;
783
894
  }
784
- /** Strictly parses one protocol 3 frame; throws {@link DeviceProtocolError}. */
895
+ /** Strictly parses one protocol 4 frame; throws {@link DeviceProtocolError}. */
785
896
  export function parseDeviceFrame(raw, from, maxFrameBytes) {
786
897
  if (maxFrameBytes !== undefined &&
787
898
  new TextEncoder().encode(raw).byteLength > integer(maxFrameBytes, 1))
@@ -810,16 +921,19 @@ export function parseDeviceFrame(raw, from, maxFrameBytes) {
810
921
  return request(o);
811
922
  }
812
923
  if (o.type === "hello") {
813
- if (from !== "device" || o.protocol !== 3)
814
- throw new DeviceProtocolError("Expected protocol 3 hello");
924
+ if (from !== "device" || o.protocol !== DEVICE_PROTOCOL_VERSION)
925
+ throw new DeviceProtocolError(`Expected protocol ${DEVICE_PROTOCOL_VERSION} hello`);
815
926
  const transport = object(o.transport);
816
927
  keys(transport, ["maxFrameBytes"]);
817
928
  const maxFrameBytes = integer(transport.maxFrameBytes, 1024);
818
- const permissionSupport = support(o.permissionSupport);
929
+ const permissionSupport = parseSandboxPermissionSupport(o.permissionSupport);
819
930
  if (o.instanceGeneration === null &&
820
931
  (o.runtimeIdentity !== undefined ||
821
932
  permissionSupport.restricted !== null ||
822
- permissionSupport.fullAccess ||
933
+ permissionSupport.outsideSandbox ||
934
+ permissionSupport.network.openPublic ||
935
+ permissionSupport.network.allowlist ||
936
+ permissionSupport.network.perOperationHosts ||
823
937
  permissionSupport.background ||
824
938
  !permissionSupport.unavailableReason))
825
939
  throw new DeviceProtocolError("Unbound hello cannot advertise runtime capability");
@@ -834,10 +948,10 @@ export function parseDeviceFrame(raw, from, maxFrameBytes) {
834
948
  }
835
949
  return freeze({
836
950
  ...base,
837
- protocol: 3,
951
+ protocol: DEVICE_PROTOCOL_VERSION,
838
952
  permissionSupport,
839
953
  transport: { maxFrameBytes },
840
- ownerCeiling: owner(o.ownerCeiling),
954
+ ownerCeiling: parseOwnerCeilingReport(o.ownerCeiling),
841
955
  instanceGeneration: o.instanceGeneration === null ? null : string(o.instanceGeneration),
842
956
  ...(runtimeIdentity && { runtimeIdentity }),
843
957
  });
@@ -849,7 +963,7 @@ export function parseDeviceFrame(raw, from, maxFrameBytes) {
849
963
  const base = parseLegacyDeviceFrame(JSON.stringify({ type: "policy", policy: o.policy }), from);
850
964
  if (base.type !== "policy")
851
965
  throw new DeviceProtocolError("Expected policy");
852
- return freeze({ ...base, ownerCeiling: owner(o.ownerCeiling) });
966
+ return freeze({ ...base, ownerCeiling: parseOwnerCeilingReport(o.ownerCeiling) });
853
967
  }
854
968
  if (o.type === "res" && o.ok === false) {
855
969
  if (from !== "device")
@@ -857,7 +971,16 @@ export function parseDeviceFrame(raw, from, maxFrameBytes) {
857
971
  keys(o, ["type", "id", "ok", "error"]);
858
972
  const e = object(o.error);
859
973
  keys(e, ["kind", "message"]);
860
- if (!["gone", "fs_gone", "policy", "error", "denied", "unsupported", "unknown"].includes(String(e.kind)))
974
+ if (![
975
+ "gone",
976
+ "fs_gone",
977
+ "policy",
978
+ "error",
979
+ "denied",
980
+ "unsupported",
981
+ "unknown",
982
+ "invalid",
983
+ ].includes(String(e.kind)))
861
984
  throw new DeviceProtocolError("Unknown outcome kind");
862
985
  return freeze({
863
986
  type: "res",
@@ -898,8 +1021,8 @@ export function parseOperationResult(op, result, request) {
898
1021
  instanceGeneration: request.instanceGeneration,
899
1022
  bindingId: request.bindingId,
900
1023
  runtimeIdentity,
901
- permissionSupport: support(o.permissionSupport),
902
- ownerCeiling: owner(o.ownerCeiling),
1024
+ permissionSupport: parseSandboxPermissionSupport(o.permissionSupport),
1025
+ ownerCeiling: parseOwnerCeilingReport(o.ownerCeiling),
903
1026
  });
904
1027
  }
905
1028
  if (op === "backgroundReadOutput") {
@@ -966,7 +1089,7 @@ export function parseOperationResult(op, result, request) {
966
1089
  keys(o, ["policy", "ownerCeiling"]);
967
1090
  return freeze({
968
1091
  ...parseOpResult("policy", { policy: o.policy }),
969
- ownerCeiling: owner(o.ownerCeiling),
1092
+ ownerCeiling: parseOwnerCeilingReport(o.ownerCeiling),
970
1093
  });
971
1094
  }
972
1095
  if (op === "policyStatus") {
@@ -977,7 +1100,7 @@ export function parseOperationResult(op, result, request) {
977
1100
  if (status.outcome === "applied" && ownerCeiling === undefined)
978
1101
  throw new DeviceProtocolError("An applied policy status carries the owner report");
979
1102
  if (ownerCeiling !== undefined)
980
- status.ownerCeiling = owner(ownerCeiling);
1103
+ status.ownerCeiling = parseOwnerCeilingReport(ownerCeiling);
981
1104
  return freeze(status);
982
1105
  }
983
1106
  if (op === "revokeOperation") {
@@ -1,4 +1,4 @@
1
- export declare const SDK_VERSION = "0.1.0-rc.38";
1
+ export declare const SDK_VERSION = "0.1.0-rc.39";
2
2
  export * from "./agent-template.js";
3
3
  export * from "./bootstrap.js";
4
4
  export * from "./cards.js";
@@ -24,6 +24,7 @@ export * from "./marketplace.js";
24
24
  export * from "./model.js";
25
25
  export * from "./model-params.js";
26
26
  export * from "./net.js";
27
+ export * from "./network-classes.js";
27
28
  export * from "./org-access.js";
28
29
  export * from "./permissions.js";
29
30
  export * from "./plugin-manifest.js";
@@ -31,7 +32,7 @@ export * from "./plugin-package.js";
31
32
  export * from "./sandbox.js";
32
33
  export * from "./sandbox-operation.js";
33
34
  export { SANDBOX_RUNTIME_SOURCE } from "./sandbox-runtime-source.js";
34
- export { isSandboxMoveDenied, isSandboxWriteDenied, SANDBOX_GIT_ALLOWED_DIRECTORIES, SANDBOX_GIT_ALLOWED_FILES, SANDBOX_GIT_DENIED_INTERNALS, SANDBOX_MANDATORY_WRITE_DENIES, SANDBOX_PROTECTED_PATH_NAMES, } from "./sandbox-write-denies.js";
35
+ export { isSandboxHomeWriteDenied, isSandboxMoveDenied, isSandboxWriteDenied, SANDBOX_GIT_ALLOWED_DIRECTORIES, SANDBOX_GIT_ALLOWED_FILES, SANDBOX_GIT_DENIED_INTERNALS, SANDBOX_HOME_WRITE_DENIES, SANDBOX_MANDATORY_WRITE_DENIES, SANDBOX_PROTECTED_PATH_NAMES, SANDBOX_RESERVED_NAME_PREFIX, SANDBOX_RUNTIME_DIRECTORIES, SANDBOX_SYSTEM_WRITE_DENIES, sandboxRuntimeDirectoryOf, } from "./sandbox-write-denies.js";
35
36
  export * from "./secret.js";
36
37
  export * from "./setup-check.js";
37
38
  export * from "./setup-guide.js";
@@ -1,4 +1,4 @@
1
- export const SDK_VERSION = "0.1.0-rc.38";
1
+ export const SDK_VERSION = "0.1.0-rc.39";
2
2
  export * from "./agent-template.js";
3
3
  export * from "./bootstrap.js";
4
4
  export * from "./cards.js";
@@ -24,6 +24,7 @@ export * from "./marketplace.js";
24
24
  export * from "./model.js";
25
25
  export * from "./model-params.js";
26
26
  export * from "./net.js";
27
+ export * from "./network-classes.js";
27
28
  export * from "./org-access.js";
28
29
  export * from "./permissions.js";
29
30
  export * from "./plugin-manifest.js";
@@ -31,7 +32,7 @@ export * from "./plugin-package.js";
31
32
  export * from "./sandbox.js";
32
33
  export * from "./sandbox-operation.js";
33
34
  export { SANDBOX_RUNTIME_SOURCE } from "./sandbox-runtime-source.js";
34
- export { isSandboxMoveDenied, isSandboxWriteDenied, SANDBOX_GIT_ALLOWED_DIRECTORIES, SANDBOX_GIT_ALLOWED_FILES, SANDBOX_GIT_DENIED_INTERNALS, SANDBOX_MANDATORY_WRITE_DENIES, SANDBOX_PROTECTED_PATH_NAMES, } from "./sandbox-write-denies.js";
35
+ export { isSandboxHomeWriteDenied, isSandboxMoveDenied, isSandboxWriteDenied, SANDBOX_GIT_ALLOWED_DIRECTORIES, SANDBOX_GIT_ALLOWED_FILES, SANDBOX_GIT_DENIED_INTERNALS, SANDBOX_HOME_WRITE_DENIES, SANDBOX_MANDATORY_WRITE_DENIES, SANDBOX_PROTECTED_PATH_NAMES, SANDBOX_RESERVED_NAME_PREFIX, SANDBOX_RUNTIME_DIRECTORIES, SANDBOX_SYSTEM_WRITE_DENIES, sandboxRuntimeDirectoryOf, } from "./sandbox-write-denies.js";
35
36
  export * from "./secret.js";
36
37
  export * from "./setup-check.js";
37
38
  export * from "./setup-guide.js";
@@ -0,0 +1,98 @@
1
+ /**
2
+ * The address classes of the sandbox network (approval-only profiles design, "Open network"): pure
3
+ * data plus {@link classifyAddress}. The device workers (macOS SRT, the Linux forwarder) and the
4
+ * cloud providers' egress proxies decide every sandboxed connection on the resolved address with
5
+ * this one table, so the classes cannot drift between them.
6
+ *
7
+ * The table ({@link ADDRESS_CLASS_RANGES}) is data a copy in another language can mirror (the Linux
8
+ * forwarder's Python): the class of an address is that of the longest-prefix range containing it.
9
+ * Every family ends with a catch-all, so the table is total.
10
+ */
11
+ /**
12
+ * The class of one IP address.
13
+ *
14
+ * - `public`: globally routable; the only class open in `open-public` mode.
15
+ * - `private`: `10/8`, `172.16/12`, `192.168/16`.
16
+ * - `cgnat`: `100.64/10`.
17
+ * - `ula`: IPv6 unique local `fc00::/7` (except the metadata address).
18
+ * - `link-local`: `169.254/16` and `fe80::/10` (except the metadata addresses).
19
+ * - `metadata`: cloud metadata endpoints (`169.254.169.254`, `fd00:ec2::254`).
20
+ * - `loopback`: `127/8`, `::1`.
21
+ * - `multicast`, `broadcast`, `unspecified` (`0/8`, `::`), `nat64` (the NAT64 prefixes),
22
+ * `reserved` (every other special-purpose range).
23
+ *
24
+ * The host's own interface addresses are not a class of the table: the worker that knows them
25
+ * closes them in addition (a placeholder in the table test).
26
+ */
27
+ export type AddressClass = "public" | "private" | "cgnat" | "ula" | "link-local" | "metadata" | "loopback" | "multicast" | "broadcast" | "unspecified" | "nat64" | "reserved";
28
+ /** Every class closed in `open-public` mode: reachable only by running outside the sandbox. */
29
+ export declare const OPEN_PUBLIC_DENIED_CLASSES: readonly AddressClass[];
30
+ /**
31
+ * One range of the address-class table. A range with `embeddedIpv4At` is an IPv6 form that carries
32
+ * an IPv4 address (v4-mapped, SIIT, v4-compatible, 6to4): the address classifies as the 32-bit IPv4
33
+ * address starting at that bit offset (from the most significant bit). The NAT64 prefixes are not
34
+ * such ranges: the design closes them whatever they embed.
35
+ */
36
+ export type AddressClassRange = {
37
+ readonly family: "ipv4" | "ipv6";
38
+ /** `address/prefix`, the address in its canonical lower-case form. */
39
+ readonly cidr: string;
40
+ readonly class: AddressClass;
41
+ } | {
42
+ readonly family: "ipv6";
43
+ readonly cidr: string;
44
+ readonly embeddedIpv4At: number;
45
+ };
46
+ /**
47
+ * The address-class table, most specific range first within each family (longest prefix wins).
48
+ * IPv4 follows the kernel's `net/public-address.ts` (and the sandbox-docker egress proxy); IPv6
49
+ * does too, plus closures the design adds: the well-known NAT64 prefixes (`64:ff9b::/96`,
50
+ * `64:ff9b:1::/48`) whatever they embed, `2001::/23` (Teredo, ORCHID and the other IETF
51
+ * assignments), `3fff::/20`, and everything outside global unicast `2000::/3`.
52
+ *
53
+ * Not covered: an operator-specific NAT64 prefix (a network-specific prefix, RFC 6052, announced
54
+ * by the local DNS64) is ordinary global unicast here, so a private IPv4 address reached through
55
+ * it classifies as public. A worker on such a network resolves through a resolver it trusts or adds
56
+ * the prefix to its own deny list.
57
+ */
58
+ export declare const ADDRESS_CLASS_RANGES: readonly AddressClassRange[];
59
+ /**
60
+ * Classifies one IPv4 or IPv6 address literal by {@link ADDRESS_CLASS_RANGES}. IPv6 may carry a
61
+ * zone (`fe80::1%en0`) and a trailing dotted IPv4 address; an IPv6 form that embeds an IPv4 address
62
+ * (v4-mapped and the others in the table) classifies as that IPv4 address, except NAT64. Throws on a
63
+ * string that is not an IP address: brackets, ports, short, octal or hex IPv4 forms, and an IPv4
64
+ * address with a zone.
65
+ */
66
+ export declare function classifyAddress(ip: string): AddressClass;
67
+ /**
68
+ * Every address closed in `open-public` mode as one CIDR list (IPv4, then IPv6), computed from
69
+ * {@link ADDRESS_CLASS_RANGES}: for a consumer that can only deny ranges (the macOS runtime's
70
+ * resolved-address deny list). Embedded forms are expanded (the v4-mapped, SIIT, v4-compatible and
71
+ * 6to4 sub-ranges of every closed IPv4 range), and adjacent closed blocks are merged. An address
72
+ * is in a listed CIDR exactly when {@link classifyAddress} gives it a closed class.
73
+ */
74
+ export declare const OPEN_PUBLIC_DENIED_CIDRS: readonly string[];
75
+ /**
76
+ * Encrypted DNS for a network whose resolver answers with fake IPs (maintainer decision
77
+ * 2026-11-19): a router running a fake-IP proxy (OpenClash and the like) intercepts every port-53
78
+ * query and answers each name with an address in {@link fakeIpCidr} (`198.18.0.0/15`, a reserved
79
+ * class), so in open mode every name would resolve to a closed address. When the system
80
+ * resolver's answer for a name contains such an address, a sandbox egress proxy re-resolves the
81
+ * name (A and AAAA) through DNS-over-HTTPS (RFC 8484, GET, wire format) at these IP-literal
82
+ * endpoints, in order (Cloudflare, then Google as the fallback), verifying TLS against the
83
+ * endpoint's IP SAN so no DNS is needed to reach them. {@link timeoutMs} is one overall deadline
84
+ * per name, covering A and AAAA and every endpoint; each endpoint gets its share of the time left.
85
+ * An answer is cached only when both queries succeeded, for its TTL, at most
86
+ * {@link cacheTtlCapSeconds}, and for at most {@link cacheMaxNames} names. The real address is
87
+ * classified like any resolved address and dialled as checked. When encrypted DNS fails the
88
+ * connection is refused, naming the fake-IP resolver; the fake address is never dialled. The same
89
+ * rule applies to an allowlisted name. Shared by the macOS worker and the Linux forwarder, so both
90
+ * keep identical endpoints and limits.
91
+ */
92
+ export declare const SANDBOX_FAKE_IP_DNS: {
93
+ readonly fakeIpCidr: string;
94
+ readonly endpoints: readonly string[];
95
+ readonly timeoutMs: number;
96
+ readonly cacheTtlCapSeconds: number;
97
+ readonly cacheMaxNames: number;
98
+ };