n8n-nodes-sftp-tp

Nodos comunitarios de n8n para subir, descargar y listar archivos por SFTP en servidores SSH legacy.

Por qué existe

El nodo SFTP nativo de n8n (n8n-nodes-base.ftp) usa la librería ssh2 y no
expone ninguna configuración de algoritmos SSH. Contra servidores SFTP que sólo
negocian algoritmos antiguos, la conexión falla con:

Couldn't connect with these settings
read ECONNRESET

…aunque las mismas credenciales conectan bien desde FileZilla. La causa es que
el servidor sólo negocia algoritmos SSH antiguos que la librería ssh2
rechaza por defecto, y n8n no deja ajustarlos.

Estos nodos hacen lo mismo que el nativo (upload, download, list), pero exponen los
algoritmos de negociación (KEX, host key, cipher, HMAC) y la cadena de
identificación del cliente. Por defecto agregan un set de algoritmos legacy,
así que funcionan out-of-the-box contra servidores viejos.

Qué hace

El paquete expone tres nodos que comparten credencial nativa SFTP y opciones SSH legacy:

SFTP TP Upload

• Sube un archivo binario de un item a una ruta remota.
• Parámetros:
  • Propiedad Binaria — propiedad del item con el archivo (por defecto data).
  • Ruta Remota — ruta absoluta completa, incluido el nombre del archivo.
  • Opciones → Crear Directorios Faltantes — crea el directorio remoto si no existe.

SFTP TP Download

• Descarga un archivo remoto y lo devuelve como binario en el item.
• Parámetros:
  • Ruta Remota — ruta absoluta del archivo a descargar.
  • Propiedad Binaria De Salida — nombre de la propiedad binaria a poblar (por defecto data).
  • Opciones:
    • Borrar Remoto Después De Descargar — útil para colas de archivos que se procesan una sola vez.
    • Nombre De Archivo Forzado — override del basename remoto.
    • MIME Type — para CSV se sugiere text/csv (default: application/octet-stream).
    • Continuar Si Archivo No Existe — devuelve un item con skipped: true en lugar de fallar.

SFTP TP List

• Lista entradas de una carpeta remota.
• Parámetros:
  • Carpeta Remota — ruta absoluta a listar.
  • Salida — Un Item Por Entrada (default, ideal para iterar con un Split In Batches o un loop) o Un Único Item Con Array entries.
  • Opciones:
    • Patrón De Nombre (glob) — filtra por nombre, soporta * y ?. Ej. *.csv, report_*.csv.
    • Incluir Directorios — por default sólo devuelve archivos.
    • Incluir Symlinks — por default los excluye.
    • Continuar Si Carpeta No Existe.
• Cada entrada incluye: name, type (file / directory / symlink), size, modifyTime (epoch ms) + modifyTimeIso (ISO 8601), accessTime, path absoluto.

Opciones SSH (compartidas)

Los tres nodos exponen el mismo bloque Opciones SSH (Servidores Legacy):

• Listas de algoritmos a agregar: kex, serverHostKey, cipher, hmac.
• Ident — cadena de identificación SSH del cliente, opcional.
• Timeout De Conexión (Ms) — default 20 000.
• Debug SSH — vuelca el handshake a los logs de n8n.

Si no se tocan, se aplican valores legacy por defecto que cubren la mayoría de los servidores SFTP antiguos.

Publicar en npm

Para poder instalarlo desde la interfaz de n8n, el paquete tiene que estar en
el registro público de npm. El código del nodo no contiene secretos (las
credenciales viven en el almacén de credenciales de n8n, no en el código), así
que es seguro publicarlo público.

Vía GitHub Actions (recomendado)

El repo incluye el workflow .github/workflows/publish-n8n-nodes-sftp-tp.yml,
que publica el paquete en npm desde GitHub.

Setup (una sola vez):

1. Crear una cuenta en npmjs.com si no se tiene.
2. En npm: Access Tokens → Generate New Token → tipo Automation
   (el tipo Automation salta el 2FA, necesario para CI). Copiar el token.
3. En GitHub: repo Settings → Secrets and variables → Actions → New
   repository secret. Nombre: NPM_TOKEN. Valor: el token de npm.

⚠️ El token de npm es un secreto. Va sólo en el secret de GitHub, nunca
en el código, ni en el chat, ni en un archivo del repo.

