wireshade 1.0.0

package/examples/08_local_forwarding.js

@@ -0,0 +1,30 @@
+const { WireShade } = require('../index');
+const path = require('path');
+
+/**
+ * Example: TCP Port Forwarding
+ * Forwards localhost:8080 -> 10.0.0.5:80 via VPN
+ */
+
+async function examplePortForward() {
+    const gw = new WireShade(path.join(__dirname, 'wireguard.conf'));
+
+    gw.on('connect', async () => {
+        console.log("VPN Connected.");
+
+        try {
+            const server = await gw.forwardLocal(8080, '10.0.0.5', 80);
+
+            console.log(`Forwarding localhost:8080 -> 10.0.0.5:80`);
+            console.log("Press Ctrl+C to stop.");
+
+            // server is a net.Server
+            server.on('error', (e) => console.error("Server error:", e.message));
+
+        } catch (err) {
+            console.error("Failed to start forwarding:", err.message);
+        }
+    });
+}
+
+examplePortForward();

package/examples/09_reconnect_config.js

@@ -0,0 +1,128 @@
+/**
+ * WireShadeClient Reconnection Demo
+ * 
+ * Zeigt die automatische Reconnection-Logik mit Events und Konfiguration.
+ */
+
+const { WireShade, ConnectionState } = require('../index');
+const https = require('https');
+
+const { readWireGuardConfig } = require('../lib/config_parser');
+const path = require('path');
+
+const wireguardConfig = readWireGuardConfig(path.join(__dirname, 'wireguard.conf'));
+
+const config = {
+    wireguard: wireguardConfig,
+
+    logging: true,
+
+    // Reconnection configuration
+    reconnect: {
+        enabled: true,           // Auto-reconnect on disconnect
+        maxAttempts: 5,          // Max attempts (0 = infinite)
+        delay: 1000,             // Initial delay: 1 second
+        maxDelay: 30000,         // Max delay: 30 seconds
+        backoffMultiplier: 2,    // Double delay each attempt
+        healthCheckInterval: 60000 // Check every 60 seconds
+    },
+
+    hosts: {
+        'internal.service.lan': '10.0.0.5'
+    }
+};
+
+async function main() {
+    console.log('=== WireShadeClient Reconnection Demo ===\n');
+
+    const client = new WireShade(config);
+
+    // Event: State changes
+    client.on('stateChange', (state) => {
+        const stateEmoji = {
+            [ConnectionState.DISCONNECTED]: '🔴',
+            [ConnectionState.CONNECTING]: '🟡',
+            [ConnectionState.CONNECTED]: '🟢',
+            [ConnectionState.RECONNECTING]: '🟠'
+        };
+        console.log(`[State] ${stateEmoji[state] || '⚪'} ${state}`);
+    });
+
+    // Event: Connected
+    client.on('connect', () => {
+        console.log('[Event] ✅ Verbunden!');
+    });
+
+    // Event: Disconnected
+    client.on('disconnect', (err) => {
+        console.log('[Event] ❌ Verbindung getrennt:', err?.message || 'Unknown');
+    });
+
+    // Event: Reconnecting
+    client.on('reconnecting', (attempt) => {
+        console.log(`[Event] 🔄 Reconnect Versuch ${attempt}...`);
+    });
+
+    // Event: Reconnected
+    client.on('reconnect', () => {
+        console.log('[Event] ✅ Wiederverbunden!');
+    });
+
+    // Event: Reconnect failed
+    client.on('reconnectFailed', () => {
+        console.log('[Event] ❌ Reconnection fehlgeschlagen nach max Versuchen');
+    });
+
+    // Event: Health check
+    client.on('healthCheck', () => {
+        console.log('[Health] 💓 Health check...');
+    });
+
+    // Wait for initial connection
+    await new Promise(resolve => setTimeout(resolve, 4000));
+
+    // Test: Make a request
+    console.log('\n--- Test Request ---');
+    try {
+        const response = await makeRequest(client, 'https://ifconfig.me/ip');
+        console.log('Externe IP:', response.trim());
+    } catch (err) {
+        console.log('Request fehlgeschlagen:', err.message);
+    }
+
+    // Demo: Manual reconnect
+    console.log('\n--- Manual Reconnect Test ---');
+    console.log('Drücke Ctrl+C um zu beenden.\n');
+
+    // Keep running
+    setInterval(async () => {
+        if (client.connected) {
+            console.log(`[${new Date().toLocaleTimeString()}] Status: Verbunden`);
+        } else {
+            console.log(`[${new Date().toLocaleTimeString()}] Status: ${client.state}`);
+        }
+    }, 10000);
+
+    // Graceful shutdown
+    process.on('SIGINT', () => {
+        console.log('\n\nShutting down...');
+        client.close();
+        process.exit(0);
+    });
+}
+
+function makeRequest(client, url) {
+    return new Promise((resolve, reject) => {
+        const req = https.get(url, { agent: client.getHttpsAgent() }, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => resolve(data));
+        });
+        req.on('error', reject);
+        req.setTimeout(10000, () => {
+            req.destroy(new Error('Timeout'));
+        });
+    });
+}
+
+main().catch(console.error);

