Pular para conteúdo

SFTP_CONNECT - Conectar via SSH File Transfer Protocol

O que é este Node?

O SFTP_CONNECT é o node responsável por estabelecer conexão segura com servidores SFTP usando protocolo SSH. SFTP é completamente diferente de FTP/FTPS - usa SSH (porta 22) ao invés de FTP (porta 21).

Por que este Node existe?

SFTP é o padrão moderno para transferência segura de arquivos. O SFTP_CONNECT existe para:

  1. Segurança Máxima: Todas as conexões e dados são criptografados via SSH
  2. Autenticação Forte: Suporta chaves SSH além de senha
  3. Conformidade: Muitas empresas e órgãos governamentais exigem SFTP
  4. Firewall-Friendly: Usa apenas porta 22 (SSH), mais fácil de configurar em firewalls

Diferença: FTP vs FTPS vs SFTP

Protocolo Porta Padrão Segurança Tecnologia Base
FTP 21 ❌ Nenhuma (texto puro) File Transfer Protocol
FTPS 990 ou 21 ⚠️ SSL/TLS opcional FTP + SSL/TLS
SFTP 22 ✅ Sempre criptografado SSH File Transfer

IMPORTANTE: SFTP ≠ FTPS! São protocolos completamente diferentes: - FTPS = FTP com camada SSL/TLS (extensão do FTP) - SFTP = Subsistema do SSH (nada a ver com FTP)

Como funciona internamente?

Quando o SFTP_CONNECT é executado, o sistema:

  1. Inicia Handshake SSH: Conecta na porta 22 e negocia criptografia
  2. Autentica via SSH: Usa senha ou chave privada SSH
  3. Estabelece Túnel Seguro: Todo tráfego é criptografado end-to-end
  4. Inicia Subsistema SFTP: Ativa protocolo de transferência dentro do SSH
  5. Mantém Conexão: Sessão SSH permanece aberta para operações
  6. Se falhar: Retorna erro (credenciais inválidas, porta bloqueada, host não alcançável)
  7. Se sucesso: Conexão SFTP segura estabelecida

Código interno (sftp-executor.service.ts - não implementado ainda): 

// NOTA: Este executor ainda não existe no código.
// Seria necessário criar sftp-executor.service.ts usando biblioteca 'ssh2-sftp-client'
import * as SFTP from 'ssh2-sftp-client';

private async connectSFTP(config: SFTPConfig): Promise<SFTP> {
  const sftp = new SFTP();

  await sftp.connect({
    host: config.host,
    port: config.port || 22,
    username: config.username,
    password: config.password,
    // ou privateKey: fs.readFileSync('/path/to/key')
  });

  return sftp;
}

Quando você DEVE usar este Node?

Use SFTP_CONNECT sempre que precisar de transferência segura de arquivos via SSH:

Casos de uso

  1. Dados Bancários: "Enviar arquivos de pagamento para banco via SFTP (exigido por regulação)"
  2. Dados Médicos: "Transferir prontuários eletrônicos com criptografia obrigatória"
  3. Compliance PCI-DSS: "Enviar relatórios de transações de cartão via SFTP seguro"

Quando NÃO usar SFTP_CONNECT

  • Servidor Não Suporta SSH: Alguns servidores antigos só têm FTP. Use FTP_CONNECT
  • Desenvolvimento Local: Para testes rápidos, FTP pode ser mais simples de configurar
  • Performance Crítica: FTP pode ser ligeiramente mais rápido (sem overhead de criptografia)

Parâmetros Detalhados

host (string, obrigatório)

O que é: Endereço do servidor SFTP (SSH).

Padrão: Nenhum (obrigatório)

Flow completo para testar:

