@capybara-hq/device 0.1.0-rc.5 → 0.1.0-rc.7

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/dist/policy.js CHANGED
@@ -185,6 +185,27 @@ export function effectiveEgress(policy, limits, grants) {
185
185
  out.add(h);
186
186
  return [...out];
187
187
  }
188
+ /** Characters the sandbox runtime reads as a glob in a path entry. */
189
+ const GLOB_CHARS = /[*?[\]{}]/;
190
+ /**
191
+ * Write denies for git under each writable root (spec §5.2.1): `.git/hooks` at every tier (a hook
192
+ * is code that runs unsandboxed when the owner later runs git there), `.git/config` at `strict`.
193
+ * The runtime has the same mandatory denies, but anchored at this program's own working directory,
194
+ * which may not contain the roots. A root whose path reads as a glob gets none (it cannot be
195
+ * anchored literally); the runtime's own denies still apply when it lies under the working
196
+ * directory.
197
+ */
198
+ function gitWriteDenies(writable, gitConfig) {
199
+ const out = [];
200
+ for (const root of writable) {
201
+ if (GLOB_CHARS.test(root))
202
+ continue;
203
+ out.push(`${root}/.git/hooks/**`, `${root}/**/.git/hooks/**`);
204
+ if (!gitConfig)
205
+ out.push(`${root}/.git/config`, `${root}/**/.git/config`);
206
+ }
207
+ return out;
208
+ }
188
209
  /**
189
210
  * The sandbox-runtime configuration (spec §5.1, §5.2.3): writes only under the workspace and tmp
190
211
  * roots (the runtime's implicit write paths denied), skills read only, the secret paths (plus
@@ -197,6 +218,8 @@ export function effectiveEgress(policy, limits, grants) {
197
218
  * and use unix sockets under the tmp root, the workspace and the socket directory. On Linux unix
198
219
  * sockets stay blocked (srt can only allow all of them there, the host daemons' included) and the
199
220
  * sandbox's own network namespace gives it a loopback anyway. `allowAllUnixSockets` is never set.
221
+ * `dev` and `open` may write `.git/config` (so git can init, clone, set remotes and config);
222
+ * `.git/hooks` stays unwritable at every tier ({@link gitWriteDenies}).
200
223
  */
