scp-next 1.0.0

package/dist/index.cjs

@@ -0,0 +1,828 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  AuthenticationError: () => AuthenticationError,
+  ConfigurationError: () => ConfigurationError,
+  ConnectionError: () => ConnectionError,
+  FileSystemError: () => FileSystemError,
+  HostVerificationError: () => HostVerificationError,
+  ScpNextClientImpl: () => ScpNextClientImpl,
+  ScpNextError: () => ScpNextError,
+  TransferError: () => TransferError,
+  ValidationError: () => ValidationError,
+  copy: () => copy,
+  createClient: () => createClient,
+  download: () => download,
+  toScpNextError: () => toScpNextError,
+  upload: () => upload
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/client/client.ts
+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
+var SENSITIVE_KEYS = [
+  "password",
+  "passphrase",
+  "privatekey",
+  "privatekeyfile",
+  "token",
+  "authorization",
+  "credential",
+  "secret"
+];
+var PRIVATE_KEY_PATTERN = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g;
+function isSensitiveKey(key) {
+  const normalized = key.replace(/[-_\s]/g, "").toLowerCase();
+  return SENSITIVE_KEYS.some((sensitive) => normalized.includes(sensitive));
+}
+function redactSensitiveValues(value) {
+  if (typeof value === "string") {
+    return value.replace(PRIVATE_KEY_PATTERN, "[REDACTED]");
+  }
+  if (Array.isArray(value)) {
+    const redacted = value.map((item) => redactSensitiveValues(item));
+    return redacted;
+  }
+  if (value && typeof value === "object") {
+    const redacted = {};
+    for (const [key, nestedValue] of Object.entries(value)) {
+      redacted[key] = isSensitiveKey(key) ? "[REDACTED]" : redactSensitiveValues(nestedValue);
+    }
+    return redacted;
+  }
+  return value;
+}
+
+// src/errors/index.ts
+var ScpNextError = class extends Error {
+  code;
+  context;
+  constructor(message, options = {}) {
+    super(message, { cause: options.cause });
+    this.name = new.target.name;
+    this.code = options.code ?? "SCP_NEXT_ERROR";
+    this.context = redactSensitiveValues(options.context ?? {});
+  }
+};
+var ConfigurationError = class extends ScpNextError {
+  constructor(message, options = {}) {
+    super(message, { ...options, code: "SCP_NEXT_CONFIGURATION_ERROR" });
+  }
+};
+var ValidationError = class extends ScpNextError {
+  constructor(message, options = {}) {
+    super(message, { ...options, code: "SCP_NEXT_VALIDATION_ERROR" });
+  }
+};
+var AuthenticationError = class extends ScpNextError {
+  constructor(message, options = {}) {
+    super(message, { ...options, code: "SCP_NEXT_AUTHENTICATION_ERROR" });
+  }
+};
+var ConnectionError = class extends ScpNextError {
+  constructor(message, options = {}) {
+    super(message, { ...options, code: "SCP_NEXT_CONNECTION_ERROR" });
+  }
+};
+var TransferError = class extends ScpNextError {
+  constructor(message, options = {}) {
+    super(message, { ...options, code: "SCP_NEXT_TRANSFER_ERROR" });
+  }
+};
+var FileSystemError = class extends ScpNextError {
+  constructor(message, options = {}) {
+    super(message, { ...options, code: "SCP_NEXT_FILESYSTEM_ERROR" });
+  }
+};
+var HostVerificationError = class extends ScpNextError {
+  constructor(message, options = {}) {
+    super(message, { ...options, code: "SCP_NEXT_HOST_VERIFICATION_ERROR" });
+  }
+};
+function toScpNextError(error) {
+  if (error instanceof ScpNextError) {
+    return error;
+  }
+  const message = error instanceof Error ? error.message : "Unexpected scp-next error.";
+  const lowerMessage = message.toLowerCase();
+  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")) {
+    return new HostVerificationError("SSH host verification failed.", { cause: error });
+  }
+  if (lowerMessage.includes("timed out") || lowerMessage.includes("connection") || lowerMessage.includes("econn")) {
+    return new ConnectionError("SSH connection failed.", { cause: error });
+  }
+  return new TransferError(String(redactSensitiveValues(message)), { cause: error });
+}
+
+// src/security/host-verification.ts
+var import_node_crypto = require("crypto");
+var import_promises2 = require("fs/promises");
+
+// src/paths/local-path.ts
+var import_node_fs = require("fs");
+var import_promises = require("fs/promises");
+var import_node_os = __toESM(require("os"), 1);
+var import_node_path = __toESM(require("path"), 1);
+function expandHome(inputPath) {
+  if (inputPath === "~") {
+    return import_node_os.default.homedir();
+  }
+  if (inputPath.startsWith(`~${import_node_path.default.sep}`) || inputPath.startsWith("~/")) {
+    return import_node_path.default.join(import_node_os.default.homedir(), inputPath.slice(2));
+  }
+  return inputPath;
+}
+function resolveLocalPath(inputPath, baseDir = process.cwd()) {
+  const expanded = expandHome(inputPath);
+  return import_node_path.default.isAbsolute(expanded) ? import_node_path.default.normalize(expanded) : import_node_path.default.resolve(baseDir, expanded);
+}
+async function assertLocalPathExists(inputPath) {
+  try {
+    await (0, import_promises.access)(resolveLocalPath(inputPath), import_node_fs.constants.F_OK);
+  } catch (error) {
+    throw new FileSystemError(`Local path does not exist: ${inputPath}`, {
+      cause: error,
+      context: { path: inputPath }
+    });
+  }
+}
+async function assertDownloadDestination(inputPath, createDirectories = false) {
+  const resolved = resolveLocalPath(inputPath);
+  const parent = import_node_path.default.dirname(resolved);
+  if (createDirectories) {
+    await (0, import_promises.mkdir)(parent, { recursive: true });
+    return;
+  }
+  try {
+    await (0, import_promises.access)(parent, import_node_fs.constants.W_OK);
+  } catch (error) {
+    throw new FileSystemError(`Local destination parent does not exist or is not writable: ${parent}`, {
+      cause: error,
+      context: { path: inputPath }
+    });
+  }
+}
+async function getLocalPathKind(inputPath) {
+  const stats = await (0, import_promises.stat)(resolveLocalPath(inputPath));
+  if (stats.isDirectory()) {
+    return "directory";
+  }
+  if (stats.isFile()) {
+    return "file";
+  }
+  throw new ValidationError(`Local path must be a file or directory: ${inputPath}`, {
+    context: { path: inputPath }
+  });
+}
+
+// src/security/host-verification.ts
+function normalizeFingerprint(fingerprint) {
+  return fingerprint.trim().replace(/^SHA256:/i, "").replace(/^sha256:/i, "").replace(/=+$/g, "");
+}
+function isFingerprintMatch(actual, expected) {
+  return normalizeFingerprint(actual) === normalizeFingerprint(expected);
+}
+async function resolveAllowedFingerprints(options) {
+  const fingerprints = /* @__PURE__ */ new Set();
+  const knownHostsFile = options.knownHostsFile ?? "~/.ssh/known_hosts";
+  if (!options.host) {
+    throw new HostVerificationError("A host is required for SSH host verification.");
+  }
+  if (options.hostFingerprint) {
+    fingerprints.add(normalizeFingerprint(options.hostFingerprint));
+  }
+  try {
+    await (0, import_promises2.access)(expandHome(knownHostsFile));
+    const content = await (0, import_promises2.readFile)(expandHome(knownHostsFile), "utf8");
+    for (const line of content.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("@")) {
+        continue;
+      }
+      const [hosts, algorithm, key] = trimmed.split(/\s+/);
+      if (!hosts || !algorithm || !key || !hosts.split(",").includes(options.host)) {
+        continue;
+      }
+      const fingerprint = (0, import_node_crypto.createHash)("sha256").update(Buffer.from(key, "base64")).digest("base64").replace(/=+$/g, "");
+      fingerprints.add(fingerprint);
+    }
+  } catch (error) {
+    if (options.knownHostsFile || !options.hostFingerprint) {
+      throw new HostVerificationError(
+        "SSH host verification requires hostFingerprint or an accessible knownHostsFile.",
+        { cause: error, context: { knownHostsFile } }
+      );
+    }
+  }
+  if (fingerprints.size === 0) {
+    throw new HostVerificationError(
+      "SSH host verification failed before connecting: no matching host fingerprint was configured."
+    );
+  }
+  return fingerprints;
+}
+function createHostVerifier(allowedFingerprints) {
+  return (hashedKey) => {
+    for (const expected of allowedFingerprints) {
+      if (isFingerprintMatch(hashedKey, expected)) {
+        return true;
+      }
+    }
+    return false;
+  };
+}
+
+// src/client/transport.ts
+function toRemoteFileInfo(info) {
+  return {
+    type: info.type,
+    name: info.name,
+    size: info.size
+  };
+}
+var Ssh2SftpTransport = class {
+  client;
+  constructor(name = "scp-next") {
+    this.client = new import_ssh2_sftp_client.default(name);
+  }
+  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;
+    }
+    try {
+      await this.client.connect(connectOptions);
+    } catch (error) {
+      const converted = toScpNextError(error);
+      if (converted instanceof HostVerificationError) {
+        throw converted;
+      }
+      throw new ConnectionError("Unable to connect to SSH server.", {
+        cause: error,
+        context: {
+          host: options.host,
+          port: options.port,
+          username: options.username
+        }
+      });
+    }
+  }
+  async close() {
+    await this.client.end();
+  }
+  async exists(remotePath) {
+    return this.client.exists(remotePath);
+  }
+  async mkdir(remotePath, recursive = true) {
+    await this.client.mkdir(remotePath, recursive);
+  }
+  async list(remotePath) {
+    const files = await this.client.list(remotePath);
+    return files.map(toRemoteFileInfo);
+  }
+  async uploadFile(localPath, remotePath, onStep) {
+    try {
+      await this.client.fastPut(localPath, remotePath, this.transferOptions(onStep));
+    } catch (error) {
+      throw new TransferError(`Upload failed for ${localPath}.`, {
+        cause: error,
+        context: { localPath, remotePath }
+      });
+    }
+  }
+  async downloadFile(remotePath, localPath, onStep) {
+    try {
+      await this.client.fastGet(remotePath, localPath, this.transferOptions(onStep));
+    } catch (error) {
+      throw new TransferError(`Download failed for ${remotePath}.`, {
+        cause: error,
+        context: { remotePath, localPath }
+      });
+    }
+  }
+  transferOptions(onStep) {
+    if (!onStep) {
+      return void 0;
+    }
+    return {
+      step(transferredBytes, chunkBytes, totalBytes) {
+        onStep({ transferredBytes, chunkBytes, totalBytes });
+      }
+    };
+  }
+};
+
+// src/client/walk.ts
+var import_promises4 = require("fs/promises");
+var import_node_path3 = __toESM(require("path"), 1);
+
+// src/paths/remote-path.ts
+var import_node_path2 = __toESM(require("path"), 1);
+function assertRemotePath(inputPath, label = "remote path") {
+  if (!inputPath || inputPath.trim().length === 0) {
+    throw new ValidationError(`Invalid ${label}: remote paths must not be empty.`, {
+      context: { path: inputPath }
+    });
+  }
+}
+function normalizeRemotePath(inputPath) {
+  assertRemotePath(inputPath);
+  return import_node_path2.default.posix.normalize(inputPath.replace(/\\/g, "/"));
+}
+function remoteJoin(...parts) {
+  const joined = import_node_path2.default.posix.join(...parts);
+  assertRemotePath(joined);
+  return joined;
+}
+function remoteDirname(inputPath) {
+  assertRemotePath(inputPath);
+  return import_node_path2.default.posix.dirname(inputPath);
+}
+
+// src/client/walk.ts
+async function walkLocalFiles(rootPath) {
+  const resolvedRoot = resolveLocalPath(rootPath);
+  const stats = await (0, import_promises4.stat)(resolvedRoot);
+  if (stats.isFile()) {
+    return [
+      {
+        absolutePath: resolvedRoot,
+        relativePath: import_node_path3.default.basename(resolvedRoot),
+        size: stats.size
+      }
+    ];
+  }
+  const files = [];
+  async function visit(directory) {
+    const entries = await (0, import_promises4.readdir)(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      const absolutePath = import_node_path3.default.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await visit(absolutePath);
+      } else if (entry.isFile()) {
+        const entryStats = await (0, import_promises4.stat)(absolutePath);
+        files.push({
+          absolutePath,
+          relativePath: import_node_path3.default.relative(resolvedRoot, absolutePath),
+          size: entryStats.size
+        });
+      }
+    }
+  }
+  await visit(resolvedRoot);
+  return files;
+}
+async function walkRemoteFiles(transport, rootPath) {
+  const rootEntries = await transport.list(rootPath);
+  const files = [];
+  async function visit(directory, relativeBase, entries) {
+    for (const entry of entries) {
+      const fullPath = remoteJoin(directory, entry.name);
+      const relativePath = relativeBase ? remoteJoin(relativeBase, entry.name) : entry.name;
+      if (entry.type === "d") {
+        await visit(fullPath, relativePath, await transport.list(fullPath));
+      } else if (entry.type === "-") {
+        files.push({
+          remotePath: fullPath,
+          relativePath,
+          size: entry.size
+        });
+      }
+    }
+  }
+  await visit(rootPath, "", rootEntries);
+  return files;
+}
+
+// src/config/validation.ts
+var import_promises5 = require("fs/promises");
+function validatePort(port) {
+  if (port === void 0) {
+    return;
+  }
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new ValidationError("Port must be an integer between 1 and 65535.", {
+      context: { port }
+    });
+  }
+}
+function validateTimeout(timeout) {
+  if (timeout === void 0) {
+    return;
+  }
+  if (!Number.isFinite(timeout) || timeout <= 0) {
+    throw new ValidationError("Timeout must be a positive number.", {
+      context: { timeout }
+    });
+  }
+}
+async function validateServerOptions(options) {
+  if (!options.host) {
+    throw new ValidationError("Host is required.");
+  }
+  if (!options.username) {
+    throw new ValidationError("Username is required.");
+  }
+  validatePort(options.port);
+  validateTimeout(options.timeout);
+  if (options.privateKeyFile) {
+    try {
+      await (0, import_promises5.access)(resolveLocalPath(options.privateKeyFile));
+    } catch (error) {
+      throw new ValidationError(`Private key file does not exist: ${options.privateKeyFile}`, {
+        cause: error,
+        context: { privateKeyFile: options.privateKeyFile }
+      });
+    }
+  }
+  const hasAuthentication = Boolean(options.password) || Boolean(options.privateKey) || Boolean(options.privateKeyFile) || Boolean(options.agent) || Boolean(process.env.SSH_AUTH_SOCK);
+  if (!hasAuthentication) {
+    throw new ValidationError(
+      "Authentication is required. Provide a password, private key, private key file, or SSH agent."
+    );
+  }
+}
+async function validateUploadOptions(options) {
+  if (!options.localPath) {
+    throw new ValidationError("Missing localPath.");
+  }
+  if (!options.remotePath) {
+    throw new ValidationError("Missing remotePath.");
+  }
+  assertRemotePath(options.remotePath, "remotePath");
+  validateTimeout(options.timeout);
+  await assertLocalPathExists(options.localPath);
+  if (!options.dryRun) {
+    await validateServerOptions(options);
+  }
+}
+async function validateDownloadOptions(options) {
+  if (!options.remotePath) {
+    throw new ValidationError("Missing remotePath.");
+  }
+  if (!options.localPath) {
+    throw new ValidationError("Missing localPath.");
+  }
+  assertRemotePath(options.remotePath, "remotePath");
+  validateTimeout(options.timeout);
+  await assertDownloadDestination(options.localPath, options.createDirectories);
+  if (!options.dryRun) {
+    await validateServerOptions(options);
+  }
+}
+
+// src/client/client.ts
+function percentage(transferredBytes, totalBytes) {
+  if (!totalBytes || totalBytes <= 0) {
+    return void 0;
+  }
+  return Math.min(100, Math.round(transferredBytes / totalBytes * 100));
+}
+function mergeOptions(serverOptions, transferOptions) {
+  return { ...serverOptions, ...transferOptions ?? {} };
+}
+var ScpNextClientImpl = class {
+  serverOptions;
+  transport;
+  connected = false;
+  constructor(serverOptions, dependencies = {}) {
+    this.serverOptions = serverOptions;
+    this.transport = dependencies.transport ?? new Ssh2SftpTransport();
+  }
+  async connect() {
+    await validateServerOptions(this.serverOptions);
+    await this.transport.connect(this.serverOptions);
+    this.connected = true;
+  }
+  async upload(localPath, remotePath, options = {}) {
+    const uploadOptions = {
+      ...mergeOptions(this.serverOptions, options),
+      localPath,
+      remotePath
+    };
+    await validateUploadOptions(uploadOptions);
+    if (options.dryRun) {
+      return;
+    }
+    await this.ensureConnected();
+    await this.uploadWithTransport(uploadOptions);
+  }
+  async download(remotePath, localPath, options = {}) {
+    const downloadOptions = {
+      ...mergeOptions(this.serverOptions, options),
+      remotePath,
+      localPath
+    };
+    await validateDownloadOptions(downloadOptions);
+    if (options.dryRun) {
+      return;
+    }
+    await this.ensureConnected();
+    await this.downloadWithTransport(downloadOptions);
+  }
+  async close() {
+    if (this.connected) {
+      await this.transport.close();
+      this.connected = false;
+    }
+  }
+  async ensureConnected() {
+    if (!this.connected) {
+      await this.connect();
+    }
+  }
+  async uploadWithTransport(options) {
+    const localKind = await getLocalPathKind(options.localPath);
+    const remotePath = normalizeRemotePath(options.remotePath);
+    if (localKind === "directory" && !options.recursive) {
+      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 totalBytes2 = void 0;
+      await this.transport.uploadFile(resolveLocalPath(options.localPath), remotePath, (step) => {
+        options.onProgress?.({
+          operation: "upload",
+          source: options.localPath,
+          destination: options.remotePath,
+          transferredBytes: step.transferredBytes,
+          totalBytes: step.totalBytes || totalBytes2,
+          percentage: percentage(step.transferredBytes, step.totalBytes),
+          currentFile: options.localPath
+        });
+      });
+      return;
+    }
+    const files = await walkLocalFiles(options.localPath);
+    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);
+    }
+    for (const file of files) {
+      const destinationFile = remoteJoin(remotePath, file.relativePath.split(import_node_path4.default.sep).join("/"));
+      await this.ensureRemoteParent(destinationFile, true);
+      await this.assertRemoteOverwrite(destinationFile, options.overwrite);
+      await this.transport.uploadFile(file.absolutePath, destinationFile, (step) => {
+        const transferredBytes = completedBytes + step.transferredBytes;
+        options.onProgress?.({
+          operation: "upload",
+          source: options.localPath,
+          destination: options.remotePath,
+          transferredBytes,
+          totalBytes,
+          percentage: percentage(transferredBytes, totalBytes),
+          currentFile: file.relativePath,
+          completedFiles,
+          totalFiles: files.length
+        });
+      });
+      completedBytes += file.size;
+      completedFiles += 1;
+    }
+  }
+  async downloadWithTransport(options) {
+    const remotePath = normalizeRemotePath(options.remotePath);
+    const remoteKind = await this.transport.exists(remotePath);
+    if (!remoteKind) {
+      throw new TransferError(`Remote path does not exist: ${options.remotePath}`, {
+        context: { remotePath: options.remotePath }
+      });
+    }
+    if (remoteKind === "d") {
+      if (!options.recursive) {
+        throw new ValidationError("Downloading a directory requires recursive mode.");
+      }
+      await this.downloadDirectory(options);
+      return;
+    }
+    await this.downloadSingleFile(options, remotePath);
+  }
+  async downloadSingleFile(options, remotePath) {
+    const localPath = resolveLocalPath(options.localPath);
+    await this.assertLocalOverwrite(localPath, options.overwrite);
+    if (options.createDirectories) {
+      await (0, import_promises6.mkdir)(import_node_path4.default.dirname(localPath), { recursive: true });
+    }
+    await this.transport.downloadFile(remotePath, localPath, (step) => {
+      options.onProgress?.({
+        operation: "download",
+        source: options.remotePath,
+        destination: options.localPath,
+        transferredBytes: step.transferredBytes,
+        totalBytes: step.totalBytes,
+        percentage: percentage(step.transferredBytes, step.totalBytes),
+        currentFile: options.remotePath
+      });
+    });
+  }
+  async downloadDirectory(options) {
+    const remotePath = normalizeRemotePath(options.remotePath);
+    const localRoot = resolveLocalPath(options.localPath);
+    const files = await walkRemoteFiles(this.transport, remotePath);
+    const totalBytes = files.reduce((sum, file) => sum + file.size, 0);
+    let completedBytes = 0;
+    let completedFiles = 0;
+    await (0, import_promises6.mkdir)(localRoot, { recursive: Boolean(options.createDirectories) });
+    for (const file of files) {
+      const localFile = import_node_path4.default.join(localRoot, ...file.relativePath.split("/"));
+      await this.assertLocalOverwrite(localFile, options.overwrite);
+      await (0, import_promises6.mkdir)(import_node_path4.default.dirname(localFile), { recursive: true });
+      await this.transport.downloadFile(file.remotePath, localFile, (step) => {
+        const transferredBytes = completedBytes + step.transferredBytes;
+        options.onProgress?.({
+          operation: "download",
+          source: options.remotePath,
+          destination: options.localPath,
+          transferredBytes,
+          totalBytes,
+          percentage: percentage(transferredBytes, totalBytes),
+          currentFile: file.relativePath,
+          completedFiles,
+          totalFiles: files.length
+        });
+      });
+      completedBytes += file.size;
+      completedFiles += 1;
+    }
+  }
+  async ensureRemoteParent(remotePath, createDirectories = false) {
+    const parent = remoteDirname(remotePath);
+    if (parent === "." || parent === "/") {
+      return;
+    }
+    if (createDirectories) {
+      await this.transport.mkdir(parent, true);
+      return;
+    }
+    const exists = await this.transport.exists(parent);
+    if (exists !== "d") {
+      throw new TransferError(`Remote destination parent does not exist: ${parent}`, {
+        context: { remotePath }
+      });
+    }
+  }
+  async assertRemoteOverwrite(remotePath, overwrite = false) {
+    if (overwrite) {
+      return;
+    }
+    const exists = await this.transport.exists(remotePath);
+    if (exists) {
+      throw new TransferError(`Remote destination already exists: ${remotePath}`, {
+        context: { remotePath }
+      });
+    }
+  }
+  async assertLocalOverwrite(localPath, overwrite = false) {
+    if (overwrite) {
+      return;
+    }
+    try {
+      await (0, import_promises6.access)(localPath);
+      throw new TransferError(`Local destination already exists: ${localPath}`, {
+        context: { localPath }
+      });
+    } catch (error) {
+      if (error instanceof TransferError) {
+        throw error;
+      }
+    }
+  }
+};
+function createClient(options) {
+  return new ScpNextClientImpl(options);
+}
+
+// src/client/upload.ts
+async function upload(options) {
+  const client = new ScpNextClientImpl(options);
+  try {
+    await client.upload(options.localPath, options.remotePath, options);
+  } finally {
+    await client.close();
+  }
+}
+
+// src/client/download.ts
+async function download(options) {
+  const client = new ScpNextClientImpl(options);
+  try {
+    await client.download(options.remotePath, options.localPath, options);
+  } finally {
+    await client.close();
+  }
+}
+
+// src/client/copy.ts
+async function copy(options) {
+  if (options.source.type === "local" && options.destination.type === "remote") {
+    await upload({
+      ...options,
+      localPath: options.source.path,
+      remotePath: options.destination.path
+    });
+    return;
+  }
+  if (options.source.type === "remote" && options.destination.type === "local") {
+    await download({
+      ...options,
+      remotePath: options.source.path,
+      localPath: options.destination.path
+    });
+    return;
+  }
+  throw new ValidationError("copy() supports only local-to-remote or remote-to-local transfers.", {
+    context: {
+      sourceType: options.source.type,
+      destinationType: options.destination.type
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  ConfigurationError,
+  ConnectionError,
+  FileSystemError,
+  HostVerificationError,
+  ScpNextClientImpl,
+  ScpNextError,
+  TransferError,
+  ValidationError,
+  copy,
+  createClient,
+  download,
+  toScpNextError,
+  upload
+});
+//# sourceMappingURL=index.cjs.map