@miraj181/ipingyou 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skmirajulislam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# 🔗 iPingYou — SecureLink CLI
+
+Secure peer-to-peer remote access via SSH & Cloudflare Tunnels. A Node.js CLI tool that lets two machines establish an encrypted SSH connection through Cloudflare's network, coordinated by a lightweight broker.
+
+## Architecture
+
+```
+ Host Machine                  Broker (Express.js)              Client Machine
+┌──────────────┐   POST       ┌──────────────────┐   GET       ┌──────────────┐
+│ cloudflared  │──/register──▶│  In-Memory Map   │◀─/resolve──│  ipingyou    │
+│ tunnel :22   │   {uid,url}  │  AES-256-CBC     │   /:uid     │  connect     │
+│              │              │  1hr TTL expiry   │             │              │
+│  SSH daemon  │◀─────────────│──────────────────│─────────────│  SSH via     │
+│              │  cloudflared │                   │ ProxyCmd    │  ProxyCmd    │
+└──────────────┘  TCP proxy   └──────────────────┘             └──────────────┘
+```
+
+### Flow
+1. **Host** starts `ipingyou host` → generates an 8-char UID, spins up `cloudflared` tunnel, registers with broker
+2. **Host** shares UID with the client (verbally, chat, etc.)
+3. **Client** runs `ipingyou connect` → enters UID, broker resolves it to tunnel URL → SSH connects via cloudflared proxy
+4. On `Ctrl+C`, all spawned processes are killed via `tree-kill` and the UID is revoked from the broker
+
+## Quick Start
+
+### 1. Start the Broker (self-hosted or Render)
+
+```bash
+cd ipingyou
+cp .env.example .env
+npm install
+npm run broker
+# Broker: http://localhost:4000
+```
+
+### 2. Host Mode (Machine being accessed)
+
+```bash
+npx ipingyou host
+# or interactively:
+npx ipingyou
+```
+
+### 3. Client Mode (Machine accessing)
+
+```bash
+npx ipingyou connect
+# or interactively:
+npx ipingyou
+```
+
+## CLI Commands
+
+```
+ipingyou                    Interactive mode (prompts for host/client)
+ipingyou host               Start as host — allow remote access
+ipingyou connect            Start as client — access a remote machine
+ipingyou broker             Start the central broker server
+ipingyou broker -p 5000     Start broker on custom port
+```
+
+## Prerequisites
+
+| Tool | Required | Install |
+|------|----------|---------|
+| Node.js ≥18 | ✅ | [nodejs.org](https://nodejs.org) |
+| `ssh` | ✅ | Ships with macOS/Linux; `winget install Microsoft.OpenSSH.Client` on Windows |
+| `cloudflared` | ✅ | `brew install cloudflared` / [download](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) |
+
+The CLI auto-detects your OS and will attempt to install missing dependencies on Linux (apt/pacman) and guide you on macOS/Windows.
+
+## Project Structure
+
+```
+ipingyou/
+├── src/
+│   ├── cli.js              ← Main CLI entry (npx-ready, shebang)
+│   ├── server.js           ← Central Broker (Express.js)
+│   ├── lib/
+│   │   ├── cleanup.js      ← Graceful shutdown + tree-kill
+│   │   ├── crypto.js       ← AES-256-CBC encrypt/decrypt
+│   │   ├── platform.js     ← OS detection + dependency check
+│   │   └── uid.js          ← Random 8-char UID generator (nanoid)
+│   └── modes/
+│       ├── host.js         ← Host mode logic
+│       └── client.js       ← Client mode logic
+├── .env.example
+├── .gitignore
+├── package.json
+├── render.yaml             ← One-click Render deploy
+└── README.md
+```
+
+## Security
+
+- **AES-256-CBC** — Tunnel URLs are encrypted at rest in the broker's memory
+- **Random UIDs** — 8-char nanoid, not hardware-based; session dies = door locked forever
+- **1-hour TTL** — Broker auto-expires entries; no stale data
+- **Auto-revoke** — On `Ctrl+C`, UID is deleted from broker before exit
+- **tree-kill** — All child processes (cloudflared, SSH) are recursively killed on shutdown
+- **No persistence** — Broker uses in-memory Map only; server restart = clean slate
+
+## Deploy Broker to Render (Free)
+
+1. Push this repo to GitHub
+2. Go to [render.com/new](https://render.com/new)
+3. Click **"New Web Service"** → connect your repo
+4. Render auto-detects `render.yaml` → click **Deploy**
+5. Set `SECRET_KEY` in Render Dashboard → Environment
+6. Set `BROKER_URL` in your local `.env` to your Render URL
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SECRET_KEY` | Dev key | AES-256 hex key (64 chars) |
+| `BROKER_URL` | `http://localhost:4000` | Broker endpoint for CLI |
+| `BROKER_PORT` | `4000` | Port for broker server |
+
+## Differences from remote-penitrator
+
+| Aspect | remote-penitrator | iPingYou |
+|--------|-------------------|----------|
+| Interface | Shell scripts + web dashboard | Interactive Node.js CLI |
+| Direction | One-way (runner → C2) | Peer-to-peer (host ↔ client) |
+| UID System | Hardcoded PC IDs | Random per-session UIDs |
+| Process Mgmt | Manual | tree-kill auto-cleanup |
+| Install | Copy scripts | `npx ipingyou` |
+| Modes | Reporter only | Host + Client + Broker |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@miraj181/ipingyou",
+  "version": "1.0.0",
+  "description": "SecureLink-CLI — Secure peer-to-peer remote access via SSH & Cloudflare Tunnels",
+  "main": "src/cli.js",
+  "bin": {
+    "ipingyou": "src/cli.js",
+    "securelink": "src/cli.js"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/cli.js",
+    "broker": "node src/server.js",
+    "dev:broker": "nodemon src/server.js",
+    "dev:cli": "node src/cli.js",
+    "prepublishOnly": "node -e \"require('fs').accessSync('LICENSE')\" && node src/cli.js --help"
+  },
+  "keywords": [
+    "ssh",
+    "remote-access",
+    "cloudflare-tunnel",
+    "cloudflared",
+    "cli",
+    "peer-to-peer",
+    "securelink",
+    "tunnel",
+    "remote-desktop",
+    "p2p"
+  ],
+  "author": "skmirajulislam",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skmirajulislam/ipingyou.git"
+  },
+  "homepage": "https://github.com/skmirajulislam/ipingyou#readme",
+  "bugs": {
+    "url": "https://github.com/skmirajulislam/ipingyou/issues"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.5",
+    "execa": "^9.5.2",
+    "express": "^4.21.0",
+    "inquirer": "^12.3.2",
+    "nanoid": "^5.0.9",
+    "ora": "^8.1.1",
+    "tree-kill": "^1.2.2"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "module"
+}

package/src/cli.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+/**
+ * ============================================================
+ *  SecureLink-CLI  (ipingyou)
+ * ============================================================
+ *  Secure peer-to-peer remote access via SSH & Cloudflare
+ *  Tunnels.  Designed to run via npx or as a global install.
+ *
+ *  Usage:
+ *    npx ipingyou              — Interactive mode
+ *    npx ipingyou host         — Start as host directly
+ *    npx ipingyou connect      — Start as client directly
+ *    npx ipingyou broker       — Start the central broker
+ *
+ *  Security:
+ *    All tunnel URLs are AES-256-CBC encrypted on the CLI side.
+ *    The broker is a zero-knowledge relay — it NEVER sees plaintext.
+ * ============================================================
+ */
+
+import 'dotenv/config';
+import { Command } from 'commander';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+
+import { detectOS, checkDependencies } from './lib/platform.js';
+import { installShutdownHandlers } from './lib/cleanup.js';
+import { startHostMode } from './modes/host.js';
+import { startClientMode } from './modes/client.js';
+
+// ─── ASCII Banner ────────────────────────────────────────────
+function showBanner() {
+  console.log('');
+  console.log(chalk.cyan.bold('  ╔═══════════════════════════════════════════╗'));
+  console.log(chalk.cyan.bold('  ║                                           ║'));
+  console.log(chalk.cyan.bold('  ║') + chalk.white.bold('     🔗  iPingYou  —  SecureLink CLI  ') + chalk.cyan.bold('     ║'));
+  console.log(chalk.cyan.bold('  ║                                           ║'));
+  console.log(chalk.cyan.bold('  ║') + chalk.dim('   Secure P2P Remote Access via SSH +  ') + chalk.cyan.bold('    ║'));
+  console.log(chalk.cyan.bold('  ║') + chalk.dim('   Cloudflare Tunnels  |  AES-256-CBC ') + chalk.cyan.bold('    ║'));
+  console.log(chalk.cyan.bold('  ║                                           ║'));
+  console.log(chalk.cyan.bold('  ╚═══════════════════════════════════════════╝'));
+  console.log('');
+}
+
+function showSystemInfo() {
+  const osInfo = detectOS();
+  const platform = osInfo.isLinux ? '🐧 Linux' : osInfo.isMac ? '🍎 macOS' : '🪟 Windows';
+  console.log(chalk.dim(`  ${platform}  |  ${osInfo.arch}  |  ${osInfo.hostname}  |  Node ${process.version}`));
+  console.log('');
+}
+
+function showRichHelp() {
+  console.log(chalk.bold.yellow('  ✨ Welcome to iPingYou SecureLink CLI! ✨'));
+  console.log(chalk.dim('  ───────────────────────────────────────────────────────'));
+  console.log(chalk.cyan('  A zero-knowledge peer-to-peer remote access tool.'));
+  console.log(chalk.cyan('  Securely share your local SSH terminal with anyone over the internet.'));
+  console.log('');
+  
+  console.log(chalk.bold.white('  🚀 Usage Modes:'));
+  console.log(`    ${chalk.green('host')}    : Generates a secure session UID and exposes your local machine.`);
+  console.log(`    ${chalk.blue('connect')} : Prompts for a UID to connect to a remote host.`);
+  console.log(`              ${chalk.dim('Supports Interactive SSH Shell & SCP File Transfers')}`);
+  console.log(`    ${chalk.yellow('broker')}  : Start your own relay server (for self-hosting).`);
+  console.log('');
+  
+  console.log(chalk.bold.white('  🔒 Security Architecture:'));
+  console.log(`    • Cloudflare Tunnels punch through NAT/Firewalls securely.`);
+  console.log(`    • ${chalk.green('End-to-End Encryption')}: Tunnel URLs are AES-256 encrypted locally.`);
+  console.log(`    • The Broker never sees your plaintext URL, only ciphertext.`);
+  console.log('');
+
+  console.log(chalk.bold.white('  💡 Examples:'));
+  console.log(`    $ npx ipingyou          ${chalk.dim('# Interactive wizard (Recommended)')}`);
+  console.log(`    $ npx ipingyou host     ${chalk.dim('# Quick start as Host')}`);
+  console.log(`    $ npx ipingyou connect  ${chalk.dim('# Quick start as Client')}`);
+  console.log(`    $ npx ipingyou broker   ${chalk.dim('# Start Relay')}`);
+  console.log('');
+}
+
+/**
+ * Fatal error handler — logs and exits with code 1.
+ * @param {string} context  — which command/mode failed
+ * @param {Error}  err      — the error object
+ */
+function fatal(context, err) {
+  console.error('');
+  console.error(chalk.red(`  ❌ FATAL [${context}]`));
+  console.error(chalk.red(`     ${err.message}`));
+  if (err.stack) {
+    const stackLines = err.stack.split('\n').slice(1, 4);
+    stackLines.forEach(line => console.error(chalk.dim(`     ${line.trim()}`)));
+  }
+  console.error('');
+  process.exit(1);
+}
+
+// ─── Interactive Mode Selection ──────────────────────────────
+async function interactiveMode() {
+  showBanner();
+  showSystemInfo();
+
+  // Check dependencies first
+  const deps = await checkDependencies();
+
+  if (!deps.ssh || !deps.cloudflared) {
+    const { proceed } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'proceed',
+        message: 'Some dependencies are missing. Continue anyway?',
+        default: false,
+      },
+    ]);
+    if (!proceed) {
+      console.log(chalk.dim('  Install the missing tools and try again.'));
+      process.exit(0);
+    }
+  }
+
+  // Mode selection
+  const { mode } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'mode',
+      message: 'What would you like to do?',
+      choices: [
+        {
+          name: `${chalk.green('🛡️  Allow Remote Access')}  ${chalk.dim('— Let someone connect to this machine')}`,
+          value: 'host',
+        },
+        {
+          name: `${chalk.blue('🌐 Access a Remote Machine')}  ${chalk.dim('— Connect to a host via their UID (SSH/SCP)')}`,
+          value: 'client',
+        },
+        new inquirer.Separator(),
+        {
+          name: `${chalk.yellow('📡 Start Broker Server')}  ${chalk.dim('— Run the central relay (for self-hosting)')}`,
+          value: 'broker',
+        },
+        {
+          name: `${chalk.magenta('📖 Help / Information')}   ${chalk.dim('— Learn how iPingYou works')}`,
+          value: 'help',
+        },
+      ],
+    },
+  ]);
+
+  switch (mode) {
+    case 'host':
+      await startHostMode();
+      break;
+    case 'client':
+      await startClientMode();
+      break;
+    case 'broker':
+      await startBroker();
+      break;
+    case 'help':
+      showRichHelp();
+      break;
+  }
+}
+
+// ─── Broker Start ────────────────────────────────────────────
+async function startBroker() {
+  console.log(chalk.cyan('  Starting broker server...'));
+  console.log('');
+  // Dynamically import the server (it self-starts on import)
+  await import('./server.js');
+}
+
+// ─── Commander Setup ─────────────────────────────────────────
+const program = new Command();
+
+program
+  .name('ipingyou')
+  .description('SecureLink-CLI — Secure P2P remote access via SSH & Cloudflare Tunnels')
+  .version('1.0.0')
+  .addHelpText('beforeAll', () => {
+    showBanner();
+    showRichHelp();
+    return '';
+  });
+
+program
+  .command('host')
+  .description('Start host mode — allow remote access to this machine')
+  .action(async () => {
+    try {
+      showBanner();
+      showSystemInfo();
+      installShutdownHandlers();
+      await checkDependencies();
+      await startHostMode();
+    } catch (err) {
+      fatal('host', err);
+    }
+  });
+
+program
+  .command('connect')
+  .description('Connect to a remote machine via its UID (SSH or SCP)')
+  .option('-u, --uid <uid>', 'The remote host UID')
+  .action(async () => {
+    try {
+      showBanner();
+      showSystemInfo();
+      installShutdownHandlers();
+      await checkDependencies();
+      await startClientMode();
+    } catch (err) {
+      fatal('connect', err);
+    }
+  });
+
+program
+  .command('broker')
+  .description('Start the central broker server')
+  .option('-p, --port <port>', 'Port to listen on', '4000')
+  .action(async (opts) => {
+    try {
+      if (opts.port) process.env.BROKER_PORT = opts.port;
+      showBanner();
+      await startBroker();
+    } catch (err) {
+      fatal('broker', err);
+    }
+  });
+
+// ─── Default: interactive mode ──────────────────────────────
+program.action(async () => {
+  try {
+    installShutdownHandlers();
+    await interactiveMode();
+  } catch (err) {
+    fatal('interactive', err);
+  }
+});
+
+program.parse();

