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

package/lib/schemas-DBIgsx0q.js

@@ -0,0 +1,177 @@
+import { z } from "zod";
+//#region lib/types/schemas.js
+/** Strict JSON validation for SSH helper requests and remote observations. */
+/** Admit a process identity from the private helper protocol. */
+const processIdSchema = z.uuid().transform((value) => value);
+/** Admit a text iterator identity from the private helper protocol. */
+const textStreamIdSchema = z.uuid().transform((value) => value);
+/** A remote POSIX absolute path; spelling is preserved until remote canonicalization. */
+const remotePath = z.string().min(1).refine((value) => value.startsWith("/") && !value.includes("\0"), "expected an absolute POSIX path");
+/** Filesystem identity returned by the remote filesystem provider. */
+const targetSchema = z.object({
+	targetKey: remotePath,
+	displayPath: z.string()
+}).strict();
+/** Remote metadata observation. */
+const infoSchema = z.object({
+	version: z.string(),
+	type: z.enum([
+		"file",
+		"directory",
+		"other"
+	]),
+	size: z.number().nonnegative().optional()
+}).strict();
+/** Metadata that preserves a final symlink. */
+const pathInfoSchema = infoSchema.extend({ type: z.enum([
+	"file",
+	"directory",
+	"symlink",
+	"other"
+]) });
+/** A resolved file-effect policy; the remote helper owns path canonicalization. */
+const policySchema = z.object({
+	mode: z.enum([
+		"read-only",
+		"workspace-write",
+		"danger-full-access"
+	]),
+	workspaceRoot: remotePath,
+	sessionId: z.string().optional()
+}).strict();
+/** Complete directory entries. */
+const entriesSchema = z.array(z.object({
+	name: z.string(),
+	type: z.enum([
+		"file",
+		"directory",
+		"other"
+	]),
+	target: targetSchema,
+	version: z.string().optional(),
+	size: z.number().nonnegative().optional()
+}).strict());
+/** Guarded write intent. */
+const intentSchema = z.discriminatedUnion("kind", [z.object({ kind: z.literal("createIfAbsent") }).strict(), z.object({
+	kind: z.literal("replaceIfVersion"),
+	version: z.string()
+}).strict()]);
+/** Literal text edit. */
+const editSchema = z.object({
+	oldString: z.string(),
+	newString: z.string(),
+	replaceAll: z.boolean()
+}).strict();
+/** Atomic write observation. */
+const writeResultSchema = z.object({
+	operation: z.enum(["create", "update"]),
+	version: z.string(),
+	before: z.string().nullable(),
+	after: z.string()
+}).strict();
+/** Atomic edit observation. */
+const editResultSchema = z.object({
+	version: z.string(),
+	before: z.string(),
+	after: z.string()
+}).strict();
+/** Explicit child environment; null encodes an environment tombstone. */
+const environmentSchema = z.record(z.string(), z.string().nullable());
+const collection = z.object({
+	maxBytes: z.number().int().positive(),
+	spill: z.object({ maxBytes: z.number().int().positive() }).strict().optional()
+}).strict();
+/** Ordinary or terminal process requested by a trusted SSH client. */
+const spawnSchema = z.object({
+	argv: z.array(z.string().refine((value) => !value.includes("\0"))).min(1),
+	cwd: remotePath,
+	env: environmentSchema.optional(),
+	graceMs: z.number().int().positive().max(2147483647),
+	stdio: z.object({
+		stdin: z.union([
+			z.literal("ignore"),
+			z.literal("pipe"),
+			z.object({ data: z.string() }).strict()
+		]),
+		stdout: z.union([
+			z.literal("pipe"),
+			z.literal("inherit"),
+			collection
+		]),
+		stderr: z.union([
+			z.literal("pipe"),
+			z.literal("inherit"),
+			collection
+		]),
+		control: z.literal("pipe").optional()
+	}).strict().optional(),
+	terminal: z.object({
+		terminalType: z.string().min(1),
+		rows: z.number().int().positive(),
+		cols: z.number().int().positive()
+	}).strict().optional()
+}).strict().refine((value) => value.stdio === void 0 !== (value.terminal === void 0), "select ordinary or terminal execution");
+/** Connection handshake binds sockets and workspace to one helper process. */
+const helloSchema = z.object({
+	protocol: z.literal(1),
+	hash: z.string().regex(/^[0-9a-f]{64}$/),
+	platform: z.enum(["linux", "darwin"]),
+	nodeVersion: z.string(),
+	node: remotePath,
+	root: remotePath,
+	workspace: remotePath,
+	bootstrapHash: z.string().regex(/^[0-9a-f]{64}$/).optional()
+}).strict();
+/** A prepared process publishes its sockets before target code may execute. */
+const streamEndpointSchema = z.object({
+	path: remotePath,
+	capability: z.string().regex(/^[0-9a-f]{64}$/)
+}).strict();
+/** Prepared process and its independently authenticated stream endpoints. */
+const preparedSchema = z.object({
+	id: processIdSchema,
+	streams: z.partialRecord(z.enum([
+		"stdin",
+		"stdout",
+		"stderr",
+		"control",
+		"terminal"
+	]), streamEndpointSchema)
+}).strict();
+/** Direct process exit facts. */
+const outcomeSchema = z.object({
+	exitCode: z.number().int().nullable(),
+	signal: z.string().nullable()
+}).strict();
+/** A bounded raw tail positioned in whole-stream byte coordinates. */
+const outputSnapshotSchema = z.object({
+	tail: z.base64(),
+	totalBytes: z.number().int().nonnegative()
+}).strict();
+/**
+* Bound one encoded tail and its RPC envelope by the declared collection budget.
+* @param maxBytes - the collector's retained raw-byte limit.
+* @returns the private snapshot frame limit, capped by the helper protocol ceiling.
+*/
+function outputSnapshotFrameLimit(maxBytes) {
+	return Math.min(64 * 1024 * 1024, maxBytes * 2 + 1024);
+}
+/** Direct exit, retained output snapshots, and optional complete spill locations. */
+const doneSchema = z.object({
+	outcome: outcomeSchema,
+	spills: z.object({
+		stdout: remotePath.optional(),
+		stderr: remotePath.optional()
+	}).strict(),
+	collected: z.object({
+		stdout: outputSnapshotSchema.optional(),
+		stderr: outputSnapshotSchema.optional()
+	}).strict()
+}).strict();
+/** Remote terminal foreground observation. */
+const foregroundSchema = z.object({
+	processGroupId: z.number().int().positive(),
+	inputWaiting: z.boolean()
+}).strict().nullable();
+//#endregion
+export { writeResultSchema as S, remotePath as _, environmentSchema as a, targetSchema as b, infoSchema as c, outputSnapshotFrameLimit as d, outputSnapshotSchema as f, processIdSchema as g, preparedSchema as h, entriesSchema as i, intentSchema as l, policySchema as m, editResultSchema as n, foregroundSchema as o, pathInfoSchema as p, editSchema as r, helloSchema as s, doneSchema as t, outcomeSchema as u, spawnSchema as v, textStreamIdSchema as x, streamEndpointSchema as y };

