Nest SFTP Module

Common errors

• Nest can't resolve dependencies of the SftpClientService (?). Please make sure that the argument SftpClientService at index [0] is available in the SftpModule context.

  cause The SftpModule was not imported or configured correctly, or `SftpClientService` is being injected outside a module that imports `SftpModule`.
  fix Ensure `SftpModule.forRoot()` or `SftpModule.forRootAsync()` is properly imported in your `AppModule` or a shared module that is imported by the consuming module. Remember that `SftpModule` is often made global as per the documentation.

• Error: Timeout while waiting for handshake

  cause The SFTP server did not respond within the configured timeout period, often due to incorrect host/port, network issues, or a firewall blocking the connection.
  fix Verify `host` and `port` in your `ConnectConfig`. Check network connectivity and firewall rules between your application and the SFTP server. Increase the `timeout` option in `ConnectConfig` if the server is known to be slow.

• Error: Authentication failure. User: [username]

  cause Incorrect username or password provided in the `ConnectConfig`.
  fix Double-check the `username` and `password` for accuracy, including any special character escaping requirements. Ensure the user has the necessary permissions on the SFTP server.

• TypeError: SftpModule.forRootAsync is not a function

  cause You might be using an older version of `nest-sftp` that does not support `forRootAsync`, or there's a TypeScript compilation issue.
  fix Update `nest-sftp` to the latest version (v2.x or later added `forRootAsync`). If on a recent version, check your `tsconfig.json` for module resolution settings and ensure proper project setup.

Warnings

• breaking Version 3.0.0 introduced breaking changes due to potential updates in its underlying dependency `ssh2-sftp-client` or internal module structure, although the changelog does not explicitly detail them. Users upgrading from v2.x should review their module configuration and SFTP client usage.
  Fix: Review the official README for the latest configuration patterns, especially `forRootAsync` usage. Re-evaluate `SftpModule` imports and `SftpClientService` injection.
• breaking The `SftpModule` configuration methods (`forRoot`, `forRootAsync`) might have changed signature or preferred usage across major versions. The documentation emphasizes `forRootAsync` which suggests that the synchronous `forRoot` might have limitations or be less recommended in newer versions.
  Fix: Migrate `SftpModule` configuration to `forRootAsync` pattern, especially if you need to inject other services (like `ConfigService`) to retrieve SFTP connection details.
• gotcha Special characters in SFTP passwords, specifically backslashes (`\`), exclamation marks (`!`), and opening parentheses (`(`), need careful handling. Backslashes usually require escaping (`\\`).
  Fix: When providing passwords, ensure that `\` is escaped to `\\`. Test passwords containing `!` or `(` thoroughly, as they might interact poorly with shell environments or configuration parsing, even if the library itself handles them.
• gotcha The `debug` option for `ConnectConfig` directly uses a `console.log` function. Exposing raw sensitive connection details in production logs via this can be a security risk.
  Fix: For production environments, ensure the `debug` property is either omitted or points to a custom logging function that sanitizes or redacts sensitive information before outputting to logs.
• gotcha While `nest-sftp` supports a wide range of NestJS peer dependencies (7-11), ensure compatibility by testing thoroughly if you are on the edges of this range or using a pre-release NestJS version.
  Fix: Always test new `nest-sftp` versions against your specific NestJS version. Consult the `nest-sftp` changelog for explicit NestJS version support updates, such as the v3.1.0 update for NestJS 11.

Install

• npm install nest-sftp npm
• yarn add nest-sftp yarn
• pnpm add nest-sftp pnpm

Imports

• SftpModule
  wrong:

  const SftpModule = require('nest-sftp');

  correct:

  import { SftpModule } from 'nest-sftp';

  This is the main module for registering SFTP capabilities in NestJS. Use `forRoot` or `forRootAsync`.
• SftpClientService
  wrong:

  import { SftpClientService } from 'nest-sftp/sftp-client.service';

  correct:

  import { SftpClientService } from 'nest-sftp';

  This service is injected into your application's providers to perform SFTP operations. It's automatically exposed by SftpModule.
• ConnectConfig
  wrong:

  import { ConnectConfig } from 'nest-sftp';

  correct:

  import { ConnectConfig } from 'ssh2-sftp-client';

  While nest-sftp uses `ssh2-sftp-client`, its `ConnectConfig` interface comes directly from the underlying library for type consistency.

Quickstart

This quickstart demonstrates registering the SftpModule asynchronously, injecting SftpClientService, and performing basic SFTP operations like listing, uploading, downloading, and deleting files.

import { Module, Injectable, Logger } from '@nestjs/common';
import { SftpModule, SftpClientService } from 'nest-sftp';
import { ConnectConfig } from 'ssh2-sftp-client';

@Injectable()
class ConfigService {
  getSftpConnectionInfo(): ConnectConfig {
    // In a real app, fetch these from environment variables or a configuration store
    return {
      host: process.env.SFTP_HOST ?? 'sftp.example.com',
      port: parseInt(process.env.SFTP_PORT ?? '22', 10),
      username: process.env.SFTP_USERNAME ?? 'user',
      password: process.env.SFTP_PASSWORD ?? 'password',
      // Optional: debug logging
      debug: console.log
    };
  }
}

@Injectable()
export class AppService {
  private readonly logger = new Logger(AppService.name);
  constructor(private readonly sftpClient: SftpClientService) {}

  async runSftpExample(): Promise<void> {
    try {
      this.logger.log('Attempting to list SFTP directory...');
      const list = await this.sftpClient.list('/remote/path');
      this.logger.log(`Listed directory: ${JSON.stringify(list.map(f => f.name))}`);

      const remoteFile = `/remote/path/test-${Date.now()}.txt`;
      const localContent = 'Hello SFTP from NestJS!';
      const buffer = Buffer.from(localContent);

      this.logger.log(`Uploading file to ${remoteFile}`);
      await this.sftpClient.upload(buffer, remoteFile);
      this.logger.log('File uploaded successfully.');

      this.logger.log(`Downloading file from ${remoteFile}`);
      const downloadedBuffer = await this.sftpClient.download(remoteFile);
      this.logger.log(`Downloaded content: ${downloadedBuffer.toString()}`);

      this.logger.log(`Deleting file ${remoteFile}`);
      await this.sftpClient.delete(remoteFile);
      this.logger.log('File deleted successfully.');

    } catch (error) {
      this.logger.error('SFTP operation failed:', error.message);
    }
  }
}

@Module({
  imports: [
    SftpModule.forRootAsync(
      {
        useFactory: (configService: ConfigService) => {
          return configService.getSftpConnectionInfo();
        },
        inject: [ConfigService],
        imports: [ConfigService],
      }
    ),
  ],
  controllers: [],
  providers: [ConfigService, AppService],
  exports: [ConfigService, AppService]
})
export class AppModule {
  constructor(private readonly appService: AppService) {
    // Kick off the SFTP example when the app starts
    // This would typically be triggered by an endpoint or lifecycle hook in a real app
    this.appService.runSftpExample();
  }
}