@deepseek-ai/dsh-ssh 0.1.6-alpha.1

package/lib/index.js

@@ -0,0 +1,359 @@
+import { a as SshRpcPeer } from "./protocol-C43fD--H.js";
+import { s as helloSchema } from "./schemas-DBIgsx0q.js";
+import { n as authenticateStream } from "./stream-security-DJlQsPG-.js";
+import { execFile, spawn } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { createConnection } from "node:net";
+import { Service } from "@deepseek-ai/cordis";
+import schema from "@deepseek-ai/schemastery";
+import { z } from "zod";
+//#region lib/types/index.js
+/** OpenSSH connection owner for one version-matched POSIX helper and its independent forwarded streams. */
+/** One non-reconnecting SSH session; loss invalidates all active operations. */
+var SshConnection = class extends Service {
+	static Config = schema.object({
+		host: schema.string().required(),
+		node: schema.string().required(),
+		helper: schema.string().required(),
+		helperHash: schema.string().required(),
+		workspace: schema.string().required(),
+		bootstrapPath: schema.string(),
+		bootstrapHash: schema.string(),
+		requestTimeoutMs: schema.number().default(3e4),
+		maxFrameBytes: schema.number().default(64 * 1024 * 1024),
+		maxPending: schema.number().default(128),
+		leaseMs: schema.number().default(3e4)
+	});
+	/** Verified remote helper coordinates; callers must await this before launch. */
+	ready;
+	rpc;
+	child;
+	childClosed;
+	directory;
+	heartbeat;
+	closed = false;
+	lifetime = new AbortController();
+	operations = /* @__PURE__ */ new Set();
+	disposal;
+	failure;
+	sockets = /* @__PURE__ */ new Set();
+	nextSocket = 0;
+	config;
+	remote;
+	constructor(ctx, config) {
+		super(ctx, "ssh");
+		if (process.platform !== "linux" && process.platform !== "darwin") throw new Error("SSH runtime requires a POSIX client");
+		this.config = z.object({
+			host: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_.@-]*$/),
+			node: z.string().startsWith("/"),
+			helper: z.string().startsWith("/"),
+			helperHash: z.string().regex(/^[0-9a-f]{64}$/),
+			workspace: z.string().startsWith("/"),
+			requestTimeoutMs: z.number().int().positive().max(2147483647),
+			bootstrapPath: z.string().startsWith("/").optional(),
+			bootstrapHash: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+			maxFrameBytes: z.number().int().positive().max(64 * 1024 * 1024),
+			maxPending: z.number().int().positive().max(128),
+			leaseMs: z.number().int().min(3e3).max(6e5)
+		}).refine((value) => value.bootstrapPath === void 0 === (value.bootstrapHash === void 0), "bootstrapPath and bootstrapHash must be paired").parse(config);
+		this.ready = this.start();
+		this.ready.catch((error) => {
+			this.fail(error);
+		});
+		ctx.effect(() => () => this.dispose());
+	}
+	/** Hold plugin readiness until the remote identity and helper digest are verified. */
+	async [Service.init]() {
+		await this.ready;
+	}
+	/** Verified remote Node executable for the paired PTC runtime. */
+	get nodeExecutable() {
+		if (this.remote === void 0) throw new Error("SSH helper is not ready");
+		return this.remote.node;
+	}
+	/** Verified preinstalled PTC entry; unconfigured runtimes fail before program execution. */
+	get bootstrapPath() {
+		if (this.remote === void 0 || this.config.bootstrapPath === void 0) throw new Error("SSH PTC requires a verified bootstrapPath and bootstrapHash");
+		return this.config.bootstrapPath;
+	}
+	/**
+	* Send a helper operation; cancellation never replays an ambiguous mutation.
+	* @param method - the private helper operation.
+	* @param params - JSON request fields validated by the helper.
+	* @param result - response validation before returning provider-visible data.
+	* @param signal - cancellation, which does not undo completed remote effects.
+	* @param wait - allow a process observation to outlast the administrative deadline.
+	* @returns the validated remote result.
+	*/
+	async request(method, params, result, signal, wait = false) {
+		this.assertOpen();
+		await this.ready;
+		this.assertOpen();
+		const bounded = wait ? signal : signal === void 0 ? AbortSignal.timeout(this.config.requestTimeoutMs) : AbortSignal.any([signal, AbortSignal.timeout(this.config.requestTimeoutMs)]);
+		return this.rpc.request(method, params, result, bounded);
+	}
+	/**
+	* Forward one authenticated stream through an independent SSH channel.
+	* @param endpoint - private coordinates issued by this connection's helper.
+	* @param signal - cancellation of allocation and the resulting socket.
+	* @returns a paused socket; attach a consumer before resuming it.
+	*/
+	async connectStream(endpoint, signal) {
+		return this.track(this.establishStream(endpoint, signal));
+	}
+	async establishStream(endpoint, signal) {
+		const hello = await this.ready;
+		this.assertOpen();
+		signal = signal === void 0 ? this.lifetime.signal : AbortSignal.any([signal, this.lifetime.signal]);
+		const remote = endpoint.path;
+		if (!remote.startsWith(`${hello.root}/`) || /[:\r\n\0]/u.test(remote)) throw new Error("SSH helper returned an invalid stream path");
+		signal.throwIfAborted();
+		const local = join(this.directory, `s${this.nextSocket++}`);
+		const forward = `${local}:${remote}`;
+		const cancelForward = async () => {
+			if (!this.closed) await this.controlCommand([
+				"-O",
+				"cancel",
+				"-L",
+				forward
+			]).catch(() => {});
+			await rm(local, { force: true });
+		};
+		try {
+			await this.controlCommand([
+				"-O",
+				"forward",
+				"-o",
+				"ExitOnForwardFailure=yes",
+				"-L",
+				forward
+			], signal);
+		} catch (error) {
+			await cancelForward();
+			throw error;
+		}
+		signal.throwIfAborted();
+		const socket = createConnection({
+			path: local,
+			allowHalfOpen: true
+		});
+		this.sockets.add(socket);
+		socket.once("close", () => {
+			this.sockets.delete(socket);
+			this.track(cancelForward()).catch(() => {});
+		});
+		await new Promise((resolve, reject) => {
+			const cleanup = () => {
+				signal.removeEventListener("abort", aborted);
+				socket.off("connect", connected);
+				socket.off("error", failed);
+				socket.off("close", closed);
+			};
+			const connected = () => {
+				cleanup();
+				resolve();
+			};
+			const failed = (error) => {
+				cleanup();
+				reject(error);
+			};
+			const closed = () => {
+				failed(/* @__PURE__ */ new Error("SSH connection closed before stream establishment"));
+			};
+			const aborted = () => {
+				socket.destroy(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)));
+			};
+			socket.once("connect", connected);
+			socket.once("error", failed);
+			socket.once("close", closed);
+			signal.addEventListener("abort", aborted, { once: true });
+		});
+		const authenticated = await authenticateStream(socket, endpoint.capability, this.config.requestTimeoutMs, signal);
+		this.sockets.add(authenticated);
+		authenticated.on("error", () => {
+			authenticated.destroy();
+		});
+		authenticated.once("close", () => {
+			this.sockets.delete(authenticated);
+		});
+		return authenticated;
+	}
+	/** Tear down the helper's remote managed ranges before releasing the SSH master when reachable. */
+	dispose() {
+		this.disposal ??= this.disposeOnce();
+		return this.disposal;
+	}
+	async disposeOnce() {
+		this.closed = true;
+		this.lifetime.abort(/* @__PURE__ */ new Error("SSH connection is closing"));
+		if (this.heartbeat !== void 0) clearInterval(this.heartbeat);
+		try {
+			await this.ready.catch(() => {});
+			if (this.failure === void 0) await this.rpc?.request("close", {}, z.null(), AbortSignal.timeout(this.config.requestTimeoutMs));
+		} finally {
+			this.rpc?.close();
+			const socketClosures = [...this.sockets].reverse().map((socket) => new Promise((resolve) => {
+				if (socket.closed) resolve();
+				else {
+					socket.once("close", () => {
+						resolve();
+					});
+					socket.destroy();
+				}
+			}));
+			this.child?.kill("SIGTERM");
+			const force = setTimeout(() => {
+				this.child?.kill("SIGKILL");
+			}, this.config.requestTimeoutMs);
+			try {
+				await this.childClosed;
+			} finally {
+				clearTimeout(force);
+			}
+			await Promise.all(socketClosures);
+			while (this.operations.size > 0) await Promise.allSettled([...this.operations]);
+			if (this.directory !== void 0) await rm(this.directory, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+	controlPath() {
+		return join(this.directory, "master");
+	}
+	assertOpen() {
+		if (this.closed) throw new Error("SSH connection is closed");
+		if (this.failure !== void 0) throw this.failure;
+	}
+	track(operation) {
+		this.operations.add(operation);
+		operation.finally(() => {
+			this.operations.delete(operation);
+		}).catch(() => {});
+		return operation;
+	}
+	async controlCommand(args, signal) {
+		const signals = [this.lifetime.signal, AbortSignal.timeout(this.config.requestTimeoutMs)];
+		if (signal !== void 0) signals.push(signal);
+		const combined = AbortSignal.any(signals);
+		combined.throwIfAborted();
+		const result = Promise.withResolvers();
+		const command = execFile("ssh", [
+			"-S",
+			this.controlPath(),
+			...args,
+			this.config.host
+		], {
+			signal: combined,
+			maxBuffer: 64 * 1024
+		}, (error) => {
+			if (error === null) result.resolve(void 0);
+			else result.reject(error);
+		});
+		const closed = new Promise((resolve) => {
+			command.once("close", () => {
+				resolve();
+			});
+		});
+		let force;
+		const escalate = () => {
+			force = setTimeout(() => {
+				command.kill("SIGKILL");
+			}, this.config.requestTimeoutMs);
+			force.unref();
+		};
+		combined.addEventListener("abort", escalate, { once: true });
+		try {
+			await result.promise;
+		} finally {
+			await closed;
+			combined.removeEventListener("abort", escalate);
+			if (force !== void 0) clearTimeout(force);
+		}
+	}
+	fail(error) {
+		if (this.failure !== void 0) return;
+		this.failure = error;
+		this.lifetime.abort(error);
+		if (this.heartbeat !== void 0) clearInterval(this.heartbeat);
+		this.rpc?.close(error);
+		for (const socket of [...this.sockets].reverse()) socket.destroy(error);
+		this.child?.kill("SIGTERM");
+	}
+	async start() {
+		this.directory = await mkdtemp("/tmp/dsh-ssh-");
+		if (this.closed) throw new Error("SSH connection closed before startup");
+		const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+		const command = [
+			this.config.node,
+			"--disable-sigusr1",
+			this.config.helper
+		].map(quote).join(" ");
+		const child = spawn("ssh", [
+			"-T",
+			"-M",
+			"-S",
+			this.controlPath(),
+			"-o",
+			"ControlPersist=no",
+			"-o",
+			"BatchMode=yes",
+			"-o",
+			"StrictHostKeyChecking=yes",
+			"-o",
+			"ForwardAgent=no",
+			"-o",
+			"ClearAllForwardings=yes",
+			"-o",
+			"ServerAliveInterval=10",
+			"-o",
+			"ServerAliveCountMax=3",
+			this.config.host,
+			command
+		], { stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		] });
+		this.child = child;
+		this.childClosed = new Promise((resolve) => {
+			child.once("close", () => {
+				resolve();
+			});
+		});
+		child.stderr.resume();
+		child.once("error", (error) => {
+			this.fail(error);
+		});
+		child.once("close", () => {
+			this.fail(/* @__PURE__ */ new Error("SSH helper disconnected; remote outcomes and cleanup are unknown"));
+		});
+		const rpc = new SshRpcPeer(child.stdout, child.stdin, this.config.maxFrameBytes, this.config.maxPending);
+		this.rpc = rpc;
+		rpc.once("closed", (error) => {
+			this.fail(error);
+		});
+		const hello = await rpc.request("hello", {
+			protocol: 1,
+			workspace: this.config.workspace,
+			leaseMs: this.config.leaseMs,
+			...this.config.bootstrapPath === void 0 ? {} : { bootstrapPath: this.config.bootstrapPath }
+		}, helloSchema, AbortSignal.timeout(this.config.requestTimeoutMs));
+		if (hello.hash !== this.config.helperHash) throw new Error("SSH helper digest differs from the configured artifact");
+		if (hello.bootstrapHash !== this.config.bootstrapHash) throw new Error("SSH PTC bootstrap digest differs from the configured artifact");
+		this.remote = hello;
+		let heartbeatPending;
+		this.heartbeat = setInterval(() => {
+			heartbeatPending ??= rpc.request("heartbeat", {}, z.null(), AbortSignal.timeout(this.config.leaseMs / 2)).catch((error) => {
+				this.fail(error);
+			}).finally(() => {
+				heartbeatPending = void 0;
+			});
+		}, Math.floor(this.config.leaseMs / 3));
+		this.heartbeat.unref();
+		return hello;
+	}
+};
+//#endregion
+export { SshConnection, SshConnection as default };

package/lib/protocol-C43fD--H.js

@@ -0,0 +1,276 @@
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+//#region lib/types/protocol.js
+/** Bounded, versioned requests between an SSH client and its private remote helper. */
+/** Wire version shared by the installed helper and client package. */
+const SSH_PROTOCOL_VERSION = 1;
+/** Maximum prepared or running process handles owned by one helper. */
+const SSH_MAX_PROCESS_HANDLES = 128;
+/** Maximum open text iterators owned by one helper. */
+const SSH_MAX_TEXT_STREAMS = 128;
+const managementLimits = {
+	heartbeat: 1,
+	close: 1,
+	"process.terminate": 128,
+	"fs.streamClose": 128
+};
+function requestClass(method) {
+	switch (method) {
+		case "heartbeat":
+		case "close":
+		case "process.terminate":
+		case "fs.streamClose": return method;
+		default: return "ordinary";
+	}
+}
+const errorSchema = z.object({
+	name: z.string(),
+	message: z.string(),
+	code: z.string().optional()
+}).strict();
+const requestIdSchema = z.string().transform((value) => value);
+const frameSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("request"),
+		id: requestIdSchema,
+		method: z.string(),
+		params: z.unknown()
+	}).strict(),
+	z.object({
+		type: z.literal("result"),
+		id: requestIdSchema,
+		value: z.unknown()
+	}).strict(),
+	z.object({
+		type: z.literal("error"),
+		id: requestIdSchema,
+		error: errorSchema
+	}).strict(),
+	z.object({
+		type: z.literal("cancel"),
+		id: requestIdSchema
+	}).strict()
+]);
+function operationError(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+/** A remote error retains its typed filesystem or sandbox code. */
+var RemoteOperationError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "RemoteOperationError";
+	}
+};
+/** The peer owns pending calls and rejects ambiguous operations on connection loss; it never replays requests. */
+var SshRpcPeer = class extends EventEmitter {
+	input;
+	output;
+	maxFrameBytes;
+	maxPending;
+	handler;
+	pending = /* @__PURE__ */ new Map();
+	active = /* @__PURE__ */ new Map();
+	writeTail = Promise.resolve();
+	queuedBytes = 0;
+	failure;
+	constructor(input, output, maxFrameBytes, maxPending, handler) {
+		super();
+		this.input = input;
+		this.output = output;
+		this.maxFrameBytes = maxFrameBytes;
+		this.maxPending = maxPending;
+		this.handler = handler;
+		input.on("error", (error) => {
+			this.close(error);
+		});
+		output.on("error", (error) => {
+			this.close(error);
+		});
+		output.on("close", () => {
+			this.close();
+		});
+		this.readFrames().catch((error) => {
+			this.close(operationError(error));
+		});
+	}
+	/**
+	* Send one request and validate its response before exposing it to the caller.
+	* @param method - the private helper operation.
+	* @param params - JSON request fields.
+	* @param schema - validation for the remote response.
+	* @param signal - cancellation without rollback of remote effects.
+	* @returns the validated response or a transport/remote-operation rejection.
+	*/
+	async request(method, params, schema, signal) {
+		signal?.throwIfAborted();
+		if (this.failure !== void 0) throw this.failure;
+		const kind = requestClass(method);
+		if (this.atCapacity(kind, this.pending.values())) throw new Error("SSH helper pending request limit reached");
+		const id = randomUUID();
+		const result = Promise.withResolvers();
+		result.promise.catch(() => {});
+		this.pending.set(id, {
+			...result,
+			requestClass: kind
+		});
+		const abort = () => {
+			result.reject(/* @__PURE__ */ new Error("SSH operation cancelled; a completed remote mutation is not rolled back"));
+			this.send({
+				type: "cancel",
+				id
+			}).catch(() => {});
+		};
+		signal?.addEventListener("abort", abort, { once: true });
+		try {
+			this.send({
+				type: "request",
+				id,
+				method,
+				params
+			}).catch((error) => {
+				this.pending.delete(id);
+				result.reject(operationError(error));
+			});
+			return schema.parse(await result.promise);
+		} finally {
+			signal?.removeEventListener("abort", abort);
+		}
+	}
+	/**
+	* Fail pending operations and abort remote handlers without claiming rollback.
+	* @param error - the transport failure reported to all pending operations.
+	*/
+	close(error = /* @__PURE__ */ new Error("SSH connection lost; remote operation outcome and cleanup are unknown")) {
+		if (this.failure !== void 0) return;
+		this.failure = error;
+		for (const pending of this.pending.values()) pending.reject(error);
+		this.pending.clear();
+		for (const { controller } of this.active.values()) controller.abort(error);
+		this.active.clear();
+		this.input.destroy();
+		this.output.destroy();
+		this.emit("closed", error);
+	}
+	async send(frame) {
+		if (this.failure !== void 0) return Promise.reject(this.failure);
+		const body = Buffer.from(JSON.stringify(frame));
+		if (body.length > this.maxFrameBytes || this.queuedBytes + body.length + 4 > this.maxFrameBytes * 2) return Promise.reject(/* @__PURE__ */ new Error("SSH helper frame or write queue limit exceeded"));
+		const header = Buffer.alloc(4);
+		header.writeUInt32BE(body.length);
+		const bytes = Buffer.concat([header, body]);
+		this.queuedBytes += bytes.length;
+		const write = this.writeTail.then(async () => {
+			if (this.failure !== void 0) throw this.failure;
+			if (!this.output.write(bytes)) await new Promise((resolve, reject) => {
+				const cleanup = () => {
+					this.output.off("drain", drained);
+					this.off("closed", closed);
+				};
+				const drained = () => {
+					cleanup();
+					resolve();
+				};
+				const closed = (error) => {
+					cleanup();
+					reject(error);
+				};
+				this.output.once("drain", drained);
+				this.once("closed", closed);
+				if (this.failure !== void 0) closed(this.failure);
+			});
+		});
+		this.writeTail = write.catch((error) => {
+			this.close(operationError(error));
+		});
+		return write.finally(() => {
+			this.queuedBytes -= bytes.length;
+		});
+	}
+	async readFrames() {
+		const header = Buffer.alloc(4);
+		let headerBytes = 0;
+		let payload;
+		let payloadBytes = 0;
+		for await (const raw of this.input) {
+			const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+			let offset = 0;
+			while (offset < chunk.length) {
+				if (payload === void 0) {
+					const count = Math.min(4 - headerBytes, chunk.length - offset);
+					chunk.copy(header, headerBytes, offset, offset + count);
+					headerBytes += count;
+					offset += count;
+					if (headerBytes < 4) continue;
+					const size = header.readUInt32BE(0);
+					if (size === 0 || size > this.maxFrameBytes) throw new Error("SSH helper sent an invalid frame length");
+					payload = Buffer.alloc(size);
+					payloadBytes = 0;
+				}
+				const count = Math.min(payload.length - payloadBytes, chunk.length - offset);
+				chunk.copy(payload, payloadBytes, offset, offset + count);
+				payloadBytes += count;
+				offset += count;
+				if (payloadBytes === payload.length) {
+					const frame = frameSchema.parse(JSON.parse(payload.toString("utf8")));
+					payload = void 0;
+					headerBytes = 0;
+					this.receive(frame);
+				}
+			}
+		}
+		throw new Error(headerBytes > 0 || payload !== void 0 ? "SSH helper disconnected during a frame; outcome is unknown" : "SSH helper disconnected; outcome is unknown");
+	}
+	receive(frame) {
+		if (frame.type === "result" || frame.type === "error") {
+			const pending = this.pending.get(frame.id);
+			if (pending === void 0) return;
+			this.pending.delete(frame.id);
+			if (frame.type === "result") pending.resolve(frame.value);
+			else pending.reject(new RemoteOperationError(frame.error.message, frame.error.code));
+			return;
+		}
+		if (frame.type === "cancel") {
+			this.active.get(frame.id)?.controller.abort(/* @__PURE__ */ new Error("SSH caller cancelled the operation"));
+			return;
+		}
+		const kind = requestClass(frame.method);
+		if (this.handler === void 0 || this.active.has(frame.id) || this.atCapacity(kind, this.active.values())) throw new Error("SSH helper received an unexpected or excessive request");
+		const controller = new AbortController();
+		this.active.set(frame.id, {
+			controller,
+			requestClass: kind
+		});
+		this.handler(frame.method, frame.params, controller.signal).then((value) => this.send({
+			type: "result",
+			id: frame.id,
+			value: value ?? null
+		}), (error) => {
+			const detail = operationError(error);
+			const code = "code" in detail && typeof detail.code === "string" ? detail.code : void 0;
+			return this.send({
+				type: "error",
+				id: frame.id,
+				error: {
+					name: detail.name,
+					message: detail.message,
+					...code === void 0 ? {} : { code }
+				}
+			});
+		}).catch((error) => {
+			this.close(operationError(error));
+		}).finally(() => {
+			this.active.delete(frame.id);
+		});
+	}
+	atCapacity(kind, requests) {
+		const limit = kind === "ordinary" ? this.maxPending : managementLimits[kind];
+		let count = 0;
+		for (const request of requests) if (request.requestClass === kind) count++;
+		return count >= limit;
+	}
+};
+//#endregion
+export { SshRpcPeer as a, SSH_PROTOCOL_VERSION as i, SSH_MAX_PROCESS_HANDLES as n, SSH_MAX_TEXT_STREAMS as r, RemoteOperationError as t };

package/lib/protocol.js

@@ -0,0 +1,2 @@
+import { a as SshRpcPeer, i as SSH_PROTOCOL_VERSION, n as SSH_MAX_PROCESS_HANDLES, r as SSH_MAX_TEXT_STREAMS, t as RemoteOperationError } from "./protocol-C43fD--H.js";
+export { RemoteOperationError, SSH_MAX_PROCESS_HANDLES, SSH_MAX_TEXT_STREAMS, SSH_PROTOCOL_VERSION, SshRpcPeer };