157 lines
7.0 KiB
Markdown
157 lines
7.0 KiB
Markdown
# 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](https://holesail.io) for tunneling, provides seamless DNS and HTTP proxying, and supports both public and private P2P networks.
|
||
|
||
```bash
|
||
[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
|
||
```
|
||
|
||
[](https://git.ssh.surf/snxraven/p2ns/raw/branch/main/images/sc.webp)
|
||
|
||
## 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](https://holesail.io))
|
||
- **Environment Variables**: Use `.env` to store your custom keys securely.
|
||
|
||
### Installation
|
||
|
||
1. **Clone the Repository**
|
||
|
||
```bash
|
||
git clone https://git.ssh.surf/snxraven/p2ns.git
|
||
cd p2ns
|
||
```
|
||
|
||
2. **Install Dependencies**
|
||
|
||
```bash
|
||
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.
|
||
|
||
```plaintext
|
||
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).
|
||
|
||
```bash
|
||
sudo node index.js
|
||
```
|
||
|
||
5. **Start the HTTP Server**
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
holesail --live 80 --public
|
||
```
|
||
|
||
This command will create a P2P tunnel on port 80 and output a connection hash. Example output:
|
||
|
||
```bash
|
||
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`:
|
||
|
||
```javascript
|
||
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:
|
||
|
||
```plaintext
|
||
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:
|
||
|
||
```bash
|
||
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).
|