@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/README.md +34 -10
- package/dist/args.d.ts +5 -1
- package/dist/args.js +23 -2
- package/dist/cli.js +9 -2
- package/dist/client.js +6 -2
- package/dist/commands/drain.d.ts +13 -0
- package/dist/commands/drain.js +28 -0
- package/dist/commands/service.d.ts +17 -3
- package/dist/commands/service.js +74 -9
- package/dist/exec/os.d.ts +38 -3
- package/dist/exec/os.js +108 -17
- package/dist/exec/reap.d.ts +41 -0
- package/dist/exec/reap.js +89 -0
- package/dist/exec/shared.js +5 -2
- package/dist/policy-ops.d.ts +47 -0
- package/dist/policy-ops.js +90 -0
- package/dist/policy-store.d.ts +8 -2
- package/dist/policy-store.js +8 -2
- package/dist/policy.d.ts +4 -0
- package/dist/policy.js +32 -7
- package/dist/server-ops.d.ts +2 -1
- package/dist/server-ops.js +85 -8
- package/dist/state.d.ts +2 -0
- package/dist/state.js +10 -1
- package/package.json +2 -2
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
|
-
|
|
212
|
-
|
|
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],
|
package/dist/server-ops.d.ts
CHANGED
|
@@ -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 `
|
|
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;
|
package/dist/server-ops.js
CHANGED
|
@@ -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
|
|
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 `
|
|
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
|
|
243
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
37
|
+
"@capybara-hq/plugin-sdk": "^0.1.0-rc.20"
|
|
38
38
|
},
|
|
39
39
|
"devDependencies": {
|
|
40
40
|
"@types/ws": "^8.5.13"
|