{
  "name": "Teste SFTP Connect - Host",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "sftp_1",
      "type": "sftp",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Conectar SFTP",
        "parameters": {
          "host": "sftp.example.com",
          "port": 22,
          "username": "sftpuser",
          "password": "securepass",
          "operation": "list",
          "remotePath": "/",
          "outputVariable": "sftp_connection"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar Conexão",
        "parameters": {
          "message": "🔒 Conectado via SSH ao servidor: {{sftp_connection.host}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "sftp_1" },
    { "source": "sftp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Inicie o flow. Sistema deve conectar via SSH na porta 22.

port (number, opcional)

O que é: Porta TCP do servidor SSH.

Padrão: 22 (porta padrão SSH/SFTP)

username (string, obrigatório)

O que é: Nome de usuário SSH para autenticação.

Padrão: Nenhum (obrigatório)

password (string, obrigatório)

O que é: Senha SSH ou passphrase da chave privada.

Padrão: Nenhum (obrigatório se não usar chave SSH)

privateKey (string, opcional)

O que é: Caminho para arquivo de chave privada SSH (autenticação por chave).

Padrão: Nenhum (use password OU privateKey)

Flow completo para testar:

{
  "name": "SFTP com Chave SSH",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "sftp_1",
      "type": "sftp",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Conectar com Chave SSH",
        "parameters": {
          "host": "sftp.secure.com",
          "port": 22,
          "username": "deploy",
          "privateKey": "/home/user/.ssh/id_rsa",
          "operation": "list",
          "remotePath": "/"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "🔐 Autenticado via chave SSH!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "sftp_1" },
    { "source": "sftp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Usa chave SSH ao invés de senha (mais seguro).

Parâmetros

Campo Tipo Obrigatório Descrição
host string Sim Endereço do servidor SFTP/SSH
port number Não Porta TCP (padrão: 22)
username string Sim Nome de usuário SSH
password string Condicional Senha (obrigatório se não usar privateKey)
privateKey string Condicional Caminho da chave SSH (obrigatório se não usar password)
operation string Sim Operação: list (para testar conexão)
remotePath string Não Caminho remoto (padrão: /)
outputVariable string Não Variável de resultado (padrão: sftp_result)

Exemplo 1: Conexão SFTP Segura com Senha

Objetivo: Conectar a servidor SFTP e listar arquivos usando autenticação por senha

JSON para Importar

{
  "name": "Conexão SFTP com Senha",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "sftp_1",
      "type": "sftp",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Conectar SFTP",
        "parameters": {
          "host": "sftp.banco.com.br",
          "port": 22,
          "username": "empresa_cliente",
          "password": "SecureP@ss123",
          "operation": "list",
          "remotePath": "/",
          "outputVariable": "file_list"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Mostrar Resultado",
        "parameters": {
          "message": "🔒 Conexão SSH segura estabelecida!\nEncontrados {{file_list.count}} arquivos."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "sftp_1" },
    { "source": "sftp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 🔒 Conexão SSH segura estabelecida!
Encontrados 8 arquivos.

Exemplo 2: Autenticação via Chave SSH (Mais Seguro)

Objetivo: Conectar usando chave privada SSH ao invés de senha

JSON para Importar

{
  "name": "SFTP com Chave SSH",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Configurar Chave",
        "parameters": {
          "variableName": "ssh_key_path",
          "value": "/home/deploy/.ssh/id_ed25519"
        }
      }
    },
    {
      "id": "sftp_1",
      "type": "sftp",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Conectar com Chave",
        "parameters": {
          "host": "sftp.producao.com",
          "port": 22,
          "username": "deploy_bot",
          "privateKey": "{{ssh_key_path}}",
          "operation": "list",
          "remotePath": "/app/uploads/",
          "outputVariable": "connection"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Autenticação por chave SSH bem-sucedida!\nSem senha transmitida pela rede."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "sftp_1" },
    { "source": "sftp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: ✅ Autenticação por chave SSH bem-sucedida!
Sem senha transmitida pela rede.

Resposta do Node

{
  "success": true,
  "data": {
    "sftp_result": {
      "success": true,
      "path": "/",
      "files": [],
      "count": 0,
      "protocol": "sftp",
      "sshVersion": "OpenSSH_8.2"
    },
    "operation": "list",
    "host": "sftp.example.com",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "executionTime": 987
}

Boas Práticas

✅ SIM:

  • Use SFTP ao invés de FTP sempre que possível (segurança)
  • Prefira autenticação por chave SSH ao invés de senha
  • Use porta 22 padrão (ou customize se necessário)
  • Verifique fingerprint SSH na primeira conexão
  • Armazene chaves SSH com permissões restritas (chmod 600)

❌ NÃO:

  • Não confunda SFTP com FTPS (são protocolos diferentes)
  • Não use senhas fracas em conexões SFTP
  • Não compartilhe chaves privadas SSH
  • Não desabilite verificação de host key (risco de man-in-the-middle)

Dicas

💡 Dica 1: SFTP = SSH File Transfer Protocol (porta 22). FTPS = FTP + SSL (porta 990). São protocolos completamente diferentes!

💡 Dica 2: Para gerar chave SSH: ssh-keygen -t ed25519 -C "seu@email.com". Depois adicione chave pública no servidor.

💡 Dica 3: SFTP é sempre criptografado (100% seguro). FTP é sempre texto puro (0% seguro). FTPS é FTP com SSL (seguro se configurado).

💡 Dica 4: Maioria dos bancos e instituições financeiras exige SFTP por segurança e compliance.

Próximos Nodes

→ SFTP_UPLOAD - Enviar arquivo via SFTP seguro → SFTP_DOWNLOAD - Baixar arquivo via SFTP → SFTP_LIST - Listar arquivos no servidor SFTP → FTP_CONNECT - Conexão FTP padrão (menos seguro)