### Security Model

1. **One-time Token**: 256-bit cryptographically random token (64 hex chars)
2. **Single Connection**: Only one download allowed per token
3. **Auto-shutdown**: Server closes after transfer completes or disconnects
4. **Token Validation**: Every request must include the correct token

### Data Flow

1. **Sender** (`send.js`):
   - Generates random port and security token
   - Starts HTTP server on ephemeral port
   - Streams file directly from disk to HTTP response
   - Auto-shutdown after transfer or timeout (5 min default)

2. **Receiver** (`receive.js`):
   - Connects to sender URL with token
   - Streams HTTP response directly to disk
   - Reports progress, speed, and completion status
   - Validates received bytes match expected size

---

## 📦 Requirements

- **Node.js**: 14.0.0 or higher
- **Network**: TCP connectivity between nodes (any port 1024-65535)
- **Firewall**: Must allow outbound connections and inbound on ephemeral ports
- **Disk Space**: Sufficient space on destination for received files

---

## 🚀 Installation

### The "Install Once" Pattern

Instead of deploying scripts on every transfer, we deploy them **once per node** and use a fast version check for subsequent transfers.

### Method 1: Using deploy.js (Recommended)

### Method 2: Manual Deployment

On each target node, create the directory and copy files:

---

## 💡 Usage

### Basic Transfer Workflow

### Using the Command Line

#### Sender

---

## 📚 API Reference

### send.js

Starts an HTTP server to stream a file.

**Usage:** `node send.js <filePath> [options]`

**Arguments:**
- `filePath` (required): Path to the file to send

**Options:**
- `--port <n>`: Use specific port (default: random ephemeral)
- `--timeout <n>`: Timeout in minutes (default: 5)

**Output (JSON):**
| Field | Type | Description |
|-------|------|-------------|
| `url` | string | HTTP URL for receiver to connect to |
| `token` | string | Security token (64 hex chars) |
| `fileSize` | number | File size in bytes |
| `fileName` | string | Original filename |
| `sourceIp` | string | IP address of sender |
| `port` | number | TCP port used |
| `version` | string | Version of send.js |

**Exit Codes:**
- `0`: Success (transfer completed or info displayed)
- `1`: Error (check stderr for JSON error details)

**Error Output (JSON):**

Error codes: `FILE_NOT_FOUND`, `NOT_A_FILE`, `SERVER_ERROR`, `TIMEOUT`, `READ_ERROR`, `RESPONSE_ERROR`

---

### receive.js

Connects to a sender and downloads a file.

**Usage:** `node receive.js <url> <token> <outputPath> [options]`

**Arguments:**
- `url` (required): URL from send.js output
- `token` (required): Security token from send.js output
- `outputPath` (required): Path to save the received file

**Options:**
- `--timeout <n>`: Connection timeout in seconds (default: 30)
- `--no-progress`: Suppress progress updates

**Output (JSON):**
| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | Always true on success |
| `bytesReceived` | number | Actual bytes received |
| `totalBytes` | number | Expected bytes (from Content-Length) |
| `duration` | number | Transfer time in seconds |
| `speedMBps` | number | Average speed in MB/s |
| `outputPath` | string | Absolute path to saved file |

**Progress Updates (when not using `--no-progress`):**

**Exit Codes:**
- `0`: Success
- `1`: Error (check stderr for JSON error details)

Error codes: `INVALID_ARGS`, `INVALID_URL`, `CONNECTION_ERROR`, `HTTP_ERROR`, `TIMEOUT`, `WRITE_ERROR`, `SIZE_MISMATCH`, `FILE_EXISTS`, `NO_DATA`

---

### ensure-installed.js

Fast check if node-transfer is installed on a node.

**Usage:** `node ensure-installed.js <targetDir>`

**Arguments:**
- `targetDir` (required): Directory to check

**Output (JSON):**

Installed:

┌──────────────┐     HTTP Stream      ┌──────────────┐
│  send.js     │ ◄──────────────────► │ receive.js   │
│  (Source)    │   (Token-protected)  │ (Destination)│
└──────────────┘                      └──────────────┘
       │                                     │
       ▼                                     ▼
┌──────────────┐                      ┌──────────────┐
│  Read Stream │                      │ Write Stream │
│  (fs.create  │                      │ (fs.create   │
│   ReadStream)│                      │  WriteStream)│
└──────────────┘                      └──────────────┘
       │                                     │
       ▼                                     ▼
┌──────────────┐                      ┌──────────────┐
│  File on     │                      │  File on     │
│  Disk        │                      │  Disk        │
└──────────────┘                      └──────────────┘

# Generate deployment script for a target node
node deploy.js E3V3

# This outputs a PowerShell script that you can execute via nodes.invoke()

# Create directory
mkdir C:/openclaw/skills/node-transfer/scripts -Force

# Copy these files (ensure UTF-8 without BOM encoding):
# - send.js
# - receive.js
# - ensure-installed.js
# - version.js