wireshade 1.0.0

package/README.md

@@ -0,0 +1,258 @@
+# 👻 WireShade using Node.js
+
+**The Ultimate Userspace WireGuard® Implementation for Node.js**
+
+[![npm version](https://img.shields.io/npm/v/wireshade.svg)](https://www.npmjs.com/package/wireshade)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**WireShade** enables your Node.js application to connect directly to a WireGuard VPN **without root privileges**, kernel modules, or modifying system network settings. It runs entirely in userspace using a custom Rust-based TCP/IP stack (`smoltcp`) integrated directly into Node.js.
+
+<div align="center">
+
+[🇺🇸 English](README.md) | [🇩🇪 Deutsch](README.de.md) | [🇪🇸 Español](README.es.md) | [🇫🇷 Français](README.fr.md) | [🇨🇳 中文](README.zh.md)
+
+</div>
+
+---
+
+## 🚀 Why WireShade?
+
+WireShade solves complex networking implementation challenges with a clean, native userspace solution:
+
+*   **🛡️ Stealth & Security:** Route specific Node.js traffic through a secure WireGuard VPN while keeping the rest of your system traffic normal. Perfect for **web scraping**, **bots**, or **secure communication**.
+*   **🌍 Reverse Tunneling:** Expose a local Express server, WebSocket server, or Next.js app to the private VPN network, even if you are behind a NAT or firewall.
+*   **🔌 Zero-Config Client:** No need to install WireGuard on the host machine. Just `npm install` and go.
+*   **🔄 Automatic Reconnection:** Built-in logic to handle connection drops and network changes seamlessly.
+*   **⚡ High Performance:** Powered by Rust and NAPI-RS for near-native performance.
+
+## 🧠 How it Works (Technical Deep Dive)
+
+WireShade bypasses the host operating system's network stack by running a **userspace TCP/IP stack** ([smoltcp](https://github.com/smoltcp-rs/smoltcp)) inside your Node.js process. 
+
+1.  **Handshake:** WireShade establishes a WireGuard handshake over UDP.
+2.  **Encapsulation:** IP packets are encrypted and encapsulated within UDP packets.
+3.  **Userspace Routing:** Decrypted packets are handled by `smoltcp` in Rust, which manages TCP state, retransmission, and buffering.
+4.  **Node.js Integration:** Data moves between Rust streams and Node.js `net.Socket`/`http.Agent` instances via high-performance NAPI bindings.
+
+This architecture means:
+- **No Virtual Network Interface (TUN/TAP)** is created on your OS.
+- **Root privileges are NOT required.**
+- **No conflict** with existing VPNs or system networking.
+- **Cross-platform** compatibility (Windows, macOS, Linux, **Raspberry Pi**, Docker containers) without kernel modules.
+
+## 📦 Installation
+
+```bash
+npm install wireshade
+```
+
+_Note: Windows users need basic build tools (Visual Studio Build Tools) if prebuilds are not available, but prebuilt binaries are planned._
+
+---
+
+## 🛠️ Usage Examples
+
+All examples assume you have initialized the client:
+```javascript
+const { WireShade, readConfig } = require('wireshade');
+const client = new WireShade(readConfig('./wg0.conf'));
+await client.start();
+```
+
+### 1. HTTP/HTTPS Requests (Client)
+Use WireShade as a transparent agent for your requests.
+
+**Simplified API:**
+```javascript
+const html = await client.get('https://internal.service/api');
+console.log(html);
+```
+
+**Native `http`/`https` Module:**
+```javascript
+const https = require('https');
+
+https.get('https://api.internal/data', { agent: client.getHttpsAgent() }, (res) => {
+    res.pipe(process.stdout);
+});
+```
+
+**Axios:**
+```javascript
+const axios = require('axios');
+
+// Configure Axios to use the VPN agent
+const response = await axios.get('https://internal.service/api', {
+    httpAgent: client.getHttpAgent(),
+    httpsAgent: client.getHttpsAgent()
+});
+```
+
+**Fetch (`node-fetch`):**
+```javascript
+const fetch = require('node-fetch');
+
+const response = await fetch('https://internal.service/api', {
+    agent: (parsedUrl) => {
+        return parsedUrl.protocol === 'https:' 
+            ? client.getHttpsAgent() 
+            : client.getHttpAgent();
+    }
+});
+```
+
+### 2. TCP & WebSockets to VPN (Client)
+Connect to raw TCP services or WebSockets running inside the VPN.
+
+**Raw TCP:**
+```javascript
+const socket = client.connect({ host: '10.0.0.5', port: 22 });
+socket.write('SSH-2.0-MyClient\r\n');
+```
+
+**WebSockets (using `ws` library):**
+```javascript
+const WebSocket = require('ws');
+
+// Use the WireShade agent for the handshake
+const ws = new WebSocket('ws://10.0.0.5:8080/stream', {
+    agent: client.getHttpAgent() 
+});
+
+ws.on('open', () => console.log('Connected to VPN WebSocket!'));
+```
+
+### 3. Expose Local Servers (Express, Next.js, WebSockets)
+Make your local server accessible **only** via the VPN (Reverse Tunneling).
+
+**Express / Next.js / Fastify:**
+```javascript
+const express = require('express');
+const http = require('http');
+const { WireShadeServer } = require('wireshade');
+
+// 1. Setup your App
+const app = express();
+app.get('/', (req, res) => res.send('🎉 Hidden inside the VPN!'));
+
+// 2. Create standard HTTP server (not listening yet)
+const httpServer = http.createServer(app);
+
+// 3. Listen on the VPN
+const vpnServer = new WireShadeServer(client);
+vpnServer.on('connection', (socket) => {
+    httpServer.emit('connection', socket); // Feed VPN socket to HTTP server
+});
+
+await vpnServer.listen(80); // Listen on Port 80 of the VPN IP
+console.log('Server online at http://<VPN-IP>/');
+```
+
+**WebSocket Server:**
+```javascript
+const { WebSocketServer } = require('ws');
+const wss = new WebSocketServer({ noServer: true });
+
+httpServer.on('upgrade', (req, socket, head) => {
+    wss.handleUpgrade(req, socket, head, (ws) => {
+        wss.emit('connection', ws, req);
+    });
+});
+```
+
+### 4. Port Forwarding
+WireShade supports both **Local Forwarding** (access VPN service locally) and **Remote Forwarding** (expose local service to VPN).
+
+**Local Forwarding (VPN -> Localhost):**
+Access a PostgreSQL database running at `10.0.0.5:5432` inside the VPN via `localhost:3333`.
+```javascript
+await client.forwardLocal(3333, '10.0.0.5', 5432);
+console.log('Connect to DB at localhost:3333');
+```
+
+**Remote Forwarding (Localhost -> VPN):**
+Expose your local development server (`localhost:3000`) to the VPN on port `8080`.
+```javascript
+// Listen on VPN Port 8080 -> Forward to localhost:3000
+await client.forwardRemote(8080, 'localhost', 3000);
+console.log('VPN users can access your dev server at http://<VPN-IP>:8080');
+```
+
+---
+
+## ⚙️ Configuration & Features
+
+### Auto-Reconnection
+WireShade includes robust reconnection logic.
+
+```javascript
+const client = new WireShade({
+    wireguard: { ... },
+    reconnect: {
+        enabled: true,
+        maxAttempts: 10,
+        delay: 1000,           // Start with 1s delay
+        backoffMultiplier: 1.5 // Exponential backoff
+    }
+});
+
+client.on('reconnecting', (attempt) => console.log(`🔄 Reconnecting... (${attempt})`));
+```
+
+### Custom DNS / Hosts
+Map internal VPN hostnames to IPs without touching `/etc/hosts`.
+
+```javascript
+const client = new WireShade({
+    wireguard: { ... },
+    hosts: {
+        'internal-api.local': '10.0.0.4',
+        'db-prod': '10.0.0.5'
+    }
+});
+```
+
+## 📚 API Reference
+
+**`new WireShade(config)`**
+- Creates a new VPN instance. `config` matches standard WireGuard parameters (`privateKey`, `endpoint`, etc.).
+
+**`client.start()`**
+- Connects to the VPN. Returns a `Promise` that resolves on connection.
+
+**`client.get(url, [options])`**
+- Helper to make a simple HTTP GET request through the VPN. Returns connection body.
+
+**`client.connect(options)`**
+- Creates a raw TCP socket (`net.Socket`) connected through the tunnel.
+
+**`client.listen(port, [callback])`**
+- Starts a TCP server listening on the **VPN IP** at the specified port.
+
+**`client.forwardLocal(localPort, remoteHost, remotePort)`**
+- Forwards a local port to a remote destination inside the VPN.
+
+**`client.forwardRemote(vpnPort, targetHost, targetPort)`**
+- Forwards a listener on the VPN IP to a target on your local machine.
+
+**`client.getHttpAgent() / client.getHttpsAgent()`**
+- Returns a Node.js `http.Agent` / `https.Agent` configured to route traffic through the tunnel.
+
+---
+
+---
+
+## 🎯 Use Cases
+
+*   **Microservices Communication:** Connect secure microservices across different clouds without exposing public ports.
+*   **Web Scraping:** Rotate IP addresses by creating multiple WireShade instances connected to different VPN endpoints.
+*   **Development Access:** Give developers access to private internal databases from their local machines securely.
+*   **IoT & Edge:** Connect edge devices behind restrictive NATs back to a central server using server mode.
+
+---
+
+## 📜 License
+
+MIT License.
+
+*WireGuard is a registered trademark of Jason A. Donenfeld.*

package/README.zh.md

@@ -0,0 +1,109 @@
+# 👻 WireShade Node.js 版
+
+**Node.js 终极用户态 WireGuard® 实现**
+
+[![npm version](https://img.shields.io/npm/v/wireshade.svg)](https://www.npmjs.com/package/wireshade)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**WireShade** 使您的 Node.js 应用程序能够直接连接到 WireGuard VPN，而**无需 root 权限**、内核模块或修改系统网络设置。它使用直接集成到 Node.js 中的自定义 Rust TCP/IP 栈（`smoltcp`）完全在用户态运行。
+
+<div align="center">
+
+[🇺🇸 English](README.md) | [🇩🇪 Deutsch](README.de.md) | [🇪🇸 Español](README.es.md) | [🇫🇷 Français](README.fr.md) | [🇨🇳 中文](README.zh.md)
+
+</div>
+
+---
+
+## 🚀 为什么选择 WireShade？
+
+WireShade 以干净的原生用户态解决方案解决了复杂的网络实现挑战：
+
+*   **🛡️ 隐蔽与安全：** 通过安全的 WireGuard VPN 路由特定的 Node.js 流量，同时保持其余系统流量正常。非常适合 **Web 爬虫**、**机器人**或**安全通信**。
+*   **🌍 反向隧道：** 将本地 Express 服务器、WebSocket 服务器或 Next.js 应用程序暴露给私有 VPN 网络，即使您在 NAT 或防火墙后面。
+*   **🔌 零配置客户端：** 无需在主机上安装 WireGuard。只需 `npm install` 即可。
+*   **🔄 自动重连：** 内置逻辑，可无缝处理连接断开和网络更改。
+*   **⚡ 高性能：** 由 Rust 和 NAPI-RS 提供支持，具有近乎原生的性能。
+
+## 📦 安装
+
+```bash
+npm install wireshade
+```
+
+---
+
+## 🛠️ 使用示例
+
+所有示例均假设您已初始化客户端：
+```javascript
+const { WireShade, readConfig } = require('wireshade');
+const client = new WireShade(readConfig('./wg0.conf'));
+await client.start();
+```
+
+### 1. HTTP/HTTPS请求 (客户端)
+使用 WireShade 作为请求的透明代理。
+
+**原生 `http`/`https` 模块：**
+```javascript
+const https = require('https');
+
+https.get('https://api.internal/data', { agent: client.getHttpsAgent() }, (res) => {
+    res.pipe(process.stdout);
+});
+```
+
+**Axios：**
+```javascript
+const axios = require('axios');
+
+const response = await axios.get('https://internal.service/api', {
+    httpAgent: client.getHttpAgent(),
+    httpsAgent: client.getHttpsAgent()
+});
+```
+
+### 2. TCP & WebSockets 到 VPN (客户端)
+连接到 VPN 内部运行的原始 TCP 服务或 WebSocket。
+
+**WebSockets：**
+```javascript
+const WebSocket = require('ws');
+
+const ws = new WebSocket('ws://10.0.0.5:8080/stream', {
+    agent: client.getHttpAgent() 
+});
+
+ws.on('open', () => console.log('已连接到 VPN WebSocket！'));
+```
+
+### 3. 暴露本地服务器 (反向隧道)
+使您的本地服务器**仅**通过 VPN 可访问。
+
+**Express / Next.js：**
+```javascript
+const express = require('express');
+const http = require('http');
+const { WireShadeServer } = require('wireshade');
+
+const app = express();
+app.get('/', (req, res) => res.send('🎉 隐藏在 VPN 内部！'));
+
+const httpServer = http.createServer(app);
+const vpnServer = new WireShadeServer(client);
+
+// 将 VPN 套接字传输到 HTTP 服务器
+vpnServer.on('connection', (socket) => httpServer.emit('connection', socket));
+
+await vpnServer.listen(80);
+console.log('服务器在线地址 http://<VPN-IP>/');
+```
+
+---
+
+## 📜 许可证
+
+MIT 许可证。
+
+*WireGuard 是 Jason A. Donenfeld 的注册商标。*

package/build.rs

@@ -0,0 +1,5 @@
+extern crate napi_build;
+
+fn main() {
+    napi_build::setup();
+}

package/examples/01_quickstart.js

@@ -0,0 +1,36 @@
+const { WireShade } = require('../index');
+const path = require('path');
+
+async function main() {
+    console.log("--- Zero-Config WireShade Demo ---");
+
+    // 1. Initialize
+    const gw = new WireShade(path.join(__dirname, 'wireguard.conf'));
+
+    // 2. Connect
+    console.log("Connecting...");
+    await gw.start();
+    console.log("✅ VPN Connected!");
+
+    // 3. Simple HTTP Request (like fetch)
+    try {
+        console.log("Fetching IP...");
+        const body = await gw.get('http://10.0.0.5/');
+        console.log(`🌍 External IP: ${body.trim()}`);
+    } catch (e) {
+        console.error("Request failed:", e.message);
+    }
+
+    // 4. Simple Server
+    console.log("Starting server on port 8080...");
+    await gw.listen(8080, (socket) => {
+        console.log("incoming connection!");
+        socket.end('HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\n\r\nHello from minimal WireShade!');
+    });
+
+    console.log("Server running. Waiting for connections...");
+
+    gw.on('error', console.error);
+}
+
+main();

package/examples/02_http_request.js

@@ -0,0 +1,44 @@
+const { WireShade } = require('../index');
+const path = require('path');
+
+/**
+ * Example: Simple HTTP Request
+ * Demonstrates the simplified get() API.
+ */
+
+async function exampleHttp() {
+    const log = (msg) => console.log(`[WireShade HTTP] ${msg}`);
+
+    const gw = new WireShade(path.join(__dirname, 'wireguard.conf'));
+
+    gw.on('connect', async () => {
+        const target = 'http://10.0.0.5/';
+        log(`VPN Connected. Fetching ${target}...`);
+
+        console.log("\n--- Method 1: Simplified API (gw.get) ---");
+        try {
+            console.time("Request");
+            const body = await gw.get(target);
+            console.timeEnd("Request");
+
+            log(`Response length: ${body.length} bytes`);
+        } catch (err) {
+            console.error("Method 1 failed:", err.message);
+        }
+
+        console.log("\n--- Method 2: Native-like API (gw.http.get) ---");
+        gw.http.get(target, (res) => {
+            log(`Status: ${res.statusCode}`);
+            res.on('data', d => process.stdout.write(`Chunk: ${d.length} bytes\n`));
+            res.on('end', () => {
+                log("Done.");
+                process.exit(0);
+            });
+        }).on('error', (err) => {
+            console.error("Method 2 failed:", err);
+            process.exit(1);
+        });
+    });
+}
+
+exampleHttp();

package/examples/03_https_custom_dns.js

@@ -0,0 +1,47 @@
+const { WireShade } = require('../index');
+const path = require('path');
+
+/**
+ * Example: HTTPS Request with Custom DNS
+ * Demonstrates simplified configuration for hosts.
+ */
+
+async function exampleHttps() {
+    const log = (msg) => console.log(`[WireShade HTTPS] ${msg}`);
+
+    // Config + Options (Hosts)
+    const gw = new WireShade(path.join(__dirname, 'wireguard.conf'), {
+        hosts: {
+            'internal.service.lan': '10.0.0.5'
+        }
+    });
+
+    gw.on('connect', async () => {
+        const target = 'https://internal.service.lan/';
+        log(`VPN Connected. Fetching ${target}...`);
+
+        // Method 1: Simplified API (gw.get)
+        // const body = await gw.get(target);
+
+        // Method 2: Native-like API (gw.https.get) using host mapping
+        log("Using gw.https.get() with Host Mapping...");
+
+        const req = gw.https.get(target, (res) => {
+            log(`Status: ${res.statusCode}`);
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                log(`Response received!`);
+                console.log(data.substring(0, 100));
+                process.exit(0);
+            });
+        });
+
+        req.on('error', (err) => {
+            console.error("HTTPS Request Failed:", err);
+            process.exit(1);
+        });
+    });
+}
+
+exampleHttps();

package/examples/04_tcp_socket.js

@@ -0,0 +1,50 @@
+const { WireShade } = require('../index');
+const path = require('path');
+
+/**
+ * Example: Raw TCP Socket
+ * Demonstrates low-level access to the TCP connection using the simplified API.
+ */
+
+async function exampleTcp() {
+    const log = (msg) => console.log(`[WireShade TCP] ${msg}`);
+
+    // Initialize with config file
+    const gw = new WireShade(path.join(__dirname, 'wireguard.conf'));
+
+    gw.on('connect', () => {
+        log("VPN Connected. Establishing TCP connection...");
+
+        const targetIp = '10.0.0.5';
+        const targetPort = 80;
+
+        const socket = gw.connect({
+            host: targetIp,
+            port: targetPort
+        });
+
+        socket.on('connect', () => {
+            log(`Socket connected to ${targetIp}:${targetPort}`);
+
+            const request = "GET / HTTP/1.1\r\nHost: 10.0.0.5\r\nConnection: close\r\n\r\n";
+            socket.write(request);
+            log("HTTP GET sent.");
+        });
+
+        socket.on('data', (data) => {
+            log(`Received ${data.length} bytes:`);
+            console.log(data.toString().split('\n')[0] + '...'); // Print first line
+        });
+
+        socket.on('close', () => {
+            log("Connection closed.");
+            process.exit(0);
+        });
+
+        socket.on('error', (err) => {
+            console.error("Socket error:", err.message);
+        });
+    });
+}
+
+exampleTcp();

package/examples/05_internet_routing.js

@@ -0,0 +1,33 @@
+const { WireShade } = require('../index');
+const path = require('path');
+
+/**
+ * Example: Internet Access
+ * Demonstrates routing traffic to the public internet through the WireGuard tunnel.
+ */
+
+async function exampleInternet() {
+    const log = (msg) => console.log(`[WireShade Internet] ${msg}`);
+
+    const gw = new WireShade(path.join(__dirname, 'wireguard.conf'));
+
+    gw.on('connect', async () => {
+        log("VPN Connected. Checking public IP...");
+
+        // Using gw.https.get for native-like control
+        gw.https.get('https://ifconfig.me/ip', (res) => {
+            let ip = '';
+            res.on('data', c => ip += c);
+            res.on('end', () => {
+                log(`\nResult IP: ${ip.trim()}`);
+                log("(This should match your WireGuard Exit-IP)");
+                process.exit(0);
+            });
+        }).on('error', (err) => {
+            console.error("Failed:", err.message);
+            process.exit(1);
+        });
+    });
+}
+
+exampleInternet();

package/examples/06_simple_server.js

@@ -0,0 +1,40 @@
+const { WireShade } = require('../index');
+const path = require('path');
+
+/**
+ * Server über WireGuard veröffentlichen (Reverse Tunnel)
+ */
+
+const VPN_PORT = 8080;
+
+async function main() {
+    console.log("=== WireShade Reverse Tunnel Demo ===");
+
+    const gw = new WireShade(path.join(__dirname, 'wireguard.conf'));
+
+    gw.on('connect', async () => {
+        console.log("Listen on http://10.0.0.2:8080/");
+
+        try {
+            await gw.listen(VPN_PORT, (socket) => {
+                console.log(`[Server] New connection!`);
+
+                socket.end([
+                    'HTTP/1.1 200 OK',
+                    'Content-Type: text/html',
+                    'Connection: close',
+                    '',
+                    '<h1>Hello from WireShade Server!</h1>'
+                ].join('\r\n'));
+            });
+
+            console.log(`✅ Server listening on VPN port ${VPN_PORT}`);
+        } catch (err) {
+            console.error("Server start failed:", err);
+        }
+    });
+
+    gw.on('error', console.error);
+}
+
+main();

package/examples/07_express_app.js

@@ -0,0 +1,37 @@
+const express = require('express');
+const { WireShade } = require('../index');
+const http = require('http');
+const path = require('path');
+
+/**
+ * Express über WireGuard veröffentlichen (Reverse Tunnel)
+ */
+
+async function main() {
+    console.log("=== WireShade + Express Demo ===");
+
+    // 1. Setup Express
+    const app = express();
+    app.get('/', (req, res) => res.send('<h1>🎉 Express via WireShade!</h1>'));
+    app.get('/api/status', (req, res) => res.json({ status: 'online', vpn: true }));
+
+    // Create standard HTTP server (but don't listen on TCP port)
+    const httpServer = http.createServer(app);
+
+    // 2. Setup GhostWire
+    const gw = new WireShade(path.join(__dirname, 'wireguard.conf'));
+
+    gw.on('connect', async () => {
+        console.log(`VPN Connected as ${gw.config.wireguard.sourceIp}`);
+
+        // 3. Bridge VPN connections to Express
+        await gw.listen(8080, (socket) => {
+            // Inject the VPN socket into the HTTP server
+            httpServer.emit('connection', socket);
+        });
+
+        console.log("✅ Express Server accessible at http://10.0.0.2:8080");
+    });
+}
+
+main();