@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/exec/os.js CHANGED
@@ -1,14 +1,16 @@
1
1
  import { spawn } from "node:child_process";
2
2
  import { createHash, randomBytes } from "node:crypto";
3
- import { existsSync, realpathSync } from "node:fs";
3
+ import { existsSync, lstatSync, mkdirSync, realpathSync } from "node:fs";
4
4
  import { homedir, constants as osConstants } from "node:os";
5
- import { resolve } from "node:path";
5
+ import { join, resolve } from "node:path";
6
6
  import { SandboxManager, } from "@anthropic-ai/sandbox-runtime";
7
+ import { isBackgroundLaunch, } from "@capybara-hq/plugin-sdk";
7
8
  import { blockedHosts, denyReason, isPublicName, networkTrailer, } from "../network.js";
8
9
  import { ANY_HOST, deviceTier, effectiveEgress, grantedHosts, srtConfig, tierFacts, } from "../policy.js";
9
10
  import { detectLocalProxy, PROXY_GUARD_TTL_MS } from "../proxy-guard.js";
10
11
  import { FS_HELPER_SCRIPT } from "./fs-helper.js";
11
12
  import { EXEC_MARKER, killMarked } from "./procs.js";
13
+ import { Reaper } from "./reap.js";
12
14
  import { cacheEnv, cacheRoot, ENV_NAME_RE, HostFiles, isUnder, OutputCap, osRoots, PIPE_GRACE_MS, policyError, prepareSocketDir, RootGuard, shellQuote, socketDirPath, toolHomeEnv, } from "./shared.js";
13
15
  import { DeviceOpError } from "./types.js";
14
16
  export { osRoots, ROOT_MARKER, utf8Prefix } from "./shared.js";