package/examples/10_remote_forwarding.js

@@ -0,0 +1,63 @@
+const { WireShade } = require('../index');
+const path = require('path');
+const http = require('http');
+
+/**
+ * Example: Remote Forwarding (Reverse Port Forwarding)
+ * 
+ * Scenario: 
+ * You have a service running on your local LAN (e.g., a local printer web interface, 
+ * or a development server on another machine) at '192.168.1.50:80'.
+ * 
+ * You want to make this service accessible to everyone in the VPN at '10.0.0.2:8080'.
+ * 
+ * Flow: [VPN User] -> [WireShade VPN IP:8080] -> [WireShade] -> [Local LAN IP:80]
+ */
+
+async function main() {
+    console.log("=== WireShade Remote Forwarding Demo ===");
+
+    // 1. Initialize
+    const gw = new WireShade(path.join(__dirname, 'wireguard.conf'));
+
+    gw.on('connect', async () => {
+        console.log(`VPN Connected as ${gw.config.wireguard.sourceIp}`);
+
+        // Mock a "local service" for demonstration purposes
+        // In reality, this would be an existing service on your machine or network.
+        startMockLocalService(3000);
+
+        try {
+            // 2. Start Forwarding
+            // Listen on VPN Port 8080 -> Forward to localhost:3000
+            const vpnPort = 8080;
+            const localTargetHost = 'localhost';
+            const localTargetPort = 3000;
+
+            await gw.forwardRemote(vpnPort, localTargetHost, localTargetPort);
+
+            console.log(`\n✅ Forwarding Active!`);
+            console.log(`Traffic to VPN ${gw.config.wireguard.sourceIp}:${vpnPort} is now forwarded to ${localTargetHost}:${localTargetPort}`);
+
+        } catch (err) {
+            console.error("Forwarding failed:", err);
+        }
+    });
+
+    gw.on('error', console.error);
+    await gw.start();
+}
+
+function startMockLocalService(port) {
+    const server = http.createServer((req, res) => {
+        console.log(`[Local Service] Received request: ${req.method} ${req.url}`);
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end(`Hello from the Local Service! You reached me via VPN.`);
+    });
+    server.listen(port, () => {
+        console.log(`[Local Service] Running on port ${port}`);
+    });
+    return server;
+}
+
+main();

package/examples/README.md

@@ -0,0 +1,54 @@
+# WireShade Examples
+
+This directory contains example scripts demonstrating various capabilities of the WireShade library.
+
+## Getting Started
+
+1.  Ensure you have a valid `wireguard.conf` in this directory (or update the scripts to point to one).
+2.  Run the examples using `node examples/<filename>`.
+
+## Available Examples
+
+### 1. Quickstart (`01_quickstart.js`)
+The "Hello World" of WireShade. Shows how to initialize the connection, perform a simple request, and start a listener.
+- **Run:** `node examples/01_quickstart.js`
+
+### 2. HTTP Request (`02_http_request.js`)
+Performs a simple HTTP GET request to an internal web server using the simplified `gw.get()` API.
+- **Run:** `node examples/02_http_request.js`
+
+### 3. HTTPS & Custom DNS (`03_https_custom_dns.js`)
+Demonstrates how to access an HTTPS server with a custom hostname (`internal.service.lan`) mapped to an internal IP.
+- **Run:** `node examples/03_https_custom_dns.js`
+
+### 4. Raw TCP Socket (`04_tcp_socket.js`)
+Shows low-level usage to send raw data bytes (HTTP request manually constructed) and receive raw bytes, bypassing higher-level helpers.
+- **Run:** `node examples/04_tcp_socket.js`
+
+### 5. Internet Routing (`05_internet_routing.js`)
+Tests routing to the public internet by fetching your IP from `ifconfig.me`. Confirms that traffic exits via the WireGuard VPN gateway.
+- **Run:** `node examples/05_internet_routing.js`
+
+### 6. Simple Server (`06_simple_server.js`)
+Host a basic HTTP server inside the VPN tunnel. 
+- **Run:** `node examples/06_simple_server.js`
+
+### 7. Express App (`07_express_app.js`)
+Run a full Express.js application and make it accessible via the VPN tunnel (Reverse Tunneling).
+- **Run:** `node examples/07_express_app.js`
+
+### 8. Local Forwarding (`08_local_forwarding.js`)
+Starts a local TCP server on port `8080` that forwards all traffic to an internal host (`10.0.0.5:80`).
+- **Run:** `node examples/08_local_forwarding.js`
+
+### 9. Advanced Reconnect (`09_reconnect_config.js`)
+Demonstrates reconnection logic, health checks, and event monitoring.
+- **Run:** `node examples/09_reconnect_config.js`
+
+### 10. Remote Forwarding (`10_remote_forwarding.js`)
+Exposes a service running on your local machine (or local network) to the VPN. Traffic sent to a specific VPN port is forwarded to the local target.
+- **Run:** `node examples/10_remote_forwarding.js`
+
+
+## Configuration
+All examples read from `wireguard.conf` in this directory. Ensure this file contains your valid Client configuration.

