@peakflo/agent-harness 0.2.20-rc.1 → 0.2.20-rc.2

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 (34) hide show
  1. package/README.md +78 -0
  2. package/dist/browser-broker/agent-actions.mjs +799 -0
  3. package/dist/browser-broker/browsers.mjs +1699 -0
  4. package/dist/browser-broker/credentials.mjs +211 -0
  5. package/dist/browser-broker/disk-guard.mjs +84 -0
  6. package/dist/browser-broker/egress.mjs +183 -0
  7. package/dist/browser-broker/input.mjs +270 -0
  8. package/dist/browser-broker/lease.mjs +547 -0
  9. package/dist/browser-broker/local-network.mjs +173 -0
  10. package/dist/browser-broker/local.mjs +158 -0
  11. package/dist/browser-broker/log.mjs +28 -0
  12. package/dist/browser-broker/network-policy.mjs +144 -0
  13. package/dist/browser-broker/os-users.mjs +493 -0
  14. package/dist/browser-broker/package.json +1 -0
  15. package/dist/browser-broker/protocol.mjs +321 -0
  16. package/dist/browser-broker/queue.mjs +37 -0
  17. package/dist/browser-broker/recorder-scripts.mjs +221 -0
  18. package/dist/browser-broker/recorder.mjs +438 -0
  19. package/dist/browser-broker/recording-store.mjs +493 -0
  20. package/dist/browser-broker/relay.mjs +399 -0
  21. package/dist/browser-broker/screencast.mjs +198 -0
  22. package/dist/browser-broker/state-store.mjs +112 -0
  23. package/dist/browser-broker/transfers.mjs +460 -0
  24. package/dist/control-plane.d.ts +6 -0
  25. package/dist/control-plane.js +10 -0
  26. package/dist/github-workspace.d.ts +2 -0
  27. package/dist/github-workspace.js +4 -0
  28. package/dist/harness.d.ts +1 -0
  29. package/dist/harness.js +24 -0
  30. package/dist/runtime/knowledge-tools.d.ts +1 -0
  31. package/dist/runtime/knowledge-tools.js +3 -0
  32. package/dist/runtime/local-browser.d.ts +33 -0
  33. package/dist/runtime/local-browser.js +135 -0
  34. package/package.json +5 -3