package/lib/schemas.js

@@ -0,0 +1,2 @@
+import { S as writeResultSchema, _ as remotePath, a as environmentSchema, b as targetSchema, c as infoSchema, d as outputSnapshotFrameLimit, f as outputSnapshotSchema, g as processIdSchema, h as preparedSchema, i as entriesSchema, l as intentSchema, m as policySchema, n as editResultSchema, o as foregroundSchema, p as pathInfoSchema, r as editSchema, s as helloSchema, t as doneSchema, u as outcomeSchema, v as spawnSchema, x as textStreamIdSchema, y as streamEndpointSchema } from "./schemas-DBIgsx0q.js";
+export { doneSchema, editResultSchema, editSchema, entriesSchema, environmentSchema, foregroundSchema, helloSchema, infoSchema, intentSchema, outcomeSchema, outputSnapshotFrameLimit, outputSnapshotSchema, pathInfoSchema, policySchema, preparedSchema, processIdSchema, remotePath, spawnSchema, streamEndpointSchema, targetSchema, textStreamIdSchema, writeResultSchema };

package/lib/stream-security-DJlQsPG-.js

@@ -0,0 +1,75 @@
+import { connect } from "node:tls";
+//#region lib/types/stream-security.js
+/** TLS-PSK authenticates forwarded streams even when a remote pathname is replaced. */
+/** Certificate-free PSK authentication and AEAD records; no unauthenticated cipher fallback. */
+const SSH_STREAM_TLS_OPTIONS = {
+	ciphers: "PSK-AES256-GCM-SHA384",
+	minVersion: "TLSv1.2",
+	maxVersion: "TLSv1.2"
+};
+/**
+* Authenticate a forwarded socket with its private administrative-channel key.
+* @param socket - the connected OpenSSH forwarding socket.
+* @param capability - the per-stream 256-bit key encoded as hexadecimal.
+* @param timeoutMs - deadline for completing TLS authentication.
+* @param signal - cancellation of authentication and the resulting TLS stream.
+* @returns an authenticated paused stream; the key is never transmitted as data.
+*/
+async function authenticateStream(socket, capability, timeoutMs, signal) {
+	if (signal?.aborted) {
+		socket.destroy();
+		signal.throwIfAborted();
+	}
+	const stream = connect({
+		...SSH_STREAM_TLS_OPTIONS,
+		socket,
+		rejectUnauthorized: true,
+		pskCallback: () => ({
+			psk: Buffer.from(capability, "hex"),
+			identity: "dsh-stream"
+		}),
+		checkServerIdentity: () => void 0
+	});
+	const abort = () => {
+		stream.destroy(signal?.reason instanceof Error ? signal.reason : new Error(String(signal?.reason)));
+	};
+	signal?.addEventListener("abort", abort, { once: true });
+	stream.once("close", () => {
+		signal?.removeEventListener("abort", abort);
+	});
+	try {
+		await new Promise((resolve, reject) => {
+			const cleanup = () => {
+				stream.off("secureConnect", secured);
+				stream.off("error", failed);
+				stream.off("close", closed);
+				clearTimeout(timer);
+			};
+			const secured = () => {
+				cleanup();
+				stream.disableRenegotiation();
+				stream.pause();
+				resolve();
+			};
+			const failed = (error) => {
+				cleanup();
+				reject(error);
+			};
+			const closed = () => {
+				failed(/* @__PURE__ */ new Error("SSH stream closed during authentication"));
+			};
+			const timer = setTimeout(() => {
+				failed(/* @__PURE__ */ new Error("SSH stream authentication timed out"));
+			}, timeoutMs);
+			stream.once("secureConnect", secured);
+			stream.once("error", failed);
+			stream.once("close", closed);
+		});
+		return stream;
+	} catch (error) {
+		stream.destroy();
+		throw error;
+	}
+}
+//#endregion
+export { authenticateStream as n, SSH_STREAM_TLS_OPTIONS as t };