package/examples/_legacy_easy_api.js

@@ -0,0 +1,53 @@
+const { WireShadeClient } = require('../index');
+const https = require('https');
+
+async function testEasyApi() {
+    console.log("--- WireShade Easy API Test (Quiet Mode) ---");
+
+    const client = new WireShadeClient({
+        wireguard: {
+            privateKey: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+            peerPublicKey: "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=",
+            presharedKey: "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=",
+            endpoint: "203.0.113.1:51820",
+            sourceIp: "10.0.0.2"
+        },
+        logging: false, // DISABLES INTERNAL LOGS
+        onConnect: () => {
+            console.log("\n>>> EVENT: WireGuard Connection Ready! <<<");
+        },
+        onDisconnect: () => {
+            console.log(">>> EVENT: WireGuard Connection Closed! <<<");
+        },
+        hosts: {
+            'internal.service.lan': '10.0.0.5'
+        }
+    });
+
+    // Wait a bit to ensure onConnect fired (just for demo flow)
+    await new Promise(r => setTimeout(r, 200));
+
+    const target = 'https://internal.service.lan';
+    console.log(`\n[HTTPS] Fetching ${target}...`);
+
+    https.get(target, { agent: client.getHttpsAgent() }, (res) => {
+        console.log(`[Response] Status: ${res.statusCode}`);
+        // res.on('data', d => process.stdout.write(d)); // Suppress body for cleaner output
+        console.log(`[Response] Headers received.`);
+
+        // Start Port Forwarding after request
+        startForwarding(client);
+    }).on('error', console.error);
+
+    async function startForwarding(client) {
+        try {
+            await client.forwardLocal(9090, '10.0.0.5', 80);
+            console.log("\n[Forward] Listening on localhost:9090 -> 10.0.0.5:80");
+            console.log("[Forward] Speed test: Open http://localhost:9090 (Should be fast now!)");
+        } catch (e) {
+            console.error(e);
+        }
+    }
+}
+
+testEasyApi();

package/examples/wireguard.conf

@@ -0,0 +1,8 @@
+[Interface]
+PrivateKey = AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
+Address = 10.0.0.2/32
+
+[Peer]
+PublicKey = BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=
+PresharedKey = CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=
+Endpoint = 203.0.113.1:51820

package/index.js

@@ -0,0 +1,29 @@
+const fs = require('fs');
+const path = require('path');
+
+let binding;
+try {
+    binding = require('./wireshade.node');
+} catch (e) {
+    try {
+        binding = require('./wireshade.win32-x64-msvc.node');
+    } catch (e2) {
+        throw new Error('Could not load native binding');
+    }
+}
+
+const { WireShadeAgent } = require('./lib/agent');
+const { WireShadeClient, ConnectionState } = require('./lib/client');
+const { WireShadeServer } = require('./lib/server');
+const { parseWireGuardConfig, readWireGuardConfig } = require('./lib/config_parser');
+
+module.exports = {
+    WireShade: WireShadeClient, // The high-level client is the main export
+    NativeWireShade: binding.WireShade,
+    WireShadeClient,
+    WireShadeAgent,
+    WireShadeServer,
+    ConnectionState,
+    parseConfig: parseWireGuardConfig,
+    readConfig: readWireGuardConfig
+};

