@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.
- package/README.md +65 -33
- package/dist/api.d.ts +3 -3
- package/dist/args.d.ts +8 -3
- package/dist/args.js +27 -14
- package/dist/cli.js +1 -1
- package/dist/client.js +1 -1
- package/dist/commands/ceiling.d.ts +3 -2
- package/dist/commands/ceiling.js +39 -21
- package/dist/commands/login.d.ts +15 -11
- package/dist/commands/login.js +46 -33
- package/dist/commands/policy.js +16 -10
- package/dist/commands/start.d.ts +11 -3
- package/dist/commands/start.js +25 -9
- package/dist/commands/status.js +10 -6
- package/dist/exec/docker-operations.d.ts +14 -2
- package/dist/exec/docker-operations.js +32 -5
- package/dist/exec/linux-agent.d.ts +13 -3
- package/dist/exec/linux-agent.js +450 -43
- package/dist/exec/linux-operation-backend.d.ts +27 -6
- package/dist/exec/linux-operation-backend.js +30 -9
- package/dist/exec/linux-operation-worker.d.ts +51 -3
- package/dist/exec/linux-operation-worker.js +55 -3
- package/dist/exec/linux-runtime.d.ts +3 -2
- package/dist/exec/linux-runtime.js +4 -2
- package/dist/exec/mac-operation-backend.d.ts +7 -2
- package/dist/exec/mac-operation-backend.js +18 -10
- package/dist/exec/mac-write-policy.d.ts +2 -0
- package/dist/exec/mac-write-policy.js +1 -1
- package/dist/exec/operation-types.d.ts +35 -5
- package/dist/exec/operation-types.js +73 -23
- package/dist/exec/operation-worker.d.ts +80 -1
- package/dist/exec/operation-worker.js +197 -14
- package/dist/exec/protected-targets.d.ts +16 -0
- package/dist/exec/protected-targets.js +53 -0
- package/dist/exec/shared.d.ts +7 -3
- package/dist/exec/shared.js +7 -5
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/CAPYBARA-MODIFICATIONS.patch +343 -7
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/resolved-address-guard.js +220 -6
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-config.js +17 -0
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-manager.js +11 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.d.ts +77 -46
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +206 -83
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +3 -2
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +3 -2
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/network-classes.d.ts +98 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/network-classes.js +291 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-linux-runtime-source.js +460 -28
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-native-runtime-source.js +143 -3
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.d.ts +36 -4
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.js +21 -4
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-runtime-source.js +2 -2
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-write-denies.d.ts +87 -8
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-write-denies.js +249 -10
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox.d.ts +11 -22
- package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
- package/dist/owner-report.d.ts +1 -1
- package/dist/owner-report.js +5 -4
- package/dist/policy-store.d.ts +2 -1
- package/dist/policy-store.js +2 -1
- package/dist/policy.d.ts +23 -14
- package/dist/policy.js +28 -21
- package/dist/runtime-manifest.json +1 -1
- package/dist/server-ops.d.ts +30 -5
- package/dist/server-ops.js +105 -85
- package/dist/staged-connect.d.ts +1 -1
- package/dist/staged-connect.js +1 -1
- package/dist/staged-device.d.ts +1 -1
- package/dist/staged-device.js +7 -5
- package/dist/staged-session.d.ts +1 -1
- package/dist/state.d.ts +41 -21
- package/dist/state.js +102 -45
- 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
|
|
6
|
-
* this file. Protocol 2's frames keep a `Legacy` prefix where a
|
|
7
|
-
* (`LegacyDeviceHello`, `parseLegacyDeviceFrame`, ...); protocol
|
|
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 =
|
|
13
|
+
export const DEVICE_PROTOCOL_VERSION = 4;
|
|
14
14
|
/**
|
|
15
|
-
* Protocol
|
|
16
|
-
* on the header, a protocol close on the hello)
|
|
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 =
|
|
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 `
|
|
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 =
|
|
105
|
-
const 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
|
-
|
|
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
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
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
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
-
"
|
|
716
|
+
"outsideSandbox",
|
|
717
|
+
"network",
|
|
718
|
+
"allowedDomains",
|
|
636
719
|
"restrictedProjectReach",
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
if (o.
|
|
641
|
-
throw new DeviceProtocolError(
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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 !==
|
|
814
|
-
throw new DeviceProtocolError(
|
|
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 =
|
|
929
|
+
const permissionSupport = parseSandboxPermissionSupport(o.permissionSupport);
|
|
819
930
|
if (o.instanceGeneration === null &&
|
|
820
931
|
(o.runtimeIdentity !== undefined ||
|
|
821
932
|
permissionSupport.restricted !== null ||
|
|
822
|
-
permissionSupport.
|
|
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:
|
|
951
|
+
protocol: DEVICE_PROTOCOL_VERSION,
|
|
838
952
|
permissionSupport,
|
|
839
953
|
transport: { maxFrameBytes },
|
|
840
|
-
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:
|
|
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 (![
|
|
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:
|
|
902
|
-
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:
|
|
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 =
|
|
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.
|
|
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.
|
|
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
|
+
};
|