@jabberwocky238/dsh-ssh 0.0.0-stage → 0.2.4

package/lib/index.js

@@ -0,0 +1,572 @@
+import { a as SshRpcPeer } from "./protocol-CDhW_IHU.js";
+import { s as helloSchema } from "./schemas-BD3YbDxe.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";
+import { assertNever } from "@deepseek-ai/dsh-util-values";
+//#region lib/types/index.js
+/** OpenSSH connection owner for version-matched POSIX helpers, one per login, and their independent forwarded streams. */
+/** Remote login names a bound Agent may run as. */
+const LOGIN = /^[a-z_][a-z0-9_-]{0,31}$/;
+/** Requests that address a handle an earlier request on the same helper created. */
+const HANDLE_METHODS = new Set([
+	"process.start",
+	"process.done",
+	"process.wait",
+	"process.terminate",
+	"terminal.resize",
+	"terminal.write",
+	"terminal.inspect",
+	"terminal.activity",
+	"terminal.signal",
+	"fs.next",
+	"fs.streamClose"
+]);
+/**
+* One non-reconnecting OpenSSH master and the helper behind it, as the alias's
+* own login or as a named login on the same alias.
+*/
+var SshChannel = class {
+	config;
+	login;
+	onFailure;
+	/** Verified remote helper coordinates; callers must await this before launch. */
+	ready;
+	/** Requests and forwarded sockets in flight, which keep an idle login channel open. */
+	active = 0;
+	rpc;
+	child;
+	childClosed;
+	directory;
+	heartbeat;
+	closed = false;
+	lifetime = new AbortController();
+	operations = /* @__PURE__ */ new Set();
+	disposal;
+	failure;
+	sockets = /* @__PURE__ */ new Set();
+	nextSocket = 0;
+	/** The helper's verified hello, once startup completes. */
+	remote;
+	/**
+	* @param config - validated connection configuration.
+	* @param login - remote login to authenticate as instead of the alias's own; undefined keeps the alias's.
+	* @param onFailure - observer of the channel's first failure.
+	*/
+	constructor(config, login, onFailure) {
+		this.config = config;
+		this.login = login;
+		this.onFailure = onFailure;
+		this.ready = this.start();
+		this.ready.catch((error) => {
+			this.fail(error);
+		});
+	}
+	/** Whether the channel failed or is closing, so it accepts no new work. */
+	get unusable() {
+		return this.closed || this.failure !== void 0;
+	}
+	async request(method, params, result, signal, wait = false) {
+		this.assertOpen();
+		this.active++;
+		try {
+			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 await this.rpc.request(method, params, result, bounded);
+		} finally {
+			this.active--;
+		}
+	}
+	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);
+		this.active++;
+		socket.once("close", () => {
+			this.sockets.delete(socket);
+			this.active--;
+			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;
+	}
+	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");
+	}
+	/** The destination arguments that name the remote login and alias. */
+	destination() {
+		return this.login === void 0 ? [this.config.host] : [
+			"-l",
+			this.login,
+			this.config.host
+		];
+	}
+	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.destination()
+		], {
+			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");
+		this.onFailure(error);
+	}
+	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 launch = this.config.launch;
+		let command;
+		let bootstrapPath;
+		let bootstrapHash;
+		switch (launch.kind) {
+			case "node-script":
+				command = [
+					launch.node,
+					"--disable-sigusr1",
+					this.config.helper
+				].map(quote).join(" ");
+				bootstrapPath = launch.bootstrapPath;
+				bootstrapHash = launch.bootstrapHash;
+				break;
+			case "executable":
+				command = `NODE_OPTIONS='--disable-sigusr1' ${quote(this.config.helper)}`;
+				break;
+			/* v8 ignore next -- Config parsing admits only these two launch kinds. */
+			default: return assertNever(launch);
+		}
+		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.destination(),
+			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: 2,
+			workspace: this.config.workspace,
+			leaseMs: this.config.leaseMs,
+			...bootstrapPath === void 0 ? {} : { 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.kind !== launch.kind) throw new Error("SSH helper runtime differs from the configured launch kind");
+		if (hello.bootstrapHash !== 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;
+	}
+};
+/**
+* The deployment's SSH service. Every operation runs on the alias's own login
+* unless the Agent driving it was bound to another login with
+* {@link SshConnection.bindLogin}; that Agent's operations then run on a
+* connection authenticated as the bound login, opened on first use and closed
+* after `loginIdleMs` without work. A process, terminal or text stream stays on
+* the connection that created it, whoever later observes or cancels it.
+*/
+var SshConnection = class extends Service {
+	static Config = schema.object({
+		host: schema.string().required(),
+		helper: schema.string().required(),
+		launch: schema.union([schema.object({
+			kind: schema.const("node-script").required(),
+			node: schema.string().required(),
+			bootstrapPath: schema.string(),
+			bootstrapHash: schema.string()
+		}), schema.object({ kind: schema.const("executable").required() })]).required(),
+		helperHash: schema.string().required(),
+		workspace: schema.string().required(),
+		requestTimeoutMs: schema.number().default(3e4),
+		maxFrameBytes: schema.number().default(64 * 1024 * 1024),
+		maxPending: schema.number().default(128),
+		leaseMs: schema.number().default(3e4),
+		loginIdleMs: schema.number().default(6e5)
+	});
+	/** Verified remote helper coordinates of the alias's own login; callers must await this before launch. */
+	ready;
+	config;
+	primary;
+	/** Login each bound Agent runs as. */
+	bindings = /* @__PURE__ */ new WeakMap();
+	logins = /* @__PURE__ */ new Map();
+	idle = /* @__PURE__ */ new Map();
+	/** Helper-issued handle ids and the channel whose helper issued them. */
+	handles = /* @__PURE__ */ new Map();
+	closed = false;
+	disposal;
+	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_.@-]*$/),
+			launch: z.discriminatedUnion("kind", [z.object({
+				kind: z.literal("node-script"),
+				node: z.string().startsWith("/"),
+				bootstrapPath: z.string().startsWith("/").optional(),
+				bootstrapHash: z.string().regex(/^[0-9a-f]{64}$/).optional()
+			}).strict().refine((value) => value.bootstrapPath === void 0 === (value.bootstrapHash === void 0), "bootstrapPath and bootstrapHash must be paired"), z.object({ kind: z.literal("executable") }).strict()]),
+			helper: z.string().startsWith("/"),
+			helperHash: z.string().regex(/^[0-9a-f]{64}$/),
+			workspace: z.string().startsWith("/"),
+			requestTimeoutMs: z.number().int().positive().max(2147483647),
+			maxFrameBytes: z.number().int().positive().max(64 * 1024 * 1024),
+			maxPending: z.number().int().positive().max(128),
+			leaseMs: z.number().int().min(3e3).max(6e5),
+			loginIdleMs: z.number().int().positive().max(2147483647)
+		}).strict().parse(config);
+		this.primary = new SshChannel(this.config, void 0, () => {});
+		this.ready = this.primary.ready;
+		ctx.effect(() => () => this.dispose());
+	}
+	/** Hold plugin readiness until the remote identity and helper digest are verified. */
+	async [Service.init]() {
+		await this.ready;
+	}
+	/** Verified remote PTC launch configuration; script deployments require a verified bootstrap. */
+	get ptcLaunch() {
+		const remote = this.primary.remote;
+		if (remote === void 0) throw new Error("SSH helper is not ready");
+		const launch = this.config.launch;
+		switch (launch.kind) {
+			case "executable": return {
+				kind: "embedded",
+				executable: remote.executable
+			};
+			case "node-script":
+				if (launch.bootstrapPath === void 0) throw new Error("SSH PTC requires a verified bootstrapPath and bootstrapHash");
+				return {
+					kind: "node-script",
+					executable: remote.executable,
+					bootstrapPath: launch.bootstrapPath
+				};
+			/* v8 ignore next -- Config parsing admits only these two launch kinds. */
+			default: return assertNever(launch);
+		}
+	}
+	/**
+	* Run every operation an Agent drives as `login` instead of the alias's own
+	* login. The remote host must accept the alias's key for that login. An
+	* Agent's operations are those made while it is the current initiator
+	* (`ctx.agents.currentInitiator()`); operations outside any initiator, or
+	* inside `ctx.agents.withoutInitiator()`, keep the alias's own login.
+	* @param agent - the Agent to bind; a child Agent it creates is not bound.
+	* @param login - remote login name.
+	* @returns a disposer that removes the binding; register it as an effect of the Agent's context.
+	* @throws when `login` is not a valid login name or the Agent is already bound.
+	*/
+	bindLogin(agent, login) {
+		if (!LOGIN.test(login)) throw new Error(`SSH login ${JSON.stringify(login)} is not a valid login name`);
+		if (this.bindings.has(agent)) throw new Error("SSH login is already bound for this Agent");
+		this.bindings.set(agent, login);
+		return () => {
+			this.bindings.delete(agent);
+		};
+	}
+	/**
+	* 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) {
+		const handle = HANDLE_METHODS.has(method) ? handleOf(params) : void 0;
+		const channel = (handle === void 0 ? void 0 : this.handles.get(handle)) ?? this.channelForInitiator();
+		const value = await channel.request(method, params, result, signal, wait);
+		if (channel !== this.primary) {
+			if (method === "process.prepare") this.handles.set(handleOf(value), channel);
+			else if (method === "fs.stream" && typeof value === "string") this.handles.set(value, channel);
+		}
+		if (handle !== void 0 && (method === "process.terminate" || method === "fs.streamClose" || method === "fs.next" && isDone(value))) this.handles.delete(handle);
+		if (channel !== this.primary) this.scheduleIdle(channel);
+		return value;
+	}
+	/**
+	* Forward one authenticated stream through an independent SSH channel.
+	* @param endpoint - private coordinates issued by one of this service's helpers.
+	* @param signal - cancellation of allocation and the resulting socket.
+	* @returns a paused socket; attach a consumer before resuming it.
+	*/
+	async connectStream(endpoint, signal) {
+		const channel = [...this.logins.values()].find((candidate) => {
+			const root = candidate.remote?.root;
+			return root !== void 0 && endpoint.path.startsWith(`${root}/`);
+		}) ?? this.primary;
+		const socket = await channel.connectStream(endpoint, signal);
+		if (channel !== this.primary) socket.once("close", () => {
+			this.scheduleIdle(channel);
+		});
+		return socket;
+	}
+	/** Tear down every helper's remote managed ranges before releasing their SSH masters when reachable. */
+	dispose() {
+		if (this.disposal !== void 0) return this.disposal;
+		this.closed = true;
+		for (const timer of this.idle.values()) clearTimeout(timer);
+		this.idle.clear();
+		const logins = [...this.logins.values()].map((channel) => channel.dispose());
+		const primary = this.primary.dispose();
+		this.logins.clear();
+		this.handles.clear();
+		this.disposal = Promise.allSettled(logins).then(() => primary);
+		return this.disposal;
+	}
+	/** The channel for the Agent driving the current operation. */
+	channelForInitiator() {
+		if (this.closed) return this.primary;
+		const agent = this.ctx.get("agents")?.currentInitiator();
+		const login = agent === void 0 ? void 0 : this.bindings.get(agent);
+		if (login === void 0) return this.primary;
+		let channel = this.logins.get(login);
+		if (channel === void 0 || channel.unusable) {
+			const opened = new SshChannel(this.config, login, () => {
+				if (this.logins.get(login) === opened) this.logins.delete(login);
+				for (const [id, owner] of this.handles) if (owner === opened) this.handles.delete(id);
+			});
+			channel = opened;
+			this.logins.set(login, channel);
+		}
+		const timer = this.idle.get(channel);
+		if (timer !== void 0) {
+			clearTimeout(timer);
+			this.idle.delete(channel);
+		}
+		return channel;
+	}
+	/** Close a login channel once it holds no work and no handles for `loginIdleMs`. */
+	scheduleIdle(channel) {
+		if (this.closed || channel.active > 0 || [...this.handles.values()].includes(channel)) return;
+		const previous = this.idle.get(channel);
+		if (previous !== void 0) clearTimeout(previous);
+		const timer = setTimeout(() => {
+			this.idle.delete(channel);
+			if (channel.active > 0 || [...this.handles.values()].includes(channel)) return;
+			for (const [login, owner] of this.logins) if (owner === channel) this.logins.delete(login);
+			channel.dispose().catch(() => {});
+		}, this.config.loginIdleMs);
+		timer.unref();
+		this.idle.set(channel, timer);
+	}
+};
+/** The handle id a request addresses or a prepare result carries. */
+function handleOf(value) {
+	if (typeof value !== "object" || value === null || !("id" in value)) return void 0;
+	return typeof value.id === "string" ? value.id : void 0;
+}
+/** Whether an `fs.next` result reports the end of its stream. */
+function isDone(value) {
+	return typeof value === "object" && value !== null && "done" in value && value.done === true;
+}
+//#endregion
+export { SshConnection, SshConnection as default };