package/lib/agent.js

@@ -0,0 +1,116 @@
+const http = require('http');
+const { Duplex } = require('stream');
+const dns = require('dns');
+
+class WireShadeAgent extends http.Agent {
+  constructor(wireShade, options) {
+    super(options);
+    this.gw = wireShade;
+    this.options = options || {};
+
+    // Configure Logger
+    // Priority: options.logger -> console.log (unless logging===false)
+    this.log = this.options.logger || (this.options.logging === false ? () => { } : console.log);
+    this.error = this.options.logger || console.error;
+  }
+  createConnection(options, cb) {
+    const { host, port } = options;
+    const log = this.log;
+    const error = this.error;
+
+    log(`[Agent] Connecting to ${host}:${port}`);
+
+    const stream = new Duplex({
+      allowHalfOpen: true,
+      read(size) { },
+      write(chunk, encoding, callback) {
+        log(`[AgentStream] write called with ${chunk.length} bytes`);
+        if (this.connection) {
+          log(`[AgentStream] Sending immediately...`);
+          this.connection.send(chunk).then(() => {
+            log(`[AgentStream] Send completed for ${chunk.length} bytes`);
+            callback();
+          }).catch((err) => {
+            error(`[AgentStream] Send error:`, err);
+            callback(err);
+          });
+        } else {
+          log(`[AgentStream] Buffering - connection not ready yet`);
+          if (!this.pendingBuffer) this.pendingBuffer = [];
+          this.pendingBuffer.push({ chunk, callback });
+        }
+      }
+    });
+
+    // Mock Socket methods required by http.Agent/ClientRequest
+    stream.setTimeout = (msecs, callback) => {
+      if (callback) stream.once('timeout', callback);
+      return stream;
+    };
+    stream.setNoDelay = (enable) => stream;
+    stream.setKeepAlive = (enable, initialDelay) => stream;
+    stream.ref = () => stream;
+    stream.unref = () => stream;
+
+    // Use custom lookup if provided in options (Standard node http.Agent behavior), else default dns.lookup
+    const lookup = options.lookup || dns.lookup;
+
+    lookup(host, { family: 4 }, (err, address, family) => {
+      if (err) {
+        return cb(err);
+      }
+      log(`[Agent] Resolved ${host} to ${address}`);
+
+      this.gw.connect(address, parseInt(port),
+        (err, data) => {
+          const buffer = data || (Buffer.isBuffer(err) ? err : null);
+          if (buffer) {
+            log(`[Agent] Received ${buffer.length} bytes via connection`);
+            stream.push(buffer);
+          } else if (err && !data) {
+            error('[Agent] Receive error:', err);
+            stream.destroy(err);
+          }
+        },
+        () => {
+          stream.push(null);
+        }
+      ).then(conn => {
+        log(`[Agent] Connected! Setting stream.connection...`);
+        stream.connection = conn;
+        stream.emit('connect');
+
+        log(`[Agent] Checking pendingBuffer: ${stream.pendingBuffer ? stream.pendingBuffer.length + ' items' : 'none'}`);
+        if (stream.pendingBuffer && stream.pendingBuffer.length > 0) {
+          log(`[AgentStream] Flushing ${stream.pendingBuffer.length} buffered chunks`);
+          const flushPromises = stream.pendingBuffer.map(({ chunk, callback }) => {
+            log(`[AgentStream] Flushing chunk of ${chunk.length} bytes...`);
+            return conn.send(chunk).then(() => {
+              log(`[AgentStream] Flush completed for ${chunk.length} bytes`);
+              callback();
+            }).catch(err => {
+              error(`[AgentStream] Flush error:`, err);
+              callback(err);
+            });
+          });
+          stream.pendingBuffer = null;
+          Promise.all(flushPromises).then(() => {
+            log(`[Agent] All buffered data flushed, calling cb`);
+            if (cb) cb(null, stream);
+          });
+        } else {
+          log(`[Agent] No buffered data, calling cb immediately`);
+          if (cb) cb(null, stream);
+        }
+      }).catch(err => {
+        error('[Agent] Connection failed:', err.message, err.code, err);
+        if (cb) cb(err);
+        else stream.emit('error', err);
+      });
+    });
+
+    return stream;
+  }
+}
+
+module.exports = { WireShadeAgent };