@masstensor/diagnose 0.1.0 → 0.3.0

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/engine.js CHANGED
@@ -1,6 +1,9 @@
1
1
  import { execute, prepareWrite } from './executor.js';
2
- import { CHUNK_SIZE } from './schema.js';
3
- import { digest, redact } from './util.js';
2
+ import { CHUNK_SIZE, MAX_OUTPUT } from './schema.js';
3
+ import { digest, redact, safeText } from './util.js';
4
+ import { SessionResources, resourceOperation } from './resources.js';
5
+ import { randomUUID } from 'node:crypto';
6
+ import { dirname, join, basename } from 'node:path';
4
7
  function aborted(promise, signal) {
5
8
  return new Promise((resolve, reject) => {
6
9
  const cancel = () => reject(new Error('Task cancelled'));
@@ -21,19 +24,54 @@ export class ProbeEngine {
21
24
  seen = new Set();
22
25
  idle;
23
26
  lifetime;
24
- constructor(peer, approve, audit, notice = () => { }) {
27
+ mode = 'ask';
28
+ owner = randomUUID();
29
+ resources;
30
+ approvalQueue = Promise.resolve();
31
+ get permissionMode() { return this.mode; }
32
+ // Local API only. No wire message or task argument can change permission mode.
33
+ setPermissionMode(mode) {
34
+ if (!['ask', 'auto'].includes(mode))
35
+ throw new Error('Invalid permission mode');
36
+ if (mode === this.mode)
37
+ return;
38
+ this.audit.record('permissions.changed', { from: this.mode, to: mode, automaticExecution: mode === 'auto', automaticTransfer: mode === 'auto' });
39
+ this.mode = mode;
40
+ if (mode === 'ask')
41
+ this.cancelAll();
42
+ if (mode === 'ask')
43
+ void this.resources.revoke().catch(() => this.peer.close('Resource cleanup failed'));
44
+ this.notice(`Permission mode: ${mode}${mode === 'auto' ? ' (automatic execution AND transmission)' : ' (active work cancelled; approval required)'}`);
45
+ }
46
+ cancelAll() {
47
+ for (const [id, controller] of this.jobs) {
48
+ this.audit.record('task.cancel-requested', { id, source: 'local' });
49
+ controller.abort();
50
+ }
51
+ void this.resources.revoke(this.owner).catch(() => this.peer.close('Resource cleanup failed'));
52
+ }
53
+ constructor(peer, approve, audit, notice = () => { }, options = {}) {
25
54
  this.peer = peer;
26
55
  this.approve = approve;
27
56
  this.audit = audit;
28
57
  this.notice = notice;
29
- this.idle = setTimeout(() => peer.close('Idle timeout'), 600000);
30
- this.lifetime = setTimeout(() => peer.close('Session lifetime exceeded'), 3600000);
58
+ this.resources = options.resources ?? new SessionResources(join(dirname(audit.path), basename(audit.path) + '.resources'), audit);
59
+ this.resources.setAudit(audit);
60
+ if (options.idleMs !== 0)
61
+ this.idle = setTimeout(() => peer.close('Idle timeout'), options.idleMs ?? 600000);
62
+ if (options.lifetimeMs !== 0)
63
+ this.lifetime = setTimeout(() => peer.close('Session lifetime exceeded'), options.lifetimeMs ?? 3600000);
31
64
  peer.on('message', (message) => {
32
- this.idle.refresh();
65
+ this.idle?.refresh();
66
+ if (message.type === 'resource.request') {
67
+ void this.resources.control(this.owner, message.request).then(value => this.peer.send({ type: 'resource.result', requestId: message.requestId, value }), error => this.peer.send({ type: 'resource.result', requestId: message.requestId, error: redact(error.message).slice(0, 2000) })).catch(() => { });
68
+ return;
69
+ }
33
70
  if (message.type === 'task.cancel') {
34
71
  try {
35
- audit.record('task.cancel-requested', { id: message.id });
72
+ audit.record('task.cancel-requested', { id: message.id, source: 'operator' });
36
73
  this.jobs.get(message.id)?.abort();
74
+ void this.resources.control(this.owner, { id: message.id, action: 'close', cursor: 0, limit: 65536, eof: false }).catch(() => { });
37
75
  }
38
76
  catch {
39
77
  peer.close('Audit unavailable');
@@ -49,8 +87,8 @@ export class ProbeEngine {
49
87
  void this.reply(task.id, { status: 'duplicate' });
50
88
  return;
51
89
  }
52
- if (this.jobs.size || this.seen.size >= 1000) {
53
- void this.reply(task.id, { status: 'error', error: 'Probe busy or session task limit reached' });
90
+ if (this.jobs.size >= 4 || this.seen.size >= 1000) {
91
+ void this.reply(task.id, { status: 'error', error: 'Four concurrent task slots or session task limit reached; wait or close unused work' });
54
92
  return;
55
93
  }
56
94
  const controller = new AbortController();
@@ -59,25 +97,122 @@ export class ProbeEngine {
59
97
  void this.run(task, controller);
60
98
  });
61
99
  peer.on('closed', () => { clearTimeout(this.idle); clearTimeout(this.lifetime); for (const controller of this.jobs.values())
62
- controller.abort(); try {
100
+ controller.abort(); void this.resources.disconnect(this.owner).catch(() => { }); try {
63
101
  audit.record('session.closed', {});
64
102
  }
65
- catch { /* Cannot continue a closed session. */ } });
103
+ catch { /* Session is already closed. */ } });
66
104
  }
67
105
  async reply(id, result) { await this.peer.send({ type: 'task.result', id, result }).catch(() => { }); }
68
106
  async finish(id, result) { this.jobs.delete(id); await this.reply(id, result); }
69
- async permission(request) { return aborted(this.approve(request), request.signal); }
107
+ permission(request) {
108
+ const result = this.approvalQueue.then(() => this.decidePermission(request));
109
+ this.approvalQueue = result.then(() => { }, () => { });
110
+ return result;
111
+ }
112
+ async decidePermission(request) {
113
+ request.signal.throwIfAborted();
114
+ if (this.mode === 'auto') {
115
+ this.audit.record('task.auto-approved', { id: request.task.id, stage: request.stage, digest: request.digest, ...(request.bytes === undefined ? {} : { bytes: request.bytes }) });
116
+ this.notice(`[AUTO ${request.stage}] ${request.task.operation} ${request.task.id}\n${safeText(request.preview.slice(0, 8192))}${request.preview.length > 8192 ? '\n[Terminal preview truncated; task digest and byte counts are audited.]' : ''}`);
117
+ return true;
118
+ }
119
+ return aborted(this.approve(request), request.signal);
120
+ }
121
+ recordRequest(task, parentId) {
122
+ const target = 'path' in task.arguments ? task.arguments.path : 'executable' in task.arguments ? task.arguments.executable : 'interpreter' in task.arguments ? task.arguments.interpreter : undefined;
123
+ const scope = task.operation === 'file.read' ? { offset: task.arguments.offset, length: task.arguments.length }
124
+ : task.operation === 'serial.capture' || task.operation === 'serial.exchange' ? { baudRate: task.arguments.baudRate, durationMs: task.arguments.durationMs }
125
+ : task.operation === 'process.run' || task.operation === 'process.script' ? { cwd: task.arguments.cwd ?? process.cwd(), argumentCount: task.arguments.args.length, timeoutMs: task.arguments.timeoutMs, ...(task.operation === 'process.script' ? { scriptBytes: Buffer.byteLength(task.arguments.script) } : {}) } : {};
126
+ this.audit.record('task.requested', { id: task.id, operation: task.operation, digest: digest(task), ...(parentId ? { parentId } : {}), ...(target ? { target } : {}), ...scope });
127
+ }
128
+ async runAtomic(task, signal, write, parentId) {
129
+ signal.throwIfAborted();
130
+ this.audit.record('task.executing', { id: task.id, ...(parentId ? { parentId } : {}) });
131
+ this.notice(`Executing ${task.operation} ${task.id}`);
132
+ const execution = resourceOperation(task.operation) ? { result: { status: 'ok', data: await this.resources.open(task, this.owner, signal) }, outputs: [] } : await execute(task, signal, write);
133
+ if (execution.outputs.some(item => item.truncated))
134
+ execution.result.truncated = true;
135
+ if (task.operation === 'file.write' && execution.result.status === 'ok')
136
+ this.audit.record('task.file-changed', { id: task.id, ...(parentId ? { parentId } : {}), ...execution.result.data });
137
+ if (['file.mkdir', 'file.remove', 'file.rename', 'file.chmod'].includes(task.operation) && execution.result.status === 'ok')
138
+ this.audit.record('task.filesystem-changed', { id: task.id, operation: task.operation, ...(parentId ? { parentId } : {}), ...task.arguments });
139
+ this.audit.record('task.collected', { id: task.id, ...(parentId ? { parentId } : {}), bytes: execution.outputs.reduce((n, item) => n + item.bytes.length, 0), status: execution.result.status, streams: execution.outputs.map(item => ({ stream: item.stream, bytes: item.bytes.length, encoding: item.encoding })) });
140
+ return execution;
141
+ }
142
+ async runBatch(task, parentSignal, writes, hash) {
143
+ const controller = new AbortController();
144
+ const abort = () => controller.abort();
145
+ parentSignal.addEventListener('abort', abort, { once: true });
146
+ if (parentSignal.aborted)
147
+ abort();
148
+ let timedOut = false, total = 0, truncated = false, outputLimit = false;
149
+ const timer = setTimeout(() => { timedOut = true; controller.abort(); }, task.arguments.timeoutMs);
150
+ const outputs = [], results = [];
151
+ try {
152
+ for (const [index, step] of task.arguments.steps.entries()) {
153
+ if (controller.signal.aborted)
154
+ break;
155
+ if (total >= MAX_OUTPUT) {
156
+ truncated = true;
157
+ break;
158
+ }
159
+ if (digest(task) !== hash)
160
+ throw new Error('Batch parameters changed after approval');
161
+ let execution;
162
+ try {
163
+ execution = await this.runAtomic(step, controller.signal, writes.get(step.id), task.id);
164
+ }
165
+ catch (error) {
166
+ execution = { result: { status: controller.signal.aborted ? 'cancelled' : 'error', error: redact(error.message).slice(0, 2000) }, outputs: [] };
167
+ this.audit.record('task.failed', { id: step.id, parentId: task.id, status: execution.result.status });
168
+ }
169
+ if (timedOut)
170
+ execution.result = { ...execution.result, status: 'error', error: 'Batch timeout' };
171
+ const streams = [];
172
+ for (const item of execution.outputs) {
173
+ const keep = Math.max(0, Math.min(item.bytes.length, MAX_OUTPUT - total));
174
+ if (keep < item.bytes.length) {
175
+ truncated = true;
176
+ outputLimit = true;
177
+ execution.result.truncated = true;
178
+ }
179
+ const stream = `${index}.${item.stream}`;
180
+ streams.push(stream);
181
+ if (keep)
182
+ outputs.push({ ...item, stream, bytes: item.bytes.subarray(0, keep) });
183
+ total += keep;
184
+ }
185
+ truncated ||= execution.result.truncated === true;
186
+ results.push({ id: step.id, operation: step.operation, result: execution.result, streams });
187
+ this.audit.record('task.step-completed', { id: step.id, parentId: task.id, index, status: execution.result.status });
188
+ if (timedOut || outputLimit || (task.arguments.stopOnError && execution.result.status !== 'ok'))
189
+ break;
190
+ }
191
+ parentSignal.throwIfAborted();
192
+ if (timedOut)
193
+ this.audit.record('task.batch-timeout', { id: task.id, completedSteps: results.length });
194
+ const stoppedEarly = results.length < task.arguments.steps.length;
195
+ return { result: { status: !timedOut && !stoppedEarly && !outputLimit && results.every(item => item.result.status === 'ok') ? 'ok' : 'error', truncated, ...(timedOut ? { error: 'Batch timeout' } : {}), data: { steps: results, totalSteps: task.arguments.steps.length, completedSteps: results.length, stoppedEarly } }, outputs };
196
+ }
197
+ finally {
198
+ clearTimeout(timer);
199
+ parentSignal.removeEventListener('abort', abort);
200
+ }
201
+ }
70
202
  async run(task, controller) {
71
203
  const { signal } = controller;
72
204
  const hash = digest(task);
73
205
  try {
74
- const target = 'path' in task.arguments ? task.arguments.path : 'executable' in task.arguments ? task.arguments.executable : undefined;
75
- const scope = task.operation === 'file.read' ? { offset: task.arguments.offset, length: task.arguments.length }
76
- : task.operation.startsWith('serial.') ? { baudRate: task.arguments.baudRate, durationMs: task.arguments.durationMs }
77
- : task.operation === 'process.run' ? { cwd: task.arguments.cwd ?? process.cwd(), argumentCount: task.arguments.args.length, timeoutMs: task.arguments.timeoutMs } : {};
78
- this.audit.record('task.requested', { id: task.id, operation: task.operation, digest: hash, ...(target ? { target } : {}), ...scope });
79
- const write = prepareWrite(task);
80
- const preview = redact(JSON.stringify(task, null, 2)) + (write ? '\n' + write.preview : '') + (task.operation.startsWith('serial.') ? '\nSerial control lines may reset the device.' : '');
206
+ const steps = task.operation === 'batch.run' ? task.arguments.steps : [task];
207
+ if (task.operation === 'batch.run' && steps.some(step => resourceOperation(step.operation)))
208
+ throw new Error('Open interactive/transfer/forward resources separately; their subsequent actions share one approved scope');
209
+ if (task.operation === 'batch.run')
210
+ this.audit.record('task.requested', { id: task.id, operation: task.operation, digest: hash, steps: steps.length });
211
+ for (const step of steps)
212
+ this.recordRequest(step, task.operation === 'batch.run' ? task.id : undefined);
213
+ const writes = new Map(steps.map(step => [step.id, prepareWrite(step)]));
214
+ const details = steps.map((step, index) => `${writes.get(step.id) ? `\nStep ${index + 1} write preview:\n${writes.get(step.id).preview}` : ''}${step.operation === 'process.script' ? `\nStep ${index + 1} complete script (${step.arguments.interpreter}):\n${step.arguments.script}\n--- end script ---` : ''}`).join('');
215
+ const preview = safeText(JSON.stringify(task, null, 2) + details) + (steps.some(step => step.operation.startsWith('serial.')) ? '\nSerial control lines may reset the device.' : '');
81
216
  if (!await this.permission({ stage: 'execute', task, digest: hash, preview, signal })) {
82
217
  this.audit.record('task.denied', { id: task.id });
83
218
  await this.finish(task.id, { status: 'denied' });
@@ -86,34 +221,36 @@ export class ProbeEngine {
86
221
  signal.throwIfAborted();
87
222
  if (digest(task) !== hash)
88
223
  throw new Error('Task parameters changed after approval');
89
- this.audit.record('task.approved', { id: task.id, digest: hash });
90
- await this.peer.send({ type: 'task.started', id: task.id, digest: hash });
91
- this.notice(`Executing ${task.operation}`);
92
- const execution = await execute(task, signal, write);
93
- if (execution.outputs.some(item => item.truncated))
94
- execution.result.truncated = true;
95
- if (task.operation === 'file.write' && execution.result.status === 'ok')
96
- this.audit.record('task.file-changed', { id: task.id, ...execution.result.data });
97
- const count = execution.outputs.reduce((sum, item) => sum + item.bytes.length, 0);
98
- this.audit.record('task.collected', { id: task.id, bytes: count, status: execution.result.status, streams: execution.outputs.map(item => ({ stream: item.stream, bytes: item.bytes.length, encoding: item.encoding })) });
99
- if (signal.aborted) {
100
- await this.finish(task.id, { status: 'cancelled' });
224
+ const continuous = resourceOperation(task.operation);
225
+ if (continuous && !await this.permission({ stage: 'send', task, digest: hash, preview: `${preview}\nThis grants continuing raw bidirectional input/output, file bytes or tunnel traffic for this resource. No automatic redaction. Further input/actions within the approved handle do not prompt again. retainOnDisconnect keeps the resource alive while this host CLI remains running.`, signal })) {
226
+ await this.finish(task.id, { status: 'denied' });
101
227
  return;
102
228
  }
103
- const resultText = JSON.stringify(execution.result);
229
+ signal.throwIfAborted();
230
+ if (digest(task) !== hash)
231
+ throw new Error('Task parameters changed after approval');
232
+ this.audit.record('task.approved', { id: task.id, digest: hash, mode: this.mode });
233
+ await this.peer.send({ type: 'task.started', id: task.id, digest: hash });
234
+ const execution = task.operation === 'batch.run' ? await this.runBatch(task, signal, writes, hash) : await this.runAtomic(task, signal, writes.get(task.id));
235
+ const count = execution.outputs.reduce((sum, item) => sum + item.bytes.length, 0);
236
+ if (task.operation === 'batch.run')
237
+ this.audit.record('task.collected', { id: task.id, bytes: count, status: execution.result.status });
238
+ signal.throwIfAborted();
104
239
  const outputPreview = execution.outputs.map(item => `[${item.stream}/${item.encoding}; ${item.bytes.length} bytes]\n${item.encoding === 'utf8' ? item.bytes.toString('utf8') : `BINARY: no automatic redaction. Preview shows first 256 bytes; approval sends all ${item.bytes.length} bytes.\n${item.bytes.subarray(0, 256).toString('hex')}`}`).join('\n');
105
- if (!await this.permission({ stage: 'send', task, digest: hash, preview: resultText + '\n' + outputPreview, bytes: count, signal })) {
240
+ if (!continuous && !await this.permission({ stage: 'send', task, digest: hash, preview: JSON.stringify(execution.result) + '\n' + outputPreview, bytes: count, signal })) {
106
241
  this.audit.record('task.send-denied', { id: task.id });
107
242
  await this.finish(task.id, { status: 'denied', error: 'Collected locally; user declined transfer' });
108
243
  return;
109
244
  }
110
245
  signal.throwIfAborted();
111
- this.audit.record('task.transfer-approved', { id: task.id, bytes: count });
246
+ this.audit.record('task.transfer-approved', { id: task.id, bytes: count, mode: this.mode });
112
247
  await this.transfer(task.id, execution, signal);
113
248
  this.audit.record('task.completed', { id: task.id, status: execution.result.status });
114
249
  }
115
250
  catch (error) {
116
251
  const status = signal.aborted ? 'cancelled' : 'error';
252
+ if (signal.aborted && task.operation !== 'batch.run' && resourceOperation(task.operation))
253
+ await this.resources.abandon(task, this.owner).catch(() => { });
117
254
  try {
118
255
  this.audit.record('task.failed', { id: task.id, status });
119
256
  }
@@ -134,11 +271,11 @@ export class ProbeEngine {
134
271
  for (let offset = 0; offset < item.bytes.length; offset += CHUNK_SIZE) {
135
272
  signal.throwIfAborted();
136
273
  const chunk = item.bytes.subarray(offset, offset + CHUNK_SIZE);
137
- // The audit entry is durable before the corresponding bytes leave this endpoint.
138
274
  this.audit.record('task.chunk-sending', { id, index, bytes: chunk.length });
139
275
  await this.peer.send({ type: 'task.output', id, stream: item.stream, chunk: chunk.toString('base64'), index: index++ });
140
276
  }
141
277
  }
278
+ signal.throwIfAborted();
142
279
  this.jobs.delete(id);
143
280
  await this.peer.send({ type: 'task.result', id, result: { ...execution.result, data: { ...(execution.result.data ?? {}), encodings } } });
144
281
  }
@@ -1,5 +1,5 @@
1
1
  import { type ChildProcess } from 'node:child_process';
2
- import { type Task, type Result } from './schema.js';
2
+ import { type AtomicTask, type Task, type Result } from './schema.js';
3
3
  export type Execution = {
4
4
  result: Result;
5
5
  outputs: {
@@ -14,5 +14,5 @@ export declare function prepareWrite(task: Task): {
14
14
  preview: string;
15
15
  parent: string;
16
16
  } | undefined;
17
- export declare function execute(task: Task, signal: AbortSignal, write?: ReturnType<typeof prepareWrite>): Promise<Execution>;
17
+ export declare function execute(task: AtomicTask, signal: AbortSignal, write?: ReturnType<typeof prepareWrite>): Promise<Execution>;
18
18
  export declare function killTree(child: ChildProcess, force?: boolean): void;
package/dist/executor.js CHANGED
@@ -1,10 +1,10 @@
1
1
  import { spawn } from 'node:child_process';
2
2
  import { constants, lstatSync, readFileSync, realpathSync } from 'node:fs';
3
- import { open, rename, unlink } from 'node:fs/promises';
3
+ import { open, rename, unlink, lstat, opendir, mkdir, rm, chmod, readlink } from 'node:fs/promises';
4
4
  import { dirname, basename, resolve, join } from 'node:path';
5
5
  import { randomUUID } from 'node:crypto';
6
6
  import { isUtf8 } from 'node:buffer';
7
- import os from 'node:os';
7
+ import { inspectSystem } from './discover.js';
8
8
  import { SerialPort } from 'serialport';
9
9
  import { MAX_OUTPUT } from './schema.js';
10
10
  import { redact, sha256 } from './util.js';
@@ -36,7 +36,49 @@ function output(stream, bytes) {
36
36
  export async function execute(task, signal, write) {
37
37
  signal.throwIfAborted();
38
38
  switch (task.operation) {
39
- case 'system.inspect': return { result: { status: 'ok', data: { platform: process.platform, arch: process.arch, release: os.release(), node: process.version, serialPorts: await SerialPort.list() } }, outputs: [] };
39
+ case 'system.inspect': return { result: { status: 'ok', data: await inspectSystem() }, outputs: [] };
40
+ case 'file.stat': {
41
+ const stat = await lstat(task.arguments.path);
42
+ return { result: { status: 'ok', data: { size: stat.size, mode: stat.mode & 0o777, modifiedAt: stat.mtime.toISOString(), type: stat.isDirectory() ? 'directory' : stat.isSymbolicLink() ? 'symlink' : stat.isFile() ? 'file' : 'other', ...(stat.isSymbolicLink() ? { target: await readlink(task.arguments.path) } : {}) } }, outputs: [] };
43
+ }
44
+ case 'file.list': {
45
+ const directory = await opendir(task.arguments.path);
46
+ const entries = [];
47
+ let index = 0, more = false;
48
+ for await (const entry of directory) {
49
+ signal.throwIfAborted();
50
+ if (index++ < task.arguments.offset)
51
+ continue;
52
+ if (entries.length >= task.arguments.limit) {
53
+ more = true;
54
+ break;
55
+ }
56
+ entries.push({ name: entry.name, type: entry.isDirectory() ? 'directory' : entry.isSymbolicLink() ? 'symlink' : entry.isFile() ? 'file' : 'other' });
57
+ }
58
+ return { result: { status: 'ok', data: { entries, nextOffset: task.arguments.offset + entries.length, hasMore: more } }, outputs: [] };
59
+ }
60
+ case 'file.mkdir':
61
+ await mkdir(task.arguments.path, { recursive: task.arguments.recursive, mode: 0o700 });
62
+ return { result: { status: 'ok' }, outputs: [] };
63
+ case 'file.remove':
64
+ await rm(task.arguments.path, { recursive: task.arguments.recursive, force: false });
65
+ return { result: { status: 'ok' }, outputs: [] };
66
+ case 'file.rename': {
67
+ try {
68
+ await lstat(task.arguments.destination);
69
+ if (!task.arguments.overwrite)
70
+ throw new Error('Destination exists; explicit overwrite is required');
71
+ }
72
+ catch (error) {
73
+ if (error.code !== 'ENOENT')
74
+ throw error;
75
+ }
76
+ await rename(task.arguments.path, task.arguments.destination);
77
+ return { result: { status: 'ok' }, outputs: [] };
78
+ }
79
+ case 'file.chmod':
80
+ await chmod(task.arguments.path, task.arguments.mode);
81
+ return { result: { status: 'ok' }, outputs: [] };
40
82
  case 'file.read': {
41
83
  const path = resolve(task.arguments.path);
42
84
  const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
@@ -84,8 +126,10 @@ export async function execute(task, signal, write) {
84
126
  return { result: { status: 'ok', data: { path, bytesWritten: Buffer.byteLength(task.arguments.content), beforeSha256: write.sha, afterSha256: sha256(Buffer.from(task.arguments.content)) } }, outputs: [] };
85
127
  }
86
128
  case 'process.run': return runProcess(task.arguments, signal);
129
+ case 'process.script': return runProcess({ ...task.arguments, executable: task.arguments.interpreter }, signal, task.arguments.script);
87
130
  case 'serial.capture':
88
131
  case 'serial.exchange': return capture(task, signal);
132
+ default: throw new Error('This operation requires the session resource manager');
89
133
  }
90
134
  }
91
135
  export function killTree(child, force = false) {
@@ -101,7 +145,7 @@ export function killTree(child, force = false) {
101
145
  }
102
146
  catch { /* Child may already have exited. */ }
103
147
  }
104
- async function runProcess(args, signal) {
148
+ async function runProcess(args, signal, script) {
105
149
  return new Promise(resolveResult => {
106
150
  const chunks = { stdout: [], stderr: [] };
107
151
  let bytes = 0, truncated = false, timedOut = false, launchError;
@@ -109,7 +153,11 @@ async function runProcess(args, signal) {
109
153
  for (const key of Object.keys(env))
110
154
  if (/^(?:DIAGNOSE_|OWON_|NPM_TOKEN|NODE_AUTH_TOKEN)/i.test(key))
111
155
  delete env[key];
112
- const child = spawn(args.executable, args.args, { cwd: args.cwd ?? process.cwd(), env, shell: false, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
156
+ const child = spawn(args.executable, args.args, { cwd: args.cwd ?? process.cwd(), env, shell: false, detached: process.platform !== 'win32', stdio: [script === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'], windowsHide: true });
157
+ if (script !== undefined) {
158
+ child.stdin.on('error', () => { });
159
+ child.stdin.end(script);
160
+ }
113
161
  let force;
114
162
  const stop = () => { killTree(child); force ??= setTimeout(() => killTree(child, true), 1000); force.unref(); };
115
163
  const timeout = setTimeout(() => { timedOut = true; stop(); }, args.timeoutMs);
@@ -0,0 +1,10 @@
1
+ import type { Operator } from './operator.js';
2
+ export type Forward = {
3
+ id: string;
4
+ direction: string;
5
+ host: string;
6
+ port: number;
7
+ readonly closed: boolean;
8
+ close: () => Promise<void>;
9
+ };
10
+ export declare function forward(operator: Operator, id: string, localPort?: number): Promise<Forward>;
@@ -0,0 +1,115 @@
1
+ import net from 'node:net';
2
+ async function write(socket, bytes) { await new Promise((resolve, reject) => socket.write(bytes, error => error ? reject(error) : resolve())); }
3
+ export async function forward(operator, id, localPort = 0) {
4
+ const meta = await operator.resource({ id, action: 'status' });
5
+ if (meta.kind !== 'forward')
6
+ throw new Error('First authorize a net.forward resource');
7
+ let closed = false, server;
8
+ const sockets = new Set();
9
+ const attach = (socket, connectionId) => {
10
+ sockets.add(socket);
11
+ socket.on('error', () => socket.destroy());
12
+ socket.on('data', bytes => { socket.pause(); void (async () => { for (let offset = 0; offset < bytes.length; offset += 65536)
13
+ await operator.resource({ id: connectionId, action: 'input', data: bytes.subarray(offset, offset + 65536).toString('base64') }); socket.resume(); })().catch(() => socket.destroy()); });
14
+ socket.on('end', () => { void operator.resource({ id: connectionId, action: 'input', data: '', eof: true }).catch(() => socket.destroy()); });
15
+ socket.on('close', () => { sockets.delete(socket); void operator.resource({ id: connectionId, action: 'close' }).catch(() => { }); });
16
+ void (async () => { while (!closed && !socket.destroyed) {
17
+ const result = await operator.resource({ id: connectionId, action: 'read' });
18
+ if (result.data)
19
+ await write(socket, Buffer.from(result.data, 'base64'));
20
+ if (result.ended) {
21
+ socket.end();
22
+ break;
23
+ }
24
+ if (!result.data)
25
+ await new Promise(resolve => setTimeout(resolve, 25));
26
+ } })().catch(() => socket.destroy());
27
+ socket.resume();
28
+ };
29
+ const connect = async (socket, host, port) => { const connection = await operator.resource({ id, action: 'connect', host, port }); attach(socket, connection.id); };
30
+ const stop = async () => { if (closed)
31
+ return; closed = true; server?.close(); for (const socket of sockets)
32
+ socket.destroy(); await operator.resource({ id, action: 'close' }).catch(() => { }); };
33
+ operator.peer.once('closed', () => { void stop(); });
34
+ if (meta.direction === 'remote') {
35
+ void (async () => {
36
+ while (!closed) {
37
+ const result = await operator.resource({ id, action: 'accept' });
38
+ for (const connectionId of result.connections) {
39
+ const socket = net.createConnection({ host: meta.host, port: meta.port, allowHalfOpen: true });
40
+ socket.pause();
41
+ socket.once('connect', () => attach(socket, connectionId));
42
+ socket.once('error', () => { void operator.resource({ id: connectionId, action: 'close' }).catch(() => { }); });
43
+ }
44
+ await new Promise(resolve => setTimeout(resolve, 50));
45
+ }
46
+ })().catch(() => { void stop(); });
47
+ return { id, direction: meta.direction, host: meta.bindHost ?? '127.0.0.1', port: meta.listeningPort, get closed() { return closed; }, close: stop };
48
+ }
49
+ server = net.createServer({ allowHalfOpen: true }, socket => {
50
+ socket.pause();
51
+ socket.on('error', () => socket.destroy());
52
+ if (meta.direction !== 'socks') {
53
+ void connect(socket).catch(() => socket.destroy());
54
+ return;
55
+ }
56
+ let buffer = Buffer.alloc(0), greeted = false;
57
+ const handshake = (bytes) => {
58
+ buffer = Buffer.concat([buffer, bytes]);
59
+ if (buffer.length > 4096) {
60
+ socket.destroy();
61
+ return;
62
+ }
63
+ if (!greeted) {
64
+ if (buffer.length < 2 || buffer.length < 2 + buffer[1])
65
+ return;
66
+ if (buffer[0] !== 5 || !buffer.subarray(2, 2 + buffer[1]).includes(0)) {
67
+ socket.end(Buffer.from([5, 255]));
68
+ return;
69
+ }
70
+ const count = 2 + buffer[1];
71
+ buffer = buffer.subarray(count);
72
+ greeted = true;
73
+ socket.write(Buffer.from([5, 0]));
74
+ }
75
+ if (buffer.length < 5)
76
+ return;
77
+ if (buffer[0] !== 5 || buffer[1] !== 1) {
78
+ socket.end(Buffer.from([5, 7, 0, 1, 0, 0, 0, 0, 0, 0]));
79
+ return;
80
+ }
81
+ let host, end;
82
+ if (buffer[3] === 1) {
83
+ end = 8;
84
+ if (buffer.length < end + 2)
85
+ return;
86
+ host = [...buffer.subarray(4, 8)].join('.');
87
+ }
88
+ else if (buffer[3] === 3) {
89
+ end = 5 + buffer[4];
90
+ if (buffer.length < end + 2)
91
+ return;
92
+ host = buffer.subarray(5, end).toString('utf8');
93
+ }
94
+ else if (buffer[3] === 4) {
95
+ end = 20;
96
+ if (buffer.length < end + 2)
97
+ return;
98
+ host = Array.from({ length: 8 }, (_, i) => buffer.readUInt16BE(4 + 2 * i).toString(16)).join(':');
99
+ }
100
+ else {
101
+ socket.destroy();
102
+ return;
103
+ }
104
+ const port = buffer.readUInt16BE(end), remainder = buffer.subarray(end + 2);
105
+ socket.pause();
106
+ socket.off('data', handshake);
107
+ void (async () => { const connection = await operator.resource({ id, action: 'connect', host, port }); await write(socket, Buffer.from([5, 0, 0, 1, 0, 0, 0, 0, 0, 0])); if (remainder.length)
108
+ socket.unshift(remainder); attach(socket, connection.id); })().catch(() => socket.end(Buffer.from([5, 5, 0, 1, 0, 0, 0, 0, 0, 0])));
109
+ };
110
+ socket.on('data', handshake);
111
+ socket.resume();
112
+ });
113
+ await new Promise((resolveListen, reject) => { server.once('error', reject); server.listen(localPort, '127.0.0.1', () => { server.off('error', reject); resolveListen(); }); });
114
+ return { id, direction: meta.direction, host: '127.0.0.1', port: server.address().port, get closed() { return closed; }, close: stop };
115
+ }
@@ -0,0 +1,32 @@
1
+ export type ResourceMeta = {
2
+ id: string;
3
+ kind: 'process' | 'upload' | 'download' | 'forward' | 'tcp';
4
+ state: string;
5
+ createdAt: string;
6
+ updatedAt: string;
7
+ ownerPid: number;
8
+ tokenHash: string;
9
+ retainOnDisconnect: boolean;
10
+ [key: string]: unknown;
11
+ };
12
+ export type OutputRecord = {
13
+ stream: string;
14
+ data: string;
15
+ };
16
+ export declare class Journal {
17
+ readonly root: string;
18
+ private key;
19
+ constructor(root: string);
20
+ private path;
21
+ private seal;
22
+ private unseal;
23
+ save(meta: ResourceMeta): void;
24
+ load(id: string): ResourceMeta;
25
+ exists(id: string): boolean;
26
+ append(id: string, stream: string, bytes: Buffer): void;
27
+ read(id: string, cursor?: number, limit?: number): {
28
+ records: OutputRecord[];
29
+ cursor: number;
30
+ hasMore: boolean;
31
+ };
32
+ }
@@ -0,0 +1,81 @@
1
+ import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
2
+ import { mkdirSync, readFileSync, writeFileSync, openSync, closeSync, appendFileSync, readSync, statSync, renameSync, existsSync } from 'node:fs';
3
+ import { join } from 'node:path';
4
+ import { CHUNK_SIZE } from './schema.js';
5
+ export class Journal {
6
+ root;
7
+ key;
8
+ constructor(root) {
9
+ this.root = root;
10
+ mkdirSync(root, { recursive: true, mode: 0o700 });
11
+ const path = join(root, 'key');
12
+ try {
13
+ writeFileSync(path, randomBytes(32), { flag: 'wx', mode: 0o600 });
14
+ }
15
+ catch (error) {
16
+ if (error.code !== 'EEXIST')
17
+ throw error;
18
+ }
19
+ this.key = readFileSync(path);
20
+ if (this.key.length !== 32)
21
+ throw new Error('Invalid local journal key');
22
+ }
23
+ path(id, extension) { if (!/^[a-f0-9-]{36}$/.test(id))
24
+ throw new Error('Invalid resource ID'); return join(this.root, id + extension); }
25
+ seal(id, bytes) {
26
+ const nonce = randomBytes(12), cipher = createCipheriv('aes-256-gcm', this.key, nonce);
27
+ cipher.setAAD(Buffer.from(id));
28
+ const encrypted = Buffer.concat([cipher.update(bytes), cipher.final()]);
29
+ return Buffer.concat([nonce, cipher.getAuthTag(), encrypted]);
30
+ }
31
+ unseal(id, bytes) {
32
+ const cipher = createDecipheriv('aes-256-gcm', this.key, bytes.subarray(0, 12));
33
+ cipher.setAAD(Buffer.from(id));
34
+ cipher.setAuthTag(bytes.subarray(12, 28));
35
+ return Buffer.concat([cipher.update(bytes.subarray(28)), cipher.final()]);
36
+ }
37
+ save(meta) { meta.updatedAt = new Date().toISOString(); const path = this.path(meta.id, '.meta'); const temp = path + '.tmp'; writeFileSync(temp, this.seal(meta.id, Buffer.from(JSON.stringify(meta))), { mode: 0o600, flush: true }); renameSync(temp, path); }
38
+ load(id) { return JSON.parse(this.unseal(id, readFileSync(this.path(id, '.meta'))).toString()); }
39
+ exists(id) { return existsSync(this.path(id, '.meta')); }
40
+ append(id, stream, bytes) {
41
+ for (let offset = 0; offset < bytes.length; offset += CHUNK_SIZE) {
42
+ const record = this.seal(id, Buffer.from(JSON.stringify({ stream, data: bytes.subarray(offset, offset + CHUNK_SIZE).toString('base64') })));
43
+ const header = Buffer.alloc(4);
44
+ header.writeUInt32BE(record.length);
45
+ appendFileSync(this.path(id, '.log'), Buffer.concat([header, record]), { mode: 0o600 });
46
+ }
47
+ }
48
+ read(id, cursor = 0, limit = 65536) {
49
+ const path = this.path(id, '.log');
50
+ if (!existsSync(path))
51
+ return { records: [], cursor: 0, hasMore: false };
52
+ const size = statSync(path).size;
53
+ if (cursor > size)
54
+ throw new Error('Output cursor is beyond stored data');
55
+ const fd = openSync(path, 'r');
56
+ const records = [];
57
+ let bytes = 0;
58
+ try {
59
+ while (cursor + 4 <= size && bytes < limit) {
60
+ const header = Buffer.alloc(4);
61
+ readSync(fd, header, 0, 4, cursor);
62
+ const length = header.readUInt32BE();
63
+ if (length < 28 || length > 128 * 1024 || cursor + 4 + length > size)
64
+ throw new Error('Invalid or incomplete journal record');
65
+ const block = Buffer.alloc(length);
66
+ readSync(fd, block, 0, length, cursor + 4);
67
+ const record = JSON.parse(this.unseal(id, block).toString());
68
+ const count = Buffer.from(record.data, 'base64').length;
69
+ if (records.length && bytes + count > limit)
70
+ break;
71
+ records.push(record);
72
+ bytes += count;
73
+ cursor += 4 + length;
74
+ }
75
+ return { records, cursor, hasMore: cursor < size };
76
+ }
77
+ finally {
78
+ closeSync(fd);
79
+ }
80
+ }
81
+ }