201
224
  export function srtConfig(policy, roots, egress, opts = {}) {
202
225
  const platform = opts.platform ?? process.platform;
@@ -204,16 +227,18 @@ export function srtConfig(policy, roots, egress, opts = {}) {
204
227
  const darwin = platform === "darwin";
205
228
  const dev = tier !== "strict";
206
229
  const socketDir = darwin && dev ? opts.socketDir : undefined;
230
+ const allowWrite = [
231
+ roots.workspace,
232
+ roots.tmp,
233
+ ...(socketDir !== undefined ? [socketDir] : []),
234
+ ...(dev && opts.cacheDir !== undefined ? [opts.cacheDir] : []),
235
+ ];
207
236
  return {
208
237
  filesystem: {
209
238
  denyRead: [...deniedSecretPaths(opts.home), ...(opts.denyRead ?? [])],
210
- allowWrite: [
211
- roots.workspace,
212
- roots.tmp,
213
- ...(socketDir !== undefined ? [socketDir] : []),
214
- ...(dev && opts.cacheDir !== undefined ? [opts.cacheDir] : []),
215
- ],
216
- denyWrite: [roots.skills, ...implicitWritePaths()],
239
+ allowWrite,
240
+ denyWrite: [roots.skills, ...implicitWritePaths(), ...gitWriteDenies(allowWrite, dev)],
241
+ allowGitConfig: dev,
217
242
  },
218
243
  network: {
219
244
  allowedDomains: [...egress],
@@ -57,7 +57,8 @@ export declare function summaryFacts(executor: Executor, ctx: OpContext): Summar
57
57
  /**
58
58
  * Runs one request and returns the answer plus its local audit line and, for an exec, its tier
59
59
  * and isolation (for the local command log). A vanished device
60
- * directory answers `fs_gone` for every operation except `stop` and `policy`. Never throws.
60
+ * directory answers `fs_gone` for every operation except `stop`, `policy` and `policyStatus`.
61
+ * Never throws.
61
62
  */
62
63
  export declare function serveOp(executor: Executor, req: KernelReq, signal: AbortSignal, ctx?: OpContext): Promise<{
63
64
  res: DeviceRes;
@@ -1,4 +1,4 @@
1
- import { isSandboxTier, tierAtMost, validateAllowHost, } from "@capybara-hq/plugin-sdk";
1
+ import { isPolicyOpId, isSandboxTier, tierAtMost, validateAllowHost, } from "@capybara-hq/plugin-sdk";
2
2
  import { execIsolation } from "./exec/switch.js";
3
3
  import { DeviceOpError } from "./exec/types.js";
4
4
  import { grantedHosts, tierFacts } from "./policy.js";
@@ -121,7 +121,7 @@ function opHosts(list, key, fromApproval) {
121
121
  * Every host is validated; the op is idempotent. Returns the result and the local audit line; a
122
122
  * refusal carries its audit line too ({@link PolicyRefused}).
123
123
  */
124
- function applyPolicyOp(store, args, facts) {
124
+ function applyPolicyOp(store, args, facts, written) {
125
125
  const source = (args.source ?? {});
126
126
  const fromApproval = source.approvalId !== undefined;
127
127
  const add = [...new Set(opHosts(args.add, "add", fromApproval))];
@@ -173,7 +173,7 @@ function applyPolicyOp(store, args, facts) {
173
173
  return p.tier === undefined || !tierAtMost(nextTier, p.tier);
174
174
  };
175
175
  let sandboxBackOn = false;
176
- const next = store.update((p) => {
176
+ const change = (p) => {
177
177
  // Judged against the file as it is now, inside the lock: a local `remoteGrants off` wins.
178
178
  if (p.remoteGrants !== "owner") {
179
179
  if (add.length > 0)
@@ -199,13 +199,87 @@ function applyPolicyOp(store, args, facts) {
199
199
  isolation,
200
200
  allowedDomains: [...kept, ...add.filter((h) => !present.has(h))],
201
201
  };
202
- });
202
+ };
203
+ const next = store.update(change, { written });
203
204
  const also = sandboxBackOn ? "; isolation sandbox (tier changed by the deployment)" : "";
204
205
  return {
205
206
  result: { policy: policySummary(next, facts) },
206
207
  detail: `policy ${what}${also} ${by}${approval}`,
207
208
  };
208
209
  }
210
+ /** The answer to a `policy` op whose outcome is logged already: the change is not made again. */
211
+ function answerFromLog(req, known, store, facts) {
212
+ if (known.outcome === "applied") {
213
+ return {
214
+ type: "res",
215
+ id: req.id,
216
+ ok: true,
217
+ result: { policy: policySummary(store.current(), facts) },
218
+ };
219
+ }
220
+ return {
221
+ type: "res",
222
+ id: req.id,
223
+ ok: false,
224
+ error: { kind: known.kind ?? "policy", message: known.message ?? "refused" },
225
+ };
226
+ }
227
+ /**
228
+ * A `policy` op by its op id: logged `started` before anything is checked or written, then
229
+ * `applied` (inside the policy lock, right after the write) or `refused` with the message. An op
230
+ * id applied or refused before is answered from the log without applying it again. Throws like
231
+ * {@link applyPolicyOp}.
232
+ */
233
+ function servePolicyOp(req, store, facts) {
234
+ const opId = req.args.opId;
235
+ if (!isPolicyOpId(opId)) {
236
+ throw new DeviceOpError("error", 'invalid request: field "opId" must be a valid op id');
237
+ }
238
+ const known = store.ops.claim(opId);
239
+ if (known !== undefined)
240
+ return { res: answerFromLog(req, known, store, facts) };
241
+ try {
242
+ const { result, detail } = applyPolicyOp(store, req.args, facts, () => {
243
+ try {
244
+ store.ops.recordHeld({ opId, outcome: "applied" });
245
+ }
246
+ catch {
247
+ // the change stands; the log keeps `started` and the deployment learns it from the hello
248
+ }
249
+ });
250
+ return { res: { type: "res", id: req.id, ok: true, result }, detail };
251
+ }
252
+ catch (e) {
253
+ // an op the log already says was applied stays applied (the log reports what the file holds)
254
+ if (store.ops.get(opId)?.outcome !== "applied") {
255
+ try {
256
+ store.ops.record({
257
+ opId,
258
+ outcome: "refused",
259
+ message: e instanceof Error ? e.message : String(e),
260
+ kind: e instanceof DeviceOpError ? e.kind : "error",
261
+ });
262
+ }
263
+ catch {
264
+ // nothing was applied; the log keeps `started`
265
+ }
266
+ }
267
+ throw e;
268
+ }
269
+ }
270
+ /** What the log says of an op id, with the summary now. Read-only. */
271
+ function policyStatus(store, args, facts) {
272
+ const opId = args?.opId;
273
+ if (!isPolicyOpId(opId)) {
274
+ throw new DeviceOpError("error", 'invalid request: field "opId" must be a valid op id');
275
+ }
276
+ const known = store.ops.get(opId);
277
+ return {
278
+ outcome: known?.outcome ?? "unknown",
279
+ policy: policySummary(store.current(), facts),
280
+ ...(known?.outcome === "refused" && known.message !== undefined && { message: known.message }),
281
+ };
282
+ }
209
283
  /** The audit line of an exec whose grants applied (OS mode only: Docker mode ignores grants). */
210
284
  function grantsDetail(executor, args, policy) {
211
285
  if (executor.mode !== "os" || args.grants === undefined || policy === undefined) {
@@ -220,7 +294,8 @@ function grantsDetail(executor, args, policy) {
220
294
  /**
221
295
  * Runs one request and returns the answer plus its local audit line and, for an exec, its tier
222
296
  * and isolation (for the local command log). A vanished device
223
- * directory answers `fs_gone` for every operation except `stop` and `policy`. Never throws.
297
+ * directory answers `fs_gone` for every operation except `stop`, `policy` and `policyStatus`.
298
+ * Never throws.
224
299
  */
225
300
  export async function serveOp(executor, req, signal, ctx = {}) {
226
301
  const ok = (result) => ({ type: "res", id: req.id, ok: true, result });
@@ -228,7 +303,7 @@ export async function serveOp(executor, req, signal, ctx = {}) {
228
303
  if (req.op === "stop")
229
304
  return { res: ok(null) };
230
305
  // The policy lives in the state directory, not the device directory.
231
- if (req.op === "policy") {
306
+ if (req.op === "policy" || req.op === "policyStatus") {
232
307
  if (ctx.policy === undefined) {
233
308
  return {
234
309
  res: {
@@ -239,8 +314,10 @@ export async function serveOp(executor, req, signal, ctx = {}) {
239
314
  },
240
315
  };
241
316
  }
242
- const { result, detail } = applyPolicyOp(ctx.policy, req.args, summaryFacts(executor, ctx));
243
- return { res: ok(result), detail };
317
+ const facts = summaryFacts(executor, ctx);
318
+ if (req.op === "policyStatus")
319
+ return { res: ok(policyStatus(ctx.policy, req.args, facts)) };
320
+ return servePolicyOp(req, ctx.policy, facts);
244
321
  }
245
322
  if ((await executor.ensureRoot()) === "gone") {
246
323
  return {
package/dist/state.d.ts CHANGED
@@ -43,6 +43,8 @@ type Env = Record<string, string | undefined>;
43
43
  export declare function stateDir(env?: Env, home?: string): string;
44
44
  export declare function credentialPath(dir: string): string;
45
45
  export declare function policyPath(dir: string): string;
46
+ /** The outcomes of the latest `policy` ops by op id (written under the policy lock). */
47
+ export declare function policyOpsPath(dir: string): string;
46
48
  /** The lock file that serializes read-modify-writes of policy.json across processes. */
47
49
  export declare function policyLockPath(dir: string): string;
48
50
  /** The default working directory of a device: `~/capybara-device/<deviceId>`. */
package/dist/state.js CHANGED
@@ -26,6 +26,10 @@ export function credentialPath(dir) {
26
26
  export function policyPath(dir) {
27
27
  return join(dir, "policy.json");
28
28
  }
29
+ /** The outcomes of the latest `policy` ops by op id (written under the policy lock). */
30
+ export function policyOpsPath(dir) {
31
+ return join(dir, "policy-ops.json");
32
+ }
29
33
  /** The lock file that serializes read-modify-writes of policy.json across processes. */
30
34
  export function policyLockPath(dir) {
31
35
  return join(dir, "policy.json.lock");
@@ -279,7 +283,12 @@ export function withPolicyLock(dir, fn, opts = {}) {
279
283
  catch {
280
284
  // Already gone.
281
285
  }
282
- closeSync(fd);
286
+ try {
287
+ closeSync(fd);
288
+ }
289
+ catch {
290
+ // `fn` ran (a policy write may have happened): a failed close must not turn it into an error
291
+ }
283
292
  }
284
293
  }
285
294
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@capybara-hq/device",
3
- "version": "0.1.0-rc.5",
3
+ "version": "0.1.0-rc.7",
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.17"
37
+ "@capybara-hq/plugin-sdk": "^0.1.0-rc.20"
38
38
  },
39
39
  "devDependencies": {
40
40
  "@types/ws": "^8.5.13"