wireshade 1.0.0

package/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "wireshade"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+napi = { version = "2.12", features = ["tokio_rt", "async"] }
+napi-derive = "2.12"
+# Core networking
+tokio = { version = "1", features = ["full"] }
+# The userspace TCP/IP stack
+smoltcp = { version = "0.12", features = ["std", "medium-ip", "proto-ipv4", "socket-tcp", "async"] }
+# WireGuard implementation (Cloudflare)
+boringtun = "0.6"
+# Utilities
+bytes = "1"
+thiserror = "1"
+hex = "0.4"
+base64 = "0.21"
+log = "0.4"
+env_logger = "0.10"
+
+[build-dependencies]
+napi-build = "2.0"

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WireShade Authors
+
+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.de.md

@@ -0,0 +1,256 @@
+# 👻 WireShade - Node.js WireGuard Client
+
+**Die ultimative Userspace WireGuard® Implementierung für 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** ermöglicht es deiner Node.js-Anwendung, sich direkt mit einem WireGuard-VPN zu verbinden – **ohne Root-Rechte**, Kernel-Module oder Änderungen an den Systemeinstellungen. Es läuft vollständig im Userspace unter Verwendung eines benutzerdefinierten Rust-basierten TCP/IP-Stacks (`smoltcp`), der direkt in Node.js integriert ist.
+
+<div align="center">
+
+[🇺🇸 English](README.md) | [🇩🇪 Deutsch](README.de.md) | [🇪🇸 Español](README.es.md) | [🇫🇷 Français](README.fr.md) | [🇨🇳 中文](README.zh.md)
+
+</div>
+
+---
+
+## 🚀 Warum WireShade?
+
+WireShade löst komplexe Netzwerk-Herausforderungen mit einer sauberen, nativen Lösung:
+
+*   **🛡️ Sicherheit & Stealth:** Route spezifischen Node.js-Traffic durch ein sicheres WireGuard-VPN, während der Rest deines Systems das normale Internet nutzt. Perfekt für **Web-Scraping**, **Bots** oder **sichere Kommunikation**.
+*   **🌍 Reverse Tunneling:** Mache einen lokalen Express-Server, WebSocket-Server oder Next.js App im privaten VPN-Netzwerk verfügbar, selbst hinter NAT oder Firewalls.
+*   **🔌 Zero-Config Client:** Keine Installation von WireGuard auf dem Host-System notwendig. Einfach `npm install` und loslegen.
+*   **🔄 Automatischer Reconnect:** Eingebaute Logik, um Verbindungsabbrüche und Netzwerkwechsel nahtlos zu handhaben.
+*   **⚡ Hohe Performance:** Angetrieben durch Rust und NAPI-RS für nahezu native Geschwindigkeit.
+
+## 🧠 Wie es funktioniert (Technical Deep Dive)
+
+WireShade umgeht den Netzwerkstack des Host-Betriebssystems, indem es einen **Userspace TCP/IP-Stack** ([smoltcp](https://github.com/smoltcp-rs/smoltcp)) direkt in deinem Node.js-Prozess ausführt.
+
+1.  **Handshake:** WireShade baut einen WireGuard-Handshake über UDP auf.
+2.  **Kapselung:** IP-Pakete werden verschlüsselt und in UDP-Pakete verpackt.
+3.  **Userspace Routing:** Entschlüsselte Pakete werden von `smoltcp` in Rust verarbeitet (TCP-State, Retransmission, Buffering).
+4.  **Node.js Integration:** Daten fließen über hochperformante NAPI-Bindings zwischen Rust-Streams und Node.js `net.Socket`/`http.Agent`-Instanzen.
+
+Diese Architektur bedeutet:
+- **Kein virtuelles Netzwerkinterface (TUN/TAP)** wird auf deinem OS erstellt.
+- **Root-Rechte sind NICHT erforderlich.**
+- **Kein Konflikt** mit bestehenden VPNs oder Systemnetzwerken.
+- **Plattformunabhängige** Kompatibilität (Windows, macOS, Linux, **Raspberry Pi**, Docker Container) ohne Kernel-Module.
+
+## 📦 Installation
+
+```bash
+npm install wireshade
+```
+
+---
+
+## 🛠️ Anwendungsbeispiele
+
+Alle Beispiele gehen davon aus, dass der Client initialisiert ist:
+```javascript
+const { WireShade, readConfig } = require('wireshade');
+const client = new WireShade(readConfig('./wg0.conf'));
+await client.start();
+```
+
+### 1. HTTP/HTTPS Requests (Client)
+Nutze WireShade als transparenten Agent für deine Requests.
+
+**Vereinfachte API:**
+```javascript
+const html = await client.get('https://internal.service/api');
+console.log(html);
+```
+
+**Natives `http`/`https` Modul:**
+```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');
+
+// Nutze die Agents in der Axios-Config
+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 ins VPN (Client)
+Verbinde dich zu reinen TCP-Diensten oder WebSockets, die im VPN laufen.
+
+**Raw TCP:**
+```javascript
+const socket = client.connect({ host: '10.0.0.5', port: 22 });
+socket.write('SSH-2.0-MyClient\r\n');
+```
+
+**WebSockets (mit `ws` Library):**
+```javascript
+const WebSocket = require('ws');
+
+// Nutze den WireShade Agent für den Handshake
+const ws = new WebSocket('ws://10.0.0.5:8080/stream', {
+    agent: client.getHttpAgent() 
+});
+
+ws.on('open', () => console.log('Verbunden mit VPN WebSocket!'));
+```
+
+### 3. Server veröffentlichen (Express, Next.js, WebSockets)
+Mache deinen lokalen Server **nur** über das VPN erreichbar (Reverse Tunneling).
+
+**Express / Next.js / Fastify:**
+```javascript
+const express = require('express');
+const http = require('http');
+const { WireShadeServer } = require('wireshade');
+
+// 1. Setup der App
+const app = express();
+app.get('/', (req, res) => res.send('🎉 Versteckt im VPN!'));
+
+// 2. HTTP Server vorbereiten (noch nicht listen())
+const httpServer = http.createServer(app);
+
+// 3. Auf dem VPN lauschen
+const vpnServer = new WireShadeServer(client);
+vpnServer.on('connection', (socket) => {
+    httpServer.emit('connection', socket); // Leite VPN-Socket an HTTP-Server
+});
+
+await vpnServer.listen(80); // Lausche auf Port 80 der VPN-IP
+console.log('Server online unter 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 unterstützt sowohl **Local Forwarding** (Zugriff auf VPN-Dienst lokal) als auch **Remote Forwarding** (Lokalen Dienst ins VPN stellen).
+
+**Local Forwarding (VPN -> Localhost):**
+Greife auf eine PostgreSQL-Datenbank (`10.0.0.5:5432`) im VPN über `localhost:3333` zu.
+```javascript
+await client.forwardLocal(3333, '10.0.0.5', 5432);
+console.log('Verbinde deinen DB-Client mit localhost:3333');
+```
+
+**Remote Forwarding (Localhost -> VPN):**
+Stelle deinen lokalen Entwicklungsserver (`localhost:3000`) im VPN auf Port `8080` bereit.
+```javascript
+// Lausche auf VPN Port 8080 -> Leite weiter an localhost:3000
+await client.forwardRemote(8080, 'localhost', 3000);
+console.log('VPN-Nutzer können deinen Server unter http://<VPN-IP>:8080 erreichen');
+```
+
+---
+
+## ⚙️ Konfiguration & Features
+
+### Auto-Reconnection (Verbindungswiederherstellung)
+WireShade enthält robuste Logik für Reconnects.
+
+```javascript
+const client = new WireShadeClient({
+    wireguard: { ... },
+    reconnect: {
+        enabled: true,
+        maxAttempts: 10,
+        delay: 1000,
+        backoffMultiplier: 1.5
+    }
+});
+
+client.on('reconnecting', (attempt) => console.log(`🔄 Verbinde neu... (${attempt})`));
+```
+
+### Custom DNS / Hosts
+Mappe interne VPN-Hostnamen auf IP-Adressen, ohne `/etc/hosts` anzufassen.
+
+```javascript
+const client = new WireShadeClient({
+    wireguard: { ... },
+    hosts: {
+        'intern-api.local': '10.0.0.4',
+        'db-prod': '10.0.0.5'
+    }
+});
+```
+
+## 📚 API Referenz
+
+**`new WireShadeClient(config)`**
+- Erstellt eine neue VPN-Instanz. `config` entspricht den Standard-WireGuard-Parametern (`privateKey`, `endpoint`, etc.).
+
+**`client.start()`**
+- Verbindet mit dem VPN. Gibt ein `Promise` zurück, das bei Verbindung aufgelöst wird.
+
+**`client.get(url, [options])`**
+- Helper für einfache HTTP GET Requests durch den Tunnel. Gibt den Body zurück.
+
+**`client.connect(options)`**
+- Erstellt einen rohen TCP-Socket (`net.Socket`), der durch den Tunnel verbunden ist.
+
+**`client.listen(port, [callback])`**
+- Startet einen TCP-Server, der auf der **VPN-IP** am angegebenen Port lauscht.
+
+**`client.forwardLocal(localPort, remoteHost, remotePort)`**
+- Leitet einen lokalen Port an ein Ziel im VPN weiter.
+
+**`client.forwardRemote(vpnPort, targetHost, targetPort)`**
+- Leitet einen Port der VPN-IP an ein lokales Ziel weiter (Reverse Port Forwarding).
+
+**`client.getHttpAgent() / client.getHttpsAgent()`**
+- Gibt einen Node.js `http.Agent` / `https.Agent` zurück, der so konfiguriert ist, dass er Traffic durch den Tunnel leitet.
+
+---
+
+---
+
+## 🎯 Use Cases (Einsatzgebiete)
+
+*   **Microservices Kommunikation:** Verbinde sichere Dienste über verschiedene Clouds hinweg, ohne öffentliche Ports zu öffnen.
+*   **Web Scraping:** Rotiere IP-Adressen durch Erstellung mehrerer WireShade-Instanzen mit verschiedenen VPN-Endpunkten.
+*   **Entwickler-Zugang:** Gib Entwicklern sicheren Zugriff auf interne Datenbanken direkt von ihrem lokalen Rechner.
+*   **IoT & Edge:** Verbinde Geräte hinter restriktiven Firewalls sicher mit einem zentralen Server (Reverse Tunneling).
+
+---
+
+## 📜 Lizenz
+
+MIT Lizenz.
+
+*WireGuard ist eine eingetragene Marke von Jason A. Donenfeld.*

package/README.es.md

@@ -0,0 +1,109 @@
+# 👻 WireShade usando Node.js
+
+**La implementación definitiva de WireGuard® en espacio de usuario para 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** permite que tu aplicación Node.js se conecte directamente a una VPN WireGuard **sin privilegios de root**, módulos del kernel ni modificaciones en la configuración de red del sistema. Se ejecuta completamente en espacio de usuario utilizando una pila TCP/IP basada en Rust (`smoltcp`) integrada directamente en 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>
+
+---
+
+## 🚀 ¿Por qué WireShade?
+
+WireShade resuelve desafíos complejos de implementación de redes con una solución limpia y nativa en espacio de usuario:
+
+*   **🛡️ Sigilo y Seguridad:** Enruta tráfico específico de Node.js a través de una VPN WireGuard segura mientras mantienes el resto del tráfico de tu sistema normal. Perfecto para **web scraping**, **bots** o **comunicación segura**.
+*   **🌍 Túnel Inverso:** Expone un servidor Express local, un servidor WebSocket o una aplicación Next.js a la red VPN privada, incluso si estás detrás de un NAT o firewall.
+*   **🔌 Cliente Cero Configuración:** No es necesario instalar WireGuard en la máquina host. Simplemente `npm install` y listo.
+*   **🔄 Reconexión Automática:** Lógica integrada para manejar caídas de conexión y cambios de red sin problemas.
+*   **⚡ Alto Rendimiento:** Impulsado por Rust y NAPI-RS para un rendimiento casi nativo.
+
+## 📦 Instalación
+
+```bash
+npm install wireshade
+```
+
+---
+
+## 🛠️ Ejemplos de Uso
+
+Todos los ejemplos asumen que has inicializado el cliente:
+```javascript
+const { WireShade, readConfig } = require('wireshade');
+const client = new WireShade(readConfig('./wg0.conf'));
+await client.start();
+```
+
+### 1. Solicitudes HTTP/HTTPS (Cliente)
+Usa WireShade como un agente transparente para tus solicitudes.
+
+**Módulo nativo `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 y WebSockets a VPN (Cliente)
+Conéctate a servicios TCP sin procesar o WebSockets que se ejecutan dentro de la VPN.
+
+**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('¡Conectado al WebSocket VPN!'));
+```
+
+### 3. Exponer Servidores Locales (Túnel Inverso)
+Haz que tu servidor local sea accesible **solo** a través de la 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('🎉 ¡Oculto dentro de la VPN!'));
+
+const httpServer = http.createServer(app);
+const vpnServer = new WireShadeServer(client);
+
+// Alimentar el socket VPN al servidor HTTP
+vpnServer.on('connection', (socket) => httpServer.emit('connection', socket));
+
+await vpnServer.listen(80);
+console.log('Servidor en línea en http://<VPN-IP>/');
+```
+
+---
+
+## 📜 Licencia
+
+Licencia MIT.
+
+*WireGuard es una marca registrada de Jason A. Donenfeld.*

package/README.fr.md

@@ -0,0 +1,109 @@
+# 👻 WireShade avec Node.js
+
+**L'implémentation ultime de WireGuard® en espace utilisateur pour 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** permet à votre application Node.js de se connecter directement à un VPN WireGuard **sans privilèges root**, sans modules noyau, et sans modifier les paramètres réseau du système. Il s'exécute entièrement dans l'espace utilisateur en utilisant une pile TCP/IP personnalisée basée sur Rust (`smoltcp`) intégrée directement dans 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>
+
+---
+
+## 🚀 Pourquoi WireShade ?
+
+WireShade résout les défis complexes d'implémentation réseau avec une solution propre et native :
+
+*   **🛡️ Discrétion & Sécurité :** Acheminez le trafic spécifique de Node.js via un VPN WireGuard sécurisé tout en gardant le reste du trafic de votre système normal. Parfait pour le **web scraping**, les **bots**, ou la **communication sécurisée**.
+*   **🌍 Tunnel Inverse (Reverse Tunneling) :** Exposez un serveur Express local, un serveur WebSocket ou une application Next.js au réseau VPN privé, même si vous êtes derrière un NAT ou un pare-feu.
+*   **🔌 Client Zéro Configuration :** Pas besoin d'installer WireGuard sur la machine hôte. Juste `npm install` et c'est parti.
+*   **🔄 Reconnexion Automatique :** Logique intégrée pour gérer les pertes de connexion et les changements de réseau de manière transparente.
+*   **⚡ Haute Performance :** Propulsé par Rust et NAPI-RS pour des performances quasi-natives.
+
+## 📦 Installation
+
+```bash
+npm install wireshade
+```
+
+---
+
+## 🛠️ Exemples d'Utilisation
+
+Tous les exemples supposent que vous avez initialisé le client :
+```javascript
+const { WireShade, readConfig } = require('wireshade');
+const client = new WireShade(readConfig('./wg0.conf'));
+await client.start();
+```
+
+### 1. Requêtes HTTP/HTTPS (Client)
+Utilisez WireShade comme un agent transparent pour vos requêtes.
+
+**Module natif `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 vers VPN (Client)
+Connectez-vous à des services TCP bruts ou WebSockets s'exécutant à l'intérieur du VPN.
+
+**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('Connecté au WebSocket VPN !'));
+```
+
+### 3. Exposer des Serveurs Locaux (Tunnel Inverse)
+Rendez votre serveur local accessible **uniquement** via le 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('🎉 Caché dans le VPN !'));
+
+const httpServer = http.createServer(app);
+const vpnServer = new WireShadeServer(client);
+
+// Transmettre le socket VPN au serveur HTTP
+vpnServer.on('connection', (socket) => httpServer.emit('connection', socket));
+
+await vpnServer.listen(80);
+console.log('Serveur en ligne sur http://<VPN-IP>/');
+```
+
+---
+
+## 📜 Licence
+
+Licence MIT.
+
+*WireGuard est une marque déposée de Jason A. Donenfeld.*