scp-next 1.0.4 → 1.0.6

package/README.md

@@ -13,8 +13,7 @@
 [module-image]: https://img.shields.io/badge/module-ESM%20%2B%20CJS-blue
 
 `scp-next` is an SCP-style command-line tool and library for secure file transfers over SSH.
-The package uses SFTP internally through `ssh2-sftp-client` instead of implementing SCP or
-SFTP protocols manually.
+The package uses SFTP internally through `ssh2-sftp-client` instead of implementing SCP or SFTP protocols manually.
 
 ## Features
 
@@ -45,6 +44,9 @@ scp-next run <job> [source] [destination] [options]
 CLI commands use `<source> <destination>`. Programmatic upload and download APIs use
 `localPath` and `remotePath`.
 
+Destination paths follow familiar `cp`/`scp` behavior. If the destination exists as a directory or ends with a path separator, `scp-next` places the source inside that directory using the source basename.
+Use `--create-directories` when a destination directory may be missing.
+
 ## Upload Examples
 
 ```bash
@@ -66,9 +68,8 @@ scp-next upload ./dist /var/www/example \
   --recursive
 ```
 
-Password arguments are convenient, but they may be exposed through shell history and process
-listings. Prefer `SCP_NEXT_PASSWORD`, SSH agents, or protected private-key files for shared
-or production environments.
+Password arguments are convenient, but they may be exposed through shell history and process listings.
+Prefer `SCP_NEXT_PASSWORD`, SSH agents, or protected private-key files for shared or production environments.
 
 ## Download Examples
 
@@ -248,8 +249,7 @@ Highest to lowest:
 6. Configured job values
 7. Internal defaults
 
-For `run`, job values are loaded first, then root configuration, selected profile,
-environment variables, explicit positional overrides, and CLI options.
+For `run`, job values are loaded first, then root configuration, selected profile, environment variables, explicit positional overrides, and CLI options.
 
 ## Library Usage
 
@@ -322,23 +322,17 @@ Supported methods:
 
 ## Host Verification
 
-`hostFingerprint` compares the server host key SHA-256 fingerprint. `knownHostsFile`
-supports plain OpenSSH `known_hosts` entries for exact host names. When neither is supplied,
-`scp-next` reads `~/.ssh/known_hosts`. Hashed host names and every OpenSSH marker variant are
-not currently parsed.
+`hostFingerprint` compares the server host key SHA-256 fingerprint. `knownHostsFile` supports plain OpenSSH `known_hosts` entries for exact host names. When neither is supplied, `scp-next` reads `~/.ssh/known_hosts`. Hashed host names and every OpenSSH marker variant are not currently parsed.
 
-`scp-next` fails closed if it cannot establish a host verifier. Use `hostFingerprint` for CI
-or deployments where a known-hosts file is not available.
+`scp-next` fails closed if it cannot establish a host verifier. Use `hostFingerprint` for CI or deployments where a known-hosts file is not available.
 
 ## Progress Reporting
 
-Interactive terminals display concise progress. Progress is disabled with `--quiet` or when
-stderr is not a TTY, which keeps CI logs readable. Library users can pass `onProgress`.
+Interactive terminals display concise progress. Progress is disabled with `--quiet` or when stderr is not a TTY, which keeps CI logs readable. Library users can pass `onProgress`.
 
 ## Dry Run
 
-`--dry-run` resolves configuration and validates local paths and transfer direction without
-connecting to the remote server or modifying local/remote files.
+`--dry-run` resolves configuration and validates local paths and transfer direction without connecting to the remote server or modifying local/remote files.
 
 ```text
 Dry run: upload
@@ -361,8 +355,7 @@ Public typed errors:
 - `FileSystemError`
 - `HostVerificationError`
 
-Each error includes a stable `code`, readable `message`, optional `cause`, and redacted
-non-sensitive context.
+Each error includes a stable `code`, readable `message`, optional `cause`, and redacted non-sensitive context.
 
 ```ts
 import { AuthenticationError, upload } from "scp-next";
