@jabberwocky238/dsh-ssh 0.0.0-stage → 0.2.4

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 = 2;
+/** 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

package/lib/types/schemas.d.ts

@@ -0,0 +1,217 @@
+/** Strict JSON validation for SSH helper requests and remote observations. */
+import { z } from 'zod';
+import type { Branded } from '@deepseek-ai/dsh-brand';
+/** Identity of one prepared or running process in its owning SSH helper. */
+export type SshProcessId = Branded<'SshProcessId'>;
+/** Identity of one open text iterator in its owning SSH helper. */
+export type SshTextStreamId = Branded<'SshTextStreamId'>;
+/** Admit a process identity from the private helper protocol. */
+export declare const processIdSchema: z.ZodPipe<z.ZodUUID, z.ZodTransform<SshProcessId, string>>;
+/** Admit a text iterator identity from the private helper protocol. */
+export declare const textStreamIdSchema: z.ZodPipe<z.ZodUUID, z.ZodTransform<SshTextStreamId, string>>;
+/** A remote POSIX absolute path; spelling is preserved until remote canonicalization. */
+export declare const remotePath: z.ZodString;
+/** Filesystem identity returned by the remote filesystem provider. */
+export declare const targetSchema: z.ZodObject<{
+    targetKey: z.ZodString;
+    displayPath: z.ZodString;
+}, z.core.$strict>;
+/** Remote metadata observation. */
+export declare const infoSchema: z.ZodObject<{
+    version: z.ZodString;
+    type: z.ZodEnum<{
+        file: "file";
+        directory: "directory";
+        other: "other";
+    }>;
+    size: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** Metadata that preserves a final symlink. */
+export declare const pathInfoSchema: z.ZodObject<{
+    version: z.ZodString;
+    size: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodEnum<{
+        file: "file";
+        directory: "directory";
+        other: "other";
+        symlink: "symlink";
+    }>;
+}, z.core.$strict>;
+/** A resolved file-effect policy; the remote helper owns path canonicalization. */
+export declare const policySchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        "read-only": "read-only";
+        "workspace-write": "workspace-write";
+        "danger-full-access": "danger-full-access";
+    }>;
+    workspaceRoot: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Complete directory entries. */
+export declare const entriesSchema: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        file: "file";
+        directory: "directory";
+        other: "other";
+    }>;
+    target: z.ZodObject<{
+        targetKey: z.ZodString;
+        displayPath: z.ZodString;
+    }, z.core.$strict>;
+    version: z.ZodOptional<z.ZodString>;
+    size: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>>;
+/** Guarded write intent. */
+export declare const intentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"createIfAbsent">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"replaceIfVersion">;
+    version: z.ZodString;
+}, z.core.$strict>], "kind">;
+/** Literal text edit. */
+export declare const editSchema: z.ZodObject<{
+    oldString: z.ZodString;
+    newString: z.ZodString;
+    replaceAll: z.ZodBoolean;
+}, z.core.$strict>;
+/** Atomic write observation. */
+export declare const writeResultSchema: z.ZodObject<{
+    operation: z.ZodEnum<{
+        create: "create";
+        update: "update";
+    }>;
+    version: z.ZodString;
+    before: z.ZodNullable<z.ZodString>;
+    after: z.ZodString;
+}, z.core.$strict>;
+/** Atomic edit observation. */
+export declare const editResultSchema: z.ZodObject<{
+    version: z.ZodString;
+    before: z.ZodString;
+    after: z.ZodString;
+}, z.core.$strict>;
+/** Explicit child environment; null encodes an environment tombstone. */
+export declare const environmentSchema: z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>;
+/** Ordinary or terminal process requested by a trusted SSH client. */
+export declare const spawnSchema: z.ZodObject<{
+    argv: z.ZodArray<z.ZodString>;
+    cwd: z.ZodString;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>;
+    graceMs: z.ZodNumber;
+    stdio: z.ZodOptional<z.ZodObject<{
+        stdin: z.ZodUnion<readonly [z.ZodLiteral<"ignore">, z.ZodLiteral<"pipe">, z.ZodObject<{
+            data: z.ZodString;
+        }, z.core.$strict>]>;
+        stdout: z.ZodUnion<readonly [z.ZodLiteral<"pipe">, z.ZodLiteral<"inherit">, z.ZodObject<{
+            maxBytes: z.ZodNumber;
+            spill: z.ZodOptional<z.ZodObject<{
+                maxBytes: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>]>;
+        stderr: z.ZodUnion<readonly [z.ZodLiteral<"pipe">, z.ZodLiteral<"inherit">, z.ZodObject<{
+            maxBytes: z.ZodNumber;
+            spill: z.ZodOptional<z.ZodObject<{
+                maxBytes: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>]>;
+        control: z.ZodOptional<z.ZodLiteral<"pipe">>;
+    }, z.core.$strict>>;
+    terminal: z.ZodOptional<z.ZodObject<{
+        terminalType: z.ZodString;
+        rows: z.ZodNumber;
+        cols: z.ZodNumber;
+        shellActivity: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Connection handshake binds sockets and workspace to one helper process. */
+export declare const helloSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<2>;
+    hash: z.ZodString;
+    kind: z.ZodEnum<{
+        executable: "executable";
+        "node-script": "node-script";
+    }>;
+    platform: z.ZodEnum<{
+        linux: "linux";
+        darwin: "darwin";
+    }>;
+    nodeVersion: z.ZodString;
+    executable: z.ZodString;
+    root: z.ZodString;
+    workspace: z.ZodString;
+    bootstrapHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** A prepared process publishes its sockets before target code may execute. */
+export declare const streamEndpointSchema: z.ZodObject<{
+    path: z.ZodString;
+    capability: z.ZodString;
+}, z.core.$strict>;
+/** A stream capability reaches only the authenticated SSH client and its helper. */
+export type SshStreamEndpoint = z.infer<typeof streamEndpointSchema>;
+/** Prepared process and its independently authenticated stream endpoints. */
+export declare const preparedSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUUID, z.ZodTransform<SshProcessId, string>>;
+    streams: z.ZodRecord<z.ZodEnum<{
+        stdin: "stdin";
+        stdout: "stdout";
+        stderr: "stderr";
+        control: "control";
+        terminal: "terminal";
+    }> & z.core.$partial, z.ZodObject<{
+        path: z.ZodString;
+        capability: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Direct process exit facts. */
+export declare const outcomeSchema: z.ZodObject<{
+    exitCode: z.ZodNullable<z.ZodNumber>;
+    signal: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/** A bounded raw tail positioned in whole-stream byte coordinates. */
+export declare const outputSnapshotSchema: z.ZodObject<{
+    tail: z.ZodBase64;
+    totalBytes: z.ZodNumber;
+}, z.core.$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.
+ */
+export declare function outputSnapshotFrameLimit(maxBytes: number): number;
+/** Direct exit, retained output snapshots, and optional complete spill locations. */
+export declare const doneSchema: z.ZodObject<{
+    outcome: z.ZodObject<{
+        exitCode: z.ZodNullable<z.ZodNumber>;
+        signal: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    spills: z.ZodObject<{
+        stdout: z.ZodOptional<z.ZodString>;
+        stderr: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    collected: z.ZodObject<{
+        stdout: z.ZodOptional<z.ZodObject<{
+            tail: z.ZodBase64;
+            totalBytes: z.ZodNumber;
+        }, z.core.$strict>>;
+        stderr: z.ZodOptional<z.ZodObject<{
+            tail: z.ZodBase64;
+            totalBytes: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** Remote terminal foreground observation. */
+export declare const foregroundSchema: z.ZodNullable<z.ZodObject<{
+    processGroupId: z.ZodNumber;
+    inputWaiting: z.ZodBoolean;
+}, z.core.$strict>>;
+/** Conservative shell lifecycle and process observation returned by the execution provider. */
+export declare const terminalActivitySchema: z.ZodObject<{
+    state: z.ZodEnum<{
+        unknown: "unknown";
+        idle: "idle";
+        busy: "busy";
+    }>;
+    revision: z.ZodNumber;
+}, z.core.$strict>;
+//# sourceMappingURL=schemas.d.ts.map

package/lib/types/stream-security.d.ts

@@ -0,0 +1,19 @@
+/** TLS-PSK authenticates forwarded streams even when a remote pathname is replaced. */
+import { type TLSSocket } from 'node:tls';
+import type { Socket } from 'node:net';
+/** Certificate-free PSK authentication and AEAD records; no unauthenticated cipher fallback. */
+export declare const SSH_STREAM_TLS_OPTIONS: {
+    readonly ciphers: "PSK-AES256-GCM-SHA384";
+    readonly minVersion: "TLSv1.2";
+    readonly 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.
+ */
+export declare function authenticateStream(socket: Socket, capability: string, timeoutMs: number, signal?: AbortSignal): Promise<TLSSocket>;
+//# sourceMappingURL=stream-security.d.ts.map

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@jabberwocky238/dsh-ssh",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.4",
+  "description": "Shared OpenSSH connection to a versioned POSIX helper, with per-Agent login binding",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./protocol": {
+      "types": "./lib/types/protocol.d.ts",
+      "default": "./lib/protocol.js"
+    },
+    "./schemas": {
+      "types": "./lib/types/schemas.d.ts",
+      "default": "./lib/schemas.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jabberwocky238/deepseek-harness.git",
+    "directory": "packages/ssh/ssh"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.5-alpha.1",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-util-values": "0.2.1-alpha.2"
+  }
 }