@masstensor/diagnose 0.3.2 → 0.7.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/DEVELOPMENT_PLAN.md +69 -0
- package/KNOWLEDGE_SECURITY.md +47 -0
- package/PAIRING_PROTOCOL.md +37 -0
- package/README.md +56 -9
- package/USER_GUIDE.md +460 -20
- package/deploy/Caddyfile +1 -1
- package/deploy/ecosystem.config.cjs +1 -1
- package/dist/agent-command.d.ts +4 -0
- package/dist/agent-command.js +33 -0
- package/dist/agent.d.ts +1 -1
- package/dist/agent.js +48 -8
- package/dist/cases.d.ts +118 -0
- package/dist/cases.js +115 -0
- package/dist/cli.js +187 -25
- package/dist/crypto.d.ts +7 -0
- package/dist/crypto.js +16 -1
- package/dist/discover.js +1 -1
- package/dist/engine.d.ts +3 -0
- package/dist/engine.js +49 -9
- package/dist/history.d.ts +13 -0
- package/dist/history.js +57 -0
- package/dist/journal.d.ts +23 -1
- package/dist/journal.js +82 -5
- package/dist/knowledge-cli.d.ts +2 -0
- package/dist/knowledge-cli.js +164 -0
- package/dist/knowledge-drafts.d.ts +47 -0
- package/dist/knowledge-drafts.js +76 -0
- package/dist/knowledge-mcp.d.ts +5 -0
- package/dist/knowledge-mcp.js +65 -0
- package/dist/maintenance.d.ts +2 -0
- package/dist/maintenance.js +46 -0
- package/dist/mcp.d.ts +1 -1
- package/dist/mcp.js +42 -20
- package/dist/operator.d.ts +4 -0
- package/dist/operator.js +33 -8
- package/dist/pairing.d.ts +40 -0
- package/dist/pairing.js +92 -0
- package/dist/peer.d.ts +13 -0
- package/dist/peer.js +87 -11
- package/dist/relay-main.js +1 -1
- package/dist/relay.d.ts +1 -0
- package/dist/relay.js +27 -4
- package/dist/resources.js +47 -26
- package/dist/schema.d.ts +2 -0
- package/dist/schema.js +2 -2
- package/dist/short-pairing.d.ts +25 -0
- package/dist/short-pairing.js +73 -0
- package/dist/skill-library.d.ts +27 -0
- package/dist/skill-library.js +226 -0
- package/dist/skill.d.ts +9 -0
- package/dist/skill.js +59 -0
- package/dist/transfers.js +28 -11
- package/dist/util.d.ts +2 -0
- package/dist/util.js +17 -3
- package/dist/vault-crypto.d.ts +11 -0
- package/dist/vault-crypto.js +30 -0
- package/dist/vault-server.d.ts +10 -0
- package/dist/vault-server.js +156 -0
- package/dist/vault.d.ts +19 -0
- package/dist/vault.js +72 -0
- package/examples/skills/device-troubleshooting/SKILL.md +35 -0
- package/examples/skills/device-troubleshooting/references/device-profile.md +16 -0
- package/examples/skills/owon.md +27 -0
- package/npm-shrinkwrap.json +209 -3
- package/package.json +15 -5
- package/scripts/setup-node.ps1 +54 -0
- package/scripts/setup-node.sh +52 -0
- package/src/agent-command.ts +25 -0
- package/src/agent.ts +37 -7
- package/src/cases.ts +74 -0
- package/src/cli.ts +57 -22
- package/src/crypto.ts +14 -1
- package/src/discover.ts +1 -1
- package/src/engine.ts +28 -7
- package/src/history.ts +43 -0
- package/src/journal.ts +41 -5
- package/src/knowledge-cli.ts +67 -0
- package/src/knowledge-drafts.ts +55 -0
- package/src/knowledge-mcp.ts +35 -0
- package/src/maintenance.ts +30 -0
- package/src/mcp.ts +26 -18
- package/src/operator.ts +25 -9
- package/src/pairing.ts +64 -0
- package/src/peer.ts +42 -14
- package/src/relay-main.ts +1 -1
- package/src/relay.ts +18 -6
- package/src/resources.ts +35 -13
- package/src/schema.ts +4 -4
- package/src/short-pairing.ts +57 -0
- package/src/skill-library.ts +162 -0
- package/src/skill.ts +45 -0
- package/src/transfers.ts +14 -3
- package/src/util.ts +15 -3
- package/src/vault-crypto.ts +25 -0
- package/src/vault-server.ts +72 -0
- package/src/vault.ts +51 -0
- package/test/agent.test.ts +79 -7
- package/test/cli.test.ts +3 -3
- package/test/knowledge-mcp.test.ts +37 -0
- package/test/knowledge.test.ts +112 -0
- package/test/mcp.test.ts +1 -1
- package/test/pairing.test.ts +124 -0
- package/test/review.test.ts +129 -0
- package/test/setup.test.ts +16 -0
- package/test/short-pairing.test.ts +100 -0
- package/test/skill-library.test.ts +62 -0
- package/test/skill.test.ts +25 -0
package/src/resources.ts
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
import { spawn as spawnProcess } from 'node:child_process';
|
|
2
2
|
import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
|
|
3
3
|
import { constants } from 'node:fs';
|
|
4
|
-
import { open, lstat, realpath, rename, unlink } from 'node:fs/promises';
|
|
4
|
+
import { open, lstat, realpath, rename, unlink, link } from 'node:fs/promises';
|
|
5
5
|
import { dirname, resolve, join, basename } from 'node:path';
|
|
6
6
|
import net from 'node:net';
|
|
7
|
-
import { Journal, type ResourceMeta } from './journal.js';
|
|
7
|
+
import { Journal, retention, type ResourceMeta } from './journal.js';
|
|
8
8
|
import { killTree } from './executor.js';
|
|
9
9
|
import { Audit, sha256 } from './util.js';
|
|
10
10
|
import type { AtomicTask, ResourceRequest } from './schema.js';
|
|
@@ -21,9 +21,12 @@ export class SessionResources {
|
|
|
21
21
|
readonly journal: Journal;
|
|
22
22
|
private resources = new Map<string, Resource>();
|
|
23
23
|
private writes = new Map<string, Promise<unknown>>();
|
|
24
|
-
constructor(root: string, private audit: Audit) { this.journal = new Journal(root); }
|
|
24
|
+
constructor(root: string, private audit: Audit) { this.journal = new Journal(root, retention); }
|
|
25
25
|
setAudit(audit: Audit): void { this.audit = audit; }
|
|
26
26
|
private create(id: string, kind: ResourceMeta['kind'], owner: string, retainOnDisconnect: boolean, details: Record<string, unknown> = {}): { resource: Resource; token: string } {
|
|
27
|
+
for (const [key, value] of this.resources) {
|
|
28
|
+
if (!['running', 'open', 'listening'].includes(value.meta.state) && (!this.journal.exists(key) || this.resources.size >= 256)) this.resources.delete(key);
|
|
29
|
+
}
|
|
27
30
|
if (this.resources.has(id) || this.journal.exists(id)) throw new Error('Resource ID already exists. Resume it; do not replay its creation.');
|
|
28
31
|
if ([...this.resources.values()].filter(r => ['running', 'open', 'listening'].includes(r.meta.state)).length >= 128) throw new Error('Active resource limit reached; close unused resources');
|
|
29
32
|
const token = randomBytes(32).toString('base64url'), now = new Date().toISOString();
|
|
@@ -72,7 +75,9 @@ export class SessionResources {
|
|
|
72
75
|
if (request.action === 'input') {
|
|
73
76
|
if (!resource.input) throw new Error('This resource does not accept input'); const bytes = Buffer.from(request.data ?? '', 'base64');
|
|
74
77
|
if (bytes.length > 65536 || bytes.toString('base64') !== (request.data ?? '')) throw new Error('Invalid input encoding');
|
|
75
|
-
this.audit.record('resource.input', { id: meta.id, bytes: bytes.length, eof: request.eof });
|
|
78
|
+
this.audit.record('resource.input', { id: meta.id, bytes: bytes.length, eof: request.eof });
|
|
79
|
+
if (meta.kind === 'process') this.audit.history.event(meta.id, 'process-input', { encoding: 'base64', data: bytes.toString('base64'), eof: request.eof });
|
|
80
|
+
await resource.input(bytes, request.eof); return { acceptedBytes: bytes.length };
|
|
76
81
|
}
|
|
77
82
|
if (request.action === 'resize') { if (!resource.resize || !request.cols || !request.rows) throw new Error('Resize requires a PTY and dimensions'); this.audit.record('resource.resize', { id: meta.id, cols: request.cols, rows: request.rows }); resource.resize(request.cols, request.rows); return publicMeta(meta); }
|
|
78
83
|
if (request.action === 'signal') { if (!resource.signal) throw new Error('Not a running process'); const signal = request.signal ?? 'SIGINT'; this.audit.record('resource.signal', { id: meta.id, signal }); resource.signal(signal); return { signalled: true }; }
|
|
@@ -84,8 +89,10 @@ export class SessionResources {
|
|
|
84
89
|
const args = task.arguments, executable = args.executable ?? (process.platform === 'win32' ? process.env.ComSpec ?? 'cmd.exe' : process.env.SHELL ?? '/bin/sh');
|
|
85
90
|
const { resource, token } = this.create(task.id, 'process', owner, args.retainOnDisconnect, { state: 'running', executable, cwd: resolve(args.cwd ?? process.cwd()), pty: args.pty, cols: args.cols, rows: args.rows, bytes: 0 });
|
|
86
91
|
const { meta } = resource; const env = { ...process.env, ...args.env }; for (const key of Object.keys(env)) if (/^(?:DIAGNOSE_|OWON_|NPM_TOKEN|NODE_AUTH_TOKEN)/i.test(key)) delete env[key];
|
|
87
|
-
let timer: NodeJS.Timeout | undefined,
|
|
88
|
-
|
|
92
|
+
let timer: NodeJS.Timeout | undefined, closing: Promise<void> | undefined;
|
|
93
|
+
// A leader exiting does not mean its process group has exited. Clean up
|
|
94
|
+
// immediately, while the group ID still belongs to this job.
|
|
95
|
+
const ended = (code: number | null, signal?: number | string): void => { resource.signal?.('SIGKILL'); clearTimeout(timer); meta.state = 'exited'; meta.exitCode = code; if (signal !== undefined) meta.signal = signal; this.journal.save(meta); this.audit.record('resource.process-exited', { id: meta.id, exitCode: code }); };
|
|
89
96
|
const collect = (stream: string, bytes: Buffer): void => {
|
|
90
97
|
try {
|
|
91
98
|
const keep = Math.max(0, Math.min(bytes.length, args.maxOutputBytes - Number(meta.bytes))); if (keep) this.journal.append(meta.id, stream, bytes.subarray(0, keep)); meta.bytes = Number(meta.bytes) + keep;
|
|
@@ -99,15 +106,24 @@ export class SessionResources {
|
|
|
99
106
|
child.onData(value => collect('terminal', Buffer.isBuffer(value) ? value : Buffer.from(value))); child.onExit(value => ended(value.exitCode, value.signal));
|
|
100
107
|
resource.input = async (bytes, eof) => { child.write(bytes.toString('utf8')); if (eof) child.write('\x04'); };
|
|
101
108
|
resource.resize = (cols, rows) => { child.resize(cols, rows); meta.cols = cols; meta.rows = rows; this.journal.save(meta); };
|
|
102
|
-
resource.signal = signal => { try { child.kill(signal); } catch {} };
|
|
109
|
+
resource.signal = signal => { try { if (process.platform === 'win32') child.kill(signal); else process.kill(-child.pid, signal as NodeJS.Signals); } catch {} };
|
|
103
110
|
} else {
|
|
104
111
|
const child = spawnProcess(executable, args.args, { cwd: String(meta.cwd), env, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true }); meta.pid = child.pid;
|
|
105
112
|
child.stdout.on('data', bytes => collect('stdout', bytes)); child.stderr.on('data', bytes => collect('stderr', bytes)); child.stdin.on('error', () => {});
|
|
106
|
-
child.on('error', error => { meta.error = error.message; }); child.on('
|
|
113
|
+
child.on('error', error => { meta.error = error.message; meta.state = 'failed'; this.journal.save(meta); }); child.on('exit', (code, signal) => ended(code, signal ?? undefined));
|
|
107
114
|
resource.input = (bytes, eof) => new Promise((resolveInput, reject) => { if (child.stdin.destroyed || child.stdin.writableEnded) { reject(new Error('Process stdin is closed')); return; } if (eof) child.stdin.end(bytes, resolveInput); else child.stdin.write(bytes, error => error ? reject(error) : resolveInput()); });
|
|
108
115
|
resource.signal = signal => { if (process.platform === 'win32') killTree(child, signal === 'SIGKILL'); else { try { process.kill(-child.pid!, signal as NodeJS.Signals); } catch {} } };
|
|
109
116
|
}
|
|
110
|
-
resource.close = () => {
|
|
117
|
+
resource.close = () => {
|
|
118
|
+
if (closing) return closing;
|
|
119
|
+
if (meta.state !== 'running') return;
|
|
120
|
+
resource.signal?.('SIGTERM');
|
|
121
|
+
closing = new Promise<void>(resolveClose => setTimeout(() => {
|
|
122
|
+
if (meta.state === 'running') resource.signal?.('SIGKILL');
|
|
123
|
+
resolveClose();
|
|
124
|
+
}, 1000));
|
|
125
|
+
return closing;
|
|
126
|
+
};
|
|
111
127
|
if (args.timeoutMs) { timer = setTimeout(() => { meta.timedOut = true; void resource.close(); }, args.timeoutMs); timer.unref(); }
|
|
112
128
|
this.journal.save(meta); this.audit.record('resource.process-started', { id: meta.id, pid: meta.pid, pty: args.pty, retainOnDisconnect: args.retainOnDisconnect });
|
|
113
129
|
return { ...publicMeta(meta), resumeToken: token, output: 'Raw, unredacted bytes. Poll read from cursor 0 for live output; input/resize/signals are authorized for this handle.' };
|
|
@@ -116,7 +132,7 @@ export class SessionResources {
|
|
|
116
132
|
private async startTransfer(task: Extract<AtomicTask, { operation: 'file.transfer' }>, owner: string, signal?: AbortSignal): Promise<unknown> {
|
|
117
133
|
const args = task.arguments, path = resolve(args.path); let details: Record<string, unknown>;
|
|
118
134
|
if (args.direction === 'download') { const stat = await lstat(path); if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('Download requires a regular non-symlink file'); details = { path, size: stat.size, sha256: await fileHash(path), offset: 0 }; }
|
|
119
|
-
else { if (args.size === undefined || !args.sha256) throw new Error('Upload requires exact size and SHA-256'); const before = await currentHash(path); if (before !== null && !args.overwrite) throw new Error('Target exists; explicit overwrite authorization required'); details = { path, parent: await realpath(dirname(path)), temp: join(dirname(path), `.${basename(path)}.diagnose-${task.id}`), beforeSha256: before, size: args.size, sha256: args.sha256, offset: 0 }; }
|
|
135
|
+
else { if (args.size === undefined || !args.sha256) throw new Error('Upload requires exact size and SHA-256'); const before = await currentHash(path); if (before !== null && !args.overwrite) throw new Error('Target exists; explicit overwrite authorization required'); details = { path, parent: await realpath(dirname(path)), temp: join(dirname(path), `.${basename(path)}.diagnose-${task.id}`), beforeSha256: before, mode: before === null ? 0o600 : (await lstat(path)).mode & 0o777, size: args.size, sha256: args.sha256, offset: 0 }; }
|
|
120
136
|
signal?.throwIfAborted(); const { resource, token } = this.create(task.id, args.direction, owner, args.retainOnDisconnect, details);
|
|
121
137
|
const live = await this.restoreTransfer(resource.meta, owner, true); if (signal?.aborted || resource.owner !== owner) { await live.close(); throw new Error('Transfer authorization was cancelled'); } this.resources.set(task.id, live);
|
|
122
138
|
this.audit.record('resource.transfer-opened', { id: task.id, direction: args.direction, path, size: details.size }); return { ...publicMeta(live.meta), resumeToken: token, encoding: 'base64', redaction: 'none; exact file bytes' };
|
|
@@ -137,7 +153,13 @@ export class SessionResources {
|
|
|
137
153
|
if (meta.offset !== meta.size) throw new Error('Upload is incomplete'); await file.sync();
|
|
138
154
|
if (await fileHash(String(meta.temp)) !== meta.sha256) throw new Error('Upload SHA-256 mismatch; destination untouched');
|
|
139
155
|
if (await realpath(dirname(String(meta.path))) !== meta.parent || await currentHash(String(meta.path)) !== meta.beforeSha256) throw new Error('Destination changed since upload authorization');
|
|
140
|
-
|
|
156
|
+
if (closed || resource.owner !== owner) throw new Error('Transfer authorization was revoked');
|
|
157
|
+
await file.chmod(Number(meta.mode ?? 0o600)); await file.close();
|
|
158
|
+
if (closed || resource.owner !== owner) throw new Error('Transfer authorization was revoked');
|
|
159
|
+
closed = true;
|
|
160
|
+
if (meta.beforeSha256 === null) { await link(String(meta.temp), String(meta.path)); await unlink(String(meta.temp)); }
|
|
161
|
+
else await rename(String(meta.temp), String(meta.path));
|
|
162
|
+
meta.state = 'committed'; this.journal.save(meta); this.audit.record('resource.file-changed', { id: meta.id, path: meta.path, beforeSha256: meta.beforeSha256, afterSha256: meta.sha256, bytes: meta.size }); return publicMeta(meta);
|
|
141
163
|
};
|
|
142
164
|
}
|
|
143
165
|
return resource;
|
|
@@ -170,9 +192,9 @@ export class SessionResources {
|
|
|
170
192
|
resource.close = async () => { server?.close(); for (const child of this.resources.values()) if (child.meta.parentId === task.id) await child.close(); resource.meta.state = 'closed'; this.journal.save(resource.meta); };
|
|
171
193
|
this.journal.save(resource.meta); return { ...publicMeta(resource.meta), resumeToken: token };
|
|
172
194
|
}
|
|
173
|
-
async disconnect(owner: string): Promise<void> {
|
|
195
|
+
async disconnect(owner: string): Promise<void> { const affected = [...this.resources.values()].filter(resource => resource.owner === owner); for (const resource of affected) resource.owner = ''; await Promise.all(affected.filter(resource => !resource.meta.retainOnDisconnect).map(resource => resource.close())); }
|
|
174
196
|
async abandon(task: AtomicTask, owner: string): Promise<void> { const id = task.operation === 'resource.resume' ? task.arguments.id : task.id, resource = this.resources.get(id); if (resource?.owner === owner) { resource.owner = ''; if (task.operation !== 'resource.resume' || !resource.meta.retainOnDisconnect) await resource.close(); } }
|
|
175
|
-
async revoke(owner?: string): Promise<void> {
|
|
197
|
+
async revoke(owner?: string): Promise<void> { const affected = [...this.resources.values()].filter(resource => owner === undefined || resource.owner === owner); for (const resource of affected) resource.owner = ''; await Promise.all(affected.map(resource => resource.close())); }
|
|
176
198
|
listLocal(): Record<string, unknown>[] { return [...this.resources.values()].map(resource => publicMeta(resource.meta)); }
|
|
177
199
|
async localInput(id: string, value: Buffer): Promise<void> { const resource = this.resources.get(id); if (!resource?.input || resource.meta.state !== 'running') throw new Error('No live process with this ID'); this.audit.record('resource.local-input', { id, bytes: value.length }); await resource.input(value, false); }
|
|
178
200
|
renewCredential(id: string): string { const meta = this.resources.get(id)?.meta ?? this.journal.load(id); const token = randomBytes(32).toString('base64url'); meta.tokenHash = sha256(Buffer.from(token)); this.journal.save(meta); this.audit.record('resource.local-credential-renewed', { id }); return token; }
|
package/src/schema.ts
CHANGED
|
@@ -39,9 +39,9 @@ export type Result = { status: 'ok' | 'error' | 'denied' | 'cancelled' | 'duplic
|
|
|
39
39
|
export const resourceRequestSchema = z.object({ id: z.string().uuid().optional(), action: z.enum(['list', 'read', 'input', 'resize', 'signal', 'status', 'close', 'commit', 'connect', 'accept']), cursor: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(65536).default(65536), data: z.string().max(90000).optional(), eof: z.boolean().default(false), cols: z.number().int().min(20).max(500).optional(), rows: z.number().int().min(5).max(200).optional(), signal: z.enum(['SIGINT', 'SIGTERM', 'SIGKILL', 'SIGHUP', 'SIGQUIT']).optional(), host: z.string().min(1).max(253).optional(), port: z.number().int().min(1).max(65535).optional() }).strict();
|
|
40
40
|
export type ResourceRequest = z.infer<typeof resourceRequestSchema>;
|
|
41
41
|
export type WireMessage =
|
|
42
|
-
| { type: 'session.accepted'; label: string; fingerprint: string }
|
|
42
|
+
| { type: 'session.accepted'; label: string; fingerprint: string; credential?: string }
|
|
43
43
|
| { type: 'session.closed'; reason: string }
|
|
44
|
-
| { type: 'task.request'; task: Task }
|
|
44
|
+
| { type: 'task.request'; task: Task; sequence?: number }
|
|
45
45
|
| { type: 'task.started'; id: string; digest: string }
|
|
46
46
|
| { type: 'task.output'; id: string; stream: string; chunk: string; index: number }
|
|
47
47
|
| { type: 'task.result'; id: string; result: Result }
|
|
@@ -55,12 +55,12 @@ export type WireMessage =
|
|
|
55
55
|
export function parseMessage(value: unknown): WireMessage {
|
|
56
56
|
const basic = z.object({ type: z.string() }).passthrough().parse(value);
|
|
57
57
|
switch (basic.type) {
|
|
58
|
-
case 'task.request': return { type: basic.type, task: taskSchema.parse(basic.task) };
|
|
58
|
+
case 'task.request': return { type: basic.type, task: taskSchema.parse(basic.task), ...(basic.sequence === undefined ? {} : { sequence: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).parse(basic.sequence) }) };
|
|
59
59
|
case 'task.cancel': return { type: basic.type, id: z.string().uuid().parse(basic.id) };
|
|
60
60
|
case 'resource.request': return { type: basic.type, requestId: z.string().uuid().parse(basic.requestId), request: resourceRequestSchema.parse(basic.request) };
|
|
61
61
|
case 'resource.result': return z.object({ type: z.literal('resource.result'), requestId: z.string().uuid(), value: z.unknown().optional(), error: z.string().max(2000).optional() }).strict().parse(value);
|
|
62
62
|
case 'ping': case 'pong': return { type: basic.type };
|
|
63
|
-
case 'session.accepted': return z.object({ type: z.literal('session.accepted'), label: z.string().max(120), fingerprint: z.string().max(100) }).strict().parse(value);
|
|
63
|
+
case 'session.accepted': return z.object({ type: z.literal('session.accepted'), label: z.string().max(120), fingerprint: z.string().max(100), credential: z.string().regex(/^D1\.[A-Za-z0-9_-]{16}\.[A-Za-z0-9_-]{43}$/).optional() }).strict().parse(value);
|
|
64
64
|
case 'session.closed': return z.object({ type: z.literal('session.closed'), reason: z.string().max(200) }).strict().parse(value);
|
|
65
65
|
case 'task.started': return z.object({ type: z.literal('task.started'), id: z.string().uuid(), digest: z.string().regex(/^[a-f0-9]{64}$/) }).strict().parse(value);
|
|
66
66
|
case 'task.output': return z.object({ type: z.literal('task.output'), id: z.string().uuid(), stream: z.string().max(20), chunk: z.string().max(CHUNK_SIZE * 2), index: z.number().int().min(0) }).strict().parse(value);
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import * as opaque from '@serenity-kit/opaque';
|
|
2
|
+
import { hkdfSync } from 'node:crypto';
|
|
3
|
+
|
|
4
|
+
// Registration runs entirely on the probe. The relay sees neither the password,
|
|
5
|
+
// registration record nor OPAQUE server setup. Both login roles are endpoints.
|
|
6
|
+
await opaque.ready;
|
|
7
|
+
const identifiers = (room: string) => ({ client: `diagnose/v2/operator/${room}`, server: `diagnose/v2/probe/${room}` });
|
|
8
|
+
const key = (sessionKey: string, room: string) => Buffer.from(hkdfSync('sha256', Buffer.from(sessionKey, 'base64url'), 'diagnose/opaque/v2', `noise-psk/${room}`, 32));
|
|
9
|
+
export function pakeMessage(stage: string, value: string): Buffer { return Buffer.from(JSON.stringify({ pake: stage, value })); }
|
|
10
|
+
export function pakeValue(bytes: Buffer, expected: string): string {
|
|
11
|
+
if (bytes.length > 4096) throw new Error('Oversized PAKE message');
|
|
12
|
+
const value = JSON.parse(bytes.toString());
|
|
13
|
+
if (value?.pake !== expected || typeof value.value !== 'string' || !/^[A-Za-z0-9_+/=-]{1,2048}$/.test(value.value) || Object.keys(value).length !== 2) throw new Error('Invalid PAKE message');
|
|
14
|
+
return value.value;
|
|
15
|
+
}
|
|
16
|
+
export class InvitationHost {
|
|
17
|
+
private setup: string;
|
|
18
|
+
private record: string;
|
|
19
|
+
private state?: string;
|
|
20
|
+
constructor(private room: string, password: Buffer) {
|
|
21
|
+
this.setup = opaque.server.createSetup();
|
|
22
|
+
const registration = opaque.client.startRegistration({ password: password.toString() });
|
|
23
|
+
const response = opaque.server.createRegistrationResponse({ serverSetup: this.setup, userIdentifier: room, registrationRequest: registration.registrationRequest });
|
|
24
|
+
this.record = opaque.client.finishRegistration({ clientRegistrationState: registration.clientRegistrationState, registrationResponse: response.registrationResponse, password: password.toString(), identifiers: identifiers(room), keyStretching: 'memory-constrained' }).registrationRecord;
|
|
25
|
+
}
|
|
26
|
+
start(bytes: Buffer): Buffer {
|
|
27
|
+
if (this.state) throw new Error('PAKE already started');
|
|
28
|
+
const response = opaque.server.startLogin({ serverSetup: this.setup, registrationRecord: this.record, userIdentifier: this.room, startLoginRequest: pakeValue(bytes, 'start'), identifiers: identifiers(this.room) });
|
|
29
|
+
this.state = response.serverLoginState;
|
|
30
|
+
return pakeMessage('response', response.loginResponse);
|
|
31
|
+
}
|
|
32
|
+
finish(bytes: Buffer): Buffer {
|
|
33
|
+
if (!this.state) throw new Error('PAKE not started');
|
|
34
|
+
const state = this.state; this.state = undefined;
|
|
35
|
+
const response = opaque.server.finishLogin({ serverLoginState: state, finishLoginRequest: pakeValue(bytes, 'finish'), identifiers: identifiers(this.room) });
|
|
36
|
+
return key(response.sessionKey, this.room);
|
|
37
|
+
}
|
|
38
|
+
reset(): void { this.state = undefined; }
|
|
39
|
+
destroy(): void { this.reset(); this.setup = ''; this.record = ''; }
|
|
40
|
+
}
|
|
41
|
+
export class InvitationJoin {
|
|
42
|
+
private state?: string;
|
|
43
|
+
constructor(private room: string, private password: Buffer) {}
|
|
44
|
+
start(): Buffer {
|
|
45
|
+
if (this.state) throw new Error('PAKE already started');
|
|
46
|
+
const response = opaque.client.startLogin({ password: this.password.toString() }); this.state = response.clientLoginState;
|
|
47
|
+
return pakeMessage('start', response.startLoginRequest);
|
|
48
|
+
}
|
|
49
|
+
finish(bytes: Buffer): { reply: Buffer; secret: Buffer } {
|
|
50
|
+
if (!this.state) throw new Error('PAKE not started');
|
|
51
|
+
const state = this.state; this.state = undefined;
|
|
52
|
+
const response = opaque.client.finishLogin({ clientLoginState: state, password: this.password.toString(), loginResponse: pakeValue(bytes, 'response'), identifiers: identifiers(this.room), keyStretching: 'memory-constrained' });
|
|
53
|
+
if (!response) throw new Error('Incorrect invitation');
|
|
54
|
+
return { reply: pakeMessage('finish', response.finishLoginRequest), secret: key(response.sessionKey, this.room) };
|
|
55
|
+
}
|
|
56
|
+
destroy(): void { this.state = undefined; }
|
|
57
|
+
}
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
import { constants } from 'node:fs';
|
|
3
|
+
import { lstat, mkdir, mkdtemp, open, readdir, rename, rm, writeFile } from 'node:fs/promises';
|
|
4
|
+
import { homedir } from 'node:os';
|
|
5
|
+
import { join, resolve } from 'node:path';
|
|
6
|
+
import { loadSkill, type SessionSkill } from './skill.js';
|
|
7
|
+
|
|
8
|
+
const MAX_BYTES = 8 * 1024 * 1024;
|
|
9
|
+
const MAX_FILES = 128;
|
|
10
|
+
const namePattern = /^[a-z0-9][a-z0-9-]{0,63}$/;
|
|
11
|
+
const revisionPattern = /^[a-f0-9]{64}$/;
|
|
12
|
+
type Entry = { path: string; bytes: Buffer; executable: boolean };
|
|
13
|
+
export const skillsUsage = 'diagnose skills import NAME FILE.md|DIRECTORY\ndiagnose skills list\nLaunch: diagnose agent codex|claude|gemini --skill library:NAME@REVISION';
|
|
14
|
+
|
|
15
|
+
// Portable names only: reject separators, traversal, Windows aliases and device names.
|
|
16
|
+
function validPart(part: string): boolean {
|
|
17
|
+
return /^[a-zA-Z0-9_.-]+$/.test(part) && !['.', '..'].includes(part) && !/[. ]$/.test(part) && !/^(con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\.|$)/i.test(part);
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
async function readBundle(input: string): Promise<Entry[]> {
|
|
21
|
+
const source = resolve(input), info = await lstat(source);
|
|
22
|
+
if (info.isSymbolicLink()) throw new Error('Skill bundles cannot contain symbolic links');
|
|
23
|
+
const entries: Entry[] = []; let total = 0, visited = 0;
|
|
24
|
+
const add = async (file: string, path: string) => {
|
|
25
|
+
if (entries.length >= MAX_FILES) throw new Error('Skill bundle exceeds 128 files');
|
|
26
|
+
const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
|
|
27
|
+
try {
|
|
28
|
+
const metadata = await handle.stat();
|
|
29
|
+
if (!metadata.isFile()) throw new Error('Skill bundles require regular files');
|
|
30
|
+
if (metadata.size > MAX_BYTES - total) throw new Error('Skill bundle exceeds 8 MiB');
|
|
31
|
+
const buffer = Buffer.alloc(MAX_BYTES - total + 1); let size = 0;
|
|
32
|
+
while (size < buffer.length) { const { bytesRead } = await handle.read(buffer, size, buffer.length - size, size); if (!bytesRead) break; size += bytesRead; }
|
|
33
|
+
total += size;
|
|
34
|
+
if (total > MAX_BYTES) throw new Error('Skill bundle exceeds 8 MiB');
|
|
35
|
+
entries.push({ path, bytes: Buffer.from(buffer.subarray(0, size)), executable: !!(metadata.mode & 0o111) });
|
|
36
|
+
} finally { await handle.close(); }
|
|
37
|
+
};
|
|
38
|
+
const walk = async (directory: string, prefix: string, depth: number): Promise<void> => {
|
|
39
|
+
if (depth > 16) throw new Error('Skill directory nesting exceeds 16 levels');
|
|
40
|
+
const names = await readdir(directory); const portable = new Set<string>();
|
|
41
|
+
for (const name of names.sort()) {
|
|
42
|
+
if (++visited > 256) throw new Error('Skill bundle exceeds 256 directory entries');
|
|
43
|
+
if (!validPart(name) || portable.has(name.toLowerCase())) throw new Error('Skill bundle contains a non-portable or duplicate path');
|
|
44
|
+
portable.add(name.toLowerCase());
|
|
45
|
+
const file = join(directory, name), path = prefix + name, item = await lstat(file);
|
|
46
|
+
if (item.isSymbolicLink()) throw new Error('Skill bundles cannot contain symbolic links');
|
|
47
|
+
if (item.isDirectory()) await walk(file, path + '/', depth + 1);
|
|
48
|
+
else if (item.isFile()) await add(file, path);
|
|
49
|
+
else throw new Error('Skill bundles require regular files');
|
|
50
|
+
}
|
|
51
|
+
};
|
|
52
|
+
if (info.isDirectory()) await walk(source, '', 0);
|
|
53
|
+
else { await loadSkill(source); await add(source, 'SKILL.md'); }
|
|
54
|
+
if (!entries.some(entry => entry.path === 'SKILL.md')) throw new Error('Skill directory requires SKILL.md');
|
|
55
|
+
await loadSkill(info.isDirectory() ? join(source, 'SKILL.md') : source);
|
|
56
|
+
return entries.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function digest(entries: Entry[]): string {
|
|
60
|
+
// Length-delimited canonical JSON avoids ambiguous path/content concatenation.
|
|
61
|
+
return createHash('sha256').update(JSON.stringify(entries.map(entry => [entry.path, entry.bytes.toString('base64')]))).digest('hex');
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export class SkillLibrary {
|
|
65
|
+
constructor(readonly root = join(homedir(), '.diagnose', 'skills')) {}
|
|
66
|
+
|
|
67
|
+
async bundle(reference: string): Promise<{ reference: string; files: { path: string; data: string }[] }> {
|
|
68
|
+
const skill = await this.load(reference);
|
|
69
|
+
return { reference, files: (await readBundle(skill.baseDirectory)).map(entry => ({ path: entry.path, data: entry.bytes.toString('base64') })) };
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
async exportTo(reference: string, directory: string): Promise<void> {
|
|
73
|
+
const bundle = await this.bundle(reference);
|
|
74
|
+
await this.writeBundle(bundle.files, directory);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
private async writeBundle(files: { path: string; data: string }[], directory: string): Promise<void> {
|
|
78
|
+
if (!Array.isArray(files) || files.length > MAX_FILES) throw new Error('Invalid skill bundle');
|
|
79
|
+
let total = 0;
|
|
80
|
+
for (const entry of files) {
|
|
81
|
+
if (typeof entry.path !== 'string' || entry.path.length > 2048 || !entry.path.split('/').every(validPart) || typeof entry.data !== 'string') throw new Error('Invalid bundle path or content');
|
|
82
|
+
const bytes = Buffer.from(entry.data, 'base64'); total += bytes.length;
|
|
83
|
+
if (total > MAX_BYTES || bytes.toString('base64') !== entry.data) throw new Error('Invalid or oversized bundle content');
|
|
84
|
+
const parts = entry.path.split('/'), name = parts.pop()!;
|
|
85
|
+
const parent = join(directory, ...parts); await mkdir(parent, { recursive: true, mode: 0o700 });
|
|
86
|
+
await writeFile(join(parent, name), bytes, { flag: 'wx', mode: 0o600 });
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
async restore(bundle: { reference: string; files: { path: string; data: string }[] }): Promise<string> {
|
|
91
|
+
const match = /^library:([a-z0-9][a-z0-9-]{0,63})@([a-f0-9]{64})$/.exec(bundle.reference);
|
|
92
|
+
if (!match) throw new Error('Invalid bundle reference');
|
|
93
|
+
await mkdir(this.root, { recursive: true, mode: 0o700 });
|
|
94
|
+
const directory = await mkdtemp(join(this.root, '.restore-'));
|
|
95
|
+
try {
|
|
96
|
+
await this.writeBundle(bundle.files, directory);
|
|
97
|
+
if (digest(await readBundle(directory)) !== match[2]) throw new Error('Downloaded bundle failed integrity verification');
|
|
98
|
+
return await this.import(match[1], directory);
|
|
99
|
+
} finally { await rm(directory, { recursive: true, force: true }); }
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
async import(name: string, input: string): Promise<string> {
|
|
103
|
+
if (!namePattern.test(name) || !validPart(name)) throw new Error('Skill name must be a portable name of 1..64 lowercase letters, digits or hyphens, starting with a letter or digit');
|
|
104
|
+
const entries = await readBundle(input), revision = digest(entries), parent = join(this.root, name);
|
|
105
|
+
await mkdir(parent, { recursive: true, mode: 0o700 });
|
|
106
|
+
const reference = `library:${name}@${revision}`, destination = join(parent, revision);
|
|
107
|
+
try { await lstat(destination); await this.load(reference); return reference; }
|
|
108
|
+
catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
|
|
109
|
+
const temporary = await mkdtemp(join(parent, '.import-'));
|
|
110
|
+
try {
|
|
111
|
+
for (const entry of entries) {
|
|
112
|
+
const parts = entry.path.split('/'); const filename = parts.pop()!;
|
|
113
|
+
const directory = join(temporary, ...parts);
|
|
114
|
+
await mkdir(directory, { recursive: true, mode: 0o700 });
|
|
115
|
+
await writeFile(join(directory, filename), entry.bytes, { flag: 'wx', mode: entry.executable ? 0o700 : 0o600 });
|
|
116
|
+
}
|
|
117
|
+
if (digest(await readBundle(temporary)) !== revision) throw new Error('Skill changed during import');
|
|
118
|
+
try { await rename(temporary, destination); }
|
|
119
|
+
catch (error) {
|
|
120
|
+
// Windows reports EPERM when another import already published this
|
|
121
|
+
// nonempty directory. Accept only a fully verified existing revision,
|
|
122
|
+
// never an error code alone (which could also mean real permission loss).
|
|
123
|
+
try { await this.load(reference); } catch { throw error; }
|
|
124
|
+
}
|
|
125
|
+
await this.load(reference);
|
|
126
|
+
return reference;
|
|
127
|
+
} finally { await rm(temporary, { recursive: true, force: true }); }
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
async load(reference: string): Promise<SessionSkill> {
|
|
131
|
+
const match = /^library:([^@]+)@([^@]+)$/.exec(reference);
|
|
132
|
+
if (!match || !namePattern.test(match[1]) || !validPart(match[1]) || !revisionPattern.test(match[2])) throw new Error('Use library:NAME@FULL_SHA256_REVISION from diagnose skills list');
|
|
133
|
+
const directory = join(this.root, match[1], match[2]);
|
|
134
|
+
if (digest(await readBundle(directory)) !== match[2]) throw new Error('Stored skill failed integrity verification; import a clean copy');
|
|
135
|
+
return { ...await loadSkill(directory), libraryReference: reference };
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
async list(): Promise<string[]> {
|
|
139
|
+
let names: string[];
|
|
140
|
+
try { names = await readdir(this.root); } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []; throw error; }
|
|
141
|
+
const references: string[] = [];
|
|
142
|
+
for (const name of names.sort()) {
|
|
143
|
+
if (!namePattern.test(name) || !(await lstat(join(this.root, name))).isDirectory()) continue;
|
|
144
|
+
for (const revision of (await readdir(join(this.root, name))).sort()) {
|
|
145
|
+
if (revisionPattern.test(revision)) references.push(`library:${name}@${revision}`);
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
return references;
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
export async function resolveSkill(input: string): Promise<SessionSkill> {
|
|
153
|
+
return input.startsWith('library:') ? new SkillLibrary().load(input) : loadSkill(input);
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
export async function skillsCommand(args: string[]): Promise<void> {
|
|
157
|
+
const library = new SkillLibrary();
|
|
158
|
+
if (args[0] === 'import' && args.length === 3) { console.log(await library.import(args[1], args[2])); return; }
|
|
159
|
+
if (args[0] === 'list' && args.length === 1) { console.log(JSON.stringify(await library.list(), null, 2)); return; }
|
|
160
|
+
if (args.length && !['--help', 'help'].includes(args[0])) throw new Error(skillsUsage);
|
|
161
|
+
console.log(skillsUsage);
|
|
162
|
+
}
|
package/src/skill.ts
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { open, realpath, stat } from 'node:fs/promises';
|
|
2
|
+
import { dirname, extname, join, resolve } from 'node:path';
|
|
3
|
+
import { isUtf8 } from 'node:buffer';
|
|
4
|
+
import { createHash } from 'node:crypto';
|
|
5
|
+
|
|
6
|
+
export type SessionSkill = { sourceFile: string; baseDirectory: string; sha256: string; instructions: string; libraryReference?: string };
|
|
7
|
+
const MAX_SKILL = 256 * 1024;
|
|
8
|
+
|
|
9
|
+
export async function loadSkill(input: string): Promise<SessionSkill> {
|
|
10
|
+
if (!input.trim()) throw new Error('--skill requires a non-empty path');
|
|
11
|
+
let path = resolve(input);
|
|
12
|
+
if ((await stat(path)).isDirectory()) path = join(path, 'SKILL.md');
|
|
13
|
+
if (!['.md', '.markdown'].includes(extname(path).toLowerCase())) throw new Error('--skill requires a Markdown file or a directory containing SKILL.md');
|
|
14
|
+
const sourceFile = await realpath(path);
|
|
15
|
+
if (!(await stat(sourceFile)).isFile()) throw new Error('Skill must be a regular file');
|
|
16
|
+
const file = await open(sourceFile, 'r');
|
|
17
|
+
try {
|
|
18
|
+
const info = await file.stat();
|
|
19
|
+
if (!info.isFile()) throw new Error('Skill must be a regular file');
|
|
20
|
+
if (info.size > MAX_SKILL) throw new Error('Skill exceeds 256 KiB');
|
|
21
|
+
const buffer = Buffer.alloc(MAX_SKILL + 1); let length = 0;
|
|
22
|
+
while (length < buffer.length) { const { bytesRead } = await file.read(buffer, length, buffer.length - length, length); if (!bytesRead) break; length += bytesRead; }
|
|
23
|
+
if (length > MAX_SKILL) throw new Error('Skill exceeds 256 KiB');
|
|
24
|
+
const bytes = buffer.subarray(0, length);
|
|
25
|
+
if (!isUtf8(bytes)) throw new Error('Skill must contain UTF-8 Markdown');
|
|
26
|
+
const instructions = bytes.toString('utf8').replace(/^\uFEFF/, '');
|
|
27
|
+
if (!instructions.trim()) throw new Error('Skill is empty');
|
|
28
|
+
return { sourceFile, baseDirectory: dirname(sourceFile), sha256: createHash('sha256').update(bytes).digest('hex'), instructions };
|
|
29
|
+
} finally { await file.close(); }
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export function skillPrompt(snapshot: string): string {
|
|
33
|
+
return [
|
|
34
|
+
'Start the remote troubleshooting task selected by the diagnostician now.',
|
|
35
|
+
`Task snapshot path (JSON): ${JSON.stringify(snapshot)}`,
|
|
36
|
+
'First read this local UTF-8 JSON file using your local file-reading tools. Follow its instructions field as the task for this session; do not merely summarize it or wait for the task to be repeated.',
|
|
37
|
+
'Resolve relative references and scripts against baseDirectory in the snapshot. It is a Markdown task or skill entry, not a globally installed agent skill. Read referenced material only as needed. Bundled scripts are task resources, not startup hooks; run them only as required by the task and existing permissions.',
|
|
38
|
+
'Referenced files and scripts are initially on the diagnostician computer. For a remote script, explicitly submit its contents or transfer it with authorization; do not assume the same path exists remotely.',
|
|
39
|
+
'Use diagnose_* MCP tools for actions on the remote user computer. Your ordinary shell and file tools operate on the diagnostician computer; do not confuse the two.',
|
|
40
|
+
'Use diagnose_capabilities to inspect argument schemas. Use diagnose_case status/show to find an existing case. If none exists, create one for the actual external target and goal before remote tasks; if the snapshot has libraryReference, record it as the case skill. Confirm target identity and interface before repairs. Keep before/after evidence IDs and finish the case with a supported outcome. If reusable knowledge emerged, propose diagnose_skill_draft for human review; never run draft acceptance or vault upload on the diagnostician behalf.',
|
|
41
|
+
'If a pairing code, target identity, or necessary detail is missing, ask the diagnostician for it, then continue. Keep pairing codes and credentials out of command arguments and reports.',
|
|
42
|
+
'Pair and obtain the remote user approval before remote actions. Respect the existing user and agent permission modes; this task does not grant permissions or authorize bypassing them.',
|
|
43
|
+
'Investigate, explain the proposed repair and its impact, apply only authorized changes, repeat the original failing check, and report evidence, changes, and remaining issues. Do not claim success without verification.'
|
|
44
|
+
].join('\n');
|
|
45
|
+
}
|
package/src/transfers.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { open, stat, rename, writeFile, readFile, unlink } from 'node:fs/promises';
|
|
1
|
+
import { open, stat, lstat, rename, writeFile, readFile, unlink, link, chmod } from 'node:fs/promises';
|
|
2
2
|
import { createHash } from 'node:crypto';
|
|
3
3
|
import { resolve } from 'node:path';
|
|
4
4
|
import type { Operator } from './operator.js';
|
|
@@ -6,6 +6,10 @@ export type TransferProgress = { state: string; bytes: number; size: number; res
|
|
|
6
6
|
export type TransferOptions = { resumeId?: string; resumeToken?: string; overwrite?: boolean; signal?: AbortSignal; progress?: (progress: TransferProgress) => void };
|
|
7
7
|
type Descriptor = { id: string; resumeToken?: string; size: number; sha256: string; offset: number };
|
|
8
8
|
async function hash(path: string): Promise<string> { const file = await open(path, 'r'); try { const value = createHash('sha256'); for await (const bytes of file.createReadStream({ autoClose: false })) value.update(bytes); return value.digest('hex'); } finally { await file.close(); } }
|
|
9
|
+
async function snapshot(path: string): Promise<{ sha256: string; mode: number } | null> {
|
|
10
|
+
try { const info = await lstat(path); if (!info.isFile() || info.isSymbolicLink()) throw new Error('Local target must be a regular non-symlink file'); return { sha256: await hash(path), mode: info.mode & 0o777 }; }
|
|
11
|
+
catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null; throw error; }
|
|
12
|
+
}
|
|
9
13
|
async function grant(operator: Operator, input: Parameters<Operator['run']>[0], options: TransferOptions): Promise<Descriptor> {
|
|
10
14
|
options.signal?.throwIfAborted(); const id = await operator.start(options.resumeId ? { operation: 'resource.resume', arguments: { id: options.resumeId, resumeToken: options.resumeToken }, reason: input.reason } : input);
|
|
11
15
|
const abort = () => { void operator.cancel(id).catch(() => {}); }; options.signal?.addEventListener('abort', abort, { once: true });
|
|
@@ -26,7 +30,8 @@ export async function upload(operator: Operator, localPath: string, remotePath:
|
|
|
26
30
|
}
|
|
27
31
|
export async function download(operator: Operator, remotePath: string, localPath: string, reason: string, options: TransferOptions = {}): Promise<TransferProgress> {
|
|
28
32
|
const destination = resolve(localPath), partial = destination + '.diagnose.part', sidecar = destination + '.diagnose.json';
|
|
29
|
-
|
|
33
|
+
const before = await snapshot(destination);
|
|
34
|
+
if (before && !options.overwrite) throw new Error('Local target exists; explicit overwrite is required');
|
|
30
35
|
let saved: { resourceId: string; resumeToken: string; sha256: string } | undefined;
|
|
31
36
|
try { saved = JSON.parse(await readFile(sidecar, 'utf8')); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
|
|
32
37
|
const effective = options.resumeId ? options : saved ? { ...options, resumeId: saved.resourceId, resumeToken: saved.resumeToken } : options;
|
|
@@ -44,5 +49,11 @@ export async function download(operator: Operator, remotePath: string, localPath
|
|
|
44
49
|
await file.sync();
|
|
45
50
|
} finally { await file.close(); }
|
|
46
51
|
if (progress.bytes !== resource.size || await hash(partial) !== resource.sha256) throw new Error('Download integrity mismatch; destination untouched');
|
|
47
|
-
options.signal?.throwIfAborted();
|
|
52
|
+
options.signal?.throwIfAborted();
|
|
53
|
+
if (before === null) { await link(partial, destination); await unlink(partial); }
|
|
54
|
+
else {
|
|
55
|
+
if (JSON.stringify(await snapshot(destination)) !== JSON.stringify(before)) throw new Error('Local destination changed during download; destination untouched');
|
|
56
|
+
await chmod(partial, before.mode); options.signal?.throwIfAborted(); await rename(partial, destination);
|
|
57
|
+
}
|
|
58
|
+
await unlink(sidecar); await operator.resource({ id: resource.id, action: 'close' }); progress.state = 'completed'; options.progress?.({ ...progress }); return progress;
|
|
48
59
|
}
|
package/src/util.ts
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
|
-
import { createHash } from 'node:crypto';
|
|
2
|
-
import { appendFileSync, mkdirSync, openSync, closeSync, realpathSync } from 'node:fs';
|
|
1
|
+
import { createHash, randomUUID } from 'node:crypto';
|
|
2
|
+
import { appendFileSync, mkdirSync, openSync, closeSync, realpathSync, statSync, renameSync } from 'node:fs';
|
|
3
3
|
import { dirname, resolve, relative, isAbsolute } from 'node:path';
|
|
4
4
|
import os from 'node:os';
|
|
5
|
+
import { History } from './history.js';
|
|
6
|
+
import { cleanupAudit } from './maintenance.js';
|
|
5
7
|
|
|
6
8
|
export function safeText(text: string): string {
|
|
7
9
|
return text.replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, '').replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '');
|
|
@@ -9,6 +11,7 @@ export function safeText(text: string): string {
|
|
|
9
11
|
export function redact(text: string): string {
|
|
10
12
|
return safeText(text)
|
|
11
13
|
.replace(/("?(?:password|passwd|pswd|secret|token|session|authorization|api[_-]?key)"?\s*[:=]\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s,}\r\n]+)/gi, '$1[REDACTED]')
|
|
14
|
+
.replace(/\b[a-z]{3}-[a-z]{3}-[a-z]{3}\b/gi, '[INVITATION CODE]')
|
|
12
15
|
.replace(/\bD1\.[A-Za-z0-9_-]{16}\.[A-Za-z0-9_-]{43}\b/g, '[PAIRING CODE]')
|
|
13
16
|
.replace(/\b[a-f0-9]{32,}\b/gi, '[REDACTED]')
|
|
14
17
|
.replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?-----END [^-]*PRIVATE KEY-----/g, '[PRIVATE KEY]');
|
|
@@ -26,14 +29,23 @@ export function inside(root: string, path: string): boolean {
|
|
|
26
29
|
|
|
27
30
|
export class Audit {
|
|
28
31
|
readonly path: string;
|
|
29
|
-
|
|
32
|
+
readonly history: History;
|
|
33
|
+
constructor(path = resolve(os.homedir(), '.diagnose', `audit-${Date.now()}-pid${process.pid}-${randomUUID()}.jsonl`)) {
|
|
30
34
|
this.path = path;
|
|
31
35
|
mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
|
|
32
36
|
const fd = openSync(path, 'ax', 0o600); closeSync(fd);
|
|
37
|
+
this.history = new History(resolve(dirname(path), 'history'));
|
|
38
|
+
cleanupAudit(dirname(path), undefined, path);
|
|
33
39
|
this.record('session.created', {});
|
|
34
40
|
}
|
|
35
41
|
record(event: string, details: Record<string, unknown>): void {
|
|
36
42
|
// No command text, payload, credentials, or file contents are persisted by default.
|
|
43
|
+
if (statSync(this.path).size > 8 * 1024 * 1024) {
|
|
44
|
+
renameSync(this.path, this.path.replace(/\.jsonl$/, '') + `-closed-${randomUUID()}.jsonl`);
|
|
45
|
+
const fd = openSync(this.path, 'ax', 0o600); closeSync(fd);
|
|
46
|
+
cleanupAudit(dirname(this.path), undefined, this.path);
|
|
47
|
+
}
|
|
37
48
|
appendFileSync(this.path, JSON.stringify({ at: new Date().toISOString(), event, ...details }) + '\n', { mode: 0o600, flush: true });
|
|
49
|
+
if (typeof details.id === 'string') this.history.event(details.id, event, details);
|
|
38
50
|
}
|
|
39
51
|
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { createHash, createHmac, hkdfSync, randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
|
|
2
|
+
export const MAX_VAULT_OBJECT = 12 * 1024 * 1024;
|
|
3
|
+
export function newRecovery(): string { return 'K1.' + randomBytes(32).toString('base64url'); }
|
|
4
|
+
export function vaultKeys(recovery: string) {
|
|
5
|
+
if (!/^K1\.[A-Za-z0-9_-]{43}$/.test(recovery)) throw new Error('Invalid library recovery key');
|
|
6
|
+
const root = Buffer.from(recovery.slice(3), 'base64url');
|
|
7
|
+
if (root.toString('base64url') !== recovery.slice(3)) throw new Error('Noncanonical recovery key');
|
|
8
|
+
const derive = (purpose: string) => Buffer.from(hkdfSync('sha256', root, 'diagnose-library-v1', purpose, 32));
|
|
9
|
+
const auth = derive('authentication').toString('base64url');
|
|
10
|
+
return { auth, namespace: createHash('sha256').update(auth).digest('hex'), encryption: derive('encryption'), index: derive('object-names') };
|
|
11
|
+
}
|
|
12
|
+
export function objectId(recovery: string, reference: string): string { return createHmac('sha256', vaultKeys(recovery).index).update(reference).digest('hex'); }
|
|
13
|
+
export function sealBundle(recovery: string, id: string, bytes: Buffer): Buffer {
|
|
14
|
+
const keys = vaultKeys(recovery), nonce = randomBytes(12), cipher = createCipheriv('aes-256-gcm', keys.encryption, nonce);
|
|
15
|
+
cipher.setAAD(Buffer.from(`diagnose-library-v1:${keys.namespace}:${id}`));
|
|
16
|
+
const sealed = Buffer.concat([Buffer.from([1]), nonce, cipher.update(bytes), cipher.final(), cipher.getAuthTag()]);
|
|
17
|
+
if (sealed.length > MAX_VAULT_OBJECT) throw new Error('Encrypted bundle exceeds 12 MiB');
|
|
18
|
+
return sealed;
|
|
19
|
+
}
|
|
20
|
+
export function openBundle(recovery: string, id: string, sealed: Buffer): Buffer {
|
|
21
|
+
if (sealed.length < 29 || sealed.length > MAX_VAULT_OBJECT || sealed[0] !== 1) throw new Error('Invalid encrypted library object');
|
|
22
|
+
const keys = vaultKeys(recovery), decipher = createDecipheriv('aes-256-gcm', keys.encryption, sealed.subarray(1, 13));
|
|
23
|
+
decipher.setAAD(Buffer.from(`diagnose-library-v1:${keys.namespace}:${id}`)); decipher.setAuthTag(sealed.subarray(-16));
|
|
24
|
+
return Buffer.concat([decipher.update(sealed.subarray(13, -16)), decipher.final()]);
|
|
25
|
+
}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import type { IncomingMessage, ServerResponse } from 'node:http';
|
|
2
|
+
import { createHash, randomUUID } from 'node:crypto';
|
|
3
|
+
import { mkdirSync, readdirSync, statSync, existsSync, readFileSync, writeFileSync, renameSync, rmSync, unlinkSync } from 'node:fs';
|
|
4
|
+
import { join } from 'node:path';
|
|
5
|
+
import { MAX_VAULT_OBJECT } from './vault-crypto.js';
|
|
6
|
+
|
|
7
|
+
// Opaque capability-authenticated immutable objects. No encryption key reaches
|
|
8
|
+
// this module. One relay process owns the store; do not use PM2 cluster mode.
|
|
9
|
+
export class VaultServer {
|
|
10
|
+
private activeUploads = 0;
|
|
11
|
+
private requests = new Map<string, { since: number; count: number }>();
|
|
12
|
+
constructor(readonly root: string, readonly maxTotalBytes = 1024 ** 3) {
|
|
13
|
+
mkdirSync(root, { recursive: true, mode: 0o700 });
|
|
14
|
+
// No interrupted request is published: abandoned staging files are disposable.
|
|
15
|
+
for (const name of readdirSync(root)) if (/^[a-f0-9]{64}$/.test(name)) for (const file of readdirSync(join(root, name))) if (file.startsWith('.upload-')) rmSync(join(root, name, file), { force: true });
|
|
16
|
+
}
|
|
17
|
+
private inventory(directory: string): { id: string; bytes: number }[] {
|
|
18
|
+
if (!existsSync(directory)) return [];
|
|
19
|
+
return readdirSync(directory).filter(name => /^[a-f0-9]{64}$/.test(name)).map(id => ({ id, bytes: statSync(join(directory, id)).size }));
|
|
20
|
+
}
|
|
21
|
+
async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
|
|
22
|
+
const send = (status: number, value: unknown) => { res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }); res.end(JSON.stringify(value)); };
|
|
23
|
+
try {
|
|
24
|
+
const direct = req.socket.remoteAddress ?? 'unknown';
|
|
25
|
+
const ip = ['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(direct) ? String(req.headers['x-forwarded-for'] ?? direct).split(',')[0].trim() : direct;
|
|
26
|
+
for (const [key, rate] of this.requests) if (Date.now() - rate.since > 60000) this.requests.delete(key);
|
|
27
|
+
if (!this.requests.has(ip) && this.requests.size >= 10000) { send(429, { error: 'Rate limit' }); return; }
|
|
28
|
+
const rate = this.requests.get(ip) ?? { since: Date.now(), count: 0 }; this.requests.set(ip, rate);
|
|
29
|
+
if (++rate.count > 600) { send(429, { error: 'Rate limit' }); return; }
|
|
30
|
+
const auth = /^Bearer ([A-Za-z0-9_-]{43})$/.exec(req.headers.authorization ?? '');
|
|
31
|
+
if (!auth) { send(401, { error: 'Library capability required' }); return; }
|
|
32
|
+
const namespace = createHash('sha256').update(auth[1]).digest('hex'), directory = join(this.root, namespace);
|
|
33
|
+
if (existsSync(join(this.root, namespace + '.revoked'))) { send(403, { error: 'Library revoked' }); return; }
|
|
34
|
+
const match = /^\/v1\/library(?:\/([a-f0-9]{64}))?$/.exec(req.url ?? '');
|
|
35
|
+
if (!match) { send(404, { error: 'Not found' }); return; }
|
|
36
|
+
const id = match[1];
|
|
37
|
+
if (req.method === 'GET') {
|
|
38
|
+
if (!id) { send(200, { objects: this.inventory(directory) }); return; }
|
|
39
|
+
const path = join(directory, id);
|
|
40
|
+
if (!existsSync(path)) { send(404, { error: 'Not found' }); return; }
|
|
41
|
+
const bytes = readFileSync(path); res.writeHead(200, { 'Content-Type': 'application/octet-stream', 'Content-Length': bytes.length }); res.end(bytes); return;
|
|
42
|
+
}
|
|
43
|
+
if (req.method === 'DELETE' && !id) {
|
|
44
|
+
if (!existsSync(directory)) { send(404, { error: 'Library not found' }); return; }
|
|
45
|
+
writeFileSync(join(this.root, namespace + '.revoked'), '', { mode: 0o600, flush: true }); rmSync(directory, { recursive: true, force: true }); send(200, { revoked: true }); return;
|
|
46
|
+
}
|
|
47
|
+
if (req.method !== 'PUT' || !id) { send(405, { error: 'Use GET, PUT object or DELETE library' }); return; }
|
|
48
|
+
const length = Number(req.headers['content-length']);
|
|
49
|
+
if (!Number.isInteger(length) || length < 29 || length > MAX_VAULT_OBJECT) { send(413, { error: 'Content-Length required, 29 bytes..12 MiB' }); return; }
|
|
50
|
+
if (this.activeUploads >= 2) { send(429, { error: 'Upload capacity reached' }); return; }
|
|
51
|
+
if (existsSync(join(directory, id))) { send(409, { error: 'Immutable object already exists' }); return; }
|
|
52
|
+
this.activeUploads++;
|
|
53
|
+
const deadline = setTimeout(() => req.destroy(), 30000);
|
|
54
|
+
try {
|
|
55
|
+
const chunks: Buffer[] = []; let size = 0;
|
|
56
|
+
for await (const chunk of req) { size += chunk.length; if (size > length) throw new Error('Size mismatch'); chunks.push(Buffer.from(chunk)); }
|
|
57
|
+
if (size !== length) throw new Error('Incomplete upload');
|
|
58
|
+
// Commit checks are synchronous so concurrent requests cannot overrun quota.
|
|
59
|
+
if (existsSync(join(this.root, namespace + '.revoked'))) { send(403, { error: 'Library revoked' }); return; }
|
|
60
|
+
const own = this.inventory(directory), names = readdirSync(this.root).filter(name => /^[a-f0-9]{64}(?:\.revoked)?$/.test(name));
|
|
61
|
+
const total = names.filter(name => !name.endsWith('.revoked')).reduce((sum, name) => sum + this.inventory(join(this.root, name)).reduce((n, item) => n + item.bytes, 0), 0);
|
|
62
|
+
if (own.length >= 128 || own.reduce((n, item) => n + item.bytes, 0) + size > 128 * 1024 ** 2 || total + size > this.maxTotalBytes || (!existsSync(directory) && names.length >= 1000)) { send(507, { error: 'Library storage quota reached' }); return; }
|
|
63
|
+
mkdirSync(directory, { recursive: true, mode: 0o700 });
|
|
64
|
+
if (existsSync(join(directory, id))) { send(409, { error: 'Immutable object already exists' }); return; }
|
|
65
|
+
const path = join(directory, '.upload-' + randomUUID());
|
|
66
|
+
try { writeFileSync(path, Buffer.concat(chunks), { flag: 'wx', mode: 0o600, flush: true }); renameSync(path, join(directory, id)); }
|
|
67
|
+
finally { if (existsSync(path)) unlinkSync(path); }
|
|
68
|
+
send(201, { stored: true });
|
|
69
|
+
} finally { clearTimeout(deadline); this.activeUploads--; }
|
|
70
|
+
} catch { if (!res.headersSent && !res.destroyed) send(400, { error: 'Library request failed' }); else res.destroy(); }
|
|
71
|
+
}
|
|
72
|
+
}
|