@@ -69,10 +71,12 @@ export class OsExecutor {
69
71
  mode = "os";
70
72
  roots;
71
73
  dir;
72
- /** Marks every process of this device's commands: `<dirKey>.<tag>`. */
74
+ /** Marks every process of this device's commands: `<dirKey>.<tag>.<exec id>`. */
73
75
  dirKey;
74
76
  groups = new Set();
75
77
  pruneTimer;
78
+ /** Kills what a foreground exec left running once it ends. */
79
+ reaper;
76
80
  guard;
77
81
  files;
78
82
  /**
@@ -95,8 +99,16 @@ export class OsExecutor {
95
99
  * running. The ask callback allows any public name only while one runs.
96
100
  */
97
101
  openCommands = new Set();
102
+ /**
103
+ * Background tasks launched on macOS that still run, by the command id of their launch, with
104
+ * the task's process group id (its sid). A task keeps its launch's network permissions (the
105
+ * per-command list and {@link openCommands}) until its group is gone: it uses the launch's proxy
106
+ * credentials long after the launch returned. Checked on the prune tick.
107
+ */
108
+ backgroundNet = new Map();
98
109
  constructor(opts) {
99
110
  this.opts = opts;
111
+ this.reaper = new Reaper(opts.reaper);
100
112
  const dir = resolve(opts.dir);
101
113
  // The roots are reported as real paths, so what commands print matches what the kernel sends.
102
114
  this.dir = existsSync(dir) ? realpathSync(dir) : dir;
@@ -214,10 +226,31 @@ export class OsExecutor {
214
226
  .map((v) => v.line);
215
227
  return blockedHosts(lines, limits, policy);
216
228
  }
217
- /** The marker value of a tag's processes. */
229
+ /**
230
+ * `<dir>/git-template`, an empty directory commands can read but not write (it is outside the
231
+ * roots), made on demand; undefined when it cannot be made.
232
+ */
233
+ gitTemplate() {
234
+ const path = join(this.dir, "git-template");
235
+ try {
236
+ mkdirSync(path, { recursive: true, mode: 0o755 });
237
+ return lstatSync(path).isDirectory() ? path : undefined;
238
+ }
239
+ catch {
240
+ return undefined;
241
+ }
242
+ }
243
+ /**
244
+ * The marker value of a tag's processes. An exec's processes carry `<this>.<exec id>` (see
245
+ * {@link execMarker}); {@link killTagged} matches both.
246
+ */
218
247
  markerOf(tag) {
219
248
  return `${this.dirKey}.${tag}`;
220
249
  }
250
+ /** The marker value of one exec's processes: its tag's plus an id of its own (no dots in a tag). */
251
+ execMarker(tag) {
252
+ return `${this.markerOf(tag)}.${randomBytes(8).toString("hex")}`;
253
+ }
221
254
  /**
222
255
  * Wraps `script` (run by bash inside the sandbox, after the request's `env` and TMPDIR are
223
256
  * exported) and spawns it as the leader of a new process group.
@@ -231,6 +264,7 @@ export class OsExecutor {
231
264
  this.prepareSocketDir();
232
265
  // dev / open on macOS: the short socket directory, where unix sockets are allowed.
233
266
  const tmp = dev && this.socketDir !== undefined ? this.socketDir : this.roots.tmp;
267
+ const gitTemplate = dev ? this.gitTemplate() : undefined;
234
268
  const inner = {
235
269
  // The user's PATH applies inside the sandbox only (the wrapper runs with OUTER_ENV).
236
270
  PATH: process.env.PATH ?? "/usr/bin:/bin:/usr/sbin:/sbin",
@@ -244,12 +278,14 @@ export class OsExecutor {
244
278
  ...toolHomeEnv(this.opts.home ?? homedir()),
245
279
  // dev / open: package caches under <dir>/cache; the command's own values win.
246
280
  ...(dev && cacheEnv(this.cacheDir, { create: true })),
281
+ // dev / open may write .git/config but never .git/hooks: init and clone copy no sample hooks.
282
+ ...(dev && gitTemplate !== undefined && { GIT_TEMPLATE_DIR: gitTemplate }),
247
283
  ...o.env,
248
284
  // The runtime points TMPDIR at its own /tmp/claude (denied by the config): use ours.
249
285
  TMPDIR: tmp,
250
286
  // Chromium on macOS ignores TMPDIR and reads this instead (its singleton socket).
251
287
  ...(process.platform === "darwin" && { MAC_CHROMIUM_TMPDIR: tmp }),
252
- [EXEC_MARKER]: this.markerOf(o.tag),
288
+ [EXEC_MARKER]: o.marker,
253
289
  };
254
290
  for (const [k, v] of Object.entries(inner)) {
255
291
  if (!ENV_NAME_RE.test(k))
@@ -283,16 +319,41 @@ export class OsExecutor {
283
319
  }
284
320
  return { child, commandId };
285
321
  }
322
+ /** Drops a command's network permissions (its per-command list and any-host membership). */
323
+ releaseNet(commandId) {
324
+ this.backgroundNet.delete(commandId);
325
+ this.openCommands.delete(commandId);
326
+ SandboxManager.unregisterCommandNetworkLists(commandId);
327
+ }
328
+ /** Keeps a launched background task's network permissions while its group `sid` lives. */
329
+ keepBackgroundNet(commandId, sid) {
330
+ if (!killGroupId(sid, 0)) {
331
+ this.releaseNet(commandId);
332
+ return;
333
+ }
334
+ this.backgroundNet.set(commandId, sid);
335
+ this.startPruning();
336
+ }
337
+ /** Releases the network permissions of background tasks whose group is gone (all: `all`). */
338
+ pruneBackgroundNet(all = false) {
339
+ for (const [commandId, sid] of [...this.backgroundNet]) {
340
+ if (all || !killGroupId(sid, 0))
341
+ this.releaseNet(commandId);
342
+ }
343
+ }
344
+ startPruning() {
345
+ if (this.pruneTimer === undefined) {
346
+ this.pruneTimer = setInterval(() => this.prune(), PRUNE_INTERVAL_MS);
347
+ this.pruneTimer.unref();
348
+ }
349
+ }
286
350
  /** Tracks a spawned command's process group; returns the entry. */
287
351
  track(tag, child) {
288
352
  if (child.pid === undefined)
289
353
  return undefined;
290
354
  const g = { tag, pgid: child.pid, exited: false };
291
355
  this.groups.add(g);
292
- if (this.pruneTimer === undefined) {
293
- this.pruneTimer = setInterval(() => this.prune(), PRUNE_INTERVAL_MS);
294
- this.pruneTimer.unref();
295
- }
356
+ this.startPruning();
296
357
  return g;
297
358
  }
298
359
  /** Forgets finished groups with no members left (or whose id was taken by another process). */
@@ -305,7 +366,8 @@ export class OsExecutor {
305
366
  if (pidAlive(g.pgid) || !killGroupId(g.pgid, 0))
306
367
  this.groups.delete(g);
307
368
  }
308
- if (this.groups.size === 0 && this.pruneTimer !== undefined) {
369
+ this.pruneBackgroundNet();
370
+ if (this.groups.size === 0 && this.backgroundNet.size === 0 && this.pruneTimer !== undefined) {
309
371
  clearInterval(this.pruneTimer);
310
372
  this.pruneTimer = undefined;
311
373
  }
@@ -333,10 +395,13 @@ export class OsExecutor {
333
395
  allowedDomains: [...policy.allowedDomains, ...grantedHosts(policy, args.limits, args.grants)],
334
396
  };
335
397
  const egress = effectiveEgress(policy, args.limits, args.grants);
398
+ const marker = this.execMarker(args.tag);
399
+ // A background task launch detaches the task on purpose: what it leaves running stays.
400
+ const reap = !isBackgroundLaunch(args.command);
336
401
  const { child, commandId } = await this.spawnSandboxed(args.command, {
337
402
  cwd,
338
403
  ...(args.env !== undefined && { env: args.env }),
339
- tag: args.tag,
404
+ marker,
340
405
  egress,
341
406
  policy,
342
407
  tier: deviceTier(policy, args.limits),
@@ -370,7 +435,7 @@ export class OsExecutor {
370
435
  }, args.timeoutMs);
371
436
  const onAbort = () => kill();
372
437
  signal.addEventListener("abort", onAbort, { once: true });
373
- const cleanup = () => {
438
+ const cleanup = (keepFor) => {
374
439
  clearTimeout(timer);
375
440
  if (grace)
376
441
  clearTimeout(grace);
@@ -379,8 +444,10 @@ export class OsExecutor {
379
444
  group.exited = true;
380
445
  group.onKill = undefined;
381
446
  }
382
- this.openCommands.delete(commandId);
383
- SandboxManager.unregisterCommandNetworkLists(commandId);
447
+ if (keepFor !== undefined)
448
+ this.keepBackgroundNet(commandId, keepFor);
449
+ else
450
+ this.releaseNet(commandId);
384
451
  SandboxManager.cleanupAfterCommand();
385
452
  };
386
453
  const finish = () => {
@@ -396,7 +463,9 @@ export class OsExecutor {
396
463
  // The explanation is best effort: the command's result always comes back.
397
464
  }
398
465
  const trailer = networkTrailer(blocked);
399
- cleanup();
466
+ cleanup(reap || killed || timedOut || exit.code !== 0
467
+ ? undefined
468
+ : launchedGroup(cap.text("stdout")));
400
469
  child.stdout?.destroy();
401
470
  child.stderr?.destroy();
402
471
  let exitCode = exit.code;
@@ -433,6 +502,11 @@ export class OsExecutor {
433
502
  exit = { code, sig };
434
503
  if (group)
435
504
  group.exited = true;
505
+ // The call is over (exit, timeout or abort): nothing it started may outlive it, because no
506
+ // later command can stop it (the sandbox lets no command signal another's processes).
507
+ // Its group goes before the result; processes that left the group soon after.
508
+ if (group && reap)
509
+ void this.reaper.reap(group.pgid, marker);
436
510
  // A background child may hold the pipes open; do not wait for it past a short grace.
437
511
  grace = setTimeout(finish, PIPE_GRACE_MS);
438
512
  });
@@ -455,7 +529,7 @@ export class OsExecutor {
455
529
  .join(" ");
456
530
  const { child, commandId } = await this.spawnSandboxed(script, {
457
531
  cwd: this.roots.workspace,
458
- tag: "fs-helper",
532
+ marker: this.markerOf("fs-helper"),
459
533
  egress: [],
460
534
  policy: this.opts.policy(),
461
535
  tier: this.tier(),
@@ -529,12 +603,18 @@ export class OsExecutor {
529
603
  if (want.has(g.tag))
530
604
  this.killGroup(g);
531
605
  const values = new Set(tags.map((t) => this.markerOf(t)));
532
- await killMarked((v) => values.has(v));
606
+ // `<dirKey>.<tag>` or an exec's `<dirKey>.<tag>.<id>`: a tag has no dot, so `ab` never
607
+ // matches `ab-cd`'s processes.
608
+ await killMarked((v) => {
609
+ const dot = v.indexOf(".", this.dirKey.length + 1);
610
+ return values.has(dot < 0 ? v : v.slice(0, dot));
611
+ });
533
612
  }
534
613
  async killAll() {
535
614
  for (const g of [...this.groups])
536
615
  this.killGroup(g);
537
616
  await this.killLeftovers();
617
+ this.pruneBackgroundNet(true);
538
618
  }
539
619
  /** Kills every process carrying this device's marker (also a previous run's). */
540
620
  async killLeftovers() {
@@ -550,6 +630,17 @@ export class OsExecutor {
550
630
  await SandboxManager.reset();
551
631
  }
552
632
  }
633
+ /**
634
+ * The process group id a background task launch printed as its last line (the task's sid), on
635
+ * macOS only: there the sandbox shares the host's process ids, so the device can watch the group.
636
+ * Elsewhere (Linux: bwrap's own pid namespace) undefined, and the launch's permissions end with it.
637
+ */
638
+ export function launchedGroup(stdout, platform = process.platform) {
639
+ if (platform !== "darwin")
640
+ return undefined;
641
+ const last = stdout.trimEnd().split("\n").pop()?.trim() ?? "";
642
+ return /^[1-9][0-9]*$/.test(last) ? Number(last) : undefined;
643
+ }
553
644
  /**
554
645
  * The OS sandbox executor: checks the platform and dependencies, starts the sandbox's proxies
555
646
  * once for this process, and kills what a previous run of this device left running.
@@ -0,0 +1,41 @@
1
+ /** The most scans one batch of reaps makes while it still finds processes. */
2
+ export declare const REAP_ROUNDS = 3;
3
+ export interface ReaperDeps {
4
+ /** SIGKILLs a process group; false when it no longer exists. */
5
+ killGroup: (pgid: number) => boolean;
6
+ /** The pids of this user's processes whose marker value `match` accepts (see `procs.ts`). */
7
+ findMarked: (match: (value: string) => boolean) => Promise<number[]>;
8
+ /** SIGKILLs one process and the process group it leads, if any. */
9
+ killPid: (pid: number) => void;
10
+ }
11
+ /**
12
+ * Kills what a foreground exec left running once it ended (normal exit, timeout or abort). Inside
13
+ * the OS sandbox a command can neither list nor signal the processes another command started, so
14
+ * a `sleep 300 &` or `nohup server &` left behind could otherwise be stopped by nobody.
15
+ *
16
+ * The exec's process group goes at once (a `&` or `nohup` child stays in it). A process that left
17
+ * the group (`setsid`, a detached spawn) is found by the exec's own marker value, which every
18
+ * process it starts inherits; listing processes is slow on macOS (`ps -E`), so that part runs
19
+ * after the result and reaps that arrive meanwhile share one scan. On macOS `ps -E` hides the
20
+ * environment of Apple platform binaries, so it is best effort there (the group covers the rest).
21
+ * Background task launches are not reaped at all (`isBackgroundLaunch`): they detach on purpose.
22
+ */
23
+ export declare class Reaper {
24
+ private readonly deps;
25
+ /** Markers whose processes the next scan kills. */
26
+ private readonly pending;
27
+ /** The queued scan (not started yet), which every new reap joins. */
28
+ private next;
29
+ /** The scan in progress. */
30
+ private running;
31
+ constructor(deps?: Partial<ReaperDeps>);
32
+ /**
33
+ * SIGKILLs the process group `pgid` now and, soon after, every process carrying the marker
34
+ * value `marker` exactly (none when empty). Resolves once that scan is done; never rejects.
35
+ */
36
+ reap(pgid: number, marker: string): Promise<void>;
37
+ private schedule;
38
+ /** Waits for the scan in progress, then scans every marker pending by then. */
39
+ private runQueued;
40
+ private scan;
41
+ }
@@ -0,0 +1,89 @@
1
+ import { killGroupId } from "./groups.js";
2
+ import { findMarked } from "./procs.js";
3
+ /** The most scans one batch of reaps makes while it still finds processes. */
4
+ export const REAP_ROUNDS = 3;
5
+ function killPid(pid) {
6
+ // A live process's pid is a group id only when it leads that group: then the group goes too.
7
+ killGroupId(pid);
8
+ try {
9
+ process.kill(pid, "SIGKILL");
10
+ }
11
+ catch {
12
+ // Already gone.
13
+ }
14
+ }
15
+ const DEFAULT_DEPS = { killGroup: (pgid) => killGroupId(pgid), findMarked, killPid };
16
+ /**
17
+ * Kills what a foreground exec left running once it ended (normal exit, timeout or abort). Inside
18
+ * the OS sandbox a command can neither list nor signal the processes another command started, so
19
+ * a `sleep 300 &` or `nohup server &` left behind could otherwise be stopped by nobody.
20
+ *
21
+ * The exec's process group goes at once (a `&` or `nohup` child stays in it). A process that left
22
+ * the group (`setsid`, a detached spawn) is found by the exec's own marker value, which every
23
+ * process it starts inherits; listing processes is slow on macOS (`ps -E`), so that part runs
24
+ * after the result and reaps that arrive meanwhile share one scan. On macOS `ps -E` hides the
25
+ * environment of Apple platform binaries, so it is best effort there (the group covers the rest).
26
+ * Background task launches are not reaped at all (`isBackgroundLaunch`): they detach on purpose.
27
+ */
28
+ export class Reaper {
29
+ deps;
30
+ /** Markers whose processes the next scan kills. */
31
+ pending = new Set();
32
+ /** The queued scan (not started yet), which every new reap joins. */
33
+ next;
34
+ /** The scan in progress. */
35
+ running;
36
+ constructor(deps = {}) {
37
+ this.deps = { ...DEFAULT_DEPS, ...deps };
38
+ }
39
+ /**
40
+ * SIGKILLs the process group `pgid` now and, soon after, every process carrying the marker
41
+ * value `marker` exactly (none when empty). Resolves once that scan is done; never rejects.
42
+ */
43
+ reap(pgid, marker) {
44
+ this.deps.killGroup(pgid);
45
+ if (marker === "")
46
+ return Promise.resolve();
47
+ this.pending.add(marker);
48
+ return this.schedule();
49
+ }
50
+ schedule() {
51
+ if (this.next !== undefined)
52
+ return this.next;
53
+ const queued = this.runQueued();
54
+ this.next = queued;
55
+ return queued;
56
+ }
57
+ /** Waits for the scan in progress, then scans every marker pending by then. */
58
+ async runQueued() {
59
+ // Always yields first, so `schedule` has set `this.next` before it is cleared here.
60
+ await (this.running ?? Promise.resolve()).catch(() => { });
61
+ this.next = undefined;
62
+ const markers = new Set(this.pending);
63
+ this.pending.clear();
64
+ const scan = this.scan(markers);
65
+ this.running = scan;
66
+ try {
67
+ await scan;
68
+ }
69
+ finally {
70
+ if (this.running === scan)
71
+ this.running = undefined;
72
+ }
73
+ }
74
+ async scan(markers) {
75
+ for (let round = 0; round < REAP_ROUNDS; round++) {
76
+ let pids;
77
+ try {
78
+ pids = await this.deps.findMarked((v) => markers.has(v));
79
+ }
80
+ catch {
81
+ return;
82
+ }
83
+ if (pids.length === 0)
84
+ return;
85
+ for (const pid of pids)
86
+ this.deps.killPid(pid);
87
+ }
88
+ }
89
+ }
@@ -15,11 +15,14 @@ export function osRoots(dir) {
15
15
  export function cacheRoot(dir) {
16
16
  return join(dir, "cache");
17
17
  }
18
- /** Each cache variable of `dev` / `open` and its folder under the cache root. */
18
+ /**
19
+ * Each cache variable of `dev` / `open` and its folder under the cache root. No pnpm store entry:
20
+ * pnpm 10 takes it only from `npm_config_store_dir`, and npm prints a warning about that unknown
21
+ * key on every command; pnpm keeps its store at its default under HOME (the workspace).
22
+ */
19
23
  const CACHE_DIRS = [
20
24
  ["XDG_CACHE_HOME", "xdg"],
21
25
  ["npm_config_cache", "npm"],
22
- ["npm_config_store_dir", "pnpm-store"],
23
26
  ["PIP_CACHE_DIR", "pip"],
24
27
  ["UV_CACHE_DIR", "uv"],
25
28
  ["CARGO_HOME", "cargo"],
@@ -0,0 +1,47 @@
1
+ import { type DeviceErrorKind, type DevicePolicyOpOutcome, type DevicePolicyOpReport } from "@capybara-hq/plugin-sdk";
2
+ /** The most `policy` op outcomes the log keeps; the oldest is dropped first. */
3
+ export declare const MAX_LOGGED_POLICY_OPS = 100;
4
+ /** The longest refusal message the log keeps (characters); a longer one is cut. */
5
+ export declare const MAX_LOGGED_MESSAGE_LENGTH = 500;
6
+ /**
7
+ * One logged `policy` op: its id from the deployment, the outcome, and a refusal's message and
8
+ * error kind (a repeated op is answered with them).
9
+ */
10
+ export interface PolicyOpRecord {
11
+ opId: string;
12
+ outcome: DevicePolicyOpOutcome;
13
+ message?: string;
14
+ kind?: DeviceErrorKind;
15
+ time: string;
16
+ }
17
+ /**
18
+ * The outcomes of the latest `policy` ops, by the deployment's op id, in
19
+ * `<stateDir>/policy-ops.json` (oldest first, at most {@link MAX_LOGGED_POLICY_OPS}). An op is
20
+ * logged `started` before the policy is written, then `applied` or `refused`; one the program was
21
+ * stopped in the middle of stays `started`. The deployment reads it with `policyStatus` and in
22
+ * each hello (`recentOps`). Writes hold policy.json.lock, so they never interleave with a policy
23
+ * change.
24
+ */
25
+ export declare class PolicyOpLog {
26
+ private readonly dir;
27
+ private readonly file;
28
+ constructor(dir: string);
29
+ /** The logged ops, oldest first; a missing or unreadable file (or entry) reads as none. */
30
+ entries(): PolicyOpRecord[];
31
+ get(opId: string): PolicyOpRecord | undefined;
32
+ /** The outcomes a hello reports, oldest first. */
33
+ recent(): DevicePolicyOpReport[];
34
+ /** Logs an outcome under the policy lock. */
35
+ record(entry: Omit<PolicyOpRecord, "time">): void;
36
+ /**
37
+ * Logs an outcome; the caller holds policy.json.lock. A later outcome of the same op replaces
38
+ * its entry and moves it last.
39
+ */
40
+ recordHeld(entry: Omit<PolicyOpRecord, "time">): void;
41
+ /**
42
+ * Under the policy lock: the op's final outcome when it was applied or refused before (the
43
+ * caller answers from it), else logs it `started` and returns undefined (an op left `started`
44
+ * by an interrupted run is taken again: its content is idempotent).
45
+ */
46
+ claim(opId: string): PolicyOpRecord | undefined;
47
+ }
@@ -0,0 +1,90 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import { isPolicyOpId, } from "@capybara-hq/plugin-sdk";
3
+ import { policyOpsPath, withPolicyLock, writePrivate } from "./state.js";
4
+ /** The most `policy` op outcomes the log keeps; the oldest is dropped first. */
5
+ export const MAX_LOGGED_POLICY_OPS = 100;
6
+ /** The longest refusal message the log keeps (characters); a longer one is cut. */
7
+ export const MAX_LOGGED_MESSAGE_LENGTH = 500;
8
+ const KINDS = ["gone", "fs_gone", "policy", "error"];
9
+ const OUTCOMES = ["applied", "refused", "started"];
10
+ function isRecord(v) {
11
+ if (typeof v !== "object" || v === null || Array.isArray(v))
12
+ return false;
13
+ const o = v;
14
+ return (isPolicyOpId(o.opId) &&
15
+ OUTCOMES.includes(o.outcome) &&
16
+ (o.message === undefined || typeof o.message === "string") &&
17
+ (o.kind === undefined || KINDS.includes(o.kind)) &&
18
+ typeof o.time === "string");
19
+ }
20
+ /**
21
+ * The outcomes of the latest `policy` ops, by the deployment's op id, in
22
+ * `<stateDir>/policy-ops.json` (oldest first, at most {@link MAX_LOGGED_POLICY_OPS}). An op is
23
+ * logged `started` before the policy is written, then `applied` or `refused`; one the program was
24
+ * stopped in the middle of stays `started`. The deployment reads it with `policyStatus` and in
25
+ * each hello (`recentOps`). Writes hold policy.json.lock, so they never interleave with a policy
26
+ * change.
27
+ */
28
+ export class PolicyOpLog {
29
+ dir;
30
+ file;
31
+ constructor(dir) {
32
+ this.dir = dir;
33
+ this.file = policyOpsPath(dir);
34
+ }
35
+ /** The logged ops, oldest first; a missing or unreadable file (or entry) reads as none. */
36
+ entries() {
37
+ if (!existsSync(this.file))
38
+ return [];
39
+ let raw;
40
+ try {
41
+ raw = JSON.parse(readFileSync(this.file, "utf8"));
42
+ }
43
+ catch {
44
+ // a broken log is replaced at the next write: the deployment then learns less, never more
45
+ return [];
46
+ }
47
+ return Array.isArray(raw) ? raw.filter(isRecord).slice(-MAX_LOGGED_POLICY_OPS) : [];
48
+ }
49
+ get(opId) {
50
+ return this.entries().find((e) => e.opId === opId);
51
+ }
52
+ /** The outcomes a hello reports, oldest first. */
53
+ recent() {
54
+ return this.entries().map((e) => ({ opId: e.opId, outcome: e.outcome }));
55
+ }
56
+ /** Logs an outcome under the policy lock. */
57
+ record(entry) {
58
+ withPolicyLock(this.dir, () => this.recordHeld(entry));
59
+ }
60
+ /**
61
+ * Logs an outcome; the caller holds policy.json.lock. A later outcome of the same op replaces
62
+ * its entry and moves it last.
63
+ */
64
+ recordHeld(entry) {
65
+ const next = {
66
+ ...entry,
67
+ ...(entry.message !== undefined && {
68
+ message: entry.message.slice(0, MAX_LOGGED_MESSAGE_LENGTH),
69
+ }),
70
+ time: new Date().toISOString(),
71
+ };
72
+ const kept = this.entries().filter((e) => e.opId !== entry.opId);
73
+ kept.push(next);
74
+ writePrivate(this.file, `${JSON.stringify(kept.slice(-MAX_LOGGED_POLICY_OPS), null, 2)}\n`);
75
+ }
76
+ /**
77
+ * Under the policy lock: the op's final outcome when it was applied or refused before (the
78
+ * caller answers from it), else logs it `started` and returns undefined (an op left `started`
79
+ * by an interrupted run is taken again: its content is idempotent).
80
+ */
81
+ claim(opId) {
82
+ return withPolicyLock(this.dir, () => {
83
+ const known = this.get(opId);
84
+ if (known !== undefined && known.outcome !== "started")
85
+ return known;
86
+ this.recordHeld({ opId, outcome: "started" });
87
+ return undefined;
88
+ });
89
+ }
90
+ }
@@ -1,3 +1,4 @@
1
+ import { PolicyOpLog } from "./policy-ops.js";
1
2
  import { type Policy } from "./state.js";
2
3
  /**
3
4
  * The device's local policy as the running program sees it. Commands read {@link current} at
@@ -19,6 +20,8 @@ export declare class PolicyStore {
19
20
  * the key is dropped at the next write).
20
21
  */
21
22
  readonly legacyNetworkOpen: boolean;
23
+ /** The outcomes of the `policy` ops this machine served, by op id (next to policy.json). */
24
+ readonly ops: PolicyOpLog;
22
25
  constructor(dir: string, opts?: {
23
26
  err?: (line: string) => void;
24
27
  initial?: Policy;
@@ -32,7 +35,10 @@ export declare class PolicyStore {
32
35
  /**
33
36
  * Read-modify-write under policy.json.lock: reads the file (throws on an invalid one rather
34
37
  * than overwrite it), writes the change atomically keeping unknown keys, and swaps the
35
- * in-memory policy. Returns the new policy.
38
+ * in-memory policy. `written` runs after that, still holding the lock (the `policy` op logs its
39
+ * outcome there, next to the change). Returns the new policy.
36
40
  */
37
- update(change: (p: Policy) => Policy): Policy;
41
+ update(change: (p: Policy) => Policy, opts?: {
42
+ written?: (p: Policy) => void;
43
+ }): Policy;
38
44
  }
@@ -1,4 +1,5 @@
1
1
  import { statSync } from "node:fs";
2
+ import { PolicyOpLog } from "./policy-ops.js";
2
3
  import { policyPath, readPolicyFile, withPolicyLock, writePolicy } from "./state.js";
3
4
  /** What identifies one version of policy.json: absent, or its inode, size and mtime. */
4
5
  function versionOf(file) {
@@ -31,10 +32,13 @@ export class PolicyStore {
31
32
  * the key is dropped at the next write).
32
33
  */
33
34
  legacyNetworkOpen;
35
+ /** The outcomes of the `policy` ops this machine served, by op id (next to policy.json). */
36
+ ops;
34
37
  constructor(dir, opts = {}) {
35
38
  this.dir = dir;
36
39
  this.file = policyPath(dir);
37
40
  this.err = opts.err ?? (() => { });
41
+ this.ops = new PolicyOpLog(dir);
38
42
  this.version = versionOf(this.file);
39
43
  // Without an initial policy, an unreadable file throws here: the program does not start.
40
44
  if (opts.initial !== undefined) {
@@ -77,15 +81,17 @@ export class PolicyStore {
77
81
  /**
78
82
  * Read-modify-write under policy.json.lock: reads the file (throws on an invalid one rather
79
83
  * than overwrite it), writes the change atomically keeping unknown keys, and swaps the
80
- * in-memory policy. Returns the new policy.
84
+ * in-memory policy. `written` runs after that, still holding the lock (the `policy` op logs its
85
+ * outcome there, next to the change). Returns the new policy.
81
86
  */
82
- update(change) {
87
+ update(change, opts = {}) {
83
88
  return withPolicyLock(this.dir, () => {
84
89
  const { policy, extra } = readPolicyFile(this.dir);
85
90
  const next = change(policy);
86
91
  writePolicy(this.dir, next, extra);
87
92
  this.policy = next;
88
93
  this.version = versionOf(this.file);
94
+ opts.written?.(next);
89
95
  return next;
90
96
  });
91
97
  }
package/dist/policy.d.ts CHANGED
@@ -90,6 +90,8 @@ export interface SrtConfig {
90
90
  denyRead: string[];
91
91
  allowWrite: string[];
92
92
  denyWrite: string[];
93
+ /** Whether commands may write `.git/config` (`dev` / `open`); `.git/hooks` never. */
94
+ allowGitConfig: boolean;
93
95
  };
94
96
  network: {
95
97
  allowedDomains: string[];
@@ -128,6 +130,8 @@ export interface SrtConfigOptions {
128
130
  * and use unix sockets under the tmp root, the workspace and the socket directory. On Linux unix
129
131
  * sockets stay blocked (srt can only allow all of them there, the host daemons' included) and the
130
132
  * sandbox's own network namespace gives it a loopback anyway. `allowAllUnixSockets` is never set.
133
+ * `dev` and `open` may write `.git/config` (so git can init, clone, set remotes and config);
134
+ * `.git/hooks` stays unwritable at every tier ({@link gitWriteDenies}).
131
135
  */
132
136
  export declare function srtConfig(policy: Policy, roots: SandboxRoots, egress: string[], opts?: SrtConfigOptions): SrtConfig;
133
137
  export {};