ShadowNet 🌐

The educational, production-grade Peer-to-Peer Mesh VPN.

---

⚡ Introduction

ShadowNet is a decentralized, peer-to-peer (P2P) mesh VPN that creates a secure private network over the public internet. Unlike traditional hub-and-spoke VPNs, ShadowNet allows nodes to communicate directly with each other, minimizing latency and eliminating central bottlenecks.

It is designed as an educational reference implementation, demonstrating advanced concepts like UDP Hole Punching, STUN, userspace packet processing, and the Noise Protocol Framework.

🚀 Key Features

• Nesg P2P (True P2P): Traffic flows directly between peers (A ↔ B) without touching the control plane.
• NAT Traversal: Advanced UDP hole-punching technology connects peers behind residential routers, CGNAT, and strict firewalls.
• Userspace WireGuard: Portable, kernel-independent implementation using wireguard-go.
• Zero Trust Architecture: Identity is cryptographic (Public Key). IP addresses are just transport details.
• Split-Brain Architecture: Strict separation of the Control Plane (Signaling) and Data Plane (Media).
• Modern Dashboard: A real-time visualization of your mesh network.

---

📚 Documentation & Concepts

We have built a comprehensive, interactive documentation section directly into the dashboard to teach you how it works.

Visit the ShadowNet Documentation Hub covering:

• Introduction to P2P Mesh VPNs
• WireGuard Protocol Internals (Noise_IK)
• NAT Traversal & STUN
• TUN/TAP Device Integration

---

🛠️ Architecture

ShadowNet operates on a "Split-Brain" model:

graph TD
    subgraph Control Plane ["📡 Control Plane (Signal)"]
        API[REST API]
        DB[(Peer Store)]
        API --> DB
    end

    subgraph Data Plane ["🕸️ Data Plane (Media)"]
        NodeA[💻 Node A]
        NodeB[💻 Node B]
        NodeC[💻 Node C]
    end

    NodeA -- "1. Register (HTTP)" --> API
    NodeB -- "1. Register (HTTP)" --> API
    
    NodeA -- "2. P2P Tunnel (UDP)" <--> NodeB
    NodeB -- "2. P2P Tunnel (UDP)" <--> NodeC
    NodeA -- "2. P2P Tunnel (UDP)" <--> NodeC

    style Control Plane fill:#f9f,stroke:#333,stroke-width:2px
    style Data Plane fill:#bbf,stroke:#333,stroke-width:2px

Loading

• Control Plane: The "Phone Book". It helps peers find each other's current public IP:Port. It never sees or touches encrypted VPN traffic.
• Data Plane: The "Call". Peers establish direct UDP tunnels using WireGuard.

---

🏁 Quickstart

Prerequisites

• Linux (Kernel 5.4+)
• Go 1.21+
• Node.js 18+ (for dashboard)

1. 🐳 Docker Quickstart (Recommended)

The fastest way to spin up the entire stack (Control Plane + Dashboard + 3 Nodes):

# Start everything in detached mode
docker-compose up -d

# View the Dashboard
xdg-open http://localhost:3000

This spins up:

• Control Plane on port 8080
• Dashboard on port 3000
• 3 Demo Nodes that automatically interconnect

2. Manual Quickstart (Development)

Prerequisites

• Linux (Kernel 5.4+)
• Go 1.21+
• Node.js 18+

Run the Dashboard

cd web
npm install
npm run dev

Open http://localhost:3000

Run the Control Plane

go run cmd/controlplane/main.go
# Server listens on :8080 by default

Run a Node (Client)

Use sudo (required for TUN device creation) and specify the control plane URL.

# Join the mesh
sudo go run cmd/node/main.go \
  -id=my-node-1 \
  -controlplane-url=http://localhost:8080

(Note: sudo is required because the node creates a userspace tun0 interface network device)

---

🧩 Technology Stack

Component	Technology	Role
Core Networking	wireguard-go	Userspace implementation of the WireGuard protocol
NAT Traversal	pion/stun	STUN client for public endpoint discovery
Interface	water (TUN/TAP)	OS-level virtual network interface creation
Control Plane	Go + SQLite	Signaling server and peer state management
Dashboard	Next.js + Tailwind	Real-time visualization and management UI

---

👥 Contributing

ShadowNet is an open-source project designed for learning. We welcome contributions!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

(WireGuard is a registered trademark of Jason A. Donenfeld.)