Node Connector

Overview

Node Connector lets you create visual workflows by connecting plugin nodes on a canvas. Each node represents an action (run a script, SSH into a server, upload via FTP, rename files, etc.). Nodes pass data from one to the next, forming an execution chain.

Key Features

• Visual drag-and-drop node editor with SVG canvas
• Extensible plugin architecture — add plugins by dropping a JS file
• Three trigger modes: Cron (scheduled), Webhook (HTTP), Terminal (manual)
• Real-time execution monitoring via Server-Sent Events (SSE)
• Per-sheet scheduling with node-cron
• Multi-user authentication with JWT
• Single Docker image deployment (Nginx + API + Scheduler)

Architecture

Project Structure

Local Setup (no Docker)

Run Node Connector directly on your machine for full access to host tools (Python, CMD, bash, and any installed program). This is the recommended approach when you need terminal plugins to interact with your system.

Prerequisites

• Node.js 18+ installed on your machine

One-Command Start

# Windows — double-click start.bat or run:
start.bat

# Linux / macOS
./start.sh

# Or directly (any platform)
node start.js

The start.js launcher automatically:

1. Installs dependencies for API, frontend, and scheduler (if node_modules/ is missing)
2. Builds the frontend (if front/build/ doesn't exist)
3. Writes config.js pointing the frontend to the API
4. Starts the API server (which also serves the frontend static files)
5. Starts the scheduler (after a 3-second delay for API readiness)

How It Works

Without Docker, there is no Nginx. Instead, the Express API serves double duty — it handles both API routes (/auth, /sheet) and the frontend static files from front/build/. Everything runs on a single port.

Environment Variables

Set these before running start.js, or use the defaults:

Rebuilding the Frontend

The frontend is only built once. To rebuild after frontend code changes:

# Delete the build folder and restart
rm -rf front/build
node start.js

Auto-Start on Boot

To have Node Connector start automatically when the system boots, use the provided service scripts. They require elevated privileges.

Windows (Task Scheduler)

# Install — run as Administrator
service-install.bat

# Uninstall — run as Administrator
service-uninstall.bat

This creates a Windows Task Scheduler task named NodeConnector that runs node start.js at system startup under the SYSTEM account. To start immediately without rebooting:

schtasks /run /tn "NodeConnector"

Linux (systemd)

# Install
sudo ./service-install.sh

# Uninstall
sudo ./service-uninstall.sh

This creates a systemd service named node-connector that starts on boot with automatic restart on failure. Useful commands:

sudo systemctl status node-connector     # Check status
sudo systemctl stop node-connector       # Stop service
sudo systemctl restart node-connector    # Restart service
sudo journalctl -u node-connector -f     # View logs

Docker Deployment

Build & Run

docker build -t node-connector .
docker run -d -p 80:80 node-connector

With Required Secrets

All secret environment variables are required in production. The container will exit on startup if any are missing.

docker run -d -p 80:80 \
  -e JWT_SECRET=$(openssl rand -hex 32) \
  -e REFRESH_TOKEN_SECRET=$(openssl rand -hex 32) \
  -e INTERNAL_API_KEY=$(openssl rand -hex 32) \
  -e ENCRYPTION_KEY=$(openssl rand -hex 32) \
  node-connector

With Host Volume (for file operations)

# Linux / macOS
docker run -d -p 80:80 -v /path/on/host:/data node-connector

# Windows
docker run -d -p 80:80 -v C:\Users\You\Desktop:/data node-connector

Windows Quick Script (run.bat)

@echo off
REM Stops existing containers, rebuilds, and starts fresh
for /f "tokens=*" %%i in ('docker ps -q --filter "ancestor=node-connector"') do docker stop %%i
for /f "tokens=*" %%i in ('docker ps -aq --filter "ancestor=node-connector"') do docker rm %%i
docker build -t node-connector .
docker run -d -p 80:80 --name node-connector node-connector

Container Services

Authentication

The API uses JWT-based authentication with httpOnly cookies. Access tokens expire in 15 minutes and are automatically refreshed using a refresh token cookie (7-day expiry). Tokens are never exposed to JavaScript, preventing XSS-based token theft.

Authentication Method

Sheets

A sheet is a workflow definition containing a graph of connected nodes. Sheet metadata is stored in SQLite; node data is stored as JSON files.

Nodes

Nodes are the building blocks of a workflow. Each node uses a plugin and has configurable parameters, inputs (from upstream nodes), and outputs (to downstream nodes).

Node Structure

{
  "id": "uuid",
  "title": "Node Title",
  "className": "CustomScript",   // Plugin class name
  "position": { "x": 100, "y": 200 },
  "params": {
    "0": { "name": "Script", "alias": "script", "type": "big_string", "default": "...", "value": "..." }
  },
  "inputs": ["node-id-1"],       // IDs of upstream nodes
  "outputs": ["node-id-2"]       // IDs of downstream nodes
}

Execution

Single Node (Interactive)

SSE events have this shape:

{
  "id": "node-uuid",
  "result": { ... },          // Plugin output (after execution)
  "error": false,
  "message": "Done",
  "stage": "executed"          // "executing" | "executed"
}

Batch (All Root Nodes)

// Response
{
  "sheetUid": "...",
  "sheetName": "My Workflow",
  "results": [
    {
      "rootNodeId": "...",
      "rootNodeTitle": "Start",
      "status": "success",
      "nodes": [
        { "nodeId": "...", "title": "Custom Script", "result": { ... } }
      ]
    }
  ]
}

Webhook Trigger

Settings & Triggers

Trigger Types

Cron Schedule Options

Plugin System

Plugins are auto-discovered from the api/plugins/ directory. Any .js file exporting a class that extends Plugin is loaded automatically.

Base Plugin Class

const Plugin = require("./../src/models/plugin");

class MyPlugin extends Plugin {
  name()            { return "My Plugin"; }
  description()     { return "What this plugin does"; }
  icon()            { return "🔧"; }
  iconBase64()      { return null; }   // Optional: return "data:image/png;base64,..." for a custom image icon
  tags()            { return ["category"]; }

  paramsDefinition() {
    return [
      {
        name: "Param Name",      // Display label
        alias: "param_alias",    // Key in params object
        type: "string",          // "string" | "big_string" | "number" | "boolean" | "select" | "radio"
        secret: false,           // true = rendered as password field, encrypted at rest
        default: "default value",
        value: undefined
      }
    ];
  }

  async logic(params = {}) {
    // params.param_alias  = this node's configured value
    // params.input        = output from upstream nodes

    return {
      status: { error: false, message: "Success" },
      output: { key: "value" }  // Passed to downstream nodes
    };
  }
}

module.exports = MyPlugin;

Plugin Icons

Plugins support two icon modes:

• Emoji (default) — Return an emoji string from icon(). Rendered as SVG <text> on the canvas and <span> in the palette.
• Base64 image — Override iconBase64() to return a data URI (e.g., "data:image/png;base64,..."). Rendered as SVG <image> on the canvas and <img> in the palette. The emoji icon serves as a fallback if iconBase64() returns null.

Parameter Types

Secret Parameters

Add secret: true to any parameter definition to mark it as sensitive. Secret parameters are:

• Rendered as password fields (masked input) in the node editor
• Encrypted at rest using AES-256-GCM before saving to disk
• Automatically decrypted when the node is loaded for editing or execution

{ name: "Password", alias: "password", type: "string", secret: true, default: "", value: undefined }

Return Format

Every plugin's logic() must return:

{
  status: {
    error: boolean,    // true if execution failed
    message: string    // Human-readable status message
  },
  output: { ... }      // Data passed to downstream nodes via params.input
}

Available Plugins

async function main() {
  const fs = require('fs');

  // Access data from the previous node
  console.log("Received:", input);

  // Read files from mounted volume
  const files = fs.readdirSync('.');

  // Pass structured data to the next node
  output({ files, count: files.length });
}

Creating a Plugin

To create a new plugin, add a .js file in api/plugins/. It will be auto-discovered on the next API restart.

Step-by-step

1. Create a new file: api/plugins/my-plugin.js
2. Extend the Plugin base class
3. Implement all required methods
4. Export the class
5. Restart the API — the plugin appears automatically

Template

const Plugin = require("./../src/models/plugin");

class MyPlugin extends Plugin {
  name()        { return "My Plugin"; }
  description() { return "Describe what it does"; }
  icon()        { return "🚀"; }
  // iconBase64()  { return "data:image/png;base64,..."; }  // Optional: custom image icon
  tags()        { return ["custom"]; }

  paramsDefinition() {
    return [
      { name: "My Param", alias: "my_param", type: "string", default: "", value: undefined },
      { name: "API Key", alias: "api_key", type: "string", secret: true, default: "", value: undefined },  // encrypted at rest, shown as password field
      {
        name: "Method",
        alias: "method",
        type: "select",           // dropdown menu
        default: "GET",
        options: [
          { label: "GET", value: "GET" },
          { label: "POST", value: "POST" }
        ],
        value: undefined
      }
    ];
  }

  async logic(params = {}) {
    const myParam = params.my_param;
    const previousOutput = params.input || {};

    // Your logic here...
    this.log("Processing...");

    return {
      status: { error: false, message: "Done" },
      output: { result: "my output" }
    };
  }
}

module.exports = MyPlugin;

Data Flow Between Nodes

When nodes are connected, the output of one node becomes the input of the next. The execution engine handles this automatically.

Template Variables {{variable}}

Any node parameter can reference output from the previous node using {{variable}} syntax. The execution engine resolves these placeholders before the plugin runs.

Example: Custom Script → Rename File

How It Works Internally

1. Node A's logic() returns { status, output: { filepath: "...", newpath: "..." } }
2. The executer merges output into params.input for Node B
3. Before calling Node B's logic(), all string params are scanned for {{key}} patterns
4. Each {{key}} is replaced with the matching value from params.input
5. Node B receives the resolved values in its params

Variable Resolution Rules

Multi-Input Nodes

When a node has multiple input connections, the execution engine enforces these rules:

1. Wait for all inputs — The node will not execute until all upstream input nodes have completed.
2. Stop on failure — If any input node fails (error or exception), the dependent node is skipped with a "Skipped: a previous node failed" message. This failure propagates to all downstream nodes.
3. Merge all outputs — Outputs from all input nodes are merged into a single params.input object. If multiple inputs have the same output key, the last one wins (in connection order).

Accessing Input Programmatically

Built-in Plugins (SSH, FTP, Rename File)

Two ways to receive data from previous nodes:

// Option 1: Use {{variable}} in the parameter field in the UI
// Source Path: {{filepath}}
// The value is resolved before logic() is called

// Option 2: Access params.input directly in plugin code
async logic(params = {}) {
  const filePath = params.source_path || params.input.filepath;
}

Custom Script Plugin

The input variable is injected automatically into the script scope:

async function main() {
  // `input` contains the output from the previous node
  console.log("File:", input.filepath);   // "/data/report.txt"
  console.log("Count:", input.count);     // 42

  // Pass structured data to the next node
  output({ processed: true, path: input.filepath });
}

Full Chain Example

// ── Node 1: Custom Script ── "List files"
async function main() {
  const fs = require('fs');
  const files = fs.readdirSync('.');
  output({
    source: "/data/" + files[0],
    dest: "/data/archive/" + files[0]
  });
}
// Output: { source: "/data/report.txt", dest: "/data/archive/report.txt" }


// ── Node 2: Rename File ──
// Source Path field:  {{source}}   →  resolves to "/data/report.txt"
// Dest Path field:    {{dest}}     →  resolves to "/data/archive/report.txt"
// Output: { source_path, dest_path, filename }


// ── Node 3: Custom Script ── "Log result"
async function main() {
  console.log("Moved:", input.filename, "from", input.source_path);
  output({ status: "done" });
}

Execution History

Every non-test execution (cron, webhook, or terminal) is recorded in the execution history. Test executions from the UI editor are not recorded.

// History record
{
  "id": 1,
  "sheet_uid": "abc-123",
  "sheet_name": "My Workflow",
  "trigger_type": "cron",         // "cron" | "webhook" | "terminal"
  "status": "success",            // "success" | "error"
  "started_at": "2025-05-01T12:00:00.000Z",
  "duration_ms": 1523,
  "node_count": 4,
  "error_count": 0,
  "results_summary": "{...}"      // JSON string of full results
}

Trigger Type Tracking

Scheduler

The scheduler is a background service that manages per-sheet cron jobs. It runs inside the Docker container alongside the API.

How It Works

1. Starts with a 5-second delay (waits for API to be ready)
2. Every 30 seconds, syncs with the API:
   • Fetches all sheets via /sheet/list-internal
   • Filters for active sheets with trigger_type: "cron"
   • Creates new cron jobs for newly added sheets
   • Removes jobs for deleted or deactivated sheets
   • Updates jobs if the cron schedule changed
3. Each cron job calls /sheet/execute-batch on its schedule

CLI Tool

Execute sheets manually from the command line. The INTERNAL_API_KEY environment variable must be set.

Usage

# From inside the container
INTERNAL_API_KEY=your_key node cli.js <sheet-uid>

# From host (via docker exec)
docker exec node-connector node cli.js <sheet-uid>

# From host (via curl)
curl -X POST http://localhost/api/sheet/execute-batch \
  -H "Content-Type: application/json" \
  -H "X-Internal-Key: $INTERNAL_API_KEY" \
  -d '{"sheetUid":"<sheet-uid>"}'

Output

Sheet "My Workflow" executed successfully.

Root: Start Node [success]
  -> Custom Script: {"files":["a.txt","b.txt"]}
  -> Rename File: {"source_path":"/data/a.txt","dest_path":"/data/archive/a.txt"}

Frontend

The frontend is a React 19 single-page application built with Vite 6. It provides the visual workflow editor and sheet management interface.

Routes

Key Components

Sheet Editor Layout

Database Schema

The application uses SQLite for metadata and JSON files for sheet node data.

Users Table

CREATE TABLE users (
  id            INTEGER PRIMARY KEY AUTOINCREMENT,
  username      TEXT UNIQUE NOT NULL,
  password      TEXT NOT NULL,       -- bcrypt hashed
  refreshToken  TEXT
);

Sheets Table

CREATE TABLE sheets (
  id             INTEGER PRIMARY KEY AUTOINCREMENT,
  name           TEXT,
  uid            TEXT,                -- UUID
  slug           TEXT,                -- URL-safe name
  is_active      INTEGER DEFAULT 1,  -- 1 = active, 0 = inactive
  trigger_type   TEXT DEFAULT 'cron', -- 'cron' | 'webhook' | 'terminal'
  cron_schedule  TEXT DEFAULT '0 * * * *'
);

Execution History Table

CREATE TABLE execution_history (
  id              INTEGER PRIMARY KEY AUTOINCREMENT,
  sheet_uid       TEXT NOT NULL,
  sheet_name      TEXT,
  trigger_type    TEXT,              -- 'cron' | 'webhook' | 'terminal'
  status          TEXT,              -- 'success' | 'error'
  started_at      TEXT,              -- ISO 8601 timestamp
  duration_ms     INTEGER,
  node_count      INTEGER,
  error_count     INTEGER DEFAULT 0,
  results_summary TEXT               -- JSON string of full results
);

Sheet JSON Files

Stored at api/sheets/{uid}.json:

{
  "id": -1,
  "uid": "uuid",
  "name": "Sheet Name",
  "slug": "sheet-name",
  "data": {
    "nodes": [
      { "id": "...", "title": "...", "className": "...", "params": {...}, "inputs": [], "outputs": [] }
    ]
  }
}

Environment Variables

Generate strong secrets with:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Security

Authentication

• Passwords — Hashed with bcrypt (10 rounds)
• Access Tokens — JWT with 15-minute expiry, stored in httpOnly cookies (not accessible via JavaScript)
• Refresh Tokens — JWT with 7-day expiry, stored in DB per user and as httpOnly cookie scoped to /auth/refresh-token
• Cookie Flags — httpOnly, secure (production), sameSite=strict to prevent XSS and CSRF
• Token Revocation — On logout or password change, the access token is immediately blacklisted (in-memory). Blacklisted tokens are rejected by all authenticated endpoints. Expired entries are auto-cleaned every 5 minutes
• Internal Key — Separate auth for service-to-service calls
• No localStorage — Tokens are never stored in localStorage or exposed to client-side JavaScript

HTTP Security

• HTTPS Enforcement — In production (NODE_ENV=production), all HTTP requests are redirected to HTTPS via 301. Uses X-Forwarded-Proto from the reverse proxy. Disabled in development so HTTP works normally
• Helmet — Security headers (XSS protection, no sniff, etc.)
• CORS — Restricted to a single allowed origin via CORS_ORIGIN env var (defaults to http://localhost:PORT). Credentials (cookies) are included
• CSRF Protection — Double-submit cookie pattern. On login, a csrfToken cookie (readable by JavaScript) is set. The frontend sends it as the X-CSRF-Token header on every state-changing request (POST/PUT/DELETE). The server rejects requests where the header doesn't match the cookie. Login, register, and refresh-token routes are exempt. Internal API key routes are also exempt
• Nginx — Reverse proxy, no direct API exposure

Rate Limiting

Rate limit status is returned via standard headers (RateLimit-Policy, RateLimit-Remaining, RateLimit-Reset). When exceeded, the API responds with 429 Too Many Requests.

Credential Encryption

• Secret Parameters — Plugin params marked with secret: true are encrypted at rest using AES-256-GCM
• Encryption Key — Derived from ENCRYPTION_KEY env var via SHA-256. Must be changed in production
• Storage — Encrypted values are stored as { __encrypted, data, iv, tag } objects in sheet JSON files
• Backward Compatible — Existing plaintext values are automatically encrypted on the next save
• UI — Secret params render as masked password fields in the node editor

SSH Command Safety

• Command Sanitization — Null bytes and non-printable control characters are stripped from SSH commands before execution, preventing command truncation and injection via control sequences
• Connection Timeout — SSH connections time out after 10 seconds (readyTimeout) to prevent hangs on unreachable hosts
• Per-Command Timeout — Each command times out after 30 seconds, preventing runaway processes on the remote server
• Input Validation — Empty commands are filtered out, and required fields (host, username, command) are validated before any connection attempt

Custom Script Sandboxing

• Module Restrictions — Custom scripts cannot require() dangerous modules: child_process, cluster, worker_threads (process spawning) and net, dgram, tls, http, http2, https, dns (network access). Allowed modules include fs, path, crypto, os, etc.
• Environment Isolation — Child processes run with a minimal environment (PATH, HOME, TMPDIR, NODE_ENV only). Secrets like JWT_SECRET, ENCRYPTION_KEY, and INTERNAL_API_KEY are not accessible
• Execution Timeout — Scripts are killed after 30 seconds to prevent infinite loops or resource exhaustion
• No Shell Injection — Uses execFile() instead of exec(), bypassing shell interpretation entirely

Secure Temp Files

• Unpredictable Names — Temp script files use crypto.randomBytes(16) for filenames, preventing path-guessing attacks
• Private Directory — Each execution creates an isolated temp directory via fs.mkdtempSync() under os.tmpdir(), eliminating race conditions
• Restrictive Permissions — Temp files are written with mode 0600 (owner-only read/write), preventing other users from reading script contents
• Cleanup — The entire temp directory is recursively removed after execution completes

Path Traversal Protection

• Sandboxed Directory — All file-operation plugins (Read/Write File, Rename File, Download File, Zip) confine paths to a base directory (DATA_DIR env var, defaults to /data)
• Traversal Denied — Paths containing .. or other sequences that resolve outside the base directory are rejected with an error before any I/O occurs
• Affected Plugins — ReadWriteFile, RenameFile, DownloadFile, Zip, DatabaseQuery

SQL Injection Protection

• Identifier Validation — All table names, column names, and column types are validated against a strict whitelist regex (/^[a-zA-Z_][a-zA-Z0-9_]*$/) before use in SQL queries. Invalid identifiers are rejected with an error
• Quoted Identifiers — All validated identifiers are double-quoted in SQL statements to prevent injection even if the regex were bypassed
• Parameterized Values — All user-supplied values (column values, default values, LIMIT) use parameterized queries (? placeholders) instead of string interpolation
• Database Query Plugin — The Database Query plugin confines database paths to the DATA_DIR sandbox via safePath(), and opens databases in read-only mode for SELECT/PRAGMA/EXPLAIN queries

Input Validation

• Trigger type validated against allowed values
• Cron schedule validated with node-cron
• Custom scripts validated for async function main() via Babel parser
• Required fields checked on all mutation endpoints
• Node Params — All node create/update endpoints validate params arrays. Each param is sanitized to only allow known properties (name, alias, type, value, default, secret, options). Param type is validated against a whitelist (string, big_string, number, boolean, select, radio). Node position, inputs, and outputs fields are also type-checked

Password Policy

• Minimum Length — Passwords must be at least 8 characters
• Complexity — Must contain at least one lowercase letter, one uppercase letter, and one digit
• Common Password Check — Rejects passwords found in a built-in blocklist of commonly used passwords (e.g. password, 123456, admin123)
• Enforced On — Registration (POST /auth/register) and password change (PUT /auth/change-password)

Content Security Policy

• default-src — 'self' — only allow resources from the same origin by default
• script-src — 'self' — blocks inline scripts and external script sources
• style-src — 'self' 'unsafe-inline' — allows same-origin and inline styles (required by React)
• img-src — 'self' data: — allows same-origin images and data URIs (used for plugin icons)
• object-src — 'none' — blocks Flash/Java embeds
• frame-ancestors — 'none' — prevents the app from being embedded in iframes (clickjacking protection)
• Additional headers (X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security, etc.) are set automatically by helmet

Error Message Sanitization

• Generic Error Responses — User-facing API endpoints return generic error messages (e.g. "Registration failed", "Password change failed") instead of raw internal error details
• Server-Side Logging — Full error details are logged server-side via console.error for debugging, but never sent to clients
• Affected Endpoints — POST /auth/register, PUT /auth/change-password, GET /sheet/node/execute (SSE)
• Internal Endpoints — Internal-only endpoints (behind X-Internal-Key authentication) retain detailed error messages for service-to-service debugging

Client-Side Form Validation

• Register Form — Validates username (minimum 3 characters), password policy (minimum 8 characters, must include lowercase, uppercase, and digit), and password confirmation match before submitting
• Change Password Form — Validates new password against the same policy rules and confirms match before submitting
• Shared Utility — Both forms use a shared validate-password.js utility that mirrors the server-side password policy, providing instant feedback without a round-trip

Audit Logging

• Storage — All audit events are persisted to a dedicated audit_log SQLite table with timestamp, event type, user ID, username, IP address, and details
• Auth Events — login_success, login_failure (with reason: unknown user / wrong password), register, logout, password_change, token_refresh
• Sheet Events — sheet_create, sheet_update, sheet_delete (node deletion), sheet_settings_update, sheet_execute, webhook_trigger
• Non-Blocking — Audit log writes are fire-and-forget; failures are logged to console.error but never block the request
• Event Whitelist — Only predefined event types are accepted; unknown events are rejected to prevent log injection