@akms/mcp-ssh 0.0.3 → 0.1.0

package/lib/index.d.cts

@@ -28,6 +28,18 @@ interface SshPolicy {
     /** Remote path prefixes the file tools may touch. Empty means unrestricted. */
     allowedPaths: string[];
 }
+/** Intermediate host the target is reached through, as OpenSSH's `ProxyJump` / `-J`. */
+interface SshJumpProfile {
+    host: string;
+    port: number;
+    username: string;
+    /** Expanded absolute path to a private key file. */
+    privateKeyPath?: string;
+    passphrase?: string;
+    password?: string;
+    /** Expected jump host key, `SHA256:…`; a mismatch aborts the connection. */
+    hostKeyFingerprint?: string;
+}
 /** The registered host: where to connect, how to authenticate, what is permitted. */
 interface SshHostProfile {
     /** Alias shown to the model, from `SSH_NAME`; defaults to the hostname. */
@@ -47,6 +59,14 @@ interface SshHostProfile {
     hostKeyFingerprint?: string;
     /** Directory every session starts in; falls back to the login shell's default. */
     defaultCwd?: string;
+    /**
+     * Command whose stdin/stdout carry the SSH stream instead of a TCP socket — OpenSSH's
+     * `ProxyCommand`. It carries the first hop: the jump host when one is set, else the
+     * target. `%h` / `%p` / `%r` expand to that hop's host, port and user.
+     */
+    proxyCommand?: string;
+    /** Jump host the target is reached through via a forwarded TCP channel. */
+    jump?: SshJumpProfile;
     policy: SshPolicy;
 }
 /** Credential-free view of the profile, safe to hand back to the model. */
@@ -57,6 +77,13 @@ interface SshHostSummary {
     username: string;
     description?: string;
     authMethod: "privateKey" | "password" | "agent";
+    /** True when a proxy command carries the first hop; the command itself is withheld. */
+    viaProxyCommand: boolean;
+    jump?: {
+        host: string;
+        port: number;
+        username: string;
+    };
     readonly: boolean;
     allowSudo: boolean;
     allowedPaths: string[];
@@ -135,17 +162,23 @@ declare class SshConnection {
     /** Set when the peer closed a previously established connection. */
     private droppedAfterReady;
     private observedFingerprint;
+    private observedJumpFingerprint;
     constructor(profile: SshHostProfile);
     get isConnected(): boolean;
     /** Host key the server presented, once a handshake has been attempted. */
     get hostKeyFingerprint(): string | null;
+    /** Host key the jump host presented; null without a jump host or before its handshake. */
+    get jumpHostKeyFingerprint(): string | null;
     /** True when a connection was established and then lost, so shell state is gone. */
     get wasDropped(): boolean;
     /**
      * Opens the connection, or joins the in-flight attempt when one is already running.
      *
+     * With a proxy command or a jump host the carrier is opened first and handed to ssh2
+     * as the socket; it is torn down with the target connection, whichever side closes.
+     *
      * @throws {Error} If the connection was closed, authentication fails, the host is
-     *                 unreachable, or the handshake times out.
+     *                 unreachable, the handshake times out, or the carrier cannot be opened.
      */
     connect(): Promise<void>;
     /**
@@ -344,10 +377,14 @@ declare function createSshMcpServer(): SshMcpServerInstance;
  *  2) Resolve the policy over the built-in permissive stance; each variable is opt-in restriction
  *  3) Assemble the connection fields
  *  4) Expand the private key path and check it exists
+ *  5) Route: proxy command and / or jump host
  *
- * @throws {Error} If `SSH_HOST` is set without `SSH_USER`, or a typed value is malformed.
+ * @param env - Where the `SSH_*` variables are read from. Defaults to the process
+ *              environment; the `config` command passes the entry it is about to write.
+ * @throws {Error} If `SSH_HOST` is set without `SSH_USER`, a `SSH_JUMP_*` variable is set
+ *                 without `SSH_JUMP_HOST`, or a typed value is malformed.
  */
-declare function loadHostProfile(): SshHostProfile | null;
+declare function loadHostProfile(env?: NodeJS.ProcessEnv): SshHostProfile | null;
 /** Strips every secret so the profile can be described back to the model. */
 declare function toHostSummary(profile: SshHostProfile): SshHostSummary;
 
@@ -495,7 +532,7 @@ declare const $logger: Logger;
 /** Env var overriding the stderr log level ("debug" | "info" | "warn" | "error" | "silent"). */
 declare const LOG_LEVEL_ENV = "SSH_MCP_LOG_LEVEL";
 declare const SERVER_NAME = "akms-mcp-ssh";
-declare const SERVER_VERSION = "0.0.3";
+declare const SERVER_VERSION = "0.1.0";
 
 /**
  * Environment variables that define the host, one MCP server entry per host.
@@ -520,6 +557,22 @@ declare const SINGLE_HOST_ENV: {
     readonly DESCRIPTION: "SSH_DESCRIPTION";
     /** Directory new sessions start in. */
     readonly CWD: "SSH_CWD";
+    /**
+     * Command whose stdin/stdout carry the SSH stream, like OpenSSH's `ProxyCommand`.
+     * `%h` / `%p` / `%r` expand to the first hop's host, port and user.
+     */
+    readonly PROXY_COMMAND: "SSH_PROXY_COMMAND";
+    /** Presence of this variable routes the connection through a jump host. */
+    readonly JUMP_HOST: "SSH_JUMP_HOST";
+    readonly JUMP_PORT: "SSH_JUMP_PORT";
+    /** Defaults to `SSH_USER`. */
+    readonly JUMP_USER: "SSH_JUMP_USER";
+    /** Path to the jump host's private key file; defaults to `SSH_KEY`. */
+    readonly JUMP_KEY: "SSH_JUMP_KEY";
+    readonly JUMP_PASSPHRASE: "SSH_JUMP_PASSPHRASE";
+    readonly JUMP_PASSWORD: "SSH_JUMP_PASSWORD";
+    /** Pinned jump host key, `SHA256:…`. */
+    readonly JUMP_HOST_KEY: "SSH_JUMP_HOST_KEY";
     readonly READONLY: "SSH_READONLY";
     readonly ALLOW_SUDO: "SSH_ALLOW_SUDO";
     /** Comma-separated binary names. */
@@ -534,4 +587,4 @@ declare const SINGLE_HOST_ENV: {
     readonly MAX_READ_FILE_BYTES: "SSH_MAX_READ_BYTES";
 };
 
-export { $logger, GuardRejectionError, type GuardVerdict, LOG_LEVEL_ENV, type LogLevel, type Logger, type RemoteDirectoryListing, type RemoteFileContent, type RemotePathAccess, SERVER_NAME, SERVER_VERSION, SINGLE_HOST_ENV, type SegmentAnalysis, SshConnection, type SshExecOptions, type SshExecResult, type SshHostProfile, type SshHostSummary, type SshMcpServerInstance, type SshPolicy, type SshRemoteEntry, SshSession, type SshSessionInfo, SshSessionManager, type ToolContext, analyzeSegment, canonicalizeCommand, createSshMcpServer, downloadFile, extractSubstitutions, inspectCommand, inspectLocalPath, inspectRemotePath, inspectWorkingDirectory, listRemoteDirectory, loadHostProfile, normalizeCommandText, readRemoteFile, registerAllTools, splitCommandSegments, stripQuotedText, toHostSummary, uploadFile, writeRemoteFile };
+export { $logger, GuardRejectionError, type GuardVerdict, LOG_LEVEL_ENV, type LogLevel, type Logger, type RemoteDirectoryListing, type RemoteFileContent, type RemotePathAccess, SERVER_NAME, SERVER_VERSION, SINGLE_HOST_ENV, type SegmentAnalysis, SshConnection, type SshExecOptions, type SshExecResult, type SshHostProfile, type SshHostSummary, type SshJumpProfile, type SshMcpServerInstance, type SshPolicy, type SshRemoteEntry, SshSession, type SshSessionInfo, SshSessionManager, type ToolContext, analyzeSegment, canonicalizeCommand, createSshMcpServer, downloadFile, extractSubstitutions, inspectCommand, inspectLocalPath, inspectRemotePath, inspectWorkingDirectory, listRemoteDirectory, loadHostProfile, normalizeCommandText, readRemoteFile, registerAllTools, splitCommandSegments, stripQuotedText, toHostSummary, uploadFile, writeRemoteFile };

package/lib/index.d.ts

@@ -28,6 +28,18 @@ interface SshPolicy {
     /** Remote path prefixes the file tools may touch. Empty means unrestricted. */
     allowedPaths: string[];
 }
+/** Intermediate host the target is reached through, as OpenSSH's `ProxyJump` / `-J`. */
+interface SshJumpProfile {
+    host: string;
+    port: number;
+    username: string;
+    /** Expanded absolute path to a private key file. */
+    privateKeyPath?: string;
+    passphrase?: string;
+    password?: string;
+    /** Expected jump host key, `SHA256:…`; a mismatch aborts the connection. */
+    hostKeyFingerprint?: string;
+}
 /** The registered host: where to connect, how to authenticate, what is permitted. */
 interface SshHostProfile {
     /** Alias shown to the model, from `SSH_NAME`; defaults to the hostname. */
@@ -47,6 +59,14 @@ interface SshHostProfile {
     hostKeyFingerprint?: string;
     /** Directory every session starts in; falls back to the login shell's default. */
     defaultCwd?: string;
+    /**
+     * Command whose stdin/stdout carry the SSH stream instead of a TCP socket — OpenSSH's
+     * `ProxyCommand`. It carries the first hop: the jump host when one is set, else the
+     * target. `%h` / `%p` / `%r` expand to that hop's host, port and user.
+     */
+    proxyCommand?: string;
+    /** Jump host the target is reached through via a forwarded TCP channel. */
+    jump?: SshJumpProfile;
     policy: SshPolicy;
 }
 /** Credential-free view of the profile, safe to hand back to the model. */
@@ -57,6 +77,13 @@ interface SshHostSummary {
     username: string;
     description?: string;
     authMethod: "privateKey" | "password" | "agent";
+    /** True when a proxy command carries the first hop; the command itself is withheld. */
+    viaProxyCommand: boolean;
+    jump?: {
+        host: string;
+        port: number;
+        username: string;
+    };
     readonly: boolean;
     allowSudo: boolean;
     allowedPaths: string[];
@@ -135,17 +162,23 @@ declare class SshConnection {
     /** Set when the peer closed a previously established connection. */
     private droppedAfterReady;
     private observedFingerprint;
+    private observedJumpFingerprint;
     constructor(profile: SshHostProfile);
     get isConnected(): boolean;
     /** Host key the server presented, once a handshake has been attempted. */
     get hostKeyFingerprint(): string | null;
+    /** Host key the jump host presented; null without a jump host or before its handshake. */
+    get jumpHostKeyFingerprint(): string | null;
     /** True when a connection was established and then lost, so shell state is gone. */
     get wasDropped(): boolean;
     /**
      * Opens the connection, or joins the in-flight attempt when one is already running.
      *
+     * With a proxy command or a jump host the carrier is opened first and handed to ssh2
+     * as the socket; it is torn down with the target connection, whichever side closes.
+     *
      * @throws {Error} If the connection was closed, authentication fails, the host is
-     *                 unreachable, or the handshake times out.
+     *                 unreachable, the handshake times out, or the carrier cannot be opened.
      */
     connect(): Promise<void>;
     /**
@@ -344,10 +377,14 @@ declare function createSshMcpServer(): SshMcpServerInstance;
  *  2) Resolve the policy over the built-in permissive stance; each variable is opt-in restriction
  *  3) Assemble the connection fields
  *  4) Expand the private key path and check it exists
+ *  5) Route: proxy command and / or jump host
  *
- * @throws {Error} If `SSH_HOST` is set without `SSH_USER`, or a typed value is malformed.
+ * @param env - Where the `SSH_*` variables are read from. Defaults to the process
+ *              environment; the `config` command passes the entry it is about to write.
+ * @throws {Error} If `SSH_HOST` is set without `SSH_USER`, a `SSH_JUMP_*` variable is set
+ *                 without `SSH_JUMP_HOST`, or a typed value is malformed.
  */
-declare function loadHostProfile(): SshHostProfile | null;
+declare function loadHostProfile(env?: NodeJS.ProcessEnv): SshHostProfile | null;
 /** Strips every secret so the profile can be described back to the model. */
 declare function toHostSummary(profile: SshHostProfile): SshHostSummary;
 
@@ -495,7 +532,7 @@ declare const $logger: Logger;
 /** Env var overriding the stderr log level ("debug" | "info" | "warn" | "error" | "silent"). */
 declare const LOG_LEVEL_ENV = "SSH_MCP_LOG_LEVEL";
 declare const SERVER_NAME = "akms-mcp-ssh";
-declare const SERVER_VERSION = "0.0.3";
+declare const SERVER_VERSION = "0.1.0";
 
 /**
  * Environment variables that define the host, one MCP server entry per host.
@@ -520,6 +557,22 @@ declare const SINGLE_HOST_ENV: {
     readonly DESCRIPTION: "SSH_DESCRIPTION";
     /** Directory new sessions start in. */
     readonly CWD: "SSH_CWD";
+    /**
+     * Command whose stdin/stdout carry the SSH stream, like OpenSSH's `ProxyCommand`.
+     * `%h` / `%p` / `%r` expand to the first hop's host, port and user.
+     */
+    readonly PROXY_COMMAND: "SSH_PROXY_COMMAND";
+    /** Presence of this variable routes the connection through a jump host. */
+    readonly JUMP_HOST: "SSH_JUMP_HOST";
+    readonly JUMP_PORT: "SSH_JUMP_PORT";
+    /** Defaults to `SSH_USER`. */
+    readonly JUMP_USER: "SSH_JUMP_USER";
+    /** Path to the jump host's private key file; defaults to `SSH_KEY`. */
+    readonly JUMP_KEY: "SSH_JUMP_KEY";
+    readonly JUMP_PASSPHRASE: "SSH_JUMP_PASSPHRASE";
+    readonly JUMP_PASSWORD: "SSH_JUMP_PASSWORD";
+    /** Pinned jump host key, `SHA256:…`. */
+    readonly JUMP_HOST_KEY: "SSH_JUMP_HOST_KEY";
     readonly READONLY: "SSH_READONLY";
     readonly ALLOW_SUDO: "SSH_ALLOW_SUDO";
     /** Comma-separated binary names. */
@@ -534,4 +587,4 @@ declare const SINGLE_HOST_ENV: {
     readonly MAX_READ_FILE_BYTES: "SSH_MAX_READ_BYTES";
 };
 
-export { $logger, GuardRejectionError, type GuardVerdict, LOG_LEVEL_ENV, type LogLevel, type Logger, type RemoteDirectoryListing, type RemoteFileContent, type RemotePathAccess, SERVER_NAME, SERVER_VERSION, SINGLE_HOST_ENV, type SegmentAnalysis, SshConnection, type SshExecOptions, type SshExecResult, type SshHostProfile, type SshHostSummary, type SshMcpServerInstance, type SshPolicy, type SshRemoteEntry, SshSession, type SshSessionInfo, SshSessionManager, type ToolContext, analyzeSegment, canonicalizeCommand, createSshMcpServer, downloadFile, extractSubstitutions, inspectCommand, inspectLocalPath, inspectRemotePath, inspectWorkingDirectory, listRemoteDirectory, loadHostProfile, normalizeCommandText, readRemoteFile, registerAllTools, splitCommandSegments, stripQuotedText, toHostSummary, uploadFile, writeRemoteFile };
+export { $logger, GuardRejectionError, type GuardVerdict, LOG_LEVEL_ENV, type LogLevel, type Logger, type RemoteDirectoryListing, type RemoteFileContent, type RemotePathAccess, SERVER_NAME, SERVER_VERSION, SINGLE_HOST_ENV, type SegmentAnalysis, SshConnection, type SshExecOptions, type SshExecResult, type SshHostProfile, type SshHostSummary, type SshJumpProfile, type SshMcpServerInstance, type SshPolicy, type SshRemoteEntry, SshSession, type SshSessionInfo, SshSessionManager, type ToolContext, analyzeSegment, canonicalizeCommand, createSshMcpServer, downloadFile, extractSubstitutions, inspectCommand, inspectLocalPath, inspectRemotePath, inspectWorkingDirectory, listRemoteDirectory, loadHostProfile, normalizeCommandText, readRemoteFile, registerAllTools, splitCommandSegments, stripQuotedText, toHostSummary, uploadFile, writeRemoteFile };