@@ -0,0 +1,493 @@
1
+ /**
2
+ * One Unix user per chat browser — the cross-chat boundary.
3
+ *
4
+ * The Pi harness runs every chat of the tenant as ONE user (pfharness, uid
5
+ * 1500), so a profile directory alone would not keep chat A's cookies from
6
+ * chat B's agent. Each chat browser therefore gets:
7
+ *
8
+ * user/group pfb-<first 8 hex of sha256(sessionId)>, ids in 20000-29999
9
+ * (created with uid = gid; lookups read the real primary gid)
10
+ * home /var/pf/browsers/<user>/ 0700 <user>
11
+ * └─ profile/ downloads/ uploads/ home/ tmp/ 0700 <user>
12
+ *
13
+ * /var/pf/browsers itself is root 0711, so nobody can list which chats have a
14
+ * browser. The session -> user mapping lives in root-only
15
+ * /var/lib/pf-browser-broker/users/.
16
+ *
17
+ * ROOT NEVER WRITES THROUGH A PATH THE BROWSER USER CONTROLS. Everything
18
+ * inside /var/pf/browsers/<user>/ is created and written AS that user (a
19
+ * setpriv child), so a compromised browser that plants a symlink there can
20
+ * only redirect writes to files it could already write. The top directory's
21
+ * own entry sits in the root-owned parent and cannot be swapped.
22
+ */
23
+ import { createHash } from 'node:crypto';
24
+ import { spawn, spawnSync } from 'node:child_process';
25
+ import fs from 'node:fs';
26
+ import path from 'node:path';
27
+ import { log } from './log.mjs';
28
+
29
+ export const UID_MIN = 20000;
30
+ export const UID_MAX = 29999;
31
+ export const BROWSERS_ROOT = '/var/pf/browsers';
32
+ export const STATE_ROOT = '/var/lib/pf-browser-broker/users';
33
+ export const SUBDIRS = ['profile', 'downloads', 'uploads', 'home', 'tmp'];
34
+
35
+ /** pfb-<8 hex>. `salt` > 0 only after a (vanishingly rare) prefix collision. */
36
+ export function userNameFor(sessionId, salt = 0) {
37
+ const input = salt ? `${sessionId}:${salt}` : sessionId;
38
+ return 'pfb-' + createHash('sha256').update(input).digest('hex').slice(0, 8);
39
+ }
40
+
41
+ /** Deterministic first-choice uid for a name, probed upward on collision. */
42
+ export function preferredUid(name) {
43
+ const hex = name.slice(4);
44
+ return UID_MIN + (parseInt(hex, 16) % (UID_MAX - UID_MIN + 1));
45
+ }
46
+
47
+ /**
48
+ * Parse /etc/passwd or /etc/group text into { byName, ids, primaryGid }.
49
+ * `primaryGid` (passwd only: column 4) maps a user name to its primary gid.
50
+ */
51
+ export function parseIdFile(text) {
52
+ const byName = new Map();
53
+ const ids = new Set();
54
+ const primaryGid = new Map();
55
+ for (const line of text.split('\n')) {
56
+ const cols = line.split(':');
57
+ if (cols.length < 3) continue;
58
+ const id = Number(cols[2]);
59
+ byName.set(cols[0], id);
60
+ ids.add(id);
61
+ if (cols.length >= 4 && cols[3] !== '')
62
+ primaryGid.set(cols[0], Number(cols[3]));
63
+ }
64
+ return { byName, ids, primaryGid };
65
+ }
66
+
67
+ /** First uid >= preferred (wrapping) unused as BOTH a uid and a gid. */
68
+ export function allocateId(preferred, usedUids, usedGids) {
69
+ const span = UID_MAX - UID_MIN + 1;
70
+ for (let i = 0; i < span; i++) {
71
+ const id = UID_MIN + ((preferred - UID_MIN + i) % span);
72
+ if (!usedUids.has(id) && !usedGids.has(id)) return id;
73
+ }
74
+ throw new Error('No free browser uid in 20000-29999');
75
+ }
76
+
77
+ /** True when both ids sit in the browser range (never root's or a system id). */
78
+ function inRange(uid, gid) {
79
+ return (
80
+ Number.isSafeInteger(uid) &&
81
+ Number.isSafeInteger(gid) &&
82
+ uid >= UID_MIN &&
83
+ uid <= UID_MAX &&
84
+ gid >= UID_MIN &&
85
+ gid <= UID_MAX
86
+ );
87
+ }
88
+
89
+ function run(cmd, args) {
90
+ const result = spawnSync(cmd, args, { encoding: 'utf8' });
91
+ if (result.status !== 0) {
92
+ throw new Error(
93
+ `${cmd} failed (${result.status}): ${(result.stderr || '').trim().slice(0, 200)}`
94
+ );
95
+ }
96
+ return result.stdout;
97
+ }
98
+
99
+ /** Default wall-clock limit for one as-user child. */
100
+ export const RUN_AS_USER_TIMEOUT_MS = 120_000;
101
+
102
+ /**
103
+ * Run `argv` as the browser user with no capabilities left (inheritable and
104
+ * bounding sets cleared, like chromium-as-user.sh). stdin may be a stream to
105
+ * pipe in; resolves with stdout as a Buffer (at most `maxBytes`).
106
+ *
107
+ * Bounded by `timeoutMs`: on expiry the child's whole process group is
108
+ * SIGKILLed and the promise rejects at once, so a hung child can never hold
109
+ * a caller's queue (OsUsers' serial lock, a transfer) forever.
110
+ */
111
+ export function runAsUser(user, argv, options = {}) {
112
+ return runChild(
113
+ '/usr/bin/setpriv',
114
+ [
115
+ `--reuid=${user.uid}`,
116
+ `--regid=${user.gid}`,
117
+ '--clear-groups',
118
+ '--no-new-privs',
119
+ '--inh-caps=-all',
120
+ '--bounding-set=-all',
121
+ '--',
122
+ ...argv
123
+ ],
124
+ { ...options, env: { PATH: '/usr/bin:/bin', HOME: user.home, LANG: 'C' } }
125
+ );
126
+ }
127
+
128
+ /** runAsUser's spawn/collect/timeout core (exported for tests). */
129
+ export function runChild(
130
+ command,
131
+ args,
132
+ {
133
+ stdin,
134
+ env,
135
+ maxBytes = 200 * 1024 * 1024,
136
+ timeoutMs = RUN_AS_USER_TIMEOUT_MS
137
+ } = {}
138
+ ) {
139
+ return new Promise((resolve, reject) => {
140
+ const child = spawn(command, args, {
141
+ stdio: ['pipe', 'pipe', 'pipe'],
142
+ env,
143
+ // Own process group, so a timeout also kills what a `sh -c` forked.
144
+ detached: true
145
+ });
146
+ const name = args.includes('--') ? args[args.indexOf('--') + 1] : command;
147
+ let settled = false;
148
+ const settle = (fn, value) => {
149
+ if (settled) return;
150
+ settled = true;
151
+ clearTimeout(timer);
152
+ fn(value);
153
+ };
154
+ const killAll = () => {
155
+ try {
156
+ process.kill(-child.pid, 'SIGKILL');
157
+ } catch {
158
+ try {
159
+ child.kill('SIGKILL');
160
+ } catch {
161
+ /* already gone */
162
+ }
163
+ }
164
+ };
165
+ const timer = setTimeout(() => {
166
+ killAll();
167
+ settle(
168
+ reject,
169
+ new Error(`as-user ${name} timed out after ${timeoutMs} ms`)
170
+ );
171
+ }, timeoutMs);
172
+ const chunks = [];
173
+ let size = 0;
174
+ let stderr = '';
175
+ child.stdout.on('data', (chunk) => {
176
+ size += chunk.length;
177
+ if (size > maxBytes) {
178
+ killAll();
179
+ return;
180
+ }
181
+ chunks.push(chunk);
182
+ });
183
+ child.stderr.on('data', (chunk) => {
184
+ if (stderr.length < 1000) stderr += chunk;
185
+ });
186
+ child.on('error', (error) => settle(reject, error));
187
+ child.on('close', (code) => {
188
+ if (code === 0 && size <= maxBytes)
189
+ settle(resolve, Buffer.concat(chunks));
190
+ else
191
+ settle(
192
+ reject,
193
+ new Error(
194
+ `as-user ${name} failed (${code}): ${stderr.trim().slice(0, 200)}`
195
+ )
196
+ );
197
+ });
198
+ child.stdin.on('error', () => undefined);
199
+ if (stdin) {
200
+ stdin.on('error', (error) => {
201
+ killAll();
202
+ settle(reject, error);
203
+ });
204
+ stdin.pipe(child.stdin);
205
+ } else {
206
+ child.stdin.end();
207
+ }
208
+ });
209
+ }
210
+
211
+ export class OsUsers {
212
+ #lock = Promise.resolve();
213
+
214
+ /**
215
+ * `passwdFile`, `groupFile`, `exec` and `wipeData` are injectable for tests.
216
+ */
217
+ constructor({
218
+ browsersRoot = BROWSERS_ROOT,
219
+ stateRoot = STATE_ROOT,
220
+ passwdFile = '/etc/passwd',
221
+ groupFile = '/etc/group',
222
+ exec = (cmd, args) => spawnSync(cmd, args, { encoding: 'utf8' }),
223
+ wipeData = wipeUserData
224
+ } = {}) {
225
+ this.browsersRoot = browsersRoot;
226
+ this.stateRoot = stateRoot;
227
+ this.passwdFile = passwdFile;
228
+ this.groupFile = groupFile;
229
+ this.exec = exec;
230
+ this.wipeData = wipeData;
231
+ }
232
+
233
+ #serial(job) {
234
+ const result = this.#lock.then(job);
235
+ this.#lock = result.catch(() => undefined);
236
+ return result;
237
+ }
238
+
239
+ #describe(name, uid, gid) {
240
+ const base = path.join(this.browsersRoot, name);
241
+ return {
242
+ name,
243
+ uid,
244
+ gid,
245
+ base,
246
+ profile: path.join(base, 'profile'),
247
+ downloads: path.join(base, 'downloads'),
248
+ uploads: path.join(base, 'uploads'),
249
+ home: path.join(base, 'home'),
250
+ tmp: path.join(base, 'tmp')
251
+ };
252
+ }
253
+
254
+ #owner(name) {
255
+ try {
256
+ return fs.readFileSync(path.join(this.stateRoot, name), 'utf8');
257
+ } catch {
258
+ return null;
259
+ }
260
+ }
261
+
262
+ /** Create (or reuse) the chat's user and its private directories. */
263
+ ensure(sessionId) {
264
+ return this.#serial(async () => {
265
+ fs.mkdirSync(this.stateRoot, { recursive: true, mode: 0o700 });
266
+ let name;
267
+ for (let salt = 0; salt < 16; salt++) {
268
+ const candidate = userNameFor(sessionId, salt);
269
+ const owner = this.#owner(candidate);
270
+ if (owner === null || owner === sessionId) {
271
+ name = candidate;
272
+ break;
273
+ }
274
+ }
275
+ if (!name) throw new Error('Could not choose a browser user name');
276
+
277
+ const passwd = parseIdFile(fs.readFileSync(this.passwdFile, 'utf8'));
278
+ const group = parseIdFile(fs.readFileSync(this.groupFile, 'utf8'));
279
+ let uid = passwd.byName.get(name);
280
+ // An existing user runs with ITS primary gid (passwd column 4), which
281
+ // need not equal the uid nor the gid of a same-named group.
282
+ let gid =
283
+ uid === undefined
284
+ ? group.byName.get(name)
285
+ : passwd.primaryGid.get(name);
286
+ if (uid === undefined) {
287
+ const id = gid ?? allocateId(preferredUid(name), passwd.ids, group.ids);
288
+ if (gid === undefined)
289
+ run('/usr/sbin/groupadd', ['--gid', String(id), name]);
290
+ gid = id;
291
+ run('/usr/sbin/useradd', [
292
+ '--uid',
293
+ String(id),
294
+ '--gid',
295
+ String(gid),
296
+ '--no-create-home',
297
+ '--home-dir',
298
+ path.join(this.browsersRoot, name, 'home'),
299
+ '--shell',
300
+ '/usr/sbin/nologin',
301
+ '--no-user-group',
302
+ name
303
+ ]);
304
+ uid = id;
305
+ log.info('browser user created', { user: name, uid });
306
+ }
307
+ if (!inRange(uid, gid)) {
308
+ throw new Error(
309
+ `Browser user ${name} has an id outside ${UID_MIN}-${UID_MAX}`
310
+ );
311
+ }
312
+ fs.writeFileSync(path.join(this.stateRoot, name), sessionId, {
313
+ mode: 0o600
314
+ });
315
+
316
+ const user = this.#describe(name, uid, gid);
317
+ // Top directory: its entry is in the root-owned 0711 parent, so the
318
+ // browser user cannot replace it with a symlink.
319
+ let stat = null;
320
+ try {
321
+ stat = fs.lstatSync(user.base);
322
+ } catch {
323
+ /* absent */
324
+ }
325
+ if (stat && !stat.isDirectory()) fs.rmSync(user.base, { force: true });
326
+ if (!stat || !stat.isDirectory())
327
+ fs.mkdirSync(user.base, { mode: 0o700 });
328
+ fs.lchownSync(user.base, uid, gid);
329
+ fs.chmodSync(user.base, 0o700);
330
+ // Everything inside: as the user.
331
+ await runAsUser(user, [
332
+ '/bin/sh',
333
+ '-c',
334
+ 'umask 077 && cd "$1" && shift && mkdir -p "$@" && chmod 0700 "$@"',
335
+ 'sh',
336
+ user.base,
337
+ ...SUBDIRS
338
+ ]);
339
+ return user;
340
+ });
341
+ }
342
+
343
+ /** The mapped user name of a session, or null. */
344
+ #mappedName(sessionId) {
345
+ for (let salt = 0; salt < 16; salt++) {
346
+ const name = userNameFor(sessionId, salt);
347
+ const owner = this.#owner(name);
348
+ if (owner === sessionId) return name;
349
+ if (owner === null) return null;
350
+ }
351
+ return null;
352
+ }
353
+
354
+ /** The user for a session if it exists, without creating anything. */
355
+ lookup(sessionId) {
356
+ const name = this.#mappedName(sessionId);
357
+ if (!name) return null;
358
+ const passwd = parseIdFile(fs.readFileSync(this.passwdFile, 'utf8'));
359
+ const uid = passwd.byName.get(name);
360
+ if (uid === undefined) return null;
361
+ // The primary gid from passwd: never assume gid == uid.
362
+ const gid = passwd.primaryGid.get(name);
363
+ if (!inRange(uid, gid)) {
364
+ throw new Error(
365
+ `Browser user ${name} has an id outside ${UID_MIN}-${UID_MAX}`
366
+ );
367
+ }
368
+ return this.#describe(name, uid, gid);
369
+ }
370
+
371
+ /**
372
+ * Delete the chat's browser data and its Unix user. Fails (throws, and the
373
+ * user is kept so a retry can finish) when a process of the user survives,
374
+ * the data cannot be removed, or userdel / groupdel fails. The session ->
375
+ * user mapping is removed only after the user AND its group are gone.
376
+ */
377
+ wipe(sessionId) {
378
+ return this.#serial(async () => {
379
+ const user = this.lookup(sessionId);
380
+ if (!user) {
381
+ // A previous wipe deleted the user but not the group: finish it.
382
+ const name = this.#mappedName(sessionId);
383
+ if (!name) return false;
384
+ this.#deleteIds(name, ['group']);
385
+ fs.rmSync(path.join(this.stateRoot, name), { force: true });
386
+ log.info('browser user wiped', { user: name });
387
+ return true;
388
+ }
389
+ await this.wipeData(user, { exec: this.exec });
390
+ this.#deleteIds(user.name, ['user', 'group']);
391
+ fs.rmSync(path.join(this.stateRoot, user.name), { force: true });
392
+ log.info('browser user wiped', { user: user.name });
393
+ return true;
394
+ });
395
+ }
396
+
397
+ /** userdel / groupdel `name`; throws unless each succeeded or was already gone. */
398
+ #deleteIds(name, kinds) {
399
+ // Exit 6 = "no such user/group" (already gone, e.g. userdel removed the
400
+ // user group itself): done. Any other failure keeps the mapping, so the
401
+ // name stays reserved for this chat and a retry can finish the job.
402
+ for (const what of kinds) {
403
+ const cmd = what === 'user' ? '/usr/sbin/userdel' : '/usr/sbin/groupdel';
404
+ const result = this.exec(cmd, [name]);
405
+ if (result.status !== 0 && result.status !== 6) {
406
+ log.error('browser user deletion failed', {
407
+ user: name,
408
+ what,
409
+ status: result.status
410
+ });
411
+ throw new Error(
412
+ `Deleting the browser ${what} ${name} failed (${result.status}): ${String(
413
+ result.stderr || ''
414
+ )
415
+ .trim()
416
+ .slice(0, 200)}`
417
+ );
418
+ }
419
+ }
420
+ }
421
+ }
422
+
423
+ export const WIPE_KILL_ATTEMPTS = 50;
424
+ export const WIPE_KILL_INTERVAL_MS = 100;
425
+
426
+ /**
427
+ * Kill every process of `user.uid`, then delete the chat's directory:
428
+ *
429
+ * 1. `pkill -KILL -u <uid>` until `pgrep -u <uid>` finds nothing (bounded:
430
+ * WIPE_KILL_ATTEMPTS x WIPE_KILL_INTERVAL_MS, then the wipe FAILS). Only
431
+ * the root broker can start a process as a browser uid, so once none is
432
+ * left nothing can recreate files behind our back.
433
+ * 2. The CONTENTS are deleted AS THE USER (setpriv child): `find -P -xdev
434
+ * -mindepth 1 -delete` never follows a symlink and never leaves the
435
+ * filesystem, and a symlink planted by a compromised browser can at most
436
+ * point the user at files the user could delete anyway. Root never
437
+ * deletes through a path the user controls.
438
+ * 3. Root removes the now-empty top directory with rmdir (its entry sits in
439
+ * the root-owned 0711 parent, so it cannot be swapped). lstat first: a
440
+ * non-directory is never followed.
441
+ *
442
+ * `ops` is injectable for tests.
443
+ */
444
+ export async function wipeUserData(user, ops = {}) {
445
+ const {
446
+ exec = (cmd, args) => spawnSync(cmd, args, { encoding: 'utf8' }),
447
+ asUser = runAsUser,
448
+ sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
449
+ attempts = WIPE_KILL_ATTEMPTS,
450
+ intervalMs = WIPE_KILL_INTERVAL_MS
451
+ } = ops;
452
+ const uid = String(user.uid);
453
+ let gone = false;
454
+ for (let attempt = 0; attempt < attempts; attempt++) {
455
+ exec('/usr/bin/pkill', ['-KILL', '-u', uid]);
456
+ const left = exec('/usr/bin/pgrep', ['-u', uid]);
457
+ // pgrep: 0 = found, 1 = none, anything else = error (treat as "unknown").
458
+ if (left.status === 1) {
459
+ gone = true;
460
+ break;
461
+ }
462
+ await sleep(intervalMs);
463
+ }
464
+ if (!gone) {
465
+ log.error('browser processes survived the wipe', { user: user.name });
466
+ throw new Error(
467
+ `Processes of ${user.name} are still running; the browser data was not deleted.`
468
+ );
469
+ }
470
+
471
+ let stat;
472
+ try {
473
+ stat = fs.lstatSync(user.base);
474
+ } catch (error) {
475
+ if (error.code === 'ENOENT') return;
476
+ throw error;
477
+ }
478
+ if (!stat.isDirectory()) {
479
+ // Not something the browser user can have made (the parent is root's):
480
+ // remove the entry itself, never what it points to.
481
+ fs.unlinkSync(user.base);
482
+ return;
483
+ }
484
+ await asUser(user, [
485
+ '/bin/sh',
486
+ '-c',
487
+ // u+rwx first so a directory the browser made unreadable can be emptied.
488
+ 'chmod -R u+rwX -- "$1" 2>/dev/null; find -P "$1" -xdev -mindepth 1 -delete',
489
+ 'sh',
490
+ user.base
491
+ ]);
492
+ fs.rmdirSync(user.base);
493
+ }
@@ -0,0 +1 @@
1
+ {"type":"module"}