@@ -394,8 +387,8 @@ createClient(options: ScpServerOptions): ScpNextClient
 copy(options: CopyOptions): Promise<void>
 ```
 
-Upload and download APIs use explicit `localPath` and `remotePath` names. The optional
-generic `copy()` API accepts typed local/remote endpoint objects.
+Upload and download APIs use explicit `localPath` and `remotePath` names.
+The optional generic `copy()` API accepts typed local/remote endpoint objects.
 
 ## Development
 
@@ -412,11 +405,9 @@ npm pack --dry-run
 
 ## Publishing
 
-The published package includes `dist`, README, license, changelog, and docs. The CLI entry is
-`dist/cli/index.js` and contains a Node.js shebang.
+The published package includes `dist`, README, license, changelog, and docs. The CLI entry is `dist/cli/index.js` and contains a Node.js shebang.
 
 ## Transfer Mechanism
 
-Despite the package name, normal transfers use SFTP through `ssh2-sftp-client`, which is built
-on `ssh2`. This avoids remote shell execution for regular transfers and gives better support
-for progress reporting and recursive directory traversal than shelling out to an SCP command.
+Despite the package name, normal transfers use SFTP through `ssh2-sftp-client`, which is built on `ssh2`.
+This avoids remote shell execution for regular transfers and gives better support for progress reporting and recursive directory traversal than shelling out to an SCP command.

package/dist/cli/index.js

@@ -7,7 +7,7 @@ import { fileURLToPath } from "url";
 import { Command as Command4, CommanderError } from "commander";
 
 // src/client/client.ts
-import { access as access4, mkdir as mkdir2 } from "fs/promises";
+import { access as access4, mkdir as mkdir2, stat as stat3 } from "fs/promises";
 import path4 from "path";
 
 // src/client/transport.ts
@@ -109,7 +109,7 @@ function toScpNextError(error) {
   if (lowerMessage.includes("authentication") || lowerMessage.includes("permission denied")) {
     return new AuthenticationError("SSH authentication failed.", { cause: error });
   }
-  if (lowerMessage.includes("host verification") || lowerMessage.includes("host key")) {
+  if (lowerMessage.includes("host verification") || lowerMessage.includes("host key") || lowerMessage.includes("fingerprint") || lowerMessage.includes("host") && lowerMessage.includes("denied")) {
     return new HostVerificationError("SSH host verification failed.", { cause: error });
   }
   if (lowerMessage.includes("timed out") || lowerMessage.includes("connection") || lowerMessage.includes("econn")) {
@@ -183,8 +183,39 @@ async function getLocalPathKind(inputPath) {
 function normalizeFingerprint(fingerprint) {
   return fingerprint.trim().replace(/^SHA256:/i, "").replace(/^sha256:/i, "").replace(/=+$/g, "");
 }
+function isHexFingerprint(fingerprint) {
+  return /^[0-9a-f]+$/i.test(fingerprint);
+}
+function fingerprintCandidates(fingerprint) {
+  const normalized = normalizeFingerprint(fingerprint);
+  const candidates = /* @__PURE__ */ new Set([normalized]);
+  if (isHexFingerprint(normalized)) {
+    candidates.add(normalized.toLowerCase());
+  } else {
+    try {
+      candidates.add(Buffer.from(normalized, "base64").toString("hex"));
+    } catch {
+    }
+  }
+  return [...candidates];
+}
 function isFingerprintMatch(actual, expected) {
-  return normalizeFingerprint(actual) === normalizeFingerprint(expected);
+  const normalizedActual = normalizeFingerprint(actual);
+  const normalizedExpected = normalizeFingerprint(expected);
+  if (normalizedActual === normalizedExpected) {
+    return true;
+  }
+  return isHexFingerprint(normalizedActual) && isHexFingerprint(normalizedExpected) && normalizedActual.toLowerCase() === normalizedExpected.toLowerCase();
+}
+function hostVerificationHint(host) {
+  return [
+    "",
+    "Typical fix:",
+    `  ssh ${host}`,
+    "",
+    "If you trust the host key, accept it and retry the scp-next command.",
+    "Alternatively configure hostFingerprint or knownHostsFile explicitly."
+  ].join("\n");
 }
 async function resolveAllowedFingerprints(options) {
   const fingerprints = /* @__PURE__ */ new Set();
@@ -193,7 +224,9 @@ async function resolveAllowedFingerprints(options) {
     throw new HostVerificationError("A host is required for SSH host verification.");
   }
   if (options.hostFingerprint) {
-    fingerprints.add(normalizeFingerprint(options.hostFingerprint));
+    for (const fingerprint of fingerprintCandidates(options.hostFingerprint)) {
+      fingerprints.add(fingerprint);
+    }
   }
   try {
     await access2(expandHome(knownHostsFile));
@@ -204,11 +237,15 @@ async function resolveAllowedFingerprints(options) {
         continue;
       }
       const [hosts, algorithm, key] = trimmed.split(/\s+/);
-      if (!hosts || !algorithm || !key || !hosts.split(",").includes(options.host)) {
+      const hostPatterns = hosts?.split(",") ?? [];
+      const portHost = options.port ? `[${options.host}]:${options.port}` : void 0;
+      const matchesHost = hostPatterns.includes(options.host) || Boolean(portHost && hostPatterns.includes(portHost));
+      if (!hosts || !algorithm || !key || !matchesHost) {
         continue;
       }
-      const fingerprint = createHash("sha256").update(Buffer.from(key, "base64")).digest("base64").replace(/=+$/g, "");
-      fingerprints.add(fingerprint);
+      const keyBuffer = Buffer.from(key, "base64");
+      fingerprints.add(createHash("sha256").update(keyBuffer).digest("base64").replace(/=+$/g, ""));
+      fingerprints.add(createHash("sha256").update(keyBuffer).digest("hex"));
     }
   } catch (error) {
     if (options.knownHostsFile || !options.hostFingerprint) {
@@ -220,7 +257,9 @@ async function resolveAllowedFingerprints(options) {
   }
   if (fingerprints.size === 0) {
     throw new HostVerificationError(
-      "SSH host verification failed before connecting: no matching host fingerprint was configured."
+      `SSH host verification failed before connecting: no matching host fingerprint was configured.${hostVerificationHint(
+        options.host
+      )}`
     );
   }
   return fingerprints;
@@ -247,7 +286,11 @@ function toRemoteFileInfo(info) {
 var Ssh2SftpTransport = class {
   client;
   constructor(name = "scp-next") {
-    this.client = new SftpClient(name);
+    this.client = new SftpClient(name, {
+      error: () => void 0,
+      end: () => void 0,
+      close: () => void 0
+    });
   }
   async connect(options) {
     const allowedFingerprints = await resolveAllowedFingerprints(options);
@@ -277,15 +320,24 @@ var Ssh2SftpTransport = class {
     } catch (error) {
       const converted = toScpNextError(error);
       if (converted instanceof HostVerificationError) {
-        throw converted;
+        throw new HostVerificationError(
+          `SSH host verification failed during connection: ${formatErrorMessage(
+            error
+          )}.${hostVerificationTroubleshooting(options.host)}`,
+          { cause: error, context: connectionContext(options) }
+        );
+      }
+      if (isLikelyHostVerificationFailure(error)) {
+        throw new HostVerificationError(
+          `SSH host verification failed during connection.${hostVerificationTroubleshooting(
+            options.host
+          )}`,
+          { cause: error, context: connectionContext(options) }
+        );
       }
-      throw new ConnectionError("Unable to connect to SSH server.", {
+      throw new ConnectionError(`Unable to connect to SSH server: ${formatErrorMessage(error)}`, {
         cause: error,
-        context: {
-          host: options.host,
-          port: options.port,
-          username: options.username
-        }
+        context: connectionContext(options)
       });
     }
   }
@@ -306,7 +358,7 @@ var Ssh2SftpTransport = class {
     try {
       await this.client.fastPut(localPath, remotePath, this.transferOptions(onStep));
     } catch (error) {
-      throw new TransferError(`Upload failed for ${localPath}.`, {
+      throw new TransferError(`Upload failed for ${localPath}: ${formatErrorMessage(error)}`, {
         cause: error,
         context: { localPath, remotePath }
       });
@@ -316,7 +368,7 @@ var Ssh2SftpTransport = class {
     try {
       await this.client.fastGet(remotePath, localPath, this.transferOptions(onStep));
     } catch (error) {
-      throw new TransferError(`Download failed for ${remotePath}.`, {
+      throw new TransferError(`Download failed for ${remotePath}: ${formatErrorMessage(error)}`, {
         cause: error,
         context: { remotePath, localPath }
       });
@@ -333,6 +385,31 @@ var Ssh2SftpTransport = class {
     };
   }
 };
+function connectionContext(options) {
+  return {
+    host: options.host,
+    port: options.port,
+    username: options.username
+  };
+}
+function isLikelyHostVerificationFailure(error) {
+  const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+  return message.includes("host") && (message.includes("verif") || message.includes("fingerprint") || message.includes("host key") || message.includes("key mismatch") || message.includes("denied"));
+}
+function hostVerificationTroubleshooting(host) {
+  const displayHost = host ?? "<host>";
+  return [
+    "",
+    "",
+    "Typical fix:",
+    `  ssh ${displayHost}`,
+    "",
+    "If plain ssh works but scp-next fails, check that the host entry is available in",
+    "`~/.ssh/known_hosts` for the same host and port used by scp-next. For non-default ports,",
+    "OpenSSH usually stores entries as `[host]:port`.",
+    "You can also configure hostFingerprint or knownHostsFile explicitly."
+  ].join("\n");
+}
 
 // src/client/walk.ts
 import { readdir, stat as stat2 } from "fs/promises";
@@ -503,6 +580,22 @@ function percentage(transferredBytes, totalBytes) {
 function mergeOptions(serverOptions, transferOptions) {
   return { ...serverOptions, ...transferOptions ?? {} };
 }
+function hasTrailingPathSeparator(inputPath) {
+  return /[\\/]$/.test(inputPath);
+}
+function trimmedRemoteDirectory(remotePath) {
+  return remotePath.replace(/\/+$/g, "") || "/";
+}
+function remoteBasename(remotePath) {
+  return path4.posix.basename(trimmedRemoteDirectory(remotePath));
+}
+async function isExistingLocalDirectory(localPath) {
+  try {
+    return (await stat3(localPath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
 var ScpNextClientImpl = class {
   serverOptions;
   transport;
@@ -560,10 +653,9 @@ var ScpNextClientImpl = class {
       throw new ValidationError("Uploading a directory requires recursive mode.");
     }
     if (localKind === "file") {
-      await this.ensureRemoteParent(remotePath, options.createDirectories);
-      await this.assertRemoteOverwrite(remotePath, options.overwrite);
+      const destinationFile = await this.resolveRemoteDestinationForLocalFile(options, remotePath);
       const totalBytes2 = void 0;
-      await this.transport.uploadFile(resolveLocalPath(options.localPath), remotePath, (step) => {
+      await this.transport.uploadFile(resolveLocalPath(options.localPath), destinationFile, (step) => {
         options.onProgress?.({
           operation: "upload",
           source: options.localPath,
@@ -580,22 +672,15 @@ var ScpNextClientImpl = class {
     const totalBytes = files.reduce((sum, file) => sum + file.size, 0);
     let completedBytes = 0;
     let completedFiles = 0;
-    const destinationExists = await this.transport.exists(remotePath);
-    if (destinationExists && destinationExists !== "d") {
-      throw new TransferError(`Remote destination already exists and is not a directory: ${remotePath}`, {
-        context: { remotePath }
-      });
-    }
-    if (!destinationExists) {
-      if (!options.createDirectories) {
-        throw new TransferError(`Remote destination directory does not exist: ${remotePath}`, {
-          context: { remotePath }
-        });
-      }
-      await this.transport.mkdir(remotePath, true);
-    }
+    const destinationRoot = await this.resolveRemoteDestinationForLocalDirectory(
+      options,
+      remotePath
+    );
     for (const file of files) {
-      const destinationFile = remoteJoin(remotePath, file.relativePath.split(path4.sep).join("/"));
+      const destinationFile = remoteJoin(
+        destinationRoot,
+        file.relativePath.split(path4.sep).join("/")
+      );
       await this.ensureRemoteParent(destinationFile, true);
       await this.assertRemoteOverwrite(destinationFile, options.overwrite);
       await this.transport.uploadFile(file.absolutePath, destinationFile, (step) => {
@@ -616,6 +701,68 @@ var ScpNextClientImpl = class {
       completedFiles += 1;
     }
   }
+  async resolveRemoteDestinationForLocalFile(options, remotePath) {
+    const remoteKind = await this.transport.exists(remotePath);
+    const isDirectoryLikeDestination = remoteKind === "d" || remotePath.endsWith("/");
+    if (!isDirectoryLikeDestination) {
+      await this.ensureRemoteParent(remotePath, options.createDirectories);
+      await this.assertRemoteOverwrite(remotePath, options.overwrite);
+      return remotePath;
+    }
+    if (remoteKind && remoteKind !== "d") {
+      throw new TransferError(`Remote destination already exists and is not a directory: ${remotePath}`, {
+        context: { remotePath }
+      });
+    }
+    const remoteDirectory = remotePath.replace(/\/+$/g, "") || "/";
+    if (!remoteKind) {
+      if (!options.createDirectories) {
+        throw new TransferError(`Remote destination directory does not exist: ${remoteDirectory}`, {
+          context: { remotePath }
+        });
+      }
+      await this.transport.mkdir(remoteDirectory, true);
+    }
+    const destinationFile = remoteJoin(
+      remoteDirectory,
+      path4.basename(resolveLocalPath(options.localPath))
+    );
+    await this.assertRemoteOverwrite(destinationFile, options.overwrite);
+    return destinationFile;
+  }
+  async resolveRemoteDestinationForLocalDirectory(options, remotePath) {
+    const remoteKind = await this.transport.exists(remotePath);
+    const isDirectoryLikeDestination = remoteKind === "d" || remotePath.endsWith("/");
+    const localDirectoryName = path4.basename(resolveLocalPath(options.localPath));
+    if (remoteKind && remoteKind !== "d") {
+      throw new TransferError(`Remote destination already exists and is not a directory: ${remotePath}`, {
+        context: { remotePath }
+      });
+    }
+    if (isDirectoryLikeDestination) {
+      const remoteDirectory = trimmedRemoteDirectory(remotePath);
+      if (!remoteKind) {
+        if (!options.createDirectories) {
+          throw new TransferError(`Remote destination directory does not exist: ${remoteDirectory}`, {
+            context: { remotePath }
+          });
+        }
+        await this.transport.mkdir(remoteDirectory, true);
+      }
+      const destinationRoot = remoteJoin(remoteDirectory, localDirectoryName);
+      await this.ensureRemoteDirectory(destinationRoot);
+      return destinationRoot;
+    }
+    if (!remoteKind) {
+      if (!options.createDirectories) {
+        throw new TransferError(`Remote destination directory does not exist: ${remotePath}`, {
+          context: { remotePath }
+        });
+      }
+      await this.transport.mkdir(remotePath, true);
+    }
+    return remotePath;
+  }
   async downloadWithTransport(options) {
     const remotePath = normalizeRemotePath(options.remotePath);
     const remoteKind = await this.transport.exists(remotePath);
@@ -634,7 +781,7 @@ var ScpNextClientImpl = class {
     await this.downloadSingleFile(options, remotePath);
   }
   async downloadSingleFile(options, remotePath) {
-    const localPath = resolveLocalPath(options.localPath);
+    const localPath = await this.resolveLocalDestinationForRemoteFile(options, remotePath);
     await this.assertLocalOverwrite(localPath, options.overwrite);
     if (options.createDirectories) {
       await mkdir2(path4.dirname(localPath), { recursive: true });
@@ -653,7 +800,7 @@ var ScpNextClientImpl = class {
   }
   async downloadDirectory(options) {
     const remotePath = normalizeRemotePath(options.remotePath);
-    const localRoot = resolveLocalPath(options.localPath);
+    const localRoot = await this.resolveLocalDestinationForRemoteDirectory(options, remotePath);
     const files = await walkRemoteFiles(this.transport, remotePath);
     const totalBytes = files.reduce((sum, file) => sum + file.size, 0);
     let completedBytes = 0;
@@ -681,6 +828,38 @@ var ScpNextClientImpl = class {
       completedFiles += 1;
     }
   }
+  async resolveLocalDestinationForRemoteFile(options, remotePath) {
+    const localDestination = resolveLocalPath(options.localPath);
+    const isDirectoryLikeDestination = hasTrailingPathSeparator(options.localPath) || await isExistingLocalDirectory(localDestination);
+    if (!isDirectoryLikeDestination) {
+      return localDestination;
+    }
+    if (!await isExistingLocalDirectory(localDestination)) {
+      if (!options.createDirectories) {
+        throw new TransferError(`Local destination directory does not exist: ${localDestination}`, {
+          context: { localPath: options.localPath }
+        });
+      }
+      await mkdir2(localDestination, { recursive: true });
+    }
+    return path4.join(localDestination, remoteBasename(remotePath));
+  }
+  async resolveLocalDestinationForRemoteDirectory(options, remotePath) {
+    const localDestination = resolveLocalPath(options.localPath);
+    const isDirectoryLikeDestination = hasTrailingPathSeparator(options.localPath) || await isExistingLocalDirectory(localDestination);
+    if (!isDirectoryLikeDestination) {
+      return localDestination;
+    }
+    if (!await isExistingLocalDirectory(localDestination)) {
+      if (!options.createDirectories) {
+        throw new TransferError(`Local destination directory does not exist: ${localDestination}`, {
+          context: { localPath: options.localPath }
+        });
+      }
+      await mkdir2(localDestination, { recursive: true });
+    }
+    return path4.join(localDestination, remoteBasename(remotePath));
+  }
   async ensureRemoteParent(remotePath, createDirectories = false) {
     const parent = remoteDirname(remotePath);
     if (parent === "." || parent === "/") {
@@ -697,6 +876,17 @@ var ScpNextClientImpl = class {
       });
     }
   }
+  async ensureRemoteDirectory(remotePath) {
+    const exists = await this.transport.exists(remotePath);
+    if (exists && exists !== "d") {
+      throw new TransferError(`Remote destination already exists and is not a directory: ${remotePath}`, {
+        context: { remotePath }
+      });
+    }
+    if (!exists) {
+      await this.transport.mkdir(remotePath, true);
+    }
+  }
   async assertRemoteOverwrite(remotePath, overwrite = false) {
     if (overwrite) {
       return;