Publicar:

1. Subir la versión en package.json (version). npm rechaza publicar dos
   veces la misma versión.
2. Disparar el workflow, por cualquiera de estas vías:
   • Manual: pestaña Actions del repo → workflow Publicar
     n8n-nodes-sftp-tp en npm → Run workflow.
   • Por tag: crear y pushear un tag n8n-nodes-sftp-tp-vX.Y.Z:

     git tag n8n-nodes-sftp-tp-v0.1.0
     git push origin n8n-nodes-sftp-tp-v0.1.0
     

El workflow compila el TypeScript y corre npm publish con el NPM_TOKEN.

Manual desde la terminal (alternativa)

cd flows/n8n/custom-nodes/n8n-nodes-sftp-tp
npm login                      # requiere cuenta npm
npm publish --access public    # prepublishOnly compila solo

El nombre n8n-nodes-sftp-tp está libre en npm al momento de escribir esto. Si
ya estuviera tomado, cambiar name en package.json (debe seguir empezando
con n8n-nodes-).

Instalar en n8n desde la interfaz (recomendado)

Una vez publicado en npm:

1. En n8n, ir a Settings → Community nodes.
2. Click en Install a community node.
3. En npm package name escribir: n8n-nodes-sftp-tp.
4. Aceptar el aviso de riesgo e Install.
5. El nodo SFTP TP Upload queda disponible en el panel de nodos.

Requiere que la instancia tenga los paquetes comunitarios habilitados
(N8N_COMMUNITY_PACKAGES_ENABLED=true, que es el valor por defecto).

Para actualizar a una versión nueva publicada en npm, usar el botón de
actualizar del paquete en esa misma pantalla.

Instalación manual (alternativa, sin publicar)

Si se prefiere no publicar en npm, se puede instalar el paquete compilado a
mano.

# 1. Build
cd flows/n8n/custom-nodes/n8n-nodes-sftp-tp
npm install
npm run build

# 2. Registrarlo en la carpeta de extensiones de n8n
mkdir -p ~/.n8n/custom
cd ~/.n8n/custom
npm init -y                                    # sólo la primera vez
npm install /ruta/absoluta/al/clone/packages/n8n-nodes-sftp-tp

# 3. Reiniciar n8n

En Docker, ~/.n8n es un volumen montado (normalmente /home/node/.n8n); hay
que hacer el npm install contra esa ruta dentro del contenedor y reiniciarlo.

Uso

Upload

1. En el workflow, usar el nodo SFTP TP Upload.
2. Seleccionar la credencial SFTP del servidor target.
3. Propiedad Binaria: data. Ruta Remota: la ruta absoluta del archivo.
4. Dejar Opciones SSH sin tocar (usa los algoritmos legacy por defecto). Si
   aún así no conecta, activar Debug SSH para ver la negociación en los logs
   de n8n y, si hace falta, probar el campo Ident.

Lectura batch de archivos (Download + List)

Flujo recomendado para procesar archivos depositados periódicamente en una carpeta remota:

1. Cron que dispara según la frecuencia esperada (por día / por hora).
2. SFTP TP List sobre la carpeta remota, con Patrón De Nombre para filtrar (ej. *.csv). Salida: un item por archivo.
3. Filtro sobre el modifyTime para procesar sólo archivos nuevos (los anteriores ya están registrados como vistos en una base de estado del workflow).
4. SFTP TP Download sobre el path de cada entrada, con MIME Type apropiado y opcionalmente Borrar Remoto Después De Descargar si la cola es de un solo consumidor.
5. Code / parser que convierte el binario a registros estructurados.
6. Push al sistema de destino (CRM, base de datos, etc.) con la lógica de match correspondiente.

Tips operativos

• Si la lista trae muchos archivos viejos, conviene hacer cron incremental: usar el modifyTime máximo del día anterior como filtro.
• Para QA, prender Debug SSH en cualquiera de los 3 nodos y revisar los logs.
• Las opciones SSH se setean igual en los 3 nodos — si el server cambia algoritmos, hay que actualizar las defaults en los 3.

Nota

Este nodo es un workaround mientras el servidor SFTP target no habilite algoritmos
SSH modernos. Si en algún momento lo hacen, se puede volver al nodo SFTP
nativo de n8n.

Licencia

MIT — ver LICENSE.