@capybara-hq/device 0.1.0-rc.11 → 0.1.0-rc.13

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.
@@ -1,4 +1,4 @@
1
- import { isPolicyOpId, validateAllowHost, } from "@capybara-hq/plugin-sdk";
1
+ import { isPolicyOpId, MAX_DEVICE_LIST_ENTRIES, validateAllowHost, validateSandboxPathShape, } from "@capybara-hq/plugin-sdk";
2
2
  import { DeviceOpError } from "./exec/types.js";
3
3
  import { effectiveMode, grantedHosts } from "./policy.js";
4
4
  import { publicSuffixWildcard } from "./public-suffix.js";
@@ -192,6 +192,22 @@ function servePolicyOp(req, store, facts) {
192
192
  throw e;
193
193
  }
194
194
  }
195
+ /**
196
+ * Whether `op` is answered from the local policy file: it lives in the state directory, so these
197
+ * work while the device directory is gone, like the `policy` ops.
198
+ */
199
+ function isLocalPolicyOp(op) {
200
+ return op === "policy" || op === "policyStatus";
201
+ }
202
+ /** The answer to an operation this program does not serve (no policy store, or no reader). */
203
+ function unsupported(req) {
204
+ return {
205
+ type: "res",
206
+ id: req.id,
207
+ ok: false,
208
+ error: { kind: "error", message: "unsupported operation" },
209
+ };
210
+ }
195
211
  /** What the log says of an op id, with the summary now. Read-only. */
196
212
  function policyStatus(store, args, facts) {
197
213
  const opId = args?.opId;
@@ -205,6 +221,59 @@ function policyStatus(store, args, facts) {
205
221
  ...(known?.outcome === "refused" && known.message !== undefined && { message: known.message }),
206
222
  };
207
223
  }
224
+ /** A `list` / `scan` field that must be a clean absolute path, checked again here. */
225
+ function requestPath(v, key) {
226
+ const errors = typeof v === "string" ? validateSandboxPathShape(v) : ["path must be a string"];
227
+ if (errors.length > 0) {
228
+ throw new DeviceOpError("error", `invalid request: field "${key}": ${errors.join("; ")}`);
229
+ }
230
+ return v;
231
+ }
232
+ /** A `list` / `scan` request's ceiling (`limits.mode`), checked again here. */
233
+ function requestCeiling(args) {
234
+ const mode = args?.limits?.mode;
235
+ if (mode !== "auto" && mode !== "sandbox") {
236
+ throw new DeviceOpError("error", 'invalid request: field "limits.mode" must be "auto" or "sandbox"');
237
+ }
238
+ return { mode };
239
+ }
240
+ /**
241
+ * A `list` or `scan` request (a trust boundary: the device decides what a web session sees of its
242
+ * machine). Each is read in the mode it would run in now, `effectiveMode` of the owner's policy and
243
+ * the ceiling the request carries, never one an earlier command saw nor the file writes'
244
+ * window. Answered without the device directory: it reads the owner's machine, not that
245
+ * directory. Throws like the executor (a path its mode cannot reach is a `policy` refusal).
246
+ */
247
+ async function serveRead(executor, req, signal, store) {
248
+ const args = req.args;
249
+ const limits = requestCeiling(args);
250
+ if (req.op === "list") {
251
+ const path = requestPath(args?.path, "path");
252
+ const limit = args?.limit;
253
+ if (typeof limit !== "number" ||
254
+ !Number.isInteger(limit) ||
255
+ limit < 1 ||
256
+ limit > MAX_DEVICE_LIST_ENTRIES) {
257
+ throw new DeviceOpError("error", `invalid request: field "limit" must be an integer from 1 to ${MAX_DEVICE_LIST_ENTRIES}`);
258
+ }
259
+ const mode = effectiveMode(store.current(), limits);
260
+ signal.throwIfAborted();
261
+ const result = await executor.list(mode, path, limit, signal);
262
+ return { result, detail: `list ${clean(path, 300)} in ${mode} mode` };
263
+ }
264
+ const base = requestPath(args?.base, "base");
265
+ const mode = effectiveMode(store.current(), limits);
266
+ signal.throwIfAborted();
267
+ const result = await executor.scan(mode, base, signal);
268
+ return { result, detail: `scan ${clean(base, 300)} in ${mode} mode` };
269
+ }
270
+ /** Each file read uses this request's ceiling, intersected with the machine's current choice. */
271
+ function readMode(args, store) {
272
+ const mode = args?.limits?.mode;
273
+ if (mode !== "auto" && mode !== "sandbox")
274
+ throw new DeviceOpError("error", "invalid request: file reads require limits.mode auto or sandbox");
275
+ return store === undefined ? "sandbox" : effectiveMode(store.current(), { mode });
276
+ }
208
277
  /** The audit line of an exec whose grants applied (sandbox mode only: auto mode ignores grants). */