package/src/lib/animations.js

@@ -0,0 +1,226 @@
+/**
+ * ============================================================
+ *  CLI Animations & Visual Effects
+ * ============================================================
+ *  Custom spinners, progress bars, and animated text effects
+ *  for a premium CLI experience.
+ * ============================================================
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+
+// ─── Custom Spinner Frames ────────────────────────────────────
+
+/** Cyber-themed spinner for encryption operations */
+export const cryptoSpinner = {
+  interval: 100,
+  frames: [
+    chalk.green('🔐 ▰▱▱▱▱▱▱'),
+    chalk.green('🔐 ▰▰▱▱▱▱▱'),
+    chalk.green('🔐 ▰▰▰▱▱▱▱'),
+    chalk.green('🔐 ▰▰▰▰▱▱▱'),
+    chalk.green('🔐 ▰▰▰▰▰▱▱'),
+    chalk.green('🔐 ▰▰▰▰▰▰▱'),
+    chalk.green('🔐 ▰▰▰▰▰▰▰'),
+    chalk.cyan('🔓 ▰▰▰▰▰▰▰'),
+  ],
+};
+
+/** Network pulse for connection operations */
+export const networkSpinner = {
+  interval: 120,
+  frames: [
+    chalk.cyan('📡 ·     '),
+    chalk.cyan('📡 ··    '),
+    chalk.cyan('📡 ···   '),
+    chalk.cyan('📡 ····  '),
+    chalk.cyan('📡 ····· '),
+    chalk.cyan('📡 ······'),
+    chalk.blue('📡 ─────→'),
+    chalk.green('📡 ═════►'),
+  ],
+};
+
+/** Tunnel establishment animation */
+export const tunnelSpinner = {
+  interval: 150,
+  frames: [
+    chalk.yellow('🌐 ╸       '),
+    chalk.yellow('🌐 ═╸      '),
+    chalk.yellow('🌐 ══╸     '),
+    chalk.cyan('🌐 ═══╸    '),
+    chalk.cyan('🌐 ════╸   '),
+    chalk.blue('🌐 ═════╸  '),
+    chalk.blue('🌐 ══════╸ '),
+    chalk.green('🌐 ═══════►'),
+  ],
+};
+
+/** File transfer animation */
+export const fileTransferSpinner = {
+  interval: 100,
+  frames: [
+    chalk.yellow('📦 [          ] 0%  '),
+    chalk.yellow('📦 [█         ] 10% '),
+    chalk.yellow('📦 [██        ] 20% '),
+    chalk.cyan(  '📦 [███       ] 30% '),
+    chalk.cyan(  '📦 [████      ] 40% '),
+    chalk.cyan(  '📦 [█████     ] 50% '),
+    chalk.blue(  '📦 [██████    ] 60% '),
+    chalk.blue(  '📦 [███████   ] 70% '),
+    chalk.green( '📦 [████████  ] 80% '),
+    chalk.green( '📦 [█████████ ] 90% '),
+    chalk.green( '📦 [██████████] 100%'),
+  ],
+};
+
+/** SSH handshake animation */
+export const sshSpinner = {
+  interval: 130,
+  frames: [
+    chalk.yellow('🔑 ·         '),
+    chalk.yellow('🔑 ··        '),
+    chalk.cyan(  '🔑 ···       '),
+    chalk.cyan(  '🔑 ····      '),
+    chalk.blue(  '🔑 ·····     '),
+    chalk.blue(  '🔑 ······    '),
+    chalk.green( '🔑 ·······   '),
+    chalk.green( '🔑 ✓ verified'),
+  ],
+};
+
+// ─── Animated Spinner Helpers ─────────────────────────────────
+
+/**
+ * Create a styled ora spinner with a custom animation.
+ * @param {string} text  — spinner label
+ * @param {object} spinnerDef — { interval, frames }
+ * @returns {import('ora').Ora}
+ */
+export function createSpinner(text, spinnerDef) {
+  return ora({ text, spinner: spinnerDef });
+}
+
+/**
+ * Animated multi-step progress display.
+ * Runs through each step with a delay and animation.
+ *
+ * @param {Array<{text: string, duration: number, spinner?: object}>} steps
+ */
+export async function animatedSteps(steps) {
+  for (const step of steps) {
+    const spinnerDef = step.spinner || networkSpinner;
+    const spinner = ora({ text: step.text, spinner: spinnerDef }).start();
+    await sleep(step.duration);
+    spinner.succeed(step.text);
+  }
+}
+
+/**
+ * Display an animated connection trace.
+ * Shows a visual path from local → tunnel → remote.
+ */
+export async function showConnectionTrace(localLabel, remoteLabel) {
+  const width = 40;
+  const steps = [
+    { pos: 0,  char: '╸',  color: chalk.yellow },
+    { pos: 5,  char: '══╸', color: chalk.yellow },
+    { pos: 10, char: '════╸', color: chalk.cyan },
+    { pos: 15, char: '══════╸', color: chalk.cyan },
+    { pos: 20, char: '════════╸', color: chalk.blue },
+    { pos: 25, char: '══════════╸', color: chalk.blue },
+    { pos: 30, char: '════════════╸', color: chalk.green },
+    { pos: 35, char: '══════════════►', color: chalk.green },
+  ];
+
+  console.log('');
+  console.log(chalk.dim('  ┌─────────────────────────────────────────────────────┐'));
+  console.log(chalk.dim('  │') + `  ${chalk.cyan(localLabel)}  →  ${chalk.magenta('☁ Cloudflare')}  →  ${chalk.green(remoteLabel)}  ` + chalk.dim('│'));
+  console.log(chalk.dim('  └─────────────────────────────────────────────────────┘'));
+
+  for (const step of steps) {
+    const line = `  ${step.color(step.char)}`;
+    process.stdout.write(`\r${line}`);
+    await sleep(120);
+  }
+  process.stdout.write('\r' + ' '.repeat(60) + '\r');
+}
+
+/**
+ * Show a pulsing "LIVE" indicator.
+ * @param {string} message
+ * @param {number} pulses — how many times to pulse
+ */
+export async function pulseText(message, pulses = 3) {
+  const colors = [chalk.red.bold, chalk.red, chalk.yellow, chalk.green, chalk.green.bold];
+  for (let i = 0; i < pulses; i++) {
+    for (const colorFn of colors) {
+      process.stdout.write(`\r  ${colorFn('●')} ${message}`);
+      await sleep(100);
+    }
+  }
+  process.stdout.write(`\r  ${chalk.green.bold('●')} ${message}\n`);
+}
+
+/**
+ * Typing effect — prints text character by character.
+ * @param {string} text
+ * @param {number} charDelay — ms per character
+ */
+export async function typeText(text, charDelay = 25) {
+  for (const char of text) {
+    process.stdout.write(char);
+    await sleep(charDelay);
+  }
+  console.log('');
+}
+
+/**
+ * Draw a gradient progress bar.
+ * @param {number} percent — 0-100
+ * @param {number} width   — bar width in chars
+ */
+export function progressBar(percent, width = 30) {
+  const filled = Math.round((percent / 100) * width);
+  const empty = width - filled;
+  const filledStr = '█'.repeat(filled);
+  const emptyStr = '░'.repeat(empty);
+
+  let coloredFilled;
+  if (percent < 30) coloredFilled = chalk.red(filledStr);
+  else if (percent < 60) coloredFilled = chalk.yellow(filledStr);
+  else if (percent < 90) coloredFilled = chalk.cyan(filledStr);
+  else coloredFilled = chalk.green(filledStr);
+
+  return `${coloredFilled}${chalk.dim(emptyStr)} ${chalk.white.bold(`${percent}%`)}`;
+}
+
+/**
+ * Simulate a file transfer progress animation.
+ * @param {string} filename
+ * @param {string} direction — 'upload' or 'download'
+ * @param {number} durationMs — total animation time
+ */
+export async function simulateTransferProgress(filename, direction, durationMs = 2000) {
+  const icon = direction === 'upload' ? '📤' : '📥';
+  const verb = direction === 'upload' ? 'Sending' : 'Receiving';
+  const steps = 20;
+  const stepDelay = durationMs / steps;
+
+  console.log('');
+  for (let i = 0; i <= steps; i++) {
+    const pct = Math.round((i / steps) * 100);
+    const bar = progressBar(pct);
+    process.stdout.write(`\r  ${icon} ${verb} ${chalk.white.bold(filename)}  ${bar}`);
+    await sleep(stepDelay);
+  }
+  console.log('');
+  console.log(`  ${chalk.green('✓')} ${verb} complete: ${chalk.cyan(filename)}`);
+}
+
+// ─── Utility ──────────────────────────────────────────────────
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}