scp-next 1.0.20 → 1.1.2

package/dist/index.cjs

@@ -35,6 +35,7 @@ __export(src_exports, {
   ConnectionError: () => ConnectionError,
   FileSystemError: () => FileSystemError,
   HostVerificationError: () => HostVerificationError,
+  RemoteCommandError: () => RemoteCommandError,
   ScpNextClientImpl: () => ScpNextClientImpl,
   ScpNextError: () => ScpNextError,
   TransferError: () => TransferError,
@@ -52,7 +53,6 @@ var import_promises6 = require("fs/promises");
 var import_node_path4 = __toESM(require("path"), 1);
 
 // src/client/transport.ts
-var import_promises3 = require("fs/promises");
 var import_ssh2_sftp_client = __toESM(require("ssh2-sftp-client"), 1);
 
 // src/security/redact.ts
@@ -67,6 +67,8 @@ var SENSITIVE_KEYS = [
   "secret"
 ];
 var PRIVATE_KEY_PATTERN = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g;
+var SECRET_OPTION_PATTERN = /(--(?:password|passphrase|token|secret|authorization|credential)(?:=|\s+))(?:"[^"]*"|'[^']*'|\S+)/gi;
+var SECRET_ASSIGNMENT_PATTERN = /(\b(?:password|passphrase|token|secret|authorization|credential)[A-Z0-9_-]*\s*=\s*)(?:"[^"]*"|'[^']*'|[^\s&]+)/gi;
 function isSensitiveKey(key) {
   const normalized = key.replace(/[-_\s]/g, "").toLowerCase();
   return SENSITIVE_KEYS.some((sensitive) => normalized.includes(sensitive));
@@ -90,9 +92,34 @@ function redactSensitiveValues(value) {
 }
 function formatErrorMessage(error) {
   if (error instanceof Error) {
-    return String(redactSensitiveValues(error.message));
+    return redactKnownSensitiveValues(error.message, {});
+  }
+  return redactKnownSensitiveValues(String(error), {});
+}
+function redactKnownSensitiveValues(text, source) {
+  const sensitiveValues = collectSensitiveValues(source);
+  const redactedKnownValues = sensitiveValues.reduce(
+    (redacted, value) => redacted.split(value).join("[REDACTED]"),
+    String(redactSensitiveValues(text))
+  );
+  return redactedKnownValues.replace(SECRET_OPTION_PATTERN, "$1[REDACTED]").replace(SECRET_ASSIGNMENT_PATTERN, "$1[REDACTED]");
+}
+function collectSensitiveValues(value, key = "") {
+  if (isSensitiveKey(key)) {
+    if (typeof value === "string" && value) {
+      return [value];
+    }
+    if (Buffer.isBuffer(value) && value.length > 0) {
+      return [value.toString("utf8")];
+    }
+    return [];
+  }
+  if (!value || typeof value !== "object") {
+    return [];
   }
-  return String(redactSensitiveValues(error));
+  return Object.entries(value).flatMap(
+    ([nestedKey, nestedValue]) => collectSensitiveValues(nestedValue, nestedKey)
+  );
 }
 
 // src/errors/index.ts
@@ -131,6 +158,23 @@ var TransferError = class extends ScpNextError {
     super(message, { ...options, code: "SCP_NEXT_TRANSFER_ERROR" });
   }
 };
+var RemoteCommandError = class extends ScpNextError {
+  exitCode;
+  signal;
+  stdout;
+  stderr;
+  constructor(message, options) {
+    super(message, {
+      code: "SCP_NEXT_REMOTE_COMMAND_ERROR",
+      ...options.cause !== void 0 ? { cause: options.cause } : {},
+      ...options.context !== void 0 ? { context: options.context } : {}
+    });
+    this.exitCode = options.exitCode;
+    this.signal = options.signal;
+    this.stdout = options.stdout ?? "";
+    this.stderr = options.stderr ?? "";
+  }
+};
 var FileSystemError = class extends ScpNextError {
   constructor(message, options = {}) {
     super(message, { ...options, code: "SCP_NEXT_FILESYSTEM_ERROR" });
@@ -159,6 +203,9 @@ function toScpNextError(error) {
   return new TransferError(String(redactSensitiveValues(message)), { cause: error });
 }
 
+// src/client/ssh-options.ts
+var import_promises3 = require("fs/promises");
+
 // src/security/host-verification.ts
 var import_node_crypto = require("crypto");
 var import_promises2 = require("fs/promises");
@@ -316,6 +363,34 @@ function createHostVerifier(allowedFingerprints) {
   };
 }
 
+// src/client/ssh-options.ts
+async function createSshConnectOptions(options) {
+  const connectOptions = {};
+  if (options.host !== void 0) connectOptions.host = options.host;
+  if (options.port !== void 0) connectOptions.port = options.port;
+  if (options.username !== void 0) connectOptions.username = options.username;
+  if (options.password !== void 0) connectOptions.password = options.password;
+  if (options.privateKey !== void 0) {
+    connectOptions.privateKey = options.privateKey;
+  } else if (options.privateKeyFile) {
+    connectOptions.privateKey = await (0, import_promises3.readFile)(
+      expandHome(options.privateKeyFile),
+      "utf8"
+    );
+  }
+  if (options.passphrase !== void 0) connectOptions.passphrase = options.passphrase;
+  const agent = options.agent ?? process.env.SSH_AUTH_SOCK;
+  if (agent !== void 0) connectOptions.agent = agent;
+  if (options.timeout !== void 0) connectOptions.readyTimeout = options.timeout;
+  const allowedFingerprints = await resolveAllowedFingerprints(options);
+  const hostVerifier = createHostVerifier(allowedFingerprints);
+  if (hostVerifier) {
+    connectOptions.hostHash = "sha256";
+    connectOptions.hostVerifier = hostVerifier;
+  }
+  return connectOptions;
+}
+
 // src/client/transport.ts
 function toRemoteFileInfo(info) {
   return {
@@ -334,28 +409,7 @@ var Ssh2SftpTransport = class {
     });
   }
   async connect(options) {
-    const allowedFingerprints = await resolveAllowedFingerprints(options);
-    const hostVerifier = createHostVerifier(allowedFingerprints);
-    const connectOptions = {};
-    if (options.host !== void 0) connectOptions.host = options.host;
-    if (options.port !== void 0) connectOptions.port = options.port;
-    if (options.username !== void 0) connectOptions.username = options.username;
-    if (options.password !== void 0) connectOptions.password = options.password;
-    if (options.privateKey !== void 0) {
-      connectOptions.privateKey = options.privateKey;
-    } else if (options.privateKeyFile) {
-      connectOptions.privateKey = await (0, import_promises3.readFile)(expandHome(options.privateKeyFile), "utf8");
-    }
-    if (options.passphrase !== void 0) connectOptions.passphrase = options.passphrase;
-    const agent = options.agent ?? process.env.SSH_AUTH_SOCK;
-    if (agent !== void 0) {
-      connectOptions.agent = agent;
-    }
-    if (options.timeout !== void 0) connectOptions.readyTimeout = options.timeout;
-    if (hostVerifier) {
-      connectOptions.hostHash = "sha256";
-      connectOptions.hostVerifier = hostVerifier;
-    }
+    const connectOptions = await createSshConnectOptions(options);
     try {
       await this.client.connect(connectOptions);
     } catch (error) {
@@ -452,6 +506,210 @@ function hostVerificationTroubleshooting(host) {
   ].join("\n");
 }
 
+// src/client/command-executor.ts
+var import_ssh2 = require("ssh2");
+var SshCommandExecutor = class {
+  client;
+  connected = false;
+  closed = true;
+  constructor(client = new import_ssh2.Client()) {
+    this.client = client;
+    this.client.on("error", () => {
+      this.connected = false;
+    });
+    this.client.on("close", () => {
+      this.connected = false;
+      this.closed = true;
+    });
+  }
+  async connect(options) {
+    const connectOptions = await createSshConnectOptions(options);
+    this.closed = false;
+    await new Promise((resolve, reject) => {
+      const onReady = () => {
+        cleanup();
+        this.connected = true;
+        resolve();
+      };
+      const onError = (error) => {
+        cleanup();
+        this.connected = false;
+        this.closed = true;
+        try {
+          this.client.end();
+        } catch {
+        }
+        const converted = toScpNextError(error);
+        if (converted instanceof HostVerificationError) {
+          reject(converted);
+          return;
+        }
+        reject(
+          new ConnectionError(
+            `Unable to connect command executor to SSH server: ${formatErrorMessage(error)}`,
+            {
+              cause: error,
+              context: {
+                host: options.host,
+                port: options.port,
+                username: options.username
+              }
+            }
+          )
+        );
+      };
+      const onClose = () => {
+        cleanup();
+        reject(new ConnectionError("SSH connection closed before it was ready."));
+      };
+      const cleanup = () => {
+        this.client.off("ready", onReady);
+        this.client.off("error", onError);
+        this.client.off("close", onClose);
+      };
+      this.client.once("ready", onReady);
+      this.client.once("error", onError);
+      this.client.once("close", onClose);
+      try {
+        this.client.connect(connectOptions);
+      } catch (error) {
+        cleanup();
+        this.closed = true;
+        reject(
+          new ConnectionError(
+            `Unable to start SSH connection: ${formatErrorMessage(error)}`
+          )
+        );
+      }
+    });
+  }
+  async exec(command, options = {}) {
+    if (!this.connected) {
+      throw new ConnectionError("Command executor is not connected.");
+    }
+    return new Promise((resolve, reject) => {
+      try {
+        this.client.exec(command, (error, stream) => {
+          if (error) {
+            reject(
+              new RemoteCommandError("Unable to start remote command.", {
+                exitCode: null
+              })
+            );
+            return;
+          }
+          collectCommandResult(command, stream, options, resolve, reject);
+        });
+      } catch (error) {
+        reject(
+          new ConnectionError(
+            `Unable to start remote command: ${formatErrorMessage(error)}`
+          )
+        );
+      }
+    });
+  }
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.connected = false;
+    await new Promise((resolve) => {
+      this.client.once("close", resolve);
+      this.client.end();
+    });
+  }
+};
+function collectCommandResult(command, stream, options, resolve, reject) {
+  let stdout = "";
+  let stderr = "";
+  let outputBytes = 0;
+  let settled = false;
+  const maxBuffer = options.maxBuffer ?? 10 * 1024 * 1024;
+  const cleanup = () => {
+    if (timer) clearTimeout(timer);
+    stream.off("data", onStdoutData);
+    stream.stderr.off("data", onStderrData);
+    stream.off("close", onClose);
+    stream.off("error", onStreamError);
+    stream.stderr.off("error", onStreamError);
+  };
+  const fail = (error) => {
+    if (settled) return;
+    settled = true;
+    cleanup();
+    try {
+      stream.close();
+    } catch {
+    }
+    reject(error);
+  };
+  const appendOutput = (target, chunk) => {
+    outputBytes += Buffer.byteLength(chunk);
+    if (outputBytes > maxBuffer) {
+      fail(
+        new RemoteCommandError(
+          `Remote command output exceeded maxBuffer of ${maxBuffer} bytes.`,
+          {
+            exitCode: null,
+            stdout,
+            stderr
+          }
+        )
+      );
+      return;
+    }
+    if (target === "stdout") stdout += chunk;
+    else stderr += chunk;
+  };
+  const onStreamError = () => {
+    fail(
+      new RemoteCommandError("Remote command stream failed.", {
+        exitCode: null,
+        stdout,
+        stderr
+      })
+    );
+  };
+  const onStdoutData = (chunk) => {
+    appendOutput("stdout", chunk);
+  };
+  const onStderrData = (chunk) => {
+    appendOutput("stderr", chunk);
+  };
+  const onClose = (exitCode, signal) => {
+    if (settled) return;
+    settled = true;
+    cleanup();
+    resolve({
+      command,
+      stdout,
+      stderr,
+      exitCode: typeof exitCode === "number" ? exitCode : null,
+      ...signal ? { signal } : {}
+    });
+  };
+  const timer = options.timeout === void 0 ? void 0 : setTimeout(() => {
+    fail(
+      new RemoteCommandError(
+        `Remote command timed out after ${options.timeout} ms.`,
+        {
+          exitCode: null,
+          stdout,
+          stderr
+        }
+      )
+    );
+  }, options.timeout);
+  stream.setEncoding("utf8");
+  stream.stderr.setEncoding("utf8");
+  stream.on("data", onStdoutData);
+  stream.stderr.on("data", onStderrData);
+  stream.once("error", onStreamError);
+  stream.stderr.once("error", onStreamError);
+  stream.once("close", onClose);
+}
+
 // src/client/walk.ts
 var import_promises4 = require("fs/promises");
 var import_node_path3 = __toESM(require("path"), 1);
@@ -536,6 +794,33 @@ async function walkRemoteFiles(transport, rootPath) {
 
 // src/config/validation.ts
 var import_promises5 = require("fs/promises");
+
+// src/config/post-upload-commands.ts
+function isPostUploadCommands(value) {
+  return Array.isArray(value) && value.every(
+    (command) => typeof command === "string" && command.trim().length > 0
+  );
+}
+function getPostUploadCommands(source) {
+  const commands = readPostUploadCommands(source);
+  if (commands === void 0) {
+    return void 0;
+  }
+  if (!isPostUploadCommands(commands)) {
+    throw new ValidationError(
+      "postUploadCommands must be an array of non-empty command strings."
+    );
+  }
+  return commands;
+}
+function readPostUploadCommands(source) {
+  if (typeof source !== "object" || source === null) {
+    return void 0;
+  }
+  return source.postUploadCommands;
+}
+
+// src/config/validation.ts
 function validatePort(port) {
   if (port === void 0) {
     return;
@@ -591,6 +876,7 @@ async function validateUploadOptions(options) {
   }
   assertRemotePath(options.remotePath, "remotePath");
   validateTimeout(options.timeout);
+  getPostUploadCommands(options);
   await assertLocalPathExists(options.localPath);
   if (!options.dryRun) {
     await validateServerOptions(options);
@@ -605,6 +891,9 @@ async function validateDownloadOptions(options) {
   }
   assertRemotePath(options.remotePath, "remotePath");
   validateTimeout(options.timeout);
+  if (getPostUploadCommands(options)?.length) {
+    throw new ValidationError("Post-upload commands are not supported for downloads.");
+  }
   await assertDownloadDestination(options.localPath, options.createDirectories ?? true);
   if (!options.dryRun) {
     await validateServerOptions(options);
@@ -659,10 +948,13 @@ async function ensureLocalDirectory(localPath, createParents = false) {
 var ScpNextClientImpl = class {
   serverOptions;
   transport;
+  commandExecutor;
   connected = false;
+  commandExecutorConnected = false;
   constructor(serverOptions, dependencies = {}) {
     this.serverOptions = serverOptions;
     this.transport = dependencies.transport ?? new Ssh2SftpTransport();
+    this.commandExecutor = dependencies.commandExecutor ?? new SshCommandExecutor();
   }
   async connect() {
     await validateServerOptions(this.serverOptions);
@@ -677,10 +969,15 @@ var ScpNextClientImpl = class {
     };
     await validateUploadOptions(uploadOptions);
     if (options.dryRun) {
-      return;
+      return [];
     }
     await this.ensureConnected();
     await this.uploadWithTransport(uploadOptions);
+    const results = [];
+    for (const command of getPostUploadCommands(options) ?? []) {
+      results.push(await this.exec(command));
+    }
+    return results;
   }
   async download(remotePath, localPath, options = {}) {
     const downloadOptions = {
@@ -695,10 +992,57 @@ var ScpNextClientImpl = class {
     await this.ensureConnected();
     await this.downloadWithTransport(downloadOptions);
   }
+  async exec(command, options = {}) {
+    if (typeof command !== "string" || !command.trim()) {
+      throw new ValidationError("Remote command must not be empty.");
+    }
+    if (options.timeout !== void 0 && (!Number.isFinite(options.timeout) || options.timeout <= 0)) {
+      throw new ValidationError("Command timeout must be a positive number.");
+    }
+    if (options.maxBuffer !== void 0 && (!Number.isInteger(options.maxBuffer) || options.maxBuffer <= 0)) {
+      throw new ValidationError("Command maxBuffer must be a positive integer.");
+    }
+    if (options.failOnStderr !== void 0 && typeof options.failOnStderr !== "boolean") {
+      throw new ValidationError("Command failOnStderr must be a boolean.");
+    }
+    await this.ensureCommandExecutorConnected();
+    let result;
+    try {
+      result = await this.commandExecutor.exec(command, options);
+    } catch (error) {
+      if (error instanceof RemoteCommandError) {
+        throw new RemoteCommandError(error.message, {
+          exitCode: error.exitCode,
+          signal: error.signal,
+          stdout: redactKnownSensitiveValues(error.stdout, this.serverOptions),
+          stderr: redactKnownSensitiveValues(error.stderr, this.serverOptions)
+        });
+      }
+      throw error;
+    }
+    if (result.exitCode !== 0 || options.failOnStderr && result.stderr.length > 0) {
+      const reason = result.exitCode === null ? "Remote command ended without an exit code." : result.exitCode !== 0 ? `Remote command failed with exit code ${String(result.exitCode)}.` : "Remote command wrote to stderr.";
+      throw new RemoteCommandError(reason, {
+        exitCode: result.exitCode,
+        signal: result.signal,
+        stdout: redactKnownSensitiveValues(result.stdout, this.serverOptions),
+        stderr: redactKnownSensitiveValues(result.stderr, this.serverOptions)
+      });
+    }
+    return result;
+  }
   async close() {
-    if (this.connected) {
-      await this.transport.close();
-      this.connected = false;
+    const closures = [];
+    if (this.connected) closures.push(this.transport.close());
+    if (this.commandExecutorConnected) closures.push(this.commandExecutor.close());
+    const results = await Promise.allSettled(closures);
+    this.connected = false;
+    this.commandExecutorConnected = false;
+    const failure = results.find(
+      (result) => result.status === "rejected"
+    );
+    if (failure) {
+      throw failure.reason;
     }
   }
   async ensureConnected() {
@@ -706,6 +1050,13 @@ var ScpNextClientImpl = class {
       await this.connect();
     }
   }
+  async ensureCommandExecutorConnected() {
+    if (!this.commandExecutorConnected) {
+      await validateServerOptions(this.serverOptions);
+      await this.commandExecutor.connect(this.serverOptions);
+      this.commandExecutorConnected = true;
+    }
+  }
   async uploadWithTransport(options) {
     const localKind = await getLocalPathKind(options.localPath);
     const remotePath = normalizeRemotePath(options.remotePath);
@@ -984,11 +1335,18 @@ function createClient(options) {
 // src/client/upload.ts
 async function upload(options) {
   const client = new ScpNextClientImpl(options);
+  let result;
   try {
-    await client.upload(options.localPath, options.remotePath, options);
-  } finally {
-    await client.close();
+    result = await client.upload(options.localPath, options.remotePath, options);
+  } catch (error) {
+    try {
+      await client.close();
+    } catch {
+    }
+    throw error;
   }
+  await client.close();
+  return result;
 }
 
 // src/client/download.ts
@@ -1033,6 +1391,7 @@ async function copy(options) {
   ConnectionError,
   FileSystemError,
   HostVerificationError,
+  RemoteCommandError,
   ScpNextClientImpl,
   ScpNextError,
   TransferError,