package/lib/types/helper-entry.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=helper-entry.d.ts.map

package/lib/types/helper-processes.d.ts

@@ -0,0 +1,79 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type SshProcessId, type SshStreamEndpoint } from './schemas.ts';
+type Channel = 'stdin' | 'stdout' | 'stderr' | 'control' | 'terminal';
+/** Owns remote launch reservations through final process-range quiescence. */
+export declare class RemoteProcesses {
+    private readonly ctx;
+    private readonly root;
+    private readonly limit;
+    private readonly preparationMs;
+    private readonly records;
+    private readonly completed;
+    private readonly cleanups;
+    private closing;
+    constructor(ctx: Context, root: string, limit: number, preparationMs: number);
+    /**
+     * Allocate private stream listeners; no target executes until start().
+     * @param raw - untrusted process request received over SSH.
+     * @returns the reservation id and authenticated stream coordinates.
+     */
+    prepare(raw: unknown): Promise<{
+        id: SshProcessId;
+        streams: Partial<Record<Channel, SshStreamEndpoint>>;
+    }>;
+    /**
+     * Start once all data channels are authenticated; duplicate starts refuse.
+     * @param id - the prepared process reservation.
+     * @param signal - cancellation of pending process publication.
+     * @returns the terminal pid when the request owns a PTY.
+     */
+    start(id: SshProcessId, signal?: AbortSignal): Promise<{
+        pid?: number;
+    }>;
+    private startOnce;
+    /**
+     * Await the direct result without claiming all descendants have exited.
+     * @param id - the started process reservation.
+     * @returns the exit observation and remote spill paths.
+     * @throws the original startup or process failure while its completion is retained.
+     */
+    done(id: SshProcessId): Promise<unknown>;
+    /**
+     * Observe the native managed range used for termination.
+     * @param id - the started process reservation.
+     * @param signal - cancellation of this observation, leaving ownership intact.
+     * @returns whether the owned process range is empty.
+     */
+    wait(id: SshProcessId, signal?: AbortSignal): Promise<boolean>;
+    /**
+     * Terminate and await the managed range independently of output readers.
+     * @param id - the process reservation to stop.
+     */
+    terminate(id: SshProcessId): Promise<void>;
+    /**
+     * Operate on the terminal owned by the request id.
+     * @param id - the terminal reservation.
+     * @param operation - terminal input, foreground observation, or signal delivery.
+     * @param value - input bytes as text or the signal name.
+     * @returns the operation's wire result.
+     */
+    terminal(id: SshProcessId, operation: 'write' | 'inspect' | 'signal', value?: string): Promise<unknown>;
+    /**
+     * Resize an allocated terminal without replacing its process.
+     * @param id - terminal reservation.
+     * @param cols - positive terminal width.
+     * @param rows - positive terminal height.
+     * @returns after the local provider accepts the dimensions.
+     */
+    resizeTerminal(id: SshProcessId, cols: number, rows: number): Promise<void>;
+    /** Stop every owned process on lease expiry or disconnect. */
+    close(): Promise<void>;
+    private release;
+    private record;
+    private finishFailed;
+    private rememberCompleted;
+    private trackCleanup;
+    private endpoint;
+}
+export {};
+//# sourceMappingURL=helper-processes.d.ts.map

