@jalsoedesign/dockline-ssh-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dockline contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+[Documentation](https://h2ooooooo.github.io/dockline/ssh/quick-start) · [Source](https://github.com/h2ooooooo/dockline/tree/main/packages/ssh-client)
+
+# SSH commands
+
+`@jalsoedesign/dockline-ssh-client` provides scoped SSH command execution and SFTP transfers. It is independently installable; core, FTP and SFTP consumers do not need to install it.
+
+```sh
+npm install @jalsoedesign/dockline-ssh-client
+```
+
+This new workspace must be published before that registry command is available. Repository users can build it with `npm run build --workspace @jalsoedesign/dockline-ssh-client`.
+
+```ts
+import {SshClient} from '@jalsoedesign/dockline-ssh-client';
+
+const client = new SshClient({
+    host: 'server.example.com',
+    port: 22,
+    username: 'deployer',
+    privateKeyPath: '/home/me/.ssh/deployer',
+    hostFingerprint: process.env.SSH_HOST_FINGERPRINT,
+});
+
+await client.withConnection(async server => {
+    const result = await server.exec('uptime');
+
+    console.log(result.stdout);
+
+    await server.download({
+        sourceFile: '/var/backups/export.sql',
+        destinationFile: './backups/export.sql',
+    });
+
+    await server.exec('systemctl', ['restart', 'website'], {
+        sudo: true,
+        timeout: '1m',
+    });
+});
+```
+
+Without an explicit fingerprint or a supplied `trust(host, port, fingerprint)` callback, connections reject unknown hosts. The application owns trust persistence and any prompt UI. Supply optional `ask`, `log`, `signal` and `directory` callbacks/settings as the constructor's second argument. `ask` receives an input/password challenge and returns its answer. No CLI prompt implementation is bundled.
+
+`withConnection` authenticates and closes its connection in `finally`. Passwords, private-key passphrases, explicit SSH agents and keyboard-interactive authentication are supported. Agent forwarding is not enabled. An SFTP account does not necessarily have command-execution permission.
+
+## Command API
+
+- `exec(program, args?, options?)` quotes each argument for a POSIX remote shell.
+- `shell(command, options?)` explicitly executes `sh -c` for shell expressions.
+- `asUser(username, callback)` runs scoped commands through `sudo -u`.
+- `download({sourceFile, destinationFile, timeout?, maxBytes?})` uses a temporary local file before replacement.
+- `upload({sourceFile, destinationFile, timeout?, maxBytes?})` streams a local file using Dockline SFTP.
+
+Exec options include `timeout`, `sudo` (boolean or target username) and `allowFailure`. Results include `code`, `stdout` and `stderr`; returned output retains the last 1 MiB per stream while `log` receives streamed output. Nonzero exit codes reject by default. Timeouts accept positive milliseconds or strings such as `30s`, `5m` and `1h`; the default command/transfer deadline is one hour. Commands are never automatically retried.
+
+The transfer helpers open separate SFTP connections with the same resolved credentials and host verifier. They have no default byte cap. A transfer does not inherit sudo privileges: files created by privileged commands must be readable by the SFTP user.
+
+Sudo defaults to noninteractive mode. Set `sudo.password: 'prompt'` with an `ask` callback, or `sudo.passwordEnv`, when a password is required. Passwords travel through stdin when the sudo prompt appears, not command arguments. Servers requiring an interactive TTY are outside this API's initial scope.
+
+Cancellation requests command termination and closes channels. The remote server may ignore a signal; inspect remote state before retrying. Remote Windows shell syntax and persistent interactive `sudo su` sessions are not supported.
+
+See the [SSH package source](https://github.com/h2ooooooo/dockline/tree/main/packages/ssh-client).

package/dist/SshClient.d.ts

@@ -0,0 +1,58 @@
+import ssh2 from 'ssh2';
+import { type SshOptions, type Question } from './types.js';
+export interface ResolvedSsh extends SshOptions {
+    host: string;
+    port: number;
+    username: string;
+    password?: string;
+    passphrase?: string;
+}
+export interface ExecOptions {
+    timeout?: string | number;
+    sudo?: boolean | string;
+    allowFailure?: boolean;
+}
+export interface ExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface FileTransfer {
+    sourceFile: string;
+    destinationFile: string;
+    timeout?: string | number;
+    maxBytes?: number;
+}
+export interface SshServices {
+    resolve(options: SshOptions): Promise<ResolvedSsh>;
+    ask(question: Question): Promise<string | boolean>;
+    trust(host: string, port: number, fingerprint: string): Promise<boolean>;
+    log(message: string): void;
+    signal: AbortSignal;
+    directory: string;
+}
+export declare function quotePosix(value: string): string;
+export declare class SshSession {
+    private readonly client;
+    private readonly config;
+    private readonly services;
+    private readonly user?;
+    private readonly credentials;
+    constructor(client: ssh2.Client, config: ResolvedSsh, services: SshServices, user?: string | undefined, credentials?: {
+        sudoPassword?: string;
+    });
+    asUser<T>(user: string, callback: (session: SshSession) => Promise<T>): Promise<T>;
+    exec(program: string, args?: string[], options?: ExecOptions): Promise<ExecResult>;
+    shell(command: string, options?: ExecOptions): Promise<ExecResult>;
+    private execute;
+    private transfer;
+    download(options: FileTransfer): Promise<void>;
+    upload(options: FileTransfer): Promise<void>;
+}
+export declare class SshClient {
+    private readonly services;
+    constructor(config: ResolvedSsh, options?: Partial<Omit<SshServices, 'resolve'>>);
+    withConnection<T>(callback: (server: SshSession) => Promise<T>): Promise<T>;
+    withConnection<T>(options: SshOptions, callback: (server: SshSession) => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=SshClient.d.ts.map

package/dist/SshClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SshClient.d.ts","sourceRoot":"","sources":["../src/SshClient.ts"],"names":[],"mappings":"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"}

package/dist/SshClient.js

@@ -0,0 +1,256 @@
+import ssh2 from 'ssh2';
+const { Client } = ssh2;
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile, mkdir, rename, unlink } from 'node:fs/promises';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import path from 'node:path';
+import { SftpConnector } from '@jalsoedesign/dockline-sftp-client';
+import { homedir } from 'node:os';
+import { milliseconds } from './types.js';
+const absolutePath = (base, value) => path.resolve(base, value.startsWith('~/') ? path.join(homedir(), value.slice(2)) : value);
+export function quotePosix(value) {
+    if (value.includes('\0')) {
+        throw new Error('SSH arguments cannot contain NUL.');
+    }
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+export class SshSession {
+    client;
+    config;
+    services;
+    user;
+    credentials;
+    constructor(client, config, services, user, credentials = {}) {
+        this.client = client;
+        this.config = config;
+        this.services = services;
+        this.user = user;
+        this.credentials = credentials;
+    }
+    async asUser(user, callback) {
+        if (!/^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/.test(user)) {
+            throw new Error('Invalid sudo user.');
+        }
+        return callback(new SshSession(this.client, this.config, this.services, user, this.credentials));
+    }
+    exec(program, args = [], options = {}) {
+        return this.execute([program, ...args].map(quotePosix).join(' '), options);
+    }
+    shell(command, options = {}) {
+        return this.exec('sh', ['-c', command], options);
+    }
+    async execute(command, options) {
+        const sudoUser = typeof options.sudo === 'string' ? options.sudo : this.user;
+        const sudo = Boolean(options.sudo || sudoUser);
+        const marker = `DOCKLINE_SUDO_${randomUUID()}`;
+        let password;
+        if (sudo && (this.config.sudo?.password === 'prompt' || this.config.sudo?.passwordEnv)) {
+            password = this.config.sudo.passwordEnv ?
+                process.env[this.config.sudo.passwordEnv] : this.credentials.sudoPassword;
+            if (password === undefined && this.config.sudo.passwordEnv) {
+                throw new Error(`Missing sudo secret environment variable: ${this.config.sudo.passwordEnv}`);
+            }
+            password ??= String(await this.services.ask({
+                id: `sudo:${this.config.username}@${this.config.host}`,
+                type: 'password',
+                message: 'Sudo password',
+                required: true,
+            }));
+            this.credentials.sudoPassword = password;
+        }
+        if (sudo) {
+            command = `sudo ${password === undefined ? '-n' : `-S -p ${quotePosix(marker)}`} ${sudoUser ? `-u ${quotePosix(sudoUser)} ` : ''}-- ${command}`;
+        }
+        const timeout = AbortSignal.timeout(milliseconds(options.timeout ?? '1h'));
+        const signal = AbortSignal.any([this.services.signal, timeout]);
+        signal.throwIfAborted();
+        return new Promise((resolve, reject) => {
+            let channel;
+            let stdout = '';
+            let stderr = '';
+            let pending = '';
+            let sent = false;
+            const finish = (error, code = -1) => {
+                signal.removeEventListener('abort', abort);
+                this.client.removeListener('close', disconnected);
+                if (error) {
+                    reject(error);
+                }
+                else if (code !== 0 && !options.allowFailure) {
+                    reject(new Error(`SSH command exited with status ${code}. ${stderr.slice(-2000)}`));
+                }
+                else {
+                    resolve({ code, stdout, stderr });
+                }
+            };
+            const disconnected = () => finish(new Error('SSH connection closed before command completion. Remote process state is unknown.'));
+            const abort = () => {
+                try {
+                    channel?.signal('TERM');
+                }
+                catch { /* Server may reject signals. */ }
+                channel?.close();
+                finish(new Error('SSH command cancelled or timed out. The remote process may still be running.'));
+            };
+            signal.addEventListener('abort', abort, { once: true });
+            this.client.once('close', disconnected);
+            this.client.exec(command, (error, stream) => {
+                if (error) {
+                    finish(error);
+                    return;
+                }
+                channel = stream;
+                if (signal.aborted) {
+                    abort();
+                    return;
+                }
+                stream.on('error', finish);
+                stream.on('data', (chunk) => {
+                    const text = chunk.toString();
+                    stdout = (stdout + text).slice(-1024 * 1024);
+                    this.services.log(text);
+                });
+                stream.stderr.on('data', (chunk) => {
+                    pending += chunk.toString();
+                    if (password !== undefined && !sent) {
+                        if (!pending.includes(marker)) {
+                            if (pending.length < 8192) {
+                                return;
+                            }
+                        }
+                        else {
+                            pending = pending.replace(marker, '');
+                            stream.write(password + '\n');
+                            sent = true;
+                        }
+                    }
+                    stderr = (stderr + pending).slice(-1024 * 1024);
+                    this.services.log(pending);
+                    pending = '';
+                });
+                stream.on('close', (code) => {
+                    stderr = (stderr + pending.replaceAll(marker, '')).slice(-1024 * 1024);
+                    finish(undefined, typeof code === 'number' ? code : -1);
+                });
+            });
+        });
+    }
+    async transfer(options, upload) {
+        const signal = AbortSignal.any([this.services.signal, AbortSignal.timeout(milliseconds(options.timeout ?? '1h'))]);
+        const connector = new SftpConnector({
+            ...this.config,
+            initialPath: '',
+            abortSignal: signal,
+            hostVerifier: (key) => this.services.trust(this.config.host, this.config.port, 'SHA256:' + createHash('sha256').update(key).digest('base64').replace(/=+$/, '')),
+            keyboardInteractive: this.config.keyboardInteractive ? async (challenge) => Promise.all(challenge.prompts.map((prompt, index) => this.services.ask({ id: `ssh-challenge:${index}`, message: prompt.prompt, type: prompt.echo ? 'input' : 'password' }).then(String))) : undefined,
+        });
+        try {
+            await connector.connect();
+            if (upload) {
+                await connector.write(options.destinationFile, () => createReadStream(absolutePath(this.services.directory, options.sourceFile)), { abortSignal: signal, maxBytes: options.maxBytes });
+            }
+            else {
+                const destination = absolutePath(this.services.directory, options.destinationFile);
+                const temporary = `${destination}.dockline-${randomUUID()}`;
+                await mkdir(path.dirname(destination), { recursive: true });
+                try {
+                    const contents = await connector.read(options.sourceFile, {
+                        abortSignal: signal,
+                        maxBytes: options.maxBytes,
+                    });
+                    await pipeline(Buffer.isBuffer(contents) ? Readable.from([contents]) : contents, createWriteStream(temporary, { flags: 'wx', mode: 0o600 }), { signal });
+                    await rename(temporary, destination);
+                }
+                finally {
+                    await unlink(temporary).catch(() => { });
+                }
+            }
+        }
+        finally {
+            await connector.disconnect();
+        }
+    }
+    download(options) {
+        return this.transfer(options, false);
+    }
+    upload(options) {
+        return this.transfer(options, true);
+    }
+}
+export class SshClient {
+    services;
+    constructor(config, options = {}) {
+        this.services = {
+            directory: options.directory ?? process.cwd(),
+            signal: options.signal ?? new AbortController().signal,
+            log: options.log ?? (() => { }),
+            ask: options.ask ?? (async () => {
+                throw new Error('This operation requires a credential prompt callback.');
+            }),
+            trust: options.trust ?? (async () => false),
+            resolve: async (overrides) => {
+                const changed = (overrides.host && overrides.host !== config.host) || (overrides.port &&
+                    overrides.port !== config.port) || (overrides.username && overrides.username !== config.username);
+                return {
+                    ...config,
+                    ...(changed ? {
+                        password: undefined,
+                        passphrase: undefined,
+                        privateKeyPath: undefined,
+                        agent: undefined,
+                        hostFingerprint: undefined,
+                    } : {}),
+                    ...overrides,
+                };
+            },
+        };
+    }
+    async withConnection(options, callback) {
+        const config = await this.services.resolve(typeof options === 'function' ? {} : options);
+        const action = typeof options === 'function' ? options : callback;
+        const services = {
+            ...this.services,
+            trust: config.hostFingerprint ?
+                async (_host, _port, fingerprint) => fingerprint === config.hostFingerprint : this.services.trust,
+        };
+        const client = new Client();
+        const abort = () => client.destroy();
+        this.services.signal.addEventListener('abort', abort, { once: true });
+        try {
+            this.services.signal.throwIfAborted();
+            await new Promise((resolve, reject) => {
+                client.once('ready', resolve);
+                client.on('error', reject);
+                client.once('close', () => reject(new Error('SSH connection closed during authentication.')));
+                client.on('keyboard-interactive', (_name, _instructions, _language, prompts, finish) => {
+                    void Promise.all(prompts.map((prompt, index) => this.services.ask({ id: `ssh-challenge:${index}`, message: prompt.prompt, type: prompt.echo ? 'input' : 'password' }))).then(answers => finish(answers.map(String)), reject);
+                });
+                void (async () => {
+                    client.connect({
+                        host: config.host,
+                        port: config.port,
+                        username: config.username,
+                        password: config.password,
+                        privateKey: config.privateKeyPath ? await readFile(config.privateKeyPath) : undefined,
+                        passphrase: config.passphrase,
+                        agent: config.agent,
+                        tryKeyboard: config.keyboardInteractive,
+                        readyTimeout: 60000,
+                        hostVerifier: (key, verify) => {
+                            const fingerprint = 'SHA256:' + createHash('sha256').update(key).digest('base64').replace(/=+$/, '');
+                            void services.trust(config.host, config.port, fingerprint).then(verify, () => verify(false));
+                        },
+                    });
+                })().catch(reject);
+            });
+            return await action(new SshSession(client, config, services));
+        }
+        finally {
+            this.services.signal.removeEventListener('abort', abort);
+            client.destroy();
+        }
+    }
+}
+//# sourceMappingURL=SshClient.js.map

package/dist/SshClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SshClient.js","sourceRoot":"","sources":["../src/SshClient.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { SshClient, SshSession, quotePosix } from './SshClient.js';
+export type { ResolvedSsh, SshServices, ExecOptions, ExecResult, FileTransfer } from './SshClient.js';
+export type { SshOptions, Question } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAE,UAAU,EAAE,UAAU,EAAC,MAAM,gBAAgB,CAAC;AACjE,YAAY,EAAC,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAC,MAAM,gBAAgB,CAAC;AACpG,YAAY,EAAC,UAAU,EAAE,QAAQ,EAAC,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { SshClient, SshSession, quotePosix } from './SshClient.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAE,UAAU,EAAE,UAAU,EAAC,MAAM,gBAAgB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,23 @@
+export interface SshOptions {
+    password?: string;
+    passphrase?: string;
+    host?: string;
+    port?: number;
+    username?: string;
+    privateKeyPath?: string;
+    agent?: string;
+    keyboardInteractive?: boolean;
+    hostFingerprint?: string;
+    sudo?: {
+        password?: 'prompt' | 'none';
+        passwordEnv?: string;
+    };
+}
+export interface Question {
+    id: string;
+    message: string;
+    type: 'password' | 'input';
+    required?: boolean;
+}
+export declare function milliseconds(value: string | number): number;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE;QAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC;CAC/D;AACD,MAAM,WAAW,QAAQ;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AACD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAe3D"}

package/dist/types.js

@@ -0,0 +1,15 @@
+export function milliseconds(value) {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/.exec(String(value));
+    const scales = {
+        ms: 1,
+        s: 1000,
+        m: 60000,
+        h: 3600000,
+    };
+    const result = typeof value === 'number' ? value : match ? Number(match[1]) * scales[match[2]] : 0;
+    if (!Number.isFinite(result) || result <= 0 || result > 2147483647) {
+        throw new Error('Invalid positive timeout.');
+    }
+    return Math.ceil(result);
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAkBA,MAAM,UAAU,YAAY,CAAC,KAAsB;IAC/C,MAAM,KAAK,GAAG,6BAA6B,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAChE,MAAM,MAAM,GAA2B;QACnC,EAAE,EAAE,CAAC;QACL,CAAC,EAAE,IAAI;QACP,CAAC,EAAE,KAAK;QACR,CAAC,EAAE,OAAO;KACb,CAAC;IACF,MAAM,MAAM,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEnG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,MAAM,GAAG,UAAU,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IACjD,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "@jalsoedesign/dockline-ssh-client",
+    "version": "1.0.0",
+    "description": "SSH command execution, sudo scopes and file transfers for Dockline",
+    "type": "module",
+    "license": "MIT",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "require": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist",
+        "src",
+        "LICENSE",
+        "README.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "engines": {
+        "node": "^22.22.2 || ^24.15.0 || >=26.0.0",
+        "npm": ">=12.0.2"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/h2ooooooo/dockline.git",
+        "directory": "packages/ssh-client"
+    },
+    "homepage": "https://h2ooooooo.github.io/dockline/",
+    "bugs": {
+        "url": "https://github.com/h2ooooooo/dockline/issues"
+    },
+    "scripts": {
+        "build": "node ../../scripts/build.mjs --package ssh-client",
+        "test": "node ../../scripts/test-package.mjs ssh-client",
+        "typecheck": "tsc --noEmit -p tsconfig.json",
+        "prepack": "npm run build"
+    },
+    "dependencies": {
+        "@jalsoedesign/dockline-sftp-client": "^1.0.0",
+        "ssh2": "^1.17.0",
+        "@types/ssh2": "^1.15.6"
+    }
+}

package/src/SshClient.ts

@@ -0,0 +1,323 @@
+import ssh2, {type ClientChannel} from 'ssh2';
+
+const {Client} = ssh2;
+
+import {createHash, randomUUID} from 'node:crypto';
+import {readFile, mkdir, rename, unlink} from 'node:fs/promises';
+import {createReadStream, createWriteStream} from 'node:fs';
+import {Readable} from 'node:stream';
+import {pipeline} from 'node:stream/promises';
+import path from 'node:path';
+import {SftpConnector} from '@jalsoedesign/dockline-sftp-client';
+import {homedir} from 'node:os';
+import {milliseconds, type SshOptions, type Question} from './types.js';
+
+const absolutePath = (base: string, value: string) => path.resolve(base, value.startsWith('~/') ? path.join(homedir(), value.slice(2)) : value);
+
+export interface ResolvedSsh extends SshOptions {
+    host: string;
+    port: number;
+    username: string;
+    password?: string;
+    passphrase?: string;
+}
+export interface ExecOptions {
+    timeout?: string | number;
+    sudo?: boolean | string;
+    allowFailure?: boolean;
+}
+export interface ExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface FileTransfer {
+    sourceFile: string;
+    destinationFile: string;
+    timeout?: string | number;
+    maxBytes?: number;
+}
+export interface SshServices {
+    resolve(options: SshOptions): Promise<ResolvedSsh>;
+    ask(question: Question): Promise<string | boolean>;
+    trust(host: string, port: number, fingerprint: string): Promise<boolean>;
+    log(message: string): void;
+    signal: AbortSignal;
+    directory: string;
+}
+
+export function quotePosix(value: string): string {
+    if (value.includes('\0')) {
+        throw new Error('SSH arguments cannot contain NUL.');
+    }
+
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+export class SshSession {
+    public constructor(private readonly client: ssh2.Client, private readonly config: ResolvedSsh,
+        private readonly services: SshServices, private readonly user?: string,
+        private readonly credentials: {sudoPassword?: string} = {}) {}
+
+    public async asUser<T>(user: string, callback: (session: SshSession) => Promise<T>): Promise<T> {
+        if (!/^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/.test(user)) {
+            throw new Error('Invalid sudo user.');
+        }
+
+        return callback(new SshSession(this.client, this.config, this.services, user, this.credentials));
+    }
+
+    public exec(program: string, args: string[] = [], options: ExecOptions = {}): Promise<ExecResult> {
+        return this.execute([program, ...args].map(quotePosix).join(' '), options);
+    }
+
+    public shell(command: string, options: ExecOptions = {}): Promise<ExecResult> {
+        return this.exec('sh', ['-c', command], options);
+    }
+
+    private async execute(command: string, options: ExecOptions): Promise<ExecResult> {
+        const sudoUser = typeof options.sudo === 'string' ? options.sudo : this.user;
+        const sudo = Boolean(options.sudo || sudoUser);
+        const marker = `DOCKLINE_SUDO_${randomUUID()}`;
+        let password: string | undefined;
+
+        if (sudo && (this.config.sudo?.password === 'prompt' || this.config.sudo?.passwordEnv)) {
+            password = this.config.sudo.passwordEnv ?
+                process.env[this.config.sudo.passwordEnv] : this.credentials.sudoPassword;
+
+            if (password === undefined && this.config.sudo.passwordEnv) {
+                throw new Error(`Missing sudo secret environment variable: ${this.config.sudo.passwordEnv}`);
+            }
+
+            password ??= String(await this.services.ask({
+                id: `sudo:${this.config.username}@${this.config.host}`,
+                type: 'password',
+                message: 'Sudo password',
+                required: true,
+            }));
+            this.credentials.sudoPassword = password;
+        }
+
+        if (sudo) {
+            command = `sudo ${password === undefined ? '-n' : `-S -p ${quotePosix(marker)}`} ${sudoUser ? `-u ${quotePosix(sudoUser)} ` : ''}-- ${command}`;
+        }
+
+        const timeout = AbortSignal.timeout(milliseconds(options.timeout ?? '1h'));
+        const signal = AbortSignal.any([this.services.signal, timeout]);
+
+        signal.throwIfAborted();
+
+        return new Promise<ExecResult>((resolve, reject) => {
+            let channel: ClientChannel | undefined;
+            let stdout = '';
+            let stderr = '';
+            let pending = '';
+            let sent = false;
+            const finish = (error?: Error, code = -1) => {
+                signal.removeEventListener('abort', abort);
+                this.client.removeListener('close', disconnected);
+
+                if (error) {
+                    reject(error);
+                } else if (code !== 0 && !options.allowFailure) {
+                    reject(new Error(`SSH command exited with status ${code}. ${stderr.slice(-2000)}`));
+                } else {
+                    resolve({code, stdout, stderr});
+                }
+            };
+            const disconnected = () => finish(new Error('SSH connection closed before command completion. Remote process state is unknown.'));
+            const abort = () => {
+                try {
+                    channel?.signal('TERM');
+                } catch { /* Server may reject signals. */ }
+
+                channel?.close();
+                finish(new Error('SSH command cancelled or timed out. The remote process may still be running.'));
+            };
+
+            signal.addEventListener('abort', abort, {once: true});
+            this.client.once('close', disconnected);
+            this.client.exec(command, (error, stream) => {
+                if (error) {
+                    finish(error);
+
+                    return;
+                }
+
+                channel = stream;
+
+                if (signal.aborted) {
+                    abort();
+
+                    return;
+                }
+
+                stream.on('error', finish);
+                stream.on('data', (chunk: Buffer) => {
+                    const text = chunk.toString();
+
+                    stdout = (stdout + text).slice(-1024 * 1024);
+                    this.services.log(text);
+                });
+                stream.stderr.on('data', (chunk: Buffer) => {
+                    pending += chunk.toString();
+
+                    if (password !== undefined && !sent) {
+                        if (!pending.includes(marker)) {
+                            if (pending.length < 8192) {
+                                return;
+                            }
+                        } else {
+                            pending = pending.replace(marker, '');
+                            stream.write(password + '\n');
+                            sent = true;
+                        }
+                    }
+
+                    stderr = (stderr + pending).slice(-1024 * 1024);
+                    this.services.log(pending);
+                    pending = '';
+                });
+                stream.on('close', (code: number) => {
+                    stderr = (stderr + pending.replaceAll(marker, '')).slice(-1024 * 1024);
+                    finish(undefined, typeof code === 'number' ? code : -1);
+                });
+            });
+        });
+    }
+
+    private async transfer(options: FileTransfer, upload: boolean): Promise<void> {
+        const signal = AbortSignal.any([this.services.signal, AbortSignal.timeout(milliseconds(options.timeout ?? '1h'))]);
+        const connector = new SftpConnector({
+            ...this.config,
+            initialPath: '',
+            abortSignal: signal,
+            hostVerifier: (key: Buffer) => this.services.trust(this.config.host, this.config.port, 'SHA256:' + createHash('sha256').update(key).digest('base64').replace(/=+$/, '')),
+            keyboardInteractive: this.config.keyboardInteractive ? async challenge => Promise.all(challenge.prompts.map((prompt, index) => this.services.ask({id: `ssh-challenge:${index}`, message: prompt.prompt, type: prompt.echo ? 'input' : 'password'}).then(String))) : undefined,
+        });
+
+        try {
+            await connector.connect();
+
+            if (upload) {
+                await connector.write(options.destinationFile,
+                    () => createReadStream(absolutePath(this.services.directory, options.sourceFile)),
+                    {abortSignal: signal, maxBytes: options.maxBytes});
+            } else {
+                const destination = absolutePath(this.services.directory, options.destinationFile);
+                const temporary = `${destination}.dockline-${randomUUID()}`;
+
+                await mkdir(path.dirname(destination), {recursive: true});
+
+                try {
+                    const contents = await connector.read(options.sourceFile, {
+                        abortSignal: signal,
+                        maxBytes: options.maxBytes,
+                    });
+
+                    await pipeline(Buffer.isBuffer(contents) ? Readable.from([contents]) : contents as Readable, createWriteStream(temporary, {flags: 'wx', mode: 0o600}), {signal});
+                    await rename(temporary, destination);
+                } finally {
+                    await unlink(temporary).catch(() => {});
+                }
+            }
+        } finally {
+            await connector.disconnect();
+        }
+    }
+
+    public download(options: FileTransfer): Promise<void> {
+        return this.transfer(options, false);
+    }
+
+    public upload(options: FileTransfer): Promise<void> {
+        return this.transfer(options, true);
+    }
+}
+
+export class SshClient {
+    private readonly services: SshServices;
+
+    public constructor(config: ResolvedSsh, options: Partial<Omit<SshServices, 'resolve'>> = {}) {
+        this.services = {
+            directory: options.directory ?? process.cwd(),
+            signal: options.signal ?? new AbortController().signal,
+            log: options.log ?? (() => {}),
+            ask: options.ask ?? (async () => {
+                throw new Error('This operation requires a credential prompt callback.');
+            }),
+            trust: options.trust ?? (async () => false),
+            resolve: async overrides => {
+                const changed = (overrides.host && overrides.host !== config.host) || (overrides.port &&
+                    overrides.port !== config.port) || (overrides.username && overrides.username !== config.username);
+
+                return {
+                    ...config,
+                    ...(changed ? {
+                        password: undefined,
+                        passphrase: undefined,
+                        privateKeyPath: undefined,
+                        agent: undefined,
+                        hostFingerprint: undefined,
+                    } : {}),
+                    ...overrides,
+                };
+            },
+        };
+    }
+
+    public withConnection<T>(callback: (server: SshSession) => Promise<T>): Promise<T>;
+    public withConnection<T>(options: SshOptions, callback: (server: SshSession) => Promise<T>): Promise<T>;
+    public async withConnection<T>(
+        options: SshOptions | ((server: SshSession) => Promise<T>),
+        callback?: (server: SshSession) => Promise<T>,
+    ): Promise<T> {
+        const config = await this.services.resolve(typeof options === 'function' ? {} : options);
+        const action = typeof options === 'function' ? options : callback!;
+        const services: SshServices = {
+            ...this.services,
+            trust: config.hostFingerprint ?
+                async (_host, _port, fingerprint) => fingerprint === config.hostFingerprint : this.services.trust,
+        };
+        const client = new Client();
+        const abort = () => client.destroy();
+
+        this.services.signal.addEventListener('abort', abort, {once: true});
+
+        try {
+            this.services.signal.throwIfAborted();
+            await new Promise<void>((resolve, reject) => {
+                client.once('ready', resolve);
+                client.on('error', reject);
+                client.once('close', () => reject(new Error('SSH connection closed during authentication.')));
+                client.on('keyboard-interactive', (_name, _instructions, _language, prompts, finish) => {
+                    void Promise.all(prompts.map((prompt, index) => this.services.ask({id: `ssh-challenge:${index}`, message: prompt.prompt, type: prompt.echo ? 'input' : 'password'}))).then(answers => finish(answers.map(String)), reject);
+                });
+                void (async () => {
+                    client.connect({
+                        host: config.host,
+                        port: config.port,
+                        username: config.username,
+                        password: config.password,
+                        privateKey: config.privateKeyPath ? await readFile(config.privateKeyPath) : undefined,
+                        passphrase: config.passphrase,
+                        agent: config.agent,
+                        tryKeyboard: config.keyboardInteractive,
+                        readyTimeout: 60000,
+                        hostVerifier: (key: Buffer, verify: (accepted: boolean) => void) => {
+                            const fingerprint = 'SHA256:' + createHash('sha256').update(key).digest('base64').replace(/=+$/, '');
+
+                            void services.trust(config.host, config.port, fingerprint).then(verify,
+                                () => verify(false));
+                        },
+                    });
+                })().catch(reject);
+            });
+
+            return await action(new SshSession(client, config, services));
+        } finally {
+            this.services.signal.removeEventListener('abort', abort);
+            client.destroy();
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export {SshClient, SshSession, quotePosix} from './SshClient.js';
+export type {ResolvedSsh, SshServices, ExecOptions, ExecResult, FileTransfer} from './SshClient.js';
+export type {SshOptions, Question} from './types.js';

package/src/types.ts

@@ -0,0 +1,34 @@
+export interface SshOptions {
+    password?: string;
+    passphrase?: string;
+    host?: string;
+    port?: number;
+    username?: string;
+    privateKeyPath?: string;
+    agent?: string;
+    keyboardInteractive?: boolean;
+    hostFingerprint?: string;
+    sudo?: {password?: 'prompt' | 'none'; passwordEnv?: string};
+}
+export interface Question {
+    id: string;
+    message: string;
+    type: 'password' | 'input';
+    required?: boolean;
+}
+export function milliseconds(value: string | number): number {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/.exec(String(value));
+    const scales: Record<string, number> = {
+        ms: 1,
+        s: 1000,
+        m: 60000,
+        h: 3600000,
+    };
+    const result = typeof value === 'number' ? value : match ? Number(match[1]) * scales[match[2]] : 0;
+
+    if (!Number.isFinite(result) || result <= 0 || result > 2147483647) {
+        throw new Error('Invalid positive timeout.');
+    }
+
+    return Math.ceil(result);
+}