p2ns/README.md

P2P Decentralized DNS System with Holesail Integration (Currently MacOS Only)

This project implements a firewall-resistant, peer-to-peer (P2P) DNS system that leverages UDP hole-punching to bypass common network restrictions, including firewalls, NAT, and CGNAT. Built in Node.js, it integrates with Holesail for tunneling, provides seamless DNS and HTTP proxying, and supports both public and private P2P networks.

[DEBUG 2024-10-14T21:04:20.875Z] Public DNS returned records for www.google.com
[DEBUG 2024-10-14T21:04:28.465Z] DNS query received: Domain = example.tld, Type = A
Virtual interface dummy2 created with CIDR 192.168.100.2.
[DEBUG 2024-10-14T21:04:28.527Z] Assigned virtual interface IP: 192.168.100.2 for domain: example.tld
[DEBUG 2024-10-14T21:04:28.528Z] Starting Holesail client for domain: example.tld, hash: 8a5b90945f8fbd5d1b620be3c888a47aaae20706a7f140be4bfa0df9e0dbcf38, IP: 192.168.100.2, Port: 80

Features

• Global Decentralized DNS: Independent of traditional DNS infrastructure; no reliance on central DNS servers.
• Firewall & NAT Bypass: Achieved using UDP hole-punching, allowing access across restricted networks like 4G, 5G, and satellite (e.g., Starlink).
• Local IP Assignment: Dynamically assigns local IP addresses (192.168.100.x) for each domain, isolated to virtual network interfaces.
• Hybrid DNS Mode: Resolves both P2P and public DNS records seamlessly.
• Integrated HTTP Proxy: Proxies HTTP traffic directly to P2P tunnels, eliminating the need for third-party proxy servers.
• Domain-Driven Hash Proxying: Routes connections via domain-based unique hashes, no need for traditional IP address exposure.
• Customizable P2P Network: Initialize with a custom discovery key to create a private, isolated DNS network.

Getting Started

Prerequisites

• Node.js: Version 18+ recommended
• Holesail: For tunneling and establishing P2P connections (Holesail CLI setup)
• Environment Variables: Use .env to store your custom keys securely.

Installation

1. Clone the Repository

   git clone https://git.ssh.surf/snxraven/p2ns.git
   cd p2ns
   

2. Install Dependencies

   npm install
   

3. Set Up Environment Variables

   Create a .env file in the root directory to set a custom discovery key, masterNetworkDiscoveryKey, for your private network.

   masterNetworkDiscoveryKey=<your_custom_hex_key>
   

   Replace <your_custom_hex_key> with a unique hexadecimal string. This key allows you to create a private, isolated P2P DNS network, so only peers with the same masterNetworkDiscoveryKey can discover each other.

4. Start the DNS Server

   Run the DNS server with elevated permissions (required for binding to port 53).

   sudo node index.js
   

5. Start the HTTP Server

   node index.js
   

How to Add a Domain

To add a domain, use the addDomain function in the script, or add it programmatically. You’ll need to provide a unique connection hash for each domain, generated by Holesail.

Generating a Connection Hash

Use the following command to generate a live, publicly accessible connection hash from Holesail:

holesail --live 80 --public

This command will create a P2P tunnel on port 80 and output a connection hash. Example output:

Connection hash: 8a5b90945f8fbd5d1b620be3c888a47aaae20706a7f140be4bfa0df9e0dbcf38

Example Domain Addition

Once you have a connection hash, add the domain to the DNS core with the following example code in index.js:

addDomain('example.tld', '8a5b90945f8fbd5d1b620be3c888a47aaae20706a7f140be4bfa0df9e0dbcf38');

This command assigns a virtual IP and establishes a tunnel for example.tld.

Using a Custom masterNetworkDiscoveryKey for a Private Network

To create an isolated, private P2P DNS network, you can configure the system with a custom masterNetworkDiscoveryKey. This key acts as a unique identifier for your private DNS network, so only peers using the same masterNetworkDiscoveryKey will be able to discover and connect to each other.

Setting masterNetworkDiscoveryKey

The masterNetworkDiscoveryKey should be set in the .env file:

masterNetworkDiscoveryKey=<your_custom_hex_key>

When defined, the code will use masterNetworkDiscoveryKey as the main discovery key, enabling only clients with this key to participate in the network. If masterNetworkDiscoveryKey is not set, the system defaults to using dnsCore.discoveryKey.

This configuration ensures that only authorized clients with matching keys can join your network, providing a private, secure DNS namespace.

Starting Holesail Clients for Each Domain

The system will automatically start or reuse a Holesail client for each domain as requests come in, ensuring the connection stays alive and accessible over P2P.

Usage

The P2P DNS server listens on port 53 for DNS requests and automatically proxies HTTP requests on port 80. This means you can access domains in your network without needing direct IPs or proxy servers.

Example:

curl http://example.tld

The system will route the request through the P2P network to the correct local IP, based on the domain's connection hash and DNS record.

Troubleshooting

• Binding Issues on Port 53: Run the DNS server with elevated permissions (sudo).
• Custom masterNetworkDiscoveryKey Issues: Ensure your .env file is correctly loaded, and masterNetworkDiscoveryKey is set as expected.
• DNS Lookup Errors: Check that the domain and hash are correctly added to the DNS core.
• Firewall or NAT Issues: Ensure that Holesail is set to --public for external access.
• Connection Timeout: Verify that the DNS core topic is correctly set and that the Holesail client can connect.

Configuration Options

• masterNetworkDiscoveryKey: Used to create private, isolated DNS networks. Set this value in your .env file.
• Port Configurations: Adjust the DNS and HTTP server ports in index.js if needed.
• Logging: Add custom logs to track DNS queries and Holesail connections more granularly.

Security Considerations

• Environment Variables: Keep masterNetworkDiscoveryKey and other sensitive configuration values in the .env file, which should be excluded from version control.
• Firewall: Restrict external access to the DNS server to maintain control over the network.
• Key Rotation: Periodically update masterNetworkDiscoveryKey to maintain network security.

Future Enhancements

• Automatic Key Rotation: Enable the system to rotate keys for increased security.
• Dynamic Public/Private DNS Switching: Allow users to toggle between public and private network modes.
• Additional Domain Support: Add support for more complex DNS records (e.g., CNAME, MX).