package/lib/types/helper.d.ts

@@ -0,0 +1,18 @@
+import type { Readable, Writable } from 'node:stream';
+/** The private helper's authenticated transport and process lifetime. */
+export interface HelperTransport {
+    /** Authenticated request bytes from OpenSSH. */
+    input: Readable;
+    /** Responses carried only by OpenSSH exec stdout. */
+    output: Writable;
+    /** Installed entry whose digest is compared by the client. */
+    entryPath: string;
+    /** Process termination joins the same cleanup as transport loss. */
+    signal: AbortSignal;
+}
+/**
+ * Run a helper until its channel closes or its client lease expires.
+ * @param transport - private process streams, entry identity, and cancellation.
+ */
+export declare function runSshHelper(transport: HelperTransport): Promise<void>;
+//# sourceMappingURL=helper.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,93 @@
+/** OpenSSH connection owner for one version-matched POSIX helper and its independent forwarded streams. */
+import { type Socket } from 'node:net';
+import { Context, Service } from '@deepseek-ai/cordis';
+import schema from '@deepseek-ai/schemastery';
+import { z } from 'zod';
+import { helloSchema, type SshStreamEndpoint } from './schemas.ts';
+type Hello = z.infer<typeof helloSchema>;
+/** Deployment-owned SSH identity and installed helper; no model argument selects these values. */
+export interface Config {
+    /** OpenSSH host alias, including its existing user, key and known-host configuration. */
+    host: string;
+    /** Absolute remote Node executable. */
+    node: string;
+    /** Absolute path to the installed, bundled helper entry. */
+    helper: string;
+    /** SHA-256 of that bundled helper; mismatches refuse the connection. */
+    helperHash: string;
+    /** Absolute remote default workspace. */
+    workspace: string;
+    /** Optional preinstalled built PTC entry, paired with its expected digest. */
+    bootstrapPath?: string;
+    /** SHA-256 of bootstrapPath; both fields must be supplied together. */
+    bootstrapHash?: string;
+    /** Connection and administrative-request deadline, at most 2,147,483,647 milliseconds. */
+    requestTimeoutMs?: number;
+    /** Maximum JSON payload bytes per helper request or response. */
+    maxFrameBytes?: number;
+    /** Maximum ordinary requests; heartbeat and bounded resource cleanup have reserved capacity. */
+    maxPending?: number;
+    /** Remote helper lease; loss of heartbeats starts remote managed cleanup. */
+    leaseMs?: number;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        ssh: SshConnection;
+    }
+}
+/** One non-reconnecting SSH session; loss invalidates all active operations. */
+export declare class SshConnection extends Service {
+    static Config: schema<Config>;
+    /** Verified remote helper coordinates; callers must await this before launch. */
+    readonly ready: Promise<Hello>;
+    private rpc;
+    private child;
+    private childClosed;
+    private directory;
+    private heartbeat;
+    private closed;
+    private readonly lifetime;
+    private readonly operations;
+    private disposal;
+    private failure;
+    private sockets;
+    private nextSocket;
+    private readonly config;
+    private remote;
+    constructor(ctx: Context, config: Config);
+    /** Hold plugin readiness until the remote identity and helper digest are verified. */
+    [Service.init](): Promise<void>;
+    /** Verified remote Node executable for the paired PTC runtime. */
+    get nodeExecutable(): string;
+    /** Verified preinstalled PTC entry; unconfigured runtimes fail before program execution. */
+    get bootstrapPath(): string;
+    /**
+     * 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.
+     */
+    request<T>(method: string, params: unknown, result: z.ZodType<T>, signal?: AbortSignal, wait?: boolean): Promise<T>;
+    /**
+     * 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.
+     */
+    connectStream(endpoint: SshStreamEndpoint, signal?: AbortSignal): Promise<Socket>;
+    private establishStream;
+    /** Tear down the helper's remote managed ranges before releasing the SSH master when reachable. */
+    dispose(): Promise<void>;
+    private disposeOnce;
+    private controlPath;
+    private assertOpen;
+    private track;
+    private controlCommand;
+    private fail;
+    private start;
+}
+export default SshConnection;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/protocol.d.ts