209
278
  function grantsDetail(executor, args, policy) {
210
279
  if (executor.mode !== "os" || args.grants === undefined || policy === undefined) {
@@ -221,7 +290,7 @@ function grantsDetail(executor, args, policy) {
221
290
  /**
222
291
  * Runs one request and returns the answer plus its local audit line and, for an exec, its mode
223
292
  * (for the local command log). A vanished device directory answers `fs_gone` for every operation
224
- * except `stop`, `policy` and `policyStatus`. Never throws.
293
+ * except `stop`, `policy`, `policyStatus`, `list` and `scan`. Never throws.
225
294
  */
226
295
  export async function serveOp(executor, req, signal, ctx = {}) {
227
296
  const ok = (result) => ({ type: "res", id: req.id, ok: true, result });
@@ -229,22 +298,31 @@ export async function serveOp(executor, req, signal, ctx = {}) {
229
298
  if (req.op === "stop")
230
299
  return { res: ok(null) };
231
300
  // The policy lives in the state directory, not the device directory.
232
- if (req.op === "policy" || req.op === "policyStatus") {
233
- if (ctx.policy === undefined) {
234
- return {
235
- res: {
236
- type: "res",
237
- id: req.id,
238
- ok: false,
239
- error: { kind: "error", message: "unsupported operation" },
240
- },
241
- };
242
- }
301
+ if (isLocalPolicyOp(req.op)) {
302
+ if (ctx.policy === undefined)
303
+ return { res: unsupported(req) };
243
304
  const facts = summaryFacts(executor, ctx);
244
305
  if (req.op === "policyStatus")
245
306
  return { res: ok(policyStatus(ctx.policy, req.args, facts)) };
246
307
  return servePolicyOp(req, ctx.policy, facts);
247
308
  }
309
+ // They read the owner's machine in the request's own mode, not the device directory, so they
310
+ // work while that directory is gone. Served only with a policy store (the mode needs the
311
+ // owner's choice) and by an executor that can read in a given mode.
312
+ if (req.op === "list" || req.op === "scan") {
313
+ const can = req.op === "list" ? executor.list : executor.scan;
314
+ if (ctx.policy === undefined || can === undefined)
315
+ return { res: unsupported(req) };
316
+ try {
317
+ const { result, detail } = await serveRead(executor, req, signal, ctx.policy);
318
+ return { res: ok(result), detail };
319
+ }
320
+ catch (e) {
321
+ const { res } = errorAnswer(req, e);
322
+ const message = res.ok ? "" : clean(res.error.message, 300);
323
+ return { res, detail: `${req.op} refused: ${message}` };
324
+ }
325
+ }
248
326
  if ((await executor.ensureRoot()) === "gone") {
249
327
  return {
250
328
  res: {
@@ -273,7 +351,7 @@ export async function serveOp(executor, req, signal, ctx = {}) {
273
351
  const run = {
274
352
  mode: effectiveMode(policy ?? DEFAULT_POLICY, args.limits),
275
353
  };
276
- // These limits are the latest decision file operations follow.
354
+ // These limits are the latest decision file writes follow.
277
355
  executor.noteLimits?.(args.limits);
278
356
  const detail = grantsDetail(executor, args, policy);
279
357
  try {
@@ -289,7 +367,8 @@ export async function serveOp(executor, req, signal, ctx = {}) {
289
367
  }
290
368
  case "readFile": {
291
369
  const a = req.args;
292
- const r = await executor.readFile(a.path, a.maxBytes);
370
+ const mode = readMode(req.args, ctx.policy);
371
+ const r = await executor.readFile(a.path, a.maxBytes, mode);
293
372
  return {
294
373
  res: ok(r === null
295
374
  ? null
@@ -301,8 +380,10 @@ export async function serveOp(executor, req, signal, ctx = {}) {
301
380
  await executor.writeFile(a.path, Buffer.from(a.dataB64, "base64"));
302
381
  return { res: ok(null) };
303
382
  }
304
- case "stat":
305
- return { res: ok(await executor.stat(req.args.path)) };
383
+ case "stat": {
384
+ const a = req.args;
385
+ return { res: ok(await executor.stat(a.path, readMode(req.args, ctx.policy))) };
386
+ }
306
387
  case "killTagged":
307
388
  await executor.killTagged(req.args.tags);
308
389
  return { res: ok(null) };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@capybara-hq/device",
3
- "version": "0.1.0-rc.11",
3
+ "version": "0.1.0-rc.13",
4
4
  "description": "capybara-device: connects a laptop or server to a Capybara deployment as a device",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -34,7 +34,7 @@
34
34
  "dependencies": {
35
35
  "@anthropic-ai/sandbox-runtime": "0.0.81",
36
36
  "ws": "^8.18.0",
37
- "@capybara-hq/plugin-sdk": "^0.1.0-rc.22"
37
+ "@capybara-hq/plugin-sdk": "^0.1.0-rc.25"
38
38
  },
39
39
  "devDependencies": {
40
40
  "@types/ws": "^8.5.13"