@x12i/ssh

Generic SSH client for Node.js (password or key). Pooled ssh2 connections with exec, sudo, SFTP, streaming, and automatic secret redaction.

Not tied to any product, VPN, or host topology. You pass hosts and credentials; the library never prints them.

Install

npm install @x12i/ssh

Usage

import { SshService, hostConfigFromEnv } from "@x12i/ssh";

const ssh = new SshService({
  hosts: {
    box: hostConfigFromEnv(), // SSH_HOST, SSH_USER, SSH_PASSWORD, …
  },
});

const ping = await ssh.ping("box");
const result = await ssh.exec("box", "uname -a");
await ssh.exec("box", "systemctl status ssh", { sudo: true });
await ssh.upload("box", "./local.sh", "/tmp/local.sh");
await ssh.download("box", "/etc/os-release", "./os-release");

for await (const event of await ssh.stream("box", "journalctl -n 20")) {
  if (event.type === "stdout") process.stdout.write(event.data);
}

await ssh.dispose();

Credentials can also be passed explicitly:

new SshService({
  hosts: {
    box: {
      host: "203.0.113.10",
      port: 22,
      username: "deploy",
      password: process.env.SSH_PASSWORD,
      // or privateKey / passphrase
    },
  },
  hostKeyPolicy: "tofu", // "strict" | "tofu" | "insecure"
});

hostConfigFromEnv() reads SSH_HOST, SSH_USER (or SSH_USERNAME), SSH_PORT, SSH_PASSWORD (or SSH_PASS), SSH_PRIVATE_KEY, SSH_PASSPHRASE, SSH_SUDO_PASSWORD. It never logs those values.

API

| Method | Purpose | |---|---| | exec(id, command, opts?) | Run a command; { sudo, cwd, env, timeoutMs } | | stream(id, command, opts?) | Async iterable stdout/stderr/exit | | upload / download / uploadBuffer | SFTP | | runScript(id, localPath, opts?) | Upload, run, optional cleanup | | ping(id) | Auth probe | | dispose() | Close the pool | | redact(text) | Strip known secrets from a string |

Host keys: default policy is trust-on-first-use, stored under ~/.x12i/ssh/known_hosts. Passwords, sudo passwords, passphrases, and private key material are redacted from errors and command output.

License

UNLICENSED — x12i