@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
@@ -0,0 +1,291 @@
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
+ /** Every class closed in `open-public` mode: reachable only by running outside the sandbox. */
12
+ export const OPEN_PUBLIC_DENIED_CLASSES = Object.freeze([
13
+ "private",
14
+ "cgnat",
15
+ "ula",
16
+ "link-local",
17
+ "metadata",
18
+ "loopback",
19
+ "multicast",
20
+ "broadcast",
21
+ "unspecified",
22
+ "nat64",
23
+ "reserved",
24
+ ]);
25
+ const range = (family, cidr, cls) => Object.freeze({ family, cidr, class: cls });
26
+ const embedded = (cidr, at) => Object.freeze({ family: "ipv6", cidr, embeddedIpv4At: at });
27
+ /**
28
+ * The address-class table, most specific range first within each family (longest prefix wins).
29
+ * IPv4 follows the kernel's `net/public-address.ts` (and the sandbox-docker egress proxy); IPv6
30
+ * does too, plus closures the design adds: the well-known NAT64 prefixes (`64:ff9b::/96`,
31
+ * `64:ff9b:1::/48`) whatever they embed, `2001::/23` (Teredo, ORCHID and the other IETF
32
+ * assignments), `3fff::/20`, and everything outside global unicast `2000::/3`.
33
+ *
34
+ * Not covered: an operator-specific NAT64 prefix (a network-specific prefix, RFC 6052, announced
35
+ * by the local DNS64) is ordinary global unicast here, so a private IPv4 address reached through
36
+ * it classifies as public. A worker on such a network resolves through a resolver it trusts or adds
37
+ * the prefix to its own deny list.
38
+ */
39
+ export const ADDRESS_CLASS_RANGES = Object.freeze([
40
+ range("ipv4", "100.100.100.200/32", "metadata"), // Alibaba Cloud, inside CGNAT
41
+ range("ipv4", "168.63.129.16/32", "metadata"), // Azure WireServer
42
+ range("ipv4", "169.254.169.254/32", "metadata"),
43
+ range("ipv4", "255.255.255.255/32", "broadcast"),
44
+ range("ipv4", "192.0.0.0/24", "reserved"), // IETF protocol assignments
45
+ range("ipv4", "192.0.2.0/24", "reserved"), // TEST-NET-1
46
+ range("ipv4", "192.88.99.0/24", "reserved"), // 6to4 relay anycast
47
+ range("ipv4", "198.51.100.0/24", "reserved"), // TEST-NET-2
48
+ range("ipv4", "203.0.113.0/24", "reserved"), // TEST-NET-3
49
+ range("ipv4", "169.254.0.0/16", "link-local"),
50
+ range("ipv4", "192.168.0.0/16", "private"),
51
+ range("ipv4", "198.18.0.0/15", "reserved"), // benchmarking
52
+ range("ipv4", "172.16.0.0/12", "private"),
53
+ range("ipv4", "100.64.0.0/10", "cgnat"),
54
+ range("ipv4", "0.0.0.0/8", "unspecified"),
55
+ range("ipv4", "10.0.0.0/8", "private"),
56
+ range("ipv4", "127.0.0.0/8", "loopback"),
57
+ range("ipv4", "224.0.0.0/4", "multicast"),
58
+ range("ipv4", "240.0.0.0/4", "reserved"),
59
+ range("ipv4", "0.0.0.0/0", "public"),
60
+ range("ipv6", "::/128", "unspecified"),
61
+ range("ipv6", "::1/128", "loopback"),
62
+ range("ipv6", "fd00:ec2::254/128", "metadata"), // AWS IMDS over IPv6, inside ULA
63
+ embedded("::ffff:0:0/96", 96), // v4-mapped
64
+ embedded("::ffff:0:0:0/96", 96), // SIIT IPv4-translated
65
+ range("ipv6", "64:ff9b::/96", "nat64"),
66
+ embedded("::/96", 96), // v4-compatible (deprecated)
67
+ range("ipv6", "100::/64", "reserved"), // discard-only
68
+ range("ipv6", "64:ff9b:1::/48", "nat64"), // local-use NAT64
69
+ range("ipv6", "2001:db8::/32", "reserved"), // documentation
70
+ range("ipv6", "2001::/23", "reserved"), // IETF protocol assignments: Teredo, ORCHID, …
71
+ range("ipv6", "3fff::/20", "reserved"), // documentation (RFC 9637)
72
+ embedded("2002::/16", 16), // 6to4
73
+ range("ipv6", "fe80::/10", "link-local"),
74
+ range("ipv6", "fec0::/10", "reserved"), // deprecated site-local
75
+ range("ipv6", "ff00::/8", "multicast"),
76
+ range("ipv6", "fc00::/7", "ula"),
77
+ range("ipv6", "2000::/3", "public"),
78
+ range("ipv6", "::/0", "reserved"), // unallocated outside global unicast
79
+ ]);
80
+ const OCTET = /^(0|[1-9][0-9]{0,2})$/;
81
+ const GROUP = /^[0-9a-fA-F]{1,4}$/;
82
+ const ZONE = /^[0-9A-Za-z._~-]+$/;
83
+ /** A strict dotted-quad IPv4 address as a number; null otherwise (no octal, hex or short forms). */
84
+ function ipv4Value(ip) {
85
+ const parts = ip.split(".");
86
+ if (parts.length !== 4)
87
+ return null;
88
+ let value = 0;
89
+ for (const part of parts) {
90
+ if (!OCTET.test(part))
91
+ return null;
92
+ const octet = Number(part);
93
+ if (octet > 255)
94
+ return null;
95
+ value = value * 256 + octet;
96
+ }
97
+ return value;
98
+ }
99
+ /** An IPv6 address (optionally with a trailing dotted IPv4 address) as a 128-bit value; or null. */
100
+ function ipv6Value(ip) {
101
+ const halves = ip.split("::");
102
+ if (halves.length > 2)
103
+ return null;
104
+ const side = (s) => {
105
+ if (s === undefined || s === "")
106
+ return [];
107
+ const parts = s.split(":");
108
+ const groups = [];
109
+ for (let i = 0; i < parts.length; i++) {
110
+ const part = parts[i];
111
+ if (i === parts.length - 1 && part.includes(".")) {
112
+ const v4 = ipv4Value(part);
113
+ if (v4 === null)
114
+ return null;
115
+ groups.push((v4 >>> 16).toString(16), (v4 & 0xffff).toString(16));
116
+ }
117
+ else if (GROUP.test(part))
118
+ groups.push(part);
119
+ else
120
+ return null;
121
+ }
122
+ return groups;
123
+ };
124
+ const head = side(halves[0]);
125
+ const tail = halves.length === 2 ? side(halves[1]) : [];
126
+ if (head === null || tail === null)
127
+ return null;
128
+ // a trailing IPv4 address may only end the address
129
+ if (halves.length === 2 && halves[0]?.includes("."))
130
+ return null;
131
+ const count = head.length + tail.length;
132
+ if (halves.length === 2 ? count > 7 : count !== 8)
133
+ return null;
134
+ const groups = [...head, ...Array(8 - count).fill("0"), ...tail];
135
+ let value = 0n;
136
+ for (const g of groups)
137
+ value = (value << 16n) | BigInt(Number.parseInt(g, 16));
138
+ return value;
139
+ }
140
+ const compiled = ADDRESS_CLASS_RANGES.map((entry) => {
141
+ const [address = "", prefix = ""] = entry.cidr.split("/");
142
+ const bits = entry.family === "ipv4" ? 32 : 128;
143
+ const value = entry.family === "ipv4" ? ipv4Value(address) : ipv6Value(address);
144
+ if (value === null)
145
+ throw new Error(`Invalid address-class range ${entry.cidr}`);
146
+ return { bits, network: BigInt(value), prefix: Number(prefix), entry };
147
+ });
148
+ function lookup(bits, value) {
149
+ for (const r of compiled) {
150
+ if (r.bits !== bits)
151
+ continue;
152
+ const shift = BigInt(bits - r.prefix);
153
+ if (value >> shift !== r.network >> shift)
154
+ continue;
155
+ const e = r.entry;
156
+ if ("class" in e)
157
+ return e.class;
158
+ return lookup(32, (value >> BigInt(128 - 32 - e.embeddedIpv4At)) & 0xffffffffn);
159
+ }
160
+ // unreachable: each family ends with a catch-all range
161
+ throw new Error("The address-class table is not total");
162
+ }
163
+ /**
164
+ * Classifies one IPv4 or IPv6 address literal by {@link ADDRESS_CLASS_RANGES}. IPv6 may carry a
165
+ * zone (`fe80::1%en0`) and a trailing dotted IPv4 address; an IPv6 form that embeds an IPv4 address
166
+ * (v4-mapped and the others in the table) classifies as that IPv4 address, except NAT64. Throws on a
167
+ * string that is not an IP address: brackets, ports, short, octal or hex IPv4 forms, and an IPv4
168
+ * address with a zone.
169
+ */
170
+ export function classifyAddress(ip) {
171
+ const v4 = ipv4Value(ip);
172
+ if (v4 !== null)
173
+ return lookup(32, BigInt(v4));
174
+ const zone = ip.indexOf("%");
175
+ const address = zone >= 0 ? ip.slice(0, zone) : ip;
176
+ if (zone >= 0 && !ZONE.test(ip.slice(zone + 1)))
177
+ return notAnAddress(ip);
178
+ const v6 = address.includes(":") ? ipv6Value(address) : null;
179
+ if (v6 === null)
180
+ return notAnAddress(ip);
181
+ return lookup(128, v6);
182
+ }
183
+ function notAnAddress(ip) {
184
+ throw new Error(`${JSON.stringify(ip.slice(0, 64))} is not an IP address`);
185
+ }
186
+ const formatAddress = (bits, v) => {
187
+ if (bits === 32)
188
+ return [24n, 16n, 8n, 0n].map((sh) => ((v >> sh) & 0xffn).toString()).join(".");
189
+ const groups = Array.from({ length: 8 }, (_, i) => Number((v >> BigInt(112 - 16 * i)) & 0xffffn));
190
+ // RFC 5952: the first longest run of two or more zero groups becomes "::"
191
+ let best = -1;
192
+ let bestLength = 1;
193
+ for (let i = 0; i < 8;) {
194
+ if (groups[i] !== 0) {
195
+ i++;
196
+ continue;
197
+ }
198
+ let j = i;
199
+ while (j < 8 && groups[j] === 0)
200
+ j++;
201
+ if (j - i > bestLength) {
202
+ best = i;
203
+ bestLength = j - i;
204
+ }
205
+ i = j;
206
+ }
207
+ const hex = (gs) => gs.map((g) => g.toString(16)).join(":");
208
+ if (best < 0)
209
+ return hex(groups);
210
+ return `${hex(groups.slice(0, best))}::${hex(groups.slice(best + bestLength))}`;
211
+ };
212
+ /** The class shared by every address of the block, or null when the table splits it. */
213
+ function blockClass(bits, network, prefix) {
214
+ let containing;
215
+ for (const r of compiled) {
216
+ if (r.bits !== bits)
217
+ continue;
218
+ if (r.prefix > prefix) {
219
+ const shift = BigInt(bits - prefix);
220
+ if (r.network >> shift === network >> shift)
221
+ return null; // a range inside the block
222
+ }
223
+ else if (containing === undefined) {
224
+ const shift = BigInt(bits - r.prefix);
225
+ if (r.network >> shift === network >> shift)
226
+ containing = r;
227
+ }
228
+ }
229
+ if (containing === undefined)
230
+ return null;
231
+ const e = containing.entry;
232
+ if ("class" in e)
233
+ return e.class;
234
+ const at = e.embeddedIpv4At;
235
+ const v4 = (network >> BigInt(128 - 32 - at)) & 0xffffffffn;
236
+ return blockClass(32, v4, Math.min(32, Math.max(0, prefix - at)));
237
+ }
238
+ /** The closed CIDRs of a block, merged where both halves are closed ("full" = all closed). */
239
+ function closedOf(bits, network, prefix) {
240
+ const cls = blockClass(bits, network, prefix);
241
+ if (cls !== null)
242
+ return OPEN_PUBLIC_DENIED_CLASSES.includes(cls) ? "full" : [];
243
+ const half = 1n << BigInt(bits - prefix - 1);
244
+ const halves = [network, network | half].map((n) => ({
245
+ n,
246
+ closed: closedOf(bits, n, prefix + 1),
247
+ }));
248
+ if (halves.every((h) => h.closed === "full"))
249
+ return "full";
250
+ return halves.flatMap((h) => h.closed === "full" ? [`${formatAddress(bits, h.n)}/${prefix + 1}`] : h.closed);
251
+ }
252
+ /**
253
+ * Every address closed in `open-public` mode as one CIDR list (IPv4, then IPv6), computed from
254
+ * {@link ADDRESS_CLASS_RANGES}: for a consumer that can only deny ranges (the macOS runtime's
255
+ * resolved-address deny list). Embedded forms are expanded (the v4-mapped, SIIT, v4-compatible and
256
+ * 6to4 sub-ranges of every closed IPv4 range), and adjacent closed blocks are merged. An address
257
+ * is in a listed CIDR exactly when {@link classifyAddress} gives it a closed class.
258
+ */
259
+ export const OPEN_PUBLIC_DENIED_CIDRS = Object.freeze([32, 128].flatMap((bits) => {
260
+ const closed = closedOf(bits, 0n, 0);
261
+ return closed === "full" ? [`${formatAddress(bits, 0n)}/0`] : closed;
262
+ }));
263
+ /**
264
+ * Encrypted DNS for a network whose resolver answers with fake IPs (maintainer decision
265
+ * 2026-11-19): a router running a fake-IP proxy (OpenClash and the like) intercepts every port-53
266
+ * query and answers each name with an address in {@link fakeIpCidr} (`198.18.0.0/15`, a reserved
267
+ * class), so in open mode every name would resolve to a closed address. When the system
268
+ * resolver's answer for a name contains such an address, a sandbox egress proxy re-resolves the
269
+ * name (A and AAAA) through DNS-over-HTTPS (RFC 8484, GET, wire format) at these IP-literal
270
+ * endpoints, in order (Cloudflare, then Google as the fallback), verifying TLS against the
271
+ * endpoint's IP SAN so no DNS is needed to reach them. {@link timeoutMs} is one overall deadline
272
+ * per name, covering A and AAAA and every endpoint; each endpoint gets its share of the time left.
273
+ * An answer is cached only when both queries succeeded, for its TTL, at most
274
+ * {@link cacheTtlCapSeconds}, and for at most {@link cacheMaxNames} names. The real address is
275
+ * classified like any resolved address and dialled as checked. When encrypted DNS fails the
276
+ * connection is refused, naming the fake-IP resolver; the fake address is never dialled. The same
277
+ * rule applies to an allowlisted name. Shared by the macOS worker and the Linux forwarder, so both
278
+ * keep identical endpoints and limits.
279
+ */
280
+ export const SANDBOX_FAKE_IP_DNS = Object.freeze({
281
+ fakeIpCidr: "198.18.0.0/15",
282
+ endpoints: Object.freeze([
283
+ "https://1.1.1.1/dns-query",
284
+ "https://1.0.0.1/dns-query",
285
+ "https://8.8.8.8/dns-query",
286
+ "https://8.8.4.4/dns-query",
287
+ ]),
288
+ timeoutMs: 5000,
289
+ cacheTtlCapSeconds: 300,
290
+ cacheMaxNames: 256,
291
+ });