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, and Holesail for decentralized storage, peer discovery, secure invitations, and dynamic tunneling.

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

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

⚠️ 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
• Quick Start
• Architecture Overview
• Adding Domains
• Admin Interface
• DNS Resolution
• Proxying and Tunneling
• Certificate Authority
• Environment Variables
• Troubleshooting
• Security Considerations
• 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

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

Running

# Master node (initializes network)
sudo node p2ns.js --master

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

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

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:

   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:

   [{"domain": "example.tld", "hash": "hs://<hash>", "ssl": false}]
   

Domains sync across peers via Autopass with consensus-based conflict resolution. See docs/CONSENSUS.md for details.

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	Real-time metrics, health status
Logs	Live system logs
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 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 (/usr/local/share/ca-certificates).

Manual Installation

If auto-install fails, see docs/CERTIFICATES.md for manual installation instructions for:

• macOS (Keychain Access or command line)
• Linux (system certificates)
• 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
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

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:

[{"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)
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 - Comprehensive reference with all details
• Plugin System - Creating and managing plugins
• Plugin SDK - API reference for plugins
• REST API - Complete API documentation
• Consensus - Domain voting and resolution
• HyperDB - Database operations
• Plugin Channels - P2P communication
• Hyperdrive - Distributed file system
• Proxy Server - Standalone proxy configuration

Contributing

https://p2ns.space/community