# P2NS: Peer-to-Peer Decentralized DNS System

P2NS (Peer-to-Peer Name System) is a firewall-resistant P2P DNS resolution system independent of centralized DNS infrastructure. Using UDP hole-punching via Holesail, it enables connectivity across NAT, CGNAT, and restricted networks (4G/5G, Starlink).

Built with Node.js, integrating Corestore, Hyperswarm, Autopass, Autobase, and Holesail for decentralized storage, peer discovery, secure invitations, consensus, and dynamic tunneling.

[![screenshot](https://git.ssh.surf/snxraven/p2ns/raw/branch/main/images/domains-tab.png)](https://git.ssh.surf/snxraven/p2ns/raw/branch/main/images/domains-tab.png)

Example Peer-to-Peer domain: https://cert.decode (globally avalible to all peers)

[![screenshot](https://git.ssh.surf/snxraven/p2ns/raw/branch/main/images/p2p-domain-cert-dot-decode.png)](https://git.ssh.surf/snxraven/p2ns/raw/branch/main/images/p2p-domain-cert-dot-decode.png)

Local Example Plugin site with Peer-to-Peer access via the P2NS SDK. 

[![screenshot](https://git.ssh.surf/snxraven/p2ns/raw/branch/main/images/internal-domain-example-dot-plugin.png)](https://git.ssh.surf/snxraven/p2ns/raw/branch/main/images/internal-domain-example-dot-plugin.png)

## ⚠️ Disclaimer

**P2NS is a mixture of real development and vibe coding. Caution should be used when using and testing this software.** The software may contain experimental features, incomplete implementations, or unexpected behavior. Use at your own risk and always test thoroughly in non-production environments.

## Table of Contents

- [Features](#features)
- [Quick Start](#quick-start)
- [Architecture Overview](#architecture-overview)
- [Adding Domains](#adding-domains)
- [Admin Interface](#admin-interface)
- [DNS Resolution](#dns-resolution)
- [Proxying and Tunneling](#proxying-and-tunneling)
- [Certificate Authority](#certificate-authority)
- [Environment Variables](#environment-variables)
- [Troubleshooting](#troubleshooting)
- [Security Considerations](#security-considerations)
- [Additional Documentation](#additional-documentation)

## Features

- **Decentralized DNS** - Resolves domains via P2P, independent of ICANN
- **NAT Traversal** - UDP hole-punching via Holesail
- **Hybrid DNS** - Falls back to public DNS for non-P2P domains
- **HTTP/HTTPS Proxy** - With WebSocket support and auto HTTP→HTTPS redirect
- **TLS Certificates** - Auto-generated root CA and per-domain certs
- **Consensus Voting** - Resolves domain claim conflicts across peers
- **Plugin System** - Extensible with custom plugins
- **Web Admin** - Real-time management at `https://p2ns.admin`
- **Peer Directory** - Browse domains at `https://peer.directory`
- **Service Subscriptions** - Auto-subscribe to services from other domains
- **Backup/Recovery** - Automatic backups with rotation and restore
- **Health Monitoring** - Liveness/readiness probes, diagnostics, metrics

## Quick Start

### Prerequisites

- Node.js 18+ 
- macOS or Linux (Windows planned)
- `npm install -g holesail` for hash generation

### Installation

```bash
git clone https://git.ssh.surf/snxraven/p2ns.git
cd p2ns
npm install
```

### Running

```bash
# Genesis master (creates the network ledger — run once per network)
sudo node p2ns.js --master --genesis

# Additional master nodes (pair via invite; do not use --genesis)
sudo node p2ns.js --master

# Joiner node (connects via invites)
sudo node p2ns.js

# Fresh start (clears storage)
sudo node p2ns.js --clean [--master [--genesis]]
```

The system binds to UDP 53 (DNS), TCP 443 (HTTPS), and TCP 80 (HTTP redirect).

Access the admin interface at `https://p2ns.admin` (trust the root CA in your browser).

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                         P2NS Core                           │
├─────────────┬─────────────┬─────────────┬──────────────────┤
│  Corestore  │  Hyperswarm │   Autopass  │     Holesail     │
│  (Storage)  │   (Peers)   │  (Invites)  │   (Tunneling)    │
├─────────────┴─────────────┴─────────────┴──────────────────┤
│                     DNS Server (UDP 53)                     │
├─────────────────────────────────────────────────────────────┤
│              HTTPS Proxy (443) / HTTP Redirect (80)         │
├─────────────────────────────────────────────────────────────┤
│                    Virtual Interfaces                       │
│                  (lo0/lo IP aliases)                        │
├─────────────────────────────────────────────────────────────┤
│                     Plugin System                           │
│         (peer.directory, p2ns.admin, custom)                │
└─────────────────────────────────────────────────────────────┘
```

Key components:
- **DNS** (`dns.js`) - P2P/public/local DNS resolution on port 53
- **Proxy** (`*_proxy.js`) - HTTPS routing with SNI, WebSocket support
- **Holesail** (`holesail.js`) - Persistent tunnels for P2P domains
- **Virtual Interfaces** (`virtual_interfaces.js`) - IP aliases for domains
- **Certificates** (`certificate_authority.js`) - Root CA and domain certs
- **Plugins** (`plugin-handler.js`) - Extensible internal domains

## Adding Domains

1. **Generate a Holesail hash:**
   ```bash
   holesail --live 80 --public
   # Output: Connection hash: hs://<hash>
   ```

2. **Add via Admin Interface** (recommended):
   Use the "Domains" tab at `https://p2ns.admin`

3. **Add via JSON:**
   Edit `cache/domains.json`:
   ```json
   [{"domain": "example.tld", "hash": "hs://<hash>", "ssl": false}]
   ```

Domains sync across peers via Autopass with consensus-based conflict resolution. Resolution reads from the Autobase consensus sidecar ([RFC 0001](docs/rfcs/0001-autobase-consensus.md), [CONSENSUS.md](docs/CONSENSUS.md)).

## Admin Interface

Access `https://p2ns.admin` for real-time management:

| Tab | Features |
|-----|----------|
| **Domains** | Add/remove domains, view consensus status |
| **Host** | Holesail servers/clients, service subscriptions |
| **Local DNS** | Custom DNS records, conflict selector |
| **Entries** | Autopass ledger (claims/votes) |
| **Peers** | Connected peers, blocking, metrics |
| **Certificates** | Generate/regenerate domain certs, manage CA |
| **Interfaces** | Domain-to-IP mappings |
| **Backups** | Create/restore backups |
| **Diagnostics** | DNS lookup, ping, traceroute, connection tests |
| **Stats** | Live metrics (`subscribe-stats`), Core RPC invite diagnostics, Plugin RPC protocol stats |
| **Logs** | Tail split log files (core, proxy, HTTP proxy, DNS, plugins, Holesail) with filter |
| **Settings** | Environment config, subnet management |
| **Plugins** | Start/stop plugins, view logs, configure settings |

## DNS Resolution

P2NS provides hybrid DNS resolution:

| Type | Behavior |
|------|----------|
| **P2P Domains** | Resolve to local IPs, start Holesail tunnels |
| **Public Domains** | Forward to public DNS (default: 1.1.1.1) |
| **Local DNS** | Serve from `cache/local_dns.json` |
| **Internal Domains** | Map to 127.0.0.1 (plugins) |
| **Conflicting** | Managed via DNS Conflict Selector in admin |

Test with: `dig @127.0.0.1 example.tld`

### DNS Conflict Selector

For domains with both P2P and public records, use the "Local DNS" tab to toggle between P2P and Public resolution. Preferences are persisted in `cache/selector_cache.json`.

## Proxying and Tunneling

- **HTTPS Proxy** (443) - Routes to Holesail tunnels or public IPs
- **HTTP Redirect** (80) - Redirects to HTTPS
- **TLS/SNI** - Per-domain certificate selection
- **WebSocket** - Full upgrade support
- **Holesail Clients** - Lazy start, timeout after 5 min (configurable)
- **Holesail Servers** - Persistent, managed via admin

### Service Subscriptions

Subscribe to services published by other domains. See [docs/SUBSCRIPTIONS.md](docs/SUBSCRIPTIONS.md) for details.

## Certificate Authority

P2NS generates a root CA (`certs/ca.cert.pem`) and per-domain certificates with SANs.

### Auto-Installation

The CA is automatically installed on macOS (Keychain) and Linux (system store + NSS `~/.pki/nssdb` for Chrome).

### Manual Installation

If auto-install fails, see [docs/CERTIFICATES.md](docs/CERTIFICATES.md) for manual installation instructions for:
- macOS (Keychain Access or command line)
- Linux (system certificates + NSS for Chrome)
- Windows (certutil)
- Browser-specific (Firefox, Chrome)

## Environment Variables

Configure via `.env` (copy from `default.env`):

### Core Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `STORAGE_DIR` | `./my-storage` | Corestore data directory |
| `CERTS_DIR` | `./certs` | Certificate storage |
| `LOG_LEVEL` | `0` | 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR |
| `LOG_DIR` | `./logs` | Split log files (core, proxy, http-proxy, dns, plugins, holesail) |
| `LOG_BUFFER_LINES` | `2000` | In-memory tail size per log channel (admin Logs tab) |
| `TOPIC_SEED` | `p2ns-dns` | Hyperswarm topic seed |

### File Paths

| Variable | Default |
|----------|---------|
| `DOMAINS_FILE` | `./cache/domains.json` |
| `LOCAL_DNS_FILE` | `./cache/local_dns.json` |
| `HOLESAIL_SERVERS_FILE` | `./cache/holesail_servers.json` |
| `HOLESAIL_CLIENTS_FILE` | `./cache/holesail_clients.json` |
| `SELECTOR_CACHE_FILE` | `./cache/selector_cache.json` |
| `SUBSCRIPTIONS_FILE` | `./cache/subscriptions.json` |
| `PEER_HISTORY_FILE` | `./cache/peer_history.json` |
| `PEER_METRICS_FILE` | `./cache/peer_metrics.json` |

### Network Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `DNS_PORT` | `53` | DNS server port |
| `HTTPS_PORT` | `443` | HTTPS proxy port |
| `HTTP_PORT` | `80` | HTTP redirect port |
| `INTERNAL_PORT` | `8080` | Holesail client port |
| `PUBLIC_DNS_SERVER` | `1.1.1.1` | Fallback DNS (comma-separated for failover) |

### Feature Toggles

| Variable | Default | Description |
|----------|---------|-------------|
| `DISABLE_DNS_SERVER` | `false` | Disable DNS server |
| `DISABLE_PROXY_SERVER` | `false` | Disable proxy servers |
| `DISABLE_VIRTUAL_INTERFACES` | `false` | Disable virtual interfaces |
| `ALLOW_ANY_WRITER_INVITES` | `true` | Allow joiners to issue invites |
| `FULL_PERSISTENCE` | `false` | Keep Holesail connections indefinitely |

### Consensus Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `CONSENSUS_QUORUM_THRESHOLD` | `0.5` | Percentage of peers required (0.0-1.0) |
| `CONSENSUS_MIN_VOTES` | `2` | Minimum votes required |
| `CONSENSUS_TIE_BREAKER` | `timestamp` | `timestamp`, `claimant_age`, or `lexicographic` |
| `CONSENSUS_INIT_TIMEOUT_MS` | `30000` | Sidecar init timeout (ready/update) |

### Subnet Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `SUBNETS` | Single 192.168.3.x | JSON array of subnet configs |
| `SUBNET_NAME` | `lo0`/`lo` | Network interface for virtual IPs |

Example multi-subnet config:
```json
[{"base":"192.168.3.0","cidr":24,"startIndex":2,"name":"Primary"}]
```

### Backup & Metrics

| Variable | Default | Description |
|----------|---------|-------------|
| `BACKUP_DIR` | `./backups` | Backup storage |
| `BACKUP_RETENTION` | `25` | Backups to keep |
| `BACKUP_INTERVAL` | `720` | Auto-backup interval (minutes) |
| `METRICS_RETENTION_MS` | `60` | Metrics retention (minutes) |
| `RESOURCE_VALIDATION_INTERVAL` | `5` | Cleanup interval (minutes) |

### Master Node Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `MASTER_RECONNECT_INTERVAL` | `5` | Reconnection base interval (seconds) |
| `MASTER_MAX_RECONNECT_ATTEMPTS` | `10` | Max reconnection attempts |
| `MASTER_PROACTIVE_INVITE_DELAY` | `500` | Delay before sending invite (ms) |

## Troubleshooting

| Issue | Solution |
|-------|----------|
| **Port conflicts** | Check with `lsof -i :53`, use `DISABLE_DNS_SERVER=true` |
| **CA not trusted** | Import `certs/ca.cert.pem` manually (see [docs/CERTIFICATES.md](docs/CERTIFICATES.md)) |
| **Holesail failures** | Test with `holesail --live 80 --public` |
| **DNS errors** | Check logs, verify peer connections |
| **Interface issues** | Requires sudo, check with `ifconfig lo0` |
| **Ping not working (macOS)** | Disable "Stealth Mode" in Firewall settings |
| **Sync issues** | Use `--clean` to reset storage |

## Security Considerations

- **P2P Exposure** - Join trusted networks only
- **CA Security** - Protect `./certs` (enables local MITM)
- **Consensus** - Monitor for claim disputes
- **Sudo** - Run in isolated environments
- **Dependencies** - Audit for vulnerabilities

## Additional Documentation

- **[Full Documentation](docs/README_LONGFORM.md)** - Comprehensive reference with all details
- **[Plugin System](docs/plugins/README.md)** - Creating and managing plugins
- **[Plugin SDK](docs/plugins/PLUGIN_SDK.md)** - API reference for plugins
- **[REST API](docs/RESTAPI.md)** - Complete API documentation
- **[Consensus](docs/CONSENSUS.md)** - Domain voting and resolution (Autobase sidecar)
- **[RFC 0001: Autobase Consensus](docs/rfcs/0001-autobase-consensus.md)** - Implemented consensus architecture
- **[HyperDB](docs/plugins/HYPERDB.md)** - Database operations
- **[Plugin RPC](docs/plugins/PLUGIN_CHANNELS.md)** - protomux-rpc peer protocols
- **[Hyperdrive](docs/plugins/HYPERDRIVE.md)** - Distributed file system
- **[Proxy Server](proxy-server/README.md)** - Standalone proxy configuration

## Contributing

https://p2ns.space/community