@@ -0,0 +1,50 @@
+/** Bounded, versioned requests between an SSH client and its private remote helper. */
+import { EventEmitter } from 'node:events';
+import type { Readable, Writable } from 'node:stream';
+import { z } from 'zod';
+/** Wire version shared by the installed helper and client package. */
+export declare const SSH_PROTOCOL_VERSION = 1;
+/** Maximum prepared or running process handles owned by one helper. */
+export declare const SSH_MAX_PROCESS_HANDLES = 128;
+/** Maximum open text iterators owned by one helper. */
+export declare const SSH_MAX_TEXT_STREAMS = 128;
+type RequestHandler = (method: string, params: unknown, signal: AbortSignal) => Promise<unknown>;
+/** A remote error retains its typed filesystem or sandbox code. */
+export declare class RemoteOperationError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+/** The peer owns pending calls and rejects ambiguous operations on connection loss; it never replays requests. */
+export declare class SshRpcPeer extends EventEmitter {
+    private readonly input;
+    private readonly output;
+    private readonly maxFrameBytes;
+    private readonly maxPending;
+    private readonly handler?;
+    private readonly pending;
+    private readonly active;
+    private writeTail;
+    private queuedBytes;
+    private failure;
+    constructor(input: Readable, output: Writable, maxFrameBytes: number, maxPending: number, handler?: RequestHandler | undefined);
+    /**
+     * 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.
+     */
+    request<T>(method: string, params: unknown, schema: z.ZodType<T>, signal?: AbortSignal): Promise<T>;
+    /**
+     * Fail pending operations and abort remote handlers without claiming rollback.
+     * @param error - the transport failure reported to all pending operations.
+     */
+    close(error?: Error): void;
+    private send;
+    private readFrames;
+    private receive;
+    private atCapacity;
+}
+export {};
+//# sourceMappingURL=